commandmate 0.18.0 → 0.20.0

package/dist/server/src/lib/session/worktree-session-reconcile.js

@@ -0,0 +1,603 @@
+"use strict";
+/**
+ * Make everything that is keyed on a worktree ID *outside* the database follow
+ * that ID when it moves (Issue #1621, Phase 3).
+ *
+ * `migrateWorktreeIdPreservingChildren` already moves the rows. What it cannot
+ * touch is the state that lives beyond SQLite and is derived from the ID rather
+ * than stored:
+ *
+ * - tmux session names — `mcbd-{cli}-{worktreeId}[-{suffix}]` is a *derived*
+ *   value (`cli-tools/base.ts`), so the running agent keeps its process but
+ *   vanishes from the UI, and the app will happily start a **second** agent in
+ *   the same directory (Issue #1621 (a));
+ * - Auto-Yes state, response pollers, control-mode attaches and WebSocket rooms
+ *   — all keyed by worktree ID in process memory (Issue #1621 (f)).
+ *
+ * Dropping any one of those produces the same hard-to-diagnose failure: the
+ * session is alive, the UI looks fine, and instructions silently stop arriving.
+ * So every mover here **transfers** its key rather than invalidating it.
+ *
+ * Written for the bulk renumbering in Phase 4, but deliberately not specific to
+ * it: it takes (oldId, newId) pairs and is equally the right call for a future
+ * directory move.
+ *
+ * ## Why the operation is batched and two-staged
+ *
+ * A renumbering moves every ID at once, so one worktree's NEW name can be
+ * another worktree's OLD name — the design's own example is that
+ * `commandmate-main` is the new ID of the directory currently registered as
+ * `mycodebranchdesk-main`. Renaming pairwise in any order eventually hits
+ * "duplicate session: …" and, worse, an A→B / B→A swap has no valid order at
+ * all. Every rename therefore goes through a temporary name first, and the
+ * in-memory movers each detach the whole batch before writing any of it.
+ *
+ * ## Why targets come from the roster, never from `tmux ls | grep`
+ *
+ * `mcbd-claude-<wt>` is a prefix of `mcbd-claude-<wt>-2`, so anything
+ * prefix-based sweeps up a different instance's session (Issue #1156). Targets
+ * are built from `agent_instances` × the CLI tool registry and matched by exact
+ * string equality against the live session list; the tmux operations themselves
+ * go through `exactTarget()`.
+ *
+ * ## …and why prediction alone is not enough (Issue #1661)
+ *
+ * Predicting names can only find sessions whose name the prediction happens to
+ * reproduce. Anything else is not "skipped" — it is never enumerated, so it
+ * cannot be counted, and a pass that left two live sessions stranded reported
+ * `skipped: 0, errors: 0`. Two shapes escape prediction, and both are ordinary
+ * in a database that has been through a renumbering:
+ *
+ * - an additional instance (`mcbd-claude-<wt>-2`) whose `agent_instances` row
+ *   was never written or has since been removed — 45 of 70 worktrees in the
+ *   production database carry no roster rows at all;
+ * - a session whose name embeds an ID *generation* older than the one the
+ *   rename pair names, because it missed an earlier move.
+ *
+ * So the live session list is also read the other way round: each live name is
+ * attributed to a worktree ID by matching against the **exact set of IDs the
+ * database knows** (`worktrees` ∪ `worktree_aliases.old_id` ∪ this pass's
+ * pairs), longest ID first. That is set membership, not a prefix sweep: when
+ * `<wt>-2` is itself a registered worktree, `mcbd-claude-<wt>-2` resolves to
+ * *it* and a rename of `<wt>` leaves it alone — the #1156 misfire, still
+ * refused. When `<wt>-2` is not a worktree, the same name resolves to `<wt>`'s
+ * second instance and follows the move to `mcbd-claude-<new>-2`, never onto
+ * `mcbd-claude-<new>`.
+ *
+ * Live `mcbd-*` sessions that resolve to nothing at all are reported in
+ * `unaccountedSessions` and logged as a warning, because "I could not see it"
+ * must never again be rendered as "there was nothing to see".
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.__internal = void 0;
+exports.reconcileWorktreeSessions = reconcileWorktreeSessions;
+exports.reconcileWorktreeSessionsFromAliases = reconcileWorktreeSessionsFromAliases;
+const manager_1 = require("../../lib/cli-tools/manager");
+const types_1 = require("../../lib/cli-tools/types");
+const validation_1 = require("../../lib/cli-tools/validation");
+const agent_instances_db_1 = require("../../lib/db/agent-instances-db");
+const worktree_alias_db_1 = require("../../lib/db/worktree-alias-db");
+const path_validator_1 = require("../../lib/security/path-validator");
+const tmux_1 = require("../../lib/tmux/tmux");
+const control_mode_tmux_transport_1 = require("../../lib/tmux/control-mode-tmux-transport");
+const auto_yes_manager_1 = require("../../lib/polling/auto-yes-manager");
+const response_poller_1 = require("../../lib/polling/response-poller");
+const ws_server_1 = require("../../lib/ws-server");
+const logger_1 = require("../../lib/logger");
+const logger = (0, logger_1.createLogger)('worktree-session-reconcile');
+/**
+ * Prefix for the intermediate session names used by the two-stage rename.
+ *
+ * Deliberately NOT `mcbd-`: a name under that prefix would be picked up by the
+ * reading-mode key binding's `#{m:mcbd-*,#{session_name}}` guard and by any
+ * human scanning `tmux ls` for CommandMate sessions. These names exist for
+ * microseconds, but a crash mid-pass leaves one behind and it should read as
+ * obviously transient.
+ */
+const TEMP_SESSION_PREFIX = 'cmate-renaming-';
+function emptyResult() {
+    return {
+        renamedSessions: [],
+        skippedSessions: [],
+        unaccountedSessions: [],
+        planSources: { predicted: 0, discovered: 0 },
+        movedAutoYesKeys: [],
+        restartedAutoYesPollers: [],
+        movedPollerKeys: [],
+        movedRooms: [],
+        errors: [],
+    };
+}
+/**
+ * Drop pairs that are no-ops or unsafe, keeping the last mapping for a given
+ * source ID.
+ */
+function normalizeRenames(renames) {
+    const byOldId = new Map();
+    for (const { oldId, newId } of renames) {
+        if (!oldId || !newId || oldId === newId)
+            continue;
+        // The new ID becomes a tmux session-name segment and a URL segment; an ID
+        // that fails validation must never reach either.
+        if (!(0, path_validator_1.isValidWorktreeId)(oldId) || !(0, path_validator_1.isValidWorktreeId)(newId))
+            continue;
+        byOldId.set(oldId, newId);
+    }
+    return Array.from(byOldId, ([oldId, newId]) => ({ oldId, newId }));
+}
+/**
+ * Every (cliToolId, instanceId) pair whose session could belong to this worktree.
+ *
+ * The roster is read for BOTH IDs because the caller may reconcile either side
+ * of the DB move: after `migrateWorktreeIdPreservingChildren` the rows sit under
+ * `newId`, but a caller reconciling ahead of the move still finds them under
+ * `oldId`. The primary instance of every CLI tool is always included — a
+ * worktree that predates the roster (#1000) has no `agent_instances` rows at all
+ * yet can absolutely have a running `mcbd-claude-<id>` session.
+ */
+function collectInstanceTargets(db, rename) {
+    const seen = new Set();
+    const targets = [];
+    const add = (cliToolId, instanceId) => {
+        const key = `${cliToolId}|${instanceId}`;
+        if (seen.has(key))
+            return;
+        seen.add(key);
+        targets.push({ cliToolId, instanceId });
+    };
+    for (const cliToolId of types_1.CLI_TOOL_IDS)
+        add(cliToolId, cliToolId);
+    for (const worktreeId of [rename.newId, rename.oldId]) {
+        let instances;
+        try {
+            instances = (0, agent_instances_db_1.getAgentInstances)(db, worktreeId);
+        }
+        catch {
+            // No agent_instances table (older database) — the primary instances above
+            // already cover the pre-roster shape.
+            continue;
+        }
+        for (const instance of instances) {
+            if ((0, types_1.isCliToolType)(instance.cliTool))
+                add(instance.cliTool, instance.id);
+        }
+    }
+    return targets;
+}
+/** Build the (old session name → new session name) plan for one ID move. */
+function planSessionRenames(db, rename, errors) {
+    const manager = manager_1.CLIToolManager.getInstance();
+    const plans = [];
+    for (const { cliToolId, instanceId } of collectInstanceTargets(db, rename)) {
+        try {
+            const tool = manager.getTool(cliToolId);
+            const oldName = tool.getSessionName(rename.oldId, instanceId);
+            const newName = tool.getSessionName(rename.newId, instanceId);
+            // getSessionName validates already; assert it explicitly so the guarantee
+            // is stated where the name is about to be handed to tmux (Issue #1621).
+            (0, validation_1.validateSessionName)(newName);
+            if (oldName !== newName)
+                plans.push({ oldName, newName, rename, source: 'roster' });
+        }
+        catch (error) {
+            errors.push(`session name for ${rename.oldId}/${instanceId}: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    return plans;
+}
+/**
+ * Every worktree ID this database can vouch for, current or historical.
+ *
+ * This is the set a live session name is matched against, so its completeness
+ * is what keeps the matching exact: an ID that is missing here turns a name
+ * that legitimately belongs to a *different* worktree into a suffix of one that
+ * is moving. Both tables are read with their own try/catch because tests and
+ * the CLI hand around hand-built connections where either may be absent.
+ *
+ * Queried directly rather than through `worktree-db` / `worktree-alias-db` on
+ * purpose: four suites `vi.mock('@/lib/db/worktree-db')`, and importing it here
+ * would make this module inherit those mocks (the same trap that moved
+ * `renameWorktreeIdPreservingChildren` under `migrations/`).
+ *
+ * @param db - Database instance
+ * @param renames - The pairs this pass is applying (their IDs are known by definition)
+ */
+function collectKnownWorktreeIds(db, renames) {
+    const ids = new Set();
+    try {
+        const rows = db.prepare('SELECT id FROM worktrees').all();
+        for (const row of rows)
+            if (row.id)
+                ids.add(row.id);
+    }
+    catch {
+        // No `worktrees` table — nothing current to attribute against.
+    }
+    try {
+        const rows = db.prepare('SELECT old_id FROM worktree_aliases').all();
+        for (const row of rows)
+            if (row.old_id)
+                ids.add(row.old_id);
+    }
+    catch {
+        // Older database without `worktree_aliases` (migration v53).
+    }
+    for (const rename of renames) {
+        ids.add(rename.oldId);
+        ids.add(rename.newId);
+    }
+    return ids;
+}
+/**
+ * Resolve a live tmux session name to (CLI tool, worktree ID, instance suffix).
+ *
+ * `mcbd-<cli>-<id>` and `mcbd-<cli>-<id>-<suffix>` are both valid readings of
+ * the same string, which is the whole of Issue #1156. The tie is broken by
+ * asking the database rather than the string: candidate IDs are tried
+ * **longest first**, and only an exact member of `knownIds` is accepted. So
+ * `mcbd-claude-alpha-2` resolves to worktree `alpha-2` when that worktree
+ * exists, and to `alpha`'s second instance when it does not — and in neither
+ * reading does it resolve to plain `alpha`'s primary session.
+ *
+ * @param name - A live tmux session name
+ * @param knownIds - Every worktree ID the database can vouch for
+ * @returns The attribution, or `null` when nothing in `knownIds` explains the name
+ */
+function attributeSessionName(name, knownIds) {
+    for (const cliToolId of types_1.CLI_TOOL_IDS) {
+        const prefix = `mcbd-${cliToolId}-`;
+        if (!name.startsWith(prefix))
+            continue;
+        // No CLI tool id is a prefix of another, so at most one branch is entered
+        // and the remainder is unambiguously `<id>[-<suffix>]`.
+        const rest = name.slice(prefix.length);
+        let candidate = rest;
+        for (;;) {
+            if (knownIds.has(candidate)) {
+                const suffix = candidate.length === rest.length ? undefined : rest.slice(candidate.length + 1);
+                return { cliToolId, worktreeId: candidate, suffix: suffix || undefined };
+            }
+            const cut = candidate.lastIndexOf('-');
+            if (cut <= 0)
+                return null;
+            candidate = candidate.slice(0, cut);
+        }
+    }
+    return null;
+}
+/**
+ * Read the live session list the other way round: attribute each name to a
+ * worktree ID and plan a rename when that ID is moving (Issue #1661).
+ *
+ * This is what covers the sessions prediction structurally cannot see — an
+ * instance with no roster row, a name left behind by an earlier move — and it
+ * is also the only place that can notice a live `mcbd-*` session nothing
+ * explains, which it records in `result.unaccountedSessions`.
+ */
+function discoverSessionRenames(renames, liveNames, knownIds, result) {
+    const byOldId = new Map(renames.map((rename) => [rename.oldId, rename]));
+    const plans = [];
+    for (const name of liveNames) {
+        if (!name.startsWith('mcbd-'))
+            continue;
+        const attributed = attributeSessionName(name, knownIds);
+        if (!attributed) {
+            result.unaccountedSessions.push(name);
+            continue;
+        }
+        const rename = byOldId.get(attributed.worktreeId);
+        if (!rename)
+            continue;
+        try {
+            const tool = manager_1.CLIToolManager.getInstance().getTool(attributed.cliToolId);
+            // Rebuilt through getSessionName rather than by string surgery so the
+            // suffix convention stays owned by one place (`cli-tools/base.ts`).
+            const instanceId = attributed.suffix
+                ? (0, types_1.buildInstanceId)(attributed.cliToolId, attributed.suffix)
+                : attributed.cliToolId;
+            const newName = tool.getSessionName(rename.newId, instanceId);
+            (0, validation_1.validateSessionName)(newName);
+            if (name !== newName)
+                plans.push({ oldName: name, newName, rename, source: 'live' });
+        }
+        catch (error) {
+            result.errors.push(`attribute session ${name}: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    return plans;
+}
+/**
+ * Merge the predicted and discovered plans, keeping one plan per live session.
+ *
+ * Prediction wins a tie. The two agree wherever both fire; where they disagree
+ * the roster is a positive statement that the instance belongs to this worktree
+ * ("`codex-3` is an instance of `alpha`"), while attribution is an inference
+ * from the name, so the explicit record is the safer of the two to trust.
+ */
+function mergeSessionPlans(predicted, discovered) {
+    const byOldName = new Map();
+    for (const plan of [...predicted, ...discovered]) {
+        if (!byOldName.has(plan.oldName))
+            byOldName.set(plan.oldName, plan);
+    }
+    return Array.from(byOldName.values());
+}
+/** Mint a session name that is free both on the server and within this pass. */
+function allocateTempName(taken, ordinal) {
+    let candidate = `${TEMP_SESSION_PREFIX}${ordinal}`;
+    let attempt = 0;
+    while (taken.has(candidate)) {
+        attempt++;
+        candidate = `${TEMP_SESSION_PREFIX}${ordinal}-${attempt}`;
+    }
+    taken.add(candidate);
+    return candidate;
+}
+/**
+ * Rename the live tmux sessions in two stages so no intermediate state collides.
+ */
+async function renameSessionsTwoStage(plans, live, deps, result) {
+    if (plans.length === 0)
+        return [];
+    // Exact set membership, never a prefix test (Issue #1156). A predicted name
+    // that is not live is not a miss — it is a name nothing was ever running
+    // under — so it is dropped here rather than counted as skipped; what a pass
+    // could not see at all is reported through `unaccountedSessions` instead.
+    const runnable = plans.filter((plan) => live.has(plan.oldName));
+    const movingNames = new Set(runnable.map((plan) => plan.oldName));
+    const actionable = [];
+    for (const plan of runnable) {
+        // A destination that is occupied by a session this pass is NOT moving
+        // belongs to somebody else. Renaming onto it would fail anyway; skipping
+        // explicitly keeps the reason in the result instead of in an exception.
+        if (live.has(plan.newName) && !movingNames.has(plan.newName)) {
+            result.skippedSessions.push({
+                oldName: plan.oldName,
+                newName: plan.newName,
+                reason: 'destination session already exists',
+            });
+            continue;
+        }
+        actionable.push(plan);
+    }
+    const taken = new Set([...live, ...actionable.map((plan) => plan.newName)]);
+    const staged = [];
+    // Stage 1: everything out of the way, into names nothing else can claim.
+    for (const [index, plan] of actionable.entries()) {
+        const tempName = allocateTempName(taken, index);
+        try {
+            const renamed = await deps.renameSession(plan.oldName, tempName);
+            if (renamed) {
+                staged.push({ plan, tempName });
+            }
+            else {
+                // Disappeared between the listing and now (the agent exited).
+                result.skippedSessions.push({
+                    oldName: plan.oldName,
+                    newName: plan.newName,
+                    reason: 'session no longer exists',
+                });
+            }
+        }
+        catch (error) {
+            result.errors.push(`stage session ${plan.oldName}: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    // Stage 2: into the real names, now guaranteed free.
+    const completed = [];
+    for (const { plan, tempName } of staged) {
+        try {
+            await deps.renameSession(tempName, plan.newName);
+            result.renamedSessions.push({ oldName: plan.oldName, newName: plan.newName });
+            completed.push(plan);
+            // The control-mode attach survived the rename; only the registry key is
+            // stale. Re-file it so terminal input keeps reaching the session.
+            try {
+                (0, control_mode_tmux_transport_1.getControlModeTmuxTransport)().renameSession(plan.oldName, plan.newName);
+            }
+            catch (error) {
+                result.errors.push(`control-mode rekey ${plan.oldName}: ${error instanceof Error ? error.message : String(error)}`);
+            }
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            result.errors.push(`rename session ${plan.oldName} -> ${plan.newName}: ${message}`);
+            // Put it back under a name a human can find rather than leaving it parked
+            // on a temporary one.
+            try {
+                await deps.renameSession(tempName, plan.oldName);
+            }
+            catch {
+                result.errors.push(`session left under temporary name ${tempName}`);
+            }
+        }
+    }
+    return completed;
+}
+/**
+ * Move the in-process state that is keyed on a worktree ID.
+ *
+ * Runs for every requested pair, not only the ones that had a live tmux
+ * session: a WebSocket room or an Auto-Yes state can exist without a session,
+ * and leaving either behind is exactly the silent breakage this guards against.
+ */
+function migrateRuntimeState(db, renames, result) {
+    // --- Auto-Yes -------------------------------------------------------------
+    // Snapshot which pollers are running BEFORE the state moves: startAutoYesPolling
+    // refuses to start when the state at its key is not enabled, so the state has
+    // to move first, and the "was it running?" answer only exists beforehand.
+    const runningAutoYesPollers = new Set((0, auto_yes_manager_1.getAutoYesPollerCompositeKeys)());
+    const movedAutoYes = (0, auto_yes_manager_1.migrateAutoYesStateWorktreeIds)(renames);
+    result.movedAutoYesKeys = movedAutoYes.map((move) => move.newKey);
+    for (const move of movedAutoYes) {
+        if (!runningAutoYesPollers.has(move.oldKey))
+            continue;
+        try {
+            // The poller's timer chain captures the worktree ID, so re-keying its map
+            // would leave it polling the old session. Stop and restart instead — the
+            // Auto-Yes *state* (deadline, stop pattern) is what must survive, and it
+            // already has.
+            (0, auto_yes_manager_1.stopAutoYesPolling)(move.oldKey);
+            const started = (0, auto_yes_manager_1.startAutoYesPolling)(move.newWorktreeId, move.cliToolId, move.instanceId);
+            if (started.started) {
+                result.restartedAutoYesPollers.push(move.newKey);
+            }
+            else {
+                result.errors.push(`auto-yes poller ${move.newKey} not restarted: ${started.reason}`);
+            }
+        }
+        catch (error) {
+            result.errors.push(`auto-yes poller ${move.newKey}: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    // --- Response pollers -----------------------------------------------------
+    // The poller key carries the instance but not the CLI tool, so the roster
+    // supplies it. Both IDs are consulted for the same reason as the session plan.
+    const rosterCliTool = (worktreeId, instanceId) => {
+        const target = renames.find((rename) => rename.oldId === worktreeId);
+        for (const candidate of [target?.newId, worktreeId]) {
+            if (!candidate)
+                continue;
+            try {
+                for (const instance of (0, agent_instances_db_1.getAgentInstances)(db, candidate)) {
+                    if (instance.id === instanceId && (0, types_1.isCliToolType)(instance.cliTool)) {
+                        return instance.cliTool;
+                    }
+                }
+            }
+            catch {
+                // No roster available; fall through to the primary-instance anchor.
+            }
+        }
+        // The primary instance is anchored by `instanceId === cliToolId` (#868), so
+        // an instance id that names a tool IS that tool.
+        return (0, types_1.isCliToolType)(instanceId) ? instanceId : null;
+    };
+    try {
+        result.movedPollerKeys = (0, response_poller_1.migrateResponsePollerWorktreeIds)(renames, rosterCliTool).map((move) => move.newKey);
+    }
+    catch (error) {
+        result.errors.push(`response pollers: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    // --- WebSocket rooms ------------------------------------------------------
+    try {
+        result.movedRooms = (0, ws_server_1.migrateWorktreeRooms)(renames);
+    }
+    catch (error) {
+        result.errors.push(`websocket rooms: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+async function reconcileWorktreeSessions(db, renamesOrOldId, newIdOrOptions, maybeOptions) {
+    const requested = typeof renamesOrOldId === 'string'
+        ? [{ oldId: renamesOrOldId, newId: String(newIdOrOptions ?? '') }]
+        : renamesOrOldId;
+    const options = typeof renamesOrOldId === 'string'
+        ? maybeOptions
+        : newIdOrOptions;
+    const result = emptyResult();
+    const renames = normalizeRenames(requested);
+    if (renames.length === 0)
+        return result;
+    const deps = {
+        listSessions: options?.tmux?.listSessions ?? tmux_1.listSessions,
+        renameSession: options?.tmux?.renameSession ?? tmux_1.renameSession,
+    };
+    // Listed once, up front: both the prediction pass and the attribution pass
+    // need it, and it is what makes a startup with nothing stale cost exactly one
+    // `tmux list-sessions`.
+    let live = null;
+    try {
+        live = new Set((await deps.listSessions()).map((session) => session.name));
+    }
+    catch (error) {
+        result.errors.push(`list tmux sessions: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    if (live) {
+        const knownIds = collectKnownWorktreeIds(db, renames);
+        const predicted = renames.flatMap((rename) => planSessionRenames(db, rename, result.errors));
+        const discovered = discoverSessionRenames(renames, live, knownIds, result);
+        const plans = mergeSessionPlans(predicted, discovered);
+        // Counted against the live list, so `predicted` means "predicted AND
+        // found", not "names we guessed at".
+        for (const plan of plans) {
+            if (!live.has(plan.oldName))
+                continue;
+            if (plan.source === 'roster')
+                result.planSources.predicted++;
+            else
+                result.planSources.discovered++;
+        }
+        await renameSessionsTwoStage(plans, live, deps, result);
+    }
+    // Runtime state moves after the sessions: a poller that ticks in between
+    // fails one capture against a name that is briefly gone, which is a logged
+    // warning and self-heals on the next tick. The reverse order would have the
+    // restarted poller address a session that does not exist yet.
+    migrateRuntimeState(db, renames, result);
+    // A live session nobody could account for is the failure this pass used to
+    // report as success (Issue #1661), so it gets its own line at warn level
+    // rather than a zero buried in the summary.
+    if (result.unaccountedSessions.length > 0) {
+        logger.warn('reconcile:unaccounted-sessions', {
+            count: result.unaccountedSessions.length,
+            sessions: result.unaccountedSessions,
+        });
+    }
+    if (result.renamedSessions.length > 0 ||
+        result.errors.length > 0 ||
+        result.unaccountedSessions.length > 0) {
+        logger.info('reconcile:complete', {
+            renames: renames.length,
+            predicted: result.planSources.predicted,
+            discovered: result.planSources.discovered,
+            renamedSessions: result.renamedSessions.length,
+            skipped: result.skippedSessions.length,
+            unaccounted: result.unaccountedSessions.length,
+            errors: result.errors.length,
+        });
+    }
+    return result;
+}
+/**
+ * Reconcile every worktree ID move the database still remembers.
+ *
+ * Called at startup, after migrations. `worktree_aliases` is the durable record
+ * of "this ID used to name that worktree", so it is exactly the list of session
+ * names a still-running agent may be sitting under — including the moves the
+ * Phase 4 renumbering has just performed, which is what makes the bulk
+ * migration safe for a server that was restarted with agents alive.
+ *
+ * Idempotent and cheap when there is nothing to do: it lists tmux sessions once
+ * and intersects, so a startup where no old name is live performs one `tmux
+ * list-sessions` and stops. Idempotence survives the attribution pass added in
+ * #1661 for the same reason the prediction pass is idempotent — a session that
+ * already carries the current ID resolves to the *destination* of its rename
+ * pair, which is not a source, so a second run plans nothing.
+ *
+ * A database with no aliases at all still returns immediately without listing:
+ * with no ID on the move there is no session that could be following one.
+ *
+ * @param db - Database instance
+ */
+async function reconcileWorktreeSessionsFromAliases(db, options) {
+    let aliases;
+    try {
+        aliases = (0, worktree_alias_db_1.getAllWorktreeAliases)(db);
+    }
+    catch (error) {
+        const result = emptyResult();
+        result.errors.push(`read worktree aliases: ${error instanceof Error ? error.message : String(error)}`);
+        return result;
+    }
+    return reconcileWorktreeSessions(db, aliases.map((alias) => ({ oldId: alias.oldId, newId: alias.worktreeId })), options);
+}
+/**
+ * @internal Exported so tests can assert the temp-name convention and pin the
+ * live-name attribution rules directly (Issue #1661).
+ */
+exports.__internal = {
+    TEMP_SESSION_PREFIX,
+    allocateTempName,
+    buildCompositeKey: auto_yes_manager_1.buildCompositeKey,
+    attributeSessionName,
+};

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

@@ -69,7 +69,12 @@ const TOP_LEVEL_KEYS = ['version', 'title', 'goal', 'scope', 'verify', 'autoYes'
 const SCOPE_KEYS = ['allow', 'deny'];
 const VERIFY_KEYS = ['gates'];
 const AUTO_YES_KEYS = ['mode', 'allowPromptTypes', 'denyPatterns'];
-const SUCCESS_KEYS = ['requireWorkEvidence', 'requireScopeClean', 'autoVerifyOnStop'];
+const SUCCESS_KEYS = [
+    'requireWorkEvidence',
+    'requireScopeClean',
+    '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 {
@@ -276,6 +281,7 @@ function validateSuccess(value, issues) {
     const success = {
         requireWorkEvidence: true,
         requireScopeClean: true,
+        requireCommit: false,
         autoVerifyOnStop: false,
     };
     if (value === undefined || value === null)
@@ -348,6 +354,16 @@ function parseTaskContract(raw, sourceLabel) {
     if (success.requireScopeClean && scope.allow.length === 0) {
         issues.push('scope.allow: at least one pattern is required while success.requireScopeClean is true');
     }
+    // Same discipline, and the same failure it prevents: the commit requirement is
+    // judged by the work-evidence gate, and `requireWorkEvidence: false` keeps that
+    // gate out of the contract's selection entirely. Accepting the pair would put
+    // "必ず commit" in the preamble with nothing behind it — the exact D-4 defect
+    // this field exists to close.
+    if (success.requireCommit && !success.requireWorkEvidence) {
+        issues.push('success.requireCommit: requires success.requireWorkEvidence to be true ' +
+            '(the commit requirement is judged by the work-evidence gate, which ' +
+            'requireWorkEvidence: false switches off)');
+    }
     if (issues.length > 0)
         throw new TaskContractError(issues);
     return { version: 1, title, goal, scope, verify, autoYes, success };

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

@@ -54,8 +54,30 @@ function transitionTask(current, event) {
             switch (event) {
                 case 'message_sent':
                     return 'running';
+                // Issue #1637: a contract whose very first send never landed is
+                // `cancelled`, not `failed`. The row stays — the audit trail is the
+                // `task_events` entry recording `send_failed` from `pending`, which
+                // says precisely what happened — but the status has to keep the row out
+                // of later contract resolution, and `failed` cannot do that.
+                //
+                // `failed` is deliberately re-openable: VERIFIABLE_TASK_STATUSES
+                // (src/lib/db/tasks-db.ts) includes it so an agent that retries after a
+                // red gate finds its contract again (#1620). A task nothing was ever
+                // sent for has no work to re-judge, yet it is the *most recently
+                // updated* verifiable row, so `getVerifiableTask` hands it to any later
+                // run that has to discover its own task. In #1623 that is exactly what
+                // happened: a send that failed on a cold start left `cbb7fe71`, the
+                // re-send created `88280de0` which finished `succeeded` — and
+                // `succeeded` is excluded from resolution while the orphan was not, so
+                // the orchestrator's `wait --verify` judged the worktree against the
+                // orphan's *older* scope snapshot and returned exit 20 for paths the
+                // current contract allows.
+                //
+                // `cancelled` is in neither ACTIVE_TASK_STATUSES nor
+                // VERIFIABLE_TASK_STATUSES, so it closes that path at the only point
+                // this layer controls: the status the event writes.
                 case 'send_failed':
-                    return 'failed';
+                    return 'cancelled';
                 case 'cancel':
                     return 'cancelled';
                 case 'prompt_detected':