commandmate 0.18.0 → 0.20.0

package/dist/server/src/lib/db/migrations/v55-compact-churned-worktree-ids.js

@@ -0,0 +1,207 @@
+"use strict";
+/**
+ * Migration v55: fold worktree IDs that ran away back onto their directory name
+ * (Issue #1658).
+ *
+ * ## What went wrong
+ *
+ * `syncWorktreesToDB` resolved "which ID does this path already own?" against
+ * `worktrees.repository_path`, but identity lives in `worktrees.path` — that is
+ * the `NOT NULL UNIQUE` column, one row per directory for the whole table.
+ * `repository_path` only records which scan root last upserted the row, and when
+ * the *same* git repository is registered under two scan roots (a repository and
+ * one of its own linked worktrees, both listed in `WORKTREE_REPOS`),
+ * `git worktree list` returns the identical path set from either one. The column
+ * then ping-pongs, the per-repository lookup came up empty on whichever pass did
+ * not write it last, and the row's ID was re-derived — against a taken set
+ * containing its own current ID and every ID it had already been renamed away
+ * from. `deriveWorktreeId` answered by walking one rung further up the digest
+ * ladder, so every sync appended another 8 hex digits:
+ *
+ *     commandagent-bon0-run
+ *     commandagent-bon0-run-2f4530fe
+ *     commandagent-bon0-run-2f4530fe1cf1f9f8
+ *     commandagent-bon0-run-2f4530fe1cf1f9f85d499f80
+ *     …
+ *
+ * Production reached 81 characters, at which point the tmux session name derived
+ * from the ID no longer matched the running session and the UI lost it.
+ *
+ * ## Why a migration, and not just the fix
+ *
+ * The fix stops the growth; it does not undo it, because it works by *keeping*
+ * whatever ID a path already has. Left alone, those five rows would stay
+ * permanently on their inflated IDs and the abandoned rungs would stay reserved
+ * forever (the minter counts aliases as taken). This migration is the one moment
+ * they are collapsed.
+ *
+ * ## The rules
+ *
+ * - A row is compacted only when re-deriving its ID — with the path's **own**
+ *   history excluded from the taken set, which is precisely what was missing —
+ *   yields something *shorter*. Nothing else moves; a row whose short ID is
+ *   genuinely taken by another directory keeps what it has.
+ * - Another row's ID and another row's alias are never taken. Live worktrees beat
+ *   aliases at resolution, so handing out an ID somebody else still answers to
+ *   would silently redirect their bookmarks (the same rule v54 follows).
+ * - The ID a row is leaving becomes an alias, via
+ *   {@link renameWorktreeIdPreservingChildren} — that is what keeps the URLs,
+ *   open tabs and `commandmate send <id>` lines that were minted during the
+ *   churn answering.
+ * - The **intermediate rungs** are deleted. Every one of them points at the same
+ *   worktree as the rung above it, and none survived longer than the second it
+ *   took the next sync to replace it (the production alias rows are ~1s apart);
+ *   keeping them would reserve those IDs for good. Aliases that are not
+ *   ladder-shaped — `commandagent-develop-develop`, `commandagent-develop-
+ *   detached-1c64d87f`, anything from the branch-derived era — are genuine former
+ *   names and are kept. {@link isDerivedWorktreeId} is what tells them apart.
+ *
+ * No temporary-ID staging (unlike v54): a destination is only ever chosen from
+ * IDs no live row holds, so `renameWorktreeIdPreservingChildren` can never reach
+ * its merge-and-delete collision branch.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.v55_migrations = void 0;
+exports.planWorktreeIdCompaction = planWorktreeIdCompaction;
+const path_1 = __importDefault(require("path"));
+const worktree_id_1 = require("../../../lib/git/worktree-id");
+const worktree_id_rename_1 = require("./worktree-id-rename");
+/**
+ * Decide which rows collapse, and which of their aliases go with them.
+ *
+ * Exported for the unit tests: the rules (self-history exclusion, "shorter
+ * only", ladder-vs-genuine alias) are the interesting part and are a pure
+ * function of the rows plus the aliases.
+ *
+ * @param rows - Every worktree row, `id` and `path`
+ * @param aliases - Every alias row
+ * @internal
+ */
+function planWorktreeIdCompaction(rows, aliases) {
+    const aliasesByTarget = new Map();
+    for (const alias of aliases) {
+        const list = aliasesByTarget.get(alias.worktreeId);
+        if (list)
+            list.push(alias.oldId);
+        else
+            aliasesByTarget.set(alias.worktreeId, [alias.oldId]);
+    }
+    const reserved = new Set([...rows.map((row) => row.id), ...aliases.map((a) => a.oldId)]);
+    const assigned = new Set();
+    const renames = [];
+    const droppedAliasIds = [];
+    for (const row of rows) {
+        const resolvedPath = path_1.default.resolve(row.path);
+        const ownAliasIds = aliasesByTarget.get(row.id) ?? [];
+        // The row's own history cannot block the row: its current ID and every ID it
+        // already answers to are exactly the rungs it is climbing away from.
+        const taken = new Set([...reserved, ...assigned]);
+        taken.delete(row.id);
+        for (const ownAliasId of ownAliasIds)
+            taken.delete(ownAliasId);
+        const newId = (0, worktree_id_1.deriveWorktreeId)(resolvedPath, taken);
+        // Only ever collapse. A longer or equal answer means the short forms are
+        // genuinely spoken for by other directories, and moving would buy nothing.
+        if (newId.length >= row.id.length) {
+            assigned.add(row.id);
+            continue;
+        }
+        assigned.add(newId);
+        renames.push({ oldId: row.id, newId });
+        for (const ownAliasId of ownAliasIds) {
+            // Strictly longer than the ID we are landing on, and of a shape only this
+            // path's own derivation produces: an abandoned rung, nothing else.
+            if (ownAliasId.length > newId.length && (0, worktree_id_1.isDerivedWorktreeId)(ownAliasId, resolvedPath)) {
+                droppedAliasIds.push(ownAliasId);
+            }
+        }
+    }
+    return { renames, droppedAliasIds };
+}
+exports.v55_migrations = [
+    {
+        version: 55,
+        name: 'compact-churned-worktree-ids',
+        up: (db) => {
+            const rows = db
+                .prepare('SELECT id, path FROM worktrees ORDER BY id')
+                .all();
+            if (rows.length === 0) {
+                console.log('No worktrees to compact');
+                return;
+            }
+            const aliasTableExists = db
+                .prepare("SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = 'worktree_aliases'")
+                .get() !== undefined;
+            const aliases = aliasTableExists
+                ? db
+                    .prepare('SELECT old_id, worktree_id FROM worktree_aliases ORDER BY old_id')
+                    .all().map((row) => ({ oldId: row.old_id, worktreeId: row.worktree_id }))
+                : [];
+            const { renames, droppedAliasIds } = planWorktreeIdCompaction(rows, aliases);
+            if (renames.length === 0) {
+                console.log(`No churned worktree IDs to compact (${rows.length} row(s) checked)`);
+                return;
+            }
+            // Drop the abandoned rungs before the rename, so the ID being vacated is
+            // the only historical name this worktree is left with besides its genuine
+            // former names.
+            if (aliasTableExists && droppedAliasIds.length > 0) {
+                const deleteAlias = db.prepare('DELETE FROM worktree_aliases WHERE old_id = ?');
+                for (const aliasId of droppedAliasIds)
+                    deleteAlias.run(aliasId);
+            }
+            // One timestamp for every alias this migration writes, so the rows read as
+            // a single event (same reasoning as v54).
+            const now = Date.now();
+            for (const rename of renames) {
+                (0, worktree_id_rename_1.renameWorktreeIdPreservingChildren)(db, rename.oldId, rename.newId, now);
+                console.log(`Compacted worktree ${rename.oldId} -> ${rename.newId}`);
+            }
+            console.log(`Compacted ${renames.length} of ${rows.length} worktree ID(s); ` +
+                `dropped ${droppedAliasIds.length} intermediate alias(es)`);
+        },
+        down: (db) => {
+            // The inverse is well defined even though the intermediate rungs are gone:
+            // the ID each row was compacted *from* was recorded as an alias by the
+            // rename, and it is the longest ladder-shaped alias the row still has (all
+            // the shorter rungs were deleted on the way forward). Genuine former names
+            // are not ladder-shaped, so they are never mistaken for it.
+            const aliasTableExists = db
+                .prepare("SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = 'worktree_aliases'")
+                .get() !== undefined;
+            if (!aliasTableExists) {
+                console.log('No worktree_aliases table: nothing to roll back');
+                return;
+            }
+            const rows = db
+                .prepare('SELECT id, path FROM worktrees ORDER BY id')
+                .all();
+            const deleteAlias = db.prepare('DELETE FROM worktree_aliases WHERE old_id = ?');
+            const now = Date.now();
+            let restored = 0;
+            for (const row of rows) {
+                const resolvedPath = path_1.default.resolve(row.path);
+                const candidates = db
+                    .prepare('SELECT old_id FROM worktree_aliases WHERE worktree_id = ?')
+                    .all(row.id)
+                    .map((alias) => alias.old_id)
+                    .filter((oldId) => oldId.length > row.id.length && (0, worktree_id_1.isDerivedWorktreeId)(oldId, resolvedPath))
+                    .sort((a, b) => b.length - a.length || a.localeCompare(b));
+                const previousId = candidates[0];
+                if (!previousId)
+                    continue;
+                deleteAlias.run(previousId);
+                (0, worktree_id_rename_1.renameWorktreeIdPreservingChildren)(db, row.id, previousId, now);
+                // The forward ID is now the historical one; the rollback should not
+                // leave it redirecting back to the ID it just undid.
+                deleteAlias.run(row.id);
+                restored++;
+            }
+            console.log(`Rolled back ${restored} worktree ID compaction(s)`);
+        },
+    },
+];

