commandmate 0.16.0 → 0.17.0

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

@@ -0,0 +1,385 @@
+"use strict";
+/**
+ * Loader and validator for `.commandmate/tasks/<name>.yaml` — the execution
+ * contract (Issue #1545, Phase 2-1).
+ *
+ * Canonical spec: docs/design/task-contract.md
+ *
+ * A contract declares, before the message is ever sent, what the task is for,
+ * which paths may change, what counts as done, and what the auto-answer policy
+ * is. This module only *validates and preserves* those declarations: the scope
+ * gate is #1546 and autoYes enforcement is #1547.
+ *
+ * Written in the same discipline as `lib/verification/verify-config.ts`: the
+ * `yaml` package, every violation collected rather than thrown one at a time,
+ * a closed key set, and a dedicated error class. Note that the Issue body says
+ * "ignore unknown keys" while also requiring that discipline; verify-config
+ * rejects them, and so does this. A misspelled `allowPromtTypes` that parsed
+ * cleanly would produce a contract that looks like it constrains auto-answering
+ * and does not — the worst failure a contract can have.
+ *
+ * Server-only: reads from disk, so import from API routes / CLI only.
+ *
+ * @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.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");
+/** Directory contracts live in, relative to the worktree root. */
+exports.TASK_CONTRACT_DIR = '.commandmate/tasks';
+/**
+ * Auto-answer policy modes.
+ *
+ * A contract that omits `autoYes.mode` leaves the mode `null`, which is *not*
+ * `off`: null means "this contract says nothing about auto-answering, keep the
+ * existing behaviour", while `off` is an active prohibition. Phase 2-3's
+ * enforcement has to be able to tell those apart.
+ */
+exports.AUTO_YES_MODES = ['off', 'safe', 'allow-listed'];
+/**
+ * Prompt-type names accepted in `autoYes.allowPromptTypes`.
+ *
+ * Built from a `Record<PromptType, true>` so the list is exhaustive by
+ * construction: adding a variant to {@link PromptType} without adding it here
+ * fails the build, instead of silently making a valid contract invalid.
+ */
+const PROMPT_TYPE_KEYS = {
+    yes_no: true,
+    multiple_choice: true,
+    approval: true,
+    choice: true,
+    input: true,
+    continue: true,
+};
+exports.PROMPT_TYPES = Object.keys(PROMPT_TYPE_KEYS);
+exports.MAX_TITLE_LENGTH = 200;
+exports.MAX_GOAL_LENGTH = 8000;
+/** Applies to scope patterns and to autoYes.denyPatterns (ReDoS bound). */
+exports.MAX_PATTERN_LENGTH = 200;
+exports.MAX_SCOPE_PATTERNS = 200;
+exports.MAX_GATE_IDS = 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 AUTO_YES_KEYS = ['mode', 'allowPromptTypes', 'denyPatterns'];
+const SUCCESS_KEYS = ['requireWorkEvidence', 'requireScopeClean', '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) {
+        super(`invalid task contract:\n${issues.map((issue) => `  - ${issue}`).join('\n')}`);
+        this.name = 'TaskContractError';
+        this.issues = issues;
+    }
+}
+exports.TaskContractError = TaskContractError;
+function isMapping(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function asInteger(value) {
+    if (typeof value === 'number')
+        return Number.isInteger(value) ? value : null;
+    if (typeof value === 'string' && /^-?\d+$/.test(value))
+        return Number(value);
+    return null;
+}
+function asBoolean(value) {
+    if (typeof value === 'boolean')
+        return value;
+    if (value === 'true')
+        return true;
+    if (value === 'false')
+        return false;
+    return null;
+}
+function describe(value) {
+    if (value === undefined)
+        return 'nothing';
+    if (value === null)
+        return 'null';
+    if (typeof value === 'string')
+        return JSON.stringify(value);
+    if (Array.isArray(value))
+        return 'a list';
+    if (typeof value === 'object')
+        return 'a mapping';
+    return String(value);
+}
+function collectUnknownKeys(mapping, allowed, at, issues) {
+    for (const key of Object.keys(mapping)) {
+        if (!allowed.includes(key)) {
+            issues.push(`${at}: unknown key "${key}" (v1 is a closed set)`);
+        }
+    }
+}
+/**
+ * Validate a list of strings, rejecting per-entry violations individually.
+ *
+ * @returns the accepted entries; entries that produced an issue are dropped so
+ *          the returned contract never carries a value that failed validation
+ */
+function validateStringList(value, at, limits, issues) {
+    if (value === undefined)
+        return null;
+    if (value === null)
+        return [];
+    if (!Array.isArray(value)) {
+        issues.push(`${at}: must be a list (got ${describe(value)})`);
+        return null;
+    }
+    if (value.length > limits.maxEntries) {
+        issues.push(`${at}: at most ${limits.maxEntries} entries (got ${value.length})`);
+        return null;
+    }
+    const accepted = [];
+    value.forEach((entry, index) => {
+        const entryAt = `${at}[${index}]`;
+        if (typeof entry !== 'string' || entry.trim() === '') {
+            issues.push(`${entryAt}: must be a non-empty string (got ${describe(entry)})`);
+            return;
+        }
+        if (entry.length > limits.maxLength) {
+            issues.push(`${entryAt}: at most ${limits.maxLength} characters (got ${entry.length})`);
+            return;
+        }
+        accepted.push(entry);
+    });
+    return accepted;
+}
+/**
+ * A scope pattern can only speak about the inside of the worktree.
+ *
+ * An absolute path or a `..` segment is unjudgeable by the Phase 2-2 gate, and
+ * a NUL byte is never a path — all three are rejected at declaration time
+ * rather than becoming a pattern that silently matches nothing.
+ */
+function validateScopePattern(pattern, at, issues) {
+    if (pattern.includes('\0')) {
+        issues.push(`${at}: must not contain a NUL byte`);
+        return;
+    }
+    if (pattern.startsWith('/')) {
+        issues.push(`${at}: must be relative to the worktree root (got the absolute path "${pattern}")`);
+        return;
+    }
+    if (pattern.split('/').includes('..')) {
+        issues.push(`${at}: must not escape the worktree root with ".." (got "${pattern}")`);
+    }
+}
+function validateScope(value, issues) {
+    const scope = { allow: [], deny: [] };
+    if (value === undefined || value === null)
+        return scope;
+    if (!isMapping(value)) {
+        issues.push(`scope: must be a mapping (got ${describe(value)})`);
+        return scope;
+    }
+    collectUnknownKeys(value, SCOPE_KEYS, 'scope', issues);
+    const limits = { maxEntries: exports.MAX_SCOPE_PATTERNS, maxLength: exports.MAX_PATTERN_LENGTH };
+    for (const key of ['allow', 'deny']) {
+        const list = validateStringList(value[key], `scope.${key}`, limits, issues);
+        if (!list)
+            continue;
+        list.forEach((pattern, index) => validateScopePattern(pattern, `scope.${key}[${index}]`, issues));
+        scope[key] = list;
+    }
+    return scope;
+}
+function validateVerify(value, issues) {
+    if (value === undefined || value === null)
+        return { gates: null };
+    if (!isMapping(value)) {
+        issues.push(`verify: must be a mapping (got ${describe(value)})`);
+        return { gates: null };
+    }
+    collectUnknownKeys(value, VERIFY_KEYS, 'verify', issues);
+    if (value.gates === undefined || value.gates === null)
+        return { gates: null };
+    const gates = validateStringList(value.gates, 'verify.gates', { maxEntries: exports.MAX_GATE_IDS, maxLength: 32 }, issues);
+    if (!gates)
+        return { gates: 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 };
+    }
+    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}`);
+            return;
+        }
+        if (seen.has(id)) {
+            issues.push(`verify.gates[${index}]: duplicate gate id "${id}"`);
+            return;
+        }
+        seen.add(id);
+        valid.push(id);
+    });
+    return { gates: valid.length > 0 ? valid : null };
+}
+function validateAutoYes(value, issues) {
+    const autoYes = { mode: null, allowPromptTypes: [], denyPatterns: [] };
+    if (value === undefined || value === null)
+        return autoYes;
+    if (!isMapping(value)) {
+        issues.push(`autoYes: must be a mapping (got ${describe(value)})`);
+        return autoYes;
+    }
+    collectUnknownKeys(value, AUTO_YES_KEYS, 'autoYes', issues);
+    if (value.mode !== undefined && value.mode !== null) {
+        if (typeof value.mode !== 'string' ||
+            !exports.AUTO_YES_MODES.includes(value.mode)) {
+            issues.push(`autoYes.mode: must be one of ${exports.AUTO_YES_MODES.join(', ')} (got ${describe(value.mode)})`);
+        }
+        else {
+            autoYes.mode = value.mode;
+        }
+    }
+    const promptTypes = validateStringList(value.allowPromptTypes, 'autoYes.allowPromptTypes', { maxEntries: exports.MAX_ALLOW_PROMPT_TYPES, maxLength: 64 }, issues);
+    if (promptTypes) {
+        promptTypes.forEach((type, index) => {
+            if (!exports.PROMPT_TYPES.includes(type)) {
+                issues.push(`autoYes.allowPromptTypes[${index}]: unknown prompt type "${type}" ` +
+                    `(known: ${exports.PROMPT_TYPES.join(', ')})`);
+                return;
+            }
+            autoYes.allowPromptTypes.push(type);
+        });
+    }
+    const denyPatterns = validateStringList(value.denyPatterns, 'autoYes.denyPatterns', { maxEntries: exports.MAX_DENY_PATTERNS, maxLength: exports.MAX_PATTERN_LENGTH }, issues);
+    if (denyPatterns) {
+        denyPatterns.forEach((pattern, index) => {
+            try {
+                new RegExp(pattern);
+            }
+            catch (error) {
+                issues.push(`autoYes.denyPatterns[${index}]: not a valid regular expression: ${error.message}`);
+                return;
+            }
+            autoYes.denyPatterns.push(pattern);
+        });
+    }
+    return autoYes;
+}
+function validateSuccess(value, issues) {
+    const success = {
+        requireWorkEvidence: true,
+        requireScopeClean: true,
+        autoVerifyOnStop: false,
+    };
+    if (value === undefined || value === null)
+        return success;
+    if (!isMapping(value)) {
+        issues.push(`success: must be a mapping (got ${describe(value)})`);
+        return success;
+    }
+    collectUnknownKeys(value, SUCCESS_KEYS, 'success', issues);
+    for (const key of SUCCESS_KEYS) {
+        if (value[key] === undefined)
+            continue;
+        const parsed = asBoolean(value[key]);
+        if (parsed === null) {
+            issues.push(`success.${key}: must be true or false (got ${describe(value[key])})`);
+            continue;
+        }
+        success[key] = parsed;
+    }
+    return success;
+}
+function validateText(value, key, maxLength, issues) {
+    if (typeof value !== 'string' || value.trim() === '') {
+        issues.push(`${key}: required, must be a non-empty string (got ${describe(value)})`);
+        return '';
+    }
+    if (value.length > maxLength) {
+        issues.push(`${key}: at most ${maxLength} characters (got ${value.length})`);
+        return '';
+    }
+    return value.trim();
+}
+/**
+ * Parse and validate a contract document.
+ *
+ * @param raw YAML source
+ * @param sourceLabel path or label used to prefix document-level issues
+ * @throws TaskContractError with every violation collected in `issues`
+ */
+function parseTaskContract(raw, sourceLabel) {
+    let document;
+    try {
+        document = (0, yaml_1.parse)(raw);
+    }
+    catch (error) {
+        throw new TaskContractError([`${sourceLabel}: YAML parse error: ${error.message}`]);
+    }
+    if (!isMapping(document)) {
+        throw new TaskContractError([
+            `${sourceLabel}: expected a YAML mapping at the top level (got ${describe(document)})`,
+        ]);
+    }
+    const issues = [];
+    collectUnknownKeys(document, TOP_LEVEL_KEYS, 'top level', issues);
+    if (!('version' in document)) {
+        issues.push('version: required, v1 contracts must declare "version: 1"');
+    }
+    else if (asInteger(document.version) !== 1) {
+        issues.push(`version: must be 1 (got ${describe(document.version)})`);
+    }
+    const title = validateText(document.title, 'title', exports.MAX_TITLE_LENGTH, issues);
+    const goal = validateText(document.goal, 'goal', exports.MAX_GOAL_LENGTH, issues);
+    const success = validateSuccess(document.success, issues);
+    const scope = validateScope(document.scope, issues);
+    const verify = validateVerify(document.verify, issues);
+    const autoYes = validateAutoYes(document.autoYes, issues);
+    // Checked after both sections are parsed: "keep changes inside scope" with no
+    // scope listed makes the Phase 2-2 gate reject every change the moment it
+    // switches on, so the contract is rejected now instead.
+    if (success.requireScopeClean && scope.allow.length === 0) {
+        issues.push('scope.allow: at least one pattern is required while success.requireScopeClean is true');
+    }
+    if (issues.length > 0)
+        throw new TaskContractError(issues);
+    return { version: 1, title, goal, scope, verify, autoYes, success };
+}
+/**
+ * Read and validate a contract inside a worktree.
+ *
+ * `relativePath` is resolved against `worktreePath` and must stay inside it: a
+ * contract is a statement about one worktree, and a path that leaves it would
+ * let a send read an arbitrary file off the server's disk.
+ *
+ * @throws TaskContractError when the path escapes, the file is unreadable, or
+ *         the document is invalid
+ */
+function loadTaskContract(worktreePath, relativePath) {
+    if (!(0, path_validator_1.isPathSafe)(relativePath, worktreePath)) {
+        throw new TaskContractError([
+            `${relativePath}: contract path must be inside the worktree (${worktreePath})`,
+        ]);
+    }
+    const absolutePath = (0, path_1.join)(worktreePath, relativePath);
+    let raw;
+    try {
+        raw = (0, fs_1.readFileSync)(absolutePath, 'utf8');
+    }
+    catch (error) {
+        const code = error.code;
+        throw new TaskContractError([
+            code === 'ENOENT'
+                ? `${relativePath}: contract file not found in ${worktreePath}`
+                : `${relativePath}: ${error.message}`,
+        ]);
+    }
+    return parseTaskContract(raw, relativePath);
+}

package/dist/server/src/lib/tasks/task-state-machine.js

@@ -0,0 +1,183 @@
+"use strict";
+/**
+ * TaskStatus state machine (Issue #1548, Phase 3-1).
+ *
+ * Pure and side-effect free: given a status and an event, it answers what the
+ * status becomes, or `null` when the event does not apply. Phase 2-1 let each
+ * firing point decide the next status for itself, which meant the rules lived in
+ * six places and agreed with each other only by coincidence. They live here now,
+ * and `applyTaskEvent` is the only thing allowed to act on the answer.
+ *
+ * This is a different layer from `SessionStatus`. SessionStatus is derived from
+ * screen-scraped terminal output — low level, volatile, recomputed every poll.
+ * TaskStatus is durable and only moves because something *happened*. A
+ * SessionStatus reading is at most one of the events that can cause a move; it
+ * never writes TaskStatus itself.
+ *
+ * Rejection is not an error. A prompt detected while a verification run is in
+ * flight is an ordinary race, not a bug, so `transitionTask` returns `null` and
+ * the caller records the attempt and moves on. Throwing would turn a race into
+ * a crashed poller.
+ *
+ * @module lib/tasks/task-state-machine
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TASK_EVENTS = void 0;
+exports.transitionTask = transitionTask;
+exports.TASK_EVENTS = [
+    'message_sent',
+    'send_failed',
+    'prompt_detected',
+    'prompt_answered_auto',
+    'prompt_answered_human',
+    'agent_idle',
+    'verify_started',
+    'verify_passed',
+    'verify_failed',
+    'verify_not_started',
+    'cancel',
+];
+/**
+ * The status `current` becomes when `event` happens, or `null` if it does not
+ * apply.
+ *
+ * Both switches are exhaustive by `satisfies never`, so adding a TaskStatus or a
+ * TaskEvent fails the build here instead of silently defaulting to "rejected" —
+ * a new event that quietly transitions nothing is indistinguishable from one
+ * that is wired up wrong.
+ */
+function transitionTask(current, event) {
+    switch (current) {
+        case 'pending':
+            // Nothing has been sent yet, so nothing about the agent's behaviour can
+            // be true of this task.
+            switch (event) {
+                case 'message_sent':
+                    return 'running';
+                case 'send_failed':
+                    return 'failed';
+                case 'cancel':
+                    return 'cancelled';
+                case 'prompt_detected':
+                case 'prompt_answered_auto':
+                case 'prompt_answered_human':
+                case 'agent_idle':
+                case 'verify_started':
+                case 'verify_passed':
+                case 'verify_failed':
+                case 'verify_not_started':
+                    return null;
+                default:
+                    return assertNever(event);
+            }
+        case 'running':
+            switch (event) {
+                case 'prompt_detected':
+                    return 'waiting_input';
+                // The agent going quiet without a verification run is not a verdict.
+                // The status is held and only the event is recorded, so "it stopped
+                // producing output" stays visible without being mistaken for "done".
+                case 'agent_idle':
+                    return 'running';
+                case 'verify_started':
+                    return 'verifying';
+                case 'send_failed':
+                    return 'failed';
+                case 'cancel':
+                    return 'cancelled';
+                case 'message_sent':
+                case 'prompt_answered_auto':
+                case 'prompt_answered_human':
+                case 'verify_passed':
+                case 'verify_failed':
+                case 'verify_not_started':
+                    return null;
+                default:
+                    return assertNever(event);
+            }
+        case 'waiting_input':
+            switch (event) {
+                case 'prompt_answered_auto':
+                case 'prompt_answered_human':
+                    return 'running';
+                case 'agent_idle':
+                    return 'running';
+                case 'verify_started':
+                    return 'verifying';
+                case 'cancel':
+                    return 'cancelled';
+                case 'message_sent':
+                case 'send_failed':
+                case 'prompt_detected':
+                case 'verify_passed':
+                case 'verify_failed':
+                case 'verify_not_started':
+                    return null;
+                default:
+                    return assertNever(event);
+            }
+        case 'verifying':
+            // A run is in flight. Only that run's verdict — or an explicit cancel —
+            // moves the task, so a prompt or a send racing the gates cannot overwrite
+            // the outcome the gates are about to produce.
+            switch (event) {
+                case 'verify_passed':
+                    return 'succeeded';
+                case 'verify_failed':
+                    return 'failed';
+                case 'verify_not_started':
+                    return 'not_started';
+                case 'cancel':
+                    return 'cancelled';
+                case 'message_sent':
+                case 'send_failed':
+                case 'prompt_detected':
+                case 'prompt_answered_auto':
+                case 'prompt_answered_human':
+                case 'agent_idle':
+                case 'verify_started':
+                    return null;
+                default:
+                    return assertNever(event);
+            }
+        case 'failed':
+        case 'not_started':
+            // Not the end of the story. Re-instructing an agent whose work did not
+            // pass reopens the same task, and the number of times that happens is the
+            // fix-loop count Phase 4 Eval reports. Re-running the gates alone reopens
+            // it too — a task can fail on a flaky gate and pass on the retry.
+            switch (event) {
+                case 'message_sent':
+                    return 'running';
+                case 'verify_started':
+                    return 'verifying';
+                case 'cancel':
+                    return 'cancelled';
+                case 'send_failed':
+                case 'prompt_detected':
+                case 'prompt_answered_auto':
+                case 'prompt_answered_human':
+                case 'agent_idle':
+                case 'verify_passed':
+                case 'verify_failed':
+                case 'verify_not_started':
+                    return null;
+                default:
+                    return assertNever(event);
+            }
+        case 'succeeded':
+        case 'cancelled':
+            // Closed for good. `succeeded` in particular is a verdict a verification
+            // run produced; letting any later event walk it back would make "this
+            // task passed" a claim with no fixed meaning.
+            return null;
+        default:
+            return assertNever(current);
+    }
+}
+/** Compile-time exhaustiveness guard; unreachable at runtime. */
+function assertNever(value) {
+    const _exhaustive = value;
+    void _exhaustive;
+    return null;
+}

package/dist/server/src/lib/tasks/task-transition-service.js

@@ -0,0 +1,106 @@
+"use strict";
+/**
+ * The only writer of `tasks.status` (Issue #1548, Phase 3-1).
+ *
+ * `applyTaskEvent` reads the current status, asks the state machine what the
+ * event means, and — in one transaction — writes the new status and appends the
+ * event. Phase 2-1 had each firing point call `updateTaskStatus` with a status
+ * it chose itself; `updateTaskStatus` is no longer reachable from the
+ * `@/lib/db` barrel so that this is the only door.
+ *
+ * A rejected transition still writes a `task_events` row (`to_status = NULL`).
+ * The event happened; the machine declined to act on it. That distinction is
+ * what tells a wiring bug apart from a race, and it is invisible if rejected
+ * events are dropped.
+ *
+ * The UPDATE and the INSERT are one transaction because a status with no event
+ * behind it, or an event whose status never landed, would each make the log
+ * lie about the table it exists to explain. better-sqlite3 is synchronous, so a
+ * transaction here also serialises concurrent callers with no further work.
+ *
+ * @module lib/tasks/task-transition-service
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.applyTaskEvent = applyTaskEvent;
+exports.applyEventToActiveTask = applyEventToActiveTask;
+const tasks_db_1 = require("../../lib/db/tasks-db");
+const task_events_db_1 = require("../../lib/db/task-events-db");
+const logger_1 = require("../../lib/logger");
+const task_state_machine_1 = require("./task-state-machine");
+const logger = (0, logger_1.createLogger)('lib/tasks/task-transition-service');
+/**
+ * Apply `event` to a task.
+ *
+ * @param payload - Structured detail for the log. `runId` is also written to
+ *   `tasks.last_verification_run_id` on an accepted transition, so the task's
+ *   pointer to the run that last judged it and the event naming that run cannot
+ *   disagree.
+ * @returns null when the task does not exist — a deleted worktree takes its
+ *   tasks with it, and a poller still holding the id must not crash for it
+ */
+function applyTaskEvent(db, taskId, event, payload) {
+    const apply = db.transaction(() => {
+        const task = (0, tasks_db_1.getTask)(db, taskId);
+        if (!task) {
+            return null;
+        }
+        const fromStatus = task.status;
+        const toStatus = (0, task_state_machine_1.transitionTask)(fromStatus, event);
+        const now = Date.now();
+        const eventId = (0, task_events_db_1.insertTaskEvent)(db, {
+            taskId,
+            event,
+            fromStatus,
+            toStatus,
+            payload,
+            createdAt: now,
+        });
+        if (toStatus === null) {
+            return { task, fromStatus, toStatus: null, eventId };
+        }
+        const updated = (0, tasks_db_1.updateTaskStatus)(db, taskId, toStatus, payload?.runId === undefined ? {} : { lastVerificationRunId: payload.runId });
+        return { task: updated, fromStatus, toStatus, eventId };
+    });
+    const result = apply();
+    if (result === null) {
+        logger.warn('task-event-unknown-task', { taskId, event });
+    }
+    else if (result.toStatus === null) {
+        logger.warn('task-event-rejected', { taskId, event, fromStatus: result.fromStatus });
+    }
+    return result;
+}
+/**
+ * Raise `event` on whichever task is currently governing one agent instance.
+ *
+ * The no-op is the important case. Prompts, auto-answers and human replies
+ * happen constantly in sessions that were never sent a contract, and every
+ * firing point calls this unconditionally — so "no active task" has to mean
+ * "nothing happens", not "nothing to do, but raise something anyway". Anything
+ * else would make Phase 3-1 a behaviour change for contract-less use.
+ *
+ * Never throws: these callers are pollers and API routes whose real job is the
+ * message itself, and a task-log failure must not take that down with it.
+ *
+ * @param instanceId - Agent instance id; the tool id itself for the primary
+ * @returns The result, or null when no active task governs this instance
+ */
+function applyEventToActiveTask(db, worktreeId, cliToolId, instanceId, event, payload) {
+    try {
+        const task = (0, tasks_db_1.getActiveTaskForInstance)(db, worktreeId, cliToolId, instanceId);
+        if (!task) {
+            return null;
+        }
+        return applyTaskEvent(db, task.id, event, payload);
+    }
+    catch (error) {
+        logger.warn('task-event-failed', {
+            worktreeId,
+            cliToolId,
+            instanceId,
+            event,
+            error: error instanceof Error ? error.message : String(error),
+        });
+        return null;
+    }
+}