commandmate 0.22.2 → 0.23.0

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

@@ -0,0 +1,175 @@
+"use strict";
+/**
+ * Turn an execution contract into the message the agent actually receives, and
+ * cross-check it against the repository's verify.yaml (Issue #1545, Phase 2-1).
+ *
+ * Canonical spec: docs/design/task-contract.md §5
+ *
+ * The preamble spells the completion criterion out as the *real commands* the
+ * gates will run. A gate id alone tells the agent nothing about what will be
+ * executed, so a contract sent that way declares a criterion the recipient
+ * cannot evaluate.
+ *
+ * Server-only: consumes a loaded VerifyConfig.
+ *
+ * @module lib/tasks/contract-message
+ */
+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.validateContractAgainstVerifyConfig = validateContractAgainstVerifyConfig;
+exports.resolveGateCommands = resolveGateCommands;
+exports.composeContractMessage = composeContractMessage;
+const verify_config_1 = require("../../lib/verification/verify-config");
+/**
+ * How the built-in gates read in the preamble; they run git plumbing, not shell
+ * commands.
+ *
+ * work-evidence has two readings because it has two behaviours. Leaving it on
+ * the permissive wording while `requireCommit` is in force would tell the agent
+ * a criterion the run does not apply — and stating the strict wording while it
+ * is not in force is the D-4 defect (#1628) this Issue closes.
+ */
+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 の内側に収まっていること）`;
+/** 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 の変更も作業証跡として' +
+    '認めるため、commit の有無そのものは検査されない）';
+/** Named so a failing gate can say which declaration put it there. */
+exports.REQUIRE_COMMIT_SOURCE_CONFIG = `options.requireCommit (${verify_config_1.VERIFY_CONFIG_RELATIVE_PATH})`;
+exports.REQUIRE_COMMIT_SOURCE_CONTRACT = 'success.requireCommit (task contract)';
+/**
+ * Combine the repository-wide and per-delegation commit requirements (#1642).
+ *
+ * OR, deliberately, rather than "the nearer declaration wins". The whole point
+ * of the contract-side flag is to stop a rule from being declared and never
+ * checked; letting a contract answer `false` to a repository that answered
+ * `true` would reopen exactly that hole one delegation at a time. A contract can
+ * only ever tighten.
+ *
+ * Lives here rather than in gate-runner because both callers need the same
+ * answer: this module writes the sentence the agent reads, gate-runner reaches
+ * the verdict, and the two disagreeing is the defect being fixed.
+ */
+function resolveRequireCommit(contract, config) {
+    const sources = [];
+    if (config?.options.requireCommit)
+        sources.push(exports.REQUIRE_COMMIT_SOURCE_CONFIG);
+    if (contract?.success.requireCommit)
+        sources.push(exports.REQUIRE_COMMIT_SOURCE_CONTRACT);
+    return { required: sources.length > 0, sources };
+}
+/**
+ * The gate ids a contract asks for, or null for "every gate".
+ *
+ * The `success` flags — not the `verify.gates` list — decide whether the built-in
+ * 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.
+ */
+function resolveContractGateIds(contract) {
+    const gates = contract.verify.gates;
+    if (!gates)
+        return null;
+    const builtIns = [
+        [verify_config_1.WORK_EVIDENCE_GATE_ID, contract.success.requireWorkEvidence],
+        [verify_config_1.SCOPE_GATE_ID, contract.success.requireScopeClean],
+    ];
+    // 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));
+    return [...selected, ...rest];
+}
+/**
+ * Check that every gate the contract names can actually be resolved.
+ *
+ * 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.
+ *
+ * @returns issue strings, empty when the contract resolves cleanly
+ */
+function validateContractAgainstVerifyConfig(contract, config) {
+    const gates = contract.verify.gates;
+    if (!gates)
+        return [];
+    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',
+        ];
+    }
+    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(', ')}`,
+    ];
+}
+/**
+ * The commands the contract's gates will run, in the order they will run.
+ *
+ * Only ever called after {@link validateContractAgainstVerifyConfig} has
+ * accepted the contract, so an unresolvable id cannot reach here.
+ */
+function resolveGateCommands(contract, config) {
+    if (!config)
+        return [];
+    const workEvidenceLabel = resolveRequireCommit(contract, config).required
+        ? WORK_EVIDENCE_COMMIT_LABEL
+        : WORK_EVIDENCE_ANY_CHANGE_LABEL;
+    const builtInLabels = new Map([
+        [verify_config_1.WORK_EVIDENCE_GATE_ID, workEvidenceLabel],
+        [verify_config_1.SCOPE_GATE_ID, SCOPE_LABEL],
+    ]);
+    const selected = resolveContractGateIds(contract);
+    if (!selected) {
+        // An omitted gates list runs every gate, and the built-ins are still governed
+        // by the success flags rather than by the (absent) list.
+        const builtIns = [workEvidenceLabel];
+        if (contract.success.requireScopeClean)
+            builtIns.push(SCOPE_LABEL);
+        return [...builtIns, ...config.gates.map((gate) => gate.command)];
+    }
+    const byId = new Map(config.gates.map((gate) => [gate.id, gate.command]));
+    return selected.map((id) => builtInLabels.get(id) ?? byId.get(id));
+}
+/**
+ * Compose the message sent to the agent: contract preamble, then the goal.
+ *
+ * Every line states an obligation the pipeline can later check, so the agent is
+ * not asked to infer the rules from the goal text.
+ */
+function composeContractMessage(contract, config) {
+    const lines = ['## 実行契約'];
+    lines.push(contract.scope.allow.length > 0
+        ? `- 変更してよいのは次のパスのみ: ${contract.scope.allow.join(', ')}`
+        : '- 変更パスの制限: なし（scope.allow が未宣言）');
+    if (contract.scope.deny.length > 0) {
+        lines.push(`- 変更してはならないパス: ${contract.scope.deny.join(', ')}`);
+    }
+    // The sentence follows the verdict, never the other way round: this line used
+    // to be a constant asserting "未 commit の作業は未完了とみなされる" while the
+    // gate passed on an uncommitted change alone (#1628 D-4, measured in the
+    // Epic #1585 acceptance run).
+    lines.push(resolveRequireCommit(contract, config).required ? COMMIT_REQUIRED_LINE : COMMIT_EXPECTED_LINE);
+    const commands = resolveGateCommands(contract, config);
+    lines.push(commands.length > 0
+        ? `- 完了条件: 次の検証コマンドがすべて成功すること: ${commands.join(' / ')}`
+        : `- 完了条件: ${verify_config_1.VERIFY_CONFIG_RELATIVE_PATH} に検証ゲートが宣言されていないため、検証コマンドは無い`);
+    return `${lines.join('\n')}\n\n## タスク\n${contract.goal}`;
+}

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

