@naxodev/apnea 0.2.1 → 0.2.2

package/SECURITY.md

@@ -25,12 +25,16 @@ this tool at a repository.
   the ref moves, so index failure cannot advance the branch. An unrelated external Git process can
   still race that real-index replacement; the repository lock coordinates Apnea processes, not
   arbitrary Git clients.
-- **Repository locks identify owners by PID plus a random token.** The token prevents one owner
-  from deleting a replacement lock. Apnea never reclaims dead or malformed locks automatically:
-  it reports the validated lock path and requires manual cleanup after the user verifies no owner
-  remains. PID reuse can keep a dead lock looking live because there is no portable
-  process-creation identity across supported platforms; this also fails closed. Global setup waits
-  only when the recorded PID is currently live; it never retries stale or malformed ownership.
+- **Repository locks identify owners by PID plus a random token.** Apnea reclaims a valid dead
+  owner after the grace period. An atomic `<lock-path>.reclaim` directory serializes stale
+  removers across their token check and canonical rename, preserving every replacement owner.
+  A crashed remover can leave this guard behind. Apnea never reclaims the guard automatically:
+  doing so would introduce the same ownership race. If an error reports a stranded guard, stop
+  all Apnea processes using that lock before manually removing the reported guard path.
+  Malformed locks require manual cleanup after verifying that no owner remains. PID reuse can
+  keep a dead lock looking live because there is no portable process-creation identity across
+  supported platforms; this also fails closed. Global setup waits only when the recorded PID is
+  currently live; it never retries stale or malformed ownership.
 - **Setup serializes account-global configuration and role resources.** Every setup holds one
   same-user lock keyed by the canonical account home for its full read/merge/write and role-agent
   materialization. Setup takes this global lock before an optional repository lock. Global config

package/dist/cli.js

