pi-tmux-session-map 0.3.0 → 0.4.0

package/README.md

@@ -10,27 +10,31 @@ 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:
 
+```text
+restart identity: #{session_name}:#{window_index}.#{pane_index}
+live identity:    (#{pid}, #{pane_id})
 ```
-#{session_name}:#{window_index}.#{pane_index}
-```
 
-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 after 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 `.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
 
@@ -101,7 +105,8 @@ If the recorded session file no longer exists, the wrapper falls back to `pi --c
 
 ## 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 whose current session has no valid on-disk JSONL cannot be mapped exactly. The extension fails closed and waits for a later lifecycle event or reconciliation instead of publishing a speculative path.
 
 ## License
 
@@ -116,6 +121,7 @@ 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_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.

package/package.json

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

package/src/domain/atomic-write.ts

@@ -1,7 +1,7 @@
 import { 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;
 
@@ -108,8 +108,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 +119,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 });

package/src/domain/mapping-publisher.ts

@@ -0,0 +1,54 @@
+import { join } from "node:path";
+
+import { cleanupSupersededSessionMappings, ensureDirectory, writeAtomic } from "./atomic-write.ts";
+import { mappingFileName, paneIdMappingFileName } from "./pane-key.ts";
+import { sessionFileMatches } from "./session-file.ts";
+import { buildSessionMapping, serializeSessionMapping } from "./session-mapping.ts";
+import type { PaneInfo, SessionInfo } from "./status.ts";
+
+export type MappingPublication = {
+  keyFileName: string;
+  paneIdFileName: string;
+};
+
+export async function publishSessionMapping(
+  stateDir: string,
+  info: PaneInfo,
+  session: SessionInfo,
+  sessionId: string,
+  nowMs = Date.now(),
+): Promise<MappingPublication | undefined> {
+  if (
+    session.sessionFile === null
+    || info.backend !== "tmux"
+    || info.tmuxServerPid === null
+    || !(await sessionFileMatches(session.sessionFile, sessionId))
+  ) {
+    return undefined;
+  }
+  const keyFileName = mappingFileName(info.paneKey);
+  const paneIdFileName = paneIdMappingFileName(info.paneId);
+  const mapping = buildSessionMapping(
+    info.paneKey,
+    info.paneId,
+    info.tmuxServerPid,
+    session.sessionFile,
+    sessionId,
+    session.cwd,
+    session.sessionName,
+    nowMs,
+  );
+  const serialized = serializeSessionMapping(mapping);
+  await ensureDirectory(stateDir);
+  // Publish both current identities before removing stale names. A crash can
+  // leave duplicates, but never a gap; the next reconciliation removes them.
+  await writeAtomic(join(stateDir, keyFileName), serialized, 0o600);
+  await writeAtomic(join(stateDir, paneIdFileName), serialized, 0o600);
+  await cleanupSupersededSessionMappings(
+    stateDir,
+    [keyFileName, paneIdFileName],
+    session.sessionFile,
+    { paneId: info.paneId, tmuxServerPid: info.tmuxServerPid },
+  );
+  return { keyFileName, paneIdFileName };
+}

package/src/domain/pane-info.ts

@@ -12,7 +12,7 @@ export function parsePaneInfoOutput(stdout: string, paneId: string): PaneInfo |
     return undefined;
   }
 
-  const [rawPaneKey, sessionName, rawWindowIndex, rawPaneIndex] = trimmed.split("\t");
+  const [rawPaneKey, sessionName, rawWindowIndex, rawPaneIndex, tmuxServerPid] = trimmed.split("\t");
   const paneKey = normalizePaneKey(rawPaneKey ?? "");
   if (!paneKey || !sessionName) {
     return undefined;
@@ -22,6 +22,7 @@ export function parsePaneInfoOutput(stdout: string, paneId: string): PaneInfo |
     backend: "tmux",
     paneKey,
     paneId,
+    tmuxServerPid: tmuxServerPid || null,
     sessionName,
     windowIndex: parseTmuxIndex(rawWindowIndex ?? "0"),
     paneIndex: parseTmuxIndex(rawPaneIndex ?? "0"),
@@ -46,6 +47,7 @@ export function mexPaneInfo(sessionId: string | undefined): PaneInfo | undefined
     backend: "mex",
     paneKey: `mex:${sessionId}`,
     paneId: sessionId,
+    tmuxServerPid: null,
     sessionName: sessionId,
     windowIndex: 0,
     paneIndex: 0,
@@ -85,6 +87,7 @@ export function parseZellijPaneInfo(
     backend: "zellij",
     paneKey: `${sessionName}:${tabPosition}.${numericId}`,
     paneId: normalizedPaneId,
+    tmuxServerPid: null,
     sessionName,
     windowIndex: tabPosition,
     paneIndex: numericId,

package/src/domain/pane-key.ts

@@ -48,6 +48,11 @@ export function mappingFileName(key: string): string {
   return `${keyFileStem(key)}.session`;
 }
 
+/** Stable live-pane alias used to reconcile index changes while tmux runs. */
+export function paneIdMappingFileName(paneId: string): string {
+  return `pane-id-${keyFileStem(paneId)}.session`;
+}
+
 /** File name of the tws status file for a raw pane key. */
 export function statusFileName(key: string): string {
   return `${keyFileStem(key)}.json`;

package/src/domain/session-file.ts

@@ -0,0 +1,55 @@
+import { open } from "node:fs/promises";
+
+export type SessionHeader = {
+  id: string;
+  cwd: string;
+  version: number;
+};
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+export function parseSessionHeader(line: string): SessionHeader | undefined {
+  let value: unknown;
+  try {
+    value = JSON.parse(line);
+  } catch {
+    return undefined;
+  }
+  if (
+    !isRecord(value)
+    || value.type !== "session"
+    || typeof value.id !== "string"
+    || value.id === ""
+    || typeof value.cwd !== "string"
+    || value.cwd === ""
+    || typeof value.version !== "number"
+    || !Number.isInteger(value.version)
+    || value.version < 1
+    || value.version > 3
+  ) {
+    return undefined;
+  }
+  return { id: value.id, cwd: value.cwd, version: value.version };
+}
+
+export async function readSessionHeader(path: string): Promise<SessionHeader | undefined> {
+  let handle;
+  try {
+    handle = await open(path, "r");
+    const buffer = Buffer.alloc(64 * 1024);
+    const { bytesRead } = await handle.read(buffer, 0, buffer.length, 0);
+    const firstLine = buffer.subarray(0, bytesRead).toString("utf8").split(/\r?\n/, 1)[0] ?? "";
+    return parseSessionHeader(firstLine);
+  } catch {
+    return undefined;
+  } finally {
+    await handle?.close();
+  }
+}
+
+export async function sessionFileMatches(path: string, sessionId: string): Promise<boolean> {
+  const header = await readSessionHeader(path);
+  return header?.id === sessionId;
+}

package/src/domain/session-mapping.ts

@@ -1,4 +1,4 @@
-export type SessionMapping = {
+export type SessionMappingV2 = {
   schema: 2;
   paneKey: string;
   sessionFile: string;
@@ -8,16 +8,52 @@ export type SessionMapping = {
   updatedAtMs: number;
 };
 
+export type SessionMapping = {
+  schema: 3;
+  paneKey: string;
+  paneId: string;
+  tmuxServerPid: string;
+  sessionFile: string;
+  sessionId: string;
+  cwd: string;
+  sessionName: string | null;
+  updatedAtMs: number;
+};
+
+export type StructuredSessionMapping = SessionMappingV2 | SessionMapping;
+
 export type ParsedSessionMapping =
-  | { format: "structured"; mapping: SessionMapping }
+  | { format: "structured"; mapping: StructuredSessionMapping }
   | { format: "legacy"; sessionFile: string };
 
 function isRecord(value: unknown): value is Record<string, unknown> {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 
+type CommonMappingFields = {
+  paneKey: string;
+  sessionFile: string;
+  sessionId: string;
+  cwd: string;
+  sessionName: string | null;
+  updatedAtMs: number;
+};
+
+function hasCommonFields(value: Record<string, unknown>): value is Record<string, unknown> & CommonMappingFields {
+  return (
+    typeof value.paneKey === "string"
+    && typeof value.sessionFile === "string"
+    && typeof value.sessionId === "string"
+    && typeof value.cwd === "string"
+    && (typeof value.sessionName === "string" || value.sessionName === null)
+    && typeof value.updatedAtMs === "number"
+  );
+}
+
 export function buildSessionMapping(
   paneKey: string,
+  paneId: string,
+  tmuxServerPid: string,
   sessionFile: string,
   sessionId: string,
   cwd: string,
@@ -25,8 +61,10 @@ export function buildSessionMapping(
   updatedAtMs: number,
 ): SessionMapping {
   return {
-    schema: 2,
+    schema: 3,
     paneKey,
+    paneId,
+    tmuxServerPid,
     sessionFile,
     sessionId,
     cwd,
@@ -54,30 +92,46 @@ export function parseSessionMapping(content: string): ParsedSessionMapping | und
   } catch {
     return undefined;
   }
+  if (!isRecord(value) || !hasCommonFields(value)) {
+    return undefined;
+  }
+  if (value.schema === 2) {
+    return {
+      format: "structured",
+      mapping: {
+        schema: 2,
+        paneKey: value.paneKey,
+        sessionFile: value.sessionFile,
+        sessionId: value.sessionId,
+        cwd: value.cwd,
+        sessionName: value.sessionName,
+        updatedAtMs: value.updatedAtMs,
+      },
+    };
+  }
   if (
-    !isRecord(value)
-    || value.schema !== 2
-    || typeof value.paneKey !== "string"
-    || typeof value.sessionFile !== "string"
-    || typeof value.sessionId !== "string"
-    || typeof value.cwd !== "string"
-    || !(typeof value.sessionName === "string" || value.sessionName === null)
-    || typeof value.updatedAtMs !== "number"
+    value.schema === 3
+    && typeof value.paneId === "string"
+    && value.paneId !== ""
+    && typeof value.tmuxServerPid === "string"
+    && value.tmuxServerPid !== ""
   ) {
-    return undefined;
+    return {
+      format: "structured",
+      mapping: {
+        schema: 3,
+        paneKey: value.paneKey,
+        paneId: value.paneId,
+        tmuxServerPid: value.tmuxServerPid,
+        sessionFile: value.sessionFile,
+        sessionId: value.sessionId,
+        cwd: value.cwd,
+        sessionName: value.sessionName,
+        updatedAtMs: value.updatedAtMs,
+      },
+    };
   }
-  return {
-    format: "structured",
-    mapping: {
-      schema: 2,
-      paneKey: value.paneKey,
-      sessionFile: value.sessionFile,
-      sessionId: value.sessionId,
-      cwd: value.cwd,
-      sessionName: value.sessionName,
-      updatedAtMs: value.updatedAtMs,
-    },
-  };
+  return undefined;
 }
 
 export function mappedSessionFile(content: string): string | undefined {
@@ -87,3 +141,14 @@ export function mappedSessionFile(content: string): string | undefined {
   }
   return parsed.format === "structured" ? parsed.mapping.sessionFile : parsed.sessionFile;
 }
+
+export function mappedPaneIdentity(content: string): { paneId: string; tmuxServerPid: string } | undefined {
+  const parsed = parseSessionMapping(content);
+  if (!parsed || parsed.format !== "structured" || parsed.mapping.schema !== 3) {
+    return undefined;
+  }
+  return {
+    paneId: parsed.mapping.paneId,
+    tmuxServerPid: parsed.mapping.tmuxServerPid,
+  };
+}

package/src/domain/status.ts

@@ -4,6 +4,7 @@ export type PaneInfo = {
   backend: "tmux" | "zellij" | "mex";
   paneKey: string;
   paneId: string;
+  tmuxServerPid: string | null;
   sessionName: string;
   windowIndex: number;
   paneIndex: number;

package/src/index.ts

@@ -4,13 +4,13 @@ import { open, utimes } from "node:fs/promises";
 import { homedir } from "node:os";
 import { join } from "node:path";
 
-import { cleanupStaleSessionMappings, cleanupStaleTempFiles, cleanupSupersededSessionMappings, cleanupSupersededStatusFiles, ensureDirectory, writeAtomic } from "./domain/atomic-write.ts";
+import { cleanupStaleSessionMappings, cleanupStaleTempFiles, cleanupSupersededStatusFiles, ensureDirectory, writeAtomic } from "./domain/atomic-write.ts";
 import { createAsyncQueue } from "./domain/async-queue.ts";
 import { createThrottledErrorReporter } from "./domain/error-reporter.ts";
-import { PANE_KEY_FORMAT, defaultStateDir, mappingFileName, statusFileName } from "./domain/pane-key.ts";
+import { publishSessionMapping } from "./domain/mapping-publisher.ts";
+import { PANE_KEY_FORMAT, defaultStateDir, statusFileName } from "./domain/pane-key.ts";
 import { parsePaneInfoOutput, parseZellijPaneInfo, mexPaneInfo } from "./domain/pane-info.ts";
 import { buildRestoreAck, restoreAckPath, restoreExpectationFromEnvironment, serializeRestoreAck } from "./domain/restore-ack.ts";
-import { buildSessionMapping, serializeSessionMapping } from "./domain/session-mapping.ts";
 import { createRuntimeState, nextStatusTransition, refreshStatusTransition, type FinalWorkState, type RuntimeState, type WorkState } from "./domain/state.ts";
 import { buildTwsStatusPayload, serializeStatusPayload, type PaneInfo, type SessionInfo } from "./domain/status.ts";
 
@@ -33,7 +33,11 @@ const tmuxBin = process.env.PI_TMUX_SESSION_MAP_TMUX_BIN ?? "tmux";
 const zellijBin = process.env.PI_TMUX_SESSION_MAP_ZELLIJ_BIN ?? "zellij";
 const muxTimeoutMs = 1000;
 const cleanupMaxAgeMs = 24 * 60 * 60 * 1000;
-const PANE_INFO_FORMAT = `${PANE_KEY_FORMAT}\t#{session_name}\t#{window_index}\t#{pane_index}`;
+const reconcileIntervalMs = Math.max(
+  10_000,
+  Number.parseInt(process.env.PI_TMUX_SESSION_MAP_RECONCILE_INTERVAL_MS ?? "60000", 10) || 60_000,
+);
+const PANE_INFO_FORMAT = `${PANE_KEY_FORMAT}\t#{session_name}\t#{window_index}\t#{pane_index}\t#{pid}`;
 
 type StatusAction = WorkState | "refresh" | null;
 
