@sayknow-cli/coding-agent 0.4.6 → 0.5.0

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 "@sayknow-cli/agent-core";
 import { type CompactionResult, type EmergencyCompactionSample } from "@sayknow-cli/agent-core/compaction";
 import type { AssistantMessage, Effort, ImageContent, Message, MessageAttribution, Model, ProviderSessionState, ServiceTier, SimpleStreamOptions, TextContent, ToolCall, ToolChoice, Usage, UsageReport } from "@sayknow-cli/ai";
+import { type BtwTextExchange } from "./btw-contract";
 export interface ForkContextSeedMetadata {
     sourceSessionId: string;
     parentMessageCount: number;
@@ -79,7 +80,8 @@ import type { TtsrManager } from "../export/ttsr";
 import type { LoadedCustomCommand } from "../extensibility/custom-commands";
 import type { CustomTool } from "../extensibility/custom-tools/types";
 import type { ExtensionRunner } from "../extensibility/extensions";
-import type { CompactOptions, ContextUsage } from "../extensibility/extensions/types";
+import type { CompactOptions, ContextUsage, ExtensionTranscriptEntry } from "../extensibility/extensions/types";
+import type { SessionSwitchEvent } from "../extensibility/shared-events";
 import { type Skill, type SkillWarning } from "../extensibility/skills";
 import { type FileSlashCommand } from "../extensibility/slash-commands";
 import { GoalRuntime } from "../goals/runtime";
@@ -91,6 +93,7 @@ import { type AgentRegistry } from "../registry/agent-registry";
 import { MCPManager } from "../runtime-mcp/manager";
 import type { NotificationSessionController } from "../sdk/bus/session-control";
 import { type SecretObfuscator } from "../secrets/obfuscator";
+import { type MemoryGuardClaimsLease } from "../skc-runtime/memory-guard-owner-claims";
 import { type DiscoverableTool, type DiscoverableToolSearchIndex } from "../tool-discovery/tool-index";
 import type { AskAnswerSource, ToolSession } from "../tools";
 import type { CheckpointState } from "../tools/checkpoint";
@@ -100,8 +103,9 @@ import { type DefaultModelSelectionResult } from "./default-model-selection";
 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 { MemoryGuardRestoreResult } from "./memory-guard-checkpoint-participant";
 import { type CustomMessage } from "./messages";
-import type { BranchSummaryEntry, CompactionEntry, NewSessionOptions, RecoveryHydrationContext, RecoveryHydrationPromotionFence, SessionContext, SessionManager, SessionManagerCloseOutcome } from "./session-manager";
+import type { BranchSummaryEntry, CompactionEntry, NewSessionOptions, PreparedNewSession, 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 */
@@ -313,6 +317,24 @@ export interface AgentSessionConfig {
     /** Optional provider-facing cache identity, distinct from logical session identity. */
     providerCacheSessionId?: string;
 }
+export interface AgentSessionMemoryGuardRestoreInput extends Omit<AgentSessionConfig, "sessionManager" | "recoveryHydrationContext"> {
+    staged: Extract<MemoryGuardRestoreResult, {
+        kind: "staged";
+    }>;
+    claimsLease: MemoryGuardClaimsLease;
+    claimsStateDir: string;
+}
+export interface AgentMemoryGuardPromotionFence extends RecoveryHydrationPromotionFence {
+    readonly claimsLease: MemoryGuardClaimsLease;
+}
+export type AgentMemoryGuardRestoreResult = {
+    kind: "staged";
+    session: AgentSession;
+    promotionFence: AgentMemoryGuardPromotionFence;
+} | {
+    kind: "blocked";
+    reason: "transcript-mismatch" | "hydration-context-mismatch" | "claim-mismatch" | "agent-messages-mismatch";
+};
 type MidRunMaintenanceLifecycle = Parameters<NonNullable<AgentLoopConfig["maintainContext"]>>[1];
 /** Options for AgentSession.prompt() */
 export interface PromptOptions {
@@ -335,8 +357,21 @@ export interface PromptOptions {
     /**
      * Invoked after all prompt preflight checks pass and immediately before agent execution begins.
      * Cancellation before this callback rejects the prompt.
+     * Prefer `onPreflightAcceptCommit` for async durable acceptance (#3031/#3032).
      */
     onPreflightAccepted?: () => void;
+    /**
+     * Awaitable durable-accept fence. Called after preflight and before queue mutation
+     * or `#promptAgentWithIdleRetry`. SDK bus installs a closure that fsyncs acceptance.
+     */
+    onPreflightAcceptCommit?: () => void | Promise<void>;
+    /** Skill-only: prepared metadata before the durable fence (path/lineCount/cleanedArgs). */
+    onSkillPrepared?: (meta: {
+        name: string;
+        path: string;
+        lineCount?: number;
+        cleanedArgs?: string;
+    }) => void;
 }
 /** Result from a handoff operation. */
 export interface HandoffResult {
@@ -392,8 +427,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 +576,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;
@@ -653,6 +711,8 @@ export declare class AgentSession {
      * Get a tool by name from the registry.
      */
     getToolByName(name: string): AgentTool | undefined;
+    /** Get a registered tool with the same guards used for model-facing execution. */
+    getToolForExecution(name: string): AgentTool | undefined;
     /**
      * Register a UI/control-plane request handler for a currently foregrounded
      * managed bash execution. This is intentionally narrower than generic
@@ -729,13 +789,16 @@ export declare class AgentSession {
     /** All messages including custom types like BashExecutionMessage */
     get messages(): AgentMessage[];
     get transcriptPromptGeneration(): number;
+    static restoreFromMemoryGuardCheckpoint(input: AgentSessionMemoryGuardRestoreInput): Promise<AgentMemoryGuardRestoreResult>;
     /** 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>;
+    promoteRecoveryHydrationAfterOwnershipReadyFence(fence: AgentMemoryGuardPromotionFence): Promise<void>;
     /** Main startup calls this exactly once, after a strict open returned `kind: "opened"`. */
     continuePersistedHistory(): Promise<void>;
     buildDisplaySessionContext(): SessionContext;
+    /** Build display context from an unpublished successor without changing active session state. @internal */
+    buildPreparedDisplaySessionContext(prepared: PreparedNewSession): SessionContext;
     /** Convert session messages using the same pre-LLM pipeline as the active session. */
     convertMessagesToLlm(messages: AgentMessage[], signal?: AbortSignal): Promise<Message[]>;
     /** Apply session-level stream hooks to a direct side request. */
@@ -759,7 +822,7 @@ export declare class AgentSession {
     /** Live SDK configuration values exposed through the session query surface. */
     getSdkConfigItems(): Record<string, string>;
     setPlanModeState(state: PlanModeState | undefined): void;
-    invokeSkill(name: string, args?: string): Promise<{
+    invokeSkill(name: string, args?: string, options?: Pick<PromptOptions, "onPreflightAccepted" | "onPreflightAcceptCommit" | "onSkillPrepared">): Promise<{
         name: string;
         path: string;
         args?: string;
@@ -767,13 +830,7 @@ export declare class AgentSession {
     }>;
     setSdkPlanMode(on: boolean): Promise<PlanModeState | undefined>;
     operateGoal(op: "create" | "get" | "resume" | "pause" | "complete" | "drop", objective?: string): Promise<unknown>;
-    getTranscript(): Array<{
-        id: string;
-        role: string;
-        textSummary: string;
-        ts: string;
-        body: string;
-    }>;
+    getTranscript(): ExtensionTranscriptEntry[];
     getTranscriptBody(entryId: string): string | undefined;
     getGoalModeState(): GoalModeState | undefined;
     setGoalModeState(state: GoalModeState | undefined): void;
@@ -820,7 +877,7 @@ export declare class AgentSession {
      * @throws Error if no model selected or no API key available (when not streaming)
      */
     prompt(text: string, options?: PromptOptions): Promise<void>;
-    promptCustomMessage<T = unknown>(message: Pick<CustomMessage<T>, "customType" | "content" | "display" | "details" | "attribution">, options?: Pick<PromptOptions, "streamingBehavior" | "toolChoice" | "followUpQueuePolicy">): Promise<void>;
+    promptCustomMessage<T = unknown>(message: Pick<CustomMessage<T>, "customType" | "content" | "display" | "details" | "attribution">, options?: Pick<PromptOptions, "streamingBehavior" | "toolChoice" | "followUpQueuePolicy" | "onPreflightAccepted" | "onPreflightAcceptCommit">): Promise<void>;
     /**
      * Queue a steering message to interrupt the agent mid-run.
      */
@@ -860,6 +917,7 @@ export declare class AgentSession {
     sendUserMessage(content: string | (TextContent | ImageContent)[], options?: {
         deliverAs?: "steer" | "followUp";
         onPreflightAccepted?: () => void;
+        onPreflightAcceptCommit?: () => void | Promise<void>;
     }): Promise<void>;
     /**
      * Clear queued messages and return them.
@@ -962,6 +1020,8 @@ export declare class AgentSession {
     }): Promise<void>;
     setActiveModelProfile(name: string | undefined): void;
     getActiveModelProfile(): string | undefined;
+    /** Activate a complete model profile through a nonvisual session control. */
+    activateModelProfileForControl(profileName: string): Promise<boolean>;
     /** Return the persisted configured fallback selectors for a model role. */
     getConfiguredModelChain(role: string): readonly string[] | undefined;
     /** Persist the configured fallback selectors for a model role. */
@@ -1041,20 +1101,16 @@ export declare class AgentSession {
      * Get all available models with valid API keys.
      */
     getAvailableModels(): Model[];
-    /**
-     * Set thinking level.
-     * Saves the effective metadata-clamped level to the session, and to settings when requested.
-     */
     setThinkingLevel(level: ThinkingLevel | undefined, persist?: boolean): void;
     /**
-     * Set thinking level from a control surface. Global changes are durable or rolled back.
+     * Set thinking level from a control surface. Global changes commit before affecting live state.
      */
     setThinkingLevelForControl(level: ThinkingLevel, persist: boolean): Promise<void>;
     getThinkingScopeForControl(): "session" | "global config";
     getThinkingVisibility(): "visible" | "hidden";
     setThinkingVisibility(visibility: "visible" | "hidden", persist?: boolean): void;
     /**
-     * Set thinking visibility from a control surface. Global changes are durable or rolled back.
+     * Set thinking visibility from a control surface. Global changes commit before affecting live state.
      */
     setThinkingVisibilityForControl(visibility: "visible" | "hidden", persist: boolean): Promise<void>;
     /**
@@ -1271,11 +1327,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>;
     /**
@@ -1291,7 +1348,9 @@ export declare class AgentSession {
      * Listeners are preserved and will continue receiving events.
      * @returns true if switch completed, false if cancelled by hook
      */
-    switchSession(sessionPath: string): Promise<boolean>;
+    switchSession(sessionPath: string, options?: {
+        transition?: SessionSwitchEvent["transition"];
+    }): Promise<boolean>;
     /**
      * Create a branch from a specific entry.
      * Emits before_branch/branch session events to hooks.

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/fallback-chain-controller.d.ts

@@ -47,8 +47,9 @@ export declare class FallbackChainController {
     onAttemptFailure(triggerClass: FallbackTriggerClass, reason: string): FallbackFailureResult;
     advance(): boolean;
     /**
-     * Restore the entry that just advanced when credential rotation permits a retry.
-     * The chain-wide budget and failure history remain charged.
+     * Restore the entry that just advanced for one attempt with a rotated credential.
+     * Each non-terminal entry may be restored once, so credential rotation remains
+     * bounded and cannot consume the attempts reserved for downstream entries.
      */
     restorePreviousEntryForRetry(): boolean;
     isExhausted(): boolean;
@@ -56,5 +57,20 @@ export declare class FallbackChainController {
     resetSticky(): void;
 }
 export declare function cappedExponentialWithFullJitter(baseDelayMs: number, maxDelayMs: number, attemptK: number, random?: () => number): number;
+/**
+ * Legacy auto-compaction retry delay.
+ *
+ * Deliberately the mirror image of `effectiveFallbackDelay`: this path recovers
+ * Retry-After by regex over provider error prose (`#parseRetryAfterMsFromError`),
+ * so it follows the documented legacy rule — `retry.maxDelayMs` caps every
+ * legacy session retry delay, including provider retry-after hints. Managed
+ * fallback stays uncapped because it retries within its own per-entry budget;
+ * compaction has no such budget, so the final candidate would otherwise sleep
+ * for the full server-suggested duration.
+ *
+ * `maxDelayMs <= 0` means "no cap", matching `cappedExponentialWithFullJitter`.
+ * A missing, NaN, or infinite hint collapses to "no usable hint".
+ */
+export declare function compactionRetryDelay(baseDelayMs: number, maxDelayMs: number, attempt: number, retryAfterMs: number | undefined): number;
 /** Retry-After is intentionally uncapped. */
 export declare function effectiveFallbackDelay(baseDelayMs: number, maxDelayMs: number, attemptK: number, retryAfterMs: number | undefined, random?: () => number): number;

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

@@ -1,5 +1,7 @@
 import * as native from "@sayknow-cli/natives";
 import type { ResumeSessionIdentity } from "../session-manager";
+import { type NativeDirectoryTreeSnapshot } from "../session-storage";
+import { type ManagedDirectoryRoot, type ManagedSessionSecurityPolicy, type ManagedStorageLock } 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 = ".skc-managed-session-scope.v2.json";
@@ -15,14 +17,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 +42,10 @@ export type ManagedScopeResolution = {
     kind: "error";
     code: ManagedScopeErrorCode;
     message: string;
+    cause?: {
+        readonly classification: string;
+        readonly diagnostic?: string;
+    };
 };
 export interface ManagedCandidate {
     sessionId: string;
@@ -52,7 +68,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" | "artifact_capacity_exceeded" | "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 +85,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 +107,63 @@ 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 canonicalBindingOpenFlags(platform?: NodeJS.Platform): number;
+export declare function fsyncCanonicalBinding(bindingPath: string, expected: string): void;
+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;
+type DetachedArtifactRoot = {
+    originalPath: string;
+    detachedPath: string;
+    identity: {
+        dev: bigint;
+        ino: bigint;
+        size: bigint;
+        mtimeNs: bigint;
+    };
+    tree: NativeDirectoryTreeSnapshot;
+};
+export declare function matchesMigrationArtifactRoot(pathname: string, identity: {
+    dev: bigint;
+    ino: bigint;
+    size: bigint;
+    mtimeNs: bigint;
+}, expectedTree: NativeDirectoryTreeSnapshot, platform?: NodeJS.Platform): boolean;
+type SourceArtifactCleanup = {
+    state: "cleanup_pending";
+    role: "exchange_placeholder";
+    retainedPath: string;
+    identity: DetachedArtifactRoot["identity"];
+    tree: NativeDirectoryTreeSnapshot;
+};
+export declare function cleanupAuthorityMatches(cleanup: SourceArtifactCleanup, parent: string, platform?: NodeJS.Platform): boolean;
+export declare function detachArtifactRootForMigration(plan: DetachedArtifactRoot, platform?: NodeJS.Platform): {
+    detached: DetachedArtifactRoot;
+    detachOutcome: "clean";
+} | {
+    detached: DetachedArtifactRoot;
+    detachOutcome: "cleanup_pending";
+    cleanup: SourceArtifactCleanup;
+};
+export declare function restorePreparedArtifactRoot(scope: ManagedScope, source: ManagedCandidate, lock?: ManagedStorageLock): void;
 /** Resume tombstoned cleanup under its original operation lease without restoring retired candidates. */
-export declare function reconcileManagedTombstones(scope: ManagedScope): Promise<void>;
+export declare function reconcileManagedTombstones(scope: ManagedScope, expectedCandidate?: ManagedCandidate): 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,19 @@
 import { type NativeDirectoryTreeSnapshot, type NativeOwnerOnlySecurityResult, type RecoveryFsRoot } from "@sayknow-cli/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_FILES = 50000;
 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 const MANAGED_ARTIFACT_COPY_BATCH_SIZE = 256;
+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" | "artifact_capacity_exceeded" | "durability_failed" | "atomic_unavailable" | "durability_not_provable" | "migration_retired" | "managed_storage_unsupported";
 export interface ManagedStorageLock {
     path: string;
     attemptId: string;
@@ -28,6 +38,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 +57,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,29 +84,33 @@ 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>;
+export interface ManagedArtifactTreeLimits {
+    maxFiles?: number;
+    maxTotalBytes?: number;
+}
 /** Bounds a no-follow artifact tree before it can be copied or deleted. */
-export declare function validateManagedArtifactTree(root: string): void;
+export declare function validateManagedArtifactTree(root: string, limits?: ManagedArtifactTreeLimits): void;
 /** Flush a copied managed artifact tree, including empty directories, before publishing its receipt. */
 export declare function fsyncManagedArtifactTree(root: string): NativeDirectoryTreeSnapshot;
 export declare function publishManagedTombstone(destination: string, record: Record<string, unknown>, assertOwned?: () => void): Promise<void>;

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 {};