looply-cli 0.0.0-stage → 0.3.0

package/dist/evidence-facts.js

@@ -0,0 +1,114 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.artifactFacts = artifactFacts;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const observation_inventory_1 = require("./observation-inventory");
+/**
+ * A single plain name: no separator of either kind, no leading dot, so no `..`
+ * and no traversal. This is the boundary; the routing below is only routing.
+ *
+ * ⚠️ A MUTATION BATTERY SHOWED WHY IT IS THE ONE THAT MATTERS. The first
+ * version routed on `id.includes('/')` and ALSO tested for a backslash there —
+ * and narrowing that back to a forward slash survived every test, because an
+ * id with a backslash is not a plain name either and this line refuses it.
+ * Two guards where one is load-bearing is two things to keep true; the routing
+ * asks only "is this an observation id", and everything else lands here.
+ */
+const PLAIN = /^[^\\/.][^\\/]*$/;
+/**
+ * 🔴 EVERY FIELD SET SO THAT `decideRemoval` REFUSES: it refuses on
+ * `owned !== true`, on `pinned`, on `referenced`, and on `durable`. One of
+ * those would do; all four is what "nothing is permission" looks like when the
+ * answer is "I do not know what this is".
+ */
+const REFUSES = { owned: false, pinned: true, referenced: true, class: 'durable' };
+/**
+ * WHAT THE FILESYSTEM CANNOT SAY: provenance, pins and references, asked
+ * again at the moment of removal.
+ *
+ * 🔴 IT LIVES HERE, AND NOT IN `bin.ts`, FOR THE REASON `self-repo-id.ts`
+ * gives at length: a spec that needs this would otherwise have to import the
+ * CLI entry point, and two suites importing that file is how a half-written
+ * transform cache entry took the gate down twice. It is also the only way to
+ * test it at all — this is the last check before a delete, and it had no
+ * spec of its own while it was a private function in a 2,000-line file.
+ */
+/**
+ * Ownership, class and — the hard one — whether anything still refers to it.
+ *
+ * 🔴 `referenced` DEFAULTS TO TRUE, AND THAT IS THE WHOLE DESIGN OF IT.
+ * `OWNER_CHARTER.md` §5 D5 forbids deleting *"artifacts referenced by
+ * active/review/recovery work"* and says *"missing/unreadable/unknown is never
+ * deletion permission"*. Put together, those mean an artifact whose references
+ * could not be established is referenced as far as this is concerned. Only a
+ * check that RAN and found nothing may answer false.
+ *
+ * The three places a rejected candidate can still be spoken for, and all of them
+ * are bounded reads of files this project already keeps:
+ *
+ *   run.lease.json   the run holding the project right now
+ *   runs/            the run records that have not been reaped
+ *   queue.json       an item still carrying the failure this candidate is from
+ *
+ * ⚠️ NOT `events.jsonl`. Every run id that ever existed is in it, so a search
+ * there would find every artifact referenced for ever and the policy would never
+ * expire anything — a rule that always says no is indistinguishable from one
+ * nobody wrote.
+ */
+function artifactFacts(stateDir, id) {
+    /**
+     * 🔴 AN OBSERVATION IS ASKED ABOUT AS AN OBSERVATION, and this branch is
+     * here because the fallback below would have got BOTH answers wrong: not
+     * under `rejected/`, so `durable` — which refuses every removal — and
+     * `pinned: false`, which would have been a lie about a watch still running.
+     * The re-check D5 asks for is only a re-check if it asks the same question
+     * the plan did.
+     *
+     * `null` from `observationFacts` is an id that could leave the store, a
+     * session with no such file, or a record that no longer parses. Every one of
+     * those is answered with facts that REFUSE, never with permission.
+     */
+    if (id.includes('/')) {
+        const seen = (0, observation_inventory_1.observationFacts)(stateDir, id);
+        if (seen === null)
+            return REFUSES;
+        return { owned: seen.owned, pinned: seen.pinned, referenced: false, class: seen.class };
+    }
+    /**
+     * 🔴 AND AN ID THAT IS NOT A PLAIN NAME IS NOT ANSWERED AT ALL.
+     *
+     * A test with `ses_1\..\..\secret.json` found this: it contains no FORWARD
+     * slash, so the branch above did not take it, and the walk below answered
+     * `owned: true` for a path with two parent traversals in it. `class:
+     * 'durable'` happened to refuse the removal and `insideRoot` would have
+     * refused it again — but this function had stated, as a fact, that a
+     * traversal was an artifact created by this policy. `..` alone is worse
+     * still: `existsSync(rejected/..)` is TRUE, which would have made the state
+     * directory itself a `failure-diagnostic` this policy owns.
+     *
+     * D5 asks for *"path boundaries"* to be checked again here, not only at the
+     * delete. A name is a name; anything else is refused.
+     */
+    if (!PLAIN.test(id))
+        return REFUSES;
+    const rejectedDir = (0, node_path_1.join)(stateDir, 'rejected');
+    const isRejected = (0, node_fs_1.existsSync)((0, node_path_1.join)(rejectedDir, id));
+    const cls = isRejected ? 'failure-diagnostic' : 'durable';
+    let referenced = true;
+    try {
+        const lease = (0, node_fs_1.existsSync)((0, node_path_1.join)(stateDir, 'run.lease.json'))
+            ? (0, node_fs_1.readFileSync)((0, node_path_1.join)(stateDir, 'run.lease.json'), 'utf8')
+            : '';
+        const queue = (0, node_fs_1.existsSync)((0, node_path_1.join)(stateDir, 'queue.json')) ? (0, node_fs_1.readFileSync)((0, node_path_1.join)(stateDir, 'queue.json'), 'utf8') : '';
+        const runsDir = (0, node_path_1.join)(stateDir, 'runs');
+        const runs = (0, node_fs_1.existsSync)(runsDir) ? (0, node_fs_1.readdirSync)(runsDir).join('\n') : '';
+        referenced = lease.includes(id) || queue.includes(id) || runs.includes(id);
+    }
+    catch {
+        // A read that failed establishes nothing, and nothing is permission.
+        referenced = true;
+    }
+    return { owned: true, pinned: false, referenced, class: cls };
+}
+//# sourceMappingURL=evidence-facts.js.map

