commandmate 0.43.0 → 0.44.1

package/dist/cli/utils/process-inspect.js

@@ -0,0 +1,214 @@
+"use strict";
+/**
+ * Best-effort process inspection for stop/start (Issue #3087)
+ *
+ * - Zombies: `kill(pid, 0)` succeeds for a zombie, so without an init process
+ *   (a container whose PID 1 never reaps) a stopped server's group looked alive
+ *   forever. On Linux, /proc tells a zombie apart; elsewhere nothing is known
+ *   and callers keep their signal-based answer.
+ * - Listeners: when something answers on the configured port but is not the
+ *   server the PID file describes, the user is told which PID holds it.
+ *
+ * Every function here is read-only and never throws.
+ *
+ * @module process-inspect
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseProcStat = parseProcStat;
+exports.isZombieProcess = isZombieProcess;
+exports.listProcessGroupStates = listProcessGroupStates;
+exports.isExitedState = isExitedState;
+exports.findListeningPids = findListeningPids;
+exports.describeProcess = describeProcess;
+exports.describeListeners = describeListeners;
+const child_process_1 = require("child_process");
+const fs_1 = require("fs");
+/** Process states that are no longer running code: zombie and dead. */
+const EXITED_STATES = new Set(['Z', 'X', 'x']);
+/**
+ * Parse `/proc/<pid>/stat`. The command name is parenthesised and may itself
+ * contain spaces or parentheses, so fields are read after the LAST `)`.
+ */
+function parseProcStat(content) {
+    const end = content.lastIndexOf(')');
+    if (end === -1)
+        return null;
+    const fields = content.slice(end + 1).trim().split(/\s+/);
+    // fields[0] = state, fields[1] = ppid, fields[2] = pgrp
+    const pgrp = parseInt(fields[2] ?? '', 10);
+    if (!fields[0] || Number.isNaN(pgrp))
+        return null;
+    return { state: fields[0], pgrp };
+}
+function readProcStat(pid) {
+    try {
+        return parseProcStat((0, fs_1.readFileSync)(`/proc/${pid}/stat`, 'utf-8'));
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * @returns true when /proc reports the process as a zombie (or dead); false when it is
+ *   running, absent, or the platform has no /proc
+ */
+function isZombieProcess(pid) {
+    if (process.platform !== 'linux')
+        return false;
+    const stat = readProcStat(pid);
+    return stat !== null && EXITED_STATES.has(stat.state);
+}
+/**
+ * States of every process whose process group is `pgid`.
+ *
+ * @returns the state letters (possibly empty), or null when /proc cannot be read
+ *   (non-Linux), in which case nothing is known
+ */
+function listProcessGroupStates(pgid) {
+    if (process.platform !== 'linux')
+        return null;
+    let entries;
+    try {
+        entries = (0, fs_1.readdirSync)('/proc');
+    }
+    catch {
+        return null;
+    }
+    if (!Array.isArray(entries))
+        return null;
+    const states = [];
+    for (const entry of entries) {
+        if (!/^\d+$/.test(entry))
+            continue;
+        const stat = readProcStat(parseInt(entry, 10));
+        if (stat !== null && stat.pgrp === pgid) {
+            states.push(stat.state);
+        }
+    }
+    return states;
+}
+/** @returns true when a /proc state letter means the process no longer runs */
+function isExitedState(state) {
+    return EXITED_STATES.has(state);
+}
+/** Socket inodes listening on `port` per /proc/net/tcp{,6} (state 0A = LISTEN). */
+function listeningInodes(port) {
+    const inodes = new Set();
+    const hexPort = port.toString(16).toUpperCase().padStart(4, '0');
+    for (const table of ['/proc/net/tcp', '/proc/net/tcp6']) {
+        let content;
+        try {
+            content = (0, fs_1.readFileSync)(table, 'utf-8');
+        }
+        catch {
+            continue;
+        }
+        for (const line of String(content).split('\n').slice(1)) {
+            const fields = line.trim().split(/\s+/);
+            // sl local_address rem_address st tx:rx tr:when retrnsmt uid timeout inode
+            if (fields.length < 10)
+                continue;
+            const localPort = fields[1].split(':')[1];
+            if (localPort === hexPort && fields[3] === '0A') {
+                inodes.add(fields[9]);
+            }
+        }
+    }
+    return inodes;
+}
+function findListeningPidsLinux(port) {
+    const inodes = listeningInodes(port);
+    if (inodes.size === 0)
+        return [];
+    const pids = [];
+    let entries;
+    try {
+        entries = (0, fs_1.readdirSync)('/proc');
+    }
+    catch {
+        return [];
+    }
+    for (const entry of entries) {
+        if (!/^\d+$/.test(entry))
+            continue;
+        let fds;
+        try {
+            fds = (0, fs_1.readdirSync)(`/proc/${entry}/fd`);
+        }
+        catch {
+            continue; // not ours to read, or gone
+        }
+        for (const fd of fds) {
+            let target;
+            try {
+                target = (0, fs_1.readlinkSync)(`/proc/${entry}/fd/${fd}`);
+            }
+            catch {
+                continue;
+            }
+            const match = /^socket:\[(\d+)\]$/.exec(target);
+            if (match && inodes.has(match[1])) {
+                pids.push(parseInt(entry, 10));
+                break;
+            }
+        }
+    }
+    return pids;
+}
+function findListeningPidsLsof(port) {
+    try {
+        const out = (0, child_process_1.execFileSync)('lsof', ['-nP', `-iTCP:${port}`, '-sTCP:LISTEN', '-t'], {
+            encoding: 'utf-8',
+            timeout: 3000,
+            stdio: ['ignore', 'pipe', 'ignore'],
+        });
+        return [...new Set(String(out).split('\n').map((l) => parseInt(l, 10)).filter((n) => !Number.isNaN(n)))];
+    }
+    catch {
+        return []; // lsof exits 1 when nothing matches, or is not installed
+    }
+}
+/**
+ * PIDs listening on a TCP port: /proc on Linux, `lsof` elsewhere.
+ *
+ * @returns the PIDs found; empty when none are visible (another user's process, or no tool)
+ */
+function findListeningPids(port) {
+    return process.platform === 'linux' ? findListeningPidsLinux(port) : findListeningPidsLsof(port);
+}
+/**
+ * One-line description of a process for an error message.
+ *
+ * @returns the command line, or null when it cannot be read
+ */
+function describeProcess(pid) {
+    try {
+        if (process.platform === 'linux') {
+            const cmdline = (0, fs_1.readFileSync)(`/proc/${pid}/cmdline`, 'utf-8').split('\0').filter(Boolean).join(' ');
+            return cmdline || null;
+        }
+        const out = (0, child_process_1.execFileSync)('ps', ['-o', 'command=', '-p', String(pid)], {
+            encoding: 'utf-8',
+            timeout: 3000,
+            stdio: ['ignore', 'pipe', 'ignore'],
+        }).trim();
+        return out || null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * "PID 875 (node dist/server/server.js), PID 876" — or null when no PID is visible.
+ */
+function describeListeners(port) {
+    const pids = findListeningPids(port);
+    if (pids.length === 0)
+        return null;
+    return pids
+        .map((pid) => {
+        const command = describeProcess(pid);
+        return command ? `PID ${pid} (${command.slice(0, 120)})` : `PID ${pid}`;
+    })
+        .join(', ');
+}

package/dist/cli/utils/remote-pairing.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Re-issue the pairing code of a live `commandmate remote` session (Issue #3127).
+ *
+ * `remote up` shows the pairing link once, as a QR code, and keeps only the
+ * code's HASH on disk (`pairing-code.ts`). When that QR is lost — an agent's
+ * chat pane folds the output and cuts the QR off — the link cannot be shown
+ * again, because the plaintext code no longer exists anywhere. Before this
+ * module the only way back was `remote stop` + `remote`, which tears the
+ * Provider down and publishes a NEW URL.
+ *
+ * What this does instead: mint a fresh code and swap its hash into the
+ * existing handoff file, keeping the session token and the expiry. Nothing
+ * else changes — the server, the Provider and the public URL are untouched,
+ * and no new way in is created. The previous code stops working, because its
+ * hash is gone.
+ *
+ * ## Why the file is renamed away first
+ *
+ * The consumed flag is the ABSENCE of the handoff file: the server unlinks it
+ * on a successful pairing. A plain read-modify-write races with that — a
+ * pairing landing between our read and our write would see the file deleted,
+ * then recreated by us, and the already-paired session token would become
+ * pairable a second time. Renaming the file to a private name first is an
+ * atomic claim: if the rename fails with ENOENT the code was spent and we stop;
+ * if it succeeds the server can no longer consume it (it sees "absent", which
+ * answers 410 for the old code — the code we are about to replace anyway).
+ *
+ * ## Fail-closed
+ *
+ * Anything unreadable, malformed or already expired yields no code. A failure
+ * after the claim deletes the claimed file rather than guessing, so the worst
+ * case is "pairing is gone, run `remote stop` and `remote` again", never "a
+ * spent token is pairable again".
+ */
+/** Why no new code was issued. */
+export type PairingReissueFailure = 
+/** The handoff file is absent: the code was used (or never written). */
+'consumed'
+/** The code's window has closed. */
+ | 'expired'
+/** The file exists but could not be claimed or parsed. */
+ | 'unreadable'
+/** Claimed, but the new code could not be written. The pairing is gone. */
+ | 'write-failed';
+export type PairingReissueResult = {
+    ok: true;
+    /** Plaintext pairing code. Never persisted; the caller shows it and drops it. */
+    code: string;
+    /** Epoch ms, unchanged from the original code. */
+    expiresAt: number;
+} | {
+    ok: false;
+    reason: PairingReissueFailure;
+};
+/**
+ * @param filePath - Handoff file
+ * @returns The private name the file is claimed under while it is rewritten
+ */
+export declare function getReissueClaimPath(filePath: string): string;
+/**
+ * Replace the pairing code of an unused handoff file with a fresh one.
+ *
+ * @param filePath - Absolute path of the handoff file (`state.pairing.filePath`)
+ * @param now - Epoch ms, injectable for tests
+ * @returns The new code and its (unchanged) expiry, or why there is none
+ */
+export declare function reissuePairingCode(filePath: string, now?: number): PairingReissueResult;
+//# sourceMappingURL=remote-pairing.d.ts.map

package/dist/cli/utils/remote-pairing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"remote-pairing.d.ts","sourceRoot":"","sources":["../../../src/cli/utils/remote-pairing.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAYH,kCAAkC;AAClC,MAAM,MAAM,qBAAqB;AAC/B,wEAAwE;AACtE,UAAU;AACZ,oCAAoC;GAClC,SAAS;AACX,0DAA0D;GACxD,YAAY;AACd,2EAA2E;GACzE,cAAc,CAAC;AAEnB,MAAM,MAAM,oBAAoB,GAC5B;IACE,EAAE,EAAE,IAAI,CAAC;IACT,iFAAiF;IACjF,IAAI,EAAE,MAAM,CAAC;IACb,kDAAkD;IAClD,SAAS,EAAE,MAAM,CAAC;CACnB,GACD;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,qBAAqB,CAAA;CAAE,CAAC;AAEjD;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAE5D;AA+BD;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,GAAE,MAAmB,GAAG,oBAAoB,CAmCnG"}

package/dist/cli/utils/remote-pairing.js

@@ -0,0 +1,117 @@
+"use strict";
+/**
+ * Re-issue the pairing code of a live `commandmate remote` session (Issue #3127).
+ *
+ * `remote up` shows the pairing link once, as a QR code, and keeps only the
+ * code's HASH on disk (`pairing-code.ts`). When that QR is lost — an agent's
+ * chat pane folds the output and cuts the QR off — the link cannot be shown
+ * again, because the plaintext code no longer exists anywhere. Before this
+ * module the only way back was `remote stop` + `remote`, which tears the
+ * Provider down and publishes a NEW URL.
+ *
+ * What this does instead: mint a fresh code and swap its hash into the
+ * existing handoff file, keeping the session token and the expiry. Nothing
+ * else changes — the server, the Provider and the public URL are untouched,
+ * and no new way in is created. The previous code stops working, because its
+ * hash is gone.
+ *
+ * ## Why the file is renamed away first
+ *
+ * The consumed flag is the ABSENCE of the handoff file: the server unlinks it
+ * on a successful pairing. A plain read-modify-write races with that — a
+ * pairing landing between our read and our write would see the file deleted,
+ * then recreated by us, and the already-paired session token would become
+ * pairable a second time. Renaming the file to a private name first is an
+ * atomic claim: if the rename fails with ENOENT the code was spent and we stop;
+ * if it succeeds the server can no longer consume it (it sees "absent", which
+ * answers 410 for the old code — the code we are about to replace anyway).
+ *
+ * ## Fail-closed
+ *
+ * Anything unreadable, malformed or already expired yields no code. A failure
+ * after the claim deletes the claimed file rather than guessing, so the worst
+ * case is "pairing is gone, run `remote stop` and `remote` again", never "a
+ * spent token is pairable again".
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getReissueClaimPath = getReissueClaimPath;
+exports.reissuePairingCode = reissuePairingCode;
+const fs_1 = require("fs");
+const auth_1 = require("../../lib/security/auth");
+const pairing_code_1 = require("../../lib/security/pairing-code");
+/**
+ * @param filePath - Handoff file
+ * @returns The private name the file is claimed under while it is rewritten
+ */
+function getReissueClaimPath(filePath) {
+    return `${filePath}.reissue-${process.pid}`;
+}
+/**
+ * Best-effort unlink. A missing file is the state we wanted.
+ *
+ * @param filePath - File to remove
+ */
+function removeQuietly(filePath) {
+    try {
+        (0, fs_1.unlinkSync)(filePath);
+    }
+    catch {
+        // Already gone.
+    }
+}
+/**
+ * Put a claimed file back where the server reads it. When that fails the
+ * claimed copy is deleted: an orphan holding the plaintext token is worse than
+ * a pairing that has to be started again.
+ *
+ * @param claimPath - Where the file was claimed to
+ * @param filePath - Where the server expects it
+ */
+function restoreClaim(claimPath, filePath) {
+    try {
+        (0, fs_1.renameSync)(claimPath, filePath);
+    }
+    catch {
+        removeQuietly(claimPath);
+    }
+}
+/**
+ * Replace the pairing code of an unused handoff file with a fresh one.
+ *
+ * @param filePath - Absolute path of the handoff file (`state.pairing.filePath`)
+ * @param now - Epoch ms, injectable for tests
+ * @returns The new code and its (unchanged) expiry, or why there is none
+ */
+function reissuePairingCode(filePath, now = Date.now()) {
+    const claimPath = getReissueClaimPath(filePath);
+    try {
+        (0, fs_1.renameSync)(filePath, claimPath);
+    }
+    catch (error) {
+        const code = error?.code;
+        return { ok: false, reason: code === 'ENOENT' ? 'consumed' : 'unreadable' };
+    }
+    const handoff = (0, pairing_code_1.readPairingHandoff)(claimPath);
+    if (handoff === null) {
+        restoreClaim(claimPath, filePath);
+        return { ok: false, reason: 'unreadable' };
+    }
+    if ((0, pairing_code_1.isPairingExpired)(handoff, now)) {
+        restoreClaim(claimPath, filePath);
+        return { ok: false, reason: 'expired' };
+    }
+    const code = (0, pairing_code_1.generatePairingCode)();
+    try {
+        (0, pairing_code_1.writePairingHandoff)(claimPath, {
+            pairingHash: (0, auth_1.hashToken)(code),
+            expiresAt: handoff.expiresAt,
+            sessionToken: handoff.sessionToken,
+        });
+        (0, fs_1.renameSync)(claimPath, filePath);
+    }
+    catch {
+        removeQuietly(claimPath);
+        return { ok: false, reason: 'write-failed' };
+    }
+    return { ok: true, code, expiresAt: handoff.expiresAt };
+}

package/dist/cli/utils/server-identity.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Launched-server identity check
+ * Issue #3087: `remote` published whatever answered on the port
+ *
+ * A TCP connect only proves that SOMETHING listens. In #3087 an orphaned server from an
+ * earlier `start --daemon` (no authentication) kept the port, the server `remote` launched
+ * died on EADDRINUSE, and `remote` put the orphan behind a public tunnel.
+ *
+ * Before anything is published, this asks the endpoint two questions over plain HTTP(S):
+ *
+ *  1. A request carrying a token nobody holds must be refused with 401. Anything else means
+ *     authentication is off (or the answer is not CommandMate's middleware), so the server
+ *     would be reachable without pairing.
+ *  2. A request carrying the session token `remote` minted moments ago must succeed. Only
+ *     the server launched with that token's hash can accept it, so this proves the listener
+ *     is the one this invocation started — no new API route or nonce is needed.
+ *
+ * Question 1 is asked first so the session token is never sent to a server already shown to
+ * be the wrong one. Every outcome that is not a clear "yes" to both is a refusal (fail-closed);
+ * only connection errors and 5xx (a server still warming up) are retried until the deadline.
+ *
+ * @module server-identity
+ */
+/** Path probed: authenticated like every API route, and it reads nothing (Issue #1925). */
+export declare const IDENTITY_PROBE_PATH = "/api/capabilities";
+export declare const DEFAULT_IDENTITY_TIMEOUT_MS = 30000;
+export declare const DEFAULT_IDENTITY_INTERVAL_MS = 300;
+export interface VerifyLaunchedServerOptions {
+    protocol: 'http' | 'https';
+    host: string;
+    port: number;
+    /** Plaintext session token whose hash the launched server was given */
+    sessionToken: string;
+    timeoutMs?: number;
+    intervalMs?: number;
+}
+export type LaunchedServerVerdict = {
+    ok: true;
+} | {
+    ok: false;
+    reason: string;
+};
+/**
+ * Verify that the endpoint is the authenticated server this invocation launched.
+ *
+ * @returns `{ ok: true }` only when an unknown token is refused with 401 AND the session
+ *   token is accepted; otherwise `{ ok: false, reason }`. Never throws.
+ */
+export declare function verifyLaunchedServer(options: VerifyLaunchedServerOptions): Promise<LaunchedServerVerdict>;
+//# sourceMappingURL=server-identity.d.ts.map

package/dist/cli/utils/server-identity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server-identity.d.ts","sourceRoot":"","sources":["../../../src/cli/utils/server-identity.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAMH,2FAA2F;AAC3F,eAAO,MAAM,mBAAmB,sBAAsB,CAAC;AAEvD,eAAO,MAAM,2BAA2B,QAAQ,CAAC;AACjD,eAAO,MAAM,4BAA4B,MAAM,CAAC;AAGhD,MAAM,WAAW,2BAA2B;IAC1C,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,uEAAuE;IACvE,YAAY,EAAE,MAAM,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,MAAM,qBAAqB,GAAG;IAAE,EAAE,EAAE,IAAI,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAqDjF;;;;;GAKG;AACH,wBAAsB,oBAAoB,CACxC,OAAO,EAAE,2BAA2B,GACnC,OAAO,CAAC,qBAAqB,CAAC,CA0ChC"}

package/dist/cli/utils/server-identity.js

@@ -0,0 +1,118 @@
+"use strict";
+/**
+ * Launched-server identity check
+ * Issue #3087: `remote` published whatever answered on the port
+ *
+ * A TCP connect only proves that SOMETHING listens. In #3087 an orphaned server from an
+ * earlier `start --daemon` (no authentication) kept the port, the server `remote` launched
+ * died on EADDRINUSE, and `remote` put the orphan behind a public tunnel.
+ *
+ * Before anything is published, this asks the endpoint two questions over plain HTTP(S):
+ *
+ *  1. A request carrying a token nobody holds must be refused with 401. Anything else means
+ *     authentication is off (or the answer is not CommandMate's middleware), so the server
+ *     would be reachable without pairing.
+ *  2. A request carrying the session token `remote` minted moments ago must succeed. Only
+ *     the server launched with that token's hash can accept it, so this proves the listener
+ *     is the one this invocation started — no new API route or nonce is needed.
+ *
+ * Question 1 is asked first so the session token is never sent to a server already shown to
+ * be the wrong one. Every outcome that is not a clear "yes" to both is a refusal (fail-closed);
+ * only connection errors and 5xx (a server still warming up) are retried until the deadline.
+ *
+ * @module server-identity
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_IDENTITY_INTERVAL_MS = exports.DEFAULT_IDENTITY_TIMEOUT_MS = exports.IDENTITY_PROBE_PATH = void 0;
+exports.verifyLaunchedServer = verifyLaunchedServer;
+const http_1 = require("http");
+const https_1 = require("https");
+const crypto_1 = require("crypto");
+/** Path probed: authenticated like every API route, and it reads nothing (Issue #1925). */
+exports.IDENTITY_PROBE_PATH = '/api/capabilities';
+exports.DEFAULT_IDENTITY_TIMEOUT_MS = 30000;
+exports.DEFAULT_IDENTITY_INTERVAL_MS = 300;
+const REQUEST_TIMEOUT_MS = 10000;
+function probe(options, bearer, timeoutMs) {
+    return new Promise((resolve) => {
+        const send = options.protocol === 'https' ? https_1.request : http_1.request;
+        let settled = false;
+        const finish = (status) => {
+            if (settled)
+                return;
+            settled = true;
+            resolve(status);
+        };
+        try {
+            const req = send({
+                host: options.host,
+                port: options.port,
+                path: exports.IDENTITY_PROBE_PATH,
+                method: 'GET',
+                headers: { Authorization: `Bearer ${bearer}` },
+                timeout: timeoutMs,
+                // Loopback only, and identity is proven by the token, not the certificate: a
+                // self-signed CM_HTTPS_CERT must not make the check impossible.
+                rejectUnauthorized: false,
+            }, (res) => {
+                res.resume();
+                finish(res.statusCode ?? null);
+            });
+            req.on('timeout', () => {
+                req.destroy();
+                finish(null);
+            });
+            req.on('error', () => finish(null));
+            req.end();
+        }
+        catch {
+            finish(null);
+        }
+    });
+}
+function isTransient(status) {
+    return status === null || status >= 500;
+}
+/**
+ * Verify that the endpoint is the authenticated server this invocation launched.
+ *
+ * @returns `{ ok: true }` only when an unknown token is refused with 401 AND the session
+ *   token is accepted; otherwise `{ ok: false, reason }`. Never throws.
+ */
+async function verifyLaunchedServer(options) {
+    const timeoutMs = options.timeoutMs ?? exports.DEFAULT_IDENTITY_TIMEOUT_MS;
+    const intervalMs = options.intervalMs ?? exports.DEFAULT_IDENTITY_INTERVAL_MS;
+    const deadline = Date.now() + timeoutMs;
+    // A token that cannot be anyone's: fresh random bytes, never hashed or stored anywhere.
+    const decoy = (0, crypto_1.randomBytes)(32).toString('hex');
+    const where = `${options.host}:${options.port}`;
+    const ask = async (bearer) => {
+        for (;;) {
+            const remaining = deadline - Date.now();
+            const status = await probe(options, bearer, Math.max(Math.min(REQUEST_TIMEOUT_MS, remaining), 1));
+            if (!isTransient(status) || deadline - Date.now() <= 0) {
+                return status;
+            }
+            await new Promise((resolve) => setTimeout(resolve, Math.min(intervalMs, Math.max(deadline - Date.now(), 1))));
+        }
+    };
+    const unauthenticated = await ask(decoy);
+    if (unauthenticated !== 401) {
+        return {
+            ok: false,
+            reason: unauthenticated === null
+                ? `nothing answered on ${where}`
+                : `the server on ${where} did not require authentication (HTTP ${unauthenticated} for an unknown token, expected 401)`,
+        };
+    }
+    const authenticated = await ask(options.sessionToken);
+    if (authenticated === null || authenticated < 200 || authenticated >= 300) {
+        return {
+            ok: false,
+            reason: authenticated === null
+                ? `nothing answered on ${where}`
+                : `the server on ${where} is not the one this command started (HTTP ${authenticated} for this session's token)`,
+        };
+    }
+    return { ok: true };
+}

package/dist/cli/utils/server-ready.d.ts

@@ -25,4 +25,17 @@ export declare const DEFAULT_INTERVAL_MS = 300;
  * @returns true if the server accepted a connection, false on timeout
  */
 export declare function waitForServer(host: string, port: number, options?: WaitForServerOptions): Promise<boolean>;
+/**
+ * Whether something is accepting TCP connections on host:port right now.
+ *
+ * Issue #3087: a single attempt, used where "the port is free" has to be proven
+ * (before `start` spawns a server, after `stop` claims to have stopped one)
+ * rather than waited for.
+ *
+ * @param host - Host to connect to
+ * @param port - Port to connect to
+ * @param timeoutMs - How long one connection attempt may take
+ * @returns true if a connection was accepted
+ */
+export declare function isPortInUse(host: string, port: number, timeoutMs?: number): Promise<boolean>;
 //# sourceMappingURL=server-ready.d.ts.map

package/dist/cli/utils/server-ready.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"server-ready.d.ts","sourceRoot":"","sources":["../../../src/cli/utils/server-ready.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAIH,MAAM,WAAW,oBAAoB;IACnC,+CAA+C;IAC/C,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,6CAA6C;IAC7C,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,eAAO,MAAM,kBAAkB,QAAQ,CAAC;AACxC,eAAO,MAAM,mBAAmB,MAAM,CAAC;AAEvC;;;;;;;GAOG;AACH,wBAAsB,aAAa,CACjC,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,EACZ,OAAO,GAAE,oBAAyB,GACjC,OAAO,CAAC,OAAO,CAAC,CAmBlB"}
+{"version":3,"file":"server-ready.d.ts","sourceRoot":"","sources":["../../../src/cli/utils/server-ready.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAIH,MAAM,WAAW,oBAAoB;IACnC,+CAA+C;IAC/C,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,6CAA6C;IAC7C,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,eAAO,MAAM,kBAAkB,QAAQ,CAAC;AACxC,eAAO,MAAM,mBAAmB,MAAM,CAAC;AAEvC;;;;;;;GAOG;AACH,wBAAsB,aAAa,CACjC,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,EACZ,OAAO,GAAE,oBAAyB,GACjC,OAAO,CAAC,OAAO,CAAC,CAmBlB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,SAAS,GAAE,MAAa,GAAG,OAAO,CAAC,OAAO,CAAC,CAElG"}

package/dist/cli/utils/server-ready.js

@@ -12,6 +12,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.DEFAULT_INTERVAL_MS = exports.DEFAULT_TIMEOUT_MS = void 0;
 exports.waitForServer = waitForServer;
+exports.isPortInUse = isPortInUse;
 const net_1 = require("net");
 exports.DEFAULT_TIMEOUT_MS = 30000;
 exports.DEFAULT_INTERVAL_MS = 300;
@@ -39,6 +40,21 @@ async function waitForServer(host, port, options = {}) {
         await delay(Math.min(intervalMs, remaining));
     }
 }
+/**
+ * Whether something is accepting TCP connections on host:port right now.
+ *
+ * Issue #3087: a single attempt, used where "the port is free" has to be proven
+ * (before `start` spawns a server, after `stop` claims to have stopped one)
+ * rather than waited for.
+ *
+ * @param host - Host to connect to
+ * @param port - Port to connect to
+ * @param timeoutMs - How long one connection attempt may take
+ * @returns true if a connection was accepted
+ */
+function isPortInUse(host, port, timeoutMs = 1000) {
+    return tryConnect(host, port, timeoutMs);
+}
 /**
  * Attempt a single TCP connection.
  *

package/dist/lib/detection/status-reason.d.ts

@@ -112,6 +112,23 @@ export declare const STATUS_REASON: {
     readonly OPENCODE_RESPONSE_COMPLETE: "opencode_response_complete";
     readonly INPUT_PROMPT: "input_prompt";
     readonly NO_RECENT_OUTPUT: "no_recent_output";
+    /**
+     * Issue #3179: the agent's launch is still in progress.
+     *
+     * Published by `current-output-builder` and `worktree-status-helper` while
+     * `lib/session/session-starting-state` holds a record for the instance — from
+     * `beginAgentSession` until `startSession` returns or throws, bounded by the
+     * tool's readiness wait and released early by a dialog the launch does not
+     * answer. The frame underneath (a shell prompt and the launch line, or a trust
+     * dialog the launch is about to answer) is not read while it is up: the status
+     * is `running`, and `isUnclassifiedActive` / `isSelectionListActive` /
+     * `isPromptWaiting` are all false, so no pad, no answer sheet and no `wait`
+     * exit 10 is raised for a screen nobody has to drive.
+     *
+     * ADDITIVE in the sense {@link STATUS_REASON.EXITED} is: a reader that does not
+     * know the token sees a `running` session.
+     */
+    readonly STARTING: "starting";
     /**
      * Issue #2070: the tmux session is there, and the TOOL is not.
      *

package/dist/lib/detection/status-reason.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"status-reason.d.ts","sourceRoot":"","sources":["../../../src/lib/detection/status-reason.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH;;;GAGG;AACH,eAAO,MAAM,aAAa;;;;;IAKxB;;;;;;;;;;;;;;;;;;OAkBG;;IAEH,6EAA6E;;;IAG7E;;;;;;;;;;;;;;;;OAgBG;;IAEH;;;;;;;;;;;;;;;;;;;;;;;;;;OA0BG;;IAEH;;;;;;;;;;;OAWG;;;;IAIH,kEAAkE;;IAElE,6EAA6E;;;;;;IAM7E;;;;;;;;;;;;;;;OAeG;;IAEH;;;;;;;;;;;;;;;OAeG;;;CAGK,CAAC"}
+{"version":3,"file":"status-reason.d.ts","sourceRoot":"","sources":["../../../src/lib/detection/status-reason.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH;;;GAGG;AACH,eAAO,MAAM,aAAa;;;;;IAKxB;;;;;;;;;;;;;;;;;;OAkBG;;IAEH,6EAA6E;;;IAG7E;;;;;;;;;;;;;;;;OAgBG;;IAEH;;;;;;;;;;;;;;;;;;;;;;;;;;OA0BG;;IAEH;;;;;;;;;;;OAWG;;;;IAIH,kEAAkE;;IAElE,6EAA6E;;;;;;IAM7E;;;;;;;;;;;;;;;OAeG;;IAEH;;;;;;;;;;;;;;;OAeG;;IAEH;;;;;;;;;;;;;;;OAeG;;;CAGK,CAAC"}