dorfl 0.11.1 → 0.11.2

package/dist/pi-harness.js

@@ -3,6 +3,7 @@ import { existsSync, readFileSync } from 'node:fs';
 import { NullHarness, pidAlive, registerHarness, } from './harness.js';
 import { generateSessionPath } from './session-path.js';
 import { lastAssistantText } from './watch-session.js';
+import { reapProcessGroup } from './reap-agent-tree.js';
 /**
  * The **pi** harness adapter (ADR §5) — the first real agent harness
  * `dorfl` drives. It fulfils the harness seam introduced by
@@ -186,8 +187,47 @@ export class PiHarness {
                 cwd: input.dir,
                 env: input.env ?? process.env,
                 stdio: ['pipe', 'pipe', 'pipe'],
+                // PROCESS-GROUP LEADER (observation
+                // `checkpoint-releases-lock-while-predecessor-agent-still-writes`): pi's
+                // pgid becomes its own pid, so the deadline stop can signal the WHOLE
+                // agent tree with `kill(-pgid)` and VERIFY it is gone. Without this,
+                // `child.kill()` reached exactly one pid: subagents / MCP servers / tool
+                // subshells survived, were re-parented to init (so no ppid walk could even
+                // find them), and kept writing into the worktree while a SUCCESSOR agent
+                // was already editing it. A pgid is inherited by every descendant and is
+                // unaffected by re-parenting, which is why it is the only usable handle.
+                // We deliberately do NOT `unref()` here: the parent keeps supervising the
+                // child (and forwards its own termination to the group, below).
+                detached: true,
             });
             record.pid = child.pid; // the liveness anchor, recorded like spawnSync.
+            // The group id equals the leader's pid because we spawned `detached`.
+            const pgid = child.pid;
+            // `detached: true` takes pi OUT of our terminal's foreground process group,
+            // so a Ctrl-C / `kill` aimed at the runner would no longer reach it — which
+            // would WIDEN the very "aborting `do` does not kill the spawned agent tree"
+            // gap this change is closing. Forward our own termination to the group for
+            // as long as the child is live, so detaching strictly improves reachability
+            // instead of trading one orphan class for another.
+            const forwardSignal = (signal) => () => {
+                if (pgid === undefined) {
+                    return;
+                }
+                try {
+                    process.kill(-pgid, signal);
+                }
+                catch {
+                    // Already gone; nothing to forward to.
+                }
+            };
+            const onSigint = forwardSignal('SIGINT');
+            const onSigterm = forwardSignal('SIGTERM');
+            process.on('SIGINT', onSigint);
+            process.on('SIGTERM', onSigterm);
+            const stopForwarding = () => {
+                process.off('SIGINT', onSigint);
+                process.off('SIGTERM', onSigterm);
+            };
             let stderr = '';
             child.stderr?.on('data', (chunk) => {
                 stderr += chunk.toString('utf8');
@@ -225,19 +265,32 @@ export class PiHarness {
                         return;
                     }
                     timedOut = true;
+                    // Signal the whole GROUP, not just pi: the descendants are exactly the
+                    // processes that outlive it and keep writing to the worktree.
                     try {
-                        child.kill('SIGTERM');
+                        if (pgid !== undefined) {
+                            process.kill(-pgid, 'SIGTERM');
+                        }
+                        else {
+                            child.kill('SIGTERM');
+                        }
                     }
                     catch {
-                        // Best-effort: a already-exited child throws ESRCH; the `exit`
-                        // handler will still settle the promise.
+                        // Best-effort: an already-exited group throws ESRCH; the `exit`
+                        // handler will still settle the promise, and the post-exit reap below
+                        // is what actually VERIFIES the tree is gone.
                     }
                     hardTimer = setTimeout(() => {
                         if (settled) {
                             return;
                         }
                         try {
-                            child.kill('SIGKILL');
+                            if (pgid !== undefined) {
+                                process.kill(-pgid, 'SIGKILL');
+                            }
+                            else {
+                                child.kill('SIGKILL');
+                            }
                         }
                         catch {
                             // Best-effort: see above.
@@ -253,6 +306,7 @@ export class PiHarness {
                 }
                 settled = true;
                 clearDeadlineTimers();
+                stopForwarding();
                 reject(new Error(`failed to spawn pi (${this.piBin}): ${err.message}`));
             });
             // Resolve on `exit` (pi itself terminated), NOT `close`: `close` waits for
@@ -265,6 +319,7 @@ export class PiHarness {
                 }
                 settled = true;
                 clearDeadlineTimers();
+                stopForwarding();
                 // Release our end of the stdio pipes so a leaked grandchild's inherited
                 // FDs stop keeping our streams referenced; `unref` the child handle too.
                 child.stdout?.destroy();
@@ -272,15 +327,56 @@ export class PiHarness {
                 child.stdin?.destroy();
                 child.unref?.();
                 const status = code ?? -1;
-                resolve({
-                    ok: status === 0 && !timedOut,
-                    record,
-                    detail: status === 0 && !timedOut ? undefined : stderr.trim() || undefined,
-                    timedOut: timedOut ? true : undefined,
-                    // Read the agent's ANSWER from the `.jsonl` at `exit` — the same
-                    // last-assistant-text read `launch` does at return (task
-                    // `harness-agent-output`); the process has exited so the log is final.
-                    output: readLastAssistantText(sessionFile),
+                const settleWith = (reap) => {
+                    resolve({
+                        ok: status === 0 && !timedOut,
+                        record,
+                        detail: status === 0 && !timedOut
+                            ? undefined
+                            : stderr.trim() || undefined,
+                        timedOut: timedOut ? true : undefined,
+                        ...(reap ? { reap } : {}),
+                        // Read the agent's ANSWER from the `.jsonl` at `exit` — the same
+                        // last-assistant-text read `launch` does at return (task
+                        // `harness-agent-output`); the process has exited so the log is final.
+                        output: readLastAssistantText(sessionFile),
+                    });
+                };
+                if (!timedOut || pgid === undefined) {
+                    // Normal exit: we signalled nothing, so there is nothing to prove and
+                    // nothing to kill. Byte-for-byte the pre-existing behaviour — in
+                    // particular we do NOT reap a group the agent may have deliberately left
+                    // running behind a successful run.
+                    settleWith();
+                    return;
+                }
+                // DEADLINE STOP: pi's own exit says NOTHING about its descendants — that
+                // assumption is the defect. Before this promise resolves (which is the
+                // runner's cue to save WIP, release the lock and dispatch a SUCCESSOR into
+                // this same worktree), reap the group and VERIFY it is gone. Bounded by
+                // construction, so this cannot reintroduce the resolve-on-`exit` hang the
+                // doc-comment above guards against: a tree that will not die resolves with
+                // `reaped: false` and the caller refuses to release the lock.
+                void reapProcessGroup({ pgid })
+                    .then((result) => {
+                    settleWith({
+                        reaped: result.reaped,
+                        pgid,
+                        escalatedToSigkill: result.escalatedToSigkill,
+                        detail: result.detail,
+                    });
+                })
+                    .catch((err) => {
+                    // A throw here means we could not even RUN the verification, which is
+                    // indistinguishable from "might still be alive" — report it as an
+                    // unproven reap rather than silently claiming success.
+                    settleWith({
+                        reaped: false,
+                        pgid,
+                        detail: `could not verify that the agent process group ${pgid} exited ` +
+                            `(${err instanceof Error ? err.message : String(err)}); treating ` +
+                            'the predecessor as possibly still writing to the worktree.',
+                    });
                 });
             });
             // Feed the same prepared prompt on stdin, then close it (pi reads to EOF).

package/dist/pi-harness.js.map

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

package/dist/reap-agent-tree.d.ts

@@ -0,0 +1,108 @@
+/**
+ * **Reap a stopped agent's whole PROCESS TREE, and VERIFY it is gone** (spec
+ * `graceful-pre-timeout-wip-checkpoint`, observation
+ * `checkpoint-releases-lock-while-predecessor-agent-still-writes`).
+ *
+ * ## The gap this closes
+ *
+ * The deadline checkpoint used to `child.kill('SIGTERM')` the agent process and
+ * treat the signal as if it were the outcome: the moment pi's own `exit` fired,
+ * the runner saved the WIP, RELEASED the item lock, and let the next tick
+ * dispatch a CONTINUATION agent into the SAME worktree. But `child.kill` signals
+ * exactly ONE pid, and a modern agent is a TREE (subagent processes, MCP servers,
+ * model proxies, tool subshells). Those descendants survive the parent's SIGTERM,
+ * and once pi exits they are re-parented to init — so they can no longer even be
+ * FOUND by walking `ppid`, while they keep writing into the worktree.
+ *
+ * Observed on a real run: the checkpoint saved WIP at 02:13, a continuation agent
+ * onboarded into the same worktree at ~02:15, and the predecessor's session log
+ * kept being written until 02:19:29 — four minutes INTO the successor's run,
+ * whose opening `git status` had already read the tree as clean. Nothing was lost
+ * only because the two happened to touch different files. The shape is the
+ * defect: one lock, one working tree, two live writers. A write landing after the
+ * successor's `git status` is invisible to it; a write landing during its edits
+ * can be clobbered either way; and the successor can commit the predecessor's
+ * half-finished edits as its own, under a message describing something else.
+ *
+ * ## Why the PROCESS GROUP is the handle
+ *
+ * A pid-tree walk cannot work here: the descendants we must reap are precisely
+ * the ones that OUTLIVE the parent, and an orphan's `ppid` is gone. A process
+ * GROUP id, by contrast, is inherited by every descendant and is NOT changed by
+ * re-parenting. So if the agent is spawned as a group LEADER (`detached: true`,
+ * making its pgid equal its pid), `kill(-pgid, …)` reaches the entire tree,
+ * orphans included — which is why {@link reapProcessGroup} takes a pgid and why
+ * `pi-harness.ts` spawns the deadline-capable async launch detached.
+ *
+ * ## Signal, then VERIFY — never assume
+ *
+ * The point of the whole module is that sending a signal is not evidence that
+ * anything died. So: SIGTERM the group, POLL until it is actually gone, escalate
+ * to SIGKILL after a grace, keep polling, and if it STILL will not die, say so
+ * LOUDLY and let the caller refuse to release the lock. A checkpoint that cannot
+ * prove the predecessor is dead must not hand the worktree to a successor.
+ */
+/**
+ * How long to wait after SIGTERM before escalating to SIGKILL. Matches
+ * `pi-harness.ts`'s `DEADLINE_SIGKILL_GRACE_MS` intent: enough for an agent to
+ * flush its session log and exit cleanly, short enough not to stall a CI leg.
+ */
+export declare const REAP_SIGTERM_GRACE_MS = 10000;
+/** How long to keep waiting after SIGKILL before declaring the reap FAILED. */
+export declare const REAP_SIGKILL_TIMEOUT_MS = 5000;
+/** The outcome of a {@link reapProcessGroup} attempt. */
+export interface ReapResult {
+    /**
+     * True iff the group is VERIFIED gone (observed non-existent, not merely
+     * signalled). Only a `true` here licenses releasing the item lock and
+     * dispatching a successor into the same worktree.
+     */
+    reaped: boolean;
+    /** True iff SIGKILL was needed (the tree ignored SIGTERM) — worth reporting. */
+    escalatedToSigkill: boolean;
+    /** Total wall-clock ms spent waiting for the tree to die. */
+    waitedMs: number;
+    /** A human-readable account, always populated (the LOUD failure text). */
+    detail: string;
+}
+/**
+ * Is any process still alive in process group `pgid`?
+ *
+ * `process.kill(-pgid, 0)` is the liveness probe: signal 0 performs the
+ * permission/existence check WITHOUT delivering a signal (the same technique
+ * `harness.ts`'s {@link pidAlive} uses for a single pid, widened to the group).
+ *
+ *  - It THROWS `ESRCH` when no process in the group exists ⇒ the group is gone.
+ *  - It THROWS `EPERM` when the group exists but we may not signal it. That is
+ *    still "alive", and reporting it as dead would be the very assumption this
+ *    module exists to remove — so `EPERM` reads as ALIVE.
+ *  - It succeeds ⇒ alive.
+ */
+export declare function processGroupAlive(pgid: number): boolean;
+/**
+ * SIGTERM process group `pgid`, wait for it to ACTUALLY exit, escalate to
+ * SIGKILL after {@link REAP_SIGTERM_GRACE_MS}, and report whether the tree is
+ * VERIFIED gone.
+ *
+ * Bounded by construction: at worst `sigtermGraceMs + sigkillTimeoutMs` before it
+ * returns `reaped: false` with a loud `detail`. It never waits indefinitely, so
+ * it cannot reintroduce the runner-hang the async launch's resolve-on-`exit`
+ * discipline exists to avoid.
+ */
+export declare function reapProcessGroup(params: {
+    /** The process GROUP id to reap (the group leader's pid). */
+    pgid: number;
+    sigtermGraceMs?: number;
+    sigkillTimeoutMs?: number;
+    /** Injectable sleep so tests need not burn real seconds. */
+    wait?: (ms: number) => Promise<void>;
+    /**
+     * Injectable liveness probe (default {@link processGroupAlive}). Exists so the
+     * REFUSAL path — a tree that survives SIGTERM *and* SIGKILL — can be tested
+     * deterministically. There is no portable way to create a genuinely unkillable
+     * process, and the alternative (a group we truly cannot signal) would risk the
+     * test process itself, so the probe is the seam.
+     */
+    alive?: (pgid: number) => boolean;
+}): Promise<ReapResult>;
+//# sourceMappingURL=reap-agent-tree.d.ts.map

