create-agent-rig 0.9.0 → 0.10.0

package/packages/cli/dist/commands/integrations.js

@@ -0,0 +1,468 @@
+import { createHash, randomBytes } from 'node:crypto';
+import { constants } from 'node:fs';
+import { lstat, mkdir, open, rename, unlink } from 'node:fs/promises';
+import path from 'node:path';
+import { parseArgs } from 'node:util';
+import { DECLARATION_REL, MAX_DECLARATION_BYTES, parseDeclaration, serializeDeclaration, } from '../integrations/declaration.js';
+import { REGISTRY } from '../integrations/registry.js';
+import { resolveReadableInside, resolveWritableInside } from '../lib/safe-path.js';
+import { hasControlCharacter } from '../lib/safe-text.js';
+import { editMcpServers, readMcpConfig } from '../integrations/mcp-json.js';
+import { initFileContents } from './init.js';
+import { MANIFEST_REL, parseManifest, sha256 } from '../lib/manifest.js';
+import { subsystemsManifestPath } from '../lib/subsystems.js';
+import { runSpecKitLifecycle, SPEC_KIT_VERSION, } from '../integrations/spec-kit.js';
+const MCP = '.mcp.json';
+const CODEX_CONFIG = '.codex/config.toml';
+const MAX_MCP_BYTES = 64 * 1024;
+export const INTEGRATIONS_VERBS = ['list', 'add', 'apply', 'remove'];
+class Refusal extends Error {
+}
+const hash = (value) => createHash('sha256').update(JSON.stringify(value)).digest('hex');
+function serverFor(id) {
+    if (id === 'figma-mcp')
+        return { name: 'figma', server: { type: 'http', url: 'https://mcp.figma.com/mcp' } };
+    if (id === 'atlassian-mcp')
+        return { name: 'atlassian', server: { type: 'http', url: 'https://mcp.atlassian.com/v2/mcp' } };
+    if (id === 'basic-memory')
+        return { name: 'basic-memory', server: { command: 'uvx', args: ['basic-memory', 'mcp'] } };
+    throw new Refusal('not-in-matrix');
+}
+function codexSection(id) {
+    const { name, server } = serverFor(id);
+    if ('type' in server && server.type === 'http')
+        return `[mcp_servers.${name}]\nurl = ${JSON.stringify(server.url)}\n`;
+    if ('command' in server && Array.isArray(server.args))
+        return `[mcp_servers.${name}]\ncommand = ${JSON.stringify(server.command)}\nargs = [${server.args.map((arg) => JSON.stringify(arg)).join(', ')}]\n`;
+    throw new Refusal('codex-provider-not-renderable');
+}
+async function hasMachineMemoryManifest(env) {
+    let file;
+    try {
+        file = subsystemsManifestPath(env, process.platform);
+    }
+    catch {
+        return false;
+    }
+    let info;
+    try {
+        info = await lstat(file);
+        if (!info.isFile() || info.isSymbolicLink() || info.size > MAX_MCP_BYTES)
+            return false;
+    }
+    catch {
+        return false;
+    }
+    const flags = constants.O_RDONLY |
+        (process.platform === 'win32' ? 0 : constants.O_NOFOLLOW | constants.O_NONBLOCK);
+    let handle;
+    try {
+        handle = await open(file, flags);
+    }
+    catch {
+        return false;
+    }
+    try {
+        const current = await handle.stat();
+        if (!current.isFile() || current.size > MAX_MCP_BYTES)
+            return false;
+        const bytes = Buffer.alloc(MAX_MCP_BYTES + 1);
+        let offset = 0;
+        while (offset < bytes.length) {
+            const { bytesRead } = await handle.read(bytes, offset, bytes.length - offset, null);
+            if (bytesRead === 0)
+                break;
+            offset += bytesRead;
+        }
+        if (offset > MAX_MCP_BYTES)
+            return false;
+        const text = new TextDecoder('utf-8', { fatal: true, ignoreBOM: true }).decode(bytes.subarray(0, offset));
+        const parsed = JSON.parse(text);
+        return (typeof parsed === 'object' &&
+            parsed !== null &&
+            typeof parsed.entries?.memory === 'object' &&
+            parsed.entries?.memory !== null);
+    }
+    catch {
+        return false;
+    }
+    finally {
+        await handle.close().catch(() => undefined);
+    }
+}
+function renderCodexConfig(base, entries) {
+    const sections = entries
+        .filter((entry) => entry.id !== 'spec-kit' && entry.harnesses?.includes('codex'))
+        .map((entry) => codexSection(entry.id))
+        .sort((a, b) => a.localeCompare(b));
+    return Buffer.from(`${base.replace(/\n*$/, '\n')}${sections.length ? `\n${sections.join('\n')}` : ''}`);
+}
+async function snapshot(root, rel) {
+    const resolved = await resolveReadableInside(root, rel, 'file');
+    if (resolved.status === 'absent')
+        return { rel, bytes: null };
+    if (resolved.status !== 'ok')
+        throw new Refusal('preimage-unreadable');
+    const max = rel === DECLARATION_REL ? MAX_DECLARATION_BYTES : MAX_MCP_BYTES;
+    const flags = constants.O_RDONLY |
+        (process.platform === 'win32' ? 0 : constants.O_NOFOLLOW | constants.O_NONBLOCK);
+    const handle = await open(resolved.path, flags);
+    try {
+        const info = await handle.stat();
+        if (!info.isFile() || info.size > max)
+            throw new Refusal('preimage-unreadable-or-too-large');
+        const buffer = Buffer.alloc(max + 1);
+        let offset = 0;
+        while (offset < buffer.length) {
+            const { bytesRead } = await handle.read(buffer, offset, buffer.length - offset, null);
+            if (bytesRead === 0)
+                break;
+            offset += bytesRead;
+        }
+        if (offset > max)
+            throw new Refusal('preimage-too-large');
+        return { rel, bytes: buffer.subarray(0, offset) };
+    }
+    finally {
+        await handle.close();
+    }
+}
+function decode(bytes) {
+    try {
+        return new TextDecoder('utf-8', { fatal: true, ignoreBOM: true }).decode(bytes);
+    }
+    catch {
+        throw new Refusal('preimage-invalid-utf8');
+    }
+}
+function readConfig(file) {
+    if (file.bytes === null)
+        return { mcpServers: {} };
+    try {
+        return readMcpConfig(decode(file.bytes));
+    }
+    catch {
+        throw new Refusal('mcp-config-invalid-or-ambiguous');
+    }
+}
+const equalBytes = (a, b) => a === null ? b === null : b !== null && a.equals(b);
+async function checkSnapshots(root, files) {
+    for (const file of files) {
+        const current = await snapshot(root, file.rel);
+        if (!equalBytes(current.bytes, file.bytes))
+            throw new Refusal('changed-since-plan');
+    }
+}
+async function atomicWrite(root, rel, bytes) {
+    let dest = await resolveWritableInside(root, rel);
+    if (dest === null)
+        throw new Refusal('write-path-unsafe');
+    await mkdir(path.dirname(dest), { recursive: true });
+    dest = await resolveWritableInside(root, rel);
+    if (dest === null)
+        throw new Refusal('write-path-unsafe');
+    const temporary = path.join(path.dirname(dest), `.${path.basename(dest)}.${randomBytes(12).toString('hex')}.tmp`);
+    let created = false;
+    try {
+        const handle = await open(temporary, 'wx', 0o600);
+        created = true;
+        try {
+            await handle.writeFile(bytes);
+        }
+        finally {
+            await handle.close();
+        }
+        if ((await resolveWritableInside(root, rel)) !== dest)
+            throw new Refusal('write-path-changed');
+        await rename(temporary, dest);
+        created = false;
+    }
+    finally {
+        if (created)
+            await unlink(temporary).catch(() => undefined);
+    }
+}
+async function applyEdits(root, preimages, edits) {
+    await checkSnapshots(root, preimages);
+    for (const edit of edits) {
+        if ((await resolveWritableInside(root, edit.rel)) === null)
+            throw new Refusal('write-path-unsafe');
+    }
+    const written = [];
+    try {
+        for (const edit of edits) {
+            await checkSnapshots(root, [{ rel: edit.rel, bytes: edit.bytes }]);
+            await atomicWrite(root, edit.rel, edit.next);
+            written.push(edit);
+        }
+    }
+    catch (error) {
+        let restored = true;
+        for (const edit of written.reverse()) {
+            try {
+                await checkSnapshots(root, [{ rel: edit.rel, bytes: edit.next }]);
+                if (edit.bytes !== null)
+                    await atomicWrite(root, edit.rel, edit.bytes);
+                else {
+                    const dest = await resolveWritableInside(root, edit.rel);
+                    if (dest === null)
+                        throw new Refusal('rollback-path-unsafe');
+                    await unlink(dest);
+                }
+            }
+            catch {
+                restored = false;
+            }
+        }
+        if (!restored)
+            throw new Refusal('write-failed-rollback-incomplete');
+        throw error;
+    }
+}
+export async function runIntegrationsCommand(options) {
+    const json = options.args.includes('--json');
+    const verb = INTEGRATIONS_VERBS.find((value) => value === options.verb);
+    const respond = (payload, prose, exitCode = 0) => ({
+        exitCode,
+        stdout: json
+            ? `${JSON.stringify({ schemaVersion: 1, command: 'setup', verb: verb ?? 'unknown', ...payload })}\n`
+            : exitCode === 0
+                ? `${prose}\n`
+                : '',
+        stderr: !json && exitCode !== 0 ? `${prose}\n` : '',
+    });
+    let upstreamApplied = false;
+    let observed;
+    try {
+        if (verb === undefined)
+            throw new Refusal(`unknown-verb; known: ${INTEGRATIONS_VERBS.join(', ')}`);
+        if (options.args.some((arg) => hasControlCharacter(arg)))
+            throw new Refusal('malformed-argument-control-character');
+        const { values, positionals } = parseArgs({
+            args: options.args,
+            allowPositionals: true,
+            options: {
+                json: { type: 'boolean' },
+                ...(verb === 'list'
+                    ? {}
+                    : {
+                        yes: { type: 'boolean' },
+                        'dry-run': { type: 'boolean' },
+                        ...(verb === 'add'
+                            ? {
+                                harness: { type: 'string', multiple: true },
+                                required: { type: 'boolean' },
+                                version: { type: 'string' },
+                                adopt: { type: 'boolean' },
+                            }
+                            : {}),
+                    }),
+            },
+        });
+        const registry = options.registry ?? REGISTRY;
+        if (verb === 'list') {
+            if (positionals.length)
+                throw new Refusal('list-takes-no-provider');
+            return respond({ integrations: registry }, registry.map((entry) => `${entry.id}: ${entry.displayName}`).join('\n'));
+        }
+        if (positionals.length > 1 || (verb !== 'apply' && positionals.length !== 1))
+            throw new Refusal(verb === 'apply' ? 'at-most-one-id-required' : 'exactly-one-id-required');
+        const id = positionals[0];
+        if (id !== undefined && !registry.some((entry) => entry.id === id))
+            throw new Refusal('not-in-matrix');
+        if (values.adopt && id !== 'spec-kit')
+            throw new Refusal('adopt-only-for-spec-kit');
+        const [declarationFile, mcpFile, codexFile, manifestFile] = await Promise.all([
+            snapshot(options.cwd, DECLARATION_REL),
+            snapshot(options.cwd, MCP),
+            snapshot(options.cwd, CODEX_CONFIG),
+            snapshot(options.cwd, MANIFEST_REL),
+        ]);
+        const parsed = declarationFile.bytes === null
+            ? { status: 'ok', entries: [], rejected: [] }
+            : parseDeclaration(decode(declarationFile.bytes), registry);
+        if (parsed.status !== 'ok' || parsed.rejected.length)
+            throw new Refusal('declaration-invalid-or-rejected');
+        let entries = structuredClone(parsed.entries);
+        let targets = structuredClone(parsed.targets);
+        if (verb === 'add') {
+            const previous = entries.find((entry) => entry.id === id);
+            const requested = values.harness;
+            if (requested !== undefined &&
+                (!Array.isArray(requested) ||
+                    !requested.every((harness) => typeof harness === 'string') ||
+                    new Set(requested).size !== requested.length))
+                throw new Refusal('malformed-provider-selection');
+            const harnesses = [
+                ...new Set([
+                    ...(previous?.harnesses ?? []),
+                    ...(requested ?? previous?.harnesses ?? ['claude-code']),
+                ]),
+            ];
+            const candidate = {
+                ...previous,
+                id: id,
+                selected: true,
+                harnesses: harnesses,
+                ...(values.required !== undefined ? { required: values.required } : {}),
+                ...(values.version !== undefined ? { version: values.version } : {}),
+                ...(id === 'spec-kit' ? { version: values.version ?? SPEC_KIT_VERSION } : {}),
+            };
+            const checked = parseDeclaration(JSON.stringify({ schemaVersion: 1, integrations: [candidate] }), registry);
+            if (checked.status !== 'ok' || checked.rejected.length || checked.entries.length !== 1)
+                throw new Refusal('malformed-provider-selection');
+            entries = [...entries.filter((entry) => entry.id !== id), checked.entries[0]];
+        }
+        const selected = entries.filter((entry) => id === undefined || entry.id === id);
+        if (id !== undefined && !selected.length)
+            throw new Refusal('integration-not-declared');
+        const specKit = selected.find((entry) => entry.id === 'spec-kit');
+        let upstreamOptions;
+        let upstreamPlan = [];
+        if (specKit) {
+            if (specKit.version !== SPEC_KIT_VERSION || specKit.targets !== undefined)
+                throw new Refusal('spec-kit-pinned-version-and-upstream-ownership-required');
+            upstreamOptions = {
+                repoDir: options.cwd,
+                operation: verb,
+                harnesses: specKit.harnesses ?? [],
+                managed: parsed.entries.some((entry) => entry.id === 'spec-kit'),
+                adopt: values.adopt === true,
+                consent: false,
+            };
+            const planned = await runSpecKitLifecycle(upstreamOptions);
+            if (planned.reason !== 'consent-required')
+                throw new Refusal(planned.reason ?? 'upstream-plan-refused');
+            upstreamPlan = planned.plan;
+            if (verb === 'remove')
+                entries = entries.filter((entry) => entry.id !== 'spec-kit');
+        }
+        const selectedMcp = selected.filter((entry) => entry.id !== 'spec-kit');
+        const needsClaude = selectedMcp.some((entry) => entry.harnesses?.includes('claude-code'));
+        const servers = needsClaude ? { ...readConfig(mcpFile).mcpServers } : {};
+        const mcpChanges = new Map();
+        for (const entry of selectedMcp) {
+            if (entry.harnesses === undefined || entry.harnesses.length === 0)
+                throw new Refusal('harness-unsupported-or-pending');
+            if (!entry.harnesses.includes('claude-code')) {
+                if (verb === 'remove')
+                    entries = entries.filter((candidate) => candidate.id !== entry.id);
+                continue;
+            }
+            const { name, server } = serverFor(entry.id);
+            const exists = Object.hasOwn(servers, name);
+            const ownership = entry.targets?.['claude-code']?.entryHash;
+            if (exists &&
+                (ownership === undefined || hash(servers[name]) !== ownership || ownership !== hash(server)))
+                throw new Refusal('foreign-or-modified-mcp-entry');
+            if (verb === 'remove') {
+                if (!exists || ownership === undefined)
+                    throw new Refusal('owned-mcp-entry-absent');
+                delete servers[name];
+                entries = entries.filter((candidate) => candidate.id !== entry.id);
+                mcpChanges.set(name, undefined);
+            }
+            else {
+                if (!exists) {
+                    servers[name] = server;
+                    mcpChanges.set(name, server);
+                }
+                entry.targets = { ...entry.targets, 'claude-code': { entryHash: hash(server) } };
+            }
+        }
+        const codexSelected = selectedMcp.some((entry) => entry.harnesses?.includes('codex'));
+        let nextCodex = codexFile.bytes;
+        if (codexSelected) {
+            const fragment = selectedMcp
+                .filter((entry) => entry.harnesses?.includes('codex'))
+                .map((entry) => codexSection(entry.id))
+                .join('\n');
+            const manifest = manifestFile.bytes === null ? null : parseManifest(decode(manifestFile.bytes));
+            if (manifest === null)
+                throw new Refusal('release-manifest-unreadable');
+            const base = (await initFileContents(options.cwd, manifest.project, manifest.layers)).get(CODEX_CONFIG);
+            if (base === undefined)
+                throw new Refusal('release-codex-baseline-unavailable');
+            if (codexFile.bytes === null) {
+                if (verb !== 'apply' || targets?.codex === undefined)
+                    throw new Refusal('codex-config-absent-explicit-apply-required');
+            }
+            else if (targets?.codex !== undefined) {
+                if (sha256(codexFile.bytes) !== targets.codex.fileHash)
+                    throw new Refusal(`codex-config-conflict; managed provider fragment:\n${fragment}`);
+            }
+            else if (manifest.files[CODEX_CONFIG] !== sha256(codexFile.bytes)) {
+                throw new Refusal(`codex-config-not-release-baseline; managed provider fragment:\n${fragment}`);
+            }
+            nextCodex = renderCodexConfig(base, entries);
+            targets = { ...(targets ?? {}), codex: { fileHash: sha256(nextCodex) } };
+        }
+        const nextDeclaration = Buffer.from(serializeDeclaration(entries, targets));
+        if (nextDeclaration.length > MAX_DECLARATION_BYTES)
+            throw new Refusal('declaration-too-large');
+        const nextMcp = mcpChanges.size > 0
+            ? Buffer.from(editMcpServers(mcpFile.bytes === null ? '{\n  "mcpServers": {}\n}\n' : decode(mcpFile.bytes), mcpChanges))
+            : mcpFile.bytes;
+        if (nextMcp !== null && nextMcp.length > MAX_MCP_BYTES)
+            throw new Refusal('mcp-config-too-large');
+        const edits = [];
+        if (!equalBytes(mcpFile.bytes, nextMcp) && nextMcp !== null)
+            edits.push({ ...mcpFile, next: nextMcp });
+        if (!equalBytes(codexFile.bytes, nextCodex) && nextCodex !== null)
+            edits.push({ ...codexFile, next: nextCodex });
+        if (!equalBytes(declarationFile.bytes, nextDeclaration))
+            edits.push({ ...declarationFile, next: nextDeclaration });
+        const basicMemory = selected.some((entry) => entry.id === 'basic-memory');
+        const coexistence = basicMemory && (await hasMachineMemoryManifest(options.env ?? process.env))
+            ? ' existing Memory subsystem detected; Basic Memory can coexist, but this setup does not connect them.'
+            : '';
+        const basicBoundary = basicMemory
+            ? ' Basic Memory is a wiring-only preview: it configures local, per-machine storage only; does not automatically access Memory; does not synchronize across machines; and uvx is a launcher, not a verified runtime.'
+            : '';
+        const plan = `${verb}: ${selected.map((entry) => entry.id).join(', ') || 'no integrations'}; write ${edits.map((edit) => edit.rel).join(', ') || 'nothing'}. MCP wiring does not verify authorization, connectivity or trust.${basicBoundary}${coexistence}${upstreamPlan.length ? '\n' + upstreamPlan.join('\n') : ''}`;
+        if (values['dry-run'])
+            return respond({ outcome: 'planned', dryRun: true, changed: false, plan }, plan);
+        if (!values.yes &&
+            (json ||
+                options.isTTY === false ||
+                options.confirm === undefined ||
+                !(await options.confirm(plan))))
+            throw new Refusal('yes-required-for-json-or-noninteractive');
+        const preimages = [declarationFile, mcpFile, codexFile, manifestFile];
+        await checkSnapshots(options.cwd, preimages);
+        if (upstreamOptions) {
+            const rechecked = await runSpecKitLifecycle(upstreamOptions);
+            if (rechecked.reason !== 'consent-required' ||
+                JSON.stringify(rechecked.plan) !== JSON.stringify(upstreamPlan))
+                throw new Refusal('changed-since-plan');
+            const result = await (options.runSpecKit ?? runSpecKitLifecycle)({
+                ...upstreamOptions,
+                consent: true,
+            });
+            observed = result.observed;
+            if (!result.ok)
+                throw new Refusal(result.reason ?? 'upstream-incomplete-use-adopt-and-status');
+            upstreamApplied = true;
+        }
+        // An upstream lifecycle may rewrite files this operation neither writes nor
+        // reads: Spec Kit regenerates .codex/config.toml, as CRLF on Windows. The
+        // Codex config and release manifest are inputs only when a Codex MCP entry
+        // is rendered, so only then must they still match the plan.
+        await applyEdits(options.cwd, upstreamApplied && !codexSelected ? [declarationFile, mcpFile] : preimages, edits);
+        return respond({
+            outcome: verb === 'remove' ? 'removed' : 'written',
+            changed: edits.length !== 0,
+            ...(id === undefined ? {} : { id }),
+            integrations: entries,
+            ...(observed === undefined ? {} : { observed }),
+        }, plan);
+    }
+    catch (error) {
+        const failure = error instanceof Refusal ? error.message : 'invalid-arguments-or-unreadable-state';
+        const reason = upstreamApplied
+            ? `upstream-success-intent-not-recorded; use adopt/status; ${failure}`
+            : failure;
+        const diagnosis = observed === undefined ? '' : `\nUpstream status: ${JSON.stringify(observed)}`;
+        return respond({ outcome: 'refused', reason, ...(observed === undefined ? {} : { observed }) }, `setup: ${reason}${diagnosis}`, 1);
+    }
+}