package/dist/evidence-facts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"evidence-facts.js","sourceRoot":"","sources":["../src/evidence-facts.ts"],"names":[],"mappings":";;AA2DA,sCA4DC;AAvHD,qCAAgE;AAChE,yCAAiC;AACjC,mEAA2D;AAE3D;;;;;;;;;;GAUG;AACH,MAAM,KAAK,GAAG,kBAAkB,CAAC;AAEjC;;;;;GAKG;AACH,MAAM,OAAO,GAAG,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,EAAE,IAAI,EAAE,KAAK,EAAE,SAAS,EAAW,CAAC;AAE5F;;;;;;;;;;GAUG;AAEH;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,SAAgB,aAAa,CAAC,QAAgB,EAAE,EAAU;IAMxD;;;;;;;;;;;OAWG;IACH,IAAI,EAAE,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC;QACrB,MAAM,IAAI,GAAG,IAAA,wCAAgB,EAAC,QAAQ,EAAE,EAAE,CAAC,CAAC;QAC5C,IAAI,IAAI,KAAK,IAAI;YAAE,OAAO,OAAO,CAAC;QAClC,OAAO,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,UAAU,EAAE,KAAK,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,CAAC;IAC1F,CAAC;IAED;;;;;;;;;;;;;;OAcG;IACH,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC;QAAE,OAAO,OAAO,CAAC;IAEpC,MAAM,WAAW,GAAG,IAAA,gBAAI,EAAC,QAAQ,EAAE,UAAU,CAAC,CAAC;IAC/C,MAAM,UAAU,GAAG,IAAA,oBAAU,EAAC,IAAA,gBAAI,EAAC,WAAW,EAAE,EAAE,CAAC,CAAC,CAAC;IACrD,MAAM,GAAG,GAAG,UAAU,CAAC,CAAC,CAAE,oBAA8B,CAAC,CAAC,CAAE,SAAmB,CAAC;IAEhF,IAAI,UAAU,GAAG,IAAI,CAAC;IACtB,IAAI,CAAC;QACH,MAAM,KAAK,GAAG,IAAA,oBAAU,EAAC,IAAA,gBAAI,EAAC,QAAQ,EAAE,gBAAgB,CAAC,CAAC;YACxD,CAAC,CAAC,IAAA,sBAAY,EAAC,IAAA,gBAAI,EAAC,QAAQ,EAAE,gBAAgB,CAAC,EAAE,MAAM,CAAC;YACxD,CAAC,CAAC,EAAE,CAAC;QACP,MAAM,KAAK,GAAG,IAAA,oBAAU,EAAC,IAAA,gBAAI,EAAC,QAAQ,EAAE,YAAY,CAAC,CAAC,CAAC,CAAC,CAAC,IAAA,sBAAY,EAAC,IAAA,gBAAI,EAAC,QAAQ,EAAE,YAAY,CAAC,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;QACjH,MAAM,OAAO,GAAG,IAAA,gBAAI,EAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;QACvC,MAAM,IAAI,GAAG,IAAA,oBAAU,EAAC,OAAO,CAAC,CAAC,CAAC,CAAC,IAAA,qBAAW,EAAC,OAAO,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;QACxE,UAAU,GAAG,KAAK,CAAC,QAAQ,CAAC,EAAE,CAAC,IAAI,KAAK,CAAC,QAAQ,CAAC,EAAE,CAAC,IAAI,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC;IAC7E,CAAC;IAAC,MAAM,CAAC;QACP,qEAAqE;QACrE,UAAU,GAAG,IAAI,CAAC;IACpB,CAAC;IAED,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,UAAU,EAAE,KAAK,EAAE,GAAG,EAAE,CAAC;AAChE,CAAC"}

