commandmate 0.33.2 → 0.34.0

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

@@ -42,14 +42,26 @@ 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 session_generation_archive_1 = require("../../lib/session/session-generation-archive");
 const logger_1 = require("../../lib/logger");
 const logger = (0, logger_1.createLogger)('lib/session/agent-session-lifecycle');
 /**
- * Open a new event generation for an agent instance that is about to start.
+ * Open a new event generation for an agent instance that is about to start,
+ * and retire the previous process's chat history (Issue #2444).
  *
  * Safe to call for a tool that emits nothing: the fence is a timestamp, and a
  * tool with no events simply never has any to fence.
  *
+ * The archive rides here rather than in its own seam because this function is
+ * already the answer to "a new agent process is being created for this
+ * (worktree, instance)" — the one fact that distinguishes a replacement from a
+ * reconnect, and the fact `chat_messages.archived` needs. See
+ * `lib/session/session-generation-archive` for why observing the *death*
+ * instead would archive live conversations. Note that the boundary is this call
+ * and not the adoption mark: codex's and opencode's relaunch paths run
+ * `reconcileExistingSession`, which sets an adoption mark, so a reader of that
+ * mark would miss exactly the endings this exists for.
+ *
  * @param target - The instance being created
  * @param at - Epoch ms; defaults to now
  */
@@ -70,6 +82,24 @@ function beginAgentSession(target, at = Date.now()) {
         // learn by noticing their `respond` no longer has anything to answer.
         decisionsEvicted: after - before,
     });
