@vibe-commit/capture 0.7.0 → 0.9.0

package/dist/pending_revoke.js

@@ -0,0 +1,233 @@
+/**
+ * Pending revokes (slice 2, S4, R3-11): the WRITE-AHEAD record of a credential `g` has made and not yet been told to keep.
+ *
+ * ```
+ *   addPendingRevoke(home, credential, endpoint, now)   at the mint, BEFORE anything else: refuses (never overwrites) when it cannot
+ *   removePendingRevoke(home, token)                    after the revoke, or after the credential is kept: re-reads, removes ONE row
+ *   revokeHeld(home, token, fetch)                      one best-effort revoke (3 s) of a row, to ITS recorded origin
+ *   retryPendingRevokes(home, env, fetch, now)          every user-facing verb, once, at its start: one 3 s bound across all rows
+ *   readPendingRevokes(home)                            how many are waiting (for `status`'s `pending` count)
+ * ```
+ *
+ * ## ⛔ WHY IT IS WRITE-AHEAD
+ *
+ * `g` is the one place a credential is made ahead of consent (exception 3). So the credential lives in MEMORY until the yes:
+ * `credentials.json` does not exist before it, and the row below is written the instant the server hands the token over. A kill, a
+ * second Ctrl+C, a SIGHUP at the y/N or an unexpected throw therefore leaves a ROW (which the next verb revokes), never a live
+ * credential on disk that nothing remembers. The yes commits in this order: the grants, then `credentials.json`, then the row's
+ * deletion; a retry skips and drops any row whose token IS the current credential, so a kill between the last two never revokes what
+ * the user kept.
+ *
+ * ## ⛔ THE FILE HOLDS A BEARER TOKEN — the same exposure class as `credentials.json`, held to the same rules
+ *   - written mode 0600 under the 0700 directory, temp + rename;
+ *   - READ through `readSecretFile`: a file or folder others can read is refused, and an insecure or unreadable file is NEVER
+ *     overwritten (the writer refuses, and `g` fails closed);
+ *   - never printed, logged or returned: `status` counts the rows and shows nothing else, `--json` included;
+ *   - a hook never touches it (only the CLI verbs import this module; `test/connect-account.test.ts` walks the hooks' import graph).
+ *
+ * ## ⛔ A ROW IS NEVER DROPPED UNREVOKED, except by the clock
+ *   - it leaves on a 2xx, a 401 (the server does not accept it: already dead) or a 404 (a server that cannot revoke);
+ *   - or at `minted_at` + 91 days: a token that was never on disk was never used, and an ingest credential ends 90 days unused;
+ *   - there is no row cap that drops one: at the cap `addPendingRevoke` REFUSES, and `g` fails closed.
+ *
+ * ## ⛔ THE ORIGIN IS THE ROW'S
+ *
+ * A row records the issuing server's origin and a retry goes ONLY there (https, or http on loopback: `isAllowedIngestUrl`), never to
+ * wherever `VIBECOMMIT_MCP_URL` points today.
+ */
+import { chmodSync, mkdirSync, readFileSync, unlinkSync } from "node:fs";
+import { writeFileAtomic } from "./atomic_write.js";
+import { IngestCredential, INGEST_TOKEN_PREFIX } from "./credential.js";
+import { LEASE_MS, leased, readPendingRevokes, readQueue } from "./pending_revoke_file.js";
+import { REVOKE_TIMEOUT_MS, selfRevokeOutcome } from "./oauth/retire.js";
+import { credentialsPath, pendingRevokePath, rootDir } from "./paths.js";
+import { isAllowedIngestUrl } from "./post.js";
+export { readPendingRevokes } from "./pending_revoke_file.js";
+/** More rows than `g` can produce in earnest: past it `g` refuses rather than drop one. */
+export const MAX_ROWS = 8;
+/** A token never used ends 90 days after it is made; one day of slack. */
+const MAX_AGE_MS = 91 * 24 * 60 * 60 * 1000;
+/** One best-effort revoke, and the bound on a verb's whole retry. */
+export { REVOKE_TIMEOUT_MS };
+function writeRows(home, rows) {
+    if (rows.length === 0) {
+        try {
+            unlinkSync(pendingRevokePath(home));
+        }
+        catch {
+            /* already gone */
+        }
+        return;
+    }
+    mkdirSync(rootDir(home), { recursive: true, mode: 0o700 });
+    chmodSync(rootDir(home), 0o700);
+    writeFileAtomic(pendingRevokePath(home), `${JSON.stringify({ revokes: rows }, null, 2)}\n`, 0o600);
+}
+/**
+ * Write the row for a credential that has just been made. Never overwrites a file it cannot read, never drops a row.
+ * `lease: true` is `g` holding the credential at its y/N: the row carries `{ pid, lease_until }` (30 minutes) so another verb's retry
+ * leaves it alone while it is kept; every other writer (a test, an orphaned row) has no lease and is retried at once.
+ */
+export function addPendingRevoke(home, credential, endpoint, now, options = {}) {
+    try {
+        const token = credential.expose();
+        if (!token.startsWith(INGEST_TOKEN_PREFIX))
+            return { kind: "failed" };
+        const queue = readQueue(home);
+        if (queue.kind === "refused")
+            return { kind: "refused", read: queue.read };
+        const rows = queue.kind === "ok" ? queue.rows : [];
+        if (rows.some((row) => row.token === token))
+            return { kind: "written" };
+        if (rows.length >= MAX_ROWS)
+            return { kind: "full" };
+        const lease = options.lease === true ? { pid: process.pid, lease_until: new Date(now.getTime() + LEASE_MS).toISOString() } : null;
+        writeRows(home, [...rows, { token, minted_at: now.toISOString(), origin: new URL(endpoint).origin, lease }]);
+        return { kind: "written" };
+    }
+    catch {
+        return { kind: "failed" };
+    }
+}
+/** Remove ONE row, re-reading just before the write so a row queued in between survives. Deletes the file when it is empty. Never throws. */
+export function removePendingRevoke(home, token) {
+    removeRows(home, new Set([token]));
+}
+/** Give the row up to the retry: `g` is no longer holding the credential, so the next verb may revoke it. Re-reads before it writes. */
+export function releaseLease(home, token) {
+    try {
+        const queue = readQueue(home);
+        if (queue.kind !== "ok" || !queue.rows.some((row) => row.token === token && row.lease !== null))
+            return;
+        writeRows(home, queue.rows.map((row) => (row.token === token ? { ...row, lease: null } : row)));
+    }
+    catch {
+        /* the lease runs out by itself */
+    }
+}
+/**
+ * Is the row for `token` still there? `g` asks just before it commits, and the three answers are different things:
+ *   - `held`: the row is in a queue this client can use;
+ *   - `gone`: the queue is readable and the row is not in it — another verb settled (revoked) it;
+ *   - `unusable`: the queue is insecure or unreadable. Nobody revoked anything; this client can neither keep nor settle the record.
+ */
+export function holdsRow(home, token) {
+    const queue = readQueue(home);
+    if (queue.kind === "refused")
+        return "unusable";
+    return queue.kind === "ok" && queue.rows.some((row) => row.token === token) ? "held" : "gone";
+}
+function removeRows(home, tokens) {
+    try {
+        const queue = readQueue(home);
+        if (queue.kind !== "ok")
+            return;
+        const rows = queue.rows.filter((row) => !tokens.has(row.token));
+        if (rows.length !== queue.rows.length)
+            writeRows(home, rows);
+    }
+    catch {
+        /* the row stays; the next verb retries */
+    }
+}
+/** Revoke a token, with itself as the bearer, at `origin` — and only where a credential may be sent at all. */
+async function revokeToken(origin, token, fetchImpl, timeoutMs) {
+    if (!isAllowedIngestUrl(origin))
+        return null;
+    const outcome = await selfRevokeOutcome(origin, new IngestCredential(token, "file"), { fetch: fetchImpl, timeoutMs });
+    return outcome.kind === "retired" || outcome.kind === "gone" ? "revoked" : outcome.kind === "unknown" ? "unrevocable" : null;
+}
+/** The tokens this machine is using right now: `credentials.json`'s, read RAW (a mode problem does not hide it) and the environment's. */
+function currentTokens(home, env) {
+    const out = new Set();
+    try {
+        const token = JSON.parse(readFileSync(credentialsPath(home), "utf8")).token;
+        if (typeof token === "string" && token !== "")
+            out.add(token);
+    }
+    catch {
+        /* no file, or not ours: nothing to protect */
+    }
+    const envToken = env.VIBECOMMIT_TOKEN?.trim();
+    if (envToken !== undefined && envToken !== "")
+        out.add(envToken);
+    return out;
+}
+/**
+ * `g`'s every no-grant exit: one revoke within 3 s. With a readable row it goes to the row's recorded origin and removes the row on a
+ * 2xx, 401 or 404 (a failure gives the lease up so the next verb retries). With NO usable row — missing, or the queue refused — it
+ * revokes with the in-memory credential at the MINTED origin: a missing row is never taken for "already revoked".
+ */
+export async function revokeHeld(home, credential, mintedOrigin, fetchImpl) {
+    const token = credential.expose();
+    let insecure = null;
+    try {
+        const queue = readQueue(home);
+        const row = queue.kind === "ok" ? queue.rows.find((r) => r.token === token) : undefined;
+        if (queue.kind === "refused" && queue.read.kind === "insecure-file")
+            insecure = queue.read;
+        if (row !== undefined) {
+            const ended = await revokeToken(row.origin, token, fetchImpl, REVOKE_TIMEOUT_MS);
+            if (ended !== null) {
+                removePendingRevoke(home, token);
+                return { kind: ended, insecure };
+            }
+            releaseLease(home, token);
+            return { kind: "waiting", insecure };
+        }
+        const ended = await revokeToken(mintedOrigin, token, fetchImpl, REVOKE_TIMEOUT_MS);
+        return { kind: ended ?? "orphan", insecure };
+    }
+    catch {
+        return { kind: "orphan", insecure };
+    }
+}
+/**
+ * Every user-facing verb, once, at its start: one attempt at each row, and ONE 3 s bound across all of them (a row gets what is
+ * left of the bound, and none is attempted once it is spent). Silent, and needs no credential.
+ *
+ * Before EACH request it re-reads the queue and the current credential (a credential committed, or a row settled, after the loop
+ * began is never revoked on a stale view), and it
+ *   - skips and DROPS a row whose token is the current credential (the user kept it; the kill came between the credential's write
+ *     and the row's deletion) — compared on the file's raw token, so a mode problem does not hide a kept credential;
+ *   - skips (and keeps) a LEASED row: `g` is holding it at its y/N in another process;
+ *   - drops a row past `minted_at` + 91 days.
+ * Removes each row it settles as it goes, re-reading just before it writes. Returns how many rows still wait. Never throws.
+ */
+export async function retryPendingRevokes(home, env, fetchImpl, now, deadlineMs = REVOKE_TIMEOUT_MS) {
+    try {
+        const first = readQueue(home);
+        if (first.kind !== "ok")
+            return 0;
+        const started = Date.now();
+        for (const listed of first.rows) {
+            const fresh = readQueue(home);
+            if (fresh.kind !== "ok")
+                break;
+            const row = fresh.rows.find((r) => r.token === listed.token);
+            if (row === undefined)
+                continue;
+            if (currentTokens(home, env).has(row.token)) {
+                removePendingRevoke(home, row.token);
+                continue;
+            }
+            if (leased(row, now))
+                continue;
+            const age = now.getTime() - Date.parse(row.minted_at);
+            if (Number.isFinite(age) && age > MAX_AGE_MS) {
+                removePendingRevoke(home, row.token);
+                continue;
+            }
+            const left = deadlineMs - (Date.now() - started);
+            if (left <= 0)
+                break;
+            if ((await revokeToken(row.origin, row.token, fetchImpl, left)) !== null)
+                removePendingRevoke(home, row.token);
+        }
+        return readPendingRevokes(home).length;
+    }
+    catch {
+        return readPendingRevokes(home).length;
+    }
+}
+//# sourceMappingURL=pending_revoke.js.map

