@zq-silk/yui 0.15.11 → 0.15.12

package/dist/repository/taskWorkspacePreparer.js

@@ -19,11 +19,13 @@ import { enqueueWork } from "../coordination/workMailboxQueue.js";
 import { createCandidateGitSnapshot, createDirectTaskMainSnapshot, workItemExecutionGroupById, recordWorkItemWorkspaceDisposition } from "../workItem/workItem.js";
 import { createManagedWorkspace, isTaskOwnedWorkspace, managedWorkspaceKey, managedWorktreeName, sameManagedWorkspaceIdentity } from "../worktree/managedWorkspace.js";
 import { NodeGitWorkspace, worktreeIdentity } from "./gitWorkspace.js";
-import { acquireProjectMaintenanceLocks } from "./projectMaintenanceLock.js";
+import { acquireProjectMaintenanceLocks, ProjectMaintenanceLockedError, ProjectMaintenanceLockCancelledError } from "./projectMaintenanceLock.js";
 import { generateTaskWorkspaceIdentity, taskWorkspaceRefSegment, validateTaskWorkspaceIdentity } from "./taskWorkspaceIdentity.js";
 import { ResourceRegistrar } from "../resources/resourceRegistrar.js";
 import { captureTaskBaseProvenance, recordTaskBaseProvenanceEvents } from "./taskBaseFreshness.js";
 import { managedTaskRoot } from "../storage/homeLayout.js";
+import { inspectWorkspaceCleanup } from "./workspaceCleanupInspection.js";
+import { CleanupInspectionError } from "../workspace/cleanupInspection.js";
 const MAIN_WORKTREE = "main";
 const LEADER_ROLE = "leader";
 /**
@@ -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;
@@ -148,12 +163,14 @@ export class FileTaskWorkspacePreparer {
                 if (admission.disposition === "ready")
                     attemptedRequest = admission.request;
                 validateDraftTaskForActivation(this.store, task);
-                const adopted = await this.#adoptActivationEnvironment(task);
-                return adopted.workspaceFree
-                    ? this.#activateWorkspaceFreeTask(task.id, adopted, actor)
-                    : await this.#prepareActivatedTaskWorkspace(task, adopted, actor);
+                return await this.#prepareActivatedTaskWorkspace(task, actor, environment, signal);
             }
             catch (error) {
+                // Waiting did not execute the workspace operation. Preserve the
+                // activation request instead of turning contention/stop into failure.
+                if (error instanceof ProjectMaintenanceLockedError
+                    || error instanceof ProjectMaintenanceLockCancelledError)
+                    throw error;
                 if (error instanceof StorageConflictError
                     && attempt < TASK_WORKSPACE_PREPARE_MAX_CONFLICT_RETRIES) {
                     continue;
@@ -170,10 +187,28 @@ export class FileTaskWorkspacePreparer {
         }
     }
     /** Prepares the managed workspace of a Task being activated, under its fences. */
