@gajae-code/coding-agent 0.17.6 → 0.17.7

package/src/sdk/lifecycle/service.ts

@@ -11,6 +11,9 @@ import {
 } from "../broker/session-scope";
 import type { SessionBindingAuthority } from "../session-authority";
 import {
+	SESSION_LIST_SAVED_SESSION_OMISSION_DETAIL_CODES,
+	type SessionListSavedSessionOmission,
+	type SessionListSavedSessionOmissionDetailCode,
 	SessionListTraversalError,
 	type SessionListTraversalPage,
 	sessionListPageFromResponse,
@@ -238,6 +241,7 @@ export interface SessionLifecycleListResult {
 	readonly sessions: readonly SessionLifecycleListEntry[];
 	readonly warnings: readonly string[];
 	readonly savedSession?: SessionLifecycleSavedSession;
+	readonly savedSessionOmission?: SessionListSavedSessionOmission;
 }
 
 export type SessionScopedListResult = SdkSearchResultV1;
@@ -652,11 +656,118 @@ function savedSessionTranscriptIdentity(value: unknown): SessionLifecycleSavedSe
 function savedSessionFromResult(value: unknown): SessionLifecycleSavedSession | undefined {
 	if (!isRecord(value)) return undefined;
 	const identity = savedSessionTranscriptIdentity(value.identity);
-	if (typeof value.id !== "string" || typeof value.path !== "string" || value.path.length === 0 || !identity)
+	if (
+		typeof value.id !== "string" ||
+		!/^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/.test(value.id) ||
+		typeof value.path !== "string" ||
+		value.path.length === 0 ||
+		!identity
+	)
 		return undefined;
 	return { id: value.id, path: value.path, identity };
 }
 
+const savedSessionOmissionFields = new Set([
+	"sessionId",
+	"reason",
+	"detailCode",
+	"candidateCount",
+	"missingIdentityFields",
+]);
+const savedSessionOmissionDetailCodes = new Set<string>(SESSION_LIST_SAVED_SESSION_OMISSION_DETAIL_CODES);
+const savedSessionScopeDetailCodes = new Set([
+	"cwd_missing",
+	"cwd_not_directory",
+	"identity_unavailable",
+	"network_unsupported",
+	"sessions_root_unavailable",
+	"binding_conflict",
+	"binding_invalid",
+	"migration_busy",
+	"atomic_unavailable",
+	"invalid_request",
+	"durability_failed",
+	"durability_not_provable",
+	"capacity_exceeded",
+]);
+const savedSessionScanDetailCodes = new Set(["scan_failed", "unsafe_root", "invalid_candidate"]);
+const savedSessionCandidateDetailCodes = new Set([
+	"invalid_header",
+	"unreadable_candidate",
+	"source_changed",
+	"cwd_not_found",
+	"cwd_not_directory",
+	"cwd_not_utf8",
+	"cwd_network_unsupported",
+	"cwd_identity_unavailable",
+	"cwd_io_error",
+]);
+
+function isSafeSavedSessionOmissionDetailCode(value: unknown): value is SessionListSavedSessionOmissionDetailCode {
+	return typeof value === "string" && savedSessionOmissionDetailCodes.has(value);
+}
+
+function savedSessionOmissionDetailMatchesReason(
+	reason: SessionListSavedSessionOmission["reason"],
+	detailCode: SessionListSavedSessionOmissionDetailCode,
+): boolean {
+	if (reason === "scope_unavailable") return savedSessionScopeDetailCodes.has(detailCode);
+	if (reason === "candidate_scan_failed") return savedSessionScanDetailCodes.has(detailCode);
+	if (reason === "candidate_invalid") return savedSessionCandidateDetailCodes.has(detailCode);
+	return false;
+}
+
+function savedSessionOmissionFromResult(value: unknown): SessionListSavedSessionOmission | undefined {
+	if (!isRecord(value)) return undefined;
+	if (Object.keys(value).some(field => !savedSessionOmissionFields.has(field))) return undefined;
+	if (
+		typeof value.sessionId !== "string" ||
+		!/^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/.test(value.sessionId) ||
+		(value.reason !== "scope_unavailable" &&
+			value.reason !== "candidate_scan_failed" &&
+			value.reason !== "candidate_not_found" &&
+			value.reason !== "candidate_ambiguous" &&
+			value.reason !== "candidate_invalid" &&
+			value.reason !== "identity_incomplete")
+	)
+		return undefined;
+	if (
+		value.detailCode !== undefined &&
+		(!isSafeSavedSessionOmissionDetailCode(value.detailCode) ||
+			!savedSessionOmissionDetailMatchesReason(value.reason, value.detailCode))
+	)
+		return undefined;
+	if (
+		value.candidateCount !== undefined &&
+		(value.reason !== "candidate_ambiguous" ||
+			typeof value.candidateCount !== "number" ||
+			!Number.isSafeInteger(value.candidateCount) ||
+			value.candidateCount < 2)
+	)
+		return undefined;
+	let missingIdentityFields: ("nlink" | "ctimeNs")[] | undefined;
+	if (value.missingIdentityFields !== undefined) {
+		if (
+			value.reason !== "identity_incomplete" ||
+			!Array.isArray(value.missingIdentityFields) ||
+			value.missingIdentityFields.length === 0 ||
+			value.missingIdentityFields.some(field => field !== "nlink" && field !== "ctimeNs") ||
+			new Set(value.missingIdentityFields).size !== value.missingIdentityFields.length
+		)
+			return undefined;
+		missingIdentityFields = value.missingIdentityFields as ("nlink" | "ctimeNs")[];
+	}
+	if (value.reason === "candidate_ambiguous" && value.candidateCount === undefined) return undefined;
+	if (value.reason === "identity_incomplete" && missingIdentityFields === undefined) return undefined;
+	return {
+		sessionId: value.sessionId,
+		reason: value.reason,
+		...(value.detailCode === undefined ? {} : { detailCode: value.detailCode }),
+		...(value.candidateCount === undefined ? {} : { candidateCount: value.candidateCount }),
+		...(missingIdentityFields === undefined ? {} : { missingIdentityFields }),
+	};
+}
+
 function listResult(value: unknown): SessionLifecycleListResult | undefined {
 	if (!isRecord(value) || !Array.isArray(value.sessions)) return undefined;
 	const indexSeq = value.indexSeq;
@@ -702,8 +813,19 @@ function listResult(value: unknown): SessionLifecycleListResult | undefined {
 	}
 	const savedSessionPresent = Object.hasOwn(value, "savedSession");
 	const savedSession = savedSessionPresent ? savedSessionFromResult(value.savedSession) : undefined;
-	if (savedSessionPresent && !savedSession) return undefined;
-	return { indexSeq, sessions, warnings, ...(savedSession ? { savedSession } : {}) };
+	const savedSessionOmissionPresent = Object.hasOwn(value, "savedSessionOmission");
+	const savedSessionOmission = savedSessionOmissionPresent
+		? savedSessionOmissionFromResult(value.savedSessionOmission)
+		: undefined;
+	if (savedSessionPresent && (!savedSession || savedSessionOmissionPresent)) return undefined;
+	if (savedSessionOmissionPresent && !savedSessionOmission) return undefined;
+	return {
+		indexSeq,
+		sessions,
+		warnings,
+		...(savedSession ? { savedSession } : {}),
+		...(savedSessionOmission ? { savedSessionOmission } : {}),
+	};
 }
 
 function scopedPage(value: unknown): { scope: SdkSearchResultV1["scope"]; observedAt: string } | undefined {
@@ -993,6 +1115,13 @@ export class SessionLifecycleService {
 				"malformed_response",
 				"lifecycle broker returned a malformed scoped list result",
 			);
+		if (result.savedSession !== undefined || result.savedSessionOmission !== undefined)
+			return failure(
+				"session.list",
+				"uncertain",
+				"malformed_response",
+				"lifecycle broker attached an exact saved session to a scoped list result",
+			);
 		if (JSON.stringify(pageScope.scope) !== JSON.stringify(locallyResolvedScope))
 			return failure(
 				"session.list",
@@ -1178,6 +1307,35 @@ export class SessionLifecycleService {
 		const scopeRequest = target.scope === undefined ? undefined : scopeRequestV1(target.scope);
 		if (target.scope !== undefined && !scopeRequest)
 			return failure("session.list", "terminal", "invalid_request", "scope must be a valid ScopeRequestV1");
+		if (target.cwd !== undefined && (typeof target.cwd !== "string" || target.cwd.length === 0))
+			return failure("session.list", "terminal", "invalid_request", "cwd must be a non-empty string");
+		if (target.cursor !== undefined && (typeof target.cursor !== "string" || target.cursor.length === 0))
+			return failure("session.list", "terminal", "invalid_request", "cursor must be a non-empty opaque string");
+		if (
+			target.resolveSessionId !== undefined &&
+			(typeof target.resolveSessionId !== "string" ||
+				!/^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/.test(target.resolveSessionId))
+		)
+			return failure(
+				"session.list",
+				"terminal",
+				"invalid_request",
+				"resolveSessionId must be a canonical safe identifier",
+			);
+		if (scopeRequest !== undefined && (target.cwd !== undefined || target.resolveSessionId !== undefined))
+			return failure(
+				"session.list",
+				"terminal",
+				"invalid_request",
+				"cwd and resolveSessionId cannot be combined with a scoped session.list target",
+			);
+		if (target.cursor !== undefined && target.resolveSessionId !== undefined)
+			return failure(
+				"session.list",
+				"terminal",
+				"invalid_request",
+				"cursor cannot be combined with resolveSessionId",
+			);
 		let locallyResolvedScope: SdkSearchResultV1["scope"] | undefined;
 		if (scopeRequest !== undefined) {
 			try {
@@ -1253,6 +1411,30 @@ export class SessionLifecycleService {
 				"lifecycle broker returned a malformed list result",
 			);
 		const { result } = firstPage.page;
+		const requestedSessionId = typeof target.resolveSessionId === "string" ? target.resolveSessionId : undefined;
+		const exactSavedSessionTarget = requestedSessionId !== undefined && typeof target.cwd === "string";
+		if (requestedSessionId !== undefined && pages.length > 1)
+			return failure(
+				"session.list",
+				"uncertain",
+				"malformed_response",
+				"lifecycle broker paginated an exact session.list result",
+			);
+		for (const page of pages) {
+			const { savedSession, savedSessionOmission } = page.page.result;
+			if (savedSession === undefined && savedSessionOmission === undefined) continue;
+			if (
+				!exactSavedSessionTarget ||
+				(savedSession !== undefined && savedSession.id !== requestedSessionId) ||
+				(savedSessionOmission !== undefined && savedSessionOmission.sessionId !== requestedSessionId)
+			)
+				return failure(
+					"session.list",
+					"uncertain",
+					"malformed_response",
+					"lifecycle broker returned a saved session that does not match the requested target",
+				);
+		}
 		if (request.target?.scope !== undefined) {
 			const scope = firstPage.page.scope;
 			const observedAt = firstPage.page.observedAt;
@@ -1323,6 +1505,7 @@ export class SessionLifecycleService {
 				sessions: pages.flatMap(page => page.page.result.sessions),
 				warnings: result.warnings,
 				...(result.savedSession === undefined ? {} : { savedSession: result.savedSession }),
+				...(result.savedSessionOmission === undefined ? {} : { savedSessionOmission: result.savedSessionOmission }),
 			},
 		};
 	}

package/src/sdk/lifecycle-session.ts

@@ -59,13 +59,37 @@ export type CreateLifecycleAgentSessionOptions = Omit<CreateAgentSessionOptions,
 	lifecycleRequestId?: string;
 };
 
+export interface SdkLifecycleStartupOwner {
+	readonly capability: SdkStartupCapability;
+	readonly rollback: SdkStartupRollbackTracker;
+}
+
+async function disposePartialSession(session: AgentSession): Promise<void> {
+	try {
+		await session.dispose();
+	} catch (error) {
+		if (!isSessionDisposalIncompleteError(error)) throw error;
+		await session.awaitDisposeCompletion();
+	}
+}
+
 /** Internal lifecycle-only session construction with an owner-bound SDK startup result. */
 export async function createLifecycleAgentSession(
 	options: CreateLifecycleAgentSessionOptions = {},
+	owner?: SdkLifecycleStartupOwner,
 ): Promise<CreateLifecycleAgentSessionResult> {
-	const rollback = new SdkStartupRollbackTracker();
-	const capability = new SdkStartupCapability(rollback, options.readiness ?? "immediate", options.lifecycleRequestId);
+	const rollback = owner?.rollback ?? new SdkStartupRollbackTracker();
+	const capability =
+		owner?.capability ??
+		new SdkStartupCapability(rollback, options.readiness ?? "immediate", options.lifecycleRequestId);
 	try {
+		if (capability.cancelled) {
+			const failure =
+				capability.result?.status === "failed"
+					? capability.result.failure
+					: capability.normalizeFailure("startup", "pending");
+			return { capability, rollback, failure };
+		}
 		const {
 			modelId,
 			mcpStartupTimeoutMs,
@@ -91,6 +115,14 @@ export async function createLifecycleAgentSession(
 			[lifecycleMcpStartupTimeoutOption]?: number;
 		};
 		const result = await createAgentSession(internalOptions);
+		if (capability.cancelled) {
+			await disposePartialSession(result.session);
+			const failure =
+				capability.result?.status === "failed"
+					? capability.result.failure
+					: capability.normalizeFailure("startup", "pending");
+			return { capability, rollback, failure };
+		}
 		// Explicit model pin (#4707) is a guarantee, not a preference. The
 		// coordinator validated the selector against its own registry; this child
 		// owns the registry that actually serves requests, and the two can drift
@@ -106,12 +138,7 @@ export async function createLifecycleAgentSession(
 			const expected = parseModelString(modelId);
 			const expectedSelector = expected ? `${expected.provider}/${expected.id}` : modelId;
 			if (!activeSelector || activeSelector.toLowerCase() !== expectedSelector.toLowerCase()) {
-				try {
-					await result.session.dispose();
-				} catch (error) {
-					if (!isSessionDisposalIncompleteError(error)) throw error;
-					await result.session.awaitDisposeCompletion();
-				}
+				await disposePartialSession(result.session);
 				throw new Error(
 					`Model "${modelId}" not found. Use --list-models to see available models.${
 						activeSelector ? ` Session resolved ${activeSelector} instead.` : ""

package/src/sdk/protocol/operation-inventory.generated.json

@@ -2910,6 +2910,28 @@
 			"testIds": "not_applicable"
 		}
 	},
+	{
+		"sourceId": "agent_session:setCoordinatorRuntimeStateFileForTests",
+		"sourceFile": "packages/coding-agent/src/session/agent-session.ts",
+		"sourceKind": "agent_session",
+		"decision": "exclude",
+		"rationale": "test-only coordinator runtime state file setup seam, not a user-facing SDK control seam",
+		"exclusionMetadata": {
+			"adapterMappings": "not_applicable",
+			"testIds": "not_applicable"
+		}
+	},
+	{
+		"sourceId": "agent_session:getCoordinatorRuntimeStateFileForTests",
+		"sourceFile": "packages/coding-agent/src/session/agent-session.ts",
+		"sourceKind": "agent_session",
+		"decision": "exclude",
+		"rationale": "read-only test-only coordinator runtime state file accessor, not a user-facing SDK control seam",
+		"exclusionMetadata": {
+			"adapterMappings": "not_applicable",
+			"testIds": "not_applicable"
+		}
+	},
 	{
 		"sourceId": "agent_session:trackPostPromptTaskForTests",
 		"sourceFile": "packages/coding-agent/src/session/agent-session.ts",
@@ -2987,6 +3009,17 @@
 			"testIds": "not_applicable"
 		}
 	},
+	{
+		"sourceId": "agent_session:trackCoordinatorRuntimeStatePersistenceFailuresForTests",
+		"sourceFile": "packages/coding-agent/src/session/agent-session.ts",
+		"sourceKind": "agent_session",
+		"decision": "exclude",
+		"rationale": "test-only coordinator persistence failure observation seam, not a user-facing SDK control seam",
+		"exclusionMetadata": {
+			"adapterMappings": "not_applicable",
+			"testIds": "not_applicable"
+		}
+	},
 	{
 		"sourceId": "agent_session:awaitCoordinatorRuntimeStatePersistenceForTests",
 		"sourceFile": "packages/coding-agent/src/session/agent-session.ts",

package/src/sdk/protocol/operation-registry.ts

@@ -263,11 +263,15 @@ function controlDisposition(id: string): Record<Adapter, AdapterDisposition> {
 
 function controlErrors(id: string): string[] {
 	const errors: Record<string, string[]> = {
-		C01: ["client_ref_conflict", "reconciliation_capacity", "reconciliation_persist_failed"],
+		// C01/C05 submit a prompt and therefore run the prompt preflight, which
+		// refuses a session with no selected model before admission. The code is
+		// appended: ACP machine-only mapping reads errorCodes[0].
+		C01: ["client_ref_conflict", "reconciliation_capacity", "reconciliation_persist_failed", "model_not_selected"],
 		C02: ["client_ref_conflict", "reconciliation_capacity", "reconciliation_persist_failed"],
 		C09: ["client_ref_conflict", "reconciliation_capacity", "reconciliation_persist_failed"],
 		C06: ["action_claimed"],
 		C07: ["action_claimed", "terminal_uncertain"],
+		C05: ["invalid_request", "busy", "model_not_selected"],
 		C08: ["action_claimed", "terminal_uncertain"],
 		C13: ["invalid_request", "busy", "default_model_selection_recovery"],
 		C36: ["revision_conflict", "secret_input_forbidden"],

package/src/sdk/session-directory.ts

@@ -51,7 +51,7 @@ export type ListManagedSessionCandidatesResult =
 			scope: ManagedSessionScope;
 			owned: readonly LogicalSessionCandidate[];
 			foreignCount: number;
-			invalid: readonly { code: string }[];
+			invalid: readonly { code: string; sessionId?: string }[];
 	  }
 	| { kind: "error"; code: "scan_failed" | "unsafe_root" | "invalid_candidate"; message: string };
 

package/src/sdk/session-list.ts

@@ -1,5 +1,52 @@
 export type SessionListPageRecord = Record<string, unknown>;
 
+export type SessionListSavedSessionOmissionReason =
+	| "scope_unavailable"
+	| "candidate_scan_failed"
+	| "candidate_not_found"
+	| "candidate_ambiguous"
+	| "candidate_invalid"
+	| "identity_incomplete";
+
+export const SESSION_LIST_SAVED_SESSION_OMISSION_DETAIL_CODES = [
+	"cwd_missing",
+	"cwd_not_directory",
+	"identity_unavailable",
+	"network_unsupported",
+	"sessions_root_unavailable",
+	"binding_conflict",
+	"binding_invalid",
+	"migration_busy",
+	"atomic_unavailable",
+	"invalid_request",
+	"durability_failed",
+	"durability_not_provable",
+	"capacity_exceeded",
+	"scan_failed",
+	"unsafe_root",
+	"invalid_candidate",
+	"invalid_header",
+	"unreadable_candidate",
+	"source_changed",
+	"cwd_not_found",
+	"cwd_not_utf8",
+	"cwd_network_unsupported",
+	"cwd_identity_unavailable",
+	"cwd_io_error",
+] as const;
+
+export type SessionListSavedSessionOmissionDetailCode =
+	(typeof SESSION_LIST_SAVED_SESSION_OMISSION_DETAIL_CODES)[number];
+
+/** Path-free diagnostic for a requested managed transcript that could not be selected safely. */
+export interface SessionListSavedSessionOmission {
+	readonly sessionId: string;
+	readonly reason: SessionListSavedSessionOmissionReason;
+	readonly detailCode?: SessionListSavedSessionOmissionDetailCode;
+	readonly candidateCount?: number;
+	readonly missingIdentityFields?: readonly ("nlink" | "ctimeNs")[];
+}
+
 export type SessionListTraversalErrorKind = "malformed_page" | "repeated_cursor" | "page_budget_exceeded";
 
 export class SessionListTraversalError extends Error {