@gajae-code/coding-agent 0.18.7 → 0.18.8

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

@@ -3,6 +3,7 @@ import { type AuthCredentialSelector, type Model, type ProviderSessionState } fr
 import { createAppendOnlyContextManager, providerSupportsAppendOnlyAuto, resolveAppendOnlyMode } from "../append-only-mode";
 import { AsyncJobManager } from "../async";
 import { type Rule } from "../capability/rule";
+import type { ModelProfileOwnershipMarker } from "../config/model-profile-ownership";
 import { ModelRegistry } from "../config/model-registry";
 import { type ScopedModelSelection } from "../config/model-resolver";
 import { type PromptTemplate } from "../config/prompt-templates";
@@ -82,6 +83,8 @@ export interface CreateAgentSessionOptions {
     modelPattern?: string;
     /** Active profile inherited by a nested SDK/subagent session. */
     activeModelProfile?: string;
+    /** Model profile ownership marker for propagating parent profile ownership to subagent sessions. */
+    modelProfileOwnershipMarker?: ModelProfileOwnershipMarker;
     /** Thinking selector. Default: from settings, else unset */
     thinkingLevel?: ThinkingLevel;
     /** Runtime substitution metadata for the initial model_change session event. */
@@ -194,6 +197,11 @@ export interface CreateAgentSessionOptions {
      * @internal lifecycle-only startup guard.
      */
     deferOptionalModelRefresh?: boolean;
+    /**
+     * Defer model profile activation until explicit model pin validation occurs.
+     * @internal Lifecycle-only: prevents default profile activation before pin resolution.
+     */
+    deferModelProfileActivation?: boolean;
     /** Enable LSP integration (tool, formatting, diagnostics, warmup). Default: true */
     enableLsp?: boolean;
     /** Skip Python kernel availability check and prelude warmup */

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

@@ -12,7 +12,7 @@
  *
  * Modes use this class and add their own I/O layer on top.
  */
-import { type Agent, type AgentContext, type AgentEvent, type AgentLoopConfig, type AgentMessage, type AgentState, type AgentTool, type MidRunMaintenanceOutcome, type RunSettlementProof, type StablePrefixSnapshot, ThinkingLevel } from "@gajae-code/agent-core";
+import { type Agent, type AgentContext, type AgentEvent, type AgentLoopConfig, type AgentMessage, type AgentState, type AgentTerminalOwnerContext, type AgentTool, type MidRunMaintenanceOutcome, type RunCancellationDomain, type RunSettlementProof, type StablePrefixSnapshot, ThinkingLevel } from "@gajae-code/agent-core";
 import type { AttemptScope } from "@gajae-code/agent-core/attempt-scope";
 import { type CompactionResult, type EmergencyCompactionSample } from "@gajae-code/agent-core/compaction";
 import type { AssistantMessage, AttemptScopeRef, Effort, ImageContent, Message, MessageAttribution, Model, ProviderSessionState, ServiceTier, SimpleStreamOptions, TextContent, ToolCall, ToolChoice, Usage, UsageReport } from "@gajae-code/ai/core";
@@ -68,7 +68,7 @@ export interface ForkContextSeedOptions {
     signal?: AbortSignal;
 }
 import type { AuthCredentialSelector } from "@gajae-code/ai/core";
-import { type AsyncJob, type AsyncJobDeliveryState, AsyncJobManager, type FoldReason, type JobFoldEvent } from "../async";
+import { type AsyncJob, type AsyncJobDeliveryState, AsyncJobManager, type FoldReason, type JobFoldEvent, type SubagentLifecycle } from "../async";
 import type { Rule } from "../capability/rule";
 import { type ModelRegistry } from "../config/model-registry";
 import { type ResolvedModelRoleValue, type ScopedModelSelection } from "../config/model-resolver";
@@ -84,7 +84,7 @@ import type { ExtensionRunner } from "../extensibility/extensions";
 import { type CompactOptions, type ContextUsage, type ExtensionTranscriptEntry } from "../extensibility/extensions/types";
 import type { GjcRuntimeSnapshotProvider } from "../extensibility/gjc-plugins/runtime-quarantine";
 import type { SessionSwitchEvent } from "../extensibility/shared-events";
-import { type Skill, type SkillWarning } from "../extensibility/skills";
+import { type ParsedSkillInvocation, type Skill, type SkillWarning } from "../extensibility/skills";
 import { type FileSlashCommand } from "../extensibility/slash-commands";
 import { type MemoryGuardClaimsLease } from "../gjc-runtime/memory-guard-owner-claims";
 import { GoalRuntime } from "../goals/runtime";
@@ -113,7 +113,7 @@ import { type ContributionPrepOptions, type ContributionPrepResult } from "./con
 import { type FoldAdapter, FoldCoordinator, type ForegroundFoldOutcome } from "./fold-coordinator";
 import type { MemoryGuardRestoreResult } from "./memory-guard-checkpoint-participant";
 import { type CustomMessage } from "./messages";
-import type { BranchSummaryEntry, CompactionEntry, NewSessionOptions, PreparedNewSession, RecoveryHydrationContext, RecoveryHydrationPromotionFence, SessionContext, SessionManagerCloseOutcome, SessionMemoryStats } from "./session-manager";
+import type { BranchSummaryEntry, CompactionEntry, NewSessionOptions, PreparedNewSession, RecoveryHydrationContext, RecoveryHydrationPromotionFence, SessionContext, SessionManagerCloseOutcome, SessionMemoryStats, SessionArtifactPublication } from "./session-manager";
 import { SessionManager } from "./session-manager";
 import { ToolChoiceQueue } from "./tool-choice-queue";
 import { YieldQueue } from "./yield-queue";
@@ -603,11 +603,7 @@ export declare class SessionDisposalIncompleteError extends Error {
     constructor(label?: string);
 }
 export declare function isSessionDisposalIncompleteError(error: unknown): error is SessionDisposalIncompleteError;
-export interface AgentBashArtifactStore {
-    saveArtifact(content: string, toolType: string): Promise<string | undefined>;
-    getArtifactPath(id: string): Promise<string | null>;
-}
-export declare function saveAgentBashOriginalArtifact(store: AgentBashArtifactStore, originalText: string): Promise<BashArtifactSaveResult>;
+export declare function saveAgentBashOriginalArtifact(publication: SessionArtifactPublication, originalText: string): Promise<BashArtifactSaveResult>;
 type IrcRosterClaim = {
     token: symbol;
     signature: string;
@@ -854,6 +850,11 @@ export declare class AgentSession {
     getAsyncJobSnapshot(options?: {
         recentLimit?: number;
     }): AsyncJobSnapshot | null;
+    /**
+     * Lifecycle status of every subagent owned by this session, read from the
+     * manager's stable control-plane records (they outlive AsyncJob eviction).
+     */
+    getSubagentLifecycleStatuses(): SubagentLifecycle[];
     /**
      * Emit a UI-only notice to the session. Surfaces in interactive mode as a
      * `showWarning` / `showError` / `showStatus` line; non-interactive modes
@@ -1212,6 +1213,20 @@ 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>;
+    /**
+     * The loaded skill a prompt's text dispatches to, or undefined when `prompt`
+     * would submit it as ordinary text (unknown or disabled `/skill:` names,
+     * chains, or attached images). Single source for dispatch and for callers
+     * that must mirror it, such as startup title seeding.
+     */
+    resolvePromptSkillInvocation(text: string, images?: readonly unknown[]): ParsedSkillInvocation | undefined;
+    /**
+     * Whether `prompt` intercepts this slash text as an extension or custom/MCP
+     * command. Used to keep command arguments away from the title model. Mirrors the
+     * command lookup in `#tryExecuteExtensionCommand` / `#tryExecuteCustomCommand`
+     * without executing anything.
+     */
+    isLocallyHandledSlashCommand(text: string): boolean;
     promptCustomMessage<T = unknown>(message: Pick<CustomMessage<T>, "customType" | "content" | "display" | "details" | "attribution">, options?: Pick<PromptOptions, "streamingBehavior" | "toolChoice" | "followUpQueuePolicy" | "steerQueuePolicy" | "onPreflightAccepted" | "onPreflightAcceptCommit" | "preflightSignal" | "sdkRunCapability">): Promise<void>;
     /**
      * Queue a steering message to interrupt the agent mid-run.
@@ -1397,6 +1412,8 @@ export declare class AgentSession {
     rebindTerminalAbortSteeringSnapshot(token: number): void;
     discardTerminalAbortSteeringSnapshot(token: number): void;
     getTerminalTurnEpoch(): number | undefined;
+    getTerminalRunOwnerForEvent(event: object): AgentTerminalOwnerContext | undefined;
+    getRunOwnerDomain(handle: string): RunCancellationDomain | undefined;
     /**
      * Tool call ids the run resource ledger currently holds for `handle` (#5637).
      *
@@ -1464,6 +1481,17 @@ export declare class AgentSession {
     }): Promise<void>;
     setActiveModelProfile(name: string | undefined): void;
     getActiveModelProfile(): string | undefined;
+    setUnavailableModelProfile(name: string | undefined): void;
+    getUnavailableModelProfile(): string | undefined;
+    /** Revision fence for deferred activation after a user model selection. */
+    getUserModelSelectionRevision(): number;
+    /** Latest concrete user choice that seeded or cleared the session's sticky canonical variant. */
+    getUserCanonicalVariantSelection(): {
+        revision: number;
+        canonicalVariant: string | undefined;
+    };
+    /** Fence deferred startup profile recovery before an explicit control-surface selection. */
+    markUserModelSelection(): void;
     /**
      * Re-apply vendor-separated delegation after a profile activation changed the
      * role layer. `eagerTasks` is resolved at prompt build time, but under
@@ -1597,6 +1625,7 @@ export declare class AgentSession {
         reason?: TemporaryModelReason;
         providerSessionScope?: TemporaryProviderSessionScope;
         signal?: AbortSignal;
+        shouldMutate?: () => boolean;
         onMutationStarted?: () => void;
     }): Promise<TemporaryProviderSessionScope | void>;
     /** Restore the exact live-model state captured before a failed selector transaction. */

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

@@ -77,8 +77,8 @@ export declare class ArtifactManager {
      * Best-effort removal of a previously published named artifact. Used to roll
      * back staged publications when a transactional operation (e.g. gated
      * maintenance pruning) is rejected after publication succeeded. Returns false
-     * when the artifact could not be removed so callers can log the failure
-     * instead of silently treating the rollback as complete.
+     * when the exact named artifact is absent or could not be removed; success does
+     * not claim that unrelated native cleanup residue was reclaimed.
      */
     removeNamedBestEffort(filename: string): Promise<boolean>;
     /**

package/dist/types/session/internal/managed-gc-retirement-codec.d.ts

@@ -0,0 +1,32 @@
+import type { SessionStorageFileIdentity } from "../session-storage";
+import { type TaskArtifactOwnerDeletionEvidence, type TaskArtifactOwnerLocator, type TaskArtifactOwnerRetirementContinuation, type TaskArtifactOwnerRetirementOutcome, type TaskArtifactOwnerStorageContext } from "../task-artifact-owner-codec";
+export type ManagedGcSessionRetirementState = "prepared" | "artifacts_removed" | "owner_pending" | "owner_retired";
+export interface ManagedGcSessionRetirementTarget {
+    readonly transcriptPath: string;
+    readonly sessionId: string;
+    readonly cwd: string;
+    readonly transcriptIdentity: SessionStorageFileIdentity;
+    readonly taskArtifactOwnerLocator: TaskArtifactOwnerLocator;
+}
+export interface ManagedGcSessionRetirementReceipt extends ManagedGcSessionRetirementTarget {
+    readonly state: ManagedGcSessionRetirementState;
+    readonly taskArtifactOwnerDeletionEvidence: TaskArtifactOwnerDeletionEvidence;
+    readonly artifactsRemoved?: true;
+    readonly ownerRetirementAttempt?: number;
+    readonly taskArtifactOwnerRetirementOutcome?: TaskArtifactOwnerRetirementOutcome;
+    readonly taskArtifactOwnerRetirementContinuation?: TaskArtifactOwnerRetirementContinuation;
+    readonly taskArtifactOwnerPayloadRetired?: true;
+    readonly taskArtifactOwnerNamespaceRetained?: true;
+    readonly taskArtifactOwnerRetired?: true;
+}
+export declare function managedGcRetirementIdentityRecord(identity: SessionStorageFileIdentity): Record<string, unknown>;
+export declare function sameIdentity(left: SessionStorageFileIdentity, right: SessionStorageFileIdentity): boolean;
+export declare function managedGcRetirementIdentityValue(value: unknown): SessionStorageFileIdentity;
+/**
+ * Strictly decode one persisted managed-GC receipt. A decoded `owner_retired` outcome is persisted DTO data only;
+ * this pure parser does not verify current filesystem state, payload destruction, or writer quiescence. A future
+ * journal reader must perform the live physical-retirement proof for the relevant state before treating it as done.
+ */
+export declare function parseManagedGcRetirementReceipt(value: unknown, scopeDigest: string, ownerContext: TaskArtifactOwnerStorageContext, target: ManagedGcSessionRetirementTarget): ManagedGcSessionRetirementReceipt;
+/** Check only monotone DTO history; this does not establish physical cleanup or current authority. */
+export declare function continuationExtendsPrevious(previous: TaskArtifactOwnerRetirementContinuation, next: TaskArtifactOwnerRetirementContinuation): boolean;

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

@@ -1,6 +1,8 @@
 import type { RecoveryFsRoot } from "@gajae-code/natives";
 import type { ResumeSessionIdentity } from "../session-manager";
 import { type NativeDirectoryTreeSnapshot } from "../session-storage";
+import { type TaskArtifactOwnerStorageContext } from "../task-artifact-owner-codec";
+import { type ManagedGcSessionRetirementReceipt, type ManagedGcSessionRetirementTarget } from "./managed-gc-retirement-codec";
 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;
@@ -17,6 +19,57 @@ export interface ManagedScope {
     directoryPath: string;
     platform: "posix" | "win32";
 }
+export interface ManagedGcProtocolPathIdentity {
+    readonly path: string;
+    readonly dev: string;
+    readonly ino: string;
+}
+export interface ManagedGcProtocolFileSnapshot {
+    readonly name: string;
+    readonly dev: string;
+    readonly ino: string;
+    readonly nlink: string;
+    readonly size: number;
+    readonly mtimeNs: string;
+    readonly ctimeNs: string;
+    readonly mode: number;
+    readonly sha256: string;
+}
+export type ManagedGcProtocolRole = "locks" | "receipts" | "tombstones";
+export interface ManagedGcProtocolDirectorySnapshot {
+    readonly role: ManagedGcProtocolRole;
+    readonly path: string;
+    readonly dev: string;
+    readonly ino: string;
+    readonly mtimeNs: string;
+    readonly ctimeNs: string;
+    readonly mode: number;
+    readonly files: readonly ManagedGcProtocolFileSnapshot[];
+}
+/** Read-only protocol data; never a deletion capability. */
+export interface ManagedGcProtocolScopeSnapshot {
+    readonly configuredRoot: ManagedGcProtocolPathIdentity;
+    readonly profile: ManagedGcProtocolPathIdentity;
+    readonly sessionsRoot: ManagedGcProtocolPathIdentity;
+    readonly scope: ManagedGcProtocolPathIdentity;
+    readonly binding: ManagedGcProtocolFileSnapshot;
+    readonly protocol: ManagedGcProtocolPathIdentity;
+    readonly protocolMtimeNs: string;
+    readonly protocolCtimeNs: string;
+    readonly protocolMode: number;
+    readonly directories: readonly ManagedGcProtocolDirectorySnapshot[];
+}
+export interface ManagedGcProtocolScopeInput {
+    readonly scopePath: string;
+    readonly scopeIdentity: ManagedGcProtocolPathIdentity;
+    readonly bindingIdentity: ManagedGcProtocolFileSnapshot;
+    readonly protocolIdentity: ManagedGcProtocolScopeSnapshot["protocol"] & {
+        readonly mtimeNs: string;
+        readonly ctimeNs: string;
+        readonly mode: number;
+    };
+}
+export type ManagedGcProtocolScopeInspector = (inputs: readonly ManagedGcProtocolScopeInput[]) => Promise<readonly ManagedGcProtocolScopeSnapshot[]>;
 /**
  * Opaque managed writer authority captured by a trusted destination. The open
  * transaction must use this authority rather than reacquiring its root from a
@@ -34,7 +87,7 @@ export declare function managedDirectoryIdentityForScope(scope: ManagedScope): {
 };
 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" | "migration_busy" | "atomic_unavailable" | "invalid_request" | "durability_failed" | "durability_not_provable" | "capacity_exceeded";
+export type ManagedScopeErrorCode = "cwd_missing" | "cwd_not_directory" | "identity_unavailable" | "network_unsupported" | "sessions_root_unavailable" | "binding_conflict" | "binding_invalid" | "migration_busy" | "managed_gc_journal_capacity_exceeded" | "atomic_unavailable" | "invalid_request" | "durability_failed" | "durability_not_provable" | "capacity_exceeded";
 export type ManagedScopeResolution = {
     kind: "resolved";
     scope: ManagedScope;
@@ -69,7 +122,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" | "artifact_capacity_exceeded" | "durability_failed" | "atomic_unavailable" | "invalid_request" | "durability_not_provable" | "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" | "managed_gc_journal_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;
@@ -132,6 +185,8 @@ interface ManagedScopeInput {
 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;
+/** Resolve only an existing, authenticated v2 scope; this path never initializes or repairs storage. */
+export declare function resolveManagedGcScopeForRead(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>;
@@ -201,6 +256,28 @@ export declare function isRecoverableOwnerOnlyModeDrift(error: unknown): boolean
 /** Synchronously create and validate the v2 binding before a default session writer exists. */
 export declare function prepareManagedSessionScopeForWriteSync(scope: ManagedScope, policy?: ManagedSessionSecurityPolicy, authority?: ManagedCandidateWriteAuthority): ManagedScopeResolution;
 export declare function listManagedCandidates(scope: ManagedScope): ManagedCandidateListing;
+/** Build owner-storage authority only from a previously prepared trusted managed scope. */
+export declare function taskArtifactOwnerStorageContextForScope(scope: ManagedScope): TaskArtifactOwnerStorageContext;
+/** Bind the first transcript header through FileSessionStorage's descriptor-bound, no-follow snapshot. */
+export declare function bindManagedGcSessionRetirementTarget(scope: ManagedScope, transcriptPathValue: string): ManagedGcSessionRetirementTarget;
+/** Read the prepared authority first, then strictly validate every later receipt against it. */
+export declare function readManagedGcSessionRetirementReceipt(scope: ManagedScope, transcriptPath: string): Promise<ManagedGcSessionRetirementReceipt | undefined>;
+/** Read an authenticated journal without creating lock/receipt directories or repairing security state. */
+export declare function readManagedGcSessionRetirementReceiptReadOnly(scope: ManagedScope, transcriptPath: string): Promise<ManagedGcSessionRetirementReceipt | undefined>;
+/** Discover complete owner journals under authenticated existing v2 scopes without initializing storage. */
+export declare function discoverManagedGcSessionRetirementReceipts(input: {
+    agentDir: string;
+    sessionsRoot: string;
+}): Promise<readonly {
+    readonly scope: ManagedScope;
+    readonly receipt: ManagedGcSessionRetirementReceipt;
+}[]>;
+/** Inspect under a live operation lease; returned snapshots never authorize effects. */
+export declare function managedGcProtocolInspectorForLock(scope: ManagedScope, lock: ManagedStorageLock): ManagedGcProtocolScopeInspector;
+/** Bind a read-only protocol inventory to an already prepared scope's root/profile/session identities. */
+export declare function managedGcProtocolScopeInspectorForScope(scope: ManagedScope): ManagedGcProtocolScopeInspector;
+/** Atomically publish one journal state under the managed scope lock; no GC effects are activated here. */
+export declare function publishManagedGcSessionRetirementReceipt(scope: ManagedScope, receipt: ManagedGcSessionRetirementReceipt): Promise<ManagedGcSessionRetirementReceipt>;
 export declare function artifactTreeReplayCompatible(observed: NativeDirectoryTreeSnapshot, expected: NativeDirectoryTreeSnapshot): boolean;
 type DetachedArtifactRoot = {
     originalPath: string;

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

@@ -5,6 +5,7 @@ export declare const MANAGED_ARTIFACT_MAX_DEPTH = 32;
 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 declare const MANAGED_SESSION_READ_RANGE_MAX_BYTES: number;
 export declare const MANAGED_ARTIFACT_COPY_BATCH_SIZE = 256;
 /** A pre-mutation append fence rejection: no bytes from this append were written. */
 export declare class ManagedAppendIdentityMismatchError extends Error {
@@ -104,6 +105,8 @@ export interface ManagedBoundedAppendExpectation {
     readonly ctimeNs: string;
     readonly sha256: string;
 }
+/** Exact quarantine names used when native exact-unlink leaves a scrubbed lock inode. */
+export declare function isManagedLockQuarantineName(name: string): boolean;
 export interface ScrubbedProtocolRemnantReapResult {
     readonly reaped: number;
     readonly failures: number;
@@ -135,6 +138,16 @@ export declare function reapScrubbedProtocolRemnantsSync(directory: string, minA
  */
 export declare function reapScrubbedProtocolRemnants(directory: string, minAgeMs?: number): Promise<ScrubbedProtocolRemnantReapResult>;
 export declare function validateNativeSecurityResult(value: unknown, operation: "apply" | "verify", kind: "directory" | "file"): NativeOwnerOnlySecurityResult;
+export type LockRecord = {
+    attemptId: string;
+    pid: number;
+    bootId?: string;
+    processStartId: string;
+    createdAt: number;
+    heartbeatAt: number;
+    leaseExpiresAt: number;
+    released?: boolean;
+};
 export interface ManagedLockRetirementTestEvent {
     readonly path: string;
     readonly attemptId: string;
@@ -168,13 +181,18 @@ export declare function retainManagedDirectoryAuthority(root: ManagedDirectoryRo
 }): RecoveryFsRoot | undefined;
 export declare function assertManagedDirectoryRoot(root: ManagedDirectoryRoot): void;
 export declare function managedSecurityFailureClassification(error: unknown): string | undefined;
+/** Exact, identity-bound read access retained for the lifetime of one managed stream. */
+export interface ManagedSessionReadLease {
+    readRange(start: number, length: number): Uint8Array;
+    close(): 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;
-    }, policy?: ManagedSessionSecurityPolicy, profileAgentDir?: string, expectedSubtreeRoot?: ManagedDirectoryRoot);
+    }, policy?: ManagedSessionSecurityPolicy, profileAgentDir?: string, expectedSubtreeRoot?: ManagedDirectoryRoot, access?: "read-only" | "read-write");
     get dir(): string;
     get rootAuthority(): ManagedDirectoryRoot;
     get subtreeRootAuthority(): ManagedDirectoryRoot;
@@ -223,8 +241,12 @@ export declare class ManagedSessionDescendantStore {
      * managed-session indexing without weakening pathname authority.
      */
     readRangeExpectedSync(relativePath: string, start: number, length: number, expectedDescriptor?: Pick<SessionStorageStat, "dev" | "ino" | "nlink" | "size" | "mtimeNs" | "ctimeNs">): SessionStorageRangeSnapshot;
+    /** Open an identity-bound stream lease; Darwin uses exact bounded range reads per chunk. */
+    openReadLease(relativePath: string, expectedDescriptor: Pick<SessionStorageStat, "dev" | "ino" | "nlink" | "size" | "mtimeNs" | "ctimeNs">): ManagedSessionReadLease;
     /** Read an exact managed file without exposing its pathname as authority. */
     readExpected(relativePath: string): ManagedFileSnapshot | null;
+    /** Read one complete managed file through retained authority after descriptor-size admission. */
+    readExpectedBounded(relativePath: string, maxBytes: number, admitSize?: (size: number, descriptor: ManagedFileIdentity) => void): ManagedFileSnapshot | null;
     /** Remove an exact captured file without reopening its pathname as authority. */
     removeExpected(relativePath: string, expected: ManagedFileSnapshot): void;
     /** Remove one exact file without allocating its contents. */
@@ -253,10 +275,13 @@ export declare class ManagedSessionDescendantStore {
     fsyncTree(): NativeDirectoryTreeSnapshot;
 }
 export declare function shouldFsyncManagedDirectory(platform?: NodeJS.Platform): boolean;
+export declare function parseManagedLockRecord(bytes: Uint8Array): LockRecord | undefined;
 /** Create a managed directory and fail closed unless its owner-only mode/ACL verifies. */
 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 a complete no-follow file only after descriptor-size admission and before allocating its bytes. */
+export declare function captureManagedFileNoFollowBounded(pathname: string, maxBytes: number, admitSize?: (size: number, descriptor: ManagedFileIdentity) => void): ManagedFileSnapshot;
 /** Captures header/hash/copy input from one no-follow descriptor and rechecks the pathname before use. */
 export declare function captureManagedFileNoFollow(pathname: string): ManagedFileSnapshot;
 /** Streams a managed file once while retaining only a bounded header prefix and the full descriptor-bound digest. */

package/dist/types/session/internal/managed-task-owner-cleanup.d.ts

@@ -0,0 +1,62 @@
+import type { ResumeSessionIdentity } from "../session-manager";
+import { type VerifiedSessionDeleteResult, type VerifiedSessionDeleteTarget } from "../session-storage";
+import type { TaskArtifactOwnerDeletionEvidence, TaskArtifactOwnerStorageContext } from "../task-artifact-owner-codec";
+import type { ManagedGcSessionRetirementReceipt, ManagedGcSessionRetirementTarget } from "./managed-gc-retirement-codec";
+import type { ManagedGcProtocolScopeInspector } from "./managed-session-scope";
+export interface ManagedGcOwnerCleanupTarget {
+    readonly path: string;
+    readonly sessionId: string;
+    readonly cwd: string;
+    readonly identity: ResumeSessionIdentity;
+    readonly taskArtifactOwnerDeletionEvidence?: TaskArtifactOwnerDeletionEvidence;
+}
+/** Authenticated receipt operations and fencing supplied by the prepared managed scope. */
+export interface ManagedGcOwnerCleanupAuthority {
+    readonly agentDir: string;
+    readonly sessionsRoot: string;
+    readonly directoryPath: string;
+    readonly storageContext: TaskArtifactOwnerStorageContext;
+    readonly inspectProtocol: ManagedGcProtocolScopeInspector;
+    readonly assertOwned: () => void;
+    readonly bindTarget: (transcriptPath: string) => ManagedGcSessionRetirementTarget;
+    readonly readReceipt: (transcriptPath: string) => Promise<ManagedGcSessionRetirementReceipt | undefined>;
+    readonly publishReceipt: (receipt: ManagedGcSessionRetirementReceipt) => Promise<ManagedGcSessionRetirementReceipt>;
+    readonly findCompletedRetirement: (evidence: TaskArtifactOwnerDeletionEvidence, exceptTranscriptPath: string) => Promise<{
+        scope: {
+            readonly agentDir: string;
+            readonly sessionsRoot: string;
+            readonly directoryPath: string;
+        };
+        receipt: ManagedGcSessionRetirementReceipt;
+    } | undefined>;
+}
+export type ManagedGcOwnerProgress = {
+    readonly state: "none" | "owner_retired" | "payload_retired" | "pending";
+    readonly message?: string;
+};
+export type ManagedGcOwnerDeleteFields = Pick<VerifiedSessionDeleteTarget, "taskArtifactOwnerStorageContext" | "taskArtifactOwnerDeletionEvidence" | "taskArtifactOwnerRetirementOutcome" | "taskArtifactOwnerRetirementContinuation" | "taskArtifactOwnerPayloadRetired" | "taskArtifactOwnerNamespaceRetained" | "deferTaskArtifactOwnerRetirement" | "taskArtifactOwnerRetired">;
+export declare function hasUnsupportedLegacyOwnerTarget(scopeDirectory: string, target: ManagedGcOwnerCleanupTarget): boolean;
+export declare function prepareManagedGcOwnerTarget<T extends ManagedGcOwnerCleanupTarget>(authority: ManagedGcOwnerCleanupAuthority, target: T): Promise<T & ManagedGcOwnerCleanupTarget>;
+export declare function prepareManagedGcOwnerTargets<T extends ManagedGcOwnerCleanupTarget>(authority: ManagedGcOwnerCleanupAuthority, targets: readonly T[]): Promise<(T & ManagedGcOwnerCleanupTarget)[]>;
+export declare function managedGcOwnerDeleteFields(authority: ManagedGcOwnerCleanupAuthority, target: ManagedGcOwnerCleanupTarget): Promise<ManagedGcOwnerDeleteFields>;
+export declare function publishManagedGcArtifactsRemoved(authority: ManagedGcOwnerCleanupAuthority, target: ManagedGcOwnerCleanupTarget): Promise<ManagedGcSessionRetirementReceipt | undefined>;
+export declare function retireManagedGcOwnerAfterArtifacts(authority: ManagedGcOwnerCleanupAuthority, target: ManagedGcOwnerCleanupTarget, tombstoneTargets: readonly ManagedGcOwnerCleanupTarget[]): Promise<ManagedGcOwnerProgress>;
+export declare function persistManagedGcStorageOwnerDisposition(authority: ManagedGcOwnerCleanupAuthority, target: ManagedGcOwnerCleanupTarget, deletion: Extract<VerifiedSessionDeleteResult, {
+    kind: "cleanup_pending";
+    phase: "task_artifact_owner";
+}>): Promise<ManagedGcOwnerProgress>;
+export declare function managedGcOwnerProgressBeforeDelete(authority: ManagedGcOwnerCleanupAuthority, target: ManagedGcOwnerCleanupTarget, tombstoneTargets: readonly ManagedGcOwnerCleanupTarget[], artifactsRemoved: boolean): Promise<ManagedGcOwnerProgress>;
+export declare function taskArtifactOwnerTranscriptResult(authority: ManagedGcOwnerCleanupAuthority, target: ManagedGcOwnerCleanupTarget): Promise<"none" | "retired" | "payload_retired">;
+export interface ManagedGcOwnerTranscriptDeleteReceipt {
+    readonly taskArtifactOwnerTranscriptDeleted?: true;
+}
+export declare function persistManagedGcOwnerTranscriptDeletion<T extends ManagedGcOwnerTranscriptDeleteReceipt>(input: {
+    target: ManagedGcOwnerCleanupTarget;
+    fallback: T;
+    deletion: Extract<VerifiedSessionDeleteResult, {
+        kind: "deleted";
+    }>;
+    readLatest: () => T | undefined;
+    nextReceipt: (latest: T) => T;
+    publishPending: (receipt: T) => Promise<void>;
+}): Promise<void>;

package/dist/types/session/internal/task-artifact-owner-access.d.ts

@@ -5,6 +5,8 @@ export interface OwnerManifest extends TaskArtifactOwnerLocator {
     readonly sessionId: string;
 }
 export declare function newSessionRootStore(context: TaskArtifactOwnerStorageContext): ManagedSessionDescendantStore;
+/** Path-backed reader with no retained or recovery-mutable native authority. */
+export declare function newSessionRootReaderStore(context: TaskArtifactOwnerStorageContext): ManagedSessionDescendantStore;
 export declare function readOwnerManifest(store: ManagedSessionDescendantStore, locator: TaskArtifactOwnerLocator, relativePath?: string): OwnerManifest;
 export declare function assertOwnerDirectoryExists(context: TaskArtifactOwnerStorageContext, ownerId: string): void;
 export declare function assertOwnerIdentity(store: ManagedSessionDescendantStore, locator: TaskArtifactOwnerLocator): void;

package/dist/types/session/internal/task-artifact-owner-transcript.d.ts

@@ -1,3 +1,11 @@
-import { type TaskArtifactOwnerLocator } from "../task-artifact-owner-codec";
+import type { FileSessionStorage } from "../session-storage";
+import { type TaskArtifactOwnerLocator, type TaskArtifactOwnerStorageContext } from "../task-artifact-owner-codec";
+import type { ManagedGcProtocolScopeInspector } from "./managed-session-scope";
 /** Resolve the path-free owner locator using transcript replay's header-patch semantics. */
 export declare function taskArtifactOwnerLocatorFromTranscriptBytes(bytes: Uint8Array, expectedSessionId: string): TaskArtifactOwnerLocator | undefined;
+/**
+ * Read-only inventory of every authenticated managed cwd directory under one profile's
+ * sessions root. Any incomplete, replaced, or unrecognized inventory conservatively
+ * blocks owner retirement.
+ */
+export declare function hasSiblingTaskArtifactOwnerTranscript(storage: Pick<FileSessionStorage, "readSnapshotSync">, transcriptPath: string, locator: TaskArtifactOwnerLocator, context: TaskArtifactOwnerStorageContext, inspectProtocol?: ManagedGcProtocolScopeInspector): Promise<boolean>;

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

@@ -638,6 +638,21 @@ export interface ResumeSessionIdentity {
     ctimeNs?: bigint;
     sha256: string;
 }
+/** Descriptor-bound bounded fingerprint for private explicit-session rollback authority.
+ * JSON-safe: all bigint fields are stored as strings to survive JSON serialization,
+ * spread, structuredClone, and JSON round-trip. */
+export type ExplicitPersistIdentity = {
+    dev: string;
+    ino: string;
+    nlink?: string;
+    size: number;
+    mtimeMs: number;
+    mtimeNs: string;
+    ctimeNs?: string;
+    canonicalPath: string;
+    sessionId: string;
+    fingerprintSha256: string;
+};
 export interface ResumeTailResumable {
     kind: "resumable";
     identity: ResumeSessionIdentity;
@@ -953,7 +968,8 @@ export interface ReadonlySessionManager {
 /** Creates an immutable facade that never exposes SessionManager mutation authority. */
 export declare function createReadonlySessionManager(manager: SessionManager): ReadonlySessionManager;
 /** Internal artifact-writing capability. Read-only facades expose it only through a private weak-map lookup. */
-export type SessionArtifactCapability = Readonly<Pick<SessionManager, "allocateArtifactPath" | "saveArtifact" | "putBlob">>;
+export type SessionArtifactPublication = (content: string, toolType: string) => Promise<string | undefined>;
+export type SessionArtifactCapability = Readonly<Pick<SessionManager, "allocateArtifactPath" | "saveArtifact" | "putBlob" | "captureArtifactPublication">>;
 /**
  * Returns the artifact capability for a concrete persistence owner or one of its
  * immutable read-only facades. Structural lookalikes remain unauthorized.
@@ -1038,6 +1054,8 @@ export declare function materializeResidentEntriesThrowingForTests<T>(entries: T
     sessionFile?: string;
 }): T[];
 export declare function materializeResidentEntriesForPersistenceForTests<T>(entries: T[], textStore: BlobStore, imageStore?: BlobStore): T[];
+export declare function isProjectSessionTranscriptPath(projectGjcDir: string, filePath: string): boolean;
+export declare function readAuthorizedProjectSessionTranscript(projectGjcDir: string, filePath: string, maxBytes: number): Buffer | undefined;
 /**
  * Discover resumable transcripts intentionally stored inside a project's `.gjc`.
  * Runtime token/audit JSONL files are excluded by requiring a known transcript
@@ -1084,10 +1102,12 @@ interface SessionManagerStateSnapshot {
     flushed: boolean;
     ensuredOnDisk: boolean;
     needsFullRewriteOnNextPersist: boolean;
-    fileEntries: FileEntry[];
-    materializedFileEntries: FileEntry[];
+    fileEntries: readonly FileEntry[];
+    materializedFileEntries: readonly FileEntry[];
     adoptedArtifactManager: ArtifactManager | null;
     coldRestoreFile?: string;
+    /** Explicit persistence identity for snapshot serialization safety. Preserved across cross-manager adoptions. */
+    readonly explicitPersistIdentity?: ExplicitPersistIdentity;
 }
 /** Benchmark-derived cap for strong materialized session snapshots. */
 export declare const MATERIALIZED_CACHE_MAX_BYTES: number;
@@ -1109,6 +1129,7 @@ export declare const SessionManagerTestHooks: {
     beforeManagedMissingReturn?: (filePath: string, storage: SessionStorage) => void | Promise<void>;
     afterManagedMissingAssertion?: (filePath: string, storage: SessionStorage) => void | Promise<void>;
     beforeManagedSwitchIdentity?: (filePath: string, storage: SessionStorage) => void | Promise<void>;
+    beforeColdRollbackCommit?: (filePath: string, storage: SessionStorage) => void | Promise<void>;
     /** Internal first-open GC strategy override; omitted means current. */
     firstOpenGcStrategy?: SessionMemoryGcStrategy;
     /** Internal first-open secondary-artifact mode override; omitted means auto. */
@@ -1428,8 +1449,11 @@ export declare class SessionManager {
      * one bound to the current session file unless an external manager was
      * adopted via `adoptArtifactManager`. Falls back to the lazily created
      * ephemeral filesystem store once a non-persistent session has saved an
-     * artifact, so `artifact://` stays resolvable. Returns null only when no
-     * store has been established yet.
+     * artifact, so `artifact://` stays resolvable. Returns null when no store has
+     * been established yet and once the manager has released its artifact
+     * authority while closing — released authority stays observable as absence
+     * (matching `isArtifactManagerAuthorized`), while artifact *operations* are
+     * fenced by `#assertArtifactOpen()` and keep throwing.
      */
     getArtifactManager(): ArtifactManager | null;
     /** Linearizably establish this session's persistent or ephemeral artifact manager. */
@@ -1449,6 +1473,8 @@ export declare class SessionManager {
      * read back from the filesystem instead of being retained in memory.
      */
     saveArtifact(content: string, toolType: string): Promise<string | undefined>;
+    /** Capture artifact publication authority for one session lifecycle. */
+    captureArtifactPublication(): SessionArtifactPublication;
     /** Inspect an evicted artifact using a bounded range read; never rehydrates by default. */
     inspectEvictedToolOutput(handle: unknown, range?: {
         start?: number;

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

@@ -1,4 +1,10 @@
+import type { ManagedGcSessionRetirementReceipt } from "./internal/managed-gc-retirement-codec";
+import { type ManagedScope } from "./internal/managed-session-scope";
 import { type FileSessionStorage } from "./session-storage";
+import type { TaskArtifactOwnerDeletionEvidence, TaskArtifactOwnerRetirementContinuation, TaskArtifactOwnerRetirementOutcome } from "./task-artifact-owner-codec";
+export interface SessionRetirementContinuation {
+    readonly managedScope: ManagedScope;
+}
 /**
  * Outcome of a disk-retention retirement attempt.
  *
@@ -11,12 +17,34 @@ import { type FileSessionStorage } from "./session-storage";
  */
 export type SessionRetirementOutcome = {
     kind: "retired";
+    taskArtifactOwnerRetired?: true;
 } | {
     kind: "kept";
     reason: string;
 } | {
     kind: "cleanup_pending";
     reason: string;
+    phase?: "artifacts" | "transcript";
+    taskArtifactOwnerDeletionEvidence?: TaskArtifactOwnerDeletionEvidence;
+    taskArtifactOwnerRetirementOutcome?: TaskArtifactOwnerRetirementOutcome;
+    taskArtifactOwnerRetirementContinuation?: TaskArtifactOwnerRetirementContinuation;
+    taskArtifactOwnerPayloadRetired?: true;
+    taskArtifactOwnerNamespaceRetained?: true;
+    taskArtifactOwnerRetired?: true;
+};
+export type SessionRetirementProbeOutcome = Extract<SessionRetirementOutcome, {
+    kind: "cleanup_pending";
+}> | {
+    kind: "retirable";
+    taskArtifactOwnerDeletionEvidence?: TaskArtifactOwnerDeletionEvidence;
+    taskArtifactOwnerRetirementOutcome?: TaskArtifactOwnerRetirementOutcome;
+    taskArtifactOwnerRetired?: true;
+    taskArtifactOwnerRetirementContinuation?: TaskArtifactOwnerRetirementContinuation;
+    taskArtifactOwnerPayloadRetired?: true;
+    taskArtifactOwnerNamespaceRetained?: true;
+} | {
+    kind: "kept";
+    reason: string;
 };
 /**
  * Non-mutating projection of {@link retireSessionTranscript}: would the
@@ -27,12 +55,8 @@ export type SessionRetirementOutcome = {
  * authority's verdict (containment, identity, artifact tree) is deliberately
  * not predicted here — it is re-derived against live state at delete time.
  */
-export declare function probeSessionRetirement(storage: FileSessionStorage, sessionsRoot: string, transcriptPath: string): {
-    kind: "retirable";
-} | {
-    kind: "kept";
-    reason: string;
-};
+export declare function probeSessionRetirement(storage: FileSessionStorage, sessionsRoot: string, transcriptPath: string, continuation?: SessionRetirementContinuation): Promise<SessionRetirementProbeOutcome>;
+export declare function retireOrphanSessionTranscript(storage: FileSessionStorage, sessionsRoot: string, continuation: SessionRetirementContinuation, receipt: ManagedGcSessionRetirementReceipt): Promise<SessionRetirementOutcome>;
 /**
  * Retire one managed session transcript through the verified hard-delete
  * authority.
@@ -44,4 +68,4 @@ export declare function probeSessionRetirement(storage: FileSessionStorage, sess
  * caller owns the retention policy; this function owns nothing but the delete
  * authority.
  */
-export declare function retireSessionTranscript(storage: FileSessionStorage, sessionsRoot: string, transcriptPath: string): Promise<SessionRetirementOutcome>;
+export declare function retireSessionTranscript(storage: FileSessionStorage, sessionsRoot: string, transcriptPath: string, continuation?: SessionRetirementContinuation): Promise<SessionRetirementOutcome>;