@zq-silk/yui 0.4.2 → 0.5.0

package/dist/repository/taskWorkspacePreparer.js

@@ -4,9 +4,11 @@ import { isDeepStrictEqual } from "node:util";
 import { retireTaskRoleSessionsForWorkspace } from "../executor/agentExecutor.js";
 import { updateRole } from "../role/role.js";
 import { attachReviewRoundWorkspace, recordReviewWorkspaceDisposition } from "../review/reviewRound.js";
+import { bindTaskWorkspaceIdentity } from "../task/task.js";
 import { createCandidateGitSnapshot, createDirectTaskMainSnapshot, workItemExecutionGroupById, recordWorkItemWorkspaceDisposition } from "../workItem/workItem.js";
 import { createManagedWorkspace, managedWorkspaceKey, managedWorktreeName } from "../worktree/managedWorkspace.js";
 import { NodeGitWorkspace, worktreeIdentity } from "./gitWorkspace.js";
+import { generateTaskWorkspaceIdentity, isLegacyTaskRef, taskArchiveRef, taskMainBranch, taskWorkspaceRefSegment, taskWorkspaceRefSegmentFromIdentity } from "./taskWorkspaceIdentity.js";
 const MAIN_WORKTREE = "main";
 const LEADER_ROLE = "leader";
 export class WorkspaceCleanupBlockedError extends Error {
@@ -99,6 +101,15 @@ export class FileTaskWorkspacePreparer {
         if (existing !== null && existing.owner.type !== "task") {
             throw new Error(`Task main workspace ownership is invalid: ${task.id}.`);
         }
+        // The durable workspace identity is minted once, only for a Task that has
+        // never owned a managed Git workspace. A Task with an existing workspace
+        // record predates the identity (legacy) and keeps its refs until the
+        // controlled rebuild; a second prepare reuses the persisted identity.
+        const workspaceIdentity = task.workspaceIdentity === undefined
+            && (existing === null || existing.entries.length === 0)
+            ? await this.#mintTaskWorkspaceIdentity(task)
+            : undefined;
+        const taskSegment = taskWorkspaceRefSegment(workspaceIdentity === undefined ? task : { ...task, workspaceIdentity });
         const root = this.#taskWorkspaceRoot(task.id);
         const prepared = [];
         const defaultProjects = remoteDefaultProjects(this.store, task.id);
@@ -160,7 +171,7 @@ export class FileTaskWorkspacePreparer {
                 const physical = await this.git.ensureWorktree({
                     repositoryPath: project.path,
                     container: this.#projectContainer(project.name),
-                    taskId: task.id,
+                    taskSegment,
                     roleName: MAIN_WORKTREE,
                     baseRef: previous?.baseCommit ?? baseline.baseRef
                 });
@@ -209,6 +220,12 @@ export class FileTaskWorkspacePreparer {
                 let persistedTask = isDeepStrictEqual(pinnedBindings, latest.projectBindings)
                     ? latest
                     : { ...latest, projectBindings: pinnedBindings, updatedAt: timestamp.toISOString() };
+                if (workspaceIdentity !== undefined) {
+                    // The identity is persisted only now that every managed ref was
+                    // created successfully. A concurrent prepare that bound the same
+                    // identity is a no-op; a different one fails closed.
+                    persistedTask = bindTaskWorkspaceIdentity(persistedTask, workspaceIdentity, timestamp);
+                }
                 if (persistedTask.cwd !== root) {
                     persistedTask = { ...persistedTask, cwd: root, updatedAt: timestamp.toISOString() };
                 }
@@ -236,10 +253,39 @@ export class FileTaskWorkspacePreparer {
             return { taskId, status: "ready", path: root };
         }
         catch (error) {
-            await this.#discardUnadoptedEntries(task, prepared, MAIN_WORKTREE);
+            await this.#discardUnadoptedEntries(task, taskSegment, prepared, MAIN_WORKTREE);
             throw error;
         }
     }
+    /**
+     * Mint the Task's durable workspace identity with create-not-exists
+     * semantics: the candidate main branch must not already exist in any bound
+     * Project repository. On conflict (a stale ref from a crashed attempt, or
+     * another Home's work) a fresh identity is generated; only an identity whose
+     * refs were actually created is ever persisted.
+     */
+    async #mintTaskWorkspaceIdentity(task) {
+        const home = this.store.getHomeIdentity();
+        for (let attempt = 0; attempt < 16; attempt += 1) {
+            const identity = generateTaskWorkspaceIdentity({
+                home,
+                taskId: task.id,
+                now: this.now()
+            });
+            const mainBranch = taskMainBranch(taskWorkspaceRefSegmentFromIdentity(identity));
+            let conflict = false;
+            for (const binding of task.projectBindings) {
+                const project = requireProject(this.store, binding.projectId);
+                if (await this.git.refExists(project.path, mainBranch)) {
+                    conflict = true;
+                    break;
+                }
+            }
+            if (!conflict)
+                return identity;
+        }
+        throw new Error(`Could not mint a unique Task workspace identity for ${task.id}.`);
+    }
     async snapshotCandidateWorkspace(workspace) {
         if (workspace.owner.type === "review-round") {
             throw new Error("ReviewRound workspace cannot become a WorkItem Candidate source.");
@@ -331,6 +377,9 @@ export class FileTaskWorkspacePreparer {
         const task = requireTask(this.store, item.taskId);
         assertWorkItemWorkspaceEligible(this.store, task, item);
         await this.prepareTaskWorkspace(task.id);
+        // prepareTaskWorkspace may have just minted and persisted the workspace
+        // identity; derive the segment from the persisted Task.
+        const taskSegment = this.#taskSegment(requireTask(this.store, task.id));
         const main = this.store.getTaskWorkspace(task.id);
         if (main === null || main.owner.type !== "task") {
             throw new Error(`Task main workspace is not ready: ${task.id}.`);
@@ -378,7 +427,7 @@ export class FileTaskWorkspacePreparer {
                 const physical = await this.git.ensureWorktree({
                     repositoryPath: project.path,
                     container: this.#projectContainer(project.name),
-                    taskId: task.id,
+                    taskSegment,
                     roleName: item.id,
                     baseRef
                 });
@@ -467,7 +516,7 @@ export class FileTaskWorkspacePreparer {
             });
         }
         catch (error) {
-            await this.#discardUnadoptedEntries(task, prepared, item.id);
+            await this.#discardUnadoptedEntries(task, taskSegment, prepared, item.id);
             throw error;
         }
     }
@@ -485,6 +534,7 @@ export class FileTaskWorkspacePreparer {
         if (source === null) {
             throw new Error(`Execution Lane source workspace is not ready: ${executionLaneId}.`);
         }
+        const taskSegment = this.#taskSegment(task);
         const owner = lineage.purpose === "execution"
             ? {
                 type: "execution-lane",
@@ -513,7 +563,7 @@ export class FileTaskWorkspacePreparer {
                 const physical = await this.git.ensureWorktree({
                     repositoryPath: project.path,
                     container: this.#projectContainer(project.name),
-                    taskId,
+                    taskSegment,
                     roleName: managedWorktreeName(owner),
                     baseRef: entry.baseCommit
                 });
@@ -541,7 +591,7 @@ export class FileTaskWorkspacePreparer {
                 const physical = await this.git.ensureWorktree({
                     repositoryPath: project.path,
                     container: this.#projectContainer(project.name),
-                    taskId,
+                    taskSegment,
                     roleName: managedWorktreeName(owner),
                     baseRef: sourceEntry.baseCommit
                 });
@@ -579,7 +629,7 @@ export class FileTaskWorkspacePreparer {
             return workspace;
         }
         catch (error) {
-            await this.#discardUnadoptedEntries(task, prepared, managedWorktreeName(owner), true);
+            await this.#discardUnadoptedEntries(task, taskSegment, prepared, managedWorktreeName(owner), true);
             throw error;
         }
     }
@@ -780,7 +830,7 @@ export class FileTaskWorkspacePreparer {
             && owner.executionLaneId === executionLaneId));
         if (workspace === undefined)
             return "missing";
-        const state = await this.#inspectEntries(taskId, managedWorktreeName(workspace.owner), workspace.entries.filter(({ access }) => access === "write"));
+        const state = await this.#inspectEntries(this.#taskSegment(task), managedWorktreeName(workspace.owner), workspace.entries.filter(({ access }) => access === "write"));
         if (state === "dirty")
             return "dirty";
         let removed = false;
@@ -789,7 +839,7 @@ export class FileTaskWorkspacePreparer {
             const result = await this.git.removeWorktree({
                 repositoryPath: project.path,
                 container: this.#projectContainer(project.name),
-                taskId,
+                taskSegment: this.#taskSegment(task),
                 roleName: managedWorktreeName(workspace.owner),
                 deleteBranch: true
             });
@@ -808,7 +858,9 @@ export class FileTaskWorkspacePreparer {
         }
         if (this.store.getManagedWorkspace(workspace.owner) !== null)
             return "missing";
-        const state = await this.#inspectEntries(workspace.owner.taskId, managedWorktreeName(workspace.owner), workspace.entries.filter(({ access }) => access === "write"));
+        const task = requireTask(this.store, workspace.owner.taskId);
+        const taskSegment = this.#taskSegment(task);
+        const state = await this.#inspectEntries(taskSegment, managedWorktreeName(workspace.owner), workspace.entries.filter(({ access }) => access === "write"));
         if (state === "dirty")
             return "dirty";
         let removed = false;
@@ -817,7 +869,7 @@ export class FileTaskWorkspacePreparer {
             const result = await this.git.removeWorktree({
                 repositoryPath: project.path,
                 container: this.#projectContainer(project.name),
-                taskId: workspace.owner.taskId,
+                taskSegment,
                 roleName: managedWorktreeName(workspace.owner),
                 deleteBranch: true
             });
@@ -878,6 +930,7 @@ export class FileTaskWorkspacePreparer {
      * never used as a ChangeSet capture source. */
     async prepareReviewRoundWorkspace(taskId, reviewRoundId) {
         const task = requireTask(this.store, taskId);
+        const taskSegment = this.#taskSegment(task);
         const round = this.store.getReviewRound(task.id, reviewRoundId);
         if (round === null)
             throw new Error(`ReviewRound not found: ${task.id}/${reviewRoundId}.`);
@@ -915,7 +968,7 @@ export class FileTaskWorkspacePreparer {
                     throw new Error(`Task Review candidate Project is missing: ${binding.projectId}.`);
                 }
                 const project = requireProject(this.store, binding.projectId);
-                const identity = worktreeIdentity(task.id, round.id);
+                const identity = worktreeIdentity(taskSegment, round.id);
                 return {
                     projectId: binding.projectId,
                     directory: binding.directory,
@@ -967,7 +1020,7 @@ export class FileTaskWorkspacePreparer {
                     throw new ReviewRoundWorkspaceEvidenceError(`ReviewRound workspace metadata changed for ${round.id}/${entry.projectId}.`);
                 }
                 const project = requireProject(this.store, entry.projectId);
-                const identity = worktreeIdentity(task.id, round.id);
+                const identity = worktreeIdentity(taskSegment, round.id);
                 const expectedPath = join(this.#projectContainer(project.name), identity.directory);
                 if (entry.path !== expectedPath || entry.branch !== identity.branch) {
                     throw new ReviewRoundWorkspaceEvidenceError(`ReviewRound workspace managed identity mismatch for ${round.id}/${entry.projectId}.`);
@@ -1053,7 +1106,7 @@ export class FileTaskWorkspacePreparer {
                 const physical = await this.git.ensureWorktree({
                     repositoryPath: project.path,
                     container: this.#projectContainer(project.name),
-                    taskId: task.id,
+                    taskSegment,
                     roleName: round.id,
                     baseRef: source.baseCommit
                 });
@@ -1155,11 +1208,12 @@ export class FileTaskWorkspacePreparer {
             });
         }
         catch (error) {
-            await this.#discardUnadoptedEntries(task, prepared, round.id, existing === null, new Set([...retained.values()].map(({ entry }) => entry.path)));
+            await this.#discardUnadoptedEntries(task, taskSegment, prepared, round.id, existing === null, new Set([...retained.values()].map(({ entry }) => entry.path)));
             throw error;
         }
     }
     async inspectReviewRoundWorkspace(taskId, reviewRoundId) {
+        const task = requireTask(this.store, taskId);
         const round = this.store.getReviewRound(taskId, reviewRoundId);
         if (round === null)
             throw new Error(`ReviewRound not found: ${taskId}/${reviewRoundId}.`);
@@ -1170,7 +1224,7 @@ export class FileTaskWorkspacePreparer {
         if (round.workspace !== undefined && !isDeepStrictEqual(round.workspace, workspace)) {
             throw new Error(`ReviewRound workspace record diverged: ${round.id}.`);
         }
-        return this.#inspectEntries(taskId, round.id, workspace.entries);
+        return this.#inspectEntries(this.#taskSegment(task), round.id, workspace.entries);
     }
     async snapshotReviewRoundResult(taskId, reviewRoundId) {
         const round = this.store.getReviewRound(taskId, reviewRoundId);
@@ -1241,13 +1295,13 @@ export class FileTaskWorkspacePreparer {
         return this.#snapshotReviewWorkspaceEntries(round.id, run.workspace);
     }
     async inspectExecutionLaneWorkspace(taskId, executionGroupId, executionLaneId) {
-        requireTask(this.store, taskId);
+        const task = requireTask(this.store, taskId);
         const workspace = this.store.listManagedWorkspaces(taskId).find(({ owner }) => (owner.type === "execution-lane"
             && owner.executionGroupId === executionGroupId
             && owner.executionLaneId === executionLaneId));
         if (workspace === undefined)
             return "missing";
-        return this.#inspectEntries(taskId, managedWorktreeName(workspace.owner), workspace.entries.filter(({ access }) => access === "write"));
+        return this.#inspectEntries(this.#taskSegment(task), managedWorktreeName(workspace.owner), workspace.entries.filter(({ access }) => access === "write"));
     }
     async cleanupReviewRoundWorkspace(taskId, reviewRoundId) {
         const task = requireTask(this.store, taskId);
@@ -1271,7 +1325,7 @@ export class FileTaskWorkspacePreparer {
         for (const lane of round.executionGroup?.lanes ?? []) {
             assertWorkspaceSessionsRetirable(this.store, task.id, lane.roleName, this.now());
         }
-        if (await this.#inspectEntries(task.id, managedWorktreeName(workspace.owner), workspace.entries) === "dirty")
+        if (await this.#inspectEntries(this.#taskSegment(task), managedWorktreeName(workspace.owner), workspace.entries) === "dirty")
             return "dirty";
         let removed = false;
         for (const entry of workspace.entries) {
@@ -1279,7 +1333,7 @@ export class FileTaskWorkspacePreparer {
             const result = await this.git.removeWorktree({
                 repositoryPath: project.path,
                 container: this.#projectContainer(project.name),
-                taskId: task.id,
+                taskSegment: this.#taskSegment(task),
                 roleName: managedWorktreeName(workspace.owner),
                 deleteBranch: true
             });
@@ -1336,7 +1390,7 @@ export class FileTaskWorkspacePreparer {
                 assertWorkspaceSessionsRetirable(this.store, task.id, lane.roleName, this.now());
             }
         const writable = workspace.entries.filter(({ access }) => access === "write");
-        if (await this.#inspectEntries(task.id, managedWorktreeName(workspace.owner), writable) === "dirty")
+        if (await this.#inspectEntries(this.#taskSegment(task), managedWorktreeName(workspace.owner), writable) === "dirty")
             return "dirty";
         let removed = false;
         for (const entry of writable) {
@@ -1344,7 +1398,7 @@ export class FileTaskWorkspacePreparer {
             const result = await this.git.removeWorktree({
                 repositoryPath: project.path,
                 container: this.#projectContainer(project.name),
-                taskId: task.id,
+                taskSegment: this.#taskSegment(task),
                 roleName: managedWorktreeName(workspace.owner),
                 deleteBranch: true
             });
@@ -1375,7 +1429,7 @@ export class FileTaskWorkspacePreparer {
         if (main.owner.type !== "task") {
             throw new Error(`Task main workspace ownership is invalid: ${task.id}.`);
         }
-        return this.#inspectEntries(task.id, MAIN_WORKTREE, main.entries);
+        return this.#inspectEntries(this.#taskSegment(task), MAIN_WORKTREE, main.entries);
     }
     async cleanupTaskForArchive(taskId) {
         const task = requireTask(this.store, taskId);
@@ -1393,7 +1447,7 @@ export class FileTaskWorkspacePreparer {
         const main = this.store.getTaskWorkspace(task.id);
         if (main !== null) {
             assertTaskArchiveState(requireTask(this.store, task.id), task);
-            if (await this.#inspectEntries(task.id, MAIN_WORKTREE, main.entries) === "dirty") {
+            if (await this.#inspectEntries(this.#taskSegment(task), MAIN_WORKTREE, main.entries) === "dirty") {
                 return {
                     taskId,
                     status: "retained-dirty",
@@ -1406,7 +1460,7 @@ export class FileTaskWorkspacePreparer {
                 const result = await this.git.removeWorktree({
                     repositoryPath: project.path,
                     container: this.#projectContainer(project.name),
-                    taskId: task.id,
+                    taskSegment: this.#taskSegment(task),
                     roleName: MAIN_WORKTREE
                 });
                 if (result === "dirty") {
@@ -1421,7 +1475,203 @@ export class FileTaskWorkspacePreparer {
         this.#clearTaskWorkspace(task, this.#fallbackWorkspace());
         return { taskId, status: "removed" };
     }
-    async #inspectEntries(taskId, roleName, entries) {
+    /**
+     * Rebuild an eligible legacy Task's managed Git workspace under a fresh
+     * workspace identity. Legacy refs are archived (never deleted outright),
+     * the new main worktrees start from verified remote SHAs, and the Task
+     * record switches only after every Git side effect succeeded, so a crash
+     * at any point leaves the old layout usable and the command resumable.
+     *
+     * A Task that already carries an identity takes the resume path: only the
+     * pending legacy archive and old-worktree removal run.
+     */
+    async rebuildTaskWorkspace(taskId) {
+        const task = requireTask(this.store, taskId);
+        if (!["draft", "active"].includes(task.status)) {
+            throw new Error(`Only a draft or active Task can be rebuilt in place: ${task.id}/${task.status}.`);
+        }
+        if (task.workspaceIdentity !== undefined) {
+            const current = this.store.getTaskWorkspace(task.id);
+            if (current !== null && current.owner.type === "task") {
+                await ensureWorkspaceView(current.root, current.entries);
+            }
+            // Remove the legacy worktrees before archiving their refs: a worktree
+            // whose checked-out branch was just deleted reports an unborn-branch
+            // ("dirty") status and can no longer be removed cleanly.
+            await this.#removeLegacyWorktrees(task, this.store.listProjects().map((project) => project.id));
+            const archived = await this.#archiveLegacyRefs(task);
+            return { task: requireTask(this.store, task.id), archived, resumed: true };
+        }
+        assertTaskHasNoEvidence(this.store, task.id);
+        const existing = this.store.getTaskWorkspace(task.id);
+        if (existing !== null && existing.owner.type !== "task") {
+            throw new Error(`Task main workspace ownership is invalid: ${task.id}.`);
+        }
+        if (existing !== null
+            && await this.#inspectEntries(task.id, MAIN_WORKTREE, existing.entries) === "dirty") {
+            throw new Error(`Task workspace is dirty and blocks the rebuild: ${task.id}.`);
+        }
+        // Resolve verified remote SHAs before any Git side effect, mirroring the
+        // first-prepare pinning: a remote default Project is fetched and its
+        // exact advertised SHA is pinned; a local or explicit ref is validated.
+        const defaultProjects = remoteDefaultProjects(this.store, task.id);
+        const pins = new Map();
+        for (const binding of task.projectBindings) {
+            const project = requireProject(this.store, binding.projectId);
+            const useRemoteDefault = defaultProjects.has(project.id)
+                && project.remoteUrl !== undefined
+                && !looksLikeCommit(binding.baseRef);
+            if (useRemoteDefault) {
+                const resolver = this.git.resolveRemoteBaseline;
+                if (typeof resolver !== "function") {
+                    throw new Error(`Git workspace cannot resolve the remote baseline for Project: ${project.id}.`);
+                }
+                const remote = await resolver.call(this.git, {
+                    repositoryPath: project.path,
+                    remoteUrl: project.remoteUrl,
+                    // The binding captured the configured development ref at Task
+                    // creation; use that snapshot even if the Project catalog changed.
+                    developmentRef: binding.baseRef
+                });
+                pins.set(project.id, remote.commit);
+            }
+            else {
+                await this.git.inspect(project.path, binding.baseRef);
+            }
+        }
+        const identity = await this.#mintTaskWorkspaceIdentity(task);
+        const taskSegment = taskWorkspaceRefSegmentFromIdentity(identity);
+        const root = this.#taskWorkspaceRoot(task.id);
+        const prepared = [];
+        try {
+            for (const binding of task.projectBindings) {
+                const project = requireProject(this.store, binding.projectId);
+                const baseRef = pins.get(project.id) ?? binding.baseRef;
+                const physical = await this.git.ensureWorktree({
+                    repositoryPath: project.path,
+                    container: this.#projectContainer(project.name),
+                    taskSegment,
+                    roleName: MAIN_WORKTREE,
+                    baseRef
+                });
+                if (pins.has(project.id) && physical.baseCommit !== pins.get(project.id)) {
+                    throw new Error(`Task Project workspace did not start at the fetched remote baseline: ${project.id}.`);
+                }
+                prepared.push({
+                    project,
+                    entry: {
+                        projectId: project.id,
+                        directory: binding.directory,
+                        access: "write",
+                        path: physical.path,
+                        branch: physical.branch,
+                        baseRef,
+                        baseCommit: physical.baseCommit
+                    }
+                });
+            }
+            await ensureWorkspaceView(root, prepared.map(({ entry }) => entry));
+            const workspace = createManagedWorkspace({
+                owner: { type: "task", taskId: task.id },
+                root,
+                entries: prepared.map(({ entry }) => entry)
+            }, this.now());
+            // Switch the durable record only now that every new ref/worktree exists.
+            this.store.transaction((tx) => {
+                const latest = requireTask(tx, task.id);
+                if (!["draft", "active"].includes(latest.status)
+                    || latest.workspaceIdentity !== undefined
+                    || !isDeepStrictEqual(latest.projectBindings, task.projectBindings)) {
+                    throw new Error(`Task changed while rebuilding its workspace: ${task.id}.`);
+                }
+                assertTaskHasNoEvidence(tx, task.id);
+                const current = tx.getTaskWorkspace(task.id);
+                if (current === null
+                    ? existing !== null
+                    : existing === null || !sameManagedWorkspace(current, existing)) {
+                    throw new Error(`Task workspace changed while rebuilding: ${task.id}.`);
+                }
+                const pinnedBindings = latest.projectBindings.map((binding) => {
+                    const pinned = pins.get(binding.projectId);
+                    return pinned !== undefined ? { ...binding, baseRef: pinned } : binding;
+                });
+                const timestamp = this.now();
+                let persistedTask = isDeepStrictEqual(pinnedBindings, latest.projectBindings)
+                    ? latest
+                    : { ...latest, projectBindings: pinnedBindings, updatedAt: timestamp.toISOString() };
+                persistedTask = bindTaskWorkspaceIdentity(persistedTask, identity, timestamp);
+                if (persistedTask.cwd !== root) {
+                    persistedTask = { ...persistedTask, cwd: root, updatedAt: timestamp.toISOString() };
+                }
+                if (!isDeepStrictEqual(persistedTask, latest)) {
+                    tx.saveTask(persistedTask);
+                }
+                if (existing !== null)
+                    tx.removeManagedWorkspace(existing.owner);
+                tx.saveManagedWorkspace(workspace);
+            });
+            // Record switched: retire the legacy layout. The worktrees leave first
+            // (their branches are retained), then the refs are archived and
+            // deleted; each step is resumable.
+            await this.#removeLegacyWorktrees(task, existing === null
+                ? this.store.listProjects().map((project) => project.id)
+                : existing.entries.map(({ projectId }) => projectId));
+            const archived = await this.#archiveLegacyRefs(task, existing === null ? undefined : [...new Set(existing.entries.map(({ projectId }) => projectId))]);
+            return { task: requireTask(this.store, task.id), archived, resumed: false };
+        }
+        catch (error) {
+            await this.#discardUnadoptedEntries(task, taskSegment, prepared, MAIN_WORKTREE, true);
+            throw error;
+        }
+    }
+    /**
+     * List legacy (pre-identity) Task refs across the Home's Project
+     * repositories, optionally restricted to one Task. Identity-bearing
+     * branches (`yui/task-N-<8hex>/...`) are never legacy.
+     */
+    async listLegacyTaskRefs(taskId) {
+        const found = [];
+        for (const project of this.store.listProjects()) {
+            const refs = await this.git.listRefs(project.path, "refs/heads/yui/");
+            for (const ref of refs) {
+                if (!isLegacyTaskRef(ref))
+                    continue;
+                const ownerTaskId = ref.slice("refs/heads/yui/".length).split("/")[0];
+                if (taskId !== undefined && ownerTaskId !== taskId)
+                    continue;
+                found.push({ projectId: project.id, taskId: ownerTaskId, ref });
+            }
+        }
+        return found;
+    }
+    /**
+     * Archive legacy Task refs into the Home-scoped archive namespace
+     * (`refs/yui/archive/<homeId>/heads/...`). Refs owned by a draft/active
+     * Task are refused: their worktrees may still be live. Terminal and
+     * unknown-owner refs are archived; an already-archived or missing ref is
+     * simply absent on retry.
+     */
+    async archiveLegacyTaskRefs(taskId) {
+        const home = this.store.getHomeIdentity();
+        const refused = [];
+        const archived = [];
+        for (const entry of await this.listLegacyTaskRefs(taskId)) {
+            const owner = this.store.getTask(entry.taskId);
+            if (owner !== null && ["draft", "active"].includes(owner.status)) {
+                refused.push(`${entry.projectId}:${entry.ref}`);
+                continue;
+            }
+            const project = requireProject(this.store, entry.projectId);
+            await this.git.archiveRef({
+                repositoryPath: project.path,
+                sourceRef: entry.ref,
+                archiveRef: taskArchiveRef(home.homeId, entry.ref)
+            });
+            archived.push(`${entry.projectId}:${entry.ref}`);
+        }
+        return { archived, refused };
+    }
+    async #inspectEntries(taskSegment, roleName, entries) {
         if (entries.length === 0)
             return "missing";
         let found = false;
@@ -1430,7 +1680,7 @@ export class FileTaskWorkspacePreparer {
             const state = await this.git.inspectWorktree({
                 repositoryPath: project.path,
                 container: this.#projectContainer(project.name),
-                taskId,
+                taskSegment,
                 roleName
             });
             if (state === "dirty")
@@ -1463,6 +1713,15 @@ export class FileTaskWorkspacePreparer {
     #projectContainer(projectName) {
         return join(resolveWorktreeRoot(this.home, this.store.getConfig().defaultWorkspace), safePathSegment(projectName));
     }
+    /**
+     * The Task workspace ref segment for Git worktree derivation: the
+     * token-bearing segment for a Task with a persisted identity, its bare id
+     * for a pre-identity record. Every managed ref/path for one Task resolves
+     * through this single helper.
+     */
+    #taskSegment(task) {
+        return taskWorkspaceRefSegment(task);
+    }
     #taskWorkspaceRoot(taskId) {
         return join(resolveTaskRoot(this.home, this.store.getConfig().defaultWorkspace), safePathSegment(taskId), "main");
     }
@@ -1478,13 +1737,13 @@ export class FileTaskWorkspacePreparer {
     #fallbackWorkspace() {
         return this.store.getConfig().defaultWorkspace ?? process.cwd();
     }
-    async #discardUnadoptedEntries(task, prepared, roleName, deleteBranch = false, adoptedPaths = new Set(this.store.listManagedWorkspaces(task.id)
+    async #discardUnadoptedEntries(task, taskSegment, prepared, roleName, deleteBranch = false, adoptedPaths = new Set(this.store.listManagedWorkspaces(task.id)
         .flatMap((workspace) => workspace.entries.map(({ path }) => path)))) {
         for (const { project, entry } of prepared.filter(({ entry }) => entry.access === "write" && !adoptedPaths.has(entry.path))) {
             const removal = await this.git.removeWorktree({
                 repositoryPath: project.path,
                 container: this.#projectContainer(project.name),
-                taskId: task.id,
+                taskSegment,
                 roleName,
                 ...(deleteBranch ? { deleteBranch: true } : {})
             });
@@ -1493,6 +1752,57 @@ export class FileTaskWorkspacePreparer {
             }
         }
     }
+    /**
+     * Archive one Task's legacy refs (`refs/heads/yui/<taskId>/...`) into the
+     * Home-scoped archive namespace across the given Project repositories. When
+     * no Project list is given, every Project in the Home is scanned, so the
+     * resume path also finds refs in Projects that left the Task binding.
+     */
+    async #archiveLegacyRefs(task, projectIds) {
+        const home = this.store.getHomeIdentity();
+        const projects = projectIds === undefined
+            ? this.store.listProjects()
+            : projectIds.map((id) => requireProject(this.store, id));
+        const seen = new Set();
+        const archived = [];
+        for (const project of projects) {
+            const refs = await this.git.listRefs(project.path, `refs/heads/yui/${task.id}/`);
+            for (const ref of refs) {
+                const ownerTaskId = ref.slice("refs/heads/yui/".length).split("/")[0];
+                if (ownerTaskId !== task.id || !isLegacyTaskRef(ref))
+                    continue;
+                const key = `${project.id}:${ref}`;
+                if (seen.has(key))
+                    continue;
+                seen.add(key);
+                await this.git.archiveRef({
+                    repositoryPath: project.path,
+                    sourceRef: ref,
+                    archiveRef: taskArchiveRef(home.homeId, ref)
+                });
+                archived.push(key);
+            }
+        }
+        return archived;
+    }
+    /**
+     * Remove the legacy worktrees of a Task (the bare `<taskId>/main` layout).
+     * A missing worktree is expected on retry and ignored; a dirty one blocks.
+     */
+    async #removeLegacyWorktrees(task, projectIds) {
+        for (const projectId of projectIds) {
+            const project = requireProject(this.store, projectId);
+            const removal = await this.git.removeWorktree({
+                repositoryPath: project.path,
+                container: this.#projectContainer(project.name),
+                taskSegment: task.id,
+                roleName: MAIN_WORKTREE
+            });
+            if (removal === "dirty") {
+                throw new Error(`Legacy Task worktree is dirty and blocks the rebuild: ${task.id}/${project.id}.`);
+            }
+        }
+    }
     #recordWorkspaceRemoval(task, workspace, fallback, workItem) {
         this.store.transaction((tx) => {
             if (workspace.owner.type === "task") {
@@ -1555,6 +1865,19 @@ function assertTaskArchiveState(current, expected) {
         throw new WorkspaceCleanupBlockedError("task-changed", `task:${expected.id}`, true, `Task changed during archive cleanup: ${expected.id}.`);
     }
 }
+/**
+ * A controlled rebuild is only safe for a Task that owns no delivery
+ * evidence: a Run, WorkItem, ChangeSet, or Integration would pin the old
+ * refs and worktrees as historical proof.
+ */
+function assertTaskHasNoEvidence(store, taskId) {
+    if (store.listAgentRuns(taskId).length > 0
+        || store.listWorkItems(taskId).length > 0
+        || store.listChangeSets(taskId).length > 0
+        || store.listIntegrationAttempts(taskId).length > 0) {
+        throw new Error(`Task has Run, Work item, Change set, or Integration evidence and cannot be rebuilt in place: ${taskId}.`);
+    }
+}
 function requireProject(store, projectId) {
     const project = store.getProject(projectId);
     if (project === null)