package/dist/reap-agent-tree.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reap-agent-tree.d.ts","sourceRoot":"","sources":["../src/reap-agent-tree.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AAKH;;;;GAIG;AACH,eAAO,MAAM,qBAAqB,QAAS,CAAC;AAE5C,+EAA+E;AAC/E,eAAO,MAAM,uBAAuB,OAAQ,CAAC;AAE7C,yDAAyD;AACzD,MAAM,WAAW,UAAU;IAC1B;;;;OAIG;IACH,MAAM,EAAE,OAAO,CAAC;IAChB,gFAAgF;IAChF,kBAAkB,EAAE,OAAO,CAAC;IAC5B,6DAA6D;IAC7D,QAAQ,EAAE,MAAM,CAAC;IACjB,0EAA0E;IAC1E,MAAM,EAAE,MAAM,CAAC;CACf;AAUD;;;;;;;;;;;;GAYG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAgBvD;AAWD;;;;;;;;;GASG;AACH,wBAAsB,gBAAgB,CAAC,MAAM,EAAE;IAC9C,6DAA6D;IAC7D,IAAI,EAAE,MAAM,CAAC;IACb,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,4DAA4D;IAC5D,IAAI,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACrC;;;;;;OAMG;IACH,KAAK,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC;CAClC,GAAG,OAAO,CAAC,UAAU,CAAC,CAyEtB"}

