limn-review 0.1.152 → 0.1.153

package/README.md

@@ -44,10 +44,12 @@ there is nothing to set up. An Anthropic API key is the alternative: set
 `ANTHROPIC_API_KEY`. Limn stores no key and charges nothing for it. They can
 run on Codex instead (below).
 
-- **First use downloads the AI runtime, once (about 110 MB).** Press
-  **Set up AI** in the app, or run `limn ai install`. It goes to
-  `~/.limn/ai-runtime`, at the exact versions this release was tested with. The
-  package itself stays small for everyone who never uses AI.
+- **Claude and Codex work out of the box.** The first time Limn starts, it
+  downloads both in the background (Claude about 110 MB, Codex about 360 MB
+  unpacked) into `~/.limn/ai-runtime`, at the exact versions this release was
+  tested with. The package itself stays small. Signing in is the only step.
+  `limn ai install codex` runs the same download by hand;
+  `LIMN_AI_AUTO_INSTALL=false` skips the automatic one.
 - Set `LIMN_CLAUDE_PATH` to the `claude` you already have to use it instead of
   the bundled copy (the download then skips it).
 - The reviewer reads code. It cannot edit files, run commands or reach the web.
@@ -62,12 +64,13 @@ run on Codex instead (below).
 Every AI feature can run on Codex, on your own ChatGPT plan. One provider runs
 everything at a time.
 
+Codex comes with Limn. Sign in from **Settings → AI**, or:
+
 ```bash
-limn ai install codex   # adds the Codex CLI to the AI download
 limn ai login codex     # sign in with ChatGPT (add --device-auth on a headless machine)
 ```
 
-Or press **Set up AI** and sign in from **Settings → AI**. Limn keeps its own
+Limn keeps its own
 Codex sign-in in `~/.limn/codex`; your `~/.codex` is not read or changed. Codex
 with an OpenAI API key is not available yet.
 

package/dist/ai/auto-install.js

@@ -0,0 +1,81 @@
+// THE FIRST-BOOT AI DOWNLOAD — Claude and Codex come with Limn, without a click.
+//
+// The SDKs and the Codex CLI stay OUT of the npm manifest (a fast `npx limn-review`; the guardrails in
+// scripts/build-release.mjs are unchanged), so on a boot that finds either runtime missing, stale or
+// without its native program, Limn downloads what is missing in the background — the same
+// single-flight `installAiRuntime` that `limn ai install codex` and the SPA's Retry run. ⚠ A Claude
+// that is already ready is never fetched again or swapped (`['codex']` alone: the existing install
+// adding Codex). After it, signing in to each provider is the only step.
+//
+// ⚠ IT NEVER DELAYS THE SERVER. `index.ts` calls `startAiAutoInstall` AFTER `listen`, with `void`;
+// nothing awaits it. `/api/me` reads `runtime: 'installing'` (and the current step in
+// `runtimeMessage`) the moment it starts, because `install()` claims its slot synchronously.
+//
+// ⚠ A FAILURE IS RETRIED ONCE, a few minutes later (a laptop waking on a dead network), then left for
+// the reader's Retry, `limn ai install`, or the next boot — never a loop. A Codex-only failure is
+// Codex's alone (ai/runtime.ts): Claude stays set up.
+//
+// Skipped when AI is off (LIMN_AI_DISABLED=true) or LIMN_AI_AUTO_INSTALL=false.
+import { config } from '../config.js';
+import { getAiRuntimeStatus, getCodexRuntimeStatus, installAiRuntime, } from './runtime.js';
+/** How long after a failed automatic download the one automatic retry waits. */
+export const AUTO_INSTALL_RETRY_MS = 3 * 60_000;
+/**
+ * The providers a download must bring, or null when nothing is missing. ['codex'] alone over a ready
+ * Claude downloads Codex only (ai/runtime.ts): an existing install neither fetches nor swaps Claude.
+ */
+export function autoInstallProviders(claude, codex) {
+    // Already running (a `limn ai install` started by the same process cannot be, but a Retry can).
+    if (claude.runtime === 'installing' || codex.runtime === 'installing')
+        return null;
+    const needClaude = claude.runtime !== 'ready';
+    const needCodex = codex.runtime !== 'ready';
+    if (!needClaude && !needCodex)
+        return null;
+    if (!needCodex)
+        return ['claude'];
+    return needClaude ? ['claude', 'codex'] : ['codex'];
+}
+/** The testable body: one attempt, and on failure ONE scheduled retry. */
+export function runAutoInstall(deps, attempt = 1) {
+    if (!deps.enabled)
+        return;
+    const providers = autoInstallProviders(deps.claude(), deps.codex());
+    if (!providers)
+        return;
+    const names = providers.map((p) => (p === 'codex' ? 'Codex' : 'Claude')).join(' and ');
+    deps.log.info(`ai: downloading ${names} in the background`);
+    void deps
+        .install(providers)
+        .then((r) => {
+        if (r.ok) {
+            deps.log.info(`ai: ${names} downloaded — sign in to use ${providers.length > 1 ? 'them' : 'it'}`);
+            return;
+        }
+        deps.log.warn(`ai: the download did not finish: ${r.message}`);
+        if (attempt === 1)
+            deps.schedule(() => runAutoInstall(deps, 2), AUTO_INSTALL_RETRY_MS);
+    })
+        .catch(() => {
+        /* installAiRuntime never throws; belt and braces for the boot */
+    });
+}
+/** Start the first-boot download (a no-op when nothing is missing). Never throws, never awaited. */
+export function startAiAutoInstall(log) {
+    try {
+        runAutoInstall({
+            enabled: config.aiEnabled && config.aiAutoInstall,
+            claude: getAiRuntimeStatus,
+            codex: getCodexRuntimeStatus,
+            install: (providers) => installAiRuntime(undefined, { providers }),
+            schedule: (fn, ms) => {
+                setTimeout(fn, ms).unref?.();
+            },
+            log,
+        });
+    }
+    catch (err) {
+        log.warn(`ai: the background download could not start: ${err.message}`);
+    }
+}
+//# sourceMappingURL=auto-install.js.map