package/dist/pending_revoke.js.map

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

package/dist/pending_revoke_file.d.ts

@@ -0,0 +1,55 @@
+/**
+ * The pending-revoke queue's FILE: its path's format, and reading it (slice 2, S4). Split from `pending_revoke.ts` so that what
+ * `status` needs — a COUNT — does not drag the writer and the network revoke onto every process's load path.
+ *
+ * Read through `readSecretFile` (the same mode checks as `credentials.json`): a file or folder others can read, a file that is not
+ * what this client wrote, or one with a row it cannot read all come back `refused`, and `pending_revoke.ts` never overwrites those.
+ * Nothing here writes, sends or prints a token; the only thing it hands `status` is how many rows wait.
+ */
+import { type SecretFileRead } from "./credential.js";
+export interface PendingRevoke {
+    readonly token: string;
+    /** ISO 8601, when the server made the credential. */
+    readonly minted_at: string;
+    /** The issuing server's origin (`https://api.vibecommit.ai`): the only place a retry sends this token. */
+    readonly origin: string;
+    /**
+     * While `g` is holding the credential (waiting at its y/N) the row carries the holder's lease: a retry run by ANOTHER verb in the
+     * meantime must not revoke a credential that is about to be kept. A row with no lease is an orphan. See `leased`.
+     */
+    readonly lease: {
+        readonly pid: number;
+        readonly lease_until: string;
+    } | null;
+}
+/** How long a holder's lease lasts: a `g` whose question stays open longer may be revoked by another verb, and its commit then refuses. */
+export declare const LEASE_MS: number;
+/**
+ * Is the row leased at `now`? BOTH must hold: the holder's pid is alive (`kill(pid, 0)`: EPERM counts as alive, ESRCH as dead) and
+ * `now` is before the EARLIER of the row's own `lease_until` and `minted_at` + 30 minutes. The lease is capped at its mint: a
+ * `lease_until` written far in the future (a bug, or an edit) does not keep a live pid's row out of the retry for ever. A dead holder or
+ * an expired lease is an orphan, which any verb's retry revokes.
+ */
+export declare function leased(row: PendingRevoke, now: Date): boolean;
+export type Queue = {
+    readonly kind: "ok";
+    readonly rows: PendingRevoke[];
+} | {
+    readonly kind: "absent";
+}
+/** Present but not safe to read or write: never read, never overwritten. */
+ | {
+    readonly kind: "refused";
+    readonly read: Exclude<SecretFileRead, {
+        kind: "ok";
+    } | {
+        kind: "absent";
+    }> | {
+        readonly kind: "unreadable";
+    };
+};
+export declare function readQueue(home: string): Queue;
+/** The rows waiting, for a count. An absent, insecure or unreadable file reads as none (it is never sent from). */
+export declare function readPendingRevokes(home: string): PendingRevoke[];
+/** How many rows wait: all `status` shows of the queue. */
+export declare function countPendingRevokes(home: string): number;

