@zq-silk/yui 0.6.13 → 0.6.14

package/dist/run/recoveryProjection.js

@@ -0,0 +1,199 @@
+import { createHash } from "node:crypto";
+import { latestRunDurableProgressAt } from "../scheduler/roleRunStall.js";
+export const RUN_RECOVERY_ACTIONS = [
+    "diagnose",
+    "retry",
+    "replace-session",
+    "terminate"
+];
+/**
+ * Reads every durable record the recovery projection needs. Returns null
+ * only when the Run itself is absent.
+ */
+export function readRunRecoveryFacts(store, taskId, runId) {
+    const run = store.getAgentRun(taskId, runId);
+    if (run === null || run.taskId !== taskId)
+        return null;
+    const task = store.getTask(taskId);
+    const sessionSet = store.getTaskRoleSessionSet(taskId, run.roleName);
+    const progress = latestRunDurableProgressAt(store, taskId, run.roleName, runId);
+    return {
+        run,
+        task: task === null ? null : { id: task.id, status: task.status },
+        sessionSet,
+        progress,
+        latestProviderObservation: latestRunProviderObservation(store.listEvents(taskId), runId)
+    };
+}
+/**
+ * Latest Provider observation for a Run. Provider timestamps are evidence:
+ * they explain why a stale fence was supplied but never authorize recovery.
+ */
+function latestRunProviderObservation(events, runId) {
+    let latest = null;
+    for (const event of events) {
+        if (event.type !== "runtime.observation")
+            continue;
+        if (event.payload.runId !== runId)
+            continue;
+        const kind = typeof event.payload.kind === "string" ? event.payload.kind : "unknown";
+        const receivedAt = typeof event.payload.receivedAt === "string"
+            && Number.isFinite(Date.parse(event.payload.receivedAt))
+            ? event.payload.receivedAt
+            : event.createdAt;
+        const at = Date.parse(receivedAt);
+        if (latest === null || at > latest.at) {
+            latest = { kind, receivedAt, at };
+        }
+    }
+    return latest === null ? null : { kind: latest.kind, receivedAt: latest.receivedAt };
+}
+export function projectRunRecovery(facts) {
+    const { run, task, sessionSet, progress } = facts;
+    const session = activeSession(facts);
+    const canonicalProgressAt = progress?.progressAt ?? null;
+    const accepted = run.deliveredAt !== undefined;
+    const acceptanceOptions = accepted
+        ? ["accepted", "ambiguous"]
+        : ["rejected", "ambiguous"];
+    const blocked = recoveryBlocker(facts, session, canonicalProgressAt);
+    const actions = blocked === null
+        ? RUN_RECOVERY_ACTIONS.map((action) => buildActionPlan(facts, action, session, canonicalProgressAt))
+        : [];
+    const judgmentRequired = blocked === null && actions.some((plan) => plan.argv.includes(PROVIDER_ACCEPTANCE_PLACEHOLDER))
+        ? "Provider acceptance is not durably determined for every action; pass --provider-acceptance explicitly."
+        : undefined;
+    return {
+        taskId: run.taskId,
+        runId: run.id,
+        roleName: run.roleName,
+        runStatus: run.status,
+        recoverable: blocked === null,
+        canonicalProgressAt,
+        ...(progress?.evidence === undefined ? {} : { canonicalProgressEvidence: progress.evidence }),
+        provider: {
+            acceptedAt: run.deliveredAt ?? null,
+            observedAt: facts.latestProviderObservation?.receivedAt ?? null,
+            observationKind: facts.latestProviderObservation?.kind ?? null
+        },
+        providerAcceptance: {
+            accepted,
+            options: acceptanceOptions
+        },
+        session: session === null ? null : {
+            status: session.status,
+            ...(session.nativeSessionId === undefined ? {} : { nativeSessionId: session.nativeSessionId }),
+            ...(session.launchId === undefined ? {} : { launchId: session.launchId })
+        },
+        actions,
+        ...(judgmentRequired === undefined ? {} : { judgmentRequired }),
+        ...(blocked === null ? {} : { reason: blocked })
+    };
+}
+const PROVIDER_ACCEPTANCE_PLACEHOLDER = "<accepted|rejected|ambiguous>";
+function activeSession(facts) {
+    const sessions = facts.sessionSet;
+    if (sessions === null)
+        return null;
+    const session = sessions.sessions[sessions.activeAgentId];
+    if (session === undefined)
+        return null;
+    if (session.agentId !== facts.run.effective.agentId)
+        return null;
+    if (session.adapterId !== facts.run.effective.adapterId)
+        return null;
+    return session;
+}
+/**
+ * Mirrors the fail-closed checks of `recoverExactAgentRun` that are visible
+ * from durable records. A non-null result means recovery cannot currently be
+ * applied; the canonical fence is still projected for diagnosis.
+ */
+function recoveryBlocker(facts, session, canonicalProgressAt) {
+    const { run, task } = facts;
+    if (task === null)
+        return "task-missing";
+    if (task.status !== "active")
+        return "task-terminal";
+    if (run.status !== "active")
+        return "run-terminal";
+    if (canonicalProgressAt === null)
+        return "progress-unavailable";
+    if (session === null)
+        return "session-missing";
+    if (session.status === "stopped")
+        return "session-stopped";
+    if (session.status === "broken")
+        return "session-broken";
+    return null;
+}
+function buildActionPlan(facts, action, session, canonicalProgressAt) {
+    const { run } = facts;
+    const acceptance = actionAcceptance(facts, action);
+    const argv = [
+        "task",
+        "run",
+        "recover",
+        `${run.taskId}/${run.id}`,
+        "--action",
+        action,
+        "--expected-progress-at",
+        canonicalProgressAt,
+        "--provider-acceptance",
+        acceptance,
+        "--reason",
+        "<text>",
+        "--agent-id",
+        run.effective.agentId,
+        "--adapter-id",
+        run.effective.adapterId,
+        ...(session.nativeSessionId === undefined
+            ? []
+            : ["--native-session-id", session.nativeSessionId]),
+        ...(session.launchId === undefined
+            ? []
+            : ["--launch-id", session.launchId])
+    ];
+    const command = `yui ${argv
+        .map((part) => (part === "<text>" ? '"<text>"' : part))
+        .join(" ")}`;
+    const fingerprintSource = [
+        run.id,
+        action,
+        canonicalProgressAt,
+        run.effective.agentId,
+        run.effective.adapterId,
+        session.nativeSessionId ?? "",
+        session.launchId ?? ""
+    ].join("|");
+    return {
+        action,
+        reason: ACTION_REASONS[action],
+        expectedProgressAt: canonicalProgressAt,
+        agentId: run.effective.agentId,
+        adapterId: run.effective.adapterId,
+        ...(session.nativeSessionId === undefined
+            ? {}
+            : { nativeSessionId: session.nativeSessionId }),
+        ...(session.launchId === undefined ? {} : { launchId: session.launchId }),
+        command,
+        argv,
+        fingerprint: createHash("sha256").update(fingerprintSource).digest("hex")
+    };
+}
+/**
+ * The acceptance value for the copy-paste command. When exactly one value is
+ * durably valid it is filled in (the durable record, not a guess); otherwise
+ * the Leader must choose and the command carries an explicit placeholder.
+ */
+function actionAcceptance(facts, action) {
+    if (action === "diagnose")
+        return PROVIDER_ACCEPTANCE_PLACEHOLDER;
+    return facts.run.deliveredAt === undefined ? "rejected" : "accepted";
+}
+const ACTION_REASONS = {
+    diagnose: "Collect bounded diagnostics before any state-changing recovery.",
+    retry: "Request another provider turn on the same native Session when the failure is transient.",
+    "replace-session": "Request a fresh native Session when the current one is unusable.",
+    terminate: "Fail the Run explicitly when recovery is not viable."
+};

