@vibe-commit/capture 0.4.0 → 0.4.2

package/dist/pending_bound.js

@@ -0,0 +1,156 @@
+/**
+ * THE PROMOTION BOUND — `TODOS[176]`; revised after VG's review of 68eb3a7 (option A, VL ruling 2026-10-05).
+ *
+ * A pending line is promoted into the wire spool by its own session's running hook. Since the cold rung also holds the
+ * lines of a RESUMED session (state file present but not live), a pending line can be days old when that session's hook
+ * finally runs: a terminal that still exports the session id, committing by hand, would otherwise have those commits
+ * adopted as the session's own the moment it resumed. So a line is promoted only if it was OBSERVED no earlier than the
+ * START OF THE TURN the hook is delivering: `observedAt >= turnStart`.
+ *
+ * ## What "the start of the turn" is — and what 68eb3a7 got wrong
+ * 68eb3a7 compared against the FIRST unsent record. Measured with real `claude -p` (VG), that is not the turn start:
+ *   1. A session left OPEN and idle (no SessionEnd flush): after a Stop, the first unsent record is the previous Stop's
+ *      TRAILING record (attachment / stop_hook_summary), stamped at the OLD Stop time, so a lingering-id commit anywhere in
+ *      the idle gap passed `>=` and was adopted.
+ *   2. Many real records carry NO timestamp (mode, agent-name, custom-title, last-prompt, permission-mode,
+ *      file-history-snapshot, cost-state); "no bound can be computed" then meant "keep", which adopted lines 0.4.0 refused.
+ * So the turn start is the timestamp of the first unsent PROMPT-LIKE record, found by SKIPPING everything else:
+ *   - `type:"user"` whose `message.content` is a STRING (a tool_result is an array; an `isMeta` record is skipped), or
+ *   - `type:"queue-operation"` with `operation:"enqueue"` (the resume-time record `claude -p --resume` writes first).
+ * Local slash-command / `!` records are skipped (`LOCAL_RECORD`).
+ * A prompt always precedes the turn's tool calls, so it is never later than a commit made in the turn.
+ *
+ * ## Which clock is compared to which
+ * `observedAt` is the WALL CLOCK of the `post-commit` process (our process clock, written when the line was spooled).
+ * The prompt time is the `timestamp` the AGENT wrote on that record. ⛔ NEVER the committer date: it is settable
+ * (`GIT_COMMITTER_DATE`, `rebase --committer-date-is-author-date`). STRICT `>=`, no tolerance.
+ *
+ * ## The scan cap (stated): at most 64 complete records, and 8 MiB, from the sent offset — read in 64 KiB chunks
+ * 0.4.1 read ONE 64 KiB window; a big record (an attachment, a large tool_result) before the prompt pushed it out in ~1.8% of
+ * resumes (VG), and the line was dropped. Now the file is read in chunks until a prompt-like record with a timestamp is
+ * found, so a big record no longer hides the prompt. The 64-RECORD cap is unchanged, and an 8 MiB ceiling stops one
+ * pathological record from making a hook read for ever. Garbled lines and records without a valid timestamp are skipped and
+ * count toward the 64. A trailing unterminated line is not a record. A prompt beyond either cap is not found.
+ *
+ * ## What happens when no prompt time is found — the two paths differ ON PURPOSE
+ *   - STALE-OWN path (the session's state file already existed): the line is DROPPED. That is exactly what 0.4.0 did with
+ *     such a line (it never wrote one), so dropping adopts nothing 0.4.0 refused. A line with no `observedAt` is dropped
+ *     too: no 0.4.0 client wrote a stale-own pending line, so it cannot be ours.
+ *   - FIRST-TURN path (no state file yet): the line is KEPT. There the first record IS the prompt, and keeping is today's
+ *     behaviour. A legacy 0.4.0 line (no `observedAt`) is kept on this path only.
+ * A prompt dated AFTER the hook's own clock (skew: a record cannot be written ahead of now) disables the bound on both
+ * paths (kept): a bound that is demonstrably wrong must not drop a legitimate line.
+ *
+ * ## The cost, accepted (the safe direction: a lost edge, never a wrong one)
+ * A commit whose line is promoted by a hook whose unsent span has no prompt (its tool_result is the first unsent record,
+ * e.g. a hook that delivered the tool_use before the commit without refreshing liveAt) is dropped on the stale-own path.
+ */
+import { closeSync, openSync, readSync } from "node:fs";
+/** The scan reads this many bytes at a time from the sent offset… */
+export const SCAN_CHUNK_BYTES = 64 * 1024;
+/** …and at most this many in all (a whole number of chunks). Past it the answer is `none`. */
+export const SCAN_MAX_BYTES = 8 * 1024 * 1024;
+/** …and considers at most this many complete records. */
+export const SCAN_MAX_RECORDS = 64;
+const NONE = { kind: "none" };
+function isPromptLike(rec) {
+    if (rec.type === "queue-operation")
+        return rec.operation === "enqueue";
+    if (rec.type !== "user" || rec.isMeta === true)
+        return false;
+    const message = rec.message;
+    if (message === null || typeof message !== "object")
+        return false;
+    const content = message.content;
+    return typeof content === "string" && !LOCAL_RECORD.test(content);
+}
+/**
+ * A LOCAL record the CLI writes for a slash command or a `!` shell escape (`<command-name>`, `<command-message>`,
+ * `<local-command-…>`, `<bash-…>`) is `type:"user"` with STRING content and not `isMeta`, but it starts no model turn and
+ * triggers no Stop. Run as the last thing before an idle spell it is still unsent at the next turn's hook, stamped HOURS
+ * before the real prompt, so a lingering-id line observed in between would pass `>=` (VG, cell 12). Skipped. The price is
+ * the safe direction: a turn started ONLY by such a record has no turn start, so a stale-own line is dropped. Anchored at
+ * the start of the trimmed text: a real prompt that merely MENTIONS a tag still counts.
+ */
+const LOCAL_RECORD = /^\s*<(?:command-name>|command-message>|local-command|bash-)/;
+/**
+ * The turn start of the unsent span of `path` beginning at byte `offset`, as the timestamp of the first prompt-like
+ * record with a valid timestamp (see the header). `nowMs` is the hook's own clock (the skew guard).
+ */
+export function turnStart(path, offset, nowMs) {
+    if (!Number.isSafeInteger(offset) || offset < 0)
+        return NONE;
+    let fd = null;
+    try {
+        fd = openSync(path, "r");
+        const buf = Buffer.alloc(SCAN_CHUNK_BYTES);
+        // A record that crosses a chunk boundary is carried in `partial` as BYTES (never decoded early: a multi-byte character
+        // may be cut by the boundary) and decoded only once its newline arrives.
+        let partial = [];
+        let records = 0;
+        let read = 0;
+        while (read < SCAN_MAX_BYTES) {
+            const got = readSync(fd, buf, 0, SCAN_CHUNK_BYTES, offset + read);
+            if (got <= 0)
+                break;
+            read += got;
+            let start = 0;
+            for (let nl = buf.indexOf(0x0a, 0); nl !== -1 && nl < got; nl = buf.indexOf(0x0a, start)) {
+                const text = Buffer.concat([...partial, buf.subarray(start, nl)]).toString("utf8");
+                partial = [];
+                start = nl + 1;
+                records += 1;
+                if (records > SCAN_MAX_RECORDS)
+                    return NONE;
+                const found = promptStart(text, nowMs);
+                if (found !== null)
+                    return found;
+            }
+            partial.push(Buffer.from(buf.subarray(start, got))); // copy: `buf` is reused by the next read
+        }
+        return NONE;
+    }
+    catch {
+        return NONE;
+    }
+    finally {
+        if (fd !== null) {
+            try {
+                closeSync(fd);
+            }
+            catch {
+                /* nothing to do */
+            }
+        }
+    }
+}
+/** One complete record: its turn-start answer if it is a prompt-like record with a valid timestamp, else null. */
+function promptStart(line, nowMs) {
+    let rec;
+    try {
+        rec = JSON.parse(line);
+    }
+    catch {
+        return null;
+    }
+    if (rec === null || typeof rec !== "object" || Array.isArray(rec))
+        return null;
+    const r = rec;
+    if (!isPromptLike(r) || typeof r.timestamp !== "string")
+        return null;
+    const ms = Date.parse(r.timestamp);
+    if (!Number.isFinite(ms))
+        return null;
+    return ms > nowMs ? { kind: "future" } : { kind: "ts", ms };
+}
+/** Keep (promote) this pending line? See the header for the two paths. */
+export function keepsPendingLine(line, bound, mode) {
+    if (bound.kind === "future")
+        return true;
+    if (bound.kind === "none")
+        return mode === "first-turn";
+    if (line.observedAt === undefined)
+        return mode === "first-turn";
+    return line.observedAt >= bound.ms;
+}
+//# sourceMappingURL=pending_bound.js.map

