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

package/dist/core/settings.js

@@ -203,6 +203,28 @@ const pugiSettingsSchema = z.object({
         cleanupPeriodDays: z.number().int().min(0).max(365).optional(),
     })
         .optional(),
+    // Trust Sprint item 6 — bash sandbox adapter selection.
+    //
+    //   `none`             — passthrough (existing behaviour, default).
+    //   `macOS-seatbelt`   — wraps spawn calls in `/usr/bin/sandbox-exec`
+    //                        with a profile that allows reads anywhere,
+    //                        denies writes outside workspace + ~/.pugi,
+    //                        and permits standard network egress so
+    //                        `npm install` / `git fetch` still work.
+    //   `docker`           — Linux fallback (NOT shipped in this PR;
+    //                        accepted in the schema so settings.json
+    //                        does not error when operators forward-look
+    //                        at the keyword. Adapter throws at boot if
+    //                        selected today).
+    //
+    // The bash classifier denylist + permission FSM remain in force on
+    // top of the sandbox. This is defence-in-depth: the sandbox bounds
+    // what a tool CAN do; the classifier bounds what a tool TRIES.
+    bash: z
+        .object({
+        sandbox: z.enum(['none', 'macOS-seatbelt', 'docker']).optional(),
+    })
+        .optional(),
 });
 /**
  * #20 — the upstream tool drop-in compat ingest.

package/dist/runtime/cli.js

@@ -6,8 +6,10 @@ import { homedir } from 'node:os';
 import { dirname, relative, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { linkArtifact } from '../core/format/osc8-link.js';
+import { ensurePugiGitIgnore } from '../core/pugi-gitignore.js';
 import { AnvilEngineLoopClient } from '../core/engine/anvil-client.js';
 import { NativePugiEngineAdapter } from '../core/engine/native-pugi.js';
+import { attachStreamRenderer } from './stream-renderer.js';
 import { profileFor, resolveIntensity, resolveMaxTurns, } from '../core/engine/intensity.js';
 import { loadMcpRegistry } from '../core/mcp/registry.js';
 import { loadHookRegistryOrExit } from './load-hooks-or-exit.js';
@@ -29,6 +31,7 @@ import { clearApiKey, DEFAULT_API_URL, listStoredCredentials, maskApiKey, normal
 import { resolveAndValidateEnvLogin, } from '../core/auth/env-provider.js';
 import { runDeployCommand } from '../commands/deploy.js';
 import { runJobsCommand } from '../commands/jobs.js';
+import { runRetroCommand } from '../commands/retro.js';
 import { runConfigCommand } from './commands/config.js';
 import { runStyleCommand } from './commands/style.js';
 import { runThemeCommand } from './commands/theme.js';
@@ -176,6 +179,10 @@ const handlers = {
     // most-recent failed session as a redacted bundle so operators can
     // file clean bug reports without manual log-grepping.
     report: dispatchReport,
+    // PUGI-RETRO-CMD : `pugi retro` mines git history into a
+    // weekly engineering retrospective. M1 git+markdown, M2 Plane bridge,
+    // M3 health card + optional `--post-plane` upload.
+    retro: dispatchRetro,
     review,
     resume,
     roster: dispatchRoster,
@@ -2064,6 +2071,19 @@ function parseArgs(argv) {
         else if (arg === '--no-tools') {
             flags.noTools = true;
         }
+        else if (arg === '--stream') {
+            // Trust Sprint item 5 — force the stderr streaming renderer ON
+            // regardless of TTY detection. Useful for non-interactive
+            // shells that still want progress lines (recorded sessions,
+            // tmux pipes, log-tail consumers).
+            flags.stream = true;
+        }
+        else if (arg === '--no-stream') {
+            // Trust Sprint item 5 — opt out of the streaming renderer even
+            // on a TTY. CI scripts that grep stderr for known patterns
+            // pass this to keep the stream clean.
+            flags.stream = false;
+        }
         else if (arg === '--max-turns') {
             const next = argv[index + 1];
             if (!next || next.startsWith('--'))
@@ -2650,6 +2670,25 @@ const COMMAND_HELP_BODIES = {
         '',
         'Optional: --target-env production|preview, --ref <ref>, --integration <id>.',
     ],
+    retro: [
+        'pugi retro — engineering retrospective from git history.',
+        '',
+        ' pugi retro                 Default 7d window, midnight-aligned in local TZ.',
+        ' pugi retro 24h | 14d | 30d Custom window size.',
+        ' pugi retro compare [<win>] Current window vs the prior same-length window.',
+        ' --plane                    Enrich with closed + created Plane issues, cycle, modules.',
+        ' --post-plane               After rendering, post the retro as a Plane issue',
+        '                            (idempotent on date + sequence). Implies --plane.',
+        ' --json                     Emit JSON envelope to stdout.',
+        '',
+        'Outputs: `.pugi/retros/<date>-<seq>.md` plus a JSON snapshot mirror.',
+        'Metrics: commits, LOC, test ratio, sessions, hourly histogram, top 10',
+        'hotspots, focus score, ship of the week, personal + team streak.',
+        '',
+        'Plane env: PLANE_BASE_URL (default https://plane.pugi.io), PLANE_API_KEY,',
+        'PLANE_WORKSPACE_SLUG (default pugi-customers), PLANE_PROJECT_ID. The same',
+        'fields also load from `.pugi/settings.json::plane.{baseUrl,apiKey,...}`.',
+    ],
 };
 async function help(args, flags, _session) {
     // task: per-command help bodies. When dispatcher
@@ -2733,6 +2772,11 @@ async function help(args, flags, _session) {
         '                         PUGI_SKIP_SPLASH=1.',
         ' --no-tool-stream       Hide the live tool stream pane .',
         '                         Pairs with PUGI_HIDE_TOOL_STREAM=1.',
+        ' --stream               Force stderr progress lines (tool calls,',
+        '                         thinking pulses) ON regardless of TTY.',
+        '                         Trust Sprint item 5.',
+        ' --no-stream            Force stderr progress lines OFF even on a',
+        '                         TTY. --json implicitly disables stream.',
         ' --no-defaults          Skip bundled default-skills install on',
         '                         `pugi init`. Pairs with PUGI_INIT_NO_DEFAULTS=1.',
         ' --no-scan              Skip codebase scan + PUGI.md auto-gen on',
@@ -4982,7 +5026,43 @@ const ENGINE_EXIT_CODES = {
     failed: 8,
     blocked: 9,
     engine_unavailable: 1,
+    // PUGI-VERIFY-GATE: needs_verification is the engine telling the
+    // operator "you did not run a verification command — I cannot
+    // confirm correctness". CI scripts treating any non-zero as
+    // failure keep working; exit 2 historically means "misuse" (the
+    // engine completed but the operator missed a required step),
+    // which matches the semantic here.
+    needs_verification: 2,
 };
+/**
+ * PUGI-VERIFY-GATE — Codex dogfood 2026-06-04 surfaced a P0 where
+ * `pugi code` returned exit 0 while npm test failed. The spec
+ * locks the contract to exit 1 on a verification failure AND exit
+ * 2 on `needs_verification`. Legacy callers reading exit 8/9 still
+ * see "any non-zero = failure" but the new codes (1/2) are the
+ * authoritative signal for the verification gate.
+ *
+ * The override fires when `result.status` carries the new
+ * `needs_verification` literal OR when `result.unverifiedReason`
+ * is set to `verification_command_failed` — the latter pins exit
+ * 1 even if a future producer left `status: 'failed'` while
+ * inferring the cause from the reason field.
+ */
+function resolveEngineExitCode(result) {
+    if (result.status === 'needs_verification') {
+        return ENGINE_EXIT_CODES.needs_verification;
+    }
+    if (result.unverifiedReason === 'verification_command_failed') {
+        // Spec: verified=false because a verification command failed
+        // maps to CLI exit 1 (clear "this is broken" signal).
+        return 1;
+    }
+    if (result.status === 'done')
+        return ENGINE_EXIT_CODES.done;
+    if (result.status === 'failed')
+        return ENGINE_EXIT_CODES.failed;
+    return ENGINE_EXIT_CODES.blocked;
+}
 function commandLabel(kind) {
     return kind === 'build_task' ? 'build' : kind;
 }
