commandmate 0.33.2 → 0.33.3

package/dist/server/src/lib/hooks/sources/antigravity/transcript.js

@@ -76,6 +76,8 @@ exports.isAntigravityTurnClosingRecord = isAntigravityTurnClosingRecord;
 exports.isAntigravityTurnWritable = isAntigravityTurnWritable;
 exports.isAntigravityPromptRecord = isAntigravityPromptRecord;
 exports.renderAntigravityTurn = renderAntigravityTurn;
+exports.antigravityTurnLastRecordAt = antigravityTurnLastRecordAt;
+exports.resolveAntigravityTurnCompletion = resolveAntigravityTurnCompletion;
 const event_mapper_1 = require("../event-mapper");
 const turn_body_1 = require("../turn-body");
 /**
@@ -444,3 +446,104 @@ function renderAntigravityTurn(turn) {
         unknownRecordTypes: [...unknown],
     };
 }
+/**
+ * Epoch ms of the newest record agy wrote inside this turn, or 0 (Issue #2443).
+ *
+ * The maximum rather than `records.at(-1)`: `created_at` is agy's own field and
+ * a record that carries none reads as null, so the last record in file order is
+ * not always the last one with a clock on it. The prompt record is deliberately
+ * outside the walk — `records` holds everything *after* the `USER_INPUT` — which
+ * is why {@link resolveAntigravityTurnCompletion} floors the comparison at
+ * {@link AntigravityTurnAccumulator.startedAt} as well.
+ *
+ * @returns Epoch ms, or 0 when the turn has no timestamped record
+ */
+function antigravityTurnLastRecordAt(turn) {
+    let at = 0;
+    for (const record of turn.records) {
+        if (record.timestampMs !== null && record.timestampMs > at)
+            at = record.timestampMs;
+    }
+    return at;
+}
+/**
+ * Whether agy has vouched for this turn's body (Issue #2443).
+ *
+ * ## What this is separate from, and why the separation is the Issue
+ *
+ * {@link isAntigravityTurnWritable} answers "may a row be written from this
+ * turn". It has to be generous — agy writes **no record that closes a turn**, so
+ * the shape of the last thing it wrote is all there is, and an interim report
+ * ("waiting for the worker") is prose with no `tool_calls` exactly like a
+ * conclusion is. #2438 made the row that follows from that repairable. What it
+ * could not make repairable is everything a save *triggers*: a relay delivering
+ * the interim body to the session that asked for the answer cannot be taken
+ * back, and `broadcastMessage('message_updated', …)` does not rewind it.
+ *
+ * So this is the second question — "is this body final" — and it is answered
+ * from a different kind of evidence, deliberately:
+ *
+ *  - **not the wording.** "waiting", "Waiting for" and their translations are a
+ *    model's prose, and a rule keyed on them is wrong the first time the model
+ *    is asked to answer in another language or writes a conclusion that mentions
+ *    waiting.
+ *  - **not a fixed quiet period.** The gaps measured on the reporting machine
+ *    were 3 / 58 / 156 s from an interim candidate to the next record and 9 /
+ *    113 / 118 s from the final one, which overlap: no constant separates them.
+ *  - **not `status: DONE`** (all 15 measured candidates carry it, early and
+ *    final alike) **and not `truncated_fields`**, which is agy saying it
+ *    shortened a field.
+ *
+ * ## The evidence that is used
+ *
+ * agy's own `Stop` hook, correlated by instant. `Stop` is agy reporting that its
+ * loop ended, and CommandMate already records when one arrived
+ * (`session/agent-event-state`'s `getLastStopEventAt`). What makes it usable
+ * despite `source.ts`'s warning that a `Stop` can be answered with
+ * `{"decision":"continue"}` is that the correlation is an ordering rather than a
+ * flag: a stop is evidence about the file **as it was when the stop arrived**.
+ *
+ *  - A resumed loop appends records *after* the stop, which pushes
+ *    `lastRecordAt` past `stopAt` and takes the confirmation away again. The
+ *    evidence therefore withdraws itself in exactly the case the warning is
+ *    about, with no `continue`-detection of its own.
+ *  - A stop belonging to the *previous* turn is older than this turn's records
+ *    and confirms nothing.
+ *  - No stop at all — hooks not wired up, agy killed, CommandMate restarted
+ *    since — is `no-stop-event`, and the caller keeps the body provisional
+ *    rather than promoting it.
+ *
+ * The residual is agy's clock resolution: `created_at` is written to the second,
+ * so a record appended in the same second as the stop compares equal to it.
+ * That is a sub-second window, it is bounded by one `created_at` tick, and the
+ * direction of the error is a body confirmed one record early rather than a turn
+ * confirmed that never ended.
+ *
+ * Pure: the stop instant is a parameter, so this file keeps its no-filesystem,
+ * no-database, no-`globalThis` contract and the rule is a property a test states
+ * against values rather than against a running server.
+ *
+ * @param turn - The turn to judge
+ * @param stopAt - Epoch ms of this instance's last `Stop`, or null when none has
+ *   been received
+ */
+function resolveAntigravityTurnCompletion(turn, stopAt) {
+    const lastRecordAt = antigravityTurnLastRecordAt(turn);
+    const base = { confirmed: false, lastRecordAt, stopAt };
+    // A turn agy is still working through has no final body to vouch for. Asked
+    // before the clock questions so that "it is still running" never reads as
+    // "its records are unstamped".
+    if (!isAntigravityTurnWritable(turn))
+        return { ...base, reason: 'turn-open' };
+    if (lastRecordAt <= 0)
+        return { ...base, reason: 'no-timestamped-record' };
+    if (stopAt === null)
+        return { ...base, reason: 'no-stop-event' };
+    // `startedAt` as well as the newest record: a turn whose records all predate
+    // its own prompt is a shape this reader has not seen, and taking the later of
+    // the two cannot make the test easier to pass.
+    if (stopAt < Math.max(lastRecordAt, turn.startedAt)) {
+        return { ...base, reason: 'stop-before-last-record' };
+    }
+    return { confirmed: true, reason: 'stop-after-last-record', lastRecordAt, stopAt };
+}