@@ -28818,6 +28818,9 @@ function acquireRolePane(processService, role, hostAdapter, opts) {
       });
     }
     if (opts?.prefer?.pane_id && (yield* paneGet(processService, opts.prefer.pane_id)).ok) {
+      if (opts.beforeDelivery) {
+        yield* exports_Effect.uninterruptible(opts.beforeDelivery(opts.prefer));
+      }
       return {
         pane_id: opts.prefer.pane_id,
         label: opts.prefer.label,
@@ -28826,14 +28829,26 @@ function acquireRolePane(processService, role, hostAdapter, opts) {
     }
     const millis2 = yield* exports_Clock.currentTimeMillis;
     const label = roleLabel(role, millis2);
-    const split = yield* exports_Effect.result(splitPane(processService));
-    if (exports_Result.isFailure(split)) {
-      return yield* withLaunchDetails(split.failure, {
-        delivery: split.failure.details?.delivery === "unknown" ? "unknown" : "not_delivered",
-        newly_created: false
-      });
-    }
-    const paneId = split.success;
+    const paneId = yield* exports_Effect.uninterruptible(exports_Effect.gen(function* () {
+      const split = yield* exports_Effect.result(splitPane(processService));
+      if (exports_Result.isFailure(split)) {
+        if (split.failure.details?.delivery !== "unknown") {
+          yield* opts?.onAcquisitionFailure?.() ?? exports_Effect.void;
+        }
+        return yield* withLaunchDetails(split.failure, {
+          delivery: split.failure.details?.delivery === "unknown" ? "unknown" : "not_delivered",
+          newly_created: false
+        });
+      }
+      const paneId2 = split.success;
+      if (opts?.beforeDelivery) {
+        const persisted = yield* exports_Effect.result(opts.beforeDelivery({ pane_id: paneId2, label }));
+        if (exports_Result.isFailure(persisted)) {
+          return yield* cleanupFailedInteractiveLaunch(persisted.failure, paneId2, (id3) => paneClose(processService, id3));
+        }
+      }
+      return paneId2;
+    }));
     const prepared = yield* exports_Effect.result(exports_Effect.gen(function* () {
       yield* renamePane(processService, paneId, label);
       if (!opts?.interactiveCmd?.length)
@@ -28860,7 +28875,7 @@ function acquireRolePane(processService, role, hostAdapter, opts) {
     return { pane_id: paneId, label, reused: false };
   });
 }
-function runInteractivePromptImpl(processService, hostAdapter, role, interactiveCmd, prompt, prefer) {
+function runInteractivePromptImpl(processService, hostAdapter, role, interactiveCmd, prompt, prefer, beforeDelivery, onAcquisitionFailure) {
   return exports_Effect.gen(function* () {
     let preferUse = null;
     if (prefer?.pane_id) {
@@ -28871,25 +28886,42 @@ function runInteractivePromptImpl(processService, hostAdapter, role, interactive
     }
     const acquired = yield* acquireRolePane(processService, role, hostAdapter, {
       prefer: preferUse,
-      interactiveCmd: preferUse ? undefined : interactiveCmd
+      interactiveCmd: preferUse ? undefined : interactiveCmd,
+      beforeDelivery,
+      onAcquisitionFailure
     });
-    if (!acquired.reused) {
-      yield* waitAgentReady(processService, acquired.pane_id, 90000);
-    } else {
-      const st = (yield* paneGet(processService, acquired.pane_id)).agent_status;
-      if (st !== "idle" && st !== "done") {
-        yield* waitAgentReady(processService, acquired.pane_id, 30000);
+    const ready = yield* exports_Effect.result(exports_Effect.gen(function* () {
+      if (!acquired.reused) {
+        yield* waitAgentReady(processService, acquired.pane_id, 90000);
+      } else {
+        const st = (yield* paneGet(processService, acquired.pane_id)).agent_status;
+        if (st !== "idle" && st !== "done") {
+          yield* waitAgentReady(processService, acquired.pane_id, 30000);
+        }
       }
+      const beforePrompt = hostAdapter.beforeInteractivePrompt?.(interactiveCmd);
+      if (beforePrompt) {
+        yield* exports_Effect.gen(function* () {
+          yield* paneRun(processService, acquired.pane_id, beforePrompt);
+          yield* waitAgentReady(processService, acquired.pane_id, 5000);
+          yield* exports_Effect.sleep(300);
+        }).pipe(exports_Effect.ignore);
+      }
+    }));
+    if (exports_Result.isFailure(ready)) {
+      if (!acquired.reused) {
+        return yield* cleanupFailedInteractiveLaunch(ready.failure, acquired.pane_id, (id3) => paneClose(processService, id3));
+      }
+      return yield* withLaunchDetails(ready.failure, {
+        delivery: "not_delivered"
+      });
     }
-    const beforePrompt = hostAdapter.beforeInteractivePrompt?.(interactiveCmd);
-    if (beforePrompt) {
-      yield* exports_Effect.gen(function* () {
-        yield* paneRun(processService, acquired.pane_id, beforePrompt);
-        yield* waitAgentReady(processService, acquired.pane_id, 5000);
-        yield* exports_Effect.sleep(300);
-      }).pipe(exports_Effect.ignore);
-    }
-    const submitted = yield* exports_Effect.result(paneRun(processService, acquired.pane_id, prompt));
+    const submitted = yield* exports_Effect.result(exports_Effect.gen(function* () {
+      yield* paneRun(processService, acquired.pane_id, prompt);
+      return yield* ensurePromptSubmitted(acquired.pane_id, prompt, {
+        processService
+      });
+    }));
     if (exports_Result.isFailure(submitted)) {
       return yield* withLaunchDetails(submitted.failure, {
         delivery: "unknown",
@@ -28898,9 +28930,7 @@ function runInteractivePromptImpl(processService, hostAdapter, role, interactive
         reused: acquired.reused
       });
     }
-    const submit = yield* ensurePromptSubmitted(acquired.pane_id, prompt, {
-      processService
-    });
+    const submit = submitted.success;
     return {
       pane_id: acquired.pane_id,
       label: acquired.label,
@@ -30747,7 +30777,7 @@ function acquireLock(lock, resource, reclaim) {
         pid: existing.pid
       });
     }
-    if (reclaim !== undefined && lockAgeMs(lock, reclaim.now()) >= reclaim.graceMs && removeStaleOwner(lock, existing.token)) {
+    if (reclaim !== undefined && lockAgeMs(lock, reclaim.now()) >= reclaim.graceMs && removeStaleOwner(lock, existing.token, resource)) {
       continue;
     }
     throw new OperationLocked({
@@ -30773,12 +30803,30 @@ function lockAgeMs(lock, nowMs) {
     return 0;
   }
 }
-function removeStaleOwner(lock, token) {
-  const tombstone = moveOwnedToTombstone(lock, token);
-  if (tombstone === null)
-    return false;
-  fs4.rmSync(tombstone, { recursive: true, force: true });
-  return true;
+function removeStaleOwner(lock, token, resource) {
+  const guard = `${lock}.reclaim`;
+  try {
+    fs4.mkdirSync(guard, { mode: 448 });
+  } catch (error2) {
+    if (error2.code !== "EEXIST")
+      throw error2;
+    throw new OperationLocked({
+      message: `Apnea stale-lock reclamation is guarded at ${guard}. Retry after the other operation completes. ` + `If the guard persists, stop all Apnea processes using ${lock}, then remove this guard directory manually: ${guard}`,
+      repository: resource,
+      lock_path: lock,
+      reason: "stale",
+      pid: 0
+    });
+  }
+  try {
+    const tombstone = moveOwnedToTombstone(lock, token);
+    if (tombstone === null)
+      return false;
+    fs4.rmSync(tombstone, { recursive: true, force: true });
+    return true;
+  } finally {
+    fs4.rmdirSync(guard);
+  }
 }
 function withLock(lock, resource, operation, waitForRetry, reclaim) {
   const acquireOnce = () => exports_Effect.try({
@@ -31371,20 +31419,35 @@ On rework, read latest code-review and fix.`;
   const cmd = roleCmd;
   const remembered = state.role_panes[role] ?? null;
   const prefer = remembered?.profile_fingerprint === profileFingerprint ? remembered : null;
-  const launched = yield* exports_Effect.result(herdr.runInteractivePrompt(role, cmd, prompt, prefer));
+  const recordPaneOwnership = (pane) => {
+    state.pending_pane_id = pane.pane_id;
+    state.pending_pane_label = pane.label;
+    state.role_panes[role] = {
+      pane_id: pane.pane_id,
+      label: pane.label,
+      profile_fingerprint: profileFingerprint
+    };
+  };
+  let acquisitionRollbackErrors;
+  const launched = yield* exports_Effect.result(herdr.runInteractivePrompt(role, cmd, prompt, prefer, (pane) => exports_Effect.gen(function* () {
+    recordPaneOwnership(pane);
+    const persisted = yield* exports_Effect.exit(store.save(state, root));
+    if (exports_Exit.isFailure(persisted)) {
+      acquisitionRollbackErrors = yield* rollbackLaunch();
+      return yield* new HerdrError({
+        message: `failed to persist pane ownership before delivery: ${exports_Cause.pretty(persisted.cause)}`
+      });
+    }
+  }), () => exports_Effect.gen(function* () {
+    acquisitionRollbackErrors = yield* rollbackLaunch();
+  })));
   if (exports_Result.isFailure(launched)) {
     if (launched.failure.details?.delivery === "unknown") {
       const paneId = launched.failure.details.pane_id;
       const paneLabel = launched.failure.details.pane_label;
       const preserved = typeof paneId === "string" && typeof paneLabel === "string";
       if (preserved) {
-        state.pending_pane_id = paneId;
-        state.pending_pane_label = paneLabel;
-        state.role_panes[role] = {
-          pane_id: paneId,
-          label: paneLabel,
-          profile_fingerprint: profileFingerprint
-        };
+        recordPaneOwnership({ pane_id: paneId, label: paneLabel });
       }
       yield* store.save(state, root);
       return yield* new HerdrError({
@@ -31398,7 +31461,7 @@ On rework, read latest code-review and fix.`;
         }
       });
     }
-    const rollbackErrors = yield* rollbackLaunch();
+    const rollbackErrors = acquisitionRollbackErrors ?? (yield* rollbackLaunch());
     return yield* herdrAfterRollback(launched.failure, {
       task_attempted: taskRef.task,
       artifact: artifactRel
@@ -31416,13 +31479,7 @@ On rework, read latest code-review and fix.`;
     prompt_attempts: r.prompt_attempts,
     last_status: r.last_status ?? null
   };
-  state.pending_pane_id = r.pane_id;
-  state.pending_pane_label = r.label;
-  state.role_panes[role] = {
-    pane_id: r.pane_id,
-    label: r.label,
-    profile_fingerprint: profileFingerprint
-  };
+  recordPaneOwnership(r);
   const launchedAt = yield* exports_Clock.currentTimeMillis;
   markPending(launchedAt, "interactive");
   yield* store.save(state, root);

package/docs/protocol/artifacts.md

@@ -67,7 +67,7 @@ On rework after CHANGES_REQUIRED, the **round number increases** and the path ch
 
 On crash redelivery, `dispatch_role` requires `redeliver=true`, matching pending ownership, and proof that any recorded pane is dead. It clears and reuses the same path without advancing the round. Manual/no-Herdr ownership requires an explicit operator request because no pane can provide liveness evidence.
 
-`state.json.pending_delivery` records whether pending ownership crossed a `manual` or `interactive` delivery boundary. Dispatch persists `interactive` before calling `runInteractivePrompt`, even though `pending_pane_id` is still null. This closes the crash window where the prompt may be accepted but the pane id cannot be saved: redelivery refuses that ambiguous state. Completion clears the mode with every other pending field, and rollback restores the prior mode.
+`state.json.pending_delivery` records whether pending ownership crossed a `manual` or `interactive` delivery boundary. Dispatch persists `interactive` before calling `runInteractivePrompt`. The Herdr adapter then requires a successful ownership save with the acquired pane identity before starting the harness or sending the task prompt. Interruption retains that ownership for recovery. Submission and acceptance-query failures preserve the task and pending Artifact because delivery may have occurred. Proven pre-delivery failures restore the prior state. Legacy or interrupted acquisition can still leave a null pane identity; redelivery refuses that ambiguous state. Completion clears the mode with every other pending field, and rollback restores the prior mode.
 
 Version-1 state lacks this mode. A recorded pending pane safely migrates to `interactive`; a null pane cannot distinguish manual work from an accepted interactive prompt whose final save failed. It migrates to null and redelivery fails closed instead of guessing.
 

package/docs/protocol/overview.md

@@ -78,7 +78,7 @@ Pane markers are human decoration. Herdr `agent_status` is liveness (dead pane w
 - The deprecated `rework` dispatch parameter remains an assertion through 0.2.x. It grants authority only when migrating ambiguous version-1 planning or coding state.
 - Round increments **only** when the required target is dispatched on the same (phase, gate).
 - Crash / timeout / resume: after proving the prior pane is dead, explicitly dispatch the same kind with `redeliver=true`. It validates pending kind, role, phase, and round, then clears the same artifact without advancing the round. A live or ambiguous pane refuses. Manual/no-Herdr work has no pane proof, so the operator must explicitly request redelivery.
-- Pending ownership records `pending_delivery: manual | interactive`. The prepared save writes this before crossing `runInteractivePrompt`, while the pane id may still be null. Interactive null-pane ownership refuses redelivery because prompt acceptance may have happened before the final save. Version-1 ownership without this field migrates to interactive only when a pane id is already recorded; legacy null-pane ownership remains ambiguous and refuses.
+- Pending ownership records `pending_delivery: manual | interactive`. The prepared save writes this before crossing `runInteractivePrompt`. The Herdr adapter saves the acquired pane identity before starting the harness or sending the task prompt. Interruption and uncertain delivery preserve ownership for recovery. Interactive null-pane ownership still refuses redelivery as ambiguous. Version-1 ownership without this field migrates to interactive only when a pane id is already recorded; legacy null-pane ownership remains ambiguous and refuses.
 - Before liveness checks or clear-before-dispatch, redelivery parses the pending artifact with the same acceptance rule as `workflow_wait`. `status: done` completes non-review artifacts; review artifacts also require `verdict: APPROVED | CHANGES_REQUIRED`, legal rework placement, schema-valid rework values, and a valid state transition. Accepted artifacts remain byte-identical and refuse with guidance to call `workflow_wait`. Malformed or incomplete artifacts continue to liveness validation.
 
 ## Resume

package/extension/services/herdr.ts

@@ -23,6 +23,10 @@ export type PaneInfo = {
   agent?: string
 }
 export type RolePaneRef = { pane_id: string; label: string }
+/** Persist pane ownership before any task prompt can reach the pane. */
+export type BeforeInteractiveDelivery = (
+  pane: RolePaneRef,
+) => Effect.Effect<void, HerdrError>
 export type HerdrAvailability = "available" | "unavailable"
 export type InteractiveLaunch = {
   pane_id: string
@@ -51,6 +55,8 @@ export interface HerdrService {
     interactiveCmd: string[],
     prompt: string,
     prefer: RolePaneRef | null,
+    beforeDelivery?: BeforeInteractiveDelivery,
+    onAcquisitionFailure?: () => Effect.Effect<void>,
   ) => Effect.Effect<InteractiveLaunch, HerdrError>
 }
 
@@ -663,6 +669,8 @@ function acquireRolePane(
     prefer?: RolePaneRef | null
     /** Launch interactive harness only when creating a new pane */
     interactiveCmd?: string[]
+    beforeDelivery?: BeforeInteractiveDelivery
+    onAcquisitionFailure?: () => Effect.Effect<void>
   },
 ): Effect.Effect<RolePaneRef & { reused: boolean }, HerdrError> {
   return Effect.gen(function* () {
@@ -676,6 +684,9 @@ function acquireRolePane(
       opts?.prefer?.pane_id &&
       (yield* paneGet(processService, opts.prefer.pane_id)).ok
     ) {
+      if (opts.beforeDelivery) {
+        yield* Effect.uninterruptible(opts.beforeDelivery(opts.prefer))
+      }
       return {
         pane_id: opts.prefer.pane_id,
         label: opts.prefer.label,
@@ -685,17 +696,41 @@ function acquireRolePane(
 
     const millis = yield* Clock.currentTimeMillis
     const label = roleLabel(role, millis)
-    const split = yield* Effect.result(splitPane(processService))
-    if (Result.isFailure(split)) {
-      return yield* withLaunchDetails(split.failure, {
-        delivery:
-          split.failure.details?.delivery === "unknown"
-            ? "unknown"
-            : "not_delivered",
-        newly_created: false,
-      })
-    }
-    const paneId = split.success
+    // A split can create a pane before its response arrives. Finish the bounded
+    // acquisition and ownership save before observing cancellation.
+    const paneId = yield* Effect.uninterruptible(
+      Effect.gen(function* () {
+        const split = yield* Effect.result(splitPane(processService))
+        if (Result.isFailure(split)) {
+          // Restore proven non-delivery before a pending interruption can hide
+          // the split failure when this acquisition mask exits.
+          if (split.failure.details?.delivery !== "unknown") {
+            yield* opts?.onAcquisitionFailure?.() ?? Effect.void
+          }
+          return yield* withLaunchDetails(split.failure, {
+            delivery:
+              split.failure.details?.delivery === "unknown"
+                ? "unknown"
+                : "not_delivered",
+            newly_created: false,
+          })
+        }
+        const paneId = split.success
+        if (opts?.beforeDelivery) {
+          const persisted = yield* Effect.result(
+            opts.beforeDelivery({ pane_id: paneId, label }),
+          )
+          if (Result.isFailure(persisted)) {
+            return yield* cleanupFailedInteractiveLaunch(
+              persisted.failure,
+              paneId,
+              (id) => paneClose(processService, id),
+            )
+          }
+        }
+        return paneId
+      }),
+    )
     const prepared = yield* Effect.result(
       Effect.gen(function* () {
         yield* renamePane(processService, paneId, label)
@@ -748,6 +783,8 @@ function runInteractivePromptImpl(
   interactiveCmd: string[],
   prompt: string,
   prefer: RolePaneRef | null,
+  beforeDelivery?: BeforeInteractiveDelivery,
+  onAcquisitionFailure?: () => Effect.Effect<void>,
 ): Effect.Effect<InteractiveLaunch, HerdrError> {
   return Effect.gen(function* () {
     let preferUse: RolePaneRef | null = null
@@ -767,37 +804,61 @@ function runInteractivePromptImpl(
     const acquired = yield* acquireRolePane(processService, role, hostAdapter, {
       prefer: preferUse,
       interactiveCmd: preferUse ? undefined : interactiveCmd,
+      beforeDelivery,
+      onAcquisitionFailure,
     })
 
-    if (!acquired.reused) {
-      yield* waitAgentReady(processService, acquired.pane_id, 90_000)
-      // still try even if not idle/done — some harnesses accept input
-      // before status settles.
-    } else {
-      const st = (yield* paneGet(processService, acquired.pane_id)).agent_status
-      if (st !== "idle" && st !== "done") {
-        yield* waitAgentReady(processService, acquired.pane_id, 30_000)
-      }
-    }
+    const ready = yield* Effect.result(
+      Effect.gen(function* () {
+        if (!acquired.reused) {
+          yield* waitAgentReady(processService, acquired.pane_id, 90_000)
+          // Some harnesses accept input before status settles.
+        } else {
+          const st = (yield* paneGet(processService, acquired.pane_id))
+            .agent_status
+          if (st !== "idle" && st !== "done") {
+            yield* waitAgentReady(processService, acquired.pane_id, 30_000)
+          }
+        }
 
-    const beforePrompt = hostAdapter.beforeInteractivePrompt?.(interactiveCmd)
-    if (beforePrompt) {
-      // Host preparation is best-effort; command wrapping is the primary guard.
-      yield* Effect.gen(function* () {
-        yield* paneRun(processService, acquired.pane_id, beforePrompt)
-        yield* waitAgentReady(processService, acquired.pane_id, 5_000)
-        yield* Effect.sleep(300)
-      }).pipe(Effect.ignore)
+        const beforePrompt =
+          hostAdapter.beforeInteractivePrompt?.(interactiveCmd)
+        if (beforePrompt) {
+          // Host preparation is best-effort; command wrapping is the primary guard.
+          yield* Effect.gen(function* () {
+            yield* paneRun(processService, acquired.pane_id, beforePrompt)
+            yield* waitAgentReady(processService, acquired.pane_id, 5_000)
+            yield* Effect.sleep(300)
+          }).pipe(Effect.ignore)
+        }
+      }),
+    )
+    if (Result.isFailure(ready)) {
+      if (!acquired.reused) {
+        return yield* cleanupFailedInteractiveLaunch(
+          ready.failure,
+          acquired.pane_id,
+          (id) => paneClose(processService, id),
+        )
+      }
+      return yield* withLaunchDetails(ready.failure, {
+        delivery: "not_delivered",
+      })
     }
 
     // Submit pointer into the live TUI (Herdr: pane run = text + Enter),
     // then confirm the agent actually started — do not trust fire-and-forget.
     const submitted = yield* Effect.result(
-      paneRun(processService, acquired.pane_id, prompt),
+      Effect.gen(function* () {
+        yield* paneRun(processService, acquired.pane_id, prompt)
+        return yield* ensurePromptSubmitted(acquired.pane_id, prompt, {
+          processService,
+        })
+      }),
     )
     if (Result.isFailure(submitted)) {
       return yield* withLaunchDetails(submitted.failure, {
-        // The Herdr CLI can lose its response after the pane accepted text.
+        // Submission or acceptance probing can fail after the pane accepted text.
         // Closing or retrying here could kill or duplicate a live worker.
         delivery: "unknown",
         pane_id: acquired.pane_id,
@@ -805,9 +866,7 @@ function runInteractivePromptImpl(
         reused: acquired.reused,
       })
     }
-    const submit = yield* ensurePromptSubmitted(acquired.pane_id, prompt, {
-      processService,
-    })
+    const submit = submitted.success
     return {
       pane_id: acquired.pane_id,
       label: acquired.label,

package/extension/services/operation-lock.ts

@@ -190,6 +190,9 @@ function writeCandidate(directory: string, owner: Owner): void {
   fsyncDirectory(directory)
 }
 
+// The caller either releases its own live owner or holds the reclamation guard.
+// A live owner cannot be reclaimed. Stale removers must serialize the token
+// check and rename; checking the token after rename cannot undo displacement.
 function moveOwnedToTombstone(lock: string, token: string): string | null {
   if (readOwner(lock)?.token !== token) return null
   const tombstone = `${lock}.tombstone.${crypto.randomUUID()}`
@@ -270,7 +273,7 @@ function acquireLock(
     if (
       reclaim !== undefined &&
       lockAgeMs(lock, reclaim.now()) >= reclaim.graceMs &&
-      removeStaleOwner(lock, existing.token)
+      removeStaleOwner(lock, existing.token, resource)
     ) {
       // Dead owner past the freshness grace: a crashed holder. Reclaiming
       // lets crash-recoverable operations (e.g. a durable commit
@@ -307,14 +310,45 @@ function lockAgeMs(lock: string, nowMs: number): number {
 }
 
 /**
- * Remove a validated stale owner atomically: the tombstone rename re-checks
- * the token, so a concurrently refreshed lock is never displaced.
+ * Only one stale remover may validate ownership and rename the canonical path.
+ * Publication needs no guard: the old nonempty directory excludes candidates
+ * until rename, and this remover never renames the canonical path again.
+ * A delayed remover must acquire the guard and recheck the token, so it cannot
+ * displace a replacement. Live-owner release cannot race a matching stale
+ * removal because processIsAlive refuses that owner.
+ *
+ * The guard is deliberately not reclaimable. A crash here requires manual
+ * removal of `${lock}.reclaim` after all Apnea processes using this lock stop.
+ * Recursively reclaiming a stale guard would reintroduce the same race.
  */
-function removeStaleOwner(lock: string, token: string): boolean {
-  const tombstone = moveOwnedToTombstone(lock, token)
-  if (tombstone === null) return false
-  fs.rmSync(tombstone, { recursive: true, force: true })
-  return true
+function removeStaleOwner(
+  lock: string,
+  token: string,
+  resource: string,
+): boolean {
+  const guard = `${lock}.reclaim`
+  try {
+    fs.mkdirSync(guard, { mode: 0o700 })
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error
+    throw new OperationLocked({
+      message:
+        `Apnea stale-lock reclamation is guarded at ${guard}. Retry after the other operation completes. ` +
+        `If the guard persists, stop all Apnea processes using ${lock}, then remove this guard directory manually: ${guard}`,
+      repository: resource,
+      lock_path: lock,
+      reason: "stale",
+      pid: 0,
+    })
+  }
+  try {
+    const tombstone = moveOwnedToTombstone(lock, token)
+    if (tombstone === null) return false
+    fs.rmSync(tombstone, { recursive: true, force: true })
+    return true
+  } finally {
+    fs.rmdirSync(guard)
+  }
 }
 
 function withLock<A, E, R>(

package/extension/workflows/dispatch.ts

@@ -39,7 +39,7 @@ import { ok, type ToolResult } from "../result.ts"
 import { validateArtifactCompletion } from "../schema/frontmatter.ts"
 import { Config } from "../services/config.ts"
 import { FileSystem } from "../services/file-system.ts"
-import { Herdr } from "../services/herdr.ts"
+import { Herdr, type RolePaneRef } from "../services/herdr.ts"
 import { RunStore } from "../services/run-store.ts"
 import { Vcs } from "../services/vcs.ts"
 
@@ -701,8 +701,40 @@ export const dispatchWorkflow = (
     const remembered = state.role_panes[role] ?? null
     const prefer =
       remembered?.profile_fingerprint === profileFingerprint ? remembered : null
+    const recordPaneOwnership = (pane: RolePaneRef) => {
+      state.pending_pane_id = pane.pane_id
+      state.pending_pane_label = pane.label
+      state.role_panes[role] = {
+        pane_id: pane.pane_id,
+        label: pane.label,
+        profile_fingerprint: profileFingerprint,
+      }
+    }
+    let acquisitionRollbackErrors: string[] | undefined
     const launched = yield* Effect.result(
-      herdr.runInteractivePrompt(role, cmd, prompt, prefer),
+      herdr.runInteractivePrompt(
+        role,
+        cmd,
+        prompt,
+        prefer,
+        (pane) =>
+          Effect.gen(function* () {
+            recordPaneOwnership(pane)
+            const persisted = yield* Effect.exit(store.save(state, root))
+            if (Exit.isFailure(persisted)) {
+              // Restore proven non-delivery while the adapter still masks
+              // cancellation. A pending interruption can hide the typed failure.
+              acquisitionRollbackErrors = yield* rollbackLaunch()
+              return yield* new HerdrError({
+                message: `failed to persist pane ownership before delivery: ${Cause.pretty(persisted.cause)}`,
+              })
+            }
+          }),
+        () =>
+          Effect.gen(function* () {
+            acquisitionRollbackErrors = yield* rollbackLaunch()
+          }),
+      ),
     )
     if (Result.isFailure(launched)) {
       if (launched.failure.details?.delivery === "unknown") {
@@ -715,13 +747,7 @@ export const dispatchWorkflow = (
         const preserved =
           typeof paneId === "string" && typeof paneLabel === "string"
         if (preserved) {
-          state.pending_pane_id = paneId
-          state.pending_pane_label = paneLabel
-          state.role_panes[role] = {
-            pane_id: paneId,
-            label: paneLabel,
-            profile_fingerprint: profileFingerprint,
-          }
+          recordPaneOwnership({ pane_id: paneId, label: paneLabel })
         }
         yield* store.save(state, root)
         return yield* new HerdrError({
@@ -737,7 +763,8 @@ export const dispatchWorkflow = (
           },
         })
       }
-      const rollbackErrors = yield* rollbackLaunch()
+      const rollbackErrors =
+        acquisitionRollbackErrors ?? (yield* rollbackLaunch())
       return yield* herdrAfterRollback(
         launched.failure,
         {
@@ -759,13 +786,7 @@ export const dispatchWorkflow = (
       prompt_attempts: r.prompt_attempts,
       last_status: r.last_status ?? null,
     }
-    state.pending_pane_id = r.pane_id
-    state.pending_pane_label = r.label
-    state.role_panes[role] = {
-      pane_id: r.pane_id,
-      label: r.label,
-      profile_fingerprint: profileFingerprint,
-    }
+    recordPaneOwnership(r)
 
     // After the launch, not before it: `runInteractivePrompt` blocks in
     // `waitAgentReady` (up to 90s) plus prompt-submit retries. Anchoring at

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@naxodev/apnea",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "description": "Host-neutral multi-role workflow engine and standalone Bun CLI",
   "license": "MIT",
   "author": "Nacho Vazquez",