@@ -139,7 +143,24 @@ export function sessionMappingSignature(
   if (session.sessionFile === null || info.backend !== "tmux") {
     return null;
   }
-  return JSON.stringify([info.paneKey, session.sessionFile, sessionId, session.cwd, session.sessionName]);
+  return JSON.stringify([
+    info.paneKey,
+    info.paneId,
+    info.tmuxServerPid,
+    session.sessionFile,
+    sessionId,
+    session.cwd,
+    session.sessionName,
+  ]);
+}
+
+export function reconciliationDelayMs(identity: string, intervalMs = reconcileIntervalMs): number {
+  let hash = 2166136261;
+  for (const byte of Buffer.from(identity, "utf8")) {
+    hash ^= byte;
+    hash = Math.imul(hash, 16777619) >>> 0;
+  }
+  return hash % intervalMs;
 }
 
 export function twsStatusSignature(
@@ -153,6 +174,7 @@ export function twsStatusSignature(
     info.backend,
     info.paneKey,
     info.paneId,
+    info.tmuxServerPid,
     info.sessionName,
     info.windowIndex,
     info.paneIndex,
@@ -165,22 +187,8 @@ export function twsStatusSignature(
   ]);
 }
 
-async function writeSessionMapping(info: PaneInfo, session: SessionInfo, sessionId: string): Promise<void> {
-  if (session.sessionFile === null) {
-    return;
-  }
-  const fileName = mappingFileName(info.paneKey);
-  const mapping = buildSessionMapping(
-    info.paneKey,
-    session.sessionFile,
-    sessionId,
-    session.cwd,
-    session.sessionName,
-    Date.now(),
-  );
-  await ensureDirectory(stateDir);
-  await writeAtomic(join(stateDir, fileName), serializeSessionMapping(mapping), 0o600);
-  await cleanupSupersededSessionMappings(stateDir, fileName, session.sessionFile);
+async function writeSessionMapping(info: PaneInfo, session: SessionInfo, sessionId: string): Promise<boolean> {
+  return (await publishSessionMapping(stateDir, info, session, sessionId)) !== undefined;
 }
 
 async function writeRestoreAcknowledgement(
@@ -281,8 +289,8 @@ async function applyEventAction(
   const sessionId = ctx.sessionManager.getSessionId();
   const mappingSignature = sessionMappingSignature(info, session, sessionId);
   if (mappingSessionFile !== null && mappingSignature !== null && mappingSignature !== artifactCache.mappingSignature) {
-    await writeSessionMapping(info, session, sessionId);
-    artifactCache.mappingSignature = mappingSignature;
+    const published = await writeSessionMapping(info, session, sessionId);
+    artifactCache.mappingSignature = published ? mappingSignature : null;
   }
 
   if (action.restoreReason !== undefined && info.backend === "tmux") {
@@ -355,6 +363,40 @@ export default function tmuxSessionMap(pi: ExtensionAPI) {
     });
   };
 
+  let reconciliationTimer: ReturnType<typeof setTimeout> | undefined;
+  let reconciliationActive = false;
+
+  const stopReconciliation = () => {
+    reconciliationActive = false;
+    if (reconciliationTimer !== undefined) {
+      clearTimeout(reconciliationTimer);
+      reconciliationTimer = undefined;
+    }
+  };
+
+  const scheduleReconciliation = (ctx: ExtensionContext, delayMs: number) => {
+    reconciliationTimer = setTimeout(async () => {
+      reconciliationTimer = undefined;
+      if (!reconciliationActive) {
+        return;
+      }
+      await enqueue(ctx, { mapping: true, status: "refresh", refreshPane: true });
+      if (reconciliationActive) {
+        scheduleReconciliation(ctx, reconcileIntervalMs);
+      }
+    }, delayMs);
+    reconciliationTimer.unref();
+  };
+
+  const startReconciliation = (ctx: ExtensionContext) => {
+    stopReconciliation();
+    if (!process.env.TMUX || !process.env.TMUX_PANE) {
+      return;
+    }
+    reconciliationActive = true;
+    scheduleReconciliation(ctx, reconciliationDelayMs(process.env.TMUX_PANE));
+  };
+
   // Intentionally no cleanup on session_shutdown: the mapping must survive a
   // tmux server restart so resurrect can restore the exact session.
   pi.on("session_start", async (event, ctx) => {
@@ -370,6 +412,7 @@ export default function tmuxSessionMap(pi: ExtensionAPI) {
       restoreReason: event.reason,
       refreshPane: true,
     });
+    startReconciliation(ctx);
   });
   pi.on("session_info_changed", async (_event, ctx) => {
     await enqueue(ctx, { mapping: true, status: "refresh", refreshPane: true });
@@ -395,6 +438,7 @@ export default function tmuxSessionMap(pi: ExtensionAPI) {
     await enqueue(ctx, { mapping: true, status: pendingFinalState });
   });
   pi.on("session_shutdown", async (_event, ctx) => {
+    stopReconciliation();
     await enqueue(ctx, { mapping: false, status: "shutdown" });
     artifactCache.paneInfo = undefined;
     artifactCache.paneInfoResolved = false;