@zq-silk/yui 0.15.9 → 0.15.11

package/dist/repository/taskWorkspacePreparer.js

@@ -1,6 +1,7 @@
 import { lstat, mkdir, readlink, readdir, rm, rmdir, symlink, unlink } from "node:fs/promises";
-import { isAbsolute, join, relative, resolve } from "node:path";
+import { dirname, isAbsolute, join, relative, resolve } from "node:path";
 import { isDeepStrictEqual } from "node:util";
+import { recordArchiveCleanup } from "../task/archiveDiagnostics.js";
 import { retireTaskRoleSessionsForWorkspace, updateRoleAgentSessionStatus } from "../executor/agentExecutor.js";
 import { formatWorkspacePreflightError } from "../executor/workspacePreflightClassification.js";
 import { updateRole } from "../role/role.js";
@@ -22,6 +23,7 @@ import { acquireProjectMaintenanceLocks } 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";
 const MAIN_WORKTREE = "main";
 const LEADER_ROLE = "leader";
 /**
@@ -537,7 +539,7 @@ export class FileTaskWorkspacePreparer {
                     throw new Error(`Task Project baseline was not resolved: ${project.id}.`);
                 }
                 const identity = worktreeIdentity(taskSegment, MAIN_WORKTREE);
-                const destination = join(this.#projectContainer(project.name), identity.directory);
+                const destination = join(root, safePathSegment(binding.directory));
                 const physical = previous === undefined
                     ? await this.git.clone({
                         remoteUrl: project.remoteUrl,
@@ -966,9 +968,25 @@ export class FileTaskWorkspacePreparer {
                     const requestedBase = previous?.access === "write" || requestedBaseRef === undefined
                         ? null
                         : await this.git.inspect(mainEntry.path, requestedBaseRef);
+                    if (previous?.access === "read" && previous.directory === binding.directory) {
+                        const viewPath = join(root, binding.directory);
+                        const metadata = await lstat(viewPath).catch((error) => {
+                            if (errorCode(error) === "ENOENT")
+                                return null;
+                            throw error;
+                        });
+                        if (metadata?.isSymbolicLink()) {
+                            if (resolve(root, await readlink(viewPath)) !== resolve(previous.path)) {
+                                throw new Error(`Read-only workspace view changed before scope expansion: ${viewPath}.`);
+                            }
+                            // Remove only the registered read view, never its target.
+                            await unlink(viewPath);
+                        }
+                    }
                     const physical = await this.git.ensureWorktree({
                         repositoryPath: mainEntry.path,
-                        container: this.#projectContainer(project.name),
+                        container: root,
+                        directory: binding.directory,
                         taskSegment,
                         roleName: item.id,
                         baseRef
@@ -1139,7 +1157,8 @@ export class FileTaskWorkspacePreparer {
                     const project = requireProject(this.store, entry.projectId);
                     const physical = await this.git.ensureWorktree({
                         repositoryPath: this.#taskRepositoryPath(taskId, project.id),
-                        container: this.#projectContainer(project.name),
+                        container: existing.root,
+                        directory: entry.directory,
                         taskSegment,
                         roleName: managedWorktreeName(owner),
                         baseRef: entry.baseCommit
@@ -1151,6 +1170,7 @@ export class FileTaskWorkspacePreparer {
                 return existing;
             }
             const prepared = [];
+            const root = this.#executionLaneWorkspaceRoot(taskId, executionGroupId, executionLaneId);
             try {
                 for (const binding of lockedTask.projectBindings) {
                     const project = requireProject(this.store, binding.projectId);
@@ -1162,7 +1182,8 @@ export class FileTaskWorkspacePreparer {
                     const inputHead = inputHeadByProject.get(project.id) ?? sourceEntry.baseCommit;
                     const physical = await this.git.ensureWorktree({
                         repositoryPath: this.#taskRepositoryPath(taskId, project.id),
-                        container: this.#projectContainer(project.name),
+                        container: root,
+                        directory: sourceEntry.directory,
                         taskSegment,
                         roleName: managedWorktreeName(owner),
                         baseRef: inputHead
@@ -1182,7 +1203,6 @@ export class FileTaskWorkspacePreparer {
                         }
                     });
                 }
-                const root = this.#executionLaneWorkspaceRoot(taskId, executionGroupId, executionLaneId);
                 await ensureWorkspaceView(root, prepared.map(({ entry }) => entry));
                 const workspace = createManagedWorkspace({
                     owner,
@@ -1257,13 +1277,15 @@ export class FileTaskWorkspacePreparer {
             const project = requireProject(this.store, entry.projectId);
             const result = await this.git.removeWorktree({
                 repositoryPath: this.#taskRepositoryPath(task.id, project.id),
-                container: this.#projectContainer(project.name),
+                container: dirname(entry.path),
+                directory: entry.directory,
                 taskSegment: this.#taskSegment(task),
                 roleName: managedWorktreeName(workspace.owner),
                 deleteBranch: true
             });
             if (result === "dirty")
                 return "dirty";
+            this.#recordArchivePathRemoval(task, entry.path, result);
             removed ||= result === "removed";
         }
         await removeWorkspaceView(workspace.root);
@@ -1310,7 +1332,8 @@ export class FileTaskWorkspacePreparer {
             const project = requireProject(this.store, entry.projectId);
             const result = await this.git.removeWorktree({
                 repositoryPath: this.#taskRepositoryPath(task.id, project.id),
-                container: this.#projectContainer(project.name),
+                container: dirname(entry.path),
+                directory: entry.directory,
                 taskSegment,
                 roleName: managedWorktreeName(workspace.owner),
                 deleteBranch: true
@@ -1417,19 +1440,19 @@ export class FileTaskWorkspacePreparer {
             const snapshotCommits = new Map((taskScope
                 ? round.taskCandidate?.projects ?? []
                 : candidate.gitSnapshot.projects).map(({ projectId, commit }) => [projectId, commit]));
+            const reviewRoot = this.#reviewRoundWorkspaceRoot(task.id, round);
             const frozenEntries = taskScope
                 ? task.projectBindings.map((binding) => {
                     const commit = snapshotCommits.get(binding.projectId);
                     if (commit === undefined) {
                         throw new Error(`Task Review candidate Project is missing: ${binding.projectId}.`);
                     }
-                    const project = requireProject(this.store, binding.projectId);
                     const identity = worktreeIdentity(taskSegment, this.#reviewWorktreeName(round));
                     return {
                         projectId: binding.projectId,
                         directory: binding.directory,
                         access: "write",
-                        path: join(this.#projectContainer(project.name), identity.directory),
+                        path: join(reviewRoot, safePathSegment(binding.directory)),
                         branch: identity.branch,
                         baseRef: commit,
                         baseCommit: commit
@@ -1447,7 +1470,6 @@ export class FileTaskWorkspacePreparer {
             }
             const expectedEntries = new Map(frozenEntries.map((entry) => [entry.projectId, entry]));
             const existing = this.store.getReviewRoundWorkspace(task.id, round.id);
-            const reviewRoot = this.#reviewRoundWorkspaceRoot(task.id, round);
             if (taskScope && existing === null) {
                 const reassigned = await this.#reassignTaskReviewWorkspace(task, round, reviewer, reviewRoot, frozenEntries);
                 if (reassigned !== null)
@@ -1482,7 +1504,7 @@ export class FileTaskWorkspacePreparer {
                     }
                     const project = requireProject(this.store, entry.projectId);
                     const identity = worktreeIdentity(taskSegment, this.#reviewWorktreeName(round));
-                    const expectedPath = join(this.#projectContainer(project.name), identity.directory);
+                    const expectedPath = join(reviewRoot, safePathSegment(entry.directory));
                     if (entry.path !== expectedPath || entry.branch !== identity.branch) {
                         throw new ReviewRoundWorkspaceEvidenceError(`ReviewRound workspace managed identity mismatch for ${round.id}/${entry.projectId}.`);
                     }
@@ -1568,7 +1590,8 @@ export class FileTaskWorkspacePreparer {
                     const project = requireProject(this.store, source.projectId);
                     const physical = await this.git.ensureWorktree({
                         repositoryPath: this.#taskRepositoryPath(task.id, project.id),
-                        container: this.#projectContainer(project.name),
+                        container: reviewRoot,
+                        directory: source.directory,
                         taskSegment,
                         roleName: this.#reviewWorktreeName(round),
                         baseRef: source.baseCommit
@@ -1869,7 +1892,8 @@ export class FileTaskWorkspacePreparer {
             const project = requireProject(this.store, entry.projectId);
             const result = await this.git.removeWorktree({
                 repositoryPath: this.#taskRepositoryPath(task.id, project.id),
-                container: this.#projectContainer(project.name),
+                container: dirname(entry.path),
+                directory: entry.directory,
                 taskSegment: this.#taskSegment(task),
                 roleName: this.#reviewWorktreeName(round),
                 deleteBranch: true
@@ -1877,6 +1901,7 @@ export class FileTaskWorkspacePreparer {
             if (result === "dirty") {
                 throw new Error(`Review workspace changed after cleanup preflight: ${round.id}.`);
             }
+            this.#recordArchivePathRemoval(task, entry.path, result);
             removed ||= result === "removed";
         }
         await removeWorkspaceView(workspace.root);
@@ -1935,7 +1960,8 @@ export class FileTaskWorkspacePreparer {
             const project = requireProject(this.store, entry.projectId);
             const result = await this.git.removeWorktree({
                 repositoryPath: this.#taskRepositoryPath(task.id, project.id),
-                container: this.#projectContainer(project.name),
+                container: dirname(entry.path),
+                directory: entry.directory,
                 taskSegment: this.#taskSegment(task),
                 roleName: managedWorktreeName(workspace.owner),
                 deleteBranch: true
@@ -1943,6 +1969,7 @@ export class FileTaskWorkspacePreparer {
             if (result === "dirty") {
                 throw new Error(`WorkItem workspace changed after cleanup preflight: ${item.id}.`);
             }
+            this.#recordArchivePathRemoval(task, entry.path, result);
             removed ||= result === "removed";
         }
         await removeWorkspaceView(workspace.root);
@@ -1956,7 +1983,7 @@ export class FileTaskWorkspacePreparer {
         catch (error) {
             if (!removed)
                 throw error;
-            throw new Error(`WorkItem worktree was removed but durable cleanup was not recorded; retry cleanup: ${error instanceof Error ? error.message : String(error)}`);
+            throw new Error(`WorkItem worktree was removed but durable cleanup was not recorded; retry cleanup: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
         }
         return removed ? "removed" : "missing";
     }
@@ -1991,19 +2018,36 @@ export class FileTaskWorkspacePreparer {
         }
         if (attempt.status === "running"
             || attempt.status === "blocked"
+            || attempt.status === "conflicted"
             || attempt.status === "validating") {
             throw new Error(`IntegrationAttempt must be terminal before cleanup: ${attempt.id}.`);
         }
         const workspace = this.store.getIntegrationWorkspace(task.id, attempt.id);
         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
+        // how the layout helper derives it. Absent a recorded workspace, fall back
+        // to the deterministic integration owner root + bound directory.
+        const recorded = workspace?.entries[0];
+        const directory = recorded?.directory
+            ?? task.projectBindings.find(({ projectId }) => projectId === attempt.projectId)?.directory;
+        if (directory === undefined) {
+            throw new Error(`Integration Project binding is unavailable: ${task.id}/${project.id}.`);
+        }
         const result = await this.git.removeIntegrationWorktree({
             repositoryPath: this.#taskRepositoryPath(task.id, project.id),
-            container: this.#projectContainer(project.name),
+            container: recorded !== undefined
+                ? dirname(recorded.path)
+                : this.#integrationWorkspaceRoot(task.id, attempt.id),
+            directory,
             taskSegment: this.#taskSegment(task),
             integrationId: attempt.id,
-            discardChanges: attempt.status === "failed"
+            discardChanges: task.status !== "archived" && attempt.status === "failed"
         });
         if (result !== "dirty") {
+            for (const entry of workspace?.entries ?? []) {
+                this.#recordArchivePathRemoval(task, entry.path, result);
+            }
             if (workspace !== null)
                 this.#resourceRegistrar().markWorkspaceDeleted(workspace);
             await rm(join(this.home, "artifacts", "integration-checks", task.id, attempt.id), { recursive: true, force: true });
@@ -2050,10 +2094,14 @@ export class FileTaskWorkspacePreparer {
             }
             for (const entry of main.entries) {
                 assertTaskArchiveState(requireTask(this.store, task.id), task);
-                const result = await this.git.removeStrandedWorktree(entry.path);
+                const result = await this.git.removeTaskClone({
+                    path: entry.path, container: main.root, directory: entry.directory,
+                    taskSegment: this.#taskSegment(task), branch: entry.branch
+                });
                 if (result === "dirty") {
                     throw new Error(`Task workspace changed after cleanup preflight: ${task.id}.`);
                 }
+                this.#recordArchivePathRemoval(task, entry.path, result);
             }
             assertTaskArchiveState(requireTask(this.store, task.id), task);
             await removeWorkspaceView(main.root);
@@ -2064,6 +2112,16 @@ export class FileTaskWorkspacePreparer {
         this.#clearTaskWorkspace(task, this.#fallbackWorkspace());
         return { taskId, status: "removed" };
     }
+    #recordArchivePathRemoval(task, path, status) {
+        if (task.status !== "archived")
+            return;
+        recordArchiveCleanup(this.store, task.id, {
+            resource: `path:${path}`, paths: [path],
+            detail: status === "missing"
+                ? "Directory absent; exact Git cleanup completed where applicable."
+                : "Exact owned path removed."
+        }, status, this.now());
+    }
     async #inspectEntries(taskId, taskSegment, roleName, entries) {
         if (entries.length === 0)
             return "missing";
@@ -2072,7 +2130,11 @@ export class FileTaskWorkspacePreparer {
             const project = requireProject(this.store, entry.projectId);
             const state = await this.git.inspectWorktree({
                 repositoryPath: this.#taskRepositoryPath(taskId, project.id),
-                container: this.#projectContainer(project.name),
+                // A managed worktree lives at `root/<directory>`, so its parent is the
+                // owner workspace root. Deriving it from the entry keeps this helper
+                // agnostic to which owner (main/work-item/review/lane) it serves.
+                container: dirname(entry.path),
+                directory: entry.directory,
                 taskSegment,
                 roleName
             });
@@ -2082,9 +2144,6 @@ export class FileTaskWorkspacePreparer {
         }
         return found ? "clean" : "missing";
     }
-    #projectContainer(projectName) {
-        return join(resolveWorktreeRoot(this.home, this.store.getConfig().defaultWorkspace), safePathSegment(projectName));
-    }
     /**
      * The Task workspace ref segment for Git worktree derivation: the
      * token-bearing segment for a Task with a persisted identity, its bare id
@@ -2095,13 +2154,16 @@ export class FileTaskWorkspacePreparer {
         return taskWorkspaceRefSegment(task);
     }
     #taskWorkspaceRoot(taskId) {
-        return join(resolveTaskRoot(this.home, this.store.getConfig().defaultWorkspace), safePathSegment(taskId), "main");
+        return join(resolveTaskRoot(this.home), safePathSegment(taskId), "main");
     }
     #workItemWorkspaceRoot(taskId, workItemId) {
-        return join(resolveTaskRoot(this.home, this.store.getConfig().defaultWorkspace), safePathSegment(taskId), "work-items", safePathSegment(workItemId));
+        return join(resolveTaskRoot(this.home), safePathSegment(taskId), "work-items", safePathSegment(workItemId));
     }
     #reviewRoundWorkspaceRoot(taskId, round) {
-        return join(resolveTaskRoot(this.home, this.store.getConfig().defaultWorkspace), safePathSegment(taskId), "reviews", safePathSegment(this.#reviewWorktreeName(round)));
+        return join(resolveTaskRoot(this.home), safePathSegment(taskId), "reviews", safePathSegment(this.#reviewWorktreeName(round)));
+    }
+    #integrationWorkspaceRoot(taskId, integrationId) {
+        return integrationWorkspaceRoot(this.home, taskId, integrationId);
     }
     #reviewWorktreeName(round) {
         return (round.scope ?? "work-item") === "task"
@@ -2109,7 +2171,7 @@ export class FileTaskWorkspacePreparer {
             : round.id;
     }
     #executionLaneWorkspaceRoot(taskId, groupId, laneId) {
-        return join(resolveTaskRoot(this.home, this.store.getConfig().defaultWorkspace), safePathSegment(taskId), "execution-lanes", safePathSegment(groupId), safePathSegment(laneId));
+        return join(resolveTaskRoot(this.home), safePathSegment(taskId), "execution-lanes", safePathSegment(groupId), safePathSegment(laneId));
     }
     #fallbackWorkspace() {
         return this.store.getConfig().defaultWorkspace ?? process.cwd();
@@ -2127,7 +2189,8 @@ export class FileTaskWorkspacePreparer {
             }
             const removal = await this.git.removeWorktree({
                 repositoryPath: this.#taskRepositoryPath(task.id, project.id),
-                container: this.#projectContainer(project.name),
+                container: dirname(entry.path),
+                directory: entry.directory,
                 taskSegment,
                 roleName,
                 ...(deleteBranch ? { deleteBranch: true } : {})
@@ -2218,7 +2281,7 @@ function requireTask(store, taskId) {
     return task;
 }
 function assertTaskArchiveState(current, expected) {
-    if ((current.status !== "completed" && current.status !== "cancelled")
+    if ((current.status !== "completed" && current.status !== "cancelled" && current.status !== "archived")
         || !isDeepStrictEqual(current, expected)) {
         throw new WorkspaceCleanupBlockedError("task-changed", `task:${expected.id}`, true, `Task changed during archive cleanup: ${expected.id}.`);
     }
@@ -2441,14 +2504,28 @@ function recordWorkspaceDisposition(store, taskId, workItem, now) {
         throw new Error(`Work item not found: ${workItem.workItemId}.`);
     store.saveWorkItem(taskId, recordWorkItemWorkspaceDisposition(item, workItem.disposition, now));
 }
+/**
+ * Reconcile an owner workspace directory so it presents every bound Project at
+ * `root/<directory>`.
+ *
+ * Writable Projects are real Git worktrees created in place at `root/<directory>`
+ * by the Git port before this runs; they are left untouched here. Read-only
+ * Projects share an upstream worktree (the Task main clone) and are surfaced as
+ * genuine symlinks `root/<directory> -> entry.path`. Only the symlink views are
+ * reconciled: a stale or renamed read link is repaired, an obsolete one removed.
+ * A real directory (a write worktree) is never treated as a view entry, so this
+ * neither creates nor removes committed Git content.
+ */
 async function ensureWorkspaceView(root, entries) {
     await mkdir(root, { recursive: true });
-    const expected = new Map(entries.map((entry) => [entry.directory, entry.path]));
+    const expected = new Map(entries.filter((entry) => entry.access === "read").map((entry) => [entry.directory, entry.path]));
     for (const current of await readdir(root, { withFileTypes: true })) {
+        // A write entry is a real worktree directory living in place under root; it
+        // is owned by Git, not by this view, so it is never reconciled or removed
+        // here. Only symlinks (read-entry views) are this function's concern.
+        if (!current.isSymbolicLink())
+            continue;
         const target = expected.get(current.name);
-        if (!current.isSymbolicLink()) {
-            throw new Error(`Managed workspace contains an unexpected entry: ${join(root, current.name)}.`);
-        }
         const path = join(root, current.name);
         const linked = resolve(root, await readlink(path));
         if (target === undefined) {
@@ -2493,23 +2570,17 @@ function safePathSegment(value) {
 function sameCommit(left, right) {
     return left.toLowerCase() === right.toLowerCase();
 }
-export function resolveWorktreeRoot(home, workspace) {
-    return join(resolveWorkspaceRoot(home, workspace), "worktree");
-}
-export function resolveTaskRoot(home, workspace) {
-    return join(resolveWorkspaceRoot(home, workspace), "tasks");
+export function resolveTaskRoot(home) {
+    return managedTaskRoot(home);
 }
-function resolveWorkspaceRoot(home, workspace) {
-    if (workspace === undefined) {
-        throw new Error("Project workspace is not configured; run yui setup.");
-    }
-    const homeRoot = resolve(home);
-    const workspaceRoot = resolve(workspace);
-    const fromHome = relative(homeRoot, workspaceRoot);
-    if (fromHome === "" || (!fromHome.startsWith("..") && !isAbsolute(fromHome))) {
-        throw new Error("Project workspace must be outside YUI_HOME.");
-    }
-    return workspaceRoot;
+/**
+ * The integration owner root: `tasks/<taskId>/integrations/<integrationId>`.
+ * A single-project integration worktree lives at `<root>/<boundDirectory>`.
+ * Shared by the preparer and the integration service so create and cleanup
+ * derive the same on-disk path.
+ */
+export function integrationWorkspaceRoot(home, taskId, integrationId) {
+    return join(managedTaskRoot(home), safePathSegment(taskId), "integrations", safePathSegment(integrationId));
 }
 function errorCode(error) {
     return typeof error === "object" && error !== null && "code" in error

package/dist/repository/workItemCandidateSnapshot.js

@@ -0,0 +1,34 @@
+import { usageError } from "../errors/cliError.js";
+/** Read the existing source owner once and freeze its exact Candidate evidence. */
+export async function snapshotWorkItemCandidate(store, preparer, taskId, workItemId, taskFinalReviewContract) {
+    const item = store.getWorkItem(taskId, workItemId);
+    if (item === null)
+        throw usageError(`Work Item not found: ${taskId}/${workItemId}.`);
+    const workspace = store.getWorkItemWorkspace(taskId, workItemId);
+    if (workspace !== null) {
+        return { candidateGitSnapshot: await preparer.snapshotCandidateWorkspace(workspace) };
+    }
+    // Read-only results freeze their summary/artifact evidence, not Git output.
+    if (item.writeProjectIds.length === 0)
+        return {};
+    if (taskFinalReviewContract === undefined) {
+        throw usageError(`Work Item ${taskId}/${workItemId} has no managed Candidate workspace. `
+            + `Use yui task work isolate ${taskId}/${workItemId} before implementing writable work.`);
+    }
+    // Preserve the existing exact Task-final metadata-only Candidate contract.
+    // It is not the ordinary route for a new independently accepted code result.
+    const main = store.getTaskWorkspace(taskId);
+    if (main === null)
+        return {};
+    if (main.owner.type !== "task") {
+        throw usageError(`Task has no authoritative main workspace: ${taskId}.`);
+    }
+    try {
+        return {
+            directTaskMainSnapshot: await preparer.snapshotDirectTaskMain(main, item.writeProjectIds)
+        };
+    }
+    catch (error) {
+        throw usageError(error instanceof Error ? error.message : String(error));
+    }
+}

package/dist/resources/resourceDiscovery.js

@@ -11,6 +11,7 @@ import { existsSync, lstatSync, readFileSync, readdirSync, statSync } from "node
 import { basename, join, resolve } from "node:path";
 import { promisify } from "node:util";
 import { managedProjectPath } from "../repository/project.js";
+import { managedRuntimeRoot } from "../storage/homeLayout.js";
 import { isResourceQuarantinePath } from "./resourceRegistry.js";
 import { createResourceRecord, isReleaseNamespacePath, isTerminalTaskStatus } from "./resourceTypes.js";
 const executeFile = promisify(execFile);
@@ -164,8 +165,8 @@ export async function discoverResources(input) {
 function discoverRuntimeArtifacts(home, input) {
     const discovered = [];
     const now = input.now;
-    // 3a. Task runtime isolation roots: <home>.task-runtimes/<taskId>/<owner>/<launch>/
-    const runtimeRoot = `${resolve(home)}.task-runtimes`;
+    // 3a. Task runtime isolation roots: <home>/runtime/task-runtimes/<taskId>/<owner>/<launch>/
+    const runtimeRoot = managedRuntimeRoot(home);
     if (existsSync(runtimeRoot)) {
         for (const taskEntry of safeReaddir(runtimeRoot)) {
             if (!taskEntry.isDirectory())