@gajae-code/coding-agent 0.11.11 → 0.12.1

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

@@ -12,7 +12,7 @@
  *
  * Modes use this class and add their own I/O layer on top.
  */
-import { type Agent, type AgentContext, type AgentEvent, type AgentLoopConfig, type AgentMessage, type AgentState, type AgentTool, type MidRunMaintenanceOutcome, type StablePrefixSnapshot, ThinkingLevel } from "@gajae-code/agent-core";
+import { type Agent, type AgentContext, type AgentEvent, type AgentLoopConfig, type AgentMessage, type AgentState, type AgentTool, type MidRunMaintenanceOutcome, type RunSettlementProof, type StablePrefixSnapshot, ThinkingLevel } from "@gajae-code/agent-core";
 import { type CompactionResult, type EmergencyCompactionSample } from "@gajae-code/agent-core/compaction";
 import type { AssistantMessage, Effort, ImageContent, Message, MessageAttribution, Model, ProviderSessionState, ServiceTier, SimpleStreamOptions, TextContent, ToolCall, ToolChoice, Usage, UsageReport } from "@gajae-code/ai";
 import { type BtwTextExchange } from "./btw-contract";
@@ -75,14 +75,18 @@ import { type PromptTemplate } from "../config/prompt-templates";
 import type { Settings, SkillsSettings } from "../config/settings";
 import { RawSseDebugBuffer } from "../debug/raw-sse-buffer";
 import { type PythonResult } from "../eval/py/executor";
-import { type BashResult } from "../exec/bash-executor";
+import { type BashArtifactSaveResult, type BashResult } from "../exec/bash-executor";
 import type { TtsrManager } from "../export/ttsr";
 import type { LoadedCustomCommand } from "../extensibility/custom-commands";
 import type { CustomTool } from "../extensibility/custom-tools/types";
 import type { ExtensionRunner } from "../extensibility/extensions";
 import type { CompactOptions, ContextUsage, ExtensionTranscriptEntry } from "../extensibility/extensions/types";
+import type { GjcRuntimeSnapshotProvider } from "../extensibility/gjc-plugins/runtime-quarantine";
+import type { SessionSwitchEvent } from "../extensibility/shared-events";
 import { type Skill, type SkillWarning } from "../extensibility/skills";
 import { type FileSlashCommand } from "../extensibility/slash-commands";
+import { type MemoryGuardClaimsLease } from "../gjc-runtime/memory-guard-owner-claims";
+import { GjcTeamWorkerHeartbeatReporter } from "../gjc-runtime/team-worker-heartbeat";
 import { GoalRuntime } from "../goals/runtime";
 import type { Goal, GoalModeState } from "../goals/state";
 import type { HindsightSessionState } from "../hindsight/state";
@@ -101,6 +105,7 @@ import { type DefaultModelSelectionResult } from "./default-model-selection";
 export { DefaultModelSelectionRecoveryError } from "./default-model-selection";
 import type { ClientBridge, ClientBridgePermissionOption, ClientBridgePermissionOutcome, ClientBridgePermissionToolCall } from "./client-bridge";
 import { type ContributionPrepOptions, type ContributionPrepResult } from "./contribution-prep";
+import type { MemoryGuardRestoreResult } from "./memory-guard-checkpoint-participant";
 import { type CustomMessage } from "./messages";
 import type { BranchSummaryEntry, CompactionEntry, NewSessionOptions, PreparedNewSession, RecoveryHydrationContext, RecoveryHydrationPromotionFence, SessionContext, SessionManager, SessionManagerCloseOutcome } from "./session-manager";
 import { ToolChoiceQueue } from "./tool-choice-queue";