package/dist/pending_revoke_file.js

@@ -0,0 +1,74 @@
+/**
+ * The pending-revoke queue's FILE: its path's format, and reading it (slice 2, S4). Split from `pending_revoke.ts` so that what
+ * `status` needs — a COUNT — does not drag the writer and the network revoke onto every process's load path.
+ *
+ * Read through `readSecretFile` (the same mode checks as `credentials.json`): a file or folder others can read, a file that is not
+ * what this client wrote, or one with a row it cannot read all come back `refused`, and `pending_revoke.ts` never overwrites those.
+ * Nothing here writes, sends or prints a token; the only thing it hands `status` is how many rows wait.
+ */
+import { INGEST_TOKEN_PREFIX, readSecretFile } from "./credential.js";
+import { pendingRevokePath } from "./paths.js";
+/** How long a holder's lease lasts: a `g` whose question stays open longer may be revoked by another verb, and its commit then refuses. */
+export const LEASE_MS = 30 * 60 * 1000;
+/**
+ * Is the row leased at `now`? BOTH must hold: the holder's pid is alive (`kill(pid, 0)`: EPERM counts as alive, ESRCH as dead) and
+ * `now` is before the EARLIER of the row's own `lease_until` and `minted_at` + 30 minutes. The lease is capped at its mint: a
+ * `lease_until` written far in the future (a bug, or an edit) does not keep a live pid's row out of the retry for ever. A dead holder or
+ * an expired lease is an orphan, which any verb's retry revokes.
+ */
+export function leased(row, now) {
+    if (row.lease === null)
+        return false;
+    const until = Math.min(Date.parse(row.lease.lease_until), Date.parse(row.minted_at) + LEASE_MS);
+    if (!(until > now.getTime()))
+        return false;
+    try {
+        process.kill(row.lease.pid, 0);
+        return true;
+    }
+    catch (error) {
+        return error.code === "EPERM";
+    }
+}
+export function readQueue(home) {
+    const read = readSecretFile(home, pendingRevokePath(home));
+    if (read.kind === "absent")
+        return { kind: "absent" };
+    if (read.kind !== "ok")
+        return { kind: "refused", read };
+    try {
+        const doc = JSON.parse(read.raw);
+        if (doc === null || typeof doc !== "object" || !Array.isArray(doc.revokes))
+            return { kind: "refused", read: { kind: "unreadable" } };
+        const rows = [];
+        for (const row of doc.revokes) {
+            if (row === null || typeof row !== "object")
+                return { kind: "refused", read: { kind: "unreadable" } };
+            const r = row;
+            if (typeof r.token !== "string" || !r.token.startsWith(INGEST_TOKEN_PREFIX) || typeof r.minted_at !== "string" || typeof r.origin !== "string") {
+                // A row this client cannot read is a row it must not lose: refuse the whole file rather than rewrite it without the row.
+                return { kind: "refused", read: { kind: "unreadable" } };
+            }
+            // A lease this client cannot read is NO lease: the row is an orphan, which errs toward revoking.
+            const l = r.lease;
+            const lease = l !== null && l !== undefined && typeof l === "object" && typeof l.pid === "number" && Number.isInteger(l.pid) && typeof l.lease_until === "string"
+                ? { pid: l.pid, lease_until: l.lease_until }
+                : null;
+            rows.push({ token: r.token, minted_at: r.minted_at, origin: r.origin, lease });
+        }
+        return { kind: "ok", rows };
+    }
+    catch {
+        return { kind: "refused", read: { kind: "unreadable" } };
+    }
+}
+/** The rows waiting, for a count. An absent, insecure or unreadable file reads as none (it is never sent from). */
+export function readPendingRevokes(home) {
+    const queue = readQueue(home);
+    return queue.kind === "ok" ? queue.rows : [];
+}
+/** How many rows wait: all `status` shows of the queue. */
+export function countPendingRevokes(home) {
+    return readPendingRevokes(home).length;
+}
+//# sourceMappingURL=pending_revoke_file.js.map

