commandmate 0.25.0 → 0.26.1

package/dist/server/src/lib/polling/response-poller-core.js

@@ -13,6 +13,7 @@ const logger_1 = require("../../lib/logger");
 const tui_accumulator_1 = require("../tui-accumulator");
 const prompt_dedup_1 = require("./prompt-dedup");
 const response_dedup_1 = require("./response-dedup");
+const prompt_dedup_state_1 = require("./prompt-dedup-state");
 const response_checker_1 = require("./response-checker");
 const terminal_broadcast_1 = require("../../lib/realtime/terminal-broadcast");
 const logger = (0, logger_1.createLogger)('response-poller');
@@ -205,7 +206,8 @@ function splitPollerKey(pollerKey) {
  * - `pollingStartTimes`, so MAX_POLLING_DURATION still measures from when the
  *   turn actually began rather than restarting the 30-minute budget;
  * - the prompt and response dedup hashes, so the screen currently on display is
- *   not saved a second time as a new message.
+ *   not saved a second time as a new message, together with the prompt-skip
+ *   tally that explains those suppressions to `capture --json` (Issue #1695).
  *
  * The TUI accumulator (opencode / copilot only) is re-initialised empty at the
  * new key instead of carried over: `tui-accumulator.ts` exposes no way to write
@@ -266,6 +268,14 @@ function migrateResponsePollerWorktreeIds(renames, resolveCliToolId) {
         exports.pollingStartTimes.delete(move.oldKey);
         (0, prompt_dedup_1.renamePromptHashCacheKey)(move.oldKey, move.newKey);
         (0, response_dedup_1.renameResponseHashCacheKey)(move.oldKey, move.newKey);
+        // Issue #1695: the prompt hash moved on the line above, so the guard keeps
+        // suppressing the prompt on screen under the new ID. Its tally has to move
+        // with it, or `capture --json` reports zero skips for a session that is
+        // still skipping. Old worktree ID comes back out of the key we just left.
+        const movedFrom = splitPollerKey(move.oldKey);
+        if (movedFrom) {
+            (0, prompt_dedup_state_1.renamePromptDedupSkips)(movedFrom.worktreeId, move.newWorktreeId, move.cliToolId, move.instanceId);
+        }
         (0, tui_accumulator_1.clearTuiAccumulator)(move.oldKey);
     }
     for (const pollerKey of abandoned) {

package/dist/server/src/lib/session/agent-session-lifecycle.js

@@ -39,6 +39,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.beginAgentSession = beginAgentSession;
 exports.prepareAgentLaunch = prepareAgentLaunch;
+exports.buildAgentLaunchCommandLine = buildAgentLaunchCommandLine;
 const sources_1 = require("../../lib/hooks/sources");
 const agent_event_state_1 = require("../../lib/session/agent-event-state");
 const logger_1 = require("../../lib/logger");
@@ -70,13 +71,33 @@ function beginAgentSession(target, at = Date.now()) {
  * does not import a settings generator: which file gets written, and whether
  * one gets written at all, is the source's business.
  *
- * Never throws — see {@link AgentEventSource.prepareLaunch}. A tool whose
- * config could not be written starts bare, which is the pre-#1722 status quo.
+ * Never throws — see `AgentEventSource.prepareLaunch`. A tool whose config
+ * could not be written starts bare, which is the pre-#1722 status quo.
  *
- * @param target - The instance being started
- * @param executablePath - Resolved path to the agent CLI
- * @returns The command line, and the config file when one was written
+ * @param context - The instance, its executable, and the worktree it runs in
+ * @returns The command, its environment, and the config file when one landed
  */
-function prepareAgentLaunch(target, executablePath) {
-    return (0, sources_1.getAgentEventSource)(target.cliToolId).prepareLaunch(target, executablePath);
+function prepareAgentLaunch(context) {
+    return (0, sources_1.getAgentEventSource)(context.target.cliToolId).prepareLaunch(context);
+}
+/**
+ * The single line a `startSession` types into its pane (Issue #1846).
+ *
+ * `prepareAgentLaunch` returns a plan whose environment is *data*; this is the
+ * one function that turns that data into shell assignments. Before #1846 four
+ * sources each wrote their own `NAME=value ` prefix onto `plan.command`, so
+ * "does this launcher apply the environment?" was answered four times, by
+ * accident, and a fifth source that forgot would have produced a session whose
+ * hooks fire and cannot be attributed — no error, events landing on the wrong
+ * instance.
+ *
+ * Callers that need the settings path as well should call
+ * {@link prepareAgentLaunch} and render the plan themselves; every caller in
+ * `src/lib/cli-tools/` wants only the line.
+ *
+ * @param context - The instance, its executable, and the worktree it runs in
+ * @returns `NAME='value' … command`, ready for `sendKeys`
+ */
+function buildAgentLaunchCommandLine(context) {
+    return (0, sources_1.renderAgentLaunchCommand)(prepareAgentLaunch(context));
 }

package/dist/server/src/lib/session/claude-session.js

@@ -601,7 +601,11 @@ async function startClaudeSession(options) {
         // Issue #1759: which config file gets written, and whether one is written
         // at all, belongs to the tool's `AgentEventSource` (S3/S4). Claude's
         // delegates to `buildClaudeLaunchCommand`, unchanged.
-        const launchCommand = (0, agent_session_lifecycle_1.prepareAgentLaunch)({ worktreeId, cliToolId: sources_1.CLAUDE_CLI_TOOL_ID, instanceId }, claudePath).command;
+        const launchCommand = (0, agent_session_lifecycle_1.buildAgentLaunchCommandLine)({
+            target: { worktreeId, cliToolId: sources_1.CLAUDE_CLI_TOOL_ID, instanceId },
+            executablePath: claudePath,
+            worktreePath,
+        });
         // Start Claude CLI in interactive mode using dynamically resolved path
         await (0, tmux_1.sendKeys)(sessionName, launchCommand, true);
         // Wait for Claude to initialize with dynamic detection (OCP-001)

package/dist/server/src/lib/session/current-output-builder.js

@@ -12,6 +12,7 @@ exports.mergeStructuredStatus = mergeStructuredStatus;
 exports.buildCurrentOutput = buildCurrentOutput;
 const db_1 = require("../../lib/db");
 const unclassified_frame_tracker_1 = require("../../lib/detection/unclassified-frame-tracker");
+const upstream_faults_1 = require("../../lib/detection/upstream-faults");
 const models_1 = require("../../types/models");
 const logger_1 = require("../../lib/logger");
 const manager_1 = require("../../lib/cli-tools/manager");
@@ -19,6 +20,7 @@ const cli_session_1 = require("../../lib/session/cli-session");
 const status_detector_1 = require("../../lib/detection/status-detector");
 const auto_yes_manager_1 = require("../../lib/polling/auto-yes-manager");
 const auto_yes_suppression_state_1 = require("../../lib/polling/auto-yes-suppression-state");
+const prompt_dedup_state_1 = require("../../lib/polling/prompt-dedup-state");
 const status_capture_config_1 = require("../../config/status-capture-config");
 const tmux_capture_cache_1 = require("../../lib/tmux/tmux-capture-cache");
 const agent_event_state_1 = require("../../lib/session/agent-event-state");
@@ -300,6 +302,18 @@ async function buildCurrentOutput(db, worktreeId, cliToolId, instanceId) {
             // the server's job, done here and in exactly one place.
             model: null,
             reasoningEffort: null,
+            // Issue #1695: the real tally, not zeros — and deliberately unlike the two
+            // fields above. A model latch describes a process, so on a dead session it
+            // would assert something false; a skip count describes what already
+            // happened, and `lastSkippedAt` dates it. Zeroing it here would erase the
+            // evidence at exactly the moment an operator goes looking for it — the
+            // session ended and the prompt they were waiting on was never saved.
+            promptDedup: (0, prompt_dedup_state_1.getPromptDedupSkips)(worktreeId, cliToolId, instanceId),
+            // Issue #1839: there is no frame to read, so there is nothing to report.
+            // Unlike `promptDedup` this is not a tally of what already happened — it
+            // is a claim about what is on screen right now, and a dead session has no
+            // screen.
+            upstreamFault: null,
         };
     }
     const sessionState = (0, db_1.getSessionState)(db, worktreeId, resolvedInstanceId);
@@ -455,6 +469,10 @@ async function buildCurrentOutput(db, worktreeId, cliToolId, instanceId) {
         });
     }
     const realtimeSnippet = lines.slice(-100).join('\n');
+    // Issue #1839: judged on exactly what is published as `realtimeSnippet`, not
+    // on `output`. The wider capture keeps a banner from an hour ago in scope, and
+    // a fault the operator cannot see in the payload next to it is unverifiable.
+    const upstreamFaultMatch = (0, upstream_faults_1.matchUpstreamFault)(realtimeSnippet);
     const autoYesState = (0, auto_yes_manager_1.getAutoYesState)(worktreeId, cliToolId, instanceId);
     // Issue #1785 + #1784: ONE resolution for both halves, not two readers.
     //
@@ -489,6 +507,9 @@ async function buildCurrentOutput(db, worktreeId, cliToolId, instanceId) {
             expiresAt: autoYesState?.enabled ? autoYesState.expiresAt : null,
             stopReason: autoYesState?.stopReason,
             lastSuppression: (0, auto_yes_suppression_state_1.getLastPolicySuppression)(worktreeId, cliToolId, instanceId),
+            // Issue #1694: undefined (so the key is absent from the JSON) unless a
+            // stop pattern actually fired — the state clears it on every other path.
+            stopMatchedText: autoYesState?.stopMatchedText,
         },
         isSelectionListActive,
         isPagerActive,
@@ -501,5 +522,18 @@ async function buildCurrentOutput(db, worktreeId, cliToolId, instanceId) {
         // docs on CurrentOutputPayload for why nothing is normalised on the way out.
         model,
         reasoningEffort: effort,
+        // Issue #1695: appended last on purpose — every field above is a published
+        // CLI contract and reordering them churns the diff for no reader's benefit.
+        promptDedup: (0, prompt_dedup_state_1.getPromptDedupSkips)(worktreeId, cliToolId, instanceId),
+        // Issue #1839: read from `realtimeSnippet`, the same rows an operator sees
+        // in `capture --json`, so what the field claims can be checked against what
+        // is printed next to it.
+        upstreamFault: upstreamFaultMatch
+            ? {
+                id: upstreamFaultMatch.fault.id,
+                matchedText: upstreamFaultMatch.matchedText,
+                at: Date.now(),
+            }
+            : null,
     };
 }

package/dist/server/src/lib/verification/env-snapshot.js

@@ -38,6 +38,8 @@ const os_1 = require("os");
 const path_1 = require("path");
 const env_1 = require("../../lib/env");
 const logger_1 = require("../../lib/logger");
+const machine_lock_1 = require("./machine-lock");
+const worktree_index_1 = require("./worktree-index");
 const logger = (0, logger_1.createLogger)('lib/verification/env-snapshot');
 /** Bumped only when a stored snapshot stops being readable by this module. */
 exports.ENV_SNAPSHOT_VERSION = 1;
@@ -299,12 +301,25 @@ async function probeTmuxSessions(deps) {
 exports.VOLATILE_ENTRY_PATTERNS = [/-wal$/, /-shm$/, /-journal$/, /^\.DS_Store$/];
 /** This module's own storage, which must not read as something a task created. */
 exports.ENV_SNAPSHOT_DIR_NAME = 'env-snapshots';
+/**
+ * Coordination directories the verification runner itself creates under
+ * `~/.commandmate` (Issue #1771): the gate mutex locks and the worktree index
+ * registry. Neither is a side effect of the delegation — the first mutexed gate
+ * on a machine creates them — so counting them would report the runner's own
+ * bookkeeping as pollution the agent left behind.
+ *
+ * Scoped to the `~/.commandmate` probe rather than added to
+ * {@link isIgnoredEntry}: a `~/locks` directory in `$HOME` is not ours, and
+ * blanket-ignoring the name would put a hole in the probe that exists to catch
+ * exactly that.
+ */
+const COMMANDMATE_RUNTIME_ENTRY_NAMES = [machine_lock_1.MACHINE_LOCK_DIR_NAME, worktree_index_1.WORKTREE_INDEX_DIR_NAME];
 function isIgnoredEntry(name) {
     if (name === exports.ENV_SNAPSHOT_DIR_NAME)
         return true;
     return exports.VOLATILE_ENTRY_PATTERNS.some((pattern) => pattern.test(name));
 }
-function probeDirectory(deps, path, { missingIsEmpty }) {
+function probeDirectory(deps, path, { missingIsEmpty, alsoIgnored = [] }) {
     let names;
     try {
         names = deps.readDir(path);
@@ -318,7 +333,7 @@ function probeDirectory(deps, path, { missingIsEmpty }) {
         return unavailable(`could not list ${path}: ${error.message}`);
     }
     return ok(names
-        .filter((name) => !isIgnoredEntry(name))
+        .filter((name) => !isIgnoredEntry(name) && !alsoIgnored.includes(name))
         .map((name) => ({ key: name, detail: null, anchor: null })));
 }
 /** Entries directly under `$HOME`. A worker leaving `~/.commandmate-uat-1726` shows up here. */
@@ -327,7 +342,10 @@ function probeHomeEntries(deps) {
 }
 /** Entries directly under `~/.commandmate` — the state directory #1722 polluted. */
 function probeCommandmateEntries(deps) {
-    return probeDirectory(deps, (0, path_1.join)(deps.homeDir(), '.commandmate'), { missingIsEmpty: true });
+    return probeDirectory(deps, (0, path_1.join)(deps.homeDir(), '.commandmate'), {
+        missingIsEmpty: true,
+        alsoIgnored: COMMANDMATE_RUNTIME_ENTRY_NAMES,
+    });
 }
 /**
  * Take one snapshot of all four probes.

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.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.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.startVerification = startVerification;
 const child_process_1 = require("child_process");
@@ -39,6 +39,8 @@ const contract_message_1 = require("../../lib/tasks/contract-message");
 const task_transition_service_1 = require("../../lib/tasks/task-transition-service");
 const env_clean_gate_1 = require("./env-clean-gate");
 const env_snapshot_1 = require("./env-snapshot");
+const machine_lock_1 = require("./machine-lock");
+const worktree_index_1 = require("./worktree-index");
 const scope_gate_1 = require("./scope-gate");
 const verify_config_1 = require("./verify-config");
 Object.defineProperty(exports, "ENV_CLEAN_GATE_ID", { enumerable: true, get: function () { return verify_config_1.ENV_CLEAN_GATE_ID; } });
@@ -74,6 +76,85 @@ const ENV_CLEAN_GATE_COMMAND = 'lsof -iTCP -sTCP:LISTEN / tmux list-sessions / $
 exports.MAX_CONCURRENT_VERIFICATIONS = 2;
 /** Grace period between SIGTERM and SIGKILL for a gate that overran. */
 const SIGKILL_GRACE_MS = 5000;
+/**
+ * Per-worktree environment every command gate is given (Issue #1771).
+ *
+ * `CM_WORKTREE_INDEX` is what lets a repository write
+ * `E2E_PORT=$((60400+CM_WORKTREE_INDEX))` and stop N parallel worktrees from
+ * fighting over one port — removing the collision instead of serializing around
+ * it, which is the only option that keeps the parallelism. `CM_WORKTREE_ID` is
+ * for everything a number cannot name: a container name, a database prefix, a
+ * log directory.
+ */
+exports.WORKTREE_ID_ENV = 'CM_WORKTREE_ID';
+exports.WORKTREE_INDEX_ENV = 'CM_WORKTREE_INDEX';
+/**
+ * Marker line carrying a mutexed gate's wait into `log_tail` (Issue #1771).
+ *
+ * `verification_gate_results` has no column for the wait, and it must not be
+ * folded into `duration_ms`: the duration is what the gate's own command took,
+ * and adding another run's queueing to it corrupts the number every timeout
+ * budget and every "this gate got slower" judgement is made from. The log tail
+ * is the same channel work-evidence's counts and the scope gate's evidence
+ * already travel on (`src/cli/commands/verify.ts:60-99`).
+ *
+ * Mirrored by `MUTEX_LOG_PREFIX` in `src/cli/utils/verify-runner.ts`, which
+ * cannot import this module — `tsconfig.cli.json` compiles `src/cli/**` alone.
+ */
+exports.MUTEX_LOG_PREFIX = '[mutex]';
+/**
+ * First line of a gate that never ran because the lock stayed held.
+ *
+ * Deliberately not `timeout`: the gate's command was never started, so there is
+ * nothing to say it ran long. Deliberately not `failed` either — the whole point
+ * of Issue #1771 is that a resource conflict and a broken change must stop
+ * reading the same. `skipped` aggregates the run to `error` (exit 99), which is
+ * "no verdict was reached", not "the work is bad".
+ */
+exports.MUTEX_WAIT_SKIP_REASON = 'reason=mutex-wait';
+/**
+ * Marker line carrying a retried gate's two runs into `log_tail` (Issue #1772).
+ *
+ * `verification_gate_results` stores one status, one exit code and one duration
+ * per gate, and a DB migration was out of scope for #1772, so the second run's
+ * numbers travel the same way #1771's wait does: a line-anchored, machine
+ * readable first line the CLI reads back.
+ *
+ * Written whenever a retry actually ran — for `outcome=fail` too, not only for
+ * `outcome=flaky`. A gate that failed twice is evidence *against* flakiness,
+ * and a flake advisor mining history needs both halves of that ratio; a marker
+ * present only on the flaky half would make every retried gate look flaky.
+ *
+ * Mirrored by `FLAKY_LOG_PREFIX` in `src/cli/utils/verify-runner.ts`, which
+ * cannot import this module — `tsconfig.cli.json` compiles `src/cli/**` alone.
+ */
+exports.FLAKY_LOG_PREFIX = '[flaky]';
+/**
+ * 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
+ * the verify.yaml that was in effect months ago.
+ */
+const RETRY_TOTAL_RUNS = 2;
+/**
+ * Separator between the two runs' outputs inside the composed log tail.
+ *
+ * Both are kept. Keeping only one makes the single question this feature exists
+ * to answer — *what differed between the two runs* — unanswerable from the
+ * record. `maxLogTailBytes` is applied per run, because it caps what one gate
+ * command may contribute and there were two commands.
+ */
+function flakyRunHeader(index, outcome) {
+    return (`--- ${exports.FLAKY_LOG_PREFIX} run ${index}/${RETRY_TOTAL_RUNS}: ${outcome.status} ` +
+        `exit=${formatExit(outcome.exitCode)} duration=${formatSeconds(outcome.durationMs)} ---`);
+}
+/** One decimal second, the spelling both `waited=` and `duration=` use. */
+function formatSeconds(ms) {
+    return `${(ms / 1000).toFixed(1)}s`;
+}
+/** `exit_code` is null for a gate killed by a signal; say so rather than lie. */
+function formatExit(exitCode) {
+    return exitCode === null ? 'n/a' : String(exitCode);
+}
 /** A run is already in flight for this worktree. Surfaces as HTTP 409. */
 class VerificationConflictError extends Error {
     worktreeId;
@@ -191,7 +272,7 @@ class TailBuffer {
  * process group — killing only the shell leaves the `npm`/`vitest` grandchildren
  * running and holding the worktree.
  */
-function runCommand(command, cwd, timeoutSec, maxLogTailBytes) {
+function runCommand(command, cwd, timeoutSec, maxLogTailBytes, gateEnv) {
     return new Promise((resolve) => {
         const startedAt = Date.now();
         const tail = new TailBuffer(maxLogTailBytes);
@@ -203,8 +284,9 @@ function runCommand(command, cwd, timeoutSec, maxLogTailBytes) {
             cwd,
             // CI=true matches how the same commands run in the pipeline; vitest picks
             // a different fileParallelism otherwise, and a gate that passes here but
-            // fails in CI is worse than no gate.
-            env: { ...process.env, CI: 'true' },
+            // fails in CI is worse than no gate. `gateEnv` carries the per-worktree
+            // identity (#1771) and is code-supplied, never user input.
+            env: { ...process.env, CI: 'true', ...gateEnv },
             detached: true,
             stdio: ['ignore', 'pipe', 'pipe'],
         });
@@ -272,6 +354,158 @@ function runCommand(command, cwd, timeoutSec, maxLogTailBytes) {
         });
     });
 }
+/**
+ * Prefix a gate's log with what it waited for, so the wait is on the record
+ * even when the command itself printed nothing.
+ *
+ * First line rather than last: the reader's question is "why did this gate take
+ * so long", and the answer belongs before the output it is about. The GATE line
+ * is built from the whole stored tail, so placement never decides whether
+ * `waited=` reaches the terminal.
+ */
+function withMutexMarker(name, waitedMs, lockPath, logTail) {
+    const marker = `${exports.MUTEX_LOG_PREFIX} name=${name} waited=${formatSeconds(waitedMs)} lock=${lockPath}`;
+    return prefixLogTail(marker, logTail);
+}
+/** The log of a gate whose lock never came free. */
+function mutexWaitTimeoutLog(gate, name, result) {
+    if (result.acquired)
+        throw new Error('mutexWaitTimeoutLog called for an acquired lock');
+    const held = result.heldBy ? ` (held by ${result.heldBy})` : '';
+    return [
+        `${exports.MUTEX_WAIT_SKIP_REASON} waited=${formatSeconds(result.waitedMs)}`,
+        `${exports.MUTEX_LOG_PREFIX} name=${name} lock=${machineLockPathFor(name)}${held}`,
+        `Gate '${gate.id}' declares mutex '${name}' and the machine-wide lock stayed held for its ` +
+            `whole ${gate.timeoutSec}s budget, so the command was never started. This is a resource ` +
+            'conflict, not a verdict on the work: re-run once the other run finishes, or raise ' +
+            "the gate's timeoutSec.",
+    ].join('\n');
+}
+/** Resolved separately from the acquisition so the message can name it either way. */
+function machineLockPathFor(name) {
+    return (0, machine_lock_1.machineLockPath)(name, (0, machine_lock_1.resolveMachineLockRoot)());
+}
+/**
+ * Run one attempt at a command gate, holding its `mutex` for the duration
+ * (Issue #1771).
+ *
+ * The wait happens *outside* the measured interval: `startedAt`/`durationMs`
+ * come from {@link runCommand} and describe the command alone, so a gate that
+ * queued for 42s and then ran for 190s records 190s and reports the 42s beside
+ * it. Merging them would inflate every duration by however busy the machine was.
+ *
+ * One *attempt*, not one gate, since #1772: a gate declaring `retryOnFail: 1`
+ * calls this twice. The lock is taken and released per attempt rather than held
+ * 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) {
+    const mutex = gate.mutex;
+    if (!mutex) {
+        return runCommand(gate.command, worktreePath, gate.timeoutSec, maxLogTailBytes, gateEnv);
+    }
+    // The gate's own timeout is the wait budget: a gate allowed 600s of execution
+    // has already declared how long this run may spend on it, and a second knob
+    // would only let the two disagree.
+    const lock = await (0, machine_lock_1.acquireMachineLock)(mutex, { timeoutMs: gate.timeoutSec * 1000 });
+    if (!lock.acquired) {
+        const recordedAt = Date.now();
+        return {
+            status: 'skipped',
+            exitCode: null,
+            startedAt: recordedAt,
+            durationMs: 0,
+            logTail: mutexWaitTimeoutLog(gate, mutex, lock),
+        };
+    }
+    try {
+        const outcome = await runCommand(gate.command, worktreePath, gate.timeoutSec, maxLogTailBytes, gateEnv);
+        return {
+            ...outcome,
+            logTail: withMutexMarker(mutex, lock.waitedMs, lock.handle.path, outcome.logTail),
+        };
+    }
+    finally {
+        lock.handle.release();
+    }
+}
+/**
+ * Run one command gate, re-running it once when it fails and the gate asked for
+ * that (Issue #1772).
+ *
+ * A gate that fails on the machine's luck — a random UUID that happens to
+ * contain a forbidden substring, a port that was still in TIME_WAIT — is
+ * indistinguishable in the record from a gate that fails on the work, and
+ * "re-run the one red gate before believing it" has been tribal knowledge
+ * rather than something the runner does. This makes it a declaration.
+ *
+ * Only a `failed` attempt is retried. A `timeout` is not: the gate already
+ * spent its whole budget, and a second attempt would double the wall clock of
+ * exactly the gates whose budgets are largest. A `skipped` (the mutex never
+ * 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) {
+    const first = await runGateAttempt(gate, worktreePath, maxLogTailBytes, gateEnv);
+    if (gate.retryOnFail !== 1 || first.status !== 'failed')
+        return first;
+    const second = await runGateAttempt(gate, worktreePath, maxLogTailBytes, gateEnv);
+    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
+        // the retry's `skipped`/`timeout` instead would turn a gate that judged the
+        // work into a run with no verdict (exit 99), which is strictly weaker.
+        return {
+            ...first,
+            logTail: prefixLogTail(`${exports.FLAKY_LOG_PREFIX} retry reached no verdict (${second.status}); ` +
+                "the first run's result stands. Retry log:\n" +
+                (second.logTail ?? '(no output)'), first.logTail),
+        };
+    }
+    return composeRetriedGate(gate, first, second);
+}
+/**
+ * Fold two runs of one gate into the single row the schema has (Issue #1772).
+ *
+ * `status` and `exitCode` come from the run whose verdict is being reported, so
+ * the row never says `failed` beside `exit=0`: a FLAKY gate counted as a
+ * failure reports the failing run, one counted as a pass reports the passing
+ * one, and a gate that failed twice reports the later failure. `durationMs` is
+ * the sum, because both runs were this gate's own command executing — the same
+ * rule #1771 applied when it kept the lock *wait* out of the number.
+ *
+ * Both runs' numbers reach the terminal through the {@link FLAKY_LOG_PREFIX}
+ * marker, which the CLI reads to print `GATE <id> FLAKY (exit=1,0, 45.0s,44.0s)`.
+ */
+function composeRetriedGate(gate, first, second) {
+    const outcome = second.status === 'passed' ? 'flaky' : 'fail';
+    const passes = outcome === 'flaky' && gate.flakyIsPass === true;
+    const reported = passes ? second : outcome === 'flaky' ? first : second;
+    const marker = `${exports.FLAKY_LOG_PREFIX} runs=${RETRY_TOTAL_RUNS} outcome=${outcome} ` +
+        `exit=${formatExit(first.exitCode)},${formatExit(second.exitCode)} ` +
+        `duration=${formatSeconds(first.durationMs)},${formatSeconds(second.durationMs)} ` +
+        `verdict=${passes ? 'pass' : 'fail'}`;
+    const body = [
+        flakyRunHeader(1, first),
+        first.logTail ?? '',
+        flakyRunHeader(2, second),
+        second.logTail ?? '',
+    ].join('\n');
+    return {
+        status: passes ? 'passed' : 'failed',
+        exitCode: reported.exitCode,
+        // The window opens where the first run opened and closes `durationMs`
+        // later, so #1625's `finished_at - started_at === duration_ms` still holds
+        // and the pair still describes execution rather than the database write.
+        startedAt: first.startedAt,
+        durationMs: first.durationMs + second.durationMs,
+        logTail: `${marker}\n${body}`,
+    };
+}
+/** Put a machine-readable line ahead of a gate's output, keeping both. */
+function prefixLogTail(marker, logTail) {
+    return logTail ? `${marker}\n${logTail}` : marker;
+}
 /** Run a git plumbing command. No shell: every argument here is code-supplied. */
 function runGit(args, cwd) {
     return new Promise((resolve) => {
@@ -483,12 +717,29 @@ function aggregateRunStatus(gateStatuses) {
         return 'error';
     return 'passed';
 }
-async function executeRun(db, runId, worktreePath, config, selection, baseRef, task, detachedContract, envClean) {
+async function executeRun(db, runId, worktreeId, worktreePath, config, selection, baseRef, task, detachedContract, envClean) {
     const { maxLogTailBytes, skipInPrimaryCheckout } = config.options;
     const { runWorkEvidence, gates } = selection;
     // ORed with the repository-wide switch rather than replacing it (#1642): a
     // delegation may tighten the rule, never relax one the repository declared.
     const requireCommit = (0, contract_message_1.resolveRequireCommit)(task?.contract ?? null, config);
+    /**
+     * The per-worktree environment, resolved on first use (#1771).
+     *
+     * Lazy because claiming an index writes to `~/.commandmate/worktree-index`,
+     * and a run that reaches no command gate — work-evidence failed, the primary
+     * checkout guard skipped everything — must leave nothing behind. It also has
+     * to stay behind the env-clean gate below, which lists `~/.commandmate` and
+     * would otherwise diff against a directory this very run had just created.
+     */
+    let gateEnvCache = null;
+    const gateEnv = () => {
+        gateEnvCache ??= {
+            [exports.WORKTREE_ID_ENV]: worktreeId,
+            [exports.WORKTREE_INDEX_ENV]: String((0, worktree_index_1.resolveWorktreeIndex)(worktreeId)),
+        };
+        return gateEnvCache;
+    };
     /**
      * Close an open gate row with the interval its evaluator measured.
      *
@@ -595,7 +846,7 @@ async function executeRun(db, runId, worktreePath, config, selection, baseRef, t
                 'options.skipInPrimaryCheckout is true.').status);
             continue;
         }
-        const outcome = await runGate(gate.id, gate.command, gate.source, () => runCommand(gate.command, worktreePath, gate.timeoutSec, maxLogTailBytes));
+        const outcome = await runGate(gate.id, gate.command, gate.source, () => runCommandGate(gate, worktreePath, maxLogTailBytes, gateEnv()));
         statuses.push(outcome.status);
     }
     return aggregateRunStatus(statuses);
@@ -813,7 +1064,7 @@ async function startVerification(input) {
         await acquireSlot();
         let terminalStatus = 'error';
         try {
-            const status = await executeRun(db, run.id, input.worktreePath, resolvedConfig, resolvedSelection, baseRef, task, detachedContract, envCleanContext);
+            const status = await executeRun(db, run.id, input.worktreeId, input.worktreePath, resolvedConfig, resolvedSelection, baseRef, task, detachedContract, envCleanContext);
             terminalStatus = status;
             (0, db_1.finishVerificationRun)(db, run.id, status);
             return status;