@zq-silk/yui 0.2.0 → 0.4.2

package/dist/repository/project.js

@@ -0,0 +1,213 @@
+import { resolve } from "node:path";
+export function createProject(id, name, path, branches, now, metadata = {}) {
+    const timestamp = now.toISOString();
+    return validateProject({
+        schemaVersion: 2,
+        id: requireIdentity(id, "Project id"),
+        name: validateProjectName(name),
+        aliases: normalizeAliases(metadata.aliases ?? [], name),
+        path: resolve(requireText(path, "Project path")),
+        ...(metadata.remoteUrl === undefined
+            ? {}
+            : { remoteUrl: requireText(metadata.remoteUrl, "Project remote URL") }),
+        stableBranch: requireGitRef(branches.stable, "Project stable branch"),
+        developmentBranch: requireGitRef(branches.development, "Project development branch"),
+        knowledge: [],
+        createdAt: timestamp,
+        updatedAt: timestamp
+    });
+}
+export function validateProjectName(value) {
+    return requireIdentity(value, "Project name");
+}
+export function addProjectKnowledge(project, id, title, body, now) {
+    const timestamp = now.toISOString();
+    const knowledge = {
+        schemaVersion: 1,
+        id: requireIdentity(id, "Project knowledge id"),
+        title: requireText(title, "Project knowledge title"),
+        body: requireText(body, "Project knowledge body"),
+        status: "active",
+        createdAt: timestamp,
+        updatedAt: timestamp
+    };
+    if (project.knowledge.some((entry) => entry.id === knowledge.id)) {
+        throw new Error(`Project knowledge already exists: ${knowledge.id}.`);
+    }
+    return validateProject({
+        ...project,
+        knowledge: [...project.knowledge, knowledge],
+        updatedAt: timestamp
+    });
+}
+export function updateProjectMetadata(project, patch, now) {
+    const remoteUrl = patch.remoteUrl === undefined
+        ? project.remoteUrl
+        : patch.remoteUrl === null
+            ? undefined
+            : requireText(patch.remoteUrl, "Project remote URL");
+    const { remoteUrl: _remoteUrl, ...withoutRemote } = project;
+    return validateProject({
+        ...withoutRemote,
+        aliases: normalizeAliases(patch.aliases ?? project.aliases, project.name),
+        ...(remoteUrl === undefined ? {} : { remoteUrl }),
+        stableBranch: patch.stableBranch === undefined
+            ? project.stableBranch
+            : requireGitRef(patch.stableBranch, "Project stable branch"),
+        developmentBranch: patch.developmentBranch === undefined
+            ? project.developmentBranch
+            : requireGitRef(patch.developmentBranch, "Project development branch"),
+        updatedAt: now.toISOString()
+    });
+}
+export function updateProjectKnowledge(project, id, patch, now) {
+    const knowledgeId = requireIdentity(id, "Project knowledge id");
+    let found = false;
+    const knowledge = project.knowledge.map((entry) => {
+        if (entry.id !== knowledgeId)
+            return entry;
+        found = true;
+        if (entry.status === "retired") {
+            throw new Error(`Project knowledge is retired: ${knowledgeId}.`);
+        }
+        return {
+            ...entry,
+            title: patch.title === undefined
+                ? entry.title
+                : requireText(patch.title, "Project knowledge title"),
+            body: patch.body === undefined
+                ? entry.body
+                : requireText(patch.body, "Project knowledge body"),
+            updatedAt: now.toISOString()
+        };
+    });
+    if (!found)
+        throw new Error(`Project knowledge not found: ${knowledgeId}.`);
+    return validateProject({ ...project, knowledge, updatedAt: now.toISOString() });
+}
+export function retireProjectKnowledge(project, id, now) {
+    const knowledgeId = requireIdentity(id, "Project knowledge id");
+    let found = false;
+    const knowledge = project.knowledge.map((entry) => {
+        if (entry.id !== knowledgeId)
+            return entry;
+        found = true;
+        return {
+            ...entry,
+            status: "retired",
+            updatedAt: now.toISOString()
+        };
+    });
+    if (!found)
+        throw new Error(`Project knowledge not found: ${knowledgeId}.`);
+    return validateProject({ ...project, knowledge, updatedAt: now.toISOString() });
+}
+export function resolveProject(projects, reference) {
+    const normalized = requireText(reference, "Project reference").toLocaleLowerCase();
+    const matches = projects.filter((project) => (project.id.toLocaleLowerCase() === normalized
+        || project.name.toLocaleLowerCase() === normalized
+        || project.aliases.some((alias) => alias.toLocaleLowerCase() === normalized)));
+    if (matches.length > 1)
+        throw new Error(`Project reference is ambiguous: ${reference}.`);
+    return matches[0] ?? null;
+}
+export function assertProjectCatalog(projects) {
+    const paths = new Map();
+    const references = new Map();
+    for (const project of projects) {
+        validateProject(project);
+        const pathOwner = paths.get(project.path);
+        if (pathOwner !== undefined && pathOwner !== project.id) {
+            throw new Error(`Project path is already registered: ${project.path}.`);
+        }
+        paths.set(project.path, project.id);
+        for (const reference of [project.id, project.name, ...project.aliases]) {
+            const key = reference.toLocaleLowerCase();
+            const owner = references.get(key);
+            if (owner !== undefined && owner !== project.id) {
+                throw new Error(`Project reference is already registered: ${reference}.`);
+            }
+            references.set(key, project.id);
+        }
+    }
+}
+export function validateProject(project) {
+    if (project.schemaVersion !== 2) {
+        throw new Error("Project must use schemaVersion 2.");
+    }
+    requireIdentity(project.id, "Project id");
+    requireIdentity(project.name, "Project name");
+    normalizeAliases(project.aliases, project.name);
+    const references = new Set();
+    for (const reference of [project.id, project.name, ...project.aliases]) {
+        const folded = reference.toLocaleLowerCase();
+        if (references.has(folded)) {
+            throw new Error(`Duplicate Project reference: ${reference}.`);
+        }
+        references.add(folded);
+    }
+    if (resolve(requireText(project.path, "Project path")) !== project.path) {
+        throw new Error("Project path must be absolute and normalized.");
+    }
+    if (project.remoteUrl !== undefined)
+        requireText(project.remoteUrl, "Project remote URL");
+    requireGitRef(project.stableBranch, "Project stable branch");
+    requireGitRef(project.developmentBranch, "Project development branch");
+    const knowledgeIds = new Set();
+    for (const entry of project.knowledge) {
+        if (entry.schemaVersion !== 1)
+            throw new Error("Project knowledge must use schemaVersion 1.");
+        requireIdentity(entry.id, "Project knowledge id");
+        requireText(entry.title, "Project knowledge title");
+        requireText(entry.body, "Project knowledge body");
+        if (!["active", "retired"].includes(entry.status)) {
+            throw new Error("Project knowledge status is invalid.");
+        }
+        requireTimestamp(entry.createdAt, "Project knowledge createdAt");
+        requireTimestamp(entry.updatedAt, "Project knowledge updatedAt");
+        if (knowledgeIds.has(entry.id))
+            throw new Error(`Duplicate Project knowledge id: ${entry.id}.`);
+        knowledgeIds.add(entry.id);
+    }
+    requireTimestamp(project.createdAt, "Project createdAt");
+    requireTimestamp(project.updatedAt, "Project updatedAt");
+    return project;
+}
+function normalizeAliases(values, name) {
+    const aliases = values.map((value) => requireIdentity(value, "Project alias"));
+    const folded = new Set();
+    for (const value of [name, ...aliases]) {
+        const key = value.toLocaleLowerCase();
+        if (folded.has(key))
+            throw new Error(`Duplicate Project name or alias: ${value}.`);
+        folded.add(key);
+    }
+    return Object.freeze([...aliases]);
+}
+function requireIdentity(value, label) {
+    const normalized = requireText(value, label);
+    if (["__proto__", "prototype", "constructor", ".", ".."].includes(normalized)
+        || /[\/\\\0]/.test(normalized)) {
+        throw new Error(`${label} is invalid.`);
+    }
+    return normalized;
+}
+function requireGitRef(value, label) {
+    const ref = requireText(value, label);
+    if (ref.startsWith("-") || /[\r\n]/.test(ref))
+        throw new Error(`${label} is invalid.`);
+    return ref;
+}
+function requireText(value, label) {
+    if (typeof value !== "string" || value.includes("\0"))
+        throw new Error(`${label} is invalid.`);
+    const normalized = value.trim();
+    if (normalized.length === 0)
+        throw new Error(`${label} is required.`);
+    return normalized;
+}
+function requireTimestamp(value, label) {
+    if (typeof value !== "string" || !Number.isFinite(Date.parse(value))) {
+        throw new Error(`${label} is invalid.`);
+    }
+}

