@gajae-code/coding-agent 0.11.3 → 0.11.5

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 = {

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

@@ -1,3 +1,4 @@
+import { type NativeDirectoryTreeSnapshot, type NativeOwnerOnlySecurityResult, type RecoveryFsRoot } from "@gajae-code/natives";
 export declare const MANAGED_ARTIFACT_MAX_DEPTH = 32;
 export declare const MANAGED_ARTIFACT_MAX_FILES = 10000;
 export declare const MANAGED_ARTIFACT_MAX_FILE_BYTES: number;
@@ -16,23 +17,79 @@ export interface ManagedFileSnapshot {
         ino: bigint;
         size: number;
         mtimeNs: bigint;
+        ctimeNs: bigint;
+        sha256: string;
     };
 }
+export declare function validateNativeSecurityResult(value: unknown, operation: "apply" | "verify", kind: "directory" | "file"): NativeOwnerOnlySecurityResult;
+/** Captured configured-root authority for managed paths only. */
+export interface ManagedDirectoryRoot {
+    readonly canonicalPath: string;
+    readonly dev: bigint;
+    readonly ino: bigint;
+}
+export declare function managedDirectoryRoot(configuredRoot: string): ManagedDirectoryRoot;
+export declare function retainManagedDirectoryAuthority(root: ManagedDirectoryRoot, directory: string, expected?: {
+    dev: bigint;
+    ino: bigint;
+}): RecoveryFsRoot | undefined;
+export declare function assertManagedDirectoryRoot(root: ManagedDirectoryRoot): void;
+/** Internal retained-root capability for one managed descendant subtree. */
+export declare class ManagedSessionDescendantStore {
+    #private;
+    constructor(root: ManagedDirectoryRoot, baseDir: string, retained?: {
+        authority: RecoveryFsRoot;
+        authorityBaseDir: string;
+    });
+    get dir(): string;
+    get rootAuthority(): ManagedDirectoryRoot;
+    get subtreeRootAuthority(): ManagedDirectoryRoot;
+    deriveSubtree(relativePath: string): ManagedSessionDescendantStore;
+    retainAuthority(): RecoveryFsRoot | undefined;
+    assertBound(): void;
+    verifyRootSecurity(): void;
+    ensureDirectory(relativePath?: string): ManagedDirectoryRoot;
+    publishNoReplace(relativePath: string, bytes: Uint8Array): Promise<void>;
+    publishNoReplaceSync(relativePath: string, bytes: Uint8Array): void;
+    replace(relativePath: string, bytes: Uint8Array): Promise<void>;
+    replaceSync(relativePath: string, bytes: Uint8Array): void;
+    appendSync(relativePath: string, bytes: Uint8Array): void;
+    /** Read an exact managed file without exposing its pathname as authority. */
+    readExpected(relativePath: string): ManagedFileSnapshot | null;
+    /** Remove an exact captured file without reopening its pathname as authority. */
+    removeExpected(relativePath: string, expected: ManagedFileSnapshot): void;
+    /** Read and remove one managed descendant through retained authority. */
+    consume(relativePath: string): Promise<Uint8Array | null>;
+    /** Remove one managed descendant through retained authority when it exists. */
+    remove(relativePath: string): Promise<void>;
+    /** Capture a complete descendant tree through this retained root. */
+    captureTree(relativePath: string): NativeDirectoryTreeSnapshot;
+    /** Copy an exact captured tree into an absent managed destination. */
+    importTree(sourceRelativePath: string, destinationRelativePath: string, snapshot: NativeDirectoryTreeSnapshot): Promise<void>;
+    moveTreeNoReplace(sourceRelativePath: string, destinationRelativePath: string, expected: NativeDirectoryTreeSnapshot): void;
+    removeTreeExpected(relativePath: string, expected: NativeDirectoryTreeSnapshot): void;
+    fsyncTree(): NativeDirectoryTreeSnapshot;
+}
 export declare function shouldFsyncManagedDirectory(platform?: NodeJS.Platform): boolean;
 /** Create a managed directory and fail closed unless its owner-only mode/ACL verifies. */
-export declare function ensureManagedDirectory(pathname: string): void;
+export declare function ensureManagedDirectory(pathname: string, root?: ManagedDirectoryRoot): void;
+/** Captures a bounded prefix from one no-follow descriptor and rechecks the pathname before use. */
+export declare function captureManagedFilePrefixNoFollow(pathname: string, maxBytes: number): ManagedFileSnapshot;
 /** Captures header/hash/copy input from one no-follow descriptor and rechecks the pathname before use. */
 export declare function captureManagedFileNoFollow(pathname: string): ManagedFileSnapshot;
 /** Atomically publishes bytes without replacing an existing destination. */
