@gajae-code/coding-agent 0.11.4 → 0.11.5

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

@@ -2,6 +2,8 @@ import * as fs from "node:fs";
 import type { Settings } from "../../config/settings";
 import type { DaemonRuntimeInfo } from "../../daemon/control-types";
 import { HEARTBEAT_TTL_MS } from "./daemon-paths";
+import { type DaemonTransitionLock, type NotificationEndpointFile, type NotificationEndpointFileIdentity, type NotificationExactUnlinkResult } from "./notification-service";
+import { type DaemonProcessReference } from "./telegram-daemon-control";
 export { DAEMON_GENERATION, NOTIFICATION_PROTOCOL_VERSION } from "./telegram-daemon-contract";
 import { type ControlServerLike, type LifecycleControlServerFactory } from "./lifecycle-control-runtime";
 import type { OrchestratorDeps } from "./lifecycle-orchestrator";
@@ -10,9 +12,16 @@ import { type AliasTable, type CallbackRoute } from "./telegram-reference";
 export type EnsureDaemonResult = "owner_spawned" | "attached" | "disabled" | "blocked";
 /** Detailed result for orchestration that must distinguish a #2028 handoff from a fresh spawn. */
 export type EnsureTelegramDaemonDetailedResult = "spawned" | "reloaded" | "attached" | "disabled" | "blocked_identity";
