@songsid/agend 2.1.5 → 2.1.6-beta.10

package/dist/web-auth.d.ts

@@ -1,6 +1,81 @@
 export declare const WEB_TOKEN_INVALID_MESSAGE = "Token expired or invalid \u2014 run /dashboard again";
+/** No credential at all. Distinct from "wrong credential" so a browser that
+ * silently drops cookies is diagnosable instead of looking like a bad token. */
+export declare const WEB_SESSION_REQUIRED_MESSAGE = "No session \u2014 open the dashboard link again (cookies must be enabled for this site)";
+export declare const WEB_CROSS_SITE_MESSAGE = "Cross-site request rejected";
+/** A URL token is redeemed for a session cookie on a GET; it is never a
+ * credential for a write, where it would also survive in history and logs. */
+export declare const WEB_URL_TOKEN_WRITE_MESSAGE = "URL tokens are only redeemed on GET \u2014 send X-Agend-Token for API writes";
+export declare const WEB_SESSION_COOKIE = "agend_session";
+/** 12h. The old model was "valid forever"; the panel is an escape hatch, so the
+ * cookie outlives a working day and nothing more. `web-token rotate` kills every
+ * issued cookie immediately regardless of this. */
+export declare const WEB_SESSION_MAX_AGE_SECONDS: number;
 /**
  * Load the fleet-wide web bearer token, creating it only when absent/invalid.
  * A fleet restart must not revoke every previously issued /dashboard URL.
  */
 export declare function loadOrCreateWebToken(dataDir: string): string;
+/**
+ * The token as it is on disk right now, without creating one.
+ *
+ * Deliberately unbuffered: `agend web-token rotate` writes the file from a
+ * separate process, and a cached copy would keep authorizing revoked sessions
+ * until the fleet restarted — which is the whole point of having rotation.
+ * mtime/size caching cannot be used either, since a rotation within the same
+ * millisecond produces a same-size file.
+ */
+export declare function readWebToken(dataDir: string): string | null;
+/**
+ * Replace the token with a fresh one. Every previously issued URL, header token
+ * and session cookie stops being accepted as soon as the next request is served.
+ */
+export declare function rotateWebToken(dataDir: string): string;
+/**
+ * The cookie carries a derivation of the token, never the token itself: a
+ * stolen cookie opens the panel but cannot be replayed as `?token=` /
+ * `X-Agend-Token` (which also authorize /view writes and the CLI). Rotating
+ * `web.token` changes the derivation, so every issued cookie dies with it.
+ */
+export declare function webSessionCookieValue(token: string): string;
+export declare function parseCookieHeader(header: string | undefined): Map<string, string>;
+/** Minimal request shape — everything the gate reads, and nothing more, so the
+ * decision can be unit-tested without a socket. */
+export interface WebGateRequest {
+    readonly method?: string | undefined;
+    readonly headers: NodeJS.Dict<string | string[]>;
+}
+export type WebGateDecision = {
+    readonly kind: "allow";
+} | {
+    readonly kind: "exchange";
+    readonly setCookie: string;
+    readonly location: string;
+} | {
+    readonly kind: "reject";
+    readonly status: 401 | 403;
+    readonly message: string;
+};
+/**
+ * True when the request either carries no Origin (a CLI, or a top-level GET
+ * navigation, neither of which a cross-site attacker controls) or carries one
+ * that matches the Host it was sent to.
+ *
+ * Only a *mismatch* rejects: requiring Origin would break every non-browser
+ * caller, which is the same `X-Agend-Token` path the CLI uses.
+ */
+export declare function isSameOriginRequest(req: WebGateRequest): boolean;
+export declare function buildSessionCookie(token: string, secure: boolean): string;
+export declare function hasValidSessionCookie(req: WebGateRequest, token: string): boolean;
+/**
+ * The single authorization decision for every gated web route.
+ *
+ * Accepts, in order: a session cookie, an `X-Agend-Token` header (CLI and
+ * scripts), and — only to be redeemed for a cookie on a GET — a `?token=` in
+ * the URL. After the redemption the token is gone from the address bar, from
+ * browser history, and from anything that logs request URLs.
+ */
+export declare function decideWebGate(req: WebGateRequest, url: URL, token: string | null): WebGateDecision;
+/** Defence in depth for handlers that run behind the gate: authorization only,
+ * no cookie issuing (the gate already did that). */
+export declare function isWebRequestAuthorized(req: WebGateRequest, url: URL, token: string | null): boolean;

