@zq-silk/yui 0.15.9 → 0.15.12

package/dist/repository/taskWorkspacePreparer.js

@@ -1,6 +1,7 @@
 import { lstat, mkdir, readlink, readdir, rm, rmdir, symlink, unlink } from "node:fs/promises";
-import { isAbsolute, join, relative, resolve } from "node:path";
+import { dirname, isAbsolute, join, relative, resolve } from "node:path";
 import { isDeepStrictEqual } from "node:util";
+import { recordArchiveCleanup } from "../task/archiveDiagnostics.js";
 import { retireTaskRoleSessionsForWorkspace, updateRoleAgentSessionStatus } from "../executor/agentExecutor.js";
 import { formatWorkspacePreflightError } from "../executor/workspacePreflightClassification.js";
 import { updateRole } from "../role/role.js";
@@ -18,10 +19,13 @@ import { enqueueWork } from "../coordination/workMailboxQueue.js";
 import { createCandidateGitSnapshot, createDirectTaskMainSnapshot, workItemExecutionGroupById, recordWorkItemWorkspaceDisposition } from "../workItem/workItem.js";
 import { createManagedWorkspace, isTaskOwnedWorkspace, managedWorkspaceKey, managedWorktreeName, sameManagedWorkspaceIdentity } from "../worktree/managedWorkspace.js";
 import { NodeGitWorkspace, worktreeIdentity } from "./gitWorkspace.js";
-import { acquireProjectMaintenanceLocks } from "./projectMaintenanceLock.js";
+import { acquireProjectMaintenanceLocks, ProjectMaintenanceLockedError, ProjectMaintenanceLockCancelledError } from "./projectMaintenanceLock.js";
 import { generateTaskWorkspaceIdentity, taskWorkspaceRefSegment, validateTaskWorkspaceIdentity } from "./taskWorkspaceIdentity.js";
 import { ResourceRegistrar } from "../resources/resourceRegistrar.js";
 import { captureTaskBaseProvenance, recordTaskBaseProvenanceEvents } from "./taskBaseFreshness.js";
+import { managedTaskRoot } from "../storage/homeLayout.js";
+import { inspectWorkspaceCleanup } from "./workspaceCleanupInspection.js";
+import { CleanupInspectionError } from "../workspace/cleanupInspection.js";
 const MAIN_WORKTREE = "main";
 const LEADER_ROLE = "leader";
 /**
@@ -60,11 +64,21 @@ export class FileTaskWorkspacePreparer {
     store;
     git;
     now;
-    constructor(home, store, git = new NodeGitWorkspace(), now = () => new Date()) {
+    maintenanceLockOptions;
+    constructor(home, store, git = new NodeGitWorkspace(), now = () => new Date(), maintenanceLockOptions = {}) {
         this.home = home;
         this.store = store;
         this.git = git;
         this.now = now;
+        this.maintenanceLockOptions = maintenanceLockOptions;
+    }
+    inspectWorkspaceCleanup(workspace, disposition, forceArchive = false) {
+        return inspectWorkspaceCleanup(this.store, this.git, workspace, disposition, forceArchive);
+    }
+    async #assertWorkspaceCleanup(workspace, disposition) {
+        const checks = await this.inspectWorkspaceCleanup(workspace, disposition);
+        if (checks.length > 0)
+            throw new CleanupInspectionError(checks);
     }
     #resourceRegistrarValue;
     #resourceRegistrar() {
@@ -73,7 +87,7 @@ export class FileTaskWorkspacePreparer {
     #registerWorkspace(workspace) {
         this.#resourceRegistrar().registerManagedWorkspace(workspace);
     }
-    async prepareTaskWorkspace(taskId) {
+    async prepareTaskWorkspace(taskId, signal) {
         // The per-Project maintenance fence makes prepare mutually exclusive with
         // Project maintenance and Task archive cleanup: a concurrent migration must not switch the
         // Project catalog to the Home-managed repo while prepare is creating
@@ -85,7 +99,7 @@ export class FileTaskWorkspacePreparer {
         for (let attempt = 0;; attempt += 1) {
             try {
                 const task = requireTask(this.store, taskId);
-                const { release, current } = this.#acquireTaskProjectMaintenanceLocks(task);
+                const { release, current } = await this.#acquireTaskProjectMaintenanceLocks(task, signal);
                 try {
                     return await this.#prepareTaskWorkspaceLocked(current.id, false);
                 }
@@ -114,11 +128,14 @@ export class FileTaskWorkspacePreparer {
      * later launch failure can never present itself as "activation never
      * happened".
      */