+    // Issue #2444: the rows the replaced process wrote are a previous session's
+    // history now. Inside a `try` and after the fence on purpose — this module
+    // otherwise touches nothing but memory, and a database that is missing,
+    // locked or mid-migration must cost a log line, never a session that refuses
+    // to start. It is also a no-op by construction wherever there is no database
+    // to reach (see `resolveSessionArchiveDatabase`), which is what keeps the
+    // suites that call this with tmux mocked and no DB at all unchanged.
+    try {
+        (0, session_generation_archive_1.archiveSupersededSessionMessages)(target);
+    }
+    catch (error) {
+        logger.warn('session-generation-archive-failed', {
+            worktreeId: target.worktreeId,
+            cliToolId: target.cliToolId,
+            instanceId: target.instanceId ?? target.cliToolId,
+            error: error instanceof Error ? error.message : String(error),
+        });
+    }
 }
 /**
  * The command that starts this agent, with whatever config it needs written

package/dist/server/src/lib/session/ask-user-question-prompt.js

@@ -100,9 +100,11 @@ function corresponds(a, b) {
  * Containment rather than the prefix rule the labels use, because the two are
  * extracted differently. An option label is a parsed line; the question is
  * whatever the detector's upward scan swept together, and on a real capture that
- * is several lines glued into one — the canary frame yields
+ * was several lines glued into one — before Issue #2486 the canary frame yielded
  * `"⏺ I'll load the TaskCreate tool schema first. ☐ First task Which task would
- * you like to start with?"` for a question that is only its last clause.
+ * you like to start with?"` for a question that is only its last clause. The
+ * picker's tab row now caps that scan, but the scan still reads at most a few
+ * rows, so a long question arrives cut and containment is still the right test.
  *
  * The floor stops a short question ("Continue?") from matching unrelated prose;
  * the uniqueness requirement in {@link matchAskUserQuestion} does the rest. On

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

@@ -106,7 +106,7 @@ function truncateOutput(output) {
  * - vibe-local: [-p <message> -y] or [--model <model> -p <message> -y]
  * - opencode: run --format json [-m <model>] [--agent <a>] [--variant <v>] [-c] [--title <t>] <message>
  * - antigravity: -p <message> --dangerously-skip-permissions
- * - command-code: -p <message> --output-format json [--yolo | --permission-mode <permission>]
+ * - command-code: -p <message> --output-format json [--yolo | --permission-mode <permission>] --no-auto-update
  * - others: -p <message> (fallback)
  *
  * @param message - Prompt message
@@ -201,13 +201,44 @@ function buildCliArgs(message, cliToolId, permission, options) {
             // `--yolo` does not override `.commandcode/settings.json`
             // `permissions.deny`; a denied tool call still ends the run with exit 4,
             // which {@link describeCommandCodeExit} names in the failure reason.
+            //
+            // ## Issue #2454: `yolo` is a Permission *column* value, and the default
+            //
+            // Every `--permission-mode` value leaves print mode read-only. The 1.53.0
+            // bundle injects a `print-permission-gate` mod whenever `--yolo` was not
+            // passed, and that mod answers `edit_file` / `write_file` /
+            // `shell_command` / `monitor_command` / `kill_shell` with `block: true`;
+            // the mode flag never reaches it. A blocked call does not fail the run —
+            // it ends exit 0 with `subtype: "success"` — so a schedule that asked for
+            // `default` looked successful and changed nothing.
+            //
+            // So the column now spells `--yolo` as the value `yolo`
+            // ({@link COMMAND_CODE_SCHEDULE_PERMISSIONS}, copilot's shape), and the
+            // parser fills an empty cell with it. The `else` below used to be the
+            // only way to reach `--yolo` and was unreachable from a schedule, because
+            // `DEFAULT_PERMISSIONS['command-code']` was `'default'`.
             const args = ['-p', message, '--output-format', 'json'];
-            if (schedule_config_1.COMMAND_CODE_PERMISSIONS.includes(permission)) {
+            if (permission === schedule_config_1.COMMAND_CODE_YOLO_PERMISSION) {
+                args.push('--yolo');
+            }
+            else if (schedule_config_1.COMMAND_CODE_PERMISSIONS.includes(permission)) {
                 args.push('--permission-mode', permission);
             }
             else {
+                // Not reachable through the parser (it falls back to `yolo`); this is
+                // the direct-call guard.
                 args.push('--yolo');
             }
+            // Issue #2454: without this, `resolveCliStartupPlan` runs an update check
+            // and a background self-update on every scheduled run. Spelled as a
+            // literal for the same reason `getCommandForTool` spells `commandcode` as
+            // one — importing `COMMAND_CODE_LAUNCH_FLAGS` from
+            // `@/lib/cli-tools/command-code` would pull the tmux transport into the
+            // scheduler's dependency graph. The unit test imports both and asserts
+            // the spelling matches, so the copy cannot drift. `--trust` /
+            // `--skip-onboarding` are *not* copied: print mode dispatches before the
+            // TUI's trust and onboarding gates, so they have nothing to answer.
+            args.push('--no-auto-update');
             return args;
         }
         case 'antigravity':

package/dist/server/src/lib/session/resolve-session-target.js

@@ -27,9 +27,12 @@
  *
  * The roster outranks the explicit request because it is the user-maintained
  * declaration of what a named instance is; a contradiction is reported rather
- * than silently resolved. Callers decide what to do with it: routes with a side
- * effect answer 400, read-only routes answer 200 and surface the conflict in
- * the payload (design §4 D5 / DR3-015).
+ * than silently resolved. A tool-named instance id is a declaration too — the
+ * id `codex` says which agent it is — so with no roster row an explicit request
+ * for another tool is reported against the primary anchor the same way (Issue
+ * #2487). Callers decide what to do with it: routes with a side effect answer
+ * 400, read-only routes answer 200 and surface the conflict in the payload
+ * (design §4 D5 / DR3-015).
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.INSTANCE_TOOL_CONFLICT = exports.DEFAULT_SESSION_CLI_TOOL = void 0;
@@ -61,7 +64,8 @@ exports.INSTANCE_TOOL_CONFLICT = 'instance_tool_conflict';
  * @param db - Database instance
  * @param worktreeId - Worktree ID (already canonicalized and validated)
  * @param options - Targeting signals carried by the request
- * @returns The resolved target, with `conflict` set when the request contradicts the roster
+ * @returns The resolved target, with `conflict` set when the request contradicts
+ *   the roster or the primary-instance anchor
  */
 function resolveSessionTarget(db, worktreeId, options = {}) {
     const { instanceId, requestedCliTool } = options;
@@ -94,9 +98,27 @@ function resolveSessionTarget(db, worktreeId, options = {}) {
         }
         return target;
     }
