@astrosheep/keiyaku 2.9.8 → 2.9.10

package/build/agents/harness/control-types.js

@@ -1 +1,18 @@
-export {};
+/**
+ * Adapters call this only with durable admissions their native event proved.
+ * A duplicate tell coordinate is ambiguous and intentionally yields no receipt.
+ */
+export function exactLaunchInputReceipts(stage, fence, admissions) {
+    const counts = new Map();
+    for (const admission of admissions) {
+        for (const tellId of admission.tellIds)
+            counts.set(tellId, (counts.get(tellId) ?? 0) + 1);
+    }
+    if ([...counts.values()].some((count) => count !== 1))
+        return [];
+    return [...counts.keys()].sort().map((tellId) => ({
+        stage,
+        correlation: { kind: "exact", tellId },
+        launchInput: { fence },
+    }));
+}

package/build/agents/harness/index.js

@@ -1,8 +1,10 @@
 export { activityEventBodySchema, AGENT_EVENT_TEXT_MAX_CHARS, AGENT_UNKNOWN_PAYLOAD_MAX_CHARS, } from "./events.js";
 export { EXEC_EVENT_BUFFER_HARD_CAP } from "./event-channel.js";
 export { createAbortError } from "./runtime.js";
+export { exactLaunchInputReceipts } from "./control-types.js";
 export { createProviderFailure, isProviderTerminalError, ProviderTerminalError, toProviderTerminalError, } from "./provider-adapter.js";
 export { restoreOutcome } from "./outcome.js";
+export { OutcomeErrorValidationError, parseCurrentOutcomeError, } from "./outcome-error.js";
 export { call, revive } from "./projection.js";
 export { isRecoverableSessionEnvelope } from "./session.js";
 export { OUTCOME_ERROR_VERSION, SubagentFailure } from "../types.js";

package/build/agents/harness/outcome-error.js

@@ -0,0 +1,81 @@
+import { OUTCOME_ERROR_VERSION, SUBAGENT_FAILURE_CODES, } from "../types.js";
+const OUTCOME_ERROR_CODES = new Set(SUBAGENT_FAILURE_CODES);
+const OUTCOME_ERROR_KEYS = new Set([
+    "version",
+    "code",
+    "message",
+    "timeoutMs",
+    "exitCode",
+    "publicCause",
+]);
+export class OutcomeErrorValidationError extends Error {
+    incompatible;
+    constructor(message, incompatible = false) {
+        super(message);
+        this.incompatible = incompatible;
+        this.name = "OutcomeErrorValidationError";
+    }
+}
+function isPlainObject(value) {
+    if (value === null || typeof value !== "object" || Array.isArray(value))
+        return false;
+    const prototype = Object.getPrototypeOf(value);
+    return prototype === Object.prototype || prototype === null;
+}
+function isJsonCompatible(value, ancestors) {
+    if (value === null || typeof value === "boolean" || typeof value === "string")
+        return true;
+    if (typeof value === "number")
+        return Number.isFinite(value);
+    if (typeof value !== "object")
+        return false;
+    if (ancestors.has(value))
+        return false;
+    ancestors.add(value);
+    try {
+        if (Array.isArray(value))
+            return value.every((item) => isJsonCompatible(item, ancestors));
+        return isPlainObject(value) && Object.values(value).every((item) => isJsonCompatible(item, ancestors));
+    }
+    finally {
+        ancestors.delete(value);
+    }
+}
+/** Parses the one current persisted OutcomeError schema at the harness boundary. */
+export function parseCurrentOutcomeError(value, location) {
+    const error = isPlainObject(value) ? value : undefined;
+    const version = error?.version;
+    if (!error || version !== OUTCOME_ERROR_VERSION) {
+        throw new OutcomeErrorValidationError(`${location} has incompatible version ${version === undefined ? "missing" : String(version)}; expected ${OUTCOME_ERROR_VERSION}`, true);
+    }
+    if (Object.keys(error).some((key) => !OUTCOME_ERROR_KEYS.has(key))) {
+        throw new OutcomeErrorValidationError(`${location} is not the current closed OutcomeError shape`);
+    }
+    if (typeof error.code !== "string" || !OUTCOME_ERROR_CODES.has(error.code)) {
+        throw new OutcomeErrorValidationError(`${location}.code is not a recognized subagent failure code`);
+    }
+    if (typeof error.message !== "string") {
+        throw new OutcomeErrorValidationError(`${location}.message must be a string`);
+    }
+    if (error.timeoutMs !== null && (typeof error.timeoutMs !== "number"
+        || !Number.isSafeInteger(error.timeoutMs)
+        || error.timeoutMs < 0)) {
+        throw new OutcomeErrorValidationError(`${location}.timeoutMs must be null or a non-negative safe integer`);
+    }
+    if (error.exitCode !== null && (typeof error.exitCode !== "number"
+        || !Number.isSafeInteger(error.exitCode))) {
+        throw new OutcomeErrorValidationError(`${location}.exitCode must be null or a safe integer`);
+    }
+    if (error.publicCause !== undefined && (!isPlainObject(error.publicCause)
+        || !isJsonCompatible(error.publicCause, new Set()))) {
+        throw new OutcomeErrorValidationError(`${location}.publicCause must be a JSON-compatible harness failure cause`);
+    }
+    return {
+        version: OUTCOME_ERROR_VERSION,
+        code: error.code,
+        message: error.message,
+        timeoutMs: error.timeoutMs,
+        exitCode: error.exitCode,
+        ...(error.publicCause === undefined ? {} : { publicCause: error.publicCause }),
+    };
+}