@@ -0,0 +1,320 @@
+"use strict";
+/**
+ * Built-in `env-clean` gate: reconcile the machine against the snapshot taken
+ * when the task was created (Issue #1740).
+ *
+ * Canonical spec: docs/design/task-contract.md §2.6
+ *
+ * `scope` closes the question "what did this delegation change inside the
+ * repository". This gate closes the other half. Together they are the first
+ * point at which "what did this delegation change" has a complete answer.
+ *
+ * Two design rules, in order of importance:
+ *
+ *   1. **Never fail open.** A probe that could not answer produces `unknown`,
+ *      the gate reports `error`, and the run fails. Turning an unmeasured probe
+ *      into "nothing changed" is how #1614 shipped a 0 that had never been
+ *      counted, and it is the single failure this gate must not reproduce.
+ *   2. **Additions and removals are judged asymmetrically.** Everything that
+ *      existed at task start must still exist, whoever it belonged to — that is
+ *      the pkill (#1739) and `kill-server` (#1624) case. New things are a
+ *      violation *unless they are attributable to another worker*, because
+ *      parallel delegations legitimately start their own sessions and servers
+ *      inside each other's measurement windows.
+ *
+ * Server-only: consumes snapshots produced by env-snapshot.
+ *
+ * @module lib/verification/env-clean-gate
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ENV_CLEAN_GUIDANCE = exports.MAX_REPORTED_ENV_CHANGES = exports.REQUIRE_ENV_CLEAN_SOURCE_CONTRACT = exports.REQUIRE_ENV_CLEAN_SOURCE_CONFIG = void 0;
+exports.resolveRequireEnvClean = resolveRequireEnvClean;
+exports.attributeSessionName = attributeSessionName;
+exports.attributeAnchor = attributeAnchor;
+exports.diffEnvSnapshots = diffEnvSnapshots;
+exports.formatEnvCleanReport = formatEnvCleanReport;
+exports.envCleanNoBaseline = envCleanNoBaseline;
+exports.evaluateEnvClean = evaluateEnvClean;
+const path_1 = require("path");
+const types_1 = require("../../lib/cli-tools/types");
+const env_snapshot_1 = require("./env-snapshot");
+const verify_config_1 = require("./verify-config");
+// =============================================================================
+// Opt-in resolution
+// =============================================================================
+/** Named so a failing gate can say which declaration switched it on. */
+exports.REQUIRE_ENV_CLEAN_SOURCE_CONFIG = `options.requireEnvClean (${verify_config_1.VERIFY_CONFIG_RELATIVE_PATH})`;
+exports.REQUIRE_ENV_CLEAN_SOURCE_CONTRACT = 'success.requireEnvClean (task contract)';
+/**
+ * Read `success.requireEnvClean` off a contract without depending on the parser
+ * having a field for it.
+ *
+ * `TaskContractSuccess` is a closed key set in `lib/tasks/contract-parser.ts`,
+ * which is outside this delegation's `scope.allow`, so the key cannot be added
+ * to the parser here — a contract that spells it today is rejected at send time
+ * with `unknown key "requireEnvClean"`. Resolving it structurally means the
+ * per-delegation switch starts working the moment the parser opens the key
+ * (`SUCCESS_KEYS` and `TaskContractSuccess`, two lines) with no further change
+ * in this module. See docs/design/task-contract.md §2.6.
+ */
+function contractRequiresEnvClean(contract) {
+    if (!contract)
+        return false;
+    const success = contract.success;
+    return success.requireEnvClean === true;
+}
+/**
+ * Combine the repository-wide and per-delegation switches.
+ *
+ * ORed, never overridden, for the reason `resolveRequireCommit` is: a contract
+ * may tighten a rule the repository left off, but must not be able to switch off
+ * one the repository declared. Both default to false, so a contract that says
+ * nothing leaves every existing verdict exactly as it was.
+ */
+function resolveRequireEnvClean(contract, config) {
+    const sources = [];
+    if (config?.options.requireEnvClean)
+        sources.push(exports.REQUIRE_ENV_CLEAN_SOURCE_CONFIG);
+    if (contractRequiresEnvClean(contract))
+        sources.push(exports.REQUIRE_ENV_CLEAN_SOURCE_CONTRACT);
+    return { required: sources.length > 0, sources };
+}
+/** CLI tool ids, longest first: `vibe-local` must not be stripped as `vibe`. */
+const CLI_PREFIXES = [...types_1.CLI_TOOL_IDS].sort((a, b) => b.length - a.length);
+/**
+ * Attribute an `mcbd-<cli>-<worktreeId>[-suffix]` session name to a worktree.
+ *
+ * Ambiguity resolves towards `self` on purpose. Worktree ids may contain
+ * hyphens, so `mcbd-claude-foo-bar` is genuinely ambiguous between worktree
+ * `foo` with suffix `bar` and worktree `foo-bar`; calling it `self` makes an
+ * addition a violation, and being wrong in that direction costs a false report
+ * rather than a missed leak.
+ */
+function attributeSessionName(name, worktreeId) {
+    if (!name.startsWith(env_snapshot_1.MCBD_SESSION_PREFIX))
+        return 'unattributed';
+    const rest = name.slice(env_snapshot_1.MCBD_SESSION_PREFIX.length);
+    const cli = CLI_PREFIXES.find((id) => rest.startsWith(`${id}-`));
+    if (!cli)
+        return 'unattributed';
+    const tail = rest.slice(cli.length + 1);
+    if (tail === worktreeId || tail.startsWith(`${worktreeId}-`))
+        return 'self';
+    return 'other';
+}
+/**
+ * Attribute a listening process by the directory it runs in.
+ *
+ * Inside this worktree is this task. A *sibling* of this worktree is another
+ * worker — linked worktrees are created side by side, and the primary checkout
+ * the user's production server runs from sits there too, which is what keeps a
+ * parallel delegation and the user's own server from being reported as this
+ * task's leak. Anything else, including a process with no readable cwd, stays
+ * unattributed and is judged.
+ */
+function attributeAnchor(anchor, worktreePath) {
+    if (!anchor)
+        return 'unattributed';
+    const worktree = (0, path_1.resolve)(worktreePath);
+    const path = (0, path_1.resolve)(anchor);
+    if (path === worktree || path.startsWith(worktree + path_1.sep))
+        return 'self';
+    const parent = (0, path_1.dirname)(worktree);
+    // The parent directory itself is not a sibling; a process running there is as
+    // unattributable as one running in `/`.
+    if (path !== parent && path.startsWith(parent + path_1.sep))
+        return 'other';
+    return 'unattributed';
+}
+function attributeEntry(probeId, entry, context) {
+    switch (probeId) {
+        case 'tmux-sessions':
+            return attributeSessionName(entry.key, context.worktreeId);
+        case 'listeners':
+            return attributeAnchor(entry.anchor, context.worktreePath);
+        default:
+            // A file has no owner. `$HOME` and `~/.commandmate` are shared, so an
+            // entry appearing there is a violation for whoever is being judged — the
+            // rule the Issue's incident list is made of.
+            return 'unattributed';
+    }
+}
+function toChange(entry, owner) {
+    return { key: entry.key, detail: entry.detail, owner };
+}
+/**
+ * Compare two snapshots probe by probe.
+ *
+ * A probe is compared only when *both* snapshots answered it. One unavailable
+ * side makes that probe `unknown`: the alternative — treating the missing side
+ * as an empty set — would report every entry as added or removed, which is worse
+ * than useless, and treating it as equal would be the fail-open.
+ */
+function diffEnvSnapshots(baseline, final, context) {
+    const probes = env_snapshot_1.ENV_PROBE_IDS.map((probeId) => {
+        const before = baseline.probes[probeId];
+        const after = final.probes[probeId];
+        if (!before || before.status !== 'ok') {
+            return {
+                probeId,
+                status: 'unknown',
+                reason: `baseline probe unavailable: ${before?.reason ?? 'not recorded'}`,
+                added: [],
+                ignoredAdded: [],
+                removed: [],
+            };
+        }
+        if (!after || after.status !== 'ok') {
+            return {
+                probeId,
+                status: 'unknown',
+                reason: `current probe unavailable: ${after?.reason ?? 'not recorded'}`,
+                added: [],
+                ignoredAdded: [],
+                removed: [],
+            };
+        }
+        const beforeKeys = new Set(before.entries.map((entry) => entry.key));
+        const afterKeys = new Set(after.entries.map((entry) => entry.key));
+        const added = [];
+        const ignoredAdded = [];
+        for (const entry of after.entries) {
+            if (beforeKeys.has(entry.key))
+                continue;
+            const owner = attributeEntry(probeId, entry, context);
+            (owner === 'other' ? ignoredAdded : added).push(toChange(entry, owner));
+        }
+        const removed = before.entries
+            .filter((entry) => !afterKeys.has(entry.key))
+            .map((entry) => toChange(entry, attributeEntry(probeId, entry, context)));
+        return {
+            probeId,
+            status: added.length + removed.length > 0 ? 'violated' : 'clean',
+            reason: null,
+            added,
+            ignoredAdded,
+            removed,
+        };
+    });
+    // A measured violation is a verdict and outranks an unmeasured probe; an
+    // unmeasured probe outranks clean. `clean` requires every probe to have been
+    // compared and to have matched.
+    const status = probes.some((probe) => probe.status === 'violated')
+        ? 'violated'
+        : probes.some((probe) => probe.status === 'unknown')
+            ? 'unknown'
+            : 'clean';
+    return { status, probes };
+}
+// =============================================================================
+// Reporting
+// =============================================================================
+/** Violating entries listed per probe before the rest becomes a count. */
+exports.MAX_REPORTED_ENV_CHANGES = 25;
+/**
+ * Actionable coda, in the same spirit as SCOPE_ALLOW_GUIDANCE: the change list
+ * says what moved but not what to do, and the two directions are genuinely
+ * different actions.
+ */
+exports.ENV_CLEAN_GUIDANCE = 'Anything listed under "+" was started or created during this task and left behind — ' +
+    'stop it by PID and remove it. Anything under "-" existed when the task started and is ' +
+    'now gone — it was killed or deleted; restart or restore it. Never stop a process by ' +
+    'pattern (`pkill -f`): it takes every process whose command line matches, which is how ' +
+    'the production server was stopped in #1739.';
+function formatChanges(sign, changes) {
+    const listed = changes.slice(0, exports.MAX_REPORTED_ENV_CHANGES);
+    const remainder = changes.length - listed.length;
+    const lines = listed.map((change) => {
+        const detail = change.detail ? ` ${change.detail}` : '';
+        return `    ${sign} ${change.key}${detail} [${change.owner}]`;
+    });
+    if (remainder > 0)
+        lines.push(`    ... and ${remainder} more`);
+    return lines;
+}
+/** Render a diff for `log_tail`. */
+function formatEnvCleanReport(diff) {
+    const lines = [];
+    for (const probe of diff.probes) {
+        const label = env_snapshot_1.ENV_PROBE_LABELS[probe.probeId];
+        if (probe.status === 'unknown') {
+            lines.push(`  ${probe.probeId} UNKNOWN (${label}): ${probe.reason ?? 'no reason recorded'}`);
+            continue;
+        }
+        if (probe.status === 'clean') {
+            const excused = probe.ignoredAdded.length > 0
+                ? ` (${probe.ignoredAdded.length} addition(s) attributed to another worktree)`
+                : '';
+            lines.push(`  ${probe.probeId} clean (${label})${excused}`);
+            continue;
+        }
+        lines.push(`  ${probe.probeId} VIOLATED (${label}): +${probe.added.length} -${probe.removed.length}`);
+        lines.push(...formatChanges('+', probe.added));
+        lines.push(...formatChanges('-', probe.removed));
+        for (const excused of probe.ignoredAdded) {
+            lines.push(`    · ${excused.key} (ignored: belongs to another worktree)`);
+        }
+    }
+    return lines.join('\n');
+}
+// =============================================================================
+// Gate evaluation
+// =============================================================================
+/**
+ * Why the gate could not reach a verdict at all, phrased for `log_tail`.
+ *
+ * Spelled out rather than reduced to "no baseline" because the reader's next
+ * question is always "so how do I get one", and the answer — the baseline is
+ * recorded when the task is created, and only when the gate is switched on — is
+ * not guessable from the failure.
+ */
+function envCleanNoBaseline(taskId, sources) {
+    const who = taskId ? `task ${taskId}` : 'this run';
+    const how = sources.length > 0 ? sources.join(' and ') : 'nothing';
+    return (`${verify_config_1.ENV_CLEAN_GATE_ID}: UNKNOWN — no baseline snapshot exists for ${who}, so nothing can be ` +
+        'compared. This is NOT "the environment is unchanged": no measurement was taken. ' +
+        'A baseline is recorded when the task is created (`send --contract`) and only while the ' +
+        `gate is switched on (currently: ${how}). Switch it on, then re-send the task.`);
+}
+/**
+ * Judge the machine against the task's baseline.
+ *
+ * `passed` requires every probe to have been compared and matched. `failed`
+ * means a violation was measured. `error` means no verdict could be reached —
+ * either there is no baseline or a probe would not answer — and it is
+ * deliberately not `skipped`: a skip reads as "there was nothing to judge",
+ * which is the sentence this gate must never say about an unmeasured machine.
+ */
+async function evaluateEnvClean(input) {
+    const startedAt = Date.now();
+    const done = (status, logTail, exitCode) => ({
+        status,
+        exitCode,
+        startedAt,
+        durationMs: Date.now() - startedAt,
+        logTail,
+    });
+    if (!input.baseline) {
+        return done('error', envCleanNoBaseline(input.taskId, input.sources), null);
+    }
+    const capture = input.capture ?? (() => (0, env_snapshot_1.captureEnvSnapshot)({ worktreeId: input.worktreeId }));
+    let final;
+    try {
+        final = await capture();
+    }
+    catch (error) {
+        return done('error', `${verify_config_1.ENV_CLEAN_GATE_ID}: UNKNOWN — the current snapshot could not be taken: ` +
+            `${error instanceof Error ? error.message : String(error)}`, null);
+    }
+    const diff = diffEnvSnapshots(input.baseline, final, input);
+    const header = `${verify_config_1.ENV_CLEAN_GATE_ID}: baseline=${new Date(input.baseline.capturedAt).toISOString()} ` +
+        `status=${diff.status}`;
+    const report = `${header}\n${formatEnvCleanReport(diff)}`;
+    if (diff.status === 'clean')
+        return done('passed', report, 0);
+    if (diff.status === 'unknown') {
+        return done('error', `${report}\nUNKNOWN is not a pass: at least one probe could not be compared, so the ` +
+            'environment was not measured.', null);
+    }
+    return done('failed', `${report}\n${exports.ENV_CLEAN_GUIDANCE}`, 1);
+}