pi-durable-subagents 1.0.16 → 1.0.18

package/dist/orchestrator/executor/usage.js

@@ -22,20 +22,30 @@ export function sessionUsage(entries, call) {
     });
 }
 /** P31: Sum deduplicated committed message usage across executions, optionally across a whole workflow. */
+const totals = new WeakMap();
 export function totalUsage(entries, call) {
-    const seen = new Set(), total = { input: 0, output: 0, costUsd: 0 };
-    for (const e of entries)
-        if (e.type === "usage" && (call === undefined || e.call === call)) {
-            const id = `${e.call}:${e.id}`;
-            if (seen.has(id))
-                continue;
-            seen.add(id);
-            const u = e.usage;
-            total.input += u.input;
-            total.output += u.output;
-            total.costUsd += u.costUsd;
+    let state = totals.get(entries);
+    if (!state) {
+        state = { count: 0, seen: new Set(), total: { input: 0, output: 0, costUsd: 0 }, calls: new Map() };
+        totals.set(entries, state);
+    }
+    while (state.count < entries.length) {
+        const e = entries[state.count++];
+        if (e.type !== "usage")
+            continue;
+        const id = `${e.call}:${e.id}`;
+        if (state.seen.has(id))
+            continue;
+        state.seen.add(id);
+        const key = String(e.call), total = state.calls.get(key) ?? { input: 0, output: 0, costUsd: 0 }, u = e.usage;
+        state.calls.set(key, total);
+        for (const target of [total, state.total]) {
+            target.input += u.input;
+            target.output += u.output;
+            target.costUsd += u.costUsd;
         }
-    return total;
+    }
+    return { ...(call === undefined ? state.total : state.calls.get(call) ?? { input: 0, output: 0, costUsd: 0 }) };
 }
 /** V8: Reached means either configured limit has been consumed, including truthful overshoot. */
 export function reached(usage, budget) {

package/dist/orchestrator/executor/worktree.js

@@ -115,7 +115,7 @@ export class WorktreeIndex {
         }
         else if (e.type === "wf-created")
             this.origins.set(journal, e.origin);
-        else if (isEntry(e, JT.attention) && e.item?.kind === "conflict") {
+        else if (isEntry(e, JT.attention) && e.item?.kind === "conflict" && String(e.item.id).startsWith("worktree:")) {
             const held = this.reminders.get(e.item.id) ?? new Map();
             this.reminders.set(e.item.id, held);
             if (!held.has(journal))

package/dist/orchestrator/ledger.js

@@ -6,10 +6,11 @@
 //   config{hash,config}: the orchestrator settings in effect from here; config-rejected{error,hash?}: a change of
 //     config.json refused, while the earlier settings stay (cleared by the next config record).
 //   orchestrator{version,pid} / orchestrator-exit{pid}: the orchestrator running (its package version) and its exit.
+//   writer-hold/writer-release{root,call}: the writer lock of a worktree root, held by one call until it ends.
 import { foldExhaustion } from "./providers.js";
 import { isEntry } from "../types.js";
 export function emptyLedger() {
-    return { seen: 0, held: new Map(), observed: new Set(), skips: new Map(), exhausted: new Map() };
+    return { seen: 0, held: new Map(), writers: new Map(), observed: new Set(), skips: new Map(), exhausted: new Map() };
 }
 /** Apply one orchestrator ledger entry. */
 export function applyLedger(state, e) {
@@ -31,7 +32,15 @@ export function applyLedger(state, e) {
     else if (isEntry(e, "config-rejected"))
         state.rejected = { error: String(e.error), ts: e.ts };
     else if (isEntry(e, "orchestrator"))
-        state.orchestrator = { version: String(e.version), pid: Number(e.pid), ...(e.start ? { start: String(e.start) } : {}), ts: e.ts };
+        state.orchestrator = { version: String(e.version), pid: Number(e.pid), ...(e.start ? { start: String(e.start) } : {}), ts: e.ts, ...(e.restart === true ? { restart: true } : {}) };
+    else if (e.type === "writer-hold") {
+        if (!state.writers.has(String(e.root)))
+            state.writers.set(String(e.root), { call: String(e.call), ts: e.ts });
+    }
+    else if (e.type === "writer-release") {
+        if (state.writers.get(String(e.root))?.call === e.call)
+            state.writers.delete(String(e.root));
+    }
     else if (isEntry(e, "orchestrator-exit")) {
         if (state.orchestrator?.pid === e.pid)
             state.orchestrator.exited = true;

package/dist/orchestrator/main.js

@@ -6,24 +6,27 @@ var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExte
     }
     return path;
 };
+import { spawn } from 'node:child_process';
 import { mkdir } from 'node:fs/promises';
 import { fileURLToPath } from 'node:url';
 import { realpathSync } from 'node:fs';
 import { join, resolve } from 'node:path';
-import { dsaHome, orchLedger, orchLock } from "../paths.js";
+import { binDir, dsaHome, orchLedger, orchLock } from "../paths.js";
+import { writeShim } from "../platform/lease.js";
 import { openJournal } from "../kernel/journal.js";
 import { OsLock } from "../platform/lock.js";
 import { captureStart } from "../platform/proctable.js";
 import { Engine } from "./engine.js";
 import { configPath, configProblem, configStamp, recordConfig, stampedConfig, watchConfig } from "./config.js";
 import { packageVersion } from "../version.js";
-/** P2, C4, K6: Acquire the single authority before opening ledgers, recover, and idle-exit. */
+/** P2, C4, K6: Acquire the single authority before opening ledgers, recover, and idle-exit. Resolves `restart` when an
+ *  applied restart request ended it (the caller starts the successor once the lock is released). */
 export async function main(options = {}) {
     const home = options.home ?? dsaHome();
     await mkdir(home, { recursive: true });
     const lock = await new OsLock().tryAcquire(orchLock(home));
     if (!lock)
-        return;
+        return {};
     let engine, ledgers, watcher;
     try {
         let config = options.config, stamp;
@@ -41,7 +44,14 @@ export async function main(options = {}) {
         // Which version runs is visible to every pi session (status; a notice when it differs from the one pi loaded).
         // `start` (Linux) tells this process from a later one given the same pid after a crash.
         const start = await captureStart(process.pid).catch(() => '');
-        await ledgers.orch.append('orchestrator', { version: packageVersion(), pid: process.pid, ...(start ? { start } : {}) });
+        // Subagents reach `pi-durable-subagents hold …` through this shim, written before the start is recorded (executor puts its directory first on PATH).
+        try {
+            writeShim(binDir(home), process.execPath, fileURLToPath(new URL(import.meta.url.endsWith('.ts') ? '../cli/main.ts' : '../cli/main.js', import.meta.url)));
+        }
+        catch (error) {
+            console.error(`durable-subagents: cannot write ${binDir(home)}: ${String(error)}`);
+        }
+        await ledgers.orch.append('orchestrator', { version: packageVersion(), pid: process.pid, ...(start ? { start } : {}), restart: true });
         const factory = options.executor ?? (await import(__rewriteRelativeImportExtension(new URL(import.meta.url.endsWith('.ts') ? './executor/index.ts' : './executor/index.js', import.meta.url).href))).default;
         const executor = factory(ledgers);
         engine = new Engine(ledgers, executor, options);
@@ -54,6 +64,7 @@ export async function main(options = {}) {
         }
         await engine.recover();
         await engine.loop(options.signal);
+        return engine.restartRequested ? { restart: true } : {};
     }
     finally {
         try {
@@ -77,5 +88,10 @@ if (process.argv[1] && realpathSync(resolve(process.argv[1])) === fileURLToPath(
     const controller = new AbortController();
     process.once('SIGTERM', () => controller.abort());
     process.once('SIGINT', () => controller.abort());
-    main({ signal: controller.signal }).catch(error => { console.error(error); process.exitCode = 1; });
+    main({ signal: controller.signal }).then(({ restart }) => {
+        // Restart: the successor runs this same entry, which an update replaced in place; any pi session or CLI would start
+        // it too (whoever takes the lock first wins, the others exit at once).
+        if (restart)
+            spawn(process.execPath, [process.argv[1]], { detached: true, stdio: 'ignore', env: process.env }).unref();
+    }).catch(error => { console.error(error); process.exitCode = 1; });
 }

package/dist/orchestrator/snapshot.js

@@ -9,6 +9,7 @@ import { JT, isEntry } from "../types.js";
 import { emptyLedger, foldLedger } from "./ledger.js";
 import { packageVersion } from "../version.js";
 import { worktreeCalls, worktreeLabel } from "./executor/worktree.js";
+import { leaseCalls, leaseLines, leaseState } from "../platform/lease.js";
 /** A workflow has live work: it runs, or follow-ups opened on it after it finished have not ended yet. */
 export function isLive(wf) {
     return wf.status === "running" || (wf.followUps ?? 0) > 0;
@@ -127,6 +128,13 @@ function snapshotReducer(wid, entries) {
                 delete call.hibernated;
                 hibernating.delete(call.callId);
             }
+            else if (e.type === "writer-wait" || e.type === "writer-acquired") {
+                const call = calls.get(String(e.call)), holder = String(e.holder ?? "");
+                if (call && e.type === "writer-wait")
+                    call.writerWait = { root: String(e.root), holder: holder.includes("/") ? `${holder.split("@")[0]}/${holder.split("/")[1].split("@")[0]}` : holder };
+                else if (call)
+                    delete call.writerWait;
+            }
             else if (e.type === "hibernated") {
                 // The decision to hibernate precedes the fence; the slot is released only once the execution is fenced.
                 const call = calls.get(String(e.call));
@@ -191,6 +199,7 @@ function snapshotReducer(wid, entries) {
                 call.result = e.result;
                 call.endedAt = e.ts;
                 delete call.hibernated;
+                delete call.writerWait;
                 hibernating.delete(call.callId);
             }
             else if (isEntry(e, JT.attention)) {
@@ -418,7 +427,7 @@ export function formatUsage(u) {
     return `${n(u.input)} in / ${n(u.output)} out${u.costUsd > 0 ? `, $${u.costUsd.toFixed(u.costUsd < 0.01 ? 4 : 2)}` : ""}`;
 }
 /** P25, T10: Compact one workflow snapshot: per-call one-line facts, usage, open attention; no outputs or entries. */
-export function compactWorkflow(wf) {
+export function compactWorkflow(wf, leases) {
     const progress = progressOf(wf); // v12 §4
     return {
         wid: wf.wid, ...(wf.name ? { name: wf.name } : {}), ...(wf.origin ? { origin: wf.origin } : {}), status: wf.status, rev: wf.rev,
@@ -430,7 +439,8 @@ export function compactWorkflow(wf) {
             return { key: c.key, gen: c.gen, callId: c.callId, phase: c.phase, ...(r ? { status: r.status, ok: r.ok } : {}),
                 ...(c.sharedWorktree ? { sharedWorktree: c.sharedWorktree } : {}),
                 ...(c.model ? { model: c.model } : {}), ...(c.tools ? { tools: c.tools } : {}), ...(c.pending ? { pending: c.pending } : {}), ...(c.switching ? { switching: c.switching } : {}), ...(c.switchFailed ? { switchFailed: c.switchFailed } : {}), ...(nonzero(c.usage) ? { usage: c.usage } : {}),
-                ...(last ? { lastLine: clip(last, 200) } : {}), ...(r?.error ? { error: clip(r.error, 300) } : {}), ...(c.hibernated ? { hibernated: true } : {}) };
+                ...(last ? { lastLine: clip(last, 200) } : {}), ...(r?.error ? { error: clip(r.error, 300) } : {}), ...(c.hibernated ? { hibernated: true } : {}),
+                ...(c.writerWait && !r ? { writerWait: c.writerWait } : {}), ...(!r && leases?.get(c.callId) ? { lease: leases.get(c.callId) } : {}) };
         }),
         attention: wf.attention.map(a => ({ id: a.id, rev: a.rev, kind: a.kind, text: clip(a.text, 300), ...(a.call ? { call: a.call } : {}), ...(a.qid ? { qid: a.qid } : {}) })),
         ...(wf.paused ? { paused: true } : {}), ...(wf.followUps ? { followUps: wf.followUps } : {}),
@@ -460,14 +470,14 @@ function snapshots(home, origin) {
 /** P25, T10: Compact status of all workflows: own session first, then newest first; finished ones beyond the first `keep` collapse into a count. */
 export function statusView(home, options = {}) {
     const keep = options.keep ?? 10;
-    const { all, since } = snapshots(home, options.origin);
+    const { all, since } = snapshots(home, options.origin), leases = leaseState(home), byCall = leaseCalls(leases);
     let finished = 0;
     const shown = all.filter(w => !settled(w) || ++finished <= keep);
     const hidden = all.length - shown.length;
     const paused = all.filter(w => w.paused).length;
-    return { workflows: shown.map(compactWorkflow), ...(hidden ? { olderFinished: hidden, hint: "status wid=<wid> shows any workflow in detail" } : {}),
+    return { workflows: shown.map(w => compactWorkflow(w, byCall)), ...(hidden ? { olderFinished: hidden, hint: "status wid=<wid> shows any workflow in detail" } : {}),
         ...(paused ? { paused: `${paused} workflow${paused > 1 ? "s" : ""} paused (stop-all, drain or a quit pi) since ${new Date(since).toISOString()}; resume continues them (new runs are not affected)` } : {}),
-        ...slotsView(home) };
+        ...slotsView(home), ...(leases.length ? { leases: leaseLines(leases) } : {}) };
 }
 const FINAL = ["done", "failed", "stopped"];
 /** Finished with nothing left running (a follow-up on a finished workflow is live work). */
@@ -484,13 +494,13 @@ const ledgerStates = new Map();
  *  its version is not the one this process loaded: running work stays on the version it started with. */
 export function orchestratorView(state, loaded = packageVersion()) {
     const o = state.orchestrator;
-    if (!o || o.exited || !alive(o.pid, o.start))
+    if (!o || o.exited || !processAlive(o.pid, o.start))
         return {};
     return { orchestrator: `${o.version} (pid ${o.pid})`, ...(o.version === loaded ? {} : { versionNote: versionNote(o.version, loaded) }) };
 }
 /** Whether the recorded orchestrator still runs. On Linux its start time also tells it from a later process given the
  *  same pid after a crash (elsewhere the pid alone is checked). */
-function alive(pid, start) {
+export function processAlive(pid, start) {
     try {
         process.kill(pid, 0);
     }
@@ -520,10 +530,9 @@ export function versionNote(running, loaded) {
     return newer(running, loaded)
         ? `this pi session loaded durable-subagents ${loaded}, older than the running orchestrator ${running}; start a new pi session to use ${running}`
         : `the orchestrator runs durable-subagents ${running}, this pi loaded ${loaded}: running work stays on ${running}. ` +
-            `It exits about 10 s after all work ends and starts again on ${loaded}. To switch sooner without stopping running calls: ` +
-            `drain (running calls finish, nothing new starts in existing workflows; calls waiting for an answer keep it running), ` +
-            `wait until status no longer shows ${running}, then resume from a pi session started after the update. ` +
-            `A resume before it exits keeps ${running}, and pi sessions started before the update start ${running} again`;
+            `It exits about 10 s after all work ends and starts again on the installed version. To switch sooner: ` +
+            `restart (\`pi-durable-subagents restart\` or the subagents tool's restart action) — refused while an execution runs, ` +
+            `calls waiting for an answer or a slot do not block it; force fences running executions, which resume on the new version`;
 }
 /** orchestratorView of the home's orchestrator ledger. */
 export function runningOrchestrator(home) {
@@ -552,7 +561,7 @@ export function slotsView(home, now = Date.now()) {
  *  The full view (every call's last line and usage) ran to tens of thousands of tokens on a busy home. */
 export function statusBrief(home, options = {}) {
     const keep = options.keep ?? 5, now = options.now ?? Date.now(), origin = options.origin;
-    const { all } = snapshots(home, origin);
+    const { all } = snapshots(home, origin), leases = leaseState(home), byCall = leaseCalls(leases, now);
     const mine = (w) => !origin || w.origin === origin;
     const line = (w) => {
         const p = progressOf(w), notOk = latestCalls(w).filter(c => c.result && !c.result.ok).length;
@@ -569,7 +578,8 @@ export function statusBrief(home, options = {}) {
                 ...(live && c.phase !== "asking" && quiet !== undefined && quiet >= 60_000 ? { quiet: age(quiet) } : {}),
                 ...(live && c.startedAt !== undefined ? { tokens: tokens(c.usage) } : {}),
                 ...(c.result ? { status: c.result.status, ...(c.result.error ? { error: clip(c.result.error, 200) } : {}) } : {}),
-                ...(c.hibernated ? { hibernated: true } : {}),
+                ...(c.hibernated ? { hibernated: true } : {}), ...(live && c.writerWait ? { writerWait: c.writerWait } : {}),
+                ...(live && byCall.get(c.callId) ? { lease: byCall.get(c.callId) } : {}),
                 ...(live && c.switching ? { switching: c.switching } : {}), ...(live && c.switchFailed ? { switchFailed: c.switchFailed } : {}) };
         });
         const asking = open.filter(a => a.kind === "question" && a.call).map(a => ({ to: `${w.wid}/${callKey(a.call)}`, ...(a.qid ? { qid: a.qid } : {}),
@@ -588,7 +598,7 @@ export function statusBrief(home, options = {}) {
     return {
         active: active.filter(mine).map(brief), ...(others.length ? { otherSessions: others.slice(0, 10).map(line) } : {}),
         finished: finished.slice(0, keep).map(line), ...(finished.length > keep ? { olderFinished: finished.length - keep } : {}),
-        ...(paused ? { paused } : {}), ...slotsView(home, now),
+        ...(paused ? { paused } : {}), ...slotsView(home, now), ...(leases.length ? { leases: leaseLines(leases, now) } : {}),
         hint: "status wid=<wid> shows one workflow (outputs clipped); add key=<key> for one call's full result, or full:true for everything",
     };
 }

package/dist/orchestrator/store.js

@@ -105,14 +105,26 @@ export async function prepareRun(body, discovery, warnings = []) {
         ...(body.usageBudget ? { usageBudget: body.usageBudget } : {}), ...(body.maxCalls !== undefined ? { maxCalls: body.maxCalls } : {}) };
 }
 /** A1, A5: Reduce only the current revision, retaining all history for seals and allocation. */
+const revisions = new WeakMap();
+const terminals = new WeakMap();
 export function revisionEntries(wf) {
-    const entries = wf.journal.entries(), start = entries.findLastIndex(e => e.type === 'revised');
-    return entries.slice(Math.max(0, start));
+    const entries = wf.journal.entries();
+    let view = revisions.get(entries);
+    if (!view) {
+        const start = entries.findLastIndex(e => e.type === 'revised');
+        view = start < 0 ? entries : entries.slice(start);
+        revisions.set(entries, view);
+    }
+    return view;
 }
 /** A1, A5: A resume supersedes a terminal observation without deleting history. */
 export function terminalEntry(entries) {
+    if (terminals.has(entries))
+        return terminals.get(entries);
     const last = entries.findLast(e => e.type === JT.done || (e.type === 'resumed' && !e.call) || e.type === 'revised');
-    return last?.type === JT.done ? last : undefined;
+    const terminal = last?.type === JT.done ? last : undefined;
+    terminals.set(entries, terminal);
+    return terminal;
 }
 /** Housekeeping: bytes under a path (files counted once by lstat; a missing path is 0). */
 export async function diskUsage(path) {

package/dist/paths.js

@@ -6,6 +6,8 @@ import { ENV } from "./types.js";
 export const dsaHome = (env = process.env) => env[ENV.home] || path.join(os.homedir(), ".pi", "durable-subagents");
 export const orchLedger = (home) => path.join(home, "orchestrator.jsonl");
 export const orchLock = (home) => path.join(home, "orchestrator.lock");
+/** Executables for subagents: the orchestrator writes a `pi-durable-subagents` shim here and children get it on PATH. */
+export const binDir = (home) => path.join(home, "bin");
 /** Drop box for requests addressed to the orchestrator. */
 export const orchInbox = (home) => path.join(home, "inbox");
 /** Sender outboxes live under this root (kernel Outbox.open(root, ...)). */

package/dist/platform/containment.js

@@ -3,12 +3,14 @@ import { PassThrough } from "node:stream";
 import { setTimeout as delay } from "node:timers/promises";
 import { performance } from "node:perf_hooks";
 import { captureStart, ProcessTable } from "./proctable.js";
+// One table per orchestrator process, including evaluator and gate observers.
+const sharedTable = new ProcessTable();
 const identity = (p) => `${p.pid}:${p.start}`;
 /** P22, P23, C1, C3: Direct launch and identity-based retirement of executions. */
 export class Containment {
     table;
     launched = new Map();
-    constructor(table = new ProcessTable()) { this.table = table; }
+    constructor(table = sharedTable) { this.table = table; }
     /** C1, C3: Inject the execution tag and capture the direct child's start token. */
     async spawn(spec) {
         const child = spawn(spec.command, spec.args, { cwd: spec.cwd,
@@ -44,16 +46,20 @@ export class Containment {
         }
     }
     /** P22: Find tagged processes and the live descendants of known identities. */
-    async scan(known) {
+    async scan(known, options = {}) {
         const execs = new Set([...known.keys(), ...this.launched.keys()]);
-        const all = await this.table.list(execs);
+        const all = await this.table.list(execs, options);
         for (const p of all)
             if (p.tag !== undefined)
                 execs.add(p.tag);
-        const result = new Map();
+        const result = new Map(), liveStarts = new Map(all.map(p => [p.pid, p.start]));
         for (const exec of execs) {
-            const ids = new Set([...(known.get(exec) ?? []), ...(this.launched.get(exec) ?? [])]
-                .filter(p => p.start !== "").map(identity));
+            // Historical identities cannot select an absent/reused pid. Avoid allocating a string/Set entry for each one.
+            const ids = new Set();
+            for (const group of [known.get(exec) ?? [], this.launched.get(exec) ?? []])
+                for (const p of group)
+                    if (p.start !== "" && liveStarts.get(p.pid) === p.start)
+                        ids.add(identity(p));
             const selected = new Map(all.filter(p => p.tag === exec || ids.has(identity(p))).map(p => [p.pid, p]));
             let changed = true;
             while (changed) {
@@ -79,7 +85,7 @@ export class Containment {
             const remaining = deadline - performance.now();
             let timer;
             const live = await Promise.race([
-                this.scan(new Map([[exec, [...known.values()]]])),
+                this.scan(new Map([[exec, [...known.values()]]]), { fresh: true }),
                 new Promise((_, reject) => { timer = setTimeout(() => reject(new Error(`Fence timeout: ${exec}`)), Math.max(0, remaining)); }),
             ]).finally(() => clearTimeout(timer));
             const targets = live.get(exec) ?? [];

package/dist/platform/lease.js

@@ -0,0 +1,236 @@
+// Command-scoped resource leases: `pi-durable-subagents hold <resource> -- <command>` (README "Resource leases").
+// One ticket file per request under $DSA_HOME/leases/<resource>/, numbered under a kernel lock so the numbers are
+// strictly increasing and never reused. Grants are strict FIFO by number: an exclusive request needs no earlier live
+// ticket, a shared one no earlier live exclusive ticket. Whether a request is grantable depends only on earlier tickets,
+// which can only disappear, so a grant needs no lock once the ticket exists. A ticket is live while its wrapper or its
+// command (pid + start token) lives, or processes the command left in its group remain; a waiter next in line ends such
+// leftovers of a killed wrapper. Anyone may delete a dead ticket. No orchestrator is involved.
+import { chmodSync, mkdirSync, readdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
+import { readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { OsLock } from "./lock.js";
+export const RESOURCE = /^[A-Za-z0-9._-]{1,64}$/;
+export const leasesRoot = (home) => path.join(home, "leases");
+export const leaseDir = (home, resource) => path.join(leasesRoot(home), resource);
+const ticketName = (seq) => `${String(seq).padStart(12, "0")}.json`;
+const TICKET = /^\d{12}\.json$/;
+/** Whether a process still runs; on Linux the start token also tells it from a later process with the same pid. */
+export function alive(p) {
+    if (!p)
+        return false;
+    try {
+        process.kill(p.pid, 0);
+    }
+    catch (error) {
+        if (error.code !== "EPERM")
+            return false;
+    }
+    if (!p.start || process.platform !== "linux")
+        return true;
+    try {
+        const fields = readFileSync(`/proc/${p.pid}/stat`, "utf8");
+        const rest = fields.slice(fields.lastIndexOf(")") + 2).split(" ");
+        return rest[0] !== "Z" && rest[0] !== "X" && rest[19] === p.start;
+    }
+    catch {
+        return false;
+    }
+}
+/** Whether process group `pgid` still has a member that can run (Linux: zombies, which no signal ends, do not count). */
+export function groupAlive(pgid) {
+    try {
+        process.kill(-pgid, 0);
+    }
+    catch (e) {
+        if (e.code !== "EPERM")
+            return false;
+    }
+    if (process.platform !== "linux")
+        return true;
+    let pids;
+    try {
+        pids = readdirSync("/proc").filter(n => /^\d+$/.test(n));
+    }
+    catch {
+        return true;
+    }
+    for (const pid of pids) {
+        try {
+            const fields = readFileSync(`/proc/${pid}/stat`, "utf8");
+            const rest = fields.slice(fields.lastIndexOf(")") + 2).split(" ");
+            if (Number(rest[2]) === pgid && rest[0] !== "Z" && rest[0] !== "X")
+                return true;
+        }
+        catch { /* exited meanwhile */ }
+    }
+    return false;
+}
+/**
+ * Whether the command's process group outlives both the wrapper and the command (a killed wrapper cannot end what the
+ * command left behind). The command was spawned as its group's leader, so the group id is its pid. A pid stays
+ * allocated while a group uses it as its id, so with the leader gone a group with that id is the command's own. While a
+ * process owns the pid it must be the command itself (on Linux the start token, zombie or not); any other owner means
+ * the original group emptied and the pid was reused. macOS has no start token here: a reused pid that is alive there
+ * counts as the command (the lease waits for it), never as leftovers to end.
+ */
+export function orphaned(t) {
+    const c = t.command;
+    if (!c || alive(t.wrapper) || alive(c))
+        return false;
+    if (process.platform === "linux") {
+        try {
+            const fields = readFileSync(`/proc/${c.pid}/stat`, "utf8");
+            const rest = fields.slice(fields.lastIndexOf(")") + 2).split(" ");
+            if (!c.start || rest[19] !== c.start)
+                return false;
+        }
+        catch { /* the leader is gone: only its group can remain */ }
+    }
+    else {
+        try {
+            process.kill(c.pid, 0);
+            return false;
+        }
+        catch { /* the leader is gone */ }
+    }
+    if (groupAlive(c.pid))
+        return true;
+    // One /proc listing is not atomic: a member can fork and exit between reading the directory and reading the stats, so
+    // "no running member" is not proof. Whatever the group still holds is leftovers of a holder that is gone (which the
+    // waiters would end anyway), so end it: a group signal reaches every member at once, a newborn included; zombies stay.
+    try {
+        process.kill(-c.pid, "SIGKILL");
+    }
+    catch { /* the group is gone */ }
+    return false;
+}
+/** A ticket is live while its wrapper, its command, or processes the command left in its group run. */
+export const live = (t) => alive(t.wrapper) || alive(t.command) || orphaned(t);
+/** The tickets of one resource in request order (unreadable or half-written files are skipped). */
+export function readTickets(home, resource) {
+    let names;
+    try {
+        names = readdirSync(leaseDir(home, resource));
+    }
+    catch {
+        return [];
+    }
+    const out = [];
+    for (const name of names.filter(n => TICKET.test(n)).sort()) {
+        try {
+            out.push(JSON.parse(readFileSync(path.join(leaseDir(home, resource), name), "utf8")));
+        }
+        catch { /* raced with a delete */ }
+    }
+    return out;
+}
+/** Live tickets; dead ones are deleted (their numbers are never reused, so a stale reader cannot delete a newer one). */
+export function liveTickets(home, resource) {
+    return readTickets(home, resource).filter(t => {
+        if (live(t))
+            return true;
+        try {
+            unlinkSync(path.join(leaseDir(home, resource), ticketName(t.seq)));
+        }
+        catch { /* already gone */ }
+        return false;
+    });
+}
+/** The live tickets that come before `t` and keep it waiting (empty when it may run). */
+export function blockers(t, tickets) {
+    return tickets.filter(o => o.seq < t.seq && (t.mode === "exclusive" || o.mode === "exclusive"));
+}
+function writeTicketSync(home, t) {
+    const file = path.join(leaseDir(home, t.resource), ticketName(t.seq)), tmp = `${file}.${process.pid}.tmp`;
+    writeFileSync(tmp, JSON.stringify(t));
+    renameSync(tmp, file);
+}
+export async function writeTicket(home, t) {
+    const file = path.join(leaseDir(home, t.resource), ticketName(t.seq)), tmp = `${file}.${process.pid}.tmp`;
+    await writeFile(tmp, JSON.stringify(t));
+    renameSync(tmp, file);
+}
+export function removeTicket(home, t) {
+    try {
+        unlinkSync(path.join(leaseDir(home, t.resource), ticketName(t.seq)));
+    }
+    catch { /* already gone */ }
+}
+/** Queue a request: number it under the resource's kernel lock and write its ticket before the lock is released, so a
+ *  later request always sees it. */
+export async function enqueue(home, ticket, lock = new OsLock()) {
+    const dir = leaseDir(home, ticket.resource);
+    mkdirSync(dir, { recursive: true });
+    let handle = await lock.tryAcquire(path.join(dir, ".lock"));
+    for (let delay = 5; !handle; delay = Math.min(delay * 2, 100)) {
+        await new Promise(r => setTimeout(r, delay));
+        handle = await lock.tryAcquire(path.join(dir, ".lock"));
+    }
+    try {
+        const counter = path.join(dir, ".seq");
+        const last = Number.parseInt(await readFile(counter, "utf8").catch(() => "0"), 10) || 0;
+        const highest = readTickets(home, ticket.resource).reduce((m, t) => Math.max(m, t.seq), last);
+        const t = { ...ticket, seq: highest + 1 };
+        await writeFile(`${counter}.tmp`, String(t.seq));
+        renameSync(`${counter}.tmp`, counter);
+        writeTicketSync(home, t);
+        return t;
+    }
+    finally {
+        await handle.release();
+    }
+}
+/** Every resource with live tickets: holders (granted) and waiters, in request order. Cheap: a directory listing,
+ *  small files and a liveness check of the few ticket processes. */
+export function leaseState(home) {
+    let resources;
+    try {
+        resources = readdirSync(leasesRoot(home)).filter(r => RESOURCE.test(r)).sort();
+    }
+    catch {
+        return [];
+    }
+    return resources.map(resource => {
+        const tickets = liveTickets(home, resource);
+        return { resource, holders: tickets.filter(t => t.grantedAt !== undefined), waiters: tickets.filter(t => t.grantedAt === undefined) };
+    }).filter(r => r.holders.length || r.waiters.length);
+}
+const age = (ms) => ms < 60_000 ? `${Math.max(0, Math.round(ms / 1000))}s` : ms < 3_600_000 ? `${Math.round(ms / 60_000)}m` : `${(ms / 3_600_000).toFixed(1)}h`;
+const clip = (s, n) => s.length > n ? `${s.slice(0, n - 1)}…` : s;
+/** "<wid>/<key>" of a call id "<wid>@<rev>/<key>@<gen>". */
+export const callAddress = (call) => { const m = /^([^@/]+)@\d+\/(.+)@\d+$/.exec(call); return m ? `${m[1]}/${m[2]}` : call; };
+/** Who holds or waits: the subagent call when there is one, else the pid and command. */
+export const who = (t) => t.call ? callAddress(t.call) : `pid ${t.wrapper.pid} \`${clip(t.argv.join(" "), 60)}\``;
+/** One status line per resource: "machine held by <who> (exclusive, 12m, `make bench`); waiting: <who> 3m, …". */
+export function leaseLines(state, now = Date.now()) {
+    return state.map(({ resource, holders, waiters }) => {
+        const held = holders.length
+            ? `held by ${holders.map(t => `${who(t)} (${t.mode}, ${age(now - (t.grantedAt ?? t.since))}${t.call ? `, \`${clip(t.argv.join(" "), 60)}\`` : ""}${t.note ? `, ${clip(t.note, 80)}` : ""})`).join(", ")}`
+            : "free";
+        return `${resource} ${held}${waiters.length ? `; waiting: ${waiters.map(t => `${who(t)} ${t.mode === "shared" ? "shared " : ""}${age(now - t.since)}`).join(", ")}` : ""}`;
+    });
+}
+/** Per call id: "holds lease machine" / "waiting for lease machine 3m". */
+export function leaseCalls(state, now = Date.now()) {
+    const out = new Map();
+    for (const { resource, holders, waiters } of state) {
+        for (const t of holders)
+            if (t.call)
+                out.set(t.call, [out.get(t.call), `holds lease ${resource}`].filter(Boolean).join(", "));
+        for (const t of waiters)
+            if (t.call)
+                out.set(t.call, [out.get(t.call), `waiting for lease ${resource} ${age(now - t.since)}`].filter(Boolean).join(", "));
+    }
+    return out;
+}
+const quote = (s) => `'${s.replace(/'/g, `'\\''`)}'`;
+/** The `pi-durable-subagents` command for subagents: `<dir>/pi-durable-subagents` runs this node with the CLI entry of
+ *  the running orchestrator, so children can `hold` without the package on their PATH. Rewritten at every start. */
+export function writeShim(dir, node, entry) {
+    mkdirSync(dir, { recursive: true });
+    const file = path.join(dir, "pi-durable-subagents"), tmp = `${file}.${process.pid}.tmp`;
+    writeFileSync(tmp, `#!/bin/sh\nexec ${quote(node)} ${quote(entry)} "$@"\n`);
+    chmodSync(tmp, 0o755);
+    renameSync(tmp, file);
+    return file;
+}