commandmate 0.19.0 → 0.21.0

package/dist/server/src/lib/db/migrations/v54-worktree-id-path-derived.js

@@ -0,0 +1,204 @@
+"use strict";
+/**
+ * Migration v54: renumber every existing worktree to its path-derived ID
+ * (Issue #1621 Phase 4, delivered by #1645).
+ *
+ * #1644 stopped the ID from moving on its own — `syncWorktreesToDB` now looks a
+ * row up by path and keeps whatever ID it already carries. What it deliberately
+ * did NOT do is touch the rows already in the database: those still hold
+ * `sanitize(repoName)-sanitize(branch)`, so every one of them is still a
+ * branch-derived ID that merely happens to be frozen. The failures #1621
+ * enumerates are only really gone once the stored IDs are the directory's.
+ *
+ * This migration is the one moment the whole table moves at once, which is what
+ * makes the two problems below real rather than theoretical.
+ *
+ * ## Why the renaming is staged through temporary IDs
+ *
+ * One worktree's NEW ID can be another worktree's CURRENT ID. The design's own
+ * example: the directory registered today as `mycodebranchdesk-main` (repo
+ * `MyCodeBranchDesk`, branch `main`) is at `.../commandmate-main`, so its new ID
+ * is `commandmate-main` — which is exactly the shape another row could already
+ * be using. Renaming pairwise would then hit
+ * `renameWorktreeIdPreservingChildren`'s collision branch, which *merges* the
+ * source into the destination and deletes the source row: silent data loss. A
+ * straight swap (A→B, B→A) has no safe ordering at all. Every rename therefore
+ * goes `old → cmate-mig54-<n> → new`, so no intermediate state can collide.
+ *
+ * ## Why an ID is never minted onto an ID somebody else is vacating
+ *
+ * A retired ID does not disappear, it becomes an alias, and live worktrees beat
+ * aliases at resolution time. So if worktree B were handed `x` — the ID worktree
+ * A is retiring — every bookmark of A's `x` would silently start landing on B.
+ * The taken set therefore holds **every current worktree ID** and **every
+ * pre-existing alias**, minus the row's own ID (which it is free to keep). A
+ * blocked candidate falls back to `basename-<sha256(path)[0..8]>`, exactly as a
+ * same-basename collision does.
+ *
+ * ## What follows the move, and what deliberately does not
+ *
+ * Child rows follow through `renameWorktreeIdPreservingChildren`, which
+ * enumerates by `worktree_id` column rather than by declared foreign key — the
+ * only reason `tasks` (#1548), `verification_runs` (#1544) and the aliases
+ * themselves come along. `skill_operations` does NOT: it is an append-only
+ * ledger whose `BEFORE UPDATE ... RAISE(ABORT)` trigger (#1234) would abort this
+ * migration outright. Its rows keep the ID that was in force when they were
+ * written, which is what an audit log is for, and the alias recorded here keeps
+ * them resolvable.
+ *
+ * tmux sessions and in-process state cannot be reached from a migration. They
+ * are reconciled at startup by `reconcileWorktreeSessionsFromAliases`, which
+ * reads the very alias rows this migration writes (`server.ts`).
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.v54_migrations = void 0;
+exports.planWorktreeIdRenumbering = planWorktreeIdRenumbering;
+const path_1 = __importDefault(require("path"));
+const worktree_id_1 = require("../../../lib/git/worktree-id");
+const worktree_id_rename_1 = require("./worktree-id-rename");
+/**
+ * Prefix for the intermediate IDs used by the two-stage renaming.
+ *
+ * Deliberately not a plausible directory basename, and the rows carrying it
+ * exist only between the two loops below — both inside the migration's
+ * transaction, so no reader ever observes one.
+ */
+const TEMP_ID_PREFIX = 'cmate-mig54-';
+/**
+ * Decide the new ID for every worktree row.
+ *
+ * Exported for the unit tests: the planning is the part with the interesting
+ * rules (collision, self-retention, alias shadowing), and it is a pure function
+ * of the rows plus the reserved set.
+ *
+ * @param rows - Every worktree row, `id` and `path`
+ * @param aliasIds - IDs already answerable as aliases
+ * @returns The renames to apply, in row order; rows keeping their ID are omitted
+ * @internal
+ */
+function planWorktreeIdRenumbering(rows, aliasIds) {
+    const currentIds = new Set(rows.map((row) => row.id));
+    const reserved = new Set([...currentIds, ...aliasIds]);
+    const assigned = new Set();
+    const plan = [];
+    for (const row of rows) {
+        const taken = new Set([...reserved, ...assigned]);
+        // A row is never blocked by its own ID: when the directory basename already
+        // equals it, the right answer is "keep it" and no rename is emitted.
+        taken.delete(row.id);
+        const newId = (0, worktree_id_1.deriveWorktreeId)(path_1.default.resolve(row.path), taken);
+        assigned.add(newId);
+        if (newId !== row.id)
+            plan.push({ oldId: row.id, newId });
+    }
+    return plan;
+}
+exports.v54_migrations = [
+    {
+        version: 54,
+        name: 'renumber-worktree-ids-from-path',
+        up: (db) => {
+            const rows = db
+                .prepare('SELECT id, path FROM worktrees ORDER BY id')
+                .all();
+            if (rows.length === 0) {
+                console.log('No worktrees to renumber');
+                return;
+            }
+            const aliasTableExists = db
+                .prepare("SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = 'worktree_aliases'")
+                .get() !== undefined;
+            const aliasIds = aliasTableExists
+                ? db.prepare('SELECT old_id FROM worktree_aliases').all().map((row) => row.old_id)
+                : [];
+            const plan = planWorktreeIdRenumbering(rows, aliasIds);
+            if (plan.length === 0) {
+                console.log(`Worktree IDs already path-derived (${rows.length} row(s) checked)`);
+                return;
+            }
+            // Temporary IDs must not collide with anything real, including an ID this
+            // migration is about to hand out.
+            const inUse = new Set([
+                ...rows.map((row) => row.id),
+                ...aliasIds,
+                ...plan.map((entry) => entry.newId),
+            ]);
+            const tempIds = plan.map((_entry, index) => {
+                let candidate = `${TEMP_ID_PREFIX}${index}`;
+                for (let attempt = 1; inUse.has(candidate); attempt++) {
+                    candidate = `${TEMP_ID_PREFIX}${index}-${attempt}`;
+                }
+                inUse.add(candidate);
+                return candidate;
+            });
+            // A single timestamp for every alias this migration writes, so the rows
+            // read as one event. (`Date.now()` is called once rather than per row for
+            // the same reason.)
+            const now = Date.now();
+            // Stage 1: park every row on an ID nothing else can want.
+            plan.forEach((entry, index) => {
+                (0, worktree_id_rename_1.renameWorktreeIdPreservingChildren)(db, entry.oldId, tempIds[index], now);
+            });
+            // Stage 2: into the real IDs, now guaranteed free.
+            plan.forEach((entry, index) => {
+                (0, worktree_id_rename_1.renameWorktreeIdPreservingChildren)(db, tempIds[index], entry.newId, now);
+            });
+            // Stage 1 recorded `oldId → temp` and stage 2 re-pointed it to
+            // `oldId → newId` (aliases are a child table, so the sweep moved them).
+            // What stage 2 also wrote is `temp → newId`, which is a redirect for an ID
+            // that never left this transaction — drop it so it neither answers
+            // requests nor blocks a future ID.
+            const deleteAlias = aliasTableExists
+                ? db.prepare('DELETE FROM worktree_aliases WHERE old_id = ?')
+                : null;
+            if (deleteAlias) {
+                for (const tempId of tempIds)
+                    deleteAlias.run(tempId);
+            }
+            for (const entry of plan) {
+                console.log(`Renumbered worktree ${entry.oldId} -> ${entry.newId}`);
+            }
+            console.log(`Renumbered ${plan.length} of ${rows.length} worktree(s) to path-derived IDs`);
+        },
+        down: (db) => {
+            // The alias rows record where each ID came from, so the move is reversible
+            // as long as they are still there. Same two-stage staging, in reverse.
+            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 aliases = db
+                .prepare(`SELECT a.old_id, a.worktree_id
+             FROM worktree_aliases AS a
+             JOIN worktrees AS w ON w.id = a.worktree_id
+            ORDER BY a.old_id`)
+                .all();
+            if (aliases.length === 0) {
+                console.log('No worktree aliases to roll back');
+                return;
+            }
+            const now = Date.now();
+            const tempIds = aliases.map((_alias, index) => `${TEMP_ID_PREFIX}down-${index}`);
+            aliases.forEach((alias, index) => {
+                (0, worktree_id_rename_1.renameWorktreeIdPreservingChildren)(db, alias.worktree_id, tempIds[index], now);
+            });
+            aliases.forEach((alias, index) => {
+                (0, worktree_id_rename_1.renameWorktreeIdPreservingChildren)(db, tempIds[index], alias.old_id, now);
+            });
+            const deleteAlias = db.prepare('DELETE FROM worktree_aliases WHERE old_id = ?');
+            for (const tempId of tempIds)
+                deleteAlias.run(tempId);
+            // The forward IDs are now the historical ones; the rollback should not
+            // leave them redirecting back to the IDs it just undid.
+            for (const alias of aliases)
+                deleteAlias.run(alias.worktree_id);
+            console.log(`Rolled back ${aliases.length} worktree ID renumbering(s)`);
+        },
+    },
+];

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-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);
+}