package/dist/pending_bound.js.map

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

package/dist/pending_prune.d.ts

@@ -0,0 +1,60 @@
+/**
+ * ORPHAN PENDING FILES — `TODOS[175]`.
+ *
+ * A `<sid>.pending.jsonl` has ONE consumer: its own session's running hook (D2 / cross-promotion forbid any other). Two
+ * producers write them — the cold rung (an env id never seen) and, since 0.4.1, a STALE-OWN id — so an id whose session
+ * never runs again leaves its file for ever, and `status` counted it beside the real spool: a permanent "N commits are
+ * waiting" with no remedy (`finalize` has no session to close).
+ *
+ * ## Why deleting one is safe
+ * Since 0.4.1 a pending line is promotable only if it was observed no earlier than the start of the turn being delivered
+ * (`pending_bound.ts`), i.e. only by a turn that was ALREADY RUNNING when the commit was observed. A line older than any
+ * plausible turn can never pass that bound: it is dead weight, not a recoverable edge. (A turn longer than the TTL loses
+ * its edge — the safe direction: a lost edge, never a wrong one.)
+ *
+ * ## The rule
+ *  - TTL 7 days, STRICTLY older. A file is EXPIRED when its mtime AND the `observedAt` of every line are past it. A legacy
+ *    0.4.0 line has no `observedAt`; the mtime ages it. ⛔ NEVER the line's `at` (the committer date — settable).
+ *  - WHOLE FILES ONLY, and only `*.pending.jsonl`. Survivors are never rewritten (`appendPending` is an unlocked
+ *    read-modify-write, so a rewrite could race it). `.spool.jsonl` (real, attributed commits), rewrites and state files are
+ *    never touched.
+ *  - At most 50 files per call. Called from the Stop and SessionEnd hooks only — not `post-commit` (it runs under git) and
+ *    not `status` (readers stay read-only).
+ *
+ * ## The race, narrowed: rename to a tombstone, re-read, put back anything fresh
+ * Check-then-delete leaves a window in which an append lands in a file we then delete. So the file is first RENAMED to
+ * `<name>.expired-<ts>` — an atomic step after which `appendPending` creates a NEW file at the old path — and the tombstone
+ * is re-read: if it is no longer expired (a line landed before the rename) it goes back, MERGED into any new file by sha
+ * rather than clobbering it; otherwise it is deleted. The lost-append window is the rename itself. A crashed prune leaves a
+ * tombstone; one older than an hour (judged by the timestamp in its NAME — a rename keeps the old mtime) is settled the
+ * same way on the next pass.
+ *
+ * ## Self-announcing, counts only
+ * A silent delete would turn a loss into a non-event. What was discarded is tallied in `pruned-pending.tally` (a name no
+ * other scan of the sessions directory matches) as `{files, lines, at}`: no sha, no session id. `status` shows one sentence
+ * for up to 7 days after the last discard; an older tally restarts instead of accumulating.
+ *
+ * Nothing here throws: a hook must exit 0.
+ */
+export declare const PENDING_TTL_MS: number;
+export declare const PRUNE_MAX_FILES = 50;
+/** A tombstone younger than this may belong to a prune that is still running in another process. */
+export declare const TOMBSTONE_GRACE_MS = 3600000;
+export interface PruneResult {
+    readonly files: number;
+    readonly lines: number;
+}
+/** Test seam: runs between the rename and the re-read — exactly where a concurrent append would land. */
+export interface PruneSeams {
+    readonly afterRename?: (tombstone: string, original: string) => void;
+}
+/** Pure. Expired = strictly older than the TTL on the file's mtime AND on every line's `observedAt`. */
+export declare function pendingExpired(raw: string, mtimeMs: number, nowMs: number): boolean;
+/** Reads the file; an unreadable one is NOT expired (never count or delete what cannot be examined). */
+export declare function pendingFileExpired(path: string, nowMs: number): boolean;
+export declare function pruneOrphanPending(home: string, repoKey: string, nowMs: number, seams?: PruneSeams): PruneResult;
+/** The counts to announce, or null when nothing was discarded in the last 7 days. */
+export declare function readPruneTally(home: string, repoKey: string, nowMs: number): {
+    files: number;
+    lines: number;
+} | null;