package/dist/pending_revoke_file.js.map

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

package/dist/physical_path.d.ts

@@ -0,0 +1,46 @@
+/**
+ * C70: ONE resolver for every path judgement.
+ *
+ * JavaScript's `realpathSync` runs `path.resolve` FIRST, which collapses `..` lexically: `A/shared/../secret.env`, with `A/shared` a link to `/repos/B/pkg`, is judged
+ * `A/secret.env`, while the kernel (and `realpathSync.native`) open `/repos/B/secret.env`. A call that runs in, or writes into, another repository through a link
+ * and a `..` was judged as this one. `physicalPath` walks the RAW components forward with a physical cursor, as the kernel does: `.` and empty components are
+ * skipped, `..` is the parent of the PHYSICAL cursor, and a component that is a link is replaced by its fully resolved target. Nothing is normalised before it.
+ *
+ * Fail closed: a component that exists but cannot be resolved (a dangling link, a loop, an unreadable folder) makes the whole path `null`.
+ */
+/** The longest path, in bytes, that is resolved at all: at least the longest the kernel accepts (Linux 4,095 bytes, macOS 1,024), so nothing longer could have been opened. */
+export declare const MAX_PATH_BYTES = 4096;
+/** C74 (3): is this path (as a record wrote it) longer than any path the kernel could have opened? Such a path is unresolvable AT PLACEMENT: it is never stored. */
+export declare function pathTooLong(path: string): boolean;
+/**
+ * `base` + `relative`, the way the kernel reads them: a trailing separator is not doubled and `.` / empty components are dropped, but `..` is KEPT (it is only
+ * meaningful after the links before it are resolved, which is `physicalPath`'s job).
+ */
+export declare function joinRaw(base: string, relative: string): string;
+/** Where a walk ended: `path` is the physical cursor (with the `depth` components below the last place that exists appended, lexically). */
+export interface PhysicalWalk {
+    readonly path: string;
+    /** How many trailing components of `path` do not exist (0: the whole path exists). Not counted: `..` that came back up through them. */
+    readonly depth: number;
+}
+/**
+ * The walk behind `physicalPath`. The kernel's own: a component that is a link is replaced, in place, by the components of its target (a relative target is read from
+ * the link's own physical parent, an absolute one from the root), so a `..` inside a target is also taken after the links before it. Only `lstat` and `readlink`
+ * are used. A link whose target is missing is dangling: `null` (it exists, so it is never "continued past"); so is a loop, a path longer than MAX_PATH_BYTES, and a
+ * component `lstat` cannot read (EACCES, ENAMETOOLONG, EIO): the hook cannot tell whether it is a link, so a `..` after it is the same case as a `..` after a link, and
+ * when the physical answer cannot be known the rule fails closed (C49 (8)). C72 (1): Claude's `isInside` therefore equals 0.8.0 on every path with no `..` after a link
+ * and no `..` after a component that cannot be read; on those paths it WITHHOLDS (over-withholding, never a leak).
+ *
+ * BELOW the last place that exists nothing can be a link and nothing needs a syscall: a missing component sets `depth` to 1, a name there is appended (depth + 1) and a
+ * `..` there takes the parent (depth - 1), all lexically; once `depth` is back at 0 the walk looks at the file system again. So a path with thousands of missing
+ * components costs no more than its existing part.
+ */
+export declare function physicalWalk(raw: string): PhysicalWalk | null;
+/**
+ * The physical place `raw` names. `missing`: `"extend"` (default) keeps a path whose last components are not there (a file that is to be created; the caller
+ * works up to the nearest place that exists); `"fail"`: the whole path must exist (`null` otherwise, as `realpathSync` threw). `..` is taken in both after the links
+ * before it. A relative `raw` is read from the working folder.
+ */
+export declare function physicalPath(raw: string, missing?: "extend" | "fail"): string | null;
+/** The nearest place that EXISTS at or above `raw`, physically; `null` for a dangling link or a loop, or when more than `maxMissing` components are missing. */
+export declare function nearestExistingPhysical(raw: string, maxMissing?: number): string | null;

