@zq-silk/yui 0.14.1 → 0.15.0

package/dist/runtime/exactControlPlane.js

@@ -1,15 +1,11 @@
 import { createHash } from "node:crypto";
-import { readFileSync, realpathSync } from "node:fs";
-import { dirname, join, resolve } from "node:path";
+import { realpathSync } from "node:fs";
+import { resolve } from "node:path";
 import { callController as defaultCallController } from "../core/controllerClient.js";
 import { inspectStorageSchema } from "../storage/storageSchema.js";
 import { yuiVersionIdentity } from "../version.js";
-import { hasRuntimeCleanupObligation, isRuntimeLaunchReservation, runtimeLifecycleTarget } from "./lifecycleReservation.js";
-import { nativeSessionIdForLaunch } from "./preallocatedNativeSession.js";
-import { writeTextFileAtomically } from "../storage/durableFile.js";
 export const EXACT_CONTROL_ARGUMENT = "--yui-control";
 export const YUI_CONTROL_PLANE_DESCRIPTOR = "YUI_CONTROL_PLANE_DESCRIPTOR";
-export const YUI_TASK_RUNTIME_DESCRIPTOR = "YUI_TASK_RUNTIME_DESCRIPTOR";
 export function createExactControlPlaneDescriptor(input) {
     const identity = validateVersionIdentity(input.identity ?? yuiVersionIdentity());
     return Object.freeze({
@@ -25,25 +21,6 @@ export function createExactControlPlaneDescriptor(input) {
             : { activeReleaseDigest: input.activeReleaseDigest })
     });
 }
-export function createExactTaskRuntimeDescriptor(input) {
-    return Object.freeze({
-        schemaVersion: 1,
-        kind: "yui-task-runtime",
-        controlPlaneDigest: requireDigest(input.controlPlaneDigest),
-        taskId: requireIdentity(input.taskId, "Task id"),
-        roleName: requireIdentity(input.roleName, "Role name"),
-        agentId: requireIdentity(input.agentId, "Agent id"),
-        adapterId: requireAdapter(input.adapterId),
-        workspace: canonicalPath(input.workspace),
-        ...(input.turnId === undefined ? {} : { turnId: requireIdentity(input.turnId, "Turn id") }),
-        ...(input.launchId === undefined
-            ? {}
-            : { launchId: requireIdentity(input.launchId, "Launch id") }),
-        ...(input.nativeSessionId === undefined
-            ? {}
-            : { nativeSessionId: requireIdentity(input.nativeSessionId, "Native session id") })
-    });
-}
 export function serializeExactDescriptor(descriptor) {
     return JSON.stringify(descriptor);
 }
@@ -64,47 +41,9 @@ export function parseExactControlPlaneDescriptor(value) {
             : { activeReleaseDigest: record.activeReleaseDigest })
     });
 }
-export function parseExactTaskRuntimeDescriptor(value) {
-    const record = parseDescriptorRecord(value);
-    assertDescriptorKind(record, "yui-task-runtime");
-    if (record.schemaVersion !== 1) {
-        throw new Error("Exact Task runtime descriptor schema version is invalid.");
-    }
-    return createExactTaskRuntimeDescriptor({
-        controlPlaneDigest: requireText(record.controlPlaneDigest, "Control-plane digest"),
-        taskId: requireText(record.taskId, "Task id"),
-        roleName: requireText(record.roleName, "Role name"),
-        agentId: requireText(record.agentId, "Agent id"),
-        adapterId: requireAdapter(record.adapterId),
-        workspace: requireText(record.workspace, "Task runtime workspace"),
-        ...(record.turnId === undefined ? {} : { turnId: requireText(record.turnId, "Turn id") }),
-        ...(record.launchId === undefined
-            ? {}
-            : { launchId: requireText(record.launchId, "Launch id") }),
-        ...(record.nativeSessionId === undefined
-            ? {}
-            : { nativeSessionId: requireText(record.nativeSessionId, "Native session id") })
-    });
-}
 export function exactControlPlaneDigest(descriptor) {
     return createHash("sha256").update(serializeExactDescriptor(descriptor)).digest("hex");
 }
