@zq-silk/yui 0.15.9 → 0.15.12

package/dist/repository/projectMaintenanceLock.js

@@ -1,5 +1,7 @@
 import { existsSync, mkdirSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
+import { performance } from "node:perf_hooks";
+import { setTimeout as delay } from "node:timers/promises";
 /**
  * Per-Project maintenance fence.
  *
@@ -12,35 +14,66 @@ import { join } from "node:path";
  * gone; the owner file records PID + process start time, so a recycled PID
  * can never pass for the original holder.
  *
- * Maintenance operations are long-lived, so a contended fence fails fast
- * with a retryable error instead of blocking the CLI for seconds.
+ * Contenders wait asynchronously within one monotonic budget. Only lock
+ * acquisition is retried; the caller's protected operation is never replayed.
  */
-const PROJECT_MAINTENANCE_LOCK_TIMEOUT_MS = 250;
-const PROJECT_MAINTENANCE_LOCK_RETRY_MS = 10;
+const PROJECT_MAINTENANCE_LOCK_TIMEOUT_MS = 60_000;
+const PROJECT_MAINTENANCE_LOCK_RETRY_MIN_MS = 200;
+const PROJECT_MAINTENANCE_LOCK_RETRY_MAX_MS = 500;
 /** A lock older than this with a dead owner is reclaimed. */
 const STALE_PROJECT_MAINTENANCE_LOCK_AGE_MS = 1_000;
 /**
- * Raised when a Project's maintenance fence is already held. The caller
- * made no changes and is safe to retry once the holder finishes.
+ * Raised when acquisition exhausted its budget. This acquisition has not
+ * started the protected operation; callers retain responsibility for any
+ * earlier effects and must not replay the whole operation implicitly.
  */
 export class ProjectMaintenanceLockedError extends Error {
+    timeoutMs;
     projectId;
     retryable = true;
-    constructor(projectId) {
-        super(`Project maintenance is already in progress for ${projectId}; retry once it finishes.`);
+    constructor(projectId, timeoutMs = PROJECT_MAINTENANCE_LOCK_TIMEOUT_MS) {
+        super(`Timed out after ${timeoutMs}ms waiting for Project maintenance on ${projectId}; `
+            + "the lock was not acquired. Read current state before retrying.");
+        this.timeoutMs = timeoutMs;
         this.name = "ProjectMaintenanceLockedError";
         this.projectId = projectId;
     }
 }
+export class ProjectMaintenanceLockCancelledError extends Error {
+    projectId;
+    constructor(projectId, cause) {
+        super(`Cancelled waiting for Project maintenance on ${projectId}; the lock was not acquired.`, { cause });
+        this.projectId = projectId;
+        this.name = "ProjectMaintenanceLockCancelledError";
+    }
+}
+function acquisitionBudget(options) {
+    const timeoutMs = options.timeoutMs ?? PROJECT_MAINTENANCE_LOCK_TIMEOUT_MS;
+    if (!Number.isFinite(timeoutMs) || timeoutMs < 0) {
+        throw new RangeError("Project maintenance timeout must be a finite nonnegative number.");
+    }
+    const now = options.now ?? (() => performance.now());
+    return {
+        timeoutMs,
+        deadline: now() + timeoutMs,
+        now,
+        random: options.random ?? Math.random,
+        wait: options.wait ?? ((milliseconds, signal) => delay(milliseconds, undefined, { signal })),
+        signal: options.signal
+    };
+}
+function assertNotCancelled(projectId, signal) {
+    if (signal?.aborted)
+        throw new ProjectMaintenanceLockCancelledError(projectId, signal.reason);
+}
 /** Directory of one Project's maintenance fence, below the Home's locks area. */
 export function projectMaintenanceLockPath(home, projectId) {
     return join(home, "locks", "projects", `${projectId}.lock`);
 }
 /**
  * Acquire one Project's maintenance fence. Returns the release function;
- * callers MUST release on every exit path (try/finally). A live holder
- * fails fast with {@link ProjectMaintenanceLockedError}; a stale (dead)
- * holder is reclaimed.
+ * callers MUST release on every exit path (try/finally). A live holder is
+ * never stolen, including at timeout; a stale (dead) holder is reclaimed.
  *
  * There is no in-process reentrancy: every acquisition contends, so two
  * independent operations in the same process are mutually exclusive just
@@ -48,11 +81,22 @@ export function projectMaintenanceLockPath(home, projectId) {
  * fence while its caller already holds it) goes through private
  * already-locked methods, never through a second acquisition.
  */
-export function acquireProjectMaintenanceLock(home, projectId) {
+export function acquireProjectMaintenanceLock(home, projectId, options = {}) {
+    return acquireWithBudget(home, projectId, acquisitionBudget(options));
+}
+async function acquireWithBudget(home, projectId, budget, firstProject = true) {
     const lock = projectMaintenanceLockPath(home, projectId);
+    assertNotCancelled(projectId, budget.signal);
     mkdirSync(join(home, "locks", "projects"), { recursive: true, mode: 0o700 });
-    const deadline = Date.now() + PROJECT_MAINTENANCE_LOCK_TIMEOUT_MS;
+    let firstAttempt = firstProject;
     while (true) {
+        assertNotCancelled(projectId, budget.signal);
+        // Always try the first Project immediately, even for a zero-budget probe.
+        // Every retry and subsequent Project shares the original deadline.
+        if (!firstAttempt && budget.now() >= budget.deadline) {
+            throw new ProjectMaintenanceLockedError(projectId, budget.timeoutMs);
+        }
+        firstAttempt = false;
         try {
             mkdirSync(lock, { mode: 0o700 });
             const ownerIdentity = writeOwnerIdentity(lock);
@@ -70,10 +114,22 @@ export function acquireProjectMaintenanceLock(home, projectId) {
         catch (error) {
             if (!(error instanceof Error && "code" in error && error.code === "EEXIST"))
                 throw error;
+            if (budget.now() >= budget.deadline) {
+                throw new ProjectMaintenanceLockedError(projectId, budget.timeoutMs);
+            }
             reclaimStaleProjectMaintenanceLock(lock);
-            if (Date.now() >= deadline)
-                throw new ProjectMaintenanceLockedError(projectId);
-            Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, PROJECT_MAINTENANCE_LOCK_RETRY_MS);
+            const remaining = budget.deadline - budget.now();
+            if (remaining <= 0)
+                throw new ProjectMaintenanceLockedError(projectId, budget.timeoutMs);
+            const jitter = PROJECT_MAINTENANCE_LOCK_RETRY_MIN_MS
+                + budget.random() * (PROJECT_MAINTENANCE_LOCK_RETRY_MAX_MS - PROJECT_MAINTENANCE_LOCK_RETRY_MIN_MS);
+            try {
+                await budget.wait(Math.min(jitter, remaining), budget.signal);
+            }
+            catch (waitError) {
+                assertNotCancelled(projectId, budget.signal);
+                throw waitError;
+            }
         }
     }
 }
@@ -108,11 +164,12 @@ function releaseOwnedProjectMaintenanceLock(lock, ownerIdentity) {
  * including ones this process already holds: callers that need nesting must
  * use an already-locked private path instead of acquiring twice.
  */
-export function acquireProjectMaintenanceLocks(home, projectIds) {
+export async function acquireProjectMaintenanceLocks(home, projectIds, options = {}) {
+    const budget = acquisitionBudget(options);
     const releases = [];
     try {
         for (const projectId of [...new Set(projectIds)].sort()) {
-            releases.push(acquireProjectMaintenanceLock(home, projectId));
+            releases.push(await acquireWithBudget(home, projectId, budget, releases.length === 0));
         }
     }
     catch (error) {

package/dist/repository/taskWorkspaceCoordinator.js

@@ -1,4 +1,10 @@
 import { isDeepStrictEqual } from "node:util";
+import { lstat } from "node:fs/promises";
+import { isArchivePersistenceFailure, recordArchiveCleanup } from "../task/archiveDiagnostics.js";
+import { projectTaskRemoteDeliveryFromStore } from "../commands/taskRemoteDeliveryCommand.js";
+import { WorkItemChangeSetManager } from "../workspace/workItemChangeSetManager.js";
+import { archiveSettlementChecks, archiveExecutionChecks } from "../task/archivePreflight.js";
+import { CleanupInspectionError } from "../workspace/cleanupInspection.js";
 import { hasRuntimeLifecycleWork, runtimeLifecycleTarget } from "../runtime/lifecycleReservation.js";
 import { managedWorkspaceKey } from "../worktree/managedWorkspace.js";
 import { acquireProjectMaintenanceLocks } from "./projectMaintenanceLock.js";
@@ -81,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";
@@ -92,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();
@@ -133,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";
@@ -142,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();
@@ -157,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)));
@@ -168,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
@@ -196,89 +220,19 @@ 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 === "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);
@@ -292,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) {
@@ -304,32 +258,159 @@ 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 {
             releaseMaintenance?.();
         }
     }
+    /** Best-effort cleanup only after explicit force admission has committed.
+     * This is one foreground attempt, not a retry worker. Each independent result
+     * is durable before continuing, and a failed audit write really fails.
+     */
+    async cleanupArchivedTask(taskId, disposition) {
+        const task = this.store.getTask(taskId);
+        if (task?.status !== "archived"
+            || !this.store.listEvents(taskId).some(e => e.type === "task.archived" && e.payload.force === "true")) {
+            throw new Error(`Force archive must commit before cleanup: ${taskId}.`);
+        }
+        const attempt = async (diagnostic, action) => {
+            recordArchiveCleanup(this.store, taskId, diagnostic, "started");
+            let status;
+            let detail = diagnostic.detail;
+            try {
+                const result = await action();
+                status = result === "dirty" ? "retained" : result;
+                if (result === "dirty")
+                    detail = "Dirty workspace retained; force archive does not discard local changes.";
+            }
+            catch (error) {
+                if (isArchivePersistenceFailure(error))
+                    throw error;
+                status = "retained";
+                detail = error instanceof Error ? error.message : String(error);
+            }
+            recordArchiveCleanup(this.store, taskId, { ...diagnostic, detail }, status);
+            return status !== "retained";
+        };
+        let runtimeReleased = true;
+        for (const role of this.store.listRoles(taskId)) {
+            const released = await attempt({ resource: `role:${taskId}/${role.name}`,
+                detail: "Exact Role runtime stop." }, async () => {
+                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";
+            });
+            runtimeReleased &&= released;
+        }
+        const physicalReleased = await attempt({ resource: `runtime:${taskId}`,
+            detail: "Verify exact physical resource release before workspace deletion." }, async () => {
+            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);
+            return "released";
+        });
+        if (physicalReleased) {
+            // Task main owns the Git objects of its dependent worktrees, so it is
+            // always last and remains when any dependent cleanup is unresolved.
+            const workspaces = this.store.listManagedWorkspaces(taskId).sort((a, b) => Number(a.owner.type === "task") - Number(b.owner.type === "task"));
+            for (const workspace of workspaces) {
+                await attempt({ resource: managedWorkspaceKey(workspace.owner),
+                    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 = 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.");
+                        }
+                        const owner = workspace.owner;
+                        switch (owner.type) {
+                            case "work-item": {
+                                const item = this.store.getWorkItem(taskId, owner.workItemId);
+                                if (item?.status === "accepted" && disposition === "integrated") {
+                                    await new WorkItemChangeSetManager(this.store).assertIntegrated(taskId, item.id);
+                                }
+                                return await this.preparer.cleanupWorkItemWorkspace(taskId, owner.workItemId, item?.status === "retired" ? "abandoned" : disposition);
+                            }
+                            case "review-round":
+                                return await this.preparer.cleanupReviewRoundWorkspace(taskId, owner.reviewRoundId);
+                            case "execution-lane":
+                                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 await this.preparer.cleanupIntegrationWorkspace(taskId, owner.integrationAttemptId, { preserveChanges: true });
+                            case "task": {
+                                const current = this.store.getTask(taskId);
+                                const delivery = projectTaskRemoteDeliveryFromStore(this.store, current);
+                                if (!delivery.allMerged || !delivery.allVerified) {
+                                    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 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;
+                                        throw error;
+                                    });
+                                    if (expected !== null && expected !== undefined
+                                        && path !== null) {
+                                        const actual = await this.preparer.git.inspect(entry.path, "HEAD");
+                                        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, disposition);
+                                if (result.status !== "removed")
+                                    throw new Error(result.error ?? "Task main or dependent workspace retained.");
+                                return "removed";
+                            }
+                        }
+                    }
+                    finally {
+                        release();
+                    }
+                });
+            }
+        }
+        recordArchiveCleanup(this.store, taskId, { resource: `task:${taskId}`,
+            detail: "Foreground cleanup attempt finished; inspect retained resource references and warnings." }, "finished");
+    }
     #assertTaskArchiveSnapshot(snapshot) {
         this.#assertTaskArchiveLifecycle(snapshot.task);
         const managedWorkspaces = [...this.store.listManagedWorkspaces(snapshot.task.id)]