outsrc 0.2.0

package/dist/cli.js

@@ -0,0 +1,302 @@
+#!/usr/bin/env node
+import { defaultConfigPath, defaultHome, loadConfigFile } from "./config.js";
+import { migrateLegacy } from "./migrate.js";
+import { changeSetting, listSettings } from "./settings.js";
+import { defaultInitEnv, parseInitArgs, runInit } from "./init.js";
+import { createMailbox } from "./mailbox.js";
+import { installEngine, managedScript, readLock, resolveCommit, writeLockEntry } from "./engines.js";
+import { checkPluginContract, pluginVersion } from "./plugin-contract.js";
+import { isPluginAdapter, resolvePluginScript } from "./plugins.js";
+import { DEFAULT_CALLER, parseCaller } from "./types.js";
+function pluginReports(explicit) {
+    return ["codex-plugin", "grok-plugin"].flatMap((adapter) => {
+        const script = explicit[adapter] ?? managedScript(defaultHome(), adapter) ?? resolvePluginScript(adapter);
+        return script ? [checkPluginContract(adapter, script)] : [];
+    });
+}
+function flagValue(argv, name) {
+    const index = argv.indexOf(name);
+    return index >= 0 ? argv[index + 1] : undefined;
+}
+function hasFlag(argv, name) {
+    return argv.includes(name);
+}
+function takeFlag(argv, name) {
+    const index = argv.indexOf(name);
+    if (index < 0)
+        return { rest: argv };
+    const value = argv[index + 1];
+    if (value === undefined || value.startsWith("-"))
+        throw new Error(`${name} needs a value`);
+    return { value, rest: [...argv.slice(0, index), ...argv.slice(index + 2)] };
+}
+function parseMailboxArgs(argv) {
+    let rest = [...argv];
+    const callerFlag = takeFlag(rest, "--caller");
+    rest = callerFlag.rest;
+    const json = hasFlag(rest, "--json");
+    rest = rest.filter((arg) => arg !== "--json");
+    const names = ["--repo", "--target", "--message", "--thread", "--thread-id", "--request-id", "--model", "--effort", "--kind", "--base", "--ref", "--run-id", "--offset", "--limit"];
+    const flags = {};
+    for (const name of names) {
+        const taken = takeFlag(rest, name);
+        rest = taken.rest;
+        if (taken.value !== undefined)
+            flags[name] = taken.value;
+    }
+    if (rest.some((arg) => arg.startsWith("-")))
+        throw new Error(`unknown option: ${rest.find((arg) => arg.startsWith("-"))}`);
+    return {
+        caller: callerFlag.value !== undefined ? parseCaller(callerFlag.value) : undefined,
+        json,
+        flags,
+        positionals: rest,
+    };
+}
+function writeJson(body, pretty = true) {
+    process.stdout.write(`${pretty ? JSON.stringify(body, null, 2) : JSON.stringify(body)}\n`);
+}
+const HELP = `outsrc init [--repo <path>]... [--yes] [--json] [--plugins|--no-plugins] [--local claude,codex,grok]
+            [--max-jobs <n|unlimited>] [--max-run-minutes <n|unlimited>]
+       config [list] | config set <key> <value> | config unset <key>
+       doctor | list_repos | list_targets | targets | threads | prune | migrate
+       plugins [--codex <script>] [--grok <script>]
+       engines pin <codex-plugin|grok-plugin> <commit|branch|tag>
+       send --repo <alias> --target <name> --message <text> [--caller <id>] [--json]
+            [--thread-id <id>] [--request-id <id>] [--model <m>] [--effort <e>]
+            [--kind task|review|adversarial_review] [--base <ref>] [--ref <ref>]
+       inbox <thread_id> [--caller <id>] [--json]
+       history <thread_id> [--caller <id>] [--json]
+       log <thread_id> [--run-id <id>] [--offset <n>] [--limit <n>] [--caller <id>] [--json]
+       diff <thread_id> [--limit <n>] [--caller <id>] [--json]
+       stop <thread_id> [--caller <id>] [--json]
+       discard <thread_id> [--caller <id>] [--json]
+
+init sets up config and optional local MCP registration for local CLIs.
+Public install is the Outsrc bot from Bot Exchange; this CLI is for bot authors and advanced operators.
+
+Mailbox commands print JSON (same shapes as the stdio MCP tools). Pass --caller so each
+bot only sees its own threads; omit it on doctor/list_*/threads to act as the owner.
+`;
+const command = process.argv[2] ?? "help";
+try {
+    if (command === "help" || command === "--help" || command === "-h") {
+        process.stdout.write(HELP);
+    }
+    else if (command === "init") {
+        const options = parseInitArgs(process.argv.slice(3));
+        const env = defaultInitEnv(defaultConfigPath(defaultHome()), options.json);
+        try {
+            process.exitCode = await runInit(env, options);
+        }
+        finally {
+            env.close();
+        }
+    }
+    else if (command === "engines") {
+        const [sub, adapter, ref] = process.argv.slice(3);
+        if (sub !== "pin" || !adapter || !isPluginAdapter(adapter) || !ref)
+            throw new Error("usage: outsrc engines pin <codex-plugin|grok-plugin> <commit|branch|tag>");
+        const current = readLock()[adapter];
+        if (!current)
+            throw new Error(`engines.lock.json has no ${adapter} entry`);
+        const commit = resolveCommit(current.source, ref);
+        const script = installEngine(defaultHome(), adapter, { ...current, commit });
+        const report = checkPluginContract(adapter, script);
+        if (report.problems.length) {
+            writeJson({ pinned: false, report });
+            process.exitCode = 1;
+        }
+        else {
+            const entry = { ...current, commit, version: pluginVersion(script) ?? "unknown" };
+            writeLockEntry(adapter, entry);
+            writeJson({ pinned: true, entry, next: "Run npm run smoke:plugins. Commit engines.lock.json if it passes; revert it if not." });
+        }
+    }
+    else if (command === "config") {
+        const [sub, key, value, ...extra] = process.argv.slice(3).filter((arg) => arg !== "--json");
+        const configPath = defaultConfigPath(defaultHome());
+        if (sub === undefined || sub === "list")
+            writeJson(listSettings(configPath));
+        else if ((sub === "set" && key && value !== undefined && extra.length === 0) || (sub === "unset" && key && value === undefined)) {
+            const change = changeSetting(configPath, key, sub === "set" ? value : undefined);
+            writeJson(change);
+            if (!change.ok)
+                process.exitCode = 1;
+            else if (change.warning)
+                process.stderr.write(`Note: ${change.warning}\n`);
+        }
+        else
+            throw new Error("usage: outsrc config [list] | config set <key> <value> | config unset <key>");
+    }
+    else if (command === "plugins") {
+        const flags = process.argv.slice(3);
+        const codex = flagValue(flags, "--codex");
+        const grok = flagValue(flags, "--grok");
+        const reports = pluginReports({ ...(codex ? { "codex-plugin": codex } : {}), ...(grok ? { "grok-plugin": grok } : {}) });
+        writeJson({ plugins: reports });
+        if (reports.length === 0 || reports.some((report) => report.status !== "ok"))
+            process.exitCode = 1;
+    }
+    else {
+        const home = defaultHome();
+        const config = loadConfigFile(defaultConfigPath(home));
+        const parsed = parseMailboxArgs(process.argv.slice(3));
+        // Owner CLI (no --caller) sees every thread for doctor/list/threads/prune.
+        // Mailbox mutations and per-thread reads default to "local" when --caller is omitted.
+        const ownerCommands = new Set(["doctor", "list_repos", "repos", "list_targets", "targets", "threads", "prune", "migrate"]);
+        const caller = parsed.caller ?? (ownerCommands.has(command) ? undefined : DEFAULT_CALLER);
+        const box = createMailbox({ home, config, ...(caller !== undefined ? { caller } : {}) });
+        switch (command) {
+            case "doctor": {
+                const targets = box.listTargets().targets;
+                const plugins = Object.values(config.targets).flatMap((target) => target.adapter && isPluginAdapter(target.adapter) && target.command ? [checkPluginContract(target.adapter, target.command)] : []);
+                const report = {
+                    node: process.version,
+                    config: defaultConfigPath(home),
+                    repositories: box.listRepos().repos,
+                    targets,
+                    plugins,
+                    note: "Checks configuration, executable discovery and the vendor plugin CLI contract. Does not authenticate providers or establish an execution security boundary.",
+                };
+                writeJson(report);
+                if (targets.some((target) => !target.available) || plugins.some((plugin) => plugin.status === "broken"))
+                    process.exitCode = 1;
+                break;
+            }
+            case "list_repos":
+            case "repos":
+                writeJson(box.listRepos());
+                break;
+            case "list_targets":
+            case "targets":
+                writeJson(box.listTargets());
+                break;
+            case "threads":
+                writeJson(box.threads());
+                break;
+            case "migrate": {
+                const migrated = migrateLegacy({ home, config });
+                writeJson(migrated);
+                if (migrated.skipped.length)
+                    process.exitCode = 1;
+                break;
+            }
+            case "prune":
+                writeJson(box.prune());
+                break;
+            case "send": {
+                const message = parsed.flags["--message"] ?? parsed.positionals[0];
+                if (!message)
+                    throw new Error("send needs --message <text>");
+                const kind = parsed.flags["--kind"];
+                const threadId = parsed.flags["--thread-id"] ?? parsed.flags["--thread"];
+                const input = {
+                    message,
+                    ...(parsed.flags["--repo"] !== undefined ? { repo: parsed.flags["--repo"] } : {}),
+                    ...(parsed.flags["--target"] !== undefined ? { target: parsed.flags["--target"] } : {}),
+                    ...(threadId !== undefined ? { thread_id: threadId } : {}),
+                    ...(parsed.flags["--request-id"] !== undefined ? { request_id: parsed.flags["--request-id"] } : {}),
+                    ...(parsed.flags["--model"] !== undefined ? { model: parsed.flags["--model"] } : {}),
+                    ...(parsed.flags["--effort"] !== undefined ? { effort: parsed.flags["--effort"] } : {}),
+                    ...(kind === "task" || kind === "review" || kind === "adversarial_review" ? { kind } : {}),
+                    ...(parsed.flags["--base"] !== undefined ? { base: parsed.flags["--base"] } : {}),
+                    ...(parsed.flags["--ref"] !== undefined ? { ref: parsed.flags["--ref"] } : {}),
+                };
+                const sent = await box.send(input);
+                if (sent.ok)
+                    writeJson({ delivered: true, thread_id: sent.thread_id, run_id: sent.run_id });
+                else {
+                    writeJson(sent);
+                    process.exitCode = 1;
+                }
+                break;
+            }
+            case "inbox": {
+                const threadId = parsed.positionals[0] ?? parsed.flags["--thread-id"] ?? parsed.flags["--thread"];
+                if (!threadId)
+                    throw new Error("inbox needs <thread_id>");
+                const result = box.inbox(threadId);
+                writeJson(result);
+                if (!result.ok)
+                    process.exitCode = 1;
+                break;
+            }
+            case "history": {
+                const threadId = parsed.positionals[0] ?? parsed.flags["--thread-id"] ?? parsed.flags["--thread"];
+                if (!threadId)
+                    throw new Error("history needs <thread_id>");
+                const result = box.history(threadId);
+                writeJson(result);
+                if (!result.ok)
+                    process.exitCode = 1;
+                break;
+            }
+            case "log": {
+                const threadId = parsed.positionals[0] ?? parsed.flags["--thread-id"] ?? parsed.flags["--thread"];
+                if (!threadId)
+                    throw new Error("log needs <thread_id>");
+                const offset = parsed.flags["--offset"] !== undefined ? Number(parsed.flags["--offset"]) : undefined;
+                const limit = parsed.flags["--limit"] !== undefined ? Number(parsed.flags["--limit"]) : undefined;
+                if (offset !== undefined && !Number.isFinite(offset))
+                    throw new Error("--offset must be a number");
+                if (limit !== undefined && !Number.isFinite(limit))
+                    throw new Error("--limit must be a number");
+                const result = box.log({
+                    thread_id: threadId,
+                    ...(parsed.flags["--run-id"] !== undefined ? { run_id: parsed.flags["--run-id"] } : {}),
+                    ...(offset !== undefined ? { offset } : {}),
+                    ...(limit !== undefined ? { limit } : {}),
+                });
+                writeJson(result);
+                if (!result.ok)
+                    process.exitCode = 1;
+                break;
+            }
+            case "diff": {
+                const threadId = parsed.positionals[0] ?? parsed.flags["--thread-id"] ?? parsed.flags["--thread"];
+                if (!threadId)
+                    throw new Error("diff needs <thread_id>");
+                const limit = parsed.flags["--limit"] !== undefined ? Number(parsed.flags["--limit"]) : undefined;
+                if (limit !== undefined && !Number.isFinite(limit))
+                    throw new Error("--limit must be a number");
+                const result = box.diff({ thread_id: threadId, ...(limit !== undefined ? { limit } : {}) });
+                writeJson(result);
+                if ("ok" in result && result.ok === false)
+                    process.exitCode = 1;
+                break;
+            }
+            case "stop": {
+                const threadId = parsed.positionals[0] ?? parsed.flags["--thread-id"] ?? parsed.flags["--thread"];
+                if (!threadId)
+                    throw new Error("stop needs <thread_id>");
+                const result = box.stop(threadId);
+                writeJson(result);
+                if (!result.ok)
+                    process.exitCode = 1;
+                break;
+            }
+            case "discard": {
+                const threadId = parsed.positionals[0] ?? parsed.flags["--thread-id"] ?? parsed.flags["--thread"];
+                if (!threadId)
+                    throw new Error("discard needs <thread_id>");
+                const result = box.discard(threadId);
+                writeJson(result);
+                if (!result.ok)
+                    process.exitCode = 1;
+                break;
+            }
+            default:
+                throw new Error(`Unknown command: ${command}`);
+        }
+    }
+}
+catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    process.exitCode = 1;
+    const mailbox = new Set(["send", "inbox", "history", "log", "diff", "stop", "discard"]);
+    if (mailbox.has(command))
+        process.stdout.write(`${JSON.stringify({ ok: false, error: message }, null, 2)}\n`);
+    else
+        process.stderr.write(`${message}\n`);
+}

