@zq-silk/yui 0.2.0 → 0.4.2

package/dist/controller/clientRuntime.js

@@ -1,13 +1,53 @@
 import { spawn } from "node:child_process";
 import { fileURLToPath } from "node:url";
-import { callController } from "../core/controllerClient.js";
+import { callController, readControllerDiscovery } from "../core/controllerClient.js";
+import { FILE_TASK_CONTROLLER_PROTOCOL_VERSION } from "../core/protocol.js";
+import { AGENT_OPERATIONAL_ENVIRONMENT_NAMES, nativeAgentEnvironmentNames, operationalAgentEnvironment, selectEnvironment, YUI_MANAGED_RUNTIME_ENVIRONMENT_NAMES } from "../agent/launchEnvironment.js";
+import { openCompatibleFileTaskStore } from "../storage/compatibleTaskStore.js";
+import { hasRuntimeLifecycleWork } from "../runtime/lifecycleReservation.js";
+import { assertControllerStatusIdentity } from "../runtime/exactControlPlane.js";
+import { EPHEMERAL_DOMAIN_ENVIRONMENT_NAMES } from "./domainIdentity.js";
+import { YUI_VERSION, yuiVersionIdentity } from "../version.js";
 const STARTUP_TIMEOUT_MS = 5_000;
+// A lifecycle RPC may legitimately occupy the Controller for 30 seconds.
+// Restart must allow that request to drain before deciding shutdown is stuck.
+const SHUTDOWN_TIMEOUT_MS = 45_000;
 const POLL_INTERVAL_MS = 50;
