pi-tmux-session-map 0.3.0 → 0.5.0

package/README.md

@@ -10,27 +10,57 @@ It also writes [tws](https://github.com/ytaskiran/tws)-compatible Pi work-status
 
 ## How it works
 
-The extension resolves a stable tmux pane key:
+The extension records two complementary tmux identities:
 
-```
-#{session_name}:#{window_index}.#{pane_index}
+```text
+restart identity: #{session_name}:#{window_index}.#{pane_index}
+live identity:    (#{pid}, #{pane_id})
 ```
 
-That key is stable across tmux server restarts (unlike pane ids like `%42`), which is exactly what tmux-resurrect restores. File names use a readable sanitized prefix plus a 12-character SHA-256 suffix so different pane keys cannot collide and very long tmux session names stay below filesystem filename limits.
+The pane key is what tmux-resurrect recreates across server restarts. The server-PID/pane-ID pair remains stable while one tmux server is running, even when windows or panes are renumbered. A periodic, jittered reconciliation resolves the current key for the live pane ID and atomically republishes the mapping under the new key. Pane IDs are never trusted across a tmux server restart because tmux can reuse them.
+
+File names use a readable sanitized prefix plus a 12-character SHA-256 suffix so different identities cannot collide and very long tmux session names stay below filesystem filename limits.
 
 For tmux it writes the exact-resume mapping and status sidecar. For Zellij it writes only the status sidecar because Zellij owns session resurrection itself:
 
 ```text
 ~/.local/state/pi/tmux-sessions/<sanitized-pane-key>-<sha256-12>.session
+~/.local/state/pi/tmux-sessions/pane-id-<sanitized-pane-id>-<sha256-12>.session
 ~/.config/tws/pi-status/<sanitized-pane-key>-<sha256-12>.json
 ~/.config/tws-zellij/pi-status/<sanitized-pane-key>-<sha256-12>.json
 ```
 
-The `.session` file contains the active Pi session file path. It is written on `session_start`, `session_info_changed`, `agent_start`, and `agent_end` when the current Pi session has a backing session file.
+The `.session` files contain schema-3 JSON with pane key, pane ID, tmux server PID, exact Pi session path and ID, cwd, and session name. They are written only by an interactive Pi TUI with a real stdin TTY, never by a headless `pi-subagents` child that merely inherited the parent's tmux environment. Publication also requires that the JSONL exists and its session header matches Pi's current session ID. Writes occur on Pi lifecycle events and periodic reconciliation. A replacement key and pane-ID alias are published atomically before stale names are removed, so interruption can leave duplicates but never a mapping gap.
+
+The status `.json` also publishes `session_id`, `pi_pid` and `tmux_server_pid`.
+This live identity comes directly from Pi at session start, even before its JSONL
+exists. Consumers must match the foreground Pi PID, tmux server and pane, reject
+shutdown/stale status, and revalidate before copying. The session ID is therefore
+available before the first message; a resume command still requires a matching
+on-disk header. The durable `.session` mappings retain their persistence checks.
+
+For tmux-recovery's auto-continue decision the status also carries recovery evidence. `run_anchor` (`{ leaf_id, started_at_ms }`) is set at the `agent_start` that begins a run: `leaf_id` is the session leaf before the run's prompt entry, captured synchronously because Pi persists the prompt after `agent_start`. Retries keep the anchor; final states and `idle` clear it. On `shutdown`, `shutdown_cause` is `signal` when the process received SIGHUP or SIGTERM (closed terminal, dead tmux server, reboot), `quit` for an interactive quit, `reload`, or `replace` for `/new`, `/resume` and fork. Only the interactive pane owner installs the signal listener, and the cause is resolved when the queued write builds its payload, after the signal dispatch has finished. A graceful signal shutdown can still leave `working` or `retrying` when Pi exits on a dead terminal before the write lands.
+
+### Auto-continue executor
+
+When tmux-recovery restores a Pi that was interrupted inside a run, its resume wrapper sets `PI_TMUX_CONTINUE_PLAN` to a plan file in the recovery ledger. Only that restored process runs the executor, once, at its `startup`, and only as the interactive pane owner for the planned session. The executor waits for the restore acknowledgement (`resumed`; a mismatch skips) and for the plan's slot, then checks the final conditions in one section under the ledger's dispatch lock: plan still released and listed in `ready.json`, mode `on`, no hold file, same session, pane and last message entry, Pi idle without pending messages, empty editor, no open dialog, no live `pi-session-watchdog` for the session. It then claims the plan with an exclusive create (`<key>.claim`, never removed) and sends one visible `tmux-recovery-continue` message with `triggerTurn`. The German text names the stop time, the elapsed time and open tool calls and asks Pi to check the actual state first; its `continuationId` matches the message details.
+
+Any real keystroke (`ctx.ui.onTerminalInput`), interactive or RPC input, extension dialog or other run before the dispatch writes a durable veto (`<key>.skip`, first writer wins). A session end before the claim writes a `process-end` skip. After the dispatch, `before_agent_start` with the matching `continuationId` writes the outcome `admitted`, and the turn's `agent_settled` writes its final state; without admission within 120 s the outcome is `uncertain`. Nothing is ever re-sent.
+
+A `<key>.skip` that another program wrote before the claim is a veto too: TWS writes `{"class": "veto", "reason": "skipped-in-tws", …}` with an exclusive create when you skip a planned continuation. The executor checks for it at least once a second while it waits for the slot or the spacing, and again inside the dispatch section; it then stops without a claim and keeps the file as written. A file it cannot read or parse also counts as a veto. A skip written after the claim has no effect, so a writer should check `<key>.claim` after its own create to know whether it came too late.
+
+The status sidecar shows the executor in `continue`, from its start on:
+
+```json
+"continue": {"state": "planned", "reason": null, "slot_ms": 1794000014000, "deadline_ms": 1794000614000,
+             "key": "<64 hex>", "ledger_dir": "/Users/…/resurrect/pi-continue/ledger"}
+```
+
+`state` is `planned`, `dispatched`, `admitted`, the turn's outcome (`done`, `failed`, `cancelled`, …), `uncertain`, `skipped` or `stopped`; `reason` is set for `skipped` and `stopped` (for example `user-active`, `skipped-in-tws`, `claimed`). `slot_ms` and `deadline_ms` come from the released plan and stay `null` until the release.
 
 The `.json` file contains the multiplexer backend, tws work state (`idle`, `working`, `retrying`, `done`, `cancelled`, `incomplete`, `failed`, `shutdown`), and pane/session metadata. A technical-error `agent_end` is provisional `retrying`; aborts and token-limit responses become `cancelled`/`incomplete` immediately. `agent_settled` confirms the final outcome (`failed` if recovery did not succeed). The extension touches the matching `agent.trigger` file after status writes so that edition refreshes within one poll tick.
 
-Mappings are intentionally **not** removed on shutdown — they must survive `tmux kill-server` so resurrect can use them. Every Pi start in a pane overwrites that pane's mapping, so stale entries self-heal. Very old mapping files and interrupted atomic-write temp files are cleaned up opportunistically on session start.
+Mappings are intentionally **not** removed on shutdown — they must survive `tmux kill-server` so resurrect can use them. During one live tmux server, reconciliation self-heals pane renumbering through the stable pane-ID alias. After a server restart, consumers ignore old aliases and use the restart-stable pane key. Very old missing-target mappings and interrupted atomic-write temp files are cleaned up opportunistically on session start.
 
 ## Install
 
@@ -95,13 +125,14 @@ set -g @resurrect-processes '"~pi-coding-agent/dist/cli.js->pi-tmux-resume"'
 
 ## Behavior
 
-The exact session mapping is written only when Pi runs inside tmux (`$TMUX` and `$TMUX_PANE` set) and the current session has a backing session file. The tws status file is written inside either tmux or Zellij (`$ZELLIJ`, `$ZELLIJ_SESSION_NAME`, and `$ZELLIJ_PANE_ID`), even when the Pi session file is not available yet; `session_file` is `null` until Pi creates one. Final failure-like outcomes are delayed until `agent_settled`, so automatic retries or compaction recovery do not appear as permanent failures.
+The exact session mapping and pane-scoped tws status are written only when Pi is an interactive TUI with a real stdin TTY and is not marked as a `PI_SUBAGENT_CHILD`. Tmux additionally requires `$TMUX` and `$TMUX_PANE`; Zellij requires `$ZELLIJ`, `$ZELLIJ_SESSION_NAME`, and `$ZELLIJ_PANE_ID`. This ownership gate prevents invisible headless children from replacing the visible parent's resume identity or work status. When an eligible interactive session has no Pi session path, the status `session_file` is `null`. Pi can also supply a planned path before the file exists; that path alone is not proof of resumability. The live `session_id` remains available in either case. Final failure-like outcomes are delayed until `agent_settled`, so automatic retries or compaction recovery do not appear as permanent failures.
 
 If the recorded session file no longer exists, the wrapper falls back to `pi --continue` for the pane's working directory.
 
 ## Caveats
 
-- Pane keys use window/pane *indexes*: if you reorder windows or panes between save and restore, a mapping can point at a sibling pane's session. It self-heals on the next Pi start.
+- Pane IDs are scoped to one tmux server and may be reused after restart. Schema 3 therefore includes the tmux server PID and consumers require both values before using a live alias.
+- A Pi process without a valid on-disk JSONL has a live identity but no durable resume mapping. The extension waits for persistence before publishing a resume alias; it never creates session history merely to make a command available.
 
 ## License
 
@@ -116,8 +147,12 @@ Optional environment variables for hardening or local integration:
 - `PI_TMUX_SESSION_MAP_TWS_STATUS_DIR` — override only the tws status directory.
 - `PI_TMUX_SESSION_MAP_TWS_TRIGGER_FILE` — override the tws trigger file.
 - `PI_TMUX_SESSION_MAP_TMUX_BIN` — override the `tmux` binary path.
+- `PI_TMUX_SESSION_MAP_RESTORE_PANE_TIMEOUTS_MS` — comma-separated `tmux display-message` timeouts while a restore acknowledgement is pending; default `1000,2000,4000,8000,16000`.
+- `PI_TMUX_SESSION_MAP_RECONCILE_INTERVAL_MS` — periodic mapping reconciliation interval; minimum 10 seconds, default 60 seconds, deterministically jittered per pane.
 - `PI_TMUX_SESSION_MAP_ZELLIJ_BIN` — override the `zellij` binary path.
 - `PI_TMUX_SESSION_MAP_ZELLIJ_STATUS_DIR` — override the Zellij TWS status directory.
 - `PI_TMUX_SESSION_MAP_ZELLIJ_TRIGGER_FILE` — override the Zellij TWS trigger file.
 
-Lifecycle sidecar updates are serialized in-process, mapping and status files are written atomically, and `tmux display-message` is bounded by a short timeout so Pi lifecycle hooks do not hang indefinitely.
+A restore acknowledgement (`PI_TMUX_RESTORE_*` environment from `pi-tmux-resume`) is written at most once per token: the first writer wins, so a later `/new` or `/reload` cannot replace the proof of what the restore resumed. A restore keeps the tmux server busy, so while the acknowledgement is pending the pane lookup is retried with growing timeouts; if every attempt fails, the next lifecycle event or reconciliation writes it.
+
+Lifecycle sidecar updates are serialized in-process, mapping and status files are written atomically, and `tmux display-message` is bounded by a short timeout so Pi lifecycle hooks do not hang indefinitely. A refresh that times out keeps the last known pane of the process, so a busy tmux never drops a status write such as `working` at `agent_start`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-tmux-session-map",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "Map Pi sessions to tmux panes and publish TWS work status for tmux and Zellij.",
   "type": "module",
   "exports": {

package/src/continuation-executor.ts

@@ -0,0 +1,323 @@
+// Timer, veto latch and admission tracking around src/domain/continuation.ts.
+// index.ts forwards the Pi events; this class never registers handlers itself.
+
+import { randomUUID } from "node:crypto";
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+
+import {
+  CONTINUE_CUSTOM_TYPE, acquireDispatchLock, continuationMessage, createExclusive, decide, existingSkipReason, lastDispatchMs,
+  lastMessageEntryId, readMode, readPlan, readyState, releaseDispatchLock, testCheckpoint, watchdogAlive, writeAtomicSync,
+  writeOutcome, writeSkip, type ContinuePlan, type LiveFacts,
+} from "./domain/continuation.ts";
+import type { ContinueStatus } from "./domain/status.ts";
+
+/** Also the longest wait before the slot, so an outside veto shows within a second. */
+const POLL_MS = 1000;
+const LOCK_RETRY_MS = 1000;
+const ADMISSION_TIMEOUT_MS = 120_000;
+/** Without a ready.json the restore never released this attempt. */
+const READY_WAIT_LIMIT_MS = 30 * 60 * 1000;
+
+export type LiveSource = {
+  ackResumed(): boolean | undefined;
+  paneKey(): string | null;
+  sessionId(): string;
+  sessionFile(): string | null;
+  branch(): readonly { id?: string; type?: string; message?: { role?: string } }[];
+  idle(): boolean;
+  pendingMessages(): boolean;
+  editorText(): string;
+};
+
+export type SendMessage = (
+  message: { customType: string; content: string; display: boolean; details: Record<string, unknown> },
+  options: { triggerTurn: boolean },
+) => void;
+
+export class ContinuationExecutor {
+  readonly continuationId = randomUUID();
+  private timer: ReturnType<typeof setTimeout> | undefined;
+  private admissionTimer: ReturnType<typeof setTimeout> | undefined;
+  private finished = false;
+  private claimed = false;
+  private admitted = false;
+  private outcomeWritten = false;
+  private userActive = false;
+  private promptDepth = 0;
+  private startedAtMs = Date.now();
+  private stateValue = "planned";
+  private slotMs: number | null;
+  private deadlineMs: number | null;
+  /** End of a spacing wait decided under the dispatch lock. */
+  private waitUntilMs = 0;
+  readonly planPath: string;
+  readonly plan: ContinuePlan;
+  private readonly live: LiveSource;
+  private readonly send: SendMessage;
+  private readonly onChange: () => void;
+  private readonly watchdogRoot: string;
+
+  private constructor(planPath: string, plan: ContinuePlan, live: LiveSource, send: SendMessage, onChange: () => void, watchdogRoot: string) {
+    this.planPath = planPath;
+    this.plan = plan;
+    this.slotMs = plan.slotMs ?? null;
+    this.deadlineMs = plan.deadlineMs ?? null;
+    this.live = live;
+    this.send = send;
+    this.onChange = onChange;
+    this.watchdogRoot = watchdogRoot;
+  }
+
+  static fromEnvironment(live: LiveSource, send: SendMessage, onChange: () => void, env = process.env): ContinuationExecutor | undefined {
+    const planPath = env.PI_TMUX_CONTINUE_PLAN;
+    if (!planPath) return undefined;
+    const plan = readPlan(planPath);
+    if (!plan || plan.sessionId !== live.sessionId()) return undefined;
+    return new ContinuationExecutor(planPath, plan, live, send, onChange, env.PI_TMUX_SESSION_WATCHDOG_ROOT ?? "/tmp");
+  }
+
+  /** Executor state as text: planned, dispatched, admitted, an outcome, skipped:<reason>, stopped:<reason>. */
+  state(): string {
+    return this.stateValue;
+  }
+
+  /** The status sidecar `continue` field. */
+  status(): ContinueStatus {
+    const separator = this.stateValue.indexOf(":");
+    return {
+      state: separator === -1 ? this.stateValue : this.stateValue.slice(0, separator),
+      reason: separator === -1 ? null : this.stateValue.slice(separator + 1),
+      slot_ms: this.slotMs,
+      deadline_ms: this.deadlineMs,
+      key: this.plan.key,
+      ledger_dir: this.plan.ledgerDir,
+    };
+  }
+
+  start(): void {
+    this.startedAtMs = Date.now();
+    // Publish `planned` (with its slot, once known) so a display can show the wait.
+    this.onChange();
+    this.schedule(0);
+  }
+
+  // -- events forwarded by index.ts -------------------------------------------
+
+  noteUserActivity(): void {
+    if (this.claimed || this.finished) return;
+    this.userActive = true;
+    this.skip("veto", "user-active");
+  }
+
+  notePrompt(open: boolean): void {
+    this.promptDepth = Math.max(0, this.promptDepth + (open ? 1 : -1));
+    if (open) this.noteUserActivity();
+  }
+
+  beforeAgentStart(event: { messageType?: string; message?: { customType?: string; details?: { continuationId?: string } } }): void {
+    if (event.messageType === "custom" && event.message?.customType === CONTINUE_CUSTOM_TYPE
+      && event.message.details?.continuationId === this.continuationId) {
+      this.admit();
+      return;
+    }
+    // Any other run before the dispatch is activity in this session.
+    if (!this.claimed && !this.finished) {
+      this.skip("veto", "busy");
+    }
+  }
+
+  agentSettled(outcome: string): void {
+    // Only the continuation turn's own outcome; later user runs are not ours.
+    if (!this.admitted || this.outcomeWritten) return;
+    this.outcomeWritten = true;
+    writeOutcome(this.plan, outcome, this.continuationId);
+    this.setState(outcome);
+  }
+
+  shutdown(): void {
+    this.clearTimers();
+    if (!this.claimed && !this.finished) {
+      writeSkip(this.plan, "process-end", "session-ended");
+      this.finish("skipped:session-ended");
+    }
+  }
+
+  // -- internals ----------------------------------------------------------------
+
+  private setState(value: string): void {
+    this.stateValue = value;
+    this.onChange();
+  }
+
+  private finish(value: string): void {
+    this.finished = true;
+    this.clearTimers();
+    this.setState(value);
+  }
+
+  private skip(skipClass: "process-end" | "veto", reason: string): void {
+    writeSkip(this.plan, skipClass, reason);
+    this.finish(`skipped:${reason}`);
+  }
+
+  private clearTimers(): void {
+    if (this.timer !== undefined) clearTimeout(this.timer);
+    this.timer = undefined;
+  }
+
+  private schedule(ms: number): void {
+    this.clearTimers();
+    if (this.finished) return;
+    this.timer = setTimeout(() => {
+      this.timer = undefined;
+      try {
+        this.tick();
+      } catch {
+        // A file system error must not crash Pi; give up without dispatching.
+        if (!this.claimed) this.finish("stopped:error");
+      }
+    }, Math.max(0, ms));
+    this.timer.unref?.();
+  }
+
+  private tick(): void {
+    if (this.finished) return;
+    // A veto from outside (TWS `x`) ends the wait at once; the skip file is not ours to write.
+    const vetoReason = existingSkipReason(this.plan);
+    if (vetoReason !== null) {
+      this.finish(`skipped:${vetoReason}`);
+      return;
+    }
+    const now = Date.now();
+    switch (readyState(this.plan)) {
+      case "waiting":
+        if (now - this.startedAtMs > READY_WAIT_LIMIT_MS) {
+          this.skip("process-end", "timeout");
+        } else {
+          this.schedule(POLL_MS);
+        }
+        return;
+      case "not-released":
+        this.skip("process-end", "not-released");
+        return;
+      case "released":
+        break;
+    }
+    const onDisk = readPlan(this.planPath);
+    if (onDisk?.token === this.plan.token) {
+      this.noteSlot(onDisk.slotMs ?? null, onDisk.deadlineMs ?? null);
+    }
+    if (onDisk?.slotMs != null && now < onDisk.slotMs && onDisk.token === this.plan.token) {
+      this.schedule(Math.min(onDisk.slotMs - now, POLL_MS));
+      return;
+    }
+    if (now < this.waitUntilMs) {
+      this.schedule(Math.min(this.waitUntilMs - now, POLL_MS));
+      return;
+    }
+    this.dispatchSection(now);
+  }
+
+  private facts(now: number): LiveFacts {
+    return {
+      nowMs: now,
+      ackResumed: this.live.ackResumed() === true,
+      sessionId: this.live.sessionId(),
+      sessionFile: this.live.sessionFile(),
+      paneKey: this.live.paneKey(),
+      lastMessageEntryId: lastMessageEntryId(this.live.branch()),
+      idle: this.live.idle(),
+      pendingMessages: this.live.pendingMessages(),
+      editorText: this.live.editorText(),
+      userActive: this.userActive,
+      promptOpen: this.promptDepth > 0,
+      watchdogAlive: watchdogAlive(this.plan.sessionId, this.watchdogRoot),
+      mode: readMode(this.plan.configPath),
+      holdPresent: existsSync(this.plan.holdFile),
+      skipReason: existingSkipReason(this.plan),
+    };
+  }
+
+  private noteSlot(slotMs: number | null, deadlineMs: number | null): void {
+    if (slotMs === this.slotMs && deadlineMs === this.deadlineMs) return;
+    this.slotMs = slotMs;
+    this.deadlineMs = deadlineMs;
+    this.onChange();
+  }
+
+  /** One synchronous section: lock, E1-E7, claim, send, timestamp, unlock. */
+  private dispatchSection(now: number): void {
+    if (this.live.ackResumed() === undefined) {
+      this.schedule(POLL_MS); // the acknowledgement is still pending
+      return;
+    }
+    const lock = acquireDispatchLock(this.plan.ledgerDir, this.continuationId);
+    if (!lock) {
+      this.schedule(LOCK_RETRY_MS);
+      return;
+    }
+    try {
+      testCheckpoint(this.plan.ledgerDir, "in-dispatch-lock");
+      const claimPath = join(this.plan.ledgerDir, `${this.plan.key}.claim`);
+      // The pre-check runs under the dispatch lock; the O_EXCL claim below
+      // still decides if another holder claimed in between (reclaimed lock).
+      const claimedBefore = existsSync(claimPath);
+      const verdict = decide(this.plan, readPlan(this.planPath), this.facts(now), claimedBefore, lastDispatchMs(this.plan.ledgerDir));
+      switch (verdict.kind) {
+        case "wait":
+          this.waitUntilMs = verdict.untilMs;
+          this.schedule(Math.min(verdict.untilMs - now, POLL_MS));
+          return;
+        case "stop":
+          this.finish(`stopped:${verdict.reason}`);
+          return;
+        case "skip":
+          this.skip(verdict.skipClass, verdict.reason);
+          return;
+        case "vetoed":
+          this.finish(`skipped:${verdict.reason}`);
+          return;
+        case "dispatch":
+          break;
+      }
+      const claim = { continuationId: this.continuationId, token: this.plan.token, key: this.plan.key, sessionId: this.plan.sessionId, pid: process.pid, claimedAtMs: now };
+      if (!createExclusive(claimPath, `${JSON.stringify(claim)}\n`)) {
+        this.finish("stopped:claimed");
+        return;
+      }
+      this.claimed = true;
+      testCheckpoint(this.plan.ledgerDir, "after-claim");
+      try {
+        this.send(
+          { customType: CONTINUE_CUSTOM_TYPE, content: continuationMessage(this.plan, now, this.continuationId), display: true, details: { continuationId: this.continuationId } },
+          { triggerTurn: true },
+        );
+        this.setState("dispatched");
+        this.admissionTimer = setTimeout(() => {
+          if (!this.admitted) {
+            writeOutcome(this.plan, "uncertain", this.continuationId, { reason: "no-admission" });
+            this.setState("uncertain");
+          }
+        }, ADMISSION_TIMEOUT_MS);
+        this.admissionTimer.unref?.();
+      } catch (error) {
+        writeOutcome(this.plan, "uncertain", this.continuationId, { reason: `send failed: ${String(error)}` });
+        this.setState("uncertain");
+      }
+      writeAtomicSync(join(this.plan.ledgerDir, ".last-dispatch"), `${JSON.stringify({ atMs: now, pid: process.pid, continuationId: this.continuationId })}\n`);
+      this.finished = true;
+    } finally {
+      releaseDispatchLock(lock);
+    }
+  }
+
+  private admit(): void {
+    if (this.admitted) return;
+    this.admitted = true;
+    if (this.admissionTimer !== undefined) clearTimeout(this.admissionTimer);
+    // A late admission upgrades an earlier `uncertain` (display only; never re-sent).
+    writeOutcome(this.plan, "admitted", this.continuationId);
+    this.setState("admitted");
+  }
+}

package/src/domain/atomic-write.ts

@@ -1,7 +1,7 @@
-import { mkdir, readFile, readdir, rename, rm, stat, writeFile } from "node:fs/promises";
+import { link, mkdir, readFile, readdir, rename, rm, stat, writeFile } from "node:fs/promises";
 import { basename, dirname, join } from "node:path";
 
-import { mappedSessionFile } from "./session-mapping.ts";
+import { mappedPaneIdentity, mappedSessionFile } from "./session-mapping.ts";
 
 let atomicWriteCounter = 0;
 
@@ -33,6 +33,28 @@ export async function writeAtomic(file: string, data: string, mode: number): Pro
   }
 }
 
+/**
+ * Publish `file` with its complete content only if it does not exist yet.
+ * Returns false when another writer published it first; its content is kept.
+ */
+export async function writeAtomicExclusive(file: string, data: string, mode: number): Promise<boolean> {
+  const tmp = nextTempPath(file);
+  try {
+    await writeFile(tmp, data, { mode });
+    try {
+      await link(tmp, file);
+      return true;
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code === "EEXIST") {
+        return false;
+      }
+      throw error;
+    }
+  } finally {
+    await rm(tmp, { force: true });
+  }
+}
+
 export async function cleanupStaleTempFiles(
   dir: string,
   maxAgeMs: number,
@@ -108,8 +130,9 @@ export async function cleanupSupersededStatusFiles(
 
 export async function cleanupSupersededSessionMappings(
   dir: string,
-  currentFileName: string,
+  currentFileNames: string | readonly string[],
   sessionFile: string,
+  paneIdentity?: { paneId: string; tmuxServerPid: string },
 ): Promise<CleanupResult> {
   let entries: string[];
   try {
@@ -118,20 +141,28 @@ export async function cleanupSupersededSessionMappings(
     return { scanned: 0, removed: 0 };
   }
 
+  const retained = new Set(
+    typeof currentFileNames === "string" ? [currentFileNames] : currentFileNames,
+  );
   let scanned = 0;
   let removed = 0;
   for (const entry of entries) {
-    if (!entry.endsWith(".session") || entry === currentFileName) {
+    if (!entry.endsWith(".session") || retained.has(entry)) {
       continue;
     }
     scanned += 1;
     const path = join(dir, entry);
     try {
-      // A Pi session file is owned by exactly one live pane, so any other
-      // mapping pointing at it is a stale key (window renamed / pane moved) or
-      // a legacy-named duplicate of the current key.
-      const target = mappedSessionFile(await readFile(path, "utf8")) ?? "";
-      if (target !== sessionFile) {
+      const content = await readFile(path, "utf8");
+      // A Pi session and a live tmux pane id each have one current owner. A
+      // match on either identity proves this is an old key or alias, but only
+      // after the caller has atomically published the replacement files.
+      const sameSession = mappedSessionFile(content) === sessionFile;
+      const mappedIdentity = mappedPaneIdentity(content);
+      const samePane = paneIdentity !== undefined
+        && mappedIdentity?.paneId === paneIdentity.paneId
+        && mappedIdentity.tmuxServerPid === paneIdentity.tmuxServerPid;
+      if (!sameSession && !samePane) {
         continue;
       }
       await rm(path, { force: true });