@dotdrelle/wiki-manager 0.15.97 → 0.15.99

package/src/orchestrator/providers/deepAgentsProvider.js

@@ -4,6 +4,21 @@ import {
   normalizeRuntimeEvent,
 } from './runtimeProvider.js';
 
+// The gateway closes the stream when one of these arrives; the client stops
+// reconnecting on it too, so a finished run never leaves a retry loop behind.
+const TERMINAL_RUNTIME_EVENT_TYPES = new Set(['run_completed', 'run_failed', 'run_cancelled']);
+
+function sleep(ms, signal) {
+  return new Promise((resolve) => {
+    if (signal?.aborted) {
+      resolve();
+      return;
+    }
+    const timer = setTimeout(resolve, ms);
+    signal?.addEventListener?.('abort', () => { clearTimeout(timer); resolve(); }, { once: true });
+  });
+}
+
 /**
  * DeepAgentsProvider — client HTTP vers un runtime Deep Agents externe
  * (RFC § 11, option A). Implémente le contrat RuntimeProvider :
@@ -28,6 +43,8 @@ export function createDeepAgentsProvider({
   headers = {},
   version = null,
   timeoutMs = 10_000,
+  streamRetries = Number(process.env.WIKI_MANAGER_RUNTIME_STREAM_RETRIES ?? 5),
+  streamBackoffMs = Number(process.env.WIKI_MANAGER_RUNTIME_STREAM_BACKOFF_MS ?? 250),
 } = {}) {
   const base = String(endpoint).replace(/\/+$/, '');
 
@@ -117,6 +134,11 @@ export function createDeepAgentsProvider({
           capability: request.capability ?? null,
           arguments: request.arguments ?? {},
           workspace: request.workspace ?? null,
+          // The body is rebuilt field by field here, so a value the dispatcher
+          // adds only at the runtime layer would be dropped in transit. The
+          // memory scope decides which past conversation the run resumes: it
+          // has to be named in this list to exist at all.
+          memoryScope: request.memoryScope ?? null,
           model: request.model ?? null,
           language: request.language ?? null,
           mcp: Array.isArray(request.mcp) ? request.mcp : [],
@@ -152,43 +174,126 @@ export function createDeepAgentsProvider({
         },
       });
     },
+    // A broken stream must not mean "silence forever", and a naive reconnect
+    // must not replay what was already seen. `cursor` is the last `sequence`
+    // delivered, `epoch` the gateway instance that produced it; both travel
+    // back on the next connection. Bounded retries then announce the give-up:
+    // a dead subscription that never says so is the defect this closes.
     subscribe(runId, listener) {
       const controller = new AbortController();
-      const url = `${base}/runs/${encodeURIComponent(String(runId))}/events`;
-      void (async () => {
+      const target = `${base}/runs/${encodeURIComponent(String(runId))}/events`;
+      let cursor = null;
+      let epoch = null;
+      let attempts = 0;
+      let stopped = false;
+
+      const emit = (event) => {
         try {
-          const response = await fetchImpl(url, {
-            headers: { accept: 'text/event-stream', ...headers },
-            signal: controller.signal,
-          });
-          if (!response.ok) throw new Error(`HTTP ${response.status}`);
-          const reader = response.body.getReader();
-          const decoder = new TextDecoder();
-          let buffer = '';
-          while (true) {
-            const { done, value } = await reader.read();
-            if (done) break;
-            buffer += decoder.decode(value, { stream: true });
-            const blocks = buffer.split('\n\n');
-            buffer = blocks.pop() ?? '';
-            for (const block of blocks) {
-              let data = '';
-              for (const line of block.split('\n')) {
-                if (line.startsWith('data: ')) data += line.slice(6);
-              }
-              if (!data) continue;
-              try {
-                listener(normalizeRuntimeEvent(JSON.parse(data)));
-              } catch {
-                // malformed or out-of-contract frame — skip
+          listener(normalizeRuntimeEvent(event));
+        } catch {
+          // The contract refused the frame: journal it instead of vanishing.
+          try {
+            listener(normalizeRuntimeEvent({
+              type: 'degraded',
+              capability: 'stream',
+              cause: 'an out-of-contract frame arrived from the runtime',
+              fallback: 'the frame was skipped',
+            }));
+          } catch { /* nothing left to report with */ }
+        }
+      };
+      const announce = (cause, fallback) => emit({ type: 'degraded', capability: 'stream', cause, fallback });
+
+      void (async () => {
+        while (!stopped && attempts < streamRetries) {
+          attempts += 1;
+          try {
+            const query = new URLSearchParams();
+            if (cursor != null) query.set('after', String(cursor));
+            if (epoch) query.set('epoch', epoch);
+            const suffix = query.toString();
+            const response = await fetchImpl(suffix ? `${target}?${suffix}` : target, {
+              headers: { accept: 'text/event-stream', ...headers },
+              signal: controller.signal,
+            });
+            if (response.status === 404) {
+              announce(`run ${runId} is not known to the runtime`, 'it was purged or never existed; no replay is possible');
+              return;
+            }
+            if (!response.ok) throw new Error(`HTTP ${response.status}`);
+            // The budget resets on PROGRESS, not on a mere HTTP 200: a gateway
+            // that accepts a connection and immediately closes it (or replays
+            // only what was already seen) would otherwise reset the budget
+            // forever and reconnect in a loop that never gives up.
+            let progressed = false;
+            const reader = response.body.getReader();
+            const decoder = new TextDecoder();
+            let buffer = '';
+            while (true) {
+              const { done, value } = await reader.read();
+              if (done) break;
+              buffer += decoder.decode(value, { stream: true });
+              const blocks = buffer.split('\n\n');
+              buffer = blocks.pop() ?? '';
+              for (const block of blocks) {
+                const data = block
+                  .split('\n')
+                  .filter((line) => line.startsWith('data: '))
+                  .map((line) => line.slice(6))
+                  .join('');
+                if (!data) continue;
+                let parsed;
+                try {
+                  parsed = JSON.parse(data);
+                } catch {
+                  announce('a malformed frame arrived from the runtime', 'the frame was skipped');
+                  continue;
+                }
+                if (parsed?.type === 'stream_epoch') {
+                  const next = String(parsed.epoch ?? '');
+                  if (epoch && next && next !== epoch) {
+                    announce('the runtime restarted (stream epoch changed)', 'reconnect from a fresh subscription; no events were replayed');
+                    return;
+                  }
+                  epoch = next || epoch;
+                  continue;
+                }
+                if (Number.isFinite(Number(parsed?.sequence))) {
+                  const sequence = Number(parsed.sequence);
+                  if (sequence > (cursor ?? -1)) progressed = true;
+                  cursor = Math.max(cursor ?? 0, sequence);
+                }
+                emit(parsed);
+                if (TERMINAL_RUNTIME_EVENT_TYPES.has(String(parsed?.type))) return;
               }
             }
+            if (progressed) attempts = 0;
+            // The stream ended without a terminal event: reconnect from the cursor.
+          } catch (error) {
+            if (controller.signal.aborted || stopped) return;
+            if (attempts >= streamRetries) {
+              announce(
+                'gave up reconnecting to the runtime stream',
+                `after ${attempts} attempt(s): ${error instanceof Error ? error.message : String(error)}`,
+              );
+              return;
+            }
           }
-        } catch {
-          // stream ended or aborted — the unsubscribe path is a no-op
+          if (stopped || controller.signal.aborted) return;
+          if (attempts >= streamRetries) break;
+          await sleep(streamBackoffMs * 2 ** (attempts - 1), controller.signal);
+        }
+        // The loop can also end because the budget ran out on a stream that
+        // kept closing cleanly — that is a give-up too, and it must be said.
+        if (!stopped && !controller.signal.aborted) {
+          announce('gave up reconnecting to the runtime stream', `after ${attempts} attempt(s) without progress`);
         }
       })();
