looply-cli 0.0.0-stage → 0.2.0

package/dist/agent-exec.d.ts

@@ -0,0 +1,182 @@
+import type { CommandResult } from './gate';
+import type { OwnedChildren } from './owned-children';
+import type { Effort, RoleModels } from './model-routing';
+/**
+ * How looply starts a coding agent.
+ *
+ * **The prompt never touches the command line.** It is written to the agent's
+ * stdin and stdin is closed; the command line carries flags only. That is the
+ * whole point of this module, and it is not a stylistic preference:
+ *
+ * - Prompts are multi-line. `spawn(cmd, { shell: true })` on Windows runs
+ *   `cmd.exe /d /s /c "<cmd>"`, and cmd.exe ends the command at the first
+ *   newline. Every looply agent call made before this module existed delivered
+ *   only the first line of its prompt — `["-p", "You are one round of looply."]`
+ *   — and dropped every flag after it. The agent, handed a sentence fragment
+ *   and no contract, answered in prose or asked what it was for. That is the
+ *   sole reason `looply run` had never completed a round and `scan` never
+ *   produced findings.
+ * - POSIX escaping is not escaping on cmd.exe: an escaped quote or dollar sign
+ *   arrives as a literal backslash, so even a one-line prompt was corrupted.
+ * - cmd.exe caps a command line at 8191 characters. The prover prompt embeds a
+ *   whole diff, so it would have blown that ceiling as soon as a round changed
+ *   anything substantial.
+ *
+ * Sending the prompt down stdin removes all three at once, on every platform,
+ * with no quoting layer to get wrong. The command line is built from config the
+ * user wrote and carries no round data at all, so there is nothing left to
+ * inject into.
+ *
+ * The agent is still started through a shell, because on Windows the CLI is
+ * `claude.cmd` — a batch shim Node has refused to spawn directly since 20.12.
+ * That stays safe here precisely because the command line holds no prompt.
+ */
+/** The seam the prover and verifier already declared: a prompt, not a command. */
+export type AgentInvoke = (prompt: string, timeoutMs: number) => Promise<CommandResult>;
+/** The slice of a child process this needs; callbacks may fire in any order. */
+export interface AgentSpawnHandle {
+    pid: number | undefined;
+    onExit(cb: (code: number | null) => void): void;
+    onError(cb: (err: Error) => void): void;
+    /** Interleaved stdout + stderr, already decoded. */
+    onOutput(cb: (chunk: string) => void): void;
+    /**
+     * Write the prompt and close stdin. Must never throw: an agent that exits
+     * before reading its prompt makes this EPIPE, and that is a failed round to
+     * report, not a crash of the runner (DESIGN section 12 case 6).
+     */
+    writePrompt(text: string): void;
+}
+export interface AgentExecDeps {
+    spawn(cmd: string): AgentSpawnHandle;
+    /** Must take down `pid` and every descendant, not just `pid`. */
+    killTree(pid: number): void;
+    now(): number;
+}
+/**
+ * Build an {@link AgentInvoke} over a fixed command line.
+ *
+ * Settlement rules match the gate's command runner deliberately — first outcome
+ * wins, and a timeout kills the tree then resolves immediately rather than
+ * waiting for an exit that may never come — so a hung agent and a hung test
+ * behave the same way and there is one story to reason about.
+ */
+export declare function makeAgentRunner(deps: AgentExecDeps, command: string, 
+/**
+ * Where to register the spawned process while it runs.
+ *
+ * Optional so every existing caller and test is unaffected. Given one, the
+ * run can stop its agent on the way out instead of leaving it editing the
+ * repository with no parent — measured: a hard-killed runner leaves the leaf
+ * process alive and still writing.
+ */
+owned?: OwnedChildren): AgentInvoke;
+export declare function nodeAgentSpawn(cmd: string): AgentSpawnHandle;
+/**
+ * The agent command, as configured.
+ *
+ * `command` is the invocation minus the output format, which each caller picks:
+ * the implementer, prover and verifier want the plain transcript, while `scan`
+ * reads the structured envelope. Neither ever appends anything derived from the
+ * repository, so the line stays free of round data.
+ */
+export interface AgentSpec {
+    command: string;
+    outputFormatFlag: string;
+    /**
+     * Which model each role runs, for the BUILT-IN provider — `--model` on the
+     * mediated invocation. `default` covers every role not named; `brain` is the
+     * one a project usually names separately. Absent means the provider's own
+     * default, which is what every project got before this existed.
+     *
+     * ⚠️ IGNORED for a configured `agent.command`, like `executable` below: looply
+     * cannot guess the flag somebody else's binary takes for a model, and a flag
+     * that silently does nothing reads exactly like one that works.
+     *
+     * A Fable model may be named for `brain` only; `parseConfig` refuses anything
+     * else, and `model-routing.ts` says why.
+     */
+    models?: RoleModels;
+    /** `--effort` on every built-in turn. Absent leaves it to the provider. */
+    effort?: Effort;
+    /**
+     * An ABSOLUTE path to the built-in provider's executable, when it is not
+     * where `claudePackageDir` looks.
+     *
+     * 🔴 IT SELECTS A BINARY, NOT A MEDIATION. This exists so a Claude Code
+     * installed somewhere other than `node_modules/@anthropic-ai/claude-code`
+     * still goes through the MEDIATED path — the one that passes `--tools ""`,
+     * `--strict-mcp-config` and an `--allowedTools` list naming only Looply's
+     * bridge. The alternative was to configure it as a generic `agent.command`,
+     * which takes the configured branch: that appends the declared suppression
+     * arguments but wires no MCP bridge at all, so the model would end up with
+     * NO tools rather than only Looply's. A weaker configuration for a provider
+     * Looply has a purpose-built adapter for is the wrong trade.
+     *
+     * ⚠️ IGNORED unless `command` is the default. Writing an `agent.command`
+     * means "drive this as an unknown binary", and this must not quietly
+     * re-route that back through Claude's flags.
+     */
+    executable?: string;
+    /**
+     * Directories the contained agent may read and execute from.
+     *
+     * A provider runtime usually lives OUTSIDE the repository, which is right —
+     * it is machine material, not model-editable source. A contained process can
+     * only run what it was granted, so it has to be told where that is, and told
+     * EXPLICITLY: parsing the command line to guess would put a heuristic between
+     * a config string and a filesystem permission.
+     *
+     * The built-in provider needs none of this; it resolves its own package.
+     */
+    runtime?: readonly string[];
+    /**
+     * Environment variables to forward into the contained agent, BY NAME.
+     *
+     * A contained agent inherits nothing, which is the point — but a configured
+     * provider may genuinely need something from the environment: an API base
+     * URL, a model name, a provider key. Naming them is a deliberate act by a
+     * person, in a file the model cannot write, and it forwards the VALUE the
+     * daemon holds rather than putting a secret in the config.
+     *
+     * Nothing is forwarded unless it is named here. "The agent does not
+     * automatically inherit the daemon's environment" stays true; this is the
+     * word "automatically" doing its work.
+     */
+    env?: readonly string[];
+    /**
+     * HOW THIS PROVIDER IS STOPPED FROM USING ITS OWN TOOLS.
+     *
+     * 🔴 THE DEFAULT PROVIDER GETS `allowedToolArgs`; A CONFIGURED ONE GOT
+     * NOTHING. "The model gets no host tools" was delivered by Claude flags on
+     * one branch and by nothing at all on the other — so a configured provider
+     * launched through `cmd.exe` with its own file, shell and network tools fully
+     * enabled, beside a daemon holding a machine token.
+     *
+     * ⚠️ AND IT CANNOT BE FIXED BY INVENTING FLAGS. Looply does not know what
+     * argument turns an unknown binary's tools off, and guessing would be worse
+     * than the gap: a flag that silently does nothing reads exactly like one that
+     * works. So the person states it, in a file the model cannot write, and a
+     * provider that states nothing is REFUSED rather than launched unmediated.
+     *
+     * The built-in provider needs none of this; it has its own branch.
+     */
+    noHostTools?: readonly string[];
+    /**
+     * WHICH `agent.*` KEYS THE CONFIG FILE ACTUALLY CONTAINED.
+     *
+     * Set by `parseConfig` and read by `resolveProvider`, which needs to tell
+     * "the person wrote this" from "the parser defaulted it". Optional, so every
+     * hand-built spec in this tree and in every test keeps working — an absent
+     * list means "nothing is known to be explicit", which is the direction that
+     * lets a preset supply its own facts.
+     */
+    declared?: readonly string[];
+}
+export declare const DEFAULT_AGENT: AgentSpec;
+export declare function agentCommandLine(spec: AgentSpec, format: 'text' | 'json'): string;
+/** Text transcript: the implementer, the prover and the verifier. */
+export declare function nodeAgentRunner(spec?: AgentSpec, owned?: OwnedChildren): AgentInvoke;
+/** Structured envelope: `scan`, which reads `result` off the JSON. */
+export declare function nodeAgentJsonRunner(spec?: AgentSpec): AgentInvoke;
+//# sourceMappingURL=agent-exec.d.ts.map

