@gajae-code/coding-agent 0.13.3 → 0.14.0

package/dist/types/session/agent-session.d.ts

@@ -66,6 +66,7 @@ export interface ForkContextSeedOptions {
     preserveLatestUser?: boolean;
     signal?: AbortSignal;
 }
+import type { AuthCredentialSelector } from "@gajae-code/ai/core";
 import { type AsyncJob, type AsyncJobDeliveryState, AsyncJobManager } from "../async";
 import type { Rule } from "../capability/rule";
 import { type ModelRegistry } from "../config/model-registry";
@@ -115,6 +116,18 @@ import type { BranchSummaryEntry, CompactionEntry, NewSessionOptions, PreparedNe
 import { SessionManager } from "./session-manager";
 import { ToolChoiceQueue } from "./tool-choice-queue";
 import { YieldQueue } from "./yield-queue";
+/**
+ * Classify an async-result delivery against terminal-abort ownership:
+ * - "ordinary": no owned-completion envelope — deliver as before.
+ * - "fresh": an exact registered owned-completion the owning scope's gate
+ *   authorizes as a fresh-turn resume (scope:"turn", policy enabled).
+ * - "drop": a recognized owned-completion the gate denies — scope:"owned"
+ *   (policy disabled, stopped work must never call followUp/prompt), a
+ *   forged/unregistered tuple, or an envelope whose terminal scope no longer
+ *   exists. Dropped entries never reach the agent (AC 36 zero final calls
+ *   from stopped work), even if a delivery races the settlement purge.
+ */
+export declare function ownedCompletionResumeAction(message: AgentMessage): "ordinary" | "fresh" | "drop";
 /** Session-specific events that extend the core AgentEvent */
 export type AutoCompactionContinuationSkipReason = "auto_continue_disabled_non_resumable_tail";
 export type AgentSessionEvent = AgentEvent | {
@@ -199,6 +212,9 @@ export interface AgentSessionConfig {
     agent: Agent;
     sessionManager: SessionManager;
     settings: Settings;
+    /** The session's REQUESTED effective agent directory, independent of the
+     * global Settings singleton (which may be reused across sessions). */
+    agentDir?: string;
     /** Lazy memory backend service; omitted callers receive a session-local default. */
     memoryBackend?: LazyService<MemoryBackend>;
     /** Lazy workspace-tree service; omitted callers retain the legacy direct-scan path. */
@@ -241,6 +257,12 @@ export interface AgentSessionConfig {
     workflowGatePublication?: "endpoint" | "local";
     /** Tool registry for LSP and settings */
     toolRegistry?: Map<string, AgentTool>;
+    /**
+     * Tool objects this session's builder constructed from built-in descriptors, captured
+     * before any extension, MCP, or dynamically registered tool could claim their registry
+     * names. Absent means no provenance was proven and every tool reports as `custom`.
+     */
+    builtinToolIdentities?: ReadonlySet<object>;
     /** Tool-session factory context used to lazily attach workflow-gate-only tools. */
     workflowGateToolSession?: ToolSession;
     /** Current session pre-LLM message transform pipeline */
@@ -314,6 +336,8 @@ export interface AgentSessionConfig {
      * **MUST NOT** dispose it on their own teardown.
      */
     ownedAsyncJobManager?: AsyncJobManager;
+    /** False when a child borrows its parent's manager and must not dispose it. */
+    disposeAsyncJobManager?: boolean;
     /** Cheap TUI retained-memory counters; absent for headless sessions. */
     retainedMemorySampler?: () => RetainedMemorySample;
     /**
@@ -342,8 +366,12 @@ export interface AgentSessionConfig {
     providerSessionId?: string;
     /** Optional auth-selection identity, distinct from logical/canonical and provider-cache identity. */
     credentialSessionId?: string;
+    /** Opaque credential-store authority fingerprint for durable numeric session pins. */
+    credentialStoreIdentity?: string;
     /** Optional provider-facing cache identity, distinct from logical session identity. */
     providerCacheSessionId?: string;
+    /** Explicit provider affinity whose persisted transcript path scopes async ownership. */
+    asyncJobProviderSessionId?: string;
 }
 export interface AgentSessionMemoryGuardRestoreInput extends Omit<AgentSessionConfig, "sessionManager" | "recoveryHydrationContext"> {
     staged: Extract<MemoryGuardRestoreResult, {
@@ -400,6 +428,8 @@ export interface PromptOptions {
         lineCount?: number;
         cleanedArgs?: string;
     }) => void;
+    /** Optional invocation-scoped cancellation fence used before an accepted skill starts execution. */
+    preflightSignal?: AbortSignal;
 }
 /** Result from a handoff operation. */
 export interface HandoffResult {
@@ -572,6 +602,12 @@ export declare class AgentSession {
     readonly agent: Agent;
     sessionManager: SessionManager;
     readonly settings: Settings;
+    /**
+     * The session's effective agent directory: its REQUESTED directory when
+     * provided, else the global Settings singleton's (which may be reused
+     * across sessions and therefore not the requesting session's own).
+     */
+    getSessionAgentDir(): string;
     readonly memoryBackend: LazyService<MemoryBackend>;
     readonly notificationSessionController: NotificationSessionController | undefined;
     readonly taskDepth: number;
@@ -723,7 +759,32 @@ export declare class AgentSession {
     /** Whether agent is currently streaming a response */
     get isStreaming(): boolean;
     /** Wait until streaming and session settlement work are fully settled. */
-    waitForIdle(): Promise<void>;
+    /**
+     * Wait until streaming and session settlement work are fully settled.
+     *
+     * The internal-only `ignoreSelectionFenceGeneration` is used exclusively by
+     * `setDefaultModelSelection`'s mid-selection drain: the selection must not
+     * wait on work parked behind its own (or a later) fence — its agent run,
+     * recovery, and deferrals — because that work is waiting on the selection
+     * itself (#4519). External callers observe everything.
+     */
+    waitForIdle(ignoreSelectionFenceGeneration?: number): Promise<void>;
+    /**
+     * Deterministically await every in-flight agent-event handler (including the
+     * synchronous canonical persistence each one performs) plus the durable
+     * transcript flush, without waiting for a prompt/turn lifecycle.
+     *
+     * This is the explicit signal replacement for real-time settle sleeps after
+     * externally emitted events (`agent.emitExternalEvent`): the dispatcher
+     * increments `#agentEventHandlersInFlight` synchronously before this call can
+     * observe it, and each handler decrements it in its `finally`, so the
+     * settlement promise below resolves exactly when the last handler — and
+     * therefore its `sessionManager.appendMessage`/`_persist` work — has finished.
+     * `flush()` then queues deterministically behind the SessionManager persist
+     * queue, so every seeded entry is canonical AND on disk before the caller
+     * proceeds.
+     */
+    awaitSessionSettlement(): Promise<void>;
     drainAsyncJobDeliveriesForAcp(options?: {
         timeoutMs?: number;
     }): Promise<boolean>;
@@ -861,6 +922,10 @@ export declare class AgentSession {
     get sessionId(): string;
     /** Credential selection identity; defaults to the provider-facing session identity. */
     get credentialSessionId(): string;
+    /** Pin one OAuth credential for this session scope and persist the minimal intent. */
+    setCredentialPin(provider: string, selector: AuthCredentialSelector): Promise<void>;
+    /** Mask persistent/global selection for this session and restore AUTO ranking. */
+    setCredentialAuto(provider: string): Promise<void>;
     /** Current session display name, if set */
     get sessionName(): string | undefined;
     /** Scoped models for cycling (from --models flag) */
@@ -870,7 +935,7 @@ export declare class AgentSession {
     /** Live SDK configuration values exposed through the session query surface. */
     getSdkConfigItems(): Record<string, string>;
     setPlanModeState(state: PlanModeState | undefined): void;
-    invokeSkill(name: string, args?: string, options?: Pick<PromptOptions, "onPreflightAccepted" | "onPreflightAcceptCommit" | "onSkillPrepared">): Promise<{
+    invokeSkill(name: string, args?: string, options?: Pick<PromptOptions, "onPreflightAccepted" | "onPreflightAcceptCommit" | "onSkillPrepared" | "preflightSignal">): Promise<{
         name: string;
         path: string;
         args?: string;
@@ -925,7 +990,7 @@ export declare class AgentSession {
      * @throws Error if no model selected or no API key available (when not streaming)
      */
     prompt(text: string, options?: PromptOptions): Promise<void>;
-    promptCustomMessage<T = unknown>(message: Pick<CustomMessage<T>, "customType" | "content" | "display" | "details" | "attribution">, options?: Pick<PromptOptions, "streamingBehavior" | "toolChoice" | "followUpQueuePolicy" | "onPreflightAccepted" | "onPreflightAcceptCommit">): Promise<void>;
+    promptCustomMessage<T = unknown>(message: Pick<CustomMessage<T>, "customType" | "content" | "display" | "details" | "attribution">, options?: Pick<PromptOptions, "streamingBehavior" | "toolChoice" | "followUpQueuePolicy" | "onPreflightAccepted" | "onPreflightAcceptCommit" | "preflightSignal">): Promise<void>;
     /**
      * Queue a steering message to interrupt the agent mid-run.
      */
@@ -952,6 +1017,13 @@ export declare class AgentSession {
         triggerTurn?: boolean;
         deliverAs?: "steer" | "followUp" | "nextTurn";
         followUpQueuePolicy?: "respect-mode" | "sequential";
+        /** INTERNAL trusted option: origin of a hidden next-turn message —
+         *  "turn" (produced by the current turn's continuation machinery,
+         *  purged by a terminal abort) or "external" (background producers,
+         *  preserved). Extension sendMessage callers are classified
+         *  "external" at the trusted bridge and never supply this bit
+         *  (review thread P2). */
+        origin?: "turn" | "external";
     }): Promise<void>;
     /** Remove undelivered queued custom messages matching `predicate` from executable queues and tagged display mirrors. */
     purgeQueuedCustomMessages(predicate: (message: CustomMessage) => boolean): PurgeQueuedCustomMessagesResult;
@@ -964,8 +1036,14 @@ export declare class AgentSession {
      */
     sendUserMessage(content: string | (TextContent | ImageContent)[], options?: {
         deliverAs?: "steer" | "followUp";
+        /** Preserve a busy SDK dispatch as queued work across an admission fence. */
+        queuedAtDispatch?: boolean;
         onPreflightAccepted?: () => void;
         onPreflightAcceptCommit?: () => void | Promise<void>;
+        /** Fired when a queued submission (steering or follow-up) is promoted to its own run (SDK ownership correlation). */
+        onQueuedPromoted?: () => void;
+        preflightSignal?: AbortSignal;
+        sdkRunToken?: string;
     }): Promise<void>;
     /**
      * Clear queued messages and return them.
@@ -1029,11 +1107,63 @@ export declare class AgentSession {
         silent?: boolean;
     }): Promise<void>;
     /**
-     * Abort a specific active prompt and prove whether its tracked resources settled.
-     */
+     * Private terminal-abort seam: read the CURRENT turn's attempt epoch WITHOUT
+     * interrupting it. Used to write the durable initial terminal marker BEFORE
+     * any fence/stop effect (plan ordered step 4). Only the epoch is exposed —
+     * never the opaque lineage handle — so no private origin metadata leaves the
+     * session. Fails closed (undefined) when no active turn lineage exists.
+     */
+    /**
+     * Private terminal-abort seam: cancel a PENDING (not-yet-started) prompt
+     * preflight. Aborting the preflight controller fires the captured admission
+     * signal so #throwIfPromptPreflightCancelled throws and the pending prompt
+     * never starts even if its SDK waiter was already settled; the controller is
+     * reset for the next admission. No run handle exists for a preflight prompt.
+     */
+    cancelPendingPreflightForTerminalAbort(): void;
+    /**
+     * Capture the steering admission snapshot at abort ADMISSION: the host
+     * invokes this before its durable marker transaction, so client steering
+     * admitted while the abort is in flight classifies as post-snapshot and is
+     * preserved instead of being purged at the later abortPromptAndWait
+     * (review thread P1). Snapshots are stored PER-ADMISSION in a per-turn
+     * FIFO: the settlement of each admission consumes its own captured
+     * sequence, so a later overlapping abort of the same turn can never
+     * overwrite an earlier admission's snapshot and purge an already-accepted
+     * steer (review thread P1).
+     */
+    captureTerminalAbortSteeringSnapshot(): number | undefined;
+    /**
+     * Discard a captured snapshot whose admission never settles (a durable
+     * same-key replay, no-effect, conflict, or marker failure): the entry is
+     * keyed to the CURRENT turn, which is where its admission captured it.
+     * Removing by token keeps overlapping admissions' entries independent.
+     */
+    /**
+     * Rebind a captured snapshot to the CURRENT turn: the owner-mismatch
+     * fall-through may terminalize the aborting requester's own turn that won
+     * the race, while the token was captured under the other connection's
+     * turn. The entry moves to the current turn's FIFO (retaining the original
+     * admission sequence) so the settlement's purge classifies steering
+     * admitted since admission as post-snapshot (review thread P1).
+     */
+    rebindTerminalAbortSteeringSnapshot(token: number): void;
+    discardTerminalAbortSteeringSnapshot(token: number): void;
+    getTerminalTurnEpoch(): number | undefined;
     abortPromptAndWait(handle: string, options: {
         graceMs: number;
-    }): Promise<RunSettlementProof>;
+        terminal?: {
+            scope: "turn" | "owned";
+            expectedEpoch?: number;
+            steeringSnapshotToken?: number;
+        };
+    }): Promise<RunSettlementProof & {
+        terminalScope?: {
+            scopeId: string;
+            abortedAttemptEpoch: number;
+            lineageIdHash: string;
+        };
+    }>;
     /** Atomically interrupt the active run and make text the next prompt. */
     cancelAndSubmit(text: string, options?: {
         queuedEntryId?: string;
@@ -1075,6 +1205,15 @@ export declare class AgentSession {
     }): Promise<void>;
     setActiveModelProfile(name: string | undefined): void;
     getActiveModelProfile(): string | undefined;
+    /**
+     * Re-apply vendor-separated delegation after a profile activation changed the
+     * role layer. `eagerTasks` is resolved at prompt build time, but under
+     * `tools.discoveryMode: all` the `task` tool is hidden until something
+     * activates it, and the delegation directive stays behind its
+     * `has tools "task"` guard. Activating a vendor-separated profile mid-session
+     * must therefore reach the live tool set, not just the next session.
+     */
+    syncEagerDelegation(): Promise<void>;
     /** Record runtime override keys installed by a profile activation. */
     noteProfileInstalledOverrides(modelRoles: readonly string[], agentModelOverrides: readonly string[], preProfileModel: Model | undefined): void;
     /** Drop the recorded profile-installed override keys after materialization. */

package/dist/types/session/agent-storage.d.ts

@@ -23,6 +23,16 @@ export declare class AgentStorage {
      * @deprecated Use config.yml instead. This is only for migration.
      */
     getSettings(): Settings | null;
+    /**
+     * @deprecated Settings are now stored in config.yml, not agent.db.
+     * Clears the legacy settings rows after they have been drained into
+     * config.yml so a later load never re-imports them (the database has no
+     * other one-time guard). Retries transient SQLITE_BUSY contention with
+     * exponential backoff and THROWS on persistent failure: the migration must
+     * not treat a failed drain as success while stale rows stay eligible for
+     * re-import on a later load.
+     */
+    clearSettings(): Promise<void>;
     /**
      * @deprecated Settings are now stored in config.yml, not agent.db.
      * This method is kept for backward compatibility but does nothing.

package/dist/types/session/coordinator-tool-label.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Proves whether the tool OBJECT that actually ran is one this session constructed from a
+ * built-in descriptor, before any extension, MCP, or dynamically registered tool could
+ * override that registry name.
+ */
+export type BuiltinToolProvenance = (tool: object) => boolean;
+/**
+ * Canonical public label for the tool object a call was ACTUALLY dispatched to.
+ *
+ * The input is the object the producer bound to the event, never a name resolved here. A
+ * wire name is model text and the tool list behind it is mutable: a `setTools`, MCP
+ * reload, or tool refresh between dispatch and this call would otherwise publish whatever
+ * holds the name by now instead of what ran.
+ *
+ * Two independent facts must hold before a canonical label is published:
+ *
+ *  1. the producer bound a dispatched tool object at all (an unknown name the loop
+ *     rejected, and a call aborted before dispatch, bind nothing), AND
+ *  2. that object carries built-in provenance and its canonical name is one of the closed
+ *     built-in descriptors.
+ *
+ * The object check is what makes the label trustworthy. A registry name is not
+ * provenance: an SDK extension, MCP, or custom tool may register itself as `bash` or
+ * `edit`, or claim a built-in `customWireName`, and would otherwise be published under
+ * the built-in's label. Without proven provenance — including for a direct AgentSession
+ * construction that supplies none — the answer is `custom`.
+ */
+export declare function canonicalCoordinatorToolLabel(dispatchedTool: object | undefined, isBuiltinToolObject: BuiltinToolProvenance): string;

package/dist/types/session/internal/managed-session-storage.d.ts

@@ -9,6 +9,7 @@ export declare const MANAGED_ARTIFACT_COPY_BATCH_SIZE = 256;
 export declare class ManagedPublishError extends Error {
     readonly classification: "destination_conflict" | "atomic_unavailable" | "invalid_request" | "durability_not_provable" | "identity_mismatch" | "io_error" | "durability_failed";
     readonly diagnostic: string;
+    readonly stagingCleanupSafe: boolean;
     constructor(classification: ManagedPublishError["classification"], outcome: NativePublishOutcome);
 }
 export declare class ManagedReplaceError extends Error {
@@ -18,6 +19,9 @@ export declare class ManagedReplaceError extends Error {
     readonly retainedSuccessorPath: string | undefined;
     readonly retainedPlaceholderPath: string | undefined;
     readonly retainedUnknownPath: string | undefined;
+    /** Path-free Windows NTSTATUS of the underlying pre-mutation failure, when
+     * the native layer preserved one (e.g. `0xC0000043` for a sharing violation). */
+    readonly windowsErrorCode: string | undefined;
     readonly replacementCause: unknown;
     constructor(result: NativeExactUnlinkResult, cleanupReceiptPath: string, replacementCause?: unknown);
 }
@@ -25,6 +29,10 @@ export declare class ManagedCommittedMutationError extends Error {
     readonly operation: "replace" | "append";
     constructor(operation: "replace" | "append", cause: unknown);
 }
+export declare class ManagedTreeMoveOutcomeError extends Error {
+    readonly stagingCleanupSafe: boolean;
+    constructor(message: string, stagingCleanupSafe: boolean);
+}
 /** Cleanup is safe only when the native move reports that it did not commit. */
 export declare function mayCleanManagedTreeStaging(error: unknown): boolean;
 /**
@@ -97,11 +105,11 @@ export interface ScrubbedProtocolRemnantReapResult {
  * names carry a terminal remnant prefix and whose timestamps are older than
  * the age gate are removed: a zero-length single-link entry is exactly what
  * the scrub proof leaves behind, and non-zero entries (displaced predecessors
- * or detached receipts retained as evidence) are never touched. Failures are
- * swallowed — a concurrent same-owner writer may legitimately own or already
- * have reconciled any candidate.
+ * or detached receipts retained as evidence) are never touched. A proven
+ * concurrent disappearance (ENOENT) is benign; all other I/O failures are
+ * returned and logged once without aborting scope preparation.
  */
-export declare function reapScrubbedProtocolRemnantsSync(directory: string, minAgeMs?: number): number;
+export declare function reapScrubbedProtocolRemnantsSync(directory: string, minAgeMs?: number): ScrubbedProtocolRemnantReapResult;
 /**
  * Async twin of {@link reapScrubbedProtocolRemnantsSync} with the same safety
  * filters (terminal remnant prefix, zero-length, single-link, non-symlink,
@@ -169,11 +177,22 @@ export declare class ManagedSessionDescendantStore {
     ensureDirectory(relativePath?: string): ManagedDirectoryRoot;
     publishNoReplace(relativePath: string, bytes: Uint8Array): Promise<void>;
     publishNoReplaceSync(relativePath: string, bytes: Uint8Array): void;
+    /**
+     * Atomically publishes an already-written managed staging file without
+     * materializing its contents. The staging file and destination must be
+     * descendants of this retained store.
+     */
+    publishStagedFileNoReplace(sourceRelativePath: string, destinationRelativePath: string, expected: {
+        bytes: number;
+        sha256: string;
+    }): void;
     replace(relativePath: string, bytes: Uint8Array): Promise<void>;
+    replaceExpectedIdentitySync(relativePath: string, bytes: Uint8Array, expected: ManagedFileIdentity): void;
     replaceExpected(relativePath: string, bytes: Uint8Array, expected: ManagedFileSnapshot): void;
     replaceSync(relativePath: string, bytes: Uint8Array): void;
     captureBoundedAppendExpectation(relativePath: string): ManagedBoundedAppendExpectation | undefined;
     appendExpectedSync(relativePath: string, bytes: Uint8Array, expected: ManagedBoundedAppendExpectation): ManagedAppendReceipt;
+    appendExpectedIdentitySync(relativePath: string, bytes: Uint8Array, expected: ManagedFileIdentity): ManagedAppendReceipt;
     appendSync(relativePath: string, bytes: Uint8Array): ManagedAppendReceipt;
     /** Capture descriptor identity without copying file bytes when retained authority is available. */
     descriptorExpected(relativePath: string): SessionStorageStat | null;

package/dist/types/session/messages.d.ts

@@ -60,7 +60,7 @@ export declare function readPendingDisplayTag(details: unknown): string | undefi
  *  the CustomMessageEntry to disk. Scoped intentionally narrow: only fields
  *  declared here are stripped. Adding a new entry is a deliberate, reviewed
  *  change — unrelated future payload fields are never silently dropped. */
-export declare const INTERNAL_DETAILS_FIELDS: readonly ["__pendingDisplayTag"];
+export declare const INTERNAL_DETAILS_FIELDS: readonly ["__pendingDisplayTag", "ownedCompletions"];
 /** Return a `details` copy with every key in `INTERNAL_DETAILS_FIELDS`
  *  removed. Returns the input unchanged when there is nothing to strip
  *  (null/non-object, or no listed fields present) so callers don't pay a

package/dist/types/session/secure-token-file.d.ts

@@ -0,0 +1,3 @@
+export declare function readSecureTokenFile(file: string): Promise<string | null>;
+export declare function writeSecureTokenFile(file: string, token: string): Promise<void>;
+export declare function createSecureTokenFileExclusive(file: string, token: string): Promise<boolean>;

package/dist/types/session/session-manager.d.ts

@@ -8,7 +8,7 @@ import type { ManagedLegacyLocalMigrationSource } from "../internal-urls/local-p
 import { ArtifactManager } from "./artifacts";
 import { type BlobPutResult, BlobStore } from "./blob-store";
 import { type ManagedMigrationPolicy } from "./internal/managed-session-scope";
-import { type ManagedBoundedAppendExpectation, type ManagedDirectoryRoot, ManagedSessionDescendantStore } from "./internal/managed-session-storage";
+import { type ManagedBoundedAppendExpectation, type ManagedDirectoryRoot, type ManagedFileIdentity, ManagedSessionDescendantStore } from "./internal/managed-session-storage";
 import { type BaseAnchor, BoundedLabelsPinsStore, type CommittedTail, type DescriptorSnapshot, type DictionaryPartitionCommit, FixedCacheAccount, type MetadataDeltaValue, type ParentBucketCommit, type ReducerState, type ReopenClassification, SessionMemoryAccountant } from "./internal/session-memory-sidecar";
 import { type MemoryGuardCreateCheckpointInput, type MemoryGuardParticipantIngressLease, type MemoryGuardRestoreInput, type MemoryGuardRestoreResult, type MemoryGuardSessionManagerCheckpointV1 } from "./memory-guard-checkpoint-participant";
 import { type BashExecutionMessage, type CustomMessage, type FileMentionMessage, type HookMessage, type PythonExecutionMessage } from "./messages";
@@ -652,6 +652,33 @@ export declare class SessionAppendPersistenceError extends Error {
     readonly persistenceError: Error;
     constructor(phase: SessionAppendPersistenceFailurePhase, entryId: string, persistenceError: Error);
 }
+/**
+ * Typed near-limit append outcome (#4566).
+ *
+ * A live managed append that would cross the per-file transcript cap is now
+ * preflighted: when the append alone cannot fit even after a full rewrite of
+ * the live entries, this deterministic error replaces the generic
+ * `SessionAppendPersistenceError: content_too_large` abort. It states whether
+ * the in-memory entry was kept (so the just-committed source mutation keeps
+ * its receipt on the next successful persist) and how to continue.
+ */
+export declare class SessionNearLimitAppendError extends Error {
+    readonly code: "near_limit_append";
+    /** Serialized size (bytes) of the entry that could not fit. */
+    readonly entryBytes: number;
+    /** Live-entry rewrite size (bytes) the recovery already attempted. */
+    readonly liveBytes: number;
+    /** Managed per-file cap in force when the append was rejected. */
+    readonly capBytes: number;
+    /** True when the entry remains in the resident list awaiting the next persist. */
+    readonly entryRetained: boolean;
+    constructor(details: {
+        entryBytes: number;
+        liveBytes: number;
+        capBytes: number;
+        entryRetained: boolean;
+    });
+}
 export declare class SessionManagedStorageError extends Error {
     readonly code = "managed_storage_unsupported";
     constructor();
@@ -962,6 +989,7 @@ interface SessionManagerStateSnapshot {
     sessionName: string | undefined;
     titleSource: "auto" | "user" | undefined;
     sessionFile: string | undefined;
+    managedPersistExpectedIdentity: ManagedFileIdentity | undefined;
     flushed: boolean;
     ensuredOnDisk: boolean;
     needsFullRewriteOnNextPersist: boolean;
@@ -980,6 +1008,15 @@ export declare const SessionManagerTestHooks: {
     afterForkTranscriptPublished?: () => void | Promise<void>;
     beforeEphemeralArtifactManagerInstall?: (dir: string) => void | Promise<void>;
     beforePersistPatchFence?: (attempt: number) => void;
+    beforeStrictMissingCheck?: (filePath: string, storage: SessionStorage) => void;
+    beforeManagedResumeAcceptance?: (filePath: string, storage: SessionStorage) => void;
+    beforeManagedResumeReturn?: (filePath: string, storage: SessionStorage) => void;
+    beforeManagedSourceStat?: (filePath: string, storage: SessionStorage) => void | Promise<void>;
+    beforeManagedMissingInit?: (filePath: string, storage: SessionStorage) => void | Promise<void>;
+    beforeManagedMissingPublish?: (filePath: string, storage: SessionStorage) => void | Promise<void>;
+    beforeManagedMissingReturn?: (filePath: string, storage: SessionStorage) => void | Promise<void>;
+    afterManagedMissingAssertion?: (filePath: string, storage: SessionStorage) => void | Promise<void>;
+    beforeManagedSwitchIdentity?: (filePath: string, storage: SessionStorage) => void | Promise<void>;
     /** Internal first-open GC strategy override; omitted means current. */
     firstOpenGcStrategy?: SessionMemoryGcStrategy;
     /** Internal first-open secondary-artifact mode override; omitted means auto. */
@@ -996,6 +1033,8 @@ export declare const SessionManagerTestHooks: {
     lastSidecarInitError?: string;
     /** Test-only generated-ID cache capacity override. */
     coldIdHashMaxEntriesOverride?: number;
+    /** Test-only session-context budget override (in-process; does not leak to subprocesses). */
+    sessionContextBudgetBytesOverride?: number;
 };
 /**
  * Freshness snapshot captured with every async whole-session persistence

package/dist/types/session/startup-auth-config.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Read the global startup-auth configuration before Settings is initialized.
+ *
+ * The config file is canonical nested YAML only. Legacy literal dotted auth keys
+ * are rejected with a manual rewrite diagnostic; no compatibility migration is
+ * performed. Environment values are trusted credential sources and take
+ * precedence over global config values.
+ */
+import type { AuthCredentialSelector, CredentialRankingMode } from "@gajae-code/ai/core";
+export interface AuthBrokerClientConfig {
+    url: string;
+    token: string;
+}
+export interface StartupAuthConfigSnapshot {
+    broker: AuthBrokerClientConfig | null;
+    /** Opaque credential-store authority used to bind numeric row-id pins. */
+    credentialStoreIdentity: string;
+    /** Persisted authority for global numeric pins; absent values invalidate ID pins. */
+    credentialPinStoreIdentity?: string;
+    credentialRankingMode: CredentialRankingMode;
+    credentialPins: Readonly<Record<string, string>>;
+}
+export type StartupAuthConfigErrorKind = "unreadable" | "invalid-yaml" | "non-mapping-root" | "invalid-auth" | "invalid-broker" | "invalid-gateway" | "invalid-ranking-mode" | "invalid-credential-pins";
+/** A malformed startup-auth config aborts resolution rather than downgrading to local authority. */
+export declare class StartupAuthConfigError extends Error {
+    readonly kind: StartupAuthConfigErrorKind;
+    readonly name = "StartupAuthConfigError";
+    readonly code: StartupAuthConfigErrorKind;
+    readonly causeClass: StartupAuthConfigErrorKind;
+    constructor(kind: StartupAuthConfigErrorKind, configPath: string);
+}
+/** JSON-schema pattern shared with the runtime persisted-selector grammar. */
+export declare const PERSISTED_CREDENTIAL_SELECTOR_PATTERN = "^(id:[1-9][0-9]*|email:[^@\\s]+@[^@\\s]+|account:\\S+)$";
+/** Path to the local bearer token file. Created on the broker host by `gjc auth-broker token`. */
+export declare function getAuthBrokerTokenFilePath(): string;
+/** Validate the persisted selector grammar used by `auth.credentialPins`. */
+export declare function parsePersistedCredentialSelector(value: string): AuthCredentialSelector | undefined;
+export declare function isValidPersistedCredentialSelector(value: string): boolean;
+/**
+ * Resolve one typed startup-auth snapshot from trusted env and global config.
+ * Project settings are intentionally not read here, so project-scoped pins
+ * cannot influence credential selection.
+ */
+export declare function resolveStartupAuthConfig(agentDir?: string): Promise<StartupAuthConfigSnapshot>;