package/dist/exclusive-lock.d.ts

@@ -0,0 +1,52 @@
+/**
+ * ONE SHORT MUTEX, SHARED BY EVERY CHECK-AND-CLAIM THAT NEEDS ONE.
+ *
+ * ─────────────────────────────────────────────────────────────────────────────
+ * 🔴 COMPARE-AFTER-CLAIM ONLY WORKS WHEN EVERY CLAIMANT COMPARES THE SAME
+ * SEQUENCE — AND TWO SEPARATE MECHANISMS HAVE NOW LEARNED THAT THE HARD WAY.
+ *
+ * The surface lease learned it first: `src` and `src/app` are different
+ * directories with independent ordinals, so "who got there first" is not a
+ * question their contents can answer. MEASURED with the read-back in place and
+ * no mutex: eight racers produced FOUR simultaneous holders, three trials
+ * running.
+ *
+ * The spend ledger learned it second, and worse. Its claimants DID share one
+ * sequence — an append-only file ordered by `(at, id)` — and it still was not
+ * enough. A claimant that obtained an early ordering key and published it LATE
+ * was counted by nobody: everyone who decided in between sorted after it and so
+ * was excluded from its own view. MEASURED against a $3 ceiling with $2
+ * estimates: B published at T+1000 and was admitted, A published at T and was
+ * admitted, and the window held $4. A total order over rows says who is first;
+ * it does not say who has already been told yes.
+ *
+ * So the operation that makes an admission authoritative is the WHOLE
+ * check-and-claim, taken inside this lock. Publication and decision happen in
+ * the same critical section, so there is no interval in which a claim has been
+ * decided but not published — which is exactly what makes a late publication
+ * harmless: there is no such thing.
+ *
+ * ⚠️ THE READ PATHS TAKE NOTHING. `holderOf`, `checkFence` and `spendInWindow`
+ * stay lock-free; only the writers serialise. Acquisition happens once per run
+ * and takes microseconds.
+ *
+ * ⚠️ AND A DEAD HOLDER'S LOCK IS BROKEN BY CONTENT MATCH, NEVER BY PATH. Phase
+ * 1 measured what removing a lock by path costs: a process that had already lost
+ * its claim deleted the winner's, and four processes then held one lock.
+ *
+ * ⚠️ ONE IMPLEMENTATION, NOT TWO. This was extracted from `surface-lease` rather
+ * than copied beside it. A second "safe enough" mutex is how two callers come to
+ * disagree about what holding one means.
+ */
+export declare const EXCLUSIVE_LOCK_WAIT_MS = 5000;
+/**
+ * F43: HOW LONG A WAITER PAUSES BETWEEN ATTEMPTS. It waits; it does not spin.
+ * A wait sized for microsecond critical sections could afford a busy loop; the
+ * shared-grant lock is held across an ACL write that takes tens of seconds, and
+ * a spinning waiter burns a core and hammers the lock file for all of it.
+ * `Atomics.wait` blocks the thread without the event loop, which this
+ * synchronous function already does.
+ */
+export declare const EXCLUSIVE_LOCK_PAUSE_MS = 20;
+export declare function withExclusiveLock<T>(path: string, fn: () => T, fallback: (why: string) => T, waitMs?: number): T;
+//# sourceMappingURL=exclusive-lock.d.ts.map

