fix(orchestration): sweep settles the parent + posts rollup (review blocker 8)

The panel/rollup/parent-settle side-effects lived ONLY on the live TaskTable-stream
path (refreshPanelAndSettle in orchestration-reconciler). When the last child's
terminal event was lost — the exact failure the aws-samples#303 sweep exists to recover —
the sweep advanced the DDB rows to terminal but NEVER settled the Linear parent,
so the epic showed 🔄 In Progress forever. Worse, the sweep's top guard
'if (allTerminal) return 0' skipped an already-fully-terminal-but-unsettled epic
entirely, guaranteeing it never closed.

Exported refreshPanelAndSettle and call it from the sweep in BOTH spots: (a) the
top all-terminal guard now settles-then-returns instead of bare-return; (b) when
the release pass finds nothing releasable AND all children are terminal (a child
went terminal during this sweep's lost-terminal recovery). It's idempotent (panel
body edit is a no-op if unchanged; parent-state mirror claimed once via
claimRollup), so racing the live reconciler is safe. Not circular (the reconciler
doesn't import the sweep). +2 settle regression tests.

Author: isadeks

cdk/src/handlers/orchestration-reconciler.ts

@@ -648,7 +648,7 @@ async function reconcileTerminalChild(evt: TerminalTaskEvent): Promise<void> {
  * edit is idempotent (same body = no-op), so it always runs; the parent-STATE
  * mirror is claimed once via ``claimRollup`` on the first all-terminal caller.
  */
-async function refreshPanelAndSettle(
+export async function refreshPanelAndSettle(
   orchestrationId: string,
   children: readonly OrchestrationChildRow[],
   meta: { linear_workspace_id: string; parent_linear_issue_id: string; status_comment_id?: string; release_context: { channel_source?: string } },

cdk/src/handlers/reconcile-stranded-orchestrations.ts

@@ -58,6 +58,7 @@ import {
   GetCommand,
   UpdateCommand,
 } from '@aws-sdk/lib-dynamodb';
+import { refreshPanelAndSettle } from './orchestration-reconciler';
 import { createTaskCore } from './shared/create-task-core';
 import { logger } from './shared/logger';
 import { readConcurrencyBudget, releaseReadyChildren } from './shared/orchestration-release';
@@ -123,12 +124,25 @@ async function reconcileOrchestration(orchestrationId: string): Promise<number>
   const snap = await loadOrchestration(ddb, ORCHESTRATION_TABLE, orchestrationId);
   if (!snap) return 0;
 
-  // Skip orchestrations already fully terminal — nothing to recover.
-  const allTerminal = snap.children.every((c) => TERMINAL_CHILD.has(c.child_status));
-  if (allTerminal) return 0;
-
   const now = new Date().toISOString();
 
+  // Already fully terminal: no children to release/recover — BUT the parent may
+  // never have been settled (review blocker #8: the last terminal event was lost,
+  // so the DDB rows are all terminal yet the Linear parent is stuck 🔄 In Progress
+  // forever). Attempt the idempotent settle before returning, instead of the old
+  // bare skip that guaranteed the epic never closed on the lossy path.
+  const allTerminal = snap.children.every((c) => TERMINAL_CHILD.has(c.child_status));
+  if (allTerminal) {
+    try {
+      await refreshPanelAndSettle(orchestrationId, snap.children, snap.meta, now);
+    } catch (err) {
+      logger.warn('Sweep settle (already-terminal epic) failed (will retry next sweep)', {
+        orchestration_id: orchestrationId, error: err instanceof Error ? err.message : String(err),
+      });
+    }
+    return 0;
+  }
+
   // 1a. Recover a child STUCK in the transient ``releasing`` state (review #3
   //     flip-then-create): a releaser won the blocked|ready→releasing claim but
   //     crashed before createTaskCore (or before its rollback). No task exists,
@@ -226,7 +240,31 @@ async function reconcileOrchestration(orchestrationId: string): Promise<number>
     })
     .map((c) => ({ ...c, child_status: 'ready' as const }));
 
-  if (releasableRows.length === 0) return 0;
+  if (releasableRows.length === 0) {
+    // review blocker #8: nothing left to release. If EVERY child is now terminal
+    // but the parent was never settled — because the last child's terminal stream
+    // event was lost (the exact failure this sweep exists to recover) — the epic
+    // is 'done' in DynamoDB yet stuck showing 🔄 In Progress in Linear forever.
+    // The panel/rollup/settle side-effects lived ONLY on the (lossy) live-event
+    // path. Call the shared settle here so the sweep closes the loop: post the
+    // rollup + transition the parent. refreshPanelAndSettle is idempotent (body
+    // edit is a no-op if unchanged; the parent-state mirror is claimed once), so
+    // racing the live reconciler is safe.
+    const freshAllTerminal = fresh.children.every((c) => TERMINAL_CHILD.has(c.child_status));
+    if (freshAllTerminal) {
+      try {
+        await refreshPanelAndSettle(orchestrationId, fresh.children, fresh.meta, now);
+        logger.warn('Stranded orchestration settled by sweep — parent was never settled (lost terminal event)', {
+          orchestration_id: orchestrationId, parent_linear_issue_id: fresh.meta.parent_linear_issue_id,
+        });
+      } catch (err) {
+        logger.warn('Sweep settle failed (will retry next sweep)', {
+          orchestration_id: orchestrationId, error: err instanceof Error ? err.message : String(err),
+        });
+      }
+    }
+    return 0;
+  }
 
   // #331: throttle the sweep's releases to the free budget too.
   const budget = USER_CONCURRENCY_TABLE

cdk/test/handlers/reconcile-stranded-orchestrations.test.ts

@@ -77,6 +77,15 @@ jest.mock('../../src/handlers/shared/logger', () => ({
   logger: { info: jest.fn(), warn: jest.fn(), error: jest.fn() },
 }));
 
+// review blocker #8: the sweep now imports refreshPanelAndSettle from the live
+// reconciler to settle an epic whose last terminal event was lost. Mock it so we
+// can assert the sweep CALLS it (its real body is exercised by the reconciler's
+// own suite).
+const refreshPanelAndSettleMock = jest.fn();
+jest.mock('../../src/handlers/orchestration-reconciler', () => ({
+  refreshPanelAndSettle: (...args: unknown[]) => refreshPanelAndSettleMock(...args),
+}));
+
 process.env.ORCHESTRATION_TABLE_NAME = 'OrchestrationTable';
 process.env.TASK_TABLE_NAME = 'TaskTable';
 
@@ -111,6 +120,7 @@ beforeEach(() => {
   orch.clear(); tasksTbl.clear(); fakeSend.mockClear();
   createTaskCoreMock.mockReset();
   createTaskCoreMock.mockResolvedValue({ statusCode: 201, body: JSON.stringify({ data: { task_id: 'new-task' } }) });
+  refreshPanelAndSettleMock.mockReset();
 });
 
 describe('#303 stranded-orchestration backstop', () => {
@@ -136,6 +146,32 @@ describe('#303 stranded-orchestration backstop', () => {
     expect(statusOf('o2', 'B')).toBe('released');
   });
 
+  // review blocker #8: the sweep must SETTLE the parent (post rollup + transition
+  // Linear), not just flip DDB rows — else a lost last-terminal event leaves the
+  // epic 'done' in DDB but stuck 🔄 In Progress in Linear forever.
+  test('lost LAST terminal event: the only remaining child completes → sweep settles the parent', async () => {
+    seed('o-settle', [
+      { sk: 'A', status: 'succeeded' },
+      { sk: 'B', deps: ['A'], status: 'released', taskId: 'task-B' },
+    ]);
+    tasksTbl.set('task-B', { task_id: 'task-B', status: 'COMPLETED', build_passed: true });
+    await handler();
+    // B advanced to terminal in DDB…
+    expect(statusOf('o-settle', 'B')).toBe('succeeded');
+    // …and, crucially, the parent was settled (the whole point of blocker #8).
+    expect(refreshPanelAndSettleMock).toHaveBeenCalled();
+    expect(createTaskCoreMock).not.toHaveBeenCalled(); // nothing left to release
+  });
+
+  test('already fully-terminal but unsettled epic → sweep still settles (idempotent)', async () => {
+    seed('o-done', [
+      { sk: 'A', status: 'succeeded' },
+      { sk: 'B', deps: ['A'], status: 'succeeded' },
+    ]);
+    await handler();
+    expect(refreshPanelAndSettleMock).toHaveBeenCalledWith('o-done', expect.any(Array), expect.any(Object), expect.any(String));
+  });
+
   test('lost TERMINAL event with build_passed=false: A→failed, B→skipped, no release', async () => {
     seed('o3', [
       { sk: 'A', status: 'released', taskId: 'task-A' },