@pugi/cli 0.1.0-beta.11 → 0.1.0-beta.13

package/dist/core/engine/prompts.js

@@ -34,6 +34,50 @@ const COMMON_LOCAL_FIRST_PREAMBLE = [
     'Cite file paths relative to the workspace root. Keep edits minimal and reversible.',
     'When you are done, return a single final text answer that the operator can read on the CLI.',
 ].join(' ');
+/**
+ * β5a P1+P6 (2026-05-26): prompt v2 — intent marker contract +
+ * definitional examples + jargon ban. Fixes the dominant Pugi loss
+ * mode in the α7.X Phase 2 comparative eval: tool-use on pure
+ * knowledge questions ("What is grep?" → bash man grep).
+ *
+ * The CLI-side `classifyIntent` (apps/pugi-cli/src/core/engine/intent.ts)
+ * wraps definitional questions with `<intent kind="definitional">` on
+ * the user message before send. The rules below teach the model what
+ * to do with that marker.
+ *
+ * Voice constraint: same banned-jargon list as the cabinet Mira
+ * persona (брифую / диспатчу / шипаю and the English jargon list
+ * from BANNED_WORDS in mira.system-prompt.ts). Repeated here verbatim
+ * so the CLI surface has its own enforcement copy; the cabinet copy
+ * is the source of truth and ships through the runtime persona
+ * prompt for the cabinet UI. CLI runs DO NOT load the cabinet
+ * persona prompt — engine prompts are the only place to enforce
+ * voice for `pugi explain` / `pugi code` callers.
+ */
+const INTENT_MARKER_CONTRACT = [
+    '# Intent contract',
+    'When the operator\'s message starts with `<intent kind="definitional">`, treat it as a knowledge question:',
+    '  - Answer in prose. Do NOT call any tools.',
+    '  - Cite a file from the repo only when it directly supports the explanation.',
+    '  - Keep the answer to one short paragraph unless the operator asked for depth.',
+    'When no intent marker is present OR the marker is operational, use tools as needed.',
+    '',
+    '# Definitional examples',
+    'Operator: `<intent kind="definitional">What is grep?</intent>`',
+    'You: `grep is a Unix command-line tool that searches plain text for lines matching a regular expression. It reads stdin or files and prints matching lines to stdout.`',
+    '(No tool calls. One paragraph. No file paths because grep is a generic Unix tool, not a repo artefact.)',
+    '',
+    'Operator: `<intent kind="definitional">что такое pgvector?</intent>`',
+    'You: `pgvector - это расширение PostgreSQL для хранения и поиска векторных эмбеддингов. Поддерживает ivfflat и hnsw индексы; используется для RAG и semantic search.`',
+    '(One short paragraph. No tools.)',
+].join('\n');
+const JARGON_BAN = [
+    '# Voice',
+    'Brand voice: terse, operator-grade, English in code paths / Russian-Ukrainian permitted in chat answers.',
+    'Banned words (CLI customer-facing output): "брифую", "диспатчу", "шипаю", "journey", "explore", "delight", "magical", "friendly", "let me help", "I\'d be happy to", "pug-tastic". Use neutral verbs instead: brief / dispatch / ship / build / read / write.',
+    'No em-dashes. No emoji. No "AI assistant" framing.',
+].join('\n');
+const PROMPT_V2_APPENDIX = [INTENT_MARKER_CONTRACT, JARGON_BAN].join('\n\n');
 const PLAN_TOOLS_NOTE = 'PLAN MODE IS READ-ONLY. You may call read, grep, glob. Calls to write, edit, or bash will be refused and end the run. Produce a written plan, not changes.';
 const EDIT_FLOW_RULES = [
     'Before calling edit on a file you have not yet read this session, call read first — the edit tool fails otherwise.',
@@ -42,10 +86,16 @@ const EDIT_FLOW_RULES = [
 ].join(' ');
 export function systemPromptFor(kind) {
     const base = baseSystemPromptFor(kind);
+    // β5a P1+P6: append the prompt-v2 intent-marker contract +
+    // definitional examples + jargon ban to every command kind. The
+    // appendix is shared across kinds because the marker contract +
+    // voice gate are command-agnostic — a definitional question lands
+    // the same way under `pugi explain` and `pugi code`.
+    const withV2 = `${base}\n\n${PROMPT_V2_APPENDIX}`;
     const snapshot = formatBackgroundJobsSnapshot(getJobRegistrySafely());
     if (!snapshot)
-        return base;
-    return `${base}\n\n${snapshot}`;
+        return withV2;
+    return `${withV2}\n\n${snapshot}`;
 }
 function baseSystemPromptFor(kind) {
     switch (kind) {

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

@@ -4,6 +4,10 @@ import { askUser } from '../../tools/ask-user.js';
 import { skillInvoke, skillList } from '../../tools/skill-tool.js';
 import { taskCreate, taskGet, taskList, taskUpdate, } from '../../tools/tasks.js';
 import { webFetchTool } from '../../tools/web-fetch.js';
+import { webSearchTool } from '../../tools/web-search.js';
+import { agentTool } from '../../tools/agent-tool.js';
+import { multiEdit } from '../../tools/multi-edit.js';
+import { buildMcpToolDefs, defaultNonInteractiveMcpPrompt, dispatchMcpTool, MCP_TOOL_PREFIX, } from '../../tools/mcp-tool.js';
 /**
  * Tool-bridge: turns the abstract tool registry into:
  *   1. An OpenAI-shaped tools schema for `EngineLoopClient.send`.
@@ -45,6 +49,12 @@ const READ_ONLY_TOOLS = new Set([
     'task_list',
     'task_update',
     'web_fetch',
+    // β1b T4 (2026-05-26): web_search is read-only from the workspace's
+    // perspective (no file writes, no shell). Egress goes through the
+    // Anvil-proxied Brave Search API, gated by the same opt-in posture as
+    // web_fetch. Plan mode keeps the tool available because reading the
+    // web is part of how a plan is researched.
+    'web_search',
 ]);
 /**
  * Tools the engine loop dispatches. β1 expands the M1 cornerstone six
@@ -68,9 +78,25 @@ const WIRED_TOOLS = new Set([
     'task_list',
     'task_update',
     'web_fetch',
+    // β1b T4: see READ_ONLY_TOOLS above.
+    'web_search',
+    // β2 S3 (2026-05-26): real subagent spawn primitive. Only advertised
+    // when buildToolsSchema is called with allowAgent=true (orchestrator
+    // / root Mira context); plan-mode also excludes it because spawning
+    // a write-capable child violates plan-mode's read-only contract.
+    'agent',
+    // β7 L5+T11 (2026-05-26): transactional multi-file edit. Routes
+    // through the same security gate as Layer A/B/C; not advertised in
+    // plan mode (mutation surface).
+    'multi_edit',
 ]);
-export function buildToolsSchema(kind, options = { allowFetch: false }) {
+export function buildToolsSchema(kind, options = { allowFetch: false, allowSearch: false }) {
     const planMode = kind === 'plan';
+    // β4 M1/M3: splice MCP tools BEFORE the native list assembly so the
+    // engine-loop sees them in stable alphabetical order alongside native
+    // tools. We keep the entries appended after the native push so plan-
+    // mode can be filtered by namespace prefix in one place at the end.
+    const mcpDefs = buildMcpToolDefs(options.mcpRegistry);
     const toolDefs = [
         {
             name: 'read',
@@ -224,6 +250,85 @@ export function buildToolsSchema(kind, options = { allowFetch: false }) {
             },
         });
     }
+    // β1b T4 (2026-05-26): web_search advertisement. Same off-by-default
+    // privacy posture as web_fetch — the query string itself is an egress
+    // event that can leak operator intent to the upstream Brave Search
+    // backend. The tool dispatcher applies SSRF guards (no localhost via
+    // the Anvil proxy URL), rate-limits (5 req/min per session), and caps
+    // the result payload at 1 MiB. Sentinel-wrapped results so the model
+    // treats every snippet as data, not instructions.
+    if (options.allowSearch) {
+        toolDefs.push({
+            name: 'web_search',
+            description: 'Search the web via Brave Search (Anvil-proxied). Returns up to 10 sentinel-wrapped {title, url, snippet} results. Rate-limited to 5 calls/min per session. Gated off by default.',
+            parameters: {
+                type: 'object',
+                additionalProperties: false,
+                required: ['query'],
+                properties: {
+                    query: {
+                        type: 'string',
+                        description: 'Search query, max 256 chars. Plain text — no operators.',
+                    },
+                    count: {
+                        type: 'integer',
+                        description: 'Optional result count (1..10, default 10).',
+                    },
+                },
+            },
+        });
+    }
+    // β2 S3 (2026-05-26): `agent` tool — subagent spawn primitive.
+    // Off by default; surfaced only when the caller explicitly opts in
+    // (orchestrator parents pass allowAgent=true via the engine adapter).
+    // Plan mode FORCES the tool off regardless because a write-capable
+    // child would violate plan-mode's read-only contract.
+    if (options.allowAgent && !planMode) {
+        toolDefs.push({
+            name: 'agent',
+            description: 'Spawn a specialist subagent under a Cyber-Zoo brand persona. '
+                + 'Role selects the persona + isolation tier: '
+                + 'researcher/reviewer/architect are read-only, verifier reads + runs tests, '
+                + 'coder/release/devops/design_qa get write + bash. '
+                + 'The child runs a fresh Anvil engine loop with its own transcript and '
+                + 'returns a JSON envelope (filesChanged, toolCallCount, status, summary). '
+                + 'Use this when the work needs a specialist persona OR write isolation via a scratch worktree.',
+            parameters: {
+                type: 'object',
+                additionalProperties: false,
+                required: ['role', 'brief'],
+                properties: {
+                    role: {
+                        type: 'string',
+                        enum: [
+                            'orchestrator',
+                            'architect',
+                            'coder',
+                            'verifier',
+                            'reviewer',
+                            'researcher',
+                            'release',
+                            'devops',
+                            'design_qa',
+                        ],
+                        description: 'SubagentRole — selects persona + isolation tier.',
+                    },
+                    brief: {
+                        type: 'string',
+                        maxLength: 8000,
+                        description: 'One-paragraph task description forwarded to the child as the user prompt. '
+                            + 'Be concrete: include filenames, expected behavior, and acceptance criteria.',
+                    },
+                    isolation: {
+                        type: 'string',
+                        enum: ['worktree', 'shared_fs', 'auto'],
+                        description: 'Optional override. `worktree` forces a scratch git worktree for write isolation; '
+                            + '`shared_fs` forces same-tree execution; `auto` (default) defers to the role tier.',
+                    },
+                },
+            },
+        });
+    }
     if (!planMode) {
         toolDefs.push({
             name: 'write',
@@ -261,8 +366,57 @@ export function buildToolsSchema(kind, options = { allowFetch: false }) {
                     command: { type: 'string', description: 'Single shell command to execute.' },
                 },
             },
+        }, 
+        // β7 L5+T11 (2026-05-26): transactional multi-file edit. Either
+        // all entries land or none do — failures roll the workspace back
+        // via the same journal + snapshot machinery the dispatcher uses.
+        // Cap is 50 entries; beyond that the operator (or model) should
+        // split the refactor or use Layer C rewrites.
+        {
+            name: 'multi_edit',
+            description: 'Apply an ordered batch of single-occurrence file edits as one transaction. ' +
+                'Each entry is {file, oldString, newString} like the `edit` tool. Either every ' +
+                'edit lands or none do — a failure rolls the workspace back to the pre-dispatch ' +
+                'state via journal + snapshot. Cap 50 edits per call. Use this for coordinated ' +
+                'refactors (rename across files, add an import to many modules).',
+            parameters: {
+                type: 'object',
+                additionalProperties: false,
+                required: ['edits'],
+                properties: {
+                    edits: {
+                        type: 'array',
+                        minItems: 1,
+                        maxItems: 50,
+                        items: {
+                            type: 'object',
+                            additionalProperties: false,
+                            required: ['file', 'oldString', 'newString'],
+                            properties: {
+                                file: { type: 'string', description: 'Workspace-relative file path.' },
+                                oldString: { type: 'string', description: 'Verbatim substring; must be unique in the pre-edit file.' },
+                                newString: { type: 'string', description: 'Replacement string. Empty string means delete.' },
+                            },
+                        },
+                    },
+                },
+            },
         });
     }
+    // β4 M1/M3: append MCP tools last. Plan mode skips them because every
+    // MCP tool is treated as medium-risk until per-tool annotations land
+    // in the MCP spec; treating MCP read-as-read would require server-
+    // side metadata we cannot trust today (a misconfigured server could
+    // claim `read` while running a destructive op).
+    if (!planMode) {
+        for (const def of mcpDefs) {
+            toolDefs.push({
+                name: def.name,
+                description: def.description,
+                parameters: def.parameters,
+            });
+        }
+    }
     return toolDefs;
 }
 function parseArgs(raw) {
@@ -287,18 +441,27 @@ function requireString(obj, key) {
     return v;
 }
 export function buildExecutor(input) {
-    const { kind, ctx, hooks, sessionId, askUserBridge, interactive, allowFetch } = input;
+    const { kind, ctx, hooks, sessionId, askUserBridge, interactive, allowFetch, allowSearch, agentDispatch, mcpRegistry } = input;
+    const mcpPrompt = input.mcpPrompt ?? defaultNonInteractiveMcpPrompt;
     const workspaceRoot = input.workspaceRoot ?? ctx.root;
     const planMode = kind === 'plan';
     return async ({ name, arguments: argsRaw }) => {
-        if (!WIRED_TOOLS.has(name)) {
+        // β4 M1/M3: MCP tool names live outside WIRED_TOOLS. They are
+        // validated lazily by the dispatcher (the registry knows which
+        // names are actually exposed). The namespace check happens FIRST
+        // so a bad `mcp__bogus__foo` does not collide with the native
+        // unknown-tool branch.
+        const isMcpName = name.startsWith(MCP_TOOL_PREFIX);
+        if (!isMcpName && !WIRED_TOOLS.has(name)) {
             throw new Error(`unknown tool: ${name}`);
         }
-        if (planMode && !READ_ONLY_TOOLS.has(name)) {
-            // Sentinel recognised by `runEngineLoop` — terminates the loop
-            // with status `tool_refused`. The CLI surfaces this as a blocked
-            // outcome, not a failure, because plan mode is doing its job.
-            throw new Error(`PLAN_MODE_REFUSED: ${name} is not allowed in plan mode`);
+        if (planMode) {
+            // MCP tools are uniformly refused in plan mode (see schema-side
+            // rationale in buildToolsSchema). Native tools split via
+            // READ_ONLY_TOOLS as before.
+            if (isMcpName || !READ_ONLY_TOOLS.has(name)) {
+                throw new Error(`PLAN_MODE_REFUSED: ${name} is not allowed in plan mode`);
+            }
         }
         // α6.9: refuse cancelled-token tool dispatch BEFORE PreToolUse
         // hooks fire so a cancelled brief never reaches user-defined
@@ -336,8 +499,21 @@ export function buildExecutor(input) {
                 }
             }
         }
-        const args = parseArgs(argsRaw);
+        // β4 M1/M3: MCP dispatch deferred to the `dispatch` closure below so
+        // PostToolUse / PostToolUseFailure hooks observe MCP calls just like
+        // native calls. The dispatcher does its own argument parsing — MCP
+        // arg errors surface as model-visible `[MCP dispatch error] ...`
+        // strings, not throws.
+        const args = isMcpName ? {} : parseArgs(argsRaw);
         const dispatch = async () => {
+            if (isMcpName) {
+                return dispatchMcpTool({
+                    name,
+                    argumentsRaw: argsRaw,
+                    registry: mcpRegistry,
+                    prompt: mcpPrompt,
+                });
+            }
             // β1 T1/T2/T3/T5/T6: async-dispatch the new tool surface.
             // task_*, skill, ask_user_question, web_fetch all live behind
             // an async or async-compatible boundary.
@@ -353,6 +529,33 @@ export function buildExecutor(input) {
             if (name === 'web_fetch') {
                 return dispatchWebFetch(args, { ctx, allowFetch: Boolean(allowFetch) });
             }
+            if (name === 'web_search') {
+                return dispatchWebSearch(args, {
+                    ctx,
+                    allowSearch: Boolean(allowSearch),
+                    sessionId,
+                });
+            }
+            if (name === 'multi_edit') {
+                return dispatchMultiEdit(args, ctx);
+            }
+            if (name === 'agent') {
+                // β2a r1 (Backend Architect P1, 2026-05-26): defense in depth.
+                // `WIRED_TOOLS` includes `agent`, so a plan-mode model that
+                // fabricates an `agent` tool call would otherwise be routed
+                // here. The plan-mode refusal at the top of the executor only
+                // fires for tools NOT in READ_ONLY_TOOLS; `agent` is
+                // intentionally absent from both sets, so we explicitly refuse
+                // it here. This pairs with `native-pugi.ts` hard-gating
+                // `agentDispatch` itself off in plan mode — without this
+                // defensive throw a future schema bug could let a plan-mode
+                // model spawn a write-capable child and break the read-only
+                // contract.
+                if (planMode) {
+                    throw new Error('PLAN_MODE_REFUSED: agent is not allowed in plan mode');
+                }
+                return dispatchAgent(args, agentDispatch);
+            }
             return dispatchTool(name, args, ctx);
         };
         try {
@@ -592,6 +795,71 @@ async function dispatchWebFetch(args, opts) {
     });
     return JSON.stringify(result);
 }
+async function dispatchWebSearch(args, opts) {
+    const query = requireString(args, 'query');
+    // `count` is optional integer 1..10. Validate here so the tool layer
+    // gets a clean value (the tool clamps internally too — defense in
+    // depth, since the model can pass anything).
+    let count;
+    if (args['count'] !== undefined && args['count'] !== null) {
+        const n = args['count'];
+        if (typeof n !== 'number' || !Number.isInteger(n)) {
+            throw new Error('web_search: count must be an integer');
+        }
+        count = n;
+    }
+    const result = await webSearchTool({ query, ...(count !== undefined ? { count } : {}) }, {
+        settings: opts.ctx.settings,
+        allowSearch: opts.allowSearch,
+        sessionId: opts.sessionId,
+    });
+    return JSON.stringify(result);
+}
+/**
+ * β2 S3 dispatch — wire the model-emitted `agent` tool call to the
+ * real subagent spawn primitive. When the executor was built without
+ * `agentDispatch` (e.g. a child loop, or a parent that explicitly
+ * disabled subagent spawn), the call is refused with a structured
+ * envelope so the model can adapt instead of crashing the parent loop.
+ */
+async function dispatchAgent(args, opts) {
+    if (!opts) {
+        // No dispatch context — return a structured refusal envelope.
+        // This matches the agent-tool.ts no-engine-client path and lets
+        // the model decide whether to retry inline or abandon the
+        // delegation. Throwing here would terminate the parent on a tool
+        // error frame which is the wrong UX when the issue is config.
+        return JSON.stringify({
+            ok: false,
+            status: 'failed',
+            summary: 'agent tool refused: dispatch not wired in this engine adapter. '
+                + 'Re-run from a parent loop with agentDispatch configured.',
+        });
+    }
+    const parsed = parseAgentArgs(args);
+    const result = await agentTool(parsed, {
+        session: opts.parentSession,
+        engineClient: opts.engineClient,
+        ...(opts.parentBudgetRemaining
+            ? { parentBudgetRemaining: opts.parentBudgetRemaining }
+            : {}),
+    });
+    return JSON.stringify(result);
+}
+function parseAgentArgs(args) {
+    // Surface a clean error message to the model when the args don't
+    // match the schema. agentTool itself also validates via Zod; this
+    // pre-parse layer keeps the error stack short.
+    const role = requireString(args, 'role');
+    const brief = requireString(args, 'brief');
+    const isolationRaw = optionalString(args, 'isolation');
+    const out = {
+        role: role,
+        brief,
+        ...(isolationRaw ? { isolation: isolationRaw } : {}),
+    };
+    return out;
+}
 function optionalString(obj, key) {
     const v = obj[key];
     if (v === undefined || v === null)
@@ -601,4 +869,38 @@ function optionalString(obj, key) {
     }
     return v;
 }
+/**
+ * β7 L5+T11: dispatch the model-emitted `multi_edit` tool call. The
+ * tool returns a structured result envelope; we serialize it to JSON
+ * for the engine loop. A refused dispatch (security, no_match,
+ * ambiguous_match, etc.) surfaces as `ok: false` in the envelope —
+ * the model can re-strategise rather than crashing the loop.
+ */
+function dispatchMultiEdit(args, ctx) {
+    const raw = args['edits'];
+    if (!Array.isArray(raw)) {
+        throw new Error('multi_edit: edits must be an array');
+    }
+    const edits = raw.map((item, i) => {
+        if (!item || typeof item !== 'object') {
+            throw new Error(`multi_edit: edits[${i}] must be an object`);
+        }
+        const obj = item;
+        const file = obj['file'];
+        const oldString = obj['oldString'];
+        const newString = obj['newString'];
+        if (typeof file !== 'string') {
+            throw new Error(`multi_edit: edits[${i}].file must be a string`);
+        }
+        if (typeof oldString !== 'string') {
+            throw new Error(`multi_edit: edits[${i}].oldString must be a string`);
+        }
+        if (typeof newString !== 'string') {
+            throw new Error(`multi_edit: edits[${i}].newString must be a string`);
+        }
+        return { file, oldString, newString };
+    });
+    const result = multiEdit(ctx, edits);
+    return JSON.stringify(result);
+}
 //# sourceMappingURL=tool-bridge.js.map

package/dist/core/lsp/client.js

@@ -465,10 +465,59 @@ export class LspClient {
         }
     }
 }
+/**
+ * Map a short LSP language slug to the settings.json key. β7 L9 — the
+ * settings schema spells out the full language name (`typescript`,
+ * `python`, ...) for human readability; the short slug (`ts`, `py`) is
+ * what every internal call site uses. Keep this map narrow and explicit.
+ */
+const SETTINGS_KEY_BY_LANG = {
+    ts: 'typescript',
+    js: 'javascript',
+    py: 'python',
+    go: 'go',
+    rust: 'rust',
+};
+/**
+ * Report whether the operator has explicitly disabled this language via
+ * `.pugi/settings.json::lsp.<language> = false`. Absent section or
+ * absent key means "enabled by default" — backwards-compatible with the
+ * α7.7 surface that ignored settings entirely. Returns true ONLY when
+ * the operator explicitly set the value to false.
+ */
+export function isLspLanguageDisabled(lang, lspSettings) {
+    if (!lspSettings)
+        return false;
+    const key = SETTINGS_KEY_BY_LANG[lang];
+    return lspSettings[key] === false;
+}
+/**
+ * Probe every registered language server. Operator-facing helper for
+ * `pugi lsp servers` — returns one row per language with the binary
+ * name, whether it was found on PATH, and whether the settings toggle
+ * has explicitly disabled it.
+ */
+export function inspectLspServers(lspSettings) {
+    const out = [];
+    for (const lang of Object.keys(LANGUAGE_SERVERS)) {
+        const server = LANGUAGE_SERVERS[lang];
+        out.push({
+            language: lang,
+            command: server.command + (server.args.length > 0 ? ` ${server.args.join(' ')}` : ''),
+            available: detectBinary(server.probe),
+            enabled: !isLspLanguageDisabled(lang, lspSettings),
+        });
+    }
+    return out;
+}
 /**
  * Start an LSP client for the given language. Returns either an `LspClient`
  * ready to use, or a structured failure (`lsp_unavailable`,
  * `language_unsupported`).
+ *
+ * β7 L9: respects `.pugi/settings.json::lsp.<language> = false` —
+ * a disabled language reports `lsp_disabled` so the caller surface can
+ * tell the operator the binary IS available but settings says no.
  */
 export async function startLspClient(lang, opts) {
     const server = opts.serverOverride ?? LANGUAGE_SERVERS[lang];
@@ -479,6 +528,14 @@ export async function startLspClient(lang, opts) {
             detail: `no LSP server registered for language: ${lang}`,
         };
     }
+    if (!opts.serverOverride && isLspLanguageDisabled(lang, opts.lspSettings)) {
+        return {
+            ok: false,
+            reason: 'lsp_disabled',
+            detail: `${lang} is disabled in .pugi/settings.json::lsp.${SETTINGS_KEY_BY_LANG[lang]}. ` +
+                `Remove the override (or set it to true) to enable.`,
+        };
+    }
     if (!opts.serverOverride) {
         const available = detectBinary(server.probe);
         if (!available) {

package/dist/core/mcp/client.js

@@ -34,6 +34,15 @@ import { z } from 'zod';
  */
 export const mcpServerConfigSchema = z.object({
     command: z.string().min(1),
+    /**
+     * β4 r2 P1 #1 — operator's literal `command` argument as supplied to
+     * `pugi mcp install`. `command` above is now the RESOLVED absolute path
+     * we actually spawn. `originalCommand` is preserved for display/audit
+     * (`pugi mcp list`, audit logs) so operators can still see how they
+     * typed the install. Optional because pre-r2 mcp.json files do not
+     * carry the field — the loader treats absence as "use command directly".
+     */
+    originalCommand: z.string().min(1).optional(),
     args: z.array(z.string()).default([]),
     env: z.record(z.string()).default({}),
     /**