package/dist/pending_prune.js

@@ -0,0 +1,207 @@
+/**
+ * ORPHAN PENDING FILES — `TODOS[175]`.
+ *
+ * A `<sid>.pending.jsonl` has ONE consumer: its own session's running hook (D2 / cross-promotion forbid any other). Two
+ * producers write them — the cold rung (an env id never seen) and, since 0.4.1, a STALE-OWN id — so an id whose session
+ * never runs again leaves its file for ever, and `status` counted it beside the real spool: a permanent "N commits are
+ * waiting" with no remedy (`finalize` has no session to close).
+ *
+ * ## Why deleting one is safe
+ * Since 0.4.1 a pending line is promotable only if it was observed no earlier than the start of the turn being delivered
+ * (`pending_bound.ts`), i.e. only by a turn that was ALREADY RUNNING when the commit was observed. A line older than any
+ * plausible turn can never pass that bound: it is dead weight, not a recoverable edge. (A turn longer than the TTL loses
+ * its edge — the safe direction: a lost edge, never a wrong one.)
+ *
+ * ## The rule
+ *  - TTL 7 days, STRICTLY older. A file is EXPIRED when its mtime AND the `observedAt` of every line are past it. A legacy
+ *    0.4.0 line has no `observedAt`; the mtime ages it. ⛔ NEVER the line's `at` (the committer date — settable).
+ *  - WHOLE FILES ONLY, and only `*.pending.jsonl`. Survivors are never rewritten (`appendPending` is an unlocked
+ *    read-modify-write, so a rewrite could race it). `.spool.jsonl` (real, attributed commits), rewrites and state files are
+ *    never touched.
+ *  - At most 50 files per call. Called from the Stop and SessionEnd hooks only — not `post-commit` (it runs under git) and
+ *    not `status` (readers stay read-only).
+ *
+ * ## The race, narrowed: rename to a tombstone, re-read, put back anything fresh
+ * Check-then-delete leaves a window in which an append lands in a file we then delete. So the file is first RENAMED to
+ * `<name>.expired-<ts>` — an atomic step after which `appendPending` creates a NEW file at the old path — and the tombstone
+ * is re-read: if it is no longer expired (a line landed before the rename) it goes back, MERGED into any new file by sha
+ * rather than clobbering it; otherwise it is deleted. The lost-append window is the rename itself. A crashed prune leaves a
+ * tombstone; one older than an hour (judged by the timestamp in its NAME — a rename keeps the old mtime) is settled the
+ * same way on the next pass.
+ *
+ * ## Self-announcing, counts only
+ * A silent delete would turn a loss into a non-event. What was discarded is tallied in `pruned-pending.tally` (a name no
+ * other scan of the sessions directory matches) as `{files, lines, at}`: no sha, no session id. `status` shows one sentence
+ * for up to 7 days after the last discard; an older tally restarts instead of accumulating.
+ *
+ * Nothing here throws: a hook must exit 0.
+ */
+import { appendFileSync, readdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { repoSessionsDir } from "./paths.js";
+export const PENDING_TTL_MS = 7 * 24 * 3600_000;
+export const PRUNE_MAX_FILES = 50;
+/** A tombstone younger than this may belong to a prune that is still running in another process. */
+export const TOMBSTONE_GRACE_MS = 3600_000;
+const PENDING_SUFFIX = ".pending.jsonl";
+const TOMBSTONE = /^(.+\.pending\.jsonl)\.expired-(\d+)$/;
+const TALLY_NAME = "pruned-pending.tally";
+const nonBlank = (raw) => raw.split("\n").filter((l) => l.trim() !== "");
+/** Pure. Expired = strictly older than the TTL on the file's mtime AND on every line's `observedAt`. */
+export function pendingExpired(raw, mtimeMs, nowMs) {
+    if (!(nowMs - mtimeMs > PENDING_TTL_MS))
+        return false;
+    for (const l of nonBlank(raw)) {
+        let rec;
+        try {
+            rec = JSON.parse(l);
+        }
+        catch {
+            continue;
+        }
+        const at = rec !== null && typeof rec === "object" ? rec.observedAt : undefined;
+        if (typeof at === "number" && Number.isFinite(at) && !(nowMs - at > PENDING_TTL_MS))
+            return false;
+    }
+    return true;
+}
+/** Reads the file; an unreadable one is NOT expired (never count or delete what cannot be examined). */
+export function pendingFileExpired(path, nowMs) {
+    try {
+        return pendingExpired(readFileSync(path, "utf8"), statSync(path).mtimeMs, nowMs);
+    }
+    catch {
+        return false;
+    }
+}
+function shaOf(line) {
+    try {
+        const s = JSON.parse(line).sha;
+        return typeof s === "string" ? s : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Put a tombstone's lines back under its original name, merging into a file that appeared meanwhile; then remove it. */
+function restore(tomb, original, raw) {
+    let live = null;
+    try {
+        live = readFileSync(original, "utf8");
+    }
+    catch {
+        /* nothing there */
+    }
+    if (live === null) {
+        renameSync(tomb, original);
+        return;
+    }
+    const have = new Set(nonBlank(live).map(shaOf));
+    for (const l of nonBlank(raw))
+        if (!have.has(shaOf(l)))
+            appendFileSync(original, `${l}\n`);
+    rmSync(tomb, { force: true });
+}
+/** Examine one tombstone (just made, or left by a crash): delete it if still expired, else restore it. Returns the lines discarded. */
+function settle(tomb, original, nowMs) {
+    let raw;
+    let mtimeMs;
+    try {
+        raw = readFileSync(tomb, "utf8");
+        mtimeMs = statSync(tomb).mtimeMs;
+    }
+    catch {
+        return 0;
+    }
+    if (!pendingExpired(raw, mtimeMs, nowMs)) {
+        restore(tomb, original, raw);
+        return 0;
+    }
+    rmSync(tomb, { force: true });
+    return nonBlank(raw).length;
+}
+export function pruneOrphanPending(home, repoKey, nowMs, seams = {}) {
+    let files = 0;
+    let lines = 0;
+    try {
+        const dir = repoSessionsDir(home, repoKey);
+        if (dir === null)
+            return { files, lines };
+        const entries = readdirSync(dir).sort();
+        let budget = PRUNE_MAX_FILES;
+        for (const entry of entries) {
+            if (budget <= 0)
+                break;
+            try {
+                const t = TOMBSTONE.exec(entry);
+                if (t !== null) {
+                    if (nowMs - Number(t[2]) <= TOMBSTONE_GRACE_MS)
+                        continue; // maybe mid-flight in another process
+                    budget -= 1;
+                    const n = settle(join(dir, entry), join(dir, t[1]), nowMs);
+                    if (n > 0) {
+                        files += 1;
+                        lines += n;
+                    }
+                    continue;
+                }
+                if (!entry.endsWith(PENDING_SUFFIX))
+                    continue;
+                const path = join(dir, entry);
+                if (!pendingFileExpired(path, nowMs))
+                    continue;
+                budget -= 1;
+                const tomb = `${path}.expired-${nowMs}`;
+                renameSync(path, tomb);
+                seams.afterRename?.(tomb, path);
+                const n = settle(tomb, path, nowMs);
+                if (n > 0) {
+                    files += 1;
+                    lines += n;
+                }
+            }
+            catch {
+                /* one unreadable entry must not stop the pass */
+            }
+        }
+        if (files > 0 || lines > 0)
+            recordTally(dir, files, lines, nowMs);
+    }
+    catch {
+        /* never throw from a hook */
+    }
+    return { files, lines };
+}
+function readTally(dir) {
+    try {
+        const t = JSON.parse(readFileSync(join(dir, TALLY_NAME), "utf8"));
+        if (Number.isSafeInteger(t.files) && Number.isSafeInteger(t.lines) && typeof t.at === "number" && Number.isFinite(t.at))
+            return t;
+    }
+    catch {
+        /* absent or damaged: no tally */
+    }
+    return null;
+}
+function recordTally(dir, files, lines, nowMs) {
+    try {
+        const prev = readTally(dir);
+        const carry = prev !== null && nowMs - prev.at <= PENDING_TTL_MS ? prev : { files: 0, lines: 0, at: nowMs };
+        const next = { files: carry.files + files, lines: carry.lines + lines, at: nowMs };
+        writeFileSync(join(dir, TALLY_NAME), `${JSON.stringify(next)}\n`, { mode: 0o600 });
+    }
+    catch {
+        /* the discard already happened; failing to announce it must not undo or throw */
+    }
+}
+/** The counts to announce, or null when nothing was discarded in the last 7 days. */
+export function readPruneTally(home, repoKey, nowMs) {
+    const dir = repoSessionsDir(home, repoKey);
+    if (dir === null)
+        return null;
+    const t = readTally(dir);
+    if (t === null || nowMs - t.at > PENDING_TTL_MS || (t.files === 0 && t.lines === 0))
+        return null;
+    return { files: t.files, lines: t.lines };
+}
+//# sourceMappingURL=pending_prune.js.map

package/dist/pending_prune.js.map

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

package/dist/spool.d.ts

@@ -40,6 +40,7 @@
  * the sha; the observation is not. `files` is carried for wave 2 and never put
  * in a header.
  */
+import { type PendingMode, type TurnStart } from "./pending_bound.js";
 import { type SessionKey } from "./paths.js";
 /**
  * ⛔ **WHICH RUNG OF THE LADDER ANSWERED — the difference between an observation,
@@ -139,6 +140,12 @@ export interface SpoolEntry {
      * variable belonged to the committing process, and the mtimes have moved on.
      */
     readonly attribution: AttributionRung;
+    /**
+     * `TODOS[176]` — the WALL CLOCK (ms since the epoch) of the `post-commit` process when it spooled this line. Written
+     * on PENDING lines only; `pending_bound.ts` compares it with the start of the turn being delivered (the first unsent prompt-like record). Additive: a
+     * 0.4.0 line has none and is promoted as before. Never the committer date (settable).
+     */
+    readonly observedAt?: number;
 }
 /**
  * How many SHAs one hook may put on the wire.
@@ -311,6 +318,13 @@ export interface ActiveSession {
  * forgot the env path, and this seam has no other check.
  */
 export declare function activeSessionFor(home: string, repoKey: string, envSessionId: string | null, nowMs?: number, windowMs?: number): ActiveSession | null;
+/**
+ * `TODOS[176]` — which promotion path a pending line is on, decided by the session's OWN state at the moment its hook runs:
+ * `stale-own` = its state file EXISTS and is not live (a RESUMED session: the cold rung put the line here because rung 1 failed),
+ * `first-turn` = no state file yet, or one that is live (the original cold case — the first Stop promotes BEFORE it saves state).
+ * Reads only; writes nothing (D2).
+ */
+export declare function pendingModeFor(home: string, key: SessionKey, nowMs?: number, windowMs?: number): PendingMode;
 /**
  * ⛔ **THE TWO RUNGS THAT MAY GO ON `x-commit-attributions` (`D190`).**
  *
@@ -506,4 +520,11 @@ export declare function promotePending(home: string, key: SessionKey,
  * a lingering exported `CLAUDE_CODE_SESSION_ID` accumulates pending lines that
  * are never promoted and age out under `MAX_PENDING_SHAS`.
  */
-corroboration: "this-session-is-running"): number;
+corroboration: "this-session-is-running", 
+/**
+ * ⛔ `TODOS[176]` — THE PROMOTION BOUND AND ITS PATH, BOTH REQUIRED SO A CALLER CANNOT FORGET THEM. `bound` is the start
+ * of the turn this hook is delivering (`turnStart`: the first unsent PROMPT-LIKE record's timestamp); `mode` says whether the
+ * session's state file already existed (`stale-own`) or not (`first-turn`). A line observed before the turn start is DROPPED;
+ * when no turn start is found a stale-own line is dropped and a first-turn line kept. See `pending_bound.ts`.
+ */
+bound: TurnStart, mode: PendingMode): number;