-    // The roster does not know this instance (the ad-hoc `send --instance <new-id>`
-    // flow), so an explicit tool is the only declaration there is.
+    // The roster does not know this instance, so for an ad-hoc id (the
+    // `send --instance <new-id>` flow) an explicit tool is the only declaration
+    // there is. A tool-named id declares itself (#868, below), and a request for
+    // a different tool contradicts that exactly as it would a roster row (Issue
+    // #2487). Taking the request instead started `mcbd-<requested>-<wt>-<id>`, a
+    // session nothing that names the id alone ever reads: `ask --instance
+    // antigravity --agent command-code` sent there, then waited on agy.
     if (requestedCliTool) {
+        if ((0, types_1.isCliToolType)(instanceId) && requestedCliTool !== instanceId) {
+            return {
+                cliToolId: instanceId,
+                instanceId,
+                resolvedBy: 'primary',
+                conflict: {
+                    instanceId,
+                    rosterCliTool: instanceId,
+                    requestedCliTool,
+                    primaryAnchor: true,
+                },
+            };
+        }
         return { cliToolId: requestedCliTool, instanceId, resolvedBy: 'explicit' };
     }
     // #868: an instance id that names a CLI tool *is* that tool's primary
@@ -145,11 +167,17 @@ function resolveSessionTargetStrict(db, worktreeId, options = {}) {
     return { ok: true, target };
 }
 /**
- * The sentence shown to a human when the roster and the request disagree.
- * Names both declarations and the three ways out, because the operator has to
- * pick which one is wrong.
+ * The sentence shown to a human when the instance's declaration and the
+ * request disagree. Names both declarations and the three ways out, because the
+ * operator has to pick which one is wrong. A primary-anchor conflict has no
+ * roster entry to update, so its third way out is another instance.
  */
 function describeSessionTargetConflict(conflict) {
+    if (conflict.primaryAnchor) {
+        return (`Agent instance '${conflict.instanceId}' is the primary instance of ${conflict.rosterCliTool}, `
+            + `but ${conflict.requestedCliTool} was requested. `
+            + `Omit the agent, pass ${conflict.rosterCliTool}, or target a ${conflict.requestedCliTool} instance instead.`);
+    }
     return (`Agent instance '${conflict.instanceId}' is registered as ${conflict.rosterCliTool}, `
         + `but ${conflict.requestedCliTool} was requested. `
         + `Omit the agent, pass ${conflict.rosterCliTool}, or update the instance's roster entry.`);

package/dist/server/src/lib/session/session-generation-archive.js

@@ -0,0 +1,194 @@
+"use strict";
+/**
+ * Retire the previous process's chat history when a new one takes its place
+ * (Issue #2444).
+ *
+ * `chat_messages.archived` means "a previous session's history", and until this
+ * module the only thing that ever wrote it was
+ * `POST /api/worktrees/:id/kill-session`. That covers the one ending nobody
+ * actually gets: a session killed *through CommandMate*. A tmux server that
+ * went away, a CLI that was `/exit`ed back to its shell, a machine that
+ * rebooted — none of those pass through that route, so the dead session's rows
+ * stayed `archived = 0` and the chat surface kept showing them as the current
+ * conversation. Worse, the route refuses to help afterwards: with no live
+ * session left to kill it returns 404 *before* reaching the archive call, so
+ * the rows could not be retired by hand either.
+ *
+ * ## Why the seam is "a new process starts", not "the old one died"
+ *
+ * Observing the death is the tempting place — `current-output-builder`'s
+ * `!running` branch already knows — and it is the wrong one. `isRunning` is a
+ * `has-session` probe with a timeout in front of it and a liquid status
+ * verdict behind it; a single slow probe reads as `false` for a session that is
+ * very much alive, and archiving there would throw away a live conversation.
+ * "A new agent process is being created for this (worktree, instance)" is not a
+ * judgement call: {@link beginAgentSession} is called on exactly that fact, on
+ * every tool's creation path and on codex's / opencode's relaunch-into-the-same-pane
+ * path (#2070), and deliberately NOT on opencode's live-reuse path, where the
+ * process is the same process. The rows that belong to the process being
+ * replaced are precisely the ones to retire.
+ *
+ * ## Why it is its own module
+ *
+ * `agent-session-lifecycle` is an in-memory fence and nothing else — no
+ * database, no sockets — and every `src/lib/cli-tools/<tool>.ts` imports it.
+ * Keeping the database and the WebSocket here means that graph does not change:
+ * the lifecycle module calls one function, inside a `try`, and a failure to
+ * archive is a logged warning rather than a session that refuses to start.
+ *
+ * ## Known limitation
+ *
+ * A transcript reader that INSERTs a *new* row for the previous session after
+ * this has run writes it with `archived = 0`, so it lands in the new session's
+ * history. Updates to rows that already exist are unaffected: no writer touches
+ * `archived` on update. Measured as rare enough to leave alone — the readers
+ * run behind the same `startSession` that triggers this — and it is recorded
+ * here rather than guarded, because guarding it means a second notion of "which
+ * generation is this row from" and that is the schema #168 rejected.
+ *
+ * @module lib/session/session-generation-archive
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveSessionArchiveDatabase = resolveSessionArchiveDatabase;
+exports.archiveSupersededSessionMessages = archiveSupersededSessionMessages;
+const db_instance_1 = require("../../lib/db/db-instance");
+const chat_db_1 = require("../../lib/db/chat-db");
+const types_1 = require("../../lib/realtime/types");
+const logger_1 = require("../../lib/logger");
+const logger = (0, logger_1.createLogger)('lib/session/session-generation-archive');
+/**
+ * The database this module archives through, or `null` when there is none to
+ * archive through.
+ *
+ * `getDbInstance()` **creates** a database when the file is not there yet, and
+ * that is the one thing this call must never do from here. Every production
+ * caller arrives via an API route that has already opened the connection, so
+ * the singleton is warm and this is a map lookup. A Vitest worker is the
+ * opposite case: `beginAgentSession` is reached by a dozen suites that mock
+ * tmux and never touch a database, and opening one for them would either
+ * fabricate `<cwd>/data/cm.db` or — when the suite runs in a checkout that has
+ * one — hand those fixtures the developer's real chat history to write into.
+ *
+ * So under Vitest the answer is "no database" unless a test hands one in
+ * explicitly (see {@link archiveSupersededSessionMessages}'s `db` parameter) or
+ * mocks `@/lib/db/db-instance` **and** clears `VITEST`, which is how the
+ * integration test drives the production branch. Only `VITEST` is consulted,
+ * never `NODE_ENV`: `vitest.config.ts` `define`s `process.env.NODE_ENV` to the
+ * literal `'test'` at transform time, so a `NODE_ENV` check here would fold to
+ * a constant and no test could ever reach the other branch.
+ */
+function resolveSessionArchiveDatabase() {
+    if (process.env.VITEST)
+        return null;
+    return (0, db_instance_1.getDbInstance)();
+}
+/**
+ * Archive the active chat rows of the process being replaced.
+ *
+ * Scoped to one `(worktreeId, instanceId)` pair, which is what makes a restart
+ * of `codex` leave `codex-2`'s conversation alone — the two share a worktree and
+ * a tool id and nothing else. Already-archived rows are not touched (the SQL
+ * filters on `archived = 0`), so calling this twice is not two generations.
+ *
+ * Nothing happens when there was nothing to archive: no `recomputeLastUserMessage`
+ * (the sidebar's value cannot have changed) and no frame on the wire (a client
+ * asked to re-read identical history would just be paying for a round trip).
+ * That is also what keeps a healthy-reuse `startSession` — the path that never
+ * calls in here at all — indistinguishable from a first-ever launch.
+ *
+ * Throws whatever the database throws; the caller in `agent-session-lifecycle`
+ * catches, because failing to retire old rows must not stop a session from
+ * starting.
+ *
+ * @param target - The instance whose previous process is being replaced
+ * @param db - The database to write through; defaults to
+ *   {@link resolveSessionArchiveDatabase}
+ * @returns The row count and the instance it was scoped to
+ */
+function archiveSupersededSessionMessages(target, db = resolveSessionArchiveDatabase()) {
+    const instanceId = target.instanceId ?? target.cliToolId;
+    if (!db)
+        return { archived: 0, instanceId };
+    const archived = (0, chat_db_1.deleteMessagesByInstance)(db, target.worktreeId, instanceId);
+    if (archived === 0)
+        return { archived: 0, instanceId };
+    // Same pairing `kill-session` uses: the sidebar's `last_user_message` is
+    // derived from the *active* rows, so archiving without recomputing leaves it
+    // quoting a conversation the surface no longer shows.
+    (0, chat_db_1.recomputeLastUserMessage)(db, target.worktreeId);
+    logger.info('session-generation-archived', {
+        worktreeId: target.worktreeId,
+        cliToolId: target.cliToolId,
+        instanceId,
+        archived,
+    });
+    broadcastMessagesInvalidated(target.worktreeId, target.cliToolId, instanceId);
+    return { archived, instanceId };
+}
+/**
+ * Tell every open pane for this instance to re-read its history.
+ *
+ * A scope rather than a payload, for the reason `MESSAGES_INVALIDATED_EVENT_TYPE`
+ * gives: an archive has no row to publish — `message` / `message_updated` can
+ * only ever say what a row now *looks like* — so the settled state has to come
+ * from the server. PC split panes and the phone both listen through
+ * `useSplitMessages`, which matches on (worktreeId, cliToolId, instanceId) and
+ * does not branch on `reason`.
+ *
+ * Detached, and the `ws-server` import is dynamic, for the same bargain
+ * `broadcastRecordedRow` in `current-output-builder` strikes: this module sits
+ * in the import graph of every `src/lib/cli-tools/<tool>.ts` (through
+ * `agent-session-lifecycle`), and none of them should pull the WebSocket server
+ * in just by starting a pane. The rows are already committed when this runs, so
+ * a socket write that throws cannot turn a completed archive into a failure.
+ */
+function broadcastMessagesInvalidated(worktreeId, cliToolId, instanceId) {
+    void Promise.resolve().then(() => __importStar(require('../../lib/ws-server'))).then(({ broadcastMessage }) => {
+        broadcastMessage(types_1.MESSAGES_INVALIDATED_EVENT_TYPE, {
+            worktreeId,
+            cliToolId,
+            instanceId,
+            reason: 'session_generation',
+        });
+    })
+        .catch((error) => {
+        logger.warn('session-generation-invalidate-broadcast-failed', {
+            worktreeId,
+            instanceId,
+            error: error instanceof Error ? error.message : String(error),
+        });
+    });
+}

package/dist/server/src/lib/tasks/contract-message.js

@@ -15,14 +15,16 @@
  * @module lib/tasks/contract-message
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.REQUIRE_COMMIT_SOURCE_CONTRACT = exports.REQUIRE_COMMIT_SOURCE_CONFIG = void 0;
+exports.BUILT_IN_GATE_ORDER = exports.REQUIRE_COMMIT_SOURCE_CONTRACT = exports.REQUIRE_COMMIT_SOURCE_CONFIG = void 0;
 exports.resolveRequireCommit = resolveRequireCommit;
 exports.resolveContractGateIds = resolveContractGateIds;
+exports.runsEnvCleanGate = runsEnvCleanGate;
 exports.contractGateDefinitions = contractGateDefinitions;
 exports.validateContractAgainstVerifyConfig = validateContractAgainstVerifyConfig;
 exports.resolveGateCommands = resolveGateCommands;
 exports.composeContractMessage = composeContractMessage;
 const verify_config_1 = require("../../lib/verification/verify-config");
+const env_clean_gate_1 = require("../../lib/verification/env-clean-gate");
 /**
  * How the built-in gates read in the preamble; they run git plumbing, not shell
  * commands.
@@ -35,6 +37,14 @@ const verify_config_1 = require("../../lib/verification/verify-config");
 const WORK_EVIDENCE_ANY_CHANGE_LABEL = `${verify_config_1.WORK_EVIDENCE_GATE_ID}（commit または未 commit の変更が存在すること）`;
 const WORK_EVIDENCE_COMMIT_LABEL = `${verify_config_1.WORK_EVIDENCE_GATE_ID}（commit が存在すること。未 commit の変更は作業証跡として数えない）`;
 const SCOPE_LABEL = `${verify_config_1.SCOPE_GATE_ID}（変更ファイルが scope.allow の内側に収まっていること）`;
+/**
+ * `env-clean` reads the machine, not the repository, so the preamble has to say
+ * so (#2442). Without this row the gate would run — and could fail the run —
+ * without ever having been named in the completion criterion the agent was sent,
+ * which is the same "declared and never checked" defect pointed the other way.
+ */
+const ENV_CLEAN_LABEL = `${verify_config_1.ENV_CLEAN_GATE_ID}（タスク開始時に在ったポート・tmux セッション・$HOME / ~/.commandmate ` +
+    '直下のエントリが、増えても減っても不合格）';
 /** The obligation line, in the two forms the pipeline can actually enforce. */
 const COMMIT_REQUIRED_LINE = '- 作業完了後は必ず commit すること（未 commit の作業は未完了とみなされる）';
 const COMMIT_EXPECTED_LINE = '- 作業完了後は commit すること（ただし work-evidence は未 commit の変更も作業証跡として' +
@@ -63,6 +73,18 @@ function resolveRequireCommit(contract, config) {
         sources.push(exports.REQUIRE_COMMIT_SOURCE_CONTRACT);
     return { required: sources.length > 0, sources };
 }
+/**
+ * The built-in gates, in the order `gate-runner` runs them.
+ *
+ * Named once because two things have to agree with it: the resolved gate id list
+ * below and the preamble's command list. A contract that typed
+ * `gates: [lint, env-clean]` must still be told the order the run will take.
+ */
+exports.BUILT_IN_GATE_ORDER = [
+    verify_config_1.WORK_EVIDENCE_GATE_ID,
+    verify_config_1.SCOPE_GATE_ID,
+    verify_config_1.ENV_CLEAN_GATE_ID,
+];
 /**
  * The gate ids a contract asks for, or null for "every gate".
  *
@@ -70,24 +92,54 @@ function resolveRequireCommit(contract, config) {
  * gates run. A contract that required work evidence or a clean scope while
  * listing only `[lint, unit]` would otherwise declare rules that nothing
  * checked: the flags would read as enforced and the gates would never run.
+ *
+ * `env-clean` joined that rule in #2442. Only the contract's own half is visible
+ * here — `options.requireEnvClean` lives in verify.yaml, which this function does
+ * not take — so callers that hold a config OR the two together;
+ * `selectGates` in gate-runner already does, and so does
+ * {@link resolveGateCommands} for the sentence the agent reads.
  */
 function resolveContractGateIds(contract) {
     const gates = contract.verify.gates;
     if (!gates)
         return null;
-    const builtIns = [
+    const required = new Map([
         [verify_config_1.WORK_EVIDENCE_GATE_ID, contract.success.requireWorkEvidence],
         [verify_config_1.SCOPE_GATE_ID, contract.success.requireScopeClean],
-    ];
+        [verify_config_1.ENV_CLEAN_GATE_ID, contract.success.requireEnvClean],
+    ]);
     // Built-ins are listed first and in their execution order even when the
     // contract already named one, so the resolved list reads as the order the run
     // will actually take rather than the order the contract happened to type.
-    const selected = builtIns
-        .filter(([id, required]) => required || gates.includes(id))
-        .map(([id]) => id);
-    const rest = gates.filter((id) => !builtIns.some(([builtIn]) => builtIn === id));
+    const selected = exports.BUILT_IN_GATE_ORDER.filter((id) => required.get(id) === true || gates.includes(id));
+    const rest = gates.filter((id) => !exports.BUILT_IN_GATE_ORDER.includes(id));
     return [...selected, ...rest];
 }
+/**
+ * Whether a verification run for this contract will include `env-clean` (#2442).
+ *
+ * Three declarations can put the gate in a run and the baseline has to be
+ * recorded for all three, because the snapshot is taken once — at send — and
+ * cannot be reconstructed later:
+ *
+ *   1. `options.requireEnvClean` in the repository's verify.yaml,
+ *   2. `success.requireEnvClean` in the contract,
+ *   3. the contract naming `env-clean` in `verify.gates`.
+ *
+ * (3) is the one that was easy to miss. Opening the id to `verify.gates` without
+ * also asking here would have made every contract that used it report UNKNOWN
+ * forever: `selectGates` would run the gate, and `recordEnvBaseline` — reading
+ * only the OR of (1) and (2) — would never have written anything to compare
+ * against. An operator's `verify --gates env-clean` on a task created without any
+ * of the three still reports UNKNOWN, which is correct: no baseline exists, and
+ * inventing one from the state at verification time is the fail-open this gate
+ * refuses.
+ */
+function runsEnvCleanGate(contract, config) {
+    if ((0, env_clean_gate_1.resolveRequireEnvClean)(contract, config).required)
+        return true;
+    return resolveContractGateIds(contract)?.includes(verify_config_1.ENV_CLEAN_GATE_ID) ?? false;
+}
 /**
  * The gates this contract defines itself (#1791).
  *
@@ -146,7 +198,16 @@ function validateContractAgainstVerifyConfig(contract, config) {
             "repository's own — rename the contract gate.");
     }
     if (gates) {
-        const known = new Set([verify_config_1.WORK_EVIDENCE_GATE_ID, verify_config_1.SCOPE_GATE_ID, ...configIds]);
+        // `env-clean` joins the built-ins a contract may name (#2442). It is a
+        // reserved id, so it can never appear in `configIds` — leaving it out of this
+        // set made `verify.gates: [env-clean]` an unknown id at send, which is how
+        // the gate ended up reachable only through the repository-wide switch.
+        const known = new Set([
+            verify_config_1.WORK_EVIDENCE_GATE_ID,
+            verify_config_1.SCOPE_GATE_ID,
+            verify_config_1.ENV_CLEAN_GATE_ID,
+            ...configIds,
+        ]);
         const defined = new Set(definitions.map((gate) => gate.id));
         const unknown = gates.filter((id) => !known.has(id) && !defined.has(id));
         if (unknown.length > 0) {
@@ -174,11 +235,16 @@ function resolveGateCommands(contract, config) {
     const builtInLabels = new Map([
         [verify_config_1.WORK_EVIDENCE_GATE_ID, workEvidenceLabel],
         [verify_config_1.SCOPE_GATE_ID, SCOPE_LABEL],
+        // Without this row a contract naming `env-clean` resolved to `undefined` and
+        // the preamble handed the agent the literal string "undefined" as one of the
+        // commands it had to pass.
+        [verify_config_1.ENV_CLEAN_GATE_ID, ENV_CLEAN_LABEL],
     ]);
     // Contract-defined gates run after the repository's own, so the preamble
     // lists them in that order too — the line claims to be "the commands that
     // will run", and an order it invents would be the first thing to drift.
     const declared = [...config.gates, ...contractGateDefinitions(contract)];
+    const envCleanRequired = (0, env_clean_gate_1.resolveRequireEnvClean)(contract, config).required;
     const selected = resolveContractGateIds(contract);
     if (!selected) {
         // An omitted gates list runs every gate, and the built-ins are still governed
@@ -186,10 +252,18 @@ function resolveGateCommands(contract, config) {
         const builtIns = [workEvidenceLabel];
         if (contract.success.requireScopeClean)
             builtIns.push(SCOPE_LABEL);
+        if (envCleanRequired)
+            builtIns.push(ENV_CLEAN_LABEL);
         return [...builtIns, ...declared.map((gate) => gate.command)];
     }
+    // Re-derive the built-in prefix instead of trusting `selected`'s: the
+    // repository-wide `options.requireEnvClean` forces the gate into the run
+    // without appearing in the contract at all, and a preamble that omitted it
+    // would hand the agent a completion criterion the run does not use.
+    const builtIns = exports.BUILT_IN_GATE_ORDER.filter((id) => selected.includes(id) || (id === verify_config_1.ENV_CLEAN_GATE_ID && envCleanRequired));
+    const rest = selected.filter((id) => !exports.BUILT_IN_GATE_ORDER.includes(id));
     const byId = new Map(declared.map((gate) => [gate.id, gate.command]));
-    return selected.map((id) => builtInLabels.get(id) ?? byId.get(id));
+    return [...builtIns, ...rest].map((id) => builtInLabels.get(id) ?? byId.get(id));
 }
 /**
  * Compose the message sent to the agent: contract preamble, then the goal.

package/dist/server/src/lib/tasks/contract-parser.js

@@ -76,6 +76,7 @@ const SUCCESS_KEYS = [
     'requireWorkEvidence',
     'requireScopeClean',
     'requireCommit',
+    'requireEnvClean',
     'autoVerifyOnStop',
 ];
 class TaskContractError extends Error {
@@ -314,6 +315,7 @@ function validateSuccess(value, issues) {
         requireWorkEvidence: true,
         requireScopeClean: true,
         requireCommit: false,
+        requireEnvClean: false,
         autoVerifyOnStop: false,
     };
     if (value === undefined || value === null)