@zq-silk/yui 0.6.0 → 0.6.2

package/dist/run/agentRun.js

@@ -1,5 +1,7 @@
 import { validateEffectiveLaunchSnapshot } from "../executor/effectiveLaunch.js";
 import { validateTaskRecordReference } from "../task/taskRecordReference.js";
+import { markProviderRetryInFlight, validateAgentRunProviderRetry } from "./providerRetry.js";
+import { validateYieldReceipt } from "./yieldReceipt.js";
 import { validateManagedWorkspace } from "../worktree/managedWorkspace.js";
 export function createAgentRun(id, taskId, roleName, mode, input, now, context) {
     if (mode !== "new" && mode !== "resume") {
@@ -7,7 +9,7 @@ export function createAgentRun(id, taskId, roleName, mode, input, now, context)
     }
     const timestamp = now.toISOString();
     return {
-        schemaVersion: 6,
+        schemaVersion: 7,
         id: requireSafeIdentity(id, "Agent run id"),
         taskId: requireSafeIdentity(taskId, "Task id"),
         roleName: requireSafeIdentity(roleName, "Role name"),
@@ -64,8 +66,8 @@ export function markAgentRunDelivered(run, now) {
     };
 }
 export function validateAgentRun(run) {
-    if (run.schemaVersion !== 6)
-        throw new Error("Agent run must use schemaVersion 6.");
+    if (run.schemaVersion !== 7)
+        throw new Error("Agent run must use schemaVersion 7.");
     validateTaskRecordReference({ taskId: run.taskId, localId: run.id }, "agentRun");
     requireSafeIdentity(run.roleName, "Role name");
     if (run.mode !== "new" && run.mode !== "resume") {
@@ -188,10 +190,40 @@ export function validateAgentRun(run) {
         if (run.summary !== undefined || run.endedAt !== undefined) {
             throw new Error("An active Agent run cannot have terminal metadata.");
         }
+        if (run.disposition !== undefined
+            || run.observedActionabilityDigest !== undefined
+            || run.waitReason !== undefined) {
+            throw new Error("An active Agent run cannot carry Leader receipt metadata.");
+        }
     }
     else {
         requireText(run.summary ?? "", "Agent run summary");
         requireTimestamp(run.endedAt ?? "", "Agent run endedAt");
+        if (run.disposition !== undefined
+            && !["progress", "waiting", "blocked", "completed"].includes(run.disposition)) {
+            throw new Error(`Agent run disposition is invalid: ${String(run.disposition)}.`);
+        }
+        if (run.observedActionabilityDigest !== undefined) {
+            requireText(run.observedActionabilityDigest, "Agent run observedActionabilityDigest");
+        }
+        if (run.waitReason !== undefined) {
+            requireText(run.waitReason.kind, "Agent run waitReason kind");
+            if (run.waitReason.ref !== undefined) {
+                requireText(run.waitReason.ref, "Agent run waitReason ref");
+            }
+        }
+    }
+    if (run.providerRetry !== undefined) {
+        validateAgentRunProviderRetry(run.providerRetry);
+        if (run.status !== "active") {
+            throw new Error("A terminal Agent run cannot carry a providerRetry projection.");
+        }
+    }
+    if (run.yieldReceipt !== undefined) {
+        validateYieldReceipt(run.yieldReceipt);
+        if (run.status !== "yielded") {
+            throw new Error("An Agent run yield receipt requires a yielded Run.");
+        }
     }
     return run;
 }
@@ -206,13 +238,57 @@ function finishAgentRun(run, status, summary, now) {
         throw new Error(`Agent run is already terminal: ${run.id}.`);
     }
     const timestamp = now.toISOString();
-    return {
+    const terminal = {
         ...run,
         status,
         summary,
         updatedAt: timestamp,
         endedAt: timestamp
     };
+    // A terminal Run no longer waits for a retry; the projection is cleared so
+    // old and new readers agree the Run is settled.
+    if (terminal.providerRetry !== undefined) {
+        delete terminal.providerRetry;
+    }
+    return terminal;
+}
+/**
+ * Attaches (or advances) the Issue 04 in-place retry projection on an active
+ * Run. The Run stays `active`; only the projection changes.
+ */
+export function withProviderRetry(run, retry) {
+    if (run.status !== "active") {
+        throw new Error(`Cannot schedule provider retry on a terminal Agent run: ${run.id}.`);
+    }
+    return validateAgentRun({ ...run, providerRetry: retry });
+}
+/**
+ * Reopens an active retry-waiting Run for another in-place attempt on its
+ * original Native Session: transport markers are reset so the existing
+ * delivery path re-pushes the exact same input, the dispatch mode becomes
+ * `resume`, and the projection is marked in-flight.
+ */
+export function reopenRunForProviderRetry(run, now) {
+    if (run.status !== "active" || run.providerRetry === undefined) {
+        throw new Error(`Agent run is not waiting for a provider retry: ${run.id}.`);
+    }
+    const timestamp = now.toISOString();
+    // Omit the transport markers entirely (not `undefined`, which the file
+    // store rejects) so the delivery path sees an un-pushed Run.
+    const { providerRetry, pushedAt: _pushedAt, deliveredAt: _deliveredAt, ...rest } = run;
+    return validateAgentRun({
+        ...rest,
+        mode: "resume",
+        updatedAt: timestamp,
+        providerRetry: markProviderRetryInFlight(providerRetry, now)
+    });
+}
+/** Attaches the Issue 04 yield receipt to a yielded Run. */
+export function withYieldReceipt(run, receipt) {
+    if (run.status !== "yielded") {
+        throw new Error(`Cannot attach a yield receipt to a non-yielded Agent run: ${run.id}.`);
+    }
+    return validateAgentRun({ ...run, yieldReceipt: receipt });
 }
 function requireSafeIdentity(value, label) {
     const normalized = requireText(value, label);

package/dist/run/providerRetry.js

@@ -0,0 +1,84 @@
+import { requireIdentity, requireText, requireTimestamp } from "../domain/validation.js";
+export const PROVIDER_RETRY_BASE_DELAY_MS = 1_000;
+export const PROVIDER_RETRY_MAX_DELAY_MS = 60_000;
+/**
+ * Bounded exponential backoff. The delay is uncapped in attempt count (Issue
+ * 04 retries transient failures indefinitely with backoff) but capped in
+ * interval so a hot loop can never occupy the control plane.
+ */
+export function nextProviderRetryDelayMs(attempt) {
+    if (!Number.isSafeInteger(attempt) || attempt < 1) {
+        throw new Error(`Provider retry attempt must be a positive integer: ${String(attempt)}.`);
+    }
+    const exponent = Math.min(attempt - 1, 10);
+    return Math.min(PROVIDER_RETRY_MAX_DELAY_MS, PROVIDER_RETRY_BASE_DELAY_MS * (2 ** exponent));
+}
+export function validateAgentRunProviderRetry(value) {
+    if (value.schemaVersion !== 1) {
+        throw new Error("Agent run providerRetry must use schemaVersion 1.");
+    }
+    if (!Number.isSafeInteger(value.attempt) || value.attempt < 1) {
+        throw new Error("Agent run providerRetry attempt must be a positive integer.");
+    }
+    requireTimestamp(value.firstFailureAt, "Agent run providerRetry firstFailureAt");
+    requireTimestamp(value.lastFailureAt, "Agent run providerRetry lastFailureAt");
+    if (Date.parse(value.lastFailureAt) < Date.parse(value.firstFailureAt)) {
+        throw new Error("Agent run providerRetry lastFailureAt must not precede firstFailureAt.");
+    }
+    if (value.nextAttemptAt !== undefined) {
+        requireTimestamp(value.nextAttemptAt, "Agent run providerRetry nextAttemptAt");
+    }
+    if (value.launchId !== undefined) {
+        requireIdentity(value.launchId, "Agent run providerRetry launchId");
+    }
+    if (value.nativeSessionId !== undefined) {
+        requireIdentity(value.nativeSessionId, "Agent run providerRetry nativeSessionId");
+    }
+    requireText(value.lastErrorSummary, "Agent run providerRetry lastErrorSummary");
+    return value;
+}
+/**
+ * Records one more transient failure on a Run lineage. A fresh lineage starts
+ * at attempt 1; an existing projection increments its attempt and keeps the
+ * original `firstFailureAt`.
+ */
+export function scheduleProviderRetry(previous, input, now) {
+    const timestamp = now.toISOString();
+    const attempt = (previous?.attempt ?? 0) + 1;
+    const scheduleNextAttempt = input.scheduleNextAttempt ?? true;
+    return validateAgentRunProviderRetry({
+        schemaVersion: 1,
+        errorClass: input.errorClass,
+        attempt,
+        firstFailureAt: previous?.firstFailureAt ?? timestamp,
+        lastFailureAt: timestamp,
+        ...(scheduleNextAttempt
+            ? {
+                nextAttemptAt: new Date(now.getTime() + nextProviderRetryDelayMs(attempt)).toISOString()
+            }
+            : {}),
+        ...(input.launchId === undefined ? {} : { launchId: input.launchId }),
+        ...(input.nativeSessionId === undefined ? {} : { nativeSessionId: input.nativeSessionId }),
+        lastErrorSummary: input.lastErrorSummary
+    });
+}
+/**
+ * Marks the projection in-flight: the retry has been dispatched and no
+ * `nextAttemptAt` is due until the next outcome arrives.
+ */
+export function markProviderRetryInFlight(value, now) {
+    if (value.nextAttemptAt === undefined)
+        return value;
+    // Omit `nextAttemptAt` entirely so the projection is durably in-flight
+    // until the next outcome.
+    const { nextAttemptAt: _nextAttemptAt, ...rest } = value;
+    return validateAgentRunProviderRetry({
+        ...rest,
+        lastFailureAt: now.toISOString()
+    });
+}
+/** True when the projection is due for another attempt at `now`. */
+export function providerRetryIsDue(value, now) {
+    return value.nextAttemptAt !== undefined
+        && Date.parse(value.nextAttemptAt) <= now.getTime();
+}

package/dist/run/providerRetryConfig.js

@@ -0,0 +1,63 @@
+const KNOWN_ADAPTERS = ["claude", "codex"];
+function parseAdapters(value) {
+    if (value === undefined)
+        return [];
+    const adapters = [];
+    for (const raw of value.split(",")) {
+        const token = raw.trim().toLowerCase();
+        if (token === "")
+            continue;
+        if (token === "all") {
+            for (const adapter of KNOWN_ADAPTERS) {
+                if (!adapters.includes(adapter))
+                    adapters.push(adapter);
+            }
+            continue;
+        }
+        if (!KNOWN_ADAPTERS.includes(token)) {
+            throw new Error(`Unknown Provider retry adapter: ${token}.`);
+        }
+        if (!adapters.includes(token)) {
+            adapters.push(token);
+        }
+    }
+    return adapters;
+}
+/**
+ * Resolves the Issue 04 flags from the process environment.
+ *
+ * - `YUI_PROVIDER_RETRY_IN_PLACE` — comma-separated adapter ids (`claude`,
+ *   `codex`, `all`). Unset/empty disables the feature entirely.
+ * - `YUI_PROVIDER_RETRY_MODE` — `shadow` (default when adapters are listed)
+ *   records classification and "would retry" facts without changing behavior;
+ *   `enforce` keeps the Run active and retries in place.
+ * - `YUI_YIELD_RECEIPT_REPLAY` — `0` disables receipt replay; default `1`.
+ */
+export function providerRetryConfig(environment = process.env) {
+    const adapters = parseAdapters(environment.YUI_PROVIDER_RETRY_IN_PLACE);
+    const modeValue = environment.YUI_PROVIDER_RETRY_MODE?.trim().toLowerCase();
+    let mode;
+    if (adapters.length === 0) {
+        mode = "off";
+    }
+    else if (modeValue === "enforce") {
+        mode = "enforce";
+    }
+    else if (modeValue === undefined || modeValue === "" || modeValue === "shadow") {
+        mode = "shadow";
+    }
+    else {
+        throw new Error(`Unknown Provider retry mode: ${modeValue}.`);
+    }
+    const replayValue = environment.YUI_YIELD_RECEIPT_REPLAY?.trim();
+    const yieldReceiptReplay = replayValue === undefined || replayValue === "" || replayValue === "1";
+    if (!["0", "1"].includes(replayValue ?? "1")) {
+        throw new Error(`YUI_YIELD_RECEIPT_REPLAY must be 0 or 1: ${replayValue}.`);
+    }
+    return { mode, adapters, yieldReceiptReplay };
+}
+/** Whether the adapter has in-place retry enabled in the given mode. */
+export function providerRetryEnabledForAdapter(config, adapterId, mode) {
+    return config.mode === mode
+        && config.adapters.includes(adapterId);
+}

package/dist/run/yieldReceipt.js

@@ -0,0 +1,65 @@
+import { createHash } from "node:crypto";
+import { requireIdentity, requireText, requireTimestamp } from "../domain/validation.js";
+const DIGEST_PREFIX_LENGTH = 16;
+function canonicalDigestValue(value) {
+    if (value === null || typeof value !== "object")
+        return JSON.stringify(value) ?? "null";
+    if (Array.isArray(value)) {
+        return `[${value.map(canonicalDigestValue).join(",")}]`;
+    }
+    const entries = Object.entries(value)
+        .filter(([, entry]) => entry !== undefined)
+        .sort(([left], [right]) => (left < right ? -1 : left > right ? 1 : 0));
+    return `{${entries
+        .map(([key, entry]) => `${JSON.stringify(key)}:${canonicalDigestValue(entry)}`)
+        .join(",")}}`;
+}
+/**
+ * Computes the terminal outcome digest. The canonical form sorts object keys
+ * and drops `undefined` fields so the same outcome always hashes identically
+ * regardless of object construction order.
+ */
+export function computeYieldOutcomeDigest(input) {
+    return createHash("sha256")
+        .update(canonicalDigestValue(input))
+        .digest("hex");
+}
+export function formatYieldReceiptRequestId(taskId, runId, outcomeDigest) {
+    return `yield:${taskId}:${runId}:${outcomeDigest.slice(0, DIGEST_PREFIX_LENGTH)}`;
+}
+export function formatYieldReceiptId(taskId, runId, outcomeDigest) {
+    return `yield-receipt:${taskId}:${runId}:${outcomeDigest.slice(0, DIGEST_PREFIX_LENGTH)}`;
+}
+export function createYieldReceipt(taskId, runId, outcome, now) {
+    const outcomeDigest = computeYieldOutcomeDigest(outcome);
+    return validateYieldReceipt({
+        schemaVersion: 1,
+        requestId: formatYieldReceiptRequestId(taskId, runId, outcomeDigest),
+        receiptId: formatYieldReceiptId(taskId, runId, outcomeDigest),
+        outcomeDigest,
+        committedAt: now.toISOString()
+    });
+}
+export function validateYieldReceipt(value) {
+    if (value.schemaVersion !== 1) {
+        throw new Error("Yield receipt must use schemaVersion 1.");
+    }
+    requireIdentity(value.requestId, "Yield receipt requestId");
+    requireIdentity(value.receiptId, "Yield receipt receiptId");
+    requireText(value.outcomeDigest, "Yield receipt outcomeDigest");
+    requireTimestamp(value.committedAt, "Yield receipt committedAt");
+    return value;
+}
+/**
+ * Matches a presented outcome against a terminal Run's committed receipt.
+ * The same digest replays the receipt; a different digest fails closed.
+ */
+export function matchYieldReceipt(receipt, outcome) {
+    if (receipt === undefined)
+        return null;
+    const presented = computeYieldOutcomeDigest(outcome);
+    if (presented === receipt.outcomeDigest) {
+        return { kind: "replayed", receipt };
+    }
+    return { kind: "digest-mismatch", existing: receipt };
+}

package/dist/runtime/exactControlPlane.js

@@ -9,6 +9,7 @@ import { hasRuntimeCleanupObligation, isRuntimeLaunchReservation, runtimeLifecyc
 import { nativeSessionIdForLaunch } from "./preallocatedNativeSession.js";
 import { formatAgentRunReceiptId } from "../task/taskRecordReference.js";
 import { writeTextFileAtomically } from "../storage/durableFile.js";
+import { readActiveReleasePointer } from "../release/runtimeRelease.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";
@@ -20,7 +21,11 @@ export function createExactControlPlaneDescriptor(input) {
         executable: canonicalPath(input.executable),
         cliEntry: canonicalPath(input.cliEntry),
         yuiHome: canonicalPath(input.yuiHome),
-        identity: Object.freeze({ ...identity })
+        identity: Object.freeze({ ...identity }),
+        ...(input.buildId === undefined ? {} : { buildId: input.buildId }),
+        ...(input.activeReleaseDigest === undefined
+            ? {}
+            : { activeReleaseDigest: input.activeReleaseDigest })
     });
 }
 export function createExactTaskRuntimeDescriptor(input) {
@@ -55,7 +60,11 @@ export function parseExactControlPlaneDescriptor(value) {
         executable: requireText(record.executable, "Control-plane executable"),
         cliEntry: requireText(record.cliEntry, "Control-plane CLI entry"),
         yuiHome: requireText(record.yuiHome, "Control-plane YUI_HOME"),
-        identity: validateVersionIdentity(record.identity)
+        identity: validateVersionIdentity(record.identity),
+        ...(typeof record.buildId !== "string" ? {} : { buildId: record.buildId }),
+        ...(typeof record.activeReleaseDigest !== "string"
+            ? {}
+            : { activeReleaseDigest: record.activeReleaseDigest })
     });
 }
 export function parseExactTaskRuntimeDescriptor(value) {
@@ -165,6 +174,31 @@ export async function assertExactControlPlanePreflight(input, options = {}) {
             + `(expected ${descriptor.identity.aggregateSchemaVersion}, found `
             + `${storage.currentAggregateSchemaVersion ?? "unknown"}).`);
     }
+    // Issue 02: bind the descriptor to the active release. A descriptor that
+    // carries a build ID must match the Home's active release pointer; a
+    // descriptor without a build ID is rejected once a Home has an active
+    // release (old Sessions cannot mutate a released control plane). Homes
+    // without an active release pointer keep the legacy continuity contract.
+    const readActiveRelease = options.readActiveRelease ?? defaultReadActiveRelease;
+    const activeRelease = readActiveRelease(descriptor.yuiHome);
+    if (descriptor.buildId !== undefined) {
+        if (activeRelease === null) {
+            throw new Error("Exact control-plane descriptor names a release build but the Home has "
+                + "no active release pointer.");
+        }
+        if (activeRelease.buildId !== descriptor.buildId) {
+            throw new Error("Exact control-plane release changed since the descriptor was frozen "
+                + `(expected ${descriptor.buildId}, active ${activeRelease.buildId}).`);
+        }
+        if (descriptor.activeReleaseDigest !== undefined
+            && activeRelease.packageDigest !== descriptor.activeReleaseDigest) {
+            throw new Error("Exact control-plane release digest does not match the active release pointer.");
+        }
+    }
+    else if (activeRelease !== null) {
+        throw new Error("Exact control-plane descriptor predates the active release; old Sessions "
+            + "cannot mutate a released control plane. Re-launch through the current release.");
+    }
     if (options.checkController !== false) {
         const call = options.callController ?? defaultCallController;
         try {
@@ -314,6 +348,36 @@ export function refreshExactTaskRuntimeDescriptorSource(source, home, store) {
     writeTextFileAtomically(resolve(source), `${serializeExactDescriptor(refreshed)}\n`);
     return refreshed;
 }
+/**
+ * Advances a reused Hook's own exact source to the current durable Run/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 Run/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
+        || previous.nativeSessionId !== current.nativeSessionId) {
+        throw new Error("Task runtime descriptor source cannot jump to a replacement native Session.");
+    }
+    const refreshed = createExactTaskRuntimeDescriptor({
+        ...previous,
+        runId: current.runId,
+        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("{")) {
@@ -470,3 +534,16 @@ function isRecord(value) {
 function isDefinitelyNotRunning(error) {
     return isRecord(error) && error.code === "CONTROLLER_NOT_RUNNING";
 }
+function defaultReadActiveRelease(home) {
+    try {
+        const pointer = readActiveReleasePointer(home);
+        return pointer === null
+            ? null
+            : { buildId: pointer.buildId, packageDigest: pointer.packageDigest };
+    }
+    catch {
+        // A damaged pointer fails closed: treat it as an active release the
+        // descriptor cannot match, rather than silently skipping the gate.
+        return { buildId: "unknown", packageDigest: "unknown" };
+    }
+}

package/dist/runtime/index.js

@@ -6,3 +6,7 @@ export { createPendingTurnCompletion, DEFAULT_RECENT_TURN_ID_LIMIT, hasRecentTur
 export { RuntimeLaunchError } from "./ports.js";
 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 { DEFAULT_FORCED_GRACE_MS, DEFAULT_GRACEFUL_GRACE_MS, terminateSessionOwners } from "./sessionTerminationGuard.js";
+export { reconcileSessionOwners } from "./sessionReconciliation.js";