package/packages/cli/dist/commands/memory.js

@@ -3,7 +3,11 @@
 // resolves the executable from the machine subsystem manifest `setup` wrote
 // (RP-147), performs `--version --json` first, refuses a foreign contract
 // major with exit 4 before doctor/load ever run, and otherwise hands the verb
-// and its arguments to Memory verbatim and returns Memory's answer unchanged.
+// and its arguments to Memory and returns Memory's answer unchanged. The one
+// thing it adds to the arguments: a `load` that names no `--timeout-ms` gets
+// Memory's default internal deadline appended (`deadlinesFor`, RP-183);
+// everything the caller wrote passes through verbatim, and `doctor` is never
+// touched.
 //
 // What it never does, by construction: import Memory code, read Memory's
 // storage tree, or reinterpret a doctor/load payload — the only Memory bytes
@@ -22,8 +26,62 @@
 import { execFileRunner } from './setup.js';
 import { MEMORY_CONTRACT_MAJOR, SubsystemsError, handshake, readSubsystemsManifest, subsystemsManifestPath, } from '../lib/subsystems.js';
 const MEMORY_VERBS = ['doctor', 'load'];
-/** doctor/load do real work; the caller-supplied `--timeout-ms` is Memory's own bound. */
+/**
+ * The outer deadline: the rig kills the Memory child after this many ms. It is
+ * the consumer's bound, and it should not be the one that fires first — a kill
+ * leaves no JSON answer behind. So `load` always carries an INTERNAL deadline
+ * as well (RP-183): Memory's own `--timeout-ms`, which per the Memory owner
+ * (RP-183, Jira) it answers with a typed result instead of being killed.
+ * `doctor` accepts no such flag per the same source — its args are never
+ * touched. Pinned in packages/cli/test/memory.test.ts, "RP-183".
+ */
 const VERB_TIMEOUT_MS = 60_000;
