commandmate 0.49.2 → 0.50.0

package/dist/server/src/lib/test-run-detection.js

@@ -0,0 +1,53 @@
+"use strict";
+/**
+ * Is this process a test run? The one rule, for everything that must behave
+ * differently under test (Issue #4097; the rule itself is from #4086).
+ *
+ * It lives apart from the database on purpose: `db-instance` imports
+ * `agent-session-cost-sampler`, and `session-generation-archive` is reached by
+ * suites that mock `db-instance` down to a single export. This module imports
+ * nothing, so all three can read it without changing either graph.
+ *
+ * A test that needs a production branch mocks {@link isUnderTest}. Clearing
+ * `VITEST` does nothing here, and there is no flag that switches the guards off
+ * in production.
+ *
+ * @module lib/test-run-detection
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isInsideVitestWorker = isInsideVitestWorker;
+exports.isUnderTest = isUnderTest;
+/**
+ * Is this code running inside a Vitest worker?
+ *
+ * Read off the worker state Vitest itself installs on `globalThis` (its
+ * `getWorkerState()` reads the same `__vitest_worker__` global, in the forks
+ * and threads pools alike), not off environment variables: the environment is
+ * both inherited and editable. A test may swap `NODE_ENV` to `production`
+ * mid-run (tests/unit/pwa/ServiceWorkerRegistrar.test.tsx does) and must stay
+ * guarded, while a child process started outside Vitest inherits `VITEST` and
+ * must not be taken for a test run.
+ */
+function isInsideVitestWorker() {
+    const state = globalThis.__vitest_worker__;
+    return typeof state === 'object' && state !== null;
+}
+/**
+ * Is this a test run?
+ *
+ * Inside a Vitest worker: always, whatever `NODE_ENV` says right now.
+ * Outside one: only with `NODE_ENV=test` (a test's own child process, which
+ * also inherits the per-process CM_DB_PATH). `VITEST` alone never counts —
+ * the daemon spreads `process.env` into the server it starts
+ * (src/cli/utils/daemon.ts buildChildEnv), so a `NODE_ENV=production` server
+ * started from a shell where `VITEST` was left behind is a real server.
+ *
+ * @param env - defaults to `process.env`
+ * @param inVitestWorker - defaults to {@link isInsideVitestWorker}; a test
+ *   passes `false` to ask how a process outside Vitest would be judged
+ */
+function isUnderTest(env = process.env, inVitestWorker = isInsideVitestWorker()) {
+    if (inVitestWorker)
+        return true;
+    return (env.NODE_ENV ?? '').trim() === 'test';
+}

package/dist/server/src/lib/tmux/read-mode.js

@@ -117,6 +117,10 @@ const POPUP_HEIGHT = '85%';
  * Always under `~/.commandmate/`, never the install directory and never the cwd:
  * `bind-key` is server-global and long-lived, so the path it names has to outlive
  * a `npx` cache eviction or a `cd`.