package/dist/web-auth.js

@@ -1,8 +1,20 @@
 import { chmodSync, mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
-import { randomBytes } from "node:crypto";
+import { createHash, randomBytes, timingSafeEqual } from "node:crypto";
 import { join } from "node:path";
 export const WEB_TOKEN_INVALID_MESSAGE = "Token expired or invalid — run /dashboard again";
+/** No credential at all. Distinct from "wrong credential" so a browser that
+ * silently drops cookies is diagnosable instead of looking like a bad token. */
+export const WEB_SESSION_REQUIRED_MESSAGE = "No session — open the dashboard link again (cookies must be enabled for this site)";
+export const WEB_CROSS_SITE_MESSAGE = "Cross-site request rejected";
+/** A URL token is redeemed for a session cookie on a GET; it is never a
+ * credential for a write, where it would also survive in history and logs. */
+export const WEB_URL_TOKEN_WRITE_MESSAGE = "URL tokens are only redeemed on GET — send X-Agend-Token for API writes";
 const WEB_TOKEN_PATTERN = /^[0-9a-f]{48}$/i;
+export const WEB_SESSION_COOKIE = "agend_session";
+/** 12h. The old model was "valid forever"; the panel is an escape hatch, so the
+ * cookie outlives a working day and nothing more. `web-token rotate` kills every
+ * issued cookie immediately regardless of this. */
+export const WEB_SESSION_MAX_AGE_SECONDS = 12 * 60 * 60;
 function readValidToken(path) {
     try {
         const token = readFileSync(path, "utf8").trim();
@@ -28,13 +40,16 @@ function replaceTokenAtomically(path, token) {
         throw err;
     }
 }
+function tokenPath(dataDir) {
+    return join(dataDir, "web.token");
+}
 /**
  * Load the fleet-wide web bearer token, creating it only when absent/invalid.
  * A fleet restart must not revoke every previously issued /dashboard URL.
  */
 export function loadOrCreateWebToken(dataDir) {
     mkdirSync(dataDir, { recursive: true });
-    const path = join(dataDir, "web.token");
+    const path = tokenPath(dataDir);
     const existing = readValidToken(path);
     if (existing) {
         try {
@@ -51,4 +66,195 @@ export function loadOrCreateWebToken(dataDir) {
     catch { /* best effort */ }
     return token;
 }
+/**
+ * The token as it is on disk right now, without creating one.
+ *
+ * Deliberately unbuffered: `agend web-token rotate` writes the file from a
+ * separate process, and a cached copy would keep authorizing revoked sessions
+ * until the fleet restarted — which is the whole point of having rotation.
+ * mtime/size caching cannot be used either, since a rotation within the same
+ * millisecond produces a same-size file.
+ */
+export function readWebToken(dataDir) {
+    try {
+        return readValidToken(tokenPath(dataDir));
+    }
+    catch {
+        // This runs inside the request handler. A permissions or I/O error must
+        // close the panel, not throw out of the HTTP callback.
+        return null;
+    }
+}
+/**
+ * Replace the token with a fresh one. Every previously issued URL, header token
+ * and session cookie stops being accepted as soon as the next request is served.
+ */
+export function rotateWebToken(dataDir) {
+    mkdirSync(dataDir, { recursive: true });
+    const path = tokenPath(dataDir);
+    const token = randomBytes(24).toString("hex");
+    replaceTokenAtomically(path, token);
+    try {
+        chmodSync(path, 0o600);
+    }
+    catch { /* best effort */ }
+    return token;
+}
+/**
+ * The cookie carries a derivation of the token, never the token itself: a
+ * stolen cookie opens the panel but cannot be replayed as `?token=` /
+ * `X-Agend-Token` (which also authorize /view writes and the CLI). Rotating
+ * `web.token` changes the derivation, so every issued cookie dies with it.
+ */
+export function webSessionCookieValue(token) {
+    return createHash("sha256").update(`agend-web-session-v1:${token}`).digest("hex");
+}
+function constantTimeEquals(a, b) {
+    const left = Buffer.from(a, "utf8");
+    const right = Buffer.from(b, "utf8");
+    // timingSafeEqual throws on a length mismatch, which would itself leak length.
+    if (left.length !== right.length)
+        return false;
+    return timingSafeEqual(left, right);
+}
+export function parseCookieHeader(header) {
+    const jar = new Map();
+    if (!header)
+        return jar;
+    for (const part of header.split(";")) {
+        const eq = part.indexOf("=");
+        if (eq < 1)
+            continue;
+        const name = part.slice(0, eq).trim();
+        if (!name || jar.has(name))
+            continue;
+        jar.set(name, part.slice(eq + 1).trim());
+    }
+    return jar;
+}
+function headerValue(req, name) {
+    const raw = req.headers[name];
+    if (typeof raw === "string")
+        return raw;
+    if (Array.isArray(raw))
+        return raw[0] ?? null;
+    return null;
+}
+/**
+ * True when the request either carries no Origin (a CLI, or a top-level GET
+ * navigation, neither of which a cross-site attacker controls) or carries one
+ * that matches the Host it was sent to.
+ *
+ * Only a *mismatch* rejects: requiring Origin would break every non-browser
+ * caller, which is the same `X-Agend-Token` path the CLI uses.
+ */
+export function isSameOriginRequest(req) {
+    const origin = headerValue(req, "origin");
+    if (!origin)
+        return true;
+    const host = headerValue(req, "host");
+    if (!host)
+        return false;
+    try {
+        return new URL(origin).host === host;
+    }
+    catch {
+        // Anything unparseable is cross-site, including the opaque `null` origin
+        // that sandboxed frames and some redirect chains send.
+        return false;
+    }
+}
+/** Whether the browser reached us over TLS, which decides the cookie's Secure
+ * attribute. The health server is always plain HTTP, so the only signal is the
+ * tunnel/proxy in front of it. A forged header can only make us set Secure on a
+ * plain-HTTP response, which costs the forger their own cookie and nothing else. */
+function isSecureRequest(req) {
+    const proto = headerValue(req, "x-forwarded-proto");
+    if (!proto)
+        return false;
+    return proto.split(",")[0].trim().toLowerCase() === "https";
+}
+export function buildSessionCookie(token, secure) {
+    const attrs = [
+        `${WEB_SESSION_COOKIE}=${webSessionCookieValue(token)}`,
+        "Path=/",
+        "HttpOnly",
+        // Strict, not Lax: the panel can restart instances, so a cross-site
+        // navigation must not arrive already authenticated.
+        "SameSite=Strict",
+        `Max-Age=${WEB_SESSION_MAX_AGE_SECONDS}`,
+    ];
+    if (secure)
+        attrs.push("Secure");
+    return attrs.join("; ");
+}
+export function hasValidSessionCookie(req, token) {
+    const cookie = parseCookieHeader(headerValue(req, "cookie") ?? undefined).get(WEB_SESSION_COOKIE);
+    return !!cookie && constantTimeEquals(cookie, webSessionCookieValue(token));
+}
+function hasValidHeaderToken(req, token) {
+    const provided = headerValue(req, "x-agend-token");
+    return !!provided && constantTimeEquals(provided, token);
+}
+/** Same-origin relative target with the token stripped and every other query
+ * parameter kept. Relative on purpose: an absolute Location built from
+ * attacker-supplied Host would be an open redirect. */
+function locationWithoutToken(url) {
+    const stripped = new URL(url.href);
+    stripped.searchParams.delete("token");
+    return `${stripped.pathname}${stripped.search}`;
+}
+/**
+ * The single authorization decision for every gated web route.
+ *
+ * Accepts, in order: a session cookie, an `X-Agend-Token` header (CLI and
+ * scripts), and — only to be redeemed for a cookie on a GET — a `?token=` in
+ * the URL. After the redemption the token is gone from the address bar, from
+ * browser history, and from anything that logs request URLs.
+ */
+export function decideWebGate(req, url, token) {
+    // No token on disk means the panel is closed, not open to everyone. Without
+    // this, a null token compared against a missing credential authorizes.
+    if (!token)
+        return { kind: "reject", status: 401, message: WEB_TOKEN_INVALID_MESSAGE };
+    if (!isSameOriginRequest(req)) {
+        return { kind: "reject", status: 403, message: WEB_CROSS_SITE_MESSAGE };
+    }
+    if (hasValidSessionCookie(req, token))
+        return { kind: "allow" };
+    if (hasValidHeaderToken(req, token))
+        return { kind: "allow" };
+    const queryToken = url.searchParams.get("token");
+    if (queryToken && constantTimeEquals(queryToken, token)) {
+        const method = (req.method ?? "GET").toUpperCase();
+        if (method !== "GET" && method !== "HEAD") {
+            return { kind: "reject", status: 401, message: WEB_URL_TOKEN_WRITE_MESSAGE };
+        }
+        return {
+            kind: "exchange",
+            setCookie: buildSessionCookie(token, isSecureRequest(req)),
+            location: locationWithoutToken(url),
+        };
+    }
+    const presented = queryToken ?? headerValue(req, "x-agend-token") ?? headerValue(req, "cookie");
+    return {
+        kind: "reject",
+        status: 401,
+        message: presented ? WEB_TOKEN_INVALID_MESSAGE : WEB_SESSION_REQUIRED_MESSAGE,
+    };
+}
+/** Defence in depth for handlers that run behind the gate: authorization only,
+ * no cookie issuing (the gate already did that). */
+export function isWebRequestAuthorized(req, url, token) {
+    if (!token)
+        return false;
+    if (!isSameOriginRequest(req))
+        return false;
+    if (hasValidSessionCookie(req, token))
+        return true;
+    if (hasValidHeaderToken(req, token))
+        return true;
+    const queryToken = url.searchParams.get("token");
+    return !!queryToken && constantTimeEquals(queryToken, token);
+}
 //# sourceMappingURL=web-auth.js.map

package/dist/web-auth.js.map

@@ -1 +1 @@
-{"version":3,"file":"web-auth.js","sourceRoot":"","sources":["../src/web-auth.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,SAAS,EAAE,YAAY,EAAE,UAAU,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AACpG,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAEjC,MAAM,CAAC,MAAM,yBAAyB,GAAG,iDAAiD,CAAC;AAC3F,MAAM,iBAAiB,GAAG,iBAAiB,CAAC;AAE5C,SAAS,cAAc,CAAC,IAAY;IAClC,IAAI,CAAC;QACH,MAAM,KAAK,GAAG,YAAY,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,IAAI,EAAE,CAAC;QAChD,OAAO,iBAAiB,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC;IACtD,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,IAAK,GAA6B,CAAC,IAAI,KAAK,QAAQ;YAAE,OAAO,IAAI,CAAC;QAClE,MAAM,GAAG,CAAC;IACZ,CAAC;AACH,CAAC;AAED,SAAS,sBAAsB,CAAC,IAAY,EAAE,KAAa;IACzD,MAAM,IAAI,GAAG,GAAG,IAAI,QAAQ,OAAO,CAAC,GAAG,IAAI,WAAW,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;IAC5E,IAAI,CAAC;QACH,aAAa,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;QAC1E,UAAU,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;IACzB,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,IAAI,CAAC;YAAC,UAAU,CAAC,IAAI,CAAC,CAAC;QAAC,CAAC;QAAC,MAAM,CAAC,CAAC,6CAA6C,CAAC,CAAC;QACjF,MAAM,GAAG,CAAC;IACZ,CAAC;AACH,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,oBAAoB,CAAC,OAAe;IAClD,SAAS,CAAC,OAAO,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IACxC,MAAM,IAAI,GAAG,IAAI,CAAC,OAAO,EAAE,WAAW,CAAC,CAAC;IACxC,MAAM,QAAQ,GAAG,cAAc,CAAC,IAAI,CAAC,CAAC;IACtC,IAAI,QAAQ,EAAE,CAAC;QACb,IAAI,CAAC;YAAC,SAAS,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;QAAC,CAAC;QAAC,MAAM,CAAC,CAAC,iBAAiB,CAAC,CAAC;QAC3D,OAAO,QAAQ,CAAC;IAClB,CAAC;IAED,MAAM,KAAK,GAAG,WAAW,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;IAC9C,sBAAsB,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;IACpC,IAAI,CAAC;QAAC,SAAS,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;IAAC,CAAC;IAAC,MAAM,CAAC,CAAC,iBAAiB,CAAC,CAAC;IAC3D,OAAO,KAAK,CAAC;AACf,CAAC"}
+{"version":3,"file":"web-auth.js","sourceRoot":"","sources":["../src/web-auth.ts"],"names":[],"mappings":"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"}

package/dist/web-terminal.d.ts

@@ -116,6 +116,14 @@ export declare const MAX_TTL_MS: number;
 export declare const DEFAULT_COLS = 120;
 export declare const DEFAULT_ROWS = 36;
 export declare const MIN_COLS = 20, MAX_COLS = 250, MIN_ROWS = 5, MAX_ROWS = 100;
+/**
+ * tmux can report pane_dead before pane_dead_status has been populated when
+ * the host is under scheduler pressure.  Re-probe only the optional exit
+ * diagnostic; the session is already known to have ended.  The total budget
+ * is deliberately bounded so a wedged tmux cannot hold completion forever.
+ */
+export declare const EXIT_CODE_REPROBE_MAX_MS = 1000;
+export declare const EXIT_CODE_REPROBE_INTERVAL_MS = 250;
 /** Bytes of browser input allowed to wait for tmux before the session is ended as wedged (B4). */
 export declare const MAX_PENDING_INPUT_BYTES: number;
 /** Queued tmux operations allowed to wait (input batches + at most one resize); more means tmux is stuck. */
@@ -217,6 +225,15 @@ export declare class WebTerminalSession extends EventEmitter {
     private schedulePoll;
     /** Exposed for tests; the timer calls this every second. */
     poll(): Promise<void>;
+    /**
+     * Fill in tmux's optional pane-dead status after the pane is already known
+     * dead.  This is diagnostic enrichment only: timeout still completes with
+     * an undefined exit code and never retries the terminal/session itself.
+     */
+    private reProbeExitCode;
+    /** A single re-probe cannot consume more than its share of the total budget. */
+    private paneStatusWithin;
+    private delay;
     private observe;
     private finishFromExit;
     private finish;
@@ -239,6 +256,18 @@ export declare class TmuxTerminalBackend implements TerminalBackend {
      * command" scope would be violated against an unrelated process.
      */
     private readonly servers;
+    /**
+     * Where tmux actually put each socket, asked for while the server was alive.
+     *
+     * tmux does not unlink its socket when the server exits — verified on this
+     * tmux for a clean `kill-server` as well as for SIGKILL — so every session
+     * used to leave a file behind. Reconstructing the path instead would be a
+     * guess: the layout depends on TMUX_TMPDIR and the uid, and a wrong guess
+     * either deletes nothing or deletes something else. Recorded separately from
+     * `servers` because that map is only written when the PID fingerprint is
+     * strong, and a platform without one still deserves its socket cleaned up.
+     */
+    private readonly socketPaths;
     private readonly probe;
     constructor(tmuxBin?: string, opts?: {
         probeProcess?: (pid: number) => ProcessProbe;
@@ -301,7 +330,7 @@ export declare class TmuxTerminalBackend implements TerminalBackend {
      */
     kill(socket: string): Promise<void>;
     /** Test seam: adopt a server identity as if captured at start. */
-    rememberServerForTests(socket: string, pid: number, identity: string): void;
+    rememberServerForTests(socket: string, pid: number, identity: string, socketPath?: string): void;
 }
 export type ProcessProbe = {
     kind: "identified";

package/dist/web-terminal.js

@@ -29,7 +29,7 @@
 import { EventEmitter } from "node:events";
 import { execFile } from "node:child_process";
 import { randomBytes, timingSafeEqual } from "node:crypto";
-import { mkdtempSync, openSync, rmSync, readFileSync, constants as fsConstants } from "node:fs";
+import { mkdtempSync, openSync, rmSync, readFileSync, unlinkSync, constants as fsConstants } from "node:fs";
 import { Socket as NetSocket } from "node:net";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
@@ -43,6 +43,14 @@ export const MIN_COLS = 20, MAX_COLS = 250, MIN_ROWS = 5, MAX_ROWS = 100;
 const REPLAY_BUFFER_LIMIT = 256 * 1024;
 const POLL_INTERVAL_MS = 1_000;
 const SUCCESS_EXIT_GRACE_MS = 15_000;
+/**
+ * tmux can report pane_dead before pane_dead_status has been populated when
+ * the host is under scheduler pressure.  Re-probe only the optional exit
+ * diagnostic; the session is already known to have ended.  The total budget
+ * is deliberately bounded so a wedged tmux cannot hold completion forever.
+ */
+export const EXIT_CODE_REPROBE_MAX_MS = 1_000;
+export const EXIT_CODE_REPROBE_INTERVAL_MS = 250;
 /** Bytes of browser input allowed to wait for tmux before the session is ended as wedged (B4). */
 export const MAX_PENDING_INPUT_BYTES = 64 * 1024;
 /** Queued tmux operations allowed to wait (input batches + at most one resize); more means tmux is stuck. */
@@ -389,7 +397,8 @@ export class WebTerminalSession extends EventEmitter {
                 this.probeFailures = 0;
             }
             if (status && !status.alive) {
-                await this.finishFromExit(status.exitCode, pane);
+                const exitCode = status.exitCode ?? await this.reProbeExitCode();
+                await this.finishFromExit(exitCode, pane);
                 return;
             }
             if (this.successSeenAt !== null && this.now() - this.successSeenAt > SUCCESS_EXIT_GRACE_MS) {
@@ -404,6 +413,50 @@ export class WebTerminalSession extends EventEmitter {
         }
         this.schedulePoll();
     }
+    /**
+     * Fill in tmux's optional pane-dead status after the pane is already known
+     * dead.  This is diagnostic enrichment only: timeout still completes with
+     * an undefined exit code and never retries the terminal/session itself.
+     */
+    async reProbeExitCode() {
+        const deadline = Date.now() + EXIT_CODE_REPROBE_MAX_MS;
+        while (this.state === "running") {
+            const remaining = deadline - Date.now();
+            if (remaining <= 0)
+                return undefined;
+            const status = await this.paneStatusWithin(Math.min(EXIT_CODE_REPROBE_INTERVAL_MS, remaining));
+            if (status && !status.alive && status.exitCode !== undefined)
+                return status.exitCode;
+            if (this.state !== "running")
+                return undefined;
+            const afterProbe = deadline - Date.now();
+            if (afterProbe <= 0)
+                return undefined;
+            await this.delay(Math.min(EXIT_CODE_REPROBE_INTERVAL_MS, afterProbe));
+        }
+        return undefined;
+    }
+    /** A single re-probe cannot consume more than its share of the total budget. */
+    async paneStatusWithin(timeoutMs) {
+        let timer;
+        const timeout = new Promise(resolve => {
+            timer = setTimeout(() => resolve(null), timeoutMs);
+            timer.unref?.();
+        });
+        try {
+            return await Promise.race([this.backend.paneStatus(this.socketName).catch(() => null), timeout]);
+        }
+        finally {
+            if (timer)
+                clearTimeout(timer);
+        }
+    }
+    delay(ms) {
+        return new Promise(resolve => {
+            const timer = setTimeout(resolve, ms);
+            timer.unref?.();
+        });
+    }
     observe(pane) {
         const obs = this.spec.observe;
         if (!obs || !pane)
@@ -525,6 +578,18 @@ export class TmuxTerminalBackend {
      * command" scope would be violated against an unrelated process.
      */
     servers = new Map();
+    /**
+     * Where tmux actually put each socket, asked for while the server was alive.
+     *
+     * tmux does not unlink its socket when the server exits — verified on this
+     * tmux for a clean `kill-server` as well as for SIGKILL — so every session
+     * used to leave a file behind. Reconstructing the path instead would be a
+     * guess: the layout depends on TMUX_TMPDIR and the uid, and a wrong guess
+     * either deletes nothing or deletes something else. Recorded separately from
+     * `servers` because that map is only written when the PID fingerprint is
+     * strong, and a platform without one still deserves its socket cleaned up.
+     */
+    socketPaths = new Map();
     probe;
     constructor(tmuxBin = "tmux", opts = {}) {
         this.tmuxBin = tmuxBin;
@@ -585,6 +650,11 @@ export class TmuxTerminalBackend {
                 if (probe.kind === "identified")
                     this.servers.set(socket, { pid, identity: probe.identity });
             }
+            // Ask while the server is up; after it dies there is nobody to ask.
+            const socketPath = (await this.tmux(socket, "display-message", ["-p", "#{socket_path}"])
+                .catch(() => "")).trim();
+            if (socketPath)
+                this.socketPaths.set(socket, socketPath);
             await this.tmux(socket, "set-option", ["-g", "window-size", "manual"]);
             if (signal?.aborted)
                 throw aborted();
@@ -786,11 +856,24 @@ export class TmuxTerminalBackend {
             // Keep the identity so a later retry can still reach the process.
             throw new Error(`tmux server on socket ${socket} could not be confirmed dead (${state})`);
         }
+        // Only now: the socket is how every command reaches the server, including
+        // the kill above, so removing it earlier would cut off our own retries and
+        // leave a live server nothing can talk to.
+        const socketPath = this.socketPaths.get(socket);
+        this.socketPaths.delete(socket);
+        if (socketPath) {
+            try {
+                unlinkSync(socketPath);
+            }
+            catch { /* already gone, or never ours to remove */ }
+        }
         this.servers.delete(socket);
     }
     /** Test seam: adopt a server identity as if captured at start. */
-    rememberServerForTests(socket, pid, identity) {
+    rememberServerForTests(socket, pid, identity, socketPath) {
         this.servers.set(socket, { pid, identity });
+        if (socketPath)
+            this.socketPaths.set(socket, socketPath);
     }
 }
 /**