@pugi/cli 0.1.0-beta.31 → 0.1.0-beta.36

package/dist/runtime/commands/cancel.js

@@ -0,0 +1,231 @@
+/**
+ * `pugi /cancel` slash command — Wave 6 small-CC-parity batch (2026-05-27).
+ *
+ * Bridges the gap between `/jobs` (read-only list of in-flight agents)
+ * and `/stop <persona>` (kill-by-persona via admin-api). Cancel is
+ * dispatch-id-keyed — operators read `.pugi/agent-progress/*.json` for
+ * the active list, then run `/cancel <id>` (or `/cancel all`) to halt.
+ *
+ * Behaviour matrix:
+ *
+ *   /cancel                  → table of active dispatches (id · persona
+ *                              · started-at · elapsed · status)
+ *   /cancel <id>             → mark the progress JSON as failed (closest
+ *                              valid schema status to "cancelled" — the
+ *                              schema's closed status set is running/
+ *                              completed/failed) + best-effort POST to
+ *                              the future `/api/pugi/dispatches/:id/cancel`
+ *                              endpoint. If the endpoint 404s we still
+ *                              update the local JSON so /jobs reflects
+ *                              the operator's intent.
+ *   /cancel all              → loop over every running entry
+ *
+ * # Module contract
+ *
+ *   - Single entry point: `runCancelCommand(args, io, opts)`. The slash
+ *     dispatcher in `core/repl/session.ts` calls this with the parsed
+ *     verdict; a future `pugi cancel` shell surface would call it with
+ *     the same shape. Exit code semantics mirror `/feedback` — cancel
+ *     never returns non-zero from inside the REPL because the slash
+ *     surface ignores it; the shell wrapper can branch on the returned
+ *     result variant.
+ *
+ *   - No real network I/O is required for the unit test path. The
+ *     `fetcher` seam accepts a stub that resolves to `{ ok: false,
+ *     status: 404 }` so the spec exercises the local-fallback branch
+ *     deterministically.
+ *
+ *   - Filesystem reads are best-effort. A missing progress dir / a
+ *     malformed JSON file simply degrades to "no active dispatches"
+ *     rather than throwing — the cancel command is a brand surface,
+ *     never a gate.
+ *
+ *   - Wave 6 followup: a dedicated `/api/pugi/dispatches/:id/cancel`
+ *     endpoint on admin-api ships in a sibling PR. Until then, the
+ *     local progress JSON write is the source of truth so `/jobs`
+ *     and the live `pugi jobs --watch` TUI both reflect the operator
+ *     verdict instantly.
+ */
+import { existsSync, readFileSync, readdirSync, renameSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { resolveProgressDir, } from '../../core/agent-progress/writer.js';
+import { validateAgentProgress, } from '../../core/agent-progress/schema.js';
+/**
+ * Read every progress file under `dir` and return the running ones.
+ * Malformed entries are silently skipped — operator sees a smaller list
+ * rather than a crash banner.
+ */
+export function readActiveDispatches(dir) {
+    if (!existsSync(dir))
+        return [];
+    const out = [];
+    const files = readdirSync(dir).filter((f) => f.endsWith('.json'));
+    for (const file of files) {
+        try {
+            const body = readFileSync(join(dir, file), 'utf8');
+            const parsed = JSON.parse(body);
+            const verdict = validateAgentProgress(parsed);
+            if (verdict.ok && verdict.value.status === 'running') {
+                out.push(verdict.value);
+            }
+        }
+        catch {
+            // Skip malformed files; the watcher / writer is the source of
+            // truth, not the snapshot — a partial read on a half-written
+            // tmp file would otherwise crash the cancel surface.
+        }
+    }
+    // Newest-first so the operator's eye lands on the freshest agent.
+    return out.sort((a, b) => Date.parse(b.lastUpdate) - Date.parse(a.lastUpdate));
+}
+/**
+ * Atomic update: rewrite the progress JSON as `status='failed'`
+ * (closest valid status to "cancelled" in the closed schema set) with
+ * a marker step description so `/jobs` and the live TUI both display
+ * the cancellation. Returns the path on success; bubbles I/O errors.
+ *
+ * The write uses the same `<file>.tmp-<pid>-<seq>` → rename pattern as
+ * the writer module so a chokidar watcher never reads a half-written
+ * document. We do NOT import the writer's `writeProgress` because that
+ * helper validates and re-clamps every field, which would also reset
+ * fields the operator may want to inspect post-cancel (elapsedMs,
+ * percentComplete). Cancel preserves the snapshot and only swaps the
+ * status + stepDescription + lastUpdate.
+ */
+let writeSequence = 0;
+export function markCancelled(dir, agentId, nowIso) {
+    const path = join(dir, `${agentId}.json`);
+    const body = readFileSync(path, 'utf8');
+    const parsed = JSON.parse(body);
+    parsed.status = 'failed';
+    parsed.stepDescription = '(cancelled by /cancel)';
+    parsed.lastUpdate = nowIso;
+    writeSequence += 1;
+    const tmp = `${path}.tmp-${process.pid}-${writeSequence}`;
+    writeFileSync(tmp, `${JSON.stringify(parsed, null, 2)}\n`, 'utf8');
+    renameSync(tmp, path);
+    return path;
+}
+/**
+ * Render a single-line cancel snapshot row. Pure helper so the spec
+ * can pin the exact shape without standing up an Ink renderer.
+ */
+export function renderCancelRow(entry, nowEpochMs) {
+    const id = entry.agentId.length > 24
+        ? `${entry.agentId.slice(0, 23)}…`
+        : entry.agentId;
+    const persona = entry.agentType.length > 18
+        ? `${entry.agentType.slice(0, 17)}…`
+        : entry.agentType;
+    const startedMs = Date.parse(entry.startedAt);
+    const elapsedSec = Number.isFinite(startedMs)
+        ? Math.max(0, Math.floor((nowEpochMs - startedMs) / 1000))
+        : Math.max(0, Math.floor(entry.elapsedMs / 1000));
+    const elapsed = elapsedSec >= 60
+        ? `${Math.floor(elapsedSec / 60)}m${String(elapsedSec % 60).padStart(2, '0')}s`
+        : `${elapsedSec}s`;
+    return `  ${id.padEnd(24, ' ')}  ${persona.padEnd(18, ' ')}  ${elapsed.padStart(6, ' ')}  ${entry.status}`;
+}
+/**
+ * Main entry point. The slash dispatcher passes a tokenised
+ * `CancelMode`; the function returns a structured outcome so the
+ * caller can keep / drop the verdict line without re-parsing the I/O
+ * sink.
+ */
+export async function runCancelCommand(mode, io, opts = {}) {
+    const dir = opts.dir ?? resolveProgressDir();
+    const now = opts.now ?? Date.now;
+    const nowIso = new Date(now()).toISOString();
+    let active;
+    try {
+        active = readActiveDispatches(dir);
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        io.write(`/cancel failed reading progress dir: ${message}`);
+        return { kind: 'error', message };
+    }
+    if (mode.kind === 'list') {
+        if (active.length === 0) {
+            io.write('No active dispatches. Brief one with /brief <text>.');
+            return { kind: 'listed', count: 0 };
+        }
+        io.write(`Active dispatches (${active.length}):`);
+        io.write('  dispatch-id              persona             elapsed  status');
+        for (const entry of active) {
+            io.write(renderCancelRow(entry, now()));
+        }
+        io.write('Tip: /cancel <dispatch-id> to halt one, /cancel all к halt every running.');
+        return { kind: 'listed', count: active.length };
+    }
+    if (mode.kind === 'all') {
+        if (active.length === 0) {
+            io.write('Nothing к cancel — no active dispatches.');
+            return { kind: 'empty' };
+        }
+        const cancelled = [];
+        let endpointHit = false;
+        for (const entry of active) {
+            try {
+                if (opts.fetcher) {
+                    const verdict = await opts.fetcher(entry.agentId);
+                    if (verdict.ok)
+                        endpointHit = true;
+                }
+                markCancelled(dir, entry.agentId, nowIso);
+                cancelled.push(entry.agentId);
+                io.write(`Cancelled ${entry.agentId}`);
+            }
+            catch (err) {
+                const message = err instanceof Error ? err.message : String(err);
+                io.write(`  could not cancel ${entry.agentId}: ${message}`);
+            }
+        }
+        io.write(`Cancelled ${cancelled.length} of ${active.length} dispatch(es).`);
+        return { kind: 'cancelled', count: cancelled.length, ids: cancelled, endpointHit };
+    }
+    // kind === 'one'
+    const target = active.find((a) => a.agentId === mode.dispatchId);
+    if (!target) {
+        // Try prefix match — operators often type the first 8 chars.
+        const prefix = mode.dispatchId.toLowerCase();
+        const prefixMatch = active.find((a) => a.agentId.toLowerCase().startsWith(prefix));
+        if (!prefixMatch) {
+            io.write(`No active dispatch matching '${mode.dispatchId}'. Run /cancel to see the list.`);
+            return { kind: 'not-found', query: mode.dispatchId };
+        }
+        return cancelOne(prefixMatch, dir, nowIso, io, opts);
+    }
+    return cancelOne(target, dir, nowIso, io, opts);
+}
+async function cancelOne(entry, dir, nowIso, io, opts) {
+    let endpointHit = false;
+    if (opts.fetcher) {
+        try {
+            const verdict = await opts.fetcher(entry.agentId);
+            endpointHit = verdict.ok;
+        }
+        catch {
+            // network fail → fall through to local-only cancel
+        }
+    }
+    try {
+        markCancelled(dir, entry.agentId, nowIso);
+        io.write(`Cancelled dispatch ${entry.agentId}.`);
+        if (!endpointHit && opts.fetcher) {
+            io.write('  (backend cancel endpoint not reachable; progress JSON marked locally)');
+        }
+        return {
+            kind: 'cancelled',
+            count: 1,
+            ids: [entry.agentId],
+            endpointHit,
+        };
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        io.write(`/cancel ${entry.agentId} failed: ${message}`);
+        return { kind: 'error', message };
+    }
+}
+//# sourceMappingURL=cancel.js.map

package/dist/runtime/commands/codegraph-status.js

@@ -0,0 +1,227 @@
+/**
+ * `/codegraph-status` runner — Wave 6 BIG TRACK 9 Phase 2 (2026-05-27).
+ *
+ * Single source of truth for the codegraph adoption + index-freshness
+ * surface. Used by:
+ *
+ *   - REPL slash `/codegraph-status` (the discoverable surface)
+ *   - REPL slash `/codegraph`        (short alias)
+ *
+ * The runner is intentionally narrow — every information surface
+ * (installed? / index age / symbol count / last reindex / refresh CTA)
+ * is computed from the workspace-local `.pugi/codegraph-decision.json`
+ * + the live `.pugi/mcp.json` + the bounded scanner at
+ * `core/codegraph/detect-repo.ts`. NO network round-trip; everything
+ * runs offline so an air-gapped operator still gets the status table.
+ *
+ * Flags:
+ *   --install — merge codegraph into .pugi/mcp.json (accept decision)
+ *   --reindex — stamp lastIndexedAt now + hint operator к run
+ *               `codegraph index` from a fresh shell. Pugi does NOT
+ *               spawn codegraph itself (no upstream dep guarantee).
+ *   --offer   — surface the install prompt even after a decline,
+ *               useful when the operator declined three weeks ago and
+ *               wants to revisit без waiting for the 30-day cadence.
+ *
+ * Brand voice gate: ASCII output, no emoji, no decorative dividers.
+ */
+import { resolve } from 'node:path';
+import { detectRepo } from '../../core/codegraph/detect-repo.js';
+import { detectCodegraphInstalled, CODEGRAPH_DOCS_URL, } from '../../core/codegraph/install.js';
+import { readDecision, markIndexed, indexAgeDays, STALE_INDEX_DAYS, } from '../../core/codegraph/decision-store.js';
+import { evaluateOffer, applyOfferDecision, emitOfferShown, } from '../../core/codegraph/offer-hook.js';
+export function parseCodegraphStatusArgs(args) {
+    const out = {
+        install: false,
+        reindex: false,
+        offer: false,
+        unknown: null,
+    };
+    for (const arg of args) {
+        switch (arg) {
+            case '--install':
+            case '-i':
+                out.install = true;
+                break;
+            case '--reindex':
+            case '-r':
+                out.reindex = true;
+                break;
+            case '--offer':
+            case '-o':
+                out.offer = true;
+                break;
+            default:
+                out.unknown = arg;
+                return out;
+        }
+    }
+    return out;
+}
+/**
+ * Render the status table. Pure copy assembly — separates rendering
+ * from side effects so spec callers can pin the exact layout.
+ */
+export function renderStatusLines(input) {
+    const lines = ['Codegraph status:', ''];
+    lines.push(`  Installed:        ${input.installed ? 'yes' : 'no'}`);
+    if (input.installed) {
+        lines.push(`  Trust state:      ${input.trust ?? 'pending'}`);
+        lines.push(`  Config path:      ${input.configPath}`);
+    }
+    if (input.primarySymbolCount !== null) {
+        lines.push(`  Symbol count:     ~${input.primarySymbolCount} source files`);
+    }
+    if (input.languages && input.languages.length > 0) {
+        lines.push(`  Languages:        ${input.languages.join(', ')}`);
+    }
+    if (input.sizeCategory) {
+        lines.push(`  Size category:    ${input.sizeCategory}`);
+    }
+    if (input.installed) {
+        if (input.lastIndexedAt) {
+            lines.push(`  Last indexed:     ${input.lastIndexedAt}${input.ageDays !== null ? ` (${input.ageDays} day${input.ageDays === 1 ? '' : 's'} ago)` : ''}`);
+        }
+        else {
+            lines.push('  Last indexed:     never recorded — run `codegraph index` and `/codegraph-status --reindex`');
+        }
+        if (input.staleNudge) {
+            lines.push('');
+            lines.push(`  Index is ${input.ageDays} day${input.ageDays === 1 ? '' : 's'} old (threshold ${STALE_INDEX_DAYS}). ` +
+                'Run `codegraph index` then `/codegraph-status --reindex` to refresh.');
+        }
+    }
+    else {
+        lines.push('');
+        lines.push(`  Docs: ${CODEGRAPH_DOCS_URL}`);
+        lines.push('  Install via `/codegraph-status --install` OR `pugi mcp install codegraph codegraph serve --mcp`.');
+    }
+    return lines;
+}
+/**
+ * Single entry-point used by the slash dispatch + (future) standalone
+ * `pugi codegraph status` shell command. Pure orchestration — every
+ * side effect lives behind one of the flag branches.
+ */
+export async function runCodegraphStatusCommand(args, ctx) {
+    const flags = parseCodegraphStatusArgs(args);
+    if (flags.unknown) {
+        ctx.writeOutput({ command: 'codegraph-status', error: 'unknown-flag', flag: flags.unknown }, `/codegraph-status: unknown flag "${flags.unknown}". Allowed: --install, --reindex, --offer.`);
+        return;
+    }
+    const workspaceRoot = resolve(ctx.workspaceRoot);
+    // --reindex — stamp lastIndexedAt + remind the operator how to actually
+    // refresh the index. We do NOT spawn `codegraph index` — that is the
+    // operator's call (upstream codegraph may or may not be installed; we
+    // refuse to silently spawn a binary we did not vet).
+    if (flags.reindex) {
+        const decision = markIndexed(workspaceRoot);
+        if (!decision) {
+            ctx.writeOutput({ command: 'codegraph-status', error: 'no-decision' }, '/codegraph-status --reindex: no decision recorded yet. Accept the install first via `--install`.');
+            return;
+        }
+        ctx.writeOutput({ command: 'codegraph-status', reindexed: true, lastIndexedAt: decision.lastIndexedAt }, [
+            `Codegraph index timestamp updated to ${decision.lastIndexedAt}.`,
+            'Run `codegraph index` from a fresh shell to actually rebuild the SQLite cache.',
+        ].join('\n'));
+        return;
+    }
+    // --install / --offer — surface the install prompt OR accept it
+    // directly. `--install` skips the prompt + writes the entry; `--offer`
+    // renders the prompt copy even after a decline (operator-initiated
+    // revisit). The two are mutually exclusive at runtime — `--install`
+    // wins when both are set.
+    if (flags.install || flags.offer) {
+        const evaluation = evaluateOffer({
+            workspaceRoot,
+            ...(ctx.nowIso ? { nowIso: ctx.nowIso } : {}),
+            ignorePriorDecision: flags.offer,
+        });
+        if (!evaluation.shouldPrompt) {
+            const detection = detectRepo(workspaceRoot);
+            // Already-installed is the success path for `--install`; treat
+            // it as PASS rather than ERROR so a re-run is idempotent.
+            if (evaluation.reason === 'already-installed') {
+                ctx.writeOutput({ command: 'codegraph-status', alreadyInstalled: true }, 'Codegraph is already declared in .pugi/mcp.json. Run `pugi mcp trust codegraph` if not yet trusted.');
+                return;
+            }
+            ctx.writeOutput({ command: 'codegraph-status', skipped: true, reason: evaluation.reason }, `/codegraph-status --${flags.install ? 'install' : 'offer'}: nothing to do (${evaluation.reason}).` +
+                (detection.isRepo
+                    ? ` Repo: ${detection.sizeCategory}, ${detection.primarySymbolCount} src files.`
+                    : ''));
+            return;
+        }
+        if (flags.install) {
+            const result = applyOfferDecision({
+                workspaceRoot,
+                accepted: true,
+                detection: evaluation.detection,
+                ...(ctx.nowIso ? { nowIso: ctx.nowIso } : {}),
+            });
+            if (result.kind === 'declined') {
+                // Defensive — applyOfferDecision with accepted=true cannot
+                // surface a `declined` verdict by construction. We still
+                // narrow the union so TS understands the safe path below.
+                ctx.writeOutput({ command: 'codegraph-status', installFailed: true, reason: 'unexpected-decline' }, '/codegraph-status --install: install path returned a decline verdict (internal bug).');
+                return;
+            }
+            if (result.kind === 'accepted-install-failed') {
+                ctx.writeOutput({ command: 'codegraph-status', installFailed: true, reason: result.install.reason }, `/codegraph-status --install failed: ${result.install.reason}`);
+                return;
+            }
+            ctx.writeOutput({
+                command: 'codegraph-status',
+                installed: true,
+                configPath: result.install.status === 'installed' ? result.install.configPath : null,
+                docsUrl: result.docsUrl,
+                trustCommand: result.trustCommand,
+            }, [
+                result.install.status === 'installed'
+                    ? `Codegraph added к .pugi/mcp.json. Trust gate: ${result.trustCommand}`
+                    : 'Codegraph already declared. Trust gate: ' + result.trustCommand,
+                `Docs: ${result.docsUrl}`,
+            ].join('\n'));
+            return;
+        }
+        // --offer path — surface the copy but do not install yet
+        emitOfferShown(evaluation.detection);
+        ctx.writeOutput({
+            command: 'codegraph-status',
+            offered: true,
+            copy: evaluation.promptCopy,
+            docsUrl: evaluation.docsUrl,
+        }, [
+            evaluation.promptCopy,
+            `Docs: ${evaluation.docsUrl}`,
+            'Accept: /codegraph-status --install',
+            'Decline: do nothing (the prompt re-appears in 30 days).',
+        ].join('\n'));
+        return;
+    }
+    // Bare invocation — render the status table.
+    const installed = detectCodegraphInstalled(workspaceRoot);
+    const detection = detectRepo(workspaceRoot);
+    const decision = readDecision(workspaceRoot);
+    const ageDays = decision ? indexAgeDays(decision, ctx.nowIso) : null;
+    const lines = renderStatusLines({
+        installed: installed.installed,
+        trust: installed.trust,
+        configPath: installed.configPath,
+        ageDays,
+        primarySymbolCount: detection.isRepo ? detection.primarySymbolCount : null,
+        languages: detection.isRepo ? detection.languages : null,
+        sizeCategory: detection.isRepo ? detection.sizeCategory : null,
+        lastIndexedAt: decision?.lastIndexedAt ?? null,
+        staleNudge: ageDays !== null && ageDays >= STALE_INDEX_DAYS,
+    });
+    ctx.writeOutput({
+        command: 'codegraph-status',
+        installed: installed.installed,
+        trust: installed.trust,
+        configPath: installed.configPath,
+        detection,
+        decision,
+        ageDays,
+    }, lines.join('\n'));
+}
+//# sourceMappingURL=codegraph-status.js.map

package/dist/runtime/commands/mcp.js

@@ -10,7 +10,9 @@ import { loadMcpRegistry, mcpLogPath } from '../../core/mcp/registry.js';
 import { listMcpTrust, setMcpTrust } from '../../core/mcp/trust.js';
 import { createPugiMcpServer, serveStdio } from '../../core/mcp/server.js';
 import { buildPugiMcpTools } from '../../core/mcp/server-tools.js';
+import { buildOrchestratorTools } from '../../core/mcp/orchestrator-tools.js';
 import { serveHttp } from '../../core/mcp/http-server.js';
+import { resolveActiveCredential, DEFAULT_API_URL } from '../../core/credentials.js';
 import { listMcpPermissions, clearMcpPermission, } from '../../core/mcp/permission.js';
 export async function runMcpCommand(args, ctx) {
     const sub = args[0] ?? 'list';
@@ -74,6 +76,15 @@ const USAGE_LINES = [
     '    --allow-write               Expose edit/write (default off — explicit opt-in).',
     '    --allow-bash                Expose the bash tool (default off — explicit opt-in).',
     '    --no-bash                   Deprecated alias (bash is already off by default).',
+    '    --orchestrator              Expose pugi.run / pugi.read / pugi.write /',
+    '                                pugi.dispatch / pugi.publish / pugi.deploy instead of',
+    '                                the engine surface. Designed for external Claude Code',
+    '                                / Cursor sessions driving fix-publish-test loops.',
+    '                                Each tool family is gated by an env switch:',
+    '                                  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_MCP_WORKSPACE_ROOT=... overrides cwd for path validation',
     '  perms list                    Show cached per-(server, tool) decisions',
     '  perms reset <server>:<tool>   Forget one cached decision',
 ];
@@ -536,16 +547,23 @@ async function runMcpServe(args, ctx) {
     const readOnly = flags.readOnly === true;
     const writeAllowed = !readOnly && flags.writeAllowed;
     const bashAllowed = !readOnly && flags.bashAllowed;
-    const tools = buildPugiMcpTools(toolCtx, {
-        bashAllowed,
-        // Keep the legacy contract: `readOnly` for the tool-builder means
-        // "do not advertise edit/write tools". Bash advertisement is gated
-        // by the independent `bashAllowed` knob. So the builder sees
-        // `readOnly = true` whenever the operator did not opt into write
-        // explicitly, which preserves the deny-by-default surface for
-        // edit/write but no longer accidentally suppresses bash.
-        readOnly: readOnly || !writeAllowed,
-    });
+    // Wave 7 P1 — when `--orchestrator` is set the surface swaps to the
+    // CLI-orchestrator family (pugi.run / pugi.read / pugi.write /
+    // pugi.dispatch / pugi.publish / pugi.deploy). The engine surface is
+    // intentionally dropped — the two are mutually exclusive on the wire
+    // to keep tool-name resolution unambiguous on the consumer side.
+    const tools = flags.orchestrator
+        ? buildOrchestratorTools(buildOrchestratorContext(ctx.workspaceRoot))
+        : buildPugiMcpTools(toolCtx, {
+            bashAllowed,
+            // Keep the legacy contract: `readOnly` for the tool-builder means
+            // "do not advertise edit/write tools". Bash advertisement is gated
+            // by the independent `bashAllowed` knob. So the builder sees
+            // `readOnly = true` whenever the operator did not opt into write
+            // explicitly, which preserves the deny-by-default surface for
+            // edit/write but no longer accidentally suppresses bash.
+            readOnly: readOnly || !writeAllowed,
+        });
     // β4 r1 P1 #2 — deny-by-default permissionGate. The MCP cache + FSM
     // are consulted on every dispatch; allow_always-cached entries pass
     // silently, allow_once entries pass and self-clear, deny entries
@@ -604,6 +622,7 @@ async function runMcpServe(args, ctx) {
             command: 'mcp.serve',
             transport: 'http',
             url: handle.url,
+            surface: flags.orchestrator ? 'orchestrator' : 'engine',
             bearerTokenSource: handle.bearerTokenAutoGenerated
                 ? 'auto-generated (see stderr)'
                 : explicitToken === envToken
@@ -649,7 +668,7 @@ async function runMcpServe(args, ctx) {
     // the wire; nothing is printed unless the parent agent sends a
     // request that returns a response. Operator sees one info line on
     // stderr so they know the server is up.
-    process.stderr.write(`pugi-mcp (stdio): ${tools.length} tool(s) — ${tools.map((t) => t.name).join(', ')}\n`);
+    process.stderr.write(`pugi-mcp (stdio, ${flags.orchestrator ? 'orchestrator' : 'engine'}): ${tools.length} tool(s) — ${tools.map((t) => t.name).join(', ')}\n`);
     await serveStdio({
         server,
         stdin: ctx.stdin ?? process.stdin,
@@ -665,6 +684,7 @@ function parseServeFlags(args) {
         readOnly: false,
         writeAllowed: false,
         bashAllowed: false,
+        orchestrator: false,
     };
     for (let i = 0; i < args.length; i += 1) {
         const arg = args[i] ?? '';
@@ -722,6 +742,9 @@ function parseServeFlags(args) {
             // so existing operator scripts do not error.
             flags.bashAllowed = false;
         }
+        else if (arg === '--orchestrator') {
+            flags.orchestrator = true;
+        }
         else if (arg === '--help') {
             // Caller renders USAGE_LINES. We surface the same via top-level
             // dispatch — nothing to do here, just don't error.
@@ -755,9 +778,41 @@ function buildServePermissionGate(opts) {
             return false;
         if (tool.permission === 'edit' && !opts.writeAllowed)
             return false;
+        // `network` is the permission class used by orchestrator tools
+        // (pugi.dispatch / pugi.publish / pugi.deploy). The env capability
+        // gates inside each tool's `execute` body provide the per-family
+        // kill switch, so the serve-time gate is permissive here. The
+        // server's overall `permissionGate` is already deny-most-other —
+        // adding a third boolean knob (`networkAllowed`) would create more
+        // ways to misconfigure than to protect. Wave 7 P1 (2026-05-28).
         return true;
     };
 }
+/**
+ * Build the OrchestratorToolContext for `pugi mcp serve --orchestrator`.
+ * Reads from process.env + the credentials store. Encapsulated so tests
+ * never need to mock the resolveActiveCredential path — they call
+ * `buildOrchestratorTools` directly with a hand-rolled context.
+ *
+ * Wave 7 P1 (2026-05-28).
+ */
+function buildOrchestratorContext(workspaceRoot) {
+    const envRoot = process.env.PUGI_MCP_WORKSPACE_ROOT;
+    const root = envRoot && envRoot.length > 0 ? resolve(envRoot) : workspaceRoot;
+    const credential = resolveActiveCredential();
+    return {
+        workspaceRoot: root,
+        pugiBin: process.env.PUGI_MCP_PUGI_BIN ?? 'pugi',
+        apiUrl: credential?.apiUrl ?? DEFAULT_API_URL,
+        apiKey: credential?.apiKey ?? null,
+        capabilities: {
+            exec: process.env.PUGI_MCP_EXEC_ENABLED === '1',
+            publish: process.env.PUGI_MCP_PUBLISH_ENABLED === '1',
+            deploy: process.env.PUGI_MCP_DEPLOY_ENABLED === '1',
+        },
+        sshAlias: process.env.PUGI_MCP_SSH_ALIAS ?? 'codeforge',
+    };
+}
 function parseHttpBinding(input) {
     // Accept `:7100`, `7100`, or `host:7100`.
     let host = '127.0.0.1';

package/dist/runtime/commands/permissions.js

@@ -84,4 +84,27 @@ function renderModeTable(ctx) {
 export function renderBypassBanner(writeOutput) {
     writeOutput('BYPASS MODE — all tools execute without prompts AND policy hooks disabled. Switch back with /permissions allow.');
 }
+/**
+ * Resolve the effective mode + the layered source label used by the
+ * Ink picker. Shares the merge order with `renderCurrentMode` above so
+ * the picker title and the bare `/permissions` print stay in lock-step.
+ *
+ * Exposed publicly because the host (session.ts) needs the same merge
+ * shape to seed the Ink picker BEFORE it mounts.
+ */
+export function resolveLayeredMode(workspaceRoot, homeDir) {
+    const workspace = getCurrentMode(workspaceRoot);
+    const global = getGlobalDefaultMode(homeDir);
+    const effective = workspace ?? global ?? DEFAULT_PERMISSION_MODE;
+    const source = workspace
+        ? 'workspace session.json'
+        : global
+            ? 'global ~/.pugi/config.json'
+            : 'default (no override)';
+    return {
+        effective,
+        source,
+        firstRun: !workspace && !global,
+    };
+}
 //# sourceMappingURL=permissions.js.map