arceus-s 1.6.4

package/dist/mcp/server.js

@@ -0,0 +1,314 @@
+/**
+ * MCP Server (Multi-Repo)
+ *
+ * Model Context Protocol server that runs on stdio.
+ * External AI tools (Cursor, Claude) spawn this process and
+ * communicate via stdin/stdout using the MCP protocol.
+ *
+ * Supports multiple indexed repositories via the global registry.
+ *
+ * Tools: list_repos, query, cypher, context, impact, detect_changes, rename
+ * Resources: repos, repo/{name}/context, repo/{name}/clusters, ...
+ */
+import { createRequire } from 'module';
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { CompatibleStdioServerTransport } from './compatible-stdio-transport.js';
+import { CallToolRequestSchema, ListToolsRequestSchema, ListResourcesRequestSchema, ReadResourceRequestSchema, ListResourceTemplatesRequestSchema, ListPromptsRequestSchema, GetPromptRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
+import { ARC_TOOLS } from './tools.js';
+import { installGlobalStdoutSentinel } from './stdio-context.js';
+import { getResourceDefinitions, getResourceTemplates, readResource } from './resources.js';
+/**
+ * Next-step hints appended to tool responses.
+ *
+ * Agents often stop after one tool call. These hints guide them to the
+ * logical next action, creating a self-guiding workflow without hooks.
+ *
+ * Design: Each hint is a short, actionable instruction (not a suggestion).
+ * The hint references the specific tool/resource to use next.
+ */
+function getNextStepHint(toolName, args) {
+    const repo = args?.repo;
+    const repoParam = repo ? `, repo: "${repo}"` : '';
+    const repoPath = repo || '{name}';
+    switch (toolName) {
+        case 'list_repos':
+            return `\n\n---\n**Next:** READ arc://repo/{name}/context for any repo above to get its overview and check staleness.`;
+        case 'query':
+            return `\n\n---\n**Next:** To understand a specific symbol in depth, use context({name: "<symbol_name>"${repoParam}}) to see categorized refs and process participation.`;
+        case 'context':
+            return `\n\n---\n**Next:** If planning changes, use impact({target: "${args?.name || '<name>'}", direction: "upstream"${repoParam}}) to check blast radius. To see execution flows, READ arc://repo/${repoPath}/processes.`;
+        case 'impact':
+            return `\n\n---\n**Next:** Review d=1 items first (WILL BREAK). To check affected execution flows, READ arc://repo/${repoPath}/processes.`;
+        case 'detect_changes':
+            return `\n\n---\n**Next:** Review affected processes. Use context() on high-risk changed symbols. READ arc://repo/${repoPath}/process/{name} for full execution traces.`;
+        case 'rename':
+            return `\n\n---\n**Next:** Run detect_changes(${repoParam ? `{repo: "${repo}"}` : ''}) to verify no unexpected side effects from the rename.`;
+        case 'cypher':
+            return `\n\n---\n**Next:** To explore a result symbol, use context({name: "<name>"${repoParam}}). For schema reference, READ arc://repo/${repoPath}/schema.`;
+        // Legacy tool names — still return useful hints
+        case 'search':
+            return `\n\n---\n**Next:** To understand a result in context, use context({name: "<symbol_name>"${repoParam}}).`;
+        case 'explore':
+            return `\n\n---\n**Next:** If planning changes, use impact({target: "<name>", direction: "upstream"${repoParam}}).`;
+        case 'overview':
+            return `\n\n---\n**Next:** To drill into an area, READ arc://repo/${repoPath}/cluster/{name}. To see execution flows, READ arc://repo/${repoPath}/processes.`;
+        default:
+            return '';
+    }
+}
+/**
+ * Create a configured MCP Server with all handlers registered.
+ * Transport-agnostic — caller connects the desired transport.
+ */
+export function createMCPServer(backend) {
+    const require = createRequire(import.meta.url);
+    const pkgVersion = require('../../package.json').version;
+    const server = new Server({
+        name: 'arc',
+        version: pkgVersion,
+    }, {
+        capabilities: {
+            tools: {},
+            resources: {},
+            prompts: {},
+        },
+    });
+    // Handle list resources request
+    server.setRequestHandler(ListResourcesRequestSchema, async () => {
+        const resources = getResourceDefinitions();
+        return {
+            resources: resources.map((r) => ({
+                uri: r.uri,
+                name: r.name,
+                description: r.description,
+                mimeType: r.mimeType,
+            })),
+        };
+    });
+    // Handle list resource templates request (for dynamic resources)
+    server.setRequestHandler(ListResourceTemplatesRequestSchema, async () => {
+        const templates = getResourceTemplates();
+        return {
+            resourceTemplates: templates.map((t) => ({
+                uriTemplate: t.uriTemplate,
+                name: t.name,
+                description: t.description,
+                mimeType: t.mimeType,
+            })),
+        };
+    });
+    // Handle read resource request
+    server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
+        const { uri } = request.params;
+        try {
+            const content = await readResource(uri, backend);
+            return {
+                contents: [
+                    {
+                        uri,
+                        mimeType: 'text/yaml',
+                        text: content,
+                    },
+                ],
+            };
+        }
+        catch (err) {
+            return {
+                contents: [
+                    {
+                        uri,
+                        mimeType: 'text/plain',
+                        text: `Error: ${err.message}`,
+                    },
+                ],
+            };
+        }
+    });
+    // Handle list tools request
+    server.setRequestHandler(ListToolsRequestSchema, async () => ({
+        tools: ARC_TOOLS.map((tool) => ({
+            name: tool.name,
+            description: tool.description,
+            inputSchema: tool.inputSchema,
+            annotations: tool.annotations,
+        })),
+    }));
+    // Handle tool calls — append next-step hints to guide agent workflow
+    server.setRequestHandler(CallToolRequestSchema, async (request) => {
+        const { name, arguments: args } = request.params;
+        try {
+            const result = await backend.callTool(name, args);
+            const resultText = typeof result === 'string' ? result : JSON.stringify(result, null, 2);
+            const hint = getNextStepHint(name, args);
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: resultText + hint,
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : 'Unknown error';
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `Error: ${message}`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+    });
+    // Handle list prompts request
+    server.setRequestHandler(ListPromptsRequestSchema, async () => ({
+        prompts: [
+            {
+                name: 'detect_impact',
+                description: 'Analyze the impact of your current changes before committing. Guides through scope selection, change detection, process analysis, and risk assessment.',
+                arguments: [
+                    {
+                        name: 'scope',
+                        description: 'What to analyze: unstaged, staged, all, or compare',
+                        required: false,
+                    },
+                    { name: 'base_ref', description: 'Branch/commit for compare scope', required: false },
+                ],
+            },
+            {
+                name: 'generate_map',
+                description: 'Generate architecture documentation from the knowledge graph. Creates a codebase overview with execution flows and mermaid diagrams.',
+                arguments: [
+                    {
+                        name: 'repo',
+                        description: 'Repository name (omit if only one indexed)',
+                        required: false,
+                    },
+                ],
+            },
+        ],
+    }));
+    // Handle get prompt request
+    server.setRequestHandler(GetPromptRequestSchema, async (request) => {
+        const { name, arguments: args } = request.params;
+        if (name === 'detect_impact') {
+            const scope = args?.scope || 'all';
+            const baseRef = args?.base_ref || '';
+            return {
+                messages: [
+                    {
+                        role: 'user',
+                        content: {
+                            type: 'text',
+                            text: `Analyze the impact of my current code changes before committing.
+
+Follow these steps:
+1. Run \`detect_changes(${JSON.stringify({ scope, ...(baseRef ? { base_ref: baseRef } : {}) })})\` to find what changed and affected processes
+2. For each changed symbol in critical processes, run \`context({name: "<symbol>"})\` to see its full reference graph
+3. For any high-risk items (many callers or cross-process), run \`impact({target: "<symbol>", direction: "upstream"})\` for blast radius
+4. Summarize: changes, affected processes, risk level, and recommended actions
+
+Present the analysis as a clear risk report.`,
+                        },
+                    },
+                ],
+            };
+        }
+        if (name === 'generate_map') {
+            const repo = args?.repo || '';
+            return {
+                messages: [
+                    {
+                        role: 'user',
+                        content: {
+                            type: 'text',
+                            text: `Generate architecture documentation for this codebase using the knowledge graph.
+
+Follow these steps:
+1. READ \`arc://repo/${repo || '{name}'}/context\` for codebase stats
+2. READ \`arc://repo/${repo || '{name}'}/clusters\` to see all functional areas
+3. READ \`arc://repo/${repo || '{name}'}/processes\` to see all execution flows
+4. For the top 5 most important processes, READ \`arc://repo/${repo || '{name}'}/process/{name}\` for step-by-step traces
+5. Generate a mermaid architecture diagram showing the major areas and their connections
+6. Write an ARCHITECTURE.md file with: overview, functional areas, key execution flows, and the mermaid diagram`,
+                        },
+                    },
+                ],
+            };
+        }
+        throw new Error(`Unknown prompt: ${name}`);
+    });
+    return server;
+}
+/**
+ * Start the MCP server on stdio transport (for CLI use).
+ */
+export async function startMCPServer(backend) {
+    const server = createMCPServer(backend);
+    // Idempotent global sentinel install. cli/mcp.ts calls this first thing
+    // (before warnMissingOptionalGrammars / backend.init can emit to stdout);
+    // calling again here is a safety net for direct callers of startMCPServer
+    // (tests, future entry points). The transport's _safeStdout Proxy is a
+    // second layer that guarantees transport writes reach the sentinel even
+    // if anything else re-replaces process.stdout.write later. Tagged
+    // transport writes (wrapped in withMcpWrite by compatible-stdio-transport.send)
+    // pass through to the captured realStdoutWrite; untagged writes reaching
+    // the Proxy or process.stdout get redirected to stderr with the
+    // [mcp:stdout-redirect] prefix. See stdio-context.ts.
+    const sentinel = installGlobalStdoutSentinel();
+    const safeStdout = new Proxy(process.stdout, {
+        get(target, prop, receiver) {
+            if (prop === 'write')
+                return sentinel.write;
+            const val = Reflect.get(target, prop, receiver);
+            return typeof val === 'function' ? val.bind(target) : val;
+        },
+    });
+    const transport = new CompatibleStdioServerTransport(process.stdin, safeStdout);
+    await server.connect(transport);
+    // Surface the redirect counter on shutdown so users see the volume of
+    // stray writes even when individual payloads were truncated/suppressed.
+    process.on('exit', () => sentinel.flushSummary());
+    // Graceful shutdown helper. Pino's default destination is `sync: false`
+    // (buffered), so we must `flushLoggerSync()` before `process.exit` —
+    // otherwise records emitted during disconnect/close are lost. The flush
+    // is a no-op when the singleton was never used or when running under
+    // vitest. See `arc/src/core/logger.ts`.
+    let shuttingDown = false;
+    const shutdown = async (exitCode = 0) => {
+        if (shuttingDown)
+            return;
+        shuttingDown = true;
+        try {
+            await backend.disconnect();
+        }
+        catch { }
+        try {
+            await server.close();
+        }
+        catch { }
+        const { flushLoggerSync } = await import('../core/logger.js');
+        flushLoggerSync();
+        process.exit(exitCode);
+    };
+    // Handle graceful shutdown
+    process.on('SIGINT', shutdown);
+    process.on('SIGTERM', shutdown);
+    // Log crashes to stderr so they aren't silently lost.
+    // uncaughtException is fatal — shut down.
+    // unhandledRejection is logged but kept non-fatal (availability-first):
+    // killing the server for one missed catch would be worse than logging it.
+    process.on('uncaughtException', (err) => {
+        process.stderr.write(`Arceus MCP uncaughtException: ${err?.stack || err}\n`);
+        shutdown(1);
+    });
+    process.on('unhandledRejection', (reason) => {
+        process.stderr.write(`Arceus MCP unhandledRejection: ${reason?.stack || reason}\n`);
+    });
+    // Handle stdio errors — stdin close means the parent process is gone
+    process.stdin.on('end', shutdown);
+    process.stdin.on('error', () => shutdown());
+    process.stdout.on('error', () => shutdown());
+}