package/dist/spool.js

@@ -42,6 +42,7 @@
  */
 import { appendFileSync, chmodSync, existsSync, mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
+import { keepsPendingLine } from "./pending_bound.js";
 import { repoSessionsDir, sessionStatePath } from "./paths.js";
 /**
  * How many SHAs one hook may put on the wire.
@@ -306,36 +307,33 @@ export function activeSessionFor(home, repoKey, envSessionId, nowMs = Date.now()
     // forever. The refusal's premise — *we were TOLD who committed, and it is none of these* —
     // is false for a session that has merely not written its state file YET.
     //
-    // ⛔ **ONLY FOR A SESSION THAT HAS NO STATE FILE AT ALL, NEVER A STALE ONE.**
-    // `activeSessionFor(…, SESSION, +9h)` must stay `null`, and the reason is
-    // pinned by a cell: *"an id naming a session that went quiet nine hours ago
-    // is still nothing — otherwise a shell that exported the value once would
-    // keep a session alive for as long as the terminal lived."* That hazard is
-    // real and this rung would have re-opened it, because state files are never
-    // deleted: a lingering variable would file every future commit under one
-    // ancient session, and promotion would then mint permanent edges for it.
+    // ⭐ **`TODOS[176]` — AND IT IS THE SAME FOR A SESSION WHOSE STATE FILE EXISTS BUT HAS GONE STALE.**
+    // A RESUMED session (idle past the 30-minute window) is exactly as "not yet corroborated" as a brand-new one: the
+    // resumed turn's first commit is made BEFORE any hook of that turn has fired, and `liveAt` is refreshed only by a
+    // hook. Measured on the registry 0.4.0 binary: alone, that commit left no spool line anywhere (null); with another
+    // session live it was filed under the OTHER session as `env_session_unmatched` and then discarded. Either way the
+    // edge was lost for good. So rung 1 failing (X is not live) with X named by the environment now ALWAYS takes the cold
+    // rung, keyed to X's own id.
     //
-    // ⚠ The distinction is exactly the case this rung is for: a session on its
-    // FIRST turn has written nothing yet, while a dead one left a file behind.
-    // ⚠ Absence of the file is the line between too EARLY and too LATE. (Worded
-    // to avoid `from` followed by a quoted string: `provenance.test.ts` walls
-    // RAW TEXT and reads that shape as an escaping import specifier. Third time
-    // this guard has fired on ordinary prose in this package; the house response
-    // is to move the wording and leave the guard alone.)
+    // ⛔ WHAT MAKES THAT SAFE (the old comment here forbade it, for a good reason): the hazard was a shell that exported a
+    // session id once and kept committing, with the commits then adopted by a long-dead session and PROMOTED to
+    // edge-minting rows. Three things close it, and none of them is this function:
+    //   1. this rung writes ONE `.pending.jsonl` line (post_commit.ts picks the sidecar for this rung): no state file, no
+    //      `liveAt`, no spool line. A non-hook writer cannot make X live (D2; asserted as bytes in
+    //      `test/stale-own-pending.test.ts`).
+    //   2. only X's OWN running hook promotes X's bucket (`promotePending`'s call site is keyed by the executing hook's
+    //      session, never by the environment): a dead session never runs a hook, and another session's hook cannot touch it.
+    //   3. the promotion bound (`pending_bound.ts`): a line observed before the START OF THE TURN X is delivering (its first unsent prompt-like record) is
+    //      DROPPED, so a lingering-id commit from days ago is not adopted when X is finally resumed.
+    // Residual, stated: a stale exported id committing DURING the resumed turn looks exactly like X's own commit.
+    // (Worded to avoid `from` followed by a quoted string: `provenance.test.ts` walls RAW TEXT and reads that shape as an
+    // escaping import specifier.)
     //
-    // ⚠ WHAT THIS COSTS, stated rather than discovered: an environment naming a session this
-    // clone has NEVER captured now opens a `.pending.jsonl` bucket even when others are live
-    // (Codex under an outer Claude session is the case `agents/registry.ts:11-13` describes).
-    // That is the same exposure the all-quiet case already accepted. The line is `pending`, not
-    // sendable: it promotes only if THAT session's own hook later corroborates it, and otherwise
-    // ages out under `MAX_PENDING_SHAS`.
-    const envHasNoStateFile = (() => {
-        if (envSessionId === null)
-            return false;
-        const state = sessionStatePath(home, { repoKey, sessionId: envSessionId });
-        return state !== null && !existsSync(state);
-    })();
-    if (envSessionId !== null && envHasNoStateFile) {
+    // ⚠ WHAT THIS COSTS, stated rather than discovered: an environment naming a session this clone has never captured, or
+    // captured long ago, opens a `.pending.jsonl` bucket even when others are live (Codex under an outer Claude session is
+    // the case `agents/registry.ts:11-13` describes). The line is `pending`, not sendable: it promotes only if THAT
+    // session's own hook later corroborates it, and otherwise ages out under `MAX_PENDING_SHAS`.
+    if (envSessionId !== null && sessionStatePath(home, { repoKey, sessionId: envSessionId }) !== null) {
         return { sessionId: envSessionId, attribution: "env_session_uncorroborated" };
     }
     if (live.length === 0)
@@ -373,6 +371,19 @@ function readLiveAt(path) {
         return null;
     }
 }
+/**
+ * `TODOS[176]` — which promotion path a pending line is on, decided by the session's OWN state at the moment its hook runs:
+ * `stale-own` = its state file EXISTS and is not live (a RESUMED session: the cold rung put the line here because rung 1 failed),
+ * `first-turn` = no state file yet, or one that is live (the original cold case — the first Stop promotes BEFORE it saves state).
+ * Reads only; writes nothing (D2).
+ */
+export function pendingModeFor(home, key, nowMs = Date.now(), windowMs = SESSION_LIVE_WINDOW_MS) {
+    const state = sessionStatePath(home, key);
+    if (state === null || !existsSync(state))
+        return "first-turn";
+    const at = readLiveAt(state);
+    return at !== null && nowMs - at <= windowMs ? "first-turn" : "stale-own";
+}
 /** Every session whose hook last ran inside the window, most recent first. */
 function liveSessions(home, repoKey, nowMs, windowMs) {
     const dir = repoSessionsDir(home, repoKey);
@@ -764,7 +775,8 @@ function parseEntry(line) {
     const at = typeof o.at === "string" ? o.at : "";
     const branch = typeof o.branch === "string" && o.branch !== "" ? o.branch : null;
     const files = Array.isArray(o.files) ? o.files.filter((f) => typeof f === "string") : [];
-    return { sha, branch, at, files, attribution: parseRung(o.attribution) };
+    const observedAt = typeof o.observedAt === "number" && Number.isFinite(o.observedAt) && o.observedAt > 0 ? o.observedAt : undefined;
+    return { sha, branch, at, files, attribution: parseRung(o.attribution), ...(observedAt === undefined ? {} : { observedAt }) };
 }
 /**
  * ⛔ **AN UNLABELLED LINE IS `recency_heuristic`, AND THAT IS NOT A DEFAULT — IT
@@ -938,14 +950,26 @@ export function promotePending(home, key,
  * a lingering exported `CLAUDE_CODE_SESSION_ID` accumulates pending lines that
  * are never promoted and age out under `MAX_PENDING_SHAS`.
  */
-corroboration) {
+corroboration, 
+/**
+ * ⛔ `TODOS[176]` — THE PROMOTION BOUND AND ITS PATH, BOTH REQUIRED SO A CALLER CANNOT FORGET THEM. `bound` is the start
+ * of the turn this hook is delivering (`turnStart`: the first unsent PROMPT-LIKE record's timestamp); `mode` says whether the
+ * session's state file already existed (`stale-own`) or not (`first-turn`). A line observed before the turn start is DROPPED;
+ * when no turn start is found a stale-own line is dropped and a first-turn line kept. See `pending_bound.ts`.
+ */
+bound, mode) {
     void corroboration;
     const pending = readPending(home, key);
     if (pending.length === 0)
         return 0;
     let promoted = 0;
     for (const entry of pending) {
-        if (appendSpool(home, key, { ...entry, attribution: "env_session_id" }))
+        if (!keepsPendingLine(entry, bound, mode))
+            continue;
+        // The pending-only observation clock stays behind: a promoted line is an ordinary spool line.
+        const { observedAt: _observedAt, ...rest } = entry;
+        void _observedAt;
+        if (appendSpool(home, key, { ...rest, attribution: "env_session_id" }))
             promoted += 1;
     }
     clearPending(home, key);