package/dist/reap-agent-tree.js

@@ -0,0 +1,173 @@
+/**
+ * **Reap a stopped agent's whole PROCESS TREE, and VERIFY it is gone** (spec
+ * `graceful-pre-timeout-wip-checkpoint`, observation
+ * `checkpoint-releases-lock-while-predecessor-agent-still-writes`).
+ *
+ * ## The gap this closes
+ *
+ * The deadline checkpoint used to `child.kill('SIGTERM')` the agent process and
+ * treat the signal as if it were the outcome: the moment pi's own `exit` fired,
+ * the runner saved the WIP, RELEASED the item lock, and let the next tick
+ * dispatch a CONTINUATION agent into the SAME worktree. But `child.kill` signals
+ * exactly ONE pid, and a modern agent is a TREE (subagent processes, MCP servers,
+ * model proxies, tool subshells). Those descendants survive the parent's SIGTERM,
+ * and once pi exits they are re-parented to init — so they can no longer even be
+ * FOUND by walking `ppid`, while they keep writing into the worktree.
+ *
+ * Observed on a real run: the checkpoint saved WIP at 02:13, a continuation agent
+ * onboarded into the same worktree at ~02:15, and the predecessor's session log
+ * kept being written until 02:19:29 — four minutes INTO the successor's run,
+ * whose opening `git status` had already read the tree as clean. Nothing was lost
+ * only because the two happened to touch different files. The shape is the
+ * defect: one lock, one working tree, two live writers. A write landing after the
+ * successor's `git status` is invisible to it; a write landing during its edits
+ * can be clobbered either way; and the successor can commit the predecessor's
+ * half-finished edits as its own, under a message describing something else.
+ *
+ * ## Why the PROCESS GROUP is the handle
+ *
+ * A pid-tree walk cannot work here: the descendants we must reap are precisely
+ * the ones that OUTLIVE the parent, and an orphan's `ppid` is gone. A process
+ * GROUP id, by contrast, is inherited by every descendant and is NOT changed by
+ * re-parenting. So if the agent is spawned as a group LEADER (`detached: true`,
+ * making its pgid equal its pid), `kill(-pgid, …)` reaches the entire tree,
+ * orphans included — which is why {@link reapProcessGroup} takes a pgid and why
+ * `pi-harness.ts` spawns the deadline-capable async launch detached.
+ *
+ * ## Signal, then VERIFY — never assume
+ *
+ * The point of the whole module is that sending a signal is not evidence that
+ * anything died. So: SIGTERM the group, POLL until it is actually gone, escalate
+ * to SIGKILL after a grace, keep polling, and if it STILL will not die, say so
+ * LOUDLY and let the caller refuse to release the lock. A checkpoint that cannot
+ * prove the predecessor is dead must not hand the worktree to a successor.
+ */
+/** Poll interval while waiting for a signalled group to actually exit. */
+const REAP_POLL_MS = 50;
+/**
+ * How long to wait after SIGTERM before escalating to SIGKILL. Matches
+ * `pi-harness.ts`'s `DEADLINE_SIGKILL_GRACE_MS` intent: enough for an agent to
+ * flush its session log and exit cleanly, short enough not to stall a CI leg.
+ */
+export const REAP_SIGTERM_GRACE_MS = 10_000;
+/** How long to keep waiting after SIGKILL before declaring the reap FAILED. */
+export const REAP_SIGKILL_TIMEOUT_MS = 5_000;
+/** Sleep helper (injectable clock is not needed: callers inject `wait` in tests). */
+function sleep(ms) {
+    return new Promise((resolve) => {
+        const timer = setTimeout(resolve, ms);
+        timer.unref?.();
+    });
+}
+/**
+ * Is any process still alive in process group `pgid`?
+ *
+ * `process.kill(-pgid, 0)` is the liveness probe: signal 0 performs the
+ * permission/existence check WITHOUT delivering a signal (the same technique
+ * `harness.ts`'s {@link pidAlive} uses for a single pid, widened to the group).
+ *
+ *  - It THROWS `ESRCH` when no process in the group exists ⇒ the group is gone.
+ *  - It THROWS `EPERM` when the group exists but we may not signal it. That is
+ *    still "alive", and reporting it as dead would be the very assumption this
+ *    module exists to remove — so `EPERM` reads as ALIVE.
+ *  - It succeeds ⇒ alive.
+ */
+export function processGroupAlive(pgid) {
+    if (!Number.isInteger(pgid) || pgid <= 1) {
+        // pgid 0/1 (or a bogus value) would mean "our own group" / init — signalling
+        // those would be catastrophic, so never claim they are ours to reap.
+        return false;
+    }
+    try {
+        process.kill(-pgid, 0);
+        return true;
+    }
+    catch (err) {
+        const code = err.code;
+        if (code === 'EPERM') {
+            return true; // exists, just not signallable by us.
+        }
+        return false; // ESRCH (or anything else): treat as gone.
+    }
+}
+/** Signal a whole process group, tolerating an already-dead group. */
+function signalGroup(pgid, signal) {
+    try {
+        process.kill(-pgid, signal);
+    }
+    catch {
+        // ESRCH: already gone — the wait loop below observes that and succeeds.
+    }
+}
+/**
+ * SIGTERM process group `pgid`, wait for it to ACTUALLY exit, escalate to
+ * SIGKILL after {@link REAP_SIGTERM_GRACE_MS}, and report whether the tree is
+ * VERIFIED gone.
+ *
+ * Bounded by construction: at worst `sigtermGraceMs + sigkillTimeoutMs` before it
+ * returns `reaped: false` with a loud `detail`. It never waits indefinitely, so
+ * it cannot reintroduce the runner-hang the async launch's resolve-on-`exit`
+ * discipline exists to avoid.
+ */
+export async function reapProcessGroup(params) {
+    const { pgid, sigtermGraceMs = REAP_SIGTERM_GRACE_MS, sigkillTimeoutMs = REAP_SIGKILL_TIMEOUT_MS, wait = sleep, alive = processGroupAlive, } = params;
+    const started = Date.now();
+    if (!alive(pgid)) {
+        return {
+            reaped: true,
+            escalatedToSigkill: false,
+            waitedMs: 0,
+            detail: `agent process group ${pgid} was already gone (nothing to reap).`,
+        };
+    }
+    // 1. SOFT: ask the whole tree to stop, then WAIT for it to be observably gone.
+    signalGroup(pgid, 'SIGTERM');
+    while (Date.now() - started < sigtermGraceMs) {
+        if (!alive(pgid)) {
+            const waitedMs = Date.now() - started;
+            return {
+                reaped: true,
+                escalatedToSigkill: false,
+                waitedMs,
+                detail: `agent process group ${pgid} exited on SIGTERM after ${waitedMs}ms ` +
+                    '(verified gone).',
+            };
+        }
+        await wait(REAP_POLL_MS);
+    }
+    // 2. HARD: the tree ignored SIGTERM through the grace. SIGKILL it and keep
+    //    verifying — a wedged agent still holding the worktree must not survive
+    //    into the successor's run.
+    signalGroup(pgid, 'SIGKILL');
+    const killDeadline = Date.now() + sigkillTimeoutMs;
+    while (Date.now() < killDeadline) {
+        if (!alive(pgid)) {
+            const waitedMs = Date.now() - started;
+            return {
+                reaped: true,
+                escalatedToSigkill: true,
+                waitedMs,
+                detail: `agent process group ${pgid} ignored SIGTERM and was SIGKILLed; ` +
+                    `exited after ${waitedMs}ms (verified gone).`,
+            };
+        }
+        await wait(REAP_POLL_MS);
+    }
+    // 3. LOUD FAILURE: we cannot prove the predecessor is dead. Say exactly that,
+    //    and exactly what the caller must not do as a result.
+    const waitedMs = Date.now() - started;
+    return {
+        reaped: false,
+        escalatedToSigkill: true,
+        waitedMs,
+        detail: `REFUSING TO PROCEED: agent process group ${pgid} is STILL ALIVE ${waitedMs}ms ` +
+            'after SIGTERM and SIGKILL (an unkillable/uninterruptible descendant — e.g. a ' +
+            'process wedged in a kernel call, or one we lack permission to signal). It may ' +
+            'still be WRITING to the worktree, so the item lock must NOT be released and no ' +
+            'successor agent may onboard here: two live writers in one working tree can ' +
+            'silently clobber each other and let a successor commit the predecessor’s ' +
+            `half-finished edits. Inspect and kill it by hand (\`ps -g ${pgid}\`, ` +
+            `\`kill -9 -${pgid}\`) before re-running this item.`,
+    };
+}
+//# sourceMappingURL=reap-agent-tree.js.map