package/dist/mcp/staleness.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Staleness Check — re-export from core (see `core/git-staleness.ts`).
+ */
+export type { StalenessInfo } from '../core/git-staleness.js';
+export { checkStaleness } from '../core/git-staleness.js';

package/dist/mcp/staleness.js

@@ -0,0 +1,4 @@
+/**
+ * Staleness Check — re-export from core (see `core/git-staleness.ts`).
+ */
+export { checkStaleness } from '../core/git-staleness.js';

package/dist/mcp/stdio-capture.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Stdio capture — leaf module with zero non-`node:` imports.
+ *
+ * Owns the singleton state that the MCP stdout sentinel needs:
+ *   - `realStdoutWrite` / `realStderrWrite`: process.stdout.write /
+ *     process.stderr.write captured at module load, BEFORE anything else
+ *     can rebind them.
+ *   - `activeStdoutWrite`: the write handler that silenceStdout/restoreStdout
+ *     cycles in pool-adapter restore to. Defaults to `realStdoutWrite`;
+ *     `installGlobalStdoutSentinel` (in stdio-context.ts) registers the
+ *     sentinel here at MCP startup so silence/restore preserves the sentinel.
+ *
+ * This module exists separately from `pool-adapter.ts` (which previously
+ * owned the same state) so that `cli/mcp.ts`'s static-import closure does
+ * NOT transitively pull in `@ladybugdb/core`. Codex's adversarial review on
+ * PR #1383 found that the prior structure left a pre-sentinel window where
+ * native-module init banners could reach raw stdout: `cli/mcp.ts` →
+ * `mcp/stdio-context.ts` → `core/lbug/pool-adapter.ts` → `@ladybugdb/core`.
+ * Routing the sentinel state through this leaf module breaks that chain.
+ *
+ * **Constraint:** keep this module a leaf. No non-`node:` imports — adding
+ * any would re-introduce the import-time stdout-corruption hazard.
+ */
+type StdoutWrite = typeof process.stdout.write;
+/** Captured at module load, before any rebinding. */
+export declare const realStdoutWrite: StdoutWrite;
+export declare const realStderrWrite: typeof process.stderr.write;
+/**
+ * Register a wrapper (e.g., the MCP sentinel) as the active stdout write.
+ * silenceStdout/restoreStdout cycles in pool-adapter will preserve the
+ * wrapper instead of unwinding to the raw realStdoutWrite. Returns the
+ * previous value so callers can chain or restore.
+ */
+export declare function setActiveStdoutWrite(fn: StdoutWrite): StdoutWrite;
+/**
+ * Read the currently-active stdout write handler. Used by pool-adapter's
+ * restoreStdout and watchdog so silence/restore preserves the sentinel.
+ */
+export declare function getActiveStdoutWrite(): StdoutWrite;
+export {};

