@gajae-code/coding-agent 0.16.7 → 0.17.1

package/src/sdk/lifecycle/service.ts

@@ -9,6 +9,7 @@ import {
 	scopeRequestV1,
 	searchRowV1,
 } from "../broker/session-scope";
+import type { SessionBindingAuthority } from "../session-authority";
 import {
 	SessionListTraversalError,
 	type SessionListTraversalPage,
@@ -16,6 +17,8 @@ import {
 	traverseSessionList,
 } from "../session-list";
 
+export type { SessionBindingAuthority, SessionEndpointAuthority } from "../session-authority";
+
 export type SessionLifecycleOperation =
 	| "session.create"
 	| "session.fork"
@@ -23,8 +26,12 @@ export type SessionLifecycleOperation =
 	| "session.close"
 	| "session.delete"
 	| "session.reconcile_uncertain"
+	| "session.lookup"
 	| "session.list";
 
+export type SessionLifecycleMutationOperation = Exclude<SessionLifecycleOperation, "session.lookup" | "session.list">;
+export type SessionLifecycleLookupOperation = "session.create";
+
 export interface SessionLifecycleActor {
 	readonly id: string;
 	readonly namespace: string;
@@ -122,11 +129,13 @@ export type SessionResumeTarget = SessionLifecycleCoordinatorTarget & {
 	readonly readinessTimeoutMs?: number;
 };
 
-export interface SessionCloseTarget {
-	readonly sessionId: string;
-	readonly endpointGeneration?: number;
-	readonly endpointIncarnation?: string;
-}
+export type SessionCloseTarget =
+	| {
+			readonly sessionId: string;
+			readonly endpointGeneration?: never;
+			readonly endpointIncarnation?: never;
+	  }
+	| SessionBindingAuthority;
 
 export interface SessionReconcileUncertainTarget {
 	readonly sessionId: string;
@@ -155,10 +164,7 @@ export interface SessionListTarget {
 	readonly cursor?: string;
 }
 
-interface SessionLifecycleMutationRequestBase<
-	TOperation extends Exclude<SessionLifecycleOperation, "session.list">,
-	TTarget,
-> {
+interface SessionLifecycleMutationRequestBase<TOperation extends SessionLifecycleMutationOperation, TTarget> {
 	readonly operation: TOperation;
 	readonly actor: SessionLifecycleActor;
 	readonly capability: TOperation;
@@ -184,7 +190,19 @@ export interface SessionListRequest {
 	readonly timeoutMs?: number;
 }
 
-export type SessionLifecycleRequest = SessionLifecycleMutationRequest | SessionListRequest;
+export interface SessionLifecycleLookupRequest {
+	readonly operation: SessionLifecycleLookupOperation;
+	readonly actor: SessionLifecycleActor;
+	readonly capability: "session.lookup";
+	readonly requestKey: string;
+	readonly target: Readonly<Record<string, unknown>>;
+	readonly timeoutMs?: number;
+}
+
+export type SessionLifecycleRequest =
+	| SessionLifecycleMutationRequest
+	| SessionListRequest
+	| SessionLifecycleLookupRequest;
 
 export type SessionLifecycleMutationRequest =
 	| SessionCreateRequest
@@ -209,6 +227,7 @@ export interface SessionLifecycleListEntry {
 	readonly sessionId: string;
 	readonly live?: boolean;
 	readonly endpointGeneration?: number;
+	readonly endpointIncarnation?: string;
 	readonly terminalUncertain?: boolean;
 	readonly cwd?: string;
 	readonly locator?: { readonly cwd: string; readonly worktreeRoot: string | null; readonly stateRoot: string };
@@ -259,6 +278,30 @@ export interface SessionListSuccessResult {
 	readonly result: SessionLifecycleListResult | SessionScopedListResult;
 }
 
+export interface SessionLifecycleLookupIdentity {
+	readonly operation: SessionLifecycleLookupOperation;
+	readonly requestKey: string;
+}
+
+export type SessionLifecycleLookupStatus = "found" | "pending" | "not_found" | "conflict" | "uncertain" | "terminal";
+
+export interface SessionLifecycleLookupSuccessResult {
+	readonly ok: true;
+	readonly operation: "session.lookup";
+	readonly status: "found";
+	readonly request: SessionLifecycleLookupIdentity;
+	readonly result: SessionLifecycleSessionResult;
+}
+
+export interface SessionLifecycleLookupFailure {
+	readonly ok: false;
+	readonly operation: "session.lookup";
+	readonly status: Exclude<SessionLifecycleLookupStatus, "found"> | "unavailable";
+	readonly request: SessionLifecycleLookupIdentity;
+	readonly certainty: SessionLifecycleCertainty;
+	readonly error: SessionLifecycleError;
+}
+
 export interface SessionLifecycleError {
 	readonly code: string;
 	readonly message: string;
@@ -315,6 +358,7 @@ export type SessionCloseOutcome = SessionCloseResult | SessionCloseFailure;
 export type SessionDeleteOutcome = SessionDeleteResult | SessionDeleteFailure;
 export type SessionReconcileUncertainOutcome = SessionReconcileUncertainResult | SessionReconcileUncertainFailure;
 export type SessionListOutcome = SessionListSuccessResult | SessionListFailure;
+export type SessionLifecycleLookupOutcome = SessionLifecycleLookupSuccessResult | SessionLifecycleLookupFailure;
 export type SessionLifecycleResult =
 	| SessionCreateOutcome
 	| SessionForkOutcome
@@ -322,13 +366,14 @@ export type SessionLifecycleResult =
 	| SessionCloseOutcome
 	| SessionDeleteOutcome
 	| SessionReconcileUncertainOutcome
-	| SessionListOutcome;
+	| SessionListOutcome
+	| SessionLifecycleLookupOutcome;
 
 /** Shared, side-effect-free validation for lifecycle mutation requests. */
 export type SessionLifecycleMutationValidation =
 	| {
 			readonly ok: true;
-			readonly operation: Exclude<SessionLifecycleOperation, "session.list">;
+			readonly operation: SessionLifecycleMutationOperation;
 			readonly actor: SessionLifecycleActor;
 			readonly requestKey: string;
 			readonly target: Readonly<Record<string, unknown>>;
@@ -381,7 +426,7 @@ export function deriveSessionLifecycleIdempotencyKey(
 	return createHash("sha256").update(canonicalJson(identity), "utf8").digest("hex");
 }
 
-function operationOf(value: unknown): SessionLifecycleOperation {
+function operationOf(value: unknown): SessionLifecycleMutationOperation | "session.list" {
 	if (
 		value === "session.create" ||
 		value === "session.fork" ||
@@ -395,7 +440,7 @@ function operationOf(value: unknown): SessionLifecycleOperation {
 	return "session.list";
 }
 
-function failure<TOperation extends SessionLifecycleOperation>(
+function failure<TOperation extends SessionLifecycleMutationOperation | "session.list">(
 	operation: TOperation,
 	certainty: SessionLifecycleCertainty,
 	code: string,
@@ -427,6 +472,20 @@ function validTarget(target: unknown): target is Readonly<Record<string, unknown
 	return isRecord(target);
 }
 
+function validSessionCloseTarget(target: Readonly<Record<string, unknown>>): boolean {
+	const hasGeneration = Object.hasOwn(target, "endpointGeneration");
+	const hasIncarnation = Object.hasOwn(target, "endpointIncarnation");
+	if (hasGeneration !== hasIncarnation) return false;
+	if (!hasGeneration) return true;
+	return (
+		typeof target.endpointGeneration === "number" &&
+		Number.isSafeInteger(target.endpointGeneration) &&
+		target.endpointGeneration > 0 &&
+		typeof target.endpointIncarnation === "string" &&
+		/^[a-f0-9]{64}$/u.test(target.endpointIncarnation)
+	);
+}
+
 export function validateSessionReconcileUncertainTarget(value: unknown): value is SessionReconcileUncertainTarget {
 	if (!isRecord(value)) return false;
 	const target = value;
@@ -468,6 +527,8 @@ export function validateSessionLifecycleMutationRequest(request: unknown): Sessi
 		return failure(operation, "terminal", "capability_denied", `capability does not authorize ${operation}`);
 	if (!validTarget(record.target))
 		return failure(operation, "terminal", "invalid_request", "target must be an object");
+	if (operation === "session.close" && !validSessionCloseTarget(record.target))
+		return failure(operation, "terminal", "invalid_input", "session.close endpoint authority is invalid");
 	if (operation === "session.reconcile_uncertain" && !validateSessionReconcileUncertainTarget(record.target))
 		return failure(
 			operation,
@@ -503,6 +564,23 @@ function credentialFreeRecord(value: Record<string, unknown>): Record<string, un
 	return output;
 }
 
+function sessionEndpointProjection(value: Record<string, unknown>): {
+	endpointGeneration?: number;
+	endpointIncarnation?: string;
+} {
+	const endpointGeneration = value.endpointGeneration;
+	const endpointIncarnation = value.endpointIncarnation;
+	if (
+		typeof endpointGeneration !== "number" ||
+		!Number.isSafeInteger(endpointGeneration) ||
+		endpointGeneration <= 0 ||
+		typeof endpointIncarnation !== "string" ||
+		!/^[a-f0-9]{64}$/u.test(endpointIncarnation)
+	)
+		return {};
+	return { endpointGeneration, endpointIncarnation };
+}
+
 function sessionResult(value: unknown, expectedSessionId?: string): SessionLifecycleSessionResult | undefined {
 	if (!isRecord(value)) return undefined;
 	const record = credentialFreeRecord(value);
@@ -515,13 +593,8 @@ function sessionResult(value: unknown, expectedSessionId?: string): SessionLifec
 		endpointIncarnation?: string;
 		reused?: boolean;
 		note?: string;
-	} = { sessionId };
+	} = { sessionId, ...sessionEndpointProjection(record) };
 	if (typeof record.cwd === "string") result.cwd = record.cwd;
-	const endpointGeneration = record.endpointGeneration;
-	if (typeof endpointGeneration === "number" && Number.isSafeInteger(endpointGeneration) && endpointGeneration > 0)
-		result.endpointGeneration = endpointGeneration;
-	if (typeof record.endpointIncarnation === "string" && /^[a-f0-9]{64}$/.test(record.endpointIncarnation))
-		result.endpointIncarnation = record.endpointIncarnation;
 	if (typeof record.reused === "boolean") result.reused = record.reused;
 	if (typeof record.note === "string") result.note = record.note;
 	return result;
@@ -601,12 +674,12 @@ function listResult(value: unknown): SessionLifecycleListResult | undefined {
 			sessionId: string;
 			live?: boolean;
 			endpointGeneration?: number;
+			endpointIncarnation?: string;
 			terminalUncertain?: boolean;
 			cwd?: string;
 			locator?: { cwd: string; worktreeRoot: string | null; stateRoot: string };
-		} = { sessionId: entry.sessionId };
+		} = { sessionId: entry.sessionId, ...sessionEndpointProjection(entry) };
 		if (typeof entry.live === "boolean") item.live = entry.live;
-		if (typeof entry.endpointGeneration === "number") item.endpointGeneration = entry.endpointGeneration;
 		if (typeof entry.terminalUncertain === "boolean") item.terminalUncertain = entry.terminalUncertain;
 		if (isRecord(entry.locator) && typeof entry.locator.cwd === "string") item.cwd = entry.locator.cwd;
 		if (
@@ -746,6 +819,26 @@ function certaintyForThrownError(error: {
 	return "retryable";
 }
 
+function lookupStatusForError(code: string): {
+	status: Exclude<SessionLifecycleLookupStatus, "found"> | "unavailable";
+	certainty: SessionLifecycleCertainty;
+} {
+	if (code === "not_found") return { status: "not_found", certainty: "uncertain" };
+	if (code === "idempotency_conflict") return { status: "conflict", certainty: "uncertain" };
+	if (code === "lifecycle_pending") return { status: "pending", certainty: "uncertain" };
+	if (code === "terminal_uncertain") return { status: "uncertain", certainty: "uncertain" };
+	return { status: "terminal", certainty: certaintyForBrokerCode(code) };
+}
+
+function lookupFailure(
+	request: SessionLifecycleLookupIdentity,
+	status: Exclude<SessionLifecycleLookupStatus, "found"> | "unavailable",
+	certainty: SessionLifecycleCertainty,
+	error: SessionLifecycleError,
+): SessionLifecycleLookupFailure {
+	return { ok: false, operation: "session.lookup", status, request, certainty, error };
+}
+
 function brokerSuccess(value: unknown): unknown | undefined {
 	if (!isRecord(value) || value.ok !== true) return undefined;
 	return value.result;
@@ -758,6 +851,90 @@ export class SessionLifecycleService {
 		this.#client = client;
 	}
 
+	async lookup(request: SessionLifecycleLookupRequest): Promise<SessionLifecycleLookupOutcome> {
+		const operation = request.operation;
+		const requestKey = typeof request.requestKey === "string" ? request.requestKey : "";
+		const identity: SessionLifecycleLookupIdentity = { operation, requestKey };
+		if (!validActor(request.actor))
+			return lookupFailure(identity, "terminal", "terminal", {
+				code: "unauthorized",
+				message: "authenticated actor is required",
+			});
+		if (request.capability !== "session.lookup")
+			return lookupFailure(identity, "terminal", "terminal", {
+				code: "capability_denied",
+				message: "capability does not authorize session.lookup",
+			});
+		if (!validRequestKey(request.requestKey))
+			return lookupFailure(identity, "terminal", "terminal", {
+				code: "invalid_request",
+				message: "requestKey is required",
+			});
+		if (!validTarget(request.target))
+			return lookupFailure(identity, "terminal", "terminal", {
+				code: "invalid_request",
+				message: "target must be an object",
+			});
+
+		const validation = validateSessionLifecycleMutationRequest({
+			operation,
+			actor: request.actor,
+			capability: operation,
+			requestKey: request.requestKey,
+			target: request.target,
+		});
+		if (!validation.ok) return lookupFailure(identity, "terminal", validation.certainty, validation.error);
+
+		let response: unknown;
+		try {
+			response = await this.#client.global(
+				"session.lookup",
+				{ operation, target: { ...validation.target } },
+				{
+					idempotencyKey: deriveSessionLifecycleIdempotencyKey(request.actor, request.requestKey, operation),
+					...(request.timeoutMs === undefined ? {} : { timeoutMs: request.timeoutMs }),
+				},
+			);
+		} catch (thrown) {
+			const error = brokerError(thrown) ?? brokerErrorFromThrown(thrown);
+			if (error) {
+				const mapped = lookupStatusForError(error.code);
+				const transport = TRANSPORT_ERROR_CODES.has(error.code);
+				return lookupFailure(
+					identity,
+					transport ? "unavailable" : mapped.status,
+					transport ? certaintyForThrownError(error) : mapped.certainty,
+					{
+						code: error.code,
+						message: error.message,
+					},
+				);
+			}
+			return lookupFailure(identity, "unavailable", "retryable", {
+				code: "unavailable",
+				message: "lifecycle broker request was unavailable",
+			});
+		}
+
+		const error = brokerError(response);
+		if (error) {
+			const mapped = lookupStatusForError(error.code);
+			return lookupFailure(identity, mapped.status, mapped.certainty, error);
+		}
+		if (!isRecord(response) || response.ok !== true)
+			return lookupFailure(identity, "uncertain", "uncertain", {
+				code: "malformed_response",
+				message: "lifecycle broker returned a malformed lookup result",
+			});
+		const result = sessionResult(brokerSuccess(response));
+		if (!result)
+			return lookupFailure(identity, "uncertain", "uncertain", {
+				code: "malformed_response",
+				message: "lifecycle broker returned a malformed session result",
+			});
+		return { ok: true, operation: "session.lookup", status: "found", request: identity, result };
+	}
+
 	async scopedList(scope: ScopeRequestV1, limit?: number, cursor?: string): Promise<SessionListOutcome> {
 		return await this.#list(
 			{

package/src/sdk/mcp/server.ts

@@ -150,7 +150,7 @@ function mcpOperationError(
 const MCP_LIFECYCLE_ACTOR = { id: "gjc-sdk-mcp", namespace: "sdk:mcp" } as const;
 const ROUTER_START_TIMEOUT_MS = 3_000;
 const ROUTER_STOP_TIMEOUT_MS = 5_000;
-type LifecycleMutationOperation = Exclude<SessionLifecycleOperation, "session.list">;
+type LifecycleMutationOperation = Exclude<SessionLifecycleOperation, "session.lookup" | "session.list">;
 
 function isLifecycleOperation(operation: string): operation is LifecycleMutationOperation {
 	return (

package/src/sdk/prompt-deadline-lease.ts

@@ -11,7 +11,12 @@
  */
 
 /** Agent session event types that constitute attributable agent/skill/tool progress. */
-const ATTRIBUTABLE_PROGRESS_EVENT_TYPES = new Set(["tool_execution_start", "tool_execution_end"]);
+const ATTRIBUTABLE_PROGRESS_EVENT_TYPES = new Set([
+	"tool_execution_start",
+	/** Periodic output from a running tool; renews the deadline for long-running tools (e.g. Gradle compiles). */
+	"tool_execution_update",
+	"tool_execution_end",
+]);
 
 export interface PromptDeadlineLease {
 	/** When the prompt was accepted; anchors the hard maximum runtime. */
@@ -57,9 +62,12 @@ export function recordAttributableProgress(lease: PromptDeadlineLease, now: numb
 
 /**
  * Whether an agent session event at the prompt/agent runtime boundary is
- * attributable progress for the accepted prompt. Only tool execution
- * boundaries qualify: skills do their work through tools, so skill progress is
- * covered; streaming text/thinking deltas, retries, and bookkeeping are not.
+ * attributable progress for the accepted prompt. Tool execution boundaries and
+ * streaming updates qualify: skills do their work through tools, so skill
+ * progress is covered; `tool_execution_update` keeps long-running tools (e.g.
+ * a multi-minute Gradle compile that streams stdout) from tripping the
+ * inactivity deadline mid-run. Streaming text/thinking deltas, retries, and
+ * bookkeeping are not attributable.
  */
 export function isAttributableProgressEventType(type: string): boolean {
 	return ATTRIBUTABLE_PROGRESS_EVENT_TYPES.has(type);

package/src/sdk/prompt-deadline-manager.ts

@@ -7,6 +7,7 @@ import {
 	promptDeadlineAt,
 	recordAttributableProgress,
 } from "./prompt-deadline-lease";
+import { failedPromptOutcome } from "./prompt-failure";
 import type { SdkPromptTerminalOutcome } from "./prompt-status";
 import type { TurnResultContent } from "./turn-result";
 
@@ -17,10 +18,8 @@ const UNCERTAINTY_RETRY_DELAY_MS = 1_000;
 
 type DeadlineReconciliation = InvocationReconciliation | KindAwareReconciliation;
 
-export type PromptDeadlineOutcome = {
-	kind: "failed";
+export type PromptDeadlineOutcome = Extract<SdkPromptTerminalOutcome, { kind: "failed" }> & {
 	code: "prompt_deadline_exceeded";
-	message: string;
 	provenance: "deadline";
 };
 
@@ -161,12 +160,11 @@ export class PromptDeadlineManager {
 			return;
 		}
 		const generation = lease.generation;
-		const outcome: PromptDeadlineOutcome = {
-			kind: "failed",
+		const outcome: PromptDeadlineOutcome = failedPromptOutcome({
 			code: "prompt_deadline_exceeded",
-			message: "Prompt deadline exceeded.",
 			provenance: "deadline",
-		};
+			evidence: {},
+		}) as PromptDeadlineOutcome;
 		try {
 			await this.#reconciliation.claimPendingOutcome("prompt", correlation, outcome);
 		} catch {

package/src/sdk/prompt-failure.ts

@@ -3,9 +3,157 @@
  * Provider error text is retained only in the local diagnostic log; wire and
  * persisted reconciliation details expose a fixed redacted message.
  */
+import type { SdkPromptFailureCategory, SdkPromptFailurePhase, SdkPromptTerminalOutcome } from "./prompt-status";
+
 export const PROMPT_FAILURE_CODE_MAX = 64;
 const LOCAL_FAILURE_LOG_MAX = 16_384;
 
+export const PROMPT_FAILURE_MESSAGE_SUBMISSION = "Prompt submission failed.";
+export const PROMPT_FAILURE_MESSAGE_POST_START_PROVIDER = "Provider failure after execution started.";
+export const PROMPT_FAILURE_MESSAGE_POST_START_AGENT = "Agent run failed after execution started.";
+export const PROMPT_FAILURE_MESSAGE_DEADLINE = "Prompt deadline exceeded.";
+
+/** Evidence that decides whether a failure happened before or after the run started. */
+export interface PromptFailureEvidence {
+	startedAt?: number;
+	hasActivity?: boolean;
+}
+
+/** Start/activity evidence for phase derivation from a reconciliation record. */
+export function failureEvidence(record: { startedAt?: number }, hasActivity?: boolean): PromptFailureEvidence {
+	return {
+		...(record.startedAt !== undefined ? { startedAt: record.startedAt } : {}),
+		...(hasActivity === true ? { hasActivity: true } : {}),
+	};
+}
+
+/**
+ * Bounded classifier sets. Only these safe tokens may select a category; any
+ * other value (including `undefined`) stays `unknown` instead of guessing, so
+ * an unrecognized or provider-invented code cannot masquerade as a known class.
+ */
+const PROVIDER_TRANSPORT_CODES = new Set([
+	"provider_down",
+	"provider_unavailable",
+	"upstream_stream_interrupted",
+	"upstream_error",
+	"transport_reset",
+	"stream_first_event_timeout",
+	"empty_response",
+	"server_is_overloaded",
+]);
+const PROVIDER_REJECTED_CODES = new Set(["provider_rejected", "provider_http_402", "provider_http_429"]);
+const AGENT_RUNTIME_CODES = new Set([
+	"agent_failed",
+	"internal",
+	"local_snapshot_failure",
+	"local_buffer_overflow",
+	"argument_validation",
+	"execution",
+	"io_error",
+	"skill_runtime",
+	"escaped_arguments_discarded",
+	"prompt_failed",
+	"aborted",
+]);
+
+/** Whether the run had already started when the failure was recorded. */
+export function promptFailurePhase(evidence: PromptFailureEvidence): SdkPromptFailurePhase {
+	return evidence.startedAt !== undefined || evidence.hasActivity === true ? "post_start" : "submission";
+}
+
+export function isSdkPromptFailurePhase(value: unknown): value is SdkPromptFailurePhase {
+	return value === "submission" || value === "post_start";
+}
+
+/** Allowlisted origin category for a bounded safe classifier + provenance. */
+export function promptFailureCategory(
+	code: string | undefined,
+	provenance: "agent_failed" | "deadline",
+): SdkPromptFailureCategory {
+	if (provenance === "deadline" || code === "prompt_deadline_exceeded") return "deadline";
+	if (code === undefined) return "unknown";
+	if (PROVIDER_TRANSPORT_CODES.has(code) || /^provider_http_5\d\d$/.test(code)) return "provider_transport";
+	if (PROVIDER_REJECTED_CODES.has(code) || /^provider_http_4\d\d$/.test(code)) return "provider_rejected";
+	if (AGENT_RUNTIME_CODES.has(code)) return "agent_runtime";
+	return "unknown";
+}
+
+/**
+ * Phase- and category-aware safe wording. A post-start failure is never
+ * described as a submission rejection; the wording says only what the bounded
+ * category actually proves.
+ */
+export function promptFailureMessage(phase: SdkPromptFailurePhase, category: SdkPromptFailureCategory): string {
+	if (category === "deadline") return PROMPT_FAILURE_MESSAGE_DEADLINE;
+	if (phase === "submission") return PROMPT_FAILURE_MESSAGE_SUBMISSION;
+	if (category === "provider_transport" || category === "provider_rejected")
+		return PROMPT_FAILURE_MESSAGE_POST_START_PROVIDER;
+	return PROMPT_FAILURE_MESSAGE_POST_START_AGENT;
+}
+
+/**
+ * Recompute `phase`, `category` and `message` for a failed outcome from the
+ * bounded classifier plus the record's start/activity evidence. Non-failed
+ * outcomes pass through untouched. Idempotent.
+ */
+export function rephaseFailedOutcome(
+	outcome: SdkPromptTerminalOutcome,
+	evidence: PromptFailureEvidence,
+): SdkPromptTerminalOutcome {
+	if (outcome.kind !== "failed") return outcome;
+	const category = promptFailureCategory(outcome.providerCode ?? outcome.code, outcome.provenance);
+	const phase = promptFailurePhase(evidence);
+	const message = promptFailureMessage(phase, category);
+	if (category === outcome.category && phase === outcome.phase && message === outcome.message) return outcome;
+	return { ...outcome, category, phase, message };
+}
+
+/** Build a complete failed outcome from a bounded classifier and evidence. */
+export function failedPromptOutcome(input: {
+	code: "prompt_failed" | "prompt_deadline_exceeded";
+	provenance: "agent_failed" | "deadline";
+	providerCode?: string;
+	phase?: SdkPromptFailurePhase;
+	evidence: PromptFailureEvidence;
+}): Extract<SdkPromptTerminalOutcome, { kind: "failed" }> {
+	const category = promptFailureCategory(input.providerCode ?? input.code, input.provenance);
+	const phase = input.phase ?? promptFailurePhase(input.evidence);
+	return {
+		kind: "failed",
+		code: input.code,
+		message: promptFailureMessage(phase, category),
+		provenance: input.provenance,
+		phase,
+		category,
+		...(input.providerCode !== undefined ? { providerCode: input.providerCode } : {}),
+	};
+}
+
+/**
+ * Bounded safe classifier read off a terminal assistant message: the provider's
+ * own `errorCode`, else the typed transport fact's `providerCode`. Only a safe
+ * token is accepted; anything else is dropped rather than forwarded.
+ */
+export function assistantFailureCode(assistant: unknown): string | undefined {
+	try {
+		const candidate = assistant as { errorCode?: unknown; transportFailure?: { providerCode?: unknown } } | undefined;
+		const direct = candidate?.errorCode;
+		if (typeof direct === "string" && direct.length <= PROMPT_FAILURE_CODE_MAX && /^[A-Za-z0-9._-]+$/.test(direct))
+			return direct;
+		const transport = candidate?.transportFailure?.providerCode;
+		if (
+			typeof transport === "string" &&
+			transport.length <= PROMPT_FAILURE_CODE_MAX &&
+			/^[A-Za-z0-9._-]+$/.test(transport)
+		)
+			return transport;
+		return undefined;
+	} catch {
+		return undefined;
+	}
+}
+
 /** Safe-token code capped at 64; arbitrary failure text is never retained. */
 export function sanitizePromptFailure(error: unknown): { code: string; message: string } {
 	let rawCode = "";

package/src/sdk/prompt-status.ts

@@ -57,9 +57,38 @@ import type { ReceiptState } from "./receipt-state";
 export type PromptReconciliationStatus = "accepted" | "in_flight" | "terminal_ok" | "failed";
 export type SdkPromptStopReason = "end_turn" | "max_tokens" | "max_turn_requests" | "refusal" | "cancelled";
 export type SdkPromptFailureCode = "prompt_failed" | "prompt_deadline_exceeded";
+/**
+ * Stable, safe execution phase of a failed prompt. `submission` means the
+ * failure happened before the run started (a genuine submission rejection);
+ * `post_start` means the run had already started, so it must never be described
+ * as a submission rejection.
+ */
+export type SdkPromptFailurePhase = "submission" | "post_start";
+/**
+ * Allowlisted, bounded origin category for a failed prompt. It is derived only
+ * from safe classifiers (never raw provider text) and preserves `unknown` when
+ * attribution is uncertain instead of guessing.
+ */
+export type SdkPromptFailureCategory =
+	| "provider_transport"
+	| "provider_rejected"
+	| "agent_runtime"
+	| "deadline"
+	| "unknown";
 export type SdkPromptTerminalOutcome =
 	| { kind: "stopped"; reason: SdkPromptStopReason; provenance: "agent" | "client_cancel" }
-	| { kind: "failed"; code: SdkPromptFailureCode; message: string; provenance: "agent_failed" | "deadline" };
+	| {
+			kind: "failed";
+			code: SdkPromptFailureCode;
+			message: string;
+			provenance: "agent_failed" | "deadline";
+			/** Execution phase at failure time; never a submission rejection when post_start. */
+			phase: SdkPromptFailurePhase;
+			/** Bounded failure-origin category; `unknown` when attribution is uncertain. */
+			category: SdkPromptFailureCategory;
+			/** Bounded safe provider/transport classifier when the provider supplied one. */
+			providerCode?: string;
+	  };
 
 /** Exactly one selector per lookup. */
 export type TurnPromptStatusSelector = { clientRef: string } | { commandId: string; turnId: string };

package/src/sdk/prompt-watchdog.ts

@@ -115,9 +115,17 @@ export class PromptActivity {
 			this.#awaitingModel = true;
 			return;
 		}
-		// Streamed content/thinking/tool-call deltas, and the tool call the model asked for,
-		// are only ever produced by an answering model.
-		if (eventType === "message_update" || eventType === "tool_execution_start") {
+		// `message_update` is a streaming chunk: the model is still producing this response,
+		// so the gap that follows it is another inference gap, not a dead producer. Clearing
+		// `#awaitingModel` here would drop the turn to the narrow idle bound mid-stream, and a
+		// slow next chunk would be killed at that bound (issue #5571). The stream only truly
+		// ends at `message_end` (role=assistant) below, so `message_update` is intentionally
+		// left as an active model signal and does not clear inference state.
+		//
+		// The tool call the model asked for, by contrast, marks the model's turn as answered:
+		// inference has produced its result, and any following gap is governed by the tool
+		// bound while that tool runs.
+		if (eventType === "tool_execution_start") {
 			this.#awaitingModel = false;
 			return;
 		}