package/dist/reap-agent-tree.js.map

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

package/dist/worktree-writer-lock.d.ts

@@ -0,0 +1,99 @@
+/**
+ * **The per-WORKING-TREE writer sentinel** (observation
+ * `checkpoint-releases-lock-while-predecessor-agent-still-writes`).
+ *
+ * The per-item lock (`item-lock.ts`) guards the ITEM: it answers "who owns this
+ * task?" and it is what claim / requeue / bounce move around. Nothing guarded the
+ * WORKING TREE. Those are different resources, and the deadline checkpoint is
+ * exactly where they come apart: the checkpoint releases the item lock so the
+ * next tick can continue the task, but the tree the previous agent was editing is
+ * reused by the successor. If the predecessor is still alive, two agents write to
+ * one tree.
+ *
+ * The primary fix is to reap the predecessor and VERIFY it is gone before the
+ * lock moves (`reap-agent-tree.ts`). This sentinel is the INDEPENDENT backstop:
+ * even if a live writer survives by some route the reap did not cover (a
+ * deliberately `setsid`-ed grandchild, a stale run from a crashed runner, an
+ * operator manually re-driving an item), a second agent physically cannot onboard
+ * into a tree that already has a LIVE holder. It is deliberately keyed on the
+ * TREE, not on the item: two different items sharing one worktree is just as
+ * unsafe as two attempts at the same item.
+ *
+ * ## Where the sentinel lives, and why not in the tree
+ *
+ * It is written to the worktree's PRIVATE git directory (`git rev-parse
+ * --absolute-git-dir`, which for a linked worktree is
+ * `.../.git/worktrees/<name>/`), NOT to a file inside the working tree. That
+ * placement is load-bearing:
+ *
+ *  - it is per-worktree (linked worktrees each get their own git dir), which is
+ *    precisely the granularity we are guarding;
+ *  - it can never appear in `git status`, so it cannot be mistaken for agent work,
+ *    cannot be swept into a commit by a `git add -A`, and needs no new exclusion
+ *    in the empty-diff backstop / `gc`'s cleanliness predicate (unlike
+ *    `.dorfl-job.json`, which each of those has to filter out by name);
+ *  - it is removed with the worktree, so it cannot outlive what it guards.
+ *
+ * ## Liveness, not presence
+ *
+ * A pid file that only records presence becomes a permanent blocker the first
+ * time a runner is `kill -9`ed. So the holder is checked for LIVENESS (its
+ * process group first, falling back to its pid) and a dead holder's sentinel is
+ * treated as stale and taken over. Only a genuinely live foreign writer refuses.
+ */
+/** The sentinel filename inside the worktree's private git directory. */
+export declare const WRITER_SENTINEL_FILENAME = "dorfl-writer.json";
+/** The recorded holder of a worktree's writer sentinel. */
+export interface WorktreeWriter {
+    /** The runner process that owns the agent writing in this tree. */
+    pid: number;
+    /** The agent's process GROUP, when the harness spawned a killable one. */
+    pgid?: number;
+    /** The item being built in this tree (diagnostics: names the other writer). */
+    slug: string;
+    /** ISO timestamp of acquisition (diagnostics: how long it has been held). */
+    startedAt: string;
+}
+/** The outcome of trying to become a worktree's sole writer. */
+export type WorktreeWriterLock = {
+    acquired: true;
+    /** Release the sentinel. Idempotent, and safe if it was already stolen. */
+    release(): void;
+} | {
+    acquired: false;
+    /** The LIVE holder that refused us (when it could be parsed). */
+    holder?: WorktreeWriter;
+    /** Human-readable refusal, naming the other writer. */
+    reason: string;
+};
+/** The sentinel path for `dir`, or `undefined` when `dir` is not a worktree. */
+export declare function writerSentinelPath(dir: string, env?: NodeJS.ProcessEnv): string | undefined;
+/** Read + parse the sentinel, or `undefined` when absent/corrupt. */
+export declare function readWorktreeWriter(dir: string, env?: NodeJS.ProcessEnv): WorktreeWriter | undefined;
+/**
+ * Is the recorded holder still running? Prefers the agent's process GROUP (which
+ * survives the group leader's death and so catches exactly the orphaned-writer
+ * case this exists for), and falls back to the runner pid.
+ */
+export declare function writerAlive(holder: WorktreeWriter): boolean;
+/**
+ * Claim `dir` as the SOLE agent-writable working tree for `slug`.
+ *
+ * Refuses when a DIFFERENT, still-LIVE writer holds it — the second-agent case
+ * the observation describes. A dead holder's sentinel is stale and is taken over
+ * silently (a `kill -9`ed runner must not poison the worktree forever), and our
+ * OWN pid re-acquiring is a no-op re-entry rather than a refusal.
+ *
+ * When `dir` is not a git worktree there is nowhere private to record the
+ * sentinel; that is reported as acquired with a no-op release, because this is a
+ * defence-in-depth backstop and must never become a new way for a legitimate run
+ * to fail.
+ */
+export declare function acquireWorktreeWriterLock(params: {
+    dir: string;
+    slug: string;
+    /** The agent's process group, when known (the strongest liveness anchor). */
+    pgid?: number;
+    env?: NodeJS.ProcessEnv;
+}): WorktreeWriterLock;
+//# sourceMappingURL=worktree-writer-lock.d.ts.map