-    async #prepareActivatedTaskWorkspace(task, environment, actor) {
-        const { release, current } = this.#acquireTaskProjectMaintenanceLocks(task);
+    async #prepareActivatedTaskWorkspace(task, actor, callerEnvironment, signal) {
+        const { release, current } = await this.#acquireTaskProjectMaintenanceLocks(task, signal);
         try {
-            return await this.#prepareTaskWorkspaceLocked(current.id, true, environment, actor);
+            taskLocalActor(this.store, callerEnvironment, current.id);
+            if (current.executionGate.state !== "enabled") {
+                throw new Error(`Task execution is not enabled: ${current.id}.`);
+            }
+            if (!isDeepStrictEqual(current.activationRequest, task.activationRequest)) {
+                throw new Error(`Task activation request changed while waiting for Project maintenance: ${task.id}.`);
+            }
+            const provider = this.store.getTaskRoleSessionSet(current.id, LEADER_ROLE)?.providerBinding;
+            if (provider?.run != null
+                && ["submitting", "accepted", "delivery-unknown"].includes(provider.run.status)) {
+                throw new Error("Planning native input is unsettled; preserve activation intent and retry after its exact terminal.");
+            }
+            validateDraftTaskForActivation(this.store, current);
+            // Acquire before resource adoption: a timed-out/cancelled waiter must
+            // not leave an adopted environment to be repeated on the next attempt.
+            const adopted = await this.#adoptActivationEnvironment(current);
+            return adopted.workspaceFree
+                ? this.#activateWorkspaceFreeTask(current.id, adopted, actor)
+                : await this.#prepareTaskWorkspaceLocked(current.id, true, adopted, actor);
         }
         finally {
             release();
@@ -330,12 +365,19 @@ export class FileTaskWorkspacePreparer {
      * caller re-reads the Task and re-acquires the correct fence set. The
      * caller owns `release` and MUST call it on every exit path.
      */
-    #acquireTaskProjectMaintenanceLocks(task) {
+    async #acquireTaskProjectMaintenanceLocks(task, signal) {
         const projectIds = task.projectBindings.map(({ projectId }) => projectId);
+        const waitSignal = signal ?? this.maintenanceLockOptions.signal;
         const release = projectIds.length === 0
             ? () => { }
-            : acquireProjectMaintenanceLocks(this.home, projectIds);
+            : await acquireProjectMaintenanceLocks(this.home, projectIds, {
+                ...this.maintenanceLockOptions,
+                signal: waitSignal
+            });
         try {
+            if (waitSignal?.aborted) {
+                throw new ProjectMaintenanceLockCancelledError(projectIds[0] ?? task.id, waitSignal.reason);
+            }
             const current = requireTask(this.store, task.id);
             const currentIds = current.projectBindings.map(({ projectId }) => projectId).sort();
             const lockedIds = [...projectIds].sort();
@@ -358,13 +400,16 @@ export class FileTaskWorkspacePreparer {
      * catalog in that gap. The caller owns `release` and must call it on every
      * exit path.
      */
-    acquireTaskProjectMaintenanceLocks(taskId) {
-        return this.#acquireTaskProjectMaintenanceLocks(requireTask(this.store, taskId));
+    acquireTaskProjectMaintenanceLocks(taskId, signal) {
+        return this.#acquireTaskProjectMaintenanceLocks(requireTask(this.store, taskId), signal);
     }
     async #prepareTaskWorkspaceLocked(taskId, activate, 
     /** Environment and request identity the activation adopted, when one exists. */
     activationEnvironment = { workspaceFree: false }, actor = "user") {
         const task = requireTask(this.store, taskId);
+        if (task.executionGate.state !== "enabled") {
+            throw new Error(`Task execution is not enabled: ${task.id}.`);
+        }
         if (activate && task.status !== "draft") {
             throw new Error(`Only a Draft Task can atomically adopt a workspace: ${task.id}/${task.status}.`);
         }
@@ -910,15 +955,17 @@ export class FileTaskWorkspacePreparer {
         return projects;
     }
     async prepareWorkItemWorkspace(taskId, workItemId) {
-        const item = requireWorkItem(this.store, taskId, workItemId);
+        let item = requireWorkItem(this.store, taskId, workItemId);
         const task = requireTask(this.store, item.taskId);
         assertWorkItemWorkspaceEligible(this.store, task, item);
         // Hold the per-Project maintenance fence across the ensure-main-prepared
         // and the WorkItem worktree creation, so concurrent Project maintenance
         // cannot switch the Project catalog between the two. The under-lock Task
         // snapshot drives every Project read and Git effect below.
-        const { release, current: lockedTask } = this.#acquireTaskProjectMaintenanceLocks(task);
+        const { release, current: lockedTask } = await this.#acquireTaskProjectMaintenanceLocks(task);
         try {
+            item = requireWorkItem(this.store, taskId, workItemId);
+            assertWorkItemWorkspaceEligible(this.store, lockedTask, item);
             const lockedProjectIds = lockedTask.projectBindings.map(({ projectId }) => projectId);
             await this.#prepareTaskWorkspaceWithRetries(lockedTask.id, lockedProjectIds);
             // prepareTaskWorkspace may have just minted and persisted the workspace
@@ -1099,9 +1146,12 @@ export class FileTaskWorkspacePreparer {
         // already holds (one locked boundary across preparation and adoption);
         // otherwise the fence is acquired here.
         const { release, current: lockedTask } = heldFence === undefined
-            ? this.#acquireTaskProjectMaintenanceLocks(task)
+            ? await this.#acquireTaskProjectMaintenanceLocks(task)
             : { release: () => { }, current: heldFence.current };
         try {
+            if (lockedTask.status !== "active" || lockedTask.executionGate.state !== "enabled") {
+                throw new Error(`Task is not open for Execution Lane preparation: ${lockedTask.id}.`);
+            }
             const lineage = executionLaneLineage(this.store, lockedTask, executionGroupId, executionLaneId, hint);
             const item = lineage.purpose === "execution"
                 ? this.store.getWorkItem(taskId, lineage.workItemId)
@@ -1269,6 +1319,7 @@ export class FileTaskWorkspacePreparer {
             && owner.executionLaneId === executionLaneId));
         if (workspace === undefined)
             return "missing";
+        await this.#assertWorkspaceCleanup(workspace, "abandoned");
         const state = await this.#inspectEntries(task.id, this.#taskSegment(task), managedWorktreeName(workspace.owner), workspace.entries.filter(({ access }) => access === "write"));
         if (state === "dirty")
             return "dirty";
@@ -1404,8 +1455,11 @@ export class FileTaskWorkspacePreparer {
      * never used as a ChangeSet capture source. */
     async prepareReviewRoundWorkspace(taskId, reviewRoundId) {
         const taskSnapshot = requireTask(this.store, taskId);
-        const { release, current: task } = this.#acquireTaskProjectMaintenanceLocks(taskSnapshot);
+        const { release, current: task } = await this.#acquireTaskProjectMaintenanceLocks(taskSnapshot);
         try {
+            if (task.status !== "active" || task.executionGate.state !== "enabled") {
+                throw new Error(`Task is not open for ReviewRound preparation: ${task.id}.`);
+            }
             const taskSegment = this.#taskSegment(task);
             const round = this.store.getReviewRound(task.id, reviewRoundId);
             if (round === null)
@@ -1878,6 +1932,7 @@ export class FileTaskWorkspacePreparer {
         if (!isDeepStrictEqual(round.workspace, workspace)) {
             throw new Error(`ReviewRound workspace record diverged: ${round.id}.`);
         }
+        await this.#assertWorkspaceCleanup(workspace, "abandoned");
         assertWorkspaceSessionsRetirable(this.store, task.id, round.reviewerRoleName, this.now());
         for (const lane of round.executionGroup?.lanes ?? []) {
             assertWorkspaceSessionsRetirable(this.store, task.id, lane.roleName, this.now());
@@ -1945,6 +2000,7 @@ export class FileTaskWorkspacePreparer {
             throw new Error(`WorkItem has no managed isolated worktree workspace: ${item.id}.`);
         }
         assertWorkItemOwnsWorkspace(item, workspace);
+        await this.#assertWorkspaceCleanup(workspace, disposition);
         if (item.assignee !== undefined) {
             assertWorkspaceSessionsRetirable(this.store, task.id, item.assignee, this.now());
         }
@@ -1998,7 +2054,7 @@ export class FileTaskWorkspacePreparer {
         let found = false;
         for (const entry of workspace.entries.filter(({ access }) => access === "write")) {
             try {
-                if (!await this.git.isClean(entry.path))
+                if (!await this.git.inspectClean(entry.path))
                     return "dirty";
                 found = true;
             }
@@ -2010,7 +2066,7 @@ export class FileTaskWorkspacePreparer {
         }
         return found ? "clean" : "missing";
     }
-    async cleanupIntegrationWorkspace(taskId, integrationId) {
+    async cleanupIntegrationWorkspace(taskId, integrationId, options = {}) {
         const task = requireTask(this.store, taskId);
         const attempt = this.store.getIntegrationAttempt(task.id, integrationId);
         if (attempt === null) {
@@ -2023,6 +2079,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 +2103,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 ?? []) {
@@ -2069,7 +2130,7 @@ export class FileTaskWorkspacePreparer {
         }
         return this.#inspectEntries(task.id, this.#taskSegment(task), MAIN_WORKTREE, main.entries);
     }
-    async cleanupTaskForArchive(taskId) {
+    async cleanupTaskForArchive(taskId, disposition = "abandoned") {
         const task = requireTask(this.store, taskId);
         assertTaskArchiveState(task, task);
         const isolated = this.store.listManagedWorkspaces(task.id)
@@ -2084,6 +2145,7 @@ export class FileTaskWorkspacePreparer {
         }
         const main = this.store.getTaskWorkspace(task.id);
         if (main !== null) {
+            await this.#assertWorkspaceCleanup(main, disposition);
             assertTaskArchiveState(requireTask(this.store, task.id), task);
             if (await this.#inspectEntries(task.id, this.#taskSegment(task), MAIN_WORKTREE, main.entries) === "dirty") {
                 return {

package/dist/repository/workspaceCleanupInspection.js

@@ -0,0 +1,187 @@
+import { dirname, join, relative, isAbsolute } from "node:path";
+import { isDeepStrictEqual } from "node:util";
+import { managedWorkspaceKey, managedWorktreeName } from "../worktree/managedWorkspace.js";
+import { WorkItemChangeSetManager } from "../workspace/workItemChangeSetManager.js";
+import { cleanupCheckFromError } from "../workspace/cleanupInspection.js";
+import { projectTaskRemoteDeliveryFromStore } from "../commands/taskRemoteDeliveryCommand.js";
+import { taskWorkspaceRefSegment } from "./taskWorkspaceIdentity.js";
+import { integrationWorktreeIdentity, worktreeIdentity } from "./gitWorkspace.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 || ".";
+}

package/dist/runtime/agentError.js

@@ -21,7 +21,7 @@ export const AGENT_ERROR_CATEGORIES = Object.freeze([
 ]);
 export function standardAgentError(input) {
     const classification = input.classification ?? UNKNOWN_AGENT_ERROR_CLASSIFICATION;
-    const retryAfterMs = input.retryAfterMs;
+    const retryAfterMs = input.retryAfterMs ?? classification.retryAfterMs;
     if (retryAfterMs !== undefined
         && (!Number.isSafeInteger(retryAfterMs) || retryAfterMs < 0)) {
         throw new Error("Agent error retryAfterMs must be a non-negative safe integer.");
@@ -42,7 +42,8 @@ export function standardAgentError(input) {
         sessionDisposition: input.sessionDisposition
             ?? classification.sessionDisposition
             ?? "unknown",
-        ...(retryAfterMs === undefined ? {} : { retryAfterMs })
+        ...(retryAfterMs === undefined ? {} : { retryAfterMs }),
+        ...(classification.retryable === undefined ? {} : { retryable: classification.retryable })
     });
 }
 export const UNKNOWN_AGENT_ERROR_CLASSIFICATION = Object.freeze({
@@ -177,7 +178,8 @@ export function isStandardAgentError(value) {
         && ["accepted", "not-accepted", "unknown"].includes(error.inputDisposition ?? "")
         && ["recoverable", "unrecoverable", "unknown"].includes(error.sessionDisposition ?? "")
         && (error.retryAfterMs === undefined
-            || (Number.isSafeInteger(error.retryAfterMs) && error.retryAfterMs >= 0));
+            || (Number.isSafeInteger(error.retryAfterMs) && error.retryAfterMs >= 0))
+        && (error.retryable === undefined || typeof error.retryable === "boolean");
 }
 /**
  * Upper bound for one persisted raw payload. A Provider stack trace or a

package/dist/runtime/agentHost.js

@@ -18,6 +18,7 @@ import { persistRuntimeProcessExitObservation, replayRuntimeProcessExitOutbox }
 import { AGENT_HOST_CLIENT_EXIT_GRACE_MS, AGENT_HOST_CONTROL_TIMEOUT_MS, AGENT_HOST_READY_TIMEOUT_MS, ENDPOINT_DRAIN_TIMEOUT_MS, PROVIDER_ACCEPT_TIMEOUT_MS } from "./runtimeDeadlines.js";
 import { providerDeliveryFailure, providerDeliveryFailureFrom, redactAgentErrorText, serializeAgentErrorRaw } from "./agentError.js";
 import { runCodexInteractiveHost } from "./codexInteractiveHost.js";
+import { CodexPreSubmissionError } from "./codexAppServerRuntime.js";
 import { readAgentRunConfigurationObservation, unknownAgentRunConfiguration } from "./agentRunConfiguration.js";
 import { createSessionOwnerIdentity, readLinuxProcessIdentity } from "./sessionOwnerIdentity.js";
 import { yuiTmuxServerName, yuiTmuxSessionName } from "../tmux/tmuxManager.js";
@@ -767,13 +768,25 @@ export async function runAgentHost(input) {
             attemptId: request.run.attemptId,
             ...authorityFields()
         }));
-        const durableRun = hostRunControlParams(sessionPayload, session.nativeSessionId, request.authority, request.run.attemptId, request.runId);
+        const durableRun = { ...hostRunControlParams(sessionPayload, session.nativeSessionId, request.authority, request.run.attemptId, request.runId), boundedText: request.run.boundedText,
+            retrySupport: session.adapterId === "codex" ? "codex-failed-turn-v1" : "unsupported" };
+        let recoveryInput;
         // Registration precedes the Provider write, so its failure modes are not
         // the Provider's. A definite failure means the Provider never saw this
         // input and the occupancy must be released; anything unconfirmed leaves
         // durable state ambiguous and keeps it held.
         try {
-            await beginDurableProviderTurn(input.home, durableRun);
+            const admitted = await beginDurableProviderTurn(input.home, durableRun);
+            if (admitted !== null && typeof admitted === "object" && !Array.isArray(admitted)) {
+                const retry = admitted.retryInput;
+                if (retry !== null && typeof retry === "object" && !Array.isArray(retry)
+                    && typeof retry.text === "string")
+                    recoveryInput = {
+                        text: retry.text,
+                        ...(typeof retry.expectedFailedNativeTurnId === "string"
+                            ? { expectedFailedNativeTurnId: retry.expectedFailedNativeTurnId } : {})
+                    };
+            }
         }
         catch (error) {
             // Registration ends in one of three states and they are not
@@ -831,7 +844,11 @@ export async function runAgentHost(input) {
             // authority and Session identity before this native write.
             const receipt = endpointReceipt(await session.submit({
                 ...request.run,
-                boundedText: withSessionContextPointer(request.run.boundedText, activeRunPayload.environment),
+                boundedText: withSessionContextPointer(recoveryInput?.text ?? request.run.boundedText, activeRunPayload.environment),
+                ...(recoveryInput === undefined ? {} : { requireQuiescent: true }),
+                ...(recoveryInput?.expectedFailedNativeTurnId === undefined ? {} : {
+                    expectedFailedNativeTurnId: recoveryInput.expectedFailedNativeTurnId
+                }),
                 inputRef: request.runId ?? request.run.attemptId
             }), request.run.attemptId);
             transportAccepted = true;
@@ -1852,7 +1869,7 @@ function hostRunControlParams(payload, nativeSessionId, authority, attemptId, ru
 }
 async function beginDurableProviderTurn(home, durableRun) {
     try {
-        await callControllerIdempotently(home, "runtime.provider-turn-begin", durableRun);
+        return await callControllerIdempotently(home, "runtime.provider-turn-begin", durableRun);
     }
     catch (error) {
         if (error instanceof ControllerClientError && error.code === "SESSION_BUSY") {
@@ -1860,7 +1877,7 @@ async function beginDurableProviderTurn(home, durableRun) {
         }
         if (!(error instanceof ControllerAcknowledgementUnknownError))
             throw error;
-        await resolveProviderTurnSubmission(home, durableRun, new Error(`Provider Turn intent acknowledgement failed before Provider write: ${errorText(error)}`, { cause: error }));
+        await resolveProviderTurnSubmission(home, durableRun, new Error(`Provider Turn intent acknowledgement failed before Provider write: ${errorText(error)}`, { cause: error }), true);
         // The resolve is fenced on this exact attempt id, so its success proves
         // the registration did commit and is now settled with nothing written to
         // the Provider. That is a known outcome; reporting it as unknown would
@@ -1871,7 +1888,7 @@ async function beginDurableProviderTurn(home, durableRun) {
 }
 async function callControllerIdempotently(home, method, request) {
     try {
-        await callAgentController(home, method, request);
+        return await callAgentController(home, method, request);
     }
     catch (error) {
         if (!(error instanceof ControllerClientError)
@@ -1882,7 +1899,7 @@ async function callControllerIdempotently(home, method, request) {
         // These methods carry exact attempt, launch, and authority fences. A
         // bounded replay confirms a commit whose acknowledgement may have been lost.
         try {
-            await callAgentController(home, method, request);
+            return await callAgentController(home, method, request);
         }
         catch (replayError) {
             if (firstCallMayHaveApplied || controllerCallMayHaveApplied(replayError)) {
@@ -1903,7 +1920,7 @@ class ControllerAcknowledgementUnknownError extends Error {
 class ProviderTurnRegistrationSettledError extends Error {
     name = "ProviderTurnRegistrationSettledError";
 }
-async function resolveProviderTurnSubmission(home, durableRun, error) {
+async function resolveProviderTurnSubmission(home, durableRun, error, noProviderWrite = false) {
     const attemptId = durableRun.attemptId;
     if (typeof attemptId !== "string") {
         throw new Error("Provider Turn resolution has no attempt id.");
@@ -1915,6 +1932,7 @@ async function resolveProviderTurnSubmission(home, durableRun, error) {
             : error instanceof ProviderTurnBusyError ? "deferred" : "rejected",
         reason: errorText(error),
         raw: serializeAgentErrorRaw(error),
+        ...(noProviderWrite || error instanceof CodexPreSubmissionError ? { providerWrite: "not-issued" } : {}),
         observedAt: new Date().toISOString()
     };
     try {
@@ -1935,8 +1953,7 @@ async function resolveProviderTurnSubmission(home, durableRun, error) {
  */
 async function callAgentController(home, method, params) {
     try {
-        await callController(home, method, params);
-        return;
+        return await callController(home, method, params);
     }
     catch (error) {
         if (!isControllerUnavailable(error) || !isForeignHandoverLockHeld(home)) {
@@ -1948,7 +1965,7 @@ async function callAgentController(home, method, params) {
         await delay(50);
     // The pinned Host can rediscover a replacement, but must never start a
     // Controller using its own old implementation or open the Home's database.
-    await callController(home, method, params);
+    return await callController(home, method, params);
 }
 function isControllerUnavailable(error) {
     return error instanceof ControllerClientError