@@ -205,6 +210,11 @@ export interface AgentSessionConfig {
     workerIntegrationRequest?: (signal: AbortSignal) => Promise<void>;
     /** Bound terminal worker-integration settlement for embedded hosts and deterministic lifecycle tests. */
     workerIntegrationTimeoutMs?: number;
+    /**
+     * Override the runtime-owned `gjc team` worker heartbeat reporter. Defaults to a
+     * reporter derived from the team worker environment, or none outside a worker pane.
+     */
+    teamWorkerHeartbeatReporter?: GjcTeamWorkerHeartbeatReporter;
     /** Loaded skills (already discovered by SDK) */
     skills?: Skill[];
     /** Skill loading warnings (already captured by SDK) */
@@ -314,6 +324,24 @@ export interface AgentSessionConfig {
     /** Optional provider-facing cache identity, distinct from logical session identity. */
     providerCacheSessionId?: string;
 }
+export interface AgentSessionMemoryGuardRestoreInput extends Omit<AgentSessionConfig, "sessionManager" | "recoveryHydrationContext"> {
+    staged: Extract<MemoryGuardRestoreResult, {
+        kind: "staged";
+    }>;
+    claimsLease: MemoryGuardClaimsLease;
+    claimsStateDir: string;
+}
+export interface AgentMemoryGuardPromotionFence extends RecoveryHydrationPromotionFence {
+    readonly claimsLease: MemoryGuardClaimsLease;
+}
+export type AgentMemoryGuardRestoreResult = {
+    kind: "staged";
+    session: AgentSession;
+    promotionFence: AgentMemoryGuardPromotionFence;
+} | {
+    kind: "blocked";
+    reason: "transcript-mismatch" | "hydration-context-mismatch" | "claim-mismatch" | "agent-messages-mismatch";
+};
 type MidRunMaintenanceLifecycle = Parameters<NonNullable<AgentLoopConfig["maintainContext"]>>[1];
 /** Options for AgentSession.prompt() */
 export interface PromptOptions {
@@ -336,8 +364,21 @@ export interface PromptOptions {
     /**
      * Invoked after all prompt preflight checks pass and immediately before agent execution begins.
      * Cancellation before this callback rejects the prompt.
+     * Prefer `onPreflightAcceptCommit` for async durable acceptance (#3031/#3032).
      */
     onPreflightAccepted?: () => void;
+    /**
+     * Awaitable durable-accept fence. Called after preflight and before queue mutation
+     * or `#promptAgentWithIdleRetry`. SDK bus installs a closure that fsyncs acceptance.
+     */
+    onPreflightAcceptCommit?: () => void | Promise<void>;
+    /** Skill-only: prepared metadata before the durable fence (path/lineCount/cleanedArgs). */
+    onSkillPrepared?: (meta: {
+        name: string;
+        path: string;
+        lineCount?: number;
+        cleanedArgs?: string;
+    }) => void;
 }
 /** Result from a handoff operation. */
 export interface HandoffResult {
@@ -432,6 +473,11 @@ interface EphemeralTurnResult {
     replyText: string;
     assistantMessage: AssistantMessage;
 }
+export interface AgentBashArtifactStore {
+    saveArtifact(content: string, toolType: string): Promise<string | undefined>;
+    getArtifactPath(id: string): Promise<string | null>;
+}
+export declare function saveAgentBashOriginalArtifact(store: AgentBashArtifactStore, originalText: string): Promise<BashArtifactSaveResult>;
 type IrcRosterClaim = {
     token: symbol;
     signature: string;
@@ -752,13 +798,16 @@ export declare class AgentSession {
      * to avoid racing against the delivery turn.
      */
     get hasPostPromptWork(): boolean;
+    /** Stable resource ownership identifier for the active prompt run. */
+    get activePromptHandle(): string | undefined;
     /** All messages including custom types like BashExecutionMessage */
     get messages(): AgentMessage[];
     get transcriptPromptGeneration(): number;
+    static restoreFromMemoryGuardCheckpoint(input: AgentSessionMemoryGuardRestoreInput): Promise<AgentMemoryGuardRestoreResult>;
     /** The immutable recovery authority, present only before external ownership promotion. */
     get recoveryHydrationContext(): RecoveryHydrationContext | undefined;
     /** Enables normal session mutations after the owner has published its durable fence and writer lease. */
-    promoteRecoveryHydrationAfterOwnershipReadyFence(fence: RecoveryHydrationPromotionFence): Promise<void>;
+    promoteRecoveryHydrationAfterOwnershipReadyFence(fence: AgentMemoryGuardPromotionFence): Promise<void>;
     /** Main startup calls this exactly once, after a strict open returned `kind: "opened"`. */
     continuePersistedHistory(): Promise<void>;
     buildDisplaySessionContext(): SessionContext;
@@ -787,7 +836,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">): Promise<{
+    invokeSkill(name: string, args?: string, options?: Pick<PromptOptions, "onPreflightAccepted" | "onPreflightAcceptCommit" | "onSkillPrepared">): Promise<{
         name: string;
         path: string;
         args?: string;
@@ -842,7 +891,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">): Promise<void>;
+    promptCustomMessage<T = unknown>(message: Pick<CustomMessage<T>, "customType" | "content" | "display" | "details" | "attribution">, options?: Pick<PromptOptions, "streamingBehavior" | "toolChoice" | "followUpQueuePolicy" | "onPreflightAccepted" | "onPreflightAcceptCommit">): Promise<void>;
     /**
      * Queue a steering message to interrupt the agent mid-run.
      */
@@ -882,6 +931,7 @@ export declare class AgentSession {
     sendUserMessage(content: string | (TextContent | ImageContent)[], options?: {
         deliverAs?: "steer" | "followUp";
         onPreflightAccepted?: () => void;
+        onPreflightAcceptCommit?: () => void | Promise<void>;
     }): Promise<void>;
     /**
      * Clear queued messages and return them.
@@ -944,6 +994,12 @@ export declare class AgentSession {
         cause?: "user_interrupt" | "new_session" | "session_switch" | "compaction" | "handoff" | "tool_abort" | "internal";
         silent?: boolean;
     }): Promise<void>;
+    /**
+     * Abort a specific active prompt and prove whether its tracked resources settled.
+     */
+    abortPromptAndWait(handle: string, options: {
+        graceMs: number;
+    }): Promise<RunSettlementProof>;
     /** Atomically interrupt the active run and make text the next prompt. */
     cancelAndSubmit(text: string, options?: {
         queuedEntryId?: string;
@@ -1012,6 +1068,13 @@ export declare class AgentSession {
      * instead of promoting a transient runtime model to the resume default.
      */
     getSessionDefaultModelSelector(): string | undefined;
+    /**
+     * Resolve the model that `modelRoles.default` currently points to, independent
+     * of whatever model this session's log last recorded. Used by the TUI resume
+     * flow's `session.resumeModelBehavior: "ask"` prompt to offer the currently
+     * configured default as an alternative to the session's saved model.
+     */
+    resolveConfiguredDefaultModel(): Model | undefined;
     /**
      * Re-assert the session resume default ("provider/id") in the session log
      * WITHOUT touching the live runtime model. Appends a `model_change` with
@@ -1065,20 +1128,16 @@ export declare class AgentSession {
      * Get all available models with valid API keys.
      */
     getAvailableModels(): Model[];
-    /**
-     * Set thinking level.
-     * Saves the effective metadata-clamped level to the session, and to settings when requested.
-     */
     setThinkingLevel(level: ThinkingLevel | undefined, persist?: boolean): void;
     /**
-     * Set thinking level from a control surface. Global changes are durable or rolled back.
+     * Set thinking level from a control surface. Global changes commit before affecting live state.
      */
     setThinkingLevelForControl(level: ThinkingLevel, persist: boolean): Promise<void>;
     getThinkingScopeForControl(): "session" | "global config";
     getThinkingVisibility(): "visible" | "hidden";
     setThinkingVisibility(visibility: "visible" | "hidden", persist?: boolean): void;
     /**
-     * Set thinking visibility from a control surface. Global changes are durable or rolled back.
+     * Set thinking visibility from a control surface. Global changes commit before affecting live state.
      */
     setThinkingVisibilityForControl(visibility: "visible" | "hidden", persist: boolean): Promise<void>;
     /**
@@ -1125,6 +1184,15 @@ export declare class AgentSession {
      * Get available thinking levels for current model.
      */
     getAvailableThinkingLevels(): ReadonlyArray<Effort>;
+    /**
+     * Runtime evidence published for the current GJC bundle activation
+     * generation, set once by `createAgentSession` after every producer has run.
+     * Undefined until that publication happens, so consumers report runtime
+     * status as unavailable rather than falsely clear.
+     */
+    gjcRuntimeSnapshot?: GjcRuntimeSnapshotProvider;
+    /** Activation generation a published snapshot must match to be merged. */
+    gjcActivationGeneration?: number;
     /**
      * Set steering mode.
      * Saves to settings.
@@ -1316,7 +1384,9 @@ export declare class AgentSession {
      * Listeners are preserved and will continue receiving events.
      * @returns true if switch completed, false if cancelled by hook
      */
-    switchSession(sessionPath: string): Promise<boolean>;
+    switchSession(sessionPath: string, options?: {
+        transition?: SessionSwitchEvent["transition"];
+    }): Promise<boolean>;
     /**
      * Create a branch from a specific entry.
      * Emits before_branch/branch session events to hooks.

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

@@ -45,6 +45,14 @@ export declare class ArtifactManager {
     replaceNamedBytes(filename: string, bytes: Uint8Array): Promise<void>;
     publishManagedOutputGeneration(selectorFilename: string, outputFilenamePrefix: string, outputBytes: Uint8Array, metadataBytes: Uint8Array): Promise<void>;
     publishNamedNoReplace(filename: string, bytes: Uint8Array): Promise<void>;
+    /**
+     * Best-effort removal of a previously published named artifact. Used to roll
+     * back staged publications when a transactional operation (e.g. gated
+     * maintenance pruning) is rejected after publication succeeded. Returns false
+     * when the artifact could not be removed so callers can log the failure
+     * instead of silently treating the rollback as complete.
+     */
+    removeNamedBestEffort(filename: string): Promise<boolean>;
     /**
      * Atomically allocate next artifact ID.
      * IDs are sequential within the session.

package/dist/types/session/blob-store.d.ts

@@ -1,3 +1,9 @@
+declare const TAKE_BLOB_BUFFER_OWNERSHIP: unique symbol;
+/** Limits for a single best-effort resident-cache garbage-collection pass. */
+export interface ResidentCacheGcSweepOptions {
+    readonly maxDirectories?: number;
+    readonly maxDurationMs?: number;
+}
 export interface BlobPutResult {
     hash: string;
     path: string;
@@ -11,6 +17,28 @@ export declare class BlobCorruptError extends Error {
     readonly path: string;
     constructor(hash: string, path: string);
 }
+/**
+ * A resident-cache path or blob failed the owner-only verification contract.
+ * SessionManager catches this error to demote the entire resident store to
+ * memory before retrying the triggering write.
+ */
+export declare class ResidentCacheTrustError extends Error {
+    readonly reason: string;
+    readonly path: string;
+    constructor(reason: string, path: string, options?: ErrorOptions);
+}
+/**
+ * Best-effort cleanup of abandoned resident-cache instances. The root is
+ * re-verified before scanning, work is bounded, and all failures fail closed.
+ */
+export declare function sweepResidentCacheRoot(root: string, options?: ResidentCacheGcSweepOptions): Promise<void>;
+/**
+ * Create a private resident-cache instance directory beneath a trusted profile
+ * root. The cache-owned root and nonce instance are both verified owner-only
+ * directories; callers must use {@link EphemeralBlobStore.adoptVerifiedDir}
+ * rather than the destructive EphemeralBlobStore constructor.
+ */
+export declare function openVerifiedResidentCacheInstanceDir(root: string): string;
 /**
  * Content-addressed blob store for externalizing large binary data (images) from session JSONL files.
  *
@@ -31,7 +59,13 @@ export declare class BlobStore {
      * cannot afford the microtask hops of the async version (e.g. OOM-safe session writes).
      * Returns once the bytes are in the kernel page cache.
      */
-    putSync(data: Buffer): BlobPutResult;
+    putSync(data: Buffer, _ownership?: typeof TAKE_BLOB_BUFFER_OWNERSHIP): BlobPutResult;
+    /**
+     * Store a buffer that the caller will not mutate after this call returns.
+     * Resident-cache implementations may retain that private buffer without an
+     * additional defensive copy.
+     */
+    putOwnedSync(data: Buffer): BlobPutResult;
     /**
      * Durably install binary data as an immutable content-addressed blob.
      *
@@ -51,19 +85,37 @@ export declare class BlobStore {
     /** Check if a blob exists. */
     has(hash: string): Promise<boolean>;
 }
+interface EphemeralBlobStoreOptions {
+    readonly adoptVerifiedDir?: boolean;
+}
+/** Resident-cache directories still tracked by this process. Test seam. */
+export declare function trackedResidentCacheDirsForTest(): string[];
 export declare class EphemeralBlobStore extends BlobStore {
     #private;
-    constructor(dir: string);
-    putSync(data: Buffer): BlobPutResult;
+    constructor(dir: string, options?: EphemeralBlobStoreOptions);
+    /**
+     * Adopt a directory returned by {@link openVerifiedResidentCacheInstanceDir}
+     * without the ordinary constructor's destructive remove-and-recreate path.
+     */
+    static adoptVerifiedDir(dir: string): EphemeralBlobStore;
+    put(data: Buffer): Promise<BlobPutResult>;
+    putSync(data: Buffer, ownership?: typeof TAKE_BLOB_BUFFER_OWNERSHIP): BlobPutResult;
     putImmutableSync(data: Buffer): CheckedBlobPutResult;
+    get(hash: string): Promise<Buffer | null>;
     getSync(hash: string): Buffer | null;
+    /** Return a trusted in-memory copy without reopening an invalidated cache path. */
+    getBufferedSync(hash: string): Buffer | null;
     getCheckedSync(hash: string): Buffer | null;
     clear(): void;
     dispose(): void;
 }
+export interface MemoryBlobStoreOptions {
+    /** A canonical store owns every reference in its session's resident entries. */
+    readonly ownership?: "cache" | "canonical";
+}
 export declare class MemoryBlobStore extends BlobStore {
     #private;
-    constructor();
+    constructor(options?: MemoryBlobStoreOptions);
     put(data: Buffer): Promise<BlobPutResult>;
     putSync(data: Buffer): BlobPutResult;
     putImmutableSync(data: Buffer): CheckedBlobPutResult;
@@ -158,3 +210,4 @@ export declare function resolveResidentImageDataSync(blobStore: BlobStore, data:
     sessionId?: string;
     sessionFile?: string;
 }): string;
+export {};

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

@@ -51,19 +51,26 @@ export declare function retainManagedDirectoryAuthority(root: ManagedDirectoryRo
     ino: bigint;
 }): RecoveryFsRoot | undefined;
 export declare function assertManagedDirectoryRoot(root: ManagedDirectoryRoot): void;
+export declare function managedSecurityFailureClassification(error: unknown): string | undefined;
 /** Internal retained-root capability for one managed descendant subtree. */
 export declare class ManagedSessionDescendantStore {
     #private;
     constructor(root: ManagedDirectoryRoot, baseDir: string, retained?: {
         authority: RecoveryFsRoot;
         authorityBaseDir: string;
-    }, policy?: ManagedSessionSecurityPolicy);
+    }, policy?: ManagedSessionSecurityPolicy, profileAgentDir?: string);
     get dir(): string;
     get rootAuthority(): ManagedDirectoryRoot;
     get subtreeRootAuthority(): ManagedDirectoryRoot;
     get securityPolicy(): ManagedSessionSecurityPolicy;
+    get profileAgentDir(): string;
     deriveSubtree(relativePath: string): ManagedSessionDescendantStore;
     retainAuthority(): RecoveryFsRoot | undefined;
+    /**
+     * Release an authority this store opened itself. Retained authorities are owned by
+     * the security context that supplied them and are never closed here. Idempotent.
+     */
+    close(): void;
     assertBound(): void;
     verifyRootSecurity(): void;
     ensureDirectory(relativePath?: string): ManagedDirectoryRoot;

package/dist/types/session/memory-guard-checkpoint-participant.d.ts

@@ -0,0 +1,69 @@
+import type { RecoveryFsRoot } from "@gajae-code/natives";
+import type { RecoveryHydrationContext, ResumeSessionIdentity, SessionDestinationInput, SessionManager, SessionManagerCheckpointRevisionStrings, StrictSessionOpenFailure } from "./session-manager";
+export interface MemoryGuardTranscriptDescriptorV1 {
+    bytes: string;
+    relative_path: string;
+    sha256: string;
+}
+export interface MemoryGuardCheckpointBlobAuthorityV1 {
+    kind: "checkpoint_blob_tree_v1";
+    manifest_relative_path: string;
+    manifest_sha256: string;
+    root_relative_path: string;
+}
+export interface MemoryGuardCheckpointBlobManifestEntryV1 {
+    bytes: string;
+    relative_path: string;
+    sha256: string;
+}
+export interface MemoryGuardCheckpointBlobManifestV1 {
+    entries: MemoryGuardCheckpointBlobManifestEntryV1[];
+    schema_version: 1;
+}
+export interface MemoryGuardSessionManagerCheckpointV1 {
+    blob_authority: MemoryGuardCheckpointBlobAuthorityV1;
+    revisions: SessionManagerCheckpointRevisionStrings;
+    schema_version: 1;
+    session_id: string;
+    session_name: string | null;
+    transcript: MemoryGuardTranscriptDescriptorV1;
+}
+export interface MemoryGuardParticipantDescriptorV1 {
+    ordinal: number;
+    checkpoint: MemoryGuardCheckpointBlobAuthorityV1;
+    revisions: SessionManagerCheckpointRevisionStrings;
+    session_id: string;
+    session_name: string | null;
+    transcript: MemoryGuardTranscriptDescriptorV1;
+}
+export interface MemoryGuardParticipantIngressLease {
+    readonly token: symbol;
+    release(): void;
+}
+export interface MemoryGuardCreateCheckpointInput {
+    ingressLease: MemoryGuardParticipantIngressLease;
+    checkpointRoot: string;
+}
+export type MemoryGuardRestoreBlockedReason = StrictSessionOpenFailure["reason"] | "checkpoint-mismatch" | "participant-mismatch" | "transcript-mismatch" | "blob-manifest-mismatch" | "blob-missing" | "blob-hash-mismatch" | "blob-authority-mismatch" | "destination-unavailable";
+export interface MemoryGuardRestoreInput {
+    incidentAuthority: RecoveryFsRoot;
+    participant: MemoryGuardParticipantDescriptorV1;
+    checkpoint: MemoryGuardSessionManagerCheckpointV1;
+    destination: SessionDestinationInput;
+}
+export type MemoryGuardRestoreResult = {
+    kind: "staged";
+    manager: SessionManager;
+    hydrationContext: RecoveryHydrationContext;
+    transcriptIdentity: ResumeSessionIdentity;
+    cleanup: () => Promise<void>;
+} | {
+    kind: "blocked";
+    reason: MemoryGuardRestoreBlockedReason;
+};
+export declare function memoryGuardCanonicalJson(value: unknown): string;
+export declare function memoryGuardSha256Hex(value: Uint8Array | string): string;
+export declare function isMemoryGuardDecimalString(value: unknown): value is string;
+export declare function isMemoryGuardSha256Hex(value: unknown): value is string;
+export declare function isMemoryGuardRelativePath(value: unknown): value is string;
+export declare function hasOnlyKeys(value: Record<string, unknown>, allowed: readonly string[]): boolean;

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

@@ -8,6 +8,7 @@ import { ArtifactManager } from "./artifacts";
 import { type BlobPutResult, BlobStore } from "./blob-store";
 import { type ManagedMigrationPolicy } from "./internal/managed-session-scope";
 import { type ManagedDirectoryRoot, ManagedSessionDescendantStore } from "./internal/managed-session-storage";
+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";
 import { type SessionManagerReadAccess, sessionManagerReadCapability } from "./session-manager-internal";
 import type { ManagedSessionSecurityContext, SessionStorage, SessionStorageStat, VerifiedSessionDeleteResult, VerifiedSessionDeleteTarget } from "./session-storage";
@@ -71,11 +72,16 @@ export interface SessionManagerObservabilityStats {
     coldSpillReadCount: number;
     residentTextReadCount: number;
     residentImageReadCount: number;
+    residentCacheAdoptFallbackCount: number;
+    residentCacheTrustRejectCount: number;
+    residentCacheWin32FallbackCount: number;
+    residentCacheDegradedReason?: string;
     publicMaterializerCallCount: number;
     getEntryMaterializerCallCount: number;
     getBranchMaterializerCallCount: number;
     getEntriesMaterializerCallCount: number;
     materializedEntriesCachePopulateCount: number;
+    materializedCacheDemotedCount: number;
     pathOnlyContextBuildCount: number;
 }
 export interface SessionMessageEntry extends SessionEntryBase {
@@ -259,6 +265,21 @@ export type DefaultModelSelectionStage = {
     readonly tempPath: string | undefined;
     readonly persistsToExistingFile: boolean;
 };
+export interface SessionManagerRevisionSnapshot {
+    entry: number;
+    leaf: number;
+    headerExport: number;
+    label: number;
+    replayMetadata: number;
+}
+export interface SessionManagerCheckpointRevisionStrings {
+    entry: string;
+    leaf: string;
+    headerExport: string;
+    label: string;
+    replayMetadata: string;
+}
+export declare function toSessionManagerCheckpointRevisionStrings(snapshot: SessionManagerRevisionSnapshot): SessionManagerCheckpointRevisionStrings;
 export type DefaultModelSelectionPromotion = {
     readonly kind: "promoted";
 } | {
@@ -490,12 +511,17 @@ export type SessionDestination = {
     readonly directory: string;
 };
 export type SessionDestinationInput = string | SessionDestination | undefined;
-interface ForkArtifactPublication {
+type ForkArtifactPublication = {
+    readonly kind: "managed";
     readonly snapshot: native.NativeDirectoryTreeSnapshot;
     readonly store: ManagedSessionDescendantStore;
     readonly cleanupStore: ManagedSessionDescendantStore;
     readonly cleanupRelativePath: string;
-}
+} | {
+    readonly kind: "explicit";
+    readonly artifactsDir: string;
+    readonly snapshot: native.NativeDirectoryTreeSnapshot;
+};
 /** Exported for testing */
 export declare function loadEntriesFromFile(filePath: string, storage?: SessionStorage): Promise<FileEntry[]>;
 declare class RecentSessionInfo {
@@ -541,6 +567,10 @@ export declare function residentBlobSentinelForTests(kind: ResidentBlobKind, ref
 export declare function materializeResidentEntriesForPersistenceForTests<T>(entries: T[], textStore: BlobStore, imageStore?: BlobStore): T[];
 /** Get recent sessions for display in welcome screen */
 export declare function getRecentSessions(sessionDir: string, limit?: number, storage?: SessionStorage): Promise<RecentSessionInfo[]>;
+export declare function getRecentSessionDisplay(sessions: readonly SessionInfo[], limit?: number): Array<{
+    name: string;
+    timeAgo: string;
+}>;
 /**
  * Manages conversation sessions as append-only trees stored in JSONL files.
  *
@@ -576,6 +606,13 @@ interface SessionManagerStateSnapshot {
     fileEntries: FileEntry[];
     materializedFileEntries: FileEntry[];
 }
+/** Benchmark-derived cap for strong materialized session snapshots. */
+export declare const MATERIALIZED_CACHE_MAX_BYTES: number;
+/** Test-only cache retention and transition seams; these are intentionally not user settings. */
+export declare const SessionManagerTestHooks: {
+    materializedCacheMaxBytesOverride?: number;
+    beforeResidentTransitionIndexBuild?: () => void;
+};
 export declare class SessionManager {
     #private;
     private cwd;
@@ -589,18 +626,12 @@ export declare class SessionManager {
      * revision contract). Tests assert the invalidation mapping through this;
      * future export/label-view caches key off their respective domains.
      */
-    revisionSnapshot(): {
-        entry: number;
-        leaf: number;
-        headerExport: number;
-        label: number;
-        replayMetadata: number;
-    };
+    revisionSnapshot(): SessionManagerRevisionSnapshot;
     /** Puts a binary blob into the blob store and returns the blob reference */
     putBlob(data: Buffer): Promise<BlobPutResult>;
     captureState(): SessionManagerStateSnapshot;
     restoreState(snapshot: SessionManagerStateSnapshot): void;
-    /** Switch to a different session file (used for resume and branching) */
+    /** Switch to a different session file (used for resume and branching). */
     setSessionFile(sessionFile: string): Promise<void>;
     /** Start a new session. Closes any existing writer first. */
     newSession(options?: NewSessionOptions): Promise<string | undefined>;
@@ -638,9 +669,9 @@ export declare class SessionManager {
      * managed logical authorization. This is only for discarding an UNCOMMITTED
      * successor that a transaction (e.g. handoff) created via `newSession()` but
      * never durably authorized — such a session has no managed candidate listing
-     * yet, so `dropSession` would refuse it and leak its resident-cache/artifact
-     * root. Bounded to this manager's configured session root and refuses to touch
-     * the active session; tolerates missing files.
+     * yet, so `dropSession` would refuse it and leak its artifact root. Bounded to
+     * this manager's configured session root and refuses to touch the active session;
+     * tolerates missing files.
      */
     discardUncommittedSession(sessionPath: string): Promise<void>;
     /**
@@ -691,6 +722,8 @@ export declare class SessionManager {
     listForResumePickerReadOnly(): Promise<SessionInfo[]>;
     getSessionId(): string;
     getSessionFile(): string | undefined;
+    acquireMemoryGuardParticipantIngressLease(): MemoryGuardParticipantIngressLease;
+    createMemoryGuardCheckpoint(input: MemoryGuardCreateCheckpointInput): Promise<MemoryGuardSessionManagerCheckpointV1>;
     /**
      * Returns the session artifacts directory path (session file path without .jsonl).
      * Returns null when the session is not persisted to a file.
@@ -747,11 +780,6 @@ export declare class SessionManager {
     /** The source that set the session name: "user" (manual /rename or RPC) or "auto" (generated title). */
     get titleSource(): "auto" | "user" | undefined;
     getSessionName(): string | undefined;
-    /**
-     * Set the session display name.
-     * @param source - "user" for explicit renames (/rename command, RPC); "auto" for generated titles.
-     *   Auto-generated titles are silently ignored when the user has already set a name.
-     */
     setSessionName(name: string, source?: "auto" | "user"): Promise<boolean>;
     _persist(entry: SessionEntry): void;
     /** Append a configured fallback chain as child of current leaf, then advance leaf. Returns entry id. */
@@ -971,7 +999,7 @@ export declare class SessionManager {
      * legacy sibling directories.
      */
     static listForResumePickerReadOnly(cwd: string, sessionDir?: string, storage?: SessionStorage): Promise<SessionInfo[]>;
-    /** Tombstone and exact-delete a default-managed candidate. */
+    /** Delete an authorized managed or project-local picker candidate. */
     static deleteManagedCandidate(sessionPath: string): Promise<void>;
     /** Capture exact source content for a strict fork without granting write ownership. */
     static captureTranscriptStrict(filePath: string, storage?: SessionStorage): StrictSessionCaptureResult;
@@ -981,6 +1009,7 @@ export declare class SessionManager {
      * persistence; destination history always comes from the captured bytes.
      */
     static forkFromCaptured(snapshot: CapturedSessionTranscriptSnapshot, cwd: string, destinationInput?: SessionDestinationInput, _migrationPolicy?: SessionDirectoryMigrationPolicy): Promise<StrictSessionForkResult>;
+    static restoreMemoryGuardCheckpoint(input: MemoryGuardRestoreInput): Promise<MemoryGuardRestoreResult>;
     /** Inspect a selected session without acquiring write-capable ownership. */
     static inspectSessionTailReadOnly(filePath: string, storage?: SessionStorage): Promise<ResumeTailInspection>;
     /**

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

@@ -61,6 +61,8 @@ export interface SessionStorageWriterOpenOptions {
 export interface ManagedSessionSecurityContext {
     readonly kind: "managed";
     readonly agentDir: string;
+    /** Logical profile root for process-local caches; distinct from managed pathname authority. */
+    readonly profileAgentDir: string;
     readonly sessionsRoot: string;
     readonly sessionDir: string;
     readonly rootAuthority: ManagedDirectoryRoot;
@@ -69,6 +71,8 @@ export interface ManagedSessionSecurityContext {
 /** @internal Create the only accepted managed writer authority object. */
 export declare function createManagedSessionSecurityContext(input: {
     agentDir: string;
+    /** Optional for compatibility with existing authority-only callers. */
+    profileAgentDir?: string;
     sessionsRoot: string;
     sessionDir: string;
     rootAuthority: ManagedDirectoryRoot;