package/build/agents/harness/projection.js

@@ -91,6 +91,7 @@ function createProjectionState(terms, reviveTerms, options) {
         forceWaiters: new Set(),
         onLive() { },
         observer: options?.observer,
+        launchTellIds: options?.launchTellIds,
     };
     if (terms.signal) {
         const listener = () => {
@@ -239,12 +240,14 @@ async function settleProjection(shared) {
         }, shared.terms.idleTimeoutMs);
         idleTimeout.unref?.();
     };
-    executionTimeout = setTimeout(() => {
-        policyBudgetExceeded = true;
-        requestPolicyBudgetCleanup(shared, createAbortError(`${shared.terms.provider} execution policy budget expired`));
-        resolvePolicyBudget();
-    }, shared.terms.executionTimeoutMs);
-    executionTimeout.unref?.();
+    if (shared.terms.executionTimeoutMs > 0) {
+        executionTimeout = setTimeout(() => {
+            policyBudgetExceeded = true;
+            requestPolicyBudgetCleanup(shared, createAbortError(`${shared.terms.provider} execution policy budget expired`));
+            resolvePolicyBudget();
+        }, shared.terms.executionTimeoutMs);
+        executionTimeout.unref?.();
+    }
     const requestLiveAbort = () => {
         if (shared.explicitlyAborted)
             return;
@@ -259,7 +262,7 @@ async function settleProjection(shared) {
             const live = await startLiveProjection(shared.terms, shared.lifecycleAbort.signal, shared.reviveTerms, refreshIdleTimeout, shared.observer, (admission) => {
                 recordSessionAdmission(state, admission.session);
                 refreshIdleTimeout();
-            });
+            }, shared.launchTellIds);
             liveDriver = live;
             shared.onLive(live);
             resolveForceWaiters(shared, live);

package/build/agents/harness/router.js

@@ -1,5 +1,5 @@
 import { getProviderRegistration } from "../providers/registry.js";