package/dist/worktree-writer-lock.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"worktree-writer-lock.d.ts","sourceRoot":"","sources":["../src/worktree-writer-lock.ts"],"names":[],"mappings":"AAYA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AAEH,yEAAyE;AACzE,eAAO,MAAM,wBAAwB,sBAAsB,CAAC;AAE5D,2DAA2D;AAC3D,MAAM,WAAW,cAAc;IAC9B,mEAAmE;IACnE,GAAG,EAAE,MAAM,CAAC;IACZ,0EAA0E;IAC1E,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,+EAA+E;IAC/E,IAAI,EAAE,MAAM,CAAC;IACb,6EAA6E;IAC7E,SAAS,EAAE,MAAM,CAAC;CAClB;AAED,gEAAgE;AAChE,MAAM,MAAM,kBAAkB,GAC3B;IACA,QAAQ,EAAE,IAAI,CAAC;IACf,2EAA2E;IAC3E,OAAO,IAAI,IAAI,CAAC;CACf,GACD;IACA,QAAQ,EAAE,KAAK,CAAC;IAChB,iEAAiE;IACjE,MAAM,CAAC,EAAE,cAAc,CAAC;IACxB,uDAAuD;IACvD,MAAM,EAAE,MAAM,CAAC;CACd,CAAC;AAmBL,gFAAgF;AAChF,wBAAgB,kBAAkB,CACjC,GAAG,EAAE,MAAM,EACX,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,GACrB,MAAM,GAAG,SAAS,CAKpB;AAED,qEAAqE;AACrE,wBAAgB,kBAAkB,CACjC,GAAG,EAAE,MAAM,EACX,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,GACrB,cAAc,GAAG,SAAS,CAa5B;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,cAAc,GAAG,OAAO,CAK3D;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,yBAAyB,CAAC,MAAM,EAAE;IACjD,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,6EAA6E;IAC7E,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;CACxB,GAAG,kBAAkB,CAoDrB"}