fix(review): should-fix nits — task_timed_out fanout, NUL-byte test file, decompose docs

- task_timed_out added to the Linear fanout filter (fanout-task-events.ts): a
  standalone iteration that times out now settles (👀→✅/❌ + terminal reply)
  instead of maturing to 🔄 forever. Matches the Jira/Slack defaults.
- orchestration-e2e.test.ts: replaced 2 raw NUL bytes (composite-key separators
  in template literals) with the \u0000 escape — identical runtime, but git no
  longer flags the 23.6KB file binary so its diffs are reviewable.
- LINEAR_SETUP_GUIDE: the onboard-project example + flag list omitted the REAL,
  required --decompose-allowed flag (off by default), so following the guide
  verbatim made bgagent:decompose/:auto silently run as a single task. Added it
  + regenerated the Starlight mirror.

(Larger should-fix/fast-follow items — orchestration-row TTLs across seed call
sites, 4 IAM grant scope-downs, StatusIndex hot partition, baseline-build
memoization, handler splits, shared Linear client — deferred to a tracked
follow-up; each merits its own PR + regression surface.) cdk + docs green.

Author: isadeks

cdk/src/handlers/fanout-task-events.ts

@@ -181,6 +181,11 @@ export const CHANNEL_DEFAULTS: Record<NotificationChannel, ReadonlySet<string>>
   // are excluded for the same reason — N comments rather than 1.
   linear: new Set<string>([
     ...TERMINAL_EVENT_TYPES,
+    // review should-fix: include task_timed_out so a Linear standalone iteration
+    // that TIMES OUT still settles (its 👀→✅/❌ + terminal reply come through the
+    // fanout plane). Without it a timed-out iteration's threaded reply matured to
+    // 🔄 and never resolved. Matches the Jira/Slack defaults, which already have it.
+    'task_timed_out',
   ]),
   // Jira posts a single deterministic final-status comment on terminal
   // events — the Jira analogue of the Linear default above (issue #573).

cdk/test/handlers/fanout-task-events.test.ts

@@ -350,13 +350,16 @@ describe('fanout-task-events: per-channel filter contract (design §6.2)', () =>
     ]);
   });
 
-  test('Linear subscribes to terminal events only (post-once final-status comment)', () => {
+  test('Linear subscribes to terminal events + task_timed_out (post-once final-status comment)', () => {
+    // review should-fix: task_timed_out added so a Linear standalone iteration
+    // that times out still settles (matches Jira/Slack, which already had it).
     const f = CHANNEL_DEFAULTS.linear;
     expect([...f].sort()).toEqual([
       'task_cancelled',
       'task_completed',
       'task_failed',
       'task_stranded',
+      'task_timed_out',
     ]);
   });
 
@@ -483,12 +486,12 @@ describe('fanout-task-events: routeEvent (per-channel dispatch)', () => {
     expect([...outcome.dispatched].sort()).toEqual(['github', 'jira', 'linear', 'slack']);
   });
 
-  test('task_timed_out routes to Slack + Jira (Linear default predates it)', async () => {
-    // ``task_timed_out`` is a distinct terminal event the orchestrator
-    // emits. Slack and Email-... actually email does NOT include it; the
-    // Jira default (added in #573) does, Linear's (#239) does not.
+  test('task_timed_out routes to Slack + Jira + Linear (all three now subscribe)', async () => {
+    // ``task_timed_out`` is a distinct terminal event the orchestrator emits.
+    // Slack (#239) + Jira (#573) always had it; Linear now does too (review
+    // should-fix) so a timed-out standalone iteration settles. Email excludes it.
     const outcome = await routeEvent(mk('task_timed_out'));
-    expect([...outcome.dispatched].sort()).toEqual(['jira', 'slack']);
+    expect([...outcome.dispatched].sort()).toEqual(['jira', 'linear', 'slack']);
   });
 
   test('agent_error routes only to Slack', async () => {

cdk/test/handlers/linear-webhook-processor-orchestration.test.ts

@@ -198,8 +198,10 @@ describe('linear-webhook-processor — #247 orchestration routing', () => {
     // parent start signal mirrored — 👀 reaction + In Progress — via upsertEpicPanel.
     expect(upsertStatusCommentMock).toHaveBeenCalled();
     expect(swapIssueReactionMock).toHaveBeenCalledWith(expect.anything(), expect.any(String), 'eyes');
+    // The 5th arg (allowSameTypeRegression, #9b) is passed by the shared rollup
+    // re-open path; harmless on this forward Backlog→In Progress mirror.
     expect(transitionIssueStateMock).toHaveBeenCalledWith(
-      expect.anything(), expect.any(String), 'started', ['In Progress'],
+      expect.anything(), expect.any(String), 'started', ['In Progress'], true,
     );
   });
 

cdk/test/integration/orchestration-e2e.test.ts

@@ -90,12 +90,14 @@ Paste the secret at the prompt. ABCA stores it on the workspace's per-workspace
 
 ```bash
 bgagent linear list-projects --slug <slug>     # find the project UUID
-bgagent linear onboard-project <project-uuid> --repo owner/repo --label abca
+# Add --decompose-allowed if you want the bgagent:decompose / bgagent:auto
+# planning flow on this project (it is OFF by default).
+bgagent linear onboard-project <project-uuid> --repo owner/repo --label abca --decompose-allowed
 ```
 
 Default trigger label is `bgagent`; pass `--label <name>` to override.
 
-Optional flags on `onboard-project`: `--team-id` (Linear team UUID, debug only), `--region`, `--stack-name`.
+Optional flags on `onboard-project`: `--decompose-allowed` (enable the `bgagent:decompose` / `bgagent:auto` Mode-B planning flow — **off by default**, so without it those labels silently run as a single task), `--team-id` (Linear team UUID, debug only), `--region`, `--stack-name`.
 
 ### 7. Test
 

docs/guides/LINEAR_SETUP_GUIDE.md

@@ -94,12 +94,14 @@ Paste the secret at the prompt. ABCA stores it on the workspace's per-workspace
 
 ```bash
 bgagent linear list-projects --slug <slug>     # find the project UUID
-bgagent linear onboard-project <project-uuid> --repo owner/repo --label abca
+# Add --decompose-allowed if you want the bgagent:decompose / bgagent:auto
+# planning flow on this project (it is OFF by default).
+bgagent linear onboard-project <project-uuid> --repo owner/repo --label abca --decompose-allowed
 ```
 
 Default trigger label is `bgagent`; pass `--label <name>` to override.
 
-Optional flags on `onboard-project`: `--team-id` (Linear team UUID, debug only), `--region`, `--stack-name`.
+Optional flags on `onboard-project`: `--decompose-allowed` (enable the `bgagent:decompose` / `bgagent:auto` Mode-B planning flow — **off by default**, so without it those labels silently run as a single task), `--team-id` (Linear team UUID, debug only), `--region`, `--stack-name`.
 
 ### 7. Test