package/dist/server/src/lib/db/migrations/worktree-child-tables.js

@@ -0,0 +1,119 @@
+"use strict";
+/**
+ * Live-schema introspection for "which tables reference a worktree".
+ *
+ * Lives under `migrations/` rather than next to `worktree-db.ts` because the
+ * dependency has to point this way: migration v52 sweeps orphans with the same
+ * enumeration the runtime uses, and a migration that imports `worktree-db.ts`
+ * inherits every mock of it — `vi.mock('@/lib/db/worktree-db')` in an unrelated
+ * suite made `runMigrations` throw `No "getDeletableWorktreeChildTables" export
+ * is defined` (measured across 5 tests). Schema introspection is the more
+ * foundational of the two, so it is what the other side imports.
+ *
+ * Issue #1621.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getWorktreeChildTables = getWorktreeChildTables;
+exports.getWriteGuardedTables = getWriteGuardedTables;
+exports.getDeletableWorktreeChildTables = getDeletableWorktreeChildTables;
+/** Conventional name of the column holding a worktree reference. */
+const WORKTREE_REFERENCE_COLUMN = 'worktree_id';
+/**
+ * Discover every table that references a worktree, along with the referencing
+ * column. Derived dynamically from the live schema so it never drifts out of
+ * sync with future migrations that add child tables.
+ *
+ * Two sources are unioned:
+ *
+ * 1. a `worktree_id` column, **whether or not** the table declares a foreign key
+ * 2. a declared foreign key to `worktrees(id)`, whatever the column is named
+ *
+ * Source 1 is what Issue #1621 adds. FK metadata alone (all this did before)
+ * silently skipped `tasks` (#1548), `verification_runs` (#1544) and
+ * `skill_operations` (#1428): all three carry a `worktree_id` but declare no
+ * constraint, so a rename left them pointing at an ID that no longer exists and
+ * a delete left them behind as orphans — no CASCADE fires without a FK.
+ *
+ * Source 2 is kept so a future table whose FK column is *not* named
+ * `worktree_id` keeps being followed; dropping it would be a regression for
+ * every table #1151 already handled.
+ *
+ * Issue #1151, #1621.
+ */
+function getWorktreeChildTables(db) {
+    const tables = db
+        .prepare("SELECT name FROM sqlite_master WHERE type = 'table' AND name NOT LIKE 'sqlite_%'")
+        .all();
+    const children = [];
+    const seen = new Set();
+    const add = (table, column) => {
+        // JSON encoding keeps the pair unambiguous whatever the identifiers contain.
+        const key = JSON.stringify([table, column]);
+        if (seen.has(key))
+            return;
+        seen.add(key);
+        children.push({ table, column });
+    };
+    for (const { name: tableName } of tables) {
+        if (tableName === 'worktrees')
+            continue;
+        // PRAGMA identifiers cannot be bound; `tableName` comes from sqlite_master,
+        // not user input, so string interpolation here is safe.
+        const columns = db.prepare(`PRAGMA table_info("${tableName}")`).all();
+        if (columns.some((column) => column.name === WORKTREE_REFERENCE_COLUMN)) {
+            add(tableName, WORKTREE_REFERENCE_COLUMN);
+        }
+        const fks = db.prepare(`PRAGMA foreign_key_list("${tableName}")`).all();
+        for (const fk of fks) {
+            if (fk.table === 'worktrees' && (fk.to === 'id' || fk.to === null)) {
+                add(tableName, fk.from);
+            }
+        }
+    }
+    return children;
+}
+/**
+ * Tables the schema itself refuses to let us rewrite, per statement kind.
+ *
+ * An append-only ledger enforces itself with a `BEFORE UPDATE` / `BEFORE DELETE`
+ * trigger that calls `RAISE(ABORT, ...)`; `skill_operations` declares both
+ * (#1234, migrations v44/v48). Such a table carries a `worktree_id` yet is
+ * deliberately *not* owned by its worktree's lifetime: `querySkillOperationAudit`
+ * reads it across every worktree for the dashboard feed, exactly like v51 keeps
+ * `task_events` alive after its task is gone. Sweeping it is not cleanup, it is
+ * destroying audit history — and it does not even fail safely: the trigger
+ * aborts the statement, which rolls back the whole enclosing transaction, so a
+ * blind sweep breaks worktree deletion outright (measured: `deleteWorktreesByIds`
+ * threw `skill_operations is append-only` and the worktree row survived; the
+ * same sweep inside migration v52 fails startup).
+ *
+ * Detected from trigger SQL rather than by table name so a future ledger is
+ * protected the moment it declares its guard (Issue #1621).
+ */
+function getWriteGuardedTables(db) {
+    const triggers = db
+        .prepare("SELECT tbl_name, sql FROM sqlite_master WHERE type = 'trigger'")
+        .all();
+    const noUpdate = new Set();
+    const noDelete = new Set();
+    for (const trigger of triggers) {
+        if (!trigger.sql)
+            continue;
+        if (!/\bRAISE\s*\(\s*ABORT/i.test(trigger.sql))
+            continue;
+        if (/\bBEFORE\s+UPDATE\b/i.test(trigger.sql))
+            noUpdate.add(trigger.tbl_name);
+        if (/\bBEFORE\s+DELETE\b/i.test(trigger.sql))
+            noDelete.add(trigger.tbl_name);
+    }
+    return { noUpdate, noDelete };
+}
+/**
+ * Child tables whose rows a worktree actually owns — everything
+ * getWorktreeChildTables reports, minus the append-only ledgers that outlive it.
+ * This is the set a delete or an orphan sweep may touch (Issue #1621).
+ */
+function getDeletableWorktreeChildTables(db) {
+    const { noDelete } = getWriteGuardedTables(db);
+    return getWorktreeChildTables(db).filter(({ table }) => !noDelete.has(table));
+}

package/dist/server/src/lib/db/migrations/worktree-id-rename.js

@@ -0,0 +1,153 @@
+"use strict";
+/**
+ * Moving a worktree's primary key without losing anything hanging off it.
+ *
+ * Lives under `migrations/` for the same reason `worktree-child-tables.ts` does,
+ * and it is not a stylistic choice: the Phase 4 renumbering (#1645) needs this
+ * logic, and a migration that imports `worktree-db.ts` inherits every
+ * `vi.mock('@/lib/db/worktree-db')` in the suite — four suites do exactly that
+ * today, and it is what made `runMigrations` throw
+ * `No "getDeletableWorktreeChildTables" export is defined` before v52 was moved.
+ * The same reasoning applies to `worktree-alias-db.ts`, so the alias INSERT is
+ * written here and `recordWorktreeAlias` delegates to it rather than the other
+ * way round.
+ *
+ * Issue #1151 (preserve children across a rename), #1621 (FK-less tables,
+ * aliases), #1645 (bulk renumbering).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.recordWorktreeAliasRow = recordWorktreeAliasRow;
+exports.deleteWorktreeChildRows = deleteWorktreeChildRows;
+exports.renameWorktreeIdPreservingChildren = renameWorktreeIdPreservingChildren;
+const worktree_child_tables_1 = require("./worktree-child-tables");
+/** Whether `worktree_aliases` exists in this database. */
+function hasAliasTable(db) {
+    const row = db
+        .prepare("SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = 'worktree_aliases'")
+        .get();
+    return row !== undefined;
+}
+/**
+ * Record that `oldId` used to name the worktree now known as `worktreeId`.
+ *
+ * The implementation behind `recordWorktreeAlias` (`worktree-alias-db.ts`),
+ * kept here so migrations can reach it without importing that module. See that
+ * function's doc comment for the rules; in short:
+ *
+ * - a self-alias is dropped (it would resolve to itself);
+ * - an alias whose `old_id` equals the destination is deleted, because that ID
+ *   names a live worktree again and the live row must win;
+ * - re-recording an existing `old_id` re-points it, so A→B→C resolves A→C in
+ *   one hop rather than a chain.
+ *
+ * @param db - Database instance (caller supplies the transaction, if any)
+ * @param oldId - The ID that is being retired
+ * @param worktreeId - The ID it should resolve to from now on
+ * @param now - Timestamp in epoch milliseconds
+ */
+function recordWorktreeAliasRow(db, oldId, worktreeId, now) {
+    if (!oldId || !worktreeId || oldId === worktreeId)
+        return;
+    if (!hasAliasTable(db))
+        return;
+    // The destination ID now names a live worktree; any alias claiming it as a
+    // historical name is stale and would only confuse resolution.
+    db.prepare('DELETE FROM worktree_aliases WHERE old_id = ?').run(worktreeId);
+    db.prepare(`INSERT INTO worktree_aliases (old_id, worktree_id, created_at)
+     VALUES (?, ?, ?)
+     ON CONFLICT(old_id) DO UPDATE SET
+       worktree_id = excluded.worktree_id,
+       created_at = excluded.created_at`).run(oldId, worktreeId, now);
+}
+/**
+ * Delete every child row pointing at any of `worktreeIds`.
+ *
+ * Deliberately covers *all* deletable child tables, not just the FK-less ones:
+ * doing so makes deletion correct even when `PRAGMA foreign_keys` is off, and
+ * the extra statements against CASCADE tables remove rows that would have been
+ * removed anyway. Append-only ledgers are skipped (see getWriteGuardedTables).
+ * Must run before the parent row is deleted (Issue #1621).
+ */
+function deleteWorktreeChildRows(db, worktreeIds, children = (0, worktree_child_tables_1.getWorktreeChildTables)(db)) {
+    if (worktreeIds.length === 0)
+        return;
+    const { noDelete } = (0, worktree_child_tables_1.getWriteGuardedTables)(db);
+    const placeholders = worktreeIds.map(() => '?').join(',');
+    for (const { table, column } of children) {
+        if (noDelete.has(table))
+            continue;
+        db.prepare(`DELETE FROM "${table}" WHERE "${column}" IN (${placeholders})`).run(...worktreeIds);
+    }
+}
+/**
+ * Rename a worktree row's primary key from `oldId` to `newId`, re-pointing every
+ * child table's foreign key so no CASCADE deletion occurs. This is what makes a
+ * same-directory branch switch preserve chat history and all related data
+ * instead of destroying it (Issue #1151).
+ *
+ * "Every child table" means every table carrying a worktree reference, not just
+ * the ones that declare a foreign key: `tasks`, `verification_runs` and
+ * `skill_operations` do not, and used to be left addressing an ID that no
+ * longer resolves (Issue #1621).
+ *
+ * Append-only ledgers are the one exception, and the schema states it itself —
+ * `skill_operations` aborts any UPDATE (#1234). An immutable audit row records
+ * what happened under the identity in force at the time, and rewriting it is
+ * precisely what its trigger exists to prevent; attempting it does not fail
+ * quietly either, it aborts the enclosing transaction and takes the rename with
+ * it (measured). See getWriteGuardedTables.
+ *
+ * Must be called inside a transaction. `PRAGMA defer_foreign_keys` defers FK
+ * enforcement to COMMIT, letting us repoint the parent PK and its children in
+ * any order without needing `ON UPDATE CASCADE` on every constraint.
+ *
+ * @param db - Database instance
+ * @param oldId - Current primary key
+ * @param newId - Primary key it should have
+ * @param now - Timestamp recorded on the alias row (epoch milliseconds)
+ */
+function renameWorktreeIdPreservingChildren(db, oldId, newId, now = Date.now()) {
+    if (oldId === newId)
+        return;
+    const oldExists = db.prepare('SELECT 1 FROM worktrees WHERE id = ?').get(oldId);
+    if (!oldExists)
+        return;
+    // Defer FK checks until COMMIT so the parent PK and child FKs can be updated
+    // independently. Resets automatically at the end of the transaction.
+    db.pragma('defer_foreign_keys = ON');
+    const newExists = db.prepare('SELECT 1 FROM worktrees WHERE id = ?').get(newId);
+    const { noUpdate } = (0, worktree_child_tables_1.getWriteGuardedTables)(db);
+    const allChildren = (0, worktree_child_tables_1.getWorktreeChildTables)(db);
+    const children = allChildren.filter(({ table }) => !noUpdate.has(table));
+    if (newExists) {
+        // Collision guard. `path` is UNIQUE so two rows for the same directory
+        // should never coexist, but if the DB is already inconsistent keep the
+        // destination row's data and fold in the source's non-conflicting children.
+        for (const { table, column } of children) {
+            db.prepare(`UPDATE OR IGNORE "${table}" SET "${column}" = ? WHERE "${column}" = ?`).run(newId, oldId);
+        }
+        // Conflicting leftovers are dropped explicitly rather than left to CASCADE:
+        // tables without a foreign key never cascade, so relying on the parent
+        // delete alone would strand their rows on a dead ID (#1621).
+        deleteWorktreeChildRows(db, [oldId], allChildren);
+        db.prepare('DELETE FROM worktrees WHERE id = ?').run(oldId);
+        recordWorktreeAliasRow(db, oldId, newId, now);
+        return;
+    }
+    // Normal rename: move the parent PK, then repoint all child rows.
+    db.prepare('UPDATE worktrees SET id = ? WHERE id = ?').run(newId, oldId);
+    for (const { table, column } of children) {
+        db.prepare(`UPDATE "${table}" SET "${column}" = ? WHERE "${column}" = ?`).run(newId, oldId);
+    }
+    // The rename is what retires `oldId`, so this is the one place that knows an
+    // alias is needed. Recording it here (rather than at each call site) means
+    // every path that moves an ID — sync, the #1645 bulk migration, a future
+    // directory move — keeps old URLs and old `commandmate send <id>` lines
+    // answering, without any of them having to remember to.
+    //
+    // Runs AFTER the child sweep on purpose: `worktree_aliases` carries a
+    // `worktree_id`, so the loop above has already re-pointed the aliases this
+    // worktree accumulated earlier. A→B→C therefore leaves A→C and B→C, never a
+    // chain that resolution would have to walk.
+    recordWorktreeAliasRow(db, oldId, newId, now);
+}

package/dist/server/src/lib/db/worktree-alias-db.js

@@ -0,0 +1,155 @@
+"use strict";
+/**
+ * Historical worktree IDs and the worktree they now resolve to (Issue #1621,
+ * Phase 2; table created by migration v53).
+ *
+ * A worktree ID leaks out of the database the moment it is minted: into URLs
+ * the user bookmarks, into tabs they leave open, into `commandmate send <id>`
+ * lines in someone's script. #1644 stops the ID from moving on its own, but IDs
+ * written under the old branch-derived scheme still have to be renumbered
+ * (#1645), and a directory can still be moved. Recording the old ID is what
+ * keeps every one of those references answering instead of 404ing.
+ *
+ * Deliberately free of any dependency on the request/singleton layer: every
+ * function takes the `db` it should act on. The route-boundary wrapper that
+ * reaches for the singleton lives in `@/lib/git/git-route-worktree`.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.recordWorktreeAlias = recordWorktreeAlias;
+exports.resolveWorktreeIdWithAlias = resolveWorktreeIdWithAlias;
+exports.getWorktreeAliases = getWorktreeAliases;
+exports.getAllWorktreeAliases = getAllWorktreeAliases;
+exports.getAliasedWorktreeIds = getAliasedWorktreeIds;
+const worktree_id_rename_1 = require("./migrations/worktree-id-rename");
+/**
+ * Whether `worktree_aliases` exists in this database.
+ *
+ * A database opened by `getDbInstance` is always migrated, but tests hand
+ * hand-built connections around and the CLI can point at an older file. Callers
+ * on the request path must degrade to "no alias" rather than throw, so the
+ * lookups below check first.
+ */
+function hasAliasTable(db) {
+    const row = db
+        .prepare("SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = 'worktree_aliases'")
+        .get();
+    return row !== undefined;
+}
+/**
+ * Record that `oldId` used to name the worktree now known as `worktreeId`.
+ *
+ * Idempotent, and safe to call from inside the rename transaction:
+ *
+ * - a self-alias (`oldId === worktreeId`) is dropped — it would resolve to
+ *   itself and shadow nothing useful;
+ * - an alias whose `old_id` equals the *destination* is deleted, because that
+ *   ID is a live worktree again and the live row must win;
+ * - re-recording an existing `old_id` re-points it (`ON CONFLICT DO UPDATE`),
+ *   so an ID renamed A→B→C resolves A→C in one hop rather than a chain.
+ *
+ * @param db - Database instance (caller supplies the transaction, if any)
+ * @param oldId - The ID that is being retired
+ * @param worktreeId - The ID it should resolve to from now on
+ * @param now - Timestamp in epoch milliseconds
+ */
+function recordWorktreeAlias(db, oldId, worktreeId, now = Date.now()) {
+    // The statements live in `migrations/worktree-id-rename.ts`: the rename that
+    // records the alias has to be callable from a migration, and a migration that
+    // imports a `@/lib/db/*` module inherits every `vi.mock` of it in the suite
+    // (Issue #1621, #1645). This function stays the public entry point.
+    (0, worktree_id_rename_1.recordWorktreeAliasRow)(db, oldId, worktreeId, now);
+}
+/**
+ * Resolve an ID that may be historical to the ID that is current.
+ *
+ * Live worktrees win over aliases, always. An ID can be both — a worktree
+ * created at a directory whose basename matches an ID some other worktree used
+ * to have — and in that case the thing that exists now is the answer.
+ *
+ * @param db - Database instance
+ * @param id - A worktree ID as supplied by a URL, a CLI argument, …
+ * @returns The current worktree ID, or `null` when nothing resolves
+ */
+function resolveWorktreeIdWithAlias(db, id) {
+    if (!id)
+        return null;
+    const live = db.prepare('SELECT 1 FROM worktrees WHERE id = ?').get(id);
+    if (live)
+        return id;
+    if (!hasAliasTable(db))
+        return null;
+    const row = db
+        .prepare('SELECT worktree_id FROM worktree_aliases WHERE old_id = ?')
+        .get(id);
+    if (!row)
+        return null;
+    // An alias pointing at a worktree that is gone is not a redirect, it is a
+    // dangling row (only reachable if foreign keys were off when it was deleted).
+    const target = db.prepare('SELECT 1 FROM worktrees WHERE id = ?').get(row.worktree_id);
+    return target ? row.worktree_id : null;
+}
+/**
+ * Every historical ID recorded for one worktree, newest first.
+ *
+ * @param db - Database instance
+ * @param worktreeId - Current worktree ID
+ */
+function getWorktreeAliases(db, worktreeId) {
+    if (!hasAliasTable(db))
+        return [];
+    const rows = db
+        .prepare(`SELECT old_id, worktree_id, created_at
+       FROM worktree_aliases
+       WHERE worktree_id = ?
+       ORDER BY created_at DESC, old_id ASC`)
+        .all(worktreeId);
+    return rows.map((row) => ({
+        oldId: row.old_id,
+        worktreeId: row.worktree_id,
+        createdAt: row.created_at,
+    }));
+}
+/**
+ * Every alias in the database, oldest first.
+ *
+ * Feeds the startup session reconciliation (Issue #1621 Phase 3/4): each row is
+ * an ID that used to name a worktree, so `mcbd-<cli>-<old_id>` is exactly the
+ * tmux session name a still-running agent may be sitting under. Ordering by
+ * `created_at` makes the pass deterministic; the rename itself is
+ * order-independent because it runs in two stages.
+ *
+ * Returns `[]` rather than throwing when the table has not been created yet, so
+ * a caller on an older database degrades to "nothing to reconcile".
+ *
+ * @param db - Database instance
+ */
+function getAllWorktreeAliases(db) {
+    if (!hasAliasTable(db))
+        return [];
+    const rows = db
+        .prepare(`SELECT old_id, worktree_id, created_at
+       FROM worktree_aliases
+       ORDER BY created_at ASC, old_id ASC`)
+        .all();
+    return rows.map((row) => ({
+        oldId: row.old_id,
+        worktreeId: row.worktree_id,
+        createdAt: row.created_at,
+    }));
+}
+/**
+ * Every ID that is currently answerable as an alias.
+ *
+ * Feeds `deriveWorktreeId`'s taken set: a brand-new worktree must not be minted
+ * an ID that an alias already redirects somewhere else, or the redirect would
+ * be shadowed and one of the two references would start pointing at the wrong
+ * worktree (Issue #1621).
+ *
+ * @param db - Database instance
+ */
+function getAliasedWorktreeIds(db) {
+    if (!hasAliasTable(db))
+        return [];
+    const rows = db.prepare('SELECT old_id FROM worktree_aliases').all();
+    return rows.map((row) => row.old_id);
+}