pi-durable-subagents 1.0.17 → 1.0.19

package/CHANGELOG.md

@@ -1,5 +1,46 @@
 # Changelog
 
+## 1.0.19
+
+- The orchestrator no longer keeps every workflow's pinned origin branch (the
+  parent session copied for `context: "fork"`) and input bytes in memory; they
+  are read from the pinned files when needed. With about 110 workflows of
+  history, the orchestrator heap had grown to 3.7 GB; on a copy of that
+  history it now stays near 120 MB.
+
+## 1.0.18
+
+- The orchestrator uses far less CPU. Running calls share one process-table
+  scan instead of each rescanning `/proc` whenever its call directory
+  changed, streamed output no longer triggers whole-journal checks for every
+  event, and status/idle checks reuse cached journal views. In a benchmark
+  with four streaming calls and 200 other processes, CPU fell from about
+  1.9 cores to 0.07; with 100 workflows of history, from about 1.1 cores to
+  0.03.
+- `pi-durable-subagents restart [--force]` (and the `restart` tool action)
+  replaces the orchestrator with the installed version. It refuses while an
+  execution is running and lists them (`<wid>/<key>`, age, origin); calls
+  waiting for a slot or an answer do not block it. `--force` fences the
+  running executions, which resume on the new orchestrator. No execution
+  starts between the check and the restart. Against an orchestrator from
+  1.0.17 or earlier, the CLI checks the journals itself and then stops the
+  old process. Use it instead of killing the orchestrator.
+- One writer call per worktree is now enforced. A call whose tools include
+  `edit` or `write` holds its git worktree from its first execution until it
+  ends, also while waiting for an answer and across orchestrator restarts.
+  Another writer in that worktree waits in order; its status line shows
+  `(waiting for writer lock: <root> held by <wid>/<key>)` and its origin gets
+  one `conflict` notice. `writer:false` on a call, `isolation:"worktree"`, or
+  `writerLock: "off"` in config.json opt out.
+- `pi-durable-subagents hold <resource> [--shared] [--max-wait s] -- <cmd>`
+  runs a command under a resource lease, such as `machine` for benchmarks:
+  exclusive holders run one at a time, shared holders together, strictly in
+  request order. The lease lasts as long as the command, even if the `hold`
+  process is killed, and the command's leftover processes end before it is
+  released. Subagents find the command on their PATH; it also works from
+  your own shell without an orchestrator. `leases` and status show holders
+  and waiters, and a call's status line shows the lease it holds or waits for.
+
 ## 1.0.17
 
 - A silent subagent shows one warning instead of separate activity and

package/README.md

