commandmate 0.47.2 → 0.48.0

package/dist/server/src/lib/tmux/tmux-capture-cache.js

@@ -24,6 +24,7 @@ exports.isCaptureWindowSaturated = isCaptureWindowSaturated;
 exports.getCaptureGeneration = getCaptureGeneration;
 exports.isCaptureGenerationCurrent = isCaptureGenerationCurrent;
 exports.sliceOutput = sliceOutput;
+exports.sliceCutsHead = sliceCutsHead;
 exports.getCachedCapture = getCachedCapture;
 exports.setCachedCapture = setCachedCapture;
 exports.invalidateCache = invalidateCache;
@@ -87,6 +88,10 @@ function getCache() {
 function getInflight() {
     return (0, global_state_1.getOrInitGlobal)('__tmuxCaptureCacheInflight', () => new Map());
 }
+/** When each in-flight fetch started (Issue #3798), for the callers that join it. */
+function getInflightStartedAt() {
+    return (0, global_state_1.getOrInitGlobal)('__tmuxCaptureCacheInflightStartedAt', () => new WeakMap());
+}
 function getGenerationState() {
     return (0, global_state_1.getOrInitGlobal)('__tmuxCaptureCacheGeneration', () => ({ global: 0, sessions: new Map() }));
 }
@@ -122,8 +127,24 @@ function isCaptureGenerationCurrent(sessionName, generation) {
 // sliceOutput()
 // =========================================================================
 /**
- * Slice output from the end to return the last requestedLines lines.
- * If requestedLines >= total lines, returns the full output.
+ * A capture's rows (Issue #3881 third review N4). tmux ends every row with a
+ * newline, so the last one terminates a row and is not a row of its own: a
+ * 1000-row pane comes back as 1000 rows and a terminator, which `split` makes
+ * 1001 elements.
+ */
+function rowsOf(output) {
+    const terminated = output.endsWith('\n');
+    return { rows: (terminated ? output.slice(0, -1) : output).split('\n'), terminated };
+}
+/**
+ * Slice output from the end to return the last requestedLines rows.
+ * If requestedLines >= total rows, returns the full output.
+ *
+ * Issue #3881 (third review N4): counted in rows, the terminator kept. Counted
+ * in `split` elements, the terminator took one of the requested rows, so a
+ * 1000-row pane asked for 1000 rows lost its first row — on an
+ * alternate-screen pane, the row that says whether the content begins at the
+ * top of the screen.
  *
  * @param fullOutput - Full captured output string
  * @param requestedLines - Number of lines requested from the end
@@ -132,10 +153,21 @@ function isCaptureGenerationCurrent(sessionName, generation) {
 function sliceOutput(fullOutput, requestedLines) {
     if (fullOutput === '')
         return '';
-    const lines = fullOutput.split('\n');
-    if (requestedLines >= lines.length)
+    const { rows, terminated } = rowsOf(fullOutput);
+    if (requestedLines >= rows.length)
         return fullOutput;
-    return lines.slice(-requestedLines).join('\n');
+    return rows.slice(-requestedLines).join('\n') + (terminated ? '\n' : '');
+}
+/**
+ * Whether {@link sliceOutput} drops rows from the top of `fullOutput` (Issue
+ * #3881 third review N4): the one fact about a capture's top that its row count
+ * cannot tell when the window is exactly the pane's height.
+ *
+ * @param fullOutput - Full captured output string
+ * @param requestedLines - Number of lines requested from the end
+ */
+function sliceCutsHead(fullOutput, requestedLines) {
+    return fullOutput !== '' && requestedLines < rowsOf(fullOutput).rows.length;
 }
 // =========================================================================
 // getCachedCapture()
@@ -180,8 +212,10 @@ function getCachedCapture(sessionName, requestedLines) {
  * @param sessionName - tmux session name (cache key)
  * @param output - Captured output string
  * @param capturedLines - Number of lines the output was captured with
+ * @param fetchStartedAt - When the capture began (Issue #3798); every writer
+ *   in this app passes it. Defaults to now, the write time
  */
-function setCachedCapture(sessionName, output, capturedLines) {
+function setCachedCapture(sessionName, output, capturedLines, fetchStartedAt) {
     const cache = getCache();
     const now = Date.now();
     // [SEC4-002] Full sweep: remove all TTL-expired entries
@@ -209,8 +243,22 @@ function setCachedCapture(sessionName, output, capturedLines) {
         output,
         capturedLines,
         timestamp: now,
+        fetchStartedAt: fetchStartedAt ?? now,
     });
 }
+/**
+ * When the cached capture of `sessionName` was started, or null when nothing
+ * live is cached (Issue #3798). Read-only: an expired entry is left for the
+ * next read to evict.
+ *
+ * @param sessionName - tmux session name (cache key)
+ */
+function getCachedCaptureFetchStartedAt(sessionName) {
+    const entry = getCache().get(sessionName);
+    if (!entry || Date.now() - entry.timestamp > exports.CACHE_TTL_MS)
+        return null;
+    return entry.fetchStartedAt;
+}
 // =========================================================================
 // invalidateCache()
 // =========================================================================
@@ -262,10 +310,8 @@ function resetCacheForTesting() {
     globalThis.__tmuxCaptureCache = undefined;
     globalThis.__tmuxCaptureCacheInflight = undefined;
     globalThis.__tmuxCaptureCacheGeneration = undefined;
+    globalThis.__tmuxCaptureCacheInflightStartedAt = undefined;
 }
-// =========================================================================
-// getOrFetchCapture() - singleflight pattern
-// =========================================================================
 /**
  * Get capture output from cache or fetch it.
  * Implements singleflight pattern: concurrent requests for the same session
@@ -277,33 +323,52 @@ function resetCacheForTesting() {
  * @param sessionName - tmux session name
  * @param requestedLines - Number of lines requested
  * @param fetchFn - Function to fetch output on cache miss
+ * @param onServed - Told where the returned frame came from (Issue #3798),
+ *   right before it is returned; not called when the capture throws
+ * @param onSliced - Told whether the slice to `requestedLines` dropped rows
+ *   from the top of what tmux returned (Issue #3881 third review N4,
+ *   {@link sliceCutsHead}), right before it is returned
  * @returns Captured output (sliced to requestedLines)
  */
-async function getOrFetchCapture(sessionName, requestedLines, fetchFn) {
+async function getOrFetchCapture(sessionName, requestedLines, fetchFn, onServed, onSliced) {
     // 1. Check cache first
+    const cachedStartedAt = getCachedCaptureFetchStartedAt(sessionName);
     const cached = getCachedCapture(sessionName, requestedLines);
     if (cached !== null) {
+        if (cachedStartedAt !== null)
+            onServed?.({ fetchStartedAt: cachedStartedAt, source: 'cache' });
+        const entry = getCache().get(sessionName);
+        if (entry)
+            onSliced?.(sliceCutsHead(entry.output, requestedLines));
         return cached;
     }
     // 2. Check for inflight request (singleflight)
     const inflight = getInflight();
     const existingPromise = inflight.get(sessionName);
     if (existingPromise) {
+        const joinedStartedAt = getInflightStartedAt().get(existingPromise);
         const result = await existingPromise;
+        if (joinedStartedAt !== undefined)
+            onServed?.({ fetchStartedAt: joinedStartedAt, source: 'joined' });
+        onSliced?.(sliceCutsHead(result, requestedLines));
         return sliceOutput(result, requestedLines);
     }
     // 3. Create new fetch promise
     // Issue #3734: snapshot the generation before fetchFn() starts
     const generation = getCaptureGeneration(sessionName);
+    const fetchStartedAt = Date.now();
     const fetchPromise = fetchFn();
     inflight.set(sessionName, fetchPromise);
+    getInflightStartedAt().set(fetchPromise, fetchStartedAt);
     try {
         const output = await fetchPromise;
         // Cache non-empty results only [SEC4-007], and only when no invalidation
         // happened while waiting (Issue #3734)
         if (output.length > 0 && isCaptureGenerationCurrent(sessionName, generation)) {
-            setCachedCapture(sessionName, output, exports.CACHE_MAX_CAPTURE_LINES);
+            setCachedCapture(sessionName, output, exports.CACHE_MAX_CAPTURE_LINES, fetchStartedAt);
         }
+        onServed?.({ fetchStartedAt, source: 'fetched' });
+        onSliced?.(sliceCutsHead(output, requestedLines));
         return sliceOutput(output, requestedLines);
     }
     finally {

package/dist/server/src/lib/tmux/tmux.js

@@ -4,7 +4,7 @@
  * Provides functions to manage tmux sessions for Claude CLI integration
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.DIRECT_INPUT_TEXT_CHUNK_BYTES = exports.REPAINT_INVALIDATE_DELAY_MS = exports.NAVIGATION_KEY_VALUES = exports.SPECIAL_KEY_VALUES = exports.SpecialKeysAbortedError = void 0;
+exports.DIRECT_INPUT_TEXT_CHUNK_BYTES = exports.REPAINT_INVALIDATE_DELAY_MS = exports.NAVIGATION_KEY_VALUES = exports.SPECIAL_KEY_VALUES = exports.SpecialKeysAbortedError = exports.TmuxSendError = void 0;
 exports.exactTarget = exactTarget;
 exports.reconcileSessionGeometry = reconcileSessionGeometry;
 exports.hasSession = hasSession;
@@ -14,6 +14,7 @@ exports.getPaneCurrentCommand = getPaneCurrentCommand;
 exports.listSessions = listSessions;
 exports.createSession = createSession;
 exports.sendKeys = sendKeys;
+exports.deliveryOfExecFailure = deliveryOfExecFailure;
 exports.isSendableSpecialKey = isSendableSpecialKey;
 exports.sendSpecialKeys = sendSpecialKeys;
 exports.capturePane = capturePane;
@@ -462,8 +463,9 @@ async function createSession(sessionNameOrOptions, cwd) {
  * @param sendEnter - Whether to send Enter key after the command (default: true)
  * @param options - {@link SendKeysOptions}; pass `{ literal: true }` for text
  *
- * @throws {Error} If session doesn't exist, command fails, or `literal` is
- *   combined with `sendEnter`
+ * @throws {TmuxSendError} If session doesn't exist, command fails, or `literal` is
+ *   combined with `sendEnter`; its `delivery` says whether the keys may be on
+ *   the pane (Issue #3880). A normal return is `delivered`: tmux exited 0.
  *
  * @example
  * ```typescript
@@ -476,7 +478,7 @@ async function createSession(sessionNameOrOptions, cwd) {
  */
 async function sendKeys(sessionName, keys, sendEnter = true, options) {
     if (options?.literal && sendEnter) {
-        throw new Error('sendKeys: { literal: true } cannot be combined with sendEnter — a trailing C-m would be typed as text. Send Enter as a separate key.');
+        throw new TmuxSendError('sendKeys: { literal: true } cannot be combined with sendEnter — a trailing C-m would be typed as text. Send Enter as a separate key.', 'not-started', 0);
     }
     // execFile() passes arguments directly without shell interpretation,
     // so no shell-level escaping is needed
@@ -496,9 +498,45 @@ async function sendKeys(sessionName, keys, sendEnter = true, options) {
     }
     catch (error) {
         const errorMessage = error instanceof Error ? error.message : String(error);
-        throw new Error(`Failed to send keys to tmux session: ${errorMessage}`);
+        throw new TmuxSendError(`Failed to send keys to tmux session: ${errorMessage}`, deliveryOfExecFailure(error), 0);
     }
 }
+/**
+ * A `sendKeys` / `sendSpecialKeys` that failed, with how far it got
+ * (Issue #3880). The message is the one these functions always threw.
+ */
+class TmuxSendError extends Error {
+    delivery;
+    keysDelivered;
+    constructor(message, 
+    /** What the call that failed did; a failed call is never `delivered`. */
+    delivery, 
+    /** How many keys before it tmux was seen to take (`sendSpecialKeys`; 0 for `sendKeys`). */
+    keysDelivered) {
+        super(message);
+        this.delivery = delivery;
+        this.keysDelivered = keysDelivered;
+        this.name = 'TmuxSendError';
+    }
+}
+exports.TmuxSendError = TmuxSendError;
+/**
+ * Which {@link KeyDeliveryState} a rejected `execFile` of `tmux send-keys` is
+ * (Issue #3880). Read off the error's shape, never its wording: an exit status
+ * (`code` a number) is tmux refusing the command, an errno string (`ENOENT`)
+ * is a process that never ran, and anything else — `killed` by the timeout, a
+ * `signal`, an error of no known shape — may have left the key on the pane.
+ */
+function deliveryOfExecFailure(error) {
+    if (typeof error !== 'object' || error === null)
+        return 'indeterminate';
+    const { code, killed, signal } = error;
+    if (killed === true || (typeof signal === 'string' && signal !== ''))
+        return 'indeterminate';
+    if (typeof code === 'number' || typeof code === 'string')
+        return 'not-started';
+    return 'indeterminate';
+}
 /**
  * Allowed tmux special key names for sendSpecialKeys() (multi-key TUI navigation).
  * Used for cursor-based navigation sequences (e.g., ['Down', 'Down', 'Enter']).
@@ -607,7 +645,9 @@ exports.SpecialKeysAbortedError = SpecialKeysAbortedError;
  * @param sessionName - Target session name
  * @param keys - Array of tmux special key names (e.g., ['Down', 'Down', 'Space', 'Enter'])
  * @param options - Optional `shouldContinue`, asked after each delay (Issue #3706)
- * @throws {Error} If any key name is not in the allowed set, or if tmux command fails
+ * @throws {TmuxSendError} If any key name is not in the allowed set (`not-started`,
+ *   nothing sent), or if a tmux command fails — with the keys before it that
+ *   tmux took and what the failing call did (Issue #3880)
  * @throws {SpecialKeysAbortedError} If `shouldContinue` returned false between two keys
  */
 async function sendSpecialKeys(sessionName, keys, options) {
@@ -616,12 +656,15 @@ async function sendSpecialKeys(sessionName, keys, options) {
     // Validate all keys are in the allowed set (command injection prevention)
     for (const key of keys) {
         if (!ALLOWED_SPECIAL_KEYS.has(key)) {
-            throw new Error(`Invalid special key: ${key}`);
+            throw new TmuxSendError(`Invalid special key: ${key}`, 'not-started', 0);
         }
     }
+    // Issue #3880: the keys tmux was seen to take, for the error of a later one.
+    let delivered = 0;
     try {
         for (let i = 0; i < keys.length; i++) {
             await execFileAsync('tmux', ['send-keys', '-t', exactTarget(sessionName), keys[i]], { timeout: DEFAULT_TIMEOUT });
+            delivered = i + 1;
             // Delay between key presses (skip after the last key)
             if (i < keys.length - 1) {
                 await new Promise(resolve => setTimeout(resolve, SPECIAL_KEY_DELAY_MS));
@@ -635,7 +678,7 @@ async function sendSpecialKeys(sessionName, keys, options) {
         if (error instanceof SpecialKeysAbortedError)
             throw error;
         const errorMessage = error instanceof Error ? error.message : String(error);
-        throw new Error(`Failed to send special keys to tmux session: ${errorMessage}`);
+        throw new TmuxSendError(`Failed to send special keys to tmux session: ${errorMessage}`, deliveryOfExecFailure(error), delivered);
     }
 }
 /**
@@ -965,7 +1008,9 @@ exports.REPAINT_INVALIDATE_DELAY_MS = 250;
  * Drop the cached frame again once the TUI has had time to repaint.
  *
  * Fire-and-forget on purpose: the route must not wait 250 ms to answer, and the
- * work is one `Map.delete`. The timer is `unref()`ed where the runtime supports
+ * work is synchronous and small — `invalidateCache` drops the cached frame and
+ * the inflight capture and advances the session's generation (Issue #3734), so
+ * a capture started before the repaint is not written back either. The timer is `unref()`ed where the runtime supports
  * it so a pending invalidation can never hold a process (or a test runner) open.
  */
 function scheduleRepaintInvalidation(sessionName) {

package/dist/server/src/lib/verification/gate-runner.js

@@ -21,7 +21,7 @@
  * @module lib/verification/gate-runner
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.VerificationConflictError = exports.FLAKY_LOG_PREFIX = exports.MUTEX_WAIT_SKIP_REASON = exports.MUTEX_LOG_PREFIX = exports.WORKTREE_INDEX_ENV = exports.WORKTREE_ID_ENV = exports.MAX_CONCURRENT_VERIFICATIONS = exports.CONFIG_GATE_ID = exports.ENV_CLEAN_GATE_ID = exports.SCOPE_GATE_ID = exports.WORK_EVIDENCE_GATE_ID = void 0;
+exports.VerificationConflictError = exports.TIMING_LOG_PREFIX = exports.FLAKY_LOG_PREFIX = exports.MUTEX_WAIT_SKIP_REASON = exports.MUTEX_LOG_PREFIX = exports.WORKTREE_INDEX_ENV = exports.WORKTREE_ID_ENV = exports.MAX_CONCURRENT_VERIFICATIONS = exports.CONFIG_GATE_ID = exports.ENV_CLEAN_GATE_ID = exports.SCOPE_GATE_ID = exports.WORK_EVIDENCE_GATE_ID = void 0;
 exports.waitForVerification = waitForVerification;
 exports.cancelVerification = cancelVerification;
 exports.startVerification = startVerification;
@@ -87,6 +87,9 @@ const ENV_CLEAN_GATE_COMMAND = 'lsof -iTCP -sTCP:LISTEN / tmux list-sessions / $
  * once turns a verification request into a fork bomb on a developer laptop.
  * Excess runs queue rather than fail: the run row already exists and its
  * caller has the id, so a queued run is honest about what will happen.
+ *
+ * A bound on gates *executing*, not on runs open: a run waiting for a gate's
+ * `mutex` gives its slot back for the wait (Issue #3884, see RunSlot).
  */
 exports.MAX_CONCURRENT_VERIFICATIONS = 2;
 /** Grace period between SIGTERM and SIGKILL for a gate that overran. */
@@ -144,6 +147,33 @@ exports.MUTEX_WAIT_SKIP_REASON = 'reason=mutex-wait';
  * cannot import this module — `tsconfig.cli.json` compiles `src/cli/**` alone.
  */
 exports.FLAKY_LOG_PREFIX = '[flaky]';
+/**
+ * Marker line carrying a command gate's waits and its execution, apart, into
+ * `log_tail` (Issue #3884).
+ *
+ * `[timing] queue=<s> mutex=<s> run=<s>`: `queue` is the time the run waited
+ * for a {@link MAX_CONCURRENT_VERIFICATIONS} slot before and during this gate
+ * (the first command gate also carries the run's initial queue), `mutex` the
+ * time it waited for the gate's machine-wide lock, and `run` the gate's own
+ * command — `duration_ms`, which still never includes either wait (#1771).
+ * Three numbers because "this run took 40 minutes" has three different fixes:
+ * fewer runs at once, fewer heavy gates, or a faster suite.
+ *
+ * The last line, so the first line keeps meaning what it meant (the skip
+ * reason a reader of a `skipped` gate takes, the `[mutex]` / `[flaky]` marker
+ * the CLI reads). Written only for a gate that has a `mutex` or that waited for
+ * a slot: a gate that did neither has no wait to report, and its log stays
+ * byte-identical to before the marker existed. Travels on `log_tail` like
+ * `waited=` does, so it reaches `verify --json` and `verify show` without a
+ * migration; the history listing, which carries no log, reads this one line
+ * into numbers (verification-db.ts parseGateTiming, the `timing` of a gate
+ * summary — keep the two formats in step).
+ */
+exports.TIMING_LOG_PREFIX = '[timing]';
+function timingMarker(waits, runMs) {
+    return (`${exports.TIMING_LOG_PREFIX} queue=${formatSeconds(waits.queueMs)} ` +
+        `mutex=${formatSeconds(waits.mutexMs)} run=${formatSeconds(runMs)}`);
+}
 /**
  * Runs a gate is allowed. Not derived from `retryOnFail` at the call site: the
  * marker states the number so a reader of stored history never has to look up
@@ -204,13 +234,43 @@ function notRun(logTail) {
 // =============================================================================
 let activeVerifications = 0;
 const slotWaiters = [];
-function acquireSlot() {
+/**
+ * @param priority queue ahead of every run still waiting to start (Issue #3884).
+ *        Used by a run that gave its slot back while it waited for a gate's
+ *        `mutex` and now holds that machine-wide lock: every second it spends
+ *        here is a second the lock is held with nothing running under it.
+ */
+function acquireSlot(priority = false, cancellation) {
     if (activeVerifications < exports.MAX_CONCURRENT_VERIFICATIONS) {
         activeVerifications += 1;
-        return Promise.resolve();
+        return Promise.resolve(true);
     }
     return new Promise((resolve) => {
-        slotWaiters.push(resolve);
+        let settled = false;
+        let unregister = () => { };
+        const grant = () => {
+            settled = true;
+            unregister();
+            resolve(true);
+        };
+        if (priority)
+            slotWaiters.unshift(grant);
+        else
+            slotWaiters.push(grant);
+        // Issue #3884 N3: a cancelled wait leaves the queue instead of waiting for
+        // whatever the other slots are executing. Leaving takes nothing, so there
+        // is nothing to hand back.
+        if (cancellation) {
+            unregister = cancellation.register(() => {
+                if (settled)
+                    return;
+                settled = true;
+                const at = slotWaiters.indexOf(grant);
+                if (at >= 0)
+                    slotWaiters.splice(at, 1);
+                resolve(false);
+            });
+        }
     });
 }
 function releaseSlot() {
@@ -223,6 +283,63 @@ function releaseSlot() {
     }
     activeVerifications -= 1;
 }
+/**
+ * One run's hold on a {@link MAX_CONCURRENT_VERIFICATIONS} slot (Issue #3884 H-11).
+ *
+ * The slot bounds what *executes*, not what waits. A run used to take its slot
+ * up front and keep it while a gate queued for its `mutex` (`cpu.heavy`, up to
+ * the gate's whole `timeoutSec`), so one run holding the lock and one waiting
+ * for it filled both slots, and a third run could not start even its 5-second
+ * `lint`. {@link runGateAttempt} now hands the slot back while it waits for the
+ * lock and takes it again — ahead of the runs still waiting to start — once the
+ * lock is held. At most {@link MAX_CONCURRENT_VERIFICATIONS} gates still
+ * execute at once, and the heavy gates stay one per machine under their mutex,
+ * so the load a gate is judged under does not grow.
+ *
+ * No deadlock: a run waiting for a lock holds no slot, so every slot holder is
+ * executing a gate, and each gate ends within its own `timeoutSec`.
+ *
+ * Also the clock for the `queue=` of {@link TIMING_LOG_PREFIX}: the time spent
+ * waiting for a slot since the last {@link RunSlot.takeQueuedMs}.
+ */
+class RunSlot {
+    held = false;
+    queuedMs = 0;
+    get isHeld() {
+        return this.held;
+    }
+    /**
+     * @param cancellation when given, a cancel abandons the wait (Issue #3884 N3)
+     * @returns false when the wait was abandoned: no slot is held
+     */
+    async acquire(priority = false, cancellation) {
+        if (this.held)
+            return true;
+        // Only a real queue counts: a free slot is taken without a wait, and a
+        // gate that never waited must not grow a `queue=0.0s` line (its log stays
+        // byte-identical to before #3884).
+        const queued = activeVerifications >= exports.MAX_CONCURRENT_VERIFICATIONS;
+        const startedAt = Date.now();
+        const taken = await acquireSlot(priority, cancellation);
+        this.held = taken;
+        if (queued)
+            this.queuedMs += Math.max(1, Date.now() - startedAt);
+        return taken;
+    }
+    /** Idempotent: a slot already handed back is not released twice. */
+    release() {
+        if (!this.held)
+            return;
+        this.held = false;
+        releaseSlot();
+    }
+    /** The slot wait accumulated since the previous call, and reset it. */
+    takeQueuedMs() {
+        const queued = this.queuedMs;
+        this.queuedMs = 0;
+        return queued;
+    }
+}
 /**
  * In-flight runs, so callers (tests, and the CLI in Phase 1-4) can await a run
  * that {@link startVerification} deliberately did not wait for.
@@ -578,7 +695,7 @@ function machineLockPathFor(name) {
  * across both, so a retry never keeps a machine-wide resource out of another
  * worktree's hands for a run that has already failed once.
  */
-async function runGateAttempt(gate, worktreePath, maxLogTailBytes, gateEnv, cancellation) {
+async function runGateAttempt(gate, worktreePath, maxLogTailBytes, gateEnv, cancellation, slot, waits) {
     const mutex = gate.mutex;
     if (!mutex) {
         return runCommand(gate.command, worktreePath, gate.timeoutSec, maxLogTailBytes, gateEnv, cancellation);
@@ -591,10 +708,25 @@ async function runGateAttempt(gate, worktreePath, maxLogTailBytes, gateEnv, canc
     // cancelled while queued behind the lock used to stay `running` for up to
     // half an hour — holding the worktree against the very endpoint that exists
     // to release it.
+    //
+    // Issue #3884 H-11: the run's slot is handed back for as long as the lock is
+    // busy (never when it is free — `onWait` fires only once a claim has failed),
+    // and taken back ahead of the runs still waiting to start. See RunSlot.
     const lock = await (0, machine_lock_1.acquireMachineLock)(mutex, {
         timeoutMs: gate.timeoutSec * 1000,
         shouldAbandon: () => cancellation.cancelled,
+        onWait: () => slot.release(),
     });
+    waits.mutexMs += lock.waitedMs;
+    // Taken back even when the lock was not: the run goes on to record (or run)
+    // the gates after this one, and those are under the same bound. Not by a
+    // cancelled run (#3884 N3): it executes nothing more, and waiting for the
+    // gates the other slots are running would keep its worktree held past the
+    // cancel endpoint's budget. The wait for the slot is cancellable too — the
+    // latch is read below, and the lock released, once it returns.
+    if (!cancellation.cancelled)
+        await slot.acquire(true, cancellation);
+    waits.queueMs += slot.takeQueuedMs();
     if (!lock.acquired) {
         const recordedAt = Date.now();
         return {
@@ -646,14 +778,28 @@ async function runGateAttempt(gate, worktreePath, maxLogTailBytes, gateEnv, canc
  * came free) and an `error` (the command could not be spawned) never started a
  * command, so there is no verdict to seek a second opinion on.
  */
-async function runCommandGate(gate, worktreePath, maxLogTailBytes, gateEnv, cancellation) {
-    const first = await runGateAttempt(gate, worktreePath, maxLogTailBytes, gateEnv, cancellation);
+async function runCommandGate(gate, worktreePath, maxLogTailBytes, gateEnv, cancellation, slot) {
+    // The slot wait since the previous command gate (for the first one, since
+    // the run was opened) belongs to this gate: it is what kept it from starting.
+    const waits = { queueMs: slot.takeQueuedMs(), mutexMs: 0 };
+    const outcome = await runCommandGateAttempts(gate, worktreePath, maxLogTailBytes, gateEnv, cancellation, slot, waits);
+    if (!gate.mutex && waits.queueMs === 0)
+        return outcome;
+    return {
+        ...outcome,
+        logTail: `${outcome.logTail ? `${outcome.logTail}\n` : ''}${timingMarker(waits, outcome.durationMs)}`,
+    };
+}
+/** {@link runCommandGate}'s attempts, with the waits they accumulate. */
+async function runCommandGateAttempts(gate, worktreePath, maxLogTailBytes, gateEnv, cancellation, slot, waits) {
+    const attempt = () => runGateAttempt(gate, worktreePath, maxLogTailBytes, gateEnv, cancellation, slot, waits);
+    const first = await attempt();
     // A cancelled attempt reports `skipped`, so the retry below is already ruled
     // out by the status check: an operator's Stop must not buy a second run of
     // the very command they stopped.
     if (gate.retryOnFail !== 1 || first.status !== 'failed')
         return first;
-    const second = await runGateAttempt(gate, worktreePath, maxLogTailBytes, gateEnv, cancellation);
+    const second = await attempt();
     if (second.status !== 'passed' && second.status !== 'failed') {
         // The retry reached no verdict of its own, so there is nothing to compare
         // the first run against. The first run's FAIL stands unchanged — reporting
@@ -1024,7 +1170,9 @@ async function executeRun(db, runId, worktreeId, worktreePath,
 /** Issue #2043: which agent instance the run is judging, for the second witness. */
 instanceId, config, selection, baseRef, task, detachedContract, envClean, 
 /** Issue #2063: the operator's Stop switch for this run. */
-cancellation) {
+cancellation, 
+/** Issue #3884: handed back while a gate waits for its mutex. */
+slot) {
     const { maxLogTailBytes, skipInPrimaryCheckout } = config.options;
     const { runWorkEvidence, gates } = selection;
     // Issue #2043. A thunk rather than a number so the store is read at the
@@ -1209,7 +1357,7 @@ cancellation) {
             statuses.push(recordNotRun(gate.id, gate.command, gate.source, run_verdict_vocabulary_1.PRIMARY_CHECKOUT_SKIP_LOG).status);
             continue;
         }
-        const outcome = await runGate(gate.id, gate.command, gate.source, () => runCommandGate(gate, worktreePath, maxLogTailBytes, gateEnv(), cancellation));
+        const outcome = await runGate(gate.id, gate.command, gate.source, () => runCommandGate(gate, worktreePath, maxLogTailBytes, gateEnv(), cancellation, slot));
         statuses.push(outcome.status);
     }
     // The loop's own check cannot see a cancel that landed during the LAST gate:
@@ -1487,8 +1635,9 @@ async function startVerification(input) {
         baseline: resolvedSelection.runEnvClean && taskId ? (0, env_snapshot_1.loadEnvSnapshot)(taskId) : null,
         decision: envCleanDecision,
     };
+    const slot = new RunSlot();
     const completion = (async () => {
-        await acquireSlot();
+        await slot.acquire();
         let terminalStatus = 'error';
         try {
             // Cancelled while queued behind MAX_CONCURRENT_VERIFICATIONS: nothing was
@@ -1499,7 +1648,7 @@ async function startVerification(input) {
                 (0, db_1.finishVerificationRun)(db, run.id, 'cancelled');
                 return 'cancelled';
             }
-            const status = await executeRun(db, run.id, input.worktreeId, input.worktreePath, input.instanceId, resolvedConfig, resolvedSelection, baseRef, task, detachedContract, envCleanContext, cancellation);
+            const status = await executeRun(db, run.id, input.worktreeId, input.worktreePath, input.instanceId, resolvedConfig, resolvedSelection, baseRef, task, detachedContract, envCleanContext, cancellation, slot);
             terminalStatus = status;
             (0, db_1.finishVerificationRun)(db, run.id, status);
             return status;
@@ -1526,7 +1675,7 @@ async function startVerification(input) {
             // after the task transition so the run's own history is complete before
             // anything is said about it.
             notifyRunFailure(db, input, run.id, taskId, terminalStatus);
-            releaseSlot();
+            slot.release();
             inFlight.delete(run.id);
             cancellations.delete(run.id);
         }

package/dist/server/src/lib/verification/machine-lock.js

@@ -161,6 +161,7 @@ async function acquireMachineLock(name, options) {
     // A stale record is broken at most once per token, so a directory nobody can
     // remove degrades into ordinary waiting instead of a spin loop.
     const broken = new Set();
+    let waiting = false;
     for (;;) {
         // Issue #2063. Checked before the claim as well as after the sleep, so a
         // caller that was already cancelled when it got here never takes a lock it
@@ -210,6 +211,10 @@ async function acquireMachineLock(name, options) {
         if (now >= deadline) {
             return { acquired: false, waitedMs: now - startedAt, heldBy: describeOwner(holder) };
         }
+        if (!waiting) {
+            waiting = true;
+            options.onWait?.();
+        }
         await sleep(Math.min(pollIntervalMs, deadline - now));
     }
 }

package/dist/server/src/lib/ws-server.js

@@ -738,7 +738,11 @@ function handleDisconnect(ws) {
     // what it obtains instead of registering it on a socket that is gone.
     clientInfo.terminalSubscriptionSeq += 1;
     if (clientInfo.terminalSubscription) {
-        void clientInfo.terminalSubscription.unsubscribe();
+        // Issue #3749: not awaited, so a rejection would otherwise surface as an
+        // unhandled rejection.
+        clientInfo.terminalSubscription.unsubscribe().catch(() => {
+            // Best-effort cleanup on disconnect.
+        });
         clientInfo.terminalSubscription = null;
     }
     // Remove client from clients map
@@ -792,7 +796,13 @@ async function handleTerminalSubscribe(ws, message) {
         // Detached before the await, so a request arriving meanwhile neither
         // releases it a second time nor has its own registration cleared by ours.
         clientInfo.terminalSubscription = null;
-        await previous.unsubscribe();
+        try {
+            await previous.unsubscribe();
+        }
+        catch {
+            // Issue #3749: best-effort, like the other teardowns. Letting it throw
+            // ended this handler here and the new subscribe silently never happened.
+        }
     }
     if (!isCurrent())
         return;
@@ -972,7 +982,7 @@ async function handleTerminalUnsubscribe(ws) {
         return;
     // Issue #3733: also withdraws a subscribe still in flight, which would
     // otherwise register after this and keep streaming.
-    clientInfo.terminalSubscriptionSeq += 1;
+    const seq = ++clientInfo.terminalSubscriptionSeq;
     const subscription = clientInfo.terminalSubscription;
     if (!subscription) {
         return;
@@ -985,6 +995,11 @@ async function handleTerminalUnsubscribe(ws) {
     catch {
         // Best-effort cleanup during terminal unsubscribe.
     }
+    // Issue #3749: a subscribe that started while the teardown was awaited may
+    // already have said `connected:true`; a `connected:false` sent after it
+    // would contradict the subscription that is now live.
+    if (clients.get(ws) !== clientInfo || clientInfo.terminalSubscriptionSeq !== seq)
+        return;
     sendTerminalEvent(ws, { type: 'terminal_status', connected: false });
 }
 // ---------------------------------------------------------------------------