package/dist/agent-exec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-exec.d.ts","sourceRoot":"","sources":["../src/agent-exec.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,QAAQ,CAAC;AAC5C,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AACtD,OAAO,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAE1D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH,kFAAkF;AAClF,MAAM,MAAM,WAAW,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,KAAK,OAAO,CAAC,aAAa,CAAC,CAAC;AAExF,gFAAgF;AAChF,MAAM,WAAW,gBAAgB;IAC/B,GAAG,EAAE,MAAM,GAAG,SAAS,CAAC;IACxB,MAAM,CAAC,EAAE,EAAE,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,KAAK,IAAI,GAAG,IAAI,CAAC;IAChD,OAAO,CAAC,EAAE,EAAE,CAAC,GAAG,EAAE,KAAK,KAAK,IAAI,GAAG,IAAI,CAAC;IACxC,oDAAoD;IACpD,QAAQ,CAAC,EAAE,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,GAAG,IAAI,CAAC;IAC5C;;;;OAIG;IACH,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;CACjC;AAED,MAAM,WAAW,aAAa;IAC5B,KAAK,CAAC,GAAG,EAAE,MAAM,GAAG,gBAAgB,CAAC;IACrC,iEAAiE;IACjE,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,GAAG,IAAI,MAAM,CAAC;CACf;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAC7B,IAAI,EAAE,aAAa,EACnB,OAAO,EAAE,MAAM;AACf;;;;;;;GAOG;AACH,KAAK,CAAC,EAAE,aAAa,GACpB,WAAW,CA+Cb;AAED,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,gBAAgB,CA8B5D;AAQD;;;;;;;GAOG;AACH,MAAM,WAAW,SAAS;IACxB,OAAO,EAAE,MAAM,CAAC;IAChB,gBAAgB,EAAE,MAAM,CAAC;IACzB;;;;;;;;;;;;OAYG;IACH,MAAM,CAAC,EAAE,UAAU,CAAC;IACpB,2EAA2E;IAC3E,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;;;;;;;;;;;;;;OAiBG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;;;;;;;;OAUG;IACH,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC5B;;;;;;;;;;;;OAYG;IACH,GAAG,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACxB;;;;;;;;;;;;;;;;OAgBG;IACH,WAAW,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAChC;;;;;;;;OAQG;IACH,QAAQ,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC9B;AAED,eAAO,MAAM,aAAa,EAAE,SAG3B,CAAC;AAEF,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,CAEjF;AAED,qEAAqE;AACrE,wBAAgB,eAAe,CAAC,IAAI,GAAE,SAAyB,EAAE,KAAK,CAAC,EAAE,aAAa,GAAG,WAAW,CAEnG;AAED,sEAAsE;AACtE,wBAAgB,mBAAmB,CAAC,IAAI,GAAE,SAAyB,GAAG,WAAW,CAEhF"}