@@ -56,7 +56,7 @@ the npx cache, so `install-service` refuses to run from there.
 | Two steers arrive out of order and the second replaces the first | Only the second one applies. |
 | A step is refused, or a dependency fails | The workflow stops that branch cleanly. Nothing is retried in vain. |
 | A provider's usage window runs out (`No available accounts`, usage limit, quota exceeded) | Found at the second refusal in a row, while pi is still retrying. A call in a pool continues **in the same session** on the pool's next model (within pi's next retry or two); new calls skip that provider. After 15 minutes the next call that wants it tries it once; when it answers, new calls and new generations use it again. A call with a single model waits for it instead of failing. Billing errors (402, insufficient balance) still fail at once. |
-| Two subagents edit the same worktree | A reminder names both calls; neither is blocked or locked. Only observed `edit`/`write` calls count (bash-only writes are not seen). Calls with `isolation: "worktree"` have their own worktrees. |
+| Two subagents would write in the same worktree | Only one runs there at a time. A call that can write (its tools include `edit` or `write`, which pi's default tools do) holds its git worktree's writer lock from its launch until it ends, also while it waits for an answer. Another writer for that worktree waits in order, and status shows `waiting for writer lock: <root> held by <wid>/<key>`. `writer: false` (a call that does not write there), `isolation: "worktree"` and `"writerLock": "off"` opt out. |
 | A subagent waits for an answer for a long time | It releases its model slot and memory, then resumes exactly once when you answer. |
 
 ## Use it
@@ -126,7 +126,9 @@ single file: it cannot `import` or `require` other modules.
 - `timeoutMs` (active time), `output` (a relative path becomes an artifact);
 - `schema` (a structured `report`);
 - `gate` (a command, or `{command, output: "json", schema, timeoutMs}`);
-- `isolation: "worktree"`, `context: "fork"`, `budget`.
+- `isolation: "worktree"`, `context: "fork"`, `budget`;
+- `writer` (`false`: the call does not write in its cwd's worktree, so it does
+  not take that worktree's writer lock; `true`: it does, whatever its tools).
 
 The result has `ok`, `status`, the full `output` text and the structured
 `data`.
@@ -177,7 +179,8 @@ The main agent is interrupted only when there is something to decide:
 - a finished workflow;
 - a stalled subagent (the alert names the command it is running and for how long, so a long silent command reads differently from a stuck call);
 - an unknown outcome;
-- two unfinished calls observed editing the same worktree (a reminder, never a block);
+- a call waiting for another call's writer lock on its worktree (once, with the holder);
+- two unfinished calls observed editing the same worktree when one of them does not take the writer lock (a reminder);
 - a reached budget.
 
 Each one arrives once. A reminder that was already resolved is shown as
@@ -239,6 +242,10 @@ pi-durable-subagents stop-all           pause every existing workflow now; journ
                                         (runs you start afterwards are not held)
 pi-durable-subagents prune [wid] [--older-than <days>]
                                         delete finished workflows (done, failed, stopped); prints count and bytes freed
+pi-durable-subagents restart [--force]  switch to the installed version (see "Updating Durable Subagents")
+pi-durable-subagents hold <resource> [--shared] [--max-wait <s>] [--note <text>] -- <command…>
+                                        run one command while holding a resource lease (see below)
+pi-durable-subagents leases [--json]    who holds and who waits for each resource
 pi-durable-subagents doctor [--json]    read-only health check; exits 1 when something needs you
 pi-durable-subagents install-service    optional: run `start` at login and every 30 s (systemd / launchd)
 pi-durable-subagents uninstall-service
@@ -259,6 +266,45 @@ never comes back. `doctor` shows disk use, workflows by status, the largest
 journals, parked work, old open questions, and leftovers; each finding
 comes with one command to fix it.
 
+### Resource leases
+
+Benchmarks, timing measurements and big builds need the machine to
+themselves. Instead of each subagent polling for an idle machine, wrap the
+command:
+
+```sh
+pi-durable-subagents hold machine -- make bench          # exclusive
+pi-durable-subagents hold machine --shared -- npm test   # with other shared holders, never with an exclusive one
+pi-durable-subagents hold machine --max-wait 600 --note "frame phase" -- ./measure.sh
+```
+
+- The lease covers one command, not a whole call: a subagent that thinks
+  or waits for an answer holds nothing.
+- Requests are served strictly in order. An exclusive request waits for
+  everything before it, and keeps later shared requests out (no starvation).
+  A waiting `hold` prints who holds the resource; `--max-wait` gives up with
+  exit 75 without running the command.
+- The command runs without a shell (write `-- sh -c '…'` for one) in its
+  own process group; signals to `hold` go to it and its exit status is
+  returned. When it exits, whatever it left in its process group is ended
+  before the lease passes on.
+- The lease lives as long as the `hold` process or its command lives, so a
+  killed `hold` does not hand the machine over while the command still
+  runs. If `hold` is killed and its command has exited, processes the
+  command left in its group still hold the lease; the next waiter ends them
+  (on macOS, a process that took over the command's pid is waited for, not
+  ended). State is one small file per request under
+  `$DSA_HOME/leases/<resource>/`; no orchestrator is needed, and the user's
+  own shell can take part.
+- Subagents find the command on their `PATH` (the orchestrator puts a shim
+  in `$DSA_HOME/bin`), and their leases are tagged with their call:
+  `status` shows `lease: machine held by <wid>/<key> …; waiting: …` and
+  `(holds lease machine)` / `(waiting for lease machine 3m)` on call lines.
+  Tell a subagent in its task to run measurements under
+  `pi-durable-subagents hold machine -- …`.
+- Leases are cooperative: processes started without `hold` are not held
+  back, and a daemon that leaves the process group is not covered.
+
 ## Configuration
 
 State lives in `~/.pi/durable-subagents`; set `DSA_HOME` to move it.
@@ -270,7 +316,8 @@ State lives in `~/.pi/durable-subagents`; set `DSA_HOME` to move it.
   "onQuit": "pause",
   "pools": { "fast": ["anthropic/claude-haiku-4-5", "openai/gpt-5-mini"] },
   "providers": { "anthropic": { "slots": 4 } },
-  "memory": { "reserveMb": 2048, "perChildMb": 300 }
+  "memory": { "reserveMb": 2048, "perChildMb": 300 },
+  "writerLock": "queue"
 }
 ```
 
@@ -287,6 +334,11 @@ State lives in `~/.pi/durable-subagents`; set `DSA_HOME` to move it.
   progress.
 - **Memory:** new subagents wait while memory is short. Running ones are
   never stopped for memory.
+- **Writer lock:** `"queue"` (default) runs one writing call per git
+  worktree (outside git: per directory) at a time; the others wait in order.
+  `"off"` lets them run together and only reminds you of edits seen in the same
+  worktree. Writes that do not go through a writing call (your own, or a
+  `writer: false` call's bash) are not constrained.
 - **onQuit:** `"pause"` (default) pauses a session's running workflows when
   you quit that pi; `"continue"` lets them run on in the background.
 - **Changes apply without a restart:** the orchestrator re-reads the file
@@ -324,23 +376,35 @@ On load, it checks the pi exports and API methods it uses.
 
 ## Updating Durable Subagents
 
-Running work stays on the version it started with: the orchestrator is not
-restarted under it. When the orchestrator runs another version than the one a
-pi session loaded, that pi says so once, and `status` shows the running
-version with a note. The orchestrator exits about 10 s after all work ends,
-and the next start runs the new version. To switch sooner without stopping
-running calls:
-
-1. `drain`: running calls finish and nothing new starts in existing
-   workflows. A call waiting for your answer still counts as running, and a
-   workflow started after the drain is not held.
-2. Wait until `status` no longer shows the old version (about 10 s after the
-   last call ends).
-3. `resume` from a pi session started after the update.
-
-A `resume` before the old orchestrator exits keeps it running the old
-version, and a pi session started before the update still starts the old
-version; start a new one.
+Running work stays on the version it started with until you restart the
+orchestrator. When the orchestrator runs another version than the one a pi
+session loaded, that pi says so once, and `status` shows the running version
+with a note. The orchestrator exits about 10 s after all work ends, and the
+next start runs the new version. To switch sooner:
+
+```sh
+pi-durable-subagents restart          # or the subagents tool: action "restart"
+```
+
+The orchestrator refuses while any execution runs (a subagent process, or a
+gate before a call's seal) and names each one with its session and age; no new
+execution starts while it decides, so nothing slips in between. Calls waiting
+for your answer (hibernated), waiting for a provider slot, or held by a drain
+do not block it. Otherwise it exits and its successor starts at once from the
+installed files and resumes every workflow: an asker keeps its question, a
+queued call launches on the new version. `restart --force` (tool:
+`force: true`) fences running executions instead of refusing; they resume on
+the new version from their sessions, like after a crash, so a tool call that
+was running is repeated or reported as interrupted.
+
+To restart only when the machine is quiet, `drain` first (running calls finish
+and nothing new starts in existing workflows), retry `restart` until it is
+accepted, then `resume`. Never kill the orchestrator process: other sessions'
+running calls would be interrupted without a check. An orchestrator from 1.0.17
+or earlier does not know the restart request; `restart` then checks the
+journals itself and ends it with SIGTERM, which is not atomic: a call launched
+in between is fenced and resumes. A pi session started before the update still
+loads the old extension; start a new one.
 
 ## What we do not promise
 

package/dist/agent/main/tool.js

@@ -2,10 +2,10 @@ import { resolve } from "node:path";
 import { Type } from "@earendil-works/pi-ai";
 import { validateCallSpec } from "../../compat/spec.js";
 import { compileFanout } from "../../compat/fanout.js";
-const stepsDoc = "Call specs {agent, task, model?, cwd?, timeoutMs?, output?, schema?, gate?, isolation?, context?, budget?, once?, tools?, skills?, key?}; " +
+const stepsDoc = "Call specs {agent, task, model?, cwd?, timeoutMs?, output?, schema?, gate?, isolation?, context?, budget?, once?, tools?, skills?, writer?, key?}; " +
     "each call is addressed as '<wid>/<key>', where key is the step's own unique key or else 'tasks:<i>' / 'chain:<i>'.";
 export const parameters = Type.Object({
-    action: Type.Optional(Type.Union(["run", "agents", "send", "stop", "revise", "status", "resume", "drain"].map(v => Type.Literal(v)))),
+    action: Type.Optional(Type.Union(["run", "agents", "send", "stop", "revise", "status", "resume", "drain", "restart"].map(v => Type.Literal(v)))),
     workflow: Type.Optional(Type.String()), source: Type.Optional(Type.String()), args: Type.Optional(Type.Unknown()),
     tasks: Type.Optional(Type.Array(Type.Any(), { description: `Parallel calls. ${stepsDoc}` })),
     chain: Type.Optional(Type.Array(Type.Any(), { description: `Sequential calls ({previous} = previous output). ${stepsDoc}` })),
@@ -20,9 +20,10 @@ export const parameters = Type.Object({
     timeoutMs: Type.Optional(Type.Number({ description: "Per-call limit on active time in milliseconds (a number). Omit unless a hard limit is needed; prefer budgets." })),
     key: Type.Optional(Type.String({ description: "A single agent/task run: the call's key. status with wid: that call's full result." })),
     full: Type.Optional(Type.Boolean({ description: "status: with wid, the complete workflow detail including every output." })),
+    force: Type.Optional(Type.Boolean({ description: "restart: fence running executions instead of refusing (they resume on the new orchestrator)." })),
 }, { additionalProperties: true });
 /** Call fields a tasks/chain run applies to every step that does not set its own. */
-export const stepDefaults = ["model", "timeoutMs", "budget", "isolation", "context", "tools", "skills", "once"];
+export const stepDefaults = ["model", "timeoutMs", "budget", "isolation", "context", "tools", "skills", "once", "writer"];
 function string(args, name) {
     if (typeof args[name] !== "string" || !args[name])
         throw new Error(`${name} is required`);
@@ -52,7 +53,7 @@ export function request(args, cwd) {
         args.chain !== undefined, args.workflow !== undefined, args.source !== undefined];
     const action = args.action === undefined && launchForms.filter(Boolean).length === 1 ? "run" : args.action;
     if (typeof action !== "string" || !action)
-        throw new Error("action is required: run, agents, send, stop, revise, status, resume, drain");
+        throw new Error("action is required: run, agents, send, stop, revise, status, resume, drain, restart");
     if (action === "run") {
         const { action: _, workflow, source, tasks, chain, args: inputs, name, usageBudget, maxCalls, inputs: files, by: _by, ...spec } = args;
         const choices = [workflow, source, tasks, chain, spec.agent === undefined && spec.task === undefined ? undefined : spec];
@@ -141,5 +142,7 @@ export function request(args, cwd) {
         return { kind: "resume", body: args.wid !== undefined ? { wid: string(args, "wid") } : typeof args.origin === "string" ? { origin: args.origin } : {} };
     if (action === "drain")
         return { kind: "drain", body: {} };
-    throw new Error(`Unsupported action: ${action}; use run, agents, send, stop, revise, status, resume, or drain`);
+    if (action === "restart")
+        return { kind: "restart", body: args.force === true ? { force: true } : {} };
+    throw new Error(`Unsupported action: ${action}; use run, agents, send, stop, revise, status, resume, drain, or restart`);
 }

package/dist/agent/main.js

@@ -15,6 +15,8 @@ import { attention, presentText, presented, resolved, unfinishedWorkflow } from
 import { isLive, pausedElsewhere, runningOrchestrator, statusBrief, statusCallDetail, statusCompactDetail, statusDetail, statusView, widOfRid } from "../orchestrator/snapshot.js";
 import { parameters, request, sendReceipt } from "./main/tool.js";
 import { discoverAgents } from "../compat/agents.js";
+import { currentOrchestrator, legacyRestart, waitExit } from "../cli/restart.js";
+import { packageVersion } from "../version.js";
 let noteSink;
 /** P16: Queue a UI note for the next boundary without waking the model. */
 export function presentNote(text) { noteSink?.(text); }
@@ -297,6 +299,20 @@ export function registerMain(pi, ui) {
         const sessionFile = ctx?.sessionManager.getSessionFile();
         if (normalized.kind === "run" && sessionFile)
             normalized.body.origin = { sessionFile, leafId: ctx.sessionManager.getLeafId() };
+        if (normalized.kind === "restart") {
+            // Only an orchestrator that decides restarts is sent one (an older one would keep it as an invalid inbox file).
+            const previous = currentOrchestrator(home), force = args.force === true;
+            if (!previous)
+                return { applied: true, note: "no orchestrator is running; the next one starts on the installed version when work is submitted" };
+            if (!previous.restart) {
+                const legacy = legacyRestart(home, previous, force);
+                if (!legacy.applied)
+                    return { applied: false, reason: legacy.reason };
+                // It does not start its successor; this session does once it has exited (or its next periodic check would).
+                void waitExit(previous, 60_000).then(exited => exited ? serial(() => starter()) : undefined).catch(() => { });
+                return { applied: true, note: restartNote(previous) };
+            }
+        }
         const sent = await serial(async () => {
             if (!outbox || stopped)
                 throw new Error("Main session is not active");
@@ -330,6 +346,7 @@ export function registerMain(pi, ui) {
         }
         return { submitted: { rid: sent.rid } };
     }
+    const restartNote = (previous) => `orchestrator ${previous.version} (pid ${previous.pid}) exits; the installed version (this pi loaded ${packageVersion()}) starts in its place and resumes every workflow`;
     ui?.(pi, { home, presentNote, submit: args => submit({ ...args, by: "user" }, ctx?.cwd ?? process.cwd(), undefined, false) });
     // The model must name a real agent; list the ones this project can use (names are checked again per run).
     let agents = "";
@@ -343,7 +360,7 @@ export function registerMain(pi, ui) {
             "run (action optional for exactly one launch form): agent+task; tasks:[call specs] parallel; chain:[call specs] sequential ({previous}); workflow:'./script.js' or source (runs.run(key,spec), runs.all([...]), emit(value), args, runs.input(name)). Optional name, cwd, usageBudget, maxCalls, inputs. With tasks/chain, top-level model, timeoutMs, budget, isolation, context, tools, skills, once are defaults for every step (a step's own value wins); a workflow/source script sets them per runs.run call. timeoutMs is milliseconds of active time (a number); omit it unless a hard limit is needed. Explicit unknown agents are rejected BEFORE creation, with available names; unknown script agents fail only their call.",
             "agents: list names, descriptions, default models and source for this cwd; use these names for run.",
             "send to:'<wid>/<key>' (bare '<wid>' only for a single-call workflow): steer on a running call delivers at the next safe point (receipt in status/UI); a steer to a call waiting on its question interrupts the question and the subagent usually asks again — use answer to answer it; sealed → finished:<status> — use kind 'follow-up'. follow-up continues a sealed call as generation g+1 or queues after a running turn; follow-up model:'provider/id' or a pool name runs that generation on it. answer: give the qid (or just the call, or nothing when one question is open); to and rev are filled in. A question that needs the user's decision goes to the user; if you answer one yourself, tell the user what you chose. model ('provider/id' or a pool name — its first model not used up): a running call switches at its next provider request; an asking, hibernated or queued call launches on it when it runs again; the reply's model/effect (next-request|next-execution|next-generation) says which. status model = model actually used by the last request; switching = requested, not used yet; switchFailed = refused. A provider content refusal (ToS/usage policy) fails the call at once, not retried. Unknown targets list valid addresses. replaces:[rid] supersedes an earlier send.",
-            "stop target:<wid|<wid>/<key>> is terminal stopped (usage and partial edits kept); a sealed call → already-sealed:<status>, a finished workflow → terminal:<status>. drain holds existing workflows reversibly (new runs unaffected); resume [wid] releases held workflows. status: without wid, what runs, asks (with its answer address; hibernated:true holds no slot) or failed, sharedWorktree names calls sharing observed edit/write roots (reminder only), finished workflows one line each, provider slots held/limit, the config in effect and providers whose usage window is used up (avoided until a probe finds them answering again), and the orchestrator version (versionNote when it differs from the loaded one); wid: one workflow, outputs clipped; wid+key: one call's full result; full:true: everything. A run's rid from {submitted:{rid}} works wherever a wid is expected. revise wid + workflow/source/args starts a revision.",
+            "stop target:<wid|<wid>/<key>> is terminal stopped (usage and partial edits kept); a sealed call → already-sealed:<status>, a finished workflow → terminal:<status>. drain holds existing workflows reversibly (new runs unaffected); resume [wid] releases held workflows. restart (after an update) replaces the orchestrator with the installed version: refused with busy:<running executions> while any runs, unless force:true (they are fenced and resume); hibernated askers and queued calls do not block it. Never kill the orchestrator process. Commands that need the machine (benchmarks, timing) take a lease: tell the subagent to run them as `pi-durable-subagents hold machine [--shared] -- <command>` (FIFO; status lists lease holders and waiters). status: without wid, what runs, asks (with its answer address; hibernated:true holds no slot) or failed, writerWait: a call queued for its git worktree's writer lock (one call whose tools include edit/write runs per worktree; spec writer:false or isolation:'worktree' opts out), sharedWorktree names calls sharing observed edit/write roots (reminder), lease: a call holding or waiting for a resource lease, finished workflows one line each, provider slots held/limit, the config in effect and providers whose usage window is used up (avoided until a probe finds them answering again), and the orchestrator version (versionNote when it differs from the loaded one); wid: one workflow, outputs clipped; wid+key: one call's full result; full:true: everything. A run's rid from {submitted:{rid}} works wherever a wid is expected. revise wid + workflow/source/args starts a revision.",
             "Control replies are {applied:true,rid} or {applied:false,reason,rid} when decided; otherwise {submitted:{rid}} after 10s.",
             ...(agents ? [`Available agents: ${agents}.`] : []),
             "User sees a summary line above the editor; ↓ on an empty editor (or /subagents) opens the list, Enter watches live OR finished calls (finished transcripts remain on disk) and expands finished workflows. List keys: s steer (paste-capable input), x stop (confirm y), m model, a answer when asked, f follow-up on finished calls; action feedback appears in footer.",

package/dist/cli/control.js

@@ -103,6 +103,10 @@ export async function submit(home, command, target, env = process.env, options =
                 const body = { ...(target ? { wid: target } : {}), ...(options.olderThanDays !== undefined ? { olderThanDays: options.olderThanDays } : {}) };
                 requests.push(await outbox.send("orch", "prune", body));
             }
+            else if (command === "restart") {
+                const body = options.force ? { force: true } : {};
+                requests.push(await outbox.send("orch", "restart", body));
+            }
             else
                 requests.push(await outbox.send("orch", command, command === "stop" ? { target } : command === "resume" && target ? { wid: target } : {}));
             // Publish first: even a starter failure leaves a recoverable request and no idle-exit race.

package/dist/cli/hold.js

@@ -0,0 +1,184 @@
+// `pi-durable-subagents hold <resource> [--shared] [--max-wait <s>] [--note <text>] -- <command> [args…]`
+// Waits for the lease (strict FIFO), runs the command in its own process group, ends what the command left in that
+// group, then releases. See src/platform/lease.ts for the ticket protocol.
+import { spawn } from "node:child_process";
+import { watch } from "node:fs";
+import { constants } from "node:os";
+import { dsaHome } from "../paths.js";
+import { captureStart } from "../platform/proctable.js";
+import { blockers, enqueue, groupAlive, leaseDir, liveTickets, orphaned, removeTicket, RESOURCE, who, writeTicket } from "../platform/lease.js";
+export const HOLD_USAGE = "usage: pi-durable-subagents hold <resource> [--shared] [--max-wait <seconds>] [--note <text>] -- <command> [args…]";
+/** Exit status when --max-wait expires before the lease is granted (EX_TEMPFAIL). */
+export const WAIT_EXPIRED = 75;
+export function parseHold(args) {
+    const split = args.indexOf("--");
+    if (split < 0)
+        throw new Error(`hold needs -- before the command. ${HOLD_USAGE}`);
+    const opts = args.slice(0, split), argv = args.slice(split + 1);
+    let resource, mode = "exclusive", maxWaitMs, note;
+    for (let i = 0; i < opts.length; i++) {
+        const a = opts[i];
+        if (a === "--shared")
+            mode = "shared";
+        else if (a === "--max-wait" || a === "--note") {
+            const v = opts[++i];
+            if (v === undefined)
+                throw new Error(`${a} needs a value. ${HOLD_USAGE}`);
+            if (a === "--note")
+                note = v;
+            else {
+                const s = Number(v);
+                if (!Number.isFinite(s) || s < 0)
+                    throw new Error(`--max-wait must be a number of seconds ≥ 0. ${HOLD_USAGE}`);
+                maxWaitMs = s * 1000;
+            }
+        }
+        else if (a.startsWith("-"))
+            throw new Error(`Unknown option ${a}. ${HOLD_USAGE}`);
+        else if (resource === undefined)
+            resource = a;
+        else
+            throw new Error(`Unexpected argument ${a}. ${HOLD_USAGE}`);
+    }
+    if (!resource)
+        throw new Error(`hold needs a resource name. ${HOLD_USAGE}`);
+    if (!RESOURCE.test(resource))
+        throw new Error(`Invalid resource ${JSON.stringify(resource)}: use 1–64 of A-Z a-z 0-9 . _ -`);
+    if (!argv.length)
+        throw new Error(`hold needs a command after --. ${HOLD_USAGE}`);
+    return { resource, mode, ...(maxWaitMs !== undefined ? { maxWaitMs } : {}), ...(note !== undefined ? { note } : {}), argv };
+}
+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 SIGNALS = ["SIGINT", "SIGTERM", "SIGHUP"];
+/** Run one held command; resolves to the exit status for the process. */
+export async function hold(args, options = {}) {
+    const env = options.env ?? process.env, home = dsaHome(env), say = options.stderr ?? (l => process.stderr.write(`${l}\n`));
+    const pollMs = options.pollMs ?? 250, graceMs = options.graceMs ?? 2000;
+    const ticket = await enqueue(home, {
+        resource: args.resource, mode: args.mode,
+        wrapper: { pid: process.pid, start: (await captureStart(process.pid)) || undefined },
+        argv: args.argv.map(a => a.length > 200 ? `${a.slice(0, 199)}…` : a).slice(0, 32), cwd: process.cwd(),
+        ...(args.note ? { note: args.note.slice(0, 300) } : {}), since: Date.now(),
+        ...(env.DSA_EXEC ? { exec: env.DSA_EXEC } : {}), ...(env.DSA_CALL ? { call: env.DSA_CALL } : {}),
+    });
+    // Signals: while waiting they withdraw the request; while the command runs they go to its process group.
+    let child, interrupted, wake = () => { };
+    const onSignal = (signal) => {
+        if (child?.pid) {
+            try {
+                process.kill(-child.pid, signal);
+            }
+            catch { /* gone */ }
+        }
+        else {
+            interrupted = signal;
+            wake();
+        }
+    };
+    for (const s of SIGNALS)
+        process.on(s, onSignal);
+    let watcher;
+    try {
+        // Wait in order.
+        const deadline = args.maxWaitMs !== undefined ? ticket.since + args.maxWaitMs : undefined;
+        try {
+            watcher = watch(leaseDir(home, args.resource), () => wake());
+            watcher.on("error", () => { });
+        }
+        catch { /* polling suffices */ }
+        let shown;
+        const ended = new Map();
+        for (;;) {
+            if (interrupted) {
+                removeTicket(home, ticket);
+                return 128 + (constants.signals[interrupted] ?? 1);
+            }
+            const ahead = blockers(ticket, liveTickets(home, args.resource));
+            if (!ahead.length)
+                break;
+            const now = Date.now();
+            // A holder whose wrapper was killed after its command ended can leave processes in the command's group; the
+            // wrapper would have ended them before releasing, so a waiter does: TERM, then KILL after the grace period.
+            for (const t of ahead.filter(orphaned)) {
+                const first = ended.get(t.seq);
+                if (first === undefined)
+                    say(`hold: ending processes left by ${who(t)} (its hold process is gone)`);
+                try {
+                    process.kill(-t.command.pid, first !== undefined && now - first >= graceMs ? "SIGKILL" : "SIGTERM");
+                }
+                catch { /* gone */ }
+                if (first === undefined)
+                    ended.set(t.seq, now);
+            }
+            if (deadline !== undefined && now >= deadline) {
+                removeTicket(home, ticket);
+                say(`hold: ${args.resource} still held by ${ahead.filter(t => t.grantedAt !== undefined).map(who).join(", ") || who(ahead[0])} after ${age(now - ticket.since)}; not running the command (exit ${WAIT_EXPIRED})`);
+                return WAIT_EXPIRED;
+            }
+            const holders = ahead.filter(t => t.grantedAt !== undefined), key = holders.map(t => t.seq).join(",") || `q${ahead[0].seq}`;
+            if (key !== shown) {
+                shown = key;
+                const by = holders.length ? holders.map(t => `${who(t)} (${t.mode}, ${age(now - (t.grantedAt ?? t.since))})`).join(", ") : `${who(ahead[0])} (waiting)`;
+                say(`hold: waiting for ${args.resource} (${args.mode}) — held by ${by}; ${ahead.length} ahead`);
+            }
+            await new Promise(resolve => { const timer = setTimeout(resolve, pollMs); wake = () => { clearTimeout(timer); resolve(); }; });
+        }
+        watcher?.close();
+        watcher = undefined;
+        ticket.grantedAt = Date.now();
+        await writeTicket(home, ticket);
+        if (interrupted) {
+            removeTicket(home, ticket);
+            return 128 + (constants.signals[interrupted] ?? 1);
+        }
+        if (shown)
+            say(`hold: ${args.resource} granted after ${age(ticket.grantedAt - ticket.since)}`);
+        // Run. stdin stays attached only when it is not a terminal: a background process group reading the terminal stops.
+        const c = spawn(args.argv[0], args.argv.slice(1), { stdio: [process.stdin.isTTY ? "ignore" : "inherit", "inherit", "inherit"], detached: true, env });
+        child = c;
+        const exit = new Promise(resolve => {
+            c.once("error", error => { say(`hold: cannot run ${args.argv[0]}: ${error.message}`); resolve(127); });
+            c.once("exit", (code, signal) => resolve(code ?? 128 + (signal ? constants.signals[signal] ?? 1 : 1)));
+        });
+        if (c.pid) {
+            ticket.command = { pid: c.pid, start: (await captureStart(c.pid)) || undefined };
+            await writeTicket(home, ticket).catch(() => { });
+        }
+        const status = await exit;
+        // End what the command left behind in its group before the lease goes to the next holder.
+        if (c.pid && groupAlive(c.pid)) {
+            try {
+                process.kill(-c.pid, "SIGTERM");
+            }
+            catch { /* gone */ }
+            const until = Date.now() + graceMs;
+            while (groupAlive(c.pid) && Date.now() < until)
+                await new Promise(r => setTimeout(r, 50));
+            if (groupAlive(c.pid)) {
+                try {
+                    process.kill(-c.pid, "SIGKILL");
+                }
+                catch { /* gone */ }
+            }
+            for (let i = 0; i < 40 && groupAlive(c.pid); i++)
+                await new Promise(r => setTimeout(r, 25));
+        }
+        // A /proc listing is not atomic (a member can fork and exit while it is read): a last group signal ends any member
+        // the checks missed, a newborn included. The group id is still ours while it has members.
+        if (c.pid) {
+            try {
+                process.kill(-c.pid, "SIGKILL");
+            }
+            catch { /* gone */ }
+        }
+        removeTicket(home, ticket);
+        return status;
+    }
+    finally {
+        watcher?.close();
+        for (const s of SIGNALS)
+            process.off(s, onSignal);
+    }
+}
+/** `leases [--json]`. */
+export { leaseLines, leaseState } from "../platform/lease.js";