-      return () => controller.abort();
+
+      return () => {
+        stopped = true;
+        controller.abort();
+      };
     },
   };
   return provider;

package/src/orchestrator/providers/deepAgentsProvider.test.js

@@ -170,13 +170,18 @@ test('subscribe parses the SSE stream and forwards normalized events', async ()
       ]),
     }),
   });
-  const provider = createDeepAgentsProvider({ endpoint: 'http://agent-runtime:8080', fetchImpl });
+  // A single attempt: this test is about parsing, not reconnection. The mock
+  // stream carries no terminal event, so the provider would otherwise reconnect
+  // (and the mock would re-deliver) until its budget ran out.
+  const provider = createDeepAgentsProvider({
+    endpoint: 'http://agent-runtime:8080', fetchImpl, streamRetries: 1, streamBackoffMs: 1,
+  });
 
   const events = [];
   provider.subscribe('run-1', (event) => events.push(event));
 
-  await waitFor(() => events.length === 2);
-  assert.deepEqual(events.map((event) => event.type), ['tool_started', 'tool_finished']);
+  await waitFor(() => events.length >= 2);
+  assert.deepEqual(events.slice(0, 2).map((event) => event.type), ['tool_started', 'tool_finished']);
   assert.equal(events[0].tool, 'wiki_search');
 });
 
