@zq-silk/yui 1.0.0 → 1.1.0

package/dist/executor/fileRoleLaunchPlanner.js

@@ -6,7 +6,6 @@ import { fileURLToPath } from "node:url";
 import { isDeepStrictEqual } from "node:util";
 import { runPurposeAdmitsTaskState } from "../agentRun/agentRun.js";
 import { assertExecutionEnvironmentCurrent } from "../runtime/executionEnvironment.js";
-import { taskOwnsManagedWorkspace } from "../task/task.js";
 import { configuredAgentToDefinition, resolveAgentEnvironment } from "../agent/agent.js";
 import { NATIVE_AGENT_ENVIRONMENT_NAMES, nativeAgentEnvironmentNames, operationalAgentEnvironment, selectEnvironment } from "../agent/launchEnvironment.js";
 import { compileRoleSessionContext, roleSessionKind } from "../context/roleSessionContext.js";
@@ -17,7 +16,7 @@ import { managedRuntimeAdmission } from "../runtime/agentDriver.js";
 import { builtinAgentEndpointImplementation, validateAgentEndpointImplementation } from "../runtime/agentEndpointIdentity.js";
 import { builtinAgentDriverRegistry, builtinDriverIdForAdapter } from "../runtime/builtinAgentDrivers.js";
 import { assertProviderConversationReplaceable } from "../runtime/providerRuntimeIdentity.js";
-import { resolveTaskRoleSessionTitle } from "../runtime/sessionTitle.js";
+import { operatorSessionTitle, resolveTaskRoleSessionTitle } from "../runtime/sessionTitle.js";
 import { parseTaskRuntimeIsolationDescriptor, taskRuntimeIsolationEnvironment } from "../runtime/taskRuntimeIsolation.js";
 import { planningRuntimeCwd } from "../storage/homeLayout.js";
 import { resolveAgentAdapter } from "./agentAdapter.js";
