@pugi/cli 0.1.0-beta.95 → 0.1.0-beta.97

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

@@ -19,6 +19,12 @@ import { dispatchEnterWorktree, enterWorktreeJsonSchema, } from '../../tools/ent
 import { dispatchExitWorktree, exitWorktreeJsonSchema, } from '../../tools/exit-worktree.js';
 import { webFetchTool } from '../../tools/web-fetch.js';
 import { webSearchTool } from '../../tools/web-search.js';
+// Phase 1 runtime evidence pack (PUGI-291..295): server_* + http_request
+// dispatchers + JSON schema fragments. Every primitive returns a
+// sentinel string on validation failure (sleep/brief convention) so
+// the engine adapter surfaces it as a recoverable tool result.
+import { dispatchHttpRequest, httpRequestJsonSchema, } from '../../tools/http-request.js';
+import { dispatchServerHealth, dispatchServerLogs, dispatchServerStart, dispatchServerStop, serverHealthJsonSchema, serverLogsJsonSchema, serverStartJsonSchema, serverStopJsonSchema, } from '../../tools/server-tools.js';
 import { agentTool } from '../../tools/agent-tool.js';
 import { multiEdit } from '../../tools/multi-edit.js';
 import { recordVerificationCall } from '../session.js';
@@ -217,6 +223,15 @@ const WIRED_TOOLS = new Set([
     'symbols_signature',
     'symbols_type_definition',
     'symbols_workspace_symbols',
+    // Phase 1 runtime evidence pack (PUGI-291..295): server_* + http_request.
+    // Off by default in plan mode (mutation surface for start/stop; even
+    // health/logs/http_request cross the plan-mode read-only contract
+    // because they are runtime evidence primitives, not source reads).
+    'http_request',
+    'server_health',
+    'server_logs',
+    'server_start',
+    'server_stop',
 ]);
 export function buildToolsSchema(kind, options = { allowFetch: false, allowSearch: false }) {
     const planMode = kind === 'plan';
@@ -831,6 +846,31 @@ export function buildToolsSchema(kind, options = { allowFetch: false, allowSearc
                     },
                 },
             },
+        }, 
+        // Phase 1 runtime evidence pack (PUGI-291..295) - server lifecycle
+        // primitives + generic HTTP request. Off in plan mode because each
+        // tool produces side effects (a spawned process, an outbound HTTP
+        // call) the plan-mode read-only contract refuses.
+        {
+            name: 'server_start',
+            description: 'Spawn a server via /bin/sh -c <command> in the workspace and poll the health URL until it returns the expected status (default 200) or the timeout elapses. Persists pid + meta to `.pugi/runs/<runId>/server.json` and a stdout/stderr tail to `server.log`. Returns {ok, pid, port, healthStatus, logPath, durationMs, error?}. Use to materialise concrete pid + health 200 evidence rather than asserting a server is up in prose.',
+            parameters: serverStartJsonSchema,
+        }, {
+            name: 'server_stop',
+            description: 'Send SIGTERM to the supplied pid, wait graceMs (default 5000ms), then escalate to SIGKILL. Idempotent - a pid that already exited returns ok=true with signal=undefined. Returns {ok, pid, exitCode?, signal?, durationMs, error?}.',
+            parameters: serverStopJsonSchema,
+        }, {
+            name: 'server_health',
+            description: 'One-shot HTTP GET against the supplied URL with a short timeout (default 5000ms, max 60000ms). Returns {ok, status, durationMs, body?, error?} where ok=true only when the response status equals expectStatus (default 200). Body is capped at 1 KB so the envelope stays compact.',
+            parameters: serverHealthJsonSchema,
+        }, {
+            name: 'server_logs',
+            description: 'Read the trailing N lines of `.pugi/runs/<runId>/server.log`. Defaults to the most recent run when runId is omitted; pid-based lookup walks every run dir. Returns {ok, logPath, lines, totalLines, error?}.',
+            parameters: serverLogsJsonSchema,
+        }, {
+            name: 'http_request',
+            description: 'Issue an HTTP request (GET/POST/PUT/PATCH/DELETE/HEAD/OPTIONS) against a URL. Loopback hosts (localhost / 127.0.0.0/8 / ::1) always pass; non-loopback hosts require allowExternal: true so the default posture stays private. Body objects/arrays are JSON-serialised. Returns {ok, status, headers, body, json?, durationMs, error?, truncated?}.',
+            parameters: httpRequestJsonSchema,
         });
     }
     // β4 M1/M3: append MCP tools last. Plan mode skips them because every