package/dist/mcp/stdio-capture.js

@@ -0,0 +1,53 @@
+/**
+ * Stdio capture — leaf module with zero non-`node:` imports.
+ *
+ * Owns the singleton state that the MCP stdout sentinel needs:
+ *   - `realStdoutWrite` / `realStderrWrite`: process.stdout.write /
+ *     process.stderr.write captured at module load, BEFORE anything else
+ *     can rebind them.
+ *   - `activeStdoutWrite`: the write handler that silenceStdout/restoreStdout
+ *     cycles in pool-adapter restore to. Defaults to `realStdoutWrite`;
+ *     `installGlobalStdoutSentinel` (in stdio-context.ts) registers the
+ *     sentinel here at MCP startup so silence/restore preserves the sentinel.
+ *
+ * This module exists separately from `pool-adapter.ts` (which previously
+ * owned the same state) so that `cli/mcp.ts`'s static-import closure does
+ * NOT transitively pull in `@ladybugdb/core`. Codex's adversarial review on
+ * PR #1383 found that the prior structure left a pre-sentinel window where
+ * native-module init banners could reach raw stdout: `cli/mcp.ts` →
+ * `mcp/stdio-context.ts` → `core/lbug/pool-adapter.ts` → `@ladybugdb/core`.
+ * Routing the sentinel state through this leaf module breaks that chain.
+ *
+ * **Constraint:** keep this module a leaf. No non-`node:` imports — adding
+ * any would re-introduce the import-time stdout-corruption hazard.
+ */
+/** Captured at module load, before any rebinding. */
+// eslint-disable-next-line no-restricted-syntax -- this IS the captured-real-write infrastructure used by the MCP sentinel
+export const realStdoutWrite = process.stdout.write.bind(process.stdout);
+export const realStderrWrite = process.stderr.write.bind(process.stderr);
+/**
+ * The function `restoreStdout` (and the watchdog) in pool-adapter restore
+ * *to* when un-silencing. Defaults to the captured real write; the MCP
+ * server registers its sentinel here at startMCPServer (via
+ * installGlobalStdoutSentinel) so silenceStdout cycles preserve the sentinel
+ * instead of unwinding to raw stdout.
+ */
+let activeStdoutWrite = realStdoutWrite;
+/**
+ * Register a wrapper (e.g., the MCP sentinel) as the active stdout write.
+ * silenceStdout/restoreStdout cycles in pool-adapter will preserve the
+ * wrapper instead of unwinding to the raw realStdoutWrite. Returns the
+ * previous value so callers can chain or restore.
+ */
+export function setActiveStdoutWrite(fn) {
+    const prev = activeStdoutWrite;
+    activeStdoutWrite = fn;
+    return prev;
+}
+/**
+ * Read the currently-active stdout write handler. Used by pool-adapter's
+ * restoreStdout and watchdog so silence/restore preserves the sentinel.
+ */
+export function getActiveStdoutWrite() {
+    return activeStdoutWrite;
+}