package/dist/config.d.ts

@@ -0,0 +1,46 @@
+import { z } from "zod";
+import type { Config } from "./types.js";
+export declare const ConfigSchema: z.ZodObject<{
+    limits: z.ZodDefault<z.ZodObject<{
+        max_jobs: z.ZodOptional<z.ZodUnion<readonly [z.ZodNumber, z.ZodLiteral<"unlimited">]>>;
+        max_run_minutes: z.ZodOptional<z.ZodUnion<readonly [z.ZodNumber, z.ZodLiteral<"unlimited">]>>;
+    }, z.core.$strict>>;
+    repos: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        alias: z.ZodString;
+        path: z.ZodString;
+        setup: z.ZodOptional<z.ZodArray<z.ZodArray<z.ZodString>>>;
+        auto_commit: z.ZodOptional<z.ZodBoolean>;
+        retention_days: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>>;
+    targets: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodObject<{
+        adapter: z.ZodOptional<z.ZodEnum<{
+            claude: "claude";
+            codex: "codex";
+            "codex-plugin": "codex-plugin";
+            custom: "custom";
+            grok: "grok";
+            "grok-plugin": "grok-plugin";
+        }>>;
+        command: z.ZodOptional<z.ZodString>;
+        args: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        permissions: z.ZodOptional<z.ZodEnum<{
+            ask: "ask";
+            auto: "auto";
+        }>>;
+        models: z.ZodOptional<z.ZodObject<{
+            default: z.ZodString;
+            allowed: z.ZodArray<z.ZodString>;
+        }, z.core.$strip>>;
+        effort: z.ZodOptional<z.ZodObject<{
+            default: z.ZodString;
+            allowed: z.ZodArray<z.ZodString>;
+        }, z.core.$strip>>;
+        description: z.ZodOptional<z.ZodString>;
+        cost_note: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>>;
+}, z.core.$strip>;
+export declare function loadConfigFile(path: string): Config;
+/** Validate a parsed config document. Throws with the first problem. */
+export declare function configFromDocument(document: unknown, path: string): Config;
+export declare function defaultHome(): string;
+export declare function defaultConfigPath(home?: string): string;

package/dist/config.js

@@ -0,0 +1,87 @@
+import { readFileSync } from "node:fs";
+import { parse } from "smol-toml";
+import { z } from "zod";
+import { dirname } from "node:path";
+import { managedScript } from "./engines.js";
+import { isPluginAdapter, realScript, resolvePluginScript } from "./plugins.js";
+import { DEFAULT_LIMITS } from "./limits.js";
+const Options = z.object({ default: z.string(), allowed: z.array(z.string()).min(1) })
+    .refine((options) => options.allowed.includes(options.default), { message: "default must be one of allowed" });
+const TargetSchema = z.object({
+    adapter: z.enum(["claude", "codex", "grok", "custom", "codex-plugin", "grok-plugin"]).optional(),
+    command: z.string().min(1).optional(),
+    args: z.array(z.string()).default([]),
+    permissions: z.enum(["auto", "ask"]).optional(),
+    models: Options.optional(),
+    effort: Options.optional(),
+    description: z.string().optional(),
+    cost_note: z.string().optional(),
+});
+// A positive whole number, or "unlimited".
+const Limit = z.union([z.number().int().positive(), z.literal("unlimited")]);
+export const ConfigSchema = z.object({
+    limits: z.object({ max_jobs: Limit.optional(), max_run_minutes: Limit.optional() }).strict().default({}),
+    repos: z.array(z.object({
+        alias: z.string().min(1),
+        path: z.string().min(1),
+        setup: z.array(z.array(z.string()).min(1)).optional(),
+        auto_commit: z.boolean().optional(),
+        retention_days: z.number().positive().optional(),
+    })).default([]),
+    targets: z.record(z.string(), TargetSchema).default({}),
+});
+export function loadConfigFile(path) {
+    let raw;
+    try {
+        raw = readFileSync(path, "utf8");
+    }
+    catch {
+        throw new Error(`config not found: ${path}`);
+    }
+    return configFromDocument(parse(raw), path);
+}
+/** Validate a parsed config document. Throws with the first problem. */
+export function configFromDocument(document, path) {
+    const parsed = ConfigSchema.parse(document);
+    const repos = parsed.repos.map((repo) => ({
+        alias: repo.alias,
+        path: repo.path,
+        ...(repo.setup !== undefined ? { setup: repo.setup } : {}),
+        ...(repo.auto_commit !== undefined ? { autoCommit: repo.auto_commit } : {}),
+        ...(repo.retention_days !== undefined ? { retentionDays: repo.retention_days } : {}),
+    }));
+    const targets = {};
+    for (const [name, target] of Object.entries(parsed.targets)) {
+        const adapter = target.adapter;
+        let command = target.command;
+        if (command === undefined) {
+            // An unresolved plugin keeps an empty command so list_targets reports it unavailable instead of failing startup.
+            // outsrc's pinned engine wins; a Claude Code install of the same plugin is the fallback.
+            if (adapter !== undefined && isPluginAdapter(adapter))
+                command = managedScript(dirname(path), adapter) ?? resolvePluginScript(adapter) ?? "";
+            else
+                throw new Error(`target ${name} needs a command`);
+        }
+        else if (adapter !== undefined && isPluginAdapter(adapter)) {
+            command = realScript(command);
+        }
+        targets[name] = {
+            command,
+            args: target.args,
+            ...(target.adapter !== undefined ? { adapter: target.adapter } : {}),
+            ...(target.permissions !== undefined ? { permissions: target.permissions } : {}),
+            ...(target.models !== undefined ? { models: target.models } : {}),
+            ...(target.effort !== undefined ? { effort: target.effort } : {}),
+            ...(target.description !== undefined ? { description: target.description } : {}),
+            ...(target.cost_note !== undefined ? { costNote: target.cost_note } : {}),
+        };
+    }
+    const limit = (value, fallback) => value === "unlimited" ? null : value ?? fallback;
+    const limits = {
+        maxJobs: limit(parsed.limits.max_jobs, DEFAULT_LIMITS.max_jobs),
+        maxRunMinutes: limit(parsed.limits.max_run_minutes, DEFAULT_LIMITS.max_run_minutes),
+    };
+    return { repos, targets, limits };
+}
+export function defaultHome() { return process.env.OUTSRC_HOME ?? `${process.env.HOME}/.outsrc`; }
+export function defaultConfigPath(home = defaultHome()) { return `${home}/config.toml`; }

package/dist/engines.d.ts

@@ -0,0 +1,44 @@
+import { z } from "zod";
+import { type PluginAdapter } from "./plugins.js";
+export declare const LOCK_FILE: string;
+declare const EntrySchema: z.ZodObject<{
+    source: z.ZodString;
+    path: z.ZodString;
+    version: z.ZodString;
+    commit: z.ZodString;
+}, z.core.$strip>;
+export type LockEntry = z.infer<typeof EntrySchema>;
+declare const LockSchema: z.ZodObject<{
+    "codex-plugin": z.ZodOptional<z.ZodObject<{
+        source: z.ZodString;
+        path: z.ZodString;
+        version: z.ZodString;
+        commit: z.ZodString;
+    }, z.core.$strip>>;
+    "grok-plugin": z.ZodOptional<z.ZodObject<{
+        source: z.ZodString;
+        path: z.ZodString;
+        version: z.ZodString;
+        commit: z.ZodString;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type EngineLock = z.infer<typeof LockSchema>;
+export declare function readLock(file?: string): EngineLock;
+export declare function writeLockEntry(adapter: PluginAdapter, entry: LockEntry, file?: string): void;
+export declare function managedScript(home: string, adapter: PluginAdapter, lock?: {
+    "codex-plugin"?: {
+        source: string;
+        path: string;
+        version: string;
+        commit: string;
+    } | undefined;
+    "grok-plugin"?: {
+        source: string;
+        path: string;
+        version: string;
+        commit: string;
+    } | undefined;
+}): string | null;
+export declare function installEngine(home: string, adapter: PluginAdapter, entry: LockEntry): string;
+export declare function resolveCommit(source: string, ref: string): string;
+export {};

package/dist/engines.js

@@ -0,0 +1,69 @@
+import { execFileSync } from "node:child_process";
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { ensureOutsrcHome } from "./fs-home.js";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { z } from "zod";
+import { ENGINES, realScript } from "./plugins.js";
+// The lock pins each vendor plugin engine to one commit that passed npm run smoke:plugins.
+export const LOCK_FILE = join(dirname(fileURLToPath(import.meta.url)), "..", "engines.lock.json");
+const COMMIT = /^[0-9a-f]{40}$/;
+const EntrySchema = z.object({ source: z.string().min(1), path: z.string().min(1), version: z.string().min(1), commit: z.string().regex(COMMIT) });
+const LockSchema = z.object({ "codex-plugin": EntrySchema.optional(), "grok-plugin": EntrySchema.optional() });
+export function readLock(file = LOCK_FILE) {
+    return existsSync(file) ? LockSchema.parse(JSON.parse(readFileSync(file, "utf8"))) : {};
+}
+export function writeLockEntry(adapter, entry, file = LOCK_FILE) {
+    // Package lock lives in the repo/install tree, not ~/.outsrc.
+    writeFileSync(file, `${JSON.stringify({ ...readLock(file), [adapter]: EntrySchema.parse(entry) }, null, 2)}\n`);
+}
+function engineRoot(home, adapter, commit) {
+    return join(home, "engines", adapter, commit);
+}
+export function managedScript(home, adapter, lock = readLock()) {
+    const entry = lock[adapter];
+    if (!entry)
+        return null;
+    const script = join(engineRoot(home, adapter, entry.commit), ENGINES[adapter].script);
+    return existsSync(script) ? realScript(script) : null;
+}
+function git(args) {
+    return execFileSync("git", args, { encoding: "utf8", stdio: "pipe", env: { ...process.env, GIT_TERMINAL_PROMPT: "0" } });
+}
+// Fetches exactly the pinned commit and moves the plugin folder into place in one rename, so a rerun or a crash
+// never leaves a half-written engine where resolution would find it.
+export function installEngine(home, adapter, entry) {
+    const root = engineRoot(home, adapter, entry.commit);
+    const script = join(root, ENGINES[adapter].script);
+    if (existsSync(script))
+        return realScript(script);
+    ensureOutsrcHome(home);
+    mkdirSync(dirname(root), { recursive: true, mode: 0o700 });
+    const temp = mkdtempSync(join(dirname(root), ".fetch-"));
+    try {
+        git(["init", "-q", temp]);
+        git(["-C", temp, "fetch", "-q", "--depth", "1", entry.source, entry.commit]);
+        git(["-C", temp, "checkout", "-q", "FETCH_HEAD"]);
+        const head = git(["-C", temp, "rev-parse", "HEAD"]).trim();
+        if (head !== entry.commit)
+            throw new Error(`fetched ${head}, expected ${entry.commit}`);
+        const plugin = join(temp, entry.path);
+        if (!existsSync(join(plugin, ENGINES[adapter].script)))
+            throw new Error(`${entry.source} at ${entry.commit} has no ${entry.path}/${ENGINES[adapter].script}`);
+        if (!existsSync(root))
+            renameSync(plugin, root);
+    }
+    finally {
+        rmSync(temp, { recursive: true, force: true });
+    }
+    return realScript(script);
+}
+export function resolveCommit(source, ref) {
+    if (COMMIT.test(ref))
+        return ref;
+    const line = git(["ls-remote", source, ref]).split("\n").find((text) => text.trim());
+    const commit = line?.split(/\s+/)[0];
+    if (!commit || !COMMIT.test(commit))
+        throw new Error(`${source} has no ref ${ref}`);
+    return commit;
+}

package/dist/fs-home.d.ts

@@ -0,0 +1,7 @@
+import { type WriteFileOptions } from "node:fs";
+/** Create ~/.outsrc (or OUTSRC_HOME) as 0700. */
+export declare function ensureOutsrcHome(home: string): void;
+/** Write a file under the outsrc home with mode 0600. */
+export declare function writeHomeFile(path: string, data: string | Uint8Array, options?: WriteFileOptions): void;
+/** Append to a file under the outsrc home with mode 0600 (created if missing). */
+export declare function appendHomeFile(path: string, data: string | Uint8Array): void;

package/dist/fs-home.js

@@ -0,0 +1,28 @@
+import { appendFileSync, chmodSync, mkdirSync, writeFileSync } from "node:fs";
+/** Create ~/.outsrc (or OUTSRC_HOME) as 0700. */
+export function ensureOutsrcHome(home) {
+    mkdirSync(home, { recursive: true, mode: 0o700 });
+    try {
+        chmodSync(home, 0o700);
+    }
+    catch { /* best-effort on platforms that ignore mode */ }
+}
+/** Write a file under the outsrc home with mode 0600. */
+export function writeHomeFile(path, data, options) {
+    const opts = typeof options === "string"
+        ? { encoding: options, mode: 0o600 }
+        : { ...(options ?? {}), mode: 0o600 };
+    writeFileSync(path, data, opts);
+    try {
+        chmodSync(path, 0o600);
+    }
+    catch { /* best-effort */ }
+}
+/** Append to a file under the outsrc home with mode 0600 (created if missing). */
+export function appendHomeFile(path, data) {
+    appendFileSync(path, data, { mode: 0o600 });
+    try {
+        chmodSync(path, 0o600);
+    }
+    catch { /* best-effort */ }
+}

package/dist/git.d.ts

@@ -0,0 +1,9 @@
+export declare function addWorktree(opts: {
+    repo: string;
+    worktree: string;
+    branch: string;
+    ref?: string;
+}): void;
+export declare function isAgentConfig(path: string): boolean;
+/** Leave the checkout's agent settings out of a review worktree. Git still has them, so the diff still shows them. */
+export declare function hideAgentConfig(worktree: string): string[];

package/dist/git.js

@@ -0,0 +1,27 @@
+import { execFileSync } from "node:child_process";
+import { mkdirSync, rmSync } from "node:fs";
+import { dirname, join } from "node:path";
+export function addWorktree(opts) {
+    mkdirSync(dirname(opts.worktree), { recursive: true });
+    execFileSync("git", ["worktree", "add", "-b", opts.branch, opts.worktree, opts.ref ?? "HEAD"], { cwd: opts.repo, stdio: "pipe" });
+}
+// Project settings these CLIs load from the checkout: hooks, MCP servers and notify commands run as the user,
+// outside any sandbox. Codex extends a trusted repository's trust to its worktrees, and Grok reads the Claude
+// and Cursor locations too, so a branch under review could run code through any of them.
+const AGENT_CONFIG_DIRS = new Set([".claude", ".codex", ".grok", ".cursor"]);
+const AGENT_CONFIG_FILES = new Set([".mcp.json"]);
+export function isAgentConfig(path) {
+    const segments = path.split("/");
+    return segments.slice(0, -1).some((segment) => AGENT_CONFIG_DIRS.has(segment)) || AGENT_CONFIG_FILES.has(segments.at(-1) ?? "");
+}
+/** Leave the checkout's agent settings out of a review worktree. Git still has them, so the diff still shows them. */
+export function hideAgentConfig(worktree) {
+    const tracked = execFileSync("git", ["ls-files", "-z"], { cwd: worktree, encoding: "utf8" }).split("\0").filter(Boolean);
+    const hidden = tracked.filter(isAgentConfig);
+    if (hidden.length === 0)
+        return [];
+    execFileSync("git", ["update-index", "--skip-worktree", "-z", "--stdin"], { cwd: worktree, input: `${hidden.join("\0")}\0`, stdio: ["pipe", "pipe", "pipe"] });
+    for (const path of hidden)
+        rmSync(join(worktree, path), { force: true });
+    return hidden;
+}