-export async function startLiveProjection(terms, signal, reviveTerms, onIngress, observer, onSessionAdmission) {
+export async function startLiveProjection(terms, signal, reviveTerms, onIngress, observer, onSessionAdmission, launchTellIds) {
     const onSyncCheckpoint = observer
         ? (control, checkpoint) => {
             observer.onCheckpoint(control, checkpoint);
@@ -13,6 +13,9 @@ export async function startLiveProjection(terms, signal, reviveTerms, onIngress,
         }
         : undefined;
     const registration = getProviderRegistration(terms.provider);
+    if (observer && registration.tellReceiptCapabilities) {
+        await observer.onTellReceiptCapabilities(registration.tellReceiptCapabilities);
+    }
     return registration.startLive({
         terms,
         signal,
@@ -21,6 +24,7 @@ export async function startLiveProjection(terms, signal, reviveTerms, onIngress,
         onDeliveryOpportunity,
         onSessionAdmission,
         onIngress,
+        launchTellIds,
         observer,
     });
 }

package/build/agents/providers/claude-agent-sdk/adapter.js

@@ -1,6 +1,7 @@
 import { appendDebugLog } from "../../../telemetry/debug-log.js";
 import { SUBAGENT_SESSION_VERSION } from "../../session.js";
 import { createProjectionDriver } from "../../harness/execution-handle.js";
+import { exactLaunchInputReceipts } from "../../harness/control-types.js";
 import { createProviderFailure } from "../../harness/provider-adapter.js";
 import { buildSubagentEnv, createAbortError, emitProviderEvidence, linkAbortSignal, sha256Utf8 } from "../../harness/runtime.js";
 import { claudeIngressDisposition, emitClaudeThoughts, emitClaudeToolResults, emitClaudeToolStarts, emitClaudeUsage, extractAssistantMessage, extractAssistantMessageId, extractAssistantMessageModel, extractOverloadFallbackWarning, extractResultText, extractResumeToken, isClaudeApiRetryEvent, isClaudeModelRefusalFallbackEvent, isClaudeModelRefusalNoFallbackEvent, mapClaudeApiRetryWarning, } from "./events.js";
@@ -93,6 +94,7 @@ export async function startClaudeAgentSdk(prompt, cwd, options) {
             const submitted = inputStream.push(toClaudeUserMessage(message.text));
             // submitted = NEXT source next() after this tell is yielded (not the yield pull itself).
             await submitted.waitSubmitted();
+            options.onTellReceipt?.({ stage: "seen", correlation: { kind: "exact", tellId: message.id } });
             emitTurnStarted?.();
             // 落账：记录提交时越过的 result ordinal（generation fence 落点）。
             const submittedAfterResultOrdinal = completedResultOrdinal;
@@ -143,10 +145,19 @@ export async function startClaudeAgentSdk(prompt, cwd, options) {
             const unlinkOuterAbort = linkAbortSignal(options.signal, queryAbortController, () => undefined);
             try {
                 const initialMessage = toClaudeUserMessage(prompt);
-                inputStream = createPushableUserMessageStream((message) => {
-                    if (!options.onEvidence)
+                inputStream = createPushableUserMessageStream(async (message) => {
+                    if (message === initialMessage) {
+                        // Claude's source pull is the provider-native launch-input fact.
+                        // The adapter records its coordinate before asking heart to reduce
+                        // the exact attributed receipt.
+                        const fence = { kind: "ordinal", ordinal: 0 };
+                        await options.onLaunchAdmission?.({ fence, tellIds: options.launchTellIds ?? [] });
+                        const admissions = (options.listLaunchAdmissions?.() ?? []).filter((admission) => (admission.fence.kind === "ordinal" && admission.fence.ordinal === fence.ordinal));
+                        for (const receipt of exactLaunchInputReceipts("seen", fence, admissions))
+                            options.onTellReceipt?.(receipt);
                         return;
-                    if (message === initialMessage)
+                    }
+                    if (!options.onEvidence)
                         return;
                     const content = message.message.content;
                     const text = typeof content === "string"
@@ -286,7 +297,6 @@ export async function startClaudeAgentSdk(prompt, cwd, options) {
                                     bumpResultOrdinal();
                                     const checkpoint = {
                                         fence: { kind: "ordinal", ordinal: completedResultOrdinal },
-                                        consumptionEvidence: true,
                                     };
                                     // Record the native result before the synchronous pump can
                                     // consume any tell fenced to an earlier result.
@@ -300,6 +310,10 @@ export async function startClaudeAgentSdk(prompt, cwd, options) {
                                     }
                                     // Sync checkpoint: claim inbox tells and deliver them via steer control.
                                     options.onSyncCheckpoint?.({ enqueue }, checkpoint);
+                                    const admissions = (options.listLaunchAdmissions?.() ?? []).filter((admission) => (admission.fence.kind === "ordinal" && admission.fence.ordinal < checkpoint.fence.ordinal));
+                                    for (const receipt of exactLaunchInputReceipts("consumed", checkpoint.fence, admissions))
+                                        options.onTellReceipt?.(receipt);
+                                    options.onTellReceipt?.({ stage: "consumed", correlation: { kind: "fence", fence: checkpoint.fence } });
                                     // Defer end so concurrent enqueue after this result can register openSteerCount.
                                     queueMicrotask(() => maybeEndInputStream());
                                     break;

package/build/agents/providers/claude-agent-sdk/registration.js

@@ -179,7 +179,8 @@ export const claudeAgentSdkRegistration = {
         return loader ? { ...terms, loader } : terms;
     },
     nativePolicyOwnership: () => null,
-    startLive: async ({ terms, signal, reviveTerms, onSyncCheckpoint, onSessionAdmission, onIngress }) => {
+    tellReceiptCapabilities: { seen: "exact", consumed: "fence" },
+    startLive: async ({ terms, signal, reviveTerms, onSyncCheckpoint, onSessionAdmission, onIngress, launchTellIds, observer }) => {
         if (terms.provider !== CLAUDE_AGENT_SDK_PROVIDER) {
             throw new Error(`startLive expected ${CLAUDE_AGENT_SDK_PROVIDER}`);
         }
@@ -196,6 +197,15 @@ export const claudeAgentSdkRegistration = {
             disallowedTools: claudeTerms.disallowedTools,
             systemPrompt: claudeTerms.systemPrompt,
             onSyncCheckpoint,
+            onTellReceipt: observer ? (receipt) => {
+                try {
+                    observer.onTellReceipt(receipt);
+                }
+                catch { /* Receipt persistence cannot alter provider control. */ }
+            } : undefined,
+            launchTellIds,
+            onLaunchAdmission: observer ? (admission) => observer.onLaunchAdmission(admission) : undefined,
+            listLaunchAdmissions: observer ? () => observer.listLaunchAdmissions() : undefined,
             onEvidence: claudeTerms.onEvidence,
             onSessionAdmission,
             onIngress,

package/build/agents/providers/claude-agent-sdk/session.js

@@ -64,10 +64,20 @@ export function createPushableUserMessageStream(onYield) {
         pendingYieldAck.settleResolve();
         pendingYieldAck = undefined;
     };
-    const yieldQueued = (entry) => {
+    const yieldQueued = async (entry) => {
         pullCount += 1;
         pendingYieldAck = entry.ack;
-        onYield?.(entry.message);
+        try {
+            await onYield?.(entry.message);
+        }
+        catch (error) {
+            // A source-pull rejection means the SDK never received this item. Reject
+            // its post-yield acknowledgement before surfacing the provider failure.
+            entry.ack.settleReject(error);
+            if (pendingYieldAck === entry.ack)
+                pendingYieldAck = undefined;
+            throw error;
+        }
         return { value: entry.message, done: false };
     };
     return {
@@ -88,8 +98,12 @@ export function createPushableUserMessageStream(onYield) {
                 // Consumer is already inside next() (previous yield already acked at entry).
                 pullCount += 1;
                 pendingYieldAck = ack;
-                onYield?.(message);
-                waiter.resolve({ value: message, done: false });
+                void Promise.resolve(onYield?.(message)).then(() => waiter.resolve({ value: message, done: false }), (error) => {
+                    ack.settleReject(error);
+                    if (pendingYieldAck === ack)
+                        pendingYieldAck = undefined;
+                    waiter.reject(error);
+                });
                 return { waitSubmitted: () => ack.wait() };
             }
             queue.push({ message, ack });
@@ -128,7 +142,7 @@ export function createPushableUserMessageStream(onYield) {
                         // Per-yield submitted fence: next entry acks the previously yielded message.
                         acknowledgePreviousYield();
                         if (queue.length > 0) {
-                            return Promise.resolve(yieldQueued(queue.shift()));
+                            return yieldQueued(queue.shift());
                         }
                         if (failure !== undefined) {
                             return Promise.reject(failure);

package/build/agents/providers/codex-app-server/adapter.js

@@ -5,7 +5,7 @@ import { createProviderFailure } from "../../harness/provider-adapter.js";
 import { awaitProviderAbortSettlement, buildSubagentEnv, createAbortError, emitProviderEvidence, coerceString, } from "../../harness/runtime.js";
 import { CODEX_APP_SERVER_PROVIDER } from "./identity.js";
 import { CodexAppServerProcess } from "./session.js";
-import { createCodexAppServerTurnMonitor, createCodexAppServerTurnState, recordTurnStartResponse, } from "./events.js";
+import { createCodexAppServerTurnMonitor, createCodexAppServerTurnState, codexAppServerFailureMessage, codexAppServerTurnFailureCause, recordTurnStartResponse, } from "./events.js";
 export { CODEX_APP_SERVER_PROVIDER } from "./identity.js";
 /** Identity-only opacity boundary for codex-app-server turn/start effort. */
 function toCodexAppServerEffort(effort) {
@@ -84,7 +84,7 @@ export async function startCodexAppServer(prompt, cwd, options = {}) {
     appendDebugLog(`startCodexAppServer: executable=${executable} model=${options.model ?? "default"} mode=${resumeThreadId ? "resume" : "fresh"}`, { cwd, section: CODEX_APP_SERVER_PROVIDER });
     const submitSteer = async (tell, turnId) => {
         // turn/steer response {turnId} = enqueue acceptance (submitted), not consumption.
-        // clientUserMessageId = tell.id for later delivered proof via userMessage item clientId.
+        // clientUserMessageId = tell.id for later exact seen proof via userMessage item clientId.
         // tell.text is already core-rendered; send byte-for-byte — never parse or rewrite.
         const ack = await server.request("turn/steer", {
             threadId: activeThreadId,
@@ -111,6 +111,7 @@ export async function startCodexAppServer(prompt, cwd, options = {}) {
     const startTellTurn = async (tell) => {
         const started = await server.request("turn/start", {
             threadId: activeThreadId,
+            clientUserMessageId: tell.id,
             input: [{ type: "text", text: tell.text }],
             ...(options.model ? { model: options.model } : {}),
             ...(tell.effort ? { effort: toCodexAppServerEffort(tell.effort) } : {}),
@@ -249,7 +250,7 @@ export async function startCodexAppServer(prompt, cwd, options = {}) {
                 onEvidence: options.onEvidence,
                 onEvidenceDiagnostic: (text) => builder.emit({ type: "diagnostic", text }),
             });
-            const { turnCompleted } = createCodexAppServerTurnMonitor({
+            const { turnCompleted, reconcileLaunchAdmissions } = createCodexAppServerTurnMonitor({
                 server,
                 builder,
                 state: turnState,
@@ -257,6 +258,8 @@ export async function startCodexAppServer(prompt, cwd, options = {}) {
                 onEvidence: options.onEvidence,
                 onSyncCheckpoint: options.onSyncCheckpoint,
                 onDeliveryOpportunity: options.onDeliveryOpportunity,
+                onTellReceipt: options.onTellReceipt,
+                listLaunchAdmissions: options.listLaunchAdmissions,
                 enqueue,
                 drainPendingTells: () => { void drainPendingTells(); },
                 rejectPendingTells,
@@ -346,6 +349,8 @@ export async function startCodexAppServer(prompt, cwd, options = {}) {
                     ? (turnStart.turn ?? undefined)
                     : undefined;
                 const turnId = recordTurnStartResponse(turnState, turn?.id);
+                await options.onLaunchAdmission?.({ fence: { kind: "turn", turnId }, tellIds: options.launchTellIds ?? [] });
+                reconcileLaunchAdmissions();
                 if (options.onEvidence)
                     emitProviderEvidence(options.onEvidence, { type: "checkpoint", provider: CODEX_APP_SERVER_PROVIDER, fence: { kind: "turn", turnId }, source: "response" }, builderDiagnostic);
                 const completed = await turnCompleted;
@@ -354,9 +359,9 @@ export async function startCodexAppServer(prompt, cwd, options = {}) {
                     throw createAbortError(`${CODEX_APP_SERVER_PROVIDER} turn interrupted`);
                 }
                 if (completed.status === "failed") {
-                    const message = `${CODEX_APP_SERVER_PROVIDER} turn failed`;
-                    throw createProviderFailure(message, {
-                        ...(turnState.failureCause ? { publicCause: turnState.failureCause } : {}),
+                    const publicCause = codexAppServerTurnFailureCause(completed.turn) ?? turnState.failureCause;
+                    throw createProviderFailure(codexAppServerFailureMessage(publicCause), {
+                        ...(publicCause ? { publicCause } : {}),
                     });
                 }
                 if (completed.status !== "completed") {

package/build/agents/providers/codex-app-server/events.js

@@ -1,5 +1,6 @@
 import { boundActivityExcerpt, diffstatFromUnifiedPatch } from "../../harness/activity-values.js";
 import { AGENT_PLAN_ITEM_TEXT_MAX_CHARS, AGENT_PLAN_MAX_ITEMS, AGENT_THOUGHT_TEXT_MAX_CHARS, } from "../../harness/events.js";
+import { exactLaunchInputReceipts } from "../../harness/control-types.js";
 import { createProviderFailure } from "../../harness/provider-adapter.js";
 import { createAbortError, emitProviderEvidence, coerceString } from "../../harness/runtime.js";
 import { CODEX_APP_SERVER_PROVIDER } from "./identity.js";
@@ -174,7 +175,7 @@ export function createCodexAppServerTurnState() {
         lastAgentMessage: "",
     };
 }
-/** Admit only positive native exhaustion evidence; no provider strings survive. */
+/** Admit positive native exhaustion evidence for the typed activity warning. */
 export function codexAppServerRateLimitCause(params) {
     const rateLimits = appServerRecord(appServerRecord(params)?.rateLimits);
     if (!rateLimits)
@@ -182,11 +183,39 @@ export function codexAppServerRateLimitCause(params) {
     for (const value of Object.values(rateLimits)) {
         const window = appServerRecord(value);
         if (typeof window?.usedPercent === "number" && window.usedPercent >= 100) {
-            return { kind: "rate_limit_exhausted" };
+            return { code: "rate_limit_exhausted", message: "rate limit exhausted" };
         }
     }
     return undefined;
 }
+export function codexAppServerTurnFailureCause(turn) {
+    const error = appServerRecord(turn.error);
+    const httpStatus = [error?.httpStatus, error?.status, error?.statusCode, turn.httpStatus, turn.statusCode]
+        .find((value) => typeof value === "number" && Number.isSafeInteger(value));
+    const code = coerceString(error?.code) ?? coerceString(turn.errorCode);
+    const message = coerceString(error?.message) ?? coerceString(turn.error) ?? coerceString(turn.message);
+    return httpStatus === undefined && code === undefined && message === undefined
+        ? undefined
+        : {
+            ...(httpStatus === undefined ? {} : { httpStatus }),
+            ...(code === undefined ? {} : { code }),
+            ...(message === undefined ? {} : { message }),
+        };
+}
+export function codexAppServerFailureMessage(cause) {
+    if (!cause)
+        return `${CODEX_APP_SERVER_PROVIDER} turn failed`;
+    const httpStatus = typeof cause.httpStatus === "number" ? cause.httpStatus : undefined;
+    const code = typeof cause.code === "string" ? cause.code : undefined;
+    const message = typeof cause.message === "string" ? cause.message : undefined;
+    const label = [
+        httpStatus === undefined ? undefined : `HTTP ${httpStatus}`,
+        code,
+    ].filter((part) => part !== undefined).join(" ");
+    if (label && message)
+        return `${label}: ${message}`;
+    return label || message || `${CODEX_APP_SERVER_PROVIDER} turn failed`;
+}
 export function recordActiveTurnId(state, candidate, source) {
     const turnId = coerceString(candidate);
     if (!turnId)
@@ -211,7 +240,24 @@ export function recordTurnStartResponse(state, candidate) {
     return recordActiveTurnId(state, turnId, "response");
 }
 export function createCodexAppServerTurnMonitor(options) {
-    const { server, builder, state, builderDiagnostic, onEvidence, onSyncCheckpoint, onDeliveryOpportunity, enqueue, drainPendingTells, rejectPendingTells, setFailActiveTurn, pendingTellCount, isDrainingTells, setFinishAfterTellDrain, } = options;
+    const { server, builder, state, builderDiagnostic, onEvidence, onSyncCheckpoint, onDeliveryOpportunity, onTellReceipt, listLaunchAdmissions, enqueue, drainPendingTells, rejectPendingTells, setFailActiveTurn, pendingTellCount, isDrainingTells, setFinishAfterTellDrain, } = options;
+    const startedLaunchFences = new Map();
+    const completedLaunchFences = new Map();
+    const emitLaunchReceipts = (stage, fence) => {
+        const admissions = (listLaunchAdmissions?.() ?? []).filter((admission) => (admission.fence.kind === "turn" && fence.kind === "turn"
+            && admission.fence.turnId === fence.turnId));
+        for (const receipt of exactLaunchInputReceipts(stage, fence, admissions))
+            onTellReceipt?.(receipt);
+    };
+    // A notification may arrive between the native response and durable launch
+    // admission. Retain only explicit native turn fences and replay them after
+    // the adapter has recorded the coordinate; no timing inference is involved.
+    const reconcileLaunchAdmissions = () => {
+        for (const fence of startedLaunchFences.values())
+            emitLaunchReceipts("seen", fence);
+        for (const fence of completedLaunchFences.values())
+            emitLaunchReceipts("consumed", fence);
+    };
     const turnCompleted = new Promise((resolve, reject) => {
         let unsubNotifications = () => { };
         let unsubServerRequest = () => { };
@@ -277,6 +323,11 @@ export function createCodexAppServerTurnMonitor(options) {
                                 builder.emit({ type: "message", id, text });
                             }
                         }
+                        else if (itemType === "userMessage") {
+                            const tellId = coerceString(item.clientId);
+                            if (tellId)
+                                onTellReceipt?.({ stage: "seen", correlation: { kind: "exact", tellId } });
+                        }
                         else if (itemType === "reasoning") {
                             const text = extractReasoningSummary(item);
                             if (text) {
@@ -316,6 +367,11 @@ export function createCodexAppServerTurnMonitor(options) {
                         const itemType = coerceString(item.type);
                         if (!id || !itemType)
                             throw new Error(`${CODEX_APP_SERVER_PROVIDER} item/started lacked required item id or type`);
+                        if (itemType === "userMessage") {
+                            const tellId = coerceString(item.clientId);
+                            if (tellId)
+                                onTellReceipt?.({ stage: "seen", correlation: { kind: "exact", tellId } });
+                        }
                         if (isCodexAppServerActivityItemType(itemType)) {
                             builder.emit({
                                 type: "activity",
@@ -331,7 +387,7 @@ export function createCodexAppServerTurnMonitor(options) {
                         const turnId = recordActiveTurnId(state, turn?.id, "notification");
                         builder.emit({ type: "turn", phase: "started" });
                         state.activeTurnAcceptingSteer = true;
-                        const checkpoint = { fence: { kind: "turn", turnId }, consumptionEvidence: false };
+                        const checkpoint = { fence: { kind: "turn", turnId } };
                         if (onEvidence) {
                             emitProviderEvidence(onEvidence, {
                                 type: "checkpoint",
@@ -343,6 +399,8 @@ export function createCodexAppServerTurnMonitor(options) {
                         // turn/start may respond before the server has installed its active
                         // turn. The native notification is the first steer-safe boundary.
                         onSyncCheckpoint?.({ enqueue }, checkpoint);
+                        startedLaunchFences.set(turnId, checkpoint.fence);
+                        emitLaunchReceipts("seen", checkpoint.fence);
                         void drainPendingTells();
                     }
                     if (notification.method === "account/rateLimits/updated") {
@@ -370,7 +428,7 @@ export function createCodexAppServerTurnMonitor(options) {
                             state.activeTurnAcceptingSteer = false;
                             state.activeTurnId = undefined;
                             state.activeTurnSource = undefined;
-                            const checkpoint = { fence: { kind: "turn", turnId }, consumptionEvidence: true };
+                            const checkpoint = { fence: { kind: "turn", turnId } };
                             if (onEvidence) {
                                 emitProviderEvidence(onEvidence, {
                                     type: "checkpoint",
@@ -380,6 +438,9 @@ export function createCodexAppServerTurnMonitor(options) {
                                 }, builderDiagnostic);
                             }
                             onSyncCheckpoint?.({ enqueue }, checkpoint);
+                            completedLaunchFences.set(turnId, checkpoint.fence);
+                            emitLaunchReceipts("consumed", checkpoint.fence);
+                            onTellReceipt?.({ stage: "consumed", correlation: { kind: "fence", fence: checkpoint.fence } });
                             void drainPendingTells();
                             if (pendingTellCount() > 0 || isDrainingTells()) {
                                 setFinishAfterTellDrain(() => {
@@ -427,5 +488,5 @@ export function createCodexAppServerTurnMonitor(options) {
     // Abort can settle this before initialization reaches the await below.
     // Attach a handler immediately while preserving the original awaited error.
     turnCompleted.catch(() => undefined);
-    return { turnCompleted };
+    return { turnCompleted, reconcileLaunchAdmissions };
 }

package/build/agents/providers/codex-app-server/registration.js

@@ -212,7 +212,8 @@ export const codexAppServerRegistration = {
             webSearch: Object.freeze(webSearch),
         });
     },
-    startLive: async ({ terms, signal, reviveTerms, onSyncCheckpoint, onDeliveryOpportunity, onSessionAdmission, onIngress, }) => {
+    tellReceiptCapabilities: { seen: "exact", consumed: "fence" },
+    startLive: async ({ terms, signal, reviveTerms, onSyncCheckpoint, onDeliveryOpportunity, onSessionAdmission, onIngress, launchTellIds, observer, }) => {
         if (terms.provider !== CODEX_APP_SERVER_PROVIDER) {
             throw new Error(`startLive expected ${CODEX_APP_SERVER_PROVIDER}`);
         }
@@ -230,6 +231,15 @@ export const codexAppServerRegistration = {
             developerInstructions: codexTerms.developerInstructions,
             onSyncCheckpoint,
             onDeliveryOpportunity,
+            onTellReceipt: observer ? (receipt) => {
+                try {
+                    observer.onTellReceipt(receipt);
+                }
+                catch { /* Receipt persistence cannot alter provider control. */ }
+            } : undefined,
+            launchTellIds,
+            onLaunchAdmission: observer ? (admission) => observer.onLaunchAdmission(admission) : undefined,
+            listLaunchAdmissions: observer ? () => observer.listLaunchAdmissions() : undefined,
             onEvidence: codexTerms.onEvidence,
             onSessionAdmission,
             onIngress,

package/build/agents/providers/opencode-sdk/adapter.js

@@ -280,6 +280,8 @@ export async function startOpencode(prompt, cwd, options = {}) {
                     onEvidence: options.onEvidence,
                     onSyncCheckpoint: options.onSyncCheckpoint,
                     onDeliveryOpportunity: options.onDeliveryOpportunity,
+                    onTellReceipt: options.onTellReceipt,
+                    listLaunchAdmissions: options.listLaunchAdmissions,
                     executionSignal: combined.signal,
                     getSessionId: () => activeSessionId,
                     client: sdk.client,
@@ -313,7 +315,12 @@ export async function startOpencode(prompt, cwd, options = {}) {
                 // The acquisition itself lives inside streamTask, so local shutdown can
                 // always settle it even when the SDK never resolves events().
                 await eventsResultTask;
-                await promptSteer(sdk.client, prompt);
+                const launchAcknowledgement = await promptSteer(sdk.client, prompt);
+                await options.onLaunchAdmission?.({
+                    fence: launchAcknowledgement.fence,
+                    tellIds: options.launchTellIds ?? [],
+                });
+                eventController?.reconcileLaunchAdmissions();
                 await waitIdle();
                 if (gracefulInterruptRequested) {
                     await gracefulProviderSettlement;

package/build/agents/providers/opencode-sdk/events.js

@@ -1,3 +1,4 @@
+import { exactLaunchInputReceipts } from "../../harness/control-types.js";
 import { activityCallFromNamedTool } from "../../harness/activity-values.js";
 import { AGENT_THOUGHT_TEXT_MAX_CHARS, } from "../../harness/events.js";
 import { createProviderFailure } from "../../harness/provider-adapter.js";
@@ -117,7 +118,7 @@ function extractFinalAssistantMessage(messages) {
     return messages.find((message) => message.type === "assistant");
 }
 export function createOpencodeEventController(options) {
-    const { builder, control, idleMonitorIngress, idleMonitorTerminal, onEvidence, onSyncCheckpoint, onDeliveryOpportunity, getSessionId, client, } = options;
+    const { builder, control, idleMonitorIngress, idleMonitorTerminal, onEvidence, onSyncCheckpoint, onDeliveryOpportunity, onTellReceipt, listLaunchAdmissions, getSessionId, client, } = options;
     const recordedEventTypes = [];
     let totalEventCount = 0;
     let currentTurnAdmitted = false;
@@ -125,6 +126,8 @@ export function createOpencodeEventController(options) {
     let lastTurnFailure;
     let lastSeenSeq = 0;
     let turnOpen = false;
+    const promptedFences = [];
+    const emittedLaunchReceiptKeys = new Set();
     const toolCalls = new Map();
     const requestDelivery = (steerControl) => {
         try {
@@ -134,6 +137,21 @@ export function createOpencodeEventController(options) {
             // Delivery observation cannot alter provider control flow.
         }
     };
+    const reconcileLaunchAdmissions = () => {
+        for (const fence of promptedFences) {
+            const admissions = (listLaunchAdmissions?.() ?? []).filter((admission) => (admission.fence.kind === "ordinal" && fence.kind === "ordinal"
+                && admission.fence.ordinal <= fence.ordinal));
+            for (const receipt of exactLaunchInputReceipts("seen", fence, admissions)) {
+                if (fence.kind !== "ordinal" || receipt.correlation.kind !== "exact")
+                    continue;
+                const key = `${receipt.stage}:${fence.ordinal}:${receipt.correlation.tellId}`;
+                if (emittedLaunchReceiptKeys.has(key))
+                    continue;
+                emittedLaunchReceiptKeys.add(key);
+                onTellReceipt?.(receipt);
+            }
+        }
+    };
     const openTurn = () => {
         if (turnOpen)
             builder.emit({ type: "turn", phase: "completed" });
@@ -169,11 +187,14 @@ export function createOpencodeEventController(options) {
                     currentTurnFailure = undefined;
                     openTurn();
                     if (seq !== undefined) {
-                        const checkpoint = { fence: { kind: "ordinal", ordinal: seq }, consumptionEvidence: true };
+                        const checkpoint = { fence: { kind: "ordinal", ordinal: seq } };
                         if (onEvidence) {
                             emitProviderEvidence(onEvidence, { type: "checkpoint", provider: OPENCODE_SDK_PROVIDER, fence: checkpoint.fence, source: "notification" }, (text) => builder.emit({ type: "diagnostic", text }));
                         }
                         onSyncCheckpoint?.(control, checkpoint);
+                        promptedFences.push(checkpoint.fence);
+                        reconcileLaunchAdmissions();
+                        onTellReceipt?.({ stage: "seen", correlation: { kind: "fence", fence: checkpoint.fence } });
                     }
                     break;
                 }
@@ -346,6 +367,7 @@ export function createOpencodeEventController(options) {
         drainHistory,
         closeTurn,
         lastSeenSeq: () => lastSeenSeq,
+        reconcileLaunchAdmissions,
         lastTurnFailure: () => lastTurnFailure,
         recordedEventTypes: () => recordedEventTypes,
         totalEventCount: () => totalEventCount,