@@ -33,6 +32,7 @@ export class FileRoleLaunchPlanner {
     #agentEnvironment;
     #nativeAgentEnvironment;
     #createNativeSessionId;
+    #now;
     #cliPath;
     #inspectWorkspacePhysicalState;
     #entryPoint;
@@ -51,6 +51,7 @@ export class FileRoleLaunchPlanner {
         this.#agentEnvironment = this.#selectConfiguredAgentEnvironment(sourceEnvironment);
         this.#nativeAgentEnvironment = this.#selectConfiguredNativeEnvironment(sourceEnvironment);
         this.#createNativeSessionId = options.createNativeSessionId ?? randomUUID;
+        this.#now = options.now ?? (() => new Date());
         this.#inspectWorkspacePhysicalState = options.inspectWorkspacePhysicalState
             ?? inspectWorkspacePhysicalState;
         this.#cliPath = canonicalPath(options.cliPath
@@ -112,30 +113,14 @@ export class FileRoleLaunchPlanner {
         if (!runPurposeAdmitsTaskState(purpose, task)) {
             throw new Error(`Task execution is not enabled: ${input.taskId}.`);
         }
-        // A launch owns no managed workspace in two cases: a Draft planning
-        // conversation, and a Task activated with an empty environment plan. Both
-        // run with no Project entries, so there is nothing to preflight and no
-        // worktree to wait for. Every other fence — live Session, replaceable
-        // Conversation, configured Agent, Context protocol identity, adopted
-        // execution environment — still applies.
+        // Draft planning has no delivery workspace. Active Tasks always have one.
         const planningDraft = purpose === "planning" && task.status === "draft";
         // A planning cwd is a disposable per-Task runtime resource, not a delivery
         // workspace. Materialize only the exact directory selected at creation.
         if (planningDraft && resolve(role.workspace) === resolve(planningRuntimeCwd(this.home, task.id))) {
             mkdirSync(role.workspace, { recursive: true, mode: 0o700 });
         }
-        const workspaceFree = planningDraft || !taskOwnsManagedWorkspace(task);
-        // An empty resource plan is a legal Task shape, but it does not make a
-        // shared directory a legal cwd. Once such a Task is active it can name the
-        // directory it means through the existing environment plan, so require that
-        // instead of silently running in whatever workspace the Role inherited with
-        // isolation skipped.
-        if (workspaceFree && !planningDraft && role.executionEnvironment === undefined) {
-            throw new Error(`Task ${task.id} owns no workspace and no adopted execution environment, so Role `
-                + `${role.name} has no directory of its own to run in. Request activation with a `
-                + "`scratch` or `local` environment plan, or bind an adopted environment with "
-                + "`environment.bind`, instead of inheriting a shared workspace.");
-        }
+        const workspaceFree = planningDraft;
         const runWorkspace = activeRun?.workspace;
         const main = this.store.getTaskWorkspace(task.id);
         // Quick Win (EXE-04/EXE-08): classify workspace preflight failures so
@@ -259,7 +244,9 @@ export class FileRoleLaunchPlanner {
         if (input.mode === "new" && sessionSet?.providerBinding != null) {
             assertProviderConversationReplaceable(sessionSet.providerBinding);
         }
-        return this.#compile(role, input, { scope: "global" }, undefined, input.mode === "resume" && compatibleExisting ? existing.nativeSessionId : undefined, undefined, effective, { purpose: "execution" });
+        return this.#compile(role, input, { scope: "global" }, input.mode === "new" && role.name === "operator"
+            ? operatorSessionTitle(this.#now(), this.store.getConfig().timeZone)
+            : undefined, input.mode === "resume" && compatibleExisting ? existing.nativeSessionId : undefined, undefined, effective, { purpose: "execution" });
     }
     #compile(role, input, owner, sessionTitle, knownNativeSessionId, workspaceOverride, effective, sessionPolicy) {
         const launchRole = effectiveRoleForLaunch(role, effective);
@@ -389,11 +376,16 @@ export class FileRoleLaunchPlanner {
         const effectiveConfig = withNativeProjectDirectories(roleConfig, effective.executionEnvironment === undefined
             ? nativeAdditionalDirectories(effective.workspace, agentWorkspace)
             : []);
+        const postCreateOperatorTitle = owner.scope === "global"
+            && role.name === "operator"
+            && sessionTitle !== undefined;
         const compileInput = {
             agent,
             config: effectiveConfig,
             workspace: agentWorkspace,
-            ...(sessionTitle === undefined ? {} : { sessionTitle }),
+            ...(sessionTitle === undefined || postCreateOperatorTitle
+                ? {}
+                : { sessionTitle }),
             ...sessionContext
         };
         if (input.mode === "resume"
@@ -685,9 +677,7 @@ export class FileRoleLaunchPlanner {
     }
 }
 export function nativeAgentWorkspace(workspace) {
-    return workspace.entries.length === 1
-        ? workspace.entries[0].path
-        : workspace.root;
+    return workspace.root;
 }
 export function nativeAdditionalDirectories(workspace, agentWorkspace) {
     return [workspace.root, ...workspace.entries.map(({ path }) => path)]

package/dist/message/messageContinuation.js

@@ -56,7 +56,7 @@ export function messageContinuationBlocker(store, message) {
         if (target.reviewRoundId === undefined && !isDeepStrictEqual([...work.writeProjectIds].sort(), [...owner.effective.writeProjectIds].sort()))
             return "assignment-scope-changed";
         if (target.reviewRoundId === undefined && owner.workspace !== undefined) {
-            const workspace = target.roleName === "leader"
+            const workspace = target.roleName === "leader" || task.projectBindings.length === 0
                 ? store.getTaskWorkspace(message.taskId) : store.getWorkItemWorkspace(message.taskId, target.workItemId);
             const identity = (entries) => entries.map((entry) => ({
                 projectId: entry.projectId, path: entry.path, access: entry.access, branch: entry.branch

package/dist/release/releaseHandover.js

@@ -13,11 +13,20 @@
  * the candidate read-only and reports dual-owner; a crashed activator resumes
  * from the recorded phase.
  */
+import { processGenerationIsLive } from "../core/fileLockOwner.js";
 import { RELEASE_HANDOVER_PROMOTION_TIMEOUT_MS } from "../runtime/runtimeDeadlines.js";
-import { acquireHandoverLock, isOwnerLive, newHandoverId, readActiveReleasePointer, readCandidateDiscovery, readHandoverFence, readHandoverReceipt, readRuntimeIdentity, removeCandidateDiscovery, removeHandoverFence, writeActiveReleasePointer, writeHandoverFence, writeHandoverReceipt } from "./runtimeRelease.js";
+import { acquireHandoverLock, isOwnerLive, newHandoverId, readActiveReleasePointer, readCandidateDiscovery, readHandoverFence, readHandoverReceipt, readRuntimeIdentity, removeActiveReleasePointer, removeCandidateDiscovery, removeHandoverFence, writeActiveReleasePointer, writeHandoverFence, writeHandoverReceipt } from "./runtimeRelease.js";
 export const DEFAULT_CANDIDATE_READY_TIMEOUT_MS = 30_000;
 export const DEFAULT_PROMOTION_TIMEOUT_MS = RELEASE_HANDOVER_PROMOTION_TIMEOUT_MS;
 export const DEFAULT_POLL_INTERVAL_MS = 100;
+export class ControllerStartUnconfirmedError extends Error {
+    pid;
+    constructor(pid, message) {
+        super(message);
+        this.pid = pid;
+        this.name = "ControllerStartUnconfirmedError";
+    }
+}
 /**
  * Optional confirmation debounce after the candidate latches `dualOwner:
  * true`. Defaults to 0: the candidate's own exit grace
@@ -147,13 +156,17 @@ async function activateLocked(ports, locked) {
     ports.spawnCandidate(home, releaseDir, handoverId);
     const candidateReady = await waitForCandidateReady(ports, home, manifest, locked.candidateReadyTimeoutMs, locked.pollIntervalMs);
     if (candidateReady === null) {
-        await rollbackHandover(ports, home, fence, "candidate did not become ready");
+        const rollbackError = await rollbackHandover(ports, home, fence);
         return {
             outcome: "aborted",
             phase: "candidate-ready",
-            message: "The new Controller candidate did not become ready in time.",
-            action: "The old Controller has resumed accepting mutations; retry the activation.",
-            recoverable: true
+            message: rollbackError === null
+                ? "The new Controller candidate did not become ready in time."
+                : `The new Controller candidate did not become ready; rollback is unconfirmed: ${rollbackError}`,
+            action: rollbackError === null
+                ? "The old Controller has resumed accepting mutations; retry the activation."
+                : "Preserve the handover fence and candidate discovery; inspect process owners before retrying.",
+            recoverable: rollbackError === null
         };
     }
     // 6) Switch the active release pointer. This is the atomic commit point:
@@ -221,10 +234,21 @@ async function activateWithoutOldController(ports, home, manifest, releaseDir, r
         await ports.startControllerFromRelease(home, releaseDir);
     }
     catch (error) {
-        // Restore the previous pointer so the launcher keeps resolving the old
-        // release.
+        if (error instanceof ControllerStartUnconfirmedError) {
+            return {
+                outcome: "aborted",
+                phase: "start-controller",
+                message: `New Controller startup is unconfirmed (PID ${error.pid}): ${error.message}`,
+                action: "Preserve the new release pointer and inspect the exact Controller process before retrying.",
+                recoverable: false
+            };
+        }
+        // A pre-spawn failure cannot have started a Controller. Restore the
+        // pointer's previous value, including its absence.
         if (active !== null)
             writeActiveReleasePointer(home, active);
+        else
+            removeActiveReleasePointer(home);
         return {
             outcome: "aborted",
             phase: "start-controller",
@@ -252,7 +276,7 @@ async function readOldController(ports, home) {
         if (typeof identity !== "object"
             || identity === null
             || typeof identity.pid !== "number") {
-            return null;
+            throw new Error("Running Controller returned an invalid identity; handover cannot be fenced.");
         }
         const record = identity;
         if (record.releaseDrifted === true) {
@@ -262,8 +286,9 @@ async function readOldController(ports, home) {
         const startIdentity = typeof record.processStartIdentity === "string"
             ? record.processStartIdentity
             : undefined;
-        if (startIdentity === undefined)
-            return null;
+        if (startIdentity === undefined) {
+            throw new Error("Running Controller did not provide a process-generation identity; handover cannot be fenced.");
+        }
         return Object.freeze({
             pid: record.pid,
             processStartIdentity: startIdentity,
@@ -327,19 +352,29 @@ async function waitForPromotion(ports, home, fence, timeoutMs, pollIntervalMs, d
         await ports.sleep(pollIntervalMs);
     }
 }
-async function rollbackHandover(ports, home, fence, reason) {
+async function rollbackHandover(ports, home, fence) {
     const candidate = readCandidateDiscovery(home);
     if (candidate !== null) {
         try {
-            ports.killOwnedProcess({
-                pid: candidate.pid,
-                processStartIdentity: candidate.processStartIdentity,
-                buildId: "candidate",
-                version: "candidate"
-            });
+            if (processGenerationIsLive(candidate.pid, candidate.processStartIdentity)) {
+                ports.killOwnedProcess({
+                    pid: candidate.pid,
+                    processStartIdentity: candidate.processStartIdentity,
+                    buildId: "candidate",
+                    version: "candidate"
+                });
+                for (let attempt = 0; attempt < 20; attempt += 1) {
+                    if (!processGenerationIsLive(candidate.pid, candidate.processStartIdentity))
+                        break;
+                    await ports.sleep(50);
+                }
+            }
+            if (processGenerationIsLive(candidate.pid, candidate.processStartIdentity)) {
+                return `candidate PID ${candidate.pid} is still live`;
+            }
         }
-        catch {
-            // A dead candidate is the desired end state; ignore kill failures.
+        catch (error) {
+            return `candidate PID ${candidate.pid}: ${messageOf(error)}`;
         }
         removeCandidateDiscovery(home);
     }
@@ -348,8 +383,8 @@ async function rollbackHandover(ports, home, fence, reason) {
             handoverId: fence.handoverId
         });
     }
-    catch {
-        // The old Controller may have exited; the fence phase records the truth.
+    catch (error) {
+        return `old Controller rollback: ${messageOf(error)}`;
     }
     writeHandoverFence(home, Object.freeze({
         ...fence,
@@ -367,7 +402,7 @@ async function rollbackHandover(ports, home, fence, reason) {
         startedAt: fence.createdAt,
         completedAt: new Date().toISOString()
     }));
-    void reason;
+    return null;
 }
 async function recoverInterruptedHandover(ports, home, locked) {
     const fence = readHandoverFence(home);
@@ -433,7 +468,15 @@ async function recoverInterruptedHandover(ports, home, locked) {
         // candidate-ready wait.
         const candidateReady = await waitForCandidateReady(ports, home, locked.manifest, locked.candidateReadyTimeoutMs, locked.pollIntervalMs);
         if (candidateReady === null) {
-            await rollbackHandover(ports, home, fence, "candidate did not become ready");
+            const rollbackError = await rollbackHandover(ports, home, fence);
+            if (rollbackError !== null) {
+                return {
+                    outcome: "aborted", phase: "recovery",
+                    message: `Interrupted handover rollback is unconfirmed: ${rollbackError}`,
+                    action: "Preserve the handover fence and candidate discovery; inspect process owners before retrying.",
+                    recoverable: false
+                };
+            }
             return null;
         }
         const pointer = Object.freeze({
@@ -472,10 +515,19 @@ async function recoverInterruptedHandover(ports, home, locked) {
                 handoverId: fence.handoverId
             });
         }
-        catch {
-            // Old Controller may be unresponsive; the fence phase records the truth.
+        catch (error) {
+            return {
+                outcome: "aborted", phase: "recovery",
+                message: `Old Controller rollback is unconfirmed: ${messageOf(error)}`,
+                action: "Preserve the handover fence; inspect the old Controller before retrying.",
+                recoverable: false
+            };
         }
     }
+    // The exact candidate generation is gone; only now can its stale
+    // discovery be removed during interrupted-handover recovery.
+    if (readCandidateDiscovery(home) !== null)
+        removeCandidateDiscovery(home);
     removeHandoverFence(home);
     return null;
 }

package/dist/release/runtimeRelease.js

@@ -18,8 +18,7 @@ import { createHash, randomBytes, randomUUID } from "node:crypto";
 import { isStorageVersion, compareStorageVersions } from "../storage/storageVersions.js";
 import { existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, readlinkSync, rmSync, writeFileSync } from "node:fs";
 import { dirname, join, resolve } from "node:path";
-import { readLinuxProcessStartIdentity } from "../controller/domainIdentity.js";
-import { processGenerationIsLive } from "../core/fileLockOwner.js";
+import { currentProcessStartIdentity, processGenerationIsLive } from "../core/fileLockOwner.js";
 import { writeTextFileAtomically } from "../storage/durableFile.js";
 export const RELEASES_DIRECTORY = "runtime/releases";
 export const ACTIVE_RELEASE_POINTER_PATH = "runtime/active-release.json";
@@ -132,6 +131,10 @@ export function writeActiveReleasePointer(home, pointer) {
     validatePointer(pointer);
     writeTextFileAtomically(join(resolve(home), ACTIVE_RELEASE_POINTER_PATH), `${JSON.stringify(pointer, null, 2)}\n`);
 }
+/** Restore the absence of a pointer after a failed first activation. */
+export function removeActiveReleasePointer(home) {
+    rmSync(join(resolve(home), ACTIVE_RELEASE_POINTER_PATH), { force: true });
+}
 /**
  * Resolves the Home's active release. Returns null when no pointer exists
  * (no immutable release selected). Fails closed when the pointer names a release that is
@@ -227,7 +230,7 @@ export function writeHandoverReceipt(home, receipt) {
 }
 /** True when the exact process (PID + start identity) is still alive. */
 export function isOwnerLive(owner) {
-    return readLinuxProcessStartIdentity(owner.pid) === owner.processStartIdentity;
+    return processGenerationIsLive(owner.pid, owner.processStartIdentity);
 }
 export function readCandidateDiscovery(home) {
     const candidatePath = join(resolve(home), CANDIDATE_DISCOVERY_PATH);
@@ -292,10 +295,7 @@ export function isForeignHandoverLockHeld(home, allowedOwnerPid = process.pid) {
 export function acquireHandoverLock(home) {
     const lockPath = join(resolve(home), "runtime", "handover.lock");
     mkdirSync(dirname(lockPath), { recursive: true, mode: 0o700 });
-    const startIdentity = readLinuxProcessStartIdentity(process.pid);
-    if (startIdentity === undefined) {
-        throw new Error(`Cannot read Linux process start identity for activator PID ${process.pid}.`);
-    }
+    const startIdentity = currentProcessStartIdentity();
     const owner = Object.freeze({
         pid: process.pid,
         processStartIdentity: startIdentity,

package/dist/repository/gitWorkspace.js

@@ -821,7 +821,7 @@ export class NodeGitWorkspace {
         const state = await this.inspectWorktree(input);
         if (state === "dirty")
             return state;
-        const container = resolve(input.container);
+        const container = await canonicalContainer(input.container, false);
         const branch = worktreeIdentity(input.taskSegment, input.roleName).branch;
         const path = managedPath(container, input.directory);
         const project = await this.inspect(input.repositoryPath);
@@ -970,7 +970,7 @@ export class NodeGitWorkspace {
         return "removed";
     }
     async inspectWorktree(input) {
-        const container = resolve(input.container);
+        const container = await canonicalContainer(input.container, false);
         const path = managedPath(container, input.directory);
         const kind = await pathKind(path);
         const branch = input.expectedBranch ?? worktreeIdentity(input.taskSegment, input.roleName).branch;
@@ -1000,7 +1000,7 @@ export class NodeGitWorkspace {
         });
     }
     async #removeManagedWorktree(input) {
-        const container = resolve(input.container);
+        const container = await canonicalContainer(input.container, false);
         const path = managedPath(container, input.identity.directory);
         const kind = await pathKind(path);
         if (kind === "symlink")
@@ -1136,7 +1136,7 @@ async function assertOwnedWorktree(project, container, path) {
     }
 }
 async function inspectExactRecordedWorktree(input) {
-    const container = resolve(input.container);
+    const container = await canonicalContainer(input.container, false);
     const expectedBranch = worktreeIdentity(input.taskSegment, input.roleName).branch;
     const expectedPath = managedPath(container, input.directory);
     if (resolve(input.path) !== expectedPath || input.branch !== expectedBranch) {
@@ -1231,10 +1231,11 @@ async function canonicalContainer(path, create) {
     const lexical = resolve(path);
     if (create)
         await mkdir(lexical, { recursive: true, mode: 0o700 });
-    const canonical = await canonicalDirectory(lexical, "Worktree container");
-    if (canonical !== lexical)
-        throw new Error("Worktree container resolves through a symbolic link.");
-    return canonical;
+    // Resolve once into the physical path used for every containment and
+    // identity comparison below. System-owned prefix symlinks are normal on
+    // macOS (e.g. /var -> /private/var); symlinks at or below the container
+    // stay rejected by the managed-path lstat checks.
+    return canonicalDirectory(lexical, "Worktree container");
 }
 async function canonicalDirectory(path, label) {
     const value = requireText(path, label);

package/dist/repository/taskWorkspacePreparer.js

@@ -15,7 +15,7 @@ import { taskRoleRuntimeIdentity } from "../runtime/managedCaller.js";
 import { managedTaskRoot } from "../storage/homeLayout.js";
 import { StorageConflictError } from "../storage/taskStore.js";
 import { validateDraftTaskForActivation } from "../task/draftPlan.js";
-import { activateTask, bindTaskProjectCommits, bindTaskWorkspaceIdentity, synchronizeTaskProjectCommits, taskOwnsManagedWorkspace } from "../task/task.js";
+import { activateTask, bindTaskProjectCommits, bindTaskWorkspaceIdentity, synchronizeTaskProjectCommits } from "../task/task.js";
 import { admitStoredTaskActivation, adoptTaskActivationResources, recordAdoptedTaskActivation, recordFailedTaskActivation } from "../task/taskActivationService.js";
 import { taskLocalActor } from "../task/taskAuthority.js";
 import { createCandidateGitSnapshot, createDirectTaskMainSnapshot, recordWorkItemWorkspaceDisposition, workItemExecutionGroupById } from "../workItem/workItem.js";
@@ -140,11 +140,9 @@ export class FileTaskWorkspacePreparer {
                 const actor = task.activationRequest?.operation.actorId === `task:${task.id}/role:leader`
                     ? "leader" : caller;
                 if (task.status === "active") {
-                    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}.`);
-                        }
+                    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,
@@ -210,9 +208,7 @@ export class FileTaskWorkspacePreparer {
             // Acquire before resource adoption: a timed-out/cancelled waiter must
             // not leave an adopted environment to be repeated on the next attempt.
             const adopted = await this.#adoptActivationEnvironment(current);
-            return adopted.workspaceFree
-                ? this.#activateWorkspaceFreeTask(current.id, adopted, actor)
-                : await this.#prepareTaskWorkspaceLocked(current.id, true, adopted, actor);
+            return await this.#prepareTaskWorkspaceLocked(current.id, true, adopted, actor);
         }
         finally {
             release();
@@ -222,10 +218,6 @@ export class FileTaskWorkspacePreparer {
      * Prepares and adopts the resource configuration an explicit activation
      * request named, before any status change.
      *
-     * 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.
@@ -241,8 +233,6 @@ export class FileTaskWorkspacePreparer {
         // 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.
@@ -254,47 +244,6 @@ export class FileTaskWorkspacePreparer {
                 : { 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.
@@ -406,7 +355,7 @@ export class FileTaskWorkspacePreparer {
     }
     async #prepareTaskWorkspaceLocked(taskId, activate, 
     /** Environment and request identity the activation adopted, when one exists. */
-    activationEnvironment = { workspaceFree: false }, actor = "user") {
+    activationEnvironment = {}, actor = "user") {
         const task = requireTask(this.store, taskId);
         if (task.executionGate.state !== "enabled") {
             throw new Error(`Task execution is not enabled: ${task.id}.`);
@@ -695,6 +644,9 @@ export class FileTaskWorkspacePreparer {
                     throw new StorageConflictError(`Task workspace changed while preparing its workspace: ${task.id}.`);
                 }
                 const timestamp = this.now();
+                const mainWorkspaceChanged = current !== null
+                    && (current.root !== workspace.root
+                        || !isDeepStrictEqual(current.entries.map(({ projectId, directory, access, path, branch }) => ({ projectId, directory, access, path, branch })), workspace.entries.map(({ projectId, directory, access, path, branch }) => ({ projectId, directory, access, path, branch }))));
                 let persistedTask = latest;
                 if (activate) {
                     // Activation moves the Leader out of the Draft planning cwd, so its
@@ -784,6 +736,12 @@ export class FileTaskWorkspacePreparer {
                         }
                         tx.saveRole(task.id, updateRole(role, { workspace: target }, timestamp));
                     }
+                    else if (target === root && mainWorkspaceChanged) {
+                        // A newly bound Project changes the native directory grants even
+                        // though the Task cwd stays at the same root. Do not resume a
+                        // Session frozen before that Project was present.
+                        retireWorkspaceBoundSession(tx, task.id, role.name, timestamp);
+                    }
                 }
                 if (activate)
                     recordTaskActivation(tx, latest, persistedTask, timestamp, actor);

package/dist/resources/liveReferences.js

@@ -5,11 +5,12 @@
  * consumes another Issue's completion flag. Any source that cannot be read
  * fails closed: the resource is treated as referenced and retained.
  */
-import { execFile } from "node:child_process";
+import { execFile, execFileSync } from "node:child_process";
 import { createHash } from "node:crypto";
 import { existsSync, readFileSync, readdirSync, readlinkSync } from "node:fs";
 import { join, resolve } from "node:path";
 import { promisify } from "node:util";
+import { processOwnerIsLive } from "../core/fileLockOwner.js";
 import { readRuntimeIdentity, releasesDirectory, resolveActiveRelease } from "../release/runtimeRelease.js";
 import { isControllerSocketPathForHome } from "../core/controllerEndpoint.js";
 import { parseControllerDiscovery } from "../core/protocol.js";
@@ -172,8 +173,10 @@ function readRuntimeIdentityClaims(home) {
         if (!isProcessAlive(identity.pid)) {
             return Object.freeze({ claims: Object.freeze([]), diagnostics: Object.freeze([]) });
         }
-        const currentIdentity = readLinuxProcessStartIdentity(identity.pid);
-        if (currentIdentity === undefined || currentIdentity !== identity.processStartIdentity) {
+        const sameGeneration = process.platform === "linux"
+            ? readLinuxProcessStartIdentity(identity.pid) === identity.processStartIdentity
+            : processOwnerIsLive(identity.pid, identity.processStartIdentity);
+        if (!sameGeneration) {
             return Object.freeze({
                 claims: Object.freeze([]),
                 diagnostics: Object.freeze([{
@@ -242,8 +245,10 @@ export function readSessionOwnerClaims(records) {
             // The normal reconciliation owner releases dead custody records.
             continue;
         }
-        const currentIdentity = readLinuxProcessStartIdentity(pid);
-        if (currentIdentity === undefined || currentIdentity !== startIdentity) {
+        const sameGeneration = process.platform === "linux"
+            ? readLinuxProcessStartIdentity(pid) === startIdentity
+            : processOwnerIsLive(pid, startIdentity);
+        if (!sameGeneration) {
             diagnostics.push({
                 source: "controller",
                 severity: "error",
@@ -270,6 +275,8 @@ export function readSessionOwnerClaims(records) {
  * scan fails closed: every candidate path receives a protective ref.
  */
 export function scanProcessPathRefs(paths) {
+    if (process.platform === "darwin")
+        return scanDarwinProcessPathRefs(paths);
     const refs = new Map();
     const diagnostics = [];
     const add = (path, token) => {
@@ -335,6 +342,54 @@ export function scanProcessPathRefs(paths) {
     }
     return freezeResult(refs, diagnostics);
 }
+/** lsof supplies the same-user cwd and open-file observations on macOS. */
+function scanDarwinProcessPathRefs(paths) {
+    const refs = new Map();
+    try {
+        const uid = typeof process.getuid === "function" ? process.getuid() : 0;
+        const output = execFileSync("/usr/sbin/lsof", [
+            "-nP", "-w", "-F0pfn", "-u", String(uid)
+        ], { encoding: "utf8", timeout: 10_000, maxBuffer: 16 * 1024 * 1024 });
+        if (output.includes("\ufffd"))
+            throw new Error("lsof returned an undecodable path.");
+        let pid = "";
+        let descriptor = "";
+        let sawProcess = false;
+        for (const raw of output.split("\0")) {
+            const field = raw.replace(/^\n+/u, "");
+            if (field.startsWith("p") && /^[1-9][0-9]*$/u.test(field.slice(1))) {
+                pid = field.slice(1);
+                descriptor = "";
+                sawProcess = true;
+            }
+            else if (field.startsWith("f")) {
+                descriptor = field.slice(1);
+            }
+            else if (field.startsWith("n") && pid !== "" && field[1] === "/") {
+                const observed = field.slice(1);
+                for (const path of paths) {
+                    if (!isPathWithin(observed, path))
+                        continue;
+                    const tokens = refs.get(path) ?? new Set();
+                    tokens.add(`lsof:${descriptor}:${pid}`);
+                    refs.set(path, tokens);
+                }
+            }
+        }
+        if (!sawProcess)
+            throw new Error("lsof did not return a process inventory.");
+        return freezeResult(refs, []);
+    }
+    catch (error) {
+        const detail = error instanceof Error ? error.message : String(error);
+        const diagnostics = [{
+                source: "proc", severity: "error", message: `macOS process path scan failed: ${detail}`
+            }];
+        for (const path of paths)
+            refs.set(path, new Set(["lsof:unverified"]));
+        return freezeResult(refs, diagnostics);
+    }
+}
 function freezeResult(refs, diagnostics) {
     const frozen = new Map();
     for (const [path, tokens] of refs)
@@ -435,8 +490,10 @@ export function readControllerDiscovery(home) {
     }
     // PID is alive. When a start identity is recorded, verify it to guard
     // against PID reuse.
-    const currentIdentity = readLinuxProcessStartIdentity(record.pid);
-    if (currentIdentity === undefined || currentIdentity !== record.processStartIdentity) {
+    const sameGeneration = process.platform === "linux"
+        ? readLinuxProcessStartIdentity(record.pid) === record.processStartIdentity
+        : processOwnerIsLive(record.pid, record.processStartIdentity);
+    if (!sameGeneration) {
         return Object.freeze({
             protects: false,
             token: "",