-    async activateTaskWorkspace(taskId, environment = {}) {
+    async activateTaskWorkspace(taskId, environment = {}, signal) {
         for (let attempt = 0;; attempt += 1) {
             let attemptedRequest;
             try {
                 const task = requireTask(this.store, taskId);
+                if (signal?.aborted) {
+                    throw new ProjectMaintenanceLockCancelledError(task.projectBindings[0]?.projectId ?? task.id, signal.reason);
+                }
                 const caller = taskLocalActor(this.store, environment, task.id);
                 const actor = task.activationRequest?.operation.actorId === `task:${task.id}/role:leader`
                     ? "leader" : caller;
@@ -146,12 +163,14 @@ export class FileTaskWorkspacePreparer {
                 if (admission.disposition === "ready")
                     attemptedRequest = admission.request;
                 validateDraftTaskForActivation(this.store, task);
-                const adopted = await this.#adoptActivationEnvironment(task);
-                return adopted.workspaceFree
-                    ? this.#activateWorkspaceFreeTask(task.id, adopted, actor)
-                    : await this.#prepareActivatedTaskWorkspace(task, adopted, actor);
+                return await this.#prepareActivatedTaskWorkspace(task, actor, environment, signal);
             }
             catch (error) {
+                // Waiting did not execute the workspace operation. Preserve the
+                // activation request instead of turning contention/stop into failure.
+                if (error instanceof ProjectMaintenanceLockedError
+                    || error instanceof ProjectMaintenanceLockCancelledError)
+                    throw error;
                 if (error instanceof StorageConflictError
                     && attempt < TASK_WORKSPACE_PREPARE_MAX_CONFLICT_RETRIES) {
                     continue;
@@ -168,10 +187,28 @@ export class FileTaskWorkspacePreparer {
         }
     }
     /** Prepares the managed workspace of a Task being activated, under its fences. */
-    async #prepareActivatedTaskWorkspace(task, environment, actor) {
-        const { release, current } = this.#acquireTaskProjectMaintenanceLocks(task);
+    async #prepareActivatedTaskWorkspace(task, actor, callerEnvironment, signal) {
+        const { release, current } = await this.#acquireTaskProjectMaintenanceLocks(task, signal);
         try {
-            return await this.#prepareTaskWorkspaceLocked(current.id, true, environment, actor);
+            taskLocalActor(this.store, callerEnvironment, current.id);
+            if (current.executionGate.state !== "enabled") {
+                throw new Error(`Task execution is not enabled: ${current.id}.`);
+            }
+            if (!isDeepStrictEqual(current.activationRequest, task.activationRequest)) {
+                throw new Error(`Task activation request changed while waiting for Project maintenance: ${task.id}.`);
+            }
+            const provider = this.store.getTaskRoleSessionSet(current.id, LEADER_ROLE)?.providerBinding;
+            if (provider?.run != null
+                && ["submitting", "accepted", "delivery-unknown"].includes(provider.run.status)) {
+                throw new Error("Planning native input is unsettled; preserve activation intent and retry after its exact terminal.");
+            }
+            validateDraftTaskForActivation(this.store, current);
+            // Acquire before resource adoption: a timed-out/cancelled waiter must
+            // not leave an adopted environment to be repeated on the next attempt.
+            const adopted = await this.#adoptActivationEnvironment(current);
+            return adopted.workspaceFree
+                ? this.#activateWorkspaceFreeTask(current.id, adopted, actor)
+                : await this.#prepareTaskWorkspaceLocked(current.id, true, adopted, actor);
         }
         finally {
             release();
@@ -328,12 +365,19 @@ export class FileTaskWorkspacePreparer {
      * caller re-reads the Task and re-acquires the correct fence set. The
      * caller owns `release` and MUST call it on every exit path.
      */
-    #acquireTaskProjectMaintenanceLocks(task) {
+    async #acquireTaskProjectMaintenanceLocks(task, signal) {
         const projectIds = task.projectBindings.map(({ projectId }) => projectId);
+        const waitSignal = signal ?? this.maintenanceLockOptions.signal;
         const release = projectIds.length === 0
             ? () => { }
-            : acquireProjectMaintenanceLocks(this.home, projectIds);
+            : await acquireProjectMaintenanceLocks(this.home, projectIds, {
+                ...this.maintenanceLockOptions,
+                signal: waitSignal
+            });
         try {
+            if (waitSignal?.aborted) {
+                throw new ProjectMaintenanceLockCancelledError(projectIds[0] ?? task.id, waitSignal.reason);
+            }
             const current = requireTask(this.store, task.id);
             const currentIds = current.projectBindings.map(({ projectId }) => projectId).sort();
             const lockedIds = [...projectIds].sort();
@@ -356,13 +400,16 @@ export class FileTaskWorkspacePreparer {
      * catalog in that gap. The caller owns `release` and must call it on every
      * exit path.
      */
-    acquireTaskProjectMaintenanceLocks(taskId) {
-        return this.#acquireTaskProjectMaintenanceLocks(requireTask(this.store, taskId));
+    acquireTaskProjectMaintenanceLocks(taskId, signal) {
+        return this.#acquireTaskProjectMaintenanceLocks(requireTask(this.store, taskId), signal);
     }
     async #prepareTaskWorkspaceLocked(taskId, activate, 
     /** Environment and request identity the activation adopted, when one exists. */
     activationEnvironment = { workspaceFree: false }, actor = "user") {
         const task = requireTask(this.store, taskId);
+        if (task.executionGate.state !== "enabled") {
+            throw new Error(`Task execution is not enabled: ${task.id}.`);
+        }
         if (activate && task.status !== "draft") {
             throw new Error(`Only a Draft Task can atomically adopt a workspace: ${task.id}/${task.status}.`);
         }
@@ -537,7 +584,7 @@ export class FileTaskWorkspacePreparer {
                     throw new Error(`Task Project baseline was not resolved: ${project.id}.`);
                 }
                 const identity = worktreeIdentity(taskSegment, MAIN_WORKTREE);
-                const destination = join(this.#projectContainer(project.name), identity.directory);
+                const destination = join(root, safePathSegment(binding.directory));
                 const physical = previous === undefined
                     ? await this.git.clone({
                         remoteUrl: project.remoteUrl,
@@ -908,15 +955,17 @@ export class FileTaskWorkspacePreparer {
         return projects;
     }
     async prepareWorkItemWorkspace(taskId, workItemId) {
-        const item = requireWorkItem(this.store, taskId, workItemId);
+        let item = requireWorkItem(this.store, taskId, workItemId);
         const task = requireTask(this.store, item.taskId);
         assertWorkItemWorkspaceEligible(this.store, task, item);
         // Hold the per-Project maintenance fence across the ensure-main-prepared
         // and the WorkItem worktree creation, so concurrent Project maintenance
         // cannot switch the Project catalog between the two. The under-lock Task
         // snapshot drives every Project read and Git effect below.
-        const { release, current: lockedTask } = this.#acquireTaskProjectMaintenanceLocks(task);
+        const { release, current: lockedTask } = await this.#acquireTaskProjectMaintenanceLocks(task);
         try {
+            item = requireWorkItem(this.store, taskId, workItemId);
+            assertWorkItemWorkspaceEligible(this.store, lockedTask, item);
             const lockedProjectIds = lockedTask.projectBindings.map(({ projectId }) => projectId);
             await this.#prepareTaskWorkspaceWithRetries(lockedTask.id, lockedProjectIds);
             // prepareTaskWorkspace may have just minted and persisted the workspace
@@ -966,9 +1015,25 @@ export class FileTaskWorkspacePreparer {
                     const requestedBase = previous?.access === "write" || requestedBaseRef === undefined
                         ? null
                         : await this.git.inspect(mainEntry.path, requestedBaseRef);
+                    if (previous?.access === "read" && previous.directory === binding.directory) {
+                        const viewPath = join(root, binding.directory);
+                        const metadata = await lstat(viewPath).catch((error) => {
+                            if (errorCode(error) === "ENOENT")
+                                return null;
+                            throw error;
+                        });
+                        if (metadata?.isSymbolicLink()) {
+                            if (resolve(root, await readlink(viewPath)) !== resolve(previous.path)) {
+                                throw new Error(`Read-only workspace view changed before scope expansion: ${viewPath}.`);
+                            }
+                            // Remove only the registered read view, never its target.
+                            await unlink(viewPath);
+                        }
+                    }
                     const physical = await this.git.ensureWorktree({
                         repositoryPath: mainEntry.path,
-                        container: this.#projectContainer(project.name),
+                        container: root,
+                        directory: binding.directory,
                         taskSegment,
                         roleName: item.id,
                         baseRef
@@ -1081,9 +1146,12 @@ export class FileTaskWorkspacePreparer {
         // already holds (one locked boundary across preparation and adoption);
         // otherwise the fence is acquired here.
         const { release, current: lockedTask } = heldFence === undefined
-            ? this.#acquireTaskProjectMaintenanceLocks(task)
+            ? await this.#acquireTaskProjectMaintenanceLocks(task)
             : { release: () => { }, current: heldFence.current };
         try {
+            if (lockedTask.status !== "active" || lockedTask.executionGate.state !== "enabled") {
+                throw new Error(`Task is not open for Execution Lane preparation: ${lockedTask.id}.`);
+            }
             const lineage = executionLaneLineage(this.store, lockedTask, executionGroupId, executionLaneId, hint);
             const item = lineage.purpose === "execution"
                 ? this.store.getWorkItem(taskId, lineage.workItemId)
@@ -1139,7 +1207,8 @@ export class FileTaskWorkspacePreparer {
                     const project = requireProject(this.store, entry.projectId);
                     const physical = await this.git.ensureWorktree({
                         repositoryPath: this.#taskRepositoryPath(taskId, project.id),
-                        container: this.#projectContainer(project.name),
+                        container: existing.root,
+                        directory: entry.directory,
                         taskSegment,
                         roleName: managedWorktreeName(owner),
                         baseRef: entry.baseCommit
@@ -1151,6 +1220,7 @@ export class FileTaskWorkspacePreparer {
                 return existing;
             }
             const prepared = [];
+            const root = this.#executionLaneWorkspaceRoot(taskId, executionGroupId, executionLaneId);
             try {
                 for (const binding of lockedTask.projectBindings) {
                     const project = requireProject(this.store, binding.projectId);
@@ -1162,7 +1232,8 @@ export class FileTaskWorkspacePreparer {
                     const inputHead = inputHeadByProject.get(project.id) ?? sourceEntry.baseCommit;
                     const physical = await this.git.ensureWorktree({
                         repositoryPath: this.#taskRepositoryPath(taskId, project.id),
-                        container: this.#projectContainer(project.name),
+                        container: root,
+                        directory: sourceEntry.directory,
                         taskSegment,
                         roleName: managedWorktreeName(owner),
                         baseRef: inputHead
@@ -1182,7 +1253,6 @@ export class FileTaskWorkspacePreparer {
                         }
                     });
                 }
-                const root = this.#executionLaneWorkspaceRoot(taskId, executionGroupId, executionLaneId);
                 await ensureWorkspaceView(root, prepared.map(({ entry }) => entry));
                 const workspace = createManagedWorkspace({
                     owner,
@@ -1249,6 +1319,7 @@ export class FileTaskWorkspacePreparer {
             && owner.executionLaneId === executionLaneId));
         if (workspace === undefined)
             return "missing";
+        await this.#assertWorkspaceCleanup(workspace, "abandoned");
         const state = await this.#inspectEntries(task.id, this.#taskSegment(task), managedWorktreeName(workspace.owner), workspace.entries.filter(({ access }) => access === "write"));
         if (state === "dirty")
             return "dirty";
@@ -1257,13 +1328,15 @@ export class FileTaskWorkspacePreparer {
             const project = requireProject(this.store, entry.projectId);
             const result = await this.git.removeWorktree({
                 repositoryPath: this.#taskRepositoryPath(task.id, project.id),
-                container: this.#projectContainer(project.name),
+                container: dirname(entry.path),
+                directory: entry.directory,
                 taskSegment: this.#taskSegment(task),
                 roleName: managedWorktreeName(workspace.owner),
                 deleteBranch: true
             });
             if (result === "dirty")
                 return "dirty";
+            this.#recordArchivePathRemoval(task, entry.path, result);
             removed ||= result === "removed";
         }
         await removeWorkspaceView(workspace.root);
@@ -1310,7 +1383,8 @@ export class FileTaskWorkspacePreparer {
             const project = requireProject(this.store, entry.projectId);
             const result = await this.git.removeWorktree({
                 repositoryPath: this.#taskRepositoryPath(task.id, project.id),
-                container: this.#projectContainer(project.name),
+                container: dirname(entry.path),
+                directory: entry.directory,
                 taskSegment,
                 roleName: managedWorktreeName(workspace.owner),
                 deleteBranch: true
@@ -1381,8 +1455,11 @@ export class FileTaskWorkspacePreparer {
      * never used as a ChangeSet capture source. */
     async prepareReviewRoundWorkspace(taskId, reviewRoundId) {
         const taskSnapshot = requireTask(this.store, taskId);
-        const { release, current: task } = this.#acquireTaskProjectMaintenanceLocks(taskSnapshot);
+        const { release, current: task } = await this.#acquireTaskProjectMaintenanceLocks(taskSnapshot);
         try {
+            if (task.status !== "active" || task.executionGate.state !== "enabled") {
+                throw new Error(`Task is not open for ReviewRound preparation: ${task.id}.`);
+            }
             const taskSegment = this.#taskSegment(task);
             const round = this.store.getReviewRound(task.id, reviewRoundId);
             if (round === null)
@@ -1417,19 +1494,19 @@ export class FileTaskWorkspacePreparer {
             const snapshotCommits = new Map((taskScope
                 ? round.taskCandidate?.projects ?? []
                 : candidate.gitSnapshot.projects).map(({ projectId, commit }) => [projectId, commit]));
+            const reviewRoot = this.#reviewRoundWorkspaceRoot(task.id, round);
             const frozenEntries = taskScope
                 ? task.projectBindings.map((binding) => {
                     const commit = snapshotCommits.get(binding.projectId);
                     if (commit === undefined) {
                         throw new Error(`Task Review candidate Project is missing: ${binding.projectId}.`);
                     }
-                    const project = requireProject(this.store, binding.projectId);
                     const identity = worktreeIdentity(taskSegment, this.#reviewWorktreeName(round));
                     return {
                         projectId: binding.projectId,
                         directory: binding.directory,
                         access: "write",
-                        path: join(this.#projectContainer(project.name), identity.directory),
+                        path: join(reviewRoot, safePathSegment(binding.directory)),
                         branch: identity.branch,
                         baseRef: commit,
                         baseCommit: commit
@@ -1447,7 +1524,6 @@ export class FileTaskWorkspacePreparer {
             }
             const expectedEntries = new Map(frozenEntries.map((entry) => [entry.projectId, entry]));
             const existing = this.store.getReviewRoundWorkspace(task.id, round.id);
-            const reviewRoot = this.#reviewRoundWorkspaceRoot(task.id, round);
             if (taskScope && existing === null) {
                 const reassigned = await this.#reassignTaskReviewWorkspace(task, round, reviewer, reviewRoot, frozenEntries);
                 if (reassigned !== null)
@@ -1482,7 +1558,7 @@ export class FileTaskWorkspacePreparer {
                     }
                     const project = requireProject(this.store, entry.projectId);
                     const identity = worktreeIdentity(taskSegment, this.#reviewWorktreeName(round));
-                    const expectedPath = join(this.#projectContainer(project.name), identity.directory);
+                    const expectedPath = join(reviewRoot, safePathSegment(entry.directory));
                     if (entry.path !== expectedPath || entry.branch !== identity.branch) {
                         throw new ReviewRoundWorkspaceEvidenceError(`ReviewRound workspace managed identity mismatch for ${round.id}/${entry.projectId}.`);
                     }
@@ -1568,7 +1644,8 @@ export class FileTaskWorkspacePreparer {
                     const project = requireProject(this.store, source.projectId);
                     const physical = await this.git.ensureWorktree({
                         repositoryPath: this.#taskRepositoryPath(task.id, project.id),
-                        container: this.#projectContainer(project.name),
+                        container: reviewRoot,
+                        directory: source.directory,
                         taskSegment,
                         roleName: this.#reviewWorktreeName(round),
                         baseRef: source.baseCommit
@@ -1855,6 +1932,7 @@ export class FileTaskWorkspacePreparer {
         if (!isDeepStrictEqual(round.workspace, workspace)) {
             throw new Error(`ReviewRound workspace record diverged: ${round.id}.`);
         }
+        await this.#assertWorkspaceCleanup(workspace, "abandoned");
         assertWorkspaceSessionsRetirable(this.store, task.id, round.reviewerRoleName, this.now());
         for (const lane of round.executionGroup?.lanes ?? []) {
             assertWorkspaceSessionsRetirable(this.store, task.id, lane.roleName, this.now());
@@ -1869,7 +1947,8 @@ export class FileTaskWorkspacePreparer {
             const project = requireProject(this.store, entry.projectId);
             const result = await this.git.removeWorktree({
                 repositoryPath: this.#taskRepositoryPath(task.id, project.id),
-                container: this.#projectContainer(project.name),
+                container: dirname(entry.path),
+                directory: entry.directory,
                 taskSegment: this.#taskSegment(task),
                 roleName: this.#reviewWorktreeName(round),
                 deleteBranch: true
@@ -1877,6 +1956,7 @@ export class FileTaskWorkspacePreparer {
             if (result === "dirty") {
                 throw new Error(`Review workspace changed after cleanup preflight: ${round.id}.`);
             }
+            this.#recordArchivePathRemoval(task, entry.path, result);
             removed ||= result === "removed";
         }
         await removeWorkspaceView(workspace.root);
@@ -1920,6 +2000,7 @@ export class FileTaskWorkspacePreparer {
             throw new Error(`WorkItem has no managed isolated worktree workspace: ${item.id}.`);
         }
         assertWorkItemOwnsWorkspace(item, workspace);
+        await this.#assertWorkspaceCleanup(workspace, disposition);
         if (item.assignee !== undefined) {
             assertWorkspaceSessionsRetirable(this.store, task.id, item.assignee, this.now());
         }
@@ -1935,7 +2016,8 @@ export class FileTaskWorkspacePreparer {
             const project = requireProject(this.store, entry.projectId);
             const result = await this.git.removeWorktree({
                 repositoryPath: this.#taskRepositoryPath(task.id, project.id),
-                container: this.#projectContainer(project.name),
+                container: dirname(entry.path),
+                directory: entry.directory,
                 taskSegment: this.#taskSegment(task),
                 roleName: managedWorktreeName(workspace.owner),
                 deleteBranch: true
@@ -1943,6 +2025,7 @@ export class FileTaskWorkspacePreparer {
             if (result === "dirty") {
                 throw new Error(`WorkItem workspace changed after cleanup preflight: ${item.id}.`);
             }
+            this.#recordArchivePathRemoval(task, entry.path, result);
             removed ||= result === "removed";
         }
         await removeWorkspaceView(workspace.root);
@@ -1956,7 +2039,7 @@ export class FileTaskWorkspacePreparer {
         catch (error) {
             if (!removed)
                 throw error;
-            throw new Error(`WorkItem worktree was removed but durable cleanup was not recorded; retry cleanup: ${error instanceof Error ? error.message : String(error)}`);
+            throw new Error(`WorkItem worktree was removed but durable cleanup was not recorded; retry cleanup: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
         }
         return removed ? "removed" : "missing";
     }
@@ -1971,7 +2054,7 @@ export class FileTaskWorkspacePreparer {
         let found = false;
         for (const entry of workspace.entries.filter(({ access }) => access === "write")) {
             try {
-                if (!await this.git.isClean(entry.path))
+                if (!await this.git.inspectClean(entry.path))
                     return "dirty";
                 found = true;
             }
@@ -1983,7 +2066,7 @@ export class FileTaskWorkspacePreparer {
         }
         return found ? "clean" : "missing";
     }
-    async cleanupIntegrationWorkspace(taskId, integrationId) {
+    async cleanupIntegrationWorkspace(taskId, integrationId, options = {}) {
         const task = requireTask(this.store, taskId);
         const attempt = this.store.getIntegrationAttempt(task.id, integrationId);
         if (attempt === null) {
@@ -1991,19 +2074,41 @@ export class FileTaskWorkspacePreparer {
         }
         if (attempt.status === "running"
             || attempt.status === "blocked"
+            || attempt.status === "conflicted"
             || attempt.status === "validating") {
             throw new Error(`IntegrationAttempt must be terminal before cleanup: ${attempt.id}.`);
         }
         const workspace = this.store.getIntegrationWorkspace(task.id, attempt.id);
+        // A failed Integration's explicitly disposable conflict tree retains its
+        // existing cleanup contract outside archive. Archive never discards dirt.
+        if (workspace !== null && (options.preserveChanges || task.status === "archived" || attempt.status !== "failed")) {
+            await this.#assertWorkspaceCleanup(workspace, "abandoned");
+        }
         const project = requireProject(this.store, attempt.projectId);
+        // The recorded entry pins the exact on-disk worktree path; reconstruct the
+        // owner root from it so removal targets the real Git worktree regardless of
+        // how the layout helper derives it. Absent a recorded workspace, fall back
+        // to the deterministic integration owner root + bound directory.
+        const recorded = workspace?.entries[0];
+        const directory = recorded?.directory
+            ?? task.projectBindings.find(({ projectId }) => projectId === attempt.projectId)?.directory;
+        if (directory === undefined) {
+            throw new Error(`Integration Project binding is unavailable: ${task.id}/${project.id}.`);
+        }
         const result = await this.git.removeIntegrationWorktree({
             repositoryPath: this.#taskRepositoryPath(task.id, project.id),
-            container: this.#projectContainer(project.name),
+            container: recorded !== undefined
+                ? dirname(recorded.path)
+                : this.#integrationWorkspaceRoot(task.id, attempt.id),
+            directory,
             taskSegment: this.#taskSegment(task),
             integrationId: attempt.id,
-            discardChanges: attempt.status === "failed"
+            discardChanges: options.preserveChanges !== true && task.status !== "archived" && attempt.status === "failed"
         });
         if (result !== "dirty") {
+            for (const entry of workspace?.entries ?? []) {
+                this.#recordArchivePathRemoval(task, entry.path, result);
+            }
             if (workspace !== null)
                 this.#resourceRegistrar().markWorkspaceDeleted(workspace);
             await rm(join(this.home, "artifacts", "integration-checks", task.id, attempt.id), { recursive: true, force: true });
@@ -2025,7 +2130,7 @@ export class FileTaskWorkspacePreparer {
         }
         return this.#inspectEntries(task.id, this.#taskSegment(task), MAIN_WORKTREE, main.entries);
     }
-    async cleanupTaskForArchive(taskId) {
+    async cleanupTaskForArchive(taskId, disposition = "abandoned") {
         const task = requireTask(this.store, taskId);
         assertTaskArchiveState(task, task);
         const isolated = this.store.listManagedWorkspaces(task.id)
@@ -2040,6 +2145,7 @@ export class FileTaskWorkspacePreparer {
         }
         const main = this.store.getTaskWorkspace(task.id);
         if (main !== null) {
+            await this.#assertWorkspaceCleanup(main, disposition);
             assertTaskArchiveState(requireTask(this.store, task.id), task);
             if (await this.#inspectEntries(task.id, this.#taskSegment(task), MAIN_WORKTREE, main.entries) === "dirty") {
                 return {
@@ -2050,10 +2156,14 @@ export class FileTaskWorkspacePreparer {
             }
             for (const entry of main.entries) {
                 assertTaskArchiveState(requireTask(this.store, task.id), task);
-                const result = await this.git.removeStrandedWorktree(entry.path);
+                const result = await this.git.removeTaskClone({
+                    path: entry.path, container: main.root, directory: entry.directory,
+                    taskSegment: this.#taskSegment(task), branch: entry.branch
+                });
                 if (result === "dirty") {
                     throw new Error(`Task workspace changed after cleanup preflight: ${task.id}.`);
                 }
+                this.#recordArchivePathRemoval(task, entry.path, result);
             }
             assertTaskArchiveState(requireTask(this.store, task.id), task);
             await removeWorkspaceView(main.root);
@@ -2064,6 +2174,16 @@ export class FileTaskWorkspacePreparer {
         this.#clearTaskWorkspace(task, this.#fallbackWorkspace());
         return { taskId, status: "removed" };
     }
+    #recordArchivePathRemoval(task, path, status) {
+        if (task.status !== "archived")
+            return;
+        recordArchiveCleanup(this.store, task.id, {
+            resource: `path:${path}`, paths: [path],
+            detail: status === "missing"
+                ? "Directory absent; exact Git cleanup completed where applicable."
+                : "Exact owned path removed."
+        }, status, this.now());
+    }
     async #inspectEntries(taskId, taskSegment, roleName, entries) {
         if (entries.length === 0)
             return "missing";
@@ -2072,7 +2192,11 @@ export class FileTaskWorkspacePreparer {
             const project = requireProject(this.store, entry.projectId);
             const state = await this.git.inspectWorktree({
                 repositoryPath: this.#taskRepositoryPath(taskId, project.id),
-                container: this.#projectContainer(project.name),
+                // A managed worktree lives at `root/<directory>`, so its parent is the
+                // owner workspace root. Deriving it from the entry keeps this helper
+                // agnostic to which owner (main/work-item/review/lane) it serves.
+                container: dirname(entry.path),
+                directory: entry.directory,
                 taskSegment,
                 roleName
             });
@@ -2082,9 +2206,6 @@ export class FileTaskWorkspacePreparer {
         }
         return found ? "clean" : "missing";
     }
-    #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
@@ -2095,13 +2216,16 @@ export class FileTaskWorkspacePreparer {
         return taskWorkspaceRefSegment(task);
     }
     #taskWorkspaceRoot(taskId) {
-        return join(resolveTaskRoot(this.home, this.store.getConfig().defaultWorkspace), safePathSegment(taskId), "main");
+        return join(resolveTaskRoot(this.home), safePathSegment(taskId), "main");
     }
     #workItemWorkspaceRoot(taskId, workItemId) {
-        return join(resolveTaskRoot(this.home, this.store.getConfig().defaultWorkspace), safePathSegment(taskId), "work-items", safePathSegment(workItemId));
+        return join(resolveTaskRoot(this.home), safePathSegment(taskId), "work-items", safePathSegment(workItemId));
     }
     #reviewRoundWorkspaceRoot(taskId, round) {
-        return join(resolveTaskRoot(this.home, this.store.getConfig().defaultWorkspace), safePathSegment(taskId), "reviews", safePathSegment(this.#reviewWorktreeName(round)));
+        return join(resolveTaskRoot(this.home), safePathSegment(taskId), "reviews", safePathSegment(this.#reviewWorktreeName(round)));
+    }
+    #integrationWorkspaceRoot(taskId, integrationId) {
+        return integrationWorkspaceRoot(this.home, taskId, integrationId);
     }
     #reviewWorktreeName(round) {
         return (round.scope ?? "work-item") === "task"
@@ -2109,7 +2233,7 @@ export class FileTaskWorkspacePreparer {
             : round.id;
     }
     #executionLaneWorkspaceRoot(taskId, groupId, laneId) {
-        return join(resolveTaskRoot(this.home, this.store.getConfig().defaultWorkspace), safePathSegment(taskId), "execution-lanes", safePathSegment(groupId), safePathSegment(laneId));
+        return join(resolveTaskRoot(this.home), safePathSegment(taskId), "execution-lanes", safePathSegment(groupId), safePathSegment(laneId));
     }
     #fallbackWorkspace() {
         return this.store.getConfig().defaultWorkspace ?? process.cwd();
@@ -2127,7 +2251,8 @@ export class FileTaskWorkspacePreparer {
             }
             const removal = await this.git.removeWorktree({
                 repositoryPath: this.#taskRepositoryPath(task.id, project.id),
-                container: this.#projectContainer(project.name),
+                container: dirname(entry.path),
+                directory: entry.directory,
                 taskSegment,
                 roleName,
                 ...(deleteBranch ? { deleteBranch: true } : {})
@@ -2218,7 +2343,7 @@ function requireTask(store, taskId) {
     return task;
 }
 function assertTaskArchiveState(current, expected) {
-    if ((current.status !== "completed" && current.status !== "cancelled")
+    if ((current.status !== "completed" && current.status !== "cancelled" && current.status !== "archived")
         || !isDeepStrictEqual(current, expected)) {
         throw new WorkspaceCleanupBlockedError("task-changed", `task:${expected.id}`, true, `Task changed during archive cleanup: ${expected.id}.`);
     }
@@ -2441,14 +2566,28 @@ function recordWorkspaceDisposition(store, taskId, workItem, now) {
         throw new Error(`Work item not found: ${workItem.workItemId}.`);
     store.saveWorkItem(taskId, recordWorkItemWorkspaceDisposition(item, workItem.disposition, now));
 }
+/**
+ * Reconcile an owner workspace directory so it presents every bound Project at
+ * `root/<directory>`.
+ *
+ * Writable Projects are real Git worktrees created in place at `root/<directory>`
+ * by the Git port before this runs; they are left untouched here. Read-only
+ * Projects share an upstream worktree (the Task main clone) and are surfaced as
+ * genuine symlinks `root/<directory> -> entry.path`. Only the symlink views are
+ * reconciled: a stale or renamed read link is repaired, an obsolete one removed.
+ * A real directory (a write worktree) is never treated as a view entry, so this
+ * neither creates nor removes committed Git content.
+ */
 async function ensureWorkspaceView(root, entries) {
     await mkdir(root, { recursive: true });
-    const expected = new Map(entries.map((entry) => [entry.directory, entry.path]));
+    const expected = new Map(entries.filter((entry) => entry.access === "read").map((entry) => [entry.directory, entry.path]));
     for (const current of await readdir(root, { withFileTypes: true })) {
+        // A write entry is a real worktree directory living in place under root; it
+        // is owned by Git, not by this view, so it is never reconciled or removed
+        // here. Only symlinks (read-entry views) are this function's concern.
+        if (!current.isSymbolicLink())
+            continue;
         const target = expected.get(current.name);
-        if (!current.isSymbolicLink()) {
-            throw new Error(`Managed workspace contains an unexpected entry: ${join(root, current.name)}.`);
-        }
         const path = join(root, current.name);
         const linked = resolve(root, await readlink(path));
         if (target === undefined) {
@@ -2493,23 +2632,17 @@ function safePathSegment(value) {
 function sameCommit(left, right) {
     return left.toLowerCase() === right.toLowerCase();
 }
-export function resolveWorktreeRoot(home, workspace) {
-    return join(resolveWorkspaceRoot(home, workspace), "worktree");
-}
-export function resolveTaskRoot(home, workspace) {
-    return join(resolveWorkspaceRoot(home, workspace), "tasks");
+export function resolveTaskRoot(home) {
+    return managedTaskRoot(home);
 }
-function resolveWorkspaceRoot(home, workspace) {
-    if (workspace === undefined) {
-        throw new Error("Project workspace is not configured; run yui setup.");
-    }
-    const homeRoot = resolve(home);
-    const workspaceRoot = resolve(workspace);
-    const fromHome = relative(homeRoot, workspaceRoot);
-    if (fromHome === "" || (!fromHome.startsWith("..") && !isAbsolute(fromHome))) {
-        throw new Error("Project workspace must be outside YUI_HOME.");
-    }
-    return workspaceRoot;
+/**
+ * The integration owner root: `tasks/<taskId>/integrations/<integrationId>`.
+ * A single-project integration worktree lives at `<root>/<boundDirectory>`.
+ * Shared by the preparer and the integration service so create and cleanup
+ * derive the same on-disk path.
+ */
+export function integrationWorkspaceRoot(home, taskId, integrationId) {
+    return join(managedTaskRoot(home), safePathSegment(taskId), "integrations", safePathSegment(integrationId));
 }
 function errorCode(error) {
     return typeof error === "object" && error !== null && "code" in error