+ *
+ * Not moved by `CM_TMUX_SCRIPT_DIR`. `session-hook-scripts.ts` `AUTO_POPUP_SCRIPT`
+ * spells the same location for `sh` as `$HOME/.commandmate/bin/…` (Issue #4191);
+ * change both together.
  */
 function getPagerScriptPath() {
     return (0, path_1.join)((0, os_1.homedir)(), '.commandmate', 'bin', read_mode_pager_1.PAGER_SCRIPT_FILENAME);

package/dist/server/src/lib/tmux/session-hook-scripts.js

@@ -31,7 +31,7 @@
  * also runnable by hand and because a session can be renamed.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.AUTO_POPUP_SCRIPT = exports.LIVE_DELEGATE_SCRIPT = exports.LIVE_RESTORE_SCRIPT = exports.AUTO_POPUP_SCRIPT_FILENAME = exports.LIVE_DELEGATE_SCRIPT_FILENAME = exports.LIVE_RESTORE_SCRIPT_FILENAME = void 0;
+exports.AUTO_POPUP_SCRIPT = exports.LIVE_DELEGATE_SCRIPT = exports.LIVE_RESTORE_SCRIPT = exports.AUTO_POPUP_SCRIPT_FILENAME = exports.LIVE_DELEGATE_SCRIPT_FILENAME = exports.LIVE_RESTORE_SCRIPT_FILENAME = exports.SCRIPT_DIR_ENV = void 0;
 exports.getScriptDir = getScriptDir;
 exports.getScriptPath = getScriptPath;
 exports.materializeScript = materializeScript;
@@ -44,6 +44,27 @@ const path_1 = require("path");
 const tmux_pane_config_1 = require("../../config/tmux-pane-config");
 const tmux_session_surface_1 = require("../session/tmux-session-surface");
 const read_mode_pager_1 = require("./read-mode-pager");
+const safe_directory_1 = require("../../config/safe-directory");
+/**
+ * Moves {@link getScriptDir} off `~/.commandmate/bin` (Issue #4176).
+ *
+ * `ensureSessionHooks` materializes these scripts whenever the live-attach or
+ * auto-popup option is on, and a unit test that turns one on would otherwise
+ * read and rewrite the scripts the running server's tmux hooks execute.
+ * `tests/setup.ts` pins it to a temporary directory. Unset, the directory is the
+ * one it has always been. The auto-popup script still looks for the pager at
+ * `$HOME/.commandmate/bin`, where `read-mode.ts` writes it.
+ *
+ * A relative value is made absolute against this process's working directory
+ * when it is read. The scripts are written there anyway (`fs` resolves a
+ * relative path the same way), and the path recorded in the tmux hook has to
+ * be that same file: tmux runs a hook's command from its own working directory,
+ * not this process's, so a relative path in the hook would name another file or
+ * none. Rejecting the value instead would send the scripts back to
+ * `~/.commandmate/bin`, which is what the variable exists to avoid. The
+ * `/proc` check runs on the absolute form, so `../../proc/x` is refused too.
+ */
+exports.SCRIPT_DIR_ENV = 'CM_TMUX_SCRIPT_DIR';
 /** Basename of the Phase D geometry-restore script. */
 exports.LIVE_RESTORE_SCRIPT_FILENAME = 'cm-live-restore.sh';
 /** Basename of the Phase D geometry-delegation script. */
@@ -174,6 +195,13 @@ tmux set-window-option -t "=$SESSION:" window-size latest 2>/dev/null || true
  * then the control-mode test below keeps it from firing for CommandMate's own
  * transport — a popup opened on a control client would be a popup nobody can
  * see and nobody can close.
+ *
+ * The pager path below is `read-mode.ts` `getPagerScriptPath()` written for `sh`
+ * (Issue #4191): the same `~/.commandmate/bin/<PAGER_SCRIPT_FILENAME>`, from the
+ * hook's `$HOME` rather than `homedir()`. Kept as two spellings on purpose: this
+ * text runs in the tmux server's shell, not here, and the pager is not moved by
+ * {@link SCRIPT_DIR_ENV} (it is `bind-key`'s target too). Change both together;
+ * `tests/unit/lib/tmux/pager-script-location-4191.test.ts` holds them equal.
  */
 exports.AUTO_POPUP_SCRIPT = `#!/bin/sh
 # CommandMate auto read popup (Issue #2317) — generated file, edits are overwritten.
@@ -206,16 +234,20 @@ else
   tmux display-popup -w 90% -h 85% -E "sh \\"$PAGER_SCRIPT\\" --follow \\"$SESSION\\"" 2>/dev/null || true
 fi
 `;
-/** Directory every materialized CommandMate script lives in. */
+/**
+ * Directory every materialized CommandMate script lives in, always absolute:
+ * `~/.commandmate/bin` unless {@link SCRIPT_DIR_ENV} names another.
+ */
 function getScriptDir() {
-    return (0, path_1.join)((0, os_1.homedir)(), '.commandmate', 'bin');
+    const fallback = (0, path_1.join)((0, os_1.homedir)(), '.commandmate', 'bin');
+    return (0, safe_directory_1.resolveSafeAbsoluteDirectory)(process.env[exports.SCRIPT_DIR_ENV]?.trim(), fallback, exports.SCRIPT_DIR_ENV);
 }
 /** Absolute path of a materialized script. */
 function getScriptPath(filename) {
     return (0, path_1.join)(getScriptDir(), filename);
 }
 /**
- * Write a script to `~/.commandmate/bin/<filename>` if its content changed.
+ * Write a script to `<getScriptDir()>/<filename>` if its content changed.
  *
  * Idempotent by content comparison so a restart does not churn the file's mtime,
  * and re-executable after a `chmod` accident because the mode is re-applied —

package/dist/server/src/lib/tui-accumulator.js

@@ -40,21 +40,28 @@ function normalizeOpenCodeLine(line) {
 }
 /**
  * Extract meaningful content lines from raw TUI output.
- * Strips ANSI codes, box-drawing characters, and lines matching OPENCODE_SKIP_PATTERNS.
+ * Strips ANSI codes, box-drawing characters, and lines matching `skipPatterns`.
+ *
+ * Issue #4188: the skip list is the caller's, because the rows arrive here with
+ * no position. The default (`OPENCODE_SKIP_PATTERNS`) drops the rows only the
+ * chrome draws by their words. The poller passes `OPENCODE_TRANSCRIPT_SKIP_PATTERNS`
+ * when the rows it hands over were cut above the located chrome
+ * (`sliceOpenCodeTurnWithSkip`), so a reply quoting those rows keeps them.
  *
  * @param rawOutput - Raw tmux capture-pane output
+ * @param skipPatterns - Rows to drop; defaults to `OPENCODE_SKIP_PATTERNS`
  * @returns Array of cleaned, non-empty content lines
  *
  * @internal Exported for unit testing
  */
-function extractTuiContentLines(rawOutput) {
+function extractTuiContentLines(rawOutput, skipPatterns = cli_patterns_1.OPENCODE_SKIP_PATTERNS) {
     const lines = rawOutput.split('\n');
     const contentLines = [];
     for (const line of lines) {
         const cleaned = normalizeOpenCodeLine(line);
         if (!cleaned)
             continue;
-        const shouldSkip = cli_patterns_1.OPENCODE_SKIP_PATTERNS.some(pattern => pattern.test(cleaned));
+        const shouldSkip = skipPatterns.some(pattern => pattern.test(cleaned));
         if (shouldSkip)
             continue;
         // Also skip the Build summary line (completion indicator)
@@ -224,16 +231,18 @@ function initTuiAccumulator(pollerKey) {
  * @param pollerKey - Poller key ("worktreeId:cliToolId")
  * @param rawOutput - Raw tmux capture-pane output
  * @param cliToolId - CLI tool identifier (default: 'opencode' for backward compatibility)
+ * @param openCodeSkipPatterns - The skip list for an opencode capture (Issue #4188);
+ *   defaults to `OPENCODE_SKIP_PATTERNS`. Ignored for copilot.
  *
  * @internal Exported for unit testing
  */
-function accumulateTuiContent(pollerKey, rawOutput, cliToolId = 'opencode') {
+function accumulateTuiContent(pollerKey, rawOutput, cliToolId = 'opencode', openCodeSkipPatterns = cli_patterns_1.OPENCODE_SKIP_PATTERNS) {
     const state = tuiResponseAccumulator.get(pollerKey);
     if (!state)
         return;
     const contentLines = cliToolId === 'copilot'
         ? extractCopilotContentLines(rawOutput)
-        : extractTuiContentLines(rawOutput);
+        : extractTuiContentLines(rawOutput, openCodeSkipPatterns);
     if (contentLines.length === 0)
         return;
     state.pollCount++;

package/dist/server/src/lib/verification/env-clean-gate.js

@@ -38,6 +38,8 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.ENV_CLEAN_GUIDANCE = exports.MAX_REPORTED_ENV_CHANGES = exports.isLivePid = exports.readLivePidCwd = exports.REQUIRE_ENV_CLEAN_SOURCE_CONTRACT = exports.REQUIRE_ENV_CLEAN_SOURCE_CONFIG = void 0;
 exports.resolveRequireEnvClean = resolveRequireEnvClean;
 exports.attributeSessionName = attributeSessionName;
+exports.readSiblingWorktreeIds = readSiblingWorktreeIds;
+exports.defaultOtherWorktreeProbe = defaultOtherWorktreeProbe;
 exports.attributeAnchor = attributeAnchor;
 exports.isZcompdumpEntry = isZcompdumpEntry;
 exports.demoVitestPid = demoVitestPid;
@@ -62,6 +64,7 @@ const fs_1 = require("fs");
 const path_1 = require("path");
 const db_instance_1 = require("../../lib/db/db-instance");
 const worktree_db_1 = require("../../lib/db/worktree-db");
+const worktree_id_1 = require("../../lib/git/worktree-id");
 const session_name_1 = require("../../lib/cli-tools/session-name");
 const types_1 = require("../../lib/cli-tools/types");
 const env_snapshot_1 = require("./env-snapshot");
@@ -115,20 +118,116 @@ function resolveRequireEnvClean(contract, config) {
  * session to this task, and a session this task's agent started in any
  * server's namespace is still this task's addition.
  *
- * Ambiguity resolves towards `self` on purpose. Worktree ids may contain
- * hyphens, so `mcbd-claude-foo-bar` is genuinely ambiguous between worktree
- * `foo` with suffix `bar` and worktree `foo-bar`; calling it `self` makes an
- * addition a violation, and being wrong in that direction costs a false report
- * rather than a missed leak.
+ * Worktree ids may contain hyphens, so `mcbd-claude-foo-bar` is genuinely
+ * ambiguous by name between worktree `foo` with instance suffix `bar` and
+ * worktree `foo-bar`. The rule (Issue #4192):
+ *
+ *   - tail equal to the task's id — `self`;
+ *   - tail not starting with `<id>-` — `other`;
+ *   - tail `<id>-…` — `other` only when `isOtherWorktree` positively says some
+ *     hyphen-boundary prefix of the tail longer than `<id>` (the whole tail
+ *     included) is another worktree: `commandmate-issue-4175-v2` when that
+ *     worktree exists next to, or is registered beside, `commandmate-issue-4175`.
+ *     Otherwise `self`: `-codex-2`, `-2`, a named instance.
+ *
+ * Without that evidence the ambiguity still resolves towards `self` on purpose:
+ * calling it `self` makes an addition a violation, and being wrong in that
+ * direction costs a false report rather than a missed leak. The evidence wins
+ * over the instance reading because it is a fact about the machine (a real
+ * worktree with exactly that id), where the instance reading is only a shape
+ * every name has. The cost, accepted: an instance of this worktree whose suffix
+ * begins with the rest of a live sibling's id (`foo` instance `v2` beside a
+ * worktree `foo-v2`) is excused as that sibling's.
  */
-function attributeSessionName(name, worktreeId) {
+function attributeSessionName(name, worktreeId, isOtherWorktree) {
     const parsed = (0, session_name_1.parseSessionName)(name);
     if (!parsed)
         return 'unattributed';
     const tail = parsed.rest;
-    if (tail === worktreeId || tail.startsWith(`${worktreeId}-`))
+    if (tail === worktreeId)
         return 'self';
-    return 'other';
+    if (!tail.startsWith(`${worktreeId}-`))
+        return 'other';
+    if (isOtherWorktree && longerWorktreeIds(tail, worktreeId).some((id) => askProbe(isOtherWorktree, id))) {
+        return 'other';
+    }
+    return 'self';
+}
+/** Hyphen-boundary prefixes of `tail` longer than `worktreeId`, the whole tail last. */
+function longerWorktreeIds(tail, worktreeId) {
+    const ids = [];
+    let end = tail.indexOf('-', worktreeId.length + 1);
+    while (end !== -1) {
+        ids.push(tail.slice(0, end));
+        end = tail.indexOf('-', end + 1);
+    }
+    ids.push(tail);
+    return ids;
+}
+function askProbe(probe, id) {
+    try {
+        return probe(id) === true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Ids of the git worktrees next to `worktreePath` (#4192): its sibling
+ * directories that carry a `.git` entry, minted the way `deriveWorktreeId`
+ * mints a first registration (sanitized basename). Never throws.
+ */
+function readSiblingWorktreeIds(worktreePath) {
+    const worktree = (0, path_1.resolve)(worktreePath);
+    const parent = (0, path_1.dirname)(worktree);
+    const own = (0, path_1.basename)(worktree);
+    const ids = new Set();
+    try {
+        for (const entry of (0, fs_1.readdirSync)(parent, { withFileTypes: true })) {
+            if (!entry.isDirectory() || entry.name === own)
+                continue;
+            if (!(0, fs_1.existsSync)((0, path_1.join)(parent, entry.name, '.git')))
+                continue;
+            const id = (0, worktree_id_1.sanitizeIdSegment)(entry.name);
+            if (id)
+                ids.add(id);
+        }
+    }
+    catch {
+        // An unreadable parent is no evidence of anything.
+    }
+    return ids;
+}
+/**
+ * The evidence {@link evaluateEnvClean} judges `<id>-…` session names by
+ * (#4192), read at verification — the sibling worktree is usually created
+ * after the baseline, so the baseline cannot know it:
+ *
+ *   - a sibling directory of the task's worktree that is a git worktree with
+ *     exactly that id (no database needed; a worktree not yet synced counts);
+ *   - otherwise a row of this server's worktree table with that id and a path
+ *     other than the task's (covers the collision-suffixed ids a basename
+ *     cannot reproduce).
+ *
+ * The session is `self` again only when both are gone — the sibling directory
+ * and its row in this server's worktree table (removing the directory without
+ * a sync leaves the row, which still counts as evidence) — the strict direction.
+ */
+function defaultOtherWorktreeProbe(worktreePath, lookupRegisteredPath = (worktreeId) => (0, worktree_db_1.getWorktreeById)((0, db_instance_1.getDbInstance)(), worktreeId)?.path ?? null) {
+    let siblings = null;
+    const own = (0, path_1.resolve)(worktreePath);
+    return (candidateId) => {
+        siblings ??= readSiblingWorktreeIds(worktreePath);
+        if (siblings.has(candidateId))
+            return true;
+        try {
+            const path = lookupRegisteredPath(candidateId);
+            return path !== null && path !== '' && (0, path_1.resolve)(path) !== own;
+        }
+        catch {
+            return false;
+        }
+    };
 }
 /**
  * Attribute a listening process by the directory it runs in.
@@ -252,7 +351,7 @@ function attributeHomeEntry(name, worktreePath, resolvePidCwd = exports.readLive
 function attributeEntry(probeId, entry, context, resolvePidCwd) {
     switch (probeId) {
         case 'tmux-sessions':
-            return attributeSessionName(entry.key, context.worktreeId);
+            return attributeSessionName(entry.key, context.worktreeId, context.isOtherWorktree);
         case 'listeners':
             return attributeAnchor(entry.anchor, context.worktreePath);
         case 'home-entries':
@@ -489,7 +588,8 @@ function recordOtherRepositorySessions(snapshot, taskWorktreeId, server) {
     return sessions.entries
         .map((entry) => entry.key)
         .filter((name) => {
-        if (attributeSessionName(name, taskWorktreeId) !== 'other')
+        const isOtherWorktree = (id) => server.repositoryOf?.(id) != null;
+        if (attributeSessionName(name, taskWorktreeId, isOtherWorktree) !== 'other')
             return false;
         if (isOtherServerSession(name, server))
             return false;
@@ -567,7 +667,7 @@ function isKillByAnotherWorker(record, context, taskSession) {
         ? 'unattributed'
         : taskSession && record.callerSession === taskSession
             ? 'self'
-            : attributeSessionName(record.callerSession, context.worktreeId);
+            : attributeSessionName(record.callerSession, context.worktreeId, context.isOtherWorktree);
     const cwdOwner = attributeAnchor(record.callerCwd, context.worktreePath);
     if (sessionOwner === 'self' || cwdOwner === 'self')
         return false;
@@ -990,7 +1090,12 @@ async function evaluateEnvClean(input) {
         // An unreadable ledger excuses nothing; it is not a reason to withhold a verdict.
         sessionKills = [];
     }
-    const diff = diffEnvSnapshots(input.baseline, final, input, {
+    const context = {
+        worktreeId: input.worktreeId,
+        worktreePath: input.worktreePath,
+        isOtherWorktree: input.isOtherWorktree ?? defaultOtherWorktreeProbe(input.worktreePath),
+    };
+    const diff = diffEnvSnapshots(input.baseline, final, context, {
         ignoreHomeEntries: input.ignoreHomeEntries,
         resolvePidCwd: input.resolvePidCwd,
         sessionKills,

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

@@ -288,7 +288,7 @@ function releaseSlot() {
  *
  * 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
+ * the gate's whole wait budget, `mutexWaitSec` or else `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
@@ -673,9 +673,9 @@ function mutexWaitTimeoutLog(gate, name, result) {
         `${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.",
+            `whole ${(0, verify_config_1.mutexWaitBudgetSec)(gate)}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 ${gate.mutexWaitSec === undefined ? 'timeoutSec (or declare mutexWaitSec)' : 'mutexWaitSec'}.`,
     ].join('\n');
 }
 /** Resolved separately from the acquisition so the message can name it either way. */
@@ -701,9 +701,10 @@ async function runGateAttempt(gate, worktreePath, maxLogTailBytes, gateEnv, canc
     if (!mutex) {
         return runCommand(gate.command, worktreePath, gate.timeoutSec, maxLogTailBytes, gateEnv, cancellation);
     }
-    // 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.
+    // The wait budget is `mutexWaitSec`, or the gate's own timeout when it declares
+    // none (Issue #4162; docs/orchestrate/exit-codes.md, 3-4 99). The queue length
+    // and the hang limit are separate facts about a gate, but no key still means
+    // the single budget every gate had before.
     //
     // Issue #2063: the wait is abandonable. `build` declares 1800s here, so a run
     // cancelled while queued behind the lock used to stay `running` for up to
@@ -714,7 +715,7 @@ async function runGateAttempt(gate, worktreePath, maxLogTailBytes, gateEnv, canc
     // 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,
+        timeoutMs: (0, verify_config_1.mutexWaitBudgetSec)(gate) * 1000,
         shouldAbandon: () => cancellation.cancelled,
         onWait: () => slot.release(),
     });

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

@@ -8,8 +8,9 @@
  * Server-only: reads from disk, so import this from API routes / CLI only.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.VerifyConfigError = exports.MAX_ENV_CLEAN_IGNORE_HOME_ENTRIES = 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.VerifyConfigError = exports.MAX_MUTEX_WAIT_SEC = exports.MAX_ENV_CLEAN_IGNORE_HOME_ENTRIES = 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.defaultPlannedGateIds = defaultPlannedGateIds;
+exports.mutexWaitBudgetSec = mutexWaitBudgetSec;
 exports.validateGateEntries = validateGateEntries;
 exports.loadVerifyConfig = loadVerifyConfig;
 const fs_1 = require("fs");
@@ -115,8 +116,18 @@ exports.MAX_RETRY_ON_FAIL = 1;
  * this long is already a repository papering over a machine it should fix.
  */
 exports.MAX_ENV_CLEAN_IGNORE_HOME_ENTRIES = 32;
+/**
+ * Longest `mutexWaitSec` a gate may declare (Issue #4162): above `timeoutSec`'s
+ * ceiling on purpose, because a queue of several slow gates is longer than any
+ * one of them. A day is past any queue worth waiting behind.
+ */
+exports.MAX_MUTEX_WAIT_SEC = 86400;
+/** The lock-wait budget of a gate, in seconds: `mutexWaitSec`, or `timeoutSec` when absent (Issue #4162). */
+function mutexWaitBudgetSec(gate) {
+    return gate.mutexWaitSec ?? gate.timeoutSec;
+}
 const TOP_LEVEL_KEYS = ['version', 'gates', 'options'];
-const GATE_KEYS = ['id', 'command', 'timeoutSec', 'mutex', 'retryOnFail', 'flakyIsPass'];
+const GATE_KEYS = ['id', 'command', 'timeoutSec', 'mutex', 'mutexWaitSec', 'retryOnFail', 'flakyIsPass'];
 const OPTION_KEYS = [
     'baseRef',
     'skipInPrimaryCheckout',
@@ -261,6 +272,23 @@ function validateGateEntry(entry, at, seenIds, gates, issues) {
             mutex = entry.mutex;
         }
     }
+    let mutexWaitSec;
+    if (entry.mutexWaitSec !== undefined) {
+        const parsed = asInteger(entry.mutexWaitSec);
+        if (parsed === null) {
+            issues.push(`${at}.mutexWaitSec: must be an integer (got ${describe(entry.mutexWaitSec)})`);
+        }
+        else if (parsed < MIN_TIMEOUT_SEC || parsed > exports.MAX_MUTEX_WAIT_SEC) {
+            issues.push(`${at}.mutexWaitSec: must be ${MIN_TIMEOUT_SEC}..${exports.MAX_MUTEX_WAIT_SEC} (got ${parsed})`);
+        }
+        else if (entry.mutex === undefined) {
+            // A knob that can never fire is a config bug, as with flakyIsPass below.
+            issues.push(`${at}.mutexWaitSec: requires mutex (without a lock there is no wait)`);
+        }
+        else {
+            mutexWaitSec = parsed;
+        }
+    }
     let retryOnFail;
     if (entry.retryOnFail !== undefined) {
         const parsed = asInteger(entry.retryOnFail);
@@ -304,6 +332,8 @@ function validateGateEntry(entry, at, seenIds, gates, issues) {
         // absence has to keep meaning "this gate runs exactly once".
         if (mutex !== undefined)
             gate.mutex = mutex;
+        if (mutexWaitSec !== undefined)
+            gate.mutexWaitSec = mutexWaitSec;
         if (retryOnFail !== undefined)
             gate.retryOnFail = retryOnFail;
         if (flakyIsPass !== undefined)

package/dist/server/src/types/agent-roles.js

@@ -0,0 +1,56 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EXPECTED_ROLE_NAME_HEADER = exports.INSTANCE_CREATION_KEY_PATTERN = exports.INSTANCE_CREATION_KEY_HEADER = exports.AGENT_ROLE_ANTIGRAVITY_ENABLED_ENV_VAR = exports.AGENT_ROLE_CLI_TOOLS = exports.MAX_ROLE_NAME_LENGTH = exports.MAX_ROLE_BODY_BYTES = void 0;
+exports.isAgentRoleCliTool = isAgentRoleCliTool;
+exports.isAgentRoleAdapterEnabled = isAgentRoleAdapterEnabled;
+exports.agentRoleReplacesDefaultInstructions = agentRoleReplacesDefaultInstructions;
+/** Largest body, in UTF-8 bytes. Applied to the body, never to a composed artifact (§5). */
+exports.MAX_ROLE_BODY_BYTES = 16384;
+/** Longest role name, in UTF-16 code units. The name reaches no file name or command line. */
+exports.MAX_ROLE_NAME_LENGTH = 64;
+/** The tools a role can be given to (D3). Gemini and vibe-local are out of scope. */
+exports.AGENT_ROLE_CLI_TOOLS = [
+    'claude',
+    'codex',
+    'command-code',
+    'opencode',
+    'opencode-v2',
+    'copilot',
+    'antigravity',
+];
+function isAgentRoleCliTool(value) {
+    return typeof value === 'string' && exports.AGENT_ROLE_CLI_TOOLS.includes(value);
+}
+/** Turns Antigravity's adapter on, once its check under a dedicated OS user has passed (§6.6). */
+exports.AGENT_ROLE_ANTIGRAVITY_ENABLED_ENV_VAR = 'CM_AGENT_ROLE_ANTIGRAVITY_ENABLED';
+/**
+ * Whether a launch may apply a role through this tool's adapter yet. Antigravity
+ * can hold settings and its adapter is built, but stays off until the check under
+ * a dedicated OS user has passed (D3). A role resolved for a tool that is off
+ * refuses the launch; it never starts without it.
+ */
+function isAgentRoleAdapterEnabled(tool) {
+    if (tool !== 'antigravity')
+        return true;
+    return typeof process !== 'undefined' && process.env?.[exports.AGENT_ROLE_ANTIGRAVITY_ENABLED_ENV_VAR] === '1';
+}
+/**
+ * Whether a role through this tool replaces its default instructions instead of
+ * adding to them: OpenCode V2 overrides the agent's `system`, which removes the
+ * provider's base prompt (§7.2). The API says so, so a client can.
+ */
+function agentRoleReplacesDefaultInstructions(tool) {
+    return tool === 'opencode-v2';
+}
+/**
+ * Carries a key on a create or a roster PATCH (#4132): a client makes one per request. A
+ * condition about the request rather than part of what is written, so the body is the same
+ * with or without it.
+ */
+exports.INSTANCE_CREATION_KEY_HEADER = 'Idempotency-Key';
+exports.INSTANCE_CREATION_KEY_PATTERN = /^[A-Za-z0-9_-]{16,128}$/;
+/**
+ * Carries the name a rename replaces (#4132), URI-encoded since a name need not be ASCII.
+ * A condition as well: the body of an edit stays only what the edit changes.
+ */
+exports.EXPECTED_ROLE_NAME_HEADER = 'X-Expected-Role-Name';