pi-durable-subagents 1.0.19 → 1.0.21

package/CHANGELOG.md

@@ -1,5 +1,45 @@
 # Changelog
 
+## 1.0.21
+
+1.0.20 was not published; its changes ship in this release.
+
+- Programs can name requests: `run`, `send` and `stop` take `--request <id>`
+  (CLI) or `request` (the `subagents` tool). A retry with the same id and the
+  same content gets the first outcome and never starts a second workflow or
+  follow-up; other content under the id is a `request-conflict` and sends
+  nothing. Exit codes: 0 applied, 1 rejected, 3 conflict, 75 not decided yet
+  (retry with the same id). `describe --key <id>` (or a wid) reports the
+  state, open questions and every call's output in full, what live calls
+  wait for and why their last execution was fenced. A pruned workflow leaves
+  a tombstone with its final status, request id and digest. See "Driving dsa
+  from a program" in the README.
+- A forced restart needs the user's approval in a checkable form: a refused
+  `restart` lists the running executions grouped by session (with held
+  leases) and a token; `restart --force <token> --reason <text>` fences
+  exactly that set and is refused again if it changed. A subagent cannot
+  force a restart. The ledger records who forced it and why, and `status`
+  shows it for 24 hours.
+- An asker cut off by a restart or crash before its planned hibernation no
+  longer loses its question: it hibernates and resumes with the answer
+  (also an answer given while dsa restarted), and a `once` step waiting for
+  an answer no longer ends as `unknown`.
+- A workflow's done notice names a follow-up still going (queued or running)
+  instead of calling it `unknown`.
+- Orchestrator starts are fast again. Each start re-parsed every workflow's
+  staged snapshot (tens of megabytes each when it holds a forked parent
+  session) before handling any request, so a restart stalled all work for
+  over a minute. A verified `pins.json` record per revision now replaces that
+  work: on a copy of a home with 117 workflows, recovery takes about 6 s
+  instead of 80 s. The first start after the update builds the records once.
+  A record that does not verify falls back to the snapshot, so a changed
+  pinned file is still reported as a conflict.
+- `restart` no longer reports a failure while the orchestrator is still
+  recovering: it says the request is submitted and keeps waiting (up to 10
+  minutes), then exits 75 with "still pending — do not resubmit" if no
+  orchestrator reached it. After the restart it waits for the orchestrator
+  that actually decided it.
+
 ## 1.0.19
 
 - The orchestrator no longer keeps every workflow's pinned origin branch (the

package/README.md

@@ -57,7 +57,9 @@ the npx cache, so `install-service` refuses to run from there.
 | 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 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. |
+| A subagent waits for an answer for a long time | It releases its model slot and memory, then resumes exactly once when you answer. The question survives orchestrator restarts (also forced ones) and crashes, including one that hits before the subagent released its slot. |
+| A subagent's work ends (finished, stopped, or cut off) | Every process its tools started ends with that execution, also ones started with `nohup`, `setsid` or `&`: they carry the execution's tag (see the limit below). Anything that must outlive the subagent has to be started by you or the parent session. A command run under `hold` is no exception: a forced restart stops it and its lease is released. |
+| A subagent runs in a worktree you made (`isolation: "none"`, the default, with `cwd`) | Durable Subagents never creates, cleans, moves or deletes that directory or its branch, also not on `prune`; `prune` deletes only its own state and the worktrees it created for `isolation: "worktree"`. |
 
 ## Use it
 
@@ -238,11 +240,18 @@ pi-durable-subagents start              start the orchestrator if work is pendin
 pi-durable-subagents resume [wid]       continue unfinished or parked work (undoes drain / stop-all)
 pi-durable-subagents drain              hold existing workflows: running calls finish, nothing new starts in them
 pi-durable-subagents stop <wid|call>
