@pugi/cli 0.1.0-beta.98 → 1.0.0-alpha.1

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

@@ -1,806 +0,0 @@
-/**
- * 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