@gajae-code/coding-agent 0.12.0 → 0.12.1

package/dist/types/sdk/bus/telegram-daemon.d.ts

@@ -62,6 +62,7 @@ export interface TelegramDaemonFs {
         dev?: number;
         ino?: number;
         ctimeMs?: number;
+        isDirectory?: () => boolean;
     }>;
     readEndpointFile?(path: string): Promise<NotificationEndpointFile>;
     exactUnlink?(path: string, identity: NotificationEndpointFileIdentity): Promise<NotificationExactUnlinkResult>;
@@ -722,6 +723,8 @@ export interface TelegramDaemonOptions {
         enabled: boolean;
     };
     idleTimeoutMs?: number;
+    /** TTL for durable topic-adoption intents (default 10 minutes). Observed, not a fixed contract. */
+    adoptionIntentTtlMs?: number;
     scanIntervalMs?: number;
     pid?: number;
     /** Liveness probe for skipping dead-PID endpoint records in {@link TelegramNotificationDaemon.scanRoots}. */
@@ -758,6 +761,8 @@ export interface TelegramDaemonOptions {
     toolActivity?: {
         enabled: boolean;
     };
+    /** Controls which Telegram sends play an audible notification. Defaults to all. */
+    sound?: "all" | "important" | "none";
     /**
      * Per-session Telegram forum-topic naming. `nameTemplate` supports the
      * `{repo}`, `{branch}`, and `{title}` placeholders; unset preserves the
@@ -958,7 +963,7 @@ export declare class TelegramNotificationDaemon {
     private reserveSeenUpdateId;
     private releaseSeenUpdateId;
     scanRoots(): Promise<void>;
-    connectSession(sessionId: string, url: string, token: string): void;
+    connectSession(sessionId: string, url: string, token: string): SessionSocket;
     /**
      * Start ack-based liveness for a session whose server advertised the
      * `client_ping_pong` capability. Each interval drops the session when no pong
@@ -1030,6 +1035,16 @@ export declare class TelegramNotificationDaemon {
     private deleteTopic;
     private persistTopics;
     loadTopics(): Promise<void>;
+    /**
+     * Rehydrate durable adoption intents after restart, then reconcile: a
+     * non-expired sidecar whose target session already has a committed topic
+     * record is a stale leftover (commit succeeded but sidecar cleanup failed)
+     * and is removed safely without touching the user topic.
+     */
+    loadAdoptionIntents(): Promise<void>;
+    /** Periodic sweep of expired adoption-intent sidecars (files only; no Telegram API). */
+    private startAdoptionSweepTimer;
+    private stopAdoptionSweepTimer;
     /** Retry crash-interrupted topic deletes; only a definite Telegram result clears the durable fence. */
     private reconcilePendingTopicDeletes;
     /** Download one Telegram file with the Bot API's 20 MiB ceiling and one end-to-end deadline. */
@@ -1117,6 +1132,15 @@ export declare class TelegramNotificationDaemon {
     handleSessionMessage(session: SessionSocket, msg: any): Promise<void>;
     private answerCallbackQueryBestEffort;
     private sendStaleGuidance;
+    /**
+     * Consume a user-created forum topic (`forum_topic_created` service message)
+     * before edited/text routing. Authenticates the chat, user, privacy, and
+     * lifecycle state; offers home, recent folders, or explicit path entry. The
+     * selected path (or an exact `/session_create path <dir>`) creates a session
+     * that adopts this topic — never a duplicate topic. Non-routable durable
+     * intents prevent duplicate creation across concurrent first frames.
+     */
+    private handleForumTopicCreatedUpdate;
     /** Consume Telegram forum-topic rename service messages before text routing. */
     private handleForumTopicEdited;
     private processTelegramUpdate;

package/dist/types/sdk/bus/telegram-reference.d.ts

@@ -85,8 +85,17 @@ export declare function buildActionMarkdown(action: {
     recommendedIndex?: unknown;
     summary?: string;
 }): string;
+export type TelegramNotificationSound = "all" | "important" | "none";
+export type TelegramDeliveryLane = "ask" | "idle" | "live" | "finalized";
+/**
+ * Resolve Telegram's optional silent-delivery flag. `finalChunk` silences
+ * non-final actionable chunks under the `important` policy; `undefined`
+ * intentionally omits the field so Telegram uses its normal audible delivery
+ * behavior.
+ */
+export declare function telegramDisableNotification(sound: TelegramNotificationSound | undefined, lane: TelegramDeliveryLane, finalChunk?: boolean): true | undefined;
 /** Send Telegram HTML text chunks sequentially so long messages preserve order. */
-export declare function sendTelegramHtmlChunks(send: TelegramSend, chatId: string, text: string, inlineKeyboard?: InlineButton[][]): Promise<void>;
+export declare function sendTelegramHtmlChunks(send: TelegramSend, chatId: string, text: string, inlineKeyboard?: InlineButton[][], sound?: TelegramNotificationSound, lane?: TelegramDeliveryLane): Promise<void>;
 /** A protocol `reply` frame the client should send to the server. */
 export interface ReplyFrame {
     type: "reply";
@@ -128,6 +137,7 @@ export interface TelegramReferenceOptions {
     endpointFile: string;
     apiBase?: string;
     fetchImpl?: typeof fetch;
+    sound?: TelegramNotificationSound;
 }
 /**
  * Run the reference bridge until the WebSocket closes. Sends `action_needed` to

package/dist/types/sdk/bus/threaded-render.d.ts

@@ -14,13 +14,13 @@ export interface ThreadedSend {
     method: "sendMessage" | "sendPhoto" | "sendDocument";
     /** Rate-limit lane for prioritisation/fairness. */
     lane: RateLimitLane;
-    /** Message text (sendMessage) or photo caption (sendPhoto). */
+    /** Message text (sendMessage) or media caption (sendPhoto/sendDocument). */
     text?: string;
     /** Base64 image bytes for sendPhoto. */
     photoBase64?: string;
     /** Base64 file bytes for sendDocument. */
     documentBase64?: string;
-    /** Image MIME type for sendPhoto. */
+    /** Uploaded media MIME type. */
     mime?: string;
     /** Suggested document filename. */
     fileName?: string;
@@ -83,6 +83,7 @@ interface ThreadedFrame {
     status?: unknown;
     message?: unknown;
 }
+export declare function supportsTelegramPhotoUpload(mime: string | undefined): boolean;
 /** Format the one-time identity header as pinned bullets. */
 export declare function formatIdentityHeader(frame: {
     repo?: unknown;

package/dist/types/sdk/bus/topic-registry.d.ts

@@ -42,6 +42,8 @@ export interface TopicRecord {
     creationLeaseEpoch?: number;
     /** An uncertain delete fences future creation and inbound routing. */
     authorityState?: "active" | "delete_pending";
+    /** Provenance for topics created by the user and adopted by GJC. Missing means daemon-created. */
+    topicOrigin?: "user_created";
     /** Telegram chat and endpoint authority last proven to use this topic. */
     chatId?: string;
     /** Canonical endpoint tuple (URL + token) that currently holds the lease. */
@@ -129,6 +131,14 @@ export declare class TopicRegistry {
     authorityEpoch(sessionId: string): number;
     /** Whether this session has an active, unambiguous topic authority. */
     isActiveUnambiguous(sessionId: string): boolean;
+    /**
+     * Pure read-only availability check for user-topic adoption. Rejects invalid
+     * ids and any id already committed, delete-pending/fenced, staged, or
+     * ambiguous, without mutating maps, epochs, or persistence. Used inside the
+     * {@link getOrCreateTopic} create callback to fail-closed before adopting a
+     * user-created topic id.
+     */
+    isTopicIdAvailable(topicId: string): boolean;
     /**
      * Resolve endpoint authority for identity-less replay. An endpoint may bootstrap
      * only when no committed, staged, or pre-create claim can own it; malformed
@@ -153,7 +163,7 @@ export declare class TopicRegistry {
      * Return the existing active topic for `sessionId`, or create one via
      * `create` (called only on first use).
      */
-    getOrCreateTopic(sessionId: string, create: () => Promise<unknown>, now?: () => number, name?: string, binding?: TopicEndpointBinding, commit?: () => Promise<void>, transientClaimant?: object): Promise<TopicRecord>;
+    getOrCreateTopic(sessionId: string, create: () => Promise<unknown>, now?: () => number, name?: string, binding?: TopicEndpointBinding, commit?: () => Promise<void>, transientClaimant?: object, topicOrigin?: TopicRecord["topicOrigin"]): Promise<TopicRecord>;
     /** Mark the identity header as sent for a session. Idempotent. */
     markIdentitySent(sessionId: string): void;
     /** Whether the identity header still needs sending for this session. */

package/dist/types/sdk/host/query/revision-store.d.ts

@@ -1,3 +1,5 @@
+/** Test seam: spill directories currently tracked for postmortem cleanup. */
+export declare function trackedSpillDirectoriesForTest(): string[];
 export declare const MAX_REVISIONS_PER_RESOURCE = 8;
 export declare const MAX_PINNED_REVISIONS = 128;
 export declare const MAX_MEMORY_BYTES: number;

package/dist/types/sdk/host/reverse-leases.d.ts

@@ -33,7 +33,7 @@ export declare class ReverseLeaseRuntime {
     heartbeat(connectionId: string, leaseId: string): ProviderLease;
     release(connectionId: string, leaseId: string, handoffTo?: string): ProviderLease;
     disconnect(connectionId: string): void;
-    request(capability: string, method: string, payload: unknown): Promise<unknown>;
+    request(capability: string, method: string, payload: unknown, signal?: AbortSignal): Promise<unknown>;
     respond(connectionId: string, id: string, leaseId: string, result: unknown, error?: {
         code: string;
         message: string;

package/dist/types/sdk/prompt-status.d.ts

@@ -17,8 +17,10 @@
  *   prior outcome unknown — callers MUST NOT reuse a clientRef as a retry
  *   mechanism and MUST treat `unknown` as uncertainty, not proof of
  *   non-execution.
- * - The durability floor is the live session process: after restart or
- *   retained-record eviction, a lookup honestly reports `unknown`.
+ * - Prompt records survive process restart: an active prompt is finalized from its
+ *   durable pending outcome, or as `prompt_failed` when it has none. Only skill
+ *   records settle as `process_restart`, and a lookup reports `unknown` only after
+ *   retained-record TTL/capacity eviction.
  * - Q26 tracks prompts accepted through the SDK control surface (which always
  *   carries a requesting connection); submissions without a delivery owner are
  *   outside the reconciliation contract and hold no reservation.
@@ -34,8 +36,24 @@ export interface TurnPromptInput {
     images?: TurnPromptImageInput[];
     clientRef?: string;
 }
-/** Terminal outcome is preserved exactly; active records never age into terminal. */
+/**
+ * Terminal outcome is preserved exactly; active records never age into terminal. A
+ * prompt that is active at process restart is finalized from its durable pending
+ * outcome (or `prompt_failed` when it has none), so it never reports as unknown.
+ */
 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";
+export type SdkPromptTerminalOutcome = {
+    kind: "stopped";
+    reason: SdkPromptStopReason;
+    provenance: "agent" | "client_cancel";
+} | {
+    kind: "failed";
+    code: SdkPromptFailureCode;
+    message: string;
+    provenance: "agent_failed" | "deadline";
+};
 /** Exactly one selector per lookup. */
 export type TurnPromptStatusSelector = {
     clientRef: string;
@@ -63,6 +81,7 @@ export interface TurnPromptReconciliationTerminalOk extends TurnPromptReconcilia
     startedAt?: number;
     /** Epoch milliseconds of the terminal transition. */
     terminalAt: number;
+    outcome?: SdkPromptTerminalOutcome;
 }
 export interface TurnPromptReconciliationFailed extends TurnPromptReconciliationIdentity {
     status: "failed";
@@ -73,6 +92,7 @@ export interface TurnPromptReconciliationFailed extends TurnPromptReconciliation
         code: string;
         message: string;
     };
+    outcome?: SdkPromptTerminalOutcome;
 }
 export interface TurnPromptReconciliationUnknown {
     status: "unknown";

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

@@ -12,6 +12,7 @@ import type { CustomCommandsLoadResult } from "../extensibility/custom-commands"
 import type { CustomTool } from "../extensibility/custom-tools/types";
 import { type ExtensionFactory, type ExtensionUIContext, type LoadExtensionsResult, type ToolDefinition } from "../extensibility/extensions";
 import { type ConstrainedPluginHook } from "../extensibility/gjc-plugins/constrained-hooks";
+import { type GjcRuntimeSnapshotProvider } from "../extensibility/gjc-plugins/runtime-quarantine";
 import { type Skill, type SkillWarning } from "../extensibility/skills";
 import type { FileSlashCommand } from "../extensibility/slash-commands";
 import type { HindsightSessionState } from "../hindsight/state";
@@ -207,6 +208,11 @@ export interface CreateAgentSessionResult {
     lspServers?: LspStartupServerInfo[];
     /** Shared event bus for tool/extension communication */
     eventBus: EventBus;
+    /**
+     * Read-only view of GJC bundle runtime evidence for the activation generation
+     * this session published. Undefined when no GJC bundles participated.
+     */
+    gjcRuntimeSnapshot?: GjcRuntimeSnapshotProvider;
 }
 export type { PromptTemplate } from "../config/prompt-templates";
 export { Settings, type SkillsSettings } from "../config/settings";

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,16 +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";
@@ -208,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) */
@@ -466,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;
@@ -786,6 +798,8 @@ 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;
@@ -980,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;
@@ -1048,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
@@ -1157,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.

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/session-manager.d.ts

@@ -72,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 {
@@ -506,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 {
@@ -596,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;
@@ -614,7 +631,7 @@ export declare class SessionManager {
     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>;
@@ -652,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>;
     /**

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;

package/dist/types/session/streaming-output.d.ts

@@ -3,6 +3,29 @@ export declare const DEFAULT_MAX_LINES = 3000;
 export declare const DEFAULT_MAX_BYTES: number;
 export declare const DEFAULT_MAX_COLUMN = 1024;
 export declare const DEFAULT_ARTIFACT_MAX_BYTES: number;
+/**
+ * Terminal publisher used when managed artifact storage exposes an ID but no
+ * writable pathname. The sink supplies raw content retained up to its artifact
+ * hard cap; `omittedBytes` is the source-byte count already omitted by that cap.
+ * A successful publisher may report additional omitted bytes (for example, a
+ * downstream storage cap); those counts are added to the sink summary. Failed
+ * and unavailable results are surfaced through the bounded artifact diagnostic
+ * without exposing an unresolvable artifact URL.
+ */
+export type TerminalArtifactPublishResult = {
+    status: "published";
+    artifactId: string;
+    omittedBytes?: number;
+} | {
+    status: "unavailable";
+} | {
+    status: "failed";
+    diagnostic: string;
+};
+export type TerminalArtifactPublisher = (content: string, info: {
+    totalBytes: number;
+    omittedBytes: number;
+}) => Promise<TerminalArtifactPublishResult>;
 export interface OutputSummary {
     output: string;
     truncated: boolean;
@@ -18,10 +41,12 @@ export interface OutputSummary {
     columnDroppedBytes?: number;
     /** Number of distinct lines that hit the per-line column cap. */
     columnTruncatedLines?: number;
-    /** Artifact ID for internal URL access (artifact://<id>) when truncated */
+    /** Artifact ID for internal URL access (artifact://<id>) when output was persisted. */
     artifactId?: string;
     /** Bytes omitted from artifact storage after the artifact hard cap was reached. */
     artifactTruncatedBytes?: number;
+    /** Bounded diagnostic when artifact writer or terminal publisher creation, write, finalization, or publication failed. */
+    artifactFailureDiagnostic?: string;
 }
 export interface OutputSinkOptions {
     /**
@@ -30,6 +55,12 @@ export interface OutputSinkOptions {
      */
     artifactPath?: string;
     artifactId?: string;
+    /**
+     * Optional terminal publisher for managed artifact stores that do not expose a
+     * writable path. It is invoked only when visible spill/truncation requires an
+     * artifact, and receives raw content bounded by `artifactMaxBytes`.
+     */
+    artifactPublisher?: TerminalArtifactPublisher;
     /** Tail buffer budget (bytes). Default DEFAULT_MAX_BYTES. */
     spillThreshold?: number;
     /**
@@ -241,12 +272,10 @@ export declare class OutputSink {
      * minimizer rewrites the captured output after the raw bytes have already
      * been streamed.
      *
-     * After this call the buffer is authoritative: streaming counters realign
-     * to the replacement, the retained head window is cleared, and head
-     * retention is disabled so subsequent `push()` calls append directly to the
-     * tail buffer instead of repopulating the (now meaningless) head window
-     * — which would otherwise reorder content and trip the middle-elision
-     * branch in `dump()` against stale totals.
+     * After this call the replacement is authoritative: counters reflect its full
+     * size, the configured head+tail byte windows are retained with UTF-8-safe
+     * boundaries, and future head accumulation is disabled so later `push()` calls
+     * append directly to the tail without reordering the replacement.
      */
     replace(text: string): void;
     dump(notice?: string): Promise<OutputSummary>;