package/dist/server/src/lib/polling/structured-history-gate.js

@@ -118,9 +118,41 @@ const logger = (0, logger_1.createLogger)('lib/polling/structured-history-gate')
  * can see is not a lock.
  */
 const captureQueue = (globalThis.__structuredHistoryCaptureQueue ??= new Map());
-/** Forget every instance's in-flight capture. Test seam. */
+/**
+ * The last completion each instance was announced for (Issue #2443).
+ *
+ * Keyed by the same triple as {@link captureQueue}, holding whatever
+ * `StructuredHistoryCaptureReport.completionKey` the reader minted. Its only job
+ * is to make the completion edge an *edge*: the poller re-reads a finished turn
+ * every couple of seconds, and #2443 forbids adding a path that re-delivers a
+ * body somebody already has.
+ *
+ * On `globalThis` for the reason {@link captureQueue} is, and in memory for the
+ * reason `session/agent-event-state` gives: the value describes a live session,
+ * and a restart that forgets it costs at most one extra announcement into a
+ * relay whose own stash guard already refuses a second payload.
+ */
+const announcedCompletions = (globalThis.__structuredHistoryAnnouncedCompletions ??= new Map());
+/** Forget every instance's in-flight capture and announced completion. Test seam. */
 function resetStructuredHistoryCaptureQueue() {
     captureQueue.clear();
+    announcedCompletions.clear();
+}
+/**
+ * Whether this completion has already been announced for this instance (#2443).
+ *
+ * A reader that minted no key is always announced — the pre-#2443 behaviour, and
+ * the behaviour claude, codex and command-code keep. Records the key as a side
+ * effect when the answer is "no", because the two steps must not be separable:
+ * an announcement that forgot to record would repeat on the next poll.
+ */
+function claimCompletionAnnouncement(key, completionKey) {
+    if (completionKey === undefined)
+        return true;
+    if (announcedCompletions.get(key) === completionKey)
+        return false;
+    announcedCompletions.set(key, completionKey);
+    return true;
 }
 /** The queue key; the same triple `buildCompositeKey` spells everywhere else. */
 function captureKeyOf(worktreeId, cliToolId, instanceId) {
@@ -296,17 +328,24 @@ async function captureStructuredHistoryTurn(worktreeId, cliToolId, instanceId, c
         return false;
     }
     const resolvedInstanceId = instanceId ?? cliToolId;
-    return serializePerInstance(captureKeyOf(worktreeId, cliToolId, resolvedInstanceId), async () => {
+    const captureKey = captureKeyOf(worktreeId, cliToolId, resolvedInstanceId);
+    return serializePerInstance(captureKey, async () => {
         // The reader's own report, kept local and copied out below: `report` is
         // the caller's object and must end up holding one verdict, not whatever
         // the last reader to touch it happened to leave there.
         const readerReport = {};
         try {
             const captured = await reader.capture({ worktreeId, cliToolId, instanceId: resolvedInstanceId }, capture, readerReport);
+            // Issue #2443: absent means `settled`, which is what leaves the three
+            // readers that have a turn-closing record exactly where they were.
+            const completion = readerReport.completion ?? 'settled';
             if (report) {
                 // A reader that says nothing is read as `unavailable` — the pre-#2436
                 // behaviour, and the safe direction: the scraper keeps the turn.
                 report.outcome = captured ? 'captured' : readerReport.outcome ?? 'unavailable';
+                report.completion = completion;
+                report.completionKey = readerReport.completionKey;
+                report.completionReason = readerReport.completionReason;
             }
             // Issue #2377: the moment a relay is waiting for. This is the single
             // point BOTH triggers of a pull capture pass through — the poller's save
@@ -317,8 +356,33 @@ async function captureStructuredHistoryTurn(worktreeId, cliToolId, instanceId, c
             // Announced only when the capture actually wrote something: a `false`
             // means the scraper is still the writer for this turn, and the poller's
             // own call below will announce it.
-            if (captured)
-                (0, relay_triggers_1.onRelayTurnCompleted)(worktreeId, cliToolId, resolvedInstanceId, true);
+            //
+            // Issue #2443 adds the second condition, and it is the whole Issue.
+            // `captured` means History holds the newest turn; it does **not** mean
+            // the agent is finished with it, because antigravity has no record that
+            // closes a turn and an interim report is saved under the same key the
+            // conclusion will land on. Announcing here would hand a relay the
+            // interim body as the answer, and `broadcastMessage('message_updated',
+            // …)` — the repair #2438 added — does not take a delivered message
+            // back. So a provisional capture announces nothing at all; the relay
+            // keeps waiting on the deadline it already has, and the settled capture
+            // that follows announces the finished body.
+            if (captured && completion === 'settled') {
+                if (claimCompletionAnnouncement(captureKey, readerReport.completionKey)) {
+                    (0, relay_triggers_1.onRelayTurnCompleted)(worktreeId, cliToolId, resolvedInstanceId, true);
+                }
+            }
+            else if (captured) {
+                logger.info('structured-history-capture-provisional', {
+                    worktreeId,
+                    cliToolId,
+                    instanceId: resolvedInstanceId,
+                    // The reader's own word for what is missing; see
+                    // `AntigravityTurnCompletionReason`. This is the line #2443 asks for
+                    // — the reason left on the relay's waiting path.
+                    reason: readerReport.completionReason ?? 'unknown',
+                });
+            }
             return captured;
         }
         catch (error) {

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/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)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "commandmate",
-  "version": "0.33.2",
+  "version": "0.33.3",
   "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",