@gajae-code/coding-agent 0.18.6 → 0.18.8

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/bus/telegram-daemon.d.ts

@@ -9,6 +9,7 @@ import { type DaemonProcessReference } from "./telegram-daemon-control";
 import { type TelegramSetupPreflight } from "./telegram-setup";
 export { loadInstallationHostId, loadLegacyInstallationHostId, type MachineIdentityDeps, parseMacPlatformUuid, parseWindowsMachineGuid, } from "../../config/machine-identity";
 export { DAEMON_GENERATION, NOTIFICATION_EVENT_SCHEMA_VERSION, NOTIFICATION_PROTOCOL_VERSION, SDK_LIFECYCLE_ROUTER_PROTOCOL_VERSION, SERVING_EPOCH, TELEGRAM_TRANSPORT_GENERATION, } from "./telegram-daemon-contract";
+import { POSITIONED_NOTIFICATION_EFFECTS_CAPABILITY } from "../host/host";
 import { type AgentDirSessionLifecycleService } from "../lifecycle/client";
 import { type NotificationSubscription, type SessionRouterProviderDeps } from "../router/session-router";
 import { NotificationOperatorRuntime } from "./operator-runtime";
@@ -136,8 +137,8 @@ export declare const ASK_CONTROLS_CAPABILITY = "ask_controls_v1";
 export declare const TOOL_ACTIVITY_CAPABILITY = "tool_activity_v2";
 /** Receive-only compatibility capability for pre-v2 hosts. */
 export declare const LEGACY_TOOL_ACTIVITY_CAPABILITY = "tool_activity_v1";
-/** Opts notification adapters into positioned-only delivery for matching live effects. */
-export declare const POSITIONED_NOTIFICATION_EFFECTS_CAPABILITY = "positioned_notification_effects_v1";
+/** Public `sdk/bus/telegram-daemon` path for the canonical `sdk/host` capability token. */
+export { POSITIONED_NOTIFICATION_EFFECTS_CAPABILITY };
 /**
  * File-lock options whose acquisition budget covers the full reload-reservation
  * critical section: the in-lock freshness poll plus the controller's

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/host.d.ts

@@ -85,6 +85,12 @@ export declare const TOOL_ACTIVITY_CAPABILITY = "tool_activity_v2";
 export declare const TURN_STREAM_CAPABILITY = "turn_stream";
 /** Capability used by notification adapters that observe a host without owning its work. */
 export declare const SESSION_HOST_OBSERVER_CAPABILITY = "session_host_observer_v1";
+/**
+ * Opts notification adapters into positioned-only delivery for matching live
+ * effects: the host excludes a negotiating connection from the raw native leg
+ * of every frame its positioned envelope already reached.
+ */
+export declare const POSITIONED_NOTIFICATION_EFFECTS_CAPABILITY = "positioned_notification_effects_v1";
 export declare const CAP_GATED_FRAME_KINDS: ReadonlySet<string>;
 /** Keep live delivery and replay on one capability gate. */
 export declare function canDeliverSdkEvent(kind: string, capabilities: ReadonlySet<string> | undefined): 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;
@@ -181,6 +182,13 @@ export interface SessionRouterOptions {
     attachFilter?: (sessionId: string) => boolean;
     /** Marks default SDK clients as notification-only observers; demanding by default. */
     observer?: boolean;
+    /**
+     * Negotiates positioned-only notification effects on default SDK clients, so the
+     * host stops sending them the raw native copy of frames whose positioned
+     * envelope already reached them. Only notification-effect publishers opt in;
+     * ordinary SDK observers keep both public surfaces.
+     */
+    positionedNotificationEffects?: boolean;
     deps?: SessionRouterDeps;
     /** Runtime-specific identity validation; Router supplies a conservative fallback. */
     correlateFrame?: SessionRouterFrameCorrelator;
@@ -217,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);
+    }, policy?: ManagedSessionSecurityPolicy, profileAgentDir?: string, expectedSubtreeRoot?: ManagedDirectoryRoot, access?: "read-only" | "read-write");
     get dir(): string;
     get rootAuthority(): ManagedDirectoryRoot;
     get subtreeRootAuthority(): ManagedDirectoryRoot;
@@ -189,6 +207,11 @@ export declare class ManagedSessionDescendantStore {
     close(): void;
     assertBound(): void;
     verifyRootSecurity(): void;
+    /** Capture a directory identity through this store's retained managed root without repairing it. */
+    captureDirectoryIdentity(relativePath: string): {
+        dev: string;
+        ino: string;
+    };
     ensureDirectory(relativePath?: string): ManagedDirectoryRoot;
     publishNoReplace(relativePath: string, bytes: Uint8Array): Promise<void>;
     publishNoReplaceSync(relativePath: string, bytes: Uint8Array): void;
@@ -218,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. */
@@ -240,13 +267,21 @@ export declare class ManagedSessionDescendantStore {
         sourceStoreRelativePath: string;
     }): ManagedFileSnapshot;
     removeTreeExpected(relativePath: string, expected: NativeDirectoryTreeSnapshot): void;
+    /** Remove one exact managed tree through the parent-identity-bound native protocol. */
+    removeTreeExpectedWithParentIdentity(relativePath: string, expected: NativeDirectoryTreeSnapshot, parentIdentity: {
+        dev: bigint;
+        ino: bigint;
+    }): NativeExactUnlinkResult;
     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

@@ -0,0 +1,19 @@
+import type { NativeDirectoryTreeSnapshot } from "@gajae-code/natives";
+import { type TaskArtifactOwnerDeletionEvidence, type TaskArtifactOwnerLocator, type TaskArtifactOwnerStorageContext } from "../task-artifact-owner-codec";
+import { ManagedSessionDescendantStore } from "./managed-session-storage";
+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;
+export declare function openOwnerStore(context: TaskArtifactOwnerStorageContext, rootStore: ManagedSessionDescendantStore, locator: TaskArtifactOwnerLocator, sessionId: string): ManagedSessionDescendantStore;
+export declare function locatorFromManifest(manifest: OwnerManifest): TaskArtifactOwnerLocator;
+export declare function captureValidatedOwnerTree(context: TaskArtifactOwnerStorageContext, rootStore: ManagedSessionDescendantStore, sessionId: string, locator: TaskArtifactOwnerLocator): NativeDirectoryTreeSnapshot;
+export declare function captureOwnerTreeIfPresent(context: TaskArtifactOwnerStorageContext, rootStore: ManagedSessionDescendantStore, ownerId: string, pathname: string): NativeDirectoryTreeSnapshot | undefined;
+export declare function ownerTreeHasPendingManagedPublication(snapshot: NativeDirectoryTreeSnapshot): boolean;
+/** Capture exact owner evidence without repairing its security, timestamps, or namespace. */
+export declare function captureTaskArtifactOwnerDeletionEvidence(context: TaskArtifactOwnerStorageContext, sessionId: string, locatorValue: unknown): TaskArtifactOwnerDeletionEvidence | undefined;