package/dist/agent-exec.js

@@ -0,0 +1,125 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_AGENT = void 0;
+exports.makeAgentRunner = makeAgentRunner;
+exports.nodeAgentSpawn = nodeAgentSpawn;
+exports.agentCommandLine = agentCommandLine;
+exports.nodeAgentRunner = nodeAgentRunner;
+exports.nodeAgentJsonRunner = nodeAgentJsonRunner;
+const node_child_process_1 = require("node:child_process");
+const command_runner_1 = require("./command-runner");
+/**
+ * Build an {@link AgentInvoke} over a fixed command line.
+ *
+ * Settlement rules match the gate's command runner deliberately — first outcome
+ * wins, and a timeout kills the tree then resolves immediately rather than
+ * waiting for an exit that may never come — so a hung agent and a hung test
+ * behave the same way and there is one story to reason about.
+ */
+function makeAgentRunner(deps, command, 
+/**
+ * Where to register the spawned process while it runs.
+ *
+ * Optional so every existing caller and test is unaffected. Given one, the
+ * run can stop its agent on the way out instead of leaving it editing the
+ * repository with no parent — measured: a hard-killed runner leaves the leaf
+ * process alive and still writing.
+ */
+owned) {
+    return (prompt, timeoutMs) => new Promise((resolve) => {
+        const started = deps.now();
+        const chunks = [];
+        let settled = false;
+        let timer;
+        let release;
+        const finish = (ok, timedOut) => {
+            if (settled)
+                return;
+            settled = true;
+            if (timer !== undefined)
+                clearTimeout(timer);
+            // Given back the moment it settles, so a finished agent is not killed
+            // later by a shutdown that thinks it is still running.
+            release?.();
+            resolve({ ok, timedOut, ms: deps.now() - started, output: chunks.join('') });
+        };
+        const handle = deps.spawn(command);
+        if (owned && handle.pid !== undefined) {
+            const pid = handle.pid;
+            release = owned.adopt({
+                pid,
+                label: 'coding agent',
+                kill: () => deps.killTree(pid),
+            });
+        }
+        handle.onOutput((c) => chunks.push(c));
+        handle.onError((err) => {
+            // Kept in the output so "the agent is not installed" reads differently
+            // in the round log from "the agent disagreed".
+            chunks.push(err.message);
+            finish(false, false);
+        });
+        handle.onExit((code) => finish(code === 0, false));
+        timer = setTimeout(() => {
+            if (settled)
+                return;
+            if (handle.pid !== undefined)
+                deps.killTree(handle.pid);
+            finish(false, true);
+        }, timeoutMs);
+        // After the listeners are attached, so a synchronous EPIPE is reported
+        // through onError rather than thrown out of the promise constructor.
+        handle.writePrompt(prompt);
+    });
+}
+function nodeAgentSpawn(cmd) {
+    const child = (0, node_child_process_1.spawn)(cmd, {
+        shell: true,
+        detached: process.platform !== 'win32',
+        stdio: ['pipe', 'pipe', 'pipe'],
+    });
+    const errCbs = [];
+    child.on('error', (e) => errCbs.forEach((cb) => cb(e)));
+    // A child that exits before reading its prompt raises EPIPE on the stream
+    // rather than at the write call, so the stream needs a listener of its own or
+    // Node treats it as unhandled and takes the whole run down with it.
+    child.stdin?.on('error', (e) => errCbs.forEach((cb) => cb(e)));
+    return {
+        pid: child.pid,
+        onExit: (cb) => child.on('exit', (code) => cb(code)),
+        onError: (cb) => errCbs.push(cb),
+        onOutput: (cb) => {
+            child.stdout?.on('data', (d) => cb(d.toString('utf8')));
+            child.stderr?.on('data', (d) => cb(d.toString('utf8')));
+        },
+        writePrompt: (text) => {
+            try {
+                child.stdin?.end(text);
+            }
+            catch {
+                // Already reported through the stream's own error listener above.
+            }
+        },
+    };
+}
+const nodeDeps = {
+    spawn: nodeAgentSpawn,
+    killTree: command_runner_1.nodeKillTree,
+    now: () => Date.now(),
+};
+exports.DEFAULT_AGENT = {
+    command: 'claude -p --dangerously-skip-permissions',
+    outputFormatFlag: '--output-format',
+};
+function agentCommandLine(spec, format) {
+    return spec.outputFormatFlag ? `${spec.command} ${spec.outputFormatFlag} ${format}` : spec.command;
+}
+/** Text transcript: the implementer, the prover and the verifier. */
+function nodeAgentRunner(spec = exports.DEFAULT_AGENT, owned) {
+    return makeAgentRunner(nodeDeps, agentCommandLine(spec, 'text'), owned);
+}
+/** Structured envelope: `scan`, which reads `result` off the JSON. */
+function nodeAgentJsonRunner(spec = exports.DEFAULT_AGENT) {
+    return makeAgentRunner(nodeDeps, agentCommandLine(spec, 'json'));
+}
+//# sourceMappingURL=agent-exec.js.map

