pi-tmux-session-map 0.3.0 → 0.5.0

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/signal-evidence.ts

@@ -0,0 +1,56 @@
+// Records whether this process received SIGHUP or SIGTERM, so a session_shutdown
+// caused by a closed terminal, a dead tmux server or a reboot can be told apart
+// from an interactive quit (both reach extensions as reason "quit").
+//
+// Pi's own handler starts the shutdown from the same signal dispatch. The
+// listener here only sets a flag; consumers read it later, when the queued
+// status write builds its payload: Node runs every signal listener
+// synchronously before any promise continuation, so the flag is set by then
+// regardless of listener order.
+
+export type TerminationSignal = "SIGHUP" | "SIGTERM";
+
+type SignalTarget = {
+  prependListener(event: TerminationSignal, listener: () => void): unknown;
+  removeListener(event: TerminationSignal, listener: () => void): unknown;
+};
+
+let recorded: TerminationSignal | null = null;
+
+export function recordedTerminationSignal(): TerminationSignal | null {
+  return recorded;
+}
+
+/** Test hook: forget a recorded signal. */
+export function resetRecordedTerminationSignal(): void {
+  recorded = null;
+}
+
+export type SignalEvidenceListener = {
+  install(): void;
+  uninstall(): void;
+};
+
+export function createSignalEvidenceListener(target: SignalTarget = process): SignalEvidenceListener {
+  const listeners = new Map<TerminationSignal, () => void>();
+  return {
+    install() {
+      if (listeners.size > 0) {
+        return;
+      }
+      for (const signal of ["SIGHUP", "SIGTERM"] as const) {
+        const listener = () => {
+          recorded ??= signal;
+        };
+        listeners.set(signal, listener);
+        target.prependListener(signal, listener);
+      }
+    },
+    uninstall() {
+      for (const [signal, listener] of listeners) {
+        target.removeListener(signal, listener);
+      }
+      listeners.clear();
+    },
+  };
+}

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;
@@ -15,6 +16,44 @@ export type SessionInfo = {
   sessionName: string | null;
 };
 
+export type LiveSessionIdentity = {
+  sessionId: string;
+  piPid: number;
+};
+
+/** Leaf before the run's prompt entry and the run start (agent_start). */
+export type RunAnchor = {
+  leaf_id: string | null;
+  started_at_ms: number;
+};
+
+/**
+ * Why a session_shutdown happened: a SIGHUP/SIGTERM (terminal closed, tmux server
+ * died, reboot), an interactive quit, a reload, or a session replacement.
+ */
+export type ShutdownCause = "signal" | "quit" | "reload" | "replace";
+
+/**
+ * Auto-continue state of this Pi for displays (TWS). `state`: planned, dispatched, admitted, an
+ * outcome (done, failed, cancelled, …), uncertain, skipped or stopped; `reason` for skipped and
+ * stopped. Slot and deadline come from the released plan; `key` and `ledger_dir` name the ledger
+ * entry, where TWS may veto a planned continuation with `<key>.skip`.
+ */
+export type ContinueStatus = {
+  state: string;
+  reason: string | null;
+  slot_ms: number | null;
+  deadline_ms: number | null;
+  key: string;
+  ledger_dir: string;
+};
+
+export type RecoveryEvidence = {
+  runAnchor: RunAnchor | null;
+  shutdownCause: ShutdownCause | null;
+  continueState?: ContinueStatus | null;
+};
+
 export type TwsStatusPayload = {
   schema: 1;
   agent: "pi";
@@ -27,10 +66,18 @@ export type TwsStatusPayload = {
   cwd: string;
   session_file: string | null;
   session_name: string | null;
+  // Additive live identity: valid even before the session JSONL exists.
+  session_id: string;
+  pi_pid: number;
+  tmux_server_pid: string | null;
   state: WorkState;
   updated_at_ms: number;
   started_at_ms: number | null;
   finished_at_ms: number | null;
+  // Additive recovery evidence for tmux-recovery's auto-continue decision.
+  run_anchor: RunAnchor | null;
+  shutdown_cause: ShutdownCause | null;
+  continue?: ContinueStatus;
 };
 
 export function buildTwsStatusPayload(
@@ -40,6 +87,8 @@ export function buildTwsStatusPayload(
   updatedAtMs: number,
   startedAtMs: number | null,
   finishedAtMs: number | null,
+  identity: LiveSessionIdentity,
+  evidence: RecoveryEvidence = { runAnchor: null, shutdownCause: null },
 ): TwsStatusPayload {
   return {
     schema: 1,
@@ -53,10 +102,16 @@ export function buildTwsStatusPayload(
     cwd: session.cwd,
     session_file: session.sessionFile,
     session_name: session.sessionName,
+    session_id: identity.sessionId,
+    pi_pid: identity.piPid,
+    tmux_server_pid: pane.tmuxServerPid,
     state,
     updated_at_ms: updatedAtMs,
     started_at_ms: startedAtMs,
     finished_at_ms: finishedAtMs,
+    run_anchor: evidence.runAnchor,
+    shutdown_cause: state === "shutdown" ? evidence.shutdownCause : null,
+    ...(evidence.continueState ? { continue: evidence.continueState } : {}),
   };
 }