-/** Stable per Task/Role/Agent location; volatile Turn/launch/native fields are content. */
-export function exactTaskRuntimeDescriptorPath(home, descriptor) {
-    const validated = createExactTaskRuntimeDescriptor(descriptor);
-    const digest = createHash("sha256").update(JSON.stringify([
-        validated.controlPlaneDigest,
-        validated.taskId,
-        validated.roleName,
-        validated.agentId,
-        validated.adapterId,
-        validated.workspace
-    ])).digest("hex");
-    return join(canonicalPath(home), "runtime", "exact-task-runtime", `${digest}.json`);
-}
-export function readExactTaskRuntimeDescriptorSource(source, home) {
-    return readTaskRuntimeSource(source, home).descriptor;
-}
 export function exactControlPlaneCommandPrefix(descriptor) {
     return [
         descriptor.executable,
@@ -134,7 +73,7 @@ export function extractExactControlArgument(args) {
 }
 /**
  * One read-only gate shared by every managed Task control command. It verifies
- * the frozen executable/CLI/Home/digest, protocol and scalar-storage identity,
+ * the frozen executable/CLI/Home/digest, protocol and storage identity,
  * on-disk schema, and any live Controller before command routing may construct
  * a writable store. Package version alone may advance at the same managed path
  * so an existing Session can cross an explicitly compatible in-place update.
@@ -153,15 +92,10 @@ export async function assertExactControlPlanePreflight(input, options = {}) {
     if (storage.status !== "current") {
         throw new Error(`Exact control-plane storage is not current: ${storage.status}.`);
     }
-    if (storage.currentLayoutVersion !== descriptor.identity.storageLayoutVersion) {
-        throw new Error("Exact control-plane storage layout does not match its frozen descriptor "
-            + `(expected ${descriptor.identity.storageLayoutVersion}, found `
-            + `${storage.currentLayoutVersion ?? "unknown"}).`);
-    }
-    if (storage.currentAggregateSchemaVersion !== descriptor.identity.aggregateSchemaVersion) {
-        throw new Error("Exact control-plane aggregate schema does not match its frozen descriptor "
-            + `(expected ${descriptor.identity.aggregateSchemaVersion}, found `
-            + `${storage.currentAggregateSchemaVersion ?? "unknown"}).`);
+    if (storage.currentVersion !== descriptor.identity.storageVersion) {
+        throw new Error("Exact control-plane storage version does not match its frozen descriptor "
+            + `(expected ${descriptor.identity.storageVersion}, found `
+            + `${storage.currentVersion ?? "unknown"}).`);
     }
     // A frozen descriptor authenticates the command that created it; it no
     // longer pins the Home's deployment pointer for the lifetime of a Session.
@@ -194,15 +128,10 @@ export async function assertCompatibleControlPlanePreflight(input, options = {})
     if (storage.status !== "current") {
         throw new Error(`Managed control-plane storage is not current: ${storage.status}.`);
     }
-    if (storage.currentLayoutVersion !== identity.storageLayoutVersion) {
-        throw new Error("Managed control-plane storage layout is incompatible "
-            + `(expected ${identity.storageLayoutVersion}, found `
-            + `${storage.currentLayoutVersion ?? "unknown"}).`);
-    }
-    if (storage.currentAggregateSchemaVersion !== identity.aggregateSchemaVersion) {
-        throw new Error("Managed control-plane aggregate schema is incompatible "
-            + `(expected ${identity.aggregateSchemaVersion}, found `
-            + `${storage.currentAggregateSchemaVersion ?? "unknown"}).`);
+    if (storage.currentVersion !== identity.storageVersion) {
+        throw new Error("Managed control-plane storage version is incompatible "
+            + `(expected ${identity.storageVersion}, found `
+            + `${storage.currentVersion ?? "unknown"}).`);
     }
     if (options.checkController !== false) {
         const call = options.callController ?? defaultCallController;
@@ -223,210 +152,31 @@ export function assertControllerStatusIdentity(status, expected = yuiVersionIden
     }
     assertControllerField(status.protocolVersion, expected.controllerProtocolVersion, "protocol");
     assertControllerField(status.version, expected.version, "version");
-    assertControllerField(status.storageLayoutVersion, expected.storageLayoutVersion, "storage layout");
-    assertControllerField(status.aggregateSchemaVersion, expected.aggregateSchemaVersion, "aggregate schema");
-}
-export function assertExactTaskRuntimeEnvironment(runtimeSource, environment, expectedControlDigest, expectedHome = requireText(environment.YUI_HOME, "YUI_HOME")) {
-    const resolved = readTaskRuntimeSource(runtimeSource, expectedHome);
-    const runtime = resolved.descriptor;
-    if (runtime.controlPlaneDigest !== requireDigest(expectedControlDigest)) {
-        throw new Error("Task runtime descriptor belongs to another exact control plane.");
-    }
-    assertEnvironment(runtime.taskId, environment.YUI_TASK_ID, "Task id");
-    assertEnvironment(runtime.roleName, environment.YUI_ROLE, "Role name");
-    assertEnvironment(runtime.agentId, environment.YUI_AGENT_ID, "Agent id");
-    assertEnvironment(runtime.adapterId, environment.YUI_ADAPTER_ID, "Agent adapter id");
-    assertSamePath(runtime.workspace, requireText(environment.YUI_WORKSPACE, "YUI_WORKSPACE"), "Task runtime workspace");
-    // A reused native pane retains its original process environment. Volatile
-    // identity therefore comes only from the atomically published descriptor
-    // plus durable state, never from stale ambient Turn/launch/native variables.
-    if (!resolved.fromFile) {
-        assertOptionalEnvironment(runtime.turnId, environment.YUI_TURN_ID, "Turn id");
-        assertOptionalEnvironment(runtime.launchId, environment.YUI_LAUNCH_ID, "Launch id");
-        assertOptionalEnvironment(runtime.nativeSessionId, environment.YUI_NATIVE_SESSION_ID, "Native session id");
-    }
-    return runtime;
-}
-/** Fences a descriptor to the one currently active durable Task runtime. */
-export function assertExactTaskRuntimeState(runtime, store, options = {}) {
-    const task = store.getTask(runtime.taskId);
-    if (task === null
-        || task.status !== "active"
-        || task.executionGate.state !== "enabled") {
-        throw new Error("Exact Task runtime Task is not current and active.");
-    }
-    const role = store.getRole(runtime.taskId, runtime.roleName);
-    if (role === null || role.activeAgentId !== runtime.agentId) {
-        throw new Error("Exact Task runtime Role or Agent is not current.");
-    }
-    const run = store.getActiveTurn(runtime.taskId, runtime.roleName);
-    if (runtime.turnId === undefined) {
-        if (run !== null)
-            throw new Error("Exact Task runtime Turn is not current.");
-    }
-    else if (run === null
-        || run.id !== runtime.turnId
-        || run.status !== "active"
-        || run.effective.agentId !== runtime.agentId
-        || run.effective.adapterId !== runtime.adapterId
-        || canonicalPath(run.effective.workspace.root) !== runtime.workspace) {
-        throw new Error("Exact Task runtime Turn is not current.");
-    }
-    const sessions = store.getTaskRoleSessionSet(runtime.taskId, runtime.roleName);
-    const session = sessions?.sessions[runtime.agentId];
-    if (sessions !== null && sessions.activeAgentId !== runtime.agentId) {
-        throw new Error("Exact Task runtime Session Agent is not current.");
-    }
-    const lifecycleMailbox = store.getWorkMailbox(runtimeLifecycleTarget({
-        scope: "task",
-        taskId: runtime.taskId,
-        roleName: runtime.roleName
-    }));
-    const reservation = runtime.launchId !== undefined
-        && isRuntimeLaunchReservation(lifecycleMailbox?.processing, runtime.launchId);
-    const sessionLaunch = runtime.launchId !== undefined
-        && session?.launchId === runtime.launchId;
-    const preallocated = options.preallocatedDriverSessionReservation;
-    const exactHostLaunchReservation = runtime.launchId !== undefined
-        && reservation
-        && !hasRuntimeCleanupObligation(lifecycleMailbox);
-    const terminalSessionReplacementReservation = exactHostLaunchReservation
-        && session !== undefined
-        && session.status === "ended";
-    const exactPreallocatedReservation = preallocated !== undefined
-        && runtime.adapterId === preallocated.adapterId
-        && exactHostLaunchReservation
-        && runtime.nativeSessionId !== undefined
-        && (session === undefined || terminalSessionReplacementReservation)
-        && runtime.nativeSessionId === nativeSessionIdForLaunch(preallocated.yuiHome, runtime.launchId, runtime.agentId, runtime.adapterId);
-    if (runtime.launchId === undefined || (!reservation && !sessionLaunch)) {
-        throw new Error("Exact Task runtime launch fence is not current.");
-    }
-    if (runtime.nativeSessionId === undefined) {
-        if (session !== undefined && !terminalSessionReplacementReservation) {
-            throw new Error("Exact Task runtime native Session fence is missing.");
-        }
-    }
-    else if (session === undefined || terminalSessionReplacementReservation) {
-        if (!exactPreallocatedReservation) {
-            throw new Error("Exact Task runtime native Session fence is not current.");
-        }
-    }
-    else if (session.agentId !== runtime.agentId
-        || session.adapterId !== runtime.adapterId
-        || session.nativeSessionId !== runtime.nativeSessionId
-        || session.launchId !== runtime.launchId
-        || session.status === "ended"
-        || session.effective.agentId !== runtime.agentId
-        || session.effective.adapterId !== runtime.adapterId
-        || canonicalPath(session.effective.workspace.root) !== runtime.workspace) {
-        throw new Error("Exact Task runtime native Session fence is not current.");
-    }
-}
-/** Publishes provider-discovered native identity without changing the stable source path. */
-export function refreshExactTaskRuntimeDescriptorSource(source, home, store) {
-    const resolved = readTaskRuntimeSource(source, home);
-    if (!resolved.fromFile) {
-        throw new Error("A managed Task runtime descriptor must use its stable file source.");
-    }
-    const current = resolved.descriptor;
-    const session = store.getTaskRoleSessionSet(current.taskId, current.roleName)
-        ?.sessions[current.agentId];
-    if (session === undefined) {
-        throw new Error("Exact Task runtime native Session is not available for refresh.");
-    }
-    const refreshed = createExactTaskRuntimeDescriptor({
-        ...current,
-        nativeSessionId: session.nativeSessionId
-    });
-    if (exactTaskRuntimeDescriptorPath(home, refreshed) !== resolve(source)) {
-        throw new Error("Refreshed Task runtime descriptor changed its stable identity.");
-    }
-    assertExactTaskRuntimeState(refreshed, store);
-    writeTextFileAtomically(resolve(source), `${serializeExactDescriptor(refreshed)}\n`);
-    return refreshed;
-}
-/**
- * Advances a reused Hook's own exact source to the current durable Turn/launch
- * generation before the volatile fence. The stable identity (control digest,
- * Task, Role, Agent, adapter, workspace) and the native Session are preserved;
- * only the volatile Turn/launch fields advance. A source may never jump to a
- * replacement native Session.
- */
-export function refreshReusedTaskRuntimeDescriptorSource(source, home, store, current) {
-    const resolved = readTaskRuntimeSource(source, home);
-    if (!resolved.fromFile) {
-        throw new Error("A managed Task runtime descriptor must use its stable file source.");
-    }
-    const previous = resolved.descriptor;
-    if (previous.nativeSessionId === undefined) {
-        if (previous.turnId !== current.turnId || previous.launchId !== current.launchId) {
-            throw new Error("Task runtime descriptor source cannot bind a native Session from another generation.");
-        }
-        return refreshExactTaskRuntimeDescriptorSource(source, home, store);
-    }
-    if (previous.nativeSessionId !== current.nativeSessionId) {
-        throw new Error("Task runtime descriptor source cannot jump to a replacement native Session.");
-    }
-    const refreshed = createExactTaskRuntimeDescriptor({
-        ...previous,
-        turnId: current.turnId,
-        launchId: current.launchId,
-        nativeSessionId: current.nativeSessionId
-    });
-    if (exactTaskRuntimeDescriptorPath(home, refreshed) !== resolve(source)) {
-        throw new Error("Refreshed Task runtime descriptor changed its stable identity.");
-    }
-    assertExactTaskRuntimeState(refreshed, store);
-    writeTextFileAtomically(resolve(source), `${serializeExactDescriptor(refreshed)}\n`);
-    return refreshed;
-}
-function readTaskRuntimeSource(source, home) {
-    const value = requireText(source, "Exact Task runtime descriptor source");
-    if (value.trimStart().startsWith("{")) {
-        return { descriptor: parseExactTaskRuntimeDescriptor(value), fromFile: false };
-    }
-    const requested = resolve(value);
-    const root = resolve(canonicalPath(home), "runtime", "exact-task-runtime");
-    if (dirname(requested) !== root) {
-        throw new Error("Exact Task runtime descriptor path is outside its control plane.");
-    }
-    let actual;
-    try {
-        actual = realpathSync(requested);
-    }
-    catch (error) {
-        throw new Error("Exact Task runtime descriptor file is unavailable.", { cause: error });
-    }
-    if (actual !== requested) {
-        throw new Error("Exact Task runtime descriptor file must not be a symbolic link.");
-    }
-    const descriptor = parseExactTaskRuntimeDescriptor(readFileSync(actual, "utf8"));
-    if (exactTaskRuntimeDescriptorPath(home, descriptor) !== requested) {
-        throw new Error("Exact Task runtime descriptor path does not match its stable identity.");
-    }
-    return { descriptor, fromFile: true };
+    assertControllerField(status.storageVersion, expected.storageVersion, "storage version");
+    assertControllerField(status.minimumStorageVersion, expected.minimumStorageVersion, "minimum storage migration version");
 }
 function validateVersionIdentity(value) {
     if (!isRecord(value))
         throw new Error("Yui version identity is invalid.");
     const version = requireText(value.version, "Yui version");
     const controllerProtocolVersion = requireVersion(value.controllerProtocolVersion, "Controller protocol version");
-    const storageLayoutVersion = requireVersion(value.storageLayoutVersion, "Storage layout version");
-    const aggregateSchemaVersion = requireVersion(value.aggregateSchemaVersion, "Aggregate schema version");
+    const storageVersion = requireVersion(value.storageVersion, "Storage version");
+    const minimumStorageVersion = requireVersion(value.minimumStorageVersion, "Minimum storage migration version");
+    if (minimumStorageVersion > storageVersion) {
+        throw new Error("Minimum storage migration version cannot exceed the current storage version.");
+    }
     return {
         version,
         controllerProtocolVersion,
-        storageLayoutVersion,
-        aggregateSchemaVersion
+        storageVersion,
+        minimumStorageVersion
     };
 }
 /** Managed continuity is a protocol/storage contract, not a package pin. */
 function assertContinuityIdentity(label, expected, actual) {
     for (const field of [
         "controllerProtocolVersion",
-        "storageLayoutVersion",
-        "aggregateSchemaVersion"
+        "storageVersion"
     ]) {
         if (expected[field] !== actual[field]) {
             throw new Error(`${label} ${field} does not match the frozen control plane `
@@ -442,8 +192,7 @@ function assertControllerContinuityIdentity(status, expected) {
         throw new Error("Controller version is invalid at the managed continuity gate.");
     }
     assertControllerField(status.protocolVersion, expected.controllerProtocolVersion, "protocol");
-    assertControllerField(status.storageLayoutVersion, expected.storageLayoutVersion, "storage layout");
-    assertControllerField(status.aggregateSchemaVersion, expected.aggregateSchemaVersion, "aggregate schema");
+    assertControllerField(status.storageVersion, expected.storageVersion, "storage version");
 }
 function assertControllerField(actual, expected, label) {
     if (actual !== expected) {
@@ -459,16 +208,6 @@ function assertSamePath(expected, actual, label) {
         throw new Error(`${label} does not match the frozen control plane (expected ${expected}, found ${normalized}).`);
     }
 }
-function assertEnvironment(expected, actual, label) {
-    if (actual !== expected) {
-        throw new Error(`${label} does not match the exact Task runtime descriptor.`);
-    }
-}
-function assertOptionalEnvironment(expected, actual, label) {
-    if (actual !== expected) {
-        throw new Error(`${label} does not match the exact Task runtime descriptor.`);
-    }
-}
 function parseDescriptorRecord(value) {
     let parsed;
     try {
@@ -487,19 +226,6 @@ function assertDescriptorKind(value, expected) {
             + `${typeof value.kind === "string" ? value.kind : "unknown"}.`);
     }
 }
-function requireAdapter(value) {
-    if (value !== "codex" && value !== "claude") {
-        throw new Error("Agent adapter id is invalid.");
-    }
-    return value;
-}
-function requireIdentity(value, label) {
-    const text = requireText(value, label).trim();
-    if (text.length === 0 || text.length > 1_024 || text.includes("\0")) {
-        throw new Error(`${label} is invalid.`);
-    }
-    return text;
-}
 function requireText(value, label) {
     if (typeof value !== "string" || value.length === 0 || value.includes("\0")) {
         throw new Error(`${label} is invalid.`);

package/dist/runtime/firstProgressAdvisory.js

@@ -4,7 +4,7 @@ export function projectFirstProgressAdvisory(input) {
         : [...(input.sessions.history ?? []), ...Object.values(input.sessions.sessions)]
             .sort((left, right) => left.createdAt.localeCompare(right.createdAt));
     const unique = [...new Map(sessions.map((session) => [
-            `${session.nativeSessionId}\0${session.launchId ?? ""}`,
+            `${session.nativeSessionId}\0${session.runtimeGenerationId ?? ""}`,
             session
         ])).values()];
     const firstGenerationAt = unique[0]?.createdAt;

package/dist/runtime/index.js

@@ -5,7 +5,7 @@ export { createRuntimeBinding } from "./runtimeBinding.js";
 export { normalizeRuntimeOwner } from "./runtimeOwner.js";
 export { createSessionLaunchRequest } from "./sessionLaunchRequest.js";
 export { DEFAULT_RECENT_TURN_ID_LIMIT, hasRecentTurnId, rememberRecentTurnId, validateRecentTurnIds } from "./recentTurnIds.js";
-export { RuntimeHostContentionError, RuntimeLaunchError } from "./ports.js";
+export { RuntimeGenerationMismatchError, RuntimeHostContentionError, RuntimeLaunchError } from "./ports.js";
 export { AgentHostPromptPushAdapter, TmuxSessionHost } from "./tmuxAdapters.js";
 export { FileTaskRuntimeIsolation, YUI_TASK_RUNTIME_ISOLATION_DESCRIPTOR, YUI_TASK_RUNTIME_SERVICE_NAMESPACE, assertTaskRuntimeIsolationPreflight, createTaskRuntimeIsolationDescriptor, parseTaskRuntimeIsolationDescriptor, planTaskRuntimeCleanup, taskRuntimeIsolationEnvironment, taskRuntimeIsolationFingerprint } from "./taskRuntimeIsolation.js";
 export { createSessionOwnerIdentity, discoverProviderRootByLaunchEnv, isLinuxProcessLive, listLaunchFencedProcesses, listOwnedProcessTree, readLinuxProcessIdentity } from "./sessionOwnerIdentity.js";

package/dist/runtime/launchBroker.js

@@ -17,30 +17,30 @@ export class LaunchBroker {
     #reservations = new Map();
     reserve(payload) {
         validatePayload(payload);
-        if (this.#reservations.has(payload.launchId)) {
-            throw new Error(`Launch payload is already reserved: ${payload.launchId}.`);
+        if (this.#reservations.has(payload.runtimeGenerationId)) {
+            throw new Error(`Launch payload is already reserved: ${payload.runtimeGenerationId}.`);
         }
         const ticket = randomBytes(32).toString("hex");
-        this.#reservations.set(payload.launchId, Object.freeze({
+        this.#reservations.set(payload.runtimeGenerationId, Object.freeze({
             ticket,
             payload,
             createdAt: Date.now()
         }));
-        return Object.freeze({ launchId: payload.launchId, ticket });
+        return Object.freeze({ runtimeGenerationId: payload.runtimeGenerationId, ticket });
     }
-    redeem(launchId, ticket) {
-        const reservation = this.#reservations.get(launchId);
+    redeem(runtimeGenerationId, ticket) {
+        const reservation = this.#reservations.get(runtimeGenerationId);
         if (reservation === undefined || reservation.ticket !== ticket) {
             throw new Error("Launch ticket is invalid or already consumed.");
         }
-        this.#reservations.delete(launchId);
+        this.#reservations.delete(runtimeGenerationId);
         if (Date.now() - reservation.createdAt > AGENT_HOST_LAUNCH_TICKET_TTL_MS) {
             throw new Error("Launch ticket expired before redemption.");
         }
         return reservation.payload;
     }
-    revoke(launchId) {
-        this.#reservations.delete(launchId);
+    revoke(runtimeGenerationId) {
+        this.#reservations.delete(runtimeGenerationId);
     }
     pendingCount() {
         return this.#reservations.size;
@@ -53,9 +53,9 @@ export function validateAgentHostLaunchPayload(value) {
     return validatePayload(value);
 }
 function validatePayload(payload) {
-    if (payload.schemaVersion !== 1)
+    if (payload.schemaVersion !== 2)
         throw new Error("Agent Host launch payload version is invalid.");
-    text(payload.launchId, "launchId");
+    text(payload.runtimeGenerationId, "runtimeGenerationId");
     text(payload.command, "command");
     text(payload.cwd, "cwd");
     if (!Array.isArray(payload.args))

package/dist/runtime/lifecycleReservation.js

@@ -33,11 +33,11 @@ export function runtimeLifecycleSignalKey(owner) {
         ? `role:${encodeURIComponent(owner.taskId)}/${encodeURIComponent(owner.roleName)}`
         : `global-role:${encodeURIComponent(owner.roleName)}`;
 }
-export function isRuntimeLaunchReservation(processing, launchId) {
+export function isRuntimeLaunchReservation(processing, runtimeGenerationId) {
     return processing?.owner === RUNTIME_LIFECYCLE_OWNER
         && processing.batch.reasons.length === 1
         && processing.batch.reasons[0] === RUNTIME_LAUNCH_RESERVED_REASON
-        && (launchId === undefined || processing.batchId === launchId);
+        && (runtimeGenerationId === undefined || processing.batchId === runtimeGenerationId);
 }
 export function hasRuntimeLaunchReservation(mailbox) {
     return isRuntimeLaunchReservation(mailbox?.processing);

package/dist/runtime/managedCaller.js

@@ -0,0 +1,111 @@
+import { createHash } from "node:crypto";
+import { activeRoleAgentBinding } from "../role/role.js";
+/** Per-process credential injected at native Session launch. */
+export const MANAGED_CALLER_KEY_ENV = "YUI_JOB_CALLER_KEY";
+/**
+ * A managed Session presented valid self-identity but is no longer the current
+ * runtime of its Task Role. This is a bounded diagnosis rather than a bare
+ * denial: the Agent can still read current state and decide whether to re-read,
+ * hand back, or stop.
+ */
+export class ManagedRuntimeDriftError extends Error {
+    name = "ManagedRuntimeDriftError";
+    constructor(message) {
+        super(message);
+    }
+}
+/** Reads the process's own immutable managed identity, or undefined when unmanaged. */
+export function managedTaskSessionIdentity(environment) {
+    const env = environment ?? {};
+    if (env.YUI_SESSION_SCOPE !== "task")
+        return undefined;
+    const taskId = identity(env.YUI_TASK_ID);
+    const roleName = identity(env.YUI_ROLE);
+    if (taskId === undefined || roleName === undefined) {
+        throw new ManagedRuntimeDriftError("Managed Task Session identity is incomplete: YUI_TASK_ID and YUI_ROLE are required.");
+    }
+    const workspace = identity(env.YUI_WORKSPACE);
+    const callerKey = identity(env[MANAGED_CALLER_KEY_ENV]);
+    return Object.freeze({
+        taskId,
+        roleName,
+        ...(workspace === undefined ? {} : { workspace }),
+        ...(callerKey === undefined ? {} : { callerKey })
+    });
+}
+/**
+ * Resolves the current runtime authority for a managed Task Session, or
+ * undefined for an unmanaged (plain user) invocation. Throws only when the
+ * process claims managed identity that durable state no longer recognizes.
+ */
+export function resolveManagedTaskCaller(store, environment) {
+    const self = managedTaskSessionIdentity(environment);
+    if (self === undefined)
+        return undefined;
+    return requireCurrentRuntime(store, self);
+}
+/** Same as resolveManagedTaskCaller, but requires a managed Task Session. */
+export function requireManagedTaskCaller(store, environment) {
+    const caller = resolveManagedTaskCaller(store, environment);
+    if (caller === undefined) {
+        throw new ManagedRuntimeDriftError("This command requires a managed Task Session.");
+    }
+    return caller;
+}
+/**
+ * The current runtime authority for one Task Role, or undefined. Used by
+ * command authorization that must not fail the whole invocation, only decline
+ * one privileged effect.
+ */
+export function currentManagedRuntime(store, environment, taskId, roleName) {
+    let caller;
+    try {
+        caller = resolveManagedTaskCaller(store, environment);
+    }
+    catch {
+        return undefined;
+    }
+    if (caller === undefined || caller.taskId !== taskId)
+        return undefined;
+    if (roleName !== undefined && caller.roleName !== roleName)
+        return undefined;
+    return caller;
+}
+function requireCurrentRuntime(store, self) {
+    const role = store.getRole(self.taskId, self.roleName);
+    if (role === null) {
+        throw new ManagedRuntimeDriftError(`This managed Session belongs to ${self.taskId}/${self.roleName}, which no longer exists. `
+            + "A new Session must be launched to act on this Task.");
+    }
+    const agentId = role.activeAgentId;
+    if (self.callerKey === undefined) {
+        throw new ManagedRuntimeDriftError(`This managed Session carries no ${MANAGED_CALLER_KEY_ENV}, so it cannot be recognized `
+            + `as the current runtime of ${self.taskId}/${self.roleName}.`);
+    }
+    const expectedHash = store.getJobCallerKeyHash(self.taskId, self.roleName, agentId);
+    if (expectedHash === null
+        || createHash("sha256").update(self.callerKey).digest("hex") !== expectedHash) {
+        throw new ManagedRuntimeDriftError(`This managed Session is no longer the current runtime of ${self.taskId}/${self.roleName} `
+            + `(the Role now runs Agent ${agentId}). Its native Session was replaced or its Role was `
+            + "rebound, so its durable caller key no longer matches. Nothing was changed. Read the "
+            + `current state with \`yui task show ${self.taskId}\`; acting requires the Session Yui `
+            + "launched for the current runtime.");
+    }
+    const activeTurn = store.getActiveTurn(self.taskId, self.roleName);
+    return Object.freeze({
+        taskId: self.taskId,
+        roleName: self.roleName,
+        agentId,
+        adapterId: activeRoleAgentBinding(role).adapterId,
+        ...(self.workspace === undefined ? {} : { workspace: self.workspace }),
+        ...(activeTurn === null || activeTurn.status !== "active"
+            ? {}
+            : { currentTurnId: activeTurn.id })
+    });
+}
+function identity(value) {
+    if (typeof value !== "string" || value.includes("\0"))
+        return undefined;
+    const normalized = value.trim();
+    return normalized.length === 0 || normalized !== value ? undefined : normalized;
+}

package/dist/runtime/ports.js

@@ -1,13 +1,13 @@
 /** A persisted launch is either temporarily unavailable or permanently lost. */
 export class RuntimeLaunchError extends Error {
     retryable;
-    launchId;
+    runtimeGenerationId;
     reason;
     name = "RuntimeLaunchError";
-    constructor(retryable, launchId, message, reason) {
+    constructor(retryable, runtimeGenerationId, message, reason) {
         super(message);
         this.retryable = retryable;
-        this.launchId = launchId;
+        this.runtimeGenerationId = runtimeGenerationId;
         this.reason = reason;
     }
 }
@@ -20,3 +20,16 @@ export class RuntimeHostContentionError extends Error {
         this.reason = reason;
     }
 }
+/** A reused Agent Host acknowledged a different runtime generation. */
+export class RuntimeGenerationMismatchError extends Error {
+    expectedRuntimeGenerationId;
+    observedRuntimeGenerationId;
+    hostState;
+    name = "RuntimeGenerationMismatchError";
+    constructor(expectedRuntimeGenerationId, observedRuntimeGenerationId, hostState, message) {
+        super(message);
+        this.expectedRuntimeGenerationId = expectedRuntimeGenerationId;
+        this.observedRuntimeGenerationId = observedRuntimeGenerationId;
+        this.hostState = hostState;
+    }
+}

package/dist/runtime/preallocatedNativeSession.js

@@ -2,10 +2,10 @@ import { createHash } from "node:crypto";
 import { resolve } from "node:path";
 import { requireText } from "./validation.js";
 /** Deterministic native identity preallocated for one exact provider launch. */
-export function nativeSessionIdForLaunch(home, launchId, agentId, adapterId) {
+export function nativeSessionIdForLaunch(home, runtimeGenerationId, agentId, adapterId) {
     const hex = createHash("sha256").update(JSON.stringify([
         resolve(requireText(home, "YUI_HOME")),
-        requireText(launchId, "Launch id"),
+        requireText(runtimeGenerationId, "Runtime generation id"),
         requireText(agentId, "Agent id"),
         requireText(adapterId, "Agent adapter id")
     ])).digest("hex");