sneakoscope 5.5.2 → 5.6.0

package/dist/core/agent-bridge/mcp-server.js

@@ -0,0 +1,156 @@
+import { fileURLToPath } from 'node:url';
+import { buildAgentManifest } from './agent-manifest.js';
+import { AGENT_MODE_ENV_PASSTHROUGH } from './agent-mode.js';
+import { exists, runProcess } from '../fsx.js';
+const MCP_SERVER_NAME = 'sks-mcp-server';
+const MCP_SERVER_VERSION = '1.0.0';
+// Same dynamic-import trick as src/core/mad-db/mad-db-executor.ts: avoids TS
+// bundling the SDK's ESM entrypoints as a static import target this file must
+// resolve at compile time, while still using the real installed SDK.
+async function loadMcpSdk() {
+    const dynamicImport = new Function('specifier', 'return import(specifier)');
+    const [{ Server }, { StdioServerTransport }, types] = await Promise.all([
+        dynamicImport('@modelcontextprotocol/sdk/server/index.js'),
+        dynamicImport('@modelcontextprotocol/sdk/server/stdio.js'),
+        dynamicImport('@modelcontextprotocol/sdk/types.js')
+    ]);
+    return {
+        Server,
+        StdioServerTransport,
+        ListToolsRequestSchema: types.ListToolsRequestSchema,
+        CallToolRequestSchema: types.CallToolRequestSchema
+    };
+}
+function exposedTools(manifest, exposeExec) {
+    return exposeExec ? manifest : manifest.filter((tool) => tool.read_only === true);
+}
+function toMcpToolDescriptor(entry) {
+    return {
+        name: entry.name,
+        description: entry.description,
+        inputSchema: {
+            type: 'object',
+            properties: {},
+            additionalProperties: true
+        },
+        annotations: {
+            readOnlyHint: entry.read_only,
+            destructiveHint: entry.requires_explicit_opt_in,
+            title: entry.name
+        }
+    };
+}
+async function resolveSksEntrypoint() {
+    // Mirrors src/core/commands/run-command.ts's runSks() bin resolution: prefer the
+    // packaged dist entrypoint, fall back to the source-tree relative path in dev.
+    const packedBin = fileURLToPath(new URL('../../bin/sks.js', import.meta.url));
+    const sourceBin = fileURLToPath(new URL('../../../bin/sks.js', import.meta.url));
+    return (await exists(packedBin)) ? packedBin : sourceBin;
+}
+async function invokeSksTool(entry) {
+    const entrypoint = await resolveSksEntrypoint();
+    const commandArgs = [entry.name, ...(entry.json_output_supported ? ['--json'] : [])];
+    const passthroughEnv = {};
+    for (const name of AGENT_MODE_ENV_PASSTHROUGH)
+        passthroughEnv[name] = '1';
+    const result = await runProcess(process.execPath, [entrypoint, ...commandArgs], {
+        env: { ...passthroughEnv, SKS_AGENT_MODE: '1' },
+        timeoutMs: 180_000,
+        maxOutputBytes: 512 * 1024
+    });
+    return { ok: result.code === 0, stdout: result.stdout, stderr: result.stderr, code: result.code };
+}
+function mcpToolErrorResult(message) {
+    return {
+        content: [{ type: 'text', text: message }],
+        isError: true
+    };
+}
+export async function runMcpServer(opts = {}) {
+    const exposeExec = opts.exposeExec === true;
+    const input = opts.input ?? process.stdin;
+    const output = opts.output ?? process.stdout;
+    const { Server, StdioServerTransport, ListToolsRequestSchema, CallToolRequestSchema } = await loadMcpSdk();
+    const server = new Server({ name: MCP_SERVER_NAME, version: MCP_SERVER_VERSION }, { capabilities: { tools: {} } });
+    server.setRequestHandler(ListToolsRequestSchema, async () => {
+        const manifest = buildAgentManifest();
+        const tools = exposedTools(manifest.tools, exposeExec).map(toMcpToolDescriptor);
+        return { tools };
+    });
+    server.setRequestHandler(CallToolRequestSchema, async (request) => {
+        const toolName = String(request?.params?.name || '');
+        const manifest = buildAgentManifest();
+        const allowed = exposedTools(manifest.tools, exposeExec);
+        // Never spawn a child process for a name the caller invented; only names present
+        // in the (possibly exec-filtered) manifest are legitimate `sks <name>` invocations.
+        const entry = allowed.find((candidate) => candidate.name === toolName);
+        if (!entry) {
+            return mcpToolErrorResult(`Unknown or unexposed tool: ${toolName}`);
+        }
+        try {
+            const result = await invokeSksTool(entry);
+            if (!result.ok) {
+                return mcpToolErrorResult(result.stderr || result.stdout || `sks ${toolName} exited with code ${result.code}`);
+            }
+            return {
+                content: [{ type: 'text', text: result.stdout }],
+                isError: false
+            };
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            return mcpToolErrorResult(`Failed to run sks ${toolName}: ${message}`);
+        }
+    });
+    const transport = new StdioServerTransport(input, output);
+    await server.connect(transport);
+}
+/** Round-trips initialize -> tools/list over in-memory streams and returns, instead of
+ * staying resident on real stdio — this is what `sks mcp-server --probe` runs, so a
+ * fixture/CI check can prove the server actually works without hanging on a real client. */
+export async function probeMcpServer(opts = {}) {
+    const { PassThrough } = await import('node:stream');
+    const clientToServer = new PassThrough();
+    const serverToClient = new PassThrough();
+    const responses = [];
+    let buffer = '';
+    serverToClient.on('data', (chunk) => {
+        buffer += chunk.toString('utf8');
+        let idx;
+        while ((idx = buffer.indexOf('\n')) !== -1) {
+            const line = buffer.slice(0, idx);
+            buffer = buffer.slice(idx + 1);
+            if (line.trim()) {
+                try {
+                    responses.push(JSON.parse(line));
+                }
+                catch { /* not a complete JSON line yet */ }
+            }
+        }
+    });
+    const send = (message) => clientToServer.write(`${JSON.stringify(message)}\n`);
+    const waitForId = async (id, timeoutMs) => {
+        const started = Date.now();
+        while (Date.now() - started < timeoutMs) {
+            const found = responses.find((r) => r.id === id);
+            if (found)
+                return found;
+            await new Promise((resolve) => setTimeout(resolve, 10));
+        }
+        throw new Error(`mcp_probe_timed_out_waiting_for_response_id_${id}`);
+    };
+    runMcpServer({ exposeExec: opts.exposeExec === true, input: clientToServer, output: serverToClient }).catch(() => undefined);
+    const timeoutMs = opts.timeoutMs ?? 10_000;
+    send({ jsonrpc: '2.0', id: 1, method: 'initialize', params: { protocolVersion: '2024-11-05', capabilities: {}, clientInfo: { name: 'sks-mcp-probe', version: '1.0.0' } } });
+    const initResponse = await waitForId(1, timeoutMs);
+    send({ jsonrpc: '2.0', id: 2, method: 'tools/list', params: {} });
+    const listResponse = await waitForId(2, timeoutMs);
+    clientToServer.end();
+    return {
+        ok: Boolean(initResponse?.result) && Array.isArray(listResponse?.result?.tools),
+        server_name: initResponse?.result?.serverInfo?.name || null,
+        protocol_version: initResponse?.result?.protocolVersion || null,
+        tool_count: Array.isArray(listResponse?.result?.tools) ? listResponse.result.tools.length : 0
+    };
+}
+//# sourceMappingURL=mcp-server.js.map

