@zq-silk/yui 0.6.13 → 0.6.14

package/dist/runtime/tmuxAdapters.js

@@ -1,8 +1,11 @@
 import { randomUUID } from "node:crypto";
 import { createRuntimeBinding } from "./runtimeBinding.js";
 import { normalizeRuntimeOwner } from "./runtimeOwner.js";
-import { RuntimeHostContentionError } from "./ports.js";
+import { RuntimeHostContentionError, RuntimeLaunchError } from "./ports.js";
+import { toRuntimeLaunchFailure, hasFatalLaunchOutput } from "./launchDiagnostics.js";
+import { builtinAgentDriverRegistry } from "./builtinAgentDrivers.js";
 import { requireSafeIdentity } from "./validation.js";
+const DEFAULT_INACTIVITY_TIMEOUT_MS = 300_000;
 /**
  * Runtime lifecycle adapter for the current tmux host. The returned hostRef is
  * opaque to the domain and self-contained for a later inspect/stop operation.
@@ -13,6 +16,9 @@ export class TmuxSessionHost {
     #globalHostId;
     #createBindingId;
     #onHostCreated;
+    #validateLaunch;
+    #waitForNativeSession;
+    #inactivityTimeoutMs;
     #launchTails = new Map();
     constructor(planner, tmux, options = {}) {
         this.planner = planner;
@@ -20,6 +26,9 @@ export class TmuxSessionHost {
         this.#globalHostId = requireSafeIdentity(options.globalHostId ?? "operator", "Global tmux host id");
         this.#createBindingId = options.createBindingId ?? randomUUID;
         this.#onHostCreated = options.onHostCreated;
+        this.#validateLaunch = options.validateLaunch;
+        this.#waitForNativeSession = options.waitForNativeSession;
+        this.#inactivityTimeoutMs = positiveInteger(options.inactivityTimeoutMs ?? DEFAULT_INACTIVITY_TIMEOUT_MS, "Launch inactivity timeout");
     }
     async start(request, beforeHostStart) {
         return this.#launch(request, beforeHostStart);
@@ -180,6 +189,202 @@ export class TmuxSessionHost {
                     : {})
             });
         }
+        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);
+            }
+        }
+        // Process creation is last: every local invariant has already passed.
+        let hostCreated;
+        try {
+            hostCreated = await ensureRoleWindow(this.tmux, hostId, planned.role, planned.launch);
+        }
+        catch (error) {
+            throw toRuntimeLaunchFailure(error, "host-start", launchContext);
+        }
+        if (hostCreated
+            && request.owner.scope === "task"
+            && planned.launch.env.YUI_JOB_CALLER_KEY !== undefined
+            && this.planner.commitTaskCallerKey !== undefined) {
+            this.planner.commitTaskCallerKey({
+                taskId: request.owner.taskId,
+                roleName: request.owner.roleName,
+                agentId: request.agentId,
+                callerKey: planned.launch.env.YUI_JOB_CALLER_KEY
+            });
+        }
+        let binding = createRuntimeBinding({
+            id: bindingId,
+            launchId: request.launchId,
+            owner: request.owner,
+            agentId: request.agentId,
+            adapterId: request.adapterId,
+            hostRef: encodeHostRef({
+                scope: request.owner.scope,
+                hostId,
+                roleName: request.owner.roleName
+            }),
+            hostCreated,
+            ...(hostCreated && planned.initialPromptRunId !== undefined
+                ? { initialPromptRunId: 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 });
+        }
+        return binding;
+    }
+    async waitForNativeSessionDiscovery(request, hostId, context, pane) {
+        if (this.#waitForNativeSession === undefined) {
+            throw new Error("Native session discovery is not configured.");
+        }
+        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);
+        try {
+            return await Promise.race([
+                discovery,
+                this.monitorPaneSignals(request, hostId, context, controller.signal)
+            ]);
+        }
+        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.
+            }
+            throw toRuntimeLaunchFailure(error, "native-session-discovery", {
+                ...context,
+                pane
+            });
+        }
+        finally {
+            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,
@@ -197,8 +402,8 @@ export class TmuxSessionHost {
             ...(request.mode === "resume" ? { nativeSessionId: request.nativeSessionId } : {})
         };
         const planned = request.owner.scope === "task"
-            ? this.planner.plan({ taskId: request.owner.taskId, ...input })
-            : this.planner.planGlobalRole(input);
+            ? 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.");
         }
@@ -225,45 +430,42 @@ export class TmuxSessionHost {
                 ? {}
                 : { initialPromptRunId: planned.initialPromptRunId })
         });
-        // Process creation is last: every local invariant has already passed.
-        const hostCreated = await ensureRoleWindow(this.tmux, hostId, planned.role, planned.launch);
-        if (hostCreated
-            && request.owner.scope === "task"
-            && planned.launch.env.YUI_JOB_CALLER_KEY !== undefined
-            && this.planner.commitTaskCallerKey !== undefined) {
-            this.planner.commitTaskCallerKey({
-                taskId: request.owner.taskId,
-                roleName: request.owner.roleName,
-                agentId: request.agentId,
-                callerKey: planned.launch.env.YUI_JOB_CALLER_KEY
-            });
+        return { planned, nativeSessionId };
+    }
+    catch (error) {
+        if (error instanceof RuntimeLaunchError
+            || error instanceof RuntimeHostContentionError) {
+            throw error;
         }
-        const binding = createRuntimeBinding({
-            id: bindingId,
-            launchId: request.launchId,
-            owner: request.owner,
+        throw toRuntimeLaunchFailure(error, "validation", {
             agentId: request.agentId,
-            adapterId: request.adapterId,
-            hostRef: encodeHostRef({
-                scope: request.owner.scope,
-                hostId,
-                roleName: request.owner.roleName
-            }),
-            hostCreated,
-            ...(hostCreated && planned.initialPromptRunId !== undefined
-                ? { initialPromptRunId: planned.initialPromptRunId }
-                : {}),
-            ...(nativeSessionId === undefined ? {} : { nativeSessionId })
+            cwd: request.workspace
         });
-        if (hostCreated && this.#onHostCreated !== undefined) {
-            const pane = await inspectRolePane(this.tmux, hostId, request.owner.roleName);
-            if (pane !== undefined) {
-                this.#onHostCreated({ binding, pane });
-            }
-        }
-        return binding;
     }
 }
+function diagnosticContext(request, planned) {
+    return {
+        command: planned.launch.command,
+        argv: [planned.launch.command, ...planned.launch.args],
+        cwd: planned.role.cwd ?? planned.role.workspace,
+        agentId: request.agentId
+    };
+}
+async function deadHostLaunchFailure(tmux, hostId, roleName, pane, context) {
+    let stderrTail;
+    try {
+        stderrTail = tmux.captureRolePane?.(hostId, roleName, 80);
+    }
+    catch {
+        // The pane state is the required evidence; capture is best-effort.
+    }
+    throw toRuntimeLaunchFailure(new Error("Provider exited immediately after managed host start."), "host-started", {
+        ...context,
+        pane,
+        ...(pane.exitStatus === undefined ? {} : { exitStatus: pane.exitStatus }),
+        ...(stderrTail === undefined || stderrTail.length === 0 ? {} : { stderrTail })
+    });
+}
 /** Non-blocking receipt-backed tmux push; it never interprets provider output. */
 export class TmuxPromptPushAdapter {
     tmux;
@@ -294,17 +496,9 @@ async function probeRoleStatus(tmux, hostId, roleName) {
         : tmux.probeRoleStatusAsync(hostId, roleName);
 }
 async function inspectRolePane(tmux, hostId, roleName) {
-    try {
-        return tmux.inspectRolePaneAsync === undefined
-            ? tmux.inspectRolePane?.(hostId, roleName)
-            : await tmux.inspectRolePaneAsync(hostId, roleName);
-    }
-    catch {
-        // The pane may have exited between creation and inspection; the owner
-        // recorder treats a missing pane as a verification gap, not a launch
-        // failure.
-        return undefined;
-    }
+    return tmux.inspectRolePaneAsync === undefined
+        ? tmux.inspectRolePane?.(hostId, roleName)
+        : await tmux.inspectRolePaneAsync(hostId, roleName);
 }
 async function killRole(tmux, hostId, roleName) {
     if (tmux.killRoleAsync === undefined) {

package/dist/scheduler/activeRoleRunDelivery.js

@@ -5,8 +5,12 @@ import { markYuiRunInput } from "../run/runIdentity.js";
 import { taskRoleSessionTitle } from "../runtime/sessionTitle.js";
 import { effectiveLaunchSnapshotsCompatible, effectiveLaunchSnapshotsCompatibleForTaskMain } from "../executor/effectiveLaunch.js";
 import { RuntimeLaunchError } from "../runtime/ports.js";
+import { RuntimeLaunchFailure } from "../runtime/launchDiagnostics.js";
 import { builtinAgentDriverRegistry } from "../runtime/builtinAgentDrivers.js";
 import { mailboxHasWork, nextPendingBatch } from "../coordination/workMailbox.js";
+import { runtimeObservationFromTaskEvent } from "../runtime/runtimeObservation.js";
+import { projectProviderContinuations } from "../runtime/runtimeContinuationProjection.js";
+import { hasRuntimeLifecycleWork, RuntimeLifecycleBusyError, runtimeLifecycleTarget } from "../runtime/lifecycleReservation.js";
 /**
  * Delivers durable Work AgentRuns before liveness reconciliation. Task command
  * handlers only record intent; this Controller path is the sole automated
@@ -41,6 +45,24 @@ export async function processActiveRoleRunDeliveries(store, delivery, now, selec
                 });
                 continue;
             }
+            // Single-flight: a Role runtime lifecycle lane that already holds a
+            // launch reservation or cleanup obligation must not be entered by a
+            // second delivery. The Run stays active-unpushed and is retried after
+            // the lane settles; the contention is never terminalized as a failure.
+            if (hasRuntimeLifecycleWork(store.getWorkMailbox(runtimeLifecycleTarget({
+                scope: "task",
+                taskId: task.id,
+                roleName: role.name
+            })))) {
+                results.push({
+                    taskId: task.id,
+                    roleName: role.name,
+                    runId: run.id,
+                    status: "skipped",
+                    reason: "runtime-unavailable"
+                });
+                continue;
+            }
             const existingSession = store.getRoleSession(task.id, role.name, run.effective.agentId);
             const receiptId = formatAgentRunReceiptId(task.id, run.id);
             const target = { kind: "role", taskId: task.id, roleName: role.name };
@@ -235,6 +257,59 @@ export async function processActiveRoleRunDeliveries(store, delivery, now, selec
             }
             catch (error) {
                 const message = error instanceof Error ? error.message : String(error);
+                // Scheduler single-flight backpressure: the Role runtime lifecycle
+                // lane was busy when the launch was reserved. The Run stays
+                // active-unpushed and its mailbox claim is retained; the next pass
+                // retries after the lane settles. This is contention before any
+                // semantic launch, never a Run failure.
+                if (error instanceof RuntimeLifecycleBusyError) {
+                    delivery.forgetPrepared?.({
+                        taskId: task.id,
+                        roleName: role.name,
+                        runId: run.id
+                    });
+                    results.push({
+                        taskId: task.id,
+                        roleName: role.name,
+                        runId: run.id,
+                        status: "skipped",
+                        reason: "runtime-unavailable",
+                        error: message
+                    });
+                    continue;
+                }
+                if (error instanceof RuntimeLaunchFailure) {
+                    if (!deliveryAttempted) {
+                        delivery.forgetPrepared?.({
+                            taskId: task.id,
+                            roleName: role.name,
+                            runId: run.id,
+                            ...(prepared?.launchId === undefined
+                                ? {}
+                                : { launchId: prepared.launchId })
+                        });
+                        const persisted = store.saveExitedRoleRun({
+                            task,
+                            role,
+                            run,
+                            session: existingSession,
+                            summary: error.message,
+                            now
+                        });
+                        results.push({
+                            taskId: task.id,
+                            roleName: role.name,
+                            runId: run.id,
+                            status: "failed",
+                            reason: "launch-failed",
+                            error: persisted === "state-changed"
+                                ? "Run state changed during launch failure."
+                                : message,
+                            terminalized: persisted === "failed"
+                        });
+                        continue;
+                    }
+                }
                 if (error instanceof RuntimeLaunchError) {
                     const terminalFailure = roleRunDeliveryFailure(run, processing.batchId, existingSession, error.launchId);
                     if (error.retryable) {
@@ -472,7 +547,7 @@ async function processActiveRunContinuation(store, delivery, task, role, run, no
         }
         inputDelivery = claim.delivery;
         deliveryAttempted = true;
-        const text = continuationInput(task, role, run, inputDelivery.attemptId, inputDelivery.batch);
+        const text = continuationInput(task, role, run, inputDelivery.attemptId, inputDelivery.batch, boundedContinuationSummaries(store, task.id, inputDelivery.batch.refs));
         if (mode !== "followup") {
             const routed = await delivery.routeProviderInput({
                 delivery: ready,
@@ -607,7 +682,7 @@ async function reconcileStrandedInputDelivery(store, delivery, task, role, run,
         return uncertain(`Provider input readback failed: ${error instanceof Error ? error.message : String(error)}`);
     }
 }
-function continuationInput(task, role, run, attemptId, batch) {
+function continuationInput(task, role, run, attemptId, batch, resultSummaries) {
     const references = batch.refs.map((ref) => ("taskId" in ref
         ? `${ref.type}:${ref.taskId}/${ref.id}`
         : `${ref.type}:${ref.id}`));
@@ -618,9 +693,70 @@ function continuationInput(task, role, run, attemptId, batch) {
         "Do not create a new Yui Run merely because this is a new Provider Turn.",
         `Reasons: ${batch.reasons.join(", ")}.`,
         ...(batch.sources.length === 0 ? [] : [`Sources: ${batch.sources.join(", ")}.`]),
-        ...(references.length === 0 ? [] : [`References: ${references.join(", ")}.`])
+        ...(references.length === 0 ? [] : [`References: ${references.join(", ")}.`]),
+        ...(resultSummaries.length === 0
+            ? []
+            : [
+                "Native child results (bounded excerpts; read the referenced event for the full content):",
+                ...resultSummaries
+            ])
     ].join("\n"), run.id, taskRoleSessionTitle(task, role.name));
 }
+/**
+ * Issue 13: the parent prompt only ever sees a bounded excerpt of a native
+ * child result plus its durable event reference. The full content stays in
+ * the Task event log and is read on demand through `yui task event show`.
+ * This prevents an unbounded provider result from being re-injected into the
+ * parent Session on every continuation wake.
+ */
+const MAX_RESULT_SUMMARY_CHARS = 512;
+const MAX_RESULT_SUMMARY_LINES = 8;
+function boundedContinuationSummaries(store, taskId, refs) {
+    if (store.listEvents === undefined)
+        return [];
+    const events = store.listEvents(taskId);
+    const continuations = projectProviderContinuations(events);
+    const byKey = new Map(continuations.map((entry) => [
+        `${entry.identity.continuationId}\u0000${entry.identity.generation}`,
+        entry
+    ]));
+    const summaries = [];
+    for (const ref of refs) {
+        if (!("taskId" in ref) || ref.type !== "event")
+            continue;
+        const event = events.find((entry) => entry.id === ref.id);
+        if (event === undefined)
+            continue;
+        const observation = runtimeObservationFromTaskEvent(event);
+        if (observation === null || observation.kind !== "continuation.reported")
+            continue;
+        const summary = observation.payload?.summary;
+        if (summary === undefined || summary.trim().length === 0)
+            continue;
+        const continuation = byKey.get(`${observation.fence.continuationId}\u0000${observation.fence.continuationGeneration}`);
+        const digest = continuation?.reports
+            .find((report) => report.reportId === observation.payload?.reportId)
+            ?.resultDigest;
+        summaries.push([
+            `- child ${observation.fence.continuationId}`,
+            ...(continuation?.durability === "durable-result"
+                ? ["  (durable-result; full content: "
+                        + `yui task event show ${taskId} ${ref.id}`
+                        + (digest === undefined ? "" : `; digest ${digest.slice(0, 12)}`)
+                        + ")"]
+                : ["  (best-effort; rerun if the parent Session was lost)"]),
+            `  ${boundedExcerpt(summary)}`
+        ].join("\n"));
+    }
+    return summaries;
+}
+function boundedExcerpt(text) {
+    const lines = text.split("\n").slice(0, MAX_RESULT_SUMMARY_LINES);
+    const joined = lines.join("\n");
+    if (joined.length <= MAX_RESULT_SUMMARY_CHARS && text.length === joined.length)
+        return joined;
+    return `${joined.slice(0, MAX_RESULT_SUMMARY_CHARS)}… [truncated]`;
+}
 function roleRunDeliveryFailure(run, mailboxBatchId, session, launchId) {
     return {
         taskId: run.taskId,

package/dist/scheduler/activeTaskProgress.js

@@ -1,5 +1,6 @@
 import { selectedActiveSchedulerTasks, isSchedulerTaskWorkspaceReady } from "./ports.js";
 import { queueLeaderWakeup } from "./wakeupQueue.js";
+import { wakeReason } from "./wakeReason.js";
 import { projectTaskExecution } from "./taskExecutionProjection.js";
 import { collectTaskActionability, computeActionabilityDigest, decideOrphanWake } from "./actionability.js";
 /**
@@ -57,14 +58,14 @@ export function repairOrphanedActiveTasks(store, now, selection) {
         if (leaderMailbox?.processing !== null && leaderMailbox?.processing !== undefined) {
             const recovered = store.releaseLeaderWakeupAndEnqueue === undefined
                 ? store.releaseWorkMailbox(leaderTarget, leaderMailbox.processing.batchId)
-                    && (queueLeaderWakeup(store, task.id, "task-orphaned", now), true)
-                : store.releaseLeaderWakeupAndEnqueue(task.id, leaderMailbox.processing.batchId, "task-orphaned", now);
+                    && (queueLeaderWakeup(store, task.id, wakeReason("task-orphaned"), now), true)
+                : store.releaseLeaderWakeupAndEnqueue(task.id, leaderMailbox.processing.batchId, wakeReason("task-orphaned"), now);
             if (recovered) {
                 repaired.push(task.id);
             }
             continue;
         }
-        queueLeaderWakeup(store, task.id, "task-orphaned", now);
+        queueLeaderWakeup(store, task.id, wakeReason("task-orphaned"), now);
         repaired.push(task.id);
     }
     return repaired;