@@ -5464,6 +5544,16 @@ function runEngineTask(kind) {
             }
         };
         process.on('SIGINT', onSigint);
+        // Trust Sprint item 5 — attach the stderr streaming renderer so
+        // the operator sees tool calls + thinking pulses as they happen
+        // rather than staring at an empty terminal until the dispatch
+        // completes. TTY default ON; `--stream`/`--no-stream` override;
+        // `--json` implicitly disables (machine consumers want stdout
+        // pristine and stderr quiet).
+        const streamerHandle = attachStreamRenderer(adapter.streamEmitter, {
+            isTty: Boolean(process.stderr.isTTY),
+            explicit: flags.json ? false : (flags.stream ?? null),
+        });
         // β4 r2 P1 #3 — try/finally so loaded MCP child processes are
         // reaped regardless of run outcome (success, blocked, failed,
         // thrown). Triple-review P1 : the try now wraps BOTH the
@@ -5521,6 +5611,23 @@ function runEngineTask(kind) {
                         filesChanged: event.result.filesChanged,
                         eventRefs: event.result.eventRefs,
                         risks: event.result.risks,
+                        // PUGI-VERIFY-GATE: pass verification state through. All
+                        // fields optional on the SDK schema; forward only what
+                        // the adapter populated so MCP/JSON consumers see the
+                        // gate.
+                        ...(event.result.verified !== undefined ? { verified: event.result.verified } : {}),
+                        ...(event.result.verificationCommands !== undefined
+                            ? { verificationCommands: event.result.verificationCommands }
+                            : {}),
+                        ...(event.result.verificationFailures !== undefined
+                            ? { verificationFailures: event.result.verificationFailures }
+                            : {}),
+                        ...(event.result.unverifiedReason !== undefined
+                            ? { unverifiedReason: event.result.unverifiedReason }
+                            : {}),
+                        ...(event.result.regressionOwnershipDispute !== undefined
+                            ? { regressionOwnershipDispute: event.result.regressionOwnershipDispute }
+                            : {}),
                     };
                 }
             }
