@zq-silk/yui 0.6.16 → 0.7.0

package/dist/runtime/runtimeObservation.js

@@ -274,8 +274,12 @@ function normalizePayload(kind, input) {
         if (!["model", "tool", "subagent", "provider", "resource"].includes(input.activity ?? "")) {
             throw new Error("activity.observed requires an activity kind.");
         }
-        if (input.usage !== undefined)
-            validateUsage(input.usage);
+        if (input.usage !== undefined) {
+            const usage = input.usage;
+            validateUsage(usage.semantics === undefined
+                ? { ...usage, semantics: "cumulative-session" }
+                : usage);
+        }
     }
     if (kind === "observer.health") {
         requireIdentity(input.sourceId, "Runtime observer source id");
@@ -339,7 +343,12 @@ function normalizePayload(kind, input) {
         ...(input.activityId === undefined
             ? {}
             : { activityId: requireIdentity(input.activityId, "Runtime activity id") }),
-        ...(input.usage === undefined ? {} : { usage: Object.freeze({ ...input.usage }) }),
+        ...(input.usage === undefined
+            ? {}
+            : { usage: Object.freeze({
+                    ...input.usage,
+                    semantics: input.usage.semantics ?? "cumulative-session"
+                }) }),
         ...(observerSource === undefined ? {} : { observerSource }),
         ...(input.sourceId === undefined
             ? {}
@@ -468,7 +477,10 @@ function normalizeFailure(input) {
             : { lastOutput: requireText(input.lastOutput, "Runtime failure last output") }),
         ...(input.runTerminal === undefined
             ? {}
-            : { runTerminal: requireBoolean(input.runTerminal, "Runtime failure runTerminal") })
+            : { runTerminal: requireBoolean(input.runTerminal, "Runtime failure runTerminal") }),
+        ...(input.retryAfterMs === undefined
+            ? {}
+            : { retryAfterMs: requirePositiveMilliseconds(input.retryAfterMs) })
     });
 }
 function requireBoolean(value, label) {
@@ -476,9 +488,18 @@ function requireBoolean(value, label) {
         throw new Error(`${label} must be boolean.`);
     return value;
 }
+function requirePositiveMilliseconds(value) {
+    if (!Number.isSafeInteger(value) || value <= 0) {
+        throw new Error("Runtime failure retryAfterMs must be a positive safe integer.");
+    }
+    return value;
+}
 function validateUsage(input) {
-    for (const [name, value] of Object.entries(input)) {
-        if (!Number.isSafeInteger(value) || value < 0) {
+    if (!["cumulative-session", "request-context", "remaining-context"].includes(input.semantics)) {
+        throw new Error("Runtime usage semantics are invalid.");
+    }
+    for (const [name, value] of Object.entries(input).filter(([name]) => name !== "semantics")) {
+        if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 0) {
             throw new Error(`Runtime usage ${name} must be a non-negative safe integer.`);
         }
     }

package/dist/runtime/runtimeProjection.js

@@ -489,10 +489,13 @@ function next(current, patch) {
     });
 }
 function usageAdvanced(previous, current) {
+    if (current.semantics === "remaining-context")
+        return false;
+    if (current.semantics === "request-context")
+        return usageTotal(current) > 0;
     // A first cumulative snapshot may contain history from a resumed native
-    // Session. It establishes the generation baseline but cannot prove that
-    // tokens were consumed during the current observation window.
-    if (previous === undefined)
+    // Session. It establishes a baseline but cannot prove current progress.
+    if (previous === undefined || previous.semantics !== "cumulative-session")
         return false;
     return usageTotal(current) > usageTotal(previous);
 }

package/dist/runtime/runtimeStopReceipt.js

@@ -0,0 +1,42 @@
+import { createHash } from "node:crypto";
+import { chmodSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+export function writeRuntimeStopReceipt(home, launchId, requestedAt) {
+    const receipt = Object.freeze({
+        schemaVersion: 1,
+        receiptId: `runtime-stop-${createHash("sha256")
+            .update(`${launchId}\0${requestedAt.toISOString()}`)
+            .digest("hex")}`,
+        launchId,
+        requestedAt: requestedAt.toISOString()
+    });
+    const path = stopReceiptPath(home, launchId);
+    mkdirSync(resolve(join(home, "runtime", "stop-receipts")), { recursive: true, mode: 0o700 });
+    const temporary = `${path}.tmp-${process.pid}`;
+    writeFileSync(temporary, `${JSON.stringify(receipt)}\n`, { mode: 0o600 });
+    renameSync(temporary, path);
+    chmodSync(path, 0o600);
+    return receipt;
+}
+export function readRuntimeStopReceipt(home, launchId) {
+    try {
+        const value = JSON.parse(readFileSync(stopReceiptPath(home, launchId), "utf8"));
+        if (value.schemaVersion !== 1 || value.launchId !== launchId
+            || typeof value.receiptId !== "string" || !Number.isFinite(Date.parse(value.requestedAt))) {
+            throw new Error("Runtime stop receipt is invalid.");
+        }
+        return Object.freeze({ ...value });
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return null;
+        throw error;
+    }
+}
+export function removeRuntimeStopReceipt(home, launchId) {
+    rmSync(stopReceiptPath(home, launchId), { force: true });
+}
+function stopReceiptPath(home, launchId) {
+    const name = createHash("sha256").update(launchId).digest("hex");
+    return resolve(join(home, "runtime", "stop-receipts", `${name}.json`));
+}

package/dist/runtime/sessionTerminationGuard.js

@@ -20,6 +20,19 @@ export async function terminateSessionOwners(owner, records, ports, options = {}
     const pollMs = positiveDuration(options.pollMs, DEFAULT_TERMINATION_POLL_MS, "pollMs");
     const now = ports.now();
     ports.emit({ stage: "stop-requested", owner, at: now });
+    // Persist one exact launch receipt before any graceful stop can kill the
+    // Host. The owner-wide event remains for compatibility and summary display.
+    for (const record of records) {
+        ports.emit({
+            stage: "stop-requested",
+            owner,
+            launchId: record.launchId,
+            ...(record.nativeSessionId === undefined
+                ? {}
+                : { nativeSessionId: record.nativeSessionId }),
+            at: now
+        });
+    }
     // A launch-fence scan is a point-in-time observation, not a durable owner
     // inventory: /proc entries can disappear between the directory and
     // environment reads. Retain every exact child identity observed during the

package/dist/runtime/tmuxAdapters.js

@@ -1,10 +1,13 @@
 import { randomUUID } from "node:crypto";
+import { fileURLToPath } from "node:url";
+import { resolve } from "node:path";
 import { createRuntimeBinding } from "./runtimeBinding.js";
 import { normalizeRuntimeOwner } from "./runtimeOwner.js";
-import { RuntimeHostContentionError, RuntimeLaunchError } from "./ports.js";
-import { toRuntimeLaunchFailure, hasFatalLaunchOutput } from "./launchDiagnostics.js";
-import { builtinAgentDriverRegistry } from "./builtinAgentDrivers.js";
+import { RuntimeHostContentionError } from "./ports.js";
+import { toRuntimeLaunchFailure } from "./launchDiagnostics.js";
 import { requireSafeIdentity } from "./validation.js";
+import { launchBrokerForHome } from "./launchBroker.js";
+import { AGENT_HOST_CONTROL_PROTOCOL, sendAgentHostLaunchControl } from "./agentHost.js";
 const DEFAULT_INACTIVITY_TIMEOUT_MS = 300_000;
 /**
  * Runtime lifecycle adapter for the current tmux host. The returned hostRef is
@@ -163,16 +166,74 @@ export class TmuxSessionHost {
         if (writableHumanAttached) {
             throw new RuntimeHostContentionError("writable-client", `A writable human is attached to ${request.owner.taskId}/${request.owner.roleName}.`);
         }
-        if (request.owner.scope === "task"
-            && request.adapterId === "claude"
-            && request.runId !== undefined
-            && await probeRoleStatus(this.tmux, hostId, request.owner.roleName) === "running") {
-            // Managed Claude is process-per-Run. A live Role window here belongs to
-            // an earlier process (or to recovery of the exact reserved Run); never
-            // plan, persist pre-start state, or inject input into it. The coordinator
-            // decides between same-generation recovery and a retry after natural
-            // exit from the durable reservation identity.
-            return createRuntimeBinding({
+        const input = {
+            roleName: request.owner.roleName,
+            agentId: request.agentId,
+            adapterId: request.adapterId,
+            effective: request.effective,
+            launchId: request.launchId,
+            mode: request.mode,
+            ...(request.runId === undefined ? {} : { runId: request.runId }),
+            ...(request.runtimeIsolation === undefined
+                ? {}
+                : { runtimeIsolation: request.runtimeIsolation }),
+            ...(request.environment === undefined
+                ? {}
+                : { environment: request.environment }),
+            ...(request.mode === "resume" ? { nativeSessionId: request.nativeSessionId } : {})
+        };
+        const planned = request.owner.scope === "task"
+            ? this.planner.plan({ taskId: request.owner.taskId, ...input })
+            : this.planner.planGlobalRole(input);
+        if (planned.role.name !== request.owner.roleName) {
+            throw new Error("Planned Role does not match the runtime owner.");
+        }
+        if (planned.role.workspace !== request.workspace) {
+            throw new Error("Planned Role workspace does not match the runtime request.");
+        }
+        const launchContext = diagnosticContext(request, planned);
+        if (this.#validateLaunch !== undefined) {
+            try {
+                await this.#validateLaunch(request);
+            }
+            catch (error) {
+                throw toRuntimeLaunchFailure(error, "validation", launchContext);
+            }
+        }
+        const plannedNativeSessionId = planned.session?.nativeSessionId;
+        if (request.mode === "resume"
+            && plannedNativeSessionId !== undefined
+            && plannedNativeSessionId !== request.nativeSessionId) {
+            throw new Error("Planned native session does not match the resume request.");
+        }
+        const nativeSessionId = plannedNativeSessionId
+            ?? (request.mode === "resume" ? request.nativeSessionId : undefined);
+        beforeHostStart?.({
+            owner: request.owner,
+            launchId: request.launchId,
+            ...(request.runId === undefined ? {} : { runId: request.runId }),
+            agentId: request.agentId,
+            adapterId: request.adapterId,
+            effective: request.effective,
+            ...(nativeSessionId === undefined ? {} : { nativeSessionId }),
+            ...(planned.initialPromptRunId === undefined
+                ? {}
+                : { initialPromptRunId: planned.initialPromptRunId })
+        });
+        const yuiHome = planned.launch.env.YUI_HOME;
+        const childLifecycle = planned.launch.childLifecycle;
+        // Custom/legacy planners do not yet expose the Agent Host contract. Keep
+        // their direct launch behavior for compatibility while all built-in
+        // managed Roles use the persistent Host below.
+        if (yuiHome === undefined || childLifecycle === undefined) {
+            let hostCreated;
+            try {
+                hostCreated = await ensureRoleWindow(this.tmux, hostId, planned.role, planned.launch);
+            }
+            catch (error) {
+                throw toRuntimeLaunchFailure(error, "host-start", launchContext);
+            }
+            let binding = createRuntimeBinding({
                 id: bindingId,
                 launchId: request.launchId,
                 owner: request.owner,
@@ -183,31 +244,99 @@ export class TmuxSessionHost {
                     hostId,
                     roleName: request.owner.roleName
                 }),
-                hostCreated: false,
-                ...(request.mode === "resume"
-                    ? { nativeSessionId: request.nativeSessionId }
-                    : {})
+                hostCreated,
+                ...(hostCreated && planned.initialPromptRunId !== undefined
+                    ? { initialPromptRunId: planned.initialPromptRunId }
+                    : {}),
+                ...(nativeSessionId === undefined ? {} : { nativeSessionId })
             });
-        }
-        const { planned, nativeSessionId } = planManagedLaunch(this.planner, request, beforeHostStart);
-        const launchContext = diagnosticContext(request, planned);
-        if (this.#validateLaunch !== undefined) {
-            try {
-                await this.#validateLaunch(request);
-            }
-            catch (error) {
-                throw toRuntimeLaunchFailure(error, "validation", launchContext);
+            if (hostCreated) {
+                const pane = await inspectRolePane(this.tmux, hostId, request.owner.roleName);
+                if (pane?.dead === true) {
+                    await deadHostLaunchFailure(this.tmux, hostId, request.owner.roleName, pane, launchContext);
+                }
+                if (request.mode === "new"
+                    && request.owner.scope === "task"
+                    && request.runId !== undefined
+                    && planned.initialPromptRunId === request.runId
+                    && this.#waitForNativeSession !== undefined) {
+                    binding = createRuntimeBinding({
+                        ...binding,
+                        nativeSessionId: await this.waitForNativeSessionDiscovery(request, hostId, launchContext)
+                    });
+                }
+                if (pane !== undefined)
+                    this.#onHostCreated?.({ binding, pane });
             }
+            return binding;
         }
-        // Process creation is last: every local invariant has already passed.
+        const broker = launchBrokerForHome(yuiHome);
+        const reservation = broker.reserve(Object.freeze({
+            schemaVersion: 1,
+            launchId: request.launchId,
+            command: planned.launch.command,
+            args: [...planned.launch.args],
+            environment: { ...planned.launch.env },
+            cwd: planned.role.cwd ?? planned.role.workspace,
+            childLifecycle,
+            startMode: planned.launch.deferProviderStart === true ? "idle" : "provider",
+            ...(planned.launch.providerInput === undefined
+                ? {}
+                : { providerInput: planned.launch.providerInput })
+        }));
+        const hostLaunch = {
+            command: process.execPath,
+            args: [
+                fileURLToPath(new URL("../cli.js", import.meta.url)),
+                "internal",
+                "agent-host",
+                reservation.launchId,
+                reservation.ticket
+            ],
+            env: {
+                YUI_HOME: resolve(yuiHome),
+                YUI_SESSION_SCOPE: request.owner.scope,
+                ...(request.owner.scope === "task" ? { YUI_TASK_ID: request.owner.taskId } : {}),
+                YUI_ROLE: request.owner.roleName,
+                YUI_LAUNCH_ID: request.launchId
+            }
+        };
         let hostCreated;
+        let providerChildLaunched = false;
+        let launchPromptAlreadySubmitted = false;
         try {
-            hostCreated = await ensureRoleWindow(this.tmux, hostId, planned.role, planned.launch);
+            hostCreated = await ensureRoleWindow(this.tmux, hostId, planned.role, hostLaunch);
+            providerChildLaunched = hostCreated && planned.launch.deferProviderStart !== true;
+            if (!hostCreated) {
+                const controlResult = await sendAgentHostLaunchControl({
+                    home: yuiHome,
+                    scope: request.owner.scope,
+                    ...(request.owner.scope === "task" ? { taskId: request.owner.taskId } : {}),
+                    roleName: request.owner.roleName,
+                    control: {
+                        protocol: AGENT_HOST_CONTROL_PROTOCOL,
+                        type: "launch",
+                        launchId: reservation.launchId,
+                        ticket: reservation.ticket
+                    }
+                });
+                if (controlResult !== "accepted") {
+                    broker.revoke(request.launchId);
+                    launchPromptAlreadySubmitted = controlResult === "active-same-launch";
+                    if (childLifecycle === "per-turn" && controlResult === "active-other-launch") {
+                        throw new RuntimeHostContentionError("provider-child-active", `The persistent Agent Host for ${request.owner.roleName} still owns another Provider turn.`);
+                    }
+                }
+                else {
+                    providerChildLaunched = planned.launch.deferProviderStart !== true;
+                }
+            }
         }
         catch (error) {
-            throw toRuntimeLaunchFailure(error, "host-start", launchContext);
+            broker.revoke(request.launchId);
+            throw error;
         }
-        if (hostCreated
+        if (providerChildLaunched
             && request.owner.scope === "task"
             && planned.launch.env.YUI_JOB_CALLER_KEY !== undefined
             && this.planner.commitTaskCallerKey !== undefined) {
@@ -218,7 +347,7 @@ export class TmuxSessionHost {
                 callerKey: planned.launch.env.YUI_JOB_CALLER_KEY
             });
         }
-        let binding = createRuntimeBinding({
+        const binding = createRuntimeBinding({
             id: bindingId,
             launchId: request.launchId,
             owner: request.owner,
@@ -230,218 +359,66 @@ export class TmuxSessionHost {
                 roleName: request.owner.roleName
             }),
             hostCreated,
-            ...(hostCreated && planned.initialPromptRunId !== undefined
+            ...(providerChildLaunched && hostCreated && planned.initialPromptRunId !== undefined
                 ? { initialPromptRunId: planned.initialPromptRunId }
                 : {}),
+            ...((launchPromptAlreadySubmitted || (providerChildLaunched && !hostCreated))
+                && planned.initialPromptRunId !== undefined
+                ? { launchPromptUncertainRunId: planned.initialPromptRunId }
+                : {}),
             ...(nativeSessionId === undefined ? {} : { nativeSessionId })
         });
-        if (hostCreated) {
-            let pane;
-            try {
-                pane = await inspectRolePane(this.tmux, hostId, request.owner.roleName);
-            }
-            catch (error) {
-                throw toRuntimeLaunchFailure(error, "host-started", launchContext);
-            }
-            if (pane === undefined) {
-                throw toRuntimeLaunchFailure(new Error("Managed host pane could not be inspected after creation."), "host-started", launchContext);
-            }
-            this.#onHostCreated?.({ binding, pane });
-            if (pane.dead) {
-                await deadHostLaunchFailure(this.tmux, hostId, request.owner.roleName, pane, launchContext);
-            }
-            if (requiresNativeSessionDiscovery(request, planned, this.#waitForNativeSession)) {
-                const discoveredNativeSessionId = await this.waitForNativeSessionDiscovery(request, hostId, launchContext, pane);
-                binding = createRuntimeBinding({
-                    ...binding,
-                    nativeSessionId: discoveredNativeSessionId
-                });
-            }
-            this.#onHostCreated?.({ binding, pane });
+        if (hostCreated && this.#onHostCreated !== undefined) {
+            const pane = await inspectRolePane(this.tmux, hostId, request.owner.roleName);
+            if (pane !== undefined)
+                this.#onHostCreated({ binding, pane });
         }
         return binding;
     }
-    async waitForNativeSessionDiscovery(request, hostId, context, pane) {
-        if (this.#waitForNativeSession === undefined) {
-            throw new Error("Native session discovery is not configured.");
-        }
+    async waitForNativeSessionDiscovery(request, hostId, context) {
         const controller = new AbortController();
         const discovery = this.#waitForNativeSession(request, controller.signal);
-        // The losing branch of the race rejects when the controller aborts; keep
-        // that rejection handled so a settled launch does not surface it later.
         discovery.catch(() => undefined);
+        let stopped = false;
+        let lastContent = "";
+        let lastActivityAt = Date.now();
+        const monitor = (async () => {
+            while (!stopped) {
+                await new Promise((resolve) => setTimeout(resolve, Math.min(1_000, this.#inactivityTimeoutMs)));
+                const pane = await inspectRolePane(this.tmux, hostId, request.owner.roleName);
+                if (pane?.dead === true) {
+                    await deadHostLaunchFailure(this.tmux, hostId, request.owner.roleName, pane, context);
+                }
+                const content = this.tmux.captureRolePane?.(hostId, request.owner.roleName, 80) ?? "";
+                if (content !== lastContent) {
+                    lastContent = content;
+                    lastActivityAt = Date.now();
+                }
+                if (Date.now() - lastActivityAt >= this.#inactivityTimeoutMs) {
+                    throw new Error(`Agent produced no signal for ${this.#inactivityTimeoutMs}ms. `
+                        + "The process is alive but emitted no lifecycle hook, output, or exit.");
+                }
+            }
+            throw new Error("Native session discovery monitor stopped.");
+        })();
+        monitor.catch(() => undefined);
         try {
-            return await Promise.race([
-                discovery,
-                this.monitorPaneSignals(request, hostId, context, controller.signal)
-            ]);
+            return await Promise.race([discovery, monitor]);
         }
         catch (error) {
             try {
                 await stopExactRole(this.tmux, hostId, request.owner.roleName);
             }
             catch {
-                // The launch failure below is authoritative; durable owner cleanup
-                // remains responsible for a Provider that rejected immediate stop.
+                // Preserve the discovery failure; durable cleanup owns later retries.
             }
-            throw toRuntimeLaunchFailure(error, "native-session-discovery", {
-                ...context,
-                pane
-            });
+            throw toRuntimeLaunchFailure(error, "native-session-discovery", context);
         }
         finally {
+            stopped = true;
             controller.abort();
         }
     }
-    /**
-     * Monitors the managed pane for agent-emitted signals while native session
-     * discovery is pending. The agent's own behavior drives the outcome:
-     *
-     * - Pane death → failure with exit status and stderr (the agent exited).
-     * - Fatal output (auth, config, executable errors) → failure with the
-     *   agent's own error text.
-     * - No signal at all (no hook, no output change, no exit) for the
-     *   inactivity window → backstop failure.
-     *
-     * There is no fixed wall-clock timeout: a slow-but-active agent is never
-     * killed merely for taking too long to start.
-     */
-    async monitorPaneSignals(request, hostId, context, signal) {
-        let lastContent = "";
-        let lastActivityAt = Date.now();
-        while (!signal.aborted) {
-            await abortableDelay(PANE_SIGNAL_POLL_MS, signal);
-            let pane;
-            try {
-                pane = await inspectRolePane(this.tmux, hostId, request.owner.roleName);
-            }
-            catch {
-                // A tmux inspection hiccup must not fabricate a Provider death; the
-                // inactivity backstop remains the safety net.
-                continue;
-            }
-            if (pane !== undefined && pane.dead) {
-                await deadHostLaunchFailure(this.tmux, hostId, request.owner.roleName, pane, context);
-            }
-            let content = "";
-            try {
-                content = this.tmux.captureRolePane?.(hostId, request.owner.roleName, 80) ?? "";
-            }
-            catch {
-                // Capture is best-effort; pane death and hooks remain authoritative.
-            }
-            if (content !== lastContent) {
-                lastContent = content;
-                lastActivityAt = Date.now();
-                if (hasFatalLaunchOutput(content)) {
-                    throw toRuntimeLaunchFailure(new Error("Agent emitted a fatal error before native session discovery completed."), "native-session-discovery", {
-                        ...context,
-                        ...(pane !== undefined ? { pane } : {}),
-                        stderrTail: content
-                    });
-                }
-            }
-            if (Date.now() - lastActivityAt >= this.#inactivityTimeoutMs) {
-                throw new Error(`Agent produced no signal for ${this.#inactivityTimeoutMs}ms. `
-                    + "The process is alive but emitted no lifecycle hook, output, or exit.");
-            }
-        }
-        throw new Error("Native session discovery was aborted.");
-    }
-}
-function requiresNativeSessionDiscovery(request, planned, wait) {
-    return request.mode === "new"
-        && request.owner.scope === "task"
-        && request.runId !== undefined
-        && planned.initialPromptRunId === request.runId
-        && wait !== undefined
-        && builtinAgentDriverRegistry()
-            .requireByAdapterId(request.adapterId)
-            .capabilities.observation.sessionBootstrap === "discovered";
-}
-function positiveInteger(value, label) {
-    if (!Number.isSafeInteger(value) || value <= 0) {
-        throw new Error(`${label} must be a positive integer.`);
-    }
-    return value;
-}
-const PANE_SIGNAL_POLL_MS = 1_000;
-function abortableDelay(milliseconds, signal) {
-    return new Promise((resolve, reject) => {
-        if (signal.aborted) {
-            reject(new Error("Native session discovery was aborted."));
-            return;
-        }
-        const onAbort = () => {
-            clearTimeout(timer);
-            reject(new Error("Native session discovery was aborted."));
-        };
-        const timer = setTimeout(() => {
-            signal.removeEventListener("abort", onAbort);
-            resolve();
-        }, milliseconds);
-        signal.addEventListener("abort", onAbort, { once: true });
-    });
-}
-function planManagedLaunch(planner, request, beforeHostStart) {
-    try {
-        const input = {
-            roleName: request.owner.roleName,
-            agentId: request.agentId,
-            adapterId: request.adapterId,
-            effective: request.effective,
-            launchId: request.launchId,
-            mode: request.mode,
-            ...(request.runId === undefined ? {} : { runId: request.runId }),
-            ...(request.runtimeIsolation === undefined
-                ? {}
-                : { runtimeIsolation: request.runtimeIsolation }),
-            ...(request.environment === undefined
-                ? {}
-                : { environment: request.environment }),
-            ...(request.mode === "resume" ? { nativeSessionId: request.nativeSessionId } : {})
-        };
-        const planned = request.owner.scope === "task"
-            ? planner.plan({ taskId: request.owner.taskId, ...input })
-            : planner.planGlobalRole(input);
-        if (planned.role.name !== request.owner.roleName) {
-            throw new Error("Planned Role does not match the runtime owner.");
-        }
-        if (planned.role.workspace !== request.workspace) {
-            throw new Error("Planned Role workspace does not match the runtime request.");
-        }
-        const plannedNativeSessionId = planned.session?.nativeSessionId;
-        if (request.mode === "resume"
-            && plannedNativeSessionId !== undefined
-            && plannedNativeSessionId !== request.nativeSessionId) {
-            throw new Error("Planned native session does not match the resume request.");
-        }
-        const nativeSessionId = plannedNativeSessionId
-            ?? (request.mode === "resume" ? request.nativeSessionId : undefined);
-        beforeHostStart?.({
-            owner: request.owner,
-            launchId: request.launchId,
-            ...(request.runId === undefined ? {} : { runId: request.runId }),
-            agentId: request.agentId,
-            adapterId: request.adapterId,
-            effective: request.effective,
-            ...(nativeSessionId === undefined ? {} : { nativeSessionId }),
-            ...(planned.initialPromptRunId === undefined
-                ? {}
-                : { initialPromptRunId: planned.initialPromptRunId })
-        });
-        return { planned, nativeSessionId };
-    }
-    catch (error) {
-        if (error instanceof RuntimeLaunchError
-            || error instanceof RuntimeHostContentionError) {
-            throw error;
-        }
-        throw toRuntimeLaunchFailure(error, "validation", {
-            agentId: request.agentId,
-            cwd: request.workspace
-        });
-    }
 }
 function diagnosticContext(request, planned) {
     return {
@@ -490,6 +467,12 @@ async function ensureRoleWindow(tmux, hostId, role, launch) {
         ? tmux.ensureRoleWindow(hostId, role, launch)
         : tmux.ensureRoleWindowAsync(hostId, role, launch);
 }
+function positiveInteger(value, label) {
+    if (!Number.isSafeInteger(value) || value <= 0) {
+        throw new Error(`${label} must be a positive integer.`);
+    }
+    return value;
+}
 async function probeRoleStatus(tmux, hostId, roleName) {
     return tmux.probeRoleStatusAsync === undefined
         ? tmux.probeRoleStatus(hostId, roleName)