pi-durable-subagents 1.0.18 → 1.0.21

package/dist/orchestrator/engine.js

@@ -7,8 +7,10 @@
 // its seal has a finished attention independent of workflow completion.
 // resumed {rid,n} supersedes a terminal park. emit {pos,value} records script outputs.
 // stop-requested {rid,call?} marks a call or workflow stop as taking effect, so its replay is applied, not already-sealed.
-// Orch entry pruned {rid,wid,endedAt,bytes} is the decisive record of a prune: appended before the journal handle is
-// closed and w/<wid> and its staging dirs are removed (bytes = footprint measured just before). Nothing is rewritten (A1).
+// Orch entry pruned {rid,wid,endedAt,bytes,status,request?,spec_digest?} is the decisive record of a prune: appended before
+// the journal handle is closed and w/<wid> and its staging dirs are removed (bytes = footprint measured just before;
+// status = the final workflow status; request/spec_digest when the workflow was created by a request id, R1 tombstone).
+// Nothing is rewritten (A1): the admitted request and created entries stay, so a retried id still resolves to this wid.
 import { watch } from 'node:fs';
 import { mkdir, readdir, unlink } from 'node:fs/promises';
 import { resolve, join } from 'node:path';
@@ -17,7 +19,9 @@ import { contentHash } from "../kernel/ids.js";
 import { planDecisions, reduceLifecycle } from "../kernel/lifecycle.js";
 import { scanInbox } from "../kernel/mailbox.js";
 import { orchInbox, pinnedDir } from "../paths.js";
+import { requestId, specDigest } from "../requests.js";
 import { JT, attentionEntries, isEntry } from "../types.js";
+import { isForceRestart, restartRefusal } from "./restart.js";
 import { EvaluatorClient } from "./evaluator-client.js";
 import { Store, revisionEntries, terminalEntry } from "./store.js";
 import { formatUsage, holdOf, refusedResult, snapshotFromEntries } from "./snapshot.js";
@@ -32,6 +36,10 @@ const wakeStatus = (status) => {
         return 'unknown';
     return status;
 };
