@gajae-code/coding-agent 0.11.6 → 0.11.8

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

@@ -0,0 +1,88 @@
+/**
+ * Public DTO contract for Q26 `turn.prompt_status` and the `clientRef`
+ * correlation field on `turn.prompt`.
+ *
+ * Semantics:
+ * - `turn.prompt` remains ordered and non-idempotent. An envelope
+ *   `idempotencyKey` is ignored for replay/conflict purposes on ordered
+ *   operations (no replay cache, no `idempotency_conflict`).
+ * - `clientRef` is a caller-chosen correlation key (trimmed, non-empty,
+ *   1..PROMPT_CLIENT_REF_MAX_LENGTH chars; one fresh value per logical prompt)
+ *   mapped to the generated commandId/turnId at preflight acceptance so a
+ *   caller can reconcile after a lost acknowledgement frame.
+ * - The clientRef index is scoped to one live session runtime: identical refs
+ *   may coexist in different sessions, lookups never cross sessions, a ref
+ *   conflicts only while its record is retained (`client_ref_conflict`), and
+ *   after terminal TTL/capacity eviction a ref may be admitted again with the
+ *   prior outcome unknown — callers MUST NOT reuse a clientRef as a retry
+ *   mechanism and MUST treat `unknown` as uncertainty, not proof of
+ *   non-execution.
+ * - The durability floor is the live session process: after restart or
+ *   retained-record eviction, a lookup honestly reports `unknown`.
+ * - Q26 tracks prompts accepted through the SDK control surface (which always
+ *   carries a requesting connection); submissions without a delivery owner are
+ *   outside the reconciliation contract and hold no reservation.
+ */
+export declare const PROMPT_CLIENT_REF_MAX_LENGTH = 128;
+export interface TurnPromptImageInput {
+    data: string;
+    mimeType?: string;
+}
+/** Public input contract for ordered `turn.prompt`. */
+export interface TurnPromptInput {
+    text: string;
+    images?: TurnPromptImageInput[];
+    clientRef?: string;
+}
+/** Terminal outcome is preserved exactly; active records never age into terminal. */
+export type PromptReconciliationStatus = "accepted" | "in_flight" | "terminal_ok" | "failed";
+/** Exactly one selector per lookup. */
+export type TurnPromptStatusSelector = {
+    clientRef: string;
+} | {
+    commandId: string;
+    turnId: string;
+};
+interface TurnPromptReconciliationIdentity {
+    commandId: string;
+    turnId: string;
+    clientRef?: string;
+    /** Epoch milliseconds of preflight acceptance. */
+    acceptedAt: number;
+}
+export interface TurnPromptReconciliationAccepted extends TurnPromptReconciliationIdentity {
+    status: "accepted";
+}
+export interface TurnPromptReconciliationInFlight extends TurnPromptReconciliationIdentity {
+    status: "in_flight";
+    /** Epoch milliseconds of the agent_start transition. */
+    startedAt: number;
+}
+export interface TurnPromptReconciliationTerminalOk extends TurnPromptReconciliationIdentity {
+    status: "terminal_ok";
+    startedAt?: number;
+    /** Epoch milliseconds of the terminal transition. */
+    terminalAt: number;
+}
+export interface TurnPromptReconciliationFailed extends TurnPromptReconciliationIdentity {
+    status: "failed";
+    startedAt?: number;
+    terminalAt: number;
+    /** Bounded, sanitized failure detail (code safe-token ≤64, message ≤512). */
+    error: {
+        code: string;
+        message: string;
+    };
+}
+export interface TurnPromptReconciliationUnknown {
+    status: "unknown";
+}
+export type TurnPromptReconciliation = TurnPromptReconciliationAccepted | TurnPromptReconciliationInFlight | TurnPromptReconciliationTerminalOk | TurnPromptReconciliationFailed | TurnPromptReconciliationUnknown;
+/** Result of a successful `turn.prompt` preflight acknowledgement. */
+export interface TurnPromptAcceptedResult {
+    commandId: string;
+    turnId: string;
+    accepted: true;
+    clientRef?: string;
+}
+export {};

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

