@gajae-code/coding-agent 0.11.4 → 0.11.6

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
@@ -543,6 +595,16 @@ export declare class SessionManager {
     newSession(options?: NewSessionOptions): Promise<string | undefined>;
     /** Tombstone and exact-delete managed transcripts, detaching the active transcript first. */
     dropSession(sessionPath: string): Promise<void>;
+    /**
+     * Exact-delete a session transcript and its artifacts by path WITHOUT requiring
+     * 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.
+     */
+    discardUncommittedSession(sessionPath: string): Promise<void>;
     /**
      * Fork the current session, creating a new session file with the same entries.
      * Returns both the old and new session file paths for artifact copying.
@@ -552,6 +614,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 +655,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 +782,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 +897,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 +928,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/session/yield-queue.d.ts

@@ -20,5 +20,13 @@ export declare class YieldQueue {
     has(kind?: string): boolean;
     flush(mode: YieldFlushMode): Promise<void>;
     clear(): void;
+    /** Drop only the queued entries of a single kind, leaving other kinds intact. */
+    clearKind(kind: string): void;
+    /**
+     * Re-schedule an idle flush if work remains and the session is idle. Used after
+     * a transition (e.g. handoff) releases a delivery fence so entries queued while
+     * fenced are not stranded until an unrelated enqueue or agent yield.
+     */
+    rearmIdle(): void;
 }
 export {};

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;

package/dist/types/tools/ask.d.ts

@@ -36,9 +36,25 @@ export declare const askSchema: z.ZodObject<{
             component: z.ZodString;
             dimension: z.ZodString;
             ambiguity: z.ZodNumber;
+            confused_terms: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            references: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                reference_id: z.ZodString;
+                label: z.ZodString;
+                origin: z.ZodString;
+                url: z.ZodOptional<z.ZodString>;
+                excerpt: z.ZodOptional<z.ZodString>;
+            }, z.core.$strict>>>;
         }, z.core.$strict>, z.ZodObject<{
             round_id: z.ZodOptional<z.ZodString>;
             ambiguity: z.ZodNumber;
+            confused_terms: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            references: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                reference_id: z.ZodString;
+                label: z.ZodString;
+                origin: z.ZodString;
+                url: z.ZodOptional<z.ZodString>;
+                excerpt: z.ZodOptional<z.ZodString>;
+            }, z.core.$strict>>>;
             round: z.ZodLiteral<0>;
             component: z.ZodLiteral<"review-topology">;
             dimension: z.ZodLiteral<"topology">;
@@ -60,6 +76,14 @@ export declare const askSchema: z.ZodObject<{
             component: z.ZodString;
             dimension: z.ZodString;
             ambiguity: z.ZodNumber;
+            confused_terms: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            references: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                reference_id: z.ZodString;
+                label: z.ZodString;
+                origin: z.ZodString;
+                url: z.ZodOptional<z.ZodString>;
+                excerpt: z.ZodOptional<z.ZodString>;
+            }, z.core.$strict>>>;
             round: z.ZodNumber;
             intent_review: z.ZodObject<{
                 observed_items: z.ZodArray<z.ZodObject<{
@@ -169,9 +193,25 @@ export declare class AskTool implements AgentTool<typeof askSchema, AskToolDetai
                 component: z.ZodString;
                 dimension: z.ZodString;
                 ambiguity: z.ZodNumber;
+                confused_terms: z.ZodOptional<z.ZodArray<z.ZodString>>;
+                references: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                    reference_id: z.ZodString;
+                    label: z.ZodString;
+                    origin: z.ZodString;
+                    url: z.ZodOptional<z.ZodString>;
+                    excerpt: z.ZodOptional<z.ZodString>;
+                }, z.core.$strict>>>;
             }, z.core.$strict>, z.ZodObject<{
                 round_id: z.ZodOptional<z.ZodString>;
                 ambiguity: z.ZodNumber;
+                confused_terms: z.ZodOptional<z.ZodArray<z.ZodString>>;
+                references: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                    reference_id: z.ZodString;
+                    label: z.ZodString;
+                    origin: z.ZodString;
+                    url: z.ZodOptional<z.ZodString>;
+                    excerpt: z.ZodOptional<z.ZodString>;
+                }, z.core.$strict>>>;
                 round: z.ZodLiteral<0>;
                 component: z.ZodLiteral<"review-topology">;
                 dimension: z.ZodLiteral<"topology">;