+pi-durable-subagents run --request <id> --spec <file|-> [--cwd <dir>] [--json] [--wait-ms <n>]
+                                        start a run under a caller-chosen id; safe to retry (see below)
+pi-durable-subagents send --request <id> --to <run-id|wid/key> --kind follow-up|answer|steer|model
+                         [--call <key>] [--qid <qid> --rev <n>] --message <text|@file> [--model <m>] [--json]
+pi-durable-subagents stop --request <id> <run-id|wid|wid/key|call> [--json]
+pi-durable-subagents describe --key <run-id> | <wid> [--json]
+                                        full read-only state of one run (never starts the orchestrator)
 pi-durable-subagents stop-all           pause every existing workflow now; journals stay resumable
                                         (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 restart [--force <token> --reason <text>]  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
@@ -255,6 +264,67 @@ The service only runs `start`: it never resumes work you drained or
 stopped. Install the CLI globally (`npm i -g pi-durable-subagents`) before
 `install-service`.
 
+### Driving dsa from a program
+
+A program (a CI job, a script, another agent) should name its requests with
+`--request <id>`: 1–124 characters `[A-Za-z0-9][A-Za-z0-9._:-]*`, unique per
+`DSA_HOME` across `run`, `send` and `stop`. The id is the identity: the first
+submission under an id is decided once and every retry with **the same
+content** gets that first outcome; a retry never starts a second workflow or
+a second follow-up. The run id is also the workflow key: `send --to <run-id>`
+and `describe --key <run-id>` find the workflow without knowing its wid.
+
+The content is hashed into `spec_digest` (the request kind, its body and, for
+answers, the question id and revision). Persist the exact spec bytes you
+submit and retry with those bytes: the run's `cwd` is part of the content
+(`spec.cwd`, else `--cwd`, else the current directory, made absolute), so
+retry from the same place or pass it explicitly. The `spec` file is the
+`subagents` tool's run form (`{agent, task, model?, schema?, …}` or
+`{tasks: […], name?, usageBudget?, maxCalls?}`); `context: "fork"` needs a pi
+session and is rejected.
+
+| exit | meaning | `--json` reply |
+| --- | --- | --- |
+| 0 | decided and applied (a retry gets the same answer) | run: `{request, wid, created, spec_digest}`; send/stop: `{request, applied, generation?, call?, spec_digest}` |
+| 1 | decided and rejected (`reason`), or a usage error | `{request, applied: false, reason, spec_digest}` |
+| 3 | `request-conflict`: the id already names other content; nothing was sent | `{request, error, wid?, spec_digest, state}` (the original's digest and state) |
+| 75 | not decided yet: submitted but undecided in `--wait-ms` (default 60 s), submitted and then a later step failed (`reason` says which), or a lock was busy (`reason: "busy"`); retry with the same id | `{request, pending: true, reason?}` |
+
+`created` is false when the id had already been decided before the command
+ran. A conflicting id stays conflicting forever, also after `prune`: the
+tombstone keeps the final status, the id and the digest. Any sender's retry
+completes a submission another one recorded but did not publish (it died in
+between), so a retry with the same content always converges.
+
+From the `subagents` tool, `request` works the same, with one difference: a
+run's origin session (what `context: "fork"` copies, and where notices go) is
+not part of the digest. A retry of the same id from another session therefore
+gets the first session's workflow, its notices and its forked context. A
+retried answer may leave out `to`, `qid` and `rev`: it addresses the question
+the first attempt answered.
+
+`describe` reports one of `absent` (never seen), `pending` (submitted, not
+decided — typically no orchestrator is running; `start` or a retry starts it),
+`rejected` (with `reason`), `running`, `asking` (open questions with their
+full text, `qid`, `rev` and the `to` address to answer), `sealed` (finished:
+`status` plus every call's unclipped `output`, `error` and schema `data`) or
+`pruned` (`pruned: {status, endedAt}`; workflows pruned before 1.0.21 have
+only `endedAt`), with `wid`, `request` and
+`spec_digest`. Live calls also show what they wait for (slot, writer lock,
+lease, exhausted provider) and the last fence of their execution
+(`lastFence: {at, exec, reason}`); the reason is a best-effort reading of the
+journals: `restart-force` when a forced restart listed the execution,
+`orchestrator-crash` when the orchestrator died uncleanly while it ran, else
+`process-died`.
+
+```sh
+pi-durable-subagents run --request build-42 --spec build-42.json --json
+# exit 75: retry later with the same id and bytes
+pi-durable-subagents describe --key build-42 --json
+pi-durable-subagents send --request build-42-a1 --to build-42 --kind answer \
+  --qid <qid> --rev <rev> --message "yes"
+```
+
 ### Housekeeping
 
 Journals are never compacted, so state only grows. `prune` removes finished
@@ -387,23 +457,45 @@ 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
+gate before a call's seal). The refusal groups executions by session with ages,
+lease annotations and a token for that exact set; 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.
+queued call launches on the new version.
+
+To interrupt those executions deliberately, first show the user the refusal's
+list and obtain their explicit approval, then use its token and a non-empty
+reason (at most 500 characters):
+
+```sh
+pi-durable-subagents restart --force <token> --reason "<why>"
+# tool: {action:"restart", force:"<token>", reason:"<why>"}
+```
+
+A changed execution set is refused with a fresh list and token. With no live
+executions no token is needed. Bare force cannot fence live executions, and the
+tool rejects `force:true`. Subagents cannot force a restart, even from bash:
+it would fence themselves and other sessions' work. Force fences running
+executions; 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.
+The restart ledger records the reason and initiator; after the next start,
+`status` shows who forced it and why for 24 hours.
+
+An orchestrator reads requests only after it has recovered its workflows, so
+a `restart` sent to one that just started waits for it (and says so); if no
+orchestrator reaches the request in time, `restart` exits 75 and the request
+stays pending — it is decided later, so do not send another.
 
 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
+journals itself with the same token, reason and subagent checks and ends it with
+SIGTERM, which is not atomic: a call launched in between is fenced and resumes.
+The old orchestrator cannot record the new audit fields. A pi session started before the update still
 loads the old extension; start a new one.
 
 ## What we do not promise
@@ -419,8 +511,15 @@ loads the old extension; start a new one.
   "outcome unknown" notice; other work keeps running.
 - A tool that already ran inside a subagent may run again after a crash, if
   its result never reached the session. Make external side effects
-  idempotent, or mark the step `once: true` (it then stops as `unknown`
-  instead of repeating).
+  idempotent, or mark the step `once: true`: when an execution is cut off
+  while a tool call is running (its result never arrived), the step then
+  ends as `unknown` instead of repeating it. Cut off between tool calls, a
+  `once` step continues like any other (nothing was left half done). A
+  step cut off while its only unfinished tool call is the question it asked
+  is not `unknown` either: it keeps waiting and resumes with the answer, also
+  an answer given while dsa restarted. If it was cut off while another tool
+  call ran beside the question, a `once` step still ends as `unknown`. A follow-up on an `unknown` step continues the
+  same session as its next generation.
 - After a crash, the model call that was in flight is paid for again.
 - Process containment uses process tags plus a 1-second tracker. A process
   that clears its tag and leaves the process tree within its first second

package/dist/agent/main/tool.js

@@ -1,3 +1,4 @@
+import { restartInputError } from "../../orchestrator/restart.js";
 import { resolve } from "node:path";
 import { Type } from "@earendil-works/pi-ai";
 import { validateCallSpec } from "../../compat/spec.js";
@@ -20,7 +21,9 @@ 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)." })),
+    force: Type.Optional(Type.Union([Type.String(), Type.Boolean()], { description: "restart: the token shown by a refusal. Show the user the list and obtain explicit approval first; boolean true is refused. Subagents cannot force a restart." })),
+    reason: Type.Optional(Type.String({ description: "restart: non-empty reason, at most 500 characters; required with force." })),
+    request: Type.Optional(Type.String({ description: "run/send/stop: your own request id (1-124 chars [A-Za-z0-9][A-Za-z0-9._:-]*) making a retry safe: the same id with the same content gets the first outcome; other content is refused (request-conflict)." })),
 }, { 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", "writer"];
@@ -39,6 +42,16 @@ function call(value, cwd, where) {
         spec.cwd = resolve(cwd, spec.cwd);
     return spec;
 }
+/** v12 §2: Reject unknown explicit call agents before starter or outbox publication; scripts remain call-local. Shared by
+ *  the tool and the CLI `run --request` (R2). */
+export function checkAgents(body, available) {
+    const names = [...(body.call ? [body.call] : []), ...(body.tasks ?? []), ...(body.chain ?? [])].map(call => call.agent);
+    if (!names.length)
+        return;
+    const known = available(), unknown = [...new Set(names.filter(name => !known.includes(name)))];
+    if (unknown.length)
+        throw new Error(`Unknown agent${unknown.length === 1 ? "" : "s"}: ${unknown.join(", ")}. Available agents: ${known.join(", ") || "(none)"}`);
+}
 /** v12 §2: Infer unambiguous runs and normalize controls into unchanged wire bodies. */
 /** P12: a send naming a model is answered with that model and when it applies — `next-request` (a running call switches
  *  at its next provider request), `next-execution` (a call with no live execution launches on it) or `next-generation`
@@ -55,7 +68,7 @@ export function request(args, cwd) {
     if (typeof action !== "string" || !action)
         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 { action: _, workflow, source, tasks, chain, args: inputs, name, usageBudget, maxCalls, inputs: files, by: _by, request: _request, ...spec } = args;
         const choices = [workflow, source, tasks, chain, spec.agent === undefined && spec.task === undefined ? undefined : spec];
         if (choices.filter(v => v !== undefined).length !== 1)
             throw new Error("run requires exactly one of workflow, source, tasks, chain, or agent/task");
@@ -142,7 +155,16 @@ 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: {} };
-    if (action === "restart")
-        return { kind: "restart", body: args.force === true ? { force: true } : {} };
+    if (action === "restart") {
+        if (args.force === true)
+            throw new Error('force:true is refused; show the user the running executions from a restart refusal, then use force:"<token>" and reason:"<why>" only with explicit user approval');
+        if (args.force !== undefined && args.force !== false && typeof args.force !== "string")
+            throw new Error("force must be the token from a refused restart");
+        const body = { ...(typeof args.force === "string" ? { token: args.force } : {}), ...(args.reason !== undefined ? { reason: args.reason } : {}) };
+        const invalid = restartInputError(body);
+        if (invalid)
+            throw new Error(invalid);
+        return { kind: "restart", body };
+    }
     throw new Error(`Unsupported action: ${action}; use run, agents, send, stop, revise, status, resume, drain, or restart`);
 }

package/dist/agent/main.js

@@ -13,8 +13,10 @@ import { dsaHome, orchInbox, orchLedger, orchLock, outboxRoot } from "../paths.j
 import { CT, JT } from "../types.js";
 import { attention, presentText, presented, resolved, unfinishedWorkflow } from "./main/snapshots.js";
 import { isLive, pausedElsewhere, runningOrchestrator, statusBrief, statusCallDetail, statusCompactDetail, statusDetail, statusView, widOfRid } from "../orchestrator/snapshot.js";
-import { parameters, request, sendReceipt } from "./main/tool.js";
+import { checkAgents, parameters, request, sendReceipt } from "./main/tool.js";
+import { findRequest, requestRid, sendIdentified } from "../requests.js";
 import { discoverAgents } from "../compat/agents.js";
+import { restartInputError } from "../orchestrator/restart.js";
 import { currentOrchestrator, legacyRestart, waitExit } from "../cli/restart.js";
 import { packageVersion } from "../version.js";
 let noteSink;
@@ -40,6 +42,7 @@ function quitPolicy(home) {
         return "pause";
     }
 }
+const REQUEST_USE = "request is a string id for run, send or stop (not combined with replaces)";
 export function registerMain(pi, ui) {
     const home = dsaHome();
     let ctx, sender = "", outbox;
@@ -261,6 +264,8 @@ export function registerMain(pi, ui) {
         for (const field of ["wid", "to", "target"])
             if (typeof args[field] === "string")
                 args = { ...args, [field]: ridToWid(args[field]) };
+        if (args.request !== undefined && (args.action === "status" || args.action === "agents"))
+            throw new Error(REQUEST_USE);
         if (args.action === "status") {
             if (typeof args.wid !== "string" || !args.wid)
                 return statusBrief(home, { origin: sender });
@@ -278,34 +283,41 @@ export function registerMain(pi, ui) {
             const { target, ...rest } = args;
             args = { ...rest, to: target };
         }
+        // A retried answer addresses the question the first attempt resolved (it may be closed by now), like the CLI.
+        if (args.action === "send" && args.kind === "answer" && typeof args.request === "string" && (args.qid === undefined || args.rev === undefined)) {
+            const prior = (await findRequest(home, requestRid(args.request)))?.request, body = prior?.body;
+            if (prior?.kind === "send" && body?.kind === "answer" && typeof body.to === "string" && prior.cond?.qid !== undefined &&
+                (args.to === undefined || args.to === body.to) && (args.qid === undefined || args.qid === prior.cond.qid))
+                args = { ...args, to: body.to, qid: prior.cond.qid, rev: args.rev ?? prior.cond.rev };
+        }
         if (args.action === "send")
             args = completeSend(args);
         // A session resumes its own held work (what its quit paused); the CLI `resume` remains the global one.
         if (args.action === "resume" && args.wid === undefined)
             args = { ...args, origin: sender };
         const normalized = request(args, cwd);
-        if (normalized.kind === "run") {
-            const body = normalized.body;
-            // v12 §2: Reject unknown explicit call agents before starter or outbox publication; scripts remain call-local.
-            const names = [...(body.call ? [body.call] : []), ...(body.tasks ?? []), ...(body.chain ?? [])].map(call => call.agent);
-            if (names.length) {
-                const available = agentsAt(cwd).map(agent => agent.name);
-                const unknown = [...new Set(names.filter(name => !available.includes(name)))];
-                if (unknown.length)
-                    throw new Error(`Unknown agent${unknown.length === 1 ? "" : "s"}: ${unknown.join(", ")}. Available agents: ${available.join(", ") || "(none)"}`);
-            }
-        }
+        // R1: a caller-chosen request id names a run, send or stop; a retry with the same content gets the first outcome.
+        if (args.request !== undefined && (typeof args.request !== "string" || !["run", "send", "stop"].includes(normalized.kind) || normalized.replaces?.length))
+            throw new Error(REQUEST_USE);
+        const rid = typeof args.request === "string" ? requestRid(args.request) : undefined;
+        if (normalized.kind === "run")
+            checkAgents(normalized.body, () => agentsAt(cwd).map(agent => agent.name));
         // P33: any call of the run may fork the origin context, so the origin branch is always offered for pinning.
         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;
+            const body = normalized.body;
+            body.initiator = process.env.DSA_CALL ? { call: process.env.DSA_CALL } : { origin: sender };
+            const invalid = restartInputError(body, process.env.DSA_EXEC !== undefined);
+            if (invalid)
+                return { applied: false, reason: invalid };
+            const previous = currentOrchestrator(home);
             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);
+                const legacy = legacyRestart(home, previous, body, { subagent: process.env.DSA_EXEC !== undefined, tool: true });
                 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).
@@ -313,7 +325,7 @@ export function registerMain(pi, ui) {
                 return { applied: true, note: restartNote(previous) };
             }
         }
-        const sent = await serial(async () => {
+        const outcome = await serial(async () => {
             if (!outbox || stopped)
                 throw new Error("Main session is not active");
             signal?.throwIfAborted();
@@ -322,8 +334,16 @@ export function registerMain(pi, ui) {
                 const withdrawn = await outbox.send("orch", "withdraw", { rids: normalized.replaces });
                 normalized.cond = { ...normalized.cond, after: withdrawn.rid };
             }
+            if (rid)
+                return sendIdentified(home, outbox, sender, rid, normalized.kind, normalized.body, normalized.cond);
             return outbox.send("orch", normalized.kind, normalized.body, normalized.cond);
         });
+        if ("conflict" in outcome) {
+            const created = ledger().find(e => e.type === JT.created && e.rid === rid);
+            return { applied: false, reason: "request-conflict", request: args.request, spec_digest: outcome.digest, ...(created ? { wid: created.wid } : {}),
+                note: "this request id was used for different content; use a new id" };
+        }
+        const sent = "digest" in outcome ? outcome.request : outcome;
         // P25: run waits for `created`; control requests wait for their terminal lifecycle record (applied or rejected+reason).
         const deadline = performance.now() + 10_000;
         while (wait || sent.kind === "run") {
@@ -360,7 +380,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. 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.",
+            "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. Never force without the user's explicit approval: show the user the refusal's list first, then supply force:'<token>' and reason. Subagents cannot force; 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

@@ -10,7 +10,10 @@ import { reduceLifecycle } from "../kernel/lifecycle.js";
 import { OsLock } from "../platform/lock.js";
 import { orchInbox, orchLedger, orchLock, outboxRoot } from "../paths.js";
 import { unfinishedWorkflow } from "../agent/main/snapshots.js";
+import { cliInitiator } from "./restart.js";
+import { restartInputError } from "../orchestrator/restart.js";
 import { JT } from "../types.js";
+import { RequestsBusy, sendIdentified } from "../requests.js";
 /** P1: Start the detached orchestrator only after probing its OS lock. */
 export async function startOrchestrator(home, env) {
     const lock = await new OsLock().tryAcquire(orchLock(home));
@@ -73,10 +76,47 @@ export async function resolution(home, rid, timeoutMs, interval = 100) {
         await delay(interval);
     }
 }
-/** P5, P38: Serialize the stable CLI sender across processes and recover its durable outbox. */
+/** P5, P38: Send one control request through the CLI sender, then start the orchestrator. */
 export async function submit(home, command, target, env = process.env, options = {}) {
     if (command === "stop" && !target)
         throw new Error("stop requires a workflow or call id");
+    return withSender(home, async (outbox) => {
+        const requests = [];
+        if (command === "stop-all") {
+            const body = { fence: true };
+            requests.push(await outbox.send("orch", "drain", body));
+        }
+        else if (command === "prune") {
+            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.restart, initiator: cliInitiator(env) };
+            const invalid = restartInputError(body, env.DSA_EXEC !== undefined);
+            if (invalid)
+                throw new Error(invalid);
+            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.
+        await startOrchestrator(home, env);
+        return requests;
+    });
+}
+/** R1: Submit a request named by a caller-chosen id through the CLI sender: a retry with the same content republishes
+ *  (or reuses) the recorded envelope, other content is a conflict and publishes nothing. Starts the orchestrator
+ *  unless the request conflicts. */
+export async function submitIdentified(home, rid, kind, body, cond, env = process.env, starter = startOrchestrator) {
+    return withSender(home, async (outbox, sender) => {
+        const result = await sendIdentified(home, outbox, sender, rid, kind, body, cond);
+        if ("request" in result)
+            await starter(home, env);
+        return result;
+    });
+}
+/** P5, P38: Serialize the stable CLI sender across processes and recover its durable outbox. */
+async function withSender(home, fn) {
     await mkdir(home, { recursive: true });
     const sender = `cli:${userInfo().username}@${hostname()}`;
     const locker = new OsLock(), deadline = performance.now() + 10_000;
@@ -86,7 +126,7 @@ export async function submit(home, command, target, env = process.env, options =
         lock = await locker.tryAcquire(join(home, `${sender}.lock`));
     }
     if (!lock)
-        throw new Error("CLI sender is busy; retry the command");
+        throw new RequestsBusy("CLI sender is busy; retry the command");
     try {
         const outbox = await Outbox.open(outboxRoot(home), sender, () => orchInbox(home));
         try {
@@ -94,24 +134,7 @@ export async function submit(home, command, target, env = process.env, options =
             for (const rid of reduceLifecycle(records).resolved.keys())
                 await outbox.markResolved(rid);
             await outbox.republishPending();
-            const requests = [];
-            if (command === "stop-all") {
-                const body = { fence: true };
-                requests.push(await outbox.send("orch", "drain", body));
-            }
-            else if (command === "prune") {
-                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.
-            await startOrchestrator(home, env);
-            return requests;
+            return await fn(outbox, sender);
         }
         finally {
             await outbox.close();