@zq-silk/yui 2.2.0 → 2.3.0

package/README.md

@@ -162,8 +162,10 @@ The task list remains at the left, task details occupy the primary reading area,
 and recorded Task messages live in a secondary discussion pane. You can resize,
 swap or hide that pane; on narrow screens it opens over the detail. Native Sessions
 remain separate from recorded Task messages.
-The detail prioritizes user input, native Session activity, Task progress and key
-conclusions; fixed file results and delivery evidence open on demand. See
+The detail has four tabs: Overview (user input, progress and key Decisions),
+Delivery (WorkItems, Reviews, Integration and remote delivery, read on demand),
+Runtime (Roles, native Session activity, open execution and usage) and Records
+(a timeline of Decisions, milestones, executions and questions). See
 [attention and progress](docs/observability/README.md#web-attention-and-progress).
 See [Web permissions](docs/architecture/capabilities-and-resources.md#cli-and-web)
 and [input timing](docs/managed-turn-and-session-runtime.md#input-timing-queue-steer-and-interrupt).

package/dist/cli/commandCatalog.js

@@ -422,9 +422,14 @@ const taskChildren = [
         usage: "yui task archive-preflight <id> (--integrated|--abandon) [--force] [--json]",
         options: ["--integrated", "--abandon", "--force", "--json"]
     },
+    {
+        name: "archive-cleanup", discovery: { surface: "public", audiences: ["public", "operator", "leader"] },
+        summary: "Retry one foreground exact-owner cleanup for an archived Task; retain unsafe resources and all history.",
+        usage: "yui task archive-cleanup <id>"
+    },
     {
         name: "archive", discovery: { surface: "public", audiences: ["public", "operator", "leader"], optionAudiences: { "--force": ["public", "operator"] } },
-        summary: "Archive a terminal Task; explicit --force commits despite delivery/cleanup warnings, retaining unsafe resources.",
+        summary: "Archive settled, delivered, stopped work, then attempt exact-owner cleanup. Retained physical resources do not require --force; force separately bypasses business admission.",
         usage: "yui task archive <id> (--integrated|--abandon) [--force] [--source-message <id> --purpose <verbatim-authorization> --request-id <id>]",
         options: ["--integrated", "--abandon", "--force", "--source-message", "--purpose", "--request-id"]
     },
@@ -992,7 +997,7 @@ const taskChildren = [
             },
             { name: "list", discovery: { surface: "managed", audiences: ["operator", "leader"] }, summary: "List Integration Attempts.", usage: "yui task integration list <task>" },
             { name: "show", discovery: { surface: "managed", audiences: ["operator", "leader"] }, summary: "Show one Integration Attempt.", usage: "yui task integration show <task>/<integration>" },
-            { name: "cleanup", discovery: { surface: "managed", audiences: ["operator", "leader"] }, summary: "Remove a terminal Integration worktree and branch.", usage: "yui task integration cleanup <task>/<integration>" }
+            { name: "cleanup", discovery: { surface: "managed", audiences: ["operator", "leader"] }, summary: "Release clean terminal Integration resources; preserve attempt history, check logs and dirty diagnostics.", usage: "yui task integration cleanup <task>/<integration>" }
         ]
     },
     {
@@ -1579,7 +1584,7 @@ export const ROOT_COMMAND = buildNode({
             name: "task", discovery: { surface: "public", audiences: ["public", "operator"] },
             summary: "Manage Tasks, WorkItems, AgentRuns, and integration.",
             sections: [
-                { id: "lifecycle", title: "Lifecycle", entries: ["create", "project", "base", "update", "activate", "activation", "execution", "complete", "cancel", "reopen", "retire", "list", "show", "context", "next-action", "remote-delivery", "archive-preflight", "archive", "replace", "reconcile", "upstream", "artifact"] },
+                { id: "lifecycle", title: "Lifecycle", entries: ["create", "project", "base", "update", "activate", "activation", "execution", "complete", "cancel", "reopen", "retire", "list", "show", "context", "next-action", "remote-delivery", "archive-preflight", "archive", "archive-cleanup", "replace", "reconcile", "upstream", "artifact"] },
                 { id: "collaboration", title: "Collaboration", entries: ["message", "input", "grant", "workflow", "publication", "work", "run", "review", "integration", "role", "overlap", "change-set"] },
                 { id: "knowledge", title: "Task Knowledge", entries: ["brief", "decision", "milestone", "event", "continuation", "wake"] }
             ],

package/dist/cli/interactionPolicy.js

@@ -236,6 +236,10 @@ export const INTERACTION_POLICIES = Object.freeze([
         ...taskTarget("archive-preflight"),
         trailingOptions: { "--integrated": "flag", "--abandon": "flag", "--force": "flag", "--json": "flag" }
     },
+    {
+        ...taskTarget("archive-cleanup", 2, ["archived"]),
+        confirmation: { action: "Clean archived Task resources", targetArgumentIndex: 2 }
+    },
     {
         ...taskTarget("archive", 2, ["completed", "cancelled"]),
         trailingOptions: { "--integrated": "flag", "--abandon": "flag", "--force": "flag" },

package/dist/commands/taskCommands.js

@@ -55,7 +55,7 @@ import { queueLeaderWakeup } from "../scheduler/wakeupQueue.js";
 import { planningRuntimeCwd } from "../storage/homeLayout.js";
 import { StorageConflictError } from "../storage/taskStore.js";
 import { archiveDeliveryWarnings, archiveRetainedResources, renderArchiveDiagnostics, taskArchiveDiagnostics } from "../task/archiveDiagnostics.js";
-import { archiveSettlementChecks } from "../task/archivePreflight.js";
+import { archiveExecutionChecks, archiveSettlementChecks } from "../task/archivePreflight.js";
 import { projectCompletionReadiness } from "../task/completionReadiness.js";
 import { assertDraftTaskExecutionFree, validateDraftWorkItemEdit } from "../task/draftPlan.js";
 import { assertTaskRemoteDeliveryProof, projectTaskRemoteDeliveryFromStore } from "../task/remoteDeliveryService.js";
@@ -1300,12 +1300,9 @@ function archiveTaskCommand(args, store, options) {
                 ? assertTaskRemoteDeliveryProof(tx, task, options.archiveRemoteDeliveryProof)
                 : undefined;
         if (!request.force) {
-            const checks = archiveSettlementChecks(tx, task);
+            const checks = [...archiveSettlementChecks(tx, task), ...archiveExecutionChecks(tx, task.id, options.yuiHome)];
             if (checks.length > 0)
                 throw new CleanupInspectionError(checks);
-            if (task.cwd !== undefined || tx.listManagedWorkspaces(task.id).length > 0) {
-                throw usageError(`Task ${task.id} still has managed worktrees; clean them before archiving.`);
-            }
             const activeRole = tx.listRoles(task.id)
                 .find((role) => tx.getActiveRun(task.id, role.name) !== null);
             if (activeRole !== undefined) {
@@ -1322,7 +1319,7 @@ function archiveTaskCommand(args, store, options) {
                     + "stop that Session before archiving.");
             }
         }
-        const retainedResources = request.force ? archiveRetainedResources(tx, task) : [];
+        const retainedResources = archiveRetainedResources(tx, task);
         const warnings = request.force && remoteDelivery !== undefined ? archiveDeliveryWarnings(remoteDelivery) : [];
         const archived = { ...archiveTask(task, now, { by: actor }), executionGate: { state: "stopped" } };
         tx.saveTask(archived);
@@ -1351,8 +1348,9 @@ function archiveTaskCommand(args, store, options) {
                 authorizationSource: JSON.stringify(options.archiveLeaderAdmission.source)
             }),
             workspaceDisposition: request.disposition,
+            cleanup: "pending",
             ...(request.force ? {
-                force: "true", cleanup: "pending",
+                force: "true",
                 warnings: JSON.stringify(warnings),
                 retainedResources: JSON.stringify(retainedResources)
             } : {}),

package/dist/commands/taskIntegrationCommands.js

@@ -49,19 +49,8 @@ async function cleanupIntegration(args, store, home, environment) {
         && integration.status !== "failed") {
         throw usageError(`Integration is not terminal: ${integration.id}/${integration.status}.`);
     }
-    // rr4/finding-5: An Integration Attempt with an active DurableJob cannot be
-    // cleaned up — the runner may still be using its worktree. Block on queued,
-    // running, and unacknowledged unknown-needs-attention jobs owned by it.
-    const activeIntegrationJob = store.listDurableJobs(integration.taskId).find((job) => (job.owner.kind === "integration-attempt"
-        && job.owner.integrationAttemptId === integration.id
-        && (job.status === "queued"
-            || job.status === "running"
-            || (job.status === "unknown-needs-attention" && job.acknowledgedAt === undefined))));
-    if (activeIntegrationJob !== undefined) {
-        throw usageError(`Integration ${integration.id} has an active DurableJob: `
-            + `${activeIntegrationJob.id}/${activeIntegrationJob.status}. `
-            + "Cancel or acknowledge it before cleanup.");
-    }
+    // The service's shared owner inspection checks both Job settlement and
+    // current physical occupancy before any runtime or worktree is released.
     const result = await new GitIntegrationService(home, store).cleanup(integration, {
         authorize: () => taskLocalActor(store, environment, integration.taskId)
     });
@@ -70,9 +59,9 @@ async function cleanupIntegration(args, store, home, environment) {
     }
     return {
         output: result === "removed"
-            ? `Cleaned Integration worktree and check logs ${integration.id}\n`
-            : `Integration worktree and check logs already clean: ${integration.id}\n`,
-        data: { integrationId: integration.id, cleanup: result }
+            ? `Cleaned Integration worktree ${integration.id}; history and check logs retained\n`
+            : `Integration worktree already clean: ${integration.id}; history and check logs retained\n`,
+        data: { integrationId: integration.id, cleanup: result, historyRetained: true }
     };
 }
 async function start(args, store, home, now, options) {

package/dist/controlPlaneCli.js

@@ -1012,6 +1012,24 @@ export async function main() {
                 emit(renderTaskArchivePreflight(data), false, data);
                 return;
             }
+            if (resolved[1] === "archive-cleanup") {
+                const taskId = resolved[2];
+                if (resolved.length !== 3 || taskId === undefined) {
+                    throw usageError("Usage: yui task archive-cleanup <task>.");
+                }
+                taskLocalActor(store, process.env, taskId);
+                const task = store.getTask(taskId);
+                if (task?.status !== "archived")
+                    throw usageError("Archive cleanup requires an archived Task.");
+                const archive = taskArchiveDiagnostics(store, task);
+                if (archive.disposition !== "integrated" && archive.disposition !== "abandoned") {
+                    throw usageError("Archive has no recorded cleanup disposition; inspect its original event.");
+                }
+                await workspaceCoordinator.cleanupArchivedTask(taskId, archive.disposition);
+                const result = taskArchiveDiagnostics(store, store.getTask(taskId));
+                emit(renderArchiveDiagnostics(result), false, { taskId, ...result });
+                return;
+            }
             if (resolved[1] === "artifact") {
                 // File/directory artifacts live in the Task's local Git repository, so
                 // their save/read/list are asynchronous and handled here rather than in
@@ -1343,30 +1361,19 @@ export async function main() {
                 }
                 {
                     if (disposition === "integrated") {
-                        archiveTaskReviewCandidate = await actualTaskReviewCandidateForTaskCommand(resolved, store, workspacePreparer, process.env);
+                        archiveTaskReviewCandidate = task.status === "cancelled" ? await actualTaskReviewCandidateForTaskCommand(resolved, store, workspacePreparer, process.env) : undefined;
                         archiveRemoteDeliveryProof = createTaskRemoteDeliveryProof(store, task, archiveTaskReviewCandidate ?? null);
                         assertTaskRemoteDeliveryIntegrated(archiveRemoteDeliveryProof.delivery);
                     }
-                    const workItemIds = store.listManagedWorkspaces(task.id)
-                        .flatMap(({ owner }) => owner.type === "work-item" ? [owner.workItemId] : []);
-                    for (const workItemId of workItemIds) {
-                        const item = store.getWorkItem(task.id, workItemId);
-                        if (item?.status !== "accepted" || disposition !== "integrated")
-                            continue;
-                        try {
-                            await new WorkItemChangeSetManager(store).assertIntegrated(task.id, item.id);
-                        }
-                        catch (error) {
-                            throw cleanupCliError(error, `work-item:${task.id}/${item.id}`);
-                        }
-                    }
-                    const cleanup = await workspaceCoordinator.cleanupTaskForArchive(task.id, disposition);
-                    if (cleanup.status === "retained-dirty") {
-                        throw usageError(cleanup.error ?? `Task ${task.id} has dirty managed worktrees and remains terminal.`, undefined, cleanupBlockedDetails(cleanup.reason ?? "dirty-worktree", cleanup.resource ?? `task:${task.id}`, cleanup.retryable ?? true, cleanup.checks));
-                    }
-                    if (cleanup.status === "failed") {
-                        throw usageError(`Task ${task.id} worktree cleanup failed: ${cleanup.error ?? "unknown error"}.`, undefined, cleanupBlockedDetails(cleanup.reason ?? "cleanup-failed", cleanup.resource ?? `task:${task.id}`, cleanup.retryable ?? true, cleanup.checks));
-                    }
+                    await workspaceCoordinator.prepareTaskForArchive(task.id);
+                    runTaskCommand(resolved.slice(1), store, {
+                        runtime, environment: process.env, yuiHome: home, archiveRemoteDeliveryProof
+                    });
+                    await workspaceCoordinator.cleanupArchivedTask(task.id, disposition);
+                    const current = store.getTask(task.id);
+                    const archive = taskArchiveDiagnostics(store, current);
+                    emit(`Archived task ${task.id}\n${renderArchiveDiagnostics(archive)}`, false, { task: current, ...archive });
+                    return;
                 }
             }
             let taskRetirementProof;

package/dist/controller/clientRuntime.js

@@ -1,4 +1,5 @@
 import { spawn } from "node:child_process";
+import { jobCleanupBlocker } from "../job/jobCleanupInspection.js";
 import { describeCliFailure } from "../errors/cliFailure.js";
 import { fileURLToPath } from "node:url";
 import { findLiveControllerProcessForHome, inspectLiveControllerProcess } from "../core/controllerProcessIdentity.js";
@@ -525,8 +526,8 @@ export class FileTaskWorkflowRuntime {
      * live, preserving the owner records for Operator recovery.
      */
     async assertTaskPhysicalResourcesReleased(taskId) {
-        const activeJobs = this.store.listActiveDurableJobs()
-            .filter((job) => job.taskId === taskId);
+        const activeJobs = this.store.listDurableJobs(taskId)
+            .filter((job) => jobCleanupBlocker(job, this.home) !== undefined);
         if (activeJobs.length > 0) {
             throw new WorkspaceCleanupBlockedError("physical-resource-live", `task:${taskId}`, true, `Task physical resources are not released: ${activeJobs.length} DurableJob(s) are still active: `
                 + activeJobs.map(({ id }) => id).join(", "));

package/dist/integration/gitIntegrationService.js

@@ -3,19 +3,17 @@ import { lstat, mkdir, open, realpath, rm, stat } from "node:fs/promises";
 import { dirname, join, relative, resolve, sep } from "node:path";
 import { promisify } from "node:util";
 import { selectEnvironment } from "../agent/launchEnvironment.js";
-import { controllerSocketPath } from "../core/controllerEndpoint.js";
 import { durableJobIdempotencyKey } from "../job/durableJob.js";
 import { readRuntimeIdentity } from "../release/runtimeRelease.js";
 import { NodeGitWorkspace } from "../repository/gitWorkspace.js";
 import { acquireProjectMaintenanceLocks } from "../repository/projectMaintenanceLock.js";
 import { taskWorkspaceRefSegment } from "../repository/taskWorkspaceIdentity.js";
-import { integrationWorkspaceRoot } from "../repository/taskWorkspacePreparer.js";
+import { FileTaskWorkspacePreparer, integrationWorkspaceRoot } from "../repository/taskWorkspacePreparer.js";
 import { ResourceRegistrar } from "../resources/resourceRegistrar.js";
-import { FileTaskRuntimeIsolation } from "../runtime/taskRuntimeIsolation.js";
-import { integrationTmuxSocketRoot, managedIntegrationRuntimeRoot } from "../storage/homeLayout.js";
+import { integrationTmuxSocketRoot } from "../storage/homeLayout.js";
+import { defaultIntegrationRuntimeIsolation } from "../runtime/integrationRuntimeIsolation.js";
 import { advanceTaskProjectCommit } from "../task/task.js";
 import { taskIntegrationSettlementCheckout, taskIntegrationTargetCheckout } from "../task/taskAuthority.js";
-import { yuiTmuxServerName } from "../tmux/tmuxManager.js";
 import { recordGateArtifactReuse } from "../verification/gateArtifact.js";
 import { touchGateArtifact } from "../verification/gateArtifactStore.js";
 import { beginGateVerification, checkResultsFromGateArtifact, checkResultsFromGateJob, gateIdentityForCandidate, lookupReusableGateArtifact, recordGateArtifactFromJob, recordGateArtifactFromStepOutcomes, resolveVerificationGate, runGateStepsInProcess } from "../verification/verificationGateService.js";
@@ -370,12 +368,9 @@ export class GitIntegrationService {
                 throw new Error("Integration changed before cleanup; read its current record.");
             }
             integration = current;
-            const activeJob = this.store.listDurableJobs(integration.taskId).find(job => job.owner.kind === "integration-attempt" && job.owner.integrationAttemptId === integration.id
-                && (job.status === "queued" || job.status === "running"
-                    || (job.status === "unknown-needs-attention" && job.acknowledgedAt === undefined)));
-            if (activeJob !== undefined) {
-                throw new Error(`Integration ${integration.id} has an active DurableJob: ${activeJob.id}/${activeJob.status}.`);
-            }
+            const managedWorkspace = this.store.getIntegrationWorkspace(integration.taskId, integration.id);
+            if (managedWorkspace === null)
+                return "missing";
             const task = this.store.getTask(integration.taskId);
             if (task === null || !task.projectBindings.some(({ projectId }) => projectId === integration.projectId)) {
                 throw new Error(`Integration Task Project is unavailable: ${integration.id}.`);
@@ -387,42 +382,8 @@ export class GitIntegrationService {
             if (taskRepository === undefined) {
                 throw new Error(`Integration Task clone is unavailable: ${task.id}/${project.id}.`);
             }
-            const managedWorkspace = this.store.getIntegrationWorkspace(integration.taskId, integration.id);
-            if (managedWorkspace !== null) {
-                const runtime = this.#runtimePreparation(integration, managedWorkspace);
-                this.runtimeIsolation.cleanup(runtime, integration.status === "committed" ? "completion" : "failure");
-            }
-            const recorded = managedWorkspace?.entries[0];
-            const directory = recorded?.directory
-                ?? task.projectBindings.find(({ projectId }) => projectId === integration.projectId)?.directory;
-            if (directory === undefined) {
-                throw new Error(`Integration Project binding is unavailable: ${task.id}/${project.id}.`);
-            }
-            const result = await this.git.removeIntegrationWorktree({
-                repositoryPath: taskRepository,
-                container: recorded !== undefined
-                    ? dirname(recorded.path)
-                    : integrationWorkspaceRoot(this.home, task.id, integration.id),
-                directory,
-                taskSegment: taskWorkspaceRefSegment(task),
-                integrationId: integration.id,
-                discardChanges: integration.status === "failed"
-            });
-            if (result !== "dirty") {
-                if (managedWorkspace !== null) {
-                    this.#resourceRegistrar().markWorkspaceDeleted(managedWorkspace);
-                }
-                await rm(integrationCheckDirectory(this.home, task.id, integration.id), {
-                    recursive: true,
-                    force: true
-                });
-                this.store.removeManagedWorkspace({
-                    type: "integration-attempt",
-                    taskId: integration.taskId,
-                    integrationAttemptId: integration.id
-                });
-            }
-            return result;
+            return await new FileTaskWorkspacePreparer(this.home, this.store, this.git, this.now)
+                .cleanupIntegrationWorkspace(task.id, integration.id, { runtimeIsolation: this.runtimeIsolation });
         }
         finally {
             release();
@@ -1024,26 +985,6 @@ function isNodeCode(error, code) {
         && "code" in error
         && error.code === code;
 }
-function defaultIntegrationRuntimeIsolation(home, homeId) {
-    const controlHome = resolve(home);
-    const runtimeRoot = managedIntegrationRuntimeRoot(controlHome);
-    return new FileTaskRuntimeIsolation({
-        // The integration check's provider data/cache/tmp live in a dedicated Home
-        // partition — the same isolation contract every Task runtime obeys — not in
-        // a system-wide `/tmp` root. Only the tmux socket ENDPOINT stays a short
-        // `/tmp` path (see `integrationCheckEnvironment`) for the `sockaddr_un`
-        // budget; ordinary runtime state is now Yui-managed under Home.
-        runtimeRoot,
-        pathLayout: "compact",
-        controlPlane: {
-            yuiHome: controlHome,
-            managedRuntimeRoot: runtimeRoot,
-            controllerSocketPath: controllerSocketPath(homeId),
-            tmuxNamespace: yuiTmuxServerName(controlHome),
-            globalInstallPaths: [process.execPath]
-        }
-    });
-}
 /**
  * Reuse is enabled only for an immutable installed release. Development
  * checkouts have no content-addressed release identity, so they return.

package/dist/job/jobCleanupInspection.js

@@ -0,0 +1,67 @@
+import { isAbsolute, join, resolve } from "node:path";
+import { processGenerationIsLive } from "../core/fileLockOwner.js";
+import { scanProcessPathRefs } from "../resources/liveReferences.js";
+import { inspectTaskRuntimeCleanupClaims, parseTaskRuntimeIsolationDescriptor, YUI_TASK_RUNTIME_ISOLATION_DESCRIPTOR } from "../runtime/taskRuntimeIsolation.js";
+/** Result uncertainty and physical occupancy are different facts. Reuse the
+ * recorded process generation and resource scanner, without rewriting the Job
+ * or treating acknowledgement as stop evidence. Every cleanup reads this anew.
+ */
+export function jobCleanupBlocker(job, home, phase = "before-removal") {
+    if (job.status === "queued" || job.status === "running")
+        return `DurableJob is ${job.status}.`;
+    if (job.status === "unknown-needs-attention" && job.acknowledgedAt === undefined) {
+        return "Unknown Job result requires explicit acknowledgement.";
+    }
+    if (job.status !== "unknown-needs-attention" && job.startedAt === undefined
+        && job.process === undefined && job.operation.effect === "none")
+        return undefined;
+    if (job.process === undefined || home === undefined) {
+        return "Job has no exact process/Home evidence for physical inspection.";
+    }
+    try {
+        if (processGenerationIsLive(job.process.pid, job.process.startIdentity)) {
+            return "The exact Job runner process is still live.";
+        }
+        // A reusable idle Role can share this workspace. Its exact-owner stop is
+        // allowed only after result/runner checks; path references must then be
+        // rechecked before any child deletion or ordinary archive commit.
+        if (phase === "before-role-stop")
+            return undefined;
+        // Steps may outlive a killed runner. Their cwd, logs and isolated runtime
+        // paths remain protective references; no process is signalled here.
+        const paths = [job.workspace, join(resolve(home), "artifacts", "jobs", job.taskId, job.id),
+            ...["TMPDIR", "XDG_DATA_HOME", "XDG_CACHE_HOME"].flatMap(key => {
+                const path = job.env[key];
+                return path !== undefined && isAbsolute(path) ? [path] : [];
+            })];
+        const serialized = job.env[YUI_TASK_RUNTIME_ISOLATION_DESCRIPTOR];
+        if (serialized !== undefined) {
+            const descriptor = parseTaskRuntimeIsolationDescriptor(serialized);
+            const owner = descriptor.workspace.owner;
+            if (descriptor.taskId !== job.taskId || descriptor.workspace.root !== job.workspace
+                || owner.type !== job.owner.kind
+                || (owner.type === "integration-attempt" && job.owner.kind === "integration-attempt"
+                    && owner.integrationAttemptId !== job.owner.integrationAttemptId)
+                || (owner.type === "work-item" && job.owner.kind === "work-item"
+                    && owner.workItemId !== job.owner.workItemId)) {
+                return "Job runtime descriptor does not match its exact owner/workspace.";
+            }
+            const claims = inspectTaskRuntimeCleanupClaims(descriptor);
+            const uncertain = claims.find(claim => claim.ownership !== "owned" || claim.state !== "inactive");
+            if (uncertain !== undefined)
+                return `Job runtime cleanup claim is unverified: ${uncertain.id}.`;
+            // cwd/fd references follow rename, unlike the recorded environment.
+            // Use the same exact claim inventory as deletion, before archive commits.
+            paths.push(descriptor.roots.runtime, ...claims.map(claim => claim.id));
+        }
+        const scan = scanProcessPathRefs(paths);
+        if (scan.diagnostics.some(diagnostic => diagnostic.severity === "error")
+            || [...scan.refs.values()].some(refs => refs.length > 0)) {
+            return "Job workspace/log/runtime references are still live or unverified.";
+        }
+    }
+    catch (error) {
+        return `Job physical inspection is unavailable: ${error instanceof Error ? error.message : String(error)}`;
+    }
+    return undefined;
+}

package/dist/repository/gitWorkspace.js

@@ -821,7 +821,7 @@ export class NodeGitWorkspace {
         const state = await this.inspectWorktree(input);
         if (state === "dirty")
             return state;
-        const container = await canonicalContainer(input.container, false);
+        const container = await cleanupContainer(input.container);
         const branch = worktreeIdentity(input.taskSegment, input.roleName).branch;
         const path = managedPath(container, input.directory);
         const project = await this.inspect(input.repositoryPath);
@@ -970,13 +970,13 @@ export class NodeGitWorkspace {
         return "removed";
     }
     async inspectWorktree(input) {
-        const container = await canonicalContainer(input.container, false);
+        const container = await cleanupContainer(input.container);
         const path = managedPath(container, input.directory);
         const kind = await pathKind(path);
         const branch = input.expectedBranch ?? worktreeIdentity(input.taskSegment, input.roleName).branch;
         if (kind === undefined) {
             const project = await this.inspect(input.repositoryPath);
-            await inspectMissingWorktreeRegistration(project.root, path, branch);
+            await inspectMissingWorktreeRegistration(project.root, path, branch, input.expectedBranch !== undefined);
             return "missing";
         }
         if (kind === "symlink")
@@ -984,7 +984,7 @@ export class NodeGitWorkspace {
         const canonicalContainerPath = await canonicalContainer(container, false);
         const project = await this.inspect(input.repositoryPath);
         await assertOwnedWorktree(project, canonicalContainerPath, path);
-        await assertExpectedBranch(path, branch);
+        await assertExpectedBranch(path, branch, input.expectedBranch !== undefined);
         const porcelain = await readWorktreeStatus(path);
         return porcelain.length > 0 ? "dirty" : "clean";
     }
@@ -1000,19 +1000,19 @@ export class NodeGitWorkspace {
         });
     }
     async #removeManagedWorktree(input) {
-        const container = await canonicalContainer(input.container, false);
+        const container = await cleanupContainer(input.container);
         const path = managedPath(container, input.identity.directory);
         const kind = await pathKind(path);
         if (kind === "symlink")
             throw new Error("Managed worktree path must not be a symbolic link.");
         const repository = await this.inspect(input.repositoryPath);
         if (kind === undefined) {
-            await removeMissingWorktreeRegistration(repository.root, path, input.identity.branch);
+            await removeMissingWorktreeRegistration(repository.root, path, input.identity.branch, true);
         }
         if (kind === "directory") {
             const canonicalContainerPath = await canonicalContainer(container, false);
             await assertOwnedWorktree(repository, canonicalContainerPath, path);
-            await assertExpectedBranch(path, input.identity.branch);
+            await assertExpectedBranch(path, input.identity.branch, true);
             if (input.discardChanges === true) {
                 await git(["-C", repository.root, "worktree", "remove", "--force", "--", path]);
             }
@@ -1043,19 +1043,22 @@ export class NodeGitWorkspace {
 /** Missing paths do not imply missing Git metadata. Never prune another
  * workspace's registration as a side effect of cleaning this exact owner.
  */
-async function removeMissingWorktreeRegistration(repositoryRoot, path, branch) {
-    if (!await inspectMissingWorktreeRegistration(repositoryRoot, path, branch))
+async function removeMissingWorktreeRegistration(repositoryRoot, path, branch, allowDetached = false) {
+    if (!await inspectMissingWorktreeRegistration(repositoryRoot, path, branch, allowDetached))
         return;
     if (await pathKind(path) !== undefined)
         throw new Error(`Worktree reappeared before metadata cleanup: ${path}.`);
     await git(["-C", repositoryRoot, "worktree", "remove", "--force", "--", path]);
 }
-async function inspectMissingWorktreeRegistration(repositoryRoot, path, branch) {
+async function inspectMissingWorktreeRegistration(repositoryRoot, path, branch, allowDetached = false) {
     const records = (await git(["-C", repositoryRoot, "worktree", "list", "--porcelain", "-z"])).split("\0\0");
     const fields = records.map(record => record.split("\0")).find(record => record.includes(`worktree ${path}`));
     if (fields === undefined)
         return false;
-    if (!fields.includes(`branch refs/heads/${branch}`) || fields.some(field => field.startsWith("locked"))) {
+    const pinnedDetached = allowDetached && fields.includes("detached")
+        && await gitSucceeds(["-C", repositoryRoot, "show-ref", "--verify", "--quiet", `refs/heads/${branch}`])
+        && fields.includes(`HEAD ${await resolveRefCommit(repositoryRoot, `refs/heads/${branch}`)}`);
+    if ((!fields.includes(`branch refs/heads/${branch}`) && !pinnedDetached) || fields.some(field => field.startsWith("locked"))) {
         cleanupFailure("git-registration-mismatch", "Missing worktree has uncertain or locked Git ownership; metadata retained.", { branch, locked: false }, { branch: fields.find(field => field.startsWith("branch "))?.slice(7) ?? null,
             locked: fields.some(field => field.startsWith("locked")) });
     }
@@ -1115,7 +1118,12 @@ async function assertExpectedBranch(path, expected, allowRebase = false) {
                 return;
             throw new Error(`Managed worktree is rebasing an unexpected branch: ${headName}.`);
         }
-        throw new Error("Managed worktree has detached HEAD without its expected rebase.");
+        // A terminal Integration can legitimately retain a detached checkout.
+        // Its exact owned path/common-dir were checked by the caller; require its
+        // retained branch to pin the same commit before allowing clean removal.
+        if (await resolveRefCommit(path, "HEAD") === await resolveRefCommit(path, `refs/heads/${expected}`))
+            return;
+        cleanupFailure("workspace-identity-mismatch", "Detached worktree is not pinned by its owned branch or rebase.", expected, "unproven detached HEAD");
     }
     const branch = await gitLine(["-C", path, "symbolic-ref", "--short", "HEAD"]);
     if (branch !== expected) {
@@ -1237,6 +1245,27 @@ async function canonicalContainer(path, create) {
     // stay rejected by the managed-path lstat checks.
     return canonicalDirectory(lexical, "Worktree container");
 }
+/** A previous removal may have deleted the whole owner container before its
+ * receipt committed. Resolve only surviving ancestors, without creating it.
+ * Git registration inspection remains mandatory even when this path is absent.
+ */
+async function cleanupContainer(path) {
+    const lexical = resolve(path);
+    if (await pathKind(lexical) === "symlink") {
+        cleanupFailure("workspace-identity-mismatch", "Cleanup container must not be a symbolic link.", "owned directory or missing path", "symbolic link");
+    }
+    try {
+        return await canonicalContainer(lexical, false);
+    }
+    catch (error) {
+        if (!isErrno(error, "ENOENT"))
+            throw error;
+        const parent = dirname(lexical);
+        if (parent === lexical)
+            throw error;
+        return join(await cleanupContainer(parent), relative(parent, lexical));
+    }
+}
 async function canonicalDirectory(path, label) {
     const value = requireText(path, label);
     const canonical = await realpath(isAbsolute(value) ? value : resolve(value));