@pugi/cli 0.1.0-beta.10 → 0.1.0-beta.101

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

@@ -0,0 +1,806 @@
+/**
+ * Pugi MCP server — orchestrator-tools surface .
+ *
+ * SCOPE — this module is intentionally orthogonal to `server-tools.ts`.
+ *
+ * - `server-tools.ts` exposes the *engine* surface (read / grep / glob /
+ *  edit / write / bash) — workspace-scoped, file-tools-backed, used by
+ *  "external agent borrows Pugi's in-process executor".
+ *
+ * - `orchestrator-tools.ts` (THIS FILE) exposes the *orchestrator*
+ *  surface — `pugi.run` / `pugi.read` / `pugi.write` / `pugi.dispatch`
+ *  / `pugi.publish` / `pugi.deploy`. These are CLI-level operations
+ *  used by an EXTERNAL the upstream tool (or Cursor) session that wants to
+ *  loop fix-publish-test against the LIVE Pugi runtime. The motivating
+ *  use case is the CEO dogfood blocker: Pugi REPL emits
+ *  pseudo-tool-tags inline (no real file writes / no real shell exec);
+ *  the operator wants to drive a remote the upstream tool session that
+ *  programmatically invokes Pugi against the engine VM, captures
+ *  output, edits source, republishes the CLI, and re-tests — all
+ *  without an interactive human at every step.
+ *
+ * SECURITY POSTURE — every orchestrator tool is gated by an env-var
+ * permission switch that defaults to OFF. The MCP server's
+ * `permissionGate` still applies on top (deny-by-default), but env
+ * gates are a coarser kill-switch the operator can flip per-machine
+ * without rebuilding the CLI.
+ *
+ *  - PUGI_MCP_EXEC_ENABLED=1    — enables `pugi.run`
+ *  - PUGI_MCP_PUBLISH_ENABLED=1 — enables `pugi.publish`
+ *  - PUGI_MCP_DEPLOY_ENABLED=1  — enables `pugi.deploy`
+ *
+ * `pugi.read` / `pugi.write` do not require an env gate (read+write
+ * enforce workspace + protected-path containment). `pugi.dispatch`
+ * uses PUGI_MCP_EXEC_ENABLED (shared with `pugi.run`) because it
+ * shells the local `pugi` binary to drive the full engine loop
+ * client-side. All three still pass through the MCP-server
+ * permissionGate, so an operator running `pugi mcp serve` without
+ * `--allow-write` still sees `pugi.write` refused at dispatch.
+ */
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { closeSync, fstatSync, mkdirSync, openSync, readFileSync, renameSync, statSync, writeFileSync, } from 'node:fs';
+import { dirname, isAbsolute, relative, resolve, sep } from 'node:path';
+import { fileURLToPath } from 'node:url';
+const execFileAsync = promisify(execFile);
+/**
+ * Protected basename patterns — mirror of
+ * `core/bash-classifier.ts::PROTECTED_BASENAME_PATTERNS`. We DO NOT
+ * import from there because that module is bash-classifier specific
+ * (the regex shapes there carry shell-quote boundaries). For path-only
+ * matching we use simpler RegExps anchored on the basename. Keeps the
+ * two modules independently auditable.
+ */
+const PROTECTED_BASENAMES = [
+    /^\.env$/,
+    /^\.env\.[A-Za-z0-9_-]+$/,
+    /^id_(rsa|ed25519|ecdsa|dsa)(\.pub)?$/,
+    /^\.npmrc$/,
+    /^\.pypirc$/,
+    /^\.gitconfig$/,
+    /^credentials(\.json)?$/,
+];
+const PROTECTED_DIR_SEGMENTS = new Set([
+    '.git',
+    '.ssh',
+    '.gnupg',
+    'node_modules',
+]);
+/**
+ * Resolve + validate a caller-supplied path against the workspace
+ * root. Refuses absolute paths outside the root, parent-traversal
+ * escapes, and protected basenames / dir segments.
+ *
+ * Exported so the spec can drive it directly — pinning the security
+ * boundary at a single audited entry point.
+ */
+export function resolveWorkspacePathOrThrow(ctx, requested) {
+    if (typeof requested !== 'string' || requested.length === 0) {
+        throw new Error('path must be a non-empty string');
+    }
+    if (requested.includes('\0')) {
+        throw new Error('path contains a null byte');
+    }
+    const root = resolve(ctx.workspaceRoot);
+    const candidate = isAbsolute(requested) ? requested : resolve(root, requested);
+    const absolute = resolve(candidate);
+    // Containment check — absolute must live under root. We use
+    // `relative` + `..` detection rather than `startsWith(root)` so a
+    // sibling dir whose name happens to share a prefix (e.g. /tmp/wsX
+    // vs /tmp/ws) does not accidentally pass.
+    const rel = relative(root, absolute);
+    if (rel === '' || rel === '.') {
+        throw new Error(`path "${requested}" resolves to the workspace root itself`);
+    }
+    if (rel.startsWith('..') || isAbsolute(rel)) {
+        throw new Error(`path "${requested}" escapes the workspace root`);
+    }
+    // Protected segment / basename check — applied to EVERY component of
+    // the resolved path under the root. We split on the OS separator so
+    // Windows + POSIX share the same gate.
+    const segments = rel.split(sep);
+    for (const segment of segments) {
+        if (PROTECTED_DIR_SEGMENTS.has(segment)) {
+            throw new Error(`path "${requested}" touches protected segment "${segment}"`);
+        }
+        for (const pattern of PROTECTED_BASENAMES) {
+            if (pattern.test(segment)) {
+                throw new Error(`path "${requested}" touches protected basename "${segment}"`);
+            }
+        }
+    }
+    return { absolute, relativeToRoot: rel };
+}
+/**
+ * Build the orchestrator tool surface. The MCP server consumes the
+ * returned array via `createPugiMcpServer({ tools })`. Permission
+ * gating happens at TWO layers:
+ *
+ *  1. `capabilities.{exec,publish,deploy}` — env-var kill-switch
+ *     checked at tool-execute time. A tool whose capability is OFF
+ *     throws a deterministic refusal message; the MCP wire surfaces
+ *     it as `isError: true` content.
+ *
+ *  2. The MCP server's `permissionGate` — checked BEFORE execute
+ *     runs. The `pugi mcp serve` wiring in `runtime/commands/mcp.ts`
+ *     synthesises a default gate; callers (tests) can pass
+ *     `() => true` to bypass.
+ *
+ * The double-layer design is intentional — it lets an operator
+ * configure `PUGI_MCP_EXEC_ENABLED=1` system-wide AND still refuse a
+ * specific `pugi.run` call via the per-tool prompt without restarting
+ * the server.
+ */
+/**
+ * Allowed dispatch subcommands. Mirror of the `command` enum in the
+ * admin-api `EngineRequestDto` (apps/admin-api/src/pugi-engine/
+ * pugi-engine.controller.ts). Kept as a local literal so this surface
+ * stays decoupled from the admin-api package — the CLI must work
+ * standalone after `npm i -g @pugi/cli`.
+ */
+const ALLOWED_DISPATCH_COMMANDS = ['code', 'explain', 'fix', 'plan', 'build'];
+export function buildOrchestratorTools(ctx) {
+    const execImpl = ctx.execFileImpl ?? execFileAsync;
+    const tools = [
+        {
+            name: 'pugi.run',
+            description: 'Execute a pugi CLI subcommand and capture stdout/stderr/exitCode. ' +
+                'Use for `--version`, `explain`, `smoke`, etc. ' +
+                'Requires PUGI_MCP_EXEC_ENABLED=1 at server boot.',
+            permission: 'bash',
+            inputSchema: {
+                type: 'object',
+                additionalProperties: false,
+                required: ['command'],
+                properties: {
+                    command: {
+                        type: 'string',
+                        description: 'Whitespace-tokenised argv tail (e.g. "explain README.md").',
+                    },
+                    cwd: {
+                        type: 'string',
+                        description: 'Optional workspace-relative cwd; defaults to workspace root.',
+                    },
+                    timeoutMs: {
+                        type: 'number',
+                        minimum: 100,
+                        maximum: 300000,
+                        description: 'Hard timeout in ms (default 30000).',
+                    },
+                },
+            },
+            async execute(args) {
+                if (!ctx.capabilities.exec) {
+                    throw new Error('pugi.run: PUGI_MCP_EXEC_ENABLED is not set. ' +
+                        'Restart `pugi mcp serve` with PUGI_MCP_EXEC_ENABLED=1 to enable shell execution.');
+                }
+                const command = requireString(args, 'command');
+                const tokens = tokeniseArgv(command);
+                if (tokens.length === 0) {
+                    throw new Error('pugi.run: command tokenises to zero args');
+                }
+                const timeoutMs = optionalNumber(args, 'timeoutMs', 30000);
+                const cwdInput = optionalString(args, 'cwd');
+                const cwd = cwdInput
+                    ? resolveWorkspacePathOrThrow(ctx, cwdInput).absolute
+                    : ctx.workspaceRoot;
+                const started = Date.now();
+                try {
+                    const { stdout, stderr } = await execImpl(ctx.pugiBin, tokens, {
+                        cwd,
+                        timeout: timeoutMs,
+                        maxBuffer: 4 * 1024 * 1024,
+                        // Strip secret envs — orchestrator-driven CLI runs do NOT
+                        // need the operator's NPM_TOKEN / GH_TOKEN / OPENAI_API_KEY
+                        // visible. We pass through only PATH + HOME + a minimal
+                        // shell. Same posture as bashToolSync(source='mcp').
+                        env: sanitisedEnv(),
+                    });
+                    const durationMs = Date.now() - started;
+                    return JSON.stringify({
+                        stdout: clamp(stdout, 32 * 1024),
+                        stderr: clamp(stderr, 32 * 1024),
+                        exitCode: 0,
+                        durationMs,
+                    });
+                }
+                catch (err) {
+                    const e = err;
+                    const durationMs = Date.now() - started;
+                    return JSON.stringify({
+                        stdout: clamp(e.stdout ?? '', 32 * 1024),
+                        stderr: clamp(e.stderr ?? (e.message ?? ''), 32 * 1024),
+                        exitCode: typeof e.code === 'number' ? e.code : 1,
+                        durationMs,
+                        ...(e.signal ? { signal: e.signal } : {}),
+                        ...(e.killed ? { killed: true } : {}),
+                    });
+                }
+            },
+        },
+        {
+            name: 'pugi.read',
+            description: 'Read a file inside the configured workspace root. Refuses paths outside ' +
+                'the root, parent-traversal escapes, and protected basenames (.env / .git / ' +
+                '.ssh / id_rsa / .npmrc / credentials.json). Default cap 256KB.',
+            permission: 'read',
+            inputSchema: {
+                type: 'object',
+                additionalProperties: false,
+                required: ['path'],
+                properties: {
+                    path: { type: 'string' },
+                },
+            },
+            async execute(args) {
+                const path = requireString(args, 'path');
+                const { absolute, relativeToRoot } = resolveWorkspacePathOrThrow(ctx, path);
+                const stat = statSync(absolute);
+                if (!stat.isFile()) {
+                    throw new Error(`pugi.read: "${relativeToRoot}" is not a regular file`);
+                }
+                const CAP = 256 * 1024;
+                const content = readFileSync(absolute, 'utf8');
+                const sizeBytes = Buffer.byteLength(content, 'utf8');
+                const truncated = sizeBytes > CAP;
+                return JSON.stringify({
+                    path: relativeToRoot,
+                    content: truncated ? content.slice(0, CAP) : content,
+                    sizeBytes,
+                    mtime: stat.mtime.toISOString(),
+                    ...(truncated ? { truncated: true, capBytes: CAP } : {}),
+                });
+            },
+        },
+        {
+            name: 'pugi.write',
+            description: 'Create or overwrite a workspace file using atomic tmp+rename. Refuses paths ' +
+                'outside the workspace root and protected basenames.',
+            permission: 'edit',
+            inputSchema: {
+                type: 'object',
+                additionalProperties: false,
+                required: ['path', 'content'],
+                properties: {
+                    path: { type: 'string' },
+                    content: { type: 'string' },
+                },
+            },
+            async execute(args) {
+                const path = requireString(args, 'path');
+                const content = requireString(args, 'content');
+                const { absolute, relativeToRoot } = resolveWorkspacePathOrThrow(ctx, path);
+                mkdirSync(dirname(absolute), { recursive: true });
+                const tmpPath = `${absolute}.pugi-mcp-tmp-${process.pid}-${Date.now()}`;
+                // Open with O_CREAT|O_EXCL so a concurrent writer cannot race
+                // a same-named tmp file out from under us. Mode 0o600 (operator
+                // only) — orchestrator writes are NOT shared artefacts.
+                const fd = openSync(tmpPath, 'wx', 0o600);
+                try {
+                    writeFileSync(fd, content, 'utf8');
+                    // fsync via fstatSync is a no-op on most kernels — the real
+                    // durability win comes from rename being atomic at the inode
+                    // layer. We still touch the fd to surface any late-EIO before
+                    // rename commits.
+                    fstatSync(fd);
+                }
+                finally {
+                    closeSync(fd);
+                }
+                renameSync(tmpPath, absolute);
+                const bytesWritten = Buffer.byteLength(content, 'utf8');
+                return JSON.stringify({
+                    path: relativeToRoot,
+                    bytesWritten,
+                });
+            },
+        },
+        {
+            name: 'pugi.dispatch',
+            description: 'Run the Pugi engine loop end-to-end by shelling to `pugi <command> <prompt>` ' +
+                '(default command "code"). Drives the full client-side tool-use loop, so the ' +
+                'caller sees real file writes, real shell exec, real cost — not just one Anvil ' +
+                'turn. Workspace cwd must be `pugi init`-ed already; auth resolves through the ' +
+                'CLI (PUGI_API_KEY env or on-disk `pugi login` state). ' +
+                'Requires PUGI_MCP_EXEC_ENABLED=1 at server boot.',
+            permission: 'bash',
+            inputSchema: {
+                type: 'object',
+                additionalProperties: false,
+                required: ['prompt'],
+                properties: {
+                    prompt: { type: 'string' },
+                    command: {
+                        type: 'string',
+                        enum: ['code', 'explain', 'fix', 'plan', 'build'],
+                        description: 'Pugi CLI subcommand. Default "code".',
+                    },
+                    cwd: {
+                        type: 'string',
+                        description: 'Optional workspace-relative cwd; defaults to the MCP workspace root. ' +
+                            'Must already be `pugi init`-ed.',
+                    },
+                    timeoutMs: {
+                        type: 'number',
+                        minimum: 100,
+                        maximum: 600000,
+                        description: 'Hard timeout in ms (default 180000).',
+                    },
+                },
+            },
+            async execute(args) {
+                if (!ctx.capabilities.exec) {
+                    throw new Error('pugi.dispatch: PUGI_MCP_EXEC_ENABLED is not set. ' +
+                        'Restart `pugi mcp serve` with PUGI_MCP_EXEC_ENABLED=1 to enable shell-driven dispatch.');
+                }
+                const prompt = requireString(args, 'prompt');
+                // Argv-injection guard. The `pugi` CLI parser (runtime/cli.ts) uses
+                // an allowlist of known global flags (`--remote`, `--allow-fetch`,
+                // `--allow-search`, `--triple`, etc.) and does not honour a `--`
+                // end-of-options sentinel. Passing a prompt that begins with `--`
+                // risks the parser swallowing it as a CLI flag (e.g. an attacker-
+                // controlled MCP client sending `prompt: "--allow-fetch"` to
+                // silently unlock a capability the operator did not intend to
+                // grant for this turn). Reject at the MCP boundary so we fail
+                // loud rather than silently shift CLI behaviour. Operators with
+                // legitimate prompts starting with `--` can prepend a space.
+                if (prompt.startsWith('--')) {
+                    throw new Error('pugi.dispatch: prompt cannot start with "--" — the child CLI parser would ' +
+                        'interpret it as a flag. Prepend a space (" --foo") or rephrase.');
+                }
+                const command = optionalString(args, 'command') ?? 'code';
+                if (!ALLOWED_DISPATCH_COMMANDS.includes(command)) {
+                    throw new Error(`pugi.dispatch: invalid command "${command}" (allowed: ${ALLOWED_DISPATCH_COMMANDS.join(', ')})`);
+                }
+                const cwdInput = optionalString(args, 'cwd');
+                const cwd = cwdInput
+                    ? resolveWorkspacePathOrThrow(ctx, cwdInput).absolute
+                    : 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', '--json'], {
+                        cwd,
+                        timeout: timeoutMs,
+                        maxBuffer: 8 * 1024 * 1024,
+                        // Auth-bearing envs are passed through here even though
+                        // `sanitisedEnv()` strips them for `pugi.run`. Rationale:
+                        // dispatch is explicitly an authenticated engine call, so
+                        // the child must reach Anvil. The CLI prefers on-disk
+                        // `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,
+                        // 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) {
+                    const e = err;
+                    // `||` chain (not `??`) so an empty / whitespace-only `e.stderr`
+                    // does not swallow a spawn-side `e.message` like `"spawn pugi
+                    // 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: 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,
+                            }
+                            : {}),
+                    });
+                }
+            },
+        },
+        {
+            name: 'pugi.publish',
+            description: 'Bump @pugi/cli version + build + publish to npm. Use bumpType "beta" for ' +
+                'prerelease bumps (default) or "patch" for stable. Requires ' +
+                'PUGI_MCP_PUBLISH_ENABLED=1 AND a configured ~/.npmrc auth token.',
+            permission: 'network',
+            inputSchema: {
+                type: 'object',
+                additionalProperties: false,
+                properties: {
+                    bumpType: {
+                        type: 'string',
+                        enum: ['patch', 'beta'],
+                        description: 'Default "beta" — pre-release bump.',
+                    },
+                },
+            },
+            async execute(args) {
+                if (!ctx.capabilities.publish) {
+                    throw new Error('pugi.publish: PUGI_MCP_PUBLISH_ENABLED is not set. ' +
+                        'Restart `pugi mcp serve` with PUGI_MCP_PUBLISH_ENABLED=1 to enable.');
+                }
+                const bumpType = optionalString(args, 'bumpType') ?? 'beta';
+                if (bumpType !== 'patch' && bumpType !== 'beta') {
+                    throw new Error(`pugi.publish: invalid bumpType "${bumpType}"`);
+                }
+                // npm version semantics: "patch" bumps z; "prerelease --preid beta"
+                // bumps the beta tag. We thread through `pnpm` because the
+                // monorepo build expects the workspace-aware variant.
+                const versionArgs = bumpType === 'beta'
+                    ? ['version', 'prerelease', '--preid', 'beta', '--no-git-tag-version']
+                    : ['version', 'patch', '--no-git-tag-version'];
+                const versionOut = await execImpl('npm', versionArgs, {
+                    cwd: ctx.workspaceRoot,
+                    timeout: 60000,
+                    env: sanitisedEnv(),
+                });
+                const newVersion = (versionOut.stdout || '').trim().replace(/^v/, '');
+                const buildOut = await execImpl('pnpm', ['build'], {
+                    cwd: ctx.workspaceRoot,
+                    timeout: 180000,
+                    env: sanitisedEnv(),
+                });
+                const publishOut = await execImpl('pnpm', ['publish', '--no-git-checks', '--access', 'public'], {
+                    cwd: ctx.workspaceRoot,
+                    timeout: 180000,
+                    env: sanitisedEnv(),
+                });
+                return JSON.stringify({
+                    newVersion,
+                    registry: 'https://registry.npmjs.org',
+                    npmExitCode: 0,
+                    buildStdoutTail: clamp(buildOut.stdout, 2000),
+                    publishStdoutTail: clamp(publishOut.stdout, 2000),
+                });
+            },
+        },
+        {
+            name: 'pugi.deploy',
+            description: 'SSH-redeploy a Pugi service on the engine VM (admin-api / admin-web / ' +
+                'pugi-web / all). Runs git pull + pnpm install + build + pm2 restart. ' +
+                'Requires PUGI_MCP_DEPLOY_ENABLED=1.',
+            permission: 'network',
+            inputSchema: {
+                type: 'object',
+                additionalProperties: false,
+                required: ['target'],
+                properties: {
+                    target: {
+                        type: 'string',
+                        enum: ['admin-api', 'admin-web', 'pugi-web', 'all'],
+                    },
+                },
+            },
+            async execute(args) {
+                if (!ctx.capabilities.deploy) {
+                    throw new Error('pugi.deploy: PUGI_MCP_DEPLOY_ENABLED is not set. ' +
+                        'Restart `pugi mcp serve` with PUGI_MCP_DEPLOY_ENABLED=1 to enable.');
+                }
+                const target = requireString(args, 'target');
+                const allowed = ['admin-api', 'admin-web', 'pugi-web', 'all'];
+                if (!allowed.includes(target)) {
+                    throw new Error(`pugi.deploy: invalid target "${target}" (allowed: ${allowed.join(', ')})`);
+                }
+                // The redeploy script lives on the engine VM at ~/deploy/<target>.sh.
+                // We do NOT inline the shell — the operator owns the remote
+                // script and can tune it without rebuilding the CLI.
+                const remoteCmd = `set -euo pipefail; ~/deploy/${target}.sh`;
+                const started = Date.now();
+                const { stdout, stderr } = await execImpl('ssh', [
+                    // BatchMode rejects password prompts so a misconfigured
+                    // ssh-agent fails fast instead of blocking the dispatch.
+                    '-o',
+                    'BatchMode=yes',
+                    '-o',
+                    'StrictHostKeyChecking=accept-new',
+                    ctx.sshAlias,
+                    remoteCmd,
+                ], {
+                    cwd: ctx.workspaceRoot,
+                    timeout: 300000,
+                    maxBuffer: 4 * 1024 * 1024,
+                    env: sanitisedEnv(),
+                });
+                const durationMs = Date.now() - started;
+                return JSON.stringify({
+                    host: ctx.sshAlias,
+                    target,
+                    gitPullHead: extractGitHead(stdout) ?? null,
+                    pm2Status: extractPm2Status(stdout, stderr) ?? null,
+                    durationMs,
+                    stdoutTail: clamp(stdout, 4000),
+                    stderrTail: clamp(stderr, 2000),
+                });
+            },
+        },
+    ];
+    return tools.sort((a, b) => a.name.localeCompare(b.name));
+}
+/* ---------- helpers ---------------------------------------------------- */
+function requireString(args, key) {
+    const v = args[key];
+    if (typeof v !== 'string' || v.length === 0) {
+        throw new Error(`argument "${key}" must be a non-empty string`);
+    }
+    return v;
+}
+function optionalString(args, key) {
+    const v = args[key];
+    if (v === undefined || v === null)
+        return undefined;
+    if (typeof v !== 'string') {
+        throw new Error(`argument "${key}" must be a string when set`);
+    }
+    return v;
+}
+function optionalNumber(args, key, fallback) {
+    const v = args[key];
+    if (v === undefined || v === null)
+        return fallback;
+    if (typeof v !== 'number' || !Number.isFinite(v)) {
+        throw new Error(`argument "${key}" must be a finite number when set`);
+    }
+    return v;
+}
+function clamp(s, max) {
+    if (typeof s !== 'string')
+        return '';
+    if (s.length <= max)
+        return s;
+    return `${s.slice(0, max)}\n…(truncated at ${max} bytes)`;
+}
+/**
+ * Tokenise an argv tail the same way the upstream tool's `pugi run` quoting
+ * convention does — whitespace-split with double-quote groups
+ * preserved. We do NOT eval a shell because that would let the model
+ * inject arbitrary commands (e.g. `; rm -rf ~`) into the orchestrator
+ * surface. Anything fancier (env-var expansion, globbing) must be
+ * delegated to the model via a `bash` capability flag — which is
+ * intentionally not part of this surface.
+ *
+ * Exported for the spec.
+ */
+export function tokeniseArgv(command) {
+    const out = [];
+    let buf = '';
+    let inQuotes = false;
+    for (let i = 0; i < command.length; i += 1) {
+        const ch = command[i];
+        if (ch === '"') {
+            inQuotes = !inQuotes;
+            continue;
+        }
+        if (ch === '\\' && command[i + 1] === '"') {
+            buf += '"';
+            i += 1;
+            continue;
+        }
+        if (!inQuotes && (ch === ' ' || ch === '\t')) {
+            if (buf.length > 0) {
+                out.push(buf);
+                buf = '';
+            }
+            continue;
+        }
+        buf += ch;
+    }
+    if (inQuotes) {
+        throw new Error('pugi.run: unterminated double-quote in command');
+    }
+    if (buf.length > 0)
+        out.push(buf);
+    return out;
+}
+function sanitisedEnv() {
+    // Allowlist — pass through only what `pugi` needs to find itself
+    // and the local toolchain. NPM_TOKEN is added back for
+    // `pugi.publish` via the npm CLI's own ~/.npmrc lookup — we do not
+    // pass it via env because that surface ends up in `ps` output on
+    // some kernels.
+    const allow = ['PATH', 'HOME', 'USER', 'SHELL', 'LANG', 'LC_ALL', 'TERM', 'NODE_OPTIONS'];
+    const out = {};
+    for (const key of allow) {
+        const value = process.env[key];
+        if (value !== undefined)
+            out[key] = value;
+    }
+    return out;
+}
+function dispatchEnv() {
+    // Like sanitisedEnv() but threads PUGI_API_KEY / PUGI_API_URL through
+    // so the child `pugi <command>` invocation can resolve auth from env
+    // when on-disk `pugi login` state is unavailable (CI, fresh container).
+    const allow = [
+        'PATH',
+        'HOME',
+        'USER',
+        'SHELL',
+        'LANG',
+        'LC_ALL',
+        'TERM',
+        'NODE_OPTIONS',
+        'PUGI_API_KEY',
+        'PUGI_API_URL',
+    ];
+    const out = {};
+    for (const key of allow) {
+        const value = process.env[key];
+        if (value !== undefined)
+            out[key] = value;
+    }
+    return out;
+}
+function extractGitHead(stdout) {
+    // Match "HEAD is now at <sha> …" or "<sha> commit message" — the
+    // remote redeploy script logs `git rev-parse HEAD` after pull.
+    const m = stdout.match(/(?:HEAD is now at|^|\n)([0-9a-f]{7,40})\b/);
+    return m ? m[1] : null;
+}
+function extractPm2Status(stdout, stderr) {
+    const haystack = `${stdout}\n${stderr}`;
+    // Match "[PM2] Process pugi-admin-api restarted" or "online" / "stopped"
+    const restart = haystack.match(/\[PM2\][^\n]+(restarted|online|stopped|errored)/i);
+    if (restart)
+        return restart[0].trim();
+    return null;
+}
+/* ---------- helper: load this module from compiled JS at runtime ------- */
+// `fileURLToPath(import.meta.url)` is used by sibling modules to find
+// fixtures at runtime; we re-export it here so the spec can build an
+// isolated workspace next to the compiled module without hard-coding
+// paths. Defensive — not currently used by the production wiring.
+export const ORCHESTRATOR_TOOLS_MODULE_FILE = (() => {
+    try {
+        return fileURLToPath(import.meta.url);
+    }
+    catch {
+        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