@gajae-code/coding-agent 0.18.7 → 0.18.9

package/dist/types/sdk/broker/session-index.d.ts

@@ -192,10 +192,12 @@ export declare class SessionIndex {
      * stamp of the last completed locked pass, the in-memory projection is
      * already current and the locked rescan is skipped entirely — this is what
      * keeps an idle SessionRouter reconcile (2s cadence) from re-parsing and
-     * re-checksumming the whole index forever. An append committed before the
-     * stat always changes the stamp, so a miss is impossible; a change landing
-     * after the stat is seen on the next poll, the same TOCTOU envelope a
-     * locked read has. A corrupt suffix never takes the fast path: re-scanning
+     * re-checksumming the whole index forever. The unchanged check runs before
+     * the local queue so unrelated heartbeat work cannot delay ordinary creates.
+     * Admission that requires serialized authority must use refresh() instead.
+     * An append committed before the stat always changes
+     * the stamp; a change landing after the stat is seen on the next poll, the
+     * same TOCTOU envelope a locked read has. A corrupt suffix never takes the fast path: re-scanning
      * preserves the existing re-diagnosis behavior. Returns true when state was
      * reloaded. Authority revalidation that needs the strongest available
      * snapshot inside an already-locked write (append, unregister) keeps using
@@ -229,7 +231,11 @@ export declare class SessionIndex {
      * injected retention policy to a fresh snapshot and truncates the log.
      */
     compact(): Promise<void>;
-    listSessions(probedIncarnations?: ReadonlyMap<string, string | undefined>): SessionList;
+    /**
+     * Public session rows. `sessionIds` scopes the projection to those sessions:
+     * rows for them are identical to the unscoped read, other sessions are absent.
+     */
+    listSessions(probedIncarnations?: ReadonlyMap<string, string | undefined>, sessionIds?: ReadonlySet<string>): SessionList;
     /**
      * Credential-free proof for one exact public endpoint generation.
      *
@@ -274,7 +280,7 @@ export declare class SessionIndex {
      * while the broker was down keep their stale or missing heartbeat and read as
      * unknown/not-live (never fresh forever). Returns the number of checkpoints written.
      */
-    checkpointLiveHeartbeats(now?: number): Promise<number>;
+    checkpointLiveHeartbeats(now?: number, abortSignal?: AbortSignal, deadlineAt?: number): Promise<number>;
     hostUnregisteredAfter(registration: Pick<IndexedSession, "sessionId" | "locator" | "endpointGeneration" | "pid" | "indexSeq" | "lifecycleRequestId" | "hostIncarnation" | "processIncarnation" | "endpointFileId">): {
         indexSeq: number;
         lifecycleRequestId?: string;

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

@@ -17,7 +17,7 @@
  * Enable with Settings notifications config, `GJC_NOTIFICATIONS=1` (a token is
  * generated), or `GJC_NOTIFICATIONS_TOKEN`.
  */
-import { type RunSettlementProof } from "@gajae-code/agent-core";
+import { type AgentTerminalOwnerContext, type RunCancellationDomain, type RunSettlementProof } from "@gajae-code/agent-core";
 import type { Tool } from "@gajae-code/ai/core";
 import type { NotificationServer as NativeNotificationServer } from "@gajae-code/natives";
 type NotificationServer = NativeNotificationServer;
@@ -266,6 +266,15 @@ export declare class PresentationArbiter {
 interface SessionRuntime {
     server: NotificationServer;
     host: SessionSdkHost;
+    getJoinedPromptCorrelations: (owner: AgentTerminalOwnerContext) => Array<{
+        commandId: string;
+        turnId: string;
+    }>;
+    isPromptRunOwner: (correlation: {
+        commandId: string;
+        turnId: string;
+    }, owner: AgentTerminalOwnerContext) => boolean;
+    retireJoinedPromptOwners: () => void;
     /** Delivers one ring-positioned event envelope to every attached subscriber
      *  connection, applying the same capability gate as event replay. */
     broadcastEventFrame: (event: SdkFrame) => string[];
@@ -640,6 +649,8 @@ export declare function createNotificationsExtension(api: ExtensionAPI, options?
      * preflight outside the durable admission path (review thread P2).
      */
     terminalAbortSeams?: {
+        getTerminalRunOwnerForEvent?: (event: object) => AgentTerminalOwnerContext | undefined;
+        getRunOwnerDomain?: (handle: string) => RunCancellationDomain | undefined;
         getTerminalTurnEpoch: () => number | undefined;
         cancelPendingPreflightForTerminalAbort: () => void;
         captureTerminalAbortSteeringSnapshot?: () => void;

package/dist/types/sdk/bus/telegram-daemon-contract.d.ts

@@ -291,8 +291,13 @@ export declare const SDK_LIFECYCLE_ROUTER_PROTOCOL_VERSION = 1;
  * so generation-191 owners cannot reap hosts with queued or promoted work.
  * Generation 193 gates streamed content on negotiated observer capabilities,
  * so existing owners are replaced before exposing the new observer path.
+ * Generation 201 binds queued cancellation and terminal deadlines to the exact
+ * consuming run, so pre-fix owners cannot serve the new generic lifecycle path.
+ * Generation 202 joins queued-removal terminal publication before ordinary
+ * abort acknowledgement, replacing owners that still acknowledge cancellation
+ * before its terminal record is durable.
  */
-export declare const DAEMON_GENERATION = 200;
+export declare const DAEMON_GENERATION = 202;
 /**
  * Serving-compatibility boundary for daemon lifecycle requests. Epoch 7
  * requires durable publication receipts and acknowledged attachment dispatch,

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

@@ -58,6 +58,8 @@ export interface SdkClientOptions {
 }
 export interface SdkRequestOptions {
     timeoutMs?: number;
+    /** Absolute wall-clock deadline for this request, including connection setup. */
+    deadline?: number;
     idempotencyKey?: string;
     confirm?: boolean;
     /**

package/dist/types/sdk/host/query/handlers.d.ts

@@ -1,3 +1,4 @@
+import type { ProjectProgressSnapshot } from "../../../progress/progress-contract.js";
 import type { ActiveProviderDescriptor } from "../../providers.js";
 import { type CursorRegistry } from "./cursor.js";
 import type { RevisionStore } from "./revision-store.js";
@@ -33,6 +34,8 @@ export interface SessionSurface {
         totalBytes: number;
     } | undefined>;
     getJobs(): unknown | Promise<unknown>;
+    /** Q32 read-only project progress snapshot (`gjc.project_progress.v1`). */
+    getProjectProgress?(): ProjectProgressSnapshot | Promise<ProjectProgressSnapshot>;
     /** Q26 keyed lookup of a submitted prompt's authoritative reconciliation status. */
     getPromptStatus?(selector: {
         commandId?: string;

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

@@ -1,4 +1,5 @@
 export { MODEL_PROFILE_DISCOVERY_QUERY, MODEL_PROFILE_ERROR_DETAIL_MAX_BYTES, type ModelProfileCatalogItem, type ModelProfileErrorCode, type ModelProfileErrorDetails, ModelProfileRegistryError, type ModelProfileRegistryErrorDetails, type UnknownModelProfileDetails, UnknownModelProfileError, } from "../config/model-profile-contract";
+export { PROJECT_PROGRESS_SNAPSHOT_SCHEMA, type ProgressSnapshotAttention, type ProgressSnapshotStory, type ProgressSnapshotTodo, type ProgressSnapshotWorkflow, type ProjectProgressSnapshot, } from "../progress/progress-contract";
 export type { QueuedInputAdmission, QueuedInputDelivery, QueuedInputExecution, QueuedInputQueuePolicy, QueuedInputRemovalReason, QueuedInputSubmission, QueuedInputTerminal, SendUserMessageOptions, TrackedSendUserMessageOptions, } from "../session/agent-session";
 export * as bus from "./bus";
 export * from "./diagnostics/observe-broker";

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

@@ -112,6 +112,7 @@ export interface SessionRouterClient {
     connect?(): Promise<void>;
     request(frame: Record<string, unknown>, options?: {
         timeoutMs?: number;
+        deadline?: number;
         connectedOnly?: boolean;
         /** Synchronous pre-send observer; a throw aborts the dispatch before the wire. */
         beforeDispatch?: (context: SdkDispatchContext) => void;
@@ -224,6 +225,7 @@ export declare class SessionRouter {
     /** Sends an SDK command through the current attachment without exposing its client. */
     request(sessionId: string, frame: Record<string, unknown>, expectedGeneration?: number, expectedAttachment?: SessionAttachment, options?: {
         timeoutMs?: number;
+        deadline?: number;
         beforeDispatch?: (context: SdkDispatchContext) => void;
         onDispatch?: SdkDispatchHandler;
         dispatchFence?: (dispatch: () => Promise<Record<string, unknown>>) => Promise<Record<string, unknown>>;

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

@@ -1,6 +1,6 @@
 export type SessionListPageRecord = Record<string, unknown>;
 export type SessionListSavedSessionOmissionReason = "scope_unavailable" | "candidate_scan_failed" | "candidate_not_found" | "candidate_ambiguous" | "candidate_invalid" | "identity_incomplete";
-export declare const SESSION_LIST_SAVED_SESSION_OMISSION_DETAIL_CODES: readonly ["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", "scan_failed", "unsafe_root", "invalid_candidate", "invalid_header", "unreadable_candidate", "source_changed", "cwd_not_found", "cwd_not_utf8", "cwd_network_unsupported", "cwd_identity_unavailable", "cwd_io_error"];
+export declare const SESSION_LIST_SAVED_SESSION_OMISSION_DETAIL_CODES: readonly ["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", "scan_failed", "unsafe_root", "invalid_candidate", "invalid_header", "unreadable_candidate", "source_changed", "cwd_not_found", "cwd_not_utf8", "cwd_network_unsupported", "cwd_identity_unavailable", "cwd_io_error"];
 export type SessionListSavedSessionOmissionDetailCode = (typeof SESSION_LIST_SAVED_SESSION_OMISSION_DETAIL_CODES)[number];
 /** Path-free diagnostic for a requested managed transcript that could not be selected safely. */
 export interface SessionListSavedSessionOmission {

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;