@zq-silk/yui 0.15.7 → 0.15.8

package/dist/repository/taskWorkspacePreparer.js

@@ -1,17 +1,21 @@
 import { lstat, mkdir, readlink, readdir, rm, rmdir, symlink, unlink } from "node:fs/promises";
 import { isAbsolute, join, relative, resolve } from "node:path";
 import { isDeepStrictEqual } from "node:util";
-import { retireTaskRoleSessionsForWorkspace } from "../executor/agentExecutor.js";
+import { retireTaskRoleSessionsForWorkspace, updateRoleAgentSessionStatus } from "../executor/agentExecutor.js";
 import { formatWorkspacePreflightError } from "../executor/workspacePreflightClassification.js";
 import { updateRole } from "../role/role.js";
-import { hasRuntimeCleanupObligation, isRuntimeLaunchReservation, runtimeLifecycleTarget } from "../runtime/lifecycleReservation.js";
+import { taskRoleRuntimeIdentity } from "../runtime/managedCaller.js";
+import { hasRuntimeCleanupObligation, runtimeLifecycleTarget, RUNTIME_HOST_DETACH_REQUIRED_REASON } from "../runtime/lifecycleReservation.js";
+import { taskLocalActor } from "../commands/taskActor.js";
 import { attachReviewRoundWorkspace, recordReviewWorkspaceDisposition } from "../review/reviewRound.js";
 import { StorageConflictError } from "../storage/taskStore.js";
-import { activateTask, bindTaskProjectCommits, bindTaskWorkspaceIdentity, synchronizeTaskProjectCommits } from "../task/task.js";
+import { activateTask, bindTaskProjectCommits, bindTaskWorkspaceIdentity, synchronizeTaskProjectCommits, taskOwnsManagedWorkspace } from "../task/task.js";
+import { admitStoredTaskActivation, adoptTaskActivationResources, recordFailedTaskActivation, recordAdoptedTaskActivation } from "../task/taskActivationService.js";
 import { validateDraftTaskForActivation } from "../task/draftPlan.js";
+import { createProjectResources } from "../resources/projectResourceService.js";
 import { createTaskEvent } from "../event/taskEvent.js";
 import { enqueueWork } from "../coordination/workMailboxQueue.js";
-import { createCandidateGitSnapshot, createDirectTaskMainSnapshot, workItemExecutionGroupById, currentWorkItemExecutionGroup, recordWorkItemWorkspaceDisposition } from "../workItem/workItem.js";
+import { createCandidateGitSnapshot, createDirectTaskMainSnapshot, workItemExecutionGroupById, recordWorkItemWorkspaceDisposition } from "../workItem/workItem.js";
 import { createManagedWorkspace, isTaskOwnedWorkspace, managedWorkspaceKey, managedWorktreeName, sameManagedWorkspaceIdentity } from "../worktree/managedWorkspace.js";
 import { NodeGitWorkspace, worktreeIdentity } from "./gitWorkspace.js";
 import { acquireProjectMaintenanceLocks } from "./projectMaintenanceLock.js";