package/dist/physical_path.js

@@ -0,0 +1,151 @@
+/**
+ * C70: ONE resolver for every path judgement.
+ *
+ * JavaScript's `realpathSync` runs `path.resolve` FIRST, which collapses `..` lexically: `A/shared/../secret.env`, with `A/shared` a link to `/repos/B/pkg`, is judged
+ * `A/secret.env`, while the kernel (and `realpathSync.native`) open `/repos/B/secret.env`. A call that runs in, or writes into, another repository through a link
+ * and a `..` was judged as this one. `physicalPath` walks the RAW components forward with a physical cursor, as the kernel does: `.` and empty components are
+ * skipped, `..` is the parent of the PHYSICAL cursor, and a component that is a link is replaced by its fully resolved target. Nothing is normalised before it.
+ *
+ * Fail closed: a component that exists but cannot be resolved (a dangling link, a loop, an unreadable folder) makes the whole path `null`.
+ */
+import { lstatSync, readlinkSync } from "node:fs";
+import { dirname, isAbsolute, parse, sep } from "node:path";
+/** More components than any path the OS accepts (PATH_MAX is 4096): a longer one is not resolved. */
+const MAX_COMPONENTS = 4096;
+/** The longest path, in bytes, that is resolved at all: at least the longest the kernel accepts (Linux 4,095 bytes, macOS 1,024), so nothing longer could have been opened. */
+export const MAX_PATH_BYTES = 4096;
+/** C74 (3): is this path (as a record wrote it) longer than any path the kernel could have opened? Such a path is unresolvable AT PLACEMENT: it is never stored. */
+export function pathTooLong(path) {
+    return Buffer.byteLength(path, "utf8") > MAX_PATH_BYTES;
+}
+/**
+ * `base` + `relative`, the way the kernel reads them: a trailing separator is not doubled and `.` / empty components are dropped, but `..` is KEPT (it is only
+ * meaningful after the links before it are resolved, which is `physicalPath`'s job).
+ */
+export function joinRaw(base, relative) {
+    const parts = relative.split("/").filter((part) => part !== "" && part !== ".");
+    if (parts.length === 0)
+        return base;
+    return `${base.endsWith(sep) ? base : base + sep}${parts.join(sep)}`;
+}
+/** The kernel's own limit on links followed while resolving one path (MAXSYMLINKS is 32 on Linux, 40 elsewhere). */
+const MAX_LINKS = 40;
+/**
+ * The walk behind `physicalPath`. The kernel's own: a component that is a link is replaced, in place, by the components of its target (a relative target is read from
+ * the link's own physical parent, an absolute one from the root), so a `..` inside a target is also taken after the links before it. Only `lstat` and `readlink`
+ * are used. A link whose target is missing is dangling: `null` (it exists, so it is never "continued past"); so is a loop, a path longer than MAX_PATH_BYTES, and a
+ * component `lstat` cannot read (EACCES, ENAMETOOLONG, EIO): the hook cannot tell whether it is a link, so a `..` after it is the same case as a `..` after a link, and
+ * when the physical answer cannot be known the rule fails closed (C49 (8)). C72 (1): Claude's `isInside` therefore equals 0.8.0 on every path with no `..` after a link
+ * and no `..` after a component that cannot be read; on those paths it WITHHOLDS (over-withholding, never a leak).
+ *
+ * BELOW the last place that exists nothing can be a link and nothing needs a syscall: a missing component sets `depth` to 1, a name there is appended (depth + 1) and a
+ * `..` there takes the parent (depth - 1), all lexically; once `depth` is back at 0 the walk looks at the file system again. So a path with thousands of missing
+ * components costs no more than its existing part.
+ */
+export function physicalWalk(raw) {
+    // C72 (2): a bound at least as large as the longest path the kernel accepts (Linux PATH_MAX counts the NUL, so 4,095 bytes; macOS 1,024): a longer path is refused with
+    // ENAMETOOLONG before any lookup, so nothing could have been opened through it. Checked before any split, so one crafted line cannot cost more than 4,096 bytes of
+    // walking (below a missing component the walk is a growing string). The absolute half rests on the agents handing the kernel the cwd-joined form (Codex joins first,
+    // mirrored by codex_folders.ts `joinRaw`; Claude's paths are absolute): a tool that passed a long relative string itself would be over-withheld, never leaked.
+    if (pathTooLong(raw))
+        return null;
+    const absolute = isAbsolute(raw) ? raw : joinRaw(process.cwd(), raw);
+    if (pathTooLong(absolute))
+        return null;
+    const root = parse(absolute).root;
+    const pending = [];
+    const parts = absolute.slice(root.length).split(sep);
+    if (parts.length > MAX_COMPONENTS)
+        return null;
+    for (let i = parts.length - 1; i >= 0; i -= 1)
+        pending.push({ part: parts[i], viaLink: false });
+    let current = root;
+    let depth = 0;
+    let links = 0;
+    let steps = 0;
+    for (let item = pending.pop(); item !== undefined; item = pending.pop()) {
+        steps += 1;
+        if (steps > 4 * MAX_COMPONENTS)
+            return null;
+        const { part, viaLink } = item;
+        if (part === "" || part === ".")
+            continue;
+        if (part === "..") {
+            current = dirname(current);
+            if (depth > 0)
+                depth -= 1;
+            continue;
+        }
+        const next = current.endsWith(sep) ? current + part : current + sep + part;
+        if (depth > 0) {
+            current = next;
+            depth += 1;
+            continue;
+        }
+        let isLink;
+        try {
+            isLink = lstatSync(next).isSymbolicLink();
+        }
+        catch (error) {
+            const code = error.code;
+            if (code !== "ENOENT" && code !== "ENOTDIR")
+                return null;
+            // A component the target of a link names that is not there makes the link dangling: it exists, so it is never continued past.
+            if (viaLink)
+                return null;
+            current = next;
+            depth = 1;
+            continue;
+        }
+        if (!isLink) {
+            current = next;
+            continue;
+        }
+        links += 1;
+        if (links > MAX_LINKS)
+            return null;
+        let target;
+        try {
+            target = readlinkSync(next);
+        }
+        catch {
+            return null;
+        }
+        if (target === "")
+            return null;
+        let rest = target;
+        if (isAbsolute(target)) {
+            const targetRoot = parse(target).root;
+            current = targetRoot;
+            rest = target.slice(targetRoot.length);
+        }
+        const targetParts = rest.split(sep);
+        if (pending.length + targetParts.length > 4 * MAX_COMPONENTS)
+            return null;
+        for (let i = targetParts.length - 1; i >= 0; i -= 1)
+            pending.push({ part: targetParts[i], viaLink: true });
+    }
+    return { path: current, depth };
+}
+/**
+ * The physical place `raw` names. `missing`: `"extend"` (default) keeps a path whose last components are not there (a file that is to be created; the caller
+ * works up to the nearest place that exists); `"fail"`: the whole path must exist (`null` otherwise, as `realpathSync` threw). `..` is taken in both after the links
+ * before it. A relative `raw` is read from the working folder.
+ */
+export function physicalPath(raw, missing = "extend") {
+    const walk = physicalWalk(raw);
+    if (walk === null)
+        return null;
+    return missing === "fail" && walk.depth > 0 ? null : walk.path;
+}
+/** The nearest place that EXISTS at or above `raw`, physically; `null` for a dangling link or a loop, or when more than `maxMissing` components are missing. */
+export function nearestExistingPhysical(raw, maxMissing = 64) {
+    const walk = physicalWalk(raw);
+    if (walk === null || walk.depth > maxMissing)
+        return null;
+    let current = walk.path;
+    for (let i = 0; i < walk.depth; i += 1)
+        current = dirname(current);
+    return current;
+}
+//# sourceMappingURL=physical_path.js.map

package/dist/physical_path.js.map

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