@fitchmultz/pi-subagents 0.52.17 → 0.52.19

package/dist/pi-intercom/inbound-delivery.js

@@ -131,7 +131,7 @@ export class InboundDeliveryOwner {
         const trigger = index === -1 ? undefined : rest.splice(index, 1)[0];
         const replyTarget = entries.find((entry) => entry.message.expectsReply === true) ?? trigger;
         if (replyTarget && this.journal.get(replyTarget.message.id) === replyTarget) {
-            this.hooks.replies.queueTurnContext({ ...replyTarget, receivedAt: Date.now() });
+            this.hooks.replies.queueTurnContext(replyTarget.message.id);
         }
         for (const entry of rest) {
             if (!this.live(generation)) {
@@ -218,11 +218,7 @@ export class InboundDeliveryOwner {
             this.journal.markNative(entry.message.id);
         }
         if (delivery !== "passive") {
-            this.hooks.replies.queueTurnContext({
-                from: entry.from,
-                message: entry.message,
-                receivedAt: Date.now(),
-            });
+            this.hooks.replies.queueTurnContext(entry.message.id);
         }
     }
     nativeMessage(entry) {

package/dist/pi-intercom/lifecycle.js

@@ -8,12 +8,8 @@ export function isContextRequest(value) {
 }
 /** Owns native context validity and occupancy, never journal or socket state. */
 export class IntercomLifecycle {
-    context = null;
-    sessionId = null;
+    state = { kind: "inactive", epoch: 0 };
     model = "unknown";
-    disposed = true;
-    epoch = 0;
-    incarnation = null;
     peerId = null;
     guardedDelivery = false;
     applicationGuard;
@@ -29,10 +25,10 @@ export class IntercomLifecycle {
         this.lineage = lineage;
     }
     get generation() {
-        return this.epoch;
+        return this.state.epoch;
     }
     get currentSessionId() {
-        return this.sessionId;
+        return this.state.kind === "inactive" ? null : this.state.sessionId;
     }
     get toolCount() {
         return this.tools.size;
@@ -64,7 +60,7 @@ export class IntercomLifecycle {
         request.respond(this.snapshot());
     }
     snapshot() {
-        if (!this.live()) {
+        if (this.state.kind !== "live" || !this.live()) {
             return {
                 version: 1,
                 rootSessionId: null,
@@ -76,10 +72,10 @@ export class IntercomLifecycle {
         }
         return {
             version: 1,
-            rootSessionId: this.lineage?.rootSessionId ?? this.sessionId,
+            rootSessionId: this.lineage?.rootSessionId ?? this.state.sessionId,
             parentSessionId: this.lineage?.parentSessionId,
             peerId: this.peerId,
-            incarnation: this.incarnation,
+            incarnation: this.state.incarnation,
             connected: this.peerId !== null,
             guardedDelivery: this.guardedDelivery ? 1 : null,
             applicationGuard: this.applicationGuard,
@@ -107,36 +103,40 @@ export class IntercomLifecycle {
             this.applicationGuard === guard.applicationGuard);
     }
     start(ctx) {
-        this.disposed = false;
-        this.epoch += 1;
-        this.context = ctx;
-        this.sessionId = ctx.sessionManager.getSessionId();
-        this.incarnation = randomUUID();
+        this.state = {
+            kind: "live",
+            epoch: this.state.epoch + 1,
+            context: ctx,
+            sessionId: ctx.sessionManager.getSessionId(),
+            incarnation: randomUUID(),
+        };
         this.applicationGuard = undefined;
         this.model = ctx.model?.id ?? "unknown";
         this.running = false;
         this.activity = 0;
         this.tools.clear();
         this.transport(null);
-        return this.epoch;
+        return this.state.epoch;
     }
     invalidate() {
-        this.disposed = true;
-        this.epoch += 1;
+        const epoch = this.state.epoch + 1;
+        this.state =
+            this.state.kind === "inactive"
+                ? { kind: "inactive", epoch }
+                : { kind: "invalidated", epoch, sessionId: this.state.sessionId };
         this.running = false;
         this.tools.clear();
         this.publishContext();
     }
     clear() {
-        this.context = null;
-        this.sessionId = null;
+        this.state = { kind: "inactive", epoch: this.state.epoch };
     }
-    live(ctx = this.context, generation = this.epoch) {
-        if (this.disposed || generation !== this.epoch || !ctx) {
+    live(ctx = this.state.kind === "live" ? this.state.context : null, generation = this.state.epoch) {
+        if (this.state.kind !== "live" || generation !== this.state.epoch || !ctx) {
             return null;
         }
         try {
-            if (this.sessionId !== null && ctx.sessionManager.getSessionId() !== this.sessionId) {
+            if (ctx.sessionManager.getSessionId() !== this.state.sessionId) {
                 return null;
             }
             // Reading a native property detects invalidated contexts without modifying them.
@@ -209,12 +209,12 @@ export class IntercomLifecycle {
     }
     async registration(pendingAsks) {
         const live = this.live();
-        if (!live || this.sessionId === null) {
+        if (!live || this.state.kind !== "live") {
             throw new Error("Intercom runtime not initialized");
         }
         return {
-            ...this.identity(this.sessionId),
-            incarnation: this.incarnation ?? undefined,
+            ...this.identity(this.state.sessionId),
+            incarnation: this.state.incarnation,
             guardedDelivery: 1,
             applicationGuard: this.applicationGuard,
             cwd: live.cwd,

package/dist/pi-intercom/reply-tracker.js

@@ -55,9 +55,9 @@ function replyBySender(contexts, to) {
 }
 export class ReplyTracker {
     pendingAsks = new Map();
-    pendingTurnContexts = [];
-    currentTurnContext = null;
-    activeAgentContext = null;
+    pendingTurnIds = [];
+    currentTurnId = null;
+    activeAgentId = null;
     askTimeoutMs;
     constructor(askTimeoutMs = 10 * 60 * 1000) {
         this.askTimeoutMs = askTimeoutMs;
@@ -70,61 +70,58 @@ export class ReplyTracker {
         }
         return context;
     }
-    queueTurnContext(context) {
-        if (context.message.expectsReply !== true) {
+    queueTurnContext(messageId) {
+        if (!this.pendingAsks.has(messageId) || this.hasTurnContext(messageId)) {
             return;
         }
-        if (this.hasTurnContext(context.message.id)) {
-            return;
-        }
-        this.pendingTurnContexts.push(context);
+        this.pendingTurnIds.push(messageId);
     }
     beginTurn(now = Date.now()) {
         this.pruneExpired(now);
-        this.currentTurnContext = this.pendingTurnContexts.shift() ?? null;
-        if (this.currentTurnContext) {
-            this.activeAgentContext = this.currentTurnContext;
+        this.currentTurnId = this.pendingTurnIds.shift() ?? null;
+        if (this.currentTurnId !== null) {
+            this.activeAgentId = this.currentTurnId;
         }
     }
     currentTurn() {
-        return this.currentTurnContext ?? this.activeAgentContext;
+        const id = this.currentTurnId ?? this.activeAgentId;
+        return id === null ? null : (this.pendingAsks.get(id) ?? null);
     }
     endTurn() {
-        this.currentTurnContext = null;
+        this.currentTurnId = null;
     }
     endAgent() {
-        this.currentTurnContext = null;
-        this.activeAgentContext = null;
+        this.currentTurnId = null;
+        this.activeAgentId = null;
     }
     reset() {
         this.pendingAsks.clear();
-        this.pendingTurnContexts.length = 0;
-        this.currentTurnContext = null;
-        this.activeAgentContext = null;
+        this.pendingTurnIds.length = 0;
+        this.endAgent();
     }
     expireSender(sessionId) {
-        const expires = (context) => context.from.id === sessionId;
+        const expiring = new Set([...this.pendingAsks.values()]
+            .filter((context) => context.from.id === sessionId)
+            .map((context) => context.message.id));
         let expired = 0;
-        for (const [messageId, context] of this.pendingAsks) {
-            if (expires(context)) {
-                this.pendingAsks.delete(messageId);
-                expired += 1;
-            }
+        for (const messageId of expiring) {
+            this.pendingAsks.delete(messageId);
+            expired += 1;
         }
-        const beforeQueued = this.pendingTurnContexts.length;
-        for (let index = this.pendingTurnContexts.length - 1; index >= 0; index -= 1) {
-            const context = this.pendingTurnContexts[index];
-            if (context !== undefined && expires(context)) {
-                this.pendingTurnContexts.splice(index, 1);
+        const beforeQueued = this.pendingTurnIds.length;
+        for (let index = this.pendingTurnIds.length - 1; index >= 0; index -= 1) {
+            const id = this.pendingTurnIds[index];
+            if (id !== undefined && expiring.has(id)) {
+                this.pendingTurnIds.splice(index, 1);
             }
         }
-        expired += beforeQueued - this.pendingTurnContexts.length;
-        if (this.currentTurnContext && expires(this.currentTurnContext)) {
-            this.currentTurnContext = null;
+        expired += beforeQueued - this.pendingTurnIds.length;
+        if (this.currentTurnId !== null && expiring.has(this.currentTurnId)) {
+            this.currentTurnId = null;
             expired += 1;
         }
-        if (this.activeAgentContext && expires(this.activeAgentContext)) {
-            this.activeAgentContext = null;
+        if (this.activeAgentId !== null && expiring.has(this.activeAgentId)) {
+            this.activeAgentId = null;
             expired += 1;
         }
         return expired;
@@ -132,26 +129,21 @@ export class ReplyTracker {
     resolveReplyTarget(options, now = Date.now()) {
         this.pruneExpired(now);
         const pending = Array.from(this.pendingAsks.values());
-        const contexts = this.currentTurnContext
-            ? [
-                this.currentTurnContext,
-                ...pending.filter((context) => context.message.id !== this.currentTurnContext?.message.id),
-            ]
-            : pending;
         const replyTo = options.replyTo ?? "";
         const to = options.to ?? "";
         if (replyTo !== "") {
-            return explicitReply(contexts, replyTo, to);
+            return explicitReply(pending, replyTo, to);
         }
         if (to !== "") {
-            return replyBySender(contexts, to);
+            return replyBySender(pending, to);
         }
         return this.implicitReplyTarget(pending);
     }
     /** Without an explicit target, the turn context wins, then a sole pending ask. */
     implicitReplyTarget(pending) {
-        if (this.currentTurnContext) {
-            return this.currentTurnContext;
+        const current = this.currentTurnId === null ? undefined : this.pendingAsks.get(this.currentTurnId);
+        if (current) {
+            return current;
         }
         const [solePending] = pending;
         if (pending.length === 1 && solePending !== undefined) {
@@ -170,22 +162,22 @@ export class ReplyTracker {
         return Array.from(this.pendingAsks.values()).sort((a, b) => a.receivedAt - b.receivedAt);
     }
     hasTurnContext(messageId) {
-        return (this.pendingTurnContexts.some((context) => context.message.id === messageId) ||
-            this.currentTurnContext?.message.id === messageId ||
-            this.activeAgentContext?.message.id === messageId);
+        return (this.pendingTurnIds.includes(messageId) ||
+            this.currentTurnId === messageId ||
+            this.activeAgentId === messageId);
     }
     removeContext(messageId) {
         this.pendingAsks.delete(messageId);
-        for (let index = this.pendingTurnContexts.length - 1; index >= 0; index -= 1) {
-            if (this.pendingTurnContexts[index]?.message.id === messageId) {
-                this.pendingTurnContexts.splice(index, 1);
+        for (let index = this.pendingTurnIds.length - 1; index >= 0; index -= 1) {
+            if (this.pendingTurnIds[index] === messageId) {
+                this.pendingTurnIds.splice(index, 1);
             }
         }
-        if (this.currentTurnContext?.message.id === messageId) {
-            this.currentTurnContext = null;
+        if (this.currentTurnId === messageId) {
+            this.currentTurnId = null;
         }
-        if (this.activeAgentContext?.message.id === messageId) {
-            this.activeAgentContext = null;
+        if (this.activeAgentId === messageId) {
+            this.activeAgentId = null;
         }
     }
     pruneExpired(now) {

package/dist/pi-intercom/session-events.js

@@ -46,6 +46,8 @@ export class IntercomSessionEvents {
         if (client?.isConnected() !== true ||
             !context ||
             context.message.expectsReply !== true ||
+            // A native turn can start without consuming its queued input after an abort.
+            journal.get(context.message.id) !== undefined ||
             error === null ||
             error === "") {
             return;

package/dist/shared/post-exit-stdio-guard.js

@@ -280,12 +280,13 @@ export function attachChildProcessLifecycle(child) {
     return new OwnedChildLifecycle(child);
 }
 function attachPostExitStdioGuard(child) {
-    let exited = false;
+    let state = { kind: "waiting" };
     let stdoutEnded = false;
     let stderrEnded = false;
-    let idleTimer;
-    let hardTimer;
     const destroyUnendedStdio = () => {
+        if (state.kind !== "draining") {
+            return;
+        }
         if (!stdoutEnded) {
             try {
                 child.stdout?.destroy();
@@ -302,51 +303,57 @@ function attachPostExitStdioGuard(child) {
                 // The process has exited; failed pipe destruction must not prevent other cleanup.
             }
         }
-    };
-    const clearTimers = () => {
-        if (idleTimer) {
-            clearTimeout(idleTimer);
-            idleTimer = undefined;
-        }
-        if (hardTimer) {
-            clearTimeout(hardTimer);
-            hardTimer = undefined;
-        }
+        cleanup();
     };
     const armIdleTimer = () => {
-        if (!exited) {
+        if (state.kind !== "draining") {
             return;
         }
-        if (idleTimer) {
-            clearTimeout(idleTimer);
-        }
-        idleTimer = setTimeout(destroyUnendedStdio, 2000);
-        idleTimer.unref();
+        clearTimeout(state.idle);
+        state.idle = setTimeout(destroyUnendedStdio, 2000);
+        state.idle.unref();
     };
-    child.stdout?.on("data", armIdleTimer);
-    child.stderr?.on("data", armIdleTimer);
-    child.stdout?.on("end", () => {
+    const stdoutEnd = () => {
         stdoutEnded = true;
         if (stderrEnded) {
-            clearTimers();
+            cleanup();
         }
-    });
-    child.stderr?.on("end", () => {
+    };
+    const stderrEnd = () => {
         stderrEnded = true;
         if (stdoutEnded) {
-            clearTimers();
+            cleanup();
         }
-    });
-    child.on("exit", () => {
-        exited = true;
-        armIdleTimer();
-        if (hardTimer) {
+    };
+    const exited = () => {
+        if (state.kind !== "waiting") {
             return;
         }
-        hardTimer = setTimeout(destroyUnendedStdio, 8000);
-        hardTimer.unref();
-    });
-    child.on("close", clearTimers);
-    child.on("error", clearTimers);
-    return clearTimers;
+        const hard = setTimeout(destroyUnendedStdio, 8000);
+        hard.unref();
+        state = { kind: "draining", idle: undefined, hard };
+        armIdleTimer();
+    };
+    function cleanup() {
+        if (state.kind === "draining") {
+            clearTimeout(state.idle);
+            clearTimeout(state.hard);
+        }
+        state = { kind: "closed" };
+        child.stdout?.off("data", armIdleTimer);
+        child.stderr?.off("data", armIdleTimer);
+        child.stdout?.off("end", stdoutEnd);
+        child.stderr?.off("end", stderrEnd);
+        child.off("exit", exited);
+        child.off("close", cleanup);
+        child.off("error", cleanup);
+    }
+    child.stdout?.on("data", armIdleTimer);
+    child.stderr?.on("data", armIdleTimer);
+    child.stdout?.on("end", stdoutEnd);
+    child.stderr?.on("end", stderrEnd);
+    child.on("exit", exited);
+    child.on("close", cleanup);
+    child.on("error", cleanup);
+    return cleanup;
 }

package/docs/development.md

@@ -23,6 +23,12 @@ Run narrow owner-boundary tests locally through `scripts/run-tests.mjs`. Full
 `npm run ci` belongs in hosted CI and includes package/install smokes and the
 complete suites. Keep the strict Oxlint/Oxfmt rules; see [code quality](code-quality.md).
 
+Builds compile into process-owned staging before replacing `dist`. If a publisher
+exits after retiring the previous build, later builds preserve its complete
+`.previous` tree until a new complete build publishes. A failed build reports
+the retained recovery paths. Recovery never promotes an older backup into a
+concurrent publisher's retirement gap or reaps live or uncertain owners.
+
 ## Native Android/Termux
 
 Use app-private storage, not Android's shared `/sdcard` filesystem. No Termux app
@@ -80,6 +86,25 @@ npm and attached to the matching GitHub release.
 
 ## Isolation and safety
 
+Parent attachment keeps one binding through detached, waiting, attaching and
+attached phases. The existing shutdown signal closes the owner. Managed
+readiness can attach only its own still-current waiting binding; shutdown joins
+admitted publication before releasing the matching generation.
+
+Parking returns resident, exit-with-parked-authority or exit-after-failed-save.
+Both exit outcomes have disposed the native runtime and must exit the actor;
+neither permits a second ordinary disposal. Restore tracks unopened, opening
+and adopted phases, keeping the exact saved cut with the phase that owns it.
+
+Directory watches distinguish unarmed, armed-to-one-inode and polling-only
+availability. Missing paths can be armed later; unsupported or failed native
+watches keep the existing polling fallback. Each coalesced Wake has one waiting
+owner loop.
+
+Smoke child cleanup treats leader exit and pipe closure separately. Pipe draining
+has waiting, draining and closed phases. Closing it cancels its deadlines and
+detaches its listeners, so later events cannot restart cleanup.
+
 Every test/smoke broker uses a short, explicit `PI_INTERCOM_RUNTIME_DIR` owned by
 the fixture. Do not touch `/tmp/pi-intercom-<uid>` to test namespace behavior on a
 workstation with active sessions. Tests for the default path inspect it without

package/docs/intercom.md

@@ -330,13 +330,20 @@ not an end-to-end exactly-once guarantee for arbitrary tool side effects.
 
 Idle recovery preserves admission order within the non-passive backlog and wakes
 once on its last item; passive breadcrumbs are appended before that waking work.
-The first eligible ask remains the implicit reply target, independently of which
-message triggers the turn. A busy recipient's steer is handed to Pi's native
+The first unresolved eligible ask remains the implicit reply target, independently
+of which message triggers the turn. Reply attribution refers to the unresolved
+ask by ID. Placing delayed input does not revive an already replied, expired, or
+retired reply obligation. A failed turn can retire only an ask whose input Pi has
+consumed; queued input remains answerable after abort recovery.
+A busy recipient's steer is handed to Pi's native
 queue and consumed at its next tool boundary; no extension probe asks another
 tool to give up the turn.
 
 Shutdown joins admitted inbound work before detaching its native owner. Stale
 runtime generations must not checkpoint or deliver into a replacement session.
+Context state is inactive, live with its session and incarnation, or invalidated
+while transport cleanup retains the session ID. Clearing cleanup drops that ID;
+transport connection and native tool activity remain separate from context validity.
 The native tests own these contracts; neither a timer nor a source-string test is
 publication evidence.
 
@@ -392,4 +399,14 @@ records include native boot/namespace/start identity to reject proven PID reuse;
 ambiguous legacy numeric PIDs remain blocking. A process is never killed merely
 to recover broker startup.
 
+Startup distinguishes absent, live and uncertain ownership. An unreadable or
+invalid PID record is uncertain, not permission to launch another broker.
+A startup claim stays owned while its process is live, regardless of age.
+Only a proven exited or replaced owner permits reclaiming it. Linux claims carry
+the same native process identity as broker PID records. Legacy or incomparable
+identities remain blocking; a timestamp alone cannot prove PID reuse.
+Each starter keeps the claim's
+file descriptor open and releases only the same device/inode, leaving a
+replacement claim untouched.
+
 Remote authenticated mail is separate: see [bridge setup](intercom-bridge.md).

package/docs/reference.md

@@ -12,6 +12,7 @@ delegate({
   name: "optional-readable-name",
   cwd: "/optional/working/directory",
   model: "provider/model",
+  thinking: "low",
   context: "fresh",
 });
 ```
@@ -21,19 +22,27 @@ canned profile. `name` is an optional display name, not a unique identity or rol
 Omitted cwd/model inherit the invoking session's effective selection. A supplied
 model must be available; there is no hidden alternate-model retry catalog.
 
+`thinking` accepts `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, or `max`.
+It overrides parent effort for this child without changing the parent. It works
+with an omitted model or a literal model ID on every supported host, including
+official Pi 1.5.0. Omission preserves inherited effort. Pi applies its native
+model-capability clamping; the launch receipt records the requested value, not
+proof of the child's effective effort.
+
 On hosts exporting Pi's native `resolveModelReference`, `model` also accepts
 `provider/model:thinking` (for example `provider/model:low` or `provider/model:off`).
-The explicit suffix overrides inherited thinking for that child only. Literal
+The explicit suffix overrides inherited thinking for that child only. If both
+`thinking` and a suffix specify effort, they must match or the launch fails. Literal
 model IDs take precedence, including IDs containing colons or additional slashes;
 unknown IDs and invalid suffixes fail without fuzzy matching or another provider.
 Native resolution follows Pi's case-insensitive ID matching. Pi still applies the
 selected model's native thinking capabilities.
 
 Official Pi, including 1.5.0, does not export that resolver. Older fork runtimes also
-lack the export. Those hosts retain
-case-sensitive literal-ID overrides and inherited thinking; suffix requests fail with an upgrade
-message rather than being parsed by an extension-side replacement. This requires
-a host with the public resolver export, not merely a matching version number.
+lack the export. Those hosts retain case-sensitive literal-ID overrides and
+support the `thinking` field. Suffix requests fail with an upgrade message rather
+than being parsed by an extension-side replacement. Suffix support requires a
+host with the public resolver export, not merely a matching version number.
 
 Fresh context is the default. Fork uses the native conversation, including
 historical tool calls and results; restricting a child's authority does not erase
@@ -58,6 +67,8 @@ tool or programmatic invocation of `delegate` or `agent_runs`.
 
 Saved runs belong to the native main session that launched them, not its cwd,
 project, display name, or a different session forked from its history.
+Live guidance and saved-run successors keep the child's saved effort even if the
+parent's effort has changed.
 
 | Action     | Purpose                                                                              |
 | ---------- | ------------------------------------------------------------------------------------ |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fitchmultz/pi-subagents",
-  "version": "0.52.17",
+  "version": "0.52.19",
   "description": "Pi extension for subagent orchestration and local session coordination",
   "license": "MIT",
   "type": "module",

package/scripts/build.mjs

@@ -67,21 +67,37 @@ async function hasPublishedDist(/** @type {string} */ path) {
   }
 }
 
-async function reapStrandedStaging(/** @type {string} */ cwd) {
+/**
+ * @param {string} cwd
+ * @param {import("node:fs").Dirent} entry
+ * @returns {{ path: string, kind: "staging" | "previous" } | undefined}
+ */
+function strandedBuild(cwd, entry) {
   // Signal 0 proves only that the owner was gone at probe time. Pid reuse
   // between this probe and removal is inherent to pid-based reaping.
-  for (const entry of await readdir(cwd, { withFileTypes: true })) {
-    const match = /^dist\.staging\.(\d+)(?:\.previous)?$/.exec(entry.name);
-    if (!match || !entry.isDirectory()) {
-      continue;
-    }
-    const ownerPid = Number(match[1]);
-    if (ownerPid === process.pid || !isOwnerGone(ownerPid)) {
-      continue;
+  const match = /^dist\.staging\.(\d+)(\.previous)?$/.exec(entry.name);
+  if (!match || !entry.isDirectory()) {
+    return;
+  }
+  const ownerPid = Number(match[1]);
+  if (ownerPid === process.pid || !isOwnerGone(ownerPid)) {
+    return;
+  }
+  return { path: join(cwd, entry.name), kind: match[2] === undefined ? "staging" : "previous" };
+}
+
+async function reapStrandedBuilds(/** @type {string} */ cwd) {
+  const stranded = (await readdir(cwd, { withFileTypes: true })).flatMap((entry) => {
+    const build = strandedBuild(cwd, entry);
+    return build ? [build] : [];
+  });
+  for (const entry of stranded) {
+    if (entry.kind === "staging") {
+      await discardStaging(entry.path);
     }
-    // Reap abandoned trees sequentially to bound filesystem removal pressure.
-    await discardStaging(join(cwd, entry.name));
   }
+  // Never promote rollback material into another live publisher's retirement gap.
+  return stranded.filter((entry) => entry.kind === "previous").map((entry) => entry.path);
 }
 
 async function compileProject(
@@ -208,13 +224,24 @@ async function publishStaging(/** @type {string} */ stagingDir, /** @type {strin
 async function main() {
   const cwd = process.cwd();
   const compiler = compilerInvocation(process.argv[2]);
-  await reapStrandedStaging(cwd);
+  const previous = await reapStrandedBuilds(cwd);
   // Pid-scoped staging isolates concurrent emits; only a complete tree publishes.
   const stagingDir = join(cwd, `dist.staging.${process.pid}`);
   await rm(stagingDir, RM_OPTIONS);
   await rm(`${stagingDir}.previous`, RM_OPTIONS);
-  await compileToStaging(cwd, stagingDir, compiler);
-  await publishStaging(stagingDir, join(cwd, "dist"));
+  try {
+    await compileToStaging(cwd, stagingDir, compiler);
+    await publishStaging(stagingDir, join(cwd, "dist"));
+  } catch (error) {
+    for (const retained of previous.filter(existsSync)) {
+      console.warn(`Previous build retained for recovery: ${retained}`);
+    }
+    throw error;
+  }
+  // A complete published winner now replaces these older rollback candidates.
+  for (const retired of previous) {
+    await discardStaging(retired);
+  }
 }
 
 main().catch((/** @type {unknown} */ error) => {