@zq-silk/yui 0.15.11 → 0.16.0

package/dist/repository/taskWorkspacePreparer.js

@@ -1,29 +1,31 @@
-import { lstat, mkdir, readlink, readdir, rm, rmdir, symlink, unlink } from "node:fs/promises";
+import { lstat, mkdir, readdir, readlink, rm, rmdir, symlink, unlink } from "node:fs/promises";
 import { dirname, isAbsolute, join, relative, resolve } from "node:path";
 import { isDeepStrictEqual } from "node:util";
 import { recordArchiveCleanup } from "../task/archiveDiagnostics.js";
+import { enqueueWork } from "../coordination/workMailboxQueue.js";
+import { createTaskEvent } from "../event/taskEvent.js";
 import { retireTaskRoleSessionsForWorkspace, updateRoleAgentSessionStatus } from "../executor/agentExecutor.js";
 import { formatWorkspacePreflightError } from "../executor/workspacePreflightClassification.js";
+import { createProjectResources } from "../resources/projectResourceService.js";
+import { ResourceRegistrar } from "../resources/resourceRegistrar.js";
+import { attachReviewRoundWorkspace, recordReviewWorkspaceDisposition } from "../review/reviewRound.js";
 import { updateRole } from "../role/role.js";
+import { hasRuntimeCleanupObligation, RUNTIME_HOST_DETACH_REQUIRED_REASON, runtimeLifecycleTarget } from "../runtime/lifecycleReservation.js";
 import { taskRoleRuntimeIdentity } from "../runtime/managedCaller.js";
-import { hasRuntimeCleanupObligation, runtimeLifecycleTarget, RUNTIME_HOST_DETACH_REQUIRED_REASON } from "../runtime/lifecycleReservation.js";
-import { taskLocalActor } from "../commands/taskActor.js";
-import { attachReviewRoundWorkspace, recordReviewWorkspaceDisposition } from "../review/reviewRound.js";
+import { managedTaskRoot } from "../storage/homeLayout.js";
 import { StorageConflictError } from "../storage/taskStore.js";
-import { activateTask, bindTaskProjectCommits, bindTaskWorkspaceIdentity, synchronizeTaskProjectCommits, taskOwnsManagedWorkspace } from "../task/task.js";
-import { admitStoredTaskActivation, adoptTaskActivationResources, recordFailedTaskActivation, recordAdoptedTaskActivation } from "../task/taskActivationService.js";
 import { validateDraftTaskForActivation } from "../task/draftPlan.js";
-import { createProjectResources } from "../resources/projectResourceService.js";
-import { createTaskEvent } from "../event/taskEvent.js";
-import { enqueueWork } from "../coordination/workMailboxQueue.js";
-import { createCandidateGitSnapshot, createDirectTaskMainSnapshot, workItemExecutionGroupById, recordWorkItemWorkspaceDisposition } from "../workItem/workItem.js";
+import { activateTask, bindTaskProjectCommits, bindTaskWorkspaceIdentity, synchronizeTaskProjectCommits, taskOwnsManagedWorkspace } from "../task/task.js";
+import { admitStoredTaskActivation, adoptTaskActivationResources, recordAdoptedTaskActivation, recordFailedTaskActivation } from "../task/taskActivationService.js";
+import { taskLocalActor } from "../task/taskAuthority.js";
+import { createCandidateGitSnapshot, createDirectTaskMainSnapshot, recordWorkItemWorkspaceDisposition, workItemExecutionGroupById } from "../workItem/workItem.js";
+import { CleanupInspectionError } from "../workspace/cleanupInspection.js";
 import { createManagedWorkspace, isTaskOwnedWorkspace, managedWorkspaceKey, managedWorktreeName, sameManagedWorkspaceIdentity } from "../worktree/managedWorkspace.js";
 import { NodeGitWorkspace, worktreeIdentity } from "./gitWorkspace.js";
-import { acquireProjectMaintenanceLocks } from "./projectMaintenanceLock.js";
-import { generateTaskWorkspaceIdentity, taskWorkspaceRefSegment, validateTaskWorkspaceIdentity } from "./taskWorkspaceIdentity.js";
-import { ResourceRegistrar } from "../resources/resourceRegistrar.js";
+import { acquireProjectMaintenanceLocks, ProjectMaintenanceLockCancelledError, ProjectMaintenanceLockedError } from "./projectMaintenanceLock.js";
 import { captureTaskBaseProvenance, recordTaskBaseProvenanceEvents } from "./taskBaseFreshness.js";
