@zq-silk/yui 0.15.11 → 0.16.0

package/dist/repository/taskWorkspaceCoordinator.js

@@ -1,7 +1,9 @@
-import { isDeepStrictEqual } from "node:util";
 import { lstat } from "node:fs/promises";
+import { isDeepStrictEqual } from "node:util";
 import { isArchivePersistenceFailure, recordArchiveCleanup } from "../task/archiveDiagnostics.js";
-import { projectTaskRemoteDeliveryFromStore } from "../commands/taskRemoteDeliveryCommand.js";
+import { archiveExecutionChecks, archiveSettlementChecks } from "../task/archivePreflight.js";
+import { projectTaskRemoteDeliveryFromStore } from "../task/remoteDeliveryService.js";
+import { CleanupInspectionError } from "../workspace/cleanupInspection.js";
 import { WorkItemChangeSetManager } from "../workspace/workItemChangeSetManager.js";
 import { hasRuntimeLifecycleWork, runtimeLifecycleTarget } from "../runtime/lifecycleReservation.js";
 import { managedWorkspaceKey } from "../worktree/managedWorkspace.js";
@@ -85,8 +87,12 @@ export class TaskWorkspaceCoordinator {
                 .map(({ projectId }) => projectId);
         const releaseMaintenance = projectIds.length === 0
             ? () => { }
-            : acquireProjectMaintenanceLocks(this.preparer.home, projectIds);
+            : await acquireProjectMaintenanceLocks(this.preparer.home, projectIds);
         try {
+            if (!isDeepStrictEqual(this.store.getWorkItem(taskId, workItemId), item)
+                || !isDeepStrictEqual(this.store.getWorkItemWorkspace(taskId, workItemId), workspace)) {
+                throw new Error(`Work item changed while waiting for cleanup: ${taskId}/${workItemId}.`);
+            }
             const state = await this.preparer.inspectWorkItemWorkspace(item.taskId, item.id);
             if (state === "dirty")
                 return "dirty";
@@ -96,7 +102,7 @@ export class TaskWorkspaceCoordinator {
             const laneCleanup = await this.preparer.cleanupExecutionLaneWorkspacesForWorkItem(item.taskId, item.id);
             if (laneCleanup === "dirty")
                 return "dirty";
-            return this.preparer.cleanupWorkItemWorkspace(item.taskId, item.id, disposition);
+            return await this.preparer.cleanupWorkItemWorkspace(item.taskId, item.id, disposition);
         }
         finally {
             releaseMaintenance();
@@ -137,8 +143,12 @@ export class TaskWorkspaceCoordinator {
                 .map(({ projectId }) => projectId);
         const releaseMaintenance = projectIds.length === 0
             ? () => { }
-            : acquireProjectMaintenanceLocks(this.preparer.home, projectIds);
+            : await acquireProjectMaintenanceLocks(this.preparer.home, projectIds);
         try {
+            if (!isDeepStrictEqual(this.store.getReviewRound(taskId, reviewRoundId), round)
+                || !isDeepStrictEqual(this.store.getReviewRoundWorkspace(taskId, reviewRoundId), workspace)) {
+                throw new Error(`ReviewRound changed while waiting for cleanup: ${taskId}/${reviewRoundId}.`);
+            }
             const state = await this.preparer.inspectReviewRoundWorkspace(taskId, reviewRoundId);
             if (state === "dirty")
                 return "dirty";
@@ -146,7 +156,7 @@ export class TaskWorkspaceCoordinator {
             const laneCleanup = await this.preparer.cleanupExecutionLaneWorkspacesForReviewRound(taskId, reviewRoundId);
             if (laneCleanup === "dirty")
                 return "dirty";
-            return this.preparer.cleanupReviewRoundWorkspace(taskId, reviewRoundId);
+            return await this.preparer.cleanupReviewRoundWorkspace(taskId, reviewRoundId);
         }
         finally {
             releaseMaintenance();
@@ -161,6 +171,9 @@ export class TaskWorkspaceCoordinator {
             if (task.status !== "completed" && task.status !== "cancelled") {
                 throw new Error(`Task must be completed or retired before archive cleanup: ${task.id}.`);
             }
+            const settlement = [...archiveSettlementChecks(this.store, task), ...archiveExecutionChecks(this.store, taskId)];
+            if (settlement.length > 0)
+                throw new CleanupInspectionError(settlement);
             const managedWorkspaces = [...this.store.listManagedWorkspaces(task.id)]
                 .sort((left, right) => managedWorkspaceKey(left.owner)
                 .localeCompare(managedWorkspaceKey(right.owner)));
@@ -172,7 +185,14 @@ export class TaskWorkspaceCoordinator {
                 for (const entry of workspace.entries)
                     projectIds.add(entry.projectId);
             }
-            releaseMaintenance = acquireProjectMaintenanceLocks(this.preparer.home, projectIds);
+            releaseMaintenance = await acquireProjectMaintenanceLocks(this.preparer.home, projectIds);
+            this.#assertTaskArchiveLifecycle(task);
+            const currentWorkspaces = [...this.store.listManagedWorkspaces(task.id)]
+                .sort((left, right) => managedWorkspaceKey(left.owner)
+                .localeCompare(managedWorkspaceKey(right.owner)));
+            if (!isDeepStrictEqual(currentWorkspaces, managedWorkspaces)) {
+                throw new Error(`Task workspaces changed while waiting for archive cleanup: ${taskId}.`);
+            }
             const laneWorkspaces = managedWorkspaces.filter(({ owner }) => owner.type === "execution-lane");
             const integrationWorkspaces = managedWorkspaces.filter(({ owner }) => owner.type === "integration-attempt");
             const workspaces = managedWorkspaces
@@ -200,93 +220,22 @@ export class TaskWorkspaceCoordinator {
                 workItems: allWorkItems,
                 reviewRounds: allReviewRounds
             };
-            for (const round of reviewRounds) {
-                if (round.status !== "completed" && round.status !== "failed") {
-                    throw new Error(`ReviewRound must be terminal before archive cleanup: ${round.id}.`);
-                }
-                if (await this.preparer.inspectReviewRoundWorkspace(task.id, round.id) === "dirty") {
-                    return {
-                        taskId,
-                        status: "retained-dirty",
-                        ...(task.cwd === undefined ? {} : { path: task.cwd }),
-                        error: `ReviewRound worktree is dirty: ${round.id}.`,
-                        reason: "dirty-worktree",
-                        resource: `review-round:${task.id}/${round.id}`,
-                        retryable: true
-                    };
-                }
-            }
-            for (const item of workItems) {
-                if (await this.preparer.inspectWorkItemWorkspace(task.id, item.id) === "dirty") {
-                    return {
-                        taskId,
-                        status: "retained-dirty",
-                        ...(task.cwd === undefined ? {} : { path: task.cwd }),
-                        error: `WorkItem worktree is dirty: ${item.id}.`,
-                        reason: "dirty-worktree",
-                        resource: `work-item:${task.id}/${item.id}`,
-                        retryable: true
-                    };
-                }
-            }
-            for (const workspace of laneWorkspaces) {
-                if (workspace.owner.type !== "execution-lane")
-                    continue;
-                if (await this.preparer.inspectExecutionLaneWorkspace(task.id, workspace.owner.executionGroupId, workspace.owner.executionLaneId) === "dirty") {
-                    return {
-                        taskId,
-                        status: "retained-dirty",
-                        ...(task.cwd === undefined ? {} : { path: task.cwd }),
-                        error: `Execution Lane worktree is dirty: ${managedWorkspaceKey(workspace.owner)}.`,
-                        reason: "dirty-worktree",
-                        resource: managedWorkspaceKey(workspace.owner),
-                        retryable: true
-                    };
-                }
-            }
-            for (const workspace of integrationWorkspaces) {
-                if (workspace.owner.type !== "integration-attempt")
-                    continue;
-                const attempt = this.store.getIntegrationAttempt(task.id, workspace.owner.integrationAttemptId);
-                if (attempt === null
-                    || attempt.status === "running"
-                    || attempt.status === "blocked"
-                    || attempt.status === "conflicted"
-                    || attempt.status === "validating") {
-                    throw new Error(`IntegrationAttempt must be terminal before archive cleanup: ${workspace.owner.integrationAttemptId}.`);
-                }
-                if (await this.preparer.inspectIntegrationWorkspace(task.id, attempt.id) === "dirty") {
-                    return {
-                        taskId,
-                        status: "retained-dirty",
-                        ...(task.cwd === undefined ? {} : { path: task.cwd }),
-                        error: `Integration worktree is dirty: ${attempt.id}.`,
-                        reason: "dirty-worktree",
-                        resource: `integration-attempt:${task.id}/${attempt.id}`,
-                        retryable: true
-                    };
-                }
-            }
-            const state = await this.preparer.inspectTaskMainWorkspace(taskId);
-            if (state === "dirty") {
-                return {
-                    taskId,
-                    status: "retained-dirty",
-                    ...(task.cwd === undefined ? {} : { path: task.cwd }),
-                    error: `Task main worktree is dirty: ${task.id}.`,
-                    reason: "dirty-worktree",
-                    resource: `task-worktree:${task.id}`,
-                    retryable: true
-                };
-            }
-            const activeRole = this.store.listRoles(taskId)
-                .find((role) => this.store.getActiveRun(taskId, role.name) !== null);
-            if (activeRole !== undefined) {
-                throw new WorkspaceCleanupBlockedError("active-turn", `role:${task.id}/${activeRole.name}`, true, `Task Role still has an active AgentRun: ${task.id}/${activeRole.name}.`);
+            const checks = [];
+            for (const workspace of managedWorkspaces) {
+                const workspaceDisposition = workspace.owner.type === "work-item"
+                    && this.store.getWorkItem(task.id, workspace.owner.workItemId)?.status === "retired" ? "abandoned" : disposition;
+                const inspected = await this.preparer.inspectWorkspaceCleanup(workspace, workspaceDisposition);
+                // Child worktrees are removed first below. Their Git registrations
+                // necessarily exist now; the clone's removal boundary rechecks them
+                // after every child cleanup and never removes an unresolved owner.
+                checks.push(...inspected.filter(c => !(workspace.owner.type === "task"
+                    && c.reason === "git-worktree-registrations")));
             }
+            if (checks.length > 0)
+                throw new CleanupInspectionError(checks);
             const roleNames = this.store.listRoles(taskId).map(({ name }) => name);
             await this.#stopLiveRoles(taskId, roleNames);
-            await this.runtime.assertTaskPhysicalResourcesReleased?.(task.id);
+            await this.runtime.releaseTaskTerminals(task.id);
             this.#assertTaskArchiveSnapshot(snapshot);
             for (const workspace of laneWorkspaces) {
                 this.#assertTaskArchiveLifecycle(task);
@@ -297,7 +246,7 @@ export class TaskWorkspaceCoordinator {
             for (const workspace of integrationWorkspaces) {
                 this.#assertTaskArchiveLifecycle(task);
                 if (workspace.owner.type === "integration-attempt") {
-                    await this.preparer.cleanupIntegrationWorkspace(task.id, workspace.owner.integrationAttemptId);
+                    await this.preparer.cleanupIntegrationWorkspace(task.id, workspace.owner.integrationAttemptId, { preserveChanges: true });
                 }
             }
             for (const round of reviewRounds) {
@@ -309,26 +258,30 @@ export class TaskWorkspaceCoordinator {
                 await this.preparer.cleanupWorkItemWorkspace(task.id, item.id, item.status === "accepted" ? disposition : "abandoned");
             }
             this.#assertTaskArchiveLifecycle(task);
-            return this.preparer.cleanupTaskForArchive(taskId);
+            return await this.preparer.cleanupTaskForArchive(taskId, disposition);
         }
         catch (error) {
             const task = this.store.getTask(taskId);
             return {
                 taskId,
-                status: "failed",
+                status: error instanceof CleanupInspectionError && error.checks.every(c => c.reason === "dirty-worktree")
+                    ? "retained-dirty" : "failed",
                 ...(task?.cwd === undefined ? {} : { path: task.cwd }),
                 error: error instanceof Error ? error.message : String(error),
-                ...(error instanceof WorkspaceCleanupBlockedError
-                    ? {
-                        reason: error.reason,
-                        resource: error.resource,
-                        retryable: error.retryable
-                    }
-                    : {
-                        reason: "cleanup-failed",
-                        resource: `task:${taskId}`,
-                        retryable: true
-                    })
+                ...(error instanceof CleanupInspectionError
+                    ? { checks: error.checks, reason: error.checks[0]?.reason ?? "cleanup-failed",
+                        resource: error.checks[0]?.resource ?? `task:${taskId}`, retryable: true }
+                    : error instanceof WorkspaceCleanupBlockedError
+                        ? {
+                            reason: error.reason,
+                            resource: error.resource,
+                            retryable: error.retryable
+                        }
+                        : {
+                            reason: "cleanup-failed",
+                            resource: `task:${taskId}`,
+                            retryable: true
+                        })
             };
         }
         finally {
@@ -368,15 +321,9 @@ export class TaskWorkspaceCoordinator {
         for (const role of this.store.listRoles(taskId)) {
             const released = await attempt({ resource: `role:${taskId}/${role.name}`,
                 detail: "Exact Role runtime stop." }, async () => {
-                const provider = this.store.getTaskRoleSessionSet(taskId, role.name)?.providerBinding;
-                const mailbox = this.store.getWorkMailbox({ kind: "role", taskId, roleName: role.name });
-                if (mailbox?.processing != null && (provider?.run == null
-                    || !["completed", "failed", "cancelled"].includes(provider.run.status))) {
-                    throw new Error(`Original mailbox claim ${mailbox.processing.batchId} retained; execution outcome is not known.`);
-                }
-                if (provider?.run != null && !["completed", "failed", "cancelled"].includes(provider.run.status)) {
-                    throw new Error(`Provider input ${provider.run.attemptId}/${provider.run.status} retained; establish exact quiescence before resolving it.`);
-                }
+                const checks = archiveExecutionChecks(this.store, taskId).filter(c => c.resource === `role:${taskId}/${role.name}`);
+                if (checks.length > 0)
+                    throw new CleanupInspectionError(checks);
                 await this.#stopLiveRoles(taskId, [role.name]);
                 return "released";
             });
@@ -384,17 +331,12 @@ export class TaskWorkspaceCoordinator {
         }
         const physicalReleased = await attempt({ resource: `runtime:${taskId}`,
             detail: "Verify exact physical resource release before workspace deletion." }, async () => {
-            const activeRun = this.store.listRuns(taskId).find(r => r.status === "active");
-            const job = this.store.listDurableJobs(taskId).find(j => ["queued", "running", "unknown-needs-attention"].includes(j.status));
-            if (activeRun !== undefined || job !== undefined) {
-                throw new Error(`Execution resources retained: ${activeRun?.id ?? job?.id}; archive is not proof of quiescence.`);
-            }
+            const checks = archiveExecutionChecks(this.store, taskId);
+            if (checks.length > 0)
+                throw new CleanupInspectionError(checks);
             if (!runtimeReleased)
                 throw new Error("One or more Role runtimes could not be safely released.");
-            if (this.runtime.assertTaskPhysicalResourcesReleased === undefined) {
-                throw new Error("Physical resource release inspection is unavailable; workspace references retained.");
-            }
-            await this.runtime.assertTaskPhysicalResourcesReleased(taskId);
+            await this.runtime.releaseTaskTerminals(taskId);
             return "released";
         });
         if (physicalReleased) {
@@ -406,7 +348,7 @@ export class TaskWorkspaceCoordinator {
                     detail: "Remove only clean, exactly owned workspace resources.",
                     paths: [workspace.root, ...workspace.entries.filter(e => e.access === "write").map(e => e.path)]
                 }, async () => {
-                    const release = acquireProjectMaintenanceLocks(this.preparer.home, workspace.entries.map(e => e.projectId));
+                    const release = await acquireProjectMaintenanceLocks(this.preparer.home, workspace.entries.map(e => e.projectId));
                     try {
                         if (!isDeepStrictEqual(this.store.getManagedWorkspace(workspace.owner), workspace)) {
                             throw new Error("Workspace ownership changed; retained.");
@@ -418,16 +360,16 @@ export class TaskWorkspaceCoordinator {
                                 if (item?.status === "accepted" && disposition === "integrated") {
                                     await new WorkItemChangeSetManager(this.store).assertIntegrated(taskId, item.id);
                                 }
-                                return this.preparer.cleanupWorkItemWorkspace(taskId, owner.workItemId, item?.status === "retired" ? "abandoned" : disposition);
+                                return await this.preparer.cleanupWorkItemWorkspace(taskId, owner.workItemId, item?.status === "retired" ? "abandoned" : disposition);
                             }
                             case "review-round":
-                                return this.preparer.cleanupReviewRoundWorkspace(taskId, owner.reviewRoundId);
+                                return await this.preparer.cleanupReviewRoundWorkspace(taskId, owner.reviewRoundId);
                             case "execution-lane":
-                                return this.preparer.cleanupExecutionLaneWorkspace(taskId, owner.executionGroupId, owner.executionLaneId);
+                                return await this.preparer.cleanupExecutionLaneWorkspace(taskId, owner.executionGroupId, owner.executionLaneId);
                             case "integration-attempt":
                                 if (await this.preparer.inspectIntegrationWorkspace(taskId, owner.integrationAttemptId) === "dirty")
                                     return "dirty";
-                                return this.preparer.cleanupIntegrationWorkspace(taskId, owner.integrationAttemptId);
+                                return await this.preparer.cleanupIntegrationWorkspace(taskId, owner.integrationAttemptId, { preserveChanges: true });
                             case "task": {
                                 const current = this.store.getTask(taskId);
                                 const delivery = projectTaskRemoteDeliveryFromStore(this.store, current);
@@ -435,7 +377,8 @@ export class TaskWorkspaceCoordinator {
                                     throw new Error("Task main retained: local commits are not covered by verified remote delivery. Force does not discard them.");
                                 }
                                 for (const entry of workspace.entries.filter(e => e.access === "write")) {
-                                    const expected = delivery.projects.find(p => p.projectId === entry.projectId)?.expectedLocalCommit;
+                                    const covered = delivery.projects.find(p => p.projectId === entry.projectId);
+                                    const expected = covered?.expectedLocalCommit;
                                     const path = await lstat(entry.path).catch(error => {
                                         if (error.code === "ENOENT")
                                             return null;
@@ -444,11 +387,12 @@ export class TaskWorkspaceCoordinator {
                                     if (expected !== null && expected !== undefined
                                         && path !== null) {
                                         const actual = await this.preparer.git.inspect(entry.path, "HEAD");
-                                        if (actual.baseCommit !== expected)
+                                        if (actual.baseCommit !== expected && actual.baseCommit !== covered?.deliveryLocalCommit) {
                                             throw new Error(`Task main HEAD changed: ${entry.path}; retained.`);
+                                        }
                                     }
                                 }
-                                const result = await this.preparer.cleanupTaskForArchive(taskId);
+                                const result = await this.preparer.cleanupTaskForArchive(taskId, disposition);
                                 if (result.status !== "removed")
                                     throw new Error(result.error ?? "Task main or dependent workspace retained.");
                                 return "removed";
@@ -500,9 +444,7 @@ export class TaskWorkspaceCoordinator {
      * human/Leader has taken responsibility for the outcome.
      */
     #assertNoActiveWorkItemDurableJobs(item) {
-        const jobs = this.store.listDurableJobs?.(item.taskId);
-        if (jobs === undefined)
-            return;
+        const jobs = this.store.listDurableJobs(item.taskId);
         const blocking = jobs.filter((job) => (job.owner.kind === "work-item"
             && job.owner.workItemId === item.id
             && (job.status === "queued"
@@ -523,18 +465,16 @@ export class TaskWorkspaceCoordinator {
     #reviewRoundRoleNames(round) {
         return [
             round.reviewerRoleName,
-            ...(round.executionGroup?.lanes.map(({ roleName }) => roleName) ?? []),
             ...(round.executionGroup?.lanes.map(({ roleName }) => roleName) ?? [])
         ];
     }
     async #stopLiveRoles(taskId, roleNames) {
         const targets = [...new Set(roleNames)];
-        const getActiveRun = this.store.getActiveRun?.bind(this.store);
         for (const roleName of targets) {
-            if (getActiveRun !== undefined && getActiveRun(taskId, roleName) !== null) {
+            if (this.store.getActiveRun(taskId, roleName) !== null) {
                 throw new Error(`Role has an active AgentRun: ${taskId}/${roleName}.`);
             }
-            if (this.store.getWorkMailbox !== undefined && hasRuntimeLifecycleWork(this.store.getWorkMailbox(runtimeLifecycleTarget({ scope: "task", taskId, roleName })))) {
+            if (hasRuntimeLifecycleWork(this.store.getWorkMailbox(runtimeLifecycleTarget({ scope: "task", taskId, roleName })))) {
                 throw new Error(`Role has unsettled runtime lifecycle state: ${taskId}/${roleName}.`);
             }
         }
@@ -551,11 +491,9 @@ export class TaskWorkspaceCoordinator {
         });
         if (live.length > 0)
             await this.runtime.stopTaskRoleSessions(taskId, live);
-        // The aggregate-16 dormant Claude placeholder is the sole exception to
-        // strict workspace-session retirement. The synchronous pane inspection is
-        // performed while holding the Task store transaction so a normal launch
-        // cannot reserve a AgentRun/Session between absence proof and terminalization.
-        if (inspect === undefined || this.store.transaction === undefined)
+        // Recheck exact runtime quiescence under the Task transaction when this
+        // runtime exposes physical panes. Store reads are always authoritative.
+        if (inspect === undefined)
             return;
         this.store.transaction((tx) => {
             const panes = inspect(taskId);
@@ -566,7 +504,7 @@ export class TaskWorkspaceCoordinator {
                 if (tx.getActiveRun(taskId, roleName) !== null) {
                     throw new Error(`Role has an active AgentRun: ${taskId}/${roleName}.`);
                 }
-                if (tx.getWorkMailbox !== undefined && hasRuntimeLifecycleWork(tx.getWorkMailbox(runtimeLifecycleTarget({ scope: "task", taskId, roleName })))) {
+                if (hasRuntimeLifecycleWork(tx.getWorkMailbox(runtimeLifecycleTarget({ scope: "task", taskId, roleName })))) {
                     throw new Error(`Role has unsettled runtime lifecycle state: ${taskId}/${roleName}.`);
                 }
             }