package/dist/ai/check-tool.js

@@ -0,0 +1,6 @@
+// The project-checks tool's names (ai/provider.ts `AgentCheckTool`), in a module of their own so the
+// providers can import them without a cycle through the registry.
+/** The checks tool's server and name on Claude (`mcp__checks__run_check`). */
+export const CHECKS_TOOL_SERVER = 'checks';
+export const RUN_CHECK_TOOL = 'run_check';
+//# sourceMappingURL=check-tool.js.map

package/dist/ai/codex/config.js

@@ -209,6 +209,7 @@ export function mcpConfig(mcp) {
         ...c(`${base}.args`, mcp.args),
         ...(mcp.env && Object.keys(mcp.env).length > 0 ? c(`${base}.env`, mcp.env) : []),
         ...c(`${base}.default_tools_approval_mode`, mcp.default_tools_approval_mode),
+        ...(mcp.tool_timeout_sec != null ? c(`${base}.tool_timeout_sec`, mcp.tool_timeout_sec) : []),
     ];
 }
 /**

package/dist/ai/codex/hook-rule.js

@@ -7,8 +7,13 @@
 //     paths inside the run's WRITE roots. A read-only run has none, so every write is denied. A patch
 //     is read for its `*** Add File:` / `*** Update File:` / `*** Delete File:` / `*** Move to:`
 //     headers; a write naming NO path we can find is denied (fail closed).
+//   • On a STORY BUILD (`roots.protect`) a write inside the write roots is ALSO denied when it touches
+//     the build's deny-list (review/write-deny.ts: CI / git / hook / package-manager config, lockfiles,
+//     agent settings) — the same rule the Claude hook applies.
 //   • `mcp__workspace__*` (Limn's own server) is allowed when every `path` it names is inside a READ
-//     root (the server checks again).
+//     root (the server checks again) — except `mcp__workspace__run_check` (the project's own checks,
+//     coding/checks/), allowed ONLY when the run carries checks (`roots.checks`) and the call names a
+//     check by a plain string; the server runs only names from its frozen list.
 //   • Any OTHER MCP tool is denied: only Limn's server may run (a user's own servers never load —
 //     Limn's CODEX_HOME carries none — and this keeps it so).
 //   • ⚠ AN ALLOW-LIST, NOT A DENY-LIST. The hook's matcher is `.*` (hook.ts), so it sees EVERY tool
@@ -20,12 +25,14 @@
 // workspace server use — and tested with `isWithin`.
 import { isAbsolute } from 'node:path';
 import { isWithin, realPathFor, resolveReal } from '../../review/path-guard.js';
+import { protectedWriteFor } from '../../review/write-deny.js';
 export const WRITE_TOOLS = new Set(['apply_patch', 'Edit', 'Write', 'MultiEdit', 'NotebookEdit']);
 export const WORKSPACE_TOOL_PREFIX = 'mcp__workspace__';
 /** Built-ins that read and write nothing on disk; every other unlisted tool is denied. */
 export const HARMLESS_TOOLS = new Set(['update_plan']);
 const PATH_KEYS = ['file_path', 'path', 'notebook_path'];
 const PATCH_HEADER = /^\s*\*\*\*\s*(Add File|Update File|Delete File|Move to)\s*:\s*(.*?)\s*$/;
