@pugi/cli 0.1.0-beta.93 → 0.1.0-beta.94

package/dist/core/mcp/orchestrator-config.js

@@ -0,0 +1,192 @@
+/**
+ * Pugi MCP orchestrator config (Trust Sprint item 7).
+ *
+ * BEFORE this module the customer had to wire three independent gates
+ * to actually run the orchestrator surface successfully:
+ *
+ *   PUGI_MCP_EXEC_ENABLED=1   (env)   — gates pugi.run + pugi.dispatch
+ *   --allow-bash              (flag)  — surfaces the bash permission class
+ *   PUGI_MCP_PUGI_BIN=...     (env)   — points the dispatcher at a binary
+ *
+ * Missing any one of the three produced an opaque "tool refused" or
+ * "binary not found" error that nobody could correlate back to the
+ * three-knob configuration. Codex deep-research 2026-06-04 logged this
+ * as a discipline gap.
+ *
+ * AFTER this module the customer flips ONE switch:
+ *
+ *   PUGI_MCP_ORCHESTRATOR=1
+ *
+ * Or one flag:
+ *
+ *   pugi mcp serve --orchestrator-bundle
+ *
+ * Either form:
+ *   - enables exec gating on pugi.run + pugi.dispatch,
+ *   - turns on the bash permission class (equivalent to --allow-bash),
+ *   - auto-resolves `pugi` from PATH (or the local dev binary when
+ *     invoked from a monorepo checkout).
+ *
+ * The legacy multi-knob configuration continues to work as deprecated
+ * aliases. When the legacy combo is observed at boot we emit a stderr
+ * warning so operators know they should migrate.
+ *
+ * Scope rule: this module is ADDITIVE. It does not modify
+ * orchestrator-tools.ts or the dispatch handler (other agent owns
+ * those files in PUGI-VERIFY-GATE).
+ */
+import { existsSync } from 'node:fs';
+import { dirname, isAbsolute, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { execFileSync } from 'node:child_process';
+import { warnDeprecation } from '../../runtime/deprecation-warning.js';
+/**
+ * Resolve the effective orchestrator configuration from inputs.
+ *
+ * Single source of truth for the gate-collapse logic. `runtime/commands/
+ * mcp.ts` consumes the result; tests call this function directly.
+ */
+export function resolveOrchestratorConfig(input) {
+    const env = input.env;
+    const bundleViaEnv = env.PUGI_MCP_ORCHESTRATOR === '1';
+    const bundleViaFlag = input.bundleFlag;
+    const bundleEnabled = bundleViaEnv || bundleViaFlag;
+    const execViaLegacyEnv = env.PUGI_MCP_EXEC_ENABLED === '1';
+    const publishViaLegacyEnv = env.PUGI_MCP_PUBLISH_ENABLED === '1';
+    const deployViaLegacyEnv = env.PUGI_MCP_DEPLOY_ENABLED === '1';
+    const bashViaFlag = input.bashFlag;
+    // Bundle implies exec + bash. Publish + deploy stay opt-in even under
+    // bundle because they cross network boundaries (npm publish, ssh
+    // deploy) — operator should still flip them deliberately.
+    const execEnabled = bundleEnabled || execViaLegacyEnv;
+    const publishEnabled = publishViaLegacyEnv;
+    const deployEnabled = deployViaLegacyEnv;
+    const bashAllowed = bundleEnabled || bashViaFlag;
+    // Emit deprecation warning the first time we see the OLD multi-flag
+    // combo without the bundle flag. We only warn if the operator clearly
+    // intended the orchestrator surface (at least one legacy env set) so
+    // bare engine-surface runs stay silent.
+    if (!bundleEnabled && execViaLegacyEnv) {
+        warnDeprecation('PUGI_MCP_EXEC_ENABLED', 'PUGI_MCP_ORCHESTRATOR=1', 'Single flag enables exec + bash + auto-resolves the pugi binary in one step.');
+    }
+    const { pugiBin, pugiBinSource } = resolvePugiBin({
+        envOverride: env.PUGI_MCP_PUGI_BIN ?? null,
+        workspaceRoot: input.workspaceRoot,
+        resolveBinary: input.resolveBinary ?? defaultBinaryResolver,
+    });
+    return {
+        bundleEnabled,
+        execEnabled,
+        publishEnabled,
+        deployEnabled,
+        bashAllowed,
+        pugiBin,
+        source: {
+            bundleViaEnv,
+            bundleViaFlag,
+            execViaLegacyEnv,
+            publishViaLegacyEnv,
+            deployViaLegacyEnv,
+            bashViaFlag,
+            pugiBinSource,
+        },
+    };
+}
+/**
+ * Resolve the `pugi` binary path. Layered fallback so operators get a
+ * working dispatcher whether they `npm i -g @pugi/cli`-ed it (PATH),
+ * baked it into env (CI), or are running from a monorepo checkout
+ * (where `pugi` is not on PATH but `dist/index.js` exists).
+ */
+function resolvePugiBin(input) {
+    if (input.envOverride && input.envOverride.length > 0) {
+        return { pugiBin: input.envOverride, pugiBinSource: 'env' };
+    }
+    const fromPath = input.resolveBinary('pugi');
+    if (fromPath && fromPath.length > 0) {
+        return { pugiBin: fromPath, pugiBinSource: 'path-lookup' };
+    }
+    const devBinary = findMonorepoDevBinary(input.workspaceRoot);
+    if (devBinary) {
+        return { pugiBin: devBinary, pugiBinSource: 'monorepo-dev-binary' };
+    }
+    // Last-resort fallback. The downstream `execFile` will throw ENOENT
+    // with a path readable error; better that than us swallowing the
+    // intent of "operator wanted orchestrator mode" silently.
+    return { pugiBin: 'pugi', pugiBinSource: 'fallback' };
+}
+/**
+ * Walk up from the workspace root looking for the monorepo pugi-cli
+ * checkout. Used when an operator runs `pugi mcp serve --orchestrator-
+ * bundle` from inside a freshly-cloned `pugi-io/pugi` repo without a
+ * global install. Skipped for non-monorepo workspaces (returns null
+ * quickly when the expected marker files are absent).
+ */
+function findMonorepoDevBinary(workspaceRoot) {
+    const candidates = [];
+    // Common shapes: workspaceRoot IS the monorepo, or workspaceRoot is
+    // a sibling sub-app of pugi-cli. Limit the walk to two levels up.
+    let current = workspaceRoot;
+    for (let i = 0; i < 4; i += 1) {
+        candidates.push(resolve(current, 'apps/pugi-cli/dist/index.js'));
+        candidates.push(resolve(current, 'apps/pugi-cli/bin/run.js'));
+        const parent = dirname(current);
+        if (parent === current)
+            break;
+        current = parent;
+    }
+    for (const candidate of candidates) {
+        if (existsSync(candidate))
+            return candidate;
+    }
+    return null;
+}
+/**
+ * Default `which`-backed binary resolver. Mirrors the pattern used by
+ * `resolveExecutablePath` in `runtime/commands/mcp.ts`. Returns null
+ * on any failure — the caller falls back to the next layer.
+ */
+function defaultBinaryResolver(command) {
+    if (isAbsolute(command)) {
+        return existsSync(command) ? command : null;
+    }
+    if (command.includes('/') || command.includes('\\'))
+        return null;
+    try {
+        const out = execFileSync('/usr/bin/which', [command], {
+            stdio: ['ignore', 'pipe', 'ignore'],
+            encoding: 'utf8',
+            timeout: 5000,
+        }).trim();
+        return out.length > 0 ? out : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Compose a human-readable diagnostic line per resolved config. Used
+ * by `pugi mcp serve --orchestrator*` startup output and `pugi doctor`
+ * so operators can verify which gates ended up live.
+ */
+export function describeOrchestratorConfig(config) {
+    const lines = [];
+    lines.push(`bundle: ${config.bundleEnabled ? 'on' : 'off'}`);
+    lines.push(`exec: ${config.execEnabled ? 'on' : 'off'}`);
+    lines.push(`publish: ${config.publishEnabled ? 'on' : 'off'}`);
+    lines.push(`deploy: ${config.deployEnabled ? 'on' : 'off'}`);
+    lines.push(`bash surfaced: ${config.bashAllowed ? 'on' : 'off'}`);
+    lines.push(`pugi binary: ${config.pugiBin} (source: ${config.source.pugiBinSource})`);
+    return lines;
+}
+/**
+ * Exported for tests so the dev-binary fallback can be exercised
+ * without invoking the full resolver. Kept internal to the module
+ * otherwise.
+ */
+export const _internalForTests = {
+    findMonorepoDevBinary,
+    resolvePugiBin,
+    currentModuleDir: () => dirname(fileURLToPath(import.meta.url)),
+};
+//# sourceMappingURL=orchestrator-config.js.map

package/dist/core/mcp/orchestrator-tools.js

@@ -358,8 +358,15 @@ export function buildOrchestratorTools(ctx) {
                     : ctx.workspaceRoot;
                 const timeoutMs = optionalNumber(args, 'timeoutMs', 180000);
                 const started = Date.now();
+                // PUGI-VERIFY-GATE: dispatch the child with `--json` so we
+                // can parse its structured outcome envelope. The CLI's JSON
+                // mode includes verified / verificationCommands /
+                // verificationFailures / unverifiedReason /
+                // regressionOwnershipDispute. The MCP response now carries
+                // those fields through alongside the honest exit code so
+                // callers see the gate state, not just a "ran" boolean.
                 try {
-                    const { stdout, stderr } = await execImpl(ctx.pugiBin, [command, prompt, '--no-tty'], {
+                    const { stdout, stderr } = await execImpl(ctx.pugiBin, [command, prompt, '--no-tty', '--json'], {
                         cwd,
                         timeout: timeoutMs,
                         maxBuffer: 8 * 1024 * 1024,
@@ -370,13 +377,33 @@ export function buildOrchestratorTools(ctx) {
                         // `pugi login` state when both are present.
                         env: dispatchEnv(),
                     });
+                    // Codex dogfood 2026-06-04: the prior implementation
+                    // hardcoded `exitCode: 0` on the happy execImpl path even
+                    // when the child surfaced a verification failure through
+                    // `--json`. The child's `--json` envelope is the source of
+                    // truth — parse it and mirror `verified` / `status` back
+                    // to the MCP caller. The execImpl-level "no throw" signal
+                    // is no longer trusted as "exit 0".
+                    const parsed = parseDispatchEnvelope(stdout);
+                    const dispatchExitCode = resolveDispatchExitCode(parsed);
                     return JSON.stringify({
                         command,
                         cwd,
-                        exitCode: 0,
+                        // CRITICAL: derived from parsed envelope, not constant 0.
+                        exitCode: dispatchExitCode,
                         durationMs: Date.now() - started,
                         stdout: clamp(stdout, 16 * 1024),
                         stderr: clamp(stderr, 4 * 1024),
+                        ...(parsed
+                            ? {
+                                status: parsed.status,
+                                verified: parsed.verified,
+                                verificationCommands: parsed.verificationCommands,
+                                verificationFailures: parsed.verificationFailures,
+                                unverifiedReason: parsed.unverifiedReason,
+                                regressionOwnershipDispute: parsed.regressionOwnershipDispute,
+                            }
+                            : {}),
                     });
                 }
                 catch (err) {
@@ -386,15 +413,35 @@ export function buildOrchestratorTools(ctx) {
                     // ENOENT"`. Operators need to distinguish "pugi binary missing"
                     // from "pugi ran and exited 1 silently."
                     const stderrText = e.stderr || e.message || '';
+                    // PUGI-VERIFY-GATE: even on the throw path, parse stdout
+                    // when present so the verification gate state surfaces.
+                    // The child's CLI exits non-zero for failed / blocked /
+                    // needs_verification, which puts execImpl on this path.
+                    const parsed = parseDispatchEnvelope(e.stdout ?? '');
+                    const dispatchExitCode = typeof e.code === 'number'
+                        ? e.code
+                        : parsed
+                            ? resolveDispatchExitCode(parsed)
+                            : 1;
                     return JSON.stringify({
                         command,
                         cwd,
-                        exitCode: typeof e.code === 'number' ? e.code : 1,
+                        exitCode: dispatchExitCode,
                         durationMs: Date.now() - started,
                         stdout: clamp(e.stdout ?? '', 16 * 1024),
                         stderr: clamp(stderrText, 4 * 1024),
                         ...(e.signal ? { signal: e.signal } : {}),
                         ...(e.killed ? { killed: true } : {}),
+                        ...(parsed
+                            ? {
+                                status: parsed.status,
+                                verified: parsed.verified,
+                                verificationCommands: parsed.verificationCommands,
+                                verificationFailures: parsed.verificationFailures,
+                                unverifiedReason: parsed.unverifiedReason,
+                                regressionOwnershipDispute: parsed.regressionOwnershipDispute,
+                            }
+                            : {}),
                     });
                 }
             },
@@ -659,4 +706,101 @@ export const ORCHESTRATOR_TOOLS_MODULE_FILE = (() => {
         return '';
     }
 })();
+/**
+ * Try to extract the JSON envelope from the child CLI's stdout.
+ * The CLI prints a single JSON object on the trailing line when
+ * `--json` is passed; older builds may interleave status events on
+ * stderr but always emit the final JSON on stdout. Scan from the
+ * end of stdout backwards looking for the first balanced JSON
+ * object so a mixed stdout (e.g. with leading banner) still
+ * parses.
+ *
+ * Returns null on any parse failure; the caller falls back to
+ * legacy behaviour (no verification fields surfaced).
+ */
+export function parseDispatchEnvelope(stdout) {
+    if (typeof stdout !== 'string' || stdout.trim() === '')
+        return null;
+    const trimmed = stdout.trim();
+    // Fast path: stdout is a single JSON object (most common).
+    if (trimmed.startsWith('{') && trimmed.endsWith('}')) {
+        try {
+            const parsed = JSON.parse(trimmed);
+            return normaliseEnvelope(parsed);
+        }
+        catch {
+            // fall through to multi-line scan
+        }
+    }
+    // Slow path: scan trailing lines for the last JSON-looking line.
+    const lines = trimmed.split('\n');
+    for (let i = lines.length - 1; i >= 0; i -= 1) {
+        const line = lines[i]?.trim();
+        if (!line || !line.startsWith('{') || !line.endsWith('}'))
+            continue;
+        try {
+            const parsed = JSON.parse(line);
+            return normaliseEnvelope(parsed);
+        }
+        catch {
+            // try the next line up
+        }
+    }
+    return null;
+}
+function normaliseEnvelope(raw) {
+    if (typeof raw['status'] !== 'string')
+        return null;
+    const result = { status: raw['status'] };
+    if (typeof raw['verified'] === 'boolean')
+        result.verified = raw['verified'];
+    if (Array.isArray(raw['verificationCommands'])) {
+        result.verificationCommands = raw['verificationCommands'].filter((item) => typeof item === 'string');
+    }
+    if (Array.isArray(raw['verificationFailures'])) {
+        const failures = [];
+        for (const item of raw['verificationFailures']) {
+            if (item && typeof item === 'object') {
+                const r = item;
+                if (typeof r['command'] === 'string' &&
+                    typeof r['exitCode'] === 'number') {
+                    failures.push({
+                        command: r['command'],
+                        exitCode: r['exitCode'],
+                        tailStderr: typeof r['tailStderr'] === 'string' ? r['tailStderr'] : '',
+                    });
+                }
+            }
+        }
+        result.verificationFailures = failures;
+    }
+    if (typeof raw['unverifiedReason'] === 'string') {
+        result.unverifiedReason = raw['unverifiedReason'];
+    }
+    if (typeof raw['regressionOwnershipDispute'] === 'boolean') {
+        result.regressionOwnershipDispute = raw['regressionOwnershipDispute'];
+    }
+    return result;
+}
+/**
+ * Honest exit code derivation from the parsed envelope. Mirrors
+ * `resolveEngineExitCode` in `cli.ts` so the MCP wrapper's
+ * propagation matches what the child CLI actually exits with — a
+ * test can assert on either surface and see consistent codes.
+ */
+export function resolveDispatchExitCode(envelope) {
+    if (envelope === null)
+        return 0;
+    if (envelope.status === 'needs_verification')
+        return 2;
+    if (envelope.unverifiedReason === 'verification_command_failed')
+        return 1;
+    if (envelope.status === 'done')
+        return 0;
+    if (envelope.status === 'failed')
+        return 1;
+    if (envelope.status === 'blocked')
+        return 1;
+    return 1;
+}
 //# sourceMappingURL=orchestrator-tools.js.map

package/dist/core/pugi-gitignore.js

@@ -0,0 +1,52 @@
+/**
+ * Ensure `.gitignore` covers Pugi's local persistence directories.
+ *
+ * Triple-review P1 (2026-06-04, ): commands that write under
+ * `.pugi/` must guarantee a `.gitignore` entry exists BEFORE the first
+ * write. Otherwise the first customer run of e.g. `pugi retro` in a
+ * fresh repo leaves `.pugi/retros/` and any future `.pugi/settings.json`
+ * (secret store) tracked by git on the next `git add -A`.
+ *
+ * Extracted from `runtime/cli.ts` so any command that mutates `.pugi/`
+ * can share the same guarantee without depending on the heavy cli.ts
+ * module graph.
+ */
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+export const DEFAULT_PUGI_GITIGNORE_MARKERS = [
+    '.pugi/',
+    '.claude/worktrees/',
+];
+const EQUIVALENTS = {
+    '.pugi/': ['.pugi/', '/.pugi/', '.pugi'],
+    '.claude/worktrees/': ['.claude/worktrees/', '/.claude/worktrees/', '.claude/worktrees'],
+};
+export function ensurePugiGitIgnore(cwd, created, skipped, markers = DEFAULT_PUGI_GITIGNORE_MARKERS) {
+    const gitignorePath = resolve(cwd, '.gitignore');
+    if (!existsSync(gitignorePath)) {
+        writeFileSync(gitignorePath, `${markers.join('\n')}\n`, {
+            encoding: 'utf8',
+            mode: 0o600,
+        });
+        created.push(gitignorePath);
+        return;
+    }
+    const current = readFileSync(gitignorePath, 'utf8');
+    const lines = current.split('\n').map((line) => line.trim());
+    const toAppend = [];
+    for (const marker of markers) {
+        const variants = EQUIVALENTS[marker] ?? [marker];
+        const present = variants.some((variant) => lines.includes(variant));
+        if (!present)
+            toAppend.push(marker);
+    }
+    if (toAppend.length === 0) {
+        skipped.push(gitignorePath);
+        return;
+    }
+    const trailing = current.endsWith('\n') ? '' : '\n';
+    const next = `${current}${trailing}${toAppend.join('\n')}\n`;
+    writeFileSync(gitignorePath, next, { encoding: 'utf8' });
+    created.push(`${gitignorePath} (+${toAppend.join(', ')})`);
+}
+//# sourceMappingURL=pugi-gitignore.js.map

package/dist/core/repl/engine-bridge.js

@@ -0,0 +1,199 @@
+import { AnvilEngineLoopClient } from '../engine/anvil-client.js';
+import { NativePugiEngineAdapter } from '../engine/native-pugi.js';
+import { openSession } from '../session.js';
+/**
+ * Translate `pugi-tool-route command="..."` into the SDK's
+ * `EngineTaskKind`. `code` and `fix` pass through verbatim; `build`
+ * maps to `build_task` per `apps/pugi-cli/src/core/engine/native-pugi.ts:1444`
+ * (`toCommandKind`).
+ */
+function commandToTaskKind(command) {
+    if (command === 'build')
+        return 'build_task';
+    return command;
+}
+/**
+ * Translate one `EngineStreamEvent` (rich, adapter-internal vocabulary)
+ * into the REPL bridge's narrow `BridgedEngineEvent` shape (four
+ * variants -- step / tool.start / tool.result / tokens).
+ *
+ * Returns `null` for events the bridge surface deliberately ignores
+ * (`tool.delta` payloads are surfaced via `tool.result` summary;
+ * `thinking.*` and `text.delta` deltas are not part of the bridge
+ * UX contract -- the synthetic agent-tree node renders a single
+ * `detail` line, not a streaming thinking block).
+ *
+ * Mutates `names` so a follow-up `tool.end` can resolve its callId
+ * back to the recorded tool name (`tool.end` carries only `callId`).
+ */
+function translateStreamEvent(event, names) {
+    if (event.type === 'status') {
+        return { type: 'step', detail: event.message };
+    }
+    if (event.type === 'tool.start') {
+        names.set(event.callId, event.name);
+        return {
+            type: 'tool.start',
+            tool: event.name,
+            args: event.arguments,
+        };
+    }
+    if (event.type === 'tool.end') {
+        const name = names.get(event.callId) ?? '';
+        names.delete(event.callId);
+        return {
+            type: 'tool.result',
+            tool: name,
+            ok: event.ok,
+            preview: event.summary,
+        };
+    }
+    // tool.delta / thinking.* / text.delta intentionally dropped.
+    return null;
+}
+/**
+ * Production factory. Returns an `EngineBridge` the REPL bootstrap
+ * passes straight to `new ReplSession({ engineBridge })`.
+ *
+ * Per invocation lifecycle:
+ *   1. `openSession(cwd)` mints a fresh session id and ensures the
+ *      `.pugi/events.jsonl` ledger captures audit lines for the
+ *      bridged turn alongside direct `pugi code` invocations.
+ *   2. `NativePugiEngineAdapter` is constructed eagerly with the
+ *      injected (or default) `EngineLoopClient`. The adapter prewarms
+ *      the real-dispatch import on construction; this happens here for
+ *      free.
+ *   3. `attachStreamListener` subscribes to the adapter's
+ *      `streamEmitter`, fans every translatable `EngineStreamEvent`
+ *      to `input.onEvent`, and detaches on bridge exit.
+ *   4. `adapter.run(task, ctx)` drives the engine loop; the terminal
+ *      `result` event maps to the bridge outcome the REPL renders.
+ *   5. The bridge's `signal` is threaded straight through `ctx.signal`
+ *      so a REPL `/stop` aborts the engine loop mid-turn.
+ *
+ * Failure modes (each must be observable, never silent):
+ *   - Adapter constructor throws (e.g. invalid config) -- the bridge
+ *     promise rejects with the underlying error. The REPL's
+ *     `runEngineBridge` catch surfaces the message on a system line.
+ *   - Network error mid-loop -- adapter yields `result.status='failed'`,
+ *     bridge returns `{ outcome: 'failed', detail: result.summary }`.
+ *   - Operator abort -- adapter honours `ctx.signal`, surfaces an
+ *     `AbortError`; we propagate the rejection so the REPL flips the
+ *     synthetic node to `failed` with a clear detail line.
+ */
+export function createEngineBridge(deps) {
+    const buildClient = deps.clientFactory ?? ((config) => new AnvilEngineLoopClient(config));
+    return async (input) => {
+        const root = deps.cwd();
+        const session = openSession(root);
+        const client = buildClient(deps.config);
+        const adapter = new NativePugiEngineAdapter({
+            client,
+            session,
+        });
+        // Per-call name map for matching `tool.end` -> `tool.start`. New
+        // every invocation so concurrent bridges never cross-pollute.
+        const callNames = new Map();
+        // Subscribe BEFORE `adapter.run()` so the first `tool.start` is
+        // captured. Detach in `finally` regardless of outcome so the
+        // listener does not accumulate across REPL turns (long sessions
+        // would otherwise leak one listener per bridged turn).
+        const onStreamEvent = (streamEvent) => {
+            const translated = translateStreamEvent(streamEvent, callNames);
+            if (translated === null)
+                return;
+            try {
+                input.onEvent(translated);
+            }
+            catch {
+                // Fire-and-forget contract -- a broken consumer must never
+                // tear down the engine loop.
+            }
+        };
+        adapter.streamEmitter.on('event', onStreamEvent);
+        const taskKind = commandToTaskKind(input.command);
+        const task = {
+            id: input.bridgeId,
+            kind: taskKind,
+            prompt: input.brief,
+            workspaceRoot: root,
+            allowedPaths: [root],
+            deniedPaths: [],
+            artifacts: [],
+            permissionMode: 'auto',
+        };
+        let terminalSummary = '';
+        let terminalStatus = 'failed';
+        let filesChangedCount = 0;
+        let detail;
+        try {
+            const events = adapter.run(task, {
+                sessionId: session.id,
+                signal: input.signal,
+            });
+            for await (const event of events) {
+                if (event.type === 'status') {
+                    // Already fanned out via streamEmitter above. The toplevel
+                    // `EngineEvent` `status` event predates the rich emitter and
+                    // is kept for backwards-compat with older adapters; we
+                    // intentionally do not double-fire `onEvent` here.
+                    continue;
+                }
+                // event.type === 'result' -- terminal.
+                terminalStatus = event.result.status;
+                terminalSummary = event.result.summary;
+                filesChangedCount = event.result.filesChanged.length;
+                if (event.result.status !== 'done') {
+                    detail = event.result.summary;
+                }
+            }
+        }
+        finally {
+            adapter.streamEmitter.off('event', onStreamEvent);
+        }
+        // Map engine `EngineResult.status` -> bridge `EngineBridgeOutcome`.
+        //
+        // `needs_verification` ( PUGI-VERIFY-GATE) downgrades a
+        // `completed` engine loop with no verification command to a status
+        // distinct from `done`. PUGI-538c-FU-OUTCOME (2026-06-05) split
+        // the bridge's failure surface: `needs_verification` now maps to
+        // the dedicated `unverified` outcome so the REPL agent-tree pane
+        // surfaces a yellow advisory instead of a red false-fail. Real
+        // verification regressions (`verification_command_failed` -> still
+        // `failed` here via the engine's `failed` status) are unchanged.
+        //
+        // Why the split matters: a fresh customer repo with no Makefile /
+        // no `package.json` test script trips `needs_verification` on
+        // every routed brief. Collapsing that to `failed` (the pre-538c
+        // mapping) produced the trust regression the CEO escalation 2026
+        // -06-04 demanded we fix: customer dogfood saw files land on
+        // disk yet read "failed" on the agent-tree, lost trust, walked
+        // away. The verify-gate contract is preserved: real test failures
+        // ALSO reach this branch via engine status `failed` (gated by
+        // `computeVerificationOutcome` when a verification command ran
+        // and exited non-zero) and still map to `failed`. Only the
+        // "no command available" path softens.
+        //
+        // `blocked` carries through (operator chose the abort / budget
+        // exhausted). `done` -> `shipped` -- the only path that produces
+        // a clean shipped status is a verified engine loop.
+        const outcome = terminalStatus === 'done'
+            ? 'shipped'
+            : terminalStatus === 'needs_verification'
+                ? 'unverified'
+                : terminalStatus === 'blocked'
+                    ? 'blocked'
+                    : 'failed';
+        return {
+            outcome,
+            filesChanged: filesChangedCount,
+            // PUGI-538c scope guard: stream emitter has no typed `tokens`
+            // event today; reporting `0` keeps the bridge contract honest
+            // until the emitter gains a tokens variant (separate follow-up).
+            tokensUsed: 0,
+            finalText: terminalSummary.length > 0 ? terminalSummary : undefined,
+            ...(detail !== undefined ? { detail } : {}),
+        };
+    };
+}
+//# sourceMappingURL=engine-bridge.js.map