commandmate 0.23.0 → 0.25.0

package/dist/server/src/lib/session/waiting-episode-state.js

@@ -0,0 +1,136 @@
+"use strict";
+/**
+ * When each agent instance started waiting, and the one place that edge is
+ * observed (Issue #1786).
+ *
+ * `isWaitingForResponse` is a level, and every question the display Issues ask
+ * is about the *edge*: #1787 wants "waiting for how long", #1788 wants to push a
+ * WebSocket frame the instant it flips, #1790 wants to fire a push notification
+ * on the same instant and not on the 200 polls that follow. A level cannot
+ * answer any of those, and three surfaces each keeping their own "was it waiting
+ * last time?" would be three chances to disagree about when a wait began.
+ *
+ * So the edge is detected exactly once, here, by {@link observeWaitingEdge}, and
+ * everything else either reads {@link getWaitingEpisode} or subscribes with
+ * {@link onWaitingTransition}. There is one caller today —
+ * `worktree-status-helper`, on the list API's per-instance probe — and it passes
+ * the *composed* verdict (scraper OR structured), so a wait that only the
+ * agent's own events can see opens an episode exactly like one the screen
+ * scraper read.
+ *
+ * ## Where #1788 / #1790 plug in
+ *
+ * `onWaitingTransition(listener)` — the listener receives every false→true and
+ * true→false crossing, with the instance it belongs to, the episode's `since`
+ * and its {@link WaitingKind}. #1788 broadcasts it (`broadcastToWorktree`),
+ * #1790 decides whether to send a push. Neither needs to touch this module's
+ * internals, and neither can move the timestamps the other reports.
+ *
+ * Listeners are called synchronously, inside the request that observed the edge,
+ * because the point of the seam is immediacy. A listener that throws is
+ * contained: this store is on the list API's hot path, and a broken notification
+ * sink must not take the status read down with it.
+ *
+ * In-memory (via `globalThis`, per Issue #1736 — see the note in
+ * `agent-event-state`) rather than SQLite, for the same reason the structured
+ * state is: it describes a live tmux session, and a wait does not outlive the
+ * server process that observed it.
+ *
+ * @module lib/session/waiting-episode-state
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.onWaitingTransition = onWaitingTransition;
+exports.observeWaitingEdge = observeWaitingEdge;
+exports.getWaitingEpisode = getWaitingEpisode;
+exports.clearWaitingEpisodes = clearWaitingEpisodes;
+exports.clearWaitingTransitionListeners = clearWaitingTransitionListeners;
+const auto_yes_state_1 = require("../../lib/auto-yes-state");
+const logger_1 = require("../../lib/logger");
+const logger = (0, logger_1.createLogger)('waiting-episode-state');
+/** compositeKey -> the wait currently in progress for that instance. */
+const episodes = globalThis.__sessionWaitingEpisodes ??
+    (globalThis.__sessionWaitingEpisodes = new Map());
+/** Subscribers to the edge. See the module docblock. */
+const listeners = globalThis.__sessionWaitingTransitionListeners ??
+    (globalThis.__sessionWaitingTransitionListeners = new Set());
+/**
+ * Subscribe to waiting edges.
+ *
+ * @returns An unsubscribe function. Idempotent — calling it twice is harmless.
+ */
+function onWaitingTransition(listener) {
+    listeners.add(listener);
+    return () => {
+        listeners.delete(listener);
+    };
+}
+/** Notify subscribers, containing anything they throw. */
+function emit(transition) {
+    for (const listener of listeners) {
+        try {
+            listener(transition);
+        }
+        catch (error) {
+            logger.error('waiting-transition-listener-failed', {
+                worktreeId: transition.worktreeId,
+                cliToolId: transition.cliToolId,
+                instanceId: transition.instanceId ?? transition.cliToolId,
+                waiting: transition.waiting,
+                error: error instanceof Error ? error.message : String(error),
+            });
+        }
+    }
+}
+/**
+ * Record this poll's waiting verdict and answer when the current wait began.
+ *
+ * The single writer of the edge, by design (Issue #1786). Idempotent for a
+ * level that has not changed: repeated `waiting: true` polls return the same
+ * `since` and emit nothing, so a listener hears one event per wait rather than
+ * one per poll.
+ *
+ * @returns The episode's `since` while waiting, or null when it is not.
+ */
+function observeWaitingEdge({ worktreeId, cliToolId, instanceId, waiting, kind = null, structuredSince = null, now = Date.now(), }) {
+    const key = (0, auto_yes_state_1.buildCompositeKey)(worktreeId, cliToolId, instanceId);
+    const existing = episodes.get(key);
+    if (!waiting) {
+        if (existing === undefined)
+            return null;
+        episodes.delete(key);
+        emit({ worktreeId, cliToolId, instanceId, waiting: false, since: null, kind: null, at: now });
+        return null;
+    }
+    if (existing !== undefined) {
+        // A wait can change character without ending — a permission dialog answered
+        // into a selection list is still one uninterrupted wait — so the kind is
+        // refreshed while `since` stays put.
+        existing.kind = kind;
+        return existing.since;
+    }
+    const since = structuredSince ?? now;
+    episodes.set(key, { since, kind });
+    emit({ worktreeId, cliToolId, instanceId, waiting: true, since, kind, at: now });
+    return since;
+}
+/**
+ * @returns The wait in progress for this instance, or null when it is not
+ *   waiting. Read-only: observing the edge is {@link observeWaitingEdge}'s job.
+ */
+function getWaitingEpisode(worktreeId, cliToolId, instanceId) {
+    return episodes.get((0, auto_yes_state_1.buildCompositeKey)(worktreeId, cliToolId, instanceId)) ?? null;
+}
+/**
+ * Drop every episode. Test seam.
+ *
+ * CI runs with `fileParallelism: false`, so one process holds this map for the
+ * whole suite: a test that opens an episode and does not clear it hands the next
+ * file a session that is already waiting.
+ */
+function clearWaitingEpisodes() {
+    episodes.clear();
+}
+/** Drop every subscriber. Test seam, paired with {@link clearWaitingEpisodes}. */
+function clearWaitingTransitionListeners() {
+    listeners.clear();
+}