@@ -5627,7 +5734,14 @@ function runEngineTask(kind) {
             // Pull the headline metrics out of `eventRefs` so the summary and
             // JSON envelope match without re-parsing strings in two places.
             const metrics = parseEventRefs(result.eventRefs);
-            const finalStatus = result.status === 'failed' ? 'error' : 'success';
+            // PUGI-VERIFY-GATE: `needs_verification` is a soft failure —
+            // the loop completed but lacks proof of correctness. Record it
+            // as `error` so the session log marker matches the non-zero
+            // exit code; a future audit query can distinguish the two via
+            // the structured outcome.
+            const finalStatus = result.status === 'failed' || result.status === 'needs_verification'
+                ? 'error'
+                : 'success';
             recordToolResult(session, toolCallId, finalStatus, result.summary);
             // Exit code policy (spec §1-§5):
             //  code/fix/build → 0 done, 8 failed, 9 blocked
@@ -5649,6 +5763,14 @@ function runEngineTask(kind) {
                     metrics.outcome === 'budget_exhausted') {
                     process.exitCode = ENGINE_EXIT_CODES.blocked;
                 }
+                else if (result.status === 'needs_verification') {
+                    // PUGI-VERIFY-GATE: plan rarely runs verification commands
+                    // (plan is read-only), but the new status reaches here when
+                    // a plan run completed without verification AND the gate
+                    // promoted `done` to `needs_verification`. Surface exit 2
+                    // so CI sees the missing signal.
+                    process.exitCode = ENGINE_EXIT_CODES.needs_verification;
+                }
                 else {
                     // `done`, or `blocked` with outcome=tool_refused (= the plan-mode
                     // gate fired, which is the contract working as designed), or
@@ -5658,7 +5780,12 @@ function runEngineTask(kind) {
                 }
             }
             else {
-                process.exitCode = ENGINE_EXIT_CODES[result.status];
+                // PUGI-VERIFY-GATE: route through `resolveEngineExitCode` so
+                // `needs_verification` maps to exit 2 and a verification
+                // command failure maps to exit 1 (per spec). Legacy `failed`
+                // / `blocked` still produce 8 / 9 to preserve scripts that
+                // already branch on them.
+                process.exitCode = resolveEngineExitCode(result);
             }
             const payload = {
                 command: label,
@@ -5673,6 +5800,15 @@ function runEngineTask(kind) {
                 sessionEventsMirror: metrics.mirror,
                 risks: result.risks,
                 plan: planArtifact ? { path: planArtifact.relPath } : undefined,
+                // PUGI-VERIFY-GATE: thread verification state into the JSON
+                // envelope so MCP wrappers, CI scripts, and the cabinet UI
+                // can branch on `verified` / `unverifiedReason` without
+                // grepping the summary string.
+                verified: result.verified,
+                verificationCommands: result.verificationCommands,
+                verificationFailures: result.verificationFailures,
+                unverifiedReason: result.unverifiedReason,
+                regressionOwnershipDispute: result.regressionOwnershipDispute,
                 // — per-edit dispatcher trace. Empty array when no inline
                 // markers were detected in the model's final response.
                 diffEdits: dispatchResults.map((dr) => ({
@@ -5751,6 +5887,11 @@ function runEngineTask(kind) {
             writeOutput(flags, payload, textLines.join('\n'));
         }
         finally {
+            // Trust Sprint item 5 — detach the streaming renderer first so
+            // it never paints during the MCP shutdown / LSP teardown phase
+            // below. The handle is a no-op when streaming was disabled, so
+            // this is unconditional and safe.
+            streamerHandle.detach();
             // CEO P1 #25 — detach the per-run SIGINT handler so a second
             // engine run from the same process (tests, scripts iterating
             // `runEngineTask`, future REPL non-watch dispatches) starts
@@ -7275,39 +7416,32 @@ function notImplemented(command) {
         writeOutput(flags, payload, payload.message);
     };
 }
-function ensurePugiGitIgnore(cwd, created, skipped) {
-    const gitignorePath = resolve(cwd, '.gitignore');
-    // PUGI-487 - also ensure `.claude/worktrees/` is git-ignored so the
-    // user-facing `pugi --worktree` flag does not surface its created
-    // trees as untracked status noise.
-    const markers = ['.pugi/', '.claude/worktrees/'];
-    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 equivalents = {
-        '.pugi/': ['.pugi/', '/.pugi/', '.pugi'],
-        '.claude/worktrees/': ['.claude/worktrees/', '/.claude/worktrees/', '.claude/worktrees'],
-    };
-    const toAppend = [];
-    for (const marker of markers) {
-        const eq = equivalents[marker] ?? [marker];
-        const present = eq.some((variant) => lines.includes(variant));
-        if (!present)
-            toAppend.push(marker);
-    }
-    if (toAppend.length === 0) {
-        skipped.push(gitignorePath);
-        return;
+/**
+ * `pugi retro` — engineering retrospective. PUGI-RETRO-CMD.
+ *
+ * Thin shim onto `runRetroCommand`. Forwards the global `--json` flag
+ * so JSON envelope mode survives the dispatcher even though
+ * `parseArgs` strips it before the per-command args reach the runner.
+ * Same pattern as `dispatchDeploy` above.
+ */
+async function dispatchRetro(args, flags, _session) {
+    const exitCode = await runRetroCommand({
+        args,
+        flags: { json: flags.json },
+        cwd: process.cwd(),
+        io: {
+            write: (text) => process.stdout.write(text),
+            writeError: (text) => process.stderr.write(text.endsWith('\n') ? text : `${text}\n`),
+        },
+    });
+    if (exitCode !== 0) {
+        process.exitCode = exitCode;
     }
-    const trailing = current.endsWith('\n') ? '' : '\n';
-    const next = `${current}${trailing}${toAppend.join('\n')}\n`;
-    writeFileSync(gitignorePath, next, { encoding: 'utf8' });
-    created.push(`${gitignorePath} (+${toAppend.join(', ')})`);
 }
+// ensurePugiGitIgnore extracted к `apps/pugi-cli/src/core/pugi-gitignore.ts`
+// ( triple-review P1 dedup). Re-exported here so existing call
+// sites at cli.ts:3732 keep their import path unchanged.
+export { ensurePugiGitIgnore } from '../core/pugi-gitignore.js';
 /**
  * Compute the workspace label surfaced in the REPL header bar
  * (Sprint ). We prefer the basename of the workspace root because

package/dist/runtime/commands/mcp.js

@@ -11,6 +11,7 @@ import { listMcpTrust, setMcpTrust } from '../../core/mcp/trust.js';
 import { createPugiMcpServer, serveStdio } from '../../core/mcp/server.js';
 import { buildPugiMcpTools } from '../../core/mcp/server-tools.js';
 import { buildOrchestratorTools } from '../../core/mcp/orchestrator-tools.js';
+import { resolveOrchestratorConfig, describeOrchestratorConfig, } from '../../core/mcp/orchestrator-config.js';
 import { serveHttp } from '../../core/mcp/http-server.js';
 import { resolveActiveCredential, DEFAULT_API_URL } from '../../core/credentials.js';
 import { listMcpPermissions, clearMcpPermission, } from '../../core/mcp/permission.js';
@@ -80,7 +81,12 @@ const USAGE_LINES = [
     '                               pugi.dispatch / pugi.publish / pugi.deploy instead of',
     '                               the engine surface. Designed for external the upstream tool',
     '                               / Cursor sessions driving fix-publish-test loops.',
-    '                               Each tool family is gated by an env switch:',
+    '   --orchestrator-bundle      Single-flag form (Trust Sprint item 7). Equivalent to',
+    '                               --orchestrator --allow-bash with PUGI_MCP_EXEC_ENABLED=1',
+    '                               and auto-resolves the pugi binary from PATH (or the',
+    '                               local dev binary when invoked from the monorepo).',
+    '                               Also enabled by setting PUGI_MCP_ORCHESTRATOR=1.',
+    '                               Legacy gates still work as deprecated aliases:',
     '                                 PUGI_MCP_EXEC_ENABLED=1    enables pugi.run',
     '                                 PUGI_MCP_PUBLISH_ENABLED=1 enables pugi.publish',
     '                                 PUGI_MCP_DEPLOY_ENABLED=1  enables pugi.deploy',
@@ -545,15 +551,31 @@ async function runMcpServe(args, ctx) {
     // `buildPugiMcpTools` call (advertising `bash` without the gate flag)
     // would still be refused at dispatch.
     const readOnly = flags.readOnly === true;
+    // Trust Sprint item 7 — resolve orchestrator config FIRST so it can
+    // contribute to bash gating downstream. The resolver collapses the
+    // legacy multi-knob mode (PUGI_MCP_EXEC_ENABLED + --allow-bash +
+    // PUGI_MCP_PUGI_BIN) into one toggle (PUGI_MCP_ORCHESTRATOR=1 or
+    // --orchestrator-bundle).
+    const orchestratorConfig = flags.orchestrator
+        ? resolveOrchestratorConfig({
+            env: process.env,
+            bundleFlag: flags.orchestratorBundle,
+            bashFlag: flags.bashAllowed,
+            workspaceRoot: ctx.workspaceRoot,
+        })
+        : null;
     const writeAllowed = !readOnly && flags.writeAllowed;
-    const bashAllowed = !readOnly && flags.bashAllowed;
+    // Bundle implies bash. We OR the resolver's decision into the
+    // bash-gating knob so a customer who set PUGI_MCP_ORCHESTRATOR=1 does
+    // not also need to pass --allow-bash (item 7 acceptance criterion).
+    const bashAllowed = !readOnly && (flags.bashAllowed || (orchestratorConfig?.bashAllowed ?? false));
     // P1 — when `--orchestrator` is set the surface swaps to the
     // CLI-orchestrator family (pugi.run / pugi.read / pugi.write /
     // pugi.dispatch / pugi.publish / pugi.deploy). The engine surface is
     // intentionally dropped — the two are mutually exclusive on the wire
     // to keep tool-name resolution unambiguous on the consumer side.
     const tools = flags.orchestrator
-        ? buildOrchestratorTools(buildOrchestratorContext(ctx.workspaceRoot))
+        ? buildOrchestratorTools(buildOrchestratorContext(ctx.workspaceRoot, orchestratorConfig))
         : buildPugiMcpTools(toolCtx, {
             bashAllowed,
             // Keep the legacy contract: `readOnly` for the tool-builder means
@@ -669,6 +691,15 @@ async function runMcpServe(args, ctx) {
     // request that returns a response. Operator sees one info line on
     // stderr so they know the server is up.
     process.stderr.write(`pugi-mcp (stdio, ${flags.orchestrator ? 'orchestrator' : 'engine'}): ${tools.length} tool(s) — ${tools.map((t) => t.name).join(', ')}\n`);
+    // Trust Sprint item 7 — when the orchestrator surface is live, surface
+    // the resolved capability table on stderr so the operator can confirm
+    // which gates ended up armed without running `pugi doctor` in another
+    // pane. Each line is prefixed for grep-ability.
+    if (orchestratorConfig) {
+        for (const line of describeOrchestratorConfig(orchestratorConfig)) {
+            process.stderr.write(`pugi-mcp orchestrator: ${line}\n`);
+        }
+    }
     await serveStdio({
         server,
         stdin: ctx.stdin ?? process.stdin,
@@ -685,6 +716,7 @@ function parseServeFlags(args) {
         writeAllowed: false,
         bashAllowed: false,
         orchestrator: false,
+        orchestratorBundle: false,
     };
     for (let i = 0; i < args.length; i += 1) {
         const arg = args[i] ?? '';
@@ -745,6 +777,14 @@ function parseServeFlags(args) {
         else if (arg === '--orchestrator') {
             flags.orchestrator = true;
         }
+        else if (arg === '--orchestrator-bundle') {
+            // Trust Sprint item 7 — single-flag form. Implies orchestrator
+            // surface + bash + exec. Mutual upgrade with --orchestrator: if
+            // both are passed the bundle wins (it is a strict superset).
+            flags.orchestrator = true;
+            flags.orchestratorBundle = true;
+            flags.bashAllowed = true;
+        }
         else if (arg === '--help') {
             // Caller renders USAGE_LINES. We surface the same via top-level
             // dispatch — nothing to do here, just don't error.
@@ -796,19 +836,35 @@ function buildServePermissionGate(opts) {
  *
  * P1 .
  */
-function buildOrchestratorContext(workspaceRoot) {
+function buildOrchestratorContext(workspaceRoot, resolved = null) {
     const envRoot = process.env.PUGI_MCP_WORKSPACE_ROOT;
     const root = envRoot && envRoot.length > 0 ? resolve(envRoot) : workspaceRoot;
     const credential = resolveActiveCredential();
+    // Trust Sprint item 7 — when `resolved` is provided we honour the
+    // consolidated capability bits. When absent (legacy direct call from
+    // a test) we fall back to the raw env so existing harnesses keep
+    // working untouched.
+    const execEnabled = resolved
+        ? resolved.execEnabled
+        : process.env.PUGI_MCP_EXEC_ENABLED === '1';
+    const publishEnabled = resolved
+        ? resolved.publishEnabled
+        : process.env.PUGI_MCP_PUBLISH_ENABLED === '1';
+    const deployEnabled = resolved
+        ? resolved.deployEnabled
+        : process.env.PUGI_MCP_DEPLOY_ENABLED === '1';
+    const pugiBin = resolved
+        ? resolved.pugiBin
+        : (process.env.PUGI_MCP_PUGI_BIN ?? 'pugi');
     return {
         workspaceRoot: root,
-        pugiBin: process.env.PUGI_MCP_PUGI_BIN ?? 'pugi',
+        pugiBin,
         apiUrl: credential?.apiUrl ?? DEFAULT_API_URL,
         apiKey: credential?.apiKey ?? null,
         capabilities: {
-            exec: process.env.PUGI_MCP_EXEC_ENABLED === '1',
-            publish: process.env.PUGI_MCP_PUBLISH_ENABLED === '1',
-            deploy: process.env.PUGI_MCP_DEPLOY_ENABLED === '1',
+            exec: execEnabled,
+            publish: publishEnabled,
+            deploy: deployEnabled,
         },
         sshAlias: process.env.PUGI_MCP_SSH_ALIAS ?? 'codeforge',
     };

package/dist/runtime/deprecation-warning.js

@@ -0,0 +1,69 @@
+/**
+ * Centralised deprecation warning helper (Trust Sprint item 7).
+ *
+ * Pugi CLI is in 0.x and we are introducing the first generation of
+ * collapsed env vars. Operators with existing scripts need a clear
+ * forward path without breakage. Pattern:
+ *
+ *   warnDeprecation('PUGI_OLD_FLAG', 'PUGI_NEW_FLAG=1', 'rationale...');
+ *
+ * Behaviour:
+ *   - Emits ONE stderr line per (old, new) pair per process. Repeat
+ *     calls for the same pair are suppressed so the operator does not
+ *     see the same noise across many tool invocations in a session.
+ *   - Silenced entirely when `PUGI_SUPPRESS_DEPRECATION_WARNINGS=1` is
+ *     set (CI escape hatch; documented in operator-deploy-checklist).
+ *   - Silenced in test runs via the standard `NODE_ENV=test` /
+ *     `PUGI_TEST_MODE=1` checks so spec output stays clean.
+ *
+ * Brand rule: no AI attribution, no em dashes. Copy stays short and
+ * actionable so the operator can paste the new form into their script
+ * in one read.
+ */
+const warnedPairs = new Set();
+/**
+ * Reset the warned-once memo. Tests call this between cases so the
+ * one-warning-per-pair guard does not bleed across specs.
+ */
+export function resetDeprecationWarningsForTest() {
+    warnedPairs.clear();
+}
+/**
+ * Emit a single deprecation warning to stderr.
+ *
+ * @param oldName  literal name of the deprecated env/flag the operator
+ *                 is using (e.g. 'PUGI_MCP_EXEC_ENABLED').
+ * @param newName  literal name of the replacement env/flag, including
+ *                 the form an operator should type (e.g.
+ *                 'PUGI_MCP_ORCHESTRATOR=1').
+ * @param hint     optional one-line rationale appended after the
+ *                 redirect. Keep under 80 chars; multi-line wrapping
+ *                 is the operator's terminal job, not ours.
+ */
+export function warnDeprecation(oldName, newName, hint) {
+    if (isSilenced())
+        return;
+    const key = `${oldName}->${newName}`;
+    if (warnedPairs.has(key))
+        return;
+    warnedPairs.add(key);
+    const baseLine = `pugi: deprecation: ${oldName} is deprecated; prefer ${newName}.`;
+    const line = hint && hint.length > 0 ? `${baseLine} ${hint}` : baseLine;
+    process.stderr.write(`${line}\n`);
+}
+/**
+ * Internal helper. Lifted so tests can mock or override.
+ */
+function isSilenced() {
+    const env = process.env;
+    if (env.PUGI_SUPPRESS_DEPRECATION_WARNINGS === '1')
+        return true;
+    if (env.PUGI_TEST_MODE === '1')
+        return true;
+    // NODE_ENV=test is set by `node --test`'s harness and by the
+    // pugi-cli vitest workflows.
+    if (env.NODE_ENV === 'test')
+        return true;
+    return false;
+}
+//# sourceMappingURL=deprecation-warning.js.map

package/dist/runtime/headless.js

@@ -403,6 +403,10 @@ export async function runHeadlessPrint(opts) {
     //   every richer event already flew through `streamEmitter` above.
     const kind = opts.kind ?? 'code';
     const taskId = `print-${Date.now()}`;
+    // PUGI-VERIFY-GATE: `needs_verification` is the new fourth
+    // status the engine adapter surfaces when a `completed` loop ran
+    // no verification command. Widen the local var to match the
+    // engine result schema.
     let finalStatus = 'failed';
     let finalSummary = '';
     let resultRisks = [];
@@ -475,14 +479,15 @@ export async function runHeadlessPrint(opts) {
         },
     });
     // 9. Emit session.end. Exit code policy per spec:
-    //   - done      → 0
+    //   - done                → 0
+    //   - needs_verification  → 2 (PUGI-VERIFY-GATE)
     //   - blocked + outcome=budget_exhausted → 2
     //   - blocked + any other reason → 2 (turn limit, tool refused — both
     //                                      count as "did not complete")
-    //   - failed    → 1
+    //   - failed              → 1
     const exitCode = finalStatus === 'done'
         ? 0
-        : finalStatus === 'blocked'
+        : finalStatus === 'blocked' || finalStatus === 'needs_verification'
             ? 2
             : 1;
     const durationMs = Date.now() - startedAt;