-export declare function publishManagedFileNoReplace(destination: string, bytes: Uint8Array, assertOwned?: () => void): Promise<void>;
-export declare function publishManagedFileNoReplaceSync(destination: string, bytes: Uint8Array): void;
+export declare function publishManagedFileNoReplace(destination: string, bytes: Uint8Array, assertOwned?: () => void, root?: ManagedDirectoryRoot): Promise<void>;
+export declare function publishManagedFileNoReplaceSync(destination: string, bytes: Uint8Array, root?: ManagedDirectoryRoot): void;
+/** Replace one managed regular file while retaining the secured staging fd through publication. */
+export declare function replaceManagedFileSync(destination: string, bytes: Uint8Array, root: ManagedDirectoryRoot): void;
+export declare function replaceManagedFile(destination: string, bytes: Uint8Array, root: ManagedDirectoryRoot): Promise<void>;
 /** Copy the exact bytes captured from one no-follow source descriptor. */
-export declare function copyManagedFileNoReplace(source: string, destination: string, snapshot?: ManagedFileSnapshot): Promise<void>;
+export declare function copyManagedFileNoReplace(source: string, destination: string, snapshot?: ManagedFileSnapshot, root?: ManagedDirectoryRoot): Promise<void>;
 /** Acquire a lease lock with bounded wait, heartbeats, conservative stale reclaim, and fencing. */
-export declare function acquireManagedLock(locksDirectory: string, name: string): Promise<ManagedStorageLock>;
+export declare function acquireManagedLock(locksDirectory: string, name: string, root?: ManagedDirectoryRoot): Promise<ManagedStorageLock>;
 /** Bounds a no-follow artifact tree before it can be copied or deleted. */
 export declare function validateManagedArtifactTree(root: string): void;
 /** Flush a copied managed artifact tree, including empty directories, before publishing its receipt. */
-export declare function fsyncManagedArtifactTree(root: string): void;
+export declare function fsyncManagedArtifactTree(root: string): NativeDirectoryTreeSnapshot;
 export declare function publishManagedTombstone(destination: string, record: Record<string, unknown>, assertOwned?: () => void): Promise<void>;
 export declare function unlinkManagedFileVerified(pathname: string, expected: ManagedFileSnapshot["identity"]): Promise<void>;

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

@@ -1,14 +1,17 @@
 import { type AgentMessage } from "@gajae-code/agent-core";
 import type { ConfiguredModelChainEntry as SharedConfiguredModelChainEntry } from "@gajae-code/agent-core/compaction";
 import type { ImageContent, Message, MessageAttribution, ServiceTier, TextContent } from "@gajae-code/ai";
+import * as native from "@gajae-code/natives";
 import type { TtsrInjectionRecord } from "../export/ttsr";
+import type { ManagedLegacyLocalMigrationSource } from "../internal-urls/local-protocol";
 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 BashExecutionMessage, type CustomMessage, type FileMentionMessage, type HookMessage, type PythonExecutionMessage } from "./messages";
 import { type SessionManagerReadAccess, sessionManagerReadCapability } from "./session-manager-internal";