@@ -204,3 +209,133 @@ test('the deepagents factory is reachable from the agentRuntimes config', () =>
   assert.equal(providers[0].type, 'deepagents');
   assertRuntimeProvider(providers[0].provider);
 });
+
+// ── Lot 0: a broken stream must not mean "silence forever" ──────────────────
+
+test('an event type this manager does not know still reaches the listener', async () => {
+  const fetchImpl = mockFetch({
+    'GET /runs/run-6/events': () => ({
+      ok: true,
+      status: 200,
+      body: sseBody([
+        { type: 'phase_started', phase: 'discover', sequence: 1 },
+        { type: 'run_completed', sequence: 2 },
+      ]),
+    }),
+  });
+  const provider = createDeepAgentsProvider({ endpoint: 'http://agent-runtime:8080', fetchImpl });
+  const events = [];
+  provider.subscribe('run-6', (event) => events.push(event));
+
+  await waitFor(() => events.some((event) => event.type === 'phase_started'));
+  assert.equal(events.find((event) => event.type === 'phase_started').phase, 'discover');
+});
+
+test('a dropped stream reconnects from the cursor and never repeats an event', async () => {
+  let connections = 0;
+  const fetchImpl = mockFetch({
+    'GET /runs/run-1/events': () => {
+      connections += 1;
+      if (connections === 1) {
+        return {
+          ok: true,
+          status: 200,
+          body: sseBody([
+            { type: 'stream_epoch', epoch: 'epoch-a' },
+            { type: 'tool_started', tool: 'wiki_search', sequence: 5 },
+          ]),
+        };
+      }
+      return {
+        ok: true,
+        status: 200,
+        body: sseBody([
+          { type: 'stream_epoch', epoch: 'epoch-a' },
+          { type: 'run_completed', sequence: 6 },
+        ]),
+      };
+    },
+  });
+  const provider = createDeepAgentsProvider({
+    endpoint: 'http://agent-runtime:8080', fetchImpl, streamRetries: 3, streamBackoffMs: 1,
+  });
+  const events = [];
+  const unsubscribe = provider.subscribe('run-1', (event) => events.push(event));
+
+  await waitFor(() => events.some((event) => event.type === 'run_completed'));
+  unsubscribe();
+
+  assert.equal(connections, 2, 'the stream was reconnected once');
+  assert.match(fetchImpl.calls[1].url, /after=5/, 'the cursor travels back');
+  assert.match(fetchImpl.calls[1].url, /epoch=epoch-a/, 'the epoch travels back');
+  assert.equal(events.filter((event) => event.type === 'tool_started').length, 1, 'no duplicate delivery');
+  assert.equal(events.filter((event) => event.type === 'stream_epoch').length, 0, 'the epoch frame is consumed, never forwarded');
+});
+
+test('a stream epoch change stops the subscription with an announced reason', async () => {
+  let connections = 0;
+  const fetchImpl = mockFetch({
+    'GET /runs/run-2/events': () => {
+      connections += 1;
+      return {
+        ok: true,
+        status: 200,
+        body: sseBody([{ type: 'stream_epoch', epoch: connections === 1 ? 'epoch-a' : 'epoch-b' }]),
+      };
+    },
+  });
+  const provider = createDeepAgentsProvider({
+    endpoint: 'http://agent-runtime:8080', fetchImpl, streamRetries: 5, streamBackoffMs: 1,
+  });
+  const events = [];
+  provider.subscribe('run-2', (event) => events.push(event));
+
+  await waitFor(() => events.some((event) => event.type === 'degraded'));
+  assert.equal(connections, 2, 'it stopped after the mismatch');
+  assert.match(events.find((event) => event.type === 'degraded').cause, /epoch changed/);
+});
+
+test('a purged run ends the subscription with an announced reason', async () => {
+  const fetchImpl = mockFetch({}); // 404 on every route
+  const provider = createDeepAgentsProvider({
+    endpoint: 'http://agent-runtime:8080', fetchImpl, streamRetries: 5, streamBackoffMs: 1,
+  });
+  const events = [];
+  provider.subscribe('run-gone', (event) => events.push(event));
+
+  await waitFor(() => events.some((event) => event.type === 'degraded'));
+  assert.match(events.find((event) => event.type === 'degraded').cause, /not known to the runtime/);
+});
+
+test('a stream that keeps failing announces the give-up', async () => {
+  const fetchImpl = mockFetch({
+    'GET /runs/run-4/events': () => ({ ok: false, status: 500, json: async () => ({}) }),
+  });
+  const provider = createDeepAgentsProvider({
+    endpoint: 'http://agent-runtime:8080', fetchImpl, streamRetries: 2, streamBackoffMs: 1,
+  });
+  const events = [];
+  provider.subscribe('run-4', (event) => events.push(event));
+
+  await waitFor(() => events.some((event) => event.type === 'degraded' && /gave up/.test(event.cause)));
+});
+
+test('a malformed frame is journalled instead of silently skipped', async () => {
+  const encoder = new TextEncoder();
+  const body = new ReadableStream({
+    start(controller) {
+      controller.enqueue(encoder.encode('data: {not json\n\n'));
+      controller.enqueue(encoder.encode(`data: ${JSON.stringify({ type: 'run_completed' })}\n\n`));
+      controller.close();
+    },
+  });
+  const fetchImpl = mockFetch({
+    'GET /runs/run-5/events': () => ({ ok: true, status: 200, body }),
+  });
+  const provider = createDeepAgentsProvider({ endpoint: 'http://agent-runtime:8080', fetchImpl });
+  const events = [];
+  provider.subscribe('run-5', (event) => events.push(event));
+
+  await waitFor(() => events.some((event) => event.type === 'degraded' && /malformed/.test(event.cause)));
+  assert.ok(events.some((event) => event.type === 'run_completed'), 'the good frame still arrives');
+});