+/** A follow-up still going when its workflow ended has no result yet: say so instead of calling it unknown. */
+/** A follow-up generation still going when its workflow ended is named by its phase; anything else without a result is unknown. */
+const going = (c) => !c.result && c.phase !== 'sealed' && c.gen > 1;
+const callStatus = (c) => going(c) ? c.phase : wakeStatus(c.result?.status);
 /** v12 §6: Name available agents in the refusal instead of making the caller guess. */
 export function unknownAgent(name, agents) {
     return `unknown agent ${JSON.stringify(name)}; available agents: ${agents.map(a => a.name).sort().join(", ") || "none"}`;
@@ -43,11 +51,11 @@ export function finishedText(wid, entries, call) {
     const calls = call ? snap.calls.filter(c => c.callId === call) : [...latest.values()];
     const counts = new Map();
     for (const c of calls) {
-        const status = wakeStatus(c.result?.status);
+        const status = callStatus(c);
         counts.set(status, (counts.get(status) ?? 0) + 1);
     }
     const parts = [...counts].map(([status, count]) => `${count} ${status}`);
-    const heading = call ? `${label}/${calls[0]?.key ?? call}@${calls[0]?.gen ?? '?'} (follow-up) ${wakeStatus(calls[0]?.result?.status)}:` :
+    const heading = call ? `${label}/${calls[0]?.key ?? call}@${calls[0]?.gen ?? '?'} (follow-up) ${calls[0] ? callStatus(calls[0]) : 'unknown'}:` :
         `${label} (${wid}) ${snap.status}${parts.length ? `: ${parts.join('; ')}` : ''}`;
     const footer = `${snap.error ? `\nError: ${tail(snap.error, 500)}` : ''}${charged(snap.usage) ? `\nUsage: ${charged(snap.usage)}` : ''}\nFull output: subagents status wid:${wid}`;
     const prefix = tail(heading, Math.max(1, 6000 - footer.length - 1));
@@ -70,7 +78,8 @@ export function finishedText(wid, entries, call) {
             continue;
         const result = c.result;
         // A stop leaves the agent's edits where they are; say so, so nobody mistakes a stopped agent for a clean undo.
-        const name = `${c.key}${c.gen > 1 ? `@${c.gen}` : ''}: ${wakeStatus(result?.status)}${result?.status === 'stopped' ? ' (edits it made so far are left in place)' : ''}`;
+        const still = going(c) ? ' (a follow-up still going; you are told when it ends)' : '';
+        const name = `${c.key}${c.gen > 1 ? `@${c.gen}` : ''}: ${callStatus(c)}${still}${result?.status === 'stopped' ? ' (edits it made so far are left in place)' : ''}`;
         const title = `\n${tail(name, allowance - 1)}`;
         const error = result?.error && allowance - title.length > 10 ? `\n  Error: ${tail(result.error, Math.min(300, allowance - title.length - 9))}` : '';
         const space = allowance - title.length - error.length;
@@ -446,13 +455,23 @@ export class Engine {
         else if (req.kind === 'restart') {
             // A replay (the restart was recorded, then the process ended before its resolution) applies without restarting again.
             if (!this.ledgers.orch.entries().some(e => e.type === 'restart' && e.rid === req.rid)) {
-                const force = req.body?.force === true;
+                // Only a restart that fenced something is recorded as a force (a token with nothing running fences nothing).
+                const body = req.body ?? {}, force = isForceRestart(body);
+                // A claimed subagent call only restricts (it cannot force); otherwise the main session's sender is authoritative.
+                const initiator = body.initiator && 'call' in body.initiator ? body.initiator : req.from.startsWith('main:') ? { origin: req.from } : body.initiator ?? { origin: req.from };
                 const gate = this.executor.quiesce?.() ?? { live: [], resume() { } };
-                if (gate.live.length && !force) {
+                const reason = restartRefusal(this.ledgers.home, gate.live.map(l => ({ ...l, origin: this.store.workflows.get(l.wid)?.origin })), body, req.from.startsWith('main:'));
+                if (reason) {
                     gate.resume();
-                    return { action: 'reject', reason: this.busyReason(gate.live) };
+                    return { action: 'reject', reason };
+                }
+                try {
+                    await this.ledgers.orch.append('restart', { rid: req.rid, force: force && gate.live.length > 0, reason: body.reason, initiator, from: req.from, live: gate.live.map(l => l.exec) });
+                }
+                catch (error) {
+                    gate.resume();
+                    throw error;
                 }
-                await this.ledgers.orch.append('restart', { rid: req.rid, force, live: gate.live.map(l => l.exec) });
                 this.restarting = true;
             }
         }
@@ -462,15 +481,6 @@ export class Engine {
             return { action: 'reject', reason: 'unsupported-kind' };
         return { action: 'apply' };
     }
-    /** Restart refused: which executions run now, whose they are and for how long, and the way to proceed. */
-    busyReason(live) {
-        const now = Date.now(), minutes = (ms) => ms < 60_000 ? `${Math.max(0, Math.round(ms / 1000))}s` : `${Math.round(ms / 60_000)}m`;
-        const shown = live.slice(0, 8).map(l => {
-            const origin = this.store.workflows.get(l.wid)?.origin;
-            return `${l.wid}/${l.key}${l.phase === 'gate' ? ' gate' : ''} ${minutes(now - l.since)}${origin ? ` from ${origin}` : ''}`;
-        });
-        return `busy: ${live.length} running execution${live.length === 1 ? '' : 's'}: ${shown.join('; ')}${live.length > shown.length ? `; +${live.length - shown.length} more` : ''} — retry when they finish (or drain first), or force to fence them; they resume on the new orchestrator`;
-    }
     /** Set by an applied restart: the loop ends and the process exits; its successor recovers every workflow. */
     get restartRequested() { return this.restarting; }
     /** A1, housekeeping: Prune finished workflows (named, or all ended more than olderThanDays ago); a replay of a
@@ -518,7 +528,11 @@ export class Engine {
     /** A1, housekeeping: The pruned entry commits first; then the handle closes and the files go (recovery finishes them). */
     async pruneWorkflow(rid, wf) {
         const bytes = await this.store.footprint(wf.wid);
-        await this.ledgers.orch.append('pruned', { rid, wid: wf.wid, endedAt: this.terminal(wf).ts, bytes });
+        const done = this.terminal(wf), entries = this.ledgers.orch.entries();
+        const createdBy = String(entries.find(e => e.type === JT.created && e.wid === wf.wid)?.rid ?? '');
+        const admitted = requestId(createdBy) !== undefined ? entries.find(e => e.type === 'request' && e.request.rid === createdBy)?.request : undefined;
+        const identity = admitted ? { request: requestId(createdBy), spec_digest: specDigest(admitted) } : {};
+        await this.ledgers.orch.append('pruned', { rid, wid: wf.wid, endedAt: done.ts, bytes, status: String(done.status), ...identity });
         this.states.delete(wf.wid);
         await this.store.drop(wf.wid);
         try {
@@ -557,7 +571,7 @@ export class Engine {
             throw new Error(`Unknown pinned agent: ${spec.agent}`);
         return { wid: st.wf.wid, widRev: `${st.wf.wid}@${st.wf.revision}`, key: entry.key, gen: entry.gen,
             callId: `${st.wf.wid}@${st.wf.revision}/${entry.key}@${entry.gen}`, spec, agent, workflowBudget: st.wf.pins.usageBudget, cwd: resolve(st.wf.cwd, spec.cwd ?? '.'), journal: st.wf.journal,
-            ...(st.wf.pins.origin !== undefined ? { originSession: join(pinnedDir(this.ledgers.home, st.wf.wid), ...(st.wf.revision === 1 ? [] : [`r${st.wf.revision}`]), 'origin.jsonl') } : {}),
+            ...(st.wf.originPath !== undefined ? { originSession: st.wf.originPath } : {}),
             ...(entry.type === 'generation' ? { continueFrom: entry.from, opening: entry.opening } : {}),
             ...(entry.type === 'generation' && typeof entry.model === 'string' ? { model: entry.model } : {}) };
     }

package/dist/orchestrator/executor/index.js

@@ -879,6 +879,7 @@ export default function createExecutor(ledgers, options = {}) {
             if (exec && sleeping?.exec === exec) {
                 await fence(journal, exec, { park: a });
                 await release(exec);
+                await adoptAnswer(journal, t.callId, sleeping);
                 for (;;) {
                     if (interrupted(a) || has(journal, "timeout-intent", exec) || t.spec.timeoutMs !== undefined && activeTotal(journal.entries(), t.callId) >= t.spec.timeoutMs)
                         break;
@@ -908,6 +909,16 @@ export default function createExecutor(ledgers, options = {}) {
                 if (ev.budget || reached(totalUsage(journal.entries(), t.callId), t.spec.budget))
                     return finish(journal, t.callId, exec, makeResult("budget"));
                 if (!bound) {
+                    // P28: an execution cut off while its only unfinished tool call is the open question's `ask` (before it
+                    // hibernated) was waiting, not working: it hibernates now and resumes with the answer, like a planned
+                    // hibernation; it is neither a loss nor, for `once`, an unknown outcome.
+                    const asking = openQuestion(entries);
+                    const segment = entries.findLastIndex(e => e.type === "custom" && e.customType === CT.exec && e.data?.exec === exec);
+                    const ownQuestion = !!asking && segment >= 0 && entries.slice(segment + 1).some(e => e.customType === CT.question && e.data?.qid === asking.qid);
+                    if (asking && ownQuestion && dangling.length && dangling.every(d => d.startsWith("ask (")) && hibernation(journal, t.callId)?.exec !== exec) {
+                        await serial(() => journal.append("hibernated", { call: t.callId, exec, qid: asking.qid, rev: asking.rev }));
+                        continue;
+                    }
                     if (ev.report)
                         return finish(journal, t.callId, exec, buildCallResult({ key: t.key, gen: t.gen, status: ev.report.outcome, output: ev.text, usage: ev.usage,
                             ...(Object.hasOwn(ev.report, "data") ? { report: { data: ev.report.data } } : {}), ...(Array.isArray(ev.report.artifacts) ? { artifacts: ev.report.artifacts } : {}) }));
@@ -1038,6 +1049,37 @@ export default function createExecutor(ledgers, options = {}) {
             }
         }
     }
+    /**
+     * P28: an answer forwarded to the child while the question was still open but before the call hibernated (a restart
+     * or crash cut the asker off, or the planned hibernation fenced it first) never reached a live child. Once the call
+     * hibernates it is bound to the question like an answer given during hibernation; the forward is retired, so the
+     * reply "apply" already given (and any retry with the same rid) stays true.
+     */
+    async function adoptAnswer(journal, call, sleeping) {
+        const entries = await readCall(journal, call);
+        await serial(async () => {
+            const all = journal.entries();
+            if (all.some(e => e.type === "answer-bound" && e.call === call && e.qid === sleeping.qid && e.rev === sleeping.rev))
+                return;
+            const receipts = new Set(entries.map(receiptId).filter(rid => rid !== undefined));
+            const f = all.find(e => {
+                if (e.type !== "forward" || e.dest !== call)
+                    return false;
+                const env = e.envelope;
+                return env.kind === "answer" && env.cond?.qid === sleeping.qid && env.cond?.rev === sleeping.rev && !receipts.has(String(e.rid2)) &&
+                    !all.some(r => r.rid2 === e.rid2 && (r.type === "forward-retired" || r.type === "forward-delivered"));
+            });
+            if (!f)
+                return;
+            const item = attentionEntries(all).find(e => e.item.call === call && e.item.qid === sleeping.qid && e.item.rev === sleeping.rev)?.item;
+            const message = String(f.envelope.body?.message ?? "");
+            // A new identity: the stale answer may still sit in the child's inbox under the forward's rid2.
+            await journal.append("answer-bound", { call, qid: sleeping.qid, rev: sleeping.rev, rid: f.rid, rid2: contentHash([String(f.rid2), "hibernated"]), hash: f.hash,
+                message: `${HIBERNATED_NOTE}\n\nQuestion: ${item?.text ?? sleeping.qid}\nAnswer: ${message}` });
+            await journal.append("forward-retired", { rid: f.rid, rid2: f.rid2, reason: "bound-to-hibernation" });
+            await (await outbox).markResolved(String(f.rid2));
+        });
+    }
     async function replayForward(e) {
         const envelope = e.envelope;
         await (await outbox).send(envelope.to, envelope.kind, envelope.body, envelope.cond, { rid: String(e.rid2) });

package/dist/orchestrator/ledger.js

@@ -6,6 +6,8 @@
 //   config{hash,config}: the orchestrator settings in effect from here; config-rejected{error,hash?}: a change of
 //     config.json refused, while the earlier settings stay (cleared by the next config record).
 //   orchestrator{version,pid} / orchestrator-exit{pid}: the orchestrator running (its package version) and its exit.
+//   restart{rid,force,reason?,initiator?,from?,live}: accepted restart; the next start consumes its status provenance.
+//     Old records lack reason/initiator/from and remain readable (A1).
 //   writer-hold/writer-release{root,call}: the writer lock of a worktree root, held by one call until it ends.
 import { foldExhaustion } from "./providers.js";
 import { isEntry } from "../types.js";
@@ -31,8 +33,12 @@ export function applyLedger(state, e) {
     }
     else if (isEntry(e, "config-rejected"))
         state.rejected = { error: String(e.error), ts: e.ts };
-    else if (isEntry(e, "orchestrator"))
-        state.orchestrator = { version: String(e.version), pid: Number(e.pid), ...(e.start ? { start: String(e.start) } : {}), ts: e.ts, ...(e.restart === true ? { restart: true } : {}) };
+    else if (e.type === "restart")
+        state.pendingRestart = e.force === true ? { ts: e.ts, reason: e.reason, initiator: e.initiator, from: e.from } : undefined;
+    else if (isEntry(e, "orchestrator")) {
+        state.orchestrator = { version: String(e.version), pid: Number(e.pid), ...(e.start ? { start: String(e.start) } : {}), ts: e.ts, ...(e.restart === true ? { restart: true } : {}), ...(state.pendingRestart ? { forceRestart: state.pendingRestart } : {}) };
+        delete state.pendingRestart;
+    }
     else if (e.type === "writer-hold") {
         if (!state.writers.has(String(e.root)))
             state.writers.set(String(e.root), { call: String(e.call), ts: e.ts });
@@ -52,7 +58,7 @@ export function applyLedger(state, e) {
 export function foldLedger(state, entries) {
     // Journal readers keep the entry objects of a ledger as it grows (kernel/journal.ts), so identity tells them apart.
     if (state.seen && entries[state.seen - 1] !== state.last)
-        Object.assign(state, emptyLedger(), { config: undefined, rejected: undefined, orchestrator: undefined, last: undefined });
+        Object.assign(state, emptyLedger(), { config: undefined, rejected: undefined, orchestrator: undefined, pendingRestart: undefined, last: undefined });
     for (; state.seen < entries.length; state.seen++)
         applyLedger(state, entries[state.seen]);
     state.last = entries[state.seen - 1];

package/dist/orchestrator/restart.js

@@ -0,0 +1,57 @@
+// Restart guards shared by the orchestrator and the legacy client. The caller owns the launch gate;
+// these checks never change durable state. A1: only an accepted restart is appended to the ledger.
+import { contentHash } from "../kernel/ids.js";
+import { leaseCalls, leaseState } from "../platform/lease.js";
+export const subagentRestartError = "a subagent cannot force a restart: it would fence itself and other sessions' work; ask the user";
+export const restartToken = (live) => contentHash(live.map(l => l.exec).sort()).slice(0, 12);
+/** Old senders' boolean force is read only to refuse it when executions are live. */
+export const isForceRestart = (body) => body.token !== undefined || body.force === true;
+export function restartInputError(body, subagent = false) {
+    const force = isForceRestart(body);
+    if (force && (subagent || body.initiator && "call" in body.initiator))
+        return subagentRestartError;
+    // An old client's bare `force: true` carries no reason: it is never a force (no token) and is refused with the
+    // list of running executions, so it is not rejected for the missing reason first.
+    if ((body.token !== undefined || body.reason !== undefined) && (typeof body.reason !== "string" || !body.reason.trim() || body.reason.length > 500))
+        return "restart reason must be non-empty and at most 500 characters (force requires --reason)";
+    if (body.token !== undefined && (typeof body.token !== "string" || !/^[a-f0-9]{12}$/.test(body.token)))
+        return "restart force needs the 12-hex token from a refused restart; first show the user the running executions";
+    return undefined;
+}
+export function restartRefusal(home, live, body, tool = false, now = Date.now()) {
+    const invalid = restartInputError(body);
+    if (invalid)
+        return invalid;
+    if (!live.length)
+        return undefined;
+    const token = restartToken(live);
+    if (body.token === token)
+        return undefined;
+    const leases = leaseCalls(leaseState(home).map(r => ({ ...r, waiters: [] })), now);
+    const groups = new Map();
+    for (const l of live) {
+        const origin = l.origin ?? "unknown";
+        groups.set(origin, [...(groups.get(origin) ?? []), l]);
+    }
+    const age = (ms) => ms < 60_000 ? `${Math.max(0, Math.round(ms / 1000))}s` : `${Math.round(ms / 60_000)}m`;
+    return [
+        ...(body.token ? [`the running executions changed since ${body.token}`] : isForceRestart(body) ? ["force without a token is refused; first show the user the running executions"] : []),
+        `busy: ${live.length} running execution${live.length === 1 ? "" : "s"} — fencing them interrupts these sessions:`,
+        ...[...groups].sort(([a], [b]) => a.localeCompare(b)).flatMap(([origin, executions]) => [
+            `${origin}:`, ...executions.map(l => `  ${l.wid}/${l.key} ${age(now - l.since)}${l.phase === "gate" ? " gate" : ""}${leases.has(l.callId) ? ` ${leases.get(l.callId)}` : ""}`),
+        ]),
+        `token: ${token}`,
+        tool ? `to fence exactly these: subagents {action:"restart", force:"${token}", reason:"<why>"}` : `to fence exactly these: pi-durable-subagents restart --force ${token} --reason "<why>"`,
+    ].join("\n");
+}
+/** Status is one line even if the reason or parent command contained newlines. */
+export const restartLine = (s) => s.replace(/\s+/g, " ").trim();
+export function initiatorSummary(initiator, from) {
+    if (initiator && "call" in initiator)
+        return restartLine(initiator.call);
+    if (initiator && "origin" in initiator)
+        return restartLine(initiator.origin);
+    if (initiator && "cli" in initiator)
+        return restartLine(`cli:${initiator.cli.user}@${initiator.cli.host}`);
+    return restartLine(from ?? "unknown");
+}

package/dist/orchestrator/snapshot.js

@@ -1,5 +1,6 @@
 // Read-only status snapshots (P25: `status` is always a fresh snapshot). Pure readers of committed journals:
 // never depend on orchestrator memory, so the UI, the CLI and the main agent see the same durable state.
+import { initiatorSummary, restartLine } from "./restart.js";
 import { existsSync, readFileSync, readdirSync } from "node:fs";
 import { join } from "node:path";
 import { compileFanout } from "../compat/fanout.js";
@@ -492,11 +493,13 @@ const latestCalls = (wf) => [...new Map(wf.calls.map(c => [c.key, c])).values()]
 const ledgerStates = new Map();
 /** The orchestrator running now (its last `orchestrator` record, without an exit, whose process lives), and a note when
  *  its version is not the one this process loaded: running work stays on the version it started with. */
-export function orchestratorView(state, loaded = packageVersion()) {
+export function orchestratorView(state, loaded = packageVersion(), now = Date.now()) {
     const o = state.orchestrator;
     if (!o || o.exited || !processAlive(o.pid, o.start))
         return {};
-    return { orchestrator: `${o.version} (pid ${o.pid})`, ...(o.version === loaded ? {} : { versionNote: versionNote(o.version, loaded) }) };
+    const r = o.forceRestart, note = r && now - r.ts < 24 * 60 * 60_000
+        ? `; restarted by force ${age(now - r.ts)} ago by ${initiatorSummary(r.initiator, r.from)}: ${restartLine(r.reason ?? "no reason recorded")}` : "";
+    return { orchestrator: `${o.version} (pid ${o.pid})${note}`, ...(o.version === loaded ? {} : { versionNote: versionNote(o.version, loaded) }) };
 }
 /** Whether the recorded orchestrator still runs. On Linux its start time also tells it from a later process given the
  *  same pid after a crash (elsewhere the pid alone is checked). */
@@ -532,7 +535,7 @@ export function versionNote(running, loaded) {
         : `the orchestrator runs durable-subagents ${running}, this pi loaded ${loaded}: running work stays on ${running}. ` +
             `It exits about 10 s after all work ends and starts again on the installed version. To switch sooner: ` +
             `restart (\`pi-durable-subagents restart\` or the subagents tool's restart action) — refused while an execution runs, ` +
-            `calls waiting for an answer or a slot do not block it; force fences running executions, which resume on the new version`;
+            `calls waiting for an answer or a slot do not block it; force with the refusal's token, a reason and explicit user approval fences running executions, which resume on the new version`;
 }
 /** orchestratorView of the home's orchestrator ledger. */
 export function runningOrchestrator(home) {
@@ -553,7 +556,7 @@ export function slotsView(home, now = Date.now()) {
             holders.set(e.pool, (holders.get(e.pool) ?? 0) + 1);
     const names = [...new Set([...Object.keys(limits), ...holders.keys()])].sort();
     const slots = names.map(p => { const n = holders.get(p) ?? 0, limit = limits[p]?.slots; return typeof limit === "number" ? `${p} ${n}/${limit}` : `${p} ${n} (no limit)`; });
-    return { ...orchestratorView(state), ...(slots.length ? { slots } : {}), ...(config ? { config: `${config.hash} since ${age(now - config.ts)} ago` } : {}),
+    return { ...orchestratorView(state, packageVersion(), now), ...(slots.length ? { slots } : {}), ...(config ? { config: `${config.hash} since ${age(now - config.ts)} ago` } : {}),
         ...(exhausted.length ? { exhausted } : {}),
         ...(rejected ? { configRejected: `${clip(rejected.error, 200)} (${age(now - rejected.ts)} ago); ${config ? config.hash : "the start settings"} stay in effect` } : {}) };
 }

package/dist/orchestrator/store.js

@@ -5,8 +5,9 @@
 // revised {rid,revision,snapshot} commit publications; old pins remain immutable.
 // pruned {rid,wid,endedAt,bytes} (written by the engine) is decisive: the wid is gone, its create-intent and
 // created entries stay for identity (A1), and recovery finishes removing w/<wid> and its staging dirs.
-import { lstat, readdir, readFile, stat, rm } from 'node:fs/promises';
-import { readFileSync } from 'node:fs';
+import { lstat, open, readdir, readFile, rename, stat, rm } from 'node:fs/promises';
+import { createReadStream, readFileSync } from 'node:fs';
+import { createHash } from 'node:crypto';
 import { basename, extname, join, relative } from 'node:path';
 import { discoverAgents } from "../compat/agents.js";
 import { parseFrontmatter } from "../compat/frontmatter.js";
@@ -16,6 +17,36 @@ import { openJournal, syncDirectory } from "../kernel/journal.js";
 import { publishFile } from "../kernel/mailbox.js";
 import { journalPath, pinnedDir, workflowDir } from "../paths.js";
 import { JT } from "../types.js";
+/** Every file publishPins writes for one revision, relative to its directory (inputs given relative too). */
+function publishedFiles(inputs, origin) {
+    return [...new Set(['script.js', 'args.json', 'agents.json', 'inputs.json', ...inputs, ...(origin ? ['origin.jsonl'] : [])])];
+}
+/** sha256 of a file, streamed. */
+async function fileHash(path) {
+    const hash = createHash('sha256');
+    for await (const chunk of createReadStream(path))
+        hash.update(chunk);
+    return hash.digest('hex');
+}
+/** Replace `name` in `dir` atomically and durably (a cache record: last writer wins). */
+async function replaceFile(dir, name, text) {
+    const temp = join(dir, `.${ulid()}.tmp`), file = await open(temp, 'wx', 0o600);
+    try {
+        await file.writeFile(text);
+        await file.sync();
+    }
+    finally {
+        await file.close();
+    }
+    try {
+        await rename(temp, join(dir, name));
+    }
+    catch (error) {
+        await rm(temp, { force: true });
+        throw error;
+    }
+    await syncDirectory(dir);
+}
 // E3: errors of the machine rather than of the request; only these propagate, so the next intake retries the request.
 // Every other staging error (validation, missing input, ENAMETOOLONG, EACCES, ...) is deterministic: failure.json.
 // Conditions that clear without changing the request: retry at the next intake. Everything else is deterministic.
@@ -190,8 +221,10 @@ export class Store {
                     body = req.body;
                 snapshot = { hash: contentHash(req), pins: await prepareRun({ ...body, maxCalls: body.maxCalls ?? this.ledgers.config.k?.spawnBudget ?? 300 }, discovery, warnings),
                     ...(warnings.length ? { warnings } : {}) };
-                if (req.kind === 'revise')
-                    snapshot.pins.origin = this.workflows.get(req.body.wid)?.pins.origin;
+                if (req.kind === 'revise') {
+                    const prior = this.workflows.get(req.body.wid)?.originPath;
+                    snapshot.pins.origin = prior === undefined ? undefined : await readFile(prior, 'utf8');
+                }
             }
             catch (error) {
                 if (transient(error))
@@ -279,6 +312,10 @@ export class Store {
     async publishPins(wid, revision, pins) {
         const root = pinnedDir(this.ledgers.home, wid), dir = revision === 1 ? root : join(root, `r${revision}`);
         const publish = async (directory, name, bytes) => {
+            // Already published (a restart): compare without writing and syncing another copy.
+            const existing = await readFile(join(directory, name)).catch(() => undefined);
+            if (existing?.equals(typeof bytes === 'string' ? Buffer.from(bytes) : bytes))
+                return;
             if (await publishFile(directory, name, bytes) === 'conflict')
                 throw new Error(`Pinned content conflict: ${directory}/${name}`);
         };
@@ -294,15 +331,57 @@ export class Store {
             inputs[name] = join(dir, 'inputs', file);
         }
         await publish(dir, 'inputs.json', JSON.stringify(inputs));
-        return { pins, scriptPath: join(dir, 'script.js'), inputs };
+        const { origin, inputs: _bytes, ...kept } = pins;
+        return { pins: { ...kept, inputs: {} }, scriptPath: join(dir, 'script.js'), inputs, originPath: origin === undefined ? undefined : join(dir, 'origin.jsonl') };
+    }
+    /** A1: The pinned files of one revision. The first publication verifies the staged snapshot and ends with `pins.json`:
+     *  the in-memory pins and the sha256 of every published file, keyed by the snapshot hash. Later starts read that small
+     *  record instead of parsing and re-publishing the snapshot (which can hold a multi-megabyte origin branch per
+     *  workflow), and use it only when it is well formed, names this snapshot, its pins hash to its digest and every file
+     *  hashes as recorded — otherwise they take the snapshot path, whose byte comparison reports a changed file as a
+     *  conflict, and record it again. */
+    async pinnedFiles(wid, revision, intent) {
+        const dir = revision === 1 ? pinnedDir(this.ledgers.home, wid) : join(pinnedDir(this.ledgers.home, wid), `r${revision}`);
+        const ref = intent.pins ? undefined : intent.snapshot;
+        if (ref) {
+            const files = await this.recorded(dir, ref.hash).catch(() => undefined);
+            if (files)
+                return files;
+        }
+        const files = await this.publishPins(wid, revision, await this.pinned(intent));
+        if (ref) {
+            const hashes = {};
+            for (const name of publishedFiles(Object.values(files.inputs).map(path => relative(dir, path)), files.originPath !== undefined))
+                hashes[name] = await fileHash(join(dir, name));
+            const body = { snapshot: ref.hash, pins: files.pins,
+                inputs: Object.fromEntries(Object.entries(files.inputs).map(([name, path]) => [name, relative(dir, path)])), origin: files.originPath !== undefined, files: hashes };
+            await replaceFile(dir, 'pins.json', JSON.stringify({ ...body, digest: contentHash(body) }));
+        }
+        return files;
+    }
+    /** The files `pins.json` in `dir` records for snapshot `hash`, when the record and every file verify; else undefined. */
+    async recorded(dir, hash) {
+        const { digest, ...body } = JSON.parse(await readFile(join(dir, 'pins.json'), 'utf8'));
+        // The digest covers everything the record decides (pins, input names → files, origin, file hashes).
+        if (body.snapshot !== hash || typeof digest !== 'string' || contentHash(body) !== digest)
+            return undefined;
+        if (!body.pins || typeof body.pins !== 'object' || !body.inputs || typeof body.inputs !== 'object' || !body.files || typeof body.files !== 'object')
+            return undefined;
+        const names = publishedFiles(Object.values(body.inputs).map(String), body.origin === true);
+        if (names.length !== Object.keys(body.files).length || names.some(name => !Object.hasOwn(body.files, name)))
+            return undefined;
+        for (const name of names)
+            if (body.files[name] !== await fileHash(join(dir, name)))
+                return undefined;
+        return { pins: body.pins, scriptPath: join(dir, 'script.js'), inputs: Object.fromEntries(Object.entries(body.inputs).map(([name, file]) => [name, join(dir, String(file))])),
+            originPath: body.origin === true ? join(dir, 'origin.jsonl') : undefined };
     }
     /** P14, A2: Publish a new revision only after the engine has retired its predecessor. */
     async revise(intent) {
         const wf = this.workflows.get(intent.wid);
         if (wf.revision >= Number(intent.revision))
             return;
-        const pins = await this.pinned(intent), revision = Number(intent.revision);
-        const files = await this.publishPins(wf.wid, revision, pins);
+        const revision = Number(intent.revision), files = await this.pinnedFiles(wf.wid, revision, intent);
         await wf.journal.append('revised', { rid: intent.rid, revision, snapshot: intent.snapshot });
         Object.assign(wf, files, { revision });
     }
@@ -315,8 +394,7 @@ export class Store {
             : wf.journal.entries().find(e => e.type === 'revised' && e.revision === revision);
         if (!intent)
             throw new Error(`Missing pinned revision: ${wf.wid}@${revision}`);
-        const pins = await this.pinned(intent);
-        return { ...wf, revision, ...await this.publishPins(wf.wid, revision, pins) };
+        return { ...wf, revision, ...await this.pinnedFiles(wf.wid, revision, intent) };
     }
     /** A1, housekeeping: Wids with a committed pruned entry; they are gone and never materialize again. */
     pruned() { return new Set(this.ledgers.orch.entries().filter(e => e.type === 'pruned').map(e => String(e.wid))); }
@@ -368,7 +446,7 @@ export class Store {
             return existing;
         if (this.pruned().has(wid))
             throw new Error(`Workflow ${wid} was pruned`);
-        const pins = await this.pinned(intent), files = await this.publishPins(wid, 1, pins);
+        const files = await this.pinnedFiles(wid, 1, intent);
         const journal = await openJournal(journalPath(this.ledgers.home, wid));
         const wf = { wid, revision: 1, origin: intent.origin, cwd: intent.cwd, journal, ...files };
         this.workflows.set(wid, wf);
@@ -377,7 +455,7 @@ export class Store {
                 ...(intent.name !== undefined ? { name: intent.name } : {}) });
         const revised = journal.entries().findLast(e => e.type === 'revised');
         if (revised)
-            Object.assign(wf, await this.publishPins(wid, Number(revised.revision), await this.pinned(revised)), { revision: Number(revised.revision) });
+            Object.assign(wf, await this.pinnedFiles(wid, Number(revised.revision), revised), { revision: Number(revised.revision) });
         if (!this.ledgers.orch.entries().some(e => e.type === JT.created && e.rid === intent.rid))
             await this.ledgers.orch.append(JT.created, { rid: intent.rid, wid, origin: intent.origin });
         return wf;

package/dist/requests.js

@@ -0,0 +1,87 @@
+// R1: Caller-chosen request ids. A program names a run/send/stop with `<id>`; its kernel rid is `req:<id>` (fits the
+// mailbox rid pattern), unique per DSA_HOME across kinds and senders. A retry with the same id and the same content
+// (spec_digest) gets the first outcome; a different content is a request-conflict and is never published.
+// The check-and-send is serialized per home by the OS lock <home>/requests.lock (CLI and tool senders alike); no
+// journal entry type is added: the admitted orch `request` entry and the senders' outbox `sent` entries are the record.
+import { readdir } from 'node:fs/promises';
+import { join } from 'node:path';
+import { setTimeout as delay } from 'node:timers/promises';
+import { contentHash } from "./kernel/ids.js";
+import { readJournalSnapshot } from "./kernel/journal.js";
+import { publishRequest } from "./kernel/mailbox.js";
+import { OsLock } from "./platform/lock.js";
+import { orchInbox, orchLedger, outboxRoot } from "./paths.js";
+export const REQUEST_ID = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,123}$/;
+const PREFIX = 'req:';
+/** R1: `<id>` → its rid `req:<id>`; ids are 1–124 chars `[A-Za-z0-9][A-Za-z0-9._:-]*`. */
+export function requestRid(id) {
+    if (!REQUEST_ID.test(id))
+        throw new Error(`invalid request id ${JSON.stringify(id)}: 1-124 characters [A-Za-z0-9][A-Za-z0-9._:-]*`);
+    return PREFIX + id;
+}
+/** R1: The request id of a `req:<id>` rid; undefined for any other rid (ULIDs never contain ':'). */
+export function requestId(rid) { return rid.startsWith(PREFIX) ? rid.slice(PREFIX.length) : undefined; }
+/** R1: spec_digest = contentHash({kind, body, cond}) (cond omitted when absent). A run's body.origin (the pi session
+ *  branch offered for context:"fork") is delivery metadata, not spec: it differs on every turn, so it is not hashed. */
+export function specDigest(req) {
+    let body = req.body;
+    if (req.kind === 'run' && body && typeof body === 'object' && !Array.isArray(body)) {
+        const { origin: _, ...rest } = body;
+        body = rest;
+    }
+    return contentHash({ kind: req.kind, body, cond: req.cond });
+}
+/** R1: The envelope recorded for `rid`: the orchestrator's admitted copy (ledger `request`, kept after prune), else any
+ *  sender's outbox `sent` entry (published or about to be). Read-only. */
+export async function findRequest(home, rid) {
+    const admitted = readJournalSnapshot(orchLedger(home)).find(e => e.type === 'request' && e.request.rid === rid);
+    if (admitted)
+        return { request: admitted.request, admitted: true };
+    const dir = join(outboxRoot(home), 'outbox');
+    const names = await readdir(dir).catch(error => { if (error.code === 'ENOENT')
+        return []; throw error; });
+    for (const name of names.filter(n => n.endsWith('.jsonl')).sort()) {
+        const sent = readJournalSnapshot(join(dir, name)).find(e => e.type === 'sent' && e.request.rid === rid);
+        if (sent)
+            return { request: sent.request, admitted: false };
+    }
+    return undefined;
+}
+/** A lock was not free within 10 s: nothing was submitted by this attempt; a retry with the same id is safe. */
+export class RequestsBusy extends Error {
+    name = 'RequestsBusy';
+}
+/** R1, P5: Check-then-send under the home-wide request-id lock (innermost: taken after a sender's own lock), so no two
+ *  senders publish one rid and no second envelope with an existing rid and other content reaches the inbox (it would
+ *  stall its sender's sequence). Same content: the recorded envelope stands (republished when it is this sender's and
+ *  pending; `sent` false). */
+export async function sendIdentified(home, outbox, sender, rid, kind, body, cond) {
+    const digest = specDigest({ kind, body, cond }), path = join(home, 'requests.lock'), locker = new OsLock(), deadline = performance.now() + 10_000;
+    let lock = await locker.tryAcquire(path);
+    while (!lock && performance.now() < deadline) {
+        await delay(25);
+        lock = await locker.tryAcquire(path);
+    }
+    if (!lock)
+        throw new RequestsBusy('request ids are busy; retry the command');
+    try {
+        const prior = await findRequest(home, rid);
+        if (prior && specDigest(prior.request) !== digest)
+            return { conflict: prior.request, digest: specDigest(prior.request) };
+        if (prior) {
+            // Its own envelope is re-offered verbatim (Outbox.send returns it and republishes it while pending).
+            // Another sender's envelope not admitted yet is published verbatim (publishing is idempotent per rid): a sender
+            // that died between recording and publishing it would otherwise leave the id pending for ever.
+            let request = prior.request;
+            if (prior.request.from === sender)
+                request = await outbox.send(prior.request.to, prior.request.kind, prior.request.body, prior.request.cond, { rid });
+            else if (!prior.admitted)
+                await publishRequest(orchInbox(home), prior.request);
+            return { request, digest, sent: false };
+        }
+        return { request: await outbox.send('orch', kind, body, cond, { rid }), digest, sent: true };
+    }
+    finally {
+        await lock.release();
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-durable-subagents",
-  "version": "1.0.18",
+  "version": "1.0.21",
   "description": "Subagents for pi that never lose work and never do it twice. Crash-safe workflows, automatic recovery, and a live view just like the main agent.",
   "type": "module",
   "license": "MIT",