package/dist/repository/taskWorkspaceCoordinator.js

@@ -0,0 +1,392 @@
+import { isDeepStrictEqual } from "node:util";
+import { retireConfirmedAbsentInactiveTaskRolePlaceholders } from "../executor/agentExecutor.js";
+import { hasRuntimeLifecycleWork, runtimeLifecycleTarget } from "../runtime/lifecycleReservation.js";
+import { managedWorkspaceKey } from "../worktree/managedWorkspace.js";
+import { WorkspaceCleanupBlockedError } from "./taskWorkspacePreparer.js";
+export { WorkspaceCleanupBlockedError } from "./taskWorkspacePreparer.js";
+/**
+ * Coordinates persisted Role cwd changes with the runtime that may still be
+ * executing in the previous directory.
+ */
+export class TaskWorkspaceCoordinator {
+    store;
+    preparer;
+    runtime;
+    constructor(store, preparer, runtime) {
+        this.store = store;
+        this.preparer = preparer;
+        this.runtime = runtime;
+    }
+    async isolateWorkItem(taskId, workItemId) {
+        const item = this.store.getWorkItem(taskId, workItemId);
+        if (item === null)
+            throw new Error(`Work item not found: ${taskId}/${workItemId}.`);
+        const assignee = this.#workItemIsolationAssignee(item);
+        const activeDevelopRun = this.store.listAgentRuns(item.taskId)
+            .find((run) => run.status === "active" && run.workItemId === item.id);
+        if (activeDevelopRun !== undefined) {
+            throw new Error(`Work Item already has an active Develop Run: ${activeDevelopRun.id}.`);
+        }
+        const task = this.store.getTask(item.taskId);
+        const taskProjectIds = task.projectBindings.map(({ projectId }) => projectId);
+        const existing = this.store.getWorkItemWorkspace(item.taskId, item.id);
+        if (existing !== null
+            && existing.owner.type === "work-item"
+            && existing.owner.workItemId === item.id
+            && sameProjectScope(existing, taskProjectIds, item.writeProjectIds)
+            && item.baseRefs === undefined)
+            return existing;
+        if (existing !== null) {
+            if (existing.owner.type !== "work-item" || existing.owner.workItemId !== item.id) {
+                throw new Error(`WorkItem already has another managed workspace: ${item.taskId}/${item.id}.`);
+            }
+        }
+        await this.preparer.prepareTaskWorkspace(item.taskId);
+        const prepared = this.store.getWorkItemWorkspace(item.taskId, item.id);
+        if (prepared !== null
+            && prepared.owner.type === "work-item"
+            && prepared.owner.workItemId === item.id
+            && sameProjectScope(prepared, taskProjectIds, item.writeProjectIds)
+            && item.baseRefs === undefined)
+            return prepared;
+        if (prepared !== null) {
+            if (prepared.owner.type !== "work-item" || prepared.owner.workItemId !== item.id) {
+                throw new Error(`WorkItem already has another managed workspace: ${item.taskId}/${item.id}.`);
+            }
+        }
+        if (assignee !== undefined)
+            await this.#stopLiveRoles(item.taskId, [assignee]);
+        return this.preparer.prepareWorkItemWorkspace(item.taskId, item.id);
+    }
+    async cleanupWorkItem(taskId, workItemId, disposition) {
+        const item = this.store.getWorkItem(taskId, workItemId);
+        if (item === null)
+            throw new Error(`Work item not found: ${taskId}/${workItemId}.`);
+        if (!isTerminalWorkItem(item)) {
+            throw new Error(`Work item must be terminal before cleanup: ${item.id}.`);
+        }
+        if (item.workspaceDisposition !== undefined
+            && item.workspaceDisposition !== disposition) {
+            throw new Error(`Work item workspace is already recorded as ${item.workspaceDisposition}.`);
+        }
+        if (item.workspaceDisposition === disposition)
+            return "missing";
+        const state = await this.preparer.inspectWorkItemWorkspace(item.taskId, item.id);
+        if (state === "dirty")
+            return "dirty";
+        this.#assertWorkItemRuntimeQuiescent(item);
+        await this.#stopLiveRoles(item.taskId, this.#workItemRoleNames(item));
+        const laneCleanup = await this.preparer.cleanupExecutionLaneWorkspacesForWorkItem(item.taskId, item.id);
+        if (laneCleanup === "dirty")
+            return "dirty";
+        return this.preparer.cleanupWorkItemWorkspace(item.taskId, item.id, disposition);
+    }
+    async cleanupWorkItemRuntime(taskId, workItemId) {
+        const item = this.store.getWorkItem(taskId, workItemId);
+        if (item === null)
+            throw new Error(`Work item not found: ${taskId}/${workItemId}.`);
+        this.#assertWorkItemRuntimeQuiescent(item);
+        await this.#stopLiveRoles(item.taskId, this.#workItemRoleNames(item));
+        return "released";
+    }
+    async cleanupReviewRound(taskId, reviewRoundId) {
+        const round = this.store.getReviewRound(taskId, reviewRoundId);
+        if (round === null)
+            throw new Error(`ReviewRound not found: ${taskId}/${reviewRoundId}.`);
+        if (round.status !== "completed" && round.status !== "failed") {
+            throw new Error(`ReviewRound must be terminal before cleanup: ${round.id}.`);
+        }
+        const state = await this.preparer.inspectReviewRoundWorkspace(taskId, reviewRoundId);
+        if (state === "dirty")
+            return "dirty";
+        await this.#stopLiveRoles(taskId, this.#reviewRoundRoleNames(round));
+        const laneCleanup = await this.preparer.cleanupExecutionLaneWorkspacesForReviewRound(taskId, reviewRoundId);
+        if (laneCleanup === "dirty")
+            return "dirty";
+        return this.preparer.cleanupReviewRoundWorkspace(taskId, reviewRoundId);
+    }
+    async cleanupTaskForArchive(taskId, disposition) {
+        try {
+            const task = this.store.getTask(taskId);
+            if (task === null)
+                throw new Error(`Task not found: ${taskId}.`);
+            if (task.status !== "completed" && task.status !== "retired") {
+                throw new Error(`Task must be completed or retired before archive cleanup: ${task.id}.`);
+            }
+            const managedWorkspaces = [...this.store.listManagedWorkspaces(task.id)]
+                .sort((left, right) => managedWorkspaceKey(left.owner)
+                .localeCompare(managedWorkspaceKey(right.owner)));
+            const laneWorkspaces = managedWorkspaces.filter(({ owner }) => owner.type === "execution-lane");
+            const workspaces = managedWorkspaces
+                .filter(({ owner }) => owner.type === "work-item");
+            const workItems = workspaces.map((workspace) => {
+                const workItemId = workspace.owner.type === "work-item"
+                    ? workspace.owner.workItemId
+                    : "";
+                const item = this.store.getWorkItem(task.id, workItemId);
+                if (item === null)
+                    throw new Error(`Work item not found: ${task.id}/${workItemId}.`);
+                if (item.status !== "completed" && item.status !== "retired") {
+                    throw new Error(`Work item must be completed or retired before archive cleanup: ${item.id}.`);
+                }
+                return item;
+            });
+            const allWorkItems = [...this.store.listWorkItems(task.id)]
+                .sort((left, right) => left.id.localeCompare(right.id));
+            const allReviewRounds = [...this.store.listReviewRounds(task.id)]
+                .sort((left, right) => left.id.localeCompare(right.id));
+            const reviewRounds = allReviewRounds.filter((round) => (round.workspace !== undefined && round.workspaceDisposition?.kind !== "removed"));
+            const snapshot = {
+                task,
+                managedWorkspaces,
+                workItems: allWorkItems,
+                reviewRounds: allReviewRounds
+            };
+            for (const round of reviewRounds) {
+                if (round.status !== "completed" && round.status !== "failed") {
+                    throw new Error(`ReviewRound must be terminal before archive cleanup: ${round.id}.`);
+                }
+                if (await this.preparer.inspectReviewRoundWorkspace(task.id, round.id) === "dirty") {
+                    return {
+                        taskId,
+                        status: "retained-dirty",
+                        ...(task.cwd === undefined ? {} : { path: task.cwd }),
+                        error: `ReviewRound worktree is dirty: ${round.id}.`,
+                        reason: "dirty-worktree",
+                        resource: `review-round:${task.id}/${round.id}`,
+                        retryable: true
+                    };
+                }
+            }
+            for (const item of workItems) {
+                if (await this.preparer.inspectWorkItemWorkspace(task.id, item.id) === "dirty") {
+                    return {
+                        taskId,
+                        status: "retained-dirty",
+                        ...(task.cwd === undefined ? {} : { path: task.cwd }),
+                        error: `WorkItem worktree is dirty: ${item.id}.`,
+                        reason: "dirty-worktree",
+                        resource: `work-item:${task.id}/${item.id}`,
+                        retryable: true
+                    };
+                }
+            }
+            for (const workspace of laneWorkspaces) {
+                if (workspace.owner.type !== "execution-lane")
+                    continue;
+                if (await this.preparer.inspectExecutionLaneWorkspace(task.id, workspace.owner.executionGroupId, workspace.owner.executionLaneId) === "dirty") {
+                    return {
+                        taskId,
+                        status: "retained-dirty",
+                        ...(task.cwd === undefined ? {} : { path: task.cwd }),
+                        error: `Execution Lane worktree is dirty: ${managedWorkspaceKey(workspace.owner)}.`,
+                        reason: "dirty-worktree",
+                        resource: managedWorkspaceKey(workspace.owner),
+                        retryable: true
+                    };
+                }
+            }
+            const state = await this.preparer.inspectTaskMainWorkspace(taskId);
+            if (state === "dirty") {
+                return {
+                    taskId,
+                    status: "retained-dirty",
+                    ...(task.cwd === undefined ? {} : { path: task.cwd }),
+                    error: `Task main worktree is dirty: ${task.id}.`,
+                    reason: "dirty-worktree",
+                    resource: `task-worktree:${task.id}`,
+                    retryable: true
+                };
+            }
+            const activeRole = this.store.listRoles(taskId)
+                .find((role) => this.store.getActiveAgentRun(taskId, role.name) !== null);
+            if (activeRole !== undefined) {
+                throw new WorkspaceCleanupBlockedError("active-run", `role:${task.id}/${activeRole.name}`, true, `Task Role still has an active Run: ${task.id}/${activeRole.name}.`);
+            }
+            const roleNames = this.store.listRoles(taskId).map(({ name }) => name);
+            if (roleNames.length > 0) {
+                await this.runtime.stopTaskRoleSessions(taskId, roleNames);
+            }
+            this.#assertTaskArchiveSnapshot(snapshot);
+            for (const workspace of laneWorkspaces) {
+                this.#assertTaskArchiveLifecycle(task);
+                if (workspace.owner.type === "execution-lane") {
+                    await this.preparer.cleanupExecutionLaneWorkspace(task.id, workspace.owner.executionGroupId, workspace.owner.executionLaneId);
+                }
+            }
+            for (const round of reviewRounds) {
+                this.#assertTaskArchiveLifecycle(task);
+                await this.preparer.cleanupReviewRoundWorkspace(task.id, round.id);
+            }
+            for (const item of workItems) {
+                this.#assertTaskArchiveLifecycle(task);
+                await this.preparer.cleanupWorkItemWorkspace(task.id, item.id, item.status === "completed" ? disposition : "abandoned");
+            }
+            this.#assertTaskArchiveLifecycle(task);
+            return this.preparer.cleanupTaskForArchive(taskId);
+        }
+        catch (error) {
+            const task = this.store.getTask(taskId);
+            return {
+                taskId,
+                status: "failed",
+                ...(task?.cwd === undefined ? {} : { path: task.cwd }),
+                error: error instanceof Error ? error.message : String(error),
+                ...(error instanceof WorkspaceCleanupBlockedError
+                    ? {
+                        reason: error.reason,
+                        resource: error.resource,
+                        retryable: error.retryable
+                    }
+                    : {
+                        reason: "cleanup-failed",
+                        resource: `task:${taskId}`,
+                        retryable: true
+                    })
+            };
+        }
+    }
+    #assertTaskArchiveSnapshot(snapshot) {
+        this.#assertTaskArchiveLifecycle(snapshot.task);
+        const managedWorkspaces = [...this.store.listManagedWorkspaces(snapshot.task.id)]
+            .sort((left, right) => managedWorkspaceKey(left.owner)
+            .localeCompare(managedWorkspaceKey(right.owner)));
+        const workItems = [...this.store.listWorkItems(snapshot.task.id)]
+            .sort((left, right) => left.id.localeCompare(right.id));
+        const reviewRounds = [...this.store.listReviewRounds(snapshot.task.id)]
+            .sort((left, right) => left.id.localeCompare(right.id));
+        if (!isDeepStrictEqual(managedWorkspaces, snapshot.managedWorkspaces)
+            || !isDeepStrictEqual(workItems, snapshot.workItems)
+            || !isDeepStrictEqual(reviewRounds, snapshot.reviewRounds)) {
+            throw new WorkspaceCleanupBlockedError("task-changed", `task:${snapshot.task.id}`, true, `Task resources changed while archive cleanup stopped runtimes: ${snapshot.task.id}.`);
+        }
+    }
+    #assertTaskArchiveLifecycle(expected) {
+        const current = this.store.getTask(expected.id);
+        if (current === null || !isDeepStrictEqual(current, expected)) {
+            throw new WorkspaceCleanupBlockedError("task-changed", `task:${expected.id}`, true, `Task changed during archive cleanup: ${expected.id}.`);
+        }
+    }
+    #assertWorkItemRuntimeQuiescent(item) {
+        const activeRun = this.store.listAgentRuns(item.taskId)
+            .find((run) => run.status === "active" && run.workItemId === item.id);
+        if (activeRun !== undefined) {
+            throw new WorkspaceCleanupBlockedError("active-run", `work-item:${item.taskId}/${item.id}`, true, `Work item still has an active Run: ${item.taskId}/${item.id}.`);
+        }
+    }
+    #workItemRoleNames(item) {
+        return [
+            ...(item.assignee === undefined ? [] : [item.assignee]),
+            ...(item.executionGroups.flatMap((group) => group.lanes.map(({ roleName }) => roleName)))
+        ];
+    }
+    #reviewRoundRoleNames(round) {
+        return [
+            round.reviewerRoleName,
+            ...(round.executionGroup?.lanes.map(({ roleName }) => roleName) ?? [])
+        ];
+    }
+    async #stopLiveRoles(taskId, roleNames) {
+        const targets = [...new Set(roleNames)];
+        const getActiveRun = this.store.getActiveAgentRun?.bind(this.store);
+        for (const roleName of targets) {
+            if (getActiveRun !== undefined && getActiveRun(taskId, roleName) !== null) {
+                throw new Error(`Role has an active Run: ${taskId}/${roleName}.`);
+            }
+            const sessions = this.store.getTaskRoleSessionSet(taskId, roleName);
+            if (sessions?.inFlight !== null && sessions?.inFlight !== undefined) {
+                throw new Error(`Role has unsettled Run state: ${taskId}/${roleName}.`);
+            }
+            if (sessions?.pendingTurnCompletion !== null
+                && sessions?.pendingTurnCompletion !== undefined) {
+                throw new Error(`Role has unsettled Run state: ${taskId}/${roleName}.`);
+            }
+            if (this.store.getWorkMailbox !== undefined && hasRuntimeLifecycleWork(this.store.getWorkMailbox(runtimeLifecycleTarget({ scope: "task", taskId, roleName })))) {
+                throw new Error(`Role has unsettled runtime lifecycle state: ${taskId}/${roleName}.`);
+            }
+        }
+        const inspect = this.runtime.inspectTaskRolePanes?.bind(this.runtime);
+        const observedPanes = inspect?.(taskId);
+        const live = targets.filter((roleName) => {
+            const sessions = this.store.getTaskRoleSessionSet(taskId, roleName);
+            const activeSession = sessions === null
+                ? undefined
+                : sessions.activeAgentId === undefined
+                    // Narrow test doubles and restored callers predating activeAgentId
+                    // still conservatively represent any nonterminal record as live.
+                    ? Object.values(sessions.sessions).find(({ status }) => status !== "stopped" && status !== "broken")
+                    : sessions.sessions[sessions.activeAgentId];
+            return observedPanes?.some((pane) => pane.roleName === roleName && !pane.dead) === true
+                || (sessions !== null && activeSession !== undefined
+                    && activeSession.status !== "stopped"
+                    && activeSession.status !== "broken");
+        });
+        if (live.length > 0)
+            await this.runtime.stopTaskRoleSessions(taskId, live);
+        // The aggregate-16 dormant Claude placeholder is the sole exception to
+        // strict workspace-session retirement. The synchronous pane inspection is
+        // performed while holding the Task store transaction so a normal launch
+        // cannot reserve a Run/Session between absence proof and terminalization.
+        if (inspect === undefined || this.store.transaction === undefined)
+            return;
+        this.store.transaction((tx) => {
+            const panes = inspect(taskId);
+            for (const roleName of targets) {
+                if (panes.some((pane) => pane.roleName === roleName && !pane.dead)) {
+                    throw new Error(`Task Role native pane must stop before workspace migration: ${roleName}.`);
+                }
+                if (tx.getActiveAgentRun(taskId, roleName) !== null) {
+                    throw new Error(`Role has an active Run: ${taskId}/${roleName}.`);
+                }
+                if (tx.getWorkMailbox !== undefined && hasRuntimeLifecycleWork(tx.getWorkMailbox(runtimeLifecycleTarget({ scope: "task", taskId, roleName })))) {
+                    throw new Error(`Role has unsettled runtime lifecycle state: ${taskId}/${roleName}.`);
+                }
+                const sessions = tx.getTaskRoleSessionSet(taskId, roleName);
+                if (sessions === null)
+                    continue;
+                const retired = retireConfirmedAbsentInactiveTaskRolePlaceholders(sessions, this.preparer.now());
+                if (retired !== sessions)
+                    tx.saveTaskRoleSessionSet(retired);
+            }
+        });
+    }
+    #workItemIsolationAssignee(item) {
+        const task = this.store.getTask(item.taskId);
+        if (task === null)
+            throw new Error(`Task not found: ${item.taskId}.`);
+        if (task.status !== "active")
+            throw new Error(`Task is not active: ${task.id}.`);
+        if (task.projectBindings.length === 0) {
+            throw new Error(`WorkItem isolation requires a Project-backed Task: ${task.id}.`);
+        }
+        if (item.assignee === "leader") {
+            throw new Error("The Leader must remain in the Task main worktree.");
+        }
+        if (isTerminalWorkItem(item)) {
+            throw new Error(`Work item is already terminal: ${item.id}.`);
+        }
+        if (item.assignee !== undefined && this.store.getActiveAgentRun(task.id, item.assignee) !== null) {
+            throw new Error(`Role has an active Run: ${task.id}/${item.assignee}.`);
+        }
+        if (item.assignee !== undefined && this.store.getRole(task.id, item.assignee) === null) {
+            throw new Error(`Role not found: ${task.id}/${item.assignee}.`);
+        }
+        return item.assignee;
+    }
+}
+function sameProjectScope(workspace, taskProjectIds, writeProjectIds) {
+    const actualProjects = workspace.entries.map(({ projectId }) => projectId).sort();
+    const expectedProjects = [...taskProjectIds].sort();
+    const actual = workspace.entries
+        .filter(({ access }) => access === "write")
+        .map(({ projectId }) => projectId)
+        .sort();
+    const expected = [...writeProjectIds].sort();
+    return actualProjects.length === expectedProjects.length
+        && actualProjects.every((projectId, index) => projectId === expectedProjects[index])
+        && actual.length === expected.length
+        && actual.every((projectId, index) => projectId === expected[index]);
+}
+function isTerminalWorkItem(item) {
+    return ["completed", "failed", "retired"].includes(item.status);
+}