package/dist/mcp/stdio-context.d.ts

@@ -0,0 +1,47 @@
+/**
+ * MCP Stdio Context — AsyncLocalStorage-tagged transport-write detection.
+ *
+ * The MCP stdio transport writes JSON-RPC frames to stdout. Per spec, the
+ * server MUST NOT write anything to stdout that is not a valid MCP message.
+ * Stray writes from dependency code corrupt the protocol and present to
+ * clients as a hung handshake or `MCP error -32000`.
+ *
+ * This module provides:
+ *   - withMcpWrite(fn): runs fn inside an AsyncLocalStorage context tagged
+ *     `mcp: true`. The transport wraps every send() in this so its writes
+ *     are recognizable as legitimate.
+ *   - isMcpWrite(): true when called inside withMcpWrite.
+ *   - createStdoutSentinel({...}): a write function suitable for installing
+ *     in a Proxy over process.stdout. Tagged writes pass through to the real
+ *     stdout; untagged writes are redirected to stderr with a [mcp:stdout-redirect]
+ *     prefix, truncated to maxBytes per redirect, and rate-limited to maxRedirects
+ *     per process so a stray loop cannot flood client logs.
+ *
+ * The sentinel is correctness-by-construction: it identifies legitimate
+ * writes by *who* called write(), not by inspecting the bytes. A byte-shape
+ * heuristic ("starts with {, ends with \n") would falsely reject Content-Length
+ * frames (which start with C and end with }) and misclassify multi-chunk writes.
+ */
+export declare function withMcpWrite<T>(fn: () => T): T;
+export declare function isMcpWrite(): boolean;
+type WriteFn = typeof process.stdout.write;
+export interface SentinelOptions {
+    realStdoutWrite: WriteFn;
+    realStderrWrite: WriteFn;
+    /** Maximum bytes of payload to surface per redirect. Defaults to 200. */
+    maxBytes?: number;
+    /** Maximum number of redirects per process before suppression. Defaults to 10. */
+    maxRedirects?: number;
+}
+export interface SentinelStats {
+    redirected: number;
+    suppressed: number;
+}
+export interface Sentinel {
+    write: WriteFn;
+    stats: () => SentinelStats;
+    flushSummary: () => void;
+}
+export declare function createStdoutSentinel(opts: SentinelOptions): Sentinel;
+export declare function installGlobalStdoutSentinel(): Sentinel;
+export {};