package/dist/agent-exec.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-exec.js","sourceRoot":"","sources":["../src/agent-exec.ts"],"names":[],"mappings":"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"}

package/dist/agent-runtime.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Why this path may not be granted to untrusted execution, or null if it may.
+ *
+ * Compared as resolved paths rather than as strings: `C:\Users\x\..\x` is the
+ * same directory as `C:\Users\x`, and a check that could not see that would be
+ * a check somebody routes around by accident.
+ */
+export declare function unsafeRuntimeGrant(path: string, home?: string, projectDir?: string): string | null;
+/**
+ * Validate every declared runtime path, or say which one is wrong.
+ *
+ * Fails closed on the whole list: a configuration with one unsafe entry is a
+ * configuration nobody has checked, and running with the rest of it would be
+ * obeying half of what was written.
+ */
+export declare function checkRuntimeGrants(paths: readonly string[], home?: string, projectDir?: string): {
+    ok: true;
+    paths: string[];
+} | {
+    ok: false;
+    because: string;
+};
+//# sourceMappingURL=agent-runtime.d.ts.map

package/dist/agent-runtime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-runtime.d.ts","sourceRoot":"","sources":["../src/agent-runtime.ts"],"names":[],"mappings":"AAwFA;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAChC,IAAI,EAAE,MAAM,EACZ,IAAI,GAAE,MAAkB,EACxB,UAAU,CAAC,EAAE,MAAM,GAClB,MAAM,GAAG,IAAI,CA4Bf;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,SAAS,MAAM,EAAE,EACxB,IAAI,GAAE,MAAkB,EACxB,UAAU,CAAC,EAAE,MAAM,GAClB;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,MAAM,EAAE,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAQhE"}