package/dist/exclusive-lock.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"exclusive-lock.d.ts","sourceRoot":"","sources":["../src/exclusive-lock.ts"],"names":[],"mappings":"AAKA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH,eAAO,MAAM,sBAAsB,OAAQ,CAAC;AAE5C;;;;;;;GAOG;AACH,eAAO,MAAM,uBAAuB,KAAK,CAAC;AAG1C,wBAAgB,iBAAiB,CAAC,CAAC,EACjC,IAAI,EAAE,MAAM,EACZ,EAAE,EAAE,MAAM,CAAC,EACX,QAAQ,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,CAAC,EAC5B,MAAM,GAAE,MAA+B,GACtC,CAAC,CAmFH"}

package/dist/exclusive-lock.js

@@ -0,0 +1,150 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EXCLUSIVE_LOCK_PAUSE_MS = exports.EXCLUSIVE_LOCK_WAIT_MS = void 0;
+exports.withExclusiveLock = withExclusiveLock;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const node_os_1 = require("node:os");
+const run_lease_1 = require("./run-lease");
+/**
+ * ONE SHORT MUTEX, SHARED BY EVERY CHECK-AND-CLAIM THAT NEEDS ONE.
+ *
+ * ─────────────────────────────────────────────────────────────────────────────
+ * 🔴 COMPARE-AFTER-CLAIM ONLY WORKS WHEN EVERY CLAIMANT COMPARES THE SAME
+ * SEQUENCE — AND TWO SEPARATE MECHANISMS HAVE NOW LEARNED THAT THE HARD WAY.
+ *
+ * The surface lease learned it first: `src` and `src/app` are different
+ * directories with independent ordinals, so "who got there first" is not a
+ * question their contents can answer. MEASURED with the read-back in place and
+ * no mutex: eight racers produced FOUR simultaneous holders, three trials
+ * running.
+ *
+ * The spend ledger learned it second, and worse. Its claimants DID share one
+ * sequence — an append-only file ordered by `(at, id)` — and it still was not
+ * enough. A claimant that obtained an early ordering key and published it LATE
+ * was counted by nobody: everyone who decided in between sorted after it and so
+ * was excluded from its own view. MEASURED against a $3 ceiling with $2
+ * estimates: B published at T+1000 and was admitted, A published at T and was
+ * admitted, and the window held $4. A total order over rows says who is first;
+ * it does not say who has already been told yes.
+ *
+ * So the operation that makes an admission authoritative is the WHOLE
+ * check-and-claim, taken inside this lock. Publication and decision happen in
+ * the same critical section, so there is no interval in which a claim has been
+ * decided but not published — which is exactly what makes a late publication
+ * harmless: there is no such thing.
+ *
+ * ⚠️ THE READ PATHS TAKE NOTHING. `holderOf`, `checkFence` and `spendInWindow`
+ * stay lock-free; only the writers serialise. Acquisition happens once per run
+ * and takes microseconds.
+ *
+ * ⚠️ AND A DEAD HOLDER'S LOCK IS BROKEN BY CONTENT MATCH, NEVER BY PATH. Phase
+ * 1 measured what removing a lock by path costs: a process that had already lost
+ * its claim deleted the winner's, and four processes then held one lock.
+ *
+ * ⚠️ ONE IMPLEMENTATION, NOT TWO. This was extracted from `surface-lease` rather
+ * than copied beside it. A second "safe enough" mutex is how two callers come to
+ * disagree about what holding one means.
+ */
+exports.EXCLUSIVE_LOCK_WAIT_MS = 5_000;
+/**
+ * F43: HOW LONG A WAITER PAUSES BETWEEN ATTEMPTS. It waits; it does not spin.
+ * A wait sized for microsecond critical sections could afford a busy loop; the
+ * shared-grant lock is held across an ACL write that takes tens of seconds, and
+ * a spinning waiter burns a core and hammers the lock file for all of it.
+ * `Atomics.wait` blocks the thread without the event loop, which this
+ * synchronous function already does.
+ */
+exports.EXCLUSIVE_LOCK_PAUSE_MS = 20;
+const PAUSE = new Int32Array(new SharedArrayBuffer(4));
+function withExclusiveLock(path, fn, fallback, waitMs = exports.EXCLUSIVE_LOCK_WAIT_MS) {
+    const mine = `${JSON.stringify({ pid: process.pid, host: (0, node_os_1.hostname)(), at: new Date().toISOString() })}\n`;
+    /**
+     * 🔴 THIS FUNCTION DOES NOT THROW ON A LOCK IT CANNOT TAKE — IT REFUSES.
+     *
+     * The extracted version rethrew an unexpected errno and let `mkdirSync`
+     * escape, and that turned a REFUSAL into a CRASH at the budget seam: a home
+     * directory that is a FILE — which is exactly how `admitSpend` is asked to
+     * prove it refuses when it cannot record — threw ENOTDIR out of the lock
+     * instead of answering "could not record what it is about to spend".
+     *
+     * Both callers already treat "could not serialise" as a refusal, and a
+     * refusal is the only safe reading of it. So every acquisition failure comes
+     * out of `fallback` with its reason. `fn()` is deliberately outside this: a
+     * caller's own error is not a lock failure and must propagate.
+     */
+    try {
+        (0, node_fs_1.mkdirSync)((0, node_path_1.dirname)(path), { recursive: true });
+    }
+    catch (e) {
+        return fallback(`this lock's directory could not be created: ${e.message}`);
+    }
+    let refused = null;
+    const take = () => {
+        try {
+            (0, node_fs_1.writeFileSync)(path, mine, { encoding: 'utf8', flag: 'wx' });
+            return true;
+        }
+        catch (e) {
+            const code = e.code;
+            // Windows answers EPERM rather than EEXIST against a pending-delete file.
+            if (code === 'EEXIST' || code === 'EPERM')
+                return false;
+            refused = e.message;
+            return false;
+        }
+    };
+    const deadline = Date.now() + waitMs;
+    let held = take();
+    while (!held && refused === null && Date.now() < deadline) {
+        Atomics.wait(PAUSE, 0, 0, exports.EXCLUSIVE_LOCK_PAUSE_MS);
+        // A holder that is gone leaves a lock nobody will ever release. Broken by
+        // reading the file, judging that pid, and removing only if the bytes have
+        // not changed in between.
+        let raw = null;
+        try {
+            raw = (0, node_fs_1.readFileSync)(path, 'utf8');
+        }
+        catch {
+            raw = null;
+        }
+        if (raw !== null) {
+            let owner = {};
+            try {
+                owner = JSON.parse(raw);
+            }
+            catch {
+                owner = {};
+            }
+            const judgeable = owner.host === (0, node_os_1.hostname)() && typeof owner.pid === 'number';
+            if (judgeable && (0, run_lease_1.nodeProbe)(owner.pid) === 'dead') {
+                try {
+                    if ((0, node_fs_1.readFileSync)(path, 'utf8') === raw)
+                        (0, node_fs_1.unlinkSync)(path);
+                }
+                catch {
+                    /* somebody else got there first, which is fine */
+                }
+            }
+        }
+        held = take();
+    }
+    if (!held) {
+        return fallback(refused === null
+            ? 'another process is holding this lock and did not finish in time'
+            : `this lock could not be taken: ${refused}`);
+    }
+    try {
+        return fn();
+    }
+    finally {
+        try {
+            if ((0, node_fs_1.readFileSync)(path, 'utf8') === mine)
+                (0, node_fs_1.unlinkSync)(path);
+        }
+        catch {
+            /* already gone, or broken by somebody who judged us dead */
+        }
+    }
+}
+//# sourceMappingURL=exclusive-lock.js.map