package/dist/server/src/lib/session/waiting-kind.js

@@ -0,0 +1,59 @@
+"use strict";
+/**
+ * What *kind* of waiting a session is in (Issue #1786).
+ *
+ * `isWaitingForResponse` answers "does this session need a human?" and nothing
+ * else, so every surface that shows it has to render one orange dot for three
+ * situations a user would act on differently:
+ *
+ *  - a y/n or numbered prompt the app itself can answer for them (`prompt`);
+ *  - a selection list or a pager, which only the terminal can drive (`menu`);
+ *  - a dialog only the agent's own events reported, or a frame neither layer
+ *    could classify (`unclassified`).
+ *
+ * Kept a pure function of the detector's verdict — no clock, no store, no tmux —
+ * because it is the one piece of #1786 that the display Issues (#1787/#1788)
+ * will read literally and therefore the one piece that has to be pinned by unit
+ * tests rather than by a live session.
+ *
+ * @module lib/session/waiting-kind
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.deriveWaitingKind = deriveWaitingKind;
+const status_detector_1 = require("../../lib/detection/status-detector");
+/**
+ * Classify a waiting session, or answer null when it is not waiting.
+ *
+ * The order is a precedence, not a sequence of independent tests: a frame that
+ * carries an answerable prompt is a `prompt` even if the reason string would
+ * also pass the menu test, because "you can answer this from the app" is the
+ * more actionable fact.
+ *
+ * | condition                                        | kind             |
+ * |--------------------------------------------------|------------------|
+ * | not waiting                                       | `null`           |
+ * | `hasActivePrompt`                                 | `'prompt'`       |
+ * | scraper `waiting` + a {@link SELECTION_LIST_REASONS} reason | `'menu'` |
+ * | anything else that is still waiting                | `'unclassified'` |
+ *
+ * The `menu` row is the same expression `current-output-builder` publishes as
+ * `isSelectionListActive`, and the pager (`codex_pager`) is a member of that set
+ * — so the pager lands in `menu` for the reason the Issue asks for, without a
+ * second copy of the membership test.
+ *
+ * `unclassified` is the honest fallback rather than a fourth guess. In practice
+ * it is reached when only the structured layer sees the dialog: every scraper
+ * `waiting` verdict is either `prompt_detected` (→ `prompt`) or a selection-list
+ * reason (→ `menu`), so a waiting session the scraper never classified is one it
+ * could not read at all.
+ */
+function deriveWaitingKind(input) {
+    if (!input.waiting)
+        return null;
+    if (input.hasActivePrompt)
+        return 'prompt';
+    if (input.scraperStatus === 'waiting' && status_detector_1.SELECTION_LIST_REASONS.has(input.scraperReason)) {
+        return 'menu';
+    }
+    return 'unclassified';
+}

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