package/dist/agent-runtime.js

@@ -0,0 +1,143 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.unsafeRuntimeGrant = unsafeRuntimeGrant;
+exports.checkRuntimeGrants = checkRuntimeGrants;
+const node_fs_1 = require("node:fs");
+const node_os_1 = require("node:os");
+const node_path_1 = require("node:path");
+const untrusted_exec_1 = require("./untrusted-exec");
+/**
+ * WHERE A CONFIGURED AGENT'S RUNTIME IS ALLOWED TO LIVE.
+ *
+ * A contained agent can only execute what it was granted, and the provider
+ * runtime is trusted machine material that generally sits OUTSIDE the
+ * model-editable repository — which is right, and which means containment needs
+ * to be told where it is.
+ *
+ * It must be TOLD, not have it inferred. A command line is not an authority
+ * description: parsing `node C:\somewhere\agent.js --flag` to guess what to
+ * grant would be a heuristic standing between untrusted input and a filesystem
+ * permission, and the first quoting surprise becomes a grant nobody intended.
+ * So the grant is a separate, explicit field a person writes.
+ *
+ * `.looply/config.yaml` is already protected from contained execution, so the
+ * model cannot edit its own next launch. That is what makes it safe to treat
+ * this as human configuration — and it is why the protection matters more now
+ * than it did when it was only about gate commands.
+ */
+/**
+ * Roots too broad to grant, whatever the configuration says.
+ *
+ * Not a blocklist of paths somebody might type — a check that the grant is not
+ * a root whose whole subtree would come with it. Granting the home directory
+ * hands over `~/.looply/machine.json` and `~/.claude`; granting a drive root
+ * hands over everything.
+ */
+function forbiddenRoots(home = (0, node_os_1.homedir)()) {
+    const win = (0, untrusted_exec_1.systemRoot)();
+    const roots = [
+        home,
+        (0, node_path_1.resolve)(home, '.looply'),
+        (0, node_path_1.resolve)(home, '.claude'),
+        win,
+        (0, node_path_1.resolve)(win, '..'),
+        process.env['ProgramFiles'] ?? 'C:\\Program Files',
+        process.env['ProgramFiles(x86)'] ?? 'C:\\Program Files (x86)',
+        process.env['APPDATA'] ?? (0, node_path_1.resolve)(home, 'AppData', 'Roaming'),
+        process.env['LOCALAPPDATA'] ?? (0, node_path_1.resolve)(home, 'AppData', 'Local'),
+        (0, node_path_1.resolve)(home, 'AppData'),
+    ];
+    return roots.map((r) => (0, node_path_1.resolve)(r));
+}
+/** True when `p` IS `root`, or `root` itself is inside `p`. */
+function coversOrIs(p, root) {
+    const a = (0, node_path_1.resolve)(p);
+    const b = (0, node_path_1.resolve)(root);
+    if (a.toLowerCase() === b.toLowerCase())
+        return true;
+    // `p` is an ANCESTOR of a forbidden root — granting it grants that root too.
+    const withSep = a.endsWith(node_path_1.sep) ? a : a + node_path_1.sep;
+    return b.toLowerCase().startsWith(withSep.toLowerCase());
+}
+/**
+ * Every name for this path: the lexical one, and the one it really is.
+ *
+ * A lexical check alone reads a junction as an ordinary directory. `mklink /J`
+ * needs no privilege on Windows, a junction to the home directory resolves to
+ * itself under `resolve`, and the ACL a grant writes follows the reparse point
+ * to the target — so a forbidden root would have been granted under a name that
+ * never looked like one.
+ *
+ * Both names are checked rather than only the real one, because a path can be
+ * unsafe either way round: a link that lands somewhere forbidden, or a plain
+ * forbidden path that resolves elsewhere.
+ *
+ * A path that does not exist yet has no real name, so only the lexical one is
+ * available. That gap is not closable from here: the grant is applied moments
+ * after this check, and anything that can create a junction in between can
+ * already write where the runtime lives.
+ */
+function bothNames(path) {
+    const lexical = (0, node_path_1.resolve)(path);
+    try {
+        const real = (0, node_path_1.resolve)(node_fs_1.realpathSync.native(lexical));
+        return real.toLowerCase() === lexical.toLowerCase() ? [lexical] : [lexical, real];
+    }
+    catch {
+        return [lexical];
+    }
+}
+/**
+ * Why this path may not be granted to untrusted execution, or null if it may.
+ *
+ * Compared as resolved paths rather than as strings: `C:\Users\x\..\x` is the
+ * same directory as `C:\Users\x`, and a check that could not see that would be
+ * a check somebody routes around by accident.
+ */
+function unsafeRuntimeGrant(path, home = (0, node_os_1.homedir)(), projectDir) {
+    const bad = forbiddenRoots(home);
+    for (const p of bothNames(path)) {
+        // INSIDE THE WORKTREE IS NOT A PLACE A RUNTIME MAY LIVE.
+        //
+        // This is the one place the validate-then-grant race is actually winnable.
+        // Everywhere else a declared runtime path sits outside the worktree, where
+        // contained execution holds no grant and so cannot swap a directory for a
+        // link between the check above and the moment the ACL is written. Inside
+        // the worktree the model has write access by design, so it could.
+        //
+        // Refusing costs nothing: the worktree is already granted in full, so a
+        // runtime declared there would be reachable anyway. What the declaration
+        // would add is only the race.
+        if (projectDir !== undefined && coversOrIs((0, node_path_1.resolve)(projectDir), p)) {
+            return `${path} is inside the project worktree, which the model can write`;
+        }
+        const root = (0, node_path_1.parse)(p).root;
+        if (p.toLowerCase() === (0, node_path_1.resolve)(root).toLowerCase()) {
+            return `${path} is a drive root, which would grant the whole machine`;
+        }
+        for (const b of bad) {
+            if (coversOrIs(p, b)) {
+                return `${path} covers ${b}, which holds credentials or machine state`;
+            }
+        }
+    }
+    return null;
+}
+/**
+ * Validate every declared runtime path, or say which one is wrong.
+ *
+ * Fails closed on the whole list: a configuration with one unsafe entry is a
+ * configuration nobody has checked, and running with the rest of it would be
+ * obeying half of what was written.
+ */
+function checkRuntimeGrants(paths, home = (0, node_os_1.homedir)(), projectDir) {
+    const out = [];
+    for (const p of paths) {
+        const bad = unsafeRuntimeGrant(p, home, projectDir);
+        if (bad !== null)
+            return { ok: false, because: `agent.runtime: ${bad}` };
+        out.push((0, node_path_1.resolve)(p));
+    }
+    return { ok: true, paths: out };
+}
+//# sourceMappingURL=agent-runtime.js.map