package/dist/exclusive-lock.js.map

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

package/dist/exec-domains.d.ts

@@ -0,0 +1,140 @@
+import { type FsGrant, type UntrustedKind } from './untrusted-exec';
+/**
+ * WHICH SIDE OF THE BOUNDARY A CHILD BELONGS ON, AND WHAT IT IS HANDED.
+ *
+ * There are exactly two domains and the rule for sorting into them is short: if
+ * anything about what runs can be influenced by project source, project config
+ * or the coding model, it is UNTRUSTED. That includes `npm test` — npm is not
+ * the point, the code underneath it is.
+ *
+ * TRUSTED children are Looply's own: git with argv Looply built, the run child,
+ * the containment helper. They keep the daemon's authority because they are the
+ * daemon.
+ *
+ * The environments are built here rather than at each call site so there is one
+ * place to read when asking what a contained process can see — and so that
+ * "start from `process.env` and delete the scary ones" is not expressible. Each
+ * builder starts from the platform baseline and adds, which fails safe when a
+ * new secret appears in the daemon's environment later.
+ */
+/** The trust domain of a child process. */
+export type ExecutionDomain = 'trusted' | 'untrusted';
+/**
+ * Where a contained child keeps the profile Windows insists it has.
+ *
+ * An AppContainer needs USERPROFILE/APPDATA/LOCALAPPDATA to start at all — the
+ * loader resolves the container's redirected storage through them. Pointing
+ * them at the daemon's profile would hand back everything the container exists
+ * to keep away: `~/.looply/machine.json`, `~/.claude`, `~/.gitconfig`. So the
+ * child gets its own, created beside the system temp directory and granted to
+ * it explicitly.
+ *
+ * Per project and per domain, so a gate cannot read what an agent left behind.
+ */
+export declare function containedRoot(kind: UntrustedKind, projectKey: string): string;
+/**
+ * The environment for project-controlled test, build and typecheck commands.
+ *
+ * Carries no credential of any kind. The two extras are both about making the
+ * boundary work rather than about trust:
+ *
+ * `NODE_OPTIONS` — an AppContainer cannot stat `C:\`, and Node's module
+ * resolution walks to the drive root, so without these flags nothing Node runs
+ * at all. Scoped here rather than set on the daemon.
+ *
+ * `GIT_CONFIG_NOSYSTEM` — defence in depth only. It removes the system git
+ * config, and with it the ambient credential helper, from anything the gate
+ * runs. It is NOT the boundary: a determined process can clear a variable. The
+ * container is the boundary.
+ */
+export declare function buildUntrustedGateEnv(projectKey: string, toolchain?: string): Record<string, string>;
+/**
+ * The search path a contained child gets.
+ *
+ * Built, not inherited. The daemon's PATH names sixty-odd directories the
+ * container cannot read, and — worse — it names the real toolchain directory,
+ * which on this machine also holds `claude`, `eas` and `heroku` shims. A gate
+ * that could resolve those would be a gate that could deploy.
+ *
+ * So: Looply's own runtime copy first, then the project's own `.bin` (which is
+ * inside the granted worktree and is how `tsc`, `jest` and friends are found),
+ * then the two system directories a shell needs to function.
+ */
+export declare function containedPath(projectKey: string, toolchain?: string): string;
+/**
+ * The environment for the coding agent.
+ *
+ * Separate from the gate's because the agent legitimately needs its model
+ * provider — and separate so that giving the agent something never gives it to
+ * the gate. It still carries no Looply machine token and no broker credential:
+ * using the model is the agent's job, speaking for the machine is not.
+ */
+export declare function buildAgentEnv(projectKey: string, provider?: Record<string, string>, toolchain?: string): Record<string, string>;
+/**
+ * The environment for the PROVIDER TRANSPORT.
+ *
+ * This one is different in kind from the others, and the difference is the
+ * point of the whole decomposition. The transport is not contained — it cannot
+ * be, because the packaged provider spawns children with piped stdio and an
+ * AppContainer cannot create the named pipes that needs. So it runs as the
+ * daemon user, and the only thing standing between it and the machine's
+ * authority is what Looply chooses to hand it.
+ *
+ * Which is: the platform baseline, its own profile, and whatever the person
+ * named in `agent.env`. Built up rather than filtered down, so a Looply
+ * credential added to the daemon's environment next year does not silently
+ * appear here.
+ *
+ * It carries NO PATH into the project. The transport has no reason to resolve
+ * anything from the worktree; the tools it can call are served over MCP and run
+ * somewhere else entirely.
+ */
+export declare function buildProviderEnv(sessionDir: string, provider?: Record<string, string>): Record<string, string>;
+/**
+ * The environment for the user's own notification script.
+ *
+ * NOT contained: this file is the person's, stored under their home directory,
+ * and running it is the product working as intended. But it inherited the whole
+ * daemon environment — every secret the daemon holds — for no reason at all. A
+ * notification does not need the machine token.
+ */
+export declare function buildNotifyEnv(): Record<string, string>;
+/**
+ * Paths inside a granted worktree that untrusted execution must never reach.
+ *
+ * Derived from the execution kind rather than chosen per call site, because a
+ * caller that forgets one is a caller that quietly hands over the authority
+ * state.
+ *
+ * `.looply/state` holds every durable fact Phase 6 rests on — the grant, the
+ * receipts, the launch and claim records, the ledger, the human control file.
+ * `.git` is where a repository-controlled config can turn a trusted git command
+ * into arbitrary execution. `config.yaml` is the one file the person edits by
+ * hand, and it names the gate commands and the rails: a round that could write
+ * it could weaken every round after it.
+ *
+ * `<projectDir>/.git` IS PROTECTED WHATEVER IT TURNS OUT TO BE. In a linked
+ * worktree it is a pointer file rather than a directory, and a write to it
+ * redirects every later git command at metadata of the writer's choosing — so
+ * it is protected for its own sake, not merely as a route to a directory.
+ *
+ * AND WHEREVER THE METADATA REALLY LIVES, appended below. In a linked worktree
+ * the real gitdir is `<common>/worktrees/<name>` and the config that decides
+ * what git executes is in the shared common dir; neither is under `projectDir`,
+ * so neither is covered by the three literals.
+ *
+ * ⚠️ THE THREE LITERALS STAY AT THE TOP OF THE BODY, and the prose stays up
+ * here. `project-memory-reachability.spec.ts` pins them by slicing the first 400
+ * characters after the signature — a deliberate guard on the ground under
+ * `source: 'human'` — and a comment inside the body pushes them out of it.
+ */
+export declare function protectedPaths(projectDir: string): string[];
+/** What untrusted execution is granted: the worktree, and its own profile. */
+export declare function untrustedGrants(kind: UntrustedKind, projectDir: string): FsGrant[];
+/**
+ * The shared directories a contained execution needs, which are granted under
+ * the shared-grant lock rather than per launch. `toolchain` is absent for the
+ * built-in provider, which resolves its own.
+ */
+export declare function sharedGrantPaths(toolchain?: string, extra?: readonly string[]): string[];
+//# sourceMappingURL=exec-domains.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"exec-domains.d.ts","sourceRoot":"","sources":["../src/exec-domains.ts"],"names":[],"mappings":"AAIA,OAAO,EAA6B,KAAK,OAAO,EAAE,KAAK,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAG/F;;;;;;;;;;;;;;;;;GAiBG;AAEH,2CAA2C;AAC3C,MAAM,MAAM,eAAe,GAAG,SAAS,GAAG,WAAW,CAAC;AAEtD;;;;;;;;;;;GAWG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,CAO7E;AAiDD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,qBAAqB,CACnC,UAAU,EAAE,MAAM,EAClB,SAAS,CAAC,EAAE,MAAM,GACjB,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAUxB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,aAAa,CAAC,UAAU,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,MAAM,CAS5E;AAED;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAC3B,UAAU,EAAE,MAAM,EAClB,QAAQ,GAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAM,EACrC,SAAS,CAAC,EAAE,MAAM,GACjB,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CASxB;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,gBAAgB,CAC9B,UAAU,EAAE,MAAM,EAClB,QAAQ,GAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAM,GACpC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAWxB;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,IAAI,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAOvD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAgB,cAAc,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,EAAE,CAoB3D;AAED,8EAA8E;AAC9E,wBAAgB,eAAe,CAAC,IAAI,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,EAAE,CA2BlF;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,SAAS,CAAC,EAAE,MAAM,EAAE,KAAK,GAAE,SAAS,MAAM,EAAO,GAAG,MAAM,EAAE,CAE5F"}