@@ -18,6 +18,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.REQUIRE_COMMIT_SOURCE_CONTRACT = exports.REQUIRE_COMMIT_SOURCE_CONFIG = void 0;
 exports.resolveRequireCommit = resolveRequireCommit;
 exports.resolveContractGateIds = resolveContractGateIds;
+exports.contractGateDefinitions = contractGateDefinitions;
 exports.validateContractAgainstVerifyConfig = validateContractAgainstVerifyConfig;
 exports.resolveGateCommands = resolveGateCommands;
 exports.composeContractMessage = composeContractMessage;
@@ -88,37 +89,75 @@ function resolveContractGateIds(contract) {
     return [...selected, ...rest];
 }
 /**
- * Check that every gate the contract names can actually be resolved.
+ * The gates this contract defines itself (#1791).
+ *
+ * Read through a helper because `contract` also arrives from
+ * `tasks.contract_json`, and a row written before the field existed parses back
+ * as `undefined` rather than an empty list. Every consumer reads it here so
+ * "an old task" and "a task that defines no gates" cannot behave differently.
+ */
+function contractGateDefinitions(contract) {
+    return contract.verify.gateDefinitions ?? [];
+}
+/**
+ * Check that the contract's gates can actually be resolved, and that its own
+ * definitions do not collide with the repository's.
  *
  * A contract pointing at a gate id that does not exist would only be caught at
  * verification time, by which point the agent has already been told a
  * completion criterion that cannot be evaluated. Reporting it here makes
  * "the contract was accepted" and "the contract's gates exist" the same moment.
  *
+ * The collision check is the same discipline pointed the other way (#1791). A
+ * contract that redefined an id `.commandmate/verify.yaml` already declares
+ * would replace the repository's own definition of passing with one written per
+ * delegation — silently, since both spell the same id in the report. Reserved
+ * ids (`work-evidence` / `scope` / `env-clean`) are refused one step earlier, by
+ * the shared gate validator in the parser; both refusals happen at send.
+ *
  * @returns issue strings, empty when the contract resolves cleanly
  */
 function validateContractAgainstVerifyConfig(contract, config) {
     const gates = contract.verify.gates;
-    if (!gates)
-        return [];
+    const definitions = contractGateDefinitions(contract);
+    const issues = [];
     if (!config) {
-        return [
-            `verify.gates: declared ${gates.join(', ')}, but ${verify_config_1.VERIFY_CONFIG_RELATIVE_PATH} ` +
-                'is missing or unreadable in this worktree, so the gate ids cannot be resolved',
-        ];
+        // Fail-closed for definitions too: the runner refuses to start a run at all
+        // without a config, so accepting the contract would promise a criterion that
+        // can never be evaluated — the exact thing this function exists to prevent.
+        if (definitions.length > 0) {
+            issues.push(`verify.gateDefinitions: declared ${definitions.map((gate) => gate.id).join(', ')}, ` +
+                `but ${verify_config_1.VERIFY_CONFIG_RELATIVE_PATH} is missing or unreadable in this worktree, ` +
+                'so no verification run can execute them');
+        }
+        if (gates) {
+            issues.push(`verify.gates: declared ${gates.join(', ')}, but ${verify_config_1.VERIFY_CONFIG_RELATIVE_PATH} ` +
+                'is missing or unreadable in this worktree, so the gate ids cannot be resolved');
+        }
+        return issues;
     }
-    const known = new Set([
-        verify_config_1.WORK_EVIDENCE_GATE_ID,
-        verify_config_1.SCOPE_GATE_ID,
-        ...config.gates.map((gate) => gate.id),
-    ]);
-    const unknown = gates.filter((id) => !known.has(id));
-    if (unknown.length === 0)
-        return [];
-    return [
-        `verify.gates: unknown gate id(s) ${unknown.join(', ')}. ` +
-            `Declared in ${verify_config_1.VERIFY_CONFIG_RELATIVE_PATH}: ${[...known].join(', ')}`,
-    ];
+    const configIds = config.gates.map((gate) => gate.id);
+    const collisions = definitions
+        .map((gate) => gate.id)
+        .filter((id) => configIds.includes(id));
+    if (collisions.length > 0) {
+        issues.push(`verify.gateDefinitions: gate id(s) ${collisions.join(', ')} are already declared in ` +
+            `${verify_config_1.VERIFY_CONFIG_RELATIVE_PATH}. A contract may add gates, never redefine the ` +
+            "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]);
+        const defined = new Set(definitions.map((gate) => gate.id));
+        const unknown = gates.filter((id) => !known.has(id) && !defined.has(id));
+        if (unknown.length > 0) {
+            const sources = [`Declared in ${verify_config_1.VERIFY_CONFIG_RELATIVE_PATH}: ${[...known].join(', ')}`];
+            if (defined.size > 0) {
+                sources.push(`in verify.gateDefinitions: ${[...defined].join(', ')}`);
+            }
+            issues.push(`verify.gates: unknown gate id(s) ${unknown.join(', ')}. ${sources.join('; ')}`);
+        }
+    }
+    return issues;
 }
 /**
  * The commands the contract's gates will run, in the order they will run.
@@ -136,6 +175,10 @@ function resolveGateCommands(contract, config) {
         [verify_config_1.WORK_EVIDENCE_GATE_ID, workEvidenceLabel],
         [verify_config_1.SCOPE_GATE_ID, SCOPE_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 selected = resolveContractGateIds(contract);
     if (!selected) {
         // An omitted gates list runs every gate, and the built-ins are still governed
@@ -143,9 +186,9 @@ function resolveGateCommands(contract, config) {
         const builtIns = [workEvidenceLabel];
         if (contract.success.requireScopeClean)
             builtIns.push(SCOPE_LABEL);
-        return [...builtIns, ...config.gates.map((gate) => gate.command)];
+        return [...builtIns, ...declared.map((gate) => gate.command)];
     }
-    const byId = new Map(config.gates.map((gate) => [gate.id, gate.command]));
+    const byId = new Map(declared.map((gate) => [gate.id, gate.command]));
     return selected.map((id) => builtInLabels.get(id) ?? byId.get(id));
 }
 /**

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

@@ -23,13 +23,14 @@
  * @module lib/tasks/contract-parser
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.TaskContractError = exports.MAX_ALLOW_PROMPT_TYPES = exports.MAX_DENY_PATTERNS = exports.MAX_GATE_IDS = exports.MAX_SCOPE_PATTERNS = exports.MAX_PATTERN_LENGTH = exports.MAX_GOAL_LENGTH = exports.MAX_TITLE_LENGTH = exports.PROMPT_TYPES = exports.AUTO_YES_MODES = exports.TASK_CONTRACT_DIR = void 0;
+exports.TaskContractError = exports.MAX_ALLOW_PROMPT_TYPES = exports.MAX_DENY_PATTERNS = exports.MAX_GATE_DEFINITIONS = exports.MAX_GATE_IDS = exports.MAX_SCOPE_PATTERNS = exports.MAX_PATTERN_LENGTH = exports.MAX_GOAL_LENGTH = exports.MAX_TITLE_LENGTH = exports.PROMPT_TYPES = exports.AUTO_YES_MODES = exports.TASK_CONTRACT_DIR = void 0;
 exports.parseTaskContract = parseTaskContract;
 exports.loadTaskContract = loadTaskContract;
 const fs_1 = require("fs");
 const path_1 = require("path");
 const yaml_1 = require("yaml");
 const path_validator_1 = require("../../lib/security/path-validator");
+const verify_config_1 = require("../../lib/verification/verify-config");
 /** Directory contracts live in, relative to the worktree root. */
 exports.TASK_CONTRACT_DIR = '.commandmate/tasks';
 /**
@@ -63,11 +64,13 @@ exports.MAX_GOAL_LENGTH = 8000;
 exports.MAX_PATTERN_LENGTH = 200;
 exports.MAX_SCOPE_PATTERNS = 200;
 exports.MAX_GATE_IDS = 32;
+/** Matches {@link MAX_GATE_IDS}: a contract cannot select more gates than it may define. */
+exports.MAX_GATE_DEFINITIONS = 32;
 exports.MAX_DENY_PATTERNS = 32;
 exports.MAX_ALLOW_PROMPT_TYPES = 16;
 const TOP_LEVEL_KEYS = ['version', 'title', 'goal', 'scope', 'verify', 'autoYes', 'success'];
 const SCOPE_KEYS = ['allow', 'deny'];
-const VERIFY_KEYS = ['gates'];
+const VERIFY_KEYS = ['gates', 'gateDefinitions'];
 const AUTO_YES_KEYS = ['mode', 'allowPromptTypes', 'denyPatterns'];
 const SUCCESS_KEYS = [
     'requireWorkEvidence',
@@ -75,8 +78,6 @@ const SUCCESS_KEYS = [
     'requireCommit',
     'autoVerifyOnStop',
 ];
-/** Mirrors GATE_ID_PATTERN in verify-config.ts: a contract can only name ids that could exist. */
-const GATE_ID_PATTERN = /^[a-z0-9][a-z0-9-]{0,31}$/;
 class TaskContractError extends Error {
     issues;
     constructor(issues) {
@@ -198,30 +199,61 @@ function validateScope(value, issues) {
     }
     return scope;
 }
+/**
+ * Validate `verify.gateDefinitions` (Issue #1791).
+ *
+ * Delegates every per-entry rule to verify-config's own gate validator, so a
+ * gate defined in a contract is held to exactly the constraints a gate declared
+ * in `.commandmate/verify.yaml` is — including the reserved ids, which is where
+ * a contract shadowing `work-evidence` or `scope` is rejected. That rejection
+ * lands here, at parse time, rather than in the verify.yaml cross-check: it
+ * needs no config to decide, and both run at send.
+ *
+ * An empty list is accepted as equivalent to omitting the key. Unlike
+ * `verify.gates: []` — which would read as "pass having run nothing" — a
+ * definition list with no entries has exactly one possible meaning, and an
+ * orchestrator that emits YAML programmatically should not have to special-case
+ * "this delegation happens to need no extra gate".
+ */
+function validateGateDefinitions(value, issues) {
+    if (value === undefined || value === null)
+        return [];
+    if (Array.isArray(value) && value.length > exports.MAX_GATE_DEFINITIONS) {
+        issues.push(`verify.gateDefinitions: at most ${exports.MAX_GATE_DEFINITIONS} entries (got ${value.length})`);
+        return [];
+    }
+    return (0, verify_config_1.validateGateEntries)(value, 'verify.gateDefinitions', issues);
+}
 function validateVerify(value, issues) {
+    const empty = () => ({ gates: null, gateDefinitions: [] });
     if (value === undefined || value === null)
-        return { gates: null };
+        return empty();
     if (!isMapping(value)) {
         issues.push(`verify: must be a mapping (got ${describe(value)})`);
-        return { gates: null };
+        return empty();
     }
     collectUnknownKeys(value, VERIFY_KEYS, 'verify', issues);
+    const gateDefinitions = validateGateDefinitions(value.gateDefinitions, issues);
+    const withDefinitions = (gates) => ({
+        gates,
+        gateDefinitions,
+    });
     if (value.gates === undefined || value.gates === null)
-        return { gates: null };
+        return withDefinitions(null);
     const gates = validateStringList(value.gates, 'verify.gates', { maxEntries: exports.MAX_GATE_IDS, maxLength: 32 }, issues);
     if (!gates)
-        return { gates: null };
+        return withDefinitions(null);
     // An empty list would read as "pass with no gates run". "Run everything" is
     // spelled by omitting the key, so the two can never be confused.
     if (Array.isArray(value.gates) && value.gates.length === 0) {
         issues.push('verify.gates: must name at least one gate (omit the key to run every gate)');
-        return { gates: null };
+        return withDefinitions(null);
     }
     const valid = [];
     const seen = new Set();
     gates.forEach((id, index) => {
-        if (!GATE_ID_PATTERN.test(id)) {
-            issues.push(`verify.gates[${index}]: "${id}" must match ${GATE_ID_PATTERN.source}`);
+        if (!verify_config_1.GATE_ID_PATTERN.test(id)) {
+            issues.push(`verify.gates[${index}]: "${id}" must match ${verify_config_1.GATE_ID_PATTERN.source}`);
             return;
         }
         if (seen.has(id)) {
@@ -231,7 +263,7 @@ function validateVerify(value, issues) {
         seen.add(id);
         valid.push(id);
     });
-    return { gates: valid.length > 0 ? valid : null };
+    return withDefinitions(valid.length > 0 ? valid : null);
 }
 function validateAutoYes(value, issues) {
     const autoYes = { mode: null, allowPromptTypes: [], denyPatterns: [] };
@@ -364,6 +396,20 @@ function parseTaskContract(raw, sourceLabel) {
             '(the commit requirement is judged by the work-evidence gate, which ' +
             'requireWorkEvidence: false switches off)');
     }
+    // Same rule again, for the gates this contract defines itself (#1791). A
+    // definition that `verify.gates` leaves out is a check the contract appears to
+    // add and never runs — and it is the *only* declaration of that gate, so
+    // unlike a verify.yaml gate there is no other run that would ever execute it.
+    // Selecting a subset is spelled by deleting the definition.
+    if (verify.gates) {
+        const unselected = verify.gateDefinitions
+            .map((gate) => gate.id)
+            .filter((id) => !verify.gates?.includes(id));
+        if (unselected.length > 0) {
+            issues.push(`verify.gateDefinitions: ${unselected.join(', ')} defined but not named in verify.gates, ` +
+                'so nothing would ever run them (list them, or delete the definition)');
+        }
+    }
     if (issues.length > 0)
         throw new TaskContractError(issues);
     return { version: 1, title, goal, scope, verify, autoYes, success };

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

@@ -389,33 +389,65 @@ async function resolveBaseRef(config, worktreePath) {
     return defaultBranch ? `origin/${defaultBranch}` : null;
 }
 /**
- * Resolve `gateIds` against the config.
+ * Every gate available to this run, in execution order (Issue #1791).
+ *
+ * The repository's own declarations first, then the ones this delegation's
+ * contract carried. Repository-wide criteria are what an Issue gate is judged
+ * *against*, so running the shared ones first is what makes a report readable
+ * top to bottom: "the repository's definition of passing held, and then the
+ * Issue-specific check did too".
+ *
+ * A contract gate whose id collides with a verify.yaml gate is refused rather
+ * than merged. `validateContractAgainstVerifyConfig` already rejects that at
+ * send, so reaching here means the contract was stored by an older build or
+ * written straight into the database — and running both would put two rows
+ * under one id in the report, which is precisely the ambiguity `source` exists
+ * to remove.
+ */
+function declaredGates(config, contractGates) {
+    const fromConfig = config.gates.map((gate) => ({
+        ...gate,
+        source: 'verify.yaml',
+    }));
+    const configIds = new Set(fromConfig.map((gate) => gate.id));
+    const collisions = contractGates.filter((gate) => configIds.has(gate.id)).map((gate) => gate.id);
+    if (collisions.length > 0) {
+        return (`Contract gate id(s) ${collisions.join(', ')} are already declared in ` +
+            `${verify_config_1.VERIFY_CONFIG_RELATIVE_PATH}. A contract may add gates, never redefine the ` +
+            "repository's own.");
+    }
+    return [...fromConfig, ...contractGates.map((gate) => ({ ...gate, source: 'contract' }))];
+}
+/**
+ * Resolve `gateIds` against the declared gates.
  *
  * Returns a message instead of a selection when the request names a gate that
  * does not exist, or selects nothing at all. Both would otherwise produce a run
  * with zero gate results, which {@link aggregateRunStatus} would have to call
  * `passed` — a green verdict from having checked nothing.
  *
+ * @param declared verify.yaml's gates followed by the contract's (#1791); the
+ *        selection preserves this order, never the order `gateIds` was typed in
  * @param requireEnvClean whether a declaration switched env-clean on. It is
  *        ORed with an explicit request rather than replacing it, so `--gates
  *        env-clean` still works with the switch off (and honestly reports
  *        UNKNOWN, because no baseline was recorded), and a delegation that
  *        declared the requirement cannot lose it by naming a narrower gate list.
  */
-function selectGates(config, gateIds, requireEnvClean) {
+function selectGates(declared, gateIds, requireEnvClean) {
     if (!gateIds) {
         return {
             runWorkEvidence: true,
             scope: 'implicit',
             runEnvClean: requireEnvClean,
-            gates: config.gates,
+            gates: declared,
         };
     }
     const known = new Set([
         verify_config_1.WORK_EVIDENCE_GATE_ID,
         verify_config_1.SCOPE_GATE_ID,
         verify_config_1.ENV_CLEAN_GATE_ID,
-        ...config.gates.map((g) => g.id),
+        ...declared.map((g) => g.id),
     ]);
     const unknown = gateIds.filter((id) => !known.has(id));
     if (unknown.length > 0) {
@@ -426,7 +458,7 @@ function selectGates(config, gateIds, requireEnvClean) {
         runWorkEvidence: requested.has(verify_config_1.WORK_EVIDENCE_GATE_ID),
         scope: requested.has(verify_config_1.SCOPE_GATE_ID) ? 'explicit' : 'off',
         runEnvClean: requested.has(verify_config_1.ENV_CLEAN_GATE_ID) || requireEnvClean,
-        gates: config.gates.filter((gate) => requested.has(gate.id)),
+        gates: declared.filter((gate) => requested.has(gate.id)),
     };
     if (!selection.runWorkEvidence &&
         selection.scope === 'off' &&
@@ -486,8 +518,8 @@ async function executeRun(db, runId, worktreePath, config, selection, baseRef, t
      * and closing back to back (what this used to do) left that loop with nothing
      * to find, and an interrupted gate with no record at all.
      */
-    const runGate = async (gateId, command, evaluate) => {
-        const row = (0, db_1.createGateResult)(db, runId, { gateId, command });
+    const runGate = async (gateId, command, source, evaluate) => {
+        const row = (0, db_1.createGateResult)(db, runId, { gateId, command, source });
         return close(row.id, await evaluate());
     };
     /**
@@ -496,26 +528,26 @@ async function executeRun(db, runId, worktreePath, config, selection, baseRef, t
      * Opened and closed on the spot: there is no execution to leave a `running`
      * row around, and the row carries {@link notRun}'s zero-length window.
      */
-    const recordNotRun = (gateId, command, reason) => {
+    const recordNotRun = (gateId, command, source, reason) => {
         const outcome = notRun(reason);
-        const row = (0, db_1.createGateResult)(db, runId, { gateId, command });
+        const row = (0, db_1.createGateResult)(db, runId, { gateId, command, source });
         return close(row.id, outcome);
     };
     const statuses = [];
     if (runWorkEvidence) {
-        const outcome = await runGate(verify_config_1.WORK_EVIDENCE_GATE_ID, WORK_EVIDENCE_GATE_COMMAND, () => evaluateWorkEvidence(worktreePath, baseRef, requireCommit));
+        const outcome = await runGate(verify_config_1.WORK_EVIDENCE_GATE_ID, WORK_EVIDENCE_GATE_COMMAND, 'builtin', () => evaluateWorkEvidence(worktreePath, baseRef, requireCommit));
         if (outcome.status !== 'passed') {
             // Nothing was produced, so every command gate below would be judging the
             // base commit. Record them as skipped so the run shows what was not run.
             const reason = `skipped: the ${verify_config_1.WORK_EVIDENCE_GATE_ID} gate did not pass.`;
             if (selection.scope !== 'off') {
-                recordNotRun(verify_config_1.SCOPE_GATE_ID, SCOPE_GATE_COMMAND, reason);
+                recordNotRun(verify_config_1.SCOPE_GATE_ID, SCOPE_GATE_COMMAND, 'builtin', reason);
             }
             if (selection.runEnvClean) {
-                recordNotRun(verify_config_1.ENV_CLEAN_GATE_ID, ENV_CLEAN_GATE_COMMAND, reason);
+                recordNotRun(verify_config_1.ENV_CLEAN_GATE_ID, ENV_CLEAN_GATE_COMMAND, 'builtin', reason);
             }
             for (const gate of gates) {
-                recordNotRun(gate.id, gate.command, reason);
+                recordNotRun(gate.id, gate.command, gate.source, reason);
             }
             return outcome.status === 'failed' ? 'not_started' : 'error';
         }
@@ -525,8 +557,8 @@ async function executeRun(db, runId, worktreePath, config, selection, baseRef, t
         // A detached contract is decided before the gate would run, so its row is
         // recorded rather than executed.
         const outcome = detachedContract
-            ? recordNotRun(verify_config_1.SCOPE_GATE_ID, SCOPE_GATE_COMMAND, (0, scope_gate_1.scopeSkipDetachedContract)(detachedContract.id, detachedContract.status))
-            : await runGate(verify_config_1.SCOPE_GATE_ID, SCOPE_GATE_COMMAND, () => (0, scope_gate_1.evaluateScope)(worktreePath, task?.contract.scope ?? null, task?.contract.success.requireScopeClean ?? false, baseRef, task?.contractPath ?? null));
+            ? recordNotRun(verify_config_1.SCOPE_GATE_ID, SCOPE_GATE_COMMAND, 'builtin', (0, scope_gate_1.scopeSkipDetachedContract)(detachedContract.id, detachedContract.status))
+            : await runGate(verify_config_1.SCOPE_GATE_ID, SCOPE_GATE_COMMAND, 'builtin', () => (0, scope_gate_1.evaluateScope)(worktreePath, task?.contract.scope ?? null, task?.contract.success.requireScopeClean ?? false, baseRef, task?.contractPath ?? null));
         // A skipped scope gate in the default selection is usually not a declined
         // check: no contract declared a scope, so there was no assertion to test.
         // Counting it would turn every contract-less run into `error` (see
@@ -544,7 +576,7 @@ async function executeRun(db, runId, worktreePath, config, selection, baseRef, t
         // the agent's working window, and the gates below are the repository's own
         // declared commands. A `test:e2e` gate that starts a server would otherwise
         // be reported as the agent leaking one.
-        const outcome = await runGate(verify_config_1.ENV_CLEAN_GATE_ID, ENV_CLEAN_GATE_COMMAND, () => (0, env_clean_gate_1.evaluateEnvClean)({
+        const outcome = await runGate(verify_config_1.ENV_CLEAN_GATE_ID, ENV_CLEAN_GATE_COMMAND, 'builtin', () => (0, env_clean_gate_1.evaluateEnvClean)({
             worktreeId: envClean.worktreeId,
             worktreePath,
             taskId: envClean.taskId,
@@ -559,11 +591,11 @@ async function executeRun(db, runId, worktreePath, config, selection, baseRef, t
             // The server process runs out of this directory. A `build` here replaces
             // the chunks the running app is serving mid-flight and breaks the live UI
             // — observed twice before this guard existed.
-            statuses.push(recordNotRun(gate.id, gate.command, 'skipped: worktreePath is the server process working directory and ' +
+            statuses.push(recordNotRun(gate.id, gate.command, gate.source, 'skipped: worktreePath is the server process working directory and ' +
                 'options.skipInPrimaryCheckout is true.').status);
             continue;
         }
-        const outcome = await runGate(gate.id, gate.command, () => runCommand(gate.command, worktreePath, gate.timeoutSec, maxLogTailBytes));
+        const outcome = await runGate(gate.id, gate.command, gate.source, () => runCommand(gate.command, worktreePath, gate.timeoutSec, maxLogTailBytes));
         statuses.push(outcome.status);
     }
     return aggregateRunStatus(statuses);
@@ -700,12 +732,21 @@ async function startVerification(input) {
     const envCleanDecision = (0, env_clean_gate_1.resolveRequireEnvClean)(task?.contract ?? null, config);
     let selection = null;
     if (config && !configFailure) {
-        const selected = selectGates(config, gateIds, envCleanDecision.required);
-        if (typeof selected === 'string') {
-            configFailure = selected;
+        // Contract gates come from the task this run is actually about (#1791), so
+        // a detached contract contributes none — the same rule `requireCommit`
+        // follows, and for the same reason: that run is not about that contract.
+        const declared = declaredGates(config, task ? (0, contract_message_1.contractGateDefinitions)(task.contract) : []);
+        if (typeof declared === 'string') {
+            configFailure = declared;
         }
         else {
-            selection = selected;
+            const selected = selectGates(declared, gateIds, envCleanDecision.required);
+            if (typeof selected === 'string') {
+                configFailure = selected;
+            }
+            else {
+                selection = selected;
+            }
         }
     }
     const baseRef = config ? await resolveBaseRef(config, input.worktreePath) : null;
@@ -733,6 +774,7 @@ async function startVerification(input) {
         const row = (0, db_1.createGateResult)(db, run.id, {
             gateId: exports.CONFIG_GATE_ID,
             command: verify_config_1.VERIFY_CONFIG_RELATIVE_PATH,
+            source: 'builtin',
         });
         (0, db_1.finishGateResult)(db, row.id, {
             status: 'error',