+export const RUN_CHECK_TOOL_NAME = 'mcp__workspace__run_check';
 const deny = (reason) => ({ allow: false, reason: `Limn path guard: ${reason}` });
 /** Every string anywhere in `v` (the patch text may sit under any key, or be the input itself). */
 function strings(v, out = [], depth = 0) {
@@ -118,9 +125,22 @@ export function decideCodexToolCall(toolName, toolInput, roots, cwd) {
             if (real == null || !writeRoots.some((r) => isWithin(r, real))) {
                 return deny(`refused: ${raw} is outside the folders this run may change.`);
             }
+            if (roots.protect === true) {
+                const why = protectedWriteFor(raw, from, writeRoots);
+                if (why)
+                    return deny(`refused: ${why}`);
+            }
         }
         return { allow: true };
     }
+    if (toolName === RUN_CHECK_TOOL_NAME) {
+        if (roots.checks !== true)
+            return deny('refused: this run may not run checks.');
+        const name = toolInput && typeof toolInput === 'object' ? toolInput.name : undefined;
+        if (typeof name !== 'string' || name === '' || name.length > 120)
+            return deny('refused: name the check to run.');
+        return { allow: true };
+    }
     if (toolName.startsWith('mcp__')) {
         if (!toolName.startsWith(WORKSPACE_TOOL_PREFIX))
             return deny(`refused: only Limn's workspace tools may run, not ${toolName}.`);
@@ -144,7 +164,12 @@ export function decideCodexToolCall(toolName, toolInput, roots, cwd) {
 /** The roots as they travel to the hook process (the `LIMN_CODEX_GUARD` environment variable). */
 export const GUARD_ENV = 'LIMN_CODEX_GUARD';
 export function encodeGuardRoots(roots) {
-    return JSON.stringify({ read: roots.read, write: roots.write });
+    return JSON.stringify({
+        read: roots.read,
+        write: roots.write,
+        ...(roots.checks ? { checks: true } : {}),
+        ...(roots.protect ? { protect: true } : {}),
+    });
 }
 /** Null when the variable is missing or malformed — the hook then denies everything it sees. */
 export function decodeGuardRoots(raw) {
@@ -154,9 +179,11 @@ export function decodeGuardRoots(raw) {
         const v = JSON.parse(raw);
         if (!v || typeof v !== 'object')
             return null;
-        const { read, write } = v;
+        const { read, write, checks, protect } = v;
         const ok = (a) => Array.isArray(a) && a.every((x) => typeof x === 'string' && isAbsolute(x));
-        return ok(read) && ok(write) ? { read, write } : null;
+        if (!ok(read) || !ok(write))
+            return null;
+        return { read, write, ...(checks === true ? { checks: true } : {}), ...(protect === true ? { protect: true } : {}) };
     }
     catch {
         return null;

package/dist/ai/codex/kinds/story-build.js

@@ -0,0 +1,2 @@
+export const CODEX_STORY_BUILD_KINDS = ['story_plan', 'story_build'];
+//# sourceMappingURL=story-build.js.map

package/dist/ai/codex/workspace-mcp-main.js

@@ -3,8 +3,8 @@
 // release install that carries no AI package, and from dev under tsx.
 import { parseServerArgv, serveWorkspaceMcp } from './workspace-mcp.js';
 try {
-    const { read, logFile } = parseServerArgv(process.argv.slice(2));
-    await serveWorkspaceMcp({ read, logFile, input: process.stdin, output: process.stdout });
+    const { read, logFile, checksSpec } = parseServerArgv(process.argv.slice(2));
+    await serveWorkspaceMcp({ read, logFile, checksSpec, input: process.stdin, output: process.stdout });
 }
 catch (e) {
     process.stderr.write(`limn workspace MCP server: ${e instanceof Error ? e.message : String(e)}\n`);

package/dist/ai/codex/workspace-mcp.js

@@ -20,6 +20,7 @@ import { appendFileSync } from 'node:fs';
 import { createInterface } from 'node:readline';
 import { helperCommand } from './entry.js';
 import { createWorkspaceTools, ToolRefusal, WORKSPACE_TOOL_DEFS } from './workspace-files.js';
+import { CheckToolRunner, loadCheckSpec, runCheckDescription, runCheckInputSchema } from '../../coding/checks/spec.js';
 export const WORKSPACE_MCP_ID = 'workspace';
 const SERVER_INFO = { name: 'limn-workspace', version: '1.0.0' };
 const DEFAULT_PROTOCOL = '2025-06-18';
@@ -27,6 +28,8 @@ const MAX_LINE_CHARS = 1024 * 1024;
 /**
  * The `mcp_servers.workspace` entry for one run: Node + the entry script + `--read <root>` per read
  * root. `opts.logFile` makes the server append one JSON line per tool call (tests, the live check).
+ * `opts.checks` adds the project's own checks (`run_check`, coding/checks/spec.ts): the server reads
+ * that frozen list ONCE at start-up, and Codex is told a call may take up to `timeoutSec`.
  */
 export function workspaceMcpConfig(roots, opts = {}) {
     if (roots.read.length === 0)
@@ -37,29 +40,49 @@ export function workspaceMcpConfig(roots, opts = {}) {
         argv.push('--read', r);
     if (opts.logFile)
         argv.push('--log', opts.logFile);
-    return { id: WORKSPACE_MCP_ID, command, args: argv, env: {}, default_tools_approval_mode: 'approve' };
+    if (opts.checks)
+        argv.push('--checks', opts.checks.specFile);
+    return {
+        id: WORKSPACE_MCP_ID,
+        command,
+        args: argv,
+        env: {},
+        default_tools_approval_mode: 'approve',
+        ...(opts.checks ? { tool_timeout_sec: Math.ceil(opts.checks.timeoutSec + 30) } : {}),
+    };
 }
-/** Parse the entry's argv (`--read <root>`…, `--log <file>`). */
+/** Parse the entry's argv (`--read <root>`…, `--log <file>`, `--checks <spec file>`). */
 export function parseServerArgv(argv) {
     const read = [];
     let logFile = null;
+    let checksSpec = null;
     for (let i = 0; i < argv.length; i++) {
         const flag = argv[i];
         const value = argv[i + 1];
-        if ((flag === '--read' || flag === '--log') && value !== undefined) {
+        if ((flag === '--read' || flag === '--log' || flag === '--checks') && value !== undefined) {
             if (flag === '--read')
                 read.push(value);
-            else
+            else if (flag === '--log')
                 logFile = value;
+            else
+                checksSpec = value;
             i++;
         }
         else
             throw new Error(`workspace MCP server: unexpected argument ${JSON.stringify(flag)}`);
     }
-    return { read, logFile };
+    return { read, logFile, checksSpec };
 }
-/** Answer one JSON-RPC message; null for a notification (no reply). */
-export function handleMessage(tools, msg, log) {
+/** The tool definitions: the three file tools, plus `run_check` when the run carries checks. */
+export function toolDefs(checks) {
+    if (!checks || checks.names.length === 0)
+        return WORKSPACE_TOOL_DEFS;
+    return [
+        ...WORKSPACE_TOOL_DEFS,
+        { name: 'run_check', description: runCheckDescription(checks.names), inputSchema: runCheckInputSchema(checks.names) },
+    ];
+}
+export function handleMessage(tools, msg, log, checks = null) {
     if (!msg || typeof msg !== 'object' || Array.isArray(msg)) {
         return { jsonrpc: '2.0', id: null, error: { code: -32600, message: 'Invalid request' } };
     }
@@ -87,7 +110,7 @@ export function handleMessage(tools, msg, log) {
         case 'ping':
             return { jsonrpc: '2.0', id, result: {} };
         case 'tools/list':
-            return { jsonrpc: '2.0', id, result: { tools: WORKSPACE_TOOL_DEFS } };
+            return { jsonrpc: '2.0', id, result: { tools: toolDefs(checks) } };
         case 'resources/list':
             return { jsonrpc: '2.0', id, result: { resources: [] } };
         case 'resources/templates/list':
@@ -96,6 +119,12 @@ export function handleMessage(tools, msg, log) {
             return { jsonrpc: '2.0', id, result: { prompts: [] } };
         case 'tools/call': {
             const name = typeof params.name === 'string' ? params.name : '';
+            if (name === 'run_check' && checks) {
+                return checks.call(params.arguments).then((reply) => {
+                    log({ tool: name, args: params.arguments, ok: !reply.isError });
+                    return { jsonrpc: '2.0', id, result: { ...(reply.isError ? { isError: true } : {}), content: [{ type: 'text', text: reply.text }] } };
+                }, () => ({ jsonrpc: '2.0', id, result: { isError: true, content: [{ type: 'text', text: 'The check could not run.' }] } }));
+            }
             try {
                 const text = tools.call(name, params.arguments);
                 log({ tool: name, args: params.arguments, ok: true });
@@ -114,6 +143,7 @@ export function handleMessage(tools, msg, log) {
 /** Serve newline-delimited JSON-RPC on `input`/`output` until `input` ends. */
 export function serveWorkspaceMcp(opts) {
     const tools = createWorkspaceTools(opts.read);
+    const checks = opts.checksSpec ? new CheckToolRunner(loadCheckSpec(opts.checksSpec)) : null;
     const log = (entry) => {
         if (!opts.logFile)
             return;
@@ -141,8 +171,10 @@ export function serveWorkspaceMcp(opts) {
             send({ jsonrpc: '2.0', id: null, error: { code: -32700, message: 'Parse error' } });
             return;
         }
-        const reply = handleMessage(tools, msg, log);
-        if (reply)
+        const reply = handleMessage(tools, msg, log, checks);
+        if (reply instanceof Promise)
+            void reply.then(send);
+        else if (reply)
             send(reply);
     });
     return new Promise((resolve) => rl.on('close', () => resolve()));

package/dist/ai/credentials.js

@@ -2,7 +2,7 @@
 // Fix, the ticket / CI reviews, diagrams, sprint paths, the docs build and chat, resolve with
 // Claude, every chat) AND the one-shot completions (review/llm.ts `cheapComplete`, which the
 // sprint briefs/themes, story labels, docs ranking, sprint Ask Claude and every platform feature —
-// reports, synthesis, work-plan wording, pointers, bot themes, the impact note, the Slack
+// reports, synthesis, work-plan wording, pointers, bot themes, the Slack
 // report — all go through).
 //
 //   1. THE LOCAL CLAUDE CODE LOGIN (default) — a `claude` session on disk or

package/dist/ai/effort.js

@@ -7,7 +7,8 @@
 // Neither ⇒ DEFAULT (null). No DB import here, for the same reason as ai/provider-setting.ts.
 //
 // WHO IT REACHES (`agenticRunEffort`): the PR review (lead, specialists, follow-up re-reviews), AI Fix
-// and Plan first, on BOTH providers — and NOTHING ELSE. REVIEW_EFFORT and REVIEW_DIFF_ONLY_EFFORT reach
+// and Plan first, and "Implement story"'s plan and build passes (`story_plan`, `story_build`; owner
+// decision 7, docs/STORY-BUILD.md), on BOTH providers — and NOTHING ELSE. REVIEW_EFFORT and REVIEW_DIFF_ONLY_EFFORT reach
 // exactly the same runs as the Settings control (REVIEW_EFFORT IS the control, locked), so "Set by
 // REVIEW_EFFORT" under it is the whole story. Every other agent kind (CI review, ticket review,
 // diagrams, Check threads, chats, Resolve with Claude) runs at its provider's own fixed depth
@@ -89,7 +90,7 @@ export function diffOnlyEffortAt(level, atDefault) {
     return higherOf(stepDownEffort(level), lowerOf(level, atDefault));
 }
 /**
- * THE EFFORT of a review / AI Fix / Plan first run on `provider`: the chosen level on a worktree run;
+ * THE EFFORT of a review / AI Fix / Plan first / story plan / story build run on `provider`: the chosen level on a worktree run;
  * diff-only, REVIEW_DIFF_ONLY_EFFORT when set (at any level, on both providers), else
  * `diffOnlyEffortAt`; Default ⇒ `defaultRunEffort`. Read once per run, at its start; the run stores
  * what it used.

package/dist/ai/provider-setting.js

@@ -8,6 +8,7 @@ import { codexCredentialRunnable, resolveAiCredential, resolveCodexCredential }
 import { CODEX_DOCS_KINDS } from './codex/kinds/docs.js';
 import { CODEX_FIX_KINDS } from './codex/kinds/fix.js';
 import { CODEX_REVIEW_KINDS } from './codex/kinds/review.js';
+import { CODEX_STORY_BUILD_KINDS } from './codex/kinds/story-build.js';
 import { CODEX_TICKETS_KINDS } from './codex/kinds/tickets.js';
 export const AI_PROVIDER_ENV = 'LIMN_AI_PROVIDER';
 /**
@@ -59,6 +60,8 @@ export const CODEX_AGENT_KINDS = new Set([
     ...CODEX_FIX_KINDS,
     ...CODEX_TICKETS_KINDS,
     ...CODEX_DOCS_KINDS,
+    // "Implement story" (listed from its contract commit — see that file's header).
+    ...CODEX_STORY_BUILD_KINDS,
 ]);
 /** Can Codex run this agent kind in this version? (`allow` is for tests.) */
 export function codexKindReady(kind, allow = CODEX_AGENT_KINDS) {
@@ -79,6 +82,8 @@ const KIND_WORDS = {
     story_docs: 'checks against docs',
     docs_build: 'the docs library',
     docs_chat: 'the docs chat',
+    story_plan: 'story plans',
+    story_build: 'story builds',
 };
 /** Every agent kind (the KIND_WORDS keys, so a new kind cannot be missed: the Record is exhaustive). */
 export const ALL_AGENT_KINDS = Object.keys(KIND_WORDS);

package/dist/ai/provider.js

@@ -1,6 +1,7 @@
 import { CLAUDE_MODEL_FOR_ROLE, claudeProvider } from './providers/claude.js';
 import { CODEX_MODEL_FOR_ROLE as CODEX_MODEL_FOR_ROLE_SRC, codexProvider } from './providers/codex.js';
 import { activeProviderId, codexRunnable } from './provider-setting.js';
+export { CHECKS_TOOL_SERVER, RUN_CHECK_TOOL } from './check-tool.js';
 // ---- the registry -------------------------------------------------------------------------------
 export { AI_PROVIDER_ENV, aiProviderEnvSetting, aiProviderSetting, aiProviderSettingStatus, setStoredAiProviderSetting, storedAiProviderSetting, CODEX_AGENT_KINDS, CODEX_NOT_AVAILABLE_MESSAGE, codexKindNotAvailableMessage, codexKindReady, codexRunnable, ALL_AGENT_KINDS, ALL_RUN_KINDS, activeProviderId, autoReadiness, codexRunKindReady, pickAutoProvider, } from './provider-setting.js';
 export { CODEX_MODEL_FOR_ROLE } from './providers/codex.js';

package/dist/ai/providers/claude.js

@@ -8,23 +8,26 @@
 //     CLAUDE.md or skills), `ISOLATED_MCP` (no claude.ai connectors), the LIMN_CLAUDE_PATH
 //     executable and the credential ladder's environment (`agentAuthOptions()`);
 //   • ⚠ THE PATH GUARD as the FIRST PreToolUse hook — `createPathGuard(cwd, roots, {readOnlyRoots})`
-//     — then `ownToolsOnlyHook(<the run's own server>)`, then the run's extra hooks (the specialist
-//     cap, the docs build's sections-write guard). Under bypassPermissions a PreToolUse deny is the
-//     only thing that confines an absolute path, and the prompt is attacker-authored;
+//     — then `ownToolsOnlyHook(<the run's own server>)`, then (a story build, `spec.protectWrites`) the
+//     write deny-list (review/write-deny.ts), then the run's extra hooks (the specialist cap, the docs
+//     build's sections-write guard). Under bypassPermissions a PreToolUse deny is the only thing that
+//     confines an absolute path, and the prompt is attacker-authored;
 //   • `additionalDirectories` = roots + read-only roots, only when there are any (the SDK adds one
 //     `--add-dir` per entry, so an empty list and no list run the same CLI);
 //   • the result tools as ONE in-process MCP server (`createSdkMcpServer`, version 1.0.0), each
 //     handler's reply as one text block (+ `isError` only when the handler set it).
 // The SDK module comes from `loadAgentSdk()`, whose `query` is TAPPED (ai/runtime.ts `tapQuery`), so
 // every message still reaches the spend budget's observer.
-import { loadAgentSdk, loadAnthropicSdk, claudeExecutableOptions, getAiRuntimeStatus } from '../runtime.js';
+import { loadAgentSdk, loadAnthropicSdk, loadZod, claudeExecutableOptions, getAiRuntimeStatus } from '../runtime.js';
 import { agentAuthOptions, agentSdkEnv, resolveAiCredential } from '../credentials.js';
 import { ISOLATED_MCP, ownToolsOnlyHook } from '../agent-isolation.js';
 import { config } from '../../config.js';
 import { NO_CLAUDE_AUTH_MESSAGE } from '../../review/auth.js';
 import { sdkModelOptions } from '../../review/model-options.js';
 import { createPathGuard, pathGuardHook } from '../../review/path-guard.js';
+import { protectedWriteHook } from '../../review/write-deny.js';
 import { recordUsage, sumModelUsage, sumUsageMap } from '../../review/usage.js';
+import { CHECKS_TOOL_SERVER, RUN_CHECK_TOOL } from '../check-tool.js';
 import { AI_MODEL_FOR_ROLE } from '../../shared/index.js';
 import { foldRateLimitEvent, parseUsageProbe } from './claude-usage.js';
 import { assistantText, describeFixBlocks, describeReviewBlocks } from './claude-activity.js';
@@ -42,21 +45,40 @@ async function runAgent(spec) {
     // From the AI runtime (ai/runtime.ts) — downloaded on first use for an npm install. A missing
     // runtime throws here, into the caller's catch, as it always did.
     const { createSdkMcpServer, query, tool } = await loadAgentSdk();
-    const mcpServers = spec.tools
-        ? {
-            [spec.tools.server]: createSdkMcpServer({
-                name: spec.tools.server,
-                version: '1.0.0',
-                tools: spec.tools.tools.map((t) => tool(t.name, t.description, t.shape, async (a) => {
-                    const reply = await t.handle(a);
+    const mcpServers = {};
+    if (spec.tools) {
+        mcpServers[spec.tools.server] = createSdkMcpServer({
+            name: spec.tools.server,
+            version: '1.0.0',
+            tools: spec.tools.tools.map((t) => tool(t.name, t.description, t.shape, async (a) => {
+                const reply = await t.handle(a);
+                return {
+                    content: [{ type: 'text', text: reply.text }],
+                    ...(reply.isError !== undefined ? { isError: reply.isError } : {}),
+                };
+            })),
+        });
+    }
+    // THE PROJECT'S CHECKS (`mcp__checks__run_check`): a second in-process server, present only when the
+    // run carries them. Its one argument is an enum of the frozen names — nothing else reaches the runner.
+    const checks = spec.checks;
+    if (checks && checks.names.length > 0) {
+        const z = await loadZod();
+        mcpServers[CHECKS_TOOL_SERVER] = createSdkMcpServer({
+            name: CHECKS_TOOL_SERVER,
+            version: '1.0.0',
+            tools: [
+                tool(RUN_CHECK_TOOL, checks.description, { name: z.enum(checks.names).describe('The check to run.') }, async (a) => {
+                    const reply = await checks.run(a);
                     return {
                         content: [{ type: 'text', text: reply.text }],
                         ...(reply.isError !== undefined ? { isError: reply.isError } : {}),
                     };
-                })),
-            }),
-        }
-        : undefined;
+                }),
+            ],
+        });
+    }
+    const ownServers = Object.keys(mcpServers);
     const guard = createPathGuard(spec.cwd, spec.roots, { readOnlyRoots: spec.readOnlyRoots });
     const extraDirs = [...spec.roots, ...spec.readOnlyRoots];
     const c = spec.claude;
@@ -82,7 +104,9 @@ async function runAgent(spec) {
             hooks: {
                 PreToolUse: [
                     pathGuardHook(guard),
-                    ownToolsOnlyHook(spec.tools ? [spec.tools.server] : []),
+                    ownToolsOnlyHook(ownServers),
+                    // The build's write deny-list (review/write-deny.ts), only on a run that asks for it.
+                    ...(spec.protectWrites && spec.writeRoots.length > 0 ? [protectedWriteHook(spec.writeRoots, spec.cwd)] : []),
                     ...(c.extraPreToolUse ?? []),
                 ],
             },
@@ -90,7 +114,7 @@ async function runAgent(spec) {
             // Don't inherit the host's .claude settings / CLAUDE.md / skills.
             settingSources: [],
             ...ISOLATED_MCP,
-            ...(mcpServers ? { mcpServers } : {}),
+            ...(ownServers.length > 0 ? { mcpServers: mcpServers } : {}),
             abortController: spec.abortController,
             // LIMN_CLAUDE_PATH → the user's own `claude` instead of the SDK's bundled binary.
             ...claudeExecutableOptions(),

package/dist/ai/providers/codex.js

@@ -491,11 +491,20 @@ export async function runAgentUnchecked(spec) {
     const z = await loadZod();
     if (resultTool)
         toolSchema = shapeToJsonSchema(z, resultTool.shape);
-    const mcp = workspaceMcpConfig(roots);
+    // THE PROJECT'S CHECKS (`mcp__workspace__run_check`, coding/checks/): the server reads Limn's frozen
+    // list once at start-up, and the guard lets the tool through ONLY on a run that carries checks.
+    const checks = spec.checks && spec.checks.names.length > 0 ? spec.checks : null;
+    const mcp = workspaceMcpConfig(roots, checks ? { checks: { specFile: checks.specFile, timeoutSec: checks.timeoutSec } } : {});
     // THE GUARD IS NOT OPTIONAL. Its trust entry is written into Limn's own home first, then Codex is
     // asked whether it will RUN the hook (and the hook must refuse a canary call). An untrusted hook is
     // skipped SILENTLY by Codex, so a run whose guard is not proven never starts — read-only or not.
-    const { hook, home } = await trustedGuard({ read: roots.read, write: roots.write });
+    // A story build (`protectWrites`) also carries the write deny-list into the guard (hook-rule.ts).
+    const { hook, home } = await trustedGuard({
+        read: roots.read,
+        write: roots.write,
+        ...(checks ? { checks: true } : {}),
+        ...(spec.protectWrites && roots.write.length > 0 ? { protect: true } : {}),
+    });
     armCodexThreadSweeps(home);
     const before = isWrite ? await Promise.all(roots.write.map(gitSnapshot)) : [];
     return withScratch(async (scratch) => {
@@ -506,7 +515,8 @@ export async function runAgentUnchecked(spec) {
         }
         const args = buildExecArgs({ cwd, writeRoots: roots.write, ...(spec.system ? { system: spec.system } : {}) }, { home, mcp, hook, schemaPath, model, effort });
         const env = codexExecEnv(credential, hook);
-        const timeoutMs = spec.codex?.timeoutMs ?? DEFAULT_AGENT_TIMEOUT_MS;
+        // A run that may run the project's checks gets longer: each may take up to its own limit.
+        const timeoutMs = spec.codex?.timeoutMs ?? (checks ? DEFAULT_AGENT_TIMEOUT_MS * 2 : DEFAULT_AGENT_TIMEOUT_MS);
         // THE NEUTRAL STREAM (ai/provider.ts): the status-line kinds, then the step the event makes (its
         // activity line, its text, the run's tokens so far — turn.completed carries the thread's total,
         // which for a run and its retry is the run's own).

package/dist/ai/result-schemas.js

@@ -14,12 +14,18 @@ export const RESULT_TOOL_NAMES = [
     'submit_design',
     'submit_paths',
     'submit_alignment',
+    // The story docs read's BUILD mode ("Implement story" → docs consideration).
+    'submit_build_docs',
     'submit_explanations',
     'record_sections',
     // The docs build's closing call (beside record_sections): a result too.
     'finish_document',
     // The docs build on CODEX: record_sections + finish_document as ONE final answer (Phase 3).
     'submit_document',
+    // "Implement story": the read-only plan pass (coding/story-build/schema.ts).
+    'submit_story_plan',
+    // "Implement story": one repository's build (coding/story-build/build.ts) — the `submit_fix` shape.
+    'submit_build',
 ];
 // Each builder is imported LAZILY: an agent's schema module is reached only when its schema is asked
 // for, never at import time of this registry.
@@ -36,10 +42,13 @@ const BUILDERS = {
     submit_design: async (z) => (await import('../review/diagrams/schema.js')).buildSubmitDesignShape(z),
     submit_paths: async (z) => (await import('../review/sprint-paths/schema.js')).buildSubmitPathsShape(z),
     submit_alignment: async (z) => (await import('../review/story-docs/schema.js')).buildSubmitAlignmentShape(z),
+    submit_build_docs: async (z) => (await import('../review/story-docs/schema.js')).buildSubmitBuildDocsShape(z),
     submit_explanations: async (z) => (await import('../review/claude-review/chat-explain.js')).buildSubmitExplanationsShape(z),
     record_sections: async (z) => (await import('../reference-docs/schema.js')).buildRecordSectionsShape(z),
     finish_document: async (z) => (await import('../reference-docs/schema.js')).buildFinishShape(z),
     submit_document: async (z) => (await import('../reference-docs/schema.js')).buildSubmitDocumentShape(z),
+    submit_story_plan: async (z) => (await import('../coding/story-build/schema.js')).buildSubmitStoryPlanShape(z),
+    submit_build: async (z) => (await import('../coding/schema.js')).buildSubmitFixShape(z),
 };
 /** The raw zod shape the Claude tool `name` is registered with. `z` defaults to the AI runtime's. */
 export async function resultToolShape(name, opts = {}, z) {