@volter/supercode-terminal 0.2.70 → 0.2.72

package/CAPABILITIES.md

@@ -23,7 +23,7 @@ means it must not be presented as supported.
 | Scrollback, selection and copy | UI/xterm | verified | Bounded scrollback and native xterm selection. |
 | Find in one terminal, next/previous match | UI | verified | Search covers the active xterm buffer. Cross-tab search is missing. |
 | URL detection | UI | partial | The stable xterm web-link provider is active; host policy and end-to-end link opening still need a dedicated proof. |
-| Exclusive input ownership | tmux/host | partial | `acquireInput`, `ownsInput` and `releaseInput` serialize a paste with other input and remain with the pane across a client restart. [Recorded tmux proof](../../docs/evidence/claude-input-2026-10-07.md#recorded-review-fixes) rejects a replacement while the badge is unrecorded, then confirms one native message after daemon restart. Older pane servers refuse this door; Windows ownership restart remains unmeasured. |
+| Exclusive input ownership | tmux/host | partial | `acquireInput`, `ownsInput` and `releaseInput` serialize a paste with other input and remain with the pane across a client restart. [Recorded tmux proof](../../docs/evidence/claude-input-2026-10-07.md#recorded-review-fixes) rejects a replacement while the badge is unrecorded, then confirms one native message after daemon restart. `PaneServerHost.createSession` can require this ABI before creating a pane; [manual old/current server admission](../../docs/evidence/launch-input-ownership-admission-2026-10-09.md) is recorded on macOS. Older pane servers refuse this door; Windows ownership restart and admission remain unmeasured. |
 | Paste and bracketed paste | UI | verified | Multiline or large pastes require confirmation; history is memory-only. Advanced transforms and slow paste are missing. |
 | Save terminal contents | UI | partial | The normal buffer is projected to a bounded plain-text download; the browser download boundary and continuous logging still need dedicated proof. |
 | Bell and background activity | UI | verified | A controlled tmux shell proved active visual bell plus inactive activity/bell tab state. System notifications are host policy. |

package/README.md

@@ -42,6 +42,23 @@ the fleet tool package dependency. Advanced hosts and legacy adapters may import
 subpaths are exported only for compatibility. Prefer the controller/client APIs
 above this layer for new applications.
 
+`TmuxTerminalHost`, `PtyTerminalHost` and `PaneServerHost` expose
+`hasLiveContext(contextKey)` for decisions that require a complete presence
+reading. Tmux reads all session IDs and context values in one command, without
+the ordinary option reader's best-effort fallback. Failed, incomplete or
+malformed identity reads reject; only an explicit no-server answer establishes
+emptiness after a failed command. Other connection errors remain unknown. The
+PTY host reads its own live catalog; an older pane server refuses this operation.
+This is a host observation, not a physical window/tab reading or an existence
+lock against a subsequent launch.
+
+`PaneServerHost.createSession({ ..., requireInputOwnership: true })` requires
+the connected server's ownership operation before creating a pane. An older
+server rejects with `input_ownership_unsupported` and starts no process; the
+same connection handles admission and creation. Omitting the option preserves
+ordinary creation. [Manual old/current server SDK readings](../../docs/evidence/launch-input-ownership-admission-2026-10-09.md)
+do not qualify Windows or native harness first-message delivery.
+
 The substrate was moved from a retired package without behavioral changes.
 Its existing home paths, environment variables, and tmux ownership markers stay
 compatible. Those files retain Apache-2.0 licensing; see `NOTICE-SUBSTRATE` and

package/index.d.ts

@@ -49,6 +49,8 @@ export type TmuxTerminalHostOptions = {
 export class TmuxTerminalHost {
   constructor(options?: TmuxTerminalHostOptions);
   listSessions(): Promise<TerminalSession[]>;
+  /** Complete context observation; failures reject rather than report absence. */
+  hasLiveContext(contextKey: string): Promise<boolean>;
   createSession(input: {
     command: TmuxCommand;
     contextKey?: string;
@@ -87,7 +89,10 @@ export class TmuxTerminalHost {
 export class PaneServerHost {
   constructor(options: { pipe: string; serverScript?: string });
   listSessions(): Promise<TerminalSession[]>;
-  createSession(input: { command: TmuxCommand; contextKey?: string; cwd?: string; env?: Record<string, string>; name?: string }): Promise<TerminalSession>;
+  /** Requires a compatible pane server; an unsupported operation rejects. */
+  hasLiveContext(contextKey: string): Promise<boolean>;
+  /** Require the running pane server's ownership door before creating a pane. */
+  createSession(input: { command: TmuxCommand; contextKey?: string; cwd?: string; env?: Record<string, string>; name?: string; requireInputOwnership?: boolean }): Promise<TerminalSession>;
   capture(sessionId: string, options?: { lines?: number; preserveEscapes?: boolean }): Promise<string>;
   sendInput(sessionId: string, data: string, options?: { deadlineMs?: number; submitMode?: 'retry' | 'single' | 'none'; inputOwner?: string }): Promise<TerminalInputDelivery>;
   /** Exclusive input ownership, retained by the pane host across client restart. */
@@ -112,6 +117,8 @@ export class PaneServerHost {
 export class PtyTerminalHost {
   constructor(options?: { attachmentTtlMs?: number });
   listSessions(): Promise<TerminalSession[]>;
+  /** Live context membership in this host's own pane catalog. */
+  hasLiveContext(contextKey: string): boolean;
   createSession(input: {
     command: TmuxCommand;
     contextKey?: string;

package/index.mjs

@@ -215,6 +215,12 @@ export class TmuxTerminalHost {
     return listing.promise;
   }
 
+  /** Complete context observation for callers deciding whether a pane has ended. */
+  hasLiveContext(contextKey) {
+    assertContextKey(contextKey);
+    return this.#tmux.hasSessionContextAsync(this.#contextOption, contextKey, this.#socket);
+  }
+
   async #listSessions() {
     this.#pruneAttachments();
     const names = this.#sessionNames();
@@ -637,6 +643,11 @@ export class PtyTerminalHost {
     return [...this.#sessions.values()].map((entry) => this.#describe(entry, table));
   }
 
+  hasLiveContext(contextKey) {
+    assertContextKey(contextKey);
+    return [...this.#sessions.values()].some((entry) => entry.contextKey === contextKey && entry.exit === null);
+  }
+
   async createSession(input) {
     const name = input.name ?? `supercode-${this.#randomToken().slice(0, 16)}`;
     if (!SESSION_NAME.test(name)) {
@@ -1105,7 +1116,8 @@ export class PaneServerHost {
   }
 
   listSessions() { return this.#request('listSessions', []); }
-  createSession(input) { return this.#request('createSession', [input]); }
+  hasLiveContext(contextKey) { assertContextKey(contextKey); return this.#request('hasLiveContext', [contextKey]); }
+  createSession(input) { return this.#request('createSession', [input], { requireInputOwnership: input.requireInputOwnership === true }); }
   capture(sessionId, options = {}) { return this.#request('capture', [sessionId, options]); }
   sendInput(sessionId, data, options = {}) { return this.#request('sendInput', [sessionId, data, options]); }
   acquireInput(sessionId, owner) { return this.#request('acquireInput', [sessionId, owner]); }
@@ -1163,12 +1175,27 @@ export class PaneServerHost {
     // A server that is leaving refuses a request unrun (`pane_server_restarting`): it is asked again of the next one.
     for (let attempt = 0; ; attempt += 1) {
       const connection = await this.#connect();
-      const id = this.#next++;
       try {
-        return await new Promise((resolve, reject) => {
-          this.#pending.set(id, { resolve, reject, connection });
-          connection.write(`${JSON.stringify({ id, op, args, ...extra })}\n`);
-        });
+        if (op === 'createSession' && extra.requireInputOwnership) {
+          // The installed client can be newer than the server that still holds
+          // this machine's panes. Check its actual ownership door before any
+          // process starts, on the same connection that will create the pane.
+          // null cannot identify a PtyTerminalHost session: session_not_found
+          // means the vendor's ownership operation ran without touching a pane.
+          try {
+            await this.#call(connection, 'ownsInput', [null, 'capability_check']);
+            throw new TerminalHostError('input_ownership_unconfirmed', 'The pane server did not confirm its input ownership door; no pane was created.');
+          } catch (error) {
+            if (error?.code === 'unsupported') {
+              throw new TerminalHostError('input_ownership_unsupported', 'The running pane server does not support input ownership required for this first message; no pane was created. Update the pane server through its owner before retrying.');
+            }
+            if (error?.code !== 'session_not_found') throw error;
+          }
+          if (connection.destroyed || this.#connection !== connection) {
+            throw new TerminalHostError('pane_server_unreachable', 'The pane server connection changed during input ownership admission; no pane was created.');
+          }
+        }
+        return await this.#call(connection, op, args, { ...extra, requireInputOwnership: undefined });
       } catch (error) {
         if (error?.code !== 'pane_server_restarting' || attempt >= 20) throw error;
         await sleep(250);
@@ -1176,6 +1203,15 @@ export class PaneServerHost {
     }
   }
 
+  #call(connection, op, args, extra = {}) {
+    const id = this.#next++;
+    return new Promise((resolve, reject) => {
+      this.#pending.set(id, { resolve, reject, connection });
+      try { connection.write(`${JSON.stringify({ id, op, args, ...extra })}\n`); }
+      catch (error) { this.#pending.delete(id); reject(error); }
+    });
+  }
+
   #connect() {
     if (this.#connection && !this.#connection.destroyed) return Promise.resolve(this.#connection);
     return (this.#connecting ??= this.#open().finally(() => { this.#connecting = null; }));

package/package.json

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

package/substrate/pane-server.mjs

@@ -32,7 +32,7 @@ function leave() {
   setTimeout(() => { server.close(); for (const connection of clients) connection.end(); setTimeout(done, 500); }, 3_000).unref?.();
 }
 
-const OPS = new Set(['listSessions', 'createSession', 'capture', 'sendInput', 'acquireInput', 'ownsInput', 'releaseInput', 'closeSession', 'renameWindow', 'issueAttachment', 'bindContext']);
+const OPS = new Set(['listSessions', 'hasLiveContext', 'createSession', 'capture', 'sendInput', 'acquireInput', 'ownsInput', 'releaseInput', 'closeSession', 'renameWindow', 'issueAttachment', 'bindContext']);
 
 function scheduleIdleExit() {
   clearTimeout(idleTimer);

package/substrate/tmux.d.ts

@@ -34,6 +34,8 @@ export declare function createSession({ command, cwd, env, name, owner, ownerOpt
     name: string;
     panes: number;
 }>;
+/** A complete context reading for absence decisions; ordinary option listings are best-effort. */
+export declare function hasSessionContextAsync(option: string, contextKey: string, socket?: string): Promise<boolean>;
 /** Read one namespaced user option for every live session in one tmux call. */
 export declare function sessionOptionValuesAsync(option: string, socket?: string): Promise<Map<string, string>>;
 /** Set one of tmux's own session options on one session. */

package/substrate/tmux.js

@@ -151,6 +151,39 @@ function assertUserOption(option) {
 // value (opaque, colons allowed) takes the whole remainder. Same rule as
 // `listPanesFormat`: printable separator, free-text field last.
 const sessionValueSeparator = ":";
+/** A complete context reading for absence decisions; ordinary option listings are best-effort. */
+export async function hasSessionContextAsync(option, contextKey, socket) {
+    assertTmux();
+    assertUserOption(option);
+    let output;
+    try {
+        output = await runAsync("tmux", tmuxArgs(socket, ["list-sessions", "-F", `#{session_id}${sessionValueSeparator}#{${option}}`]), { timeoutMs: 5_000 });
+    }
+    catch (error) {
+        // Only tmux's explicit no-server answer establishes emptiness. Connection,
+        // permission, missing-command and timeout errors remain unread observations.
+        if (error instanceof Error && /\nno server running on [^\r\n]+$/.test(error.message))
+            return false;
+        throw error;
+    }
+    // Successful list-sessions has at least one complete row. Include unbound
+    // sessions, reject malformed/duplicate identities, and inspect every row even
+    // after a match so partial identity output cannot establish absence.
+    if (!output.endsWith("\n"))
+        throw new Error("tmux context reading is incomplete");
+    const ids = new Set();
+    let present = false;
+    for (const line of output.slice(0, -1).split("\n")) {
+        const separator = line.indexOf(sessionValueSeparator);
+        const id = line.slice(0, separator);
+        if (separator < 1 || !/^\$\d+$/.test(id) || ids.has(id))
+            throw new Error("tmux context reading has an invalid session identity");
+        ids.add(id);
+        if (line.slice(separator + 1) === contextKey)
+            present = true;
+    }
+    return present;
+}
 /** Read one namespaced user option for every live session in one tmux call. */
 export async function sessionOptionValuesAsync(option, socket) {
     assertTmux();