@@ -1235,6 +1275,26 @@ export function buildExecutor(input) {
                     sessionId,
                 });
             }
+            // Phase 1 runtime evidence pack (PUGI-291..295). Each tool returns
+            // a JSON-string envelope or a sentinel string on validation
+            // failure - both paths are recoverable from the model's POV, so
+            // the engine adapter routes them as plain tool results and the
+            // model can self-correct.
+            if (name === 'server_start') {
+                return dispatchServerStart({ workspaceRoot }, args);
+            }
+            if (name === 'server_stop') {
+                return dispatchServerStop({ workspaceRoot }, args);
+            }
+            if (name === 'server_health') {
+                return dispatchServerHealth({ workspaceRoot }, args);
+            }
+            if (name === 'server_logs') {
+                return dispatchServerLogs({ workspaceRoot }, args);
+            }
+            if (name === 'http_request') {
+                return dispatchHttpRequest({}, args);
+            }
             if (name === 'multi_edit') {
                 return dispatchMultiEdit(args, ctx);
             }

package/dist/core/permissions/tool-class.js

@@ -47,11 +47,25 @@ const BUILT_IN_TOOL_CLASSES = Object.freeze({
     skill: 'read',
     task_get: 'read',
     task_list: 'read',
+    // Phase 1 runtime evidence pack (PUGI-291..295): server_health and
+    // server_logs are read-only probes (HTTP GET + tail of a log file
+    // already on disk). Classifying them as `read` keeps the ask-mode
+    // prompts honest; the dispatcher still applies the network-perm gate
+    // for server_health and the workspace-read gate for server_logs.
+    server_health: 'read',
+    server_logs: 'read',
     // Mutating actions.
     write: 'write',
     edit: 'write',
     multi_edit: 'write',
     bash: 'write',
+    // Phase 1 runtime evidence pack: server_start spawns a process,
+    // server_stop terminates one, http_request can POST/PUT/DELETE
+    // arbitrary data against a localhost service. All three are write
+    // class so plan mode refuses and ask mode prompts.
+    server_start: 'write',
+    server_stop: 'write',
+    http_request: 'write',
     task_create: 'write',
     task_update: 'write',
     todo_write: 'write',

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

@@ -1,6 +1,8 @@
 import { AnvilEngineLoopClient } from '../engine/anvil-client.js';
 import { NativePugiEngineAdapter } from '../engine/native-pugi.js';
+import { loadMcpRegistry as defaultLoadMcpRegistry } from '../mcp/registry.js';
 import { openSession } from '../session.js';
+import { loadHookRegistryOrExit as defaultLoadHookRegistry } from '../../runtime/load-hooks-or-exit.js';
 /**
  * Translate `pugi-tool-route command="..."` into the SDK's
  * `EngineTaskKind`. `code` and `fix` pass through verbatim; `build`
@@ -83,13 +85,115 @@ function translateStreamEvent(event, names) {
  */
 export function createEngineBridge(deps) {
     const buildClient = deps.clientFactory ?? ((config) => new AnvilEngineLoopClient(config));
+    const loadMcp = deps.loadMcpRegistry ?? defaultLoadMcpRegistry;
+    const loadHooks = deps.loadHookRegistry ??
+        ((opts) => defaultLoadHookRegistry(opts));
+    // PR A — per-bridge-instance caches. Spawning MCP child processes
+    // (multi-second startup for some servers) and parsing hook configuration
+    // are too expensive to repeat per turn AND have no per-turn state. We
+    // load once on the first call, reuse across turns. The MCP registry
+    // shutdown happens at process exit; a future PR will wire it to the
+    // REPL's exit hook so trusted child processes are reaped before the
+    // parent terminates.
+    //
+    // /triple-review P1 round 2: cache stored as in-flight Promise<T>
+    // instead of value + boolean flag. Two concurrent first-turn calls
+    // would otherwise both observe `mcpLoaded === false`, both spawn the
+    // expensive loader, and the second result would overwrite the first —
+    // leaking the first registry's child processes. Storing the promise
+    // means the second caller awaits the same in-flight load, gets the
+    // same instance, and there is no double-spawn. On loader failure the
+    // promise resolves to `undefined` (mirrors the value-cache fallback);
+    // a future retry on transient ENOENT would mint a NEW promise after
+    // explicit invalidation (out of scope for this PR — tracked as P2 fu).
+    let mcpRegistryPromise = null;
+    let hooksPromise = null;
+    const securityHooksParseFailed = { value: false };
+    async function resolveMcpRegistry(root) {
+        if (mcpRegistryPromise === null) {
+            mcpRegistryPromise = (async () => {
+                try {
+                    return await loadMcp(root);
+                }
+                catch (error) {
+                    // PR A — mirror cli.ts:6394 failure mode. A bad `.pugi/mcp.json`
+                    // must not crash the REPL; the operator sees a stderr warning
+                    // and continues without MCP tools. They can fix the file and
+                    // the next REPL launch picks up the new registry.
+                    const msg = error.message;
+                    process.stderr.write(`pugi REPL engine bridge: MCP registry load failed — ${msg}. ` +
+                        `Continuing without MCP tools. Fix .pugi/mcp.json to enable.\n`);
+                    return undefined;
+                }
+            })();
+        }
+        return mcpRegistryPromise;
+    }
+    async function resolveHooks(root, session) {
+        if (hooksPromise === null) {
+            hooksPromise = (async () => {
+                try {
+                    const outcome = await loadHooks({
+                        workspaceRoot: root,
+                        session,
+                        label: 'repl',
+                    });
+                    if (outcome.kind === 'parse-failure-refused') {
+                        // /triple-review P1 round 2: hooks fail-open is a security
+                        // regression vs cli.ts:6440 (hard-exit on parse failure).
+                        // SECURITY: a workspace operator who configured a `PreToolUse
+                        // onFailure: 'block'` rule that refuses bash containing `rm`
+                        // loses that protection the moment the JSON file gets a
+                        // typo. Stderr-only warning scrolls off the TUI.
+                        //
+                        // Mitigation: do NOT load hooks for this REPL session (so
+                        // the operator's mental model — "I have hooks configured" —
+                        // does not silently break), AND mark the bridge as "hooks
+                        // parse failed" so every turn surfaces the warning until
+                        // the file is fixed. The PUGI_HOOKS_BYPASS=1 env var
+                        // (loadHookRegistryOrExit:97-107) is still the explicit
+                        // escape hatch when the operator is mid-edit and acknowledges
+                        // the risk.
+                        securityHooksParseFailed.value = true;
+                        process.stderr.write('pugi REPL engine bridge: SECURITY — hooks parse failed. ' +
+                            'PreToolUse/PostToolUse rules are NOT active for this REPL ' +
+                            'session. Fix .pugi/hooks.json and restart REPL, OR set ' +
+                            'PUGI_HOOKS_BYPASS=1 to acknowledge and continue.\n');
+                        return undefined;
+                    }
+                    return outcome.hooks;
+                }
+                catch (error) {
+                    const msg = error.message;
+                    process.stderr.write(`pugi REPL engine bridge: hooks loader threw — ${msg}. ` +
+                        `Continuing without hooks.\n`);
+                    return undefined;
+                }
+            })();
+        }
+        return hooksPromise;
+    }
     return async (input) => {
         const root = deps.cwd();
         const session = openSession(root);
         const client = buildClient(deps.config);
+        const [cachedMcpRegistry, cachedHooks] = await Promise.all([
+            resolveMcpRegistry(root),
+            resolveHooks(root, session),
+        ]);
+        if (securityHooksParseFailed.value) {
+            // /triple-review P1 round 2: re-emit the security warning on every
+            // bridged turn so the operator does not miss it after scrollback.
+            // Cheap one-liner, hard to miss in TUI status pane.
+            process.stderr.write('pugi REPL engine bridge: SECURITY reminder — hooks still NOT ' +
+                'loaded for this session (.pugi/hooks.json parse failure).\n');
+        }
         const adapter = new NativePugiEngineAdapter({
             client,
             session,
+            ...(cachedMcpRegistry ? { mcpRegistry: cachedMcpRegistry } : {}),
+            ...(cachedHooks ? { hooks: cachedHooks } : {}),
+            ...(deps.intensityProfile ? { intensityProfile: deps.intensityProfile } : {}),
         });
         // Per-call name map for matching `tool.end` -> `tool.start`. New
         // every invocation so concurrent bridges never cross-pollute.

package/dist/core/repl/session.js

@@ -40,7 +40,8 @@ import { applyRewindMask } from '../checkpoint/rewinder.js';
 import { evaluateAutoCompact } from '../compact/auto-trigger.js';
 import { estimateTokensInMany } from '../compact/token-counter.js';
 import { extractAskTags, extractPlanReviewTags, signatureForAsk, } from './ask.js';
-import { extractToolRouteTags, } from './tool-route.js';
+import { extractToolRouteTags, signatureForToolRoute, } from './tool-route.js';
+import { personaSlugFor } from '../engine/prompts.js';
 import { existsSync, readdirSync, statSync } from 'node:fs';
 import { resolve as resolvePath } from 'node:path';
 import { CancellationToken } from './cancellation.js';
@@ -2788,13 +2789,70 @@ export class ReplSession {
         if (!this.streamHandle && !this.closed) {
             this.openStream();
         }
+        // PR A (PUGI-538-FU) — REPL becomes a first-class engine
+        // path. When the CLI REPL has an engine bridge wired the brief is
+        // dispatched DIRECTLY to the inproc engine adapter via
+        // `runEngineBridge` instead of POSTing к admin-api `/sessions/:id/brief`.
+        //
+        // Why this matters:
+        //  - The server-side bypass () had to fabricate a synthetic
+        //    `<pugi-tool-route>` envelope SSE event so the CLI parser would
+        //    fire `runEngineBridge`. That worked but cost one full HTTP
+        //    round-trip + SSE latency per turn — and required `cliVersion`
+        //    to thread correctly через the session-create + header pipe
+        //    (which broke in production: CEO smoke 2026-06-05 showed
+        //    `envelope=delegate` instead of `tool-route` because the version
+        //    header was missing on his customer-installed beta.95 client,
+        //    so the bypass branch never matched и the coordinator chat
+        //    ceremony ran anyway).
+        //  - Going direct removes that whole class of bug: the CLI knows
+        //    it is the CLI, it has the engine bridge in hand, it skips the
+        //    server entirely и calls the adapter inproc. Matches Claude
+        //    Code / Codex / Aider tools-first loop architecture.
+        //
+        // Personas survive: `personaSlugFor('code')` returns 'dev' (Hiroshi),
+        // the engine adapter renders the persona system prompt + memory
+        // recall just like `pugi code` direct CLI. The synthetic agent-tree
+        // node inside `runEngineBridge` carries `personaName` so the TUI
+        // shows "Hiroshi" the same way it did before.
+        //
+        // Server-side bypass от  remains в place для non-CLI surfaces
+        // (cabinet BFF, telegram bot) — they have no engine adapter wired,
+        // so the server still needs to fabricate the dispatch on their behalf.
+        //
+        // Env opt-out: `PUGI_REPL_DIRECT_ENGINE=0` falls back к the HTTP
+        // path for regression debugging. cliVersion presence is the CLI
+        // signal — REPL embedded inside cabinet BFF mounts without that
+        // field и continues к hit the server route.
+        const useDirectEngine = this.options.engineBridge !== undefined &&
+            typeof this.options.cliVersion === 'string' &&
+            this.options.cliVersion.length > 0 &&
+            (this.options.env ?? process.env).PUGI_REPL_DIRECT_ENGINE !== '0';
         try {
-            await this.options.transport.postBrief({
-                apiUrl: this.options.apiUrl,
-                apiKey: this.options.apiKey,
-                sessionId,
-                brief,
-            });
+            if (useDirectEngine) {
+                const persona = personaSlugFor('code');
+                const tag = {
+                    command: 'code',
+                    brief,
+                    persona,
+                    // Direct-dispatch tags do not flow through the parser, so the
+                    // start/end byte offsets are inapplicable. Keep `signatureForToolRoute`
+                    // so the seen-tag rolling set still de-dupes a brief that the
+                    // operator submits twice in a row by accident.
+                    signature: signatureForToolRoute('code', persona, brief),
+                    start: 0,
+                    end: 0,
+                };
+                await this.runEngineBridge(tag);
+            }
+            else {
+                await this.options.transport.postBrief({
+                    apiUrl: this.options.apiUrl,
+                    apiKey: this.options.apiKey,
+                    sessionId,
+                    brief,
+                });
+            }
         }
         catch (error) {
             this.appendSystemLine(`Brief dispatch refused: ${this.errorMessage(error)}`);

package/dist/runtime/cli.js

@@ -5021,48 +5021,26 @@ function renderLocalSessionList(rows, projectSlug) {
  * 1 is reserved for the credential gate (engine_unavailable) so
  * existing shell wrappers that branch on "any non-zero" still work.
  */
-const ENGINE_EXIT_CODES = {
-    done: 0,
-    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;
-}
+// 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.
+//
+// Phase 1 (PUGI-299) - runtime invariant additions:
+//  3. `verificationFailures` non-empty array → exit 1
+//  4. `verified === false && status === 'done'` → exit 2
+//
+// The two new rules are defensive: today `computeVerificationOutcome`
+// always populates `unverifiedReason` (rule 2) or downgrades the
+// status (rule 1) so the new branches never fire, but the invariant
+// locks the contract for future engine adapters.
+//
+// Implementation lives in `engine-exit-code.ts` so the runtime spec
+// (`test/engine-exit-code.spec.ts`) can exercise it without mounting
+// this 9700-LOC entry module.
+import { ENGINE_EXIT_CODES, resolveEngineExitCode, } from './engine-exit-code.js';
 function commandLabel(kind) {
     return kind === 'build_task' ? 'build' : kind;
 }
@@ -8132,5 +8110,12 @@ export const __test__ = {
     // env-driven $PUGI_HOME redirect) without going через the full
     // engine-task dispatch path.
     readPersistedContextTier,
+    // Phase 1 (PUGI-299) - runtime verification gate exit-code resolver.
+    // Re-exported from `engine-exit-code.ts` so the invariant spec can
+    // assert that a `verificationFailures` non-empty array OR a
+    // `verified=false` outcome MUST surface as a non-zero CLI exit
+    // even when a malformed adapter forgets to flip the status.
+    resolveEngineExitCode,
+    ENGINE_EXIT_CODES,
 };
 //# sourceMappingURL=cli.js.map

package/dist/runtime/engine-exit-code.js

@@ -0,0 +1,50 @@
+/**
+ * engine-exit-code - Phase 1 verification gate invariant (PUGI-299).
+ *
+ * The runtime resolves the CLI exit code from the engine outcome via a
+ * deterministic ladder. Extracted from `cli.ts` so the invariant is
+ * exercisable from a focused spec without mounting the 9700-LOC entry
+ * module.
+ *
+ * Contract (in priority order):
+ *  1. `status === 'needs_verification'`    → exit 2
+ *  2. `unverifiedReason === 'verification_command_failed'` → exit 1
+ *  3. `verificationFailures` is a non-empty array          → exit 1
+ *  4. `verified === false && status === 'done'`            → exit 2
+ *  5. `status === 'done'`                                   → exit 0
+ *  6. `status === 'failed'`                                 → exit 8
+ *  7. `status === 'blocked'` (catch-all)                    → exit 9
+ *
+ * The rule fires defensively: rules 3 + 4 cover producer bugs where a
+ * future engine adapter forgets to flip `unverifiedReason` or
+ * downgrade the status to `needs_verification`. Today
+ * `computeVerificationOutcome` always synthesises one of the two,
+ * but the invariant locks the contract.
+ */
+export const ENGINE_EXIT_CODES = {
+    done: 0,
+    failed: 8,
+    blocked: 9,
+    engine_unavailable: 1,
+    needs_verification: 2,
+};
+export function resolveEngineExitCode(result) {
+    if (result.status === 'needs_verification') {
+        return ENGINE_EXIT_CODES.needs_verification;
+    }
+    if (result.unverifiedReason === 'verification_command_failed') {
+        return 1;
+    }
+    if (Array.isArray(result.verificationFailures) && result.verificationFailures.length > 0) {
+        return 1;
+    }
+    if (result.verified === false && result.status === 'done') {
+        return ENGINE_EXIT_CODES.needs_verification;
+    }
+    if (result.status === 'done')
+        return ENGINE_EXIT_CODES.done;
+    if (result.status === 'failed')
+        return ENGINE_EXIT_CODES.failed;
+    return ENGINE_EXIT_CODES.blocked;
+}
+//# sourceMappingURL=engine-exit-code.js.map

package/dist/runtime/version.js

@@ -44,7 +44,7 @@ export function sanitizeSemver(raw) {
  * during import). When bumping the CLI version BOTH literals must be
  * updated; the release smoke-test (`pack:smoke`) verifies they agree.
  */
-export const PUGI_CLI_VERSION = sanitizeSemver('0.1.0-beta.95');
+export const PUGI_CLI_VERSION = sanitizeSemver('0.1.0-beta.97');
 /**
  * Outbound: the CLI's installed semver. Read at request time by
  * `version-interceptor.ts` and injected on every `fetch` call.