package/dist/runtime/builtinAgentDrivers.js

@@ -1,5 +1,6 @@
 import { AgentDriverRegistry } from "./agentDriver.js";
 import { claudeTranscriptObserver, codexTranscriptObserver, transcriptObserverSource } from "./builtinTranscriptObserver.js";
+import { parseClaudeError } from "./providerErrorCodes.js";
 export const CODEX_DRIVER_ID = "openai/codex";
 export const CLAUDE_CODE_DRIVER_ID = "anthropic/claude-code";
 export function builtinDriverIdForAdapter(adapterId) {
@@ -352,8 +353,10 @@ function claudeFailure(payload) {
     const code = firstIdentity(payload, ["error"], "Claude StopFailure error");
     const details = optionalText(payload.error_details);
     const lastOutput = optionalText(payload.last_assistant_message);
+    const parsed = parseClaudeError(code, details);
     return {
         failure: {
+            ...(parsed.code !== "unknown" ? { errorCode: parsed.code } : {}),
             code,
             ...(details === undefined ? {} : { details }),
             ...(lastOutput === undefined ? {} : { lastOutput }),

package/dist/runtime/builtinTranscriptUsage.js

@@ -1,5 +1,26 @@
 export function codexTranscriptUsage(transcript) {
-    let latest = null;
+    const report = codexTranscriptUsageReport(transcript);
+    if (report === null)
+        return null;
+    return Object.freeze({
+        inputTokens: report.uncachedInputTokens + report.cacheReadTokens + report.cacheCreatedTokens,
+        outputTokens: report.outputTokens,
+        ...(report.cacheReadTokens + report.cacheCreatedTokens === 0
+            ? {}
+            : { cachedInputTokens: report.cacheReadTokens + report.cacheCreatedTokens })
+    });
+}
+export function codexTranscriptUsageReport(transcript) {
+    // Codex token_count events are cumulative session snapshots. Per-request
+    // input is the delta between consecutive snapshots; the first snapshot is
+    // treated as one full request.
+    let latestInput = 0;
+    let latestCached = 0;
+    let latestOutput = 0;
+    let previous = 0;
+    let peak = 0;
+    let requests = 0;
+    let seen = false;
     for (const line of transcript.split("\n")) {
         const entry = parseLine(line);
         if (entry?.type !== "event_msg")
@@ -13,18 +34,44 @@ export function codexTranscriptUsage(transcript) {
         const outputTokens = integer(usage?.output_tokens);
         if (inputTokens === null || outputTokens === null)
             continue;
-        const cachedInputTokens = integer(usage?.cached_input_tokens);
-        const reasoningTokens = integer(usage?.reasoning_output_tokens);
-        latest = Object.freeze({
-            inputTokens,
-            outputTokens,
-            ...(cachedInputTokens === null ? {} : { cachedInputTokens }),
-            ...(reasoningTokens === null ? {} : { reasoningTokens })
-        });
+        const cachedInputTokens = integer(usage?.cached_input_tokens) ?? 0;
+        requests += 1;
+        seen = true;
+        const total = inputTokens + cachedInputTokens;
+        const delta = Math.max(0, total - previous);
+        if (delta > peak)
+            peak = delta;
+        previous = total;
+        latestInput = inputTokens;
+        latestCached = cachedInputTokens;
+        latestOutput = outputTokens;
     }
-    return latest;
+    if (!seen)
+        return null;
+    return Object.freeze({
+        requests,
+        uncachedInputTokens: Math.max(0, latestInput - latestCached),
+        cacheReadTokens: latestCached,
+        cacheCreatedTokens: 0,
+        outputTokens: latestOutput,
+        peakRequestTokens: peak
+    });
 }
 export function claudeTranscriptUsage(transcript) {
+    const report = claudeTranscriptUsageReport(transcript);
+    if (report === null)
+        return null;
+    return Object.freeze({
+        inputTokens: report.uncachedInputTokens + report.cacheReadTokens + report.cacheCreatedTokens,
+        outputTokens: report.outputTokens,
+        ...(report.cacheReadTokens + report.cacheCreatedTokens === 0
+            ? {}
+            : { cachedInputTokens: report.cacheReadTokens + report.cacheCreatedTokens })
+    });
+}
+export function claudeTranscriptUsageReport(transcript) {
+    // Each Claude assistant message carries its own per-request usage, so the
+    // report is a direct aggregation; the peak is the largest single message.
     const messages = new Map();
     for (const line of transcript.split("\n")) {
         const entry = parseLine(line);
@@ -33,13 +80,11 @@ export function claudeTranscriptUsage(transcript) {
         const message = object(entry.message);
         const usage = object(message?.usage);
         const directInput = integer(usage?.input_tokens);
-        const outputTokens = integer(usage?.output_tokens);
-        if (directInput === null || outputTokens === null)
+        const output = integer(usage?.output_tokens);
+        if (directInput === null || output === null)
             continue;
         const cacheRead = integer(usage?.cache_read_input_tokens) ?? 0;
         const cacheCreated = integer(usage?.cache_creation_input_tokens) ?? 0;
-        const details = object(usage?.output_tokens_details);
-        const reasoningTokens = integer(details?.thinking_tokens);
         const key = typeof message?.id === "string" && message.id.length > 0
             ? `message:${message.id}`
             : typeof entry.uuid === "string" && entry.uuid.length > 0
@@ -49,32 +94,31 @@ export function claudeTranscriptUsage(transcript) {
         // stable provider or entry identity, summing them would fabricate growth.
         if (key === null)
             continue;
-        messages.set(key, Object.freeze({
-            // Normalize inputTokens as the complete input total. cachedInputTokens is
-            // a breakdown and must not be added to it again by the projection.
-            inputTokens: directInput + cacheRead + cacheCreated,
-            outputTokens,
-            cachedInputTokens: cacheRead + cacheCreated,
-            ...(reasoningTokens === null ? {} : { reasoningTokens })
-        }));
+        messages.set(key, { directInput, cacheRead, cacheCreated, output });
     }
     if (messages.size === 0)
         return null;
-    let inputTokens = 0;
+    let uncachedInputTokens = 0;
+    let cacheReadTokens = 0;
+    let cacheCreatedTokens = 0;
     let outputTokens = 0;
-    let cachedInputTokens = 0;
-    let reasoningTokens = 0;
+    let peak = 0;
     for (const usage of messages.values()) {
-        inputTokens += usage.inputTokens;
-        outputTokens += usage.outputTokens;
-        cachedInputTokens += usage.cachedInputTokens ?? 0;
-        reasoningTokens += usage.reasoningTokens ?? 0;
+        uncachedInputTokens += usage.directInput;
+        cacheReadTokens += usage.cacheRead;
+        cacheCreatedTokens += usage.cacheCreated;
+        outputTokens += usage.output;
+        const total = usage.directInput + usage.cacheRead + usage.cacheCreated;
+        if (total > peak)
+            peak = total;
     }
     return Object.freeze({
-        inputTokens,
+        requests: messages.size,
+        uncachedInputTokens,
+        cacheReadTokens,
+        cacheCreatedTokens,
         outputTokens,
-        cachedInputTokens,
-        ...(reasoningTokens === 0 ? {} : { reasoningTokens })
+        peakRequestTokens: peak
     });
 }
 function parseLine(line) {

package/dist/runtime/continuationManager.js

@@ -1,3 +1,4 @@
+import { createHash } from "node:crypto";
 import { createProviderContinuation, observeProviderContinuation, providerContinuationKey, recordProviderReport } from "./providerContinuation.js";
 import { createRuntimeObservation } from "./runtimeObservation.js";
 export function foldContinuationObservation(existing, raw) {
@@ -30,12 +31,14 @@ export function foldContinuationObservation(existing, raw) {
         throw new Error("Continuation observation identity does not match the existing projection.");
     }
     if (observation.kind === "continuation.reported") {
+        const resultReceipt = durableResultReceipt(payload.summary);
         const next = recordProviderReport(base, {
             reportId: payload.reportId,
             ...(payload.resultRef === undefined ? {} : { resultRef: payload.resultRef }),
             ...(payload.providerDeliveryRef === undefined
                 ? {}
                 : { providerDeliveryRef: payload.providerDeliveryRef }),
+            ...resultReceipt,
             observedAt: observation.observedAt ?? observation.receivedAt
         }, observation.sequence);
         return {
@@ -62,6 +65,20 @@ export function foldContinuationObservation(existing, raw) {
         continuation: next
     };
 }
+/**
+ * The durable-result receipt for a native child report. Yui only claims
+ * "durable-result" durability when it has actually persisted result content;
+ * the sha256 digest makes replays idempotent and lets recovery verify the
+ * result by digest. A report without persisted content stays best-effort.
+ */
+function durableResultReceipt(summary) {
+    if (summary === undefined || summary.trim().length === 0)
+        return {};
+    return Object.freeze({
+        resultDigest: createHash("sha256").update(summary).digest("hex"),
+        resultSize: summary.length
+    });
+}
 /**
  * Commits the semantic continuation fact and its Leader notification before
  * releasing child ownership. The surrounding TaskStore transaction is the

package/dist/runtime/index.js

@@ -1,4 +1,5 @@
 export { createPromptEnvelope } from "./promptEnvelope.js";
+export { codexTranscriptUsage, codexTranscriptUsageReport, claudeTranscriptUsage, claudeTranscriptUsageReport } from "./builtinTranscriptUsage.js";
 export { createRuntimeBinding } from "./runtimeBinding.js";
 export { normalizeRuntimeOwner } from "./runtimeOwner.js";
 export { createSessionLaunchRequest } from "./sessionLaunchRequest.js";
@@ -8,6 +9,7 @@ export { TmuxPromptPushAdapter, 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";
 export { FileSessionOwnerRegistry } from "./sessionOwnerRegistry.js";
+export { formatRuntimeLaunchDiagnostic, redactLaunchArgument, redactLaunchText, RuntimeLaunchFailure, toRuntimeLaunchFailure } from "./launchDiagnostics.js";
 export { DEFAULT_FORCED_GRACE_MS, DEFAULT_GRACEFUL_GRACE_MS, terminateSessionOwners } from "./sessionTerminationGuard.js";
 export { ProviderContinuationReconciliationService } from "./providerContinuationReconciliationService.js";
 export { codexNotificationBoundary, CodexAppServerRequestError, CodexAppServerRuntime } from "./codexAppServerRuntime.js";

package/dist/runtime/launchDiagnostics.js

@@ -0,0 +1,154 @@
+import { CommandExecutionError } from "../tmux/commandExecutor.js";
+export const RUNTIME_LAUNCH_PHASES = [
+    "validation",
+    "host-start",
+    "host-started",
+    "native-session-discovery",
+    "host-stop",
+    "delivery"
+];
+export const RUNTIME_LAUNCH_KINDS = [
+    "config",
+    "auth",
+    "executable",
+    "tmux",
+    "timeout",
+    "provider",
+    "unknown"
+];
+const MAX_ARGUMENT_CHARS = 1_000;
+const MAX_STDERR_CHARS = 4_000;
+const MAX_DETAIL_CHARS = 1_000;
+const SECRET_VALUE_PATTERN = /(api[_-]?key|access[_-]?token|refresh[_-]?token|secret|password|passwd|cookie|authorization)(\s*[=:]\s*)([^\s,;]+)/gi;
+// Word boundary keeps "task-5-…" workspace paths from being mistaken for keys.
+const OPENAI_KEY_PATTERN = /\bsk-[A-Za-z0-9_-]{6,}/gu;
+/** A bounded, single-line, secret-redacted launch failure for Run summaries. */
+export class RuntimeLaunchFailure extends Error {
+    diagnostic;
+    name = "RuntimeLaunchFailure";
+    constructor(diagnostic) {
+        super(formatRuntimeLaunchDiagnostic(diagnostic));
+        this.diagnostic = diagnostic;
+    }
+}
+export function toRuntimeLaunchFailure(error, phase, context = {}) {
+    if (error instanceof RuntimeLaunchFailure)
+        return error;
+    const commandError = error instanceof CommandExecutionError ? error : undefined;
+    const stderrTail = tail(redactLaunchText(context.stderrTail ?? commandError?.stderr ?? ""), MAX_STDERR_CHARS);
+    const kind = classifyLaunchFailure(phase, error, stderrTail);
+    const exitStatus = context.exitStatus ?? commandError?.exitStatus;
+    const detail = tail(redactLaunchText(error instanceof Error ? error.message : String(error)), MAX_DETAIL_CHARS);
+    return new RuntimeLaunchFailure({
+        phase,
+        kind,
+        ...(context.command === undefined ? {} : { command: redactLaunchText(context.command) }),
+        ...(context.argv === undefined
+            ? {}
+            : { argv: context.argv.map((argument) => redactLaunchArgument(argument)) }),
+        ...(context.cwd === undefined ? {} : { cwd: context.cwd }),
+        ...(exitStatus === undefined
+            ? {}
+            : { exitStatus }),
+        ...(context.signal === undefined ? {} : { signal: context.signal }),
+        ...(stderrTail.length === 0 ? {} : { stderrTail }),
+        ...(context.pane === undefined ? {} : { pane: context.pane }),
+        ...(detail.length === 0 ? {} : { detail }),
+        ...(launchHint(kind, context.agentId) === undefined
+            ? {}
+            : { hint: launchHint(kind, context.agentId) })
+    });
+}
+export function formatRuntimeLaunchDiagnostic(diagnostic) {
+    const fields = [
+        `failurePhase=${diagnostic.phase}`,
+        `failureKind=${diagnostic.kind}`
+    ];
+    if (diagnostic.command !== undefined)
+        fields.push(`command=${JSON.stringify(diagnostic.command)}`);
+    if (diagnostic.argv !== undefined)
+        fields.push(`argv=${JSON.stringify(diagnostic.argv)}`);
+    if (diagnostic.cwd !== undefined)
+        fields.push(`cwd=${JSON.stringify(diagnostic.cwd)}`);
+    if (diagnostic.exitStatus !== undefined)
+        fields.push(`exitStatus=${diagnostic.exitStatus}`);
+    if (diagnostic.signal !== undefined)
+        fields.push(`signal=${JSON.stringify(diagnostic.signal)}`);
+    if (diagnostic.stderrTail !== undefined) {
+        fields.push(`stderrTail=${JSON.stringify(tail(diagnostic.stderrTail, MAX_STDERR_CHARS))}`);
+    }
+    if (diagnostic.pane !== undefined)
+        fields.push(`pane=${JSON.stringify(diagnostic.pane)}`);
+    if (diagnostic.detail !== undefined) {
+        fields.push(`detail=${JSON.stringify(tail(diagnostic.detail, MAX_DETAIL_CHARS))}`);
+    }
+    if (diagnostic.hint !== undefined)
+        fields.push(`hint=${JSON.stringify(diagnostic.hint)}`);
+    return `Role Run could not start: ${fields.join(" ")}`;
+}
+export function redactLaunchArgument(value) {
+    return tail(redactLaunchText(value), MAX_ARGUMENT_CHARS);
+}
+export function redactLaunchText(value) {
+    return value
+        .replace(OPENAI_KEY_PATTERN, "[REDACTED]")
+        .replace(SECRET_VALUE_PATTERN, "$1$2[REDACTED]");
+}
+function classifyLaunchFailure(phase, error, stderrTail) {
+    if ((error instanceof CommandExecutionError && error.code === "COMMAND_NOT_FOUND")
+        || /command not found|no such file or directory/i.test(stderrTail)) {
+        return "executable";
+    }
+    if (isConfigFailure(stderrTail))
+        return "config";
+    if (isAuthFailure(stderrTail))
+        return "auth";
+    if (phase === "host-start")
+        return "tmux";
+    if (phase === "native-session-discovery")
+        return "timeout";
+    if (phase === "validation" || phase === "delivery")
+        return "config";
+    return "provider";
+}
+function isConfigFailure(stderrTail) {
+    return /unknown model|invalid effort|unknown option|invalid value|unexpected argument|invalid .*config|model .*not (?:found|supported)|effort .*not (?:valid|supported)/i
+        .test(stderrTail);
+}
+function isAuthFailure(stderrTail) {
+    return /\bauth(?:entication|orization)?\b|unauthorized|forbidden|credential|api[_-]?key|login|sign in|token/i
+        .test(stderrTail);
+}
+/**
+ * Conservative detection of fatal error signatures in agent output during
+ * launch. These are errors the agent cannot recover from without
+ * intervention (missing executable, invalid configuration, authentication
+ * failure). Transient errors (network retries, temporary blips) are not
+ * matched. Failure-kind classification uses the broader patterns in
+ * classifyLaunchFailure once a fatal output is confirmed.
+ */
+export function hasFatalLaunchOutput(output) {
+    return /command not found|no such file or directory/i.test(output)
+        || /unknown model|invalid effort|unknown option|invalid value|unexpected argument/i.test(output)
+        || /401\s+unauthorized|403\s+forbidden|authentication failed|not logged in|sign in with/i
+            .test(output);
+}
+function launchHint(kind, agentId) {
+    switch (kind) {
+        case "config":
+            return agentId === undefined
+                ? "Verify the Provider model and effort configuration."
+                : `Verify custom model/effort with yui agent capabilities ${agentId}.`;
+        case "auth":
+            return "Verify Provider authentication and the Agent environment.";
+        case "executable":
+            return "Verify the Provider command is installed and on PATH.";
+        case "timeout":
+            return "Verify Provider lifecycle hooks and Controller connectivity.";
+        default:
+            return undefined;
+    }
+}
+function tail(value, maxChars) {
+    return value.length <= maxChars ? value : value.slice(value.length - maxChars);
+}

package/dist/runtime/lifecycleReservation.js

@@ -2,6 +2,19 @@ import { mailboxHasWork } from "../coordination/workMailbox.js";
 export const RUNTIME_LIFECYCLE_OWNER = "runtime-lifecycle";
 export const RUNTIME_LAUNCH_RESERVED_REASON = "runtime-launch-reserved";
 export const RUNTIME_CLEANUP_REQUIRED_REASON = "runtime-cleanup-required";
+/**
+ * A Role runtime lifecycle lane already holds an in-flight operation (a
+ * launch reservation or a cleanup obligation). This is scheduler
+ * backpressure: the equivalent wake/Run must be retried after the lane
+ * settles. It is never grounds to terminalize a Run, because the contention
+ * happens before (or outside) any semantic Run launch.
+ */
+export class RuntimeLifecycleBusyError extends Error {
+    name = "RuntimeLifecycleBusyError";
+    constructor(message) {
+        super(message);
+    }
+}
 export function runtimeLifecycleTarget(owner) {
     return owner.scope === "task"
         ? {

package/dist/runtime/providerContinuation.js

@@ -24,6 +24,7 @@ export function createProviderContinuation(input) {
         attachment: input.attachment,
         observation: input.observation,
         mayWriteWorkspace: input.mayWriteWorkspace,
+        durability: "best-effort",
         reports: [],
         ...(input.providerSequence === undefined ? {} : { lastProviderSequence: input.providerSequence }),
         identityConflict: false,
@@ -40,9 +41,17 @@ export function recordProviderReport(raw, report, providerSequence) {
     const normalized = validateProviderReport(report);
     if (current.reports.some((entry) => entry.reportId === normalized.reportId))
         return current;
+    // Idempotent durable-result receipt: a replay carrying the same content
+    // digest must not create a second report even when the Provider assigns a
+    // fresh report id.
+    if (normalized.resultDigest !== undefined
+        && current.reports.some((entry) => entry.resultDigest === normalized.resultDigest)) {
+        return current;
+    }
     return validateProviderContinuation({
         ...current,
         reports: [...current.reports, normalized],
+        ...(normalized.resultDigest === undefined ? {} : { durability: "durable-result" }),
         ...(providerSequence === undefined ? {} : { lastProviderSequence: providerSequence }),
         updatedAt: normalized.observedAt
     });
@@ -160,10 +169,21 @@ export function validateProviderContinuation(value) {
     if (typeof value.mayWriteWorkspace !== "boolean" || typeof value.identityConflict !== "boolean") {
         throw new Error("Provider Continuation flags are invalid.");
     }
+    if (value.durability !== "best-effort" && value.durability !== "durable-result") {
+        throw new Error("Provider Continuation durability is invalid.");
+    }
     const reports = value.reports.map(validateProviderReport);
     if (new Set(reports.map((entry) => entry.reportId)).size !== reports.length) {
         throw new Error("Provider Continuation reports contain duplicate identity.");
     }
+    if (value.durability === "durable-result"
+        && !reports.some((entry) => entry.resultDigest !== undefined)) {
+        throw new Error("Durable-result Provider Continuation requires a result digest receipt.");
+    }
+    if (value.durability === "best-effort"
+        && reports.some((entry) => entry.resultDigest !== undefined)) {
+        throw new Error("Best-effort Provider Continuation must not carry a result digest receipt.");
+    }
     timestamp(value.createdAt, "Provider Continuation createdAt");
     timestamp(value.updatedAt, "Provider Continuation updatedAt");
     if (value.settledAt !== undefined) {
@@ -197,9 +217,27 @@ function validateProviderReport(value) {
         ...(value.providerDeliveryRef === undefined
             ? {}
             : { providerDeliveryRef: text(value.providerDeliveryRef, "Provider delivery ref") }),
+        ...(value.resultDigest === undefined
+            ? {}
+            : { resultDigest: digest(value.resultDigest) }),
+        ...(value.resultSize === undefined
+            ? {}
+            : { resultSize: reportSize(value.resultSize) }),
         observedAt: timestamp(value.observedAt, "Provider report observedAt")
     };
 }
+function digest(value) {
+    if (!/^[0-9a-f]{64}$/.test(value)) {
+        throw new Error("Provider report result digest must be a sha256 hex string.");
+    }
+    return value;
+}
+function reportSize(value) {
+    if (!Number.isSafeInteger(value) || value < 0) {
+        throw new Error("Provider report result size is invalid.");
+    }
+    return value;
+}
 function providerSequenceRegresses(current, incoming) {
     if (incoming === undefined)
         return false;