@@ -103,15 +107,27 @@ export class FileTaskWorkspacePreparer {
      * transaction that moves the Task from Draft to active. A Draft never owns a
      * durable writable workspace before this boundary, and any failed attempt
      * discards its unadopted refs/worktrees.
+     *
+     * An explicit activation request drives the resource configuration. Its
+     * environment is prepared and adopted before this boundary, and the request
+     * is marked adopted inside the same transaction as the status change, so a
+     * later launch failure can never present itself as "activation never
+     * happened".
      */
-    async activateTaskWorkspace(taskId) {
+    async activateTaskWorkspace(taskId, environment = {}) {
         for (let attempt = 0;; attempt += 1) {
+            let attemptedRequest;
             try {
                 const task = requireTask(this.store, taskId);
+                const caller = taskLocalActor(this.store, environment, task.id);
+                const actor = task.activationRequest?.operation.actorId === `task:${task.id}/role:leader`
+                    ? "leader" : caller;
                 if (task.status === "active") {
-                    const workspace = this.store.getTaskWorkspace(task.id);
-                    if (!isTaskOwnedWorkspace(workspace, task.id, task.cwd, task.projectBindings.map(({ projectId, directory }) => ({ projectId, directory })))) {
-                        throw new Error(`Active Task workspace adoption is invalid: ${task.id}.`);
+                    if (taskOwnsManagedWorkspace(task)) {
+                        const workspace = this.store.getTaskWorkspace(task.id);
+                        if (!isTaskOwnedWorkspace(workspace, task.id, task.cwd, task.projectBindings.map(({ projectId, directory }) => ({ projectId, directory })))) {
+                            throw new Error(`Active Task workspace adoption is invalid: ${task.id}.`);
+                        }
                     }
                     return {
                         task,
@@ -121,24 +137,186 @@ export class FileTaskWorkspacePreparer {
                         changed: false
                     };
                 }
-                validateDraftTaskForActivation(this.store, task);
-                const { release, current } = this.#acquireTaskProjectMaintenanceLocks(task);
-                try {
-                    return await this.#prepareTaskWorkspaceLocked(current.id, true);
-                }
-                finally {
-                    release();
+                const provider = this.store.getTaskRoleSessionSet(task.id, LEADER_ROLE)?.providerBinding;
+                if (provider?.run != null
+                    && ["submitting", "accepted", "delivery-unknown"].includes(provider.run.status)) {
+                    throw new Error("Planning native input is unsettled; preserve activation intent and retry after its exact terminal.");
                 }
+                const admission = admitStoredTaskActivation(this.store, task.id);
+                if (admission.disposition === "ready")
+                    attemptedRequest = admission.request;
+                validateDraftTaskForActivation(this.store, task);
+                const adopted = await this.#adoptActivationEnvironment(task);
+                return adopted.workspaceFree
+                    ? this.#activateWorkspaceFreeTask(task.id, adopted, actor)
+                    : await this.#prepareActivatedTaskWorkspace(task, adopted, actor);
             }
             catch (error) {
                 if (error instanceof StorageConflictError
                     && attempt < TASK_WORKSPACE_PREPARE_MAX_CONFLICT_RETRIES) {
                     continue;
                 }
+                if (attemptedRequest !== undefined) {
+                    const outcome = error instanceof Error ? error.message : String(error);
+                    const current = this.store.getTask(taskId)?.activationRequest;
+                    if (current?.disposition !== "failed" || current.outcome !== outcome) {
+                        recordFailedTaskActivation(this.store, taskId, attemptedRequest, outcome, {}, this.now());
+                    }
+                }
                 throw error;
             }
         }
     }
+    /** Prepares the managed workspace of a Task being activated, under its fences. */
+    async #prepareActivatedTaskWorkspace(task, environment, actor) {
+        const { release, current } = this.#acquireTaskProjectMaintenanceLocks(task);
+        try {
+            return await this.#prepareTaskWorkspaceLocked(current.id, true, environment, actor);
+        }
+        finally {
+            release();
+        }
+    }
+    /**
+     * Prepares and adopts the resource configuration an explicit activation
+     * request named, before any status change.
+     *
+     * A Task with no request keeps the historical behavior: its managed workspace
+     * is the whole environment. A request whose plan is empty and whose Task
+     * binds no Project owns nothing physical, and is reported as workspace-free
+     * so activation creates no directory at all.
+     *
+     * The exact request that was adopted travels with the result, so the later
+     * status transaction can prove it is completing that request rather than
+     * whichever one occupies the slot by then.
+     */
+    async #adoptActivationEnvironment(task) {
+        const admission = admitStoredTaskActivation(this.store, task.id);
+        if (admission.disposition === "absent")
+            return { workspaceFree: false };
+        if (admission.disposition !== "ready") {
+            throw new Error(`Task activation is not adoptable: ${task.id}/${admission.disposition}`
+                + (admission.disposition === "unavailable" ? ` (${admission.reason})` : "")
+                + ".");
+        }
+        // Resource adoption owns its own grant, directory-identity and conflict
+        // rechecks. A failure here leaves the Task a continuable Draft.
+        const adopted = adoptTaskActivationResources(this.store, task.id, this.now);
+        return {
+            workspaceFree: admission.plan.kind === "empty"
+                && task.projectBindings.length === 0,
+            // The request whose resources were actually adopted, re-checked at the
+            // status transaction: a cancel or replacement landing during workspace
+            // preparation must fail rather than silently swap requests.
+            request: adopted.request,
+            // The exact preparation this request consumed, so the adopted record
+            // names the environment it adopted rather than the latest one present.
+            ...(adopted.preparation === undefined
+                ? {}
+                : { preparationId: adopted.preparation.id })
+        };
+    }
+    /**
+     * Moves a Task that owns nothing physical from Draft to active.
+     *
+     * An empty environment plan with no bound Project is a legal Task shape, so
+     * no workspace view, worktree or cwd is created to satisfy the framework's
+     * own model. The status change and the adopted request commit together.
+     */
+    #activateWorkspaceFreeTask(taskId, environment, actor) {
+        const task = this.store.transaction((tx) => {
+            const latest = requireTask(tx, taskId);
+            if (latest.status !== "draft") {
+                throw new Error(`Task changed while activating it: ${taskId}/${latest.status}.`);
+            }
+            if (latest.projectBindings.length !== 0
+                || latest.cwd !== undefined
+                || latest.workspaceIdentity !== undefined
+                || tx.getTaskWorkspace(taskId) !== null) {
+                throw new Error(`Task acquired workspace state while activating it: ${taskId}.`);
+            }
+            validateDraftTaskForActivation(tx, latest);
+            const timestamp = this.now();
+            // Bind before the handover below: the desired environment must be the
+            // adopted one before the obligation that ends the old physical Host
+            // exists.
+            if (environment.preparationId !== undefined) {
+                this.#bindAdoptedActivationEnvironment(tx, taskId, environment.preparationId);
+            }
+            // The physical launch is unchanged, but "unchanged" is not "compatible":
+            // the Draft's planning Session runs in the Role's inherited workspace,
+            // which is exactly the shared cwd an active Task may not execute in. Hand
+            // the conversation over instead of asserting continuity, so the next
+            // launch is re-planned under the execution rules and must name a real
+            // environment. Its plan and grants are re-proven there, not assumed here.
+            handOverPlanningSession(tx, taskId, timestamp);
+            const activated = this.#recordAdoptedActivation(tx, activateTask(latest, timestamp), environment, timestamp);
+            tx.saveTask(activated);
+            recordTaskActivation(tx, latest, activated, timestamp, actor);
+            return activated;
+        });
+        return { task, taskId, status: "ready", changed: true };
+    }
+    /**
+     * Marks the Task's activation request adopted, inside the caller's activation
+     * transaction. Returns the Task unchanged when no explicit request exists.
+     *
+     * The adopted environment and the request identity travel together, so the
+     * record can never name a preparation that a different request produced.
+     */
+    #recordAdoptedActivation(store, task, environment, now) {
+        if (task.activationRequest === undefined)
+            return task;
+        // Re-prove the adopted environment inside the status transaction. Between
+        // resource adoption and here a worktree was prepared, which takes real time:
+        // a grant may have been revoked or bounded away, or the directory may no
+        // longer be the Resource it was adopted as. `resolveExecutionEnvironment` is
+        // the same check every launch performs, including the per-resourceRef grant
+        // recheck against the reservation adoption charged, so a Task can never go
+        // active claiming an environment its authority no longer covers.
+        if (environment.preparationId !== undefined) {
+            createProjectResources(store, this.now)
+                .resolveExecutionEnvironment(task.id, environment.preparationId);
+        }
+        return recordAdoptedTaskActivation(store, task, {
+            ...(environment.preparationId === undefined
+                ? {}
+                : { preparationId: environment.preparationId }),
+            ...(environment.request === undefined ? {} : { expected: environment.request })
+        }, now);
+    }
+    /**
+     * Selects the adopted environment for every Role of a Task, so
+     * `preparationId` is the Role's actual `executionEnvironment` rather than a
+     * record no launch ever reads.
+     *
+     * This is the existing public `bindEnvironment` path, so the atomic Role
+     * update, its event and its mailbox notification are the ones task-21
+     * established — the adopted directory, its ownership, its access and its
+     * per-resource grant reservation are rechecked there and shown truthfully at
+     * launch.
+     *
+     * Runs inside the caller's activation transaction (the Store is re-entrant),
+     * and specifically *before* the planning-Session handover queues the Host
+     * detach. That order is required in both directions: the desired
+     * configuration must change before the obligation that ends the old physical
+     * Host exists, so runtime cleanup never acts on a launch configuration the
+     * Task has already replaced — which is exactly what the runtime-lifecycle
+     * guard refuses when the two are inverted. Committing with the status change
+     * also means a Task can never be observed active holding an adopted
+     * preparation that no Role executes in.
+     */
+    #bindAdoptedActivationEnvironment(store, taskId, preparationId) {
+        const resources = createProjectResources(store, this.now);
+        for (const role of store.listRoles(taskId)) {
+            if (role.executionEnvironment?.preparationId === preparationId)
+                continue;
+            resources.bindEnvironment(taskId, role.name, preparationId, {
+                source: "task.activation-adopted",
+                preparationId
+            });
+        }
+    }
     /**
      * Acquire the per-Project maintenance fences for every Project bound to a
      * Task, then re-read the Task under those fences and prove its binding set
@@ -181,7 +359,9 @@ export class FileTaskWorkspacePreparer {
     acquireTaskProjectMaintenanceLocks(taskId) {
         return this.#acquireTaskProjectMaintenanceLocks(requireTask(this.store, taskId));
     }
-    async #prepareTaskWorkspaceLocked(taskId, activate) {
+    async #prepareTaskWorkspaceLocked(taskId, activate, 
+    /** Environment and request identity the activation adopted, when one exists. */
+    activationEnvironment = { workspaceFree: false }, actor = "user") {
         const task = requireTask(this.store, taskId);
         if (activate && task.status !== "draft") {
             throw new Error(`Only a Draft Task can atomically adopt a workspace: ${task.id}/${task.status}.`);
@@ -194,6 +374,20 @@ export class FileTaskWorkspacePreparer {
         }
         if (activate)
             validateDraftTaskForActivation(this.store, task);
+        if (activate) {
+            const planning = planningLeaderSession(this.store, task.id);
+            if (planning !== undefined) {
+                const target = resolve(this.#taskWorkspaceRoot(task.id));
+                const scratch = resolve(planning.effective.workspace.root);
+                const within = (parent, child) => {
+                    const path = relative(parent, child);
+                    return path === "" || (!path.startsWith("..") && !isAbsolute(path));
+                };
+                if (within(target, scratch) || within(scratch, target)) {
+                    throw new Error("Planning and delivery workspaces overlap; preserve the planning Session and select an isolated delivery workspace.");
+                }
+            }
+        }
         const existing = this.store.getTaskWorkspace(task.id);
         if (activate && (task.workspaceIdentity !== undefined
             || task.cwd !== undefined
@@ -240,23 +434,35 @@ export class FileTaskWorkspacePreparer {
                         throw new Error(`Gitless Task workspace changed during preparation: ${task.id}.`);
                     }
                     const timestamp = this.now();
+                    // Activation moves the Leader out of the Draft planning cwd, so its
+                    // planning Session cannot continue. Hand it over explicitly before
+                    // the migration below, which refuses to retire a live Session. The
+                    // adopted environment is bound first, so the desired configuration is
+                    // already correct when the Host detach is queued.
+                    if (activate && activationEnvironment.preparationId !== undefined) {
+                        this.#bindAdoptedActivationEnvironment(tx, task.id, activationEnvironment.preparationId);
+                    }
+                    if (activate)
+                        handOverPlanningSession(tx, task.id, timestamp);
                     let next = latest.cwd === root
                         ? latest
                         : { ...latest, cwd: root, updatedAt: timestamp.toISOString() };
                     if (activate)
-                        next = activateTask(next, timestamp);
+                        next = this.#recordAdoptedActivation(tx, activateTask(next, timestamp), activationEnvironment, timestamp);
                     if (!isDeepStrictEqual(next, latest))
                         tx.saveTask(next);
                     if (current === null)
                         tx.saveManagedWorkspace(workspace);
                     for (const role of tx.listRoles(task.id)) {
+                        if (activate && role.name === "leader" && planningLeaderSession(tx, task.id) !== undefined)
+                            continue;
                         if (role.workspace !== root) {
                             retireWorkspaceBoundSession(tx, task.id, role.name, timestamp);
                             tx.saveRole(task.id, updateRole(role, { workspace: root }, timestamp));
                         }
                     }
                     if (activate)
-                        recordTaskActivation(tx, latest, next, timestamp);
+                        recordTaskActivation(tx, latest, next, timestamp, actor);
                     return next;
                 });
                 return {
@@ -436,6 +642,15 @@ export class FileTaskWorkspacePreparer {
                 const timestamp = this.now();
                 let persistedTask = latest;
                 if (activate) {
+                    // Activation moves the Leader out of the Draft planning cwd, so its
+                    // planning Session cannot continue. Hand it over explicitly before
+                    // the migration below, which refuses to retire a live Session. The
+                    // adopted environment is bound first, so the desired configuration is
+                    // already correct when the Host detach is queued.
+                    if (activationEnvironment.preparationId !== undefined) {
+                        this.#bindAdoptedActivationEnvironment(tx, task.id, activationEnvironment.preparationId);
+                    }
+                    handOverPlanningSession(tx, task.id, timestamp);
                     persistedTask = bindTaskProjectCommits(persistedTask, prepared.map(({ entry }) => ({
                         projectId: entry.projectId,
                         commit: entry.baseCommit
@@ -457,7 +672,7 @@ export class FileTaskWorkspacePreparer {
                     persistedTask = { ...persistedTask, cwd: root, updatedAt: timestamp.toISOString() };
                 }
                 if (activate)
-                    persistedTask = activateTask(persistedTask, timestamp);
+                    persistedTask = this.#recordAdoptedActivation(tx, activateTask(persistedTask, timestamp), activationEnvironment, timestamp);
                 if (!isDeepStrictEqual(persistedTask, latest)) {
                     tx.saveTask(persistedTask);
                 }
@@ -469,32 +684,31 @@ export class FileTaskWorkspacePreparer {
                     recordTaskBaseProvenanceEvents(tx, task.id, adoptedProvenance, timestamp);
                 }
                 for (const role of tx.listRoles(task.id)) {
+                    if (activate && role.name === "leader" && planningLeaderSession(tx, task.id) !== undefined)
+                        continue;
                     // The Role field is only a cwd/snapshot hint. Preserve it while a
                     // durable WorkItem or ReviewRound workspace owns that cwd; Task-main
                     // preparation must not move a Reviewer Session out from under an
                     // active or retained ReviewRound. Other Roles use Task main.
-                    // Prefer the active Turn's exact WorkItem, then a retained direct
+                    // Prefer the active AgentRun's exact WorkItem, then a retained direct
                     // WorkItem owning this cwd, before considering queued assignments.
-                    const activeRoleTurn = tx.getActiveTurn(task.id, role.name);
-                    const activeTurnItem = activeRoleTurn !== null
-                        && activeRoleTurn.purpose === "execution"
-                        && activeRoleTurn.workItemId !== undefined
-                        ? tx.getWorkItem(task.id, activeRoleTurn.workItemId)
+                    const activeRoleRun = tx.getActiveRun(task.id, role.name);
+                    const activeRunItem = activeRoleRun !== null
+                        && activeRoleRun.purpose === "execution"
+                        && activeRoleRun.workItemId !== undefined
+                        ? tx.getWorkItem(task.id, activeRoleRun.workItemId)
                         : null;
-                    // Rejection ends an execution iteration, not its workspace ownership.
-                    // Preserve this direct WorkItem's existing cwd while dispatch prepares
-                    // the Task before atomically reopening the failed WorkItem. Merely
-                    // reading Task context must not migrate its resumable Worker either.
+                    // Semantic acceptance/retirement does not release a workspace.
+                    // Preserve its cwd until explicit cleanup/reassignment removes that
+                    // durable owner; Task-main preparation must not migrate its Session.
                     const retainedItem = tx.listWorkItems(task.id).find((candidate) => (candidate.assignee === role.name
-                        && candidate.status === "failed"
-                        && currentWorkItemExecutionGroup(candidate) === undefined
                         && tx.getWorkItemWorkspace(task.id, candidate.id)?.root === role.workspace));
-                    const assignedItem = activeTurnItem !== null
-                        && activeTurnItem.assignee === role.name
-                        && !["completed", "failed", "retired"].includes(activeTurnItem.status)
-                        ? activeTurnItem
+                    const assignedItem = activeRunItem !== null
+                        && activeRunItem.assignee === role.name
+                        && !["accepted", "retired"].includes(activeRunItem.status)
+                        ? activeRunItem
                         : retainedItem ?? tx.listWorkItems(task.id).find((candidate) => (candidate.assignee === role.name
-                            && !["completed", "failed", "retired"]
+                            && !["accepted", "retired"]
                                 .includes(candidate.status)));
                     const assignedWorkspace = assignedItem === undefined
                         ? null
@@ -517,7 +731,7 @@ export class FileTaskWorkspacePreparer {
                     }
                 }
                 if (activate)
-                    recordTaskActivation(tx, latest, persistedTask, timestamp);
+                    recordTaskActivation(tx, latest, persistedTask, timestamp, actor);
                 return persistedTask;
             });
             return {
@@ -817,14 +1031,14 @@ export class FileTaskWorkspacePreparer {
                         || !isDeepStrictEqual(latestItem.writeProjectIds, item.writeProjectIds)) {
                         throw new Error(`Work item changed while preparing its workspace: ${item.id}.`);
                     }
-                    const activeDevelopTurn = tx.listTurns(lockedTask.id)
+                    const activeDevelopRun = tx.listRuns(lockedTask.id)
                         .find((run) => run.status === "active" && run.workItemId === item.id);
-                    if (activeDevelopTurn !== undefined) {
-                        throw new Error(`Work Item already has an active Develop Turn: ${activeDevelopTurn.id}.`);
+                    if (activeDevelopRun !== undefined) {
+                        throw new Error(`Work Item already has an active Develop AgentRun: ${activeDevelopRun.id}.`);
                     }
                     if (latestItem.assignee !== undefined
-                        && tx.getActiveTurn(lockedTask.id, latestItem.assignee) !== null) {
-                        throw new Error(`Role has an active Turn: ${lockedTask.id}/${latestItem.assignee}.`);
+                        && tx.getActiveRun(lockedTask.id, latestItem.assignee) !== null) {
+                        throw new Error(`Role has an active AgentRun: ${lockedTask.id}/${latestItem.assignee}.`);
                     }
                     const existingWorkspace = tx.getWorkItemWorkspace(lockedTask.id, item.id);
                     if (existingWorkspace !== null && (existingWorkspace.owner.type !== "work-item"
@@ -1431,8 +1645,8 @@ export class FileTaskWorkspacePreparer {
                         || candidateChanged) {
                         throw new ReviewRoundWorkspaceEvidenceError(`ReviewRound changed while preparing its workspace: ${round.id}.`);
                     }
-                    if (tx.getActiveTurn(task.id, reviewer.name) !== null) {
-                        throw new ReviewRoundWorkspaceEvidenceError(`Reviewer Role has an active Turn: ${task.id}/${reviewer.name}.`);
+                    if (tx.getActiveRun(task.id, reviewer.name) !== null) {
+                        throw new ReviewRoundWorkspaceEvidenceError(`Reviewer Role has an active AgentRun: ${task.id}/${reviewer.name}.`);
                     }
                     const currentWorkspace = tx.getReviewRoundWorkspace(task.id, round.id);
                     if (existing !== null
@@ -1497,8 +1711,8 @@ export class FileTaskWorkspacePreparer {
             || previousWorkspace.root !== reviewRoot) {
             throw new ReviewRoundWorkspaceEvidenceError(`Previous Task-final Review workspace cannot be continued: ${previous.id}.`);
         }
-        if (this.store.getActiveTurn(task.id, reviewer.name) !== null) {
-            throw new ReviewRoundWorkspaceEvidenceError(`Reviewer Role has an active Turn: ${task.id}/${reviewer.name}.`);
+        if (this.store.getActiveRun(task.id, reviewer.name) !== null) {
+            throw new ReviewRoundWorkspaceEvidenceError(`Reviewer Role has an active AgentRun: ${task.id}/${reviewer.name}.`);
         }
         const expected = new Map(frozenEntries.map((entry) => [entry.projectId, entry]));
         if (previousWorkspace.entries.length !== expected.size) {
@@ -1565,7 +1779,7 @@ export class FileTaskWorkspacePreparer {
                     || currentRound.workspace !== undefined
                     || !isDeepStrictEqual(currentRound.taskCandidate, round.taskCandidate)
                     || tx.getReviewRoundWorkspace(task.id, round.id) !== null
-                    || tx.getActiveTurn(task.id, reviewer.name) !== null) {
+                    || tx.getActiveRun(task.id, reviewer.name) !== null) {
                     throw new ReviewRoundWorkspaceEvidenceError(`Task-final Review workspace changed before reassignment: ${previous.id}/${round.id}.`);
                 }
                 const latestReviewer = tx.getRole(task.id, reviewer.name);
@@ -1693,7 +1907,7 @@ export class FileTaskWorkspacePreparer {
     async cleanupWorkItemWorkspace(taskId, workItemId, disposition) {
         const item = requireWorkItem(this.store, taskId, workItemId);
         const task = requireTask(this.store, item.taskId);
-        if (!["completed", "failed", "retired"].includes(item.status)) {
+        if (!["accepted", "retired"].includes(item.status)) {
             throw new Error(`Work item must be terminal before cleanup: ${item.id}.`);
         }
         if (item.workspaceDisposition !== undefined && item.workspaceDisposition !== disposition) {
@@ -1985,10 +2199,17 @@ export class FileTaskWorkspacePreparer {
         });
     }
 }
-function recordTaskActivation(store, previous, active, now) {
-    enqueueWork(store, { kind: "role", taskId: active.id, roleName: LEADER_ROLE }, "task-created", now, [{ type: "task", id: active.id }]);
+function recordTaskActivation(store, previous, active, now, actor) {
+    // Activation is the explicit request to enter delivery, not an ordinary
+    // Leader-local edit. Preserve that transition for the replacement Session.
+    enqueueWork(store, { kind: "role", taskId: active.id, roleName: LEADER_ROLE }, "execution-started", now, [{ type: "task", id: active.id }]);
     enqueueWork(store, { kind: "task", taskId: active.id }, "task-activated", now, [{ type: "task", id: active.id }]);
-    store.saveEvent(active.id, createTaskEvent(store.nextEventId(active.id), active.id, "task.activated", { fromStatus: previous.status, status: active.status }, now));
+    store.saveEvent(active.id, createTaskEvent(store.nextEventId(active.id), active.id, "task.activated", { fromStatus: previous.status, status: active.status, by: actor }, now));
+}
+function planningLeaderSession(store, taskId) {
+    const sessions = store.getTaskRoleSessionSet(taskId, "leader");
+    const current = sessions?.sessions[sessions.activeAgentId];
+    return current?.status === "active" && current.effective.executionAuthority === "planning" ? current : undefined;
 }
 function requireTask(store, taskId) {
     const task = store.getTask(taskId);
@@ -1997,7 +2218,7 @@ function requireTask(store, taskId) {
     return task;
 }
 function assertTaskArchiveState(current, expected) {
-    if ((current.status !== "completed" && current.status !== "retired")
+    if ((current.status !== "completed" && current.status !== "cancelled")
         || !isDeepStrictEqual(current, expected)) {
         throw new WorkspaceCleanupBlockedError("task-changed", `task:${expected.id}`, true, `Task changed during archive cleanup: ${expected.id}.`);
     }
@@ -2030,9 +2251,9 @@ function executionLaneLineage(store, task, executionGroupId, executionLaneId, hi
             throw new Error(`ReviewRound not found: ${hint.reviewRoundId}.`);
         return { purpose: "review", reviewRoundId: round.id };
     }
-    // Prefer the active Turn's exact WorkItem for this Lane; fall back to the
-    // first queued WorkItem only when no active Turn owns the Lane.
-    const activeLaneRun = store.listTurns(task.id)
+    // Prefer the active AgentRun's exact WorkItem for this Lane; fall back to the
+    // first queued WorkItem only when no active AgentRun owns the Lane.
+    const activeLaneRun = store.listRuns(task.id)
         .find((run) => run.status === "active"
         && run.purpose === "execution"
         && run.executionGroupId === executionGroupId
@@ -2057,16 +2278,16 @@ function executionLaneLineage(store, task, executionGroupId, executionLaneId, hi
 function assertWorkItemWorkspaceEligible(store, task, item) {
     if (task.status !== "active")
         throw new Error(`Task is not active: ${task.id}.`);
-    if (["completed", "failed", "retired"].includes(item.status)) {
+    if (["accepted", "retired"].includes(item.status)) {
         throw new Error(`Work item is already terminal: ${item.id}.`);
     }
-    const activeDevelopTurn = store.listTurns(task.id)
+    const activeDevelopRun = store.listRuns(task.id)
         .find((run) => run.status === "active" && run.workItemId === item.id);
-    if (activeDevelopTurn !== undefined) {
-        throw new Error(`Work Item already has an active Develop Turn: ${activeDevelopTurn.id}.`);
+    if (activeDevelopRun !== undefined) {
+        throw new Error(`Work Item already has an active Develop AgentRun: ${activeDevelopRun.id}.`);
     }
-    if (item.assignee !== undefined && store.getActiveTurn(task.id, item.assignee) !== null) {
-        throw new Error(`Role has an active Turn: ${task.id}/${item.assignee}.`);
+    if (item.assignee !== undefined && store.getActiveRun(task.id, item.assignee) !== null) {
+        throw new Error(`Role has an active AgentRun: ${task.id}/${item.assignee}.`);
     }
 }
 function assertWorkItemOwnsWorkspace(item, workspace) {
@@ -2086,27 +2307,78 @@ function preserveWorkspaceCreatedAt(workspace, previous) {
         : { ...workspace, createdAt: previous.createdAt };
 }
 function assertWorkspaceSessionsRetirable(store, taskId, roleName, now) {
-    if (store.getActiveTurn(taskId, roleName) !== null) {
-        throw new Error(`Role has an active Turn: ${taskId}/${roleName}.`);
+    if (store.getActiveRun(taskId, roleName) !== null) {
+        throw new Error(`Role has an active AgentRun: ${taskId}/${roleName}.`);
     }
     const sessions = store.getTaskRoleSessionSet(taskId, roleName);
     if (sessions !== null)
         retireTaskRoleSessionsForWorkspace(sessions, now);
 }
 function retireWorkspaceBoundSession(store, taskId, roleName, now) {
-    if (store.getActiveTurn(taskId, roleName) !== null) {
-        throw new Error(`Role has an active Turn: ${taskId}/${roleName}.`);
+    if (store.getActiveRun(taskId, roleName) !== null) {
+        throw new Error(`Role has an active AgentRun: ${taskId}/${roleName}.`);
     }
     const sessions = store.getTaskRoleSessionSet(taskId, roleName);
     if (sessions !== null) {
         store.saveTaskRoleSessionSet(retireTaskRoleSessionsForWorkspace(sessions, now));
     }
 }
+/**
+ * Hands a Draft planning Session over to the activated Task.
+ *
+ * A Leader plans and executes as the same logical Role, so activation never
+ * changes the Leader or Task identity. It can change the *physical* launch
+ * though: adopting a workspace or an execution environment moves the Session's
+ * cwd, and a native conversation is bound to the cwd it started in. Such a
+ * Session cannot continue, and that is not a failure to report — the plan lives
+ * in the Task's own durable facts, so the next Turn takes over from persistent
+ * Context instead of the old terminal or its full tool log.
+ *
+ * Ending the record here is what makes the takeover explicit rather than
+ * silent: the next Leader wake resolves `new`, and the queued cleanup ends the
+ * physical Host that the ended record no longer represents. Without this, a
+ * live planning Session would make workspace migration throw and leave the
+ * Task an un-activatable Draft forever.
+ */
+function handOverPlanningSession(store, taskId, now) {
+    const sessions = store.getTaskRoleSessionSet(taskId, LEADER_ROLE);
+    if (sessions === null)
+        return;
+    const live = Object.values(sessions.sessions).find(({ status }) => status !== "ended");
+    if (live === undefined)
+        return;
+    // A planning Turn that is still running owns this Session. Deferred
+    // activation is adopted only after it ends, so reaching here with an active
+    // Turn means the caller raced it; fail closed rather than cut it off.
+    if (store.getActiveRun(taskId, LEADER_ROLE) !== null) {
+        throw new Error(`Leader has an active AgentRun while activating its Task: ${taskId}/${LEADER_ROLE}.`);
+    }
+    let next = sessions;
+    for (const session of Object.values(sessions.sessions)) {
+        if (session.status === "ended")
+            continue;
+        next = updateRoleAgentSessionStatus(next, session.agentId, "ended", now, "stopped");
+    }
+    store.saveTaskRoleSessionSet(next);
+    // The durable record is ended; the physical Host still exists. Queue the
+    // explicit detach so the runtime lane closes it instead of leaking it.
+    enqueueWork(store, runtimeLifecycleTarget({ scope: "task", taskId, roleName: LEADER_ROLE }), RUNTIME_HOST_DETACH_REQUIRED_REASON, now, [{ type: "task", id: taskId }]);
+    store.saveEvent(taskId, createTaskEvent(store.nextEventId(taskId), taskId, "task.planning-session-handover", {
+        roleName: LEADER_ROLE,
+        agentId: live.agentId,
+        adapterId: live.adapterId,
+        ...(live.nativeSessionId === undefined
+            ? {}
+            : { nativeSessionId: live.nativeSessionId }),
+        reason: "activation-changed-physical-launch",
+        continuity: "persistent-context"
+    }, now));
+}
 function canCorrectActiveWorkItemRoleWorkspaceHint(store, taskId, role, item, workspace) {
     if (role.taskId !== taskId
         || item.taskId !== taskId
         || item.assignee !== role.name
-        || ["completed", "failed", "retired"].includes(item.status)
+        || ["accepted", "retired"].includes(item.status)
         || workspace.owner.type !== "work-item"
         || workspace.owner.taskId !== taskId
         || workspace.owner.workItemId !== item.id)
@@ -2117,14 +2389,15 @@ function canCorrectActiveWorkItemRoleWorkspaceHint(store, taskId, role, item, wo
         .sort();
     if (!isDeepStrictEqual(writableProjects, [...item.writeProjectIds].sort()))
         return false;
-    const run = store.getActiveTurn(taskId, role.name);
+    const run = store.getActiveRun(taskId, role.name);
+    const identity = taskRoleRuntimeIdentity(role, run);
     if (run === null
         || run.status !== "active"
         || run.purpose !== "execution"
         || run.workItemId !== item.id
         || run.workspace === undefined
         || !sameManagedWorkspaceIdentity(run.workspace, workspace)
-        || run.effective.agentId !== role.activeAgentId
+        || run.effective.agentId !== identity.agentId
         || !sameEffectiveWorkspace(run.effective.workspace, workspace))
         return false;
     const sessions = store.getTaskRoleSessionSet(taskId, role.name);
@@ -2133,13 +2406,12 @@ function canCorrectActiveWorkItemRoleWorkspaceHint(store, taskId, role, item, wo
         || sessions.owner.scope !== "task"
         || sessions.owner.taskId !== taskId
         || sessions.owner.roleName !== role.name
-        || sessions.activeAgentId !== role.activeAgentId
+        || sessions.activeAgentId !== identity.agentId
         || session === undefined
-        || session.agentId !== role.activeAgentId
+        || session.agentId !== identity.agentId
         || session.adapterId !== run.effective.adapterId
-        || session.runtimeGenerationId === undefined
         || session.nativeSessionId === undefined
-        || !["ready", "running"].includes(session.status)
+        || session.status !== "active"
         || !isDeepStrictEqual(session.effective, run.effective)
         || !sameEffectiveWorkspace(session.effective.workspace, workspace))
         return false;
@@ -2150,17 +2422,6 @@ function canCorrectActiveWorkItemRoleWorkspaceHint(store, taskId, role, item, wo
     }));
     if (hasRuntimeCleanupObligation(lifecycleMailbox))
         return false;
-    const lifecycle = lifecycleMailbox?.processing;
-    if (lifecycle !== null
-        && lifecycle !== undefined
-        && isRuntimeLaunchReservation(lifecycle)) {
-        const executionRef = lifecycle.executionRef;
-        if (!isRuntimeLaunchReservation(lifecycle, session.runtimeGenerationId)
-            || executionRef?.type !== "turn"
-            || executionRef.taskId !== taskId
-            || executionRef.id !== run.id)
-            return false;
-    }
     return true;
 }
 function sameEffectiveWorkspace(effective, workspace) {