package/src/orchestrator/resultAggregator.js

@@ -9,6 +9,7 @@ import { resolve as resolveCapability } from './capabilityResolver.js';
 import { integrate } from './planIntegrator.js';
 import { validateFragment } from './planValidator.js';
 import { isSuccessful } from './taskStatuses.js';
+import { PROACTIVE_REVIEW_CAPABILITY, triggerForTask } from './proactiveReviewScheduler.js';
 
 export function createResultAggregator({
   session = null,
@@ -102,6 +103,52 @@ export async function accept(result, {
     taskId,
     payload,
   })));
+  // A successful ingest/rebuild is a business FACT the rest of the manager can
+  // act on. We publish it as a stable event and hand it to a trigger hook; the
+  // runtime decides whether it is worth a read-only review. Nothing here
+  // mutates anything — a trigger only ever proposes.
+  if (ok) {
+    const trigger = triggerForTask({
+      capability: task?.requiredCapability,
+      operation: task?.operation,
+    });
+    if (trigger) {
+      const workspace = session.workspace ?? session._currentRunIdentity?.workspace ?? null;
+      // The RUN is the fact, not the task: a parallel ingest of N sources is N
+      // tasks with N idempotency keys, and keying on the task would fire on the
+      // first source applied — an audit of a half-written corpus. One run, one
+      // version, one review; the queued review itself starts only after the
+      // run's control-lane drain.
+      const sourceVersion = runId ?? result?.idempotencyKey ?? task?.idempotencyKey ?? null;
+      const triggerPayload = { workspace, trigger, sourceVersion, taskId, runId };
+      persistDispatch(store, dispatchAgentEvent(session, createAgentEvent(trigger, {
+        origin: 'result_aggregator',
+        runId,
+        taskId,
+        workspace,
+        payload: triggerPayload,
+      })));
+      session._onKnowledgeTrigger?.(triggerPayload);
+    }
+    // A proactive review's result is a NOTE, not a mutation: file it in the
+    // workspace's review queue (never in agent-proposals, which is for merges)
+    // and announce where it waits. The run is read-only by capability, so
+    // nothing here can have changed the wiki.
+    if (task?.requiredCapability === PROACTIVE_REVIEW_CAPABILITY && session._proactiveReview) {
+      const persisted = persistProactiveReview(session, result, session._proactiveReview, taskId);
+      persistDispatch(store, dispatchAgentEvent(session, createAgentEvent('runtime_log', {
+        origin: 'result_aggregator',
+        runId,
+        taskId,
+        payload: {
+          message: persisted.error
+            ? `proactive-review: could not file the review — ${persisted.error}`
+            : `proactive-review: ${persisted.id} is waiting — ${persisted.path} (${persisted.findings} finding(s))`,
+        },
+      })));
+      session._proactiveReview = null;
+    }
+  }
   const expansion = await maybeExpandPlan(result, {
     session,
     runId,
@@ -258,7 +305,14 @@ function persistDispatch(store, event) {
  * write machinery — this function only records, it never touches wiki content.
  */
 function persistWorktreeProposal(session, result, { runId, taskId }) {
-  const proposal = result?.result?.worktreeProposal ?? result?.worktreeProposal;
+  // The dispatcher wraps the agent's status payload under `rawStatus`
+  // (`taskResultFromStatus`), so the gateway's proposal lives at
+  // `rawStatus.result.worktreeProposal`. Reading only `result.result`/
+  // `result.worktreeProposal` matched the unit-test fixture but never the real
+  // run: the proposal was silently dropped and no review item ever appeared.
+  const proposal = result?.rawStatus?.result?.worktreeProposal
+    ?? result?.result?.worktreeProposal
+    ?? result?.worktreeProposal;
   if (!proposal || typeof proposal !== 'object') return { path: null };
   const changes = Array.isArray(proposal.changes) ? proposal.changes : [];
   if (changes.length === 0) return { path: null };
@@ -294,6 +348,66 @@ function persistWorktreeProposal(session, result, { runId, taskId }) {
   }
 }
 
+/*
+ A proactive review is a read-only audit the workspace asked for. Its result is
+ FILED, never merged: `.wiki/agent-reviews/<id>.json` is a queue of notes a
+ human reads, distinct from `.wiki/agent-proposals/` (which exists to be
+ merged). No worktree, no mutation, no external message — the capability is
+ read-only by construction; this is only where its conclusion is kept.
+*/
+function persistProactiveReview(session, result, pending, taskId) {
+  const workspacePath = session?.workspacePath;
+  if (!workspacePath || typeof workspacePath !== 'string') {
+    return { error: 'no workspace path on the session — the review stays in the run result only' };
+  }
+  // Same wrapping as the worktree proposal above: the real dispatcher result
+  // carries the gateway's content under `rawStatus.result.content`.
+  const content = String(result?.rawStatus?.result?.content ?? result?.result?.content ?? result?.content ?? '');
+  const findings = extractReviewFindings(content);
+  const id = String(pending?.id ?? `review-${taskId}`).replace(/[^a-zA-Z0-9._-]/g, '_');
+  const record = {
+    id,
+    workspace: String(pending?.workspace ?? session.workspace ?? ''),
+    trigger: pending?.trigger ?? null,
+    createdAt: pending?.createdAt ?? new Date().toISOString(),
+    status: 'proposed',
+    summary: content.replace(/\s+/g, ' ').trim().slice(0, 1000),
+    findings,
+    sourceVersion: pending?.sourceVersion ?? null,
+    budget: pending?.budget ?? null,
+    // What the deterministic scan knew when it queued this review.
+    evidence: pending?.evidence ?? null,
+  };
+  try {
+    const dir = join(workspacePath, '.wiki', 'agent-reviews');
+    mkdirSync(dir, { recursive: true });
+    const path = join(dir, `${id}.json`);
+    writeFileSync(path, JSON.stringify(record, null, 2));
+    return { path, id, findings: findings.length };
+  } catch (error) {
+    return { error: error instanceof Error ? error.message : String(error) };
+  }
+}
+
+// The `[objection] severity: … — path — statement` lines the gateway's Critique
+// emits, lifted so a review's findings are structured, not a prose blob.
+function extractReviewFindings(content, { max = 50 } = {}) {
+  const findings = [];
+  for (const line of String(content ?? '').split('\n')) {
+    const match = /^\s*\[objection\]\s*severity:\s*(blocking|non-blocking)\s*[-—]\s*(.+)$/i.exec(line.trim());
+    if (!match) continue;
+    const tail = match[2].trim();
+    const separator = tail.indexOf(' — ');
+    findings.push({
+      severity: match[1].toLowerCase(),
+      path: separator === -1 ? null : tail.slice(0, separator).trim() || null,
+      statement: (separator === -1 ? tail : tail.slice(separator + 3).trim()).slice(0, 300),
+    });
+    if (findings.length >= max) break;
+  }
+  return findings;
+}
+
 function agentPlanRequest(request, session) {
   return {
     capability: request.capability,

package/src/orchestrator/resultAggregator.test.js

@@ -1,5 +1,8 @@
 import assert from 'node:assert/strict';
 import test from 'node:test';
+import { existsSync, mkdtempSync, readFileSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
 
 import { createAgentEvent, dispatchAgentEvent } from '../core/agentEvents.js';
 import { accept } from './resultAggregator.js';
@@ -271,3 +274,138 @@ test('resultAggregator honours an explicit opt-out from the proposal constraints
   assert.equal(calls[0].constraints.requireApprovalForMutations, false);
   assert.equal(calls[0].constraints.maxTasks, 2);
 });
+
+test('a completed ingest publishes knowledge.ingested and hands the trigger to the hook', async () => {
+  const session = { agentEvents: [], activities: {}, workspace: 'docs', headlessPlan: [] };
+  const triggers = [];
+  session._onKnowledgeTrigger = (payload) => triggers.push(payload);
+  const task = { id: 't1', requiredCapability: 'knowledge.update', operation: 'ingest_apply', idempotencyKey: 'sha-1' };
+
+  await accept({ ok: true, taskId: 't1', status: 'succeeded', idempotencyKey: 'sha-1' }, {
+    session,
+    runId: 'run-1',
+    task,
+  });
+
+  assert.ok(session.agentEvents.some((event) => event.type === 'knowledge.ingested'));
+  assert.equal(triggers.length, 1);
+  assert.deepEqual(triggers[0], {
+    workspace: 'docs',
+    trigger: 'knowledge.ingested',
+    // The RUN is the fact: the task's own idempotency key is neither. A
+    // parallel ingest's other tasks must land on the same version.
+    sourceVersion: 'run-1',
+    taskId: 't1',
+    runId: 'run-1',
+  });
+});
+
+test('a completed build publishes no knowledge trigger', async () => {
+  const session = { agentEvents: [], activities: {}, workspace: 'docs', headlessPlan: [] };
+  const triggers = [];
+  session._onKnowledgeTrigger = (payload) => triggers.push(payload);
+
+  await accept({ ok: true, taskId: 't2', status: 'succeeded' }, {
+    session,
+    runId: 'run-1',
+    task: { id: 't2', requiredCapability: 'document.build', operation: 'build' },
+  });
+
+  assert.equal(triggers.length, 0);
+  assert.ok(!session.agentEvents.some((event) => event.type.startsWith('knowledge.')));
+});
+
+test('a completed proactive review is filed under .wiki/agent-reviews, never merged', async () => {
+  const workspacePath = mkdtempSync(join(tmpdir(), 'proactive-review-'));
+  const session = { agentEvents: [], activities: {}, workspace: 'docs', workspacePath, headlessPlan: [] };
+  session._proactiveReview = {
+    id: 'review-1',
+    workspace: 'docs',
+    trigger: 'knowledge.ingested',
+    sourceVersion: 'sha-9',
+    createdAt: '2026-01-01T00:00:00.000Z',
+    budget: { runsToday: 1, inFlight: 1 },
+    evidence: { kind: 'stale', counts: { aged: 0, vanishedArchive: 1, vanishedPage: 0 }, items: [{ kind: 'vanished-archive', path: 'raw/ingested/gone.md' }] },
+  };
+  try {
+    const content = [
+      'The workspace is missing a cost concept.',
+      '[objection] severity: blocking — wiki/concepts/cout/a.md — unsourced claim',
+    ].join('\n');
+    await accept(
+      { ok: true, taskId: 't-review', status: 'succeeded', result: { content } },
+      { session, runId: 'run-review', task: { id: 't-review', requiredCapability: 'agent.review' } },
+    );
+
+    const file = join(workspacePath, '.wiki', 'agent-reviews', 'review-1.json');
+    assert.ok(existsSync(file), 'the review is filed');
+    const record = JSON.parse(readFileSync(file, 'utf8'));
+    assert.equal(record.id, 'review-1');
+    assert.equal(record.trigger, 'knowledge.ingested');
+    assert.equal(record.sourceVersion, 'sha-9');
+    assert.equal(record.status, 'proposed');
+    assert.equal(record.findings.length, 1);
+    assert.equal(record.findings[0].severity, 'blocking');
+    assert.equal(record.findings[0].path, 'wiki/concepts/cout/a.md');
+    // The deterministic evidence travels with the note: "a review happened"
+    // vs "the review knew what to look at".
+    assert.deepEqual(record.evidence, {
+      kind: 'stale',
+      counts: { aged: 0, vanishedArchive: 1, vanishedPage: 0 },
+      items: [{ kind: 'vanished-archive', path: 'raw/ingested/gone.md' }],
+    });
+    // It is a note, not a proposal to merge.
+    assert.ok(!existsSync(join(workspacePath, '.wiki', 'agent-proposals')));
+    assert.equal(session._proactiveReview, null, 'the marker is consumed');
+  } finally {
+    rmSync(workspacePath, { recursive: true, force: true });
+  }
+});
+
+test('a gateway worktree proposal (rawStatus shape) is persisted for review', async () => {
+  const workspacePath = mkdtempSync(join(tmpdir(), 'worktree-proposal-'));
+  const session = { agentEvents: [], activities: {}, workspace: 'docs', workspacePath, headlessPlan: [] };
+  try {
+    const proposal = {
+      workspace: 'docs',
+      branch: 'agent/gateway-1',
+      worktreePath: '/workspaces/docs/.wiki/agent-worktrees/gateway-1',
+      worktreeRelativePath: '.wiki/agent-worktrees/gateway-1',
+      justification: 'dedup',
+      changedFiles: [{ status: 'M', path: 'wiki/a.md' }],
+      changes: [{ path: 'wiki/a.md', status: 'M', content: '# A' }],
+      diff: 'diff --git a/wiki/a.md b/wiki/a.md',
+    };
+    // The dispatcher wraps the agent's status payload under `rawStatus`
+    // (`taskResultFromStatus`). The fixture used to hand `{ result: {...} }`
+    // straight to accept — a shape the real gateway run never produces — so
+    // the proposal was silently dropped and no review item ever appeared.
+    const result = await accept({
+      ok: true,
+      taskId: 't-curate',
+      status: 'completed',
+      outputRefs: [],
+      rawStatus: {
+        runId: 'gateway-1',
+        status: 'completed',
+        result: { status: 'completed', content: 'report', worktreeProposal: proposal },
+      },
+    }, {
+      session,
+      runId: 'run-curate',
+      task: { id: 't-curate', requiredCapability: 'agent.curate', operation: 'run' },
+    });
+
+    assert.equal(result.ok, true);
+    const dir = join(workspacePath, '.wiki', 'agent-proposals');
+    assert.ok(existsSync(dir), 'the proposal directory is created');
+    const record = JSON.parse(readFileSync(join(dir, 't-curate.json'), 'utf8'));
+    assert.equal(record.branch, 'agent/gateway-1');
+    assert.equal(record.changes.length, 1);
+    assert.equal(record.changes[0].path, 'wiki/a.md');
+    // A proposal nobody is told about is a proposal nobody merges.
+    assert.ok(session.agentEvents.some((event) => String(event.payload?.message ?? '').includes('agent-proposal')));
+  } finally {
+    rmSync(workspacePath, { recursive: true, force: true });
+  }
+});