-import type { SessionStorage, SessionStorageStat, VerifiedSessionDeleteResult, VerifiedSessionDeleteTarget } from "./session-storage";
-export declare const CURRENT_SESSION_VERSION = 4;
+import type { ManagedSessionSecurityContext, SessionStorage, SessionStorageStat, VerifiedSessionDeleteResult, VerifiedSessionDeleteTarget } from "./session-storage";
+export declare const CURRENT_SESSION_VERSION = 5;
 export interface SessionHeader {
     type: "session";
     version?: number;
@@ -167,6 +170,17 @@ export interface MCPToolSelectionEntry extends SessionEntryBase {
     type: "mcp_tool_selection";
     /** MCP tool names selected for visibility in discovery mode. */
     selectedToolNames: string[];
+    /** Legacy v4 combined built-in authority, retained for read compatibility. */
+    selectedDiscoveredBuiltinToolNames?: string[];
+    /** Correlates the ordered MCP and built-in entries emitted by one combined activation. */
+    mutationCorrelationId?: string;
+}
+/** Persisted discovered-built-in selection state, independent of MCP authority. */
+export interface DiscoveredBuiltinToolSelectionEntry extends SessionEntryBase {
+    type: "discovered_builtin_tool_selection";
+    selectedToolNames: string[];
+    /** Correlates the ordered MCP and built-in entries emitted by one combined activation. */
+    mutationCorrelationId?: string;
 }
 /** Session init entry - captures initial context for subagent sessions (debugging/replay). */
 export interface SessionInitEntry extends SessionEntryBase {
@@ -214,7 +228,7 @@ export interface CustomMessageEntry<T = unknown> extends SessionEntryBase {
     evictedContent?: EvictedContentMarker;
 }
 /** Session entry - has id/parentId for tree structure (returned by "read" methods in SessionManager) */
-export type SessionEntry = SessionMessageEntry | ThinkingLevelChangeEntry | ModelChangeEntry | ServiceTierChangeEntry | CompactionEntry | BranchSummaryEntry | CustomEntry | CustomMessageEntry | LabelEntry | TtsrInjectionEntry | MCPToolSelectionEntry | SessionInitEntry | ModeChangeEntry | ConfiguredModelChainEntry;
+export type SessionEntry = SessionMessageEntry | ThinkingLevelChangeEntry | ModelChangeEntry | ServiceTierChangeEntry | CompactionEntry | BranchSummaryEntry | CustomEntry | CustomMessageEntry | LabelEntry | TtsrInjectionEntry | MCPToolSelectionEntry | DiscoveredBuiltinToolSelectionEntry | SessionInitEntry | ModeChangeEntry | ConfiguredModelChainEntry;
 /** Append-only replacement for mutable fields on the session header. */
 export interface HeaderPatchRecord {
     type: "header_patch";
@@ -270,8 +284,12 @@ export interface SessionContext {
     ttsrMessageCount?: number;
     /** MCP tool names selected through discovery for this session branch. */
     selectedMCPToolNames: string[];
+    /** Built-in discoverable tool names activated through discovery, when explicitly persisted. */
+    selectedDiscoveredBuiltinToolNames?: string[];
     /** Whether this branch contains an explicit persisted MCP selection entry. */
     hasPersistedMCPToolSelection: boolean;
+    /** Whether this branch contains an explicit persisted discovered-built-in selection entry. */
+    hasPersistedDiscoveredBuiltinToolSelection?: boolean;
     /** Active mode (e.g. "plan") or "none" if no special mode is active */
     mode: string;
     /** Mode-specific data from the last mode_change entry */
@@ -316,7 +334,7 @@ export interface StrictSessionOpenSuccess {
 }
 export interface StrictSessionOpenFailure {
     kind: "error";
-    reason: ResumeTailError["reason"] | "identity-mismatch";
+    reason: ResumeTailError["reason"] | "identity-mismatch" | "migration-required";
 }
 /** Exact transcript bytes and authority captured from one descriptor-bound read. */
 export interface CapturedSessionTranscriptSnapshot {
@@ -335,6 +353,23 @@ export type StrictSessionForkResult = {
 } | StrictSessionOpenFailure;
 /** Result of opening an inspected session without create-or-rewrite fallback. */
 export type StrictSessionOpenResult = StrictSessionOpenSuccess | StrictSessionOpenFailure;
+/**
+ * Capability returned only by a strict recovery hydration open. It represents
+ * immutable transcript authority and is consumed by the promotion seam.
+ */
+export interface RecoveryHydrationContext {
+    readonly identity: ResumeSessionIdentity;
+}
+export interface RecoveryHydrationOpenSuccess {
+    readonly kind: "hydrated";
+    readonly manager: SessionManager;
+    readonly context: RecoveryHydrationContext;
+}
+export type RecoveryHydrationOpenResult = RecoveryHydrationOpenSuccess | StrictSessionOpenFailure;
+export interface RecoveryHydrationPromotionFence {
+    /** The caller has durably published ownership and acquired its writer lease. */
+    readonly ownershipReady: true;
+}
 export interface SessionInfo {
     path: string;
     id: string;
@@ -434,6 +469,22 @@ export declare function getLatestCompactionEntry(entries: SessionEntry[]): Compa
  * Handles compaction and branch summaries along the path.
  */
 export declare function buildSessionContext(entries: SessionEntry[], leafId?: string | null, byId?: Map<string, SessionEntry>, sessionIdentityNamespace?: string): SessionContext;
+/** A session directory's authority is distinct from its string path. */
+export type SessionDestination = {
+    readonly kind: "managed";
+    readonly directory: string;
+    readonly securityContext: ManagedSessionSecurityContext;
+} | {
+    readonly kind: "explicit";
+    readonly directory: string;
+};
+export type SessionDestinationInput = string | SessionDestination | undefined;
+interface ForkArtifactPublication {
+    readonly snapshot: native.NativeDirectoryTreeSnapshot;
+    readonly store: ManagedSessionDescendantStore;
+    readonly cleanupStore: ManagedSessionDescendantStore;
+    readonly cleanupRelativePath: string;
+}
 /** Exported for testing */
 export declare function loadEntriesFromFile(filePath: string, storage?: SessionStorage): Promise<FileEntry[]>;
 declare class RecentSessionInfo {
@@ -520,6 +571,7 @@ export declare class SessionManager {
     private sessionDir;
     private readonly persist;
     private readonly storage;
+    private destination;
     private constructor();
     /**
      * Snapshot of the five cache-invalidation revision domains (plan: Lane 1
@@ -552,6 +604,7 @@ export declare class SessionManager {
         oldSessionFile: string;
         newSessionFile: string;
     } | undefined>;
+    copyArtifactsForFork(oldSessionFile: string, newSessionFile: string): Promise<ForkArtifactPublication | undefined>;
     /**
      * Move the session to a new working directory.
      * Moves session files and artifacts on disk, updates all internal references,
@@ -592,10 +645,13 @@ export declare class SessionManager {
      * Returns the session artifacts directory path (session file path without .jsonl).
      * Returns null when the session is not persisted to a file.
      * When this session has adopted an external ArtifactManager (subagent case),
-     * returns that manager's directory so reads/writes land in the shared parent
-     * dir instead of a private (non-existent) subdir.
+     * never exposes that managed directory as a pathname. Reads and writes use the
+     * adopted manager capability directly.
      */
     getArtifactsDir(): string | null;
+    isManagedDestination(): boolean;
+    /** Supplies opaque retained authority for mandatory managed legacy local migration. */
+    getManagedLegacyLocalMigrationSource(): ManagedLegacyLocalMigrationSource | null;
     /**
      * Adopt an externally-owned ArtifactManager. Used by subagents to share
      * the parent session's artifact directory and ID counter.
@@ -716,12 +772,10 @@ export declare class SessionManager {
      * @returns Entry id
      */
     appendCustomMessageEntry<T = unknown>(customType: string, content: string | (TextContent | ImageContent)[], display: boolean, details?: T, attribution?: MessageAttribution, observationId?: string): string;
-    /**
-     * Append an MCP tool selection entry recording the discovery-selected MCP tools.
-     * @param selectedToolNames MCP tool names selected for this branch
-     * @returns Entry id
-     */
-    appendMCPToolSelection(selectedToolNames: string[]): string;
+    /** Append MCP discovery selection authority without altering discovered built-in authority. */
+    appendMCPToolSelection(selectedToolNames: string[], mutationCorrelationId?: string): string;
+    /** Append discovered built-in selection authority without altering MCP authority. */
+    appendDiscoveredBuiltinToolSelection(selectedToolNames: string[], mutationCorrelationId?: string): string;
     /**
      * Append a TTSR injection entry recording which rules were injected.
      * @param ruleNames Names of rules that were injected
@@ -833,20 +887,24 @@ export declare class SessionManager {
      * @param cwd Working directory (stored in session header)
      * @param sessionDir Optional session directory. If omitted, uses default (~/.gjc/agent/sessions/<encoded-cwd>/).
      */
-    static create(cwd: string, sessionDir?: string, storage?: SessionStorage): SessionManager;
+    static nestedManagedDestination(authority: ManagedDirectoryRoot | ManagedSessionDescendantStore, directory: string): SessionDestination;
+    static managedDestination(cwd: string, agentDir?: string, storage?: SessionStorage): SessionDestination;
+    static explicitDestination(directory: string): SessionDestination;
+    static create(cwd: string, destinationInput?: SessionDestinationInput, storage?: SessionStorage): SessionManager;
     /** Resolve a default-managed candidate through binding validation and copy-retain migration before mutation. */
     static prepareManagedCandidateForWrite(filePath: string, migrationPolicy: SessionDirectoryMigrationPolicy): Promise<string>;
     /**
      * Fork a session into the current project directory.
      * Copies history from another session file while creating a new session file in the current sessionDir.
      */
-    static forkFrom(sourcePath: string, cwd: string, sessionDir?: string, storage?: SessionStorage, migrationPolicy?: SessionDirectoryMigrationPolicy): Promise<SessionManager>;
+    static forkFrom(sourcePath: string, cwd: string, destinationInput?: SessionDestinationInput, storage?: SessionStorage, migrationPolicy?: SessionDirectoryMigrationPolicy): Promise<SessionManager>;
     /**
      * Open a specific session file.
      * @param path Path to session file
      * @param sessionDir Optional session directory for /new or /branch. If omitted, derives from file's parent.
      */
-    static open(filePath: string, sessionDir?: string, storage?: SessionStorage, migrationPolicy?: SessionDirectoryMigrationPolicy): Promise<SessionManager>;
+    static open(filePath: string, destinationInput?: SessionDestinationInput, storage?: SessionStorage, migrationPolicy?: SessionDirectoryMigrationPolicy): Promise<SessionManager>;
+    static openNestedManaged(filePath: string, destination: SessionDestination, store: ManagedSessionDescendantStore, storage?: SessionStorage): Promise<SessionManager>;
     /**
      * List sessions for the resume picker without recovery or other maintenance writes.
      */
@@ -860,21 +918,33 @@ export declare class SessionManager {
      * revalidate captured authority before destination initialization and transcript
      * persistence; destination history always comes from the captured bytes.
      */
-    static forkFromCaptured(snapshot: CapturedSessionTranscriptSnapshot, cwd: string, sessionDir?: string, _migrationPolicy?: SessionDirectoryMigrationPolicy): Promise<StrictSessionForkResult>;
+    static forkFromCaptured(snapshot: CapturedSessionTranscriptSnapshot, cwd: string, destinationInput?: SessionDestinationInput, _migrationPolicy?: SessionDirectoryMigrationPolicy): Promise<StrictSessionForkResult>;
     /** Inspect a selected session without acquiring write-capable ownership. */
     static inspectSessionTailReadOnly(filePath: string, storage?: SessionStorage): Promise<ResumeTailInspection>;
+    /**
+     * Hydrate an existing predecessor transcript for recovery without taking any
+     * write-capable action. The caller must retain the returned context and use
+     * the explicit promotion seam only after its ownership-ready fence and writer
+     * lease are durable.
+     */
+    static openExistingForRecoveryHydrationStrict(identity: ResumeSessionIdentity, destinationInput?: SessionDestinationInput, storage?: SessionStorage): Promise<RecoveryHydrationOpenResult>;
+    /**
+     * Allows the normal post-open metadata sanitation only after the caller has
+     * fsynced its external ownership-ready fence and acquired the writer lease.
+     */
+    promoteRecoveryHydrationAfterOwnershipReadyFence(context: RecoveryHydrationContext, fence: RecoveryHydrationPromotionFence): Promise<void>;
     /**
      * Main startup code MUST retain the consented inspection identity and branch on
      * the returned discriminant; an error result never creates, rewrites, or adopts
      * the selected path. Breadcrumb ownership begins only after `kind: "opened"`.
      */
-    static openExistingStrict(identity: ResumeSessionIdentity, sessionDir?: string, storage?: SessionStorage, migrationPolicy?: SessionDirectoryMigrationPolicy): Promise<StrictSessionOpenResult>;
+    static openExistingStrict(identity: ResumeSessionIdentity, destinationInput?: SessionDestinationInput, storage?: SessionStorage, migrationPolicy?: SessionDirectoryMigrationPolicy): Promise<StrictSessionOpenResult>;
     /**
      * Continue the most recent session, or create new if none.
      * @param cwd Working directory
      * @param sessionDir Optional session directory. If omitted, uses default (~/.gjc/agent/sessions/<encoded-cwd>/).
      */
-    static continueRecent(cwd: string, sessionDir?: string, storage?: SessionStorage, migrationPolicy?: SessionDirectoryMigrationPolicy): Promise<SessionManager>;
+    static continueRecent(cwd: string, destinationInput?: SessionDestinationInput, storage?: SessionStorage, migrationPolicy?: SessionDirectoryMigrationPolicy): Promise<SessionManager>;
     /** Create an in-memory session (no file persistence) */
     static inMemory(cwd?: string, storage?: SessionStorage): SessionManager;
     /**

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

@@ -1,3 +1,5 @@
+import * as native from "@gajae-code/natives";
+import { type ManagedDirectoryRoot } from "./internal/managed-session-storage";
 export interface SessionStorageStat {
     dev: bigint;
     ino: bigint;
@@ -48,7 +50,31 @@ export interface SessionStorageWriterOpenOptions {
     onError?: (err: Error) => void;
     /** Injectable OS-close dispatcher; defaults to `fs.closeSync`. */
     closeAdapter?: SessionStorageWriterCloseAdapter;
+    /** Opaque authority for default-computed managed destinations only. */
+    securityContext?: SessionStorageSecurityContext;
 }
+/**
+ * Immutable authority attached only to a computed managed session destination.
+ * A caller-supplied pathname never receives this capability, even when it
+ * happens to equal the current default session directory.
+ */
+export interface ManagedSessionSecurityContext {
+    readonly kind: "managed";
+    readonly agentDir: string;
+    readonly sessionsRoot: string;
+    readonly sessionDir: string;
+    readonly rootAuthority: ManagedDirectoryRoot;
+    readonly retainedAuthority?: native.RecoveryFsRoot;
+}
+/** @internal Create the only accepted managed writer authority object. */
+export declare function createManagedSessionSecurityContext(input: {
+    agentDir: string;
+    sessionsRoot: string;
+    sessionDir: string;
+    rootAuthority: ManagedDirectoryRoot;
+    retainedAuthority?: native.RecoveryFsRoot;
+}): ManagedSessionSecurityContext;
+export type SessionStorageSecurityContext = ManagedSessionSecurityContext | undefined;
 export interface SessionStorageWriter {
     writeLine(line: string): Promise<void>;
     /**
@@ -205,6 +231,7 @@ type NativeDirectoryTreeEntry = {
     ino: string;
     size: string;
     mtimeNs: string;
+    ctimeNs: string;
     sha256?: string;
 };
 export type NativeDirectoryTreeSnapshot = {

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

@@ -24,6 +24,10 @@ export interface OutputSummary {
     artifactTruncatedBytes?: number;
 }
 export interface OutputSinkOptions {
+    /**
+     * Deprecated managed artifact pathname. Bare paths are deliberately ignored:
+     * streaming output must be terminally published through ArtifactManager.
+     */
     artifactPath?: string;
     artifactId?: string;
     /** Tail buffer budget (bytes). Default DEFAULT_MAX_BYTES. */

package/dist/types/task/executor.d.ts

@@ -15,6 +15,7 @@ import { AgentRegistry } from "../registry/agent-registry";
 import type { ForkContextSeed } from "../session/agent-session";
 import type { ArtifactManager } from "../session/artifacts";
 import type { AuthStorage } from "../session/auth-storage";
+import { SessionManager } from "../session/session-manager";
 import type { ContextFileEntry } from "../tools";
 import type { EventBus } from "../utils/event-bus";
 import type { WorkspaceTree } from "../workspace-tree";
@@ -80,6 +81,7 @@ export interface ExecutorOptions {
      * artifacts directory (no per-subagent subdir).
      */
     parentArtifactManager?: ArtifactManager;
+    managedPersistence?: ManagedTaskPersistence;
     parentHindsightSessionState?: HindsightSessionState;
     /**
      * Parent agent's OpenTelemetry configuration. When defined, the subagent's
@@ -94,6 +96,13 @@ export interface ExecutorOptions {
     autoloadSkills?: Skill[];
     forkContextSeed?: ForkContextSeed;
 }
+export declare class ManagedTaskPersistence {
+    #private;
+    constructor(artifacts: ArtifactManager, taskId: string);
+    openSession(): Promise<SessionManager>;
+    publishOutput(rawOutput: string, metadata: Uint8Array): Promise<void>;
+}
+export declare function createManagedTaskPersistence(artifacts: ArtifactManager, taskId: string): ManagedTaskPersistence;
 export declare function renderSubagentUserPrompt(assignment: string, independentMode: boolean): string;
 export interface YieldItem {
     data?: unknown;

package/dist/types/tool-discovery/tool-index.d.ts

@@ -36,6 +36,8 @@ export interface DiscoverableToolSearchResult {
     score: number;
 }
 export declare function isMCPToolName(name: string): boolean;
+/** Select persisted built-in discoveries that remain eligible in the current registry, allowlist, and baseline policy. */
+export declare function selectRestorableDiscoveredBuiltinToolNames(toolNames: Iterable<string>, toolRegistry: ReadonlyMap<string, AgentTool>, allowedNames?: ReadonlySet<string>, excludedNames?: ReadonlySet<string>): string[];
 export declare function isMCPBridgeTool(tool: {
     name: string;
     mcpServerName?: unknown;