@@ -20,7 +20,7 @@ export type ResolveManagedSessionScopeResult = {
     scope: ManagedSessionScope;
 } | {
     kind: "error";
-    code: "cwd_missing" | "cwd_not_directory" | "identity_unavailable" | "network_unsupported" | "sessions_root_unavailable" | "binding_conflict" | "binding_invalid";
+    code: "cwd_missing" | "cwd_not_directory" | "identity_unavailable" | "network_unsupported" | "sessions_root_unavailable" | "binding_conflict" | "binding_invalid" | "atomic_unavailable" | "durability_not_provable" | "durability_failed" | "invalid_request";
     message: string;
 };
 export interface LogicalSessionCandidate {

package/dist/types/sdk/startup-capability.d.ts

@@ -1,9 +1,12 @@
+import { type ModelProfileErrorCode, type ModelProfileErrorDetails } from "../config/model-profile-contract";
 export type SdkStartupPhase = "registration" | "startup";
 export type SdkStartupReason = "disabled" | "ineligible" | "factory_absent" | "runner_absent" | "pending" | "failed";
 export interface SdkStartupFailure {
     phase: SdkStartupPhase;
     reason: SdkStartupReason;
     message: string;
+    code?: ModelProfileErrorCode;
+    details?: ModelProfileErrorDetails;
 }
 export type SdkStartupResult = {
     status: "started";

package/dist/types/sdk/transport/auth-preface.d.ts

@@ -0,0 +1,9 @@
+import type * as net from "node:net";
+type AuthFailureCode = "auth_missing" | "auth_malformed" | "auth_invalid" | "auth_oversize" | "auth_timeout" | "unsupported_version";
+export declare class AuthPrefaceError extends Error {
+    readonly code: AuthFailureCode;
+    constructor(code: AuthFailureCode);
+}
+/** Consumes the one-shot socket authentication preface and leaves later bytes readable. */
+export declare function authenticatePreface(socket: net.Socket, token: string): Promise<Buffer>;
+export {};

package/dist/types/sdk/transport/index.d.ts

@@ -0,0 +1,12 @@
+export { DEFAULT_PENDING_CEILING_BYTES, MIN_PENDING_CEILING_BYTES, REQUEST_FRAME_BYTES, } from "./relay";
+export { startSocketServe } from "./socket";
+export { startStdioServe } from "./stdio";
+export type ServeOptions = {
+    url: string;
+    token: string;
+    pendingCeilingBytes: number;
+};
+export type ServeHandle = {
+    close(): Promise<void>;
+    readonly done: Promise<void>;
+};

package/dist/types/sdk/transport/relay.d.ts

@@ -0,0 +1,43 @@
+import type { Readable, Writable } from "node:stream";
+export declare const REQUEST_FRAME_BYTES: number;
+export declare const DEFAULT_PENDING_CEILING_BYTES: number;
+export declare const MIN_PENDING_CEILING_BYTES: number;
+export type RelayDirection = "downstream->ws" | "ws->downstream";
+export type TransportError = {
+    type: "transport_error";
+    code: "frame_oversize" | "pending_overflow" | "protocol_error";
+    direction?: RelayDirection;
+};
+export type RelayPair = {
+    close(): Promise<void>;
+    readonly done: Promise<void>;
+};
+export declare class RelayOpenAbortedError extends Error {
+    constructor();
+}
+export type RelayWebSocketEvent = {
+    data?: unknown;
+};
+export type RelayWebSocket = {
+    readonly bufferedAmount: number;
+    readonly readyState: number;
+    close(): void;
+    send(data: string): void;
+    addEventListener(type: string, listener: (event: RelayWebSocketEvent) => void, options?: {
+        once?: boolean;
+    }): void;
+    removeEventListener(type: string, listener: (event: RelayWebSocketEvent) => void): void;
+};
+export type RelayOptions = {
+    url: string;
+    token: string;
+    pendingCeilingBytes: number;
+    downstream: Readable;
+    downstreamSink: Writable;
+    initialDownstreamBytes?: Buffer;
+    onTransportError: (error: TransportError) => void;
+    webSocketFactory?: (url: string) => RelayWebSocket;
+    signal?: AbortSignal;
+};
+/** Starts a dedicated raw-WebSocket relay for exactly one downstream stream. */
+export declare function startRelayPair(options: RelayOptions): Promise<RelayPair>;

package/dist/types/sdk/transport/serve-cli.d.ts

@@ -0,0 +1,4 @@
+/** Resolves the pending ceiling with flag > env > default precedence; exported for tests. */
+export declare function resolveServePendingCeiling(flagValue: string | undefined, envValue: string | undefined): number;
+/** Attaches a stdio or Unix-socket relay to one live SDK session endpoint. */
+export declare function runSdkServe(argv: string[]): Promise<void>;

package/dist/types/sdk/transport/socket.d.ts

@@ -0,0 +1,7 @@
+import type { ServeHandle, ServeOptions } from "./index";
+import type { RelayOptions } from "./relay";
+/** Serves authenticated SDK JSONL clients over a private Unix-domain socket. */
+export declare function startSocketServe(options: ServeOptions & {
+    socketPath: string;
+    webSocketFactory?: RelayOptions["webSocketFactory"];
+}): Promise<ServeHandle>;

package/dist/types/sdk/transport/stdio.d.ts

@@ -0,0 +1,3 @@
+import type { ServeHandle, ServeOptions } from "./index";
+/** Serves one parent-owned JSONL connection over the process standard streams. */
+export declare function startStdioServe(options: ServeOptions): Promise<ServeHandle>;

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

@@ -15,6 +15,7 @@
 import { type Agent, type AgentContext, type AgentEvent, type AgentLoopConfig, type AgentMessage, type AgentState, type AgentTool, type MidRunMaintenanceOutcome, type StablePrefixSnapshot, ThinkingLevel } from "@gajae-code/agent-core";
 import { type CompactionResult, type EmergencyCompactionSample } from "@gajae-code/agent-core/compaction";
 import type { AssistantMessage, Effort, ImageContent, Message, MessageAttribution, Model, ProviderSessionState, ServiceTier, SimpleStreamOptions, TextContent, ToolCall, ToolChoice, Usage, UsageReport } from "@gajae-code/ai";
+import { type BtwTextExchange } from "./btw-contract";
 export interface ForkContextSeedMetadata {
     sourceSessionId: string;
     parentMessageCount: number;
@@ -392,8 +393,29 @@ interface EphemeralTurnBaseArgs {
     onTextDelta?: (delta: string) => void;
     signal?: AbortSignal;
 }
-export type EphemeralTurnArgs = (EphemeralTurnBaseArgs & {
+export interface BtwRoleTextMessage {
+    role: "user" | "assistant";
+    text: string;
+}
+export interface BtwConversationScope {
+    model: Model;
+    systemPrompt: string[];
+    messages: BtwRoleTextMessage[];
+    thinkingLevel: ThinkingLevel;
+    hideThinkingSummary: boolean;
+    serviceTier: ServiceTier | undefined;
+    credentialSessionId: string;
+    providerAffinitySessionId: string;
+    sideSessionId: string;
+}
+export interface BtwTurnCapture {
+    question: string;
+    scope: BtwConversationScope | undefined;
+}
+export type EphemeralTurnArgs = (Omit<EphemeralTurnBaseArgs, "promptText"> & {
     purpose: "btw";
+    turn: BtwTurnCapture;
+    contextExchanges?: readonly BtwTextExchange[];
 }) | (EphemeralTurnBaseArgs & {
     purpose?: "background";
     /** Internal caller-supplied, non-persistent context such as the IRC roster. */
@@ -520,6 +542,8 @@ export declare class AgentSession {
      *  recorded or the mode-state file is missing/unreadable; callers should
      *  treat undefined as a non-terminal phase (refuses to chain). */
     getActiveSkillPhase(): string | undefined;
+    /** Provider-facing ask metadata must expose only the active deep-interview phase. */
+    getDeepInterviewAskStage(): "topology" | "post-topology" | undefined;
     /** Peek the in-flight directive's invocation handler for use by the resolve tool. */
     peekQueueInvoker(): ((input: unknown) => Promise<unknown> | unknown) | undefined;
     peekStandingResolveHandler(): ((input: unknown) => Promise<unknown> | unknown) | undefined;
@@ -1271,11 +1295,12 @@ export declare class AgentSession {
         timestamp?: number;
     }): void;
     emitSubagentSteerRelayObservation(record: CustomMessage): void;
+    createBtwConversationScope(instruction: string): BtwConversationScope;
     /**
-     * Run a single ephemeral side-channel turn against this session's current
-     * model + system prompt + history. No tools are used and session history is
-     * not modified. Background turns retain the IRC/session behavior used by
-     * autoreplies; `/btw` turns use an isolated committed-context policy.
+     * Run a single ephemeral side-channel turn without modifying session history.
+     * Background turns retain IRC/session behavior. `/btw` turns require a
+     * pre-frozen, visible-text-only scope and bypass extension context transforms,
+     * provider observability hooks, and session persistence surfaces.
      */
     runEphemeralTurn(args: EphemeralTurnArgs): Promise<EphemeralTurnResult>;
     /**

package/dist/types/session/btw-contract.d.ts

@@ -0,0 +1,16 @@
+export declare const BTW_MAX_CONTEXT_TURNS = 12;
+export declare const BTW_MAX_CONTEXT_UTF8_BYTES: number;
+export declare const BTW_MAX_QUESTION_UTF8_BYTES: number;
+export declare const BTW_MAX_ANSWER_UTF8_BYTES: number;
+export declare const BTW_MAX_ERROR_UTF8_BYTES: number;
+export declare const BTW_STREAM_IDLE_TIMEOUT_MS = 30000;
+export declare const BTW_STREAM_TOTAL_TIMEOUT_MS = 120000;
+export interface BtwTextExchange {
+    question: string;
+    answer: string;
+}
+export declare function utf8ByteLength(text: string): number;
+export declare function truncateUtf8(text: string, maxBytes: number): string;
+export declare function sanitizeBtwError(text: string): string;
+export declare function exchangeUtf8Bytes(exchange: BtwTextExchange): number;
+export declare function boundBtwExchanges(exchanges: readonly BtwTextExchange[]): BtwTextExchange[];

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

@@ -1,5 +1,6 @@
 import * as native from "@gajae-code/natives";
 import type { ResumeSessionIdentity } from "../session-manager";
+import { type ManagedDirectoryRoot, type ManagedSessionSecurityPolicy } from "./managed-session-storage";
 export declare const MANAGED_SESSION_LAYOUT_VERSION: 2;
 export declare const MANAGED_SESSION_IDENTITY_VERSION: 1;
 export declare const MANAGED_SESSION_BINDING_FILE = ".gjc-managed-session-scope.v2.json";
@@ -15,14 +16,24 @@ export interface ManagedScope {
     directoryPath: string;
     platform: "posix" | "win32";
 }
+/**
+ * Opaque managed writer authority captured by a trusted destination. The open
+ * transaction must use this authority rather than reacquiring its root from a
+ * pathname after resume inspection.
+ */
+export interface ManagedCandidateWriteAuthority {
+    readonly rootAuthority: ManagedDirectoryRoot;
+    readonly retainedAuthority?: native.RecoveryFsRoot;
+    readonly retainedDirectory?: string;
+}
 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 declare function managedRootForScope(scope: ManagedScope): 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 ManagedScopeErrorCode = "cwd_missing" | "cwd_not_directory" | "identity_unavailable" | "network_unsupported" | "sessions_root_unavailable" | "binding_conflict" | "binding_invalid" | "atomic_unavailable" | "invalid_request" | "durability_failed" | "durability_not_provable";
 export type ManagedScopeResolution = {
     kind: "resolved";
     scope: ManagedScope;
@@ -30,6 +41,10 @@ export type ManagedScopeResolution = {
     kind: "error";
     code: ManagedScopeErrorCode;
     message: string;
+    cause?: {
+        readonly classification: string;
+        readonly diagnostic?: string;
+    };
 };
 export interface ManagedCandidate {
     sessionId: string;
@@ -52,7 +67,7 @@ export type ManagedCandidateListing = {
     code: "scan_failed" | "unsafe_root" | "invalid_candidate";
     message: string;
 };
-export type ManagedOpenFailure = "migration_busy" | "binding_conflict" | "binding_invalid" | "destination_conflict" | "source_changed" | "unsafe_artifacts" | "durability_failed" | "migration_retired" | "legacy_migration_disabled" | "managed_storage_unsupported";
+export type ManagedOpenFailure = "migration_busy" | "binding_conflict" | "binding_invalid" | "destination_conflict" | "source_changed" | "unsafe_artifacts" | "durability_failed" | "atomic_unavailable" | "invalid_request" | "durability_not_provable" | "migration_retired" | "legacy_migration_disabled" | "managed_storage_unsupported";
 export type ManagedOpenCandidateResult = {
     kind: "opened";
     path: string;
@@ -69,6 +84,11 @@ export type ManagedDeleteCandidateResult = {
 } | {
     kind: "already_deleted";
     tombstonePath: string;
+} | {
+    kind: "cleanup_pending";
+    tombstonePath: string;
+    phase: "artifacts" | "transcript";
+    message: string;
 } | {
     kind: "error";
     code: ManagedOpenFailure;
@@ -86,24 +106,27 @@ export declare const computeManagedScopeDigest: typeof scopeDigest;
  * attacker-plantable component below the root.
  */
 export declare function canonicalizeTrustedPath(target: string): string;
-export declare function resolveManagedScope(input: {
+interface ManagedScopeInput {
     cwd: string;
     agentDir: string;
     sessionsRoot: string;
-}): ManagedScopeResolution;
-export declare function ensureManagedScope(scope: ManagedScope): Promise<ManagedScopeResolution>;
+}
+export declare function resolveManagedScope(input: ManagedScopeInput): ManagedScopeResolution;
+/** Resolve a scope for a synchronous write without mutating an existing ACL mismatch. */
+export declare function resolveManagedScopeForWrite(input: ManagedScopeInput): ManagedScopeResolution;
+export declare function ensureManagedScope(scope: ManagedScope, policy?: ManagedSessionSecurityPolicy): Promise<ManagedScopeResolution>;
 /** Synchronously create and validate the v2 binding before a default session writer exists. */
-export declare function prepareManagedSessionScopeForWriteSync(scope: ManagedScope): ManagedScopeResolution;
+export declare function prepareManagedSessionScopeForWriteSync(scope: ManagedScope, policy?: ManagedSessionSecurityPolicy, authority?: ManagedCandidateWriteAuthority): ManagedScopeResolution;
 export declare function listManagedCandidates(scope: ManagedScope): ManagedCandidateListing;
 /** Resume tombstoned cleanup under its original operation lease without restoring retired candidates. */
 export declare function reconcileManagedTombstones(scope: ManagedScope): Promise<void>;
 /** Create the v2 binding and private write protocol directories before managed writes. */
-export declare function prepareManagedSessionScopeForWrite(scope: ManagedScope): Promise<ManagedScopeResolution>;
+export declare function prepareManagedSessionScopeForWrite(scope: ManagedScope, policy?: ManagedSessionSecurityPolicy, authority?: ManagedCandidateWriteAuthority, expectedCandidate?: ManagedCandidate, expectedIdentity?: ResumeSessionIdentity): Promise<ManagedScopeResolution>;
 /**
  * Open a validated candidate for mutation. Legacy transcripts are copied exactly once
  * into v2 and retained at their original location; no transcript data is merged.
  */
-export declare function openManagedCandidateForWrite(scope: ManagedScope, candidate: ManagedCandidate, migrationPolicy?: ManagedMigrationPolicy): Promise<ManagedOpenCandidateResult>;
+export declare function openManagedCandidateForWrite(scope: ManagedScope, candidate: ManagedCandidate, expectedIdentityOrMigrationPolicy?: ResumeSessionIdentity | ManagedMigrationPolicy, migrationPolicy?: ManagedMigrationPolicy, authority?: ManagedCandidateWriteAuthority): Promise<ManagedOpenCandidateResult>;
 /** Tombstone a verified managed candidate before exact-identity deletion. */
 export declare function deleteManagedSessionCandidate(scope: ManagedScope, candidate: ManagedCandidate): Promise<ManagedDeleteCandidateResult>;
 export {};

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

@@ -1,9 +1,18 @@
 import { type NativeDirectoryTreeSnapshot, type NativeOwnerOnlySecurityResult, type RecoveryFsRoot } from "@gajae-code/natives";
+import { type NativePublishOutcome } from "./native-publish-outcome";
 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;
 export declare const MANAGED_ARTIFACT_MAX_TOTAL_BYTES: number;
-export type ManagedStorageFailure = "migration_busy" | "binding_conflict" | "binding_invalid" | "destination_conflict" | "source_changed" | "unsafe_artifacts" | "durability_failed" | "migration_retired" | "managed_storage_unsupported";
+export declare class ManagedPublishError extends Error {
+    readonly classification: "destination_conflict" | "atomic_unavailable" | "invalid_request" | "durability_not_provable" | "identity_mismatch" | "io_error" | "durability_failed";
+    readonly diagnostic: string;
+    constructor(classification: ManagedPublishError["classification"], outcome: NativePublishOutcome);
+}
+/** Cleanup is safe only when the native move reports that it did not commit. */
+export declare function mayCleanManagedTreeStaging(error: unknown): boolean;
+export type ManagedSessionSecurityPolicy = "default" | "windows-existing-verify-first";
+export type ManagedStorageFailure = "migration_busy" | "binding_conflict" | "binding_invalid" | "destination_conflict" | "source_changed" | "unsafe_artifacts" | "durability_failed" | "atomic_unavailable" | "durability_not_provable" | "migration_retired" | "managed_storage_unsupported";
 export interface ManagedStorageLock {
     path: string;
     attemptId: string;
@@ -28,6 +37,13 @@ export interface ManagedDirectoryRoot {
     readonly dev: bigint;
     readonly ino: bigint;
 }
+/**
+ * Establish the first managed directory beneath a potentially shared ancestor.
+ * The ancestor is used only to create the managed chain; every component from
+ * `configuredRoot` downward is independently type, symlink, owner, mode, and
+ * ACL checked. This deliberately does not impose owner-only policy on `/tmp`.
+ */
+export declare function prepareManagedDirectoryRoot(configuredRoot: string, policy?: ManagedSessionSecurityPolicy): ManagedDirectoryRoot;
 export declare function managedDirectoryRoot(configuredRoot: string): ManagedDirectoryRoot;
 export declare function retainManagedDirectoryAuthority(root: ManagedDirectoryRoot, directory: string, expected?: {
     dev: bigint;
@@ -40,10 +56,11 @@ export declare class ManagedSessionDescendantStore {
     constructor(root: ManagedDirectoryRoot, baseDir: string, retained?: {
         authority: RecoveryFsRoot;
         authorityBaseDir: string;
-    });
+    }, policy?: ManagedSessionSecurityPolicy);
     get dir(): string;
     get rootAuthority(): ManagedDirectoryRoot;
     get subtreeRootAuthority(): ManagedDirectoryRoot;
+    get securityPolicy(): ManagedSessionSecurityPolicy;
     deriveSubtree(relativePath: string): ManagedSessionDescendantStore;
     retainAuthority(): RecoveryFsRoot | undefined;
     assertBound(): void;
@@ -66,27 +83,27 @@ export declare class ManagedSessionDescendantStore {
     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;
+    moveTreeNoReplace(sourceRelativePath: string, destinationRelativePath: string, expected: NativeDirectoryTreeSnapshot): NativeDirectoryTreeSnapshot;
     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, root?: ManagedDirectoryRoot): void;
+export declare function ensureManagedDirectory(pathname: string, root?: ManagedDirectoryRoot, policy?: ManagedSessionSecurityPolicy): 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, root?: ManagedDirectoryRoot): Promise<void>;
-export declare function publishManagedFileNoReplaceSync(destination: string, bytes: Uint8Array, root?: ManagedDirectoryRoot): void;
+export declare function publishManagedFileNoReplace(destination: string, bytes: Uint8Array, assertOwned?: () => void, root?: ManagedDirectoryRoot, policy?: ManagedSessionSecurityPolicy): Promise<void>;
+export declare function publishManagedFileNoReplaceSync(destination: string, bytes: Uint8Array, root?: ManagedDirectoryRoot, policy?: ManagedSessionSecurityPolicy): 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>;
+export declare function replaceManagedFileSync(destination: string, bytes: Uint8Array, root: ManagedDirectoryRoot, policy?: ManagedSessionSecurityPolicy): void;
+export declare function replaceManagedFile(destination: string, bytes: Uint8Array, root: ManagedDirectoryRoot, policy?: ManagedSessionSecurityPolicy): Promise<void>;
 /** Copy the exact bytes captured from one no-follow source descriptor. */
-export declare function copyManagedFileNoReplace(source: string, destination: string, snapshot?: ManagedFileSnapshot, root?: ManagedDirectoryRoot): Promise<void>;
+export declare function copyManagedFileNoReplace(source: string, destination: string, snapshot?: ManagedFileSnapshot, root?: ManagedDirectoryRoot, policy?: ManagedSessionSecurityPolicy): Promise<void>;
 /** Acquire a lease lock with bounded wait, heartbeats, conservative stale reclaim, and fencing. */
-export declare function acquireManagedLock(locksDirectory: string, name: string, root?: ManagedDirectoryRoot): Promise<ManagedStorageLock>;
+export declare function acquireManagedLock(locksDirectory: string, name: string, root?: ManagedDirectoryRoot, policy?: ManagedSessionSecurityPolicy): 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. */

package/dist/types/session/internal/native-publish-outcome.d.ts

@@ -0,0 +1,48 @@
+export type NativePublishMutationState = "not_committed" | "committed" | "unknown";
+export type NativePublishDurabilityState = "not_attempted" | "proven" | "not_provable";
+export type NativePublishReason = "none" | "destination_exists" | "atomic_unavailable" | "cross_device" | "permission_denied" | "io_failure" | "interrupted" | "invalid_request" | "identity_violation" | "durability_not_provable" | "unknown";
+export type NativePublishOperation = "direct_rename" | "retained_file" | "retained_tree";
+export type NativePublishPrimitive = "renameat2_noreplace" | "renameatx_np_excl" | "windows_rename_noreplace" | "unsupported" | "unknown";
+export type NativePublishPhase = "preflight" | "file_sync" | "rename" | "source_parent_sync" | "destination_parent_sync" | "terminal_identity" | "complete" | "unknown";
+type SyncFailure = {
+    phase: Exclude<NativePublishPhase, "preflight" | "file_sync" | "rename" | "complete" | "unknown">;
+    parentRole: "source" | "destination" | "shared" | "staged_file";
+    osCode?: number;
+    kind: "unsupported" | "io" | "permission" | "other";
+};
+type PublishDiagnostic = {
+    schemaVersion: 1;
+    collectionState: "complete" | "partial" | "unavailable";
+    osCode?: number;
+    syncFailures?: readonly SyncFailure[];
+};
+export type NativePublishIdentity = {
+    readonly dev: string;
+    readonly ino: string;
+    readonly size: string;
+    readonly mtimeNs: string;
+    readonly ctimeNs: string;
+    readonly sha256?: string;
+};
+export type NativePublishOutcome = {
+    readonly ok: boolean;
+    readonly code?: string;
+    readonly identity?: NativePublishIdentity;
+    readonly mutationState: NativePublishMutationState;
+    readonly durabilityState: NativePublishDurabilityState;
+    readonly reason: NativePublishReason;
+    readonly primitive: NativePublishPrimitive;
+    readonly phase: NativePublishPhase;
+    readonly diagnostic: PublishDiagnostic;
+};
+/**
+ * Treat incompatible native results as an unknown mutation; never infer safety from legacy fields.
+ * Retained descriptor operations have a stricter contract than direct rename: a reported success
+ * includes the terminal identity and all required durability evidence.
+ */
+export declare function classifyNativePublishOutcome(value: unknown, operation?: NativePublishOperation): NativePublishOutcome;
+/** Only a fully validated pre-mutation result permits exact cleanup of current staging. */
+export declare function mayCleanCurrentStaging(outcome: NativePublishOutcome): boolean;
+/** Stable, bounded text for startup errors. Native paths and messages are intentionally excluded. */
+export declare function formatNativePublishDiagnostic(outcome: NativePublishOutcome): string;
+export {};

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

@@ -553,7 +553,7 @@ export interface ResolvedSessionMatch {
     session: SessionInfo;
     scope: "local" | "global";
 }
-export declare function resolveResumableSession(sessionArg: string, cwd: string, sessionDir?: string, storage?: SessionStorage): Promise<ResolvedSessionMatch | undefined>;
+export declare function resolveResumableSession(sessionArg: string, cwd: string, sessionDir?: string, storage?: SessionStorage, managedAgentDir?: string): Promise<ResolvedSessionMatch | undefined>;
 interface SessionManagerStateSnapshot {
     sessionId: string;
     sessionName: string | undefined;
@@ -649,6 +649,8 @@ export declare class SessionManager {
     /** Get usage statistics across all assistant messages in the session. */
     getUsageStatistics(): UsageStatistics;
     getSessionDir(): string;
+    /** Lists picker candidates within this manager's captured destination authority. */
+    listForResumePickerReadOnly(): Promise<SessionInfo[]>;
     getSessionId(): string;
     getSessionFile(): string | undefined;
     /**
@@ -901,8 +903,12 @@ export declare class SessionManager {
     static managedDestination(cwd: string, agentDir?: string, storage?: SessionStorage): SessionDestination;
     static explicitDestination(directory: string): SessionDestination;
     static create(cwd: string, destinationInput?: SessionDestinationInput, storage?: SessionStorage): SessionManager;
+    /** Prepare a selected candidate using this manager's captured managed destination authority. */
+    prepareManagedCandidateForWrite(filePath: string, migrationPolicy: SessionDirectoryMigrationPolicy, expectedIdentity?: ResumeSessionIdentity): Promise<string>;
+    /** Prepare a managed candidate and retain its exact post-preparation identity for the next adoption. */
+    prepareManagedCandidateForStrictAdoption(filePath: string, migrationPolicy: SessionDirectoryMigrationPolicy, expectedIdentity: ResumeSessionIdentity): Promise<string>;
     /** Resolve a default-managed candidate through binding validation and copy-retain migration before mutation. */
-    static prepareManagedCandidateForWrite(filePath: string, migrationPolicy: SessionDirectoryMigrationPolicy): Promise<string>;
+    static prepareManagedCandidateForWrite(filePath: string, migrationPolicy: SessionDirectoryMigrationPolicy, destination: SessionDestination, expectedIdentity?: ResumeSessionIdentity): 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.
@@ -916,7 +922,15 @@ export declare class 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.
+     * List default-managed sessions for the resume picker without recovery or other
+     * maintenance writes. This is the only picker inventory that includes legacy
+     * sibling directories.
+     */
+    static listManagedForResumePickerReadOnly(cwd: string, managedAgentDir?: string, storage?: SessionStorage): Promise<SessionInfo[]>;
+    /**
+     * List sessions from an explicitly supplied picker directory without recovery
+     * or other maintenance writes. Unlike managed inventory, this never scans
+     * legacy sibling directories.
      */
     static listForResumePickerReadOnly(cwd: string, sessionDir?: string, storage?: SessionStorage): Promise<SessionInfo[]>;
     /** Tombstone and exact-delete a default-managed candidate. */
@@ -966,7 +980,13 @@ export declare class SessionManager {
     /**
      * List all sessions across all project directories.
      */
-    static listAll(storage?: SessionStorage): Promise<SessionInfo[]>;
+    static listAll(storage?: SessionStorage, managedAgentDir?: string): Promise<SessionInfo[]>;
+    /**
+     * Strict inventory bound to this manager's captured session authority. Managed
+     * managers include authorized legacy and current candidates; explicit managers
+     * authorize only their exact directory.
+     */
+    inventorySessionsStrict(): StrictInventoryResult;
     /**
      * Strict raw scoped inventory for ACP authorization. Enumerates the scoped
      * session directory without suppressing any root/scan/lstat/read/parse/stat/
@@ -977,6 +997,7 @@ export declare class SessionManager {
     static inventorySessionsStrict(cwd: string, options?: {
         sessionDir?: string;
         storage?: SessionStorage;
+        destination?: SessionDestination;
     }): StrictInventoryResult;
     /**
      * Propagate the storage-layer verified hard delete bound to exact identity evidence.

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

@@ -184,6 +184,18 @@ export interface VerifiedSessionDeleteTarget {
     detachedArtifactsPath?: string;
     /** Identity-bound quarantine path retained when transcript unlink deferred cleanup. */
     detachedTranscriptPath?: string;
+    /** Native-retained publisher successor observed during transcript cleanup. */
+    retainedTranscriptSuccessorPath?: string;
+    /** Native-retained exchange placeholder observed during transcript cleanup. */
+    retainedTranscriptPlaceholderPath?: string;
+    /** Native-retained transcript entry whose identity could not be verified. */
+    retainedTranscriptUnknownPath?: string;
+    /** Native-retained publisher successor observed during cleanup. */
+    retainedArtifactsSuccessorPath?: string;
+    /** Native-retained exchange placeholder observed during cleanup. */
+    retainedArtifactsPlaceholderPath?: string;
+    /** Native-retained entry whose identity could not be verified. */
+    retainedArtifactsUnknownPath?: string;
     /** Caller-published, no-replace quarantine pathname for the next artifact detach. */
     plannedArtifactsPath?: string;
     /** Caller-published, no-replace quarantine pathname for the next transcript detach. */
@@ -215,6 +227,9 @@ export type VerifiedSessionDeleteResult = {
     artifactsTree: NativeDirectoryTreeSnapshot;
     /** Transcript identity (unchanged) for retry binding. */
     transcriptIdentity: SessionStorageFileIdentity;
+    retainedSuccessorPath?: string;
+    retainedPlaceholderPath?: string;
+    retainedUnknownPath?: string;
 } | {
     kind: "cleanup_pending";
     phase: "transcript";
@@ -223,6 +238,9 @@ export type VerifiedSessionDeleteResult = {
     transcriptIdentity: SessionStorageFileIdentity;
     /** Optional identity-bound transcript quarantine path for restart cleanup. */
     detachedTranscriptPath?: string;
+    retainedSuccessorPath?: string;
+    retainedPlaceholderPath?: string;
+    retainedUnknownPath?: string;
 };
 type NativeDirectoryTreeEntry = {
     relativePath: string;