+export type TelegramDaemonOwnershipPhase = "provisional" | "ready" | "retired";
 export interface DaemonState {
     pid: number;
+    /** OS process-start provenance; mandatory for PID-authorized ownership actions. */
+    incarnation: string;
     ownerId: string;
+    /** Unique, durable identity for one ownership acquisition. */
+    acquisitionId?: string;
+    /** A provisional owner is physical-live but MUST NOT be attached as ready. */
+    ownershipPhase?: TelegramDaemonOwnershipPhase;
     tokenFingerprint: string;
     chatId: string;
     startedAt: number;
@@ -26,10 +35,8 @@ export interface DaemonState {
     version: 1;
     /**
      * Operational daemon generation of the process that owns the lock, distinct
-     * from the persisted state-schema {@link DaemonState.version}. It records the
-     * wire generation ({@link DAEMON_GENERATION}) the owning daemon speaks so a
-     * freshly-upgraded host can detect — and reload — a still-live pre-upgrade
-     * daemon whose schema version is unchanged. Absent on pre-generation state.
+     * from both the persisted state-schema {@link DaemonState.version} and the
+     * notification wire protocol version. Absent on pre-generation state.
      */
     generation?: number;
     stoppedAt?: number;
@@ -45,8 +52,14 @@ export interface TelegramDaemonFs {
     }>;
     readdir(path: string): Promise<string[]>;
     chmod(path: string, mode: number): Promise<void>;
+    stat?(path: string): Promise<{
+        mtimeMs: number;
+    }>;
+    readEndpointFile?(path: string): Promise<NotificationEndpointFile>;
+    exactUnlink?(path: string, identity: NotificationEndpointFileIdentity): Promise<NotificationExactUnlinkResult>;
 }
 export interface SpawnResult {
+    pid?: number;
     unref?: () => void;
 }
 export interface TelegramDaemonDeps {
@@ -54,6 +67,10 @@ export interface TelegramDaemonDeps {
     now?: () => number;
     pid?: number;
     pidAlive?: (pid: number) => boolean;
+    /** Opens an identity-stable process authority for destructive lifecycle operations. */
+    processReference?: (pid: number) => DaemonProcessReference | undefined;
+    /** Returns immutable process-start provenance, or undefined when unsupported. */
+    pidIncarnation?: (pid: number) => string | undefined;
     spawn?: (command: string, args: string[], opts: {
         detached: boolean;
         stdio: "ignore";
@@ -71,6 +88,8 @@ export interface TelegramDaemonDeps {
     sendSignal?: (pid: number, signal: NodeJS.Signals) => void;
     sleep?: (ms: number) => Promise<void>;
     waitStepMs?: number;
+    /** Bounded startup-readiness timeout; injectable for deterministic handoff tests. */
+    readinessTimeoutMs?: number;
 }
 export declare const HEARTBEAT_INTERVAL_MS = 5000;
 export { HEARTBEAT_TTL_MS };
@@ -104,6 +123,53 @@ export declare function startDaemonLifecycleControl(input: {
     auditRedactionKey: Uint8Array;
     env?: NodeJS.ProcessEnv;
 }): OrchestratorDeps;
+export declare function tryCreateOwnershipLock(fsImpl: TelegramDaemonFs, file: string, initialization: OwnershipLockMetadata): Promise<boolean>;
+type OwnershipLockMetadata = {
+    pid: number;
+    incarnation: string;
+    ownerId?: string;
+    acquisitionId?: string;
+    startedAt: number;
+};
+type LegacyOwnershipLockMetadata = {
+    pid: number;
+    incarnation?: string;
+    startedAt: number;
+};
+type OwnershipLockRead = {
+    kind: "missing";
+} | {
+    kind: "malformed";
+    raw: string;
+    mtimeMs?: number;
+} | {
+    kind: "legacy";
+    metadata: LegacyOwnershipLockMetadata;
+} | {
+    kind: "valid";
+    metadata: OwnershipLockMetadata;
+};
+/** Read lock provenance without treating a corrupt legacy artifact as a filesystem failure. */
+export declare function readOwnershipLock(fsImpl: TelegramDaemonFs, file: string): Promise<OwnershipLockRead>;
+/**
+ * A live initializer lock only proves that a concurrent publisher is active.
+ * It never proves a ready daemon: legacy or unavailable provenance remains
+ * blocked, while a canonical mismatch proves PID reuse and can be reclaimed
+ * under the transition lock.
+ */
+export declare function liveOwnershipLockDecision(input: {
+    lock: OwnershipLockRead;
+    pidAlive: (pid: number) => boolean;
+    pidIncarnation: (pid: number) => string | undefined;
+}): {
+    acquired: false;
+    attached: false;
+    blocked: true;
+} | {
+    acquired: false;
+    attached: false;
+    provisional: true;
+} | undefined;
 export declare function registerNotificationRoot(input: {
     settings: Settings;
     cwd: string;
@@ -121,12 +187,39 @@ export declare function unregisterNotificationRoot(input: {
     sessionId: string;
     fs?: TelegramDaemonFs;
 }): Promise<UnregisterNotificationRootResult>;
+export declare function hasSafeDaemonStateShape(state: unknown): state is DaemonState;
+/** True for a physically live owner with this configuration, including legacy generations. */
+export declare function isPhysicalMatchingOwner(input: {
+    state: DaemonState | undefined;
+    tokenFingerprint: string;
+    chatId: string;
+    pidAlive: (pid: number) => boolean;
+    pidIncarnation?: (pid: number) => string | undefined;
+}): boolean;
+/** True only for a signalable legacy owner or this generation's ready bound child. */
+export declare function isSignalableMatchingOwner(input: {
+    state: DaemonState | undefined;
+    tokenFingerprint: string;
+    chatId: string;
+    pidAlive: (pid: number) => boolean;
+    pidIncarnation?: (pid: number) => string | undefined;
+}): boolean;
 export declare function isFreshLiveOwner(input: {
     state: DaemonState | undefined;
     now: number;
     tokenFingerprint: string;
     chatId: string;
     pidAlive: (pid: number) => boolean;
+    pidIncarnation?: (pid: number) => string | undefined;
+}): boolean;
+/** True only when a physically live matching owner can serve this build's daemon lifecycle contract. */
+export declare function isCurrentCompatibleOwner(input: {
+    state: DaemonState | undefined;
+    now: number;
+    tokenFingerprint: string;
+    chatId: string;
+    pidAlive: (pid: number) => boolean;
+    pidIncarnation?: (pid: number) => string | undefined;
 }): boolean;
 export declare function acquireDaemonOwnership(input: {
     settings: Settings;
@@ -137,6 +230,7 @@ export declare function acquireDaemonOwnership(input: {
     now?: () => number;
     pid?: number;
     pidAlive?: (pid: number) => boolean;
+    pidIncarnation?: (pid: number) => string | undefined;
     randomId?: () => string;
     /** Permit one Windows source launcher PID to daemon PID handoff. */
     allowPidRebind?: boolean;
@@ -145,32 +239,100 @@ export declare function acquireDaemonOwnership(input: {
 }): Promise<{
     acquired: boolean;
     ownerId?: string;
+    acquisitionId?: string;
     attached?: boolean;
     blocked?: boolean;
+    provisional?: boolean;
     reason?: "identity_mismatch";
     reloadRequired?: boolean;
 }>;
 export declare function renewDaemonHeartbeat(input: {
     settings: Settings;
     ownerId: string;
-    /** Bind a daemon heartbeat to the Telegram identity that acquired the lock. */
+    acquisitionId?: string;
+    tokenFingerprint?: string;
+    chatId?: string;
+    fs?: TelegramDaemonFs;
+    now?: () => number;
+    pid?: number;
+    generation?: number;
+    pidIncarnation?: (pid: number) => string | undefined;
+    sleep?: (ms: number) => Promise<void>;
+    stealRetries?: number;
+    stealRetryDelayMs?: number;
+}): Promise<boolean>;
+/** Acquire the lifecycle transition lock with bounded retry for bind/retire races. */
+export declare function acquireTransitionLock(input: {
+    fs: TelegramDaemonFs;
+    path: string;
+    pidAlive?: (pid: number) => boolean;
+    pidIncarnation?: (pid: number) => string | undefined;
+    sleep?: (ms: number) => Promise<void>;
+    retries?: number;
+    retryDelayMs?: number;
+}): Promise<DaemonTransitionLock | undefined>;
+/** Retire only the unchanged provisional acquisition after bounded readiness fails. */
+export declare function retireProvisionalDaemonOwnership(input: {
+    settings: Settings;
+    ownerId: string;
+    acquisitionId?: string;
+    pidIncarnation?: (pid: number) => string | undefined;
+    pidAlive?: (pid: number) => boolean;
+    /** Detached child PID, when the launcher successfully reported it. */
+    pid: number;
+    /** PID which created the provisional reservation before the child was bound. */
+    launcherPid?: number;
+    fs?: TelegramDaemonFs;
+    now?: () => number;
+    sleep?: (ms: number) => Promise<void>;
+    stealRetries?: number;
+    stealRetryDelayMs?: number;
+    /** Only no-child confirmation may retire a ready-like launcher publication. */
+    allowReadyWithoutChildPid?: boolean;
+}): Promise<boolean>;
+/** Wait for a matching current-generation daemon to publish a ready state. */
+export declare function waitForTelegramDaemonReady(input: {
+    settings: Settings;
+    ownerId?: string;
+    acquisitionId?: string;
+    pid?: number;
+    excludedPid?: number;
     tokenFingerprint: string;
     chatId: string;
-    /** Require the current daemon PID after the launcher-to-daemon PID rebind. */
-    pid: number;
     fs?: TelegramDaemonFs;
     now?: () => number;
+    pidAlive?: (pid: number) => boolean;
+    pidIncarnation?: (pid: number) => string | undefined;
+    sleep?: (ms: number) => Promise<void>;
+    waitStepMs?: number;
+    timeoutMs?: number;
 }): Promise<boolean>;
-export declare function releaseDaemonOwnership(input: {
+/** Confirm the provisional owner or retire only its unchanged acquisition. */
+export declare function confirmTelegramDaemonSpawn(input: {
     settings: Settings;
-    ownerId: string;
-    /** Bind release to the Telegram identity that acquired the lock. */
+    spawned: TelegramSpawnOwnerResult;
     tokenFingerprint: string;
     chatId: string;
-    /** Require the current daemon PID after the launcher-to-daemon PID rebind. */
     pid: number;
     fs?: TelegramDaemonFs;
     now?: () => number;
+    pidAlive?: (pid: number) => boolean;
+    pidIncarnation?: (pid: number) => string | undefined;
+    sleep?: (ms: number) => Promise<void>;
+    waitStepMs?: number;
+    timeoutMs?: number;
+}): Promise<boolean>;
+export declare function releaseDaemonOwnership(input: {
+    settings: Settings;
+    ownerId: string;
+    acquisitionId?: string;
+    tokenFingerprint?: string;
+    chatId?: string;
+    pid?: number;
+    generation?: number;
+    pidIncarnation?: (pid: number) => string | undefined;
+    fs?: TelegramDaemonFs;
+    now?: () => number;
 }): Promise<void>;
 /** Read the persisted daemon ownership state (or undefined when absent). */
 export declare function readDaemonState(settings: Pick<Settings, "getAgentDir">, fs?: TelegramDaemonFs): Promise<DaemonState | undefined>;
@@ -182,18 +344,30 @@ export interface TelegramSpawnOwnerInput {
     tokenFingerprint: string;
     chatId: string;
 }
-export interface TelegramSpawnOwnerResult {
-    result: EnsureDaemonResult;
-    ownerId?: string;
+export interface TelegramSpawnAcquisition {
+    readonly ownerId: string;
+    readonly acquisitionId: string;
+    /** PID of the launcher which reserved provisional ownership before spawn. */
+    readonly launcherPid?: number;
+    /** Actual detached child which must publish the ready owner state. */
+    readonly pid?: number;
+}
+export type TelegramSpawnOwnerResult = {
+    result: "owner_spawned";
+    acquisition: TelegramSpawnAcquisition;
+    runtime: DaemonRuntimeInfo;
+    warnings: string[];
+} | {
+    result: "attached";
     runtime: DaemonRuntimeInfo;
     warnings: string[];
-    /**
-     * Set when ownership was NOT acquired because a still-live owner is running an
-     * older daemon generation. The caller must hand off via a reload rather than
-     * attach; see {@link ensureTelegramDaemonRunning}.
-     */
     reloadRequired?: boolean;
-}
+} | {
+    result: "blocked";
+    runtime: DaemonRuntimeInfo;
+    warnings: string[];
+    reloadRequired?: boolean;
+};
 /**
  * Build the detached spawn command/args for the daemon-internal entrypoint.
  * Source mode prepends the entry script so the respawn loads edited source;
@@ -331,6 +505,7 @@ export interface TelegramDaemonOptions {
     pid?: number;
     /** Liveness probe for skipping dead-PID endpoint records in {@link TelegramNotificationDaemon.scanRoots}. */
     pidAlive?: (pid: number) => boolean;
+    pidIncarnation?: (pid: number) => string | undefined;
     botApi?: BotApi;
     control?: DaemonControlHooks;
     /**
@@ -358,6 +533,10 @@ export interface TelegramDaemonOptions {
     richDraft?: {
         enabled: boolean;
     };
+    /** Tool start/completion messages (enabled by default). */
+    toolActivity?: {
+        enabled: boolean;
+    };
     /**
      * Per-session Telegram forum-topic naming. `nameTemplate` supports the
      * `{repo}`, `{branch}`, and `{title}` placeholders; unset preserves the
@@ -403,6 +582,16 @@ export declare class TelegramNotificationDaemon {
     readonly messageRoutes: Map<string | number, CallbackRoute | Omit<CallbackRoute, "answer">>;
     /** Telegram message id backing each streamed `${sessionId}:${coalesceKey}`, for in-place edits. */
     private readonly liveMessages;
+    /** Endpoint-bound ownership for visible or dispatching tool bubbles. */
+    private readonly toolActivityOwners;
+    private readonly revokedToolEndpoints;
+    private readonly unresolvedToolTerminalizations;
+    private toolTerminalizationChain;
+    private toolActivityPolicyEpoch;
+    private toolActivityStopping;
+    private readonly replayToolActivityEpochs;
+    private toolShutdownBarrier;
+    private toolActivityAmbiguous;
     readonly sessions: Map<string, SessionSocket>;
     private readonly runtime;
     private readonly sessionRouter;
@@ -525,6 +714,9 @@ export declare class TelegramNotificationDaemon {
      * (so a delayed old close cannot delete a replacement), and best-effort closes
      * the socket. `scanRoots()` then reconnects the session.
      */
+    private enqueueToolTerminalization;
+    private scheduleVisibleToolTerminalization;
+    private beginToolActivityShutdown;
     private dropSession;
     private deleteMessageRoutes;
     private static readonly THREADED_FRAMES;
@@ -543,6 +735,8 @@ export declare class TelegramNotificationDaemon {
     private topicIdentityBase;
     private topicOwnerForIdentity;
     private sessionCanClaimIdentity;
+    private toolActivityOwner;
+    private toolActivityAuthorityIsCurrent;
     private submitThreadedFrame;
     private existingTopicForPrivateChat;
     private topicAuthorityLease;

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

@@ -1,4 +1,4 @@
-import { type AgentTelemetryConfig, ThinkingLevel } from "@gajae-code/agent-core";
+import { type AgentMessage, type AgentTelemetryConfig, ThinkingLevel } from "@gajae-code/agent-core";
 import { type AuthCredentialSelector, type Model, type ProviderSessionState } from "@gajae-code/ai";
 import { createAppendOnlyContextManager, providerSupportsAppendOnlyAuto, resolveAppendOnlyMode } from "../append-only-mode";
 import { type Rule } from "../capability/rule";
@@ -25,6 +25,19 @@ import { type BuildSystemPromptResult } from "../system-prompt";
 import { BashTool, BUILTIN_TOOLS, createTools, EditTool, EvalTool, FindTool, HIDDEN_TOOLS, type LspStartupServerInfo, loadSshTool, ReadTool, ResolveTool, SearchTool, type Tool, type ToolSession, WebSearchTool, WriteTool } from "../tools";
 import { EventBus } from "../utils/event-bus";
 import { type WorkspaceTree } from "../workspace-tree";
+/**
+ * Reconcile a resumed transcript that ends on an unpaired tool call.
+ *
+ * When a subagent finishes by calling `yield` (or any turn is torn down right
+ * after a tool executes), the terminating abort can land before the tool
+ * result is persisted, leaving the saved session ending on an assistant
+ * `toolCall` with no matching `toolResult`. Replaying that history verbatim on
+ * resume produces an invalid provider request (a tool_use not followed by a
+ * tool_result) and the resumed turn fails immediately. Synthesize a placeholder
+ * result for any such trailing unpaired tool call so a resumed session always
+ * starts from a valid, paired history. No-op for well-formed transcripts.
+ */
+export declare function reconcileTrailingToolCalls(messages: AgentMessage[]): AgentMessage[];
 export interface CreateAgentSessionOptions {
     /** Working directory for project-local discovery. Default: getProjectDir() */
     cwd?: string;
@@ -152,6 +165,8 @@ export interface CreateAgentSessionOptions {
     notificationHostModeSupported?: boolean;
     /** Whether this host mode can own the root SDK endpoint. Default: true. */
     sdkHostModeSupported?: boolean;
+    /** Override configured Discord/Slack daemon readiness, primarily for embedded hosts and deterministic tests. */
+    ensureNotificationProviderDaemon?: (provider: "discord" | "slack", settings: Settings) => Promise<unknown>;
     /**
      * Opt-in OpenTelemetry instrumentation forwarded to the underlying Agent.
      * Passing `{}` enables the loop's GenAI-semantic-convention spans. See

package/dist/types/secrets/index.d.ts

@@ -1,8 +1,10 @@
-import type { SecretEntry } from "./obfuscator";
+import { type SecretEntry, SecretObfuscator } from "./obfuscator";
+/** Create an obfuscator using the process-local authenticated-placeholder key. */
+export declare function createSecretObfuscator(entries: SecretEntry[]): SecretObfuscator;
 export { deobfuscateSessionContext, obfuscateMessages, type SecretEntry, SecretObfuscator } from "./obfuscator";
 /**
  * Load secrets from project-local and global secrets.yml files.
- * Project-local entries override global entries with matching content.
+ * Project-local plain entries override global entries with matching content.
  */
 export declare function loadSecrets(cwd: string, agentDir: string): Promise<SecretEntry[]>;
 /** Collect environment variable values that look like secrets. */

package/dist/types/secrets/obfuscator.d.ts

@@ -9,7 +9,7 @@ export interface SecretEntry {
 }
 export declare class SecretObfuscator {
     #private;
-    constructor(entries: SecretEntry[]);
+    constructor(entries: SecretEntry[], key?: Uint8Array);
     hasSecrets(): boolean;
     /** Obfuscate all secrets in text. Bidirectional placeholders for obfuscate mode, one-way for replace. */
     obfuscate(text: string): string;

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

@@ -101,7 +101,7 @@ 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 CustomMessage } from "./messages";
-import type { BranchSummaryEntry, CompactionEntry, NewSessionOptions, SessionContext, SessionManager, SessionManagerCloseOutcome } from "./session-manager";
+import type { BranchSummaryEntry, CompactionEntry, NewSessionOptions, RecoveryHydrationContext, RecoveryHydrationPromotionFence, SessionContext, SessionManager, SessionManagerCloseOutcome } from "./session-manager";
 import { ToolChoiceQueue } from "./tool-choice-queue";
 import { YieldQueue } from "./yield-queue";
 /** Session-specific events that extend the core AgentEvent */
@@ -250,12 +250,30 @@ export interface AgentSessionConfig {
     discoveryMode?: "off" | "mcp-only" | "all";
     /** MCP tool names to activate for the current session when discovery mode is enabled. */
     initialSelectedMCPToolNames?: string[];
-    /** Whether constructor-provided MCP defaults should be persisted immediately. */
+    /** Built-in discoverable tool names restored for the current all-discovery session. */
+    initialSelectedDiscoveredBuiltinToolNames?: string[];
+    /** Discoverable built-ins active for configured or explicit reasons independently of persisted discovery selection. */
+    initialBaselineDiscoveredBuiltinToolNames?: string[];
+    /** Whether an MCP selection was explicitly supplied to the constructor, including an empty selection. */
+    initialMCPToolSelectionIsExplicit?: boolean;
+    /** Whether a discoverable built-in selection was explicitly supplied to the constructor, including an empty selection. */
+    initialDiscoveredBuiltinToolSelectionIsExplicit?: boolean;
+    /** Whether constructor-provided MCP selections should be persisted immediately. */
     persistInitialMCPToolSelection?: boolean;
+    /** Whether constructor-provided discovered-built-in selections should be persisted immediately. */
+    persistInitialDiscoveredBuiltinToolSelection?: boolean;
+    /** Explicit MCP authority to write for a new session; distinct from active fallback tools. */
+    initialPersistedMCPToolNames?: string[];
+    /** Explicit discovered built-in authority to write for a new session; distinct from active fallback tools. */
+    initialPersistedDiscoveredBuiltinToolNames?: string[];
+    /** Immutable predecessor authority while a recovery host is read-only. */
+    recoveryHydrationContext?: RecoveryHydrationContext;
     /** MCP server names whose tools should seed discovery-mode sessions whenever those servers are connected. */
     defaultSelectedMCPServerNames?: string[];
     /** MCP tool names that should seed brand-new sessions created from this AgentSession. */
     defaultSelectedMCPToolNames?: string[];
+    /** MCP capabilities that are always active and never part of persisted user selection. */
+    mandatoryMCPToolNames?: string[];
     /** TTSR manager for time-traveling stream rules */
     ttsrManager?: TtsrManager;
     /** Secret obfuscator for deobfuscating streaming edit content */
@@ -472,6 +490,13 @@ export declare class AgentSession {
     };
     readonly rawSseDebugBuffer: RawSseDebugBuffer;
     constructor(config: AgentSessionConfig);
+    /**
+     * Resolves when constructor-time workflow-gate tool restoration (ask
+     * registration plus durable active-workflow attachment) has settled. The
+     * SDK factory awaits this so a resumed canonical workflow session is
+     * returned with `ask` already resident.
+     */
+    get workflowGateToolRestoration(): Promise<void>;
     /** Model registry for API key resolution and model discovery */
     get modelRegistry(): ModelRegistry;
     /** Advance the tool-choice queue and return the next directive for the upcoming LLM call. */
@@ -704,6 +729,10 @@ export declare class AgentSession {
     /** All messages including custom types like BashExecutionMessage */
     get messages(): AgentMessage[];
     get transcriptPromptGeneration(): number;
+    /** 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>;
     /** Main startup calls this exactly once, after a strict open returned `kind: "opened"`. */
     continuePersistedHistory(): Promise<void>;
     buildDisplaySessionContext(): SessionContext;

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

@@ -1,3 +1,18 @@
+/**
+ * Session-scoped artifact storage for truncated tool outputs.
+ *
+ * Artifacts are stored in a directory alongside the session file,
+ * accessible via artifact:// URLs.
+ */
+import { type ManagedSessionDescendantStore } from "./internal/managed-session-storage";
+export interface ManagedOutputGeneration {
+    outputFilename: string;
+    metadataFilename: string;
+    outputSizeBytes: number;
+    outputSha256: string;
+    metadataSizeBytes: number;
+    metadataSha256: string;
+}
 export interface ArtifactSaveOptions {
     maxBytes?: number;
 }
@@ -16,32 +31,39 @@ export declare class ArtifactManager {
     /**
      * @param dir Directory that will hold artifact files. Created lazily on first save.
      */
-    constructor(dir: string);
+    constructor(target: string | ManagedSessionDescendantStore);
     /**
      * Artifact directory path.
      * Directory may not exist until first artifact is saved.
      */
     get dir(): string;
+    getManagedRootAuthority(): import("./internal/managed-session-storage").ManagedDirectoryRoot | undefined;
+    getManagedSubtreeRootAuthority(): import("./internal/managed-session-storage").ManagedDirectoryRoot | undefined;
+    getManagedStore(): ManagedSessionDescendantStore | undefined;
+    assertManagedBinding(): void;
+    replaceNamed(filename: string, content: string): Promise<void>;
+    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>;
     /**
      * Atomically allocate next artifact ID.
      * IDs are sequential within the session.
      */
     allocateId(): number;
     /**
-     * Allocate a new artifact path and ID without writing content.
+     * Reserve an artifact ID without exposing a writable managed pathname.
      *
-     * @param toolType Tool name for file extension (e.g., "bash", "read")
+     * Streaming callers that only understand bare paths fail closed; use `save`
+     * for terminally published artifact content.
      */
     allocatePath(toolType: string): Promise<{
         id: string;
-        path: string;
+        path?: string;
     }>;
     /**
      * Save content as an artifact and return the artifact ID.
-     *
-     * @param content Full content to save
-     * @param toolType Tool name for file extension (e.g., "bash", "read")
-     * @returns Artifact ID (numeric string)
+     * Content is written to a private temporary inode, synced, and linked into
+     * the artifact directory only after the complete terminal payload exists.
      */
     save(content: string, toolType: string, options?: ArtifactSaveOptions): Promise<string>;
     /**

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

@@ -1,3 +1,4 @@
+import * as native from "@gajae-code/natives";
 import type { ResumeSessionIdentity } from "../session-manager";
 export declare const MANAGED_SESSION_LAYOUT_VERSION: 2;
 export declare const MANAGED_SESSION_IDENTITY_VERSION: 1;
@@ -14,6 +15,12 @@ export interface ManagedScope {
     directoryPath: string;
     platform: "posix" | "win32";
 }
+export declare function managedDirectoryAuthorityForScope(scope: ManagedScope): native.RecoveryFsRoot | undefined;
+export declare function managedDirectoryIdentityForScope(scope: ManagedScope): {
+    dev: bigint;
+    ino: bigint;
+};
+export declare function managedRootForScope(scope: ManagedScope): import("./managed-session-storage").ManagedDirectoryRoot;
 export type ManagedMigrationPolicy = "copy-retain" | "disabled";
 export type ManagedScopeErrorCode = "cwd_missing" | "cwd_not_directory" | "identity_unavailable" | "network_unsupported" | "sessions_root_unavailable" | "binding_conflict" | "binding_invalid";
 export type ManagedScopeResolution = {