package/dist/agent-runtime.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-runtime.js","sourceRoot":"","sources":["../src/agent-runtime.ts"],"names":[],"mappings":"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"}

package/dist/approval-gate-read.d.ts

@@ -0,0 +1,66 @@
+import { type ApprovalGate } from '@looply/core';
+import type { ServerApprovalRow } from './server-client';
+/**
+ * ASKING THE SERVER WHAT A PURSUIT IS WAITING FOR.
+ *
+ * The thin half of the gate: one HTTP read, a shape check, and the pure
+ * derivation. Everything that could be a judgement lives in
+ * `deriveApprovalGate`, so this file has no branches about what an approval
+ * MEANS — only about whether it was heard.
+ *
+ * ─────────────────────────────────────────────────────────────────────────────
+ * IT FAILS CLOSED, AND THAT IS THE WHOLE REASON IT IS NOT INLINE.
+ *
+ * The tempting shape is `catch { return { kind: 'none' } }`, and it is the one
+ * mistake that matters here. "I could not ask" and "there is nothing
+ * outstanding" arrive as the same silence and are opposite facts: the first
+ * means a person may be mid-decision, and treating it as the second is a
+ * machine carrying on past a question it simply could not see.
+ *
+ * So a read that does not produce a well-formed answer produces `unknown`,
+ * which holds — and holding is free, because the next tick asks again.
+ */
+/** Just enough of the client to ask. Injected so a test can fail it precisely. */
+export interface ApprovalReader {
+    projectApprovals(projectId: string, goal: {
+        goalId: string;
+        goalVersion: number;
+    }, limit?: number): Promise<ServerApprovalRow[]>;
+}
+export interface ReadApprovalGateInput {
+    readonly projectId: string;
+    readonly goalId: string;
+    readonly goalVersion: number;
+    /** Milliseconds since the epoch, from the caller's clock. */
+    readonly now: number;
+    /**
+     * Which of these resolutions a resumed run has already been given.
+     *
+     * A FUNCTION, and asked with the ids that came back, because the machine
+     * cannot know which answers to look for until it has seen which exist. The
+     * claims are local: consuming a resolution is something this machine did, and
+     * the row on the server looks identical before and after.
+     *
+     * A failure here is `unknown`, like every other. A claim that could not be
+     * read is not a claim that is not there, and reading it as absent would hand
+     * the same answer to a second run.
+     */
+    readonly consumed?: (approvalIds: readonly string[]) => Promise<{
+        ok: true;
+        consumed: ReadonlySet<string>;
+    } | {
+        ok: false;
+        because: string;
+    }>;
+}
+/**
+ * How many rows to ask for.
+ *
+ * A pursuit at one version accumulates approvals slowly — a run raises at most
+ * one and then stops — so this is generous rather than tuned. It exists at all
+ * because the route's own default is 50 and silently taking the newest 50 of a
+ * larger set would be a gate that stops seeing the oldest outstanding question.
+ */
+export declare const APPROVAL_PAGE = 200;
+export declare function readApprovalGate(server: ApprovalReader, input: ReadApprovalGateInput): Promise<ApprovalGate>;
+//# sourceMappingURL=approval-gate-read.d.ts.map

package/dist/approval-gate-read.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"approval-gate-read.d.ts","sourceRoot":"","sources":["../src/approval-gate-read.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,YAAY,EAElB,MAAM,cAAc,CAAC;AACtB,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAEzD;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,kFAAkF;AAClF,MAAM,WAAW,cAAc;IAC7B,gBAAgB,CACd,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAA;KAAE,EAC7C,KAAK,CAAC,EAAE,MAAM,GACb,OAAO,CAAC,iBAAiB,EAAE,CAAC,CAAC;CACjC;AAED,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,6DAA6D;IAC7D,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB;;;;;;;;;;;OAWG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAClB,WAAW,EAAE,SAAS,MAAM,EAAE,KAC3B,OAAO,CAAC;QAAE,EAAE,EAAE,IAAI,CAAC;QAAC,QAAQ,EAAE,WAAW,CAAC,MAAM,CAAC,CAAA;KAAE,GAAG;QAAE,EAAE,EAAE,KAAK,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CAC5F;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,aAAa,MAAM,CAAC;AA8EjC,wBAAsB,gBAAgB,CACpC,MAAM,EAAE,cAAc,EACtB,KAAK,EAAE,qBAAqB,GAC3B,OAAO,CAAC,YAAY,CAAC,CA6CvB"}