+const LIFECYCLE_REQUEST_TIMEOUT_MS = 30_000;
+const ENVIRONMENT_REFRESH_TIMEOUT_MS = 500;
+const CONFIGURATION_REFRESH_TIMEOUT_MS = 500;
+const CONTROLLER_OPERATIONAL_ENVIRONMENT = [
+    ...AGENT_OPERATIONAL_ENVIRONMENT_NAMES,
+    "YUI_TMUX_BIN",
+    ...EPHEMERAL_DOMAIN_ENVIRONMENT_NAMES
+];
+/**
+ * Direct FileTaskStore writers must not extend state while an older Controller
+ * is still reading the same YUI_HOME.
+ */
+export async function assertFileTaskControllerStorageCompatible(home, options = {}) {
+    const call = options.call ?? callController;
+    let status;
+    try {
+        status = await call(home, "controller.status", {});
+    }
+    catch (error) {
+        if (isDefinitelyNotRunning(error))
+            return;
+        if (isUnavailable(error)) {
+            throw new Error("Controller compatibility could not be verified. Retry or run `yui controller restart`.", { cause: error });
+        }
+        throw error;
+    }
+    assertCompatibleControllerStatus(status);
+}
 /** Starts the per-home FileTask Controller on demand and waits until callable. */
 export async function ensureFileTaskController(home, options = {}) {
     const call = options.call ?? callController;
     try {
-        return await call(home, "controller.status", {});
+        const status = await call(home, "controller.status", {});
+        assertCompatibleControllerStatus(status, options.expectedVersion);
+        return status;
     }
     catch (error) {
         if (!isUnavailable(error))
@@ -16,11 +56,13 @@ export async function ensureFileTaskController(home, options = {}) {
     const timeoutMs = positive(options.startupTimeoutMs, STARTUP_TIMEOUT_MS, "startupTimeoutMs");
     const pollMs = positive(options.pollIntervalMs, POLL_INTERVAL_MS, "pollIntervalMs");
     const spawnController = options.spawnController ?? spawnDetachedFileTaskController;
-    spawnController(home, { ...process.env, ...options.environment, YUI_HOME: home });
+    spawnController(home, controllerSpawnEnvironment(home, options.environment ?? process.env));
     const deadline = Date.now() + timeoutMs;
     for (;;) {
         try {
-            return await call(home, "controller.status", {});
+            const status = await call(home, "controller.status", {});
+            assertCompatibleControllerStatus(status, options.expectedVersion);
+            return status;
         }
         catch (error) {
             if (!isUnavailable(error))
@@ -32,6 +74,79 @@ export async function ensureFileTaskController(home, options = {}) {
         }
     }
 }
+/** Start and await readiness for a captured Controller identity. */
+export async function ensureFileTaskControllerIdentity(home, identity, options = {}) {
+    assertExpectedControllerLaunchIdentity(identity);
+    const status = await ensureFileTaskController(home, {
+        ...options,
+        expectedVersion: identity.version
+    });
+    // A same-version status is not an identity proof: another Controller binary
+    // may own the Home after a restart or a stale discovery race. Authenticate
+    // the socket owner and compare the complete launch vector before reporting
+    // readiness. This post-readiness check deliberately has no retry or spawn
+    // fallback; a mismatch/unavailable/malformed identity is fail-closed.
+    const call = options.call ?? callController;
+    const actual = await call(home, "controller.identity", {}, {
+        timeoutMs: options.requestTimeoutMs
+    });
+    assertControllerLaunchIdentity(actual, identity);
+    return status;
+}
+function assertExpectedControllerLaunchIdentity(identity) {
+    if (typeof identity.executablePath !== "string"
+        || identity.executablePath.length === 0
+        || !Array.isArray(identity.args)
+        || identity.args.some((arg) => typeof arg !== "string")
+        || typeof identity.version !== "string"
+        || identity.version.length === 0) {
+        throw new Error("Expected Controller launch identity is malformed; refusing to start or accept a Controller.");
+    }
+}
+function assertControllerLaunchIdentity(actual, expected) {
+    if (!isJsonRecord(actual)) {
+        throw new Error("Authenticated Controller launch identity is malformed; refusing to accept readiness.");
+    }
+    const actualArgs = actual.args;
+    if (typeof actual.executablePath !== "string"
+        || !Array.isArray(actualArgs)
+        || actualArgs.some((arg) => typeof arg !== "string")
+        || typeof actual.version !== "string") {
+        throw new Error("Authenticated Controller launch identity is malformed; refusing to accept readiness.");
+    }
+    const argsMatch = actualArgs.length === expected.args.length
+        && actualArgs.every((arg, index) => arg === expected.args[index]);
+    if (actual.executablePath !== expected.executablePath
+        || !argsMatch
+        || actual.version !== expected.version) {
+        throw new Error("Authenticated Controller launch identity does not match the captured executable, argv, and version; refusing readiness.");
+    }
+}
+function assertCompatibleControllerStatus(status, expectedVersion) {
+    const statusRecord = isJsonRecord(status) && status.running === true ? status : null;
+    const actual = statusRecord?.protocolVersion;
+    if (statusRecord === null || actual !== FILE_TASK_CONTROLLER_PROTOCOL_VERSION) {
+        throw new Error(`Controller protocol is incompatible (expected ${FILE_TASK_CONTROLLER_PROTOCOL_VERSION}, found ${typeof actual === "number" ? actual : "unknown"}). `
+            + "Run `yui controller restart` before writing new task records.");
+    }
+    const actualVersion = statusRecord.version;
+    const expected = expectedVersion ?? YUI_VERSION;
+    const versionMismatch = expectedVersion === undefined
+        ? typeof actualVersion === "string" && actualVersion !== expected
+        : actualVersion !== expected;
+    if (versionMismatch) {
+        throw new Error(`Controller version is incompatible (expected ${expected}, found ${typeof actualVersion === "string" ? actualVersion : "unknown"}). `
+            + "Run `yui controller restart` before writing new task records.");
+    }
+    // Ordinary callers must authenticate the complete control-plane identity.
+    // An update/upgrade restore instead targets a previously captured Controller
+    // binary, which may predate the current storage-layout status fields; that
+    // path authenticates its executable, argv, and version immediately after
+    // readiness in ensureFileTaskControllerIdentity.
+    if (expectedVersion === undefined) {
+        assertControllerStatusIdentity(status, yuiVersionIdentity());
+    }
+}
 function spawnDetachedFileTaskController(home, environment) {
     const child = spawn(process.execPath, [fileURLToPath(new URL("./controllerMain.js", import.meta.url))], {
         env: environment,
@@ -40,22 +155,80 @@ function spawnDetachedFileTaskController(home, environment) {
     });
     child.unref();
 }
+/** Stops the per-home Controller and waits until its owned discovery is gone. */
+export async function stopFileTaskController(home, options = {}) {
+    const call = options.call ?? callController;
+    const shutdownTimeoutMs = positive(options.shutdownTimeoutMs, SHUTDOWN_TIMEOUT_MS, "shutdownTimeoutMs");
+    const pollMs = positive(options.pollIntervalMs, POLL_INTERVAL_MS, "pollIntervalMs");
+    const expectedPid = options.expectedPid === undefined
+        ? undefined
+        : positive(options.expectedPid, 0, "expectedPid");
+    const current = await readOptionalControllerStatus(home, call);
+    const pid = controllerPid(current);
+    if (expectedPid !== undefined && pid !== expectedPid) {
+        throw new Error(`Controller ownership changed before fenced stop (expected PID ${expectedPid}, `
+            + `found ${pid === undefined ? "none" : pid}).`);
+    }
+    if (!controllerRunning(current)) {
+        return { stopped: false, alreadyStopped: true };
+    }
+    await callFileTaskController(home, "controller.stop", expectedPid === undefined ? {} : { expectedPid }, options);
+    const deadline = Date.now() + shutdownTimeoutMs;
+    for (;;) {
+        if (options.call === undefined) {
+            const discoveryOwned = await ownedControllerDiscoveryExists(home, pid);
+            if (!discoveryOwned && expectedPid !== undefined) {
+                // A replacement owner appearing during the drain is not equivalent to
+                // the fenced process disappearing; fail closed instead of reporting a
+                // successful stop against a foreign PID.
+                const observed = controllerPid(await readOptionalControllerStatus(home, call));
+                if (observed !== undefined && observed !== expectedPid) {
+                    throw new Error(`Controller ownership changed during fenced stop (expected PID ${expectedPid}, `
+                        + `found ${observed}).`);
+                }
+            }
+            if (!discoveryOwned)
+                break;
+        }
+        else {
+            const observed = controllerPid(await readOptionalControllerStatus(home, call));
+            if (observed === undefined)
+                break;
+            if (expectedPid !== undefined && observed !== expectedPid) {
+                throw new Error(`Controller ownership changed during fenced stop (expected PID ${expectedPid}, `
+                    + `found ${observed}).`);
+            }
+            if (observed !== pid)
+                break;
+        }
+        if (Date.now() >= deadline) {
+            throw new Error(`Controller did not stop within ${shutdownTimeoutMs} ms.`);
+        }
+        await delay(pollMs);
+    }
+    return {
+        stopped: true,
+        ...(pid === undefined ? {} : { pid })
+    };
+}
 /** Restarts only the per-home Controller process; managed tmux sessions remain untouched. */
 export async function restartFileTaskController(home, options = {}) {
     const call = options.call ?? callController;
-    const timeoutMs = positive(options.startupTimeoutMs, STARTUP_TIMEOUT_MS, "startupTimeoutMs");
+    const shutdownTimeoutMs = positive(options.shutdownTimeoutMs, SHUTDOWN_TIMEOUT_MS, "shutdownTimeoutMs");
     const pollMs = positive(options.pollIntervalMs, POLL_INTERVAL_MS, "pollIntervalMs");
     const current = await readOptionalControllerStatus(home, call);
     const previousPid = controllerPid(current);
     if (controllerRunning(current)) {
         await callFileTaskController(home, "controller.stop", {}, options);
-        const deadline = Date.now() + timeoutMs;
+        const deadline = Date.now() + shutdownTimeoutMs;
         for (;;) {
-            const status = await readOptionalControllerStatus(home, call);
-            if (!controllerRunning(status))
+            const stillOwned = options.call === undefined
+                ? await ownedControllerDiscoveryExists(home, previousPid)
+                : controllerPid(await readOptionalControllerStatus(home, call)) === previousPid;
+            if (!stillOwned)
                 break;
             if (Date.now() >= deadline) {
-                throw new Error(`Controller did not stop within ${timeoutMs} ms.`);
+                throw new Error(`Controller did not stop within ${shutdownTimeoutMs} ms.`);
             }
             await delay(pollMs);
         }
@@ -68,6 +241,40 @@ export async function restartFileTaskController(home, options = {}) {
         ...(pid === undefined ? {} : { pid })
     };
 }
+function controllerSpawnEnvironment(home, source) {
+    const allowed = new Set(CONTROLLER_OPERATIONAL_ENVIRONMENT);
+    try {
+        for (const agent of openCompatibleFileTaskStore(home).listConfiguredAgents()) {
+            for (const name of nativeAgentEnvironmentNames(agent.adapterId))
+                allowed.add(name);
+            for (const binding of agent.environment)
+                allowed.add(binding.sourceName);
+        }
+    }
+    catch {
+        // The Controller remains authoritative for reporting an invalid/unavailable
+        // home. Environment filtering must never fall back to forwarding all names.
+    }
+    const environment = {};
+    for (const name of allowed) {
+        const value = source[name];
+        if (value !== undefined)
+            environment[name] = value;
+    }
+    environment.YUI_HOME = home;
+    return environment;
+}
+async function ownedControllerDiscoveryExists(home, previousPid) {
+    try {
+        const discovery = await readControllerDiscovery(home);
+        return previousPid === undefined || discovery.pid === previousPid;
+    }
+    catch (error) {
+        if (isUnavailable(error))
+            return false;
+        throw error;
+    }
+}
 export async function callFileTaskController(home, method, params = {}, options = {}) {
     const call = options.call ?? callController;
     if (method === "controller.status" || method === "controller.stop") {
@@ -82,8 +289,78 @@ export async function callFileTaskController(home, method, params = {}, options
                 : { stopped: false, alreadyStopped: true };
         }
     }
+    try {
+        return await call(home, method, params, {
+            timeoutMs: options.requestTimeoutMs
+        });
+    }
+    catch (error) {
+        if (!isUnavailable(error))
+            throw error;
+    }
     await ensureFileTaskController(home, options);
-    return call(home, method, params);
+    return call(home, method, params, {
+        timeoutMs: options.requestTimeoutMs
+    });
+}
+/**
+ * Best-effort refresh for a Controller that is already running. This path
+ * deliberately calls the authenticated socket directly: an Agent config
+ * command must not start a background Controller merely to copy secrets.
+ */
+export async function refreshRunningFileTaskControllerEnvironment(home, store, source = process.env, options = {}) {
+    const configuredSourceNames = new Set();
+    const configuredNativeNames = new Set();
+    for (const agent of store.listConfiguredAgents()) {
+        for (const name of nativeAgentEnvironmentNames(agent.adapterId)) {
+            configuredNativeNames.add(name);
+        }
+        for (const binding of agent.environment) {
+            if (!MANAGED_RUNTIME_ENVIRONMENT.has(binding.sourceName)) {
+                configuredSourceNames.add(binding.sourceName);
+            }
+        }
+    }
+    const sourceNames = options.sourceNames === undefined
+        ? [...configuredSourceNames]
+        : [...new Set(options.sourceNames)];
+    const nativeNames = options.nativeNames === undefined
+        ? [...configuredNativeNames]
+        : [...new Set(options.nativeNames)];
+    const sources = selectEnvironment(source, sourceNames);
+    const nativeSources = selectEnvironment(source, nativeNames);
+    try {
+        await (options.call ?? callController)(home, "runtime.replace-agent-environment", { sources, sourceNames, nativeSources, nativeNames }, {
+            timeoutMs: options.requestTimeoutMs
+                ?? ENVIRONMENT_REFRESH_TIMEOUT_MS
+        });
+        return { status: "refreshed" };
+    }
+    catch (error) {
+        return classifyRefreshFailure(error, options);
+    }
+}
+/** Reloads durable Controller settings without starting an absent Controller. */
+export async function refreshRunningFileTaskControllerConfiguration(home, options = {}) {
+    try {
+        await (options.call ?? callController)(home, "scheduler.configure", {}, {
+            timeoutMs: options.requestTimeoutMs
+                ?? CONFIGURATION_REFRESH_TIMEOUT_MS
+        });
+        return { status: "refreshed" };
+    }
+    catch (error) {
+        return classifyRefreshFailure(error, options);
+    }
+}
+function classifyRefreshFailure(error, options) {
+    if (isDefinitelyNotRunning(error))
+        return { status: "not-running" };
+    options.onError?.(error);
+    return {
+        status: "failed",
+        message: error instanceof Error ? error.message : String(error)
+    };
 }
 /** Foreground command bridge. It never reads or writes Agent terminal bytes. */
 export class FileTaskWorkflowRuntime {
@@ -104,81 +381,156 @@ export class FileTaskWorkflowRuntime {
         this.clientOptions = clientOptions;
     }
     notifyStateChanged(taskId) {
-        void this.#prepareAndScan(taskId).catch(this.clientOptions.onError ?? (() => { }));
+        this.notifyMailboxChanged({ kind: "task", taskId });
+    }
+    notifyMailboxChanged(target) {
+        void callFileTaskController(this.home, "scheduler.signal", { key: controllerMailboxKey(target) }, this.clientOptions).catch(this.clientOptions.onError ?? (() => { }));
     }
     reconcileTask(taskId) {
         void this.#prepareAndScan(taskId).catch(this.clientOptions.onError ?? (() => { }));
     }
-    prepareTaskRoleEnter(input) {
-        const role = this.store.getRole(input.taskId, input.roleName);
-        if (role === null)
-            throw new Error(`Role not found: ${input.taskId}/${input.roleName}.`);
-        const session = this.store.getRoleSession(input.taskId, input.roleName);
-        const mode = session?.nativeSessionId === undefined ? "new" : "resume";
-        const planned = this.planner.plan({
+    async prepareTaskRoleEnter(input) {
+        const task = this.store.getTask(input.taskId);
+        if (task?.status === "active" && this.workspacePreparer !== undefined) {
+            await this.workspacePreparer.prepareTaskWorkspace(task.id);
+        }
+        const environment = foregroundRoleEnvironment(this.store, { scope: "task", taskId: input.taskId, roleName: input.roleName }, this.clientOptions.environment ?? process.env);
+        await callFileTaskController(this.home, "runtime.ensure-role-session", {
+            scope: "task",
             taskId: input.taskId,
             roleName: input.roleName,
-            agentId: role.activeAgentId,
-            adapterId: role.agentBindings[role.activeAgentId].adapterId,
-            mode,
-            ...(mode === "resume" ? { nativeSessionId: session.nativeSessionId } : {})
+            ...(environment === undefined ? {} : { environment })
+        }, {
+            ...this.clientOptions,
+            requestTimeoutMs: LIFECYCLE_REQUEST_TIMEOUT_MS
         });
-        this.tmux.ensureRoleWindow(input.taskId, planned.role, planned.launch);
-        if (planned.session?.nativeSessionId !== undefined) {
-            this.schedulerStore.recordRuntimeNativeSession({
-                taskId: input.taskId,
-                roleName: input.roleName,
-                agentId: planned.session.agentId,
-                adapterId: planned.session.adapterId,
-                nativeSessionId: planned.session.nativeSessionId
+    }
+    async stopTaskRoleSessions(taskId, roleNames) {
+        const targets = [];
+        for (const roleName of [...new Set(roleNames)]) {
+            if (this.store.getActiveAgentRun(taskId, roleName) !== null) {
+                throw new Error(`Role has an active Run: ${taskId}/${roleName}.`);
+            }
+            const target = this.schedulerStore.enqueueRuntimeCleanup({
+                scope: "task",
+                taskId,
+                roleName
             });
+            if (target === null)
+                throw new Error(`Task not found: ${taskId}.`);
+            if (target.kind !== "role-runtime") {
+                throw new Error(`Role runtime cleanup target is invalid: ${taskId}/${roleName}.`);
+            }
+            targets.push(target);
+        }
+        if (targets.length === 0)
+            return;
+        await callFileTaskController(this.home, "scheduler.scan", {}, {
+            ...this.clientOptions,
+            requestTimeoutMs: LIFECYCLE_REQUEST_TIMEOUT_MS
+        });
+        for (const target of targets) {
+            if (hasRuntimeLifecycleWork(this.store.getWorkMailbox(target))) {
+                throw new Error(`Role runtime did not stop: ${target.taskId}/${target.roleName}.`);
+            }
+            const session = this.store.getRoleSession(target.taskId, target.roleName);
+            if (session !== null && session.status !== "stopped") {
+                throw new Error(`Role runtime session is still active: ${target.taskId}/${target.roleName}.`);
+            }
+        }
+    }
+    async stopGlobalRoleSession(roleName) {
+        if (this.store.getGlobalRole(roleName) === null) {
+            throw new Error(`Global Role not found: ${roleName}.`);
+        }
+        const target = this.schedulerStore.enqueueRuntimeCleanup({
+            scope: "global",
+            roleName
+        });
+        if (target?.kind !== "global-role-runtime") {
+            throw new Error(`Global Role runtime cleanup target is invalid: ${roleName}.`);
+        }
+        await callFileTaskController(this.home, "scheduler.scan", {}, {
+            ...this.clientOptions,
+            requestTimeoutMs: LIFECYCLE_REQUEST_TIMEOUT_MS
+        });
+        if (hasRuntimeLifecycleWork(this.store.getWorkMailbox(target))) {
+            throw new Error(`Global Role runtime did not stop: ${roleName}.`);
+        }
+        const sessions = this.store.getGlobalRoleSessionSet(roleName);
+        const active = sessions?.sessions[sessions.activeAgentId];
+        if (active !== undefined && active.status !== "stopped") {
+            throw new Error(`Global Role runtime session is still active: ${roleName}.`);
         }
     }
     inspectTaskRolePanes(taskId) {
         return this.tmux.inspectTaskRolePanes(taskId);
     }
-    prepareGlobalRoleEnter(roleName, tmuxTaskId = "operator") {
-        const role = this.store.getGlobalRole(roleName);
-        if (role === null)
-            throw new Error(`Global Role not found: ${roleName}.`);
-        const sessionSet = this.store.getGlobalRoleSessionSet(roleName);
-        const session = sessionSet?.sessions[role.activeAgentId];
-        const binding = role.agentBindings[role.activeAgentId];
-        const mode = session?.nativeSessionId === undefined ? "new" : "resume";
-        const planned = this.planner.planGlobalRole({
+    async prepareGlobalRoleEnter(roleName) {
+        const environment = foregroundRoleEnvironment(this.store, { scope: "global", roleName }, this.clientOptions.environment ?? process.env);
+        await callFileTaskController(this.home, "runtime.ensure-role-session", {
+            scope: "global",
             roleName,
-            agentId: role.activeAgentId,
-            adapterId: binding.adapterId,
-            mode,
-            ...(mode === "resume" ? { nativeSessionId: session.nativeSessionId } : {})
+            ...(environment === undefined ? {} : { environment })
+        }, {
+            ...this.clientOptions,
+            requestTimeoutMs: LIFECYCLE_REQUEST_TIMEOUT_MS
         });
-        this.tmux.ensureRoleWindow(tmuxTaskId, planned.role, planned.launch);
-        if (planned.session?.nativeSessionId !== undefined) {
-            this.schedulerStore.recordGlobalRuntimeNativeSession({
-                roleName,
-                agentId: planned.session.agentId,
-                adapterId: planned.session.adapterId,
-                nativeSessionId: planned.session.nativeSessionId
-            });
+        if (roleName === "operator") {
+            await callFileTaskController(this.home, "scheduler.signal", { key: "operator" }, this.clientOptions);
         }
     }
     async #prepareAndScan(taskId) {
         const task = this.store.getTask(taskId);
-        if (task?.repositoryId !== undefined
-            && task.status === "active"
+        if (task !== null
+            && (task.status === "draft" || task.status === "active")
             && this.workspacePreparer !== undefined) {
             await this.workspacePreparer.prepareTaskWorkspace(taskId);
         }
         await callFileTaskController(this.home, "scheduler.scan", {}, this.clientOptions);
     }
 }
+const MANAGED_RUNTIME_ENVIRONMENT = new Set(YUI_MANAGED_RUNTIME_ENVIRONMENT_NAMES);
+function foregroundRoleEnvironment(store, owner, source) {
+    const role = owner.scope === "task"
+        ? store.getRole?.(owner.taskId, owner.roleName)
+        : store.getGlobalRole?.(owner.roleName);
+    if (role === null || role === undefined)
+        return undefined;
+    const agent = store.getConfiguredAgent?.(role.activeAgentId);
+    if (agent === null || agent === undefined)
+        return undefined;
+    const declaredSources = new Set(agent.environment.map((binding) => binding.sourceName));
+    for (const name of MANAGED_RUNTIME_ENVIRONMENT)
+        declaredSources.delete(name);
+    return {
+        ...operationalAgentEnvironment(agent.adapterId, source),
+        ...selectEnvironment(source, declaredSources)
+    };
+}
+function controllerMailboxKey(target) {
+    switch (target.kind) {
+        case "operator": return "operator";
+        case "task": return `task:${encodeURIComponent(target.taskId)}`;
+        case "role": return `role:${encodeURIComponent(target.taskId)}/${encodeURIComponent(target.roleName)}`;
+        case "role-runtime":
+            return `role:${encodeURIComponent(target.taskId)}/${encodeURIComponent(target.roleName)}`;
+        case "global-role-runtime":
+            return `global-role:${encodeURIComponent(target.roleName)}`;
+    }
+}
 function isUnavailable(error) {
     if (typeof error !== "object" || error === null || !("code" in error))
         return false;
     const code = error.code;
-    return code === "CONTROLLER_UNAVAILABLE"
-        || code === "CONTROLLER_DISCOVERY_INVALID"
-        || code === "INVALID_RESPONSE";
+    return code === "CONTROLLER_NOT_RUNNING"
+        || code === "CONTROLLER_UNAVAILABLE";
+}
+function isDefinitelyNotRunning(error) {
+    if (typeof error !== "object" || error === null || !("code" in error))
+        return false;
+    const code = error.code;
+    return code === "CONTROLLER_NOT_RUNNING";
 }
 async function readOptionalControllerStatus(home, call) {
     try {

package/dist/controller/codexLifecycleHook.js

@@ -0,0 +1,108 @@
+import { callController } from "../core/controllerClient.js";
+import { runtimeLifecycleSignalKey } from "../runtime/lifecycleReservation.js";
+import { FileRuntimeEventInbox, MAX_RUNTIME_EVENT_FILE_BYTES } from "./runtimeEventInbox.js";
+import { resolveProviderHookRunFence } from "./providerHookRunFence.js";
+/**
+ * Hidden CLI entrypoint used by the managed Codex lifecycle hooks. Codex 0.145
+ * fires SessionStart and UserPromptSubmit inside run_turn(input); this parses
+ * by hook_event_name and writes one immutable runtime-inbox event per fact.
+ * SessionStart maps (via the adapter) to provider-session-started only — never
+ * pre-input readiness; UserPromptSubmit is the exact provider-accepted fence.
+ * The durable write is authoritative; the socket call is only a wake-up hint.
+ */
+export async function runCodexLifecycleHookCommand(stdinJson, environment = process.env, call = callController) {
+    const home = requireIdentity(environment.YUI_HOME, "YUI_HOME");
+    const inbox = new FileRuntimeEventInbox(home);
+    const envelope = parseCodexHookEnvelope(stdinJson, environment);
+    if (envelope.kind === "session-start") {
+        inbox.enqueueSessionLifecycle({
+            scope: "task",
+            taskId: envelope.taskId,
+            roleName: envelope.roleName,
+            agentId: envelope.agentId,
+            adapterId: "codex",
+            launchId: envelope.launchId,
+            nativeSessionId: envelope.nativeSessionId,
+            runId: envelope.runId
+            // Codex SessionStart arrives within the first turn, not before input.
+        });
+    }
+    else {
+        inbox.enqueuePromptAccepted({
+            scope: "task",
+            taskId: envelope.taskId,
+            roleName: envelope.roleName,
+            agentId: envelope.agentId,
+            adapterId: "codex",
+            launchId: envelope.launchId,
+            nativeSessionId: envelope.nativeSessionId,
+            runId: envelope.runId,
+            receiptId: envelope.receiptId
+        });
+    }
+    await call(home, "scheduler.signal", {
+        key: runtimeLifecycleSignalKey({
+            scope: "task",
+            taskId: envelope.taskId,
+            roleName: envelope.roleName
+        })
+    }, { timeoutMs: 100 }).catch(() => { });
+}
+/**
+ * Parses a Codex hook payload by hook_event_name into the exact fenced envelope.
+ * Every event requires the managed launch envelope, and the payload session id
+ * must match YUI_NATIVE_SESSION_ID, so a mismatched generation fails closed
+ * before any inbox write.
+ */
+export function parseCodexHookEnvelope(stdinJson, environment) {
+    const payload = parseObject(stdinJson);
+    if (payload.hook_event_name !== "SessionStart"
+        && payload.hook_event_name !== "UserPromptSubmit") {
+        throw new Error("Managed Codex lifecycle ingestion received an unsupported hook event.");
+    }
+    const base = parseCodexEnvelope(payload, environment);
+    switch (payload.hook_event_name) {
+        case "SessionStart":
+            return { ...base, kind: "session-start" };
+        case "UserPromptSubmit":
+            return {
+                ...base,
+                kind: "prompt-submit",
+                receiptId: requireIdentity(base.receiptId, "Codex transport receipt id")
+            };
+        default:
+            throw new Error("Managed Codex lifecycle ingestion received an unsupported hook event.");
+    }
+}
+function parseCodexEnvelope(payload, environment) {
+    const nativeSessionId = requireIdentity(payload.session_id, "Codex session id");
+    return resolveProviderHookRunFence(environment, "codex", nativeSessionId);
+}
+function parseObject(value) {
+    if (value === undefined
+        || Buffer.byteLength(value, "utf8") > MAX_RUNTIME_EVENT_FILE_BYTES) {
+        throw new Error("Codex lifecycle hook stdin JSON is invalid.");
+    }
+    try {
+        const parsed = JSON.parse(value);
+        if (!isObject(parsed))
+            throw new Error("shape");
+        return parsed;
+    }
+    catch {
+        throw new Error("Codex lifecycle hook stdin JSON is invalid.");
+    }
+}
+function requireIdentity(value, label) {
+    if (typeof value !== "string" || value.includes("\0")) {
+        throw new Error(`${label} is required.`);
+    }
+    const normalized = value.trim();
+    if (normalized.length === 0 || normalized.length > 1_024) {
+        throw new Error(`${label} is invalid.`);
+    }
+    return normalized;
+}
+function isObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}