@volter/supercode-terminal 0.3.0 → 0.3.1

package/index.mjs

@@ -24,6 +24,14 @@ const SESSION_NAME = /^[A-Za-z0-9_-]{1,64}$/;
 // relay clients.) Session-scoped, so other sessions on the same tmux server
 // keep their own settings.
 const TERMINAL_LIKE_SESSION = Object.freeze({ status: 'off', mouse: 'off', prefix: 'None', prefix2: 'None', 'remain-on-exit': 'failed' });
+// A pane session (p_*) keeps its pane after its program ends however it ended, a clean end included, until the
+// pane's end is in the pane-exit log: the record is written from the dead pane's own status, by the substrate's
+// pane-died hook or by this host (#sessionNames), whichever reads the pane first, and the pane is closed after it.
+// Only p_* sessions: they are the ones the hook and the host close.
+const PANE_SESSION = Object.freeze({ ...TERMINAL_LIKE_SESSION, 'remain-on-exit': 'on' });
+// What tmux draws in a dead pane (tmux 3.3 and later; before it the line is tmux's own and cannot be set): nothing
+// for a clean end, whose pane is about to close, and tmux's own default line for a failed one.
+const PANE_DEAD_LINE = '#{?#{&&:#{==:#{pane_dead_status},0},#{==:#{pane_dead_signal},}},,Pane is dead (#{?#{!=:#{pane_dead_status},},status #{pane_dead_status},}#{?#{!=:#{pane_dead_signal},},signal #{pane_dead_signal},}#, #{t:pane_dead_time})}';
 
 function runTmuxInput(socket, args, input = null) {
   return new Promise((resolve, reject) => {
@@ -167,6 +175,8 @@ export class TerminalWebSocketBridge {
 
 export class TmuxTerminalHost {
   #allowUnownedControl;
+  #answered = false;
+  #dead = new Map();
   #generation = 0;
   #listing = null;
   #attachments = new Map();
@@ -213,6 +223,12 @@ export class TmuxTerminalHost {
   /** Complete context observation for callers deciding whether a pane has ended. */
   hasLiveContext(contextKey) {
     assertContextKey(contextKey);
+    // A pane session whose program has ended is closed first, so tmux's answer is of the sessions something runs in.
+    // When the server answered and none is left, that is the complete reading: a server closing its last pane has
+    // no session to list and is not yet gone. A server that could not be read here is tmux's own reading below.
+    let names = null;
+    try { names = this.#sessionNames(); } catch { /* read below */ }
+    if (names && !names.length && this.#answered) return Promise.resolve(false);
     return this.#tmux.hasSessionContextAsync(this.#contextOption, contextKey, this.#socket);
   }
 
@@ -226,6 +242,9 @@ export class TmuxTerminalHost {
         this.#catalog.delete(id);
       }
     }
+    // No session, nothing more to ask: a server left with none is on its way out, and answers the readings below
+    // "no current target" until it is gone.
+    if (!names.length) return [];
     const panes = this.#panes();
     const [contextKeys, sizes] = await Promise.all([
       this.#tmux.sessionOptionValuesAsync(this.#contextOption, this.#socket),
@@ -236,7 +255,10 @@ export class TmuxTerminalHost {
       const id = this.#catalogId(name);
       const pane = panes.find((candidate) => candidate.session === name && candidate.window === 0 && candidate.pane === 0);
       const size = sizes.get(name);
+      const dead = this.#dead.get(name);
       return Object.freeze({
+        // a session of another name whose program failed: tmux keeps its pane for its last screen, and nothing runs in it
+        ...(dead ? { dead: true, exitCode: dead.exitCode } : {}),
         activeCommand: pane?.currentCommand ?? null,
         rootPid: pane?.rootPid ?? null,
         contextKey: contextKeys.get(name) ?? null,
@@ -275,7 +297,8 @@ export class TmuxTerminalHost {
       ownerOption: this.#ownerOption,
       panes: 1,
       sessionOptions: input.contextKey ? { [this.#contextOption]: input.contextKey } : {},
-      settings: TERMINAL_LIKE_SESSION,
+      settings: name.startsWith('p_') ? PANE_SESSION : TERMINAL_LIKE_SESSION,
+      optionalSettings: name.startsWith('p_') ? { 'remain-on-exit-format': PANE_DEAD_LINE } : {},
       socket: this.#socket,
     });
     // Raised once tmux has the session: a listing started before then cannot be the one that answers below.
@@ -415,6 +438,9 @@ export class TmuxTerminalHost {
       throw new TerminalHostError('close_not_allowed', 'This host does not own that tmux session.');
     }
     this.#tmux.killSessionProcessTree({ session: entry.name, socket: this.#socket });
+    // The close's own record: tmux's session-closed hook writes it too, but not when this session was the server's
+    // last (the server exits before the hook's run-shell has started).
+    if (entry.name.startsWith('p_') && !paneExitRecorded(entry.name)) recordPaneExit(entry.name, 0, null, null, hookStamp());
     this.#generation += 1;
     this.#catalog.delete(sessionId);
     this.#idByName.delete(entry.name);
@@ -491,13 +517,43 @@ export class TmuxTerminalHost {
     }
   }
 
+  /**
+   * The sessions something runs in. A session whose pane's program has ended is still a session to tmux, kept by
+   * `remain-on-exit`; it is never answered as one here, to any caller (a listing, a liveness reading, an attachment,
+   * input, a close, a name's reuse). A pane session (p_*) in that state is finished off here as the pane-died hook
+   * would: its end written to the pane-exit log when no line names the pane yet (the screen with it when it failed),
+   * then the pane closed. So neither the record nor the pane's removal waits on a run-shell inside the server, which
+   * a server without `tmux` on its PATH cannot run. A session of another name is not this host's to close (tmux keeps
+   * its failed pane for its last screen): it stays listed, marked `dead` with its `exitCode`, as the ConPTY host
+   * marks one.
+   */
   #sessionNames() {
+    let states;
+    this.#answered = false;
     try {
-      return this.#tmux.listTmuxSessionNames(this.#socket);
+      states = this.#tmux.listSessionStates(this.#socket);
+      this.#answered = true;
     } catch (error) {
-      if (isEmptyServerError(error)) return [];
-      throw error;
+      if (!isEmptyServerError(error)) throw error;
+      states = [];
+    }
+    const names = [];
+    this.#dead.clear();
+    for (const state of states) {
+      if (!state.dead) names.push(state.name);
+      else if (!state.name.startsWith('p_')) { names.push(state.name); this.#dead.set(state.name, { exitCode: state.exitCode }); }
+      else {
+        if (!paneExitRecorded(state.name)) {
+          const failed = state.exitCode !== 0 || Boolean(state.signal);
+          let screen = null;
+          if (failed) { try { screen = this.#tmux.capturePane({ lines: 200, preserveEscapes: true, socket: this.#socket, target: state.paneId }); } catch { /* the pane is gone */ } }
+          recordPaneExit(state.name, state.exitCode, state.signal, screen, hookStamp());
+        }
+        this.#tmux.closeDeadPane({ paneId: state.paneId, session: state.name, socket: this.#socket });
+        this.#generation += 1;
+      }
     }
+    return names;
   }
 }
 
@@ -578,9 +634,23 @@ for (const event of ['end', 'close', 'error']) process.stdin.on(event, sweep);
  * signal=…` when it failed), under SUPERCODE_HOME or ~/.config/supercode: the machine daemon tells a clean finish from
  * a failure by it, and a ConPTY pane that ended cleanly is otherwise gone without a trace.
  */
-function recordPaneExit(contextKey, exitCode, signal, screen = null) {
+/** Whether the pane-exit log (either home's) holds a line of this pane's end. */
+function paneExitRecorded(pane) {
+  for (const root of new Set([process.env.SUPERCODE_HOME, join(homedir(), '.config', 'supercode')].filter(Boolean))) {
+    try { if (readFileSync(join(root, 'pane-exits.log'), 'utf8').split('\n').some((line) => line.endsWith(` ${pane} closed`) || line.includes(` ${pane} died `))) return true; }
+    catch { /* no log there */ }
+  }
+  return false;
+}
+
+/** Now as the tmux hooks stamp a line (`date +%FT%T`, the machine's own time): one log's lines are ordered by it. */
+function hookStamp() {
+  const now = new Date(), two = (value) => String(value).padStart(2, '0');
+  return `${now.getFullYear()}-${two(now.getMonth() + 1)}-${two(now.getDate())}T${two(now.getHours())}:${two(now.getMinutes())}:${two(now.getSeconds())}`;
+}
+
+function recordPaneExit(contextKey, exitCode, signal, screen = null, at = new Date().toISOString().slice(0, 19)) {
   if (!contextKey) return;
-  const at = new Date().toISOString().slice(0, 19);
   const line = exitCode === 0 && !signal ? `${at} ${contextKey} closed\n` : `${at} ${contextKey} died status=${exitCode ?? ''} signal=${signal || ''}\n`;
   try { appendFileSync(join(process.env.SUPERCODE_HOME || join(homedir(), '.config', 'supercode'), 'pane-exits.log'), line); } catch { /* no log is no worse than before */ }
   if ((exitCode !== 0 || signal) && typeof screen === 'string' && /^p_[A-Za-z0-9_-]+$/.test(contextKey)) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@volter/supercode-terminal",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "type": "module",
   "description": "Optional leak-safe terminal and tmux host adapter for Volter Harness frontends",
   "exports": {

package/substrate/tmux.d.ts

@@ -25,12 +25,13 @@ export type CreateSessionOptions = {
     panes: number;
     sessionOptions?: Record<string, string>;
     settings?: Record<string, string>;
+    optionalSettings?: Record<string, string>;
     socket?: string;
 };
 export declare function assertTmux(): void;
 export declare function targetForSession(sessionName: string): string;
 export declare function assertSession(name: string, socket?: string): void;
-export declare function createSession({ command, cwd, env, name, owner, ownerOption: ownershipOption, panes, sessionOptions, settings, socket }: CreateSessionOptions): Promise<{
+export declare function createSession({ command, cwd, env, name, owner, ownerOption: ownershipOption, panes, sessionOptions, settings, optionalSettings, socket }: CreateSessionOptions): Promise<{
     name: string;
     panes: number;
 }>;
@@ -49,6 +50,33 @@ export declare function killSessionProcessTree({ session, socket }: {
     socket?: string;
 }): void;
 export declare function listTmuxSessionNames(socket?: string): string[];
+export type TmuxSessionState = {
+    name: string;
+    /** The id (`%N`) of the session's pane. */
+    paneId: string;
+    /** Whether the pane's program has ended and tmux keeps the pane (`remain-on-exit`). */
+    dead: boolean;
+    /** The ended program's exit status, when it exited; null when a signal ended it or tmux does not say. */
+    exitCode: number | null;
+    /** The signal that ended the program, as tmux names it; empty when it exited. */
+    signal: string;
+};
+/**
+ * Every session with whether its pane's program has ended, in one tmux process. A session whose pane is dead is
+ * still a session to tmux (`list-sessions` names it, `has-session` finds it) though nothing runs in it: a caller
+ * that asks only for names takes it for a live one. Throws as `listTmuxSessionNames` does when there is no server.
+ */
+export declare function listSessionStates(socket?: string): TmuxSessionState[];
+/**
+ * Closes one dead pane, and only it: the kill is tmux's own decision, in the server, on the pane being dead and
+ * still in the named session, so a pane id that another session has since been given (a server that restarted) or a
+ * session started again under the same name is never closed. Answers nothing; a pane already gone is the same end.
+ */
+export declare function closeDeadPane({ paneId, session, socket }: {
+    paneId: string;
+    session: string;
+    socket?: string;
+}): void;
 export declare function selectOrphanSessions({ allSessions, ownedSessions, prefix }: {
     allSessions: string[];
     ownedSessions: Iterable<string>;

package/substrate/tmux.js

@@ -41,7 +41,7 @@ export function assertSession(name, socket) {
 // createWindowSession), so every tmux invocation here uses runAsync (spawn, not
 // spawnSync) and the pane-ready poll below uses sleepAsync — see waitForPanesReady.
 // Nothing in this function may block the loop.
-export async function createSession({ command, cwd, env, name, owner, ownerOption: ownershipOption = ownerOption, panes, sessionOptions = {}, settings = {}, socket }) {
+export async function createSession({ command, cwd, env, name, owner, ownerOption: ownershipOption = ownerOption, panes, sessionOptions = {}, settings = {}, optionalSettings = {}, socket }) {
     assertTmux();
     if (!name) {
         throw new Error("--name is required.");
@@ -98,12 +98,12 @@ export async function createSession({ command, cwd, env, name, owner, ownerOptio
         // session with it before `remain-on-exit` or the owner stamp is set, and
         // the next set-option's "no such session" replaces the program's own
         // failure in what the launcher reports.
-        const setOnCreate = (option, value) => {
+        const setOnCreate = (option, value, quiet = false) => {
             assertOptionValue(value);
             // tmux splits commands at an argument that ends in `;`.
             if (value.endsWith(";"))
                 throw new Error(`A tmux option value set at creation cannot end in ";": ${option}`);
-            startArgs.push(";", "set-option", "-t", name, option, value);
+            startArgs.push(";", "set-option", ...(quiet ? ["-q"] : []), "-t", name, option, value);
         };
         if (owner)
             setOnCreate(ownershipOption, owner);
@@ -115,6 +115,10 @@ export async function createSession({ command, cwd, env, name, owner, ownerOptio
             assertSettingName(option);
             setOnCreate(option, value);
         }
+        for (const [option, value] of Object.entries(optionalSettings).sort(([left], [right]) => left.localeCompare(right))) {
+            assertSettingName(option);
+            setOnCreate(option, value, true);
+        }
         await runTmuxSessionCreateAsync(startArgs, { cwd, operation: "create tmux session", session: name, socket });
         await declareSessionColorEnvironmentAsync(socket);
         const target = targetForSession(name);
@@ -329,6 +333,34 @@ export function killSessionProcessTree({ session, socket }) {
 export function listTmuxSessionNames(socket) {
     return run("tmux", tmuxArgs(socket, ["list-sessions", "-F", "#{session_name}"])).split("\n").map((line) => line.trim()).filter(Boolean);
 }
+// The name last: tmux guarantees a session name holds no colon, and the fields before it never do.
+const sessionStateFormat = "#{pane_id}:#{pane_dead}:#{pane_dead_status}:#{pane_dead_signal}:#{session_name}";
+/**
+ * Every session with whether its pane's program has ended, in one tmux process. A session whose pane is dead is
+ * still a session to tmux (`list-sessions` names it, `has-session` finds it) though nothing runs in it: a caller
+ * that asks only for names takes it for a live one. Throws as `listTmuxSessionNames` does when there is no server.
+ */
+export function listSessionStates(socket) {
+    return run("tmux", tmuxArgs(socket, ["list-sessions", "-F", sessionStateFormat])).split("\n").filter((line) => line.trim()).map((line) => {
+        const [paneId = "", dead = "", status = "", signal = "", ...name] = line.split(":");
+        return { name: name.join(":"), paneId, dead: dead === "1", exitCode: /^\d+$/.test(status) ? Number(status) : null, signal };
+    });
+}
+/**
+ * Closes one dead pane, and only it: the kill is tmux's own decision, in the server, on the pane being dead and
+ * still in the named session, so a pane id that another session has since been given (a server that restarted) or a
+ * session started again under the same name is never closed. Answers nothing; a pane already gone is the same end.
+ */
+export function closeDeadPane({ paneId, session, socket }) {
+    if (!/^%\d+$/.test(paneId) || !/^[A-Za-z0-9_-]+$/.test(session))
+        return;
+    try {
+        run("tmux", tmuxArgs(socket, ["if-shell", "-F", "-t", paneId, `#{&&:#{pane_dead},#{==:#{session_name},${session}}}`, `kill-pane -t ${paneId}`]));
+    }
+    catch {
+        // the pane is gone already
+    }
+}
 // A session belongs to a provider's prefix iff it is the bare `prefix` or a
 // `prefix-*` child. The exact `-` boundary is load-bearing: prefix `worker` must
 // not claim `worker-pool-1`. The single home for that rule.
@@ -380,8 +412,17 @@ async function declareSessionColorEnvironmentAsync(socket) {
 // runs in the same invocation — `run` uses spawnSync without a shell, so the `;`
 // reaches tmux as a literal command separator, not a shell metacharacter.
 // A supercode pane (p_*) that ends leaves one line in the pane-exit log: its exit
-// status or signal when it failed (the session keeps a failed pane just long
-// enough for tmux to report it, then closes it), `closed` when it ended cleanly.
+// status or signal when it failed, `closed` when it ended cleanly. The pane-died
+// hook writes it from the dead pane's own status while the session still holds
+// the pane (its host creates p_* sessions with `remain-on-exit on`), and only then
+// closes the pane: a record written after the session is gone is lost when that
+// session was the server's last, because a server with no session exits
+// (`exit-empty`) before a hook's run-shell has started. The session-closed hook
+// writes `closed` for a session closed from outside, where no pane dies; the
+// host writes that line itself for the closes it performs.
+// The hook reads the pane's state in one `display`, so the status and the signal
+// are of one moment: a pane that is gone or not dead by then leaves no line.
+// Its screen is kept only when it failed, and only from a capture that worked.
 // The pane-died hook acts on the pane that died, named by `#{hook_pane}`, and on
 // nothing else: when its session is already gone (a close kills the session, then
 // its processes), tmux resolves an untargeted `kill-pane` and `#{session_name}` to
@@ -389,8 +430,8 @@ async function declareSessionColorEnvironmentAsync(socket) {
 // Targets are not expanded as formats, so the shell that run-shell starts resolves
 // the pane and does nothing when it no longer belongs to a p_* session.
 const PANE_EXIT_LOG = '"${SUPERCODE_HOME:-$HOME/.config/supercode}/pane-exits.log"';
-const PANE_EXIT_CAPTURE = 'case "$s" in *[!a-zA-Z0-9_-]*) exit 0 ;; esac; d="${SUPERCODE_HOME:-$HOME/.config/supercode}/pane-exits"; umask 077; mkdir -p "$d"; t capture-pane -p -e -S -200 -t "$p" 2>/dev/null | tail -c 32768 > "$d/$s.screen"';
-const PANE_DIED_HOOK = "run-shell 'p=\"#{hook_pane}\"; t() { tmux -S \"#{socket_path}\" \"$@\"; }; s=$(t display -p -t \"$p\" \"##{session_name}\" 2>/dev/null) || exit 0; case \"$s\" in p_*) ;; *) exit 0 ;; esac; printf \"%s %s died status=%s signal=%s\\n\" \"$(date +%FT%T)\" \"$s\" \"$(t display -p -t \"$p\" \"##{pane_dead_status}\")\" \"$(t display -p -t \"$p\" \"##{pane_dead_signal}\")\" >> " + PANE_EXIT_LOG + "; " + PANE_EXIT_CAPTURE + "; t kill-pane -t \"$p\"'";
+const PANE_EXIT_CAPTURE = 'case "$s" in *[!a-zA-Z0-9_-]*) exit 0 ;; esac; d="${SUPERCODE_HOME:-$HOME/.config/supercode}/pane-exits"; umask 077; mkdir -p "$d"; if t capture-pane -p -e -S -200 -t "$p" > "$d/$s.screen.part" 2>/dev/null; then tail -c 32768 "$d/$s.screen.part" > "$d/$s.screen"; fi; rm -f "$d/$s.screen.part"';
+const PANE_DIED_HOOK = "run-shell 'p=\"#{hook_pane}\"; t() { tmux -S \"#{socket_path}\" \"$@\"; }; r=$(t display -p -t \"$p\" \"##{pane_dead}|##{pane_dead_status}|##{pane_dead_signal}|##{session_name}\" 2>/dev/null) || exit 0; case \"$r\" in 1\\|*) ;; *) exit 0 ;; esac; st=$(printf %s \"$r\" | cut -d\"|\" -f2); sg=$(printf %s \"$r\" | cut -d\"|\" -f3); s=$(printf %s \"$r\" | cut -d\"|\" -f4-); case \"$s\" in p_*) ;; *) exit 0 ;; esac; if [ \"$st\" = 0 ] && [ -z \"$sg\" ]; then printf \"%s %s closed\\n\" \"$(date +%FT%T)\" \"$s\" >> " + PANE_EXIT_LOG + "; else printf \"%s %s died status=%s signal=%s\\n\" \"$(date +%FT%T)\" \"$s\" \"$st\" \"$sg\" >> " + PANE_EXIT_LOG + "; (" + PANE_EXIT_CAPTURE + "); fi; t kill-pane -t \"$p\"'";
 const SESSION_CLOSED_HOOK = "if-shell -F '#{m:p_*,#{hook_session_name}}' { run-shell 'printf \"%s %s closed\\n\" \"$(date +%FT%T)\" \"#{hook_session_name}\" >> " + PANE_EXIT_LOG + "' }";
 function sessionServerOptionArgs() {
     return [
@@ -510,8 +551,10 @@ export async function waitForPanesReady({ expectedPanes, socket, target, timeout
     const startedAt = Date.now();
     while (Date.now() - startedAt < timeoutMs) {
         const panes = await inspectPanesAsync(target, socket);
+        // A pane whose program has already ended is not waited for: it will not become ready, and its end is its
+        // caller's answer.
         const ready = panes.length === expectedPanes
-            && panes.every((pane) => pane.dead === false && pane.id);
+            && panes.every((pane) => pane.id);
         if (ready) {
             return panes;
         }