@@ -193,6 +233,14 @@ export declare class AskTool implements AgentTool<typeof askSchema, AskToolDetai
                 component: z.ZodString;
                 dimension: z.ZodString;
                 ambiguity: z.ZodNumber;
+                confused_terms: z.ZodOptional<z.ZodArray<z.ZodString>>;
+                references: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                    reference_id: z.ZodString;
+                    label: z.ZodString;
+                    origin: z.ZodString;
+                    url: z.ZodOptional<z.ZodString>;
+                    excerpt: z.ZodOptional<z.ZodString>;
+                }, z.core.$strict>>>;
                 round: z.ZodNumber;
                 intent_review: z.ZodObject<{
                     observed_items: z.ZodArray<z.ZodObject<{

package/dist/types/tools/bash-skill-urls.d.ts

@@ -24,8 +24,8 @@ export declare function resolveSkillUrlToPath(url: string, skills: readonly Skil
  */
 export declare function expandSkillUrls(command: string, skills: readonly Skill[]): string;
 /**
- * Expand supported internal URLs in a bash command string to shell-escaped absolute paths.
- * Supported schemes: skill://, agent://, artifact://, memory://, rule://, local://
+ * Expand filesystem-safe internal URLs in a bash command string. `agent://` and
+ * `artifact://` remain internal-reader-only and are rejected before resolution.
  */
 export declare function expandInternalUrls(command: string, options: InternalUrlExpansionOptions): Promise<string>;
 export {};

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

@@ -139,6 +139,8 @@ export interface ToolSession {
     cwd: string;
     /** Whether UI is available */
     hasUI: boolean;
+    /** Whether this session will bind a workflow-gate emitter after tool construction. */
+    workflowGateEligible?: boolean;
     /** Skip Python kernel availability check and warmup */
     skipPythonPreflight?: boolean;
     /** Pre-loaded context files (AGENTS.md, etc) */
@@ -185,6 +187,8 @@ export interface ToolSession {
     requestForegroundBashBackground?: () => boolean;
     /** Get session ID */
     getSessionId?: () => string | null;
+    /** Whether local:// must use external managed scratch instead of artifacts/local. */
+    isManagedSessionDestination?: () => boolean;
     /** Get Hindsight runtime state for this agent session. */
     getHindsightSessionState?: () => HindsightSessionState | undefined;
     /** Agent identity used for IRC routing. Returns the registry id (e.g. "0-Main", "0-AuthLoader"). */

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@gajae-code/coding-agent",
-	"version": "0.11.4",
+	"version": "0.11.6",
 	"description": "Gajae Code CLI with read, bash, edit, write tools and session management",
 	"homepage": "https://gajae-code.com",
 	"author": "Yeachan-Heo and Gajae Code Contributors",
@@ -47,19 +47,19 @@
 		"install:defaults": "bun src/cli.ts setup defaults",
 		"verify:insane-vendor": "bun scripts/verify-insane-vendor.ts",
 		"verify:sdk-canonicalization": "bun scripts/verify-gjc-sdk-canonicalization.ts",
-		"check:sdk-closure": "bun scripts/generate-sdk-operation-inventory.ts --check && bun scripts/generate-sdk-adapter-parity-manifest.ts --check && bun scripts/run-test-manifest.ts test/manifests/sdk-adapter-parity-v1.json && bun scripts/generate-telegram-baseline-manifest.ts --check && bun scripts/run-test-manifest.ts test/manifests/telegram-baseline-v1.json && bun test test/sdk-downgrade-rollback.test.ts test/sdk-downgrade-unknown-version.test.ts && bun scripts/verify-gjc-sdk-canonicalization.ts --self-test && bun scripts/verify-gjc-sdk-canonicalization.ts && bun scripts/verify-gjc-sdk-rename.ts"
+		"check:sdk-closure": "bun ../../scripts/telegram-daemon-generation-guard.ts --validate-current-tree && bun test ../../scripts/telegram-daemon-generation-guard.test.ts && bun scripts/generate-sdk-operation-inventory.ts --check && bun scripts/generate-sdk-adapter-parity-manifest.ts --check && bun scripts/run-test-manifest.ts test/manifests/sdk-adapter-parity-v1.json && bun scripts/generate-telegram-baseline-manifest.ts --check && bun scripts/run-test-manifest.ts test/manifests/telegram-baseline-v1.json && bun test test/sdk-downgrade-rollback.test.ts test/sdk-downgrade-unknown-version.test.ts && bun scripts/verify-gjc-sdk-canonicalization.ts --self-test && bun scripts/verify-gjc-sdk-canonicalization.ts && bun scripts/verify-gjc-sdk-rename.ts"
 	},
 	"dependencies": {
 		"@agentclientprotocol/sdk": "1.2.1",
 		"@babel/parser": "^7.29.3",
 		"@mozilla/readability": "^0.6.0",
-		"@gajae-code/stats": "0.11.4",
-		"@gajae-code/agent-core": "0.11.4",
-		"@gajae-code/ai": "0.11.4",
-		"@gajae-code/bridge-client": "0.11.4",
-		"@gajae-code/natives": "0.11.4",
-		"@gajae-code/tui": "0.11.4",
-		"@gajae-code/utils": "0.11.4",
+		"@gajae-code/stats": "0.11.6",
+		"@gajae-code/agent-core": "0.11.6",
+		"@gajae-code/ai": "0.11.6",
+		"@gajae-code/bridge-client": "0.11.6",
+		"@gajae-code/natives": "0.11.6",
+		"@gajae-code/tui": "0.11.6",
+		"@gajae-code/utils": "0.11.6",
 		"@puppeteer/browsers": "^2.13.0",
 		"@types/turndown": "5.0.6",
 		"@xterm/headless": "^6.0.0",

package/scripts/generate-sdk-operation-inventory.ts

@@ -113,6 +113,8 @@ const LOCKED_EXCLUSIONS: Readonly<Record<string, string>> = {
 	"agent_session:cancelAndSubmit": "interactive queue transaction plumbing, not an independent SDK control seam",
 	"agent_session:applyCompactionPostAppendForTests": "internal accessor/plumbing, not a user-facing control seam",
 	"agent_session:continuePersistedHistory": "internal startup lifecycle plumbing, not a user-facing control seam",
+	"agent_session:promoteRecoveryHydrationAfterOwnershipReadyFence":
+		"internal owner-recovery authority transition after a durable writer fence, never a user-facing SDK operation",
 	"agent_session:setActiveModelProfile": "internal accessor/plumbing, not a user-facing control seam",
 	"agent_session:getActiveModelProfile": "internal accessor/plumbing, not a user-facing control seam",
 	"agent_session:getSessionDefaultModelSelector": "internal accessor/plumbing, not a user-facing control seam",
@@ -256,6 +258,7 @@ const SEAM_TO_SDK: Readonly<Record<string, string>> = {
 	"slash_command:clear": "context.clear",
 	"slash_command:new": "session.new",
 	"slash_command:compact": "compaction.run",
+	"slash_command:handoff": "session.handoff",
 	"slash_command:resume": "session.resume",
 	"slash_command:retry": "retry.last",
 	"slash_command:background": "bash.background",