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

package/dist/core/engine/verification-patterns.js

@@ -0,0 +1,195 @@
+/**
+ * PUGI-VERIFY-GATE — verification command detection.
+ *
+ * Background: Codex dogfood 2026-06-04 surfaced a P0 trust failure
+ * where the Pugi engine returned `status: done` + `exitCode: 0`
+ * even after `npm test` exited non-zero on a regression the agent
+ * itself had introduced. Root cause: no layer of the dispatch
+ * pipeline knew which bash invocations were verification commands,
+ * so the engine outcome had no way to gate the final status on
+ * test/lint/build pass.
+ *
+ * This module is the deterministic, configurable allowlist of regex
+ * patterns the engine uses to recognise verification commands at
+ * dispatch time. The detection is intentionally simple (anchored on
+ * the head of the command after sudo / env-prefix stripping) so the
+ * allowlist stays auditable. False negatives are recoverable (the
+ * agent can re-run with a recognised wrapper); false positives would
+ * silently down-grade unrelated commands and are forbidden.
+ *
+ * The pattern table is exported as `VERIFICATION_PATTERNS`; callers
+ * use `detectVerificationCommand(cmd)` for the boolean + tool-tag
+ * decision. Both surfaces are pure — no I/O, no session state, no
+ * environment reads.
+ */
+/**
+ * Canonical verification allowlist. Patterns target the head of each
+ * shell-separated component AFTER:
+ *   - leading whitespace is trimmed
+ *   - leading `sudo` / `time` / `env KEY=value` prefixes are stripped
+ *
+ * Pre-trim the cmd through `extractCommandHead` before matching.
+ *
+ * When extending: keep the regex anchored (`^`) so a path containing
+ * the tool name (`./scripts/npm.sh`) does not false-positive.
+ */
+export const VERIFICATION_PATTERNS = [
+    // ----- JavaScript / TypeScript ecosystem -----
+    // npm test / npm run test / npm run lint / npm run typecheck / npm run build
+    { tool: 'npm-test', pattern: /^npm\s+(?:run\s+)?test\b/, category: 'test' },
+    { tool: 'npm-lint', pattern: /^npm\s+run\s+lint\b/, category: 'lint' },
+    { tool: 'npm-typecheck', pattern: /^npm\s+run\s+typecheck\b/, category: 'typecheck' },
+    { tool: 'npm-build', pattern: /^npm\s+run\s+build\b/, category: 'build' },
+    // pnpm (with and without -C / --filter prefixes — match the full head)
+    { tool: 'pnpm-test', pattern: /^pnpm(?:\s+(?:-C\s+\S+|--filter(?:\s+|=)\S+|-r))*\s+(?:run\s+)?test\b/, category: 'test' },
+    { tool: 'pnpm-lint', pattern: /^pnpm(?:\s+(?:-C\s+\S+|--filter(?:\s+|=)\S+|-r))*\s+(?:run\s+)?lint\b/, category: 'lint' },
+    { tool: 'pnpm-typecheck', pattern: /^pnpm(?:\s+(?:-C\s+\S+|--filter(?:\s+|=)\S+|-r))*\s+(?:run\s+)?typecheck\b/, category: 'typecheck' },
+    { tool: 'pnpm-build', pattern: /^pnpm(?:\s+(?:-C\s+\S+|--filter(?:\s+|=)\S+|-r))*\s+(?:run\s+)?build\b/, category: 'build' },
+    // yarn
+    { tool: 'yarn-test', pattern: /^yarn\s+(?:run\s+)?test\b/, category: 'test' },
+    { tool: 'yarn-lint', pattern: /^yarn\s+(?:run\s+)?lint\b/, category: 'lint' },
+    { tool: 'yarn-typecheck', pattern: /^yarn\s+(?:run\s+)?typecheck\b/, category: 'typecheck' },
+    { tool: 'yarn-build', pattern: /^yarn\s+(?:run\s+)?build\b/, category: 'build' },
+    // Direct test-runner invocations (npx and bare).
+    { tool: 'jest', pattern: /^(?:npx\s+)?jest\b/, category: 'test' },
+    { tool: 'vitest', pattern: /^(?:npx\s+)?vitest\b/, category: 'test' },
+    { tool: 'mocha', pattern: /^(?:npx\s+)?mocha\b/, category: 'test' },
+    { tool: 'tsc-typecheck', pattern: /^(?:npx\s+)?tsc\b(?=.*--noEmit|\s*$)/, category: 'typecheck' },
+    { tool: 'eslint', pattern: /^(?:npx\s+)?eslint\b/, category: 'lint' },
+    { tool: 'node-test', pattern: /^node\s+--test\b/, category: 'test' },
+    // ----- Python -----
+    { tool: 'pytest', pattern: /^(?:python\s+-m\s+)?pytest\b/, category: 'test' },
+    { tool: 'python-unittest', pattern: /^python\s+-m\s+unittest\b/, category: 'test' },
+    { tool: 'ruff', pattern: /^ruff\s+check\b/, category: 'lint' },
+    { tool: 'mypy', pattern: /^mypy\b/, category: 'typecheck' },
+    // ----- Rust -----
+    { tool: 'cargo-test', pattern: /^cargo\s+test\b/, category: 'test' },
+    { tool: 'cargo-check', pattern: /^cargo\s+check\b/, category: 'typecheck' },
+    { tool: 'cargo-clippy', pattern: /^cargo\s+clippy\b/, category: 'lint' },
+    { tool: 'cargo-build', pattern: /^cargo\s+build\b/, category: 'build' },
+    // ----- Go -----
+    { tool: 'go-test', pattern: /^go\s+test\b/, category: 'test' },
+    { tool: 'go-vet', pattern: /^go\s+vet\b/, category: 'lint' },
+    { tool: 'go-build', pattern: /^go\s+build\b/, category: 'build' },
+    // ----- Elixir -----
+    { tool: 'mix-test', pattern: /^mix\s+test\b/, category: 'test' },
+    // ----- Ruby -----
+    { tool: 'rspec', pattern: /^(?:bundle\s+exec\s+)?rspec\b/, category: 'test' },
+    { tool: 'rubocop', pattern: /^(?:bundle\s+exec\s+)?rubocop\b/, category: 'lint' },
+    // ----- Java / Kotlin / Gradle / Maven -----
+    { tool: 'gradle-test', pattern: /^(?:\.\/)?gradlew?\s+test\b/, category: 'test' },
+    { tool: 'gradle-build', pattern: /^(?:\.\/)?gradlew?\s+build\b/, category: 'build' },
+    { tool: 'maven-test', pattern: /^mvn\s+test\b/, category: 'test' },
+    { tool: 'maven-verify', pattern: /^mvn\s+verify\b/, category: 'test' },
+    // ----- C/C++ / Make -----
+    { tool: 'make-test', pattern: /^make\s+(?:test|check)\b/, category: 'test' },
+    { tool: 'ctest', pattern: /^ctest\b/, category: 'test' },
+];
+const SHELL_SEPARATORS = /\s*(?:&&|\|\||;|\|)\s*/;
+const ENV_ASSIGN = /^[A-Z_][A-Z0-9_]*=\S+$/;
+/**
+ * Strip leading `sudo` / `time` / `env A=1 B=2` noise so the verb is
+ * the first non-prefix token. Returns the stripped head as a single
+ * normalised string. Pure — no side effects.
+ *
+ * We do NOT strip generic env-variable assignments like `CI=1` that
+ * the operator typed inline (e.g. `CI=1 pnpm test`) because the
+ * regex allowlist anchors `pnpm` — matching the head after stripping
+ * `CI=1` is precisely the intent.
+ */
+export function extractCommandHead(component) {
+    let head = component.trim();
+    // sudo / time wrappers
+    while (true) {
+        if (head.startsWith('sudo ')) {
+            head = head.slice(5).trimStart();
+            continue;
+        }
+        if (head.startsWith('time ')) {
+            head = head.slice(5).trimStart();
+            continue;
+        }
+        // env A=1 B=2 prefix (inline env assignments before the verb).
+        // Peel one token at a time so `FOO=bar BAZ=qux pnpm test` resolves to `pnpm test`.
+        const firstToken = head.split(/\s+/, 1)[0] ?? '';
+        if (firstToken !== '' && ENV_ASSIGN.test(firstToken)) {
+            head = head.slice(firstToken.length).trimStart();
+            continue;
+        }
+        break;
+    }
+    return head;
+}
+/**
+ * Detect whether a shell command runs a verification step. The
+ * predicate scans every `&&` / `;` / `||` / `|`-separated component
+ * and returns the first match — a compound command like
+ * `cd packages/foo && pnpm test` is correctly flagged on the
+ * trailing component.
+ *
+ * The check is intentionally optimistic: it does not parse `if`,
+ * `for`, or function bodies. Operators wrapping verification inside
+ * a script (e.g. `./scripts/test.sh`) opt out of the gate; that is
+ * recorded in the unverifiedReason as `no_verification_command_run`
+ * downstream.
+ */
+export function detectVerificationCommand(cmd) {
+    if (typeof cmd !== 'string' || cmd.trim() === '') {
+        return { isVerification: false, tool: null, matchedComponent: '' };
+    }
+    const components = cmd.split(SHELL_SEPARATORS);
+    for (const raw of components) {
+        const head = extractCommandHead(raw);
+        if (head === '')
+            continue;
+        for (const entry of VERIFICATION_PATTERNS) {
+            if (entry.pattern.test(head)) {
+                return {
+                    isVerification: true,
+                    tool: entry.tool,
+                    matchedComponent: raw.trim(),
+                };
+            }
+        }
+    }
+    return { isVerification: false, tool: null, matchedComponent: '' };
+}
+/**
+ * Phrases the agent uses to dispute ownership of a verification
+ * failure. When ANY of these phrases appears in the final assistant
+ * text AND the agent mutated files in the same module as a failing
+ * test, the outcome's `regressionOwnershipDispute` flag is set so a
+ * downstream reviewer can decide whether to escalate.
+ *
+ * The list is case-insensitive at match time. Punctuation around the
+ * phrase is allowed because `.includes()` looks for the substring,
+ * not word boundaries (an agent that writes "this is a pre-existing
+ * test bug" still trips the flag).
+ */
+export const REGRESSION_DISPUTE_PHRASES = [
+    'pre-existing',
+    'preexisting',
+    'pre existing',
+    'not from my changes',
+    'not related to my changes',
+    'unrelated test failure',
+    'unrelated to my changes',
+    'unrelated failure',
+    'not my change',
+];
+/**
+ * Tail trimmer for stderr captured in verification ledger entries.
+ * Returns the last `maxBytes` of UTF-8 text, clamped at a hard 2 KB
+ * default to match the PUGI-VERIFY-GATE contract.
+ */
+export function tailStderr(stderr, maxBytes = 2048) {
+    if (typeof stderr !== 'string' || stderr.length === 0)
+        return '';
+    if (Buffer.byteLength(stderr, 'utf8') <= maxBytes)
+        return stderr;
+    // Approximate cap by character index — accurate enough for stderr
+    // tails that are overwhelmingly ASCII test output.
+    const slice = stderr.slice(-maxBytes);
+    return slice;
+}
+//# sourceMappingURL=verification-patterns.js.map

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