package/dist/core/agents/agent-orchestrator.js

@@ -1,5 +1,6 @@
 import path from 'node:path';
 import { createMission, missionDir, setCurrent } from '../mission.js';
+import { normalizeWorkerPromptText } from '../naruto/normalize-worker-prompt-text.js';
 import { exists, nowIso, readJson, readText, sha256, writeJsonAtomic, writeTextAtomic } from '../fsx.js';
 import { buildAgentRoster, normalizeAgentConcurrency } from './agent-roster.js';
 import { buildAgentWorkPartition } from './agent-work-partition.js';
@@ -2049,17 +2050,6 @@ function buildDirectSdkWorkerPrompt(slice) {
         'Required JSON fields: status, summary, findings, changed_files, patch_envelopes, verification, rollback_notes, blockers.'
     ].join('\n');
 }
-const WORKER_PROMPT_TEXT_MAX_CHARS = 32000;
-function normalizeWorkerPromptText(value) {
-    const normalized = String(value || '').replace(/[^\S\n]+/g, ' ').replace(/\n{3,}/g, '\n\n').trim();
-    const truncated = normalized.length > WORKER_PROMPT_TEXT_MAX_CHARS;
-    const text = truncated ? normalized.slice(0, WORKER_PROMPT_TEXT_MAX_CHARS) : normalized;
-    return {
-        text,
-        truncated,
-        dropped_chars: truncated ? normalized.length - WORKER_PROMPT_TEXT_MAX_CHARS : 0
-    };
-}
 function buildDirectNoPatchReason(slice, opts) {
     const writePathCount = sdkWritePaths(slice, opts).length;
     return {

package/dist/core/commands/agent-bridge-command.js

@@ -0,0 +1,86 @@
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { ensureDir, exists, nowIso, projectRoot, runProcess, writeJsonAtomic } from '../fsx.js';
+import { buildAgentManifest } from '../agent-bridge/agent-manifest.js';
+import { flag } from './command-utils.js';
+async function resolveSksEntrypoint() {
+    // Mirrors src/core/agent-bridge/mcp-server.ts's own bin resolution: prefer the
+    // packaged dist entrypoint, fall back to the source-tree relative path in dev.
+    const packedBin = fileURLToPath(new URL('../../bin/sks.js', import.meta.url));
+    const sourceBin = fileURLToPath(new URL('../../../bin/sks.js', import.meta.url));
+    return (await exists(packedBin)) ? packedBin : sourceBin;
+}
+async function runNonInteractiveSmoke(entrypoint) {
+    const result = await runProcess(process.execPath, [entrypoint, 'status', '--json'], {
+        env: { SKS_AGENT_MODE: '1' },
+        timeoutMs: 15_000,
+        maxOutputBytes: 32 * 1024
+    }).catch((err) => ({ code: 1, stdout: '', stderr: err instanceof Error ? err.message : String(err) }));
+    let stdoutIsCleanJson = false;
+    try {
+        JSON.parse(result.stdout);
+        stdoutIsCleanJson = true;
+    }
+    catch {
+        stdoutIsCleanJson = false;
+    }
+    return {
+        ok: result.code === 0 && stdoutIsCleanJson,
+        command: `SKS_AGENT_MODE=1 ${entrypoint} status --json`,
+        exit_code: result.code,
+        note: stdoutIsCleanJson
+            ? 'stdout parsed as clean JSON with SKS_AGENT_MODE=1 set — non-interactive contract verified end-to-end for this one command.'
+            : 'stdout did not parse as clean JSON; a real agent host would fail to consume this — see exit_code/stderr in the report.'
+    };
+}
+function registrationSnippets() {
+    return {
+        generic_mcp_host: { command: 'sks', args: ['mcp-server'] },
+        codex_cli: 'codex mcp add sks -- sks mcp-server',
+        non_interactive_cli: {
+            env: { SKS_AGENT_MODE: '1' },
+            example: 'SKS_AGENT_MODE=1 sks status --json',
+            streaming_example: 'SKS_AGENT_MODE=1 sks qa-loop run <mission> --mock --stream --json'
+        }
+    };
+}
+export async function agentBridgeCommand(subcommand, args = []) {
+    const sub = subcommand || 'setup';
+    if (sub !== 'setup') {
+        const result = { ok: false, error: `unknown_subcommand:${sub}`, supported: ['setup'] };
+        if (flag(args, '--json'))
+            console.log(JSON.stringify(result, null, 2));
+        else
+            console.log(`Unknown agent-bridge subcommand "${sub}". Supported: setup`);
+        return result;
+    }
+    const root = await projectRoot();
+    const manifest = buildAgentManifest();
+    const manifestPath = path.join(root, '.sneakoscope', 'agent-bridge', 'manifest.json');
+    await ensureDir(path.dirname(manifestPath));
+    await writeJsonAtomic(manifestPath, manifest);
+    const entrypoint = await resolveSksEntrypoint();
+    const smoke = await runNonInteractiveSmoke(entrypoint);
+    const result = {
+        schema: 'sks.agent-bridge-setup.v1',
+        generated_at: nowIso(),
+        ok: smoke.ok,
+        manifest_path: manifestPath,
+        tool_count: manifest.tools.length,
+        registration_snippets: registrationSnippets(),
+        non_interactive_smoke: smoke
+    };
+    if (flag(args, '--json')) {
+        console.log(JSON.stringify(result, null, 2));
+    }
+    else {
+        console.log(`Agent bridge manifest written: ${manifestPath} (${manifest.tools.length} tools)`);
+        console.log('Register with a generic MCP host:');
+        console.log(`  ${JSON.stringify(registrationSnippets().generic_mcp_host)}`);
+        console.log('Register with Codex CLI:');
+        console.log(`  ${registrationSnippets().codex_cli}`);
+        console.log(`Non-interactive smoke test: ${smoke.ok ? 'ok' : 'FAILED'} (${smoke.note})`);
+    }
+    return result;
+}
+//# sourceMappingURL=agent-bridge-command.js.map

package/dist/core/commands/image-ux-review-command.js

@@ -65,7 +65,7 @@ export async function imageUxReviewCommand(command, args = []) {
 async function runImageUxReview(root, command, args = []) {
     const missionRequested = readOption(args, '--mission', null);
     const missionId = missionRequested
-        ? missionRequested === 'latest' ? await findLatestMission(root) : missionRequested
+        ? missionRequested === 'latest' ? await findLatestMission(root, { mode: 'image-ux-review', route: '$Image-UX-Review', gateFile: IMAGE_UX_REVIEW_GATE_ARTIFACT }) : missionRequested
         : null;
     const imagePath = readOption(args, '--image', null) || readOption(args, '--screenshot', null);
     const generatedImage = readOption(args, '--generated-image', null);
@@ -277,7 +277,7 @@ async function extractIssuesImageUxReview(root, command, args = []) {
 }
 async function attachGeneratedImageCommand(root, command, args = []) {
     const missionArg = args.find((arg) => !String(arg).startsWith('--')) || 'latest';
-    const missionId = missionArg === 'latest' ? await findLatestMission(root) : missionArg;
+    const missionId = missionArg === 'latest' ? await findLatestMission(root, { mode: 'image-ux-review', route: '$Image-UX-Review', gateFile: IMAGE_UX_REVIEW_GATE_ARTIFACT }) : missionArg;
     const imagePath = readOption(args, '--image', null) || readOption(args, '--generated-image', null);
     if (!missionId || !imagePath) {
         const result = { schema: 'sks.image-ux-review-attach-generated.v1', ok: false, status: 'blocked', blocker: !missionId ? 'mission_required' : 'generated_image_required' };
@@ -298,7 +298,7 @@ async function attachGeneratedImageCommand(root, command, args = []) {
 }
 async function attachAfterImageCommand(root, command, args = []) {
     const missionArg = args.find((arg) => !String(arg).startsWith('--')) || 'latest';
-    const missionId = missionArg === 'latest' ? await findLatestMission(root) : missionArg;
+    const missionId = missionArg === 'latest' ? await findLatestMission(root, { mode: 'image-ux-review', route: '$Image-UX-Review', gateFile: IMAGE_UX_REVIEW_GATE_ARTIFACT }) : missionArg;
     const imagePath = readOption(args, '--image', null) || readOption(args, '--screenshot', null);
     if (!missionId || !imagePath) {
         const result = { schema: 'sks.image-ux-review-attach-after.v1', ok: false, status: 'blocked', blocker: !missionId ? 'mission_required' : 'after_image_required' };
@@ -327,7 +327,7 @@ async function attachAfterImageCommand(root, command, args = []) {
 }
 async function rebuildExistingMission(root, command, args = [], opts = {}) {
     const missionArg = args.find((arg) => !String(arg).startsWith('--')) || 'latest';
-    const missionId = missionArg === 'latest' ? await findLatestMission(root) : missionArg;
+    const missionId = missionArg === 'latest' ? await findLatestMission(root, { mode: 'image-ux-review', route: '$Image-UX-Review', gateFile: IMAGE_UX_REVIEW_GATE_ARTIFACT }) : missionArg;
     if (!missionId)
         return missingMission(args);
     const { dir, mission } = await loadMission(root, missionId);
@@ -352,7 +352,7 @@ async function rebuildExistingMission(root, command, args = [], opts = {}) {
 }
 async function statusImageUxReview(root, args = []) {
     const missionArg = args.find((arg) => !String(arg).startsWith('--')) || 'latest';
-    const missionId = missionArg === 'latest' ? await findLatestMission(root) : missionArg;
+    const missionId = missionArg === 'latest' ? await findLatestMission(root, { mode: 'image-ux-review', route: '$Image-UX-Review', gateFile: IMAGE_UX_REVIEW_GATE_ARTIFACT }) : missionArg;
     if (!missionId)
         return missingMission(args);
     const { dir } = await loadMission(root, missionId);
@@ -372,7 +372,7 @@ async function statusImageUxReview(root, args = []) {
 }
 async function explainImageUxReview(root, args = []) {
     const missionArg = args.find((arg) => !String(arg).startsWith('--')) || 'latest';
-    const missionId = missionArg === 'latest' ? await findLatestMission(root) : missionArg;
+    const missionId = missionArg === 'latest' ? await findLatestMission(root, { mode: 'image-ux-review', route: '$Image-UX-Review', gateFile: IMAGE_UX_REVIEW_GATE_ARTIFACT }) : missionArg;
     if (!missionId)
         return missingMission(args);
     const { dir } = await loadMission(root, missionId);

package/dist/core/commands/loop-command.js

@@ -1,6 +1,6 @@
 import path from 'node:path';
 import { printJson } from '../../cli/output.js';
-import { createMission, findLatestMission, loadMission, setCurrent } from '../mission.js';
+import { createMission, findLatestMission, setCurrent } from '../mission.js';
 import { readJson, sksRoot } from '../fsx.js';
 import { loopActiveWorkerHandlesPath, loopIntegrationMergePath, loopLatestCheckpointPath, loopPlanPath, loopProofPath, loopRoot, loopSideEffectReportPath } from '../loops/loop-artifacts.js';
 import { finalizeLoopGraph } from '../loops/loop-finalizer.js';
@@ -192,11 +192,7 @@ async function loopResume(args) {
 async function resolveLoopMission(root, arg) {
     if (arg && arg !== 'latest')
         return arg;
-    const latest = await findLatestMission(root);
-    if (!latest)
-        return null;
-    const loaded = await loadMission(root, latest).catch(() => null);
-    return loaded?.mission?.mode === 'loop' || await readJson(loopPlanPath(root, latest), null) ? latest : null;
+    return findLatestMission(root, { mode: 'loop' });
 }
 function normalizeParallelism(value) {
     return value === 'safe' || value === 'extreme' ? value : 'balanced';

package/dist/core/commands/mad-sks-command.js

@@ -1014,7 +1014,7 @@ async function madSksSubcommand(subcommand, args = []) {
     if (subcommand === 'doctor' || subcommand === 'status') {
         const protectedCore = resolveProtectedCore({ packageRoot: packageRoot(), targetRoot });
         const before = await snapshotProtectedCore(packageRoot(), 'status');
-        const statusMissionId = await findLatestMission(root);
+        const statusMissionId = await findLatestMission(root, { mode: 'mad-sks', route: '$MAD-SKS', gateFile: 'mad-sks-gate.json' });
         const gateVerdict = statusMissionId
             ? await evaluateGate(root, statusMissionId, 'mad-sks-gate.json')
             : await evaluateGate(root, 'no-mission', 'mad-sks-gate.json');
@@ -1330,7 +1330,7 @@ async function materializeMadSksRun(root, targetRoot, permission, userIntent, js
     }, json);
 }
 async function closeMadSks(root, args = [], json = false, action = 'close') {
-    const missionId = readOption(args, '--mission', null) || args.find((arg) => !String(arg).startsWith('--')) || await findLatestMission(root);
+    const missionId = readOption(args, '--mission', null) || args.find((arg) => !String(arg).startsWith('--')) || await findLatestMission(root, { mode: 'mad-sks', route: '$MAD-SKS', gateFile: 'mad-sks-gate.json' });
     if (!missionId) {
         const result = { schema: 'sks.mad-sks-close.v1', ok: false, action, mission_id: null, blockers: ['mad_sks_mission_missing'] };
         process.exitCode = 1;
@@ -1354,7 +1354,7 @@ async function closeMadSks(root, args = [], json = false, action = 'close') {
     return emit(result, json);
 }
 async function cleanupExpiredMadSks(root) {
-    const missionId = await findLatestMission(root);
+    const missionId = await findLatestMission(root, { mode: 'mad-sks', route: '$MAD-SKS', gateFile: 'mad-sks-gate.json' });
     if (!missionId)
         return null;
     const gate = await readJson(path.join(missionDir(root, missionId), 'mad-sks-gate.json'), null);

package/dist/core/commands/mcp-server-command.js

@@ -0,0 +1,13 @@
+import { probeMcpServer, runMcpServer } from '../agent-bridge/mcp-server.js';
+import { flag } from './command-utils.js';
+export async function mcpServerCommand(args = []) {
+    const exposeExec = flag(args, '--expose-exec');
+    if (flag(args, '--probe')) {
+        const result = await probeMcpServer({ exposeExec });
+        console.log(JSON.stringify({ schema: 'sks.mcp-server-probe.v1', ...result }, null, 2));
+        process.exitCode = result.ok ? 0 : 1;
+        return;
+    }
+    await runMcpServer({ exposeExec });
+}
+//# sourceMappingURL=mcp-server-command.js.map

package/dist/core/commands/naruto-command.js

@@ -741,7 +741,7 @@ function validRegressionProof(proof) {
 }
 async function narutoStatus(parsed) {
     const root = await sksRoot();
-    const id = parsed.missionId && parsed.missionId !== 'latest' ? parsed.missionId : await findLatestMission(root);
+    const id = parsed.missionId && parsed.missionId !== 'latest' ? parsed.missionId : await findLatestMission(root, { mode: 'naruto' });
     if (!id)
         return emit(parsed, { schema: NARUTO_RESULT_SCHEMA, ok: false, action: 'status', status: 'missing_mission' }, () => console.log('No Naruto mission found.'));
     const { dir } = await loadMission(root, id);
@@ -780,7 +780,7 @@ async function narutoStatus(parsed) {
 }
 async function narutoDashboard(parsed) {
     const root = await sksRoot();
-    const id = parsed.missionId && parsed.missionId !== 'latest' ? parsed.missionId : await findLatestMission(root);
+    const id = parsed.missionId && parsed.missionId !== 'latest' ? parsed.missionId : await findLatestMission(root, { mode: 'naruto' });
     if (!id)
         return emit(parsed, { schema: NARUTO_RESULT_SCHEMA, ok: false, action: 'dashboard', status: 'missing_mission' }, () => console.log('No Naruto mission found.'));
     const { dir } = await loadMission(root, id);
@@ -804,7 +804,7 @@ async function narutoDashboard(parsed) {
 }
 async function narutoWorkers(parsed) {
     const root = await sksRoot();
-    const id = parsed.missionId && parsed.missionId !== 'latest' ? parsed.missionId : await findLatestMission(root);
+    const id = parsed.missionId && parsed.missionId !== 'latest' ? parsed.missionId : await findLatestMission(root, { mode: 'naruto' });
     if (!id)
         return emit(parsed, { schema: NARUTO_RESULT_SCHEMA, ok: false, action: 'workers', status: 'missing_mission' }, () => console.log('No Naruto mission found.'));
     const { dir } = await loadMission(root, id);
@@ -831,7 +831,7 @@ async function narutoWorkers(parsed) {
 }
 async function narutoProof(parsed) {
     const root = await sksRoot();
-    const id = parsed.missionId && parsed.missionId !== 'latest' ? parsed.missionId : await findLatestMission(root);
+    const id = parsed.missionId && parsed.missionId !== 'latest' ? parsed.missionId : await findLatestMission(root, { mode: 'naruto' });
     if (!id)
         return emit(parsed, { schema: NARUTO_RESULT_SCHEMA, ok: false, action: 'proof', status: 'missing_mission' }, () => console.log('No Naruto mission found.'));
     const summary = await buildRuntimeProofSummary(root, id, { maxMessages: parsed.messages });

package/dist/core/commands/ppt-command.js

@@ -20,7 +20,10 @@ export async function pptCommand(command, args = []) {
     if (action === 'explain')
         return pptExplain(root, args.slice(1));
     const missionArg = args[1] && !String(args[1]).startsWith('--') ? args[1] : 'latest';
-    const missionId = missionArg === 'latest' ? await findLatestMission(root) : missionArg;
+    // build/status act on ppt-gate.json (written by build, not the imagegen-review gate),
+    // so scope by mode only here - requiring the imagegen-review gate would wrongly exclude
+    // a fresh ppt mission that hasn't gone through review yet.
+    const missionId = missionArg === 'latest' ? await findLatestMission(root, { mode: 'ppt' }) : missionArg;
     if (!missionId)
         return missingMission(args);
     const { dir, mission } = await loadMission(root, missionId);
@@ -93,7 +96,7 @@ async function pptImagegenReview(root, command, action, args = []) {
     const shouldCreate = Boolean(deckPath || mockMode || action === 'review' || action === 'export-slides' || action === 'slide-export' || action === 'callouts' || action === 'extract-issues');
     const missionId = shouldCreate && !missionArg
         ? null
-        : missionArg === 'latest' || !missionArg ? await findLatestMission(root) : missionArg;
+        : missionArg === 'latest' || !missionArg ? await findLatestMission(root, { mode: 'ppt', route: '$PPT', gateFile: PPT_IMAGEGEN_REVIEW_GATE_ARTIFACT }) : missionArg;
     const loaded = missionId ? await loadMission(root, missionId) : await createMission(root, { mode: 'ppt', prompt: `PPT imagegen review ${deckPath || 'fixture'}` });
     const id = 'id' in loaded ? loaded.id : missionId;
     const dir = loaded.dir;
@@ -243,7 +246,7 @@ async function pptFixture(root, command, args) {
 }
 async function pptExplain(root, args = []) {
     const missionArg = args.find((arg) => !String(arg).startsWith('--')) || 'latest';
-    const missionId = missionArg === 'latest' ? await findLatestMission(root) : missionArg;
+    const missionId = missionArg === 'latest' ? await findLatestMission(root, { mode: 'ppt', route: '$PPT', gateFile: PPT_IMAGEGEN_REVIEW_GATE_ARTIFACT }) : missionArg;
     if (!missionId)
         return missingMission(args);
     const { dir } = await loadMission(root, missionId);