+/** Memory's default internal deadline when the caller names none. */
+const DEFAULT_MEMORY_TIMEOUT_MS = 45_000;
+/**
+ * Headroom the outer deadline keeps above an explicit internal one. Sized per
+ * the Memory owner (RP-183, Jira): Memory's Windows cleanup may return up to
+ * 10 s after its own deadline fired; the rest is spawn overhead. The rig does
+ * not measure that lag itself.
+ */
+const OUTER_MARGIN_MS = 15_000;
+/**
+ * The largest delay `execFile`'s timer can hold: Node clamps a larger
+ * `setTimeout` to ONE millisecond, which would make the outer kill fire first
+ * — the inversion this whole helper exists to prevent. A caller who asks for
+ * more than ~24.8 days gets this ceiling as the outer deadline.
+ */
+const MAX_TIMER_MS = 2_147_483_647;
+const TIMEOUT_FLAG = '--timeout-ms';
+/** Memory's own grammar for the value: a positive integer, milliseconds. */
+const TIMEOUT_VALUE = /^[1-9][0-9]*$/;
+/**
+ * The verb's argument list and outer deadline. `load` with no `--timeout-ms`
+ * gets the default appended; a caller-owned flag — any spelling — passes
+ * through verbatim, and only a well-formed `--timeout-ms <value>` pair can
+ * raise the outer deadline above it. Memory owns the refusal of a malformed
+ * value, so the rig neither corrects nor drops one.
+ */
+const deadlinesFor = (verb, args) => {
+    if (verb !== 'load')
+        return { args: [...args], timeoutMs: VERB_TIMEOUT_MS };
+    const at = args.findIndex((arg) => arg === TIMEOUT_FLAG || arg.startsWith(`${TIMEOUT_FLAG}=`));
+    if (at === -1) {
+        return {
+            args: [...args, TIMEOUT_FLAG, String(DEFAULT_MEMORY_TIMEOUT_MS)],
+            timeoutMs: VERB_TIMEOUT_MS,
+        };
+    }
+    const value = args[at] === TIMEOUT_FLAG ? args[at + 1] : undefined;
+    const internal = value !== undefined && TIMEOUT_VALUE.test(value) ? Number(value) : null;
+    // A digit string too long for a safe integer — or for a double at all —
+    // still lands on the ceiling: `Number` yields a huge float or Infinity, and
+    // `Math.min` with the ceiling holds either.
+    const timeoutMs = internal !== null
+        ? Math.min(Math.max(VERB_TIMEOUT_MS, internal + OUTER_MARGIN_MS), MAX_TIMER_MS)
+        : VERB_TIMEOUT_MS;
+    return { args: [...args], timeoutMs };
+};
 const jsonLine = (payload) => `${JSON.stringify(payload)}\n`;
 const isVerb = (verb) => MEMORY_VERBS.includes(verb);
 export async function runMemory(options) {
@@ -106,8 +164,9 @@ export async function runMemory(options) {
             stderr: `memory: the handshake did not answer as the manifest promised (${result.reason}); ${options.verb} was not run\n`,
         };
     const [command, script] = entry.invocation;
-    const answer = await run(command, [script, options.verb, ...options.args], {
-        timeoutMs: VERB_TIMEOUT_MS,
+    const deadlines = deadlinesFor(options.verb, options.args);
+    const answer = await run(command, [script, options.verb, ...deadlines.args], {
+        timeoutMs: deadlines.timeoutMs,
     });
     if (answer.spawnError)
         return {

package/packages/cli/dist/commands/setup-wizard.js

@@ -0,0 +1,61 @@
+import { createInterface } from 'node:readline/promises';
+import { runIntegrationsCommand } from './integrations.js';
+import { REGISTRY } from '../integrations/registry.js';
+const PROVIDERS = REGISTRY.map((provider) => provider.id);
+const HARNESSES = ['claude-code', 'codex', 'both'];
+function refused(json, reason) {
+    return {
+        exitCode: 1,
+        stdout: json
+            ? `${JSON.stringify({ schemaVersion: 1, command: 'setup', outcome: 'refused', reason })}\n`
+            : '',
+        stderr: json ? '' : `setup: ${reason}\n`,
+    };
+}
+function selected(value, choices) {
+    if (value === undefined)
+        return undefined;
+    const index = Number(value);
+    if (Number.isInteger(index) && index >= 1 && index <= choices.length)
+        return choices[index - 1];
+    return choices.includes(value) ? value : undefined;
+}
+async function ask(step) {
+    const choices = step === 'provider' ? PROVIDERS : HARNESSES;
+    const label = step === 'provider' ? 'integration provider' : 'harness';
+    const display = choices.map((choice, index) => `${index + 1}) ${choice}`).join(', ');
+    const readline = createInterface({ input: process.stdin, output: process.stderr });
+    try {
+        const answer = await readline.question(`Select ${label} (${display}; Enter to cancel): `);
+        return answer.trim() === '' ? undefined : answer.trim();
+    }
+    finally {
+        readline.close();
+    }
+}
+/** Human-only selection surface; mutations remain in the deterministic command. */
+export async function runSetupWizard(options) {
+    const json = options.args.includes('--json');
+    if (json)
+        return refused(true, 'setup-wizard-requires-an-interactive-terminal');
+    if (!options.isTTY)
+        return refused(false, 'setup-wizard-requires-an-interactive-terminal');
+    if (options.args.length !== 0)
+        return refused(false, 'setup-wizard-takes-no-options');
+    const prompt = options.promptChoice ?? ask;
+    const provider = selected(await prompt('provider'), PROVIDERS);
+    if (provider === undefined)
+        return { exitCode: 0, stdout: 'setup: cancelled\n', stderr: '' };
+    const harness = selected(await prompt('harness'), HARNESSES);
+    if (harness === undefined)
+        return { exitCode: 0, stdout: 'setup: cancelled\n', stderr: '' };
+    const selectedHarnesses = harness === 'both' ? ['claude-code', 'codex'] : [harness];
+    const args = [provider, ...selectedHarnesses.flatMap((item) => ['--harness', item])];
+    return (options.runIntegration ?? runIntegrationsCommand)({
+        verb: 'add',
+        args,
+        cwd: options.cwd,
+        isTTY: options.isTTY,
+        confirm: options.confirm,
+    });
+}