package/dist/mcp/stdio-context.js

@@ -0,0 +1,145 @@
+/**
+ * MCP Stdio Context — AsyncLocalStorage-tagged transport-write detection.
+ *
+ * The MCP stdio transport writes JSON-RPC frames to stdout. Per spec, the
+ * server MUST NOT write anything to stdout that is not a valid MCP message.
+ * Stray writes from dependency code corrupt the protocol and present to
+ * clients as a hung handshake or `MCP error -32000`.
+ *
+ * This module provides:
+ *   - withMcpWrite(fn): runs fn inside an AsyncLocalStorage context tagged
+ *     `mcp: true`. The transport wraps every send() in this so its writes
+ *     are recognizable as legitimate.
+ *   - isMcpWrite(): true when called inside withMcpWrite.
+ *   - createStdoutSentinel({...}): a write function suitable for installing
+ *     in a Proxy over process.stdout. Tagged writes pass through to the real
+ *     stdout; untagged writes are redirected to stderr with a [mcp:stdout-redirect]
+ *     prefix, truncated to maxBytes per redirect, and rate-limited to maxRedirects
+ *     per process so a stray loop cannot flood client logs.
+ *
+ * The sentinel is correctness-by-construction: it identifies legitimate
+ * writes by *who* called write(), not by inspecting the bytes. A byte-shape
+ * heuristic ("starts with {, ends with \n") would falsely reject Content-Length
+ * frames (which start with C and end with }) and misclassify multi-chunk writes.
+ */
+import { AsyncLocalStorage } from 'node:async_hooks';
+// Import from the leaf module, NOT `core/lbug/pool-adapter.js`. pool-adapter
+// pulls in `@ladybugdb/core`, which would put the native module in
+// `cli/mcp.ts`'s static-import closure — exactly the pre-sentinel window
+// Codex's adversarial review flagged on PR #1383.
+import { realStdoutWrite, realStderrWrite, setActiveStdoutWrite } from './stdio-capture.js';
+const store = new AsyncLocalStorage();
+export function withMcpWrite(fn) {
+    return store.run({ mcp: true }, fn);
+}
+export function isMcpWrite() {
+    return store.getStore()?.mcp === true;
+}
+const REDIRECT_PREFIX = '[mcp:stdout-redirect] ';
+const STARTUP_WARNING = '[mcp:stdout-redirect] sentinel triggered — stray write redirected to stderr; subsequent redirects logged at exit\n';
+function chunkToBuffer(chunk) {
+    if (chunk === undefined || chunk === null)
+        return Buffer.alloc(0);
+    if (Buffer.isBuffer(chunk))
+        return chunk;
+    if (typeof chunk === 'string')
+        return Buffer.from(chunk, 'utf8');
+    // Plain Uint8Array (e.g. from a TypedArray-using producer): copy bytes
+    // verbatim instead of falling through to String(chunk), which produces
+    // garbage like "1,2,3,...".
+    if (chunk instanceof Uint8Array)
+        return Buffer.from(chunk);
+    return Buffer.from(String(chunk), 'utf8');
+}
+/**
+ * Node Writable.write contract: the completion callback, when present, is
+ * always the last argument. Match exactly that — don't try to peer past
+ * earlier arguments — so future overload shapes (e.g. an options object)
+ * do not silently break callback delivery.
+ */
+function extractCallback(rest) {
+    const last = rest[rest.length - 1];
+    return typeof last === 'function' ? last : undefined;
+}
+export function createStdoutSentinel(opts) {
+    const maxBytes = opts.maxBytes ?? 200;
+    const maxRedirects = opts.maxRedirects ?? 10;
+    let redirected = 0;
+    let suppressed = 0;
+    let warningEmitted = false;
+    const stderr = (s) => opts.realStderrWrite(s);
+    const write = (chunk, ...rest) => {
+        if (isMcpWrite()) {
+            return opts.realStdoutWrite(chunk, ...rest);
+        }
+        if (!warningEmitted) {
+            warningEmitted = true;
+            stderr(STARTUP_WARNING);
+        }
+        if (redirected < maxRedirects) {
+            redirected += 1;
+            const buf = chunkToBuffer(chunk);
+            const truncated = buf.length > maxBytes ? buf.subarray(0, maxBytes) : buf;
+            stderr(REDIRECT_PREFIX);
+            if (truncated.length > 0)
+                stderr(truncated);
+            if (buf.length > maxBytes) {
+                stderr(` (+${buf.length - maxBytes} bytes truncated)`);
+            }
+            if (truncated.length === 0 || truncated[truncated.length - 1] !== 0x0a) {
+                stderr('\n');
+            }
+        }
+        else {
+            suppressed += 1;
+        }
+        // Honor the Writable.write callback contract — fire async to match
+        // Node's "next-tick" semantics so callers never observe sync reentry.
+        const cb = extractCallback(rest);
+        if (cb) {
+            process.nextTick(() => cb(null));
+        }
+        return true;
+    };
+    return {
+        write,
+        stats: () => ({ redirected, suppressed }),
+        flushSummary: () => {
+            if (redirected === 0 && suppressed === 0)
+                return;
+            stderr(`[mcp:stdout-redirect] summary: ${redirected} redirected, ${suppressed} suppressed beyond cap\n`);
+        },
+    };
+}
+/**
+ * Install the sentinel as the global stdout interceptor — idempotent.
+ *
+ * Does three things in order:
+ *   1. Creates the sentinel from the captured `realStdoutWrite` / `realStderrWrite`.
+ *   2. Replaces `process.stdout.write` with `sentinel.write`.
+ *   3. Registers `sentinel.write` as the "active" handler in pool-adapter
+ *      so silenceStdout/restoreStdout cycles preserve the sentinel
+ *      instead of unwinding to raw stdout.
+ *
+ * Idempotent — callers may invoke it multiple times safely (cli/mcp.ts at
+ * the top of mcpCommand, and startMCPServer). The earliest caller wins;
+ * subsequent calls return the same sentinel handle. Call this BEFORE any
+ * other startup work that might emit to stdout: native module loads,
+ * `_require()`-style grammar detection, repo registry reads, embedder
+ * pipeline initialization. Anything written before the sentinel is in
+ * place reaches raw stdout uncaught.
+ *
+ * Returns the sentinel handle so the earliest caller can register
+ * `process.on('exit', sentinel.flushSummary)`.
+ */
+let _installedSentinel = null;
+export function installGlobalStdoutSentinel() {
+    if (_installedSentinel)
+        return _installedSentinel;
+    const sentinel = createStdoutSentinel({ realStdoutWrite, realStderrWrite });
+    // eslint-disable-next-line no-restricted-syntax -- installing the global sentinel is the API contract
+    process.stdout.write = sentinel.write;
+    setActiveStdoutWrite(sentinel.write);
+    _installedSentinel = sentinel;
+    return sentinel;
+}

package/dist/mcp/tools.d.ts

@@ -0,0 +1,29 @@
+/**
+ * MCP Tool Definitions
+ *
+ * Defines the tools that Arceus exposes to external AI agents.
+ * All tools support an optional `repo` parameter for multi-repo setups.
+ */
+import type { ToolAnnotations } from '@modelcontextprotocol/sdk/types.js';
+export interface ToolDefinition {
+    name: string;
+    description: string;
+    annotations: ToolAnnotations;
+    inputSchema: {
+        type: 'object';
+        properties: Record<string, {
+            type: string;
+            description?: string;
+            default?: unknown;
+            items?: {
+                type: string;
+            };
+            enum?: string[];
+            minimum?: number;
+            maximum?: number;
+            minLength?: number;
+        }>;
+        required: string[];
+    };
+}
+export declare const ARC_TOOLS: ToolDefinition[];