pi-durable-subagents 1.0.19 → 1.0.21

package/dist/cli/main.js

@@ -13,7 +13,8 @@ import { doctor, renderDoctor, size } from "./doctor.js";
 import { smoke } from "./smoke.js";
 import { serviceFiles, manageService } from "./service.js";
 import { leaseLines, leaseState } from "../platform/lease.js";
-import { currentOrchestrator, legacyRestart, waitExit, waitSuccessor } from "./restart.js";
+import { currentOrchestrator, decidedBy, legacyRestart, cliInitiator, waitExit, waitSuccessor } from "./restart.js";
+import { restartInputError } from "../orchestrator/restart.js";
 const commands = ["smoke", "tail", "status", "events", "start", "resume", "drain", "stop", "stop-all", "prune", "restart", "leases", "doctor", "install-service", "uninstall-service", "help"];
 /** P25: Reject ambiguous CLI arguments before any durable action. */
 export function parseArgs(args) {
@@ -33,12 +34,25 @@ export function parseArgs(args) {
         olderThanDays = Number(value);
         rest = [...rest.slice(0, at), ...rest.slice(at + 2)];
     }
-    const force = rest.includes("--force");
-    if (force && command !== "restart")
-        throw new Error("--force is only supported by restart");
-    if (rest.filter(a => a === "--force").length > 1)
-        throw new Error("Unknown or repeated option");
-    rest = rest.filter(a => a !== "--force");
+    let force, reason;
+    for (const flag of ["--force", "--reason"]) {
+        const index = rest.indexOf(flag);
+        if (index < 0)
+            continue;
+        if (command !== "restart")
+            throw new Error(`${flag} is only supported by restart`);
+        if (rest.filter(a => a === flag).length > 1)
+            throw new Error("Unknown or repeated option");
+        const value = rest[index + 1], present = value !== undefined && !value.startsWith("--");
+        if (flag === "--force")
+            force = present ? value : true;
+        else {
+            if (!present)
+                throw new Error("--reason needs text");
+            reason = value;
+        }
+        rest = [...rest.slice(0, index), ...rest.slice(index + (present ? 2 : 1))];
+    }
     const json = rest.includes("--json"), dryRun = rest.includes("--dry-run");
     if (dryRun && !["install-service", "uninstall-service"].includes(command))
         throw new Error("--dry-run requires a service command");
@@ -56,7 +70,7 @@ export function parseArgs(args) {
         throw new Error("Invalid workflow id");
     if (target && olderThanDays !== undefined)
         throw new Error("prune takes a workflow id or --older-than, not both");
-    return { command, json, ...(force ? { force } : {}), ...(dryRun ? { dryRun } : {}), ...(target ? { target } : {}), ...(olderThanDays !== undefined ? { olderThanDays } : {}) };
+    return { command, json, ...(force !== undefined ? { force } : {}), ...(reason !== undefined ? { reason } : {}), ...(dryRun ? { dryRun } : {}), ...(target ? { target } : {}), ...(olderThanDays !== undefined ? { olderThanDays } : {}) };
 }
 const clip = (text, n) => text.length > n ? `${text.slice(0, n)}…` : text;
 /** P25, T10: Render journal-derived status (one line per call, last output line only) without live orchestrator memory. */
@@ -118,10 +132,17 @@ export function serviceEntryError(entry) {
         return `install-service refuses to run from an npx cache (${entry}); the cache can be pruned and the service would break. Install the CLI with \`npm i -g pi-durable-subagents\` and run \`pi-durable-subagents install-service\` again.`;
     return undefined;
 }
-export const HELP = "pi-durable-subagents: smoke | status [wid] [--json] | events <wid> [--json] | tail [wid] [--json] | start | resume [wid] | drain | stop <wid|callId> | stop-all | prune [wid] [--older-than <days>] | restart [--force] | hold <resource> [--shared] [--max-wait <s>] [--note <text>] -- <command…> | leases [--json] | doctor [--json] | install-service [--dry-run] | uninstall-service [--dry-run] | chaos [--scenario <1-9>] [--keep] [--json]";
+export const HELP = "pi-durable-subagents: smoke | status [wid] [--json] | events <wid> [--json] | tail [wid] [--json] | start | resume [wid] | drain | stop <wid|callId> | stop-all | run --request <id> --spec <file|-> [--cwd <dir>] [--json] [--wait-ms <n>] | send --request <id> --to <run-id|wid/key> [--call <key>] --kind follow-up|answer|steer|model [--qid <qid> --rev <n>] [--message <text|@file>] [--model <m>] [--json] [--wait-ms <n>] | stop --request <id> <run-id|wid|wid/key> [--json] [--wait-ms <n>] | describe --key <id> | describe <wid> [--json] | prune [wid] [--older-than <days>] | restart [--force <token> --reason <text>] | hold <resource> [--shared] [--max-wait <s>] [--note <text>] -- <command…> | leases [--json] | doctor [--json] | install-service [--dry-run] | uninstall-service [--dry-run] | chaos [--scenario <1-9>] [--keep] [--json]";
 /** Restart: the orchestrator exits when no execution runs (or `force`) and the installed version takes over. */
 async function restartCommand(home, env, write, options) {
-    const starter = options.starter ?? startOrchestrator, old = currentOrchestrator(home);
+    const body = { ...(typeof options.force === "string" ? { token: options.force } : options.force === true ? { force: true } : {}), ...(options.reason !== undefined ? { reason: options.reason } : {}), initiator: cliInitiator(env) };
+    const invalid = restartInputError(body, env.DSA_EXEC !== undefined);
+    if (invalid) {
+        write(`restart refused: ${invalid}`);
+        return 1;
+    }
+    const starter = options.starter ?? startOrchestrator;
+    let old = currentOrchestrator(home);
     if (!old) {
         write(await start(home, env, starter) ? "restart: no orchestrator was running; started one for the pending work" : "restart: no orchestrator is running (one starts when work is submitted)");
         return 0;
@@ -129,23 +150,32 @@ async function restartCommand(home, env, write, options) {
     const waitMs = options.waitMs ?? 30_000;
     if (!old.restart) {
         // An orchestrator older than the restart request: check its journals here and end it with SIGTERM.
-        const legacy = legacyRestart(home, old, options.force);
+        const legacy = legacyRestart(home, old, body, { subagent: env.DSA_EXEC !== undefined });
         if (!legacy.applied) {
             write(`restart refused: ${legacy.reason}`);
             return 1;
         }
     }
     else {
-        const [req] = await submit(home, "restart", undefined, env, { force: options.force });
-        const outcome = await resolution(home, req.rid, waitMs);
+        const [req] = await submit(home, "restart", undefined, env, { restart: body });
+        // The orchestrator reads requests only after recovering its workflows (it may itself have just started): keep
+        // waiting while one runs. An undecided request stays durable and is decided later — say so, never resubmit.
+        let outcome = await resolution(home, req.rid, waitMs);
+        if (!outcome && currentOrchestrator(home)) {
+            write(`restart ${req.rid}: submitted; the orchestrator has not reached it yet (it may still be recovering) — waiting`);
+            const deadline = performance.now() + (options.pendingMs ?? 600_000);
+            while (!outcome && currentOrchestrator(home) && performance.now() < deadline)
+                outcome = await resolution(home, req.rid, Math.min(waitMs, 5_000));
+        }
         if (!outcome) {
-            write(`submitted restart ${req.rid}; not resolved within ${Math.round(waitMs / 1000)} s (see: pi-durable-subagents doctor)`);
-            return 1;
+            write(`restart ${req.rid} is still pending: it is decided when an orchestrator reaches it (do not resubmit; see: pi-durable-subagents status)`);
+            return 75;
         }
         if (outcome.type === "rejected") {
             write(`restart refused: ${outcome.reason}`);
             return 1;
         }
+        old = decidedBy(home, req.rid) ?? old;
     }
     if (!await waitExit(old, Math.max(waitMs, 60_000))) {
         write(`restart: orchestrator ${old.version} (pid ${old.pid}) is still shutting down; see: pi-durable-subagents status`);
@@ -164,7 +194,14 @@ export async function main(args = process.argv.slice(2), options = {}) {
     }
     if (args[0] === "chaos")
         return (await import("./chaos/index.js")).chaos(args.slice(1), options.env ?? process.env, options.write);
-    const { command, target, json, dryRun, olderThanDays, force } = parseArgs(args), env = options.env ?? process.env;
+    // R1–R3: program-facing commands named by request ids (strict flags of their own).
+    if (["run", "send", "describe"].includes(args[0]) || (args[0] === "stop" && args.includes("--request"))) {
+        const env = options.env ?? process.env, requests = await import("./requests.js");
+        const ctx = { home: dsaHome(env), env, write: options.write ?? ((line) => console.log(line)), starter: options.starter, waitMs: options.waitMs, cwd: options.cwd, stdin: options.stdin };
+        return args[0] === "run" ? requests.runCommand(args.slice(1), ctx) : args[0] === "send" ? requests.sendCommand(args.slice(1), ctx)
+            : args[0] === "stop" ? requests.stopCommand(args.slice(1), ctx) : requests.describeCommand(args.slice(1), ctx);
+    }
+    const { command, target, json, dryRun, olderThanDays, force, reason } = parseArgs(args), env = options.env ?? process.env;
     const home = dsaHome(env), write = options.write ?? (line => console.log(line));
     if (command === "help") {
         write(HELP);
@@ -256,7 +293,7 @@ export async function main(args = process.argv.slice(2), options = {}) {
         return 0;
     }
     if (command === "restart")
-        return restartCommand(home, env, write, { force: force === true, starter: options.starter, waitMs: options.waitMs });
+        return restartCommand(home, env, write, { force, reason, starter: options.starter, waitMs: options.waitMs, pendingMs: options.pendingMs });
     for (const req of await submit(home, command, target, env))
         write(`submitted ${req.kind} ${req.rid}`);
     return 0;

package/dist/cli/requests.js

@@ -0,0 +1,348 @@
+// R1–R4: Program-facing commands named by caller-chosen request ids — `run|send|stop --request <id>` and `describe`.
+// Exit codes: 0 decided (applied/created), 1 rejected or invalid, 3 request-conflict (the id names other content),
+// 75 not decided within --wait-ms (retry with the same id and content: safe).
+import { existsSync, readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { setTimeout as delay } from "node:timers/promises";
+import { readJournalSnapshot } from "../kernel/journal.js";
+import { reduceLifecycle } from "../kernel/lifecycle.js";
+import { journalPath, orchLedger } from "../paths.js";
+import { findRequest, REQUEST_ID, requestId, requestRid, RequestsBusy, specDigest } from "../requests.js";
+import { isLive, slotsView, workflowSnapshot } from "../orchestrator/snapshot.js";
+import { leaseCalls, leaseState } from "../platform/lease.js";
+import { checkAgents, request } from "../agent/main/tool.js";
+import { discoverAgents } from "../compat/agents.js";
+import { JT } from "../types.js";
+import { startOrchestrator, submitIdentified } from "./control.js";
+export const EXIT = { ok: 0, rejected: 1, conflict: 3, pending: 75 };
+/** Strict `--name value` / `--flag` parsing; unknown or repeated options are errors. */
+function flags(args, spec) {
+    const values = {}, positionals = [];
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if (!arg.startsWith("--")) {
+            positionals.push(arg);
+            continue;
+        }
+        const name = arg.slice(2), kind = spec[name];
+        if (!kind || Object.hasOwn(values, name))
+            throw new Error(`Unknown or repeated option ${arg}`);
+        if (kind === "flag") {
+            values[name] = true;
+            continue;
+        }
+        const value = args[++i];
+        if (value === undefined)
+            throw new Error(`${arg} needs a value`);
+        values[name] = value;
+    }
+    return { values, positionals };
+}
+const text = (values, name) => typeof values[name] === "string" ? values[name] : undefined;
+function waitMs(values, ctx) {
+    const raw = text(values, "wait-ms");
+    if (raw !== undefined && !/^\d+$/.test(raw))
+        throw new Error("--wait-ms needs a non-negative integer");
+    return raw !== undefined ? Number(raw) : ctx.waitMs ?? 60_000;
+}
+function ledger(home) { return readJournalSnapshot(orchLedger(home)); }
+function decision(entries, rid) {
+    const records = entries.filter(e => [JT.admitted, JT.applied, JT.rejected, JT.withdrawn].includes(e.type));
+    return reduceLifecycle(records).resolved.get(rid);
+}
+const createdBy = (entries, rid) => entries.find(e => e.type === JT.created && e.rid === rid);
+async function stdin() { const chunks = []; for await (const chunk of process.stdin)
+    chunks.push(chunk); return Buffer.concat(chunks).toString("utf8"); }
+/** R3: The state of a request id (`{request}`) or a workflow (`{wid}`), with full texts (no clipping). */
+export async function describe(home, key, now = Date.now()) {
+    const entries = ledger(home);
+    if ("wid" in key)
+        return describeWorkflow(home, key.wid, entries, now);
+    const rid = requestRid(key.request), found = await findRequest(home, rid);
+    if (!found)
+        return { state: "absent", request: key.request };
+    const head = { request: key.request, kind: found.request.kind, spec_digest: specDigest(found.request) };
+    const decided = decision(entries, rid), created = createdBy(entries, rid);
+    if (found.request.kind === "run" && created)
+        return { ...await describeWorkflow(home, String(created.wid), entries, now), ...head };
+    if (decided?.type === "rejected")
+        return { state: "rejected", ...head, reason: String(decided.reason) };
+    // A send or stop has no workflow of its own: its decision is the outcome.
+    if (decided && found.request.kind !== "run")
+        return { state: "applied", ...head };
+    return { state: "pending", ...head };
+}
+function describeWorkflow(home, wid, entries, now) {
+    const pruned = entries.find(e => e.type === "pruned" && e.wid === wid);
+    if (pruned)
+        return { state: "pruned", wid, pruned: { ...(pruned.status !== undefined ? { status: String(pruned.status) } : {}), endedAt: Number(pruned.endedAt) },
+            ...(typeof pruned.request === "string" ? { request: pruned.request } : {}), ...(typeof pruned.spec_digest === "string" ? { spec_digest: pruned.spec_digest } : {}) };
+    if (!/^[^/\\\0]+$/.test(wid) || wid === "." || wid === ".." || !existsSync(journalPath(home, wid)))
+        return { state: "absent", wid };
+    const wf = workflowSnapshot(home, wid), journal = readJournalSnapshot(journalPath(home, wid));
+    const created = entries.find(e => e.type === JT.created && e.wid === wid), id = created ? requestId(String(created.rid)) : undefined;
+    const admitted = id ? entries.find(e => e.type === "request" && e.request.rid === created.rid)?.request : undefined;
+    const slots = slotsView(home, now), leases = leaseCalls(leaseState(home), now);
+    const line = (lines, model) => { const provider = model?.split("/")[0]; return provider ? lines?.find(l => l.startsWith(`${provider} `)) : undefined; };
+    const latest = [...new Map(wf.calls.map(c => [c.key, c])).values()];
+    const calls = latest.map((c) => {
+        const r = c.result, waiting = r ? undefined : {
+            ...(c.writerWait ? { writerWait: c.writerWait } : {}), ...(leases.get(c.callId) ? { lease: leases.get(c.callId) } : {}),
+            ...(line(slots.slots, c.model) ? { slot: line(slots.slots, c.model) } : {}), ...(line(slots.exhausted, c.model) ? { exhausted: line(slots.exhausted, c.model) } : {}),
+            ...(c.hibernated ? { hibernated: true } : {})
+        };
+        return { key: c.key, gen: c.gen, phase: c.phase, agent: c.agent, ...(c.model ? { model: c.model } : {}),
+            ...(r ? { status: r.status, ok: r.ok, ...(r.error ? { error: r.error } : {}), output: r.output, ...(r.data !== undefined ? { data: r.data } : {}) } : {}),
+            ...(waiting && Object.keys(waiting).length ? { waiting } : {}) };
+    });
+    const keyOf = (call) => call?.replace(/^[^/]*\//, "").replace(/@\d+$/, "");
+    const questions = wf.attention.filter(a => a.kind === "question").map(a => ({ ...(a.qid ? { qid: a.qid } : {}), rev: a.rev, to: `${wid}/${keyOf(a.call)}`, ...(a.call ? { call: a.call } : {}), text: a.text }));
+    const attention = wf.attention.filter(a => a.kind !== "question").map(a => ({ id: a.id, rev: a.rev, kind: a.kind, ...(a.call ? { call: a.call } : {}), text: a.text }));
+    const state = questions.length ? "asking" : isLive(wf) || wf.status === "parked" ? "running" : "sealed";
+    const fence = lastFence(journal, entries);
+    return { state, wid, ...(id ? { request: id } : {}), ...(admitted ? { spec_digest: specDigest(admitted) } : {}), status: wf.status, ...(wf.error ? { error: wf.error } : {}),
+        calls, ...(questions.length ? { questions } : {}), ...(attention.length ? { attention } : {}), ...(fence ? { lastFence: fence } : {}) };
+}
+/** R3, best effort: why the latest execution fence happened. restart-force: a forced restart listed the execution as live;
+ *  orchestrator-crash: the execution was launched before an orchestrator start that is not preceded by a clean exit and
+ *  fenced after it (startup recovery); otherwise process-died (the child or its host went away, or a drain/stop fenced it). */
+export function lastFence(journal, orch) {
+    const fence = journal.findLast(e => e.type === JT.fenced);
+    if (!fence)
+        return undefined;
+    const exec = String(fence.exec), at = Number(fence.ts);
+    if (orch.some(e => e.type === "restart" && e.force === true && Array.isArray(e.live) && e.live.includes(exec)))
+        return { at, exec, reason: "restart-force" };
+    const launched = journal.find(e => e.type === JT.exec && e.exec === exec), starts = orch.filter(e => e.type === "orchestrator");
+    const recovery = starts.findLast(s => Number(s.ts) <= at);
+    if (launched && recovery && Number(launched.ts) < Number(recovery.ts)) {
+        const prior = orch.filter(e => Number(e.seq) < Number(recovery.seq));
+        const lastStart = prior.findLast(e => e.type === "orchestrator"), cleanExit = lastStart && prior.some(e => e.type === "orchestrator-exit" && Number(e.seq) > Number(lastStart.seq));
+        if (!cleanExit)
+            return { at, exec, reason: "orchestrator-crash" };
+    }
+    return { at, exec, reason: "process-died" };
+}
+export function renderDescription(d) {
+    const lines = [`${d.request ?? d.wid}: ${d.state}${d.reason ? ` (${d.reason})` : ""}${d.wid && d.request ? ` — ${d.wid}` : ""}${d.status && d.state !== d.status ? ` · ${d.status}` : ""}`];
+    if (d.pruned)
+        lines.push(`  pruned: ${d.pruned.status ?? "?"} at ${new Date(d.pruned.endedAt ?? 0).toISOString()}`);
+    if (d.error)
+        lines.push(`  error: ${d.error}`);
+    for (const c of d.calls ?? []) {
+        lines.push(`  ${c.key}@${c.gen} ${c.agent} ${c.phase}${c.status ? ` ${c.status}` : ""}${c.model ? ` (${c.model})` : ""}${c.error ? ` — ${c.error}` : ""}`);
+        if (c.waiting)
+            lines.push(`    waiting: ${JSON.stringify(c.waiting)}`);
+        if (c.data !== undefined)
+            lines.push(`    data: ${JSON.stringify(c.data)}`);
+        if (c.output)
+            lines.push(...c.output.split("\n").map(l => `    | ${l}`));
+    }
+    for (const q of d.questions ?? [])
+        lines.push(`  question ${q.to} qid=${q.qid} rev=${q.rev}:`, ...q.text.split("\n").map(l => `    ${l}`));
+    for (const a of d.attention ?? [])
+        lines.push(`  ${a.kind}${a.call ? ` ${a.call}` : ""}: ${a.text}`);
+    if (d.lastFence)
+        lines.push(`  last fence: ${d.lastFence.exec} ${d.lastFence.reason} at ${new Date(d.lastFence.at).toISOString()}`);
+    return lines.join("\n");
+}
+export async function describeCommand(args, ctx) {
+    const { values, positionals } = flags(args, { key: "value", json: "flag" });
+    const key = text(values, "key");
+    if ((key === undefined) === (positionals.length !== 1) || positionals.length > 1)
+        throw new Error("describe needs --key <request id> or a workflow id");
+    const d = await describe(ctx.home, key !== undefined ? { request: key } : { wid: positionals[0] });
+    ctx.write(values.json ? JSON.stringify(d, null, 2) : renderDescription(d));
+    return 0;
+}
+/** Wait (bounded) for the request's decision: a run's `created` wid, or the lifecycle resolution. */
+async function outcome(home, rid, run, timeoutMs) {
+    const deadline = performance.now() + timeoutMs;
+    for (;;) {
+        const entries = ledger(home), created = run ? createdBy(entries, rid) : undefined;
+        if (created)
+            return { type: "applied", wid: String(created.wid) };
+        const decided = decision(entries, rid);
+        if (decided?.type === "rejected")
+            return { type: "rejected", reason: String(decided.reason) };
+        if (decided && !run)
+            return { type: "applied" };
+        if (performance.now() >= deadline)
+            return undefined;
+        await delay(Math.min(100, Math.max(0, deadline - performance.now())));
+    }
+}
+async function conflict(ctx, id, original, json) {
+    const d = await describe(ctx.home, { request: id });
+    const reply = { request: id, error: "request-conflict", ...(d.wid ? { wid: d.wid } : {}), spec_digest: original, state: d.state };
+    ctx.write(json ? JSON.stringify(reply) : `${id}: request-conflict — this id names other content (${d.state}${d.wid ? `, ${d.wid}` : ""}); retry with the stored spec bytes or use a new id`);
+    return EXIT.conflict;
+}
+function pending(ctx, id, json, why = "") {
+    ctx.write(json ? JSON.stringify({ request: id, pending: true, ...(why ? { reason: why } : {}) }) : `${id}: submitted; not decided yet${why ? ` (${why})` : ""} — retry with the same id (safe)`);
+    return EXIT.pending;
+}
+/** Submit, then wait; a decision whose admitted envelope has other content (another sender won the id) is a conflict. */
+async function submitAndWait(ctx, id, kind, body, cond, wait, json) {
+    // R2: `created` is false only when the id was already decided before this invocation submitted (decisions are
+    // monotonic); racing first attempts may all report created — the wid is what identifies the run.
+    const rid = requestRid(id), earlier = Boolean(await outcome(ctx.home, rid, kind === "run", 0));
+    let sent;
+    try {
+        sent = await submitIdentified(ctx.home, rid, kind, body, cond, ctx.env, ctx.starter);
+    }
+    catch (error) {
+        // Exit 1 means decided (rejected) or a usage error. A busy lock submitted nothing, and a failure after the envelope
+        // was recorded (starting the orchestrator, say) leaves it submitted: both are "not decided yet — retry the same id".
+        const recorded = await findRequest(ctx.home, rid).catch(() => undefined);
+        if (error instanceof RequestsBusy || recorded && specDigest(recorded.request) === specDigest({ kind, body, cond }))
+            return { code: pending(ctx, id, json, error instanceof RequestsBusy ? "busy" : `submitted, then: ${error.message ?? String(error)}`) };
+        throw error;
+    }
+    if ("conflict" in sent)
+        return { code: await conflict(ctx, id, sent.digest, json) };
+    const result = await outcome(ctx.home, rid, kind === "run", wait);
+    if (!result)
+        return { code: pending(ctx, id, json) };
+    const admitted = (await findRequest(ctx.home, rid))?.request;
+    if (admitted && specDigest(admitted) !== sent.digest)
+        return { code: await conflict(ctx, id, specDigest(admitted), json) };
+    return { sent, outcome: result, earlier };
+}
+const forks = (spec) => [spec, ...["tasks", "chain"].flatMap(k => Array.isArray(spec[k]) ? spec[k] : [])]
+    .some(s => s && typeof s === "object" && s.context === "fork");
+/** R2: `run --request <id> --spec <file|-> [--cwd <dir>] [--json] [--wait-ms <n>]`. The spec is the `subagents` run
+ *  form ({agent,task,…} or {tasks|chain:[…],…}); it is validated by the tool's own normalizer and agent check. */
+export async function runCommand(args, ctx) {
+    const { values, positionals } = flags(args, { request: "value", spec: "value", cwd: "value", json: "flag", "wait-ms": "value" });
+    const id = text(values, "request"), file = text(values, "spec"), json = values.json === true, wait = waitMs(values, ctx);
+    if (!id || !file || positionals.length)
+        throw new Error("usage: run --request <id> --spec <file|-> [--cwd <dir>] [--json] [--wait-ms <n>]");
+    requestRid(id);
+    const bytes = file === "-" ? await (ctx.stdin ?? stdin)() : readFileSync(resolve(ctx.cwd ?? process.cwd(), file), "utf8");
+    let spec;
+    try {
+        spec = JSON.parse(bytes);
+    }
+    catch (error) {
+        throw new Error(`--spec is not JSON: ${error.message}`);
+    }
+    if (!spec || typeof spec !== "object" || Array.isArray(spec))
+        throw new Error("--spec must be a JSON object");
+    if (spec.action !== undefined && spec.action !== "run")
+        throw new Error("--spec describes a run; action must be absent or \"run\"");
+    if (spec.request !== undefined)
+        throw new Error("the request id is --request, not a spec field");
+    if (forks(spec))
+        throw new Error("context \"fork\" needs a pi session to fork; it is not available to run --request");
+    // RunBody.cwd = spec.cwd ?? --cwd ?? the current directory, absolute before the digest.
+    const base = resolve(ctx.cwd ?? process.cwd(), text(values, "cwd") ?? "."), dir = typeof spec.cwd === "string" && spec.cwd ? resolve(base, spec.cwd) : base;
+    const normalized = request({ ...spec, action: "run", ...(typeof spec.cwd === "string" && spec.cwd ? { cwd: dir } : {}) }, dir);
+    const body = normalized.body;
+    checkAgents(body, () => discoverAgents(dir, { home: ctx.env.HOME || undefined, agentDir: ctx.env.PI_CODING_AGENT_DIR || undefined }).agents.map(a => a.name));
+    const done = await submitAndWait(ctx, id, "run", body, undefined, wait, json);
+    if ("code" in done)
+        return done.code;
+    if (done.outcome.type === "rejected") {
+        ctx.write(json ? JSON.stringify({ request: id, applied: false, reason: done.outcome.reason, spec_digest: done.sent.digest }) : `${id}: rejected ${done.outcome.reason}`);
+        return EXIT.rejected;
+    }
+    const reply = { request: id, wid: done.outcome.wid, created: !done.earlier, spec_digest: done.sent.digest };
+    ctx.write(json ? JSON.stringify(reply) : `${id} → ${reply.wid} (${reply.created ? "created" : "existing"})`);
+    return EXIT.ok;
+}
+/** `<run-id>` or `<wid>` → wid when that run id created one; `pending` when the run is known but has no workflow yet. */
+async function widOf(home, head) {
+    if (!REQUEST_ID.test(head))
+        return { wid: head };
+    const rid = requestRid(head), created = createdBy(ledger(home), rid);
+    if (created)
+        return { wid: String(created.wid) };
+    const found = await findRequest(home, rid);
+    return found?.request.kind === "run" && decision(ledger(home), rid)?.type !== "rejected" ? { pending: true } : { wid: head };
+}
+/** R2: `--to <run-id>[/<key>] | <wid>/<key>` (+ `--call <key>`) → `<wid>/<key>`; a run of one call implies its key. */
+async function target(home, to, call, prior) {
+    const cut = to.indexOf("/"), head = cut < 0 ? to : to.slice(0, cut), key = cut < 0 ? call : to.slice(cut + 1);
+    if (cut >= 0 && call !== undefined)
+        throw new Error("give the call key in --to or --call, not both");
+    const resolved = await widOf(home, head);
+    if ("pending" in resolved)
+        return resolved;
+    if (key)
+        return { to: `${resolved.wid}/${key}` };
+    // A retry addresses what the original did (the workflow may have been pruned since).
+    const before = prior?.body?.to;
+    if (typeof before === "string" && before.startsWith(`${resolved.wid}/`))
+        return { to: before };
+    if (!existsSync(journalPath(home, resolved.wid)))
+        return { to: resolved.wid };
+    const keys = [...new Set(workflowSnapshot(home, resolved.wid).calls.map(c => c.key))];
+    if (keys.length === 1)
+        return { to: `${resolved.wid}/${keys[0]}` };
+    throw new Error(`${to} has ${keys.length ? `calls ${keys.join(", ")}` : "no calls yet"}; name one with --call <key> or --to <wid>/<key>`);
+}
+/** R2: `send --request <id> --to <…> --kind follow-up|answer|steer|model [--qid <qid> --rev <n>] --message <text|@file> [--model <m>]`. */
+export async function sendCommand(args, ctx) {
+    const { values, positionals } = flags(args, { request: "value", to: "value", call: "value", kind: "value", qid: "value", rev: "value", message: "value", model: "value", json: "flag", "wait-ms": "value" });
+    const id = text(values, "request"), to = text(values, "to"), kind = text(values, "kind"), json = values.json === true, wait = waitMs(values, ctx);
+    if (!id || !to || !kind || positionals.length)
+        throw new Error("usage: send --request <id> --to <run-id|wid/key> --kind follow-up|answer|steer|model [--qid <qid> --rev <n>] --message <text|@file> [--model <m>] [--json]");
+    const rid = requestRid(id), prior = (await findRequest(ctx.home, rid))?.request;
+    const where = await target(ctx.home, to, text(values, "call"), prior);
+    if ("pending" in where)
+        return pending(ctx, id, json, `run ${to.split("/")[0]} has no workflow yet`);
+    const raw = text(values, "message"), message = raw?.startsWith("@") ? readFileSync(resolve(ctx.cwd ?? process.cwd(), raw.slice(1)), "utf8") : raw;
+    const rev = text(values, "rev");
+    if (rev !== undefined && !/^\d+$/.test(rev))
+        throw new Error("--rev needs a positive integer");
+    let qid = text(values, "qid"), revision = rev !== undefined ? Number(rev) : undefined;
+    if (kind === "answer" && (qid === undefined || revision === undefined)) {
+        // The open question of the target call (or, on a retry, the one the original answered) supplies qid/rev.
+        const before = prior?.kind === "send" && prior.body.kind === "answer" && prior.body.to === where.to ? prior.cond : undefined;
+        const [wid, key] = [where.to.slice(0, where.to.indexOf("/")), where.to.slice(where.to.indexOf("/") + 1)];
+        const open = before ? [{ qid: before.qid, rev: before.rev }] : existsSync(journalPath(ctx.home, wid))
+            ? workflowSnapshot(ctx.home, wid).attention.filter(a => a.kind === "question" && a.call?.replace(/^[^/]*\//, "").replace(/@\d+$/, "") === key && (qid === undefined || a.qid === qid)) : [];
+        if (open.length !== 1)
+            throw new Error(open.length ? `several questions are open on ${where.to}; give --qid and --rev` : `no open question on ${where.to}${qid ? ` with qid ${qid}` : ""}`);
+        qid ??= open[0].qid;
+        revision ??= open[0].rev;
+    }
+    const normalized = request({ action: "send", to: where.to, kind, ...(message !== undefined ? { message } : {}), ...(text(values, "model") !== undefined ? { model: text(values, "model") } : {}),
+        ...(qid !== undefined ? { qid } : {}), ...(revision !== undefined ? { rev: revision } : {}) }, ctx.cwd ?? process.cwd());
+    const done = await submitAndWait(ctx, id, "send", normalized.body, normalized.cond, wait, json);
+    if ("code" in done)
+        return done.code;
+    return decided(ctx, id, done, json);
+}
+/** R2: `stop --request <id> <run-id|wid|wid/key|callId>`. */
+export async function stopCommand(args, ctx) {
+    const { values, positionals } = flags(args, { request: "value", json: "flag", "wait-ms": "value" });
+    const id = text(values, "request"), json = values.json === true, wait = waitMs(values, ctx);
+    if (!id || positionals.length !== 1)
+        throw new Error("usage: stop --request <id> <run-id|wid|wid/key> [--json]");
+    requestRid(id);
+    const raw = positionals[0], cut = raw.indexOf("/"), head = cut < 0 ? raw : raw.slice(0, cut);
+    const resolved = raw.includes("@") ? { wid: head } : await widOf(ctx.home, head);
+    if ("pending" in resolved)
+        return pending(ctx, id, json, `run ${head} has no workflow yet`);
+    const normalized = request({ action: "stop", target: raw.includes("@") ? raw : `${resolved.wid}${raw.slice(head.length)}` }, ctx.cwd ?? process.cwd());
+    const done = await submitAndWait(ctx, id, "stop", normalized.body, undefined, wait, json);
+    if ("code" in done)
+        return done.code;
+    return decided(ctx, id, done, json);
+}
+function decided(ctx, id, done, json) {
+    if (done.outcome.type === "rejected") {
+        ctx.write(json ? JSON.stringify({ request: id, applied: false, reason: done.outcome.reason, spec_digest: done.sent.digest }) : `${id}: rejected ${done.outcome.reason}`);
+        return EXIT.rejected;
+    }
+    // A follow-up opens a new generation: the orchestrator records it in the workflow journal under the request's rid.
+    const body = done.sent.request.body;
+    const wid = typeof body.to === "string" ? body.to.split("/")[0].split("@")[0] : undefined;
+    const opened = done.sent.request.kind === "send" && wid && existsSync(journalPath(ctx.home, wid))
+        ? readJournalSnapshot(journalPath(ctx.home, wid)).find(e => e.type === "generation" && e.rid === done.sent.request.rid) : undefined;
+    const reply = { request: id, applied: true, ...(opened ? { generation: Number(opened.gen), call: `${wid}/${String(opened.key)}` } : {}), spec_digest: done.sent.digest };
+    ctx.write(json ? JSON.stringify(reply) : `${id}: applied${opened ? ` (follow-up generation ${reply.generation} of ${reply.call})` : ""}`);
+    return EXIT.ok;
+}

package/dist/cli/restart.js

@@ -4,10 +4,14 @@
 // `orchestrator` record has no `restart: true`) would keep the request as an invalid inbox file and never idle-exit, so it
 // is never sent one: the client checks the journals itself and ends it with SIGTERM (its shutdown fences what still runs,
 // and recovery resumes it) — a check without the orchestrator's launch gate, so a launch can slip in between.
+import { readFileSync } from "node:fs";
+import { execFileSync } from "node:child_process";
+import { hostname, userInfo } from "node:os";
 import { setTimeout as delay } from "node:timers/promises";
 import { readJournalSnapshot } from "../kernel/journal.js";
 import { journalPath, orchLedger } from "../paths.js";
 import { JT } from "../types.js";
+import { restartInputError, restartRefusal } from "../orchestrator/restart.js";
 import { emptyLedger, foldLedger } from "../orchestrator/ledger.js";
 import { allWorkflows, liveCalls, processAlive } from "../orchestrator/snapshot.js";
 /** The orchestrator that runs now: the last `orchestrator` record without an exit, whose process lives. */
@@ -15,29 +19,36 @@ export function currentOrchestrator(home) {
     const o = foldLedger(emptyLedger(), readJournalSnapshot(orchLedger(home))).orchestrator;
     return o && !o.exited && processAlive(o.pid, o.start) ? { version: o.version, pid: o.pid, ...(o.start ? { start: o.start } : {}), ts: o.ts, ...(o.restart ? { restart: true } : {}) } : undefined;
 }
-/** Calls whose execution runs per the journals: running, asking without having hibernated (its child still runs), or
- *  running a gate (a gate-intent without its outcome; an interrupted gate is not run again). */
-export function journalLiveCalls(home, now = Date.now()) {
-    const age = (ms) => ms < 60_000 ? `${Math.max(0, Math.round(ms / 1000))}s` : `${Math.round(ms / 60_000)}m`;
+/** Best-effort provenance; never read the live DSA home to identify the invoking process. */
+export function cliInitiator(env) {
+    if (env.DSA_CALL)
+        return { call: env.DSA_CALL };
+    let parent = "";
+    try {
+        parent = process.platform === "linux" ? readFileSync(`/proc/${process.ppid}/cmdline`, "utf8").replace(/\0/g, " ").trim()
+            : process.platform === "darwin" ? execFileSync("ps", ["-o", "command=", "-p", String(process.ppid)], { encoding: "utf8", timeout: 1000, maxBuffer: 64 * 1024 }).trim() : "";
+    }
+    catch { /* Parent may have exited or /proc may be unavailable. */ }
+    return { cli: { user: userInfo().username, host: hostname(), ppid: process.ppid, parent: parent.slice(0, 200) } };
+}
+/** Calls whose execution runs per the journals: running, asking without having hibernated, or an unresolved gate. */
+export function journalLiveCalls(home) {
     return allWorkflows(home).flatMap(wf => {
         const entries = readJournalSnapshot(journalPath(home, wf.wid));
         const done = new Set(entries.filter(e => e.type === "gate").map(e => String(e.id)));
         const sealed = new Set(entries.filter(e => e.type === JT.sealed).map(e => String(e.call)));
-        const gates = new Map(entries.filter(e => e.type === "gate-intent" && !done.has(String(e.id)) && !sealed.has(String(e.call))).map(e => [String(e.call), e.ts]));
-        const where = wf.origin ? ` from ${wf.origin}` : "";
-        const running = liveCalls(wf).filter(c => !gates.has(c.callId) && (c.phase === "running" || (c.phase === "asking" && c.exec !== undefined && !c.hibernated)))
-            .map(c => `${wf.wid}/${c.key}${c.startedAt ? ` ${age(now - c.startedAt)}` : ""}${where}`);
-        const gating = [...gates].map(([call, ts]) => `${wf.wid}/${call.slice(call.indexOf("/") + 1, call.lastIndexOf("@"))} gate ${age(now - ts)}${where}`);
+        const gates = new Map(entries.filter(e => e.type === "gate-intent" && !done.has(String(e.id)) && !sealed.has(String(e.call))).map(e => [String(e.call), e]));
+        const running = liveCalls(wf).filter(c => !gates.has(c.callId) && c.exec !== undefined && (c.phase === "running" || (c.phase === "asking" && !c.hibernated)))
+            .map(c => ({ wid: wf.wid, key: c.key, gen: c.gen, callId: c.callId, exec: c.exec, since: c.startedAt ?? wf.startedAt ?? Date.now(), phase: "child", origin: wf.origin }));
+        const gating = [...gates].map(([call, e]) => ({ wid: wf.wid, key: call.slice(call.indexOf("/") + 1, call.lastIndexOf("@")), gen: Number(call.slice(call.lastIndexOf("@") + 1)), callId: call, exec: String(e.id), since: e.ts, phase: "gate", origin: wf.origin }));
         return [...running, ...gating];
     });
 }
-/** For an orchestrator without the restart request kind: refuse while calls run (unless forced), else SIGTERM it. */
-export function legacyRestart(home, old, force) {
-    const live = journalLiveCalls(home);
-    if (live.length && !force) {
-        const shown = live.slice(0, 8).join("; ") + (live.length > 8 ? `; +${live.length - 8} more` : "");
-        return { applied: false, reason: `busy: ${live.length} running call${live.length === 1 ? "" : "s"} on orchestrator ${old.version} (pid ${old.pid}): ${shown} — retry when they finish (or drain first), or force to fence them; they resume on the new orchestrator` };
-    }
+/** Legacy has no launch gate: check immediately before SIGTERM; a launch can still slip between (documented). */
+export function legacyRestart(home, old, body, options = {}) {
+    const reason = restartInputError(body, options.subagent) ?? restartRefusal(home, journalLiveCalls(home), body, options.tool);
+    if (reason)
+        return { applied: false, reason };
     try {
         process.kill(old.pid, "SIGTERM");
     }
@@ -48,6 +59,13 @@ export function legacyRestart(home, old, force) {
     return { applied: true };
 }
 /** Wait (bounded) until the process ends; false when it still runs at the deadline. */
+/** The orchestrator that decided request `rid`: the last start recorded before its resolution. */
+export function decidedBy(home, rid) {
+    const entries = readJournalSnapshot(orchLedger(home));
+    const at = entries.findIndex(e => (e.type === JT.applied || e.type === JT.rejected) && e.rid === rid);
+    const o = at < 0 ? undefined : entries.slice(0, at).findLast(e => e.type === 'orchestrator');
+    return o ? { version: String(o.version), pid: Number(o.pid), ...(o.start ? { start: String(o.start) } : {}), ts: o.ts, ...(o.restart ? { restart: true } : {}) } : undefined;
+}
 export async function waitExit(old, timeoutMs) {
     const deadline = performance.now() + timeoutMs;
     while (processAlive(old.pid, old.start)) {

package/dist/kernel/lifecycle.js

@@ -35,7 +35,8 @@ export function planDecisions(records, candidates, decide) {
         if (bound) {
             if (bound.hash === hash)
                 envelopes.set(req.rid, req);
-            else if (!conflicts.has(req.rid)) {
+            // A1, R1: a conflicting duplicate of a resolved rid is only dropped (its file still goes); it never records a decision.
+            else if (!view.resolved.has(req.rid) && !conflicts.has(req.rid)) {
                 conflicts.add(req.rid);
                 emit({ type: 'rejected', rid: req.rid, reason: 'identity-conflict' });
             }