-import { managedTaskRoot } from "../storage/homeLayout.js";
+import { generateTaskWorkspaceIdentity, taskWorkspaceRefSegment, validateTaskWorkspaceIdentity } from "./taskWorkspaceIdentity.js";
+import { inspectWorkspaceCleanup } from "./workspaceCleanupInspection.js";
 const MAIN_WORKTREE = "main";
 const LEADER_ROLE = "leader";
 /**
@@ -62,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() {
@@ -75,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
@@ -87,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);
                 }
@@ -116,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;
@@ -139,21 +154,27 @@ export class FileTaskWorkspacePreparer {
                         changed: false
                     };
                 }
+                const admission = admitStoredTaskActivation(this.store, task.id);
+                if (admission.disposition === "absent") {
+                    throw new Error(`Task activation request is required: ${task.id}. `
+                        + `Use yui task activation request ${task.id} --request-id <id> --environment <plan> first.`);
+                }
                 const provider = this.store.getTaskRoleSessionSet(task.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.");
                 }
-                const admission = admitStoredTaskActivation(this.store, task.id);
                 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;
@@ -170,10 +191,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();
@@ -183,9 +222,8 @@ export class FileTaskWorkspacePreparer {
      * Prepares and adopts the resource configuration an explicit activation
      * request named, before any status change.
      *
-     * A Task with no request keeps the historical behavior: its managed workspace
-     * is the whole environment. A request whose plan is empty and whose Task
-     * binds no Project owns nothing physical, and is reported as workspace-free
+     * A request whose plan is empty and whose Task binds no Project owns nothing
+     * physical, and is reported as workspace-free
      * so activation creates no directory at all.
      *
      * The exact request that was adopted travels with the result, so the later
@@ -194,8 +232,6 @@ export class FileTaskWorkspacePreparer {
      */
     async #adoptActivationEnvironment(task) {
         const admission = admitStoredTaskActivation(this.store, task.id);
-        if (admission.disposition === "absent")
-            return { workspaceFree: false };
         if (admission.disposition !== "ready") {
             throw new Error(`Task activation is not adoptable: ${task.id}/${admission.disposition}`
                 + (admission.disposition === "unavailable" ? ` (${admission.reason})` : "")
@@ -330,12 +366,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();
@@ -358,13 +401,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}.`);
         }
@@ -910,15 +956,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
@@ -1099,9 +1147,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)
@@ -1269,6 +1320,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";
@@ -1404,8 +1456,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)
@@ -1413,7 +1468,7 @@ export class FileTaskWorkspacePreparer {
             if (round.status !== "pending") {
                 throw new Error(`ReviewRound workspace can only prepare while pending: ${round.id}.`);
             }
-            const taskScope = (round.scope ?? "work-item") === "task";
+            const taskScope = round.scope === "task";
             const item = taskScope || round.workItemId === undefined
                 ? undefined
                 : requireWorkItem(this.store, task.id, round.workItemId);
@@ -1716,7 +1771,7 @@ export class FileTaskWorkspacePreparer {
     async #reassignTaskReviewWorkspace(task, round, reviewer, reviewRoot, frozenEntries) {
         const previous = this.store.listReviewRounds(task.id)
             .filter((candidate) => (candidate.id !== round.id
-            && (candidate.scope ?? "work-item") === "task"
+            && candidate.scope === "task"
             && candidate.reviewerRoleName === round.reviewerRoleName
             && (candidate.status === "completed" || candidate.status === "failed")
             && candidate.workspaceDisposition?.kind !== "removed"
@@ -1878,6 +1933,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());
@@ -1945,6 +2001,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());
         }
@@ -1998,7 +2055,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;
             }
@@ -2010,7 +2067,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) {
@@ -2023,6 +2080,11 @@ export class FileTaskWorkspacePreparer {
             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
@@ -2042,7 +2104,7 @@ export class FileTaskWorkspacePreparer {
             directory,
             taskSegment: this.#taskSegment(task),
             integrationId: attempt.id,
-            discardChanges: task.status !== "archived" && attempt.status === "failed"
+            discardChanges: options.preserveChanges !== true && task.status !== "archived" && attempt.status === "failed"
         });
         if (result !== "dirty") {
             for (const entry of workspace?.entries ?? []) {
@@ -2067,9 +2129,11 @@ export class FileTaskWorkspacePreparer {
         if (main.owner.type !== "task") {
             throw new Error(`Task main workspace ownership is invalid: ${task.id}.`);
         }
+        if (main.entries.length === 0)
+            return "missing";
         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)
@@ -2084,8 +2148,10 @@ 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") {
+            // Scratch-only workspaces have no Git entries or Git workspace identity.
+            if (main.entries.length > 0 && await this.#inspectEntries(task.id, this.#taskSegment(task), MAIN_WORKTREE, main.entries) === "dirty") {
                 return {
                     taskId,
                     status: "retained-dirty",
@@ -2166,7 +2232,7 @@ export class FileTaskWorkspacePreparer {
         return integrationWorkspaceRoot(this.home, taskId, integrationId);
     }
     #reviewWorktreeName(round) {
-        return (round.scope ?? "work-item") === "task"
+        return round.scope === "task"
             ? `reviewer-${round.reviewerRoleName}`
             : round.id;
     }

package/dist/repository/workspaceCleanupInspection.js

@@ -0,0 +1,187 @@
+import { dirname, isAbsolute, join, relative } from "node:path";
+import { isDeepStrictEqual } from "node:util";
+import { projectTaskRemoteDeliveryFromStore } from "../task/remoteDeliveryService.js";
+import { cleanupCheckFromError } from "../workspace/cleanupInspection.js";
+import { WorkItemChangeSetManager } from "../workspace/workItemChangeSetManager.js";
+import { managedWorkspaceKey, managedWorktreeName } from "../worktree/managedWorkspace.js";
+import { integrationWorktreeIdentity, worktreeIdentity } from "./gitWorkspace.js";
+import { taskWorkspaceRefSegment } from "./taskWorkspaceIdentity.js";
+/** Current owner facts + the same Git inspection used immediately before removal.
+ * No preparation, locks, Git refresh, runtime stop, DB writes or repair.
+ */
+export async function inspectWorkspaceCleanup(store, git, workspace, disposition, forceArchive = false) {
+    const owner = workspace.owner;
+    const task = store.getTask(owner.taskId);
+    if (task === null)
+        throw new Error(`Task not found: ${owner.taskId}.`);
+    const resource = managedWorkspaceKey(owner);
+    const sources = [resource];
+    const actions = workspaceCleanupActions(workspace);
+    const checks = [];
+    const add = (reason, detail, expected, observed) => checks.push({ resource, reason, status: "blocked", detail, expected, observed, sources, actions });
+    if (!isDeepStrictEqual(store.getManagedWorkspace(owner), workspace)) {
+        add("workspace-identity-mismatch", "Current workspace ownership differs from the inspected record.", "same managed workspace", "changed or missing");
+        return checks;
+    }
+    if (task.workspaceIdentity === undefined && workspace.entries.some(e => e.access === "write")) {
+        add("workspace-metadata-missing", "Task has no durable workspace identity; do not infer one from paths.", "recorded Task workspace identity", null);
+        return checks;
+    }
+    let roleName = managedWorktreeName(owner);
+    switch (owner.type) {
+        case "work-item": {
+            const item = store.getWorkItem(task.id, owner.workItemId);
+            if (item === null || !["accepted", "retired"].includes(item.status)) {
+                add("owner-unsettled", "WorkItem must be terminal before cleanup.", ["accepted", "retired"], item?.status ?? null);
+            }
+            if (item?.workspaceDisposition !== undefined && item.workspaceDisposition !== disposition) {
+                add("workspace-disposition-mismatch", "WorkItem cleanup disposition differs from the recorded decision.", item.workspaceDisposition, disposition);
+            }
+            if (item?.status === "accepted" && disposition === "integrated") {
+                const inspection = await new WorkItemChangeSetManager(store).inspectIntegrated(task.id, item.id);
+                checks.push(...inspection.checks);
+            }
+            break;
+        }
+        case "review-round": {
+            const round = store.getReviewRound(task.id, owner.reviewRoundId);
+            if (round === null || !["completed", "failed"].includes(round.status)) {
+                add("owner-unsettled", "ReviewRound must be terminal before cleanup.", ["completed", "failed"], round?.status ?? null);
+            }
+            if (round?.workspace === undefined || !isDeepStrictEqual(round.workspace, workspace)) {
+                add("workspace-metadata-mismatch", "ReviewRound and managed workspace records diverge.", "same workspace in ReviewRound and registry", "different or missing mirror");
+            }
+            if (round?.scope === "task")
+                roleName = `reviewer-${round.reviewerRoleName}`;
+            break;
+        }
+        case "execution-lane": {
+            const group = owner.purpose === "execution"
+                ? store.getWorkItem(task.id, owner.workItemId)?.executionGroups.find(g => g.id === owner.executionGroupId)
+                : store.getReviewRound(task.id, owner.reviewRoundId)?.executionGroup;
+            const lane = group?.id === owner.executionGroupId
+                ? group.lanes.find(l => l.id === owner.executionLaneId) : undefined;
+            if (lane === undefined || lane.disposition === "open") {
+                add("owner-unsettled", "Execution Lane is not terminally resolved.", "settled lane", lane?.disposition ?? null);
+            }
+            break;
+        }
+        case "integration-attempt": {
+            const attempt = store.getIntegrationAttempt(task.id, owner.integrationAttemptId);
+            if (attempt === null || ["running", "blocked", "conflicted", "validating"].includes(attempt.status)) {
+                add("owner-unsettled", "IntegrationAttempt must be terminal before cleanup.", "terminal attempt", attempt?.status ?? null);
+            }
+            break;
+        }
+        case "task":
+            if (!["completed", "cancelled", "archived"].includes(task.status)) {
+                add("task-not-terminal", "Task must be completed or retired before archive cleanup.", ["completed", "cancelled", "archived"], task.status);
+            }
+            break;
+    }
+    const delivery = owner.type === "task" && (disposition === "integrated" || task.status === "archived" || forceArchive)
+        ? await readArchiveDelivery(store, git, task, forceArchive) : undefined;
+    if (delivery !== undefined && (!delivery.allMerged || !delivery.allVerified)) {
+        add("delivery-coverage", "Task main has commits without verified remote coverage; cleanup does not establish delivery.", { allMerged: true, allVerified: true }, { allMerged: delivery.allMerged, allVerified: delivery.allVerified });
+    }
+    for (const entry of workspace.entries.filter(e => e.access === "write")) {
+        const entryResource = `${resource}/${entry.projectId}`;
+        const entryChecks = [];
+        const check = (reason, detail, expected, observed) => entryChecks.push({ resource: entryResource, reason, status: "blocked", detail, expected, observed, sources, actions });
+        // Integration's durable root is its single Project worktree (not the
+        // multi-Project owner container used by the other workspace owners).
+        const container = owner.type === "integration-attempt" ? dirname(workspace.root) : workspace.root;
+        const expectedPath = join(container, entry.directory);
+        if (entry.path !== expectedPath) {
+            check("workspace-path-mismatch", "Recorded path is not the current owner-root/Project path; relocation is not proven.", { ownerRelativePath: entry.directory }, { ownerRelativePath: safeRelativePath(container, entry.path) });
+            checks.push(...entryChecks);
+            continue; // Never inspect a foreign/mismatched path.
+        }
+        const taskSegment = taskWorkspaceRefSegment(task);
+        const expectedBranch = owner.type === "integration-attempt"
+            ? integrationWorktreeIdentity(taskSegment, owner.integrationAttemptId).branch
+            : worktreeIdentity(taskSegment, roleName).branch;
+        if (entry.branch !== expectedBranch) {
+            check("workspace-identity-mismatch", "Recorded branch does not match the exact owner.", expectedBranch, entry.branch);
+            checks.push(...entryChecks);
+            continue;
+        }
+        try {
+            const main = store.getTaskWorkspace(task.id)?.entries.find(e => e.projectId === entry.projectId);
+            if (main === undefined && owner.type !== "task") {
+                check("workspace-metadata-missing", "Task main Git repository reference is unavailable.", "Task main Project entry", null);
+            }
+            else {
+                const state = owner.type === "task"
+                    ? await git.inspectTaskClone({ path: entry.path, container: workspace.root, directory: entry.directory,
+                        taskSegment, branch: entry.branch })
+                    : await git.inspectWorktree({ repositoryPath: main.path, container, directory: entry.directory,
+                        taskSegment, roleName, expectedBranch });
+                if (state === "dirty")
+                    check("dirty-worktree", "Uncommitted or untracked changes must be preserved.", "clean", "dirty");
+                if (owner.type === "task" && state !== "missing" && delivery !== undefined) {
+                    const covered = delivery.projects.find(p => p.projectId === entry.projectId);
+                    const expected = covered?.expectedLocalCommit;
+                    const observed = (await git.inspect(entry.path, "HEAD")).baseCommit;
+                    if (expected != null && expected !== observed && covered?.deliveryLocalCommit !== observed) {
+                        check("head-mismatch", "Task main HEAD differs from the accepted head and its covered publication candidate.", { acceptedCommit: expected, deliveryLocalCommit: covered?.deliveryLocalCommit ?? null }, observed);
+                    }
+                }
+            }
+        }
+        catch (error) {
+            entryChecks.push(...cleanupCheckFromError(error, entryResource, sources, actions));
+        }
+        checks.push(...entryChecks);
+    }
+    return checks;
+}
+/** Reuse Publication's projection, supplying live heads only where its existing
+ * contract asks for them (active/cancelled). Completed/archived heads stay frozen.
+ * Never prepare a workspace or substitute an old binding's commit for a failed read.
+ */
+export async function readArchiveDelivery(store, git, task, forceArchive = false) {
+    const projects = [];
+    // Force admission preserves its existing store-only evidence; it never
+    // freezes new delivery heads merely because an inspection observed them.
+    if (!forceArchive && (task.status === "active" || task.status === "cancelled") && task.workspaceIdentity !== undefined) {
+        const main = store.getTaskWorkspace(task.id);
+        if (main?.owner.type === "task" && main.owner.taskId === task.id) {
+            const branch = worktreeIdentity(taskWorkspaceRefSegment(task), "main").branch;
+            for (const entry of main.entries.filter(e => e.access === "write")) {
+                if (entry.path !== join(main.root, entry.directory) || entry.branch !== branch)
+                    continue;
+                try {
+                    const head = await git.inspect(entry.path, "HEAD");
+                    if (head.root === entry.path && await git.headRef(entry.path) === branch) {
+                        projects.push({ projectId: entry.projectId, commit: head.baseCommit });
+                    }
+                }
+                catch { /* Failed reads remain unavailable in the existing projection. */ }
+            }
+        }
+    }
+    return projectTaskRemoteDeliveryFromStore(store, task, { projects });
+}
+export function workspaceCleanupActions(workspace) {
+    const owner = workspace.owner;
+    switch (owner.type) {
+        case "task": return [`yui task remote-delivery ${owner.taskId}`, `yui task show ${owner.taskId}`];
+        case "work-item": return [`yui task work show ${owner.taskId}/${owner.workItemId}`,
+            `yui task work cleanup ${owner.taskId}/${owner.workItemId} --integrated|--abandon`];
+        case "review-round": return [`yui task work review show ${owner.taskId}/${owner.reviewRoundId}`,
+            `yui task work review cleanup ${owner.taskId}/${owner.reviewRoundId}`];
+        case "integration-attempt": return [`yui task integration show ${owner.taskId}/${owner.integrationAttemptId}`,
+            `yui task integration cleanup ${owner.taskId}/${owner.integrationAttemptId}`];
+        case "execution-lane": return owner.purpose === "execution"
+            ? [`yui task work show ${owner.taskId}/${owner.workItemId}`,
+                `yui task work cleanup ${owner.taskId}/${owner.workItemId} --integrated|--abandon`]
+            : [`yui task work review show ${owner.taskId}/${owner.reviewRoundId}`,
+                `yui task work review cleanup ${owner.taskId}/${owner.reviewRoundId}`];
+    }
+}
+/** Only expose paths inside this already-authorized owner, never foreign paths. */
+export function safeRelativePath(root, path) {
+    const value = relative(root, path);
+    return value === ".." || value.startsWith("../") || isAbsolute(value) ? "[outside owner root]" : value || ".";
+}