commandmate 0.24.0 → 0.26.0

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

@@ -0,0 +1,204 @@
+"use strict";
+/**
+ * Machine-wide advisory lock for verification gates (Issue #1771).
+ *
+ * A gate that owns a fixed resource — a hard-coded port, a local database, an
+ * emulator — can only run once per machine. Two parallel worktrees running it
+ * at the same time make the second one fail on the resource, and the record
+ * says `GATE e2e FAIL exit=1`, which is indistinguishable from the change being
+ * broken. `mutex: <name>` in verify.yaml declares that constraint, and this
+ * module is what enforces it.
+ *
+ * Three properties decide the implementation:
+ *
+ *   1. **It must hold across processes.** The lock exists because CommandMate's
+ *      runner and the standalone `verify-run.sh` can be started independently
+ *      against the same machine, so an in-process mutex would not be a lock at
+ *      all. The path convention (`~/.commandmate/locks/<name>.lock`) is part of
+ *      the contract, not an implementation detail — see
+ *      docs/design/verification-config.md §9.
+ *   2. **It must be portable.** macOS ships no `flock(1)`, so the primitive is
+ *      `mkdir`, which is atomic on every POSIX filesystem and expressible in
+ *      both bash and Node.
+ *   3. **A crashed holder must not wedge the machine.** The owner record names
+ *      the pid and host, so a lock left behind by a process that no longer
+ *      exists is broken by the next waiter rather than blocking every future
+ *      run until someone deletes a directory by hand.
+ *
+ * Server-only: reads and writes the filesystem.
+ *
+ * @module lib/verification/machine-lock
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_LOCK_POLL_INTERVAL_MS = exports.MACHINE_LOCK_ROOT_ENV = exports.MACHINE_LOCK_DIR_NAME = void 0;
+exports.machineLockPath = machineLockPath;
+exports.defaultMachineLockRoot = defaultMachineLockRoot;
+exports.resolveMachineLockRoot = resolveMachineLockRoot;
+exports.acquireMachineLock = acquireMachineLock;
+const fs_1 = require("fs");
+const os_1 = require("os");
+const path_1 = require("path");
+const crypto_1 = require("crypto");
+const logger_1 = require("../../lib/logger");
+const logger = (0, logger_1.createLogger)('lib/verification/machine-lock');
+/**
+ * Directory under `~/.commandmate` that holds the locks.
+ *
+ * Exported because `env-snapshot` has to know this name: the env-clean gate
+ * lists the entries directly under `~/.commandmate` and would otherwise report
+ * the runner's own bookkeeping as pollution the delegation left behind.
+ */
+exports.MACHINE_LOCK_DIR_NAME = 'locks';
+/**
+ * Override for the lock root.
+ *
+ * Tests must never take a lock under the real `~/.commandmate/locks`: parallel
+ * worktrees on a developer machine share that directory, so a suite that used
+ * it would serialize against — and be failed by — unrelated live runs. Also
+ * useful for isolating a CI runner from a shared home.
+ */
+exports.MACHINE_LOCK_ROOT_ENV = 'CM_VERIFY_LOCK_ROOT';
+/** How often a waiter re-tries the claim. */
+exports.DEFAULT_LOCK_POLL_INTERVAL_MS = 250;
+/** File inside the lock directory naming who holds it. */
+const OWNER_FILE = 'owner';
+/** The convention both runners follow: `<root>/<name>.lock`. */
+function machineLockPath(name, root) {
+    return (0, path_1.join)(root, `${name}.lock`);
+}
+function defaultMachineLockRoot() {
+    return (0, path_1.join)((0, os_1.homedir)(), '.commandmate', exports.MACHINE_LOCK_DIR_NAME);
+}
+function resolveMachineLockRoot(env = process.env) {
+    const override = env[exports.MACHINE_LOCK_ROOT_ENV];
+    return override && override.trim() !== '' ? override : defaultMachineLockRoot();
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function readOwner(lockPath) {
+    try {
+        const parsed = JSON.parse((0, fs_1.readFileSync)((0, path_1.join)(lockPath, OWNER_FILE), 'utf8'));
+        if (typeof parsed.pid !== 'number' || typeof parsed.token !== 'string')
+            return null;
+        return {
+            pid: parsed.pid,
+            host: typeof parsed.host === 'string' ? parsed.host : '',
+            token: parsed.token,
+            acquiredAt: typeof parsed.acquiredAt === 'number' ? parsed.acquiredAt : 0,
+        };
+    }
+    catch {
+        // Either the holder has not written the record yet (it created the
+        // directory microseconds ago) or the file is corrupt. Both mean "held by
+        // someone we cannot identify", which is a reason to wait, never to break.
+        return null;
+    }
+}
+function describeOwner(owner) {
+    return owner ? `pid ${owner.pid} on ${owner.host || 'unknown host'}` : null;
+}
+/**
+ * Whether the recorded holder is gone.
+ *
+ * Only decidable on the machine that wrote the record: a pid from another host
+ * says nothing about a process here, and killing a lock on that guess would let
+ * two machines sharing a network home run the gate at once. Pid reuse can make
+ * a dead holder look alive, which only costs a wait — the safe direction.
+ */
+function isStaleOwner(owner) {
+    if (owner.host !== (0, os_1.hostname)())
+        return false;
+    try {
+        process.kill(owner.pid, 0);
+        return false;
+    }
+    catch (error) {
+        return error.code === 'ESRCH';
+    }
+}
+/** @returns true when this call created the directory and now owns it */
+function claim(lockPath, owner) {
+    try {
+        (0, fs_1.mkdirSync)(lockPath);
+    }
+    catch (error) {
+        if (error.code === 'EEXIST')
+            return false;
+        throw error;
+    }
+    (0, fs_1.writeFileSync)((0, path_1.join)(lockPath, OWNER_FILE), JSON.stringify(owner), { encoding: 'utf8' });
+    return true;
+}
+/** Remove a lock whose recorded holder is gone, but only if it is still that record. */
+function breakStale(lockPath, owner) {
+    const current = readOwner(lockPath);
+    if (!current || current.token !== owner.token)
+        return;
+    try {
+        (0, fs_1.rmSync)(lockPath, { recursive: true, force: true });
+        logger.warn('machine-lock-broken-stale', { lockPath, pid: owner.pid });
+    }
+    catch {
+        // Someone else broke or re-took it first; the next attempt sorts it out.
+    }
+}
+/**
+ * Take the machine-wide lock named `name`, waiting up to `timeoutMs`.
+ *
+ * Never throws for the ordinary "someone else has it" case: the caller has to
+ * report *not acquired* differently from *the gate failed*, and an exception
+ * would collapse the two.
+ */
+async function acquireMachineLock(name, options) {
+    const root = options.root ?? resolveMachineLockRoot();
+    const pollIntervalMs = options.pollIntervalMs ?? exports.DEFAULT_LOCK_POLL_INTERVAL_MS;
+    const lockPath = machineLockPath(name, root);
+    const startedAt = Date.now();
+    const deadline = startedAt + Math.max(0, options.timeoutMs);
+    const token = (0, crypto_1.randomUUID)();
+    (0, fs_1.mkdirSync)(root, { recursive: true });
+    // 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();
+    for (;;) {
+        const owner = { pid: process.pid, host: (0, os_1.hostname)(), token, acquiredAt: Date.now() };
+        if (claim(lockPath, owner)) {
+            return {
+                acquired: true,
+                waitedMs: Date.now() - startedAt,
+                handle: {
+                    name,
+                    path: lockPath,
+                    release: () => {
+                        const current = readOwner(lockPath);
+                        // Ours was broken and re-taken while we ran. Deleting it now would
+                        // evict a live holder.
+                        if (current && current.token !== token)
+                            return;
+                        try {
+                            (0, fs_1.rmSync)(lockPath, { recursive: true, force: true });
+                        }
+                        catch (error) {
+                            logger.warn('machine-lock-release-failed', {
+                                lockPath,
+                                error: error instanceof Error ? error.message : String(error),
+                            });
+                        }
+                    },
+                },
+            };
+        }
+        const holder = readOwner(lockPath);
+        if (holder && !broken.has(holder.token) && isStaleOwner(holder)) {
+            broken.add(holder.token);
+            breakStale(lockPath, holder);
+            continue;
+        }
+        const now = Date.now();
+        if (now >= deadline) {
+            return { acquired: false, waitedMs: now - startedAt, heldBy: describeOwner(holder) };
+        }
+        await sleep(Math.min(pollIntervalMs, deadline - now));
+    }
+}

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

@@ -30,7 +30,7 @@
  * @module lib/verification/scope-gate
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.SCOPE_SKIP_NOT_REQUIRED = exports.SCOPE_SKIP_NO_CONTRACT = exports.ScopeMatcher = exports.CONTRACT_DIR_PREFIX = exports.ALWAYS_ALLOWED_PREFIX = exports.SCOPE_ALLOW_GUIDANCE = exports.MAX_REPORTED_VIOLATIONS = void 0;
+exports.SCOPE_SKIP_NOT_REQUIRED = exports.SCOPE_SKIP_NO_CONTRACT = exports.ScopeMatcher = exports.CONTRACT_DIR_PREFIX = exports.SCOPE_EXEMPT_CONTRACT_PATH = exports.SCOPE_EXEMPT_ALWAYS_ALLOWED = exports.SCOPE_PATTERN_ARROW = exports.ALWAYS_ALLOWED_PREFIX = exports.SCOPE_ALLOW_GUIDANCE = exports.MAX_REPORTED_VIOLATIONS = void 0;
 exports.isContractPath = isContractPath;
 exports.parsePorcelainEntries = parsePorcelainEntries;
 exports.collectChangedPaths = collectChangedPaths;
@@ -71,6 +71,31 @@ exports.SCOPE_ALLOW_GUIDANCE = "To allow this diff, add the paths above to the c
  * this exemption prevents.
  */
 exports.ALWAYS_ALLOWED_PREFIX = '.commandmate/';
+/**
+ * Separator between a reported path and the pattern that decided it (#1841).
+ *
+ * Mirrored by the CLI's scope-evidence parser (`src/cli/commands/verify.ts`,
+ * SCOPE_PATTERN_ARROW): the gate's report is the only carrier for this evidence
+ * — `verification_gate_results` has columns for a status, an exit code and a log
+ * body, and nothing else — so the two constants have to agree. A round-trip
+ * test feeds a real `evaluateScope` report through that parser rather than
+ * trusting the two copies to be edited together.
+ *
+ * A path containing this exact three-character sequence would split wrongly on
+ * the way back. Nothing prevents such a filename; it is accepted because the
+ * alternative — encoding paths in a log a human reads first — costs every
+ * reader something to protect against a file no repository has.
+ */
+exports.SCOPE_PATTERN_ARROW = '  \u2190 ';
+/**
+ * Stand-ins for the two ways a path is admitted without matching `allow`.
+ *
+ * Parenthesised so they cannot be mistaken for a pattern the contract declared:
+ * a reader who greps the contract for `(exempt: .commandmate/)` should find
+ * nothing, because nothing there put it in scope.
+ */
+exports.SCOPE_EXEMPT_ALWAYS_ALLOWED = `(exempt: ${exports.ALWAYS_ALLOWED_PREFIX})`;
+exports.SCOPE_EXEMPT_CONTRACT_PATH = '(exempt: contract path)';
 /**
  * Execution contracts, dropped from both gates' change sets entirely (#1580).
  *
@@ -189,6 +214,9 @@ function hasBalancedBraces(pattern) {
     }
     return depth === 0;
 }
+function compilePattern(pattern) {
+    return { pattern, regexp: globToRegExp(pattern) };
+}
 /**
  * A scope declaration compiled once per run.
  *
@@ -205,20 +233,43 @@ class ScopeMatcher {
      */
     constructor(scope, contractPath = null) {
         this.contractPath = contractPath;
-        this.allow = scope.allow.map(globToRegExp);
-        this.deny = scope.deny.map(globToRegExp);
+        this.allow = scope.allow.map(compilePattern);
+        this.deny = scope.deny.map(compilePattern);
     }
     /**
-     * Whether `path` is a scope violation.
+     * Which declared rule decided `path`, and which way (#1841).
+     *
+     * The **first** matching pattern is reported, in the contract's declaration
+     * order, on both sides. Reporting the last would name a rule the reader
+     * cannot use: `allow: ["src/**", "src/lib/**"]` admits `src/lib/a.ts` under
+     * the first entry, and deleting the second changes nothing about the verdict.
      *
      * `path` is a repository-root-relative POSIX path as git reports it.
      */
+    classify(path) {
+        const denied = this.deny.find((entry) => entry.regexp.test(path));
+        if (denied)
+            return { admitted: false, pattern: denied.pattern };
+        if (path.startsWith(exports.ALWAYS_ALLOWED_PREFIX)) {
+            return { admitted: true, pattern: exports.SCOPE_EXEMPT_ALWAYS_ALLOWED };
+        }
+        if (path === this.contractPath) {
+            return { admitted: true, pattern: exports.SCOPE_EXEMPT_CONTRACT_PATH };
+        }
+        const allowed = this.allow.find((entry) => entry.regexp.test(path));
+        return allowed
+            ? { admitted: true, pattern: allowed.pattern }
+            : { admitted: false, pattern: null };
+    }
+    /**
+     * Whether `path` is a scope violation.
+     *
+     * Delegates to {@link classify} rather than repeating the rules: the verdict
+     * and the evidence for it must never be able to disagree, and two copies of
+     * "deny wins, then the exemptions, then allow" is exactly how they would.
+     */
     isViolation(path) {
-        if (this.deny.some((pattern) => pattern.test(path)))
-            return true;
-        if (path.startsWith(exports.ALWAYS_ALLOWED_PREFIX) || path === this.contractPath)
-            return false;
-        return !this.allow.some((pattern) => pattern.test(path));
+        return !this.classify(path).admitted;
     }
 }
 exports.ScopeMatcher = ScopeMatcher;
@@ -328,6 +379,45 @@ async function collectChangedPaths(worktreePath, baseRef) {
 function formatPatterns(patterns) {
     return patterns.length > 0 ? patterns.join(', ') : '(none)';
 }
+/**
+ * One reported path, optionally naming the rule that decided it (#1841).
+ *
+ * Admitted paths lead with `+` rather than `-` so the two sections cannot be
+ * confused by a reader — or by a grep — that has only one line in front of it.
+ */
+function formatDecidedPath(marker, path, pattern) {
+    if (pattern === null)
+        return `  ${marker} ${path}`;
+    return `  ${marker} ${path}${exports.SCOPE_PATTERN_ARROW}${pattern}`;
+}
+/**
+ * The `admitted:` section: what this run was allowed to change, and by which
+ * rule (#1841).
+ *
+ * With an `allow` of exact paths the pattern *is* the file and this adds
+ * nothing, but #1546 made globs legal, and `src/**` leaves no record of what it
+ * actually covered on the day it ran. The contract is the claim; this is the
+ * evidence for it, and it has to survive in `log_tail` because the run's own
+ * working tree will have moved on by the time anyone asks.
+ *
+ * Capped by the same rule as the violations, for the same reason (log_tail is
+ * stored per gate in SQLite), and the truncation is stated rather than silent —
+ * a list that stops at 100 with no marker reads as a complete one.
+ */
+function formatAdmitted(admitted) {
+    if (admitted.length === 0)
+        return [];
+    const listed = admitted.slice(0, exports.MAX_REPORTED_VIOLATIONS);
+    const remainder = admitted.length - listed.length;
+    return [
+        'admitted:',
+        ...listed.map((entry) => formatDecidedPath('+', entry.path, entry.pattern)),
+        // Worded `(+N more)` rather than the violations' `... and N more`: the two
+        // sections are capped independently and a reader scanning a truncated
+        // report should not have to work out which count belongs to which list.
+        ...(remainder > 0 ? [`  ... (+${remainder} more)`] : []),
+    ];
+}
 /**
  * Reasons the gate has nothing to judge, phrased for `log_tail`.
  *
@@ -381,9 +471,28 @@ async function evaluateScope(worktreePath, scope, requireScopeClean, baseRef, co
     if ('error' in changed)
         return done('error', `scope: ${changed.error}`, null);
     const matcher = new ScopeMatcher(scope, contractPath);
-    const violations = changed.paths.filter((path) => matcher.isViolation(path));
-    const summary = `scope: baseRef=${baseRef} changed=${changed.paths.length} violations=${violations.length}\n` +
-        `allow: ${formatPatterns(scope.allow)}\ndeny: ${formatPatterns(scope.deny)}`;
+    // Every changed path is classified, whether or not it will fit in the report:
+    // the cap below is a display rule, and a violation withheld from the listing
+    // still counts toward the verdict.
+    const admitted = [];
+    const violations = [];
+    const rejectedBy = new Map();
+    for (const path of changed.paths) {
+        const decision = matcher.classify(path);
+        if (decision.admitted) {
+            admitted.push({ path, pattern: decision.pattern });
+            continue;
+        }
+        violations.push(path);
+        if (decision.pattern !== null)
+            rejectedBy.set(path, decision.pattern);
+    }
+    const summary = [
+        `scope: baseRef=${baseRef} changed=${changed.paths.length} violations=${violations.length}`,
+        `allow: ${formatPatterns(scope.allow)}`,
+        `deny: ${formatPatterns(scope.deny)}`,
+        ...formatAdmitted(admitted),
+    ].join('\n');
     if (violations.length === 0) {
         // An empty change set passes: work-evidence is the gate that judges "nothing
         // happened", and failing here too would report one problem as two.
@@ -394,7 +503,11 @@ async function evaluateScope(worktreePath, scope, requireScopeClean, baseRef, co
     const report = [
         summary,
         'out of scope:',
-        ...listed.map((path) => `  - ${path}`),
+        // A deny match is named inline: the `deny:` line above lists what the
+        // contract declared, not which of those entries this path tripped, and a
+        // violation the reader must revert reads differently from one they could
+        // fix by widening `allow`.
+        ...listed.map((path) => formatDecidedPath('-', path, rejectedBy.get(path) ?? null)),
         ...(remainder > 0 ? [`  ... and ${remainder} more`] : []),
         exports.SCOPE_ALLOW_GUIDANCE,
     ].join('\n');

package/dist/server/src/lib/verification/verify-config.js

@@ -8,7 +8,7 @@
  * Server-only: reads from disk, so import this from API routes / CLI only.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.VerifyConfigError = exports.GATE_ID_PATTERN = exports.DEFAULT_MAX_LOG_TAIL_BYTES = exports.DEFAULT_TIMEOUT_SEC = exports.VERIFY_CONFIG_RELATIVE_PATH = exports.RESERVED_GATE_IDS = exports.ENV_CLEAN_GATE_ID = exports.SCOPE_GATE_ID = exports.WORK_EVIDENCE_GATE_ID = void 0;
+exports.VerifyConfigError = exports.MAX_RETRY_ON_FAIL = exports.MAX_GATE_MUTEX_LENGTH = exports.GATE_MUTEX_PATTERN = exports.GATE_ID_PATTERN = exports.DEFAULT_MAX_LOG_TAIL_BYTES = exports.DEFAULT_TIMEOUT_SEC = exports.VERIFY_CONFIG_RELATIVE_PATH = exports.RESERVED_GATE_IDS = exports.ENV_CLEAN_GATE_ID = exports.SCOPE_GATE_ID = exports.WORK_EVIDENCE_GATE_ID = void 0;
 exports.validateGateEntries = validateGateEntries;
 exports.loadVerifyConfig = loadVerifyConfig;
 const fs_1 = require("fs");
@@ -56,8 +56,29 @@ const MAX_LOG_TAIL_BYTES = 1048576;
  * runner refuses to resolve is a completion criterion nothing can evaluate.
  */
 exports.GATE_ID_PATTERN = /^[a-z0-9][a-z0-9-]{0,31}$/;
+/**
+ * Shape a `mutex` name may take (Issue #1771).
+ *
+ * Wider than {@link GATE_ID_PATTERN} because a mutex names a *resource*, not a
+ * gate: two repositories that both bind port 60303 should be able to agree on
+ * `port.60303` and be serialized against each other. Narrow enough that the
+ * name is safe as a path segment — no separator, no whitespace, nothing a shell
+ * re-interprets — because both runners turn it into
+ * `~/.commandmate/locks/<name>.lock`.
+ */
+exports.GATE_MUTEX_PATTERN = /^[A-Za-z0-9_.-]+$/;
+/** Keeps the lock directory name inside every filesystem's limit. */
+exports.MAX_GATE_MUTEX_LENGTH = 64;
+/**
+ * Largest `retryOnFail` a gate may declare (Issue #1772).
+ *
+ * Deliberately 1, and deliberately a named constant rather than a literal in
+ * one `if`: the ceiling is the feature. A gate that may re-run until it passes
+ * reports the machine's luck, not the work.
+ */
+exports.MAX_RETRY_ON_FAIL = 1;
 const TOP_LEVEL_KEYS = ['version', 'gates', 'options'];
-const GATE_KEYS = ['id', 'command', 'timeoutSec'];
+const GATE_KEYS = ['id', 'command', 'timeoutSec', 'mutex', 'retryOnFail', 'flakyIsPass'];
 const OPTION_KEYS = [
     'baseRef',
     'skipInPrimaryCheckout',
@@ -186,8 +207,69 @@ function validateGateEntry(entry, at, seenIds, gates, issues) {
             timeoutSec = parsed;
         }
     }
+    let mutex;
+    if (entry.mutex !== undefined) {
+        if (typeof entry.mutex !== 'string' || entry.mutex === '') {
+            issues.push(`${at}.mutex: must be a non-empty string (got ${describe(entry.mutex)})`);
+        }
+        else if (entry.mutex.length > exports.MAX_GATE_MUTEX_LENGTH) {
+            issues.push(`${at}.mutex: must be at most ${exports.MAX_GATE_MUTEX_LENGTH} characters (got ${entry.mutex.length})`);
+        }
+        else if (!exports.GATE_MUTEX_PATTERN.test(entry.mutex)) {
+            issues.push(`${at}.mutex: "${entry.mutex}" must match ${exports.GATE_MUTEX_PATTERN.source}`);
+        }
+        else {
+            mutex = entry.mutex;
+        }
+    }
+    let retryOnFail;
+    if (entry.retryOnFail !== undefined) {
+        const parsed = asInteger(entry.retryOnFail);
+        if (parsed === null) {
+            issues.push(`${at}.retryOnFail: must be an integer (got ${describe(entry.retryOnFail)})`);
+        }
+        else if (parsed < 0 || parsed > exports.MAX_RETRY_ON_FAIL) {
+            // Not "at most N": the range is the contract. See MAX_RETRY_ON_FAIL.
+            issues.push(`${at}.retryOnFail: must be 0 or ${exports.MAX_RETRY_ON_FAIL} (got ${parsed})`);
+        }
+        else {
+            retryOnFail = parsed;
+        }
+    }
+    let flakyIsPass;
+    if (entry.flakyIsPass !== undefined) {
+        const parsed = asBoolean(entry.flakyIsPass);
+        if (parsed === null) {
+            issues.push(`${at}.flakyIsPass: must be true or false (got ${describe(entry.flakyIsPass)})`);
+        }
+        else if (parsed && retryOnFail !== exports.MAX_RETRY_ON_FAIL) {
+            // A knob that can never fire is a config bug, not a preference: without a
+            // retry the gate has no FLAKY outcome for this to reclassify, so the
+            // declaration reads as "flakes are tolerated here" while changing nothing.
+            issues.push(`${at}.flakyIsPass: true requires retryOnFail: ${exports.MAX_RETRY_ON_FAIL} ` +
+                '(without a retry a gate can never be FLAKY)');
+        }
+        else {
+            flakyIsPass = parsed;
+        }
+    }
     if (issues.length === issuesBefore) {
-        gates.push({ id: entry.id, command: entry.command, timeoutSec });
+        const gate = {
+            id: entry.id,
+            command: entry.command,
+            timeoutSec,
+        };
+        // Only set when declared: an explicit `mutex: undefined` would serialize
+        // into a contract's stored JSON as a key, and "declared without a value"
+        // is not a state this field has. The same holds for the #1772 pair, whose
+        // absence has to keep meaning "this gate runs exactly once".
+        if (mutex !== undefined)
+            gate.mutex = mutex;
+        if (retryOnFail !== undefined)
+            gate.retryOnFail = retryOnFail;
+        if (flakyIsPass !== undefined)
+            gate.flakyIsPass = flakyIsPass;
+        gates.push(gate);
     }
 }
 function validateGates(value, issues) {

package/dist/server/src/lib/verification/worktree-index.js

@@ -0,0 +1,140 @@
+"use strict";
+/**
+ * A small, stable integer per worktree, handed to gates as `CM_WORKTREE_INDEX`
+ * (Issue #1771).
+ *
+ * The point is to let a repository *remove* the collision rather than serialize
+ * around it: a gate written as `E2E_PORT=$((60400+CM_WORKTREE_INDEX)) npm run
+ * test:e2e` gives every worktree its own port, so N parallel worktrees keep N-way
+ * parallelism. `mutex:` is the fallback for resources that cannot be
+ * parameterized at all; this is the one that preserves throughput.
+ *
+ * **CommandMate does not number worktrees.** The Issue assumed it did; it does
+ * not. `worktrees.id` is a TEXT primary key derived from the directory basename
+ * (`src/lib/git/worktree-id.ts:73`), the table has no ordinal column and no
+ * creation timestamp (`src/lib/db/migrations/v01-v05-initial-schema.ts:104`),
+ * and the only ordering any query applies is `updated_at DESC`
+ * (`src/lib/db/worktree-db.ts:113`), which reorders itself every time an agent
+ * writes a message. So the number is minted here, and the requirement it has to
+ * meet is stated rather than inherited:
+ *
+ *   - **Same worktree, same number.** The assignment is persisted, so it
+ *     survives restarts, re-registration and database resets.
+ *   - **No two live worktrees share a number.** The claim is an `O_EXCL` file
+ *     create, which is atomic, so two processes racing for the same slot cannot
+ *     both win it.
+ *
+ * A hash of the worktree id would have satisfied only the first: 30 worktrees
+ * over 1024 slots collide about 35% of the time, and a collision here is exactly
+ * the port clash the feature exists to remove. It is kept only as the fallback
+ * for a machine where the registry cannot be written at all, because a gate
+ * expanding `$((60400+CM_WORKTREE_INDEX))` with the variable unset would give
+ * *every* worktree port 60400.
+ *
+ * Layout: `~/.commandmate/worktree-index/<n>` is a file whose content is the
+ * worktree id that owns `n`. Deleting a worktree leaves its slot claimed, which
+ * is deliberate — reusing it would move a live worktree's number.
+ *
+ * Server-only: reads and writes the filesystem.
+ *
+ * @module lib/verification/worktree-index
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MAX_WORKTREE_INDEX = exports.WORKTREE_INDEX_ROOT_ENV = exports.WORKTREE_INDEX_DIR_NAME = void 0;
+exports.defaultWorktreeIndexRoot = defaultWorktreeIndexRoot;
+exports.resolveWorktreeIndexRoot = resolveWorktreeIndexRoot;
+exports.hashWorktreeIndex = hashWorktreeIndex;
+exports.resolveWorktreeIndex = resolveWorktreeIndex;
+const crypto_1 = require("crypto");
+const fs_1 = require("fs");
+const os_1 = require("os");
+const path_1 = require("path");
+const logger_1 = require("../../lib/logger");
+const logger = (0, logger_1.createLogger)('lib/verification/worktree-index');
+/**
+ * Directory under `~/.commandmate` holding the registry.
+ *
+ * Exported for the same reason as {@link MACHINE_LOCK_DIR_NAME}: env-clean
+ * lists `~/.commandmate` and must not read the runner's own bookkeeping as
+ * something the delegation left behind.
+ */
+exports.WORKTREE_INDEX_DIR_NAME = 'worktree-index';
+/** Override for the registry root; tests and isolated runners use it. */
+exports.WORKTREE_INDEX_ROOT_ENV = 'CM_VERIFY_WORKTREE_INDEX_ROOT';
+/**
+ * Highest index the registry hands out.
+ *
+ * Also the modulus of the fallback hash, so both paths produce a number a
+ * repository can add to a port base without leaving the ephemeral range.
+ */
+exports.MAX_WORKTREE_INDEX = 1024;
+function defaultWorktreeIndexRoot() {
+    return (0, path_1.join)((0, os_1.homedir)(), '.commandmate', exports.WORKTREE_INDEX_DIR_NAME);
+}
+function resolveWorktreeIndexRoot(env = process.env) {
+    const override = env[exports.WORKTREE_INDEX_ROOT_ENV];
+    return override && override.trim() !== '' ? override : defaultWorktreeIndexRoot();
+}
+/** Last-resort number for a machine whose registry cannot be written. */
+function hashWorktreeIndex(worktreeId) {
+    const digest = (0, crypto_1.createHash)('sha256').update(worktreeId).digest('hex').slice(0, 8);
+    return Number.parseInt(digest, 16) % exports.MAX_WORKTREE_INDEX;
+}
+function readSlotOwner(root, slot) {
+    try {
+        return (0, fs_1.readFileSync)((0, path_1.join)(root, slot), 'utf8').trim();
+    }
+    catch {
+        return null;
+    }
+}
+function claimSlot(root, index, worktreeId) {
+    try {
+        (0, fs_1.writeFileSync)((0, path_1.join)(root, String(index)), `${worktreeId}\n`, { encoding: 'utf8', flag: 'wx' });
+        return true;
+    }
+    catch (error) {
+        if (error.code !== 'EEXIST')
+            throw error;
+        // Lost the race — unless the winner is us, which happens when two runners
+        // for the same worktree start together on different processes.
+        return readSlotOwner(root, String(index)) === worktreeId;
+    }
+}
+/**
+ * The index for `worktreeId`, claiming one if it has none yet.
+ *
+ * @param root registry directory; defaults to {@link resolveWorktreeIndexRoot}
+ * @returns a number in `[0, MAX_WORKTREE_INDEX)`; never throws
+ */
+function resolveWorktreeIndex(worktreeId, options = {}) {
+    const root = options.root ?? resolveWorktreeIndexRoot();
+    try {
+        (0, fs_1.mkdirSync)(root, { recursive: true });
+        const taken = new Set();
+        for (const name of (0, fs_1.readdirSync)(root)) {
+            if (!/^\d+$/.test(name))
+                continue;
+            if (readSlotOwner(root, name) === worktreeId)
+                return Number(name);
+            taken.add(Number(name));
+        }
+        for (let index = 0; index < exports.MAX_WORKTREE_INDEX; index++) {
+            if (taken.has(index))
+                continue;
+            if (claimSlot(root, index, worktreeId))
+                return index;
+        }
+        logger.warn('worktree-index-exhausted', { worktreeId, root });
+    }
+    catch (error) {
+        logger.warn('worktree-index-unavailable', {
+            worktreeId,
+            root,
+            error: error instanceof Error ? error.message : String(error),
+        });
+    }
+    // Deterministic, so a machine stuck on the fallback still gives each worktree
+    // the *same* number every run — it just cannot promise they are all distinct.
+    return hashWorktreeIndex(worktreeId);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "commandmate",
-  "version": "0.24.0",
+  "version": "0.26.0",
   "description": "A local control plane for agent CLIs — orchestration and visibility for Claude Code, Codex, Gemini CLI, and more across Git worktrees",
   "keywords": [
     "claude-code",