@gajae-code/coding-agent 0.18.5 → 0.18.7

package/dist/types/sdk/diagnostics/observe-broker.d.ts

@@ -0,0 +1,185 @@
+/**
+ * Observation-only broker diagnostics facade (SPEC "Result contract").
+ *
+ * The publication is read ONLY through the approved read-only native lease
+ * (`loadDiagnosticNativeReadOnly` -> `openDiagnosticSnapshot` -> bounded read ->
+ * revalidate -> close), so every ancestor ACL/owner/mode and filesystem check of the
+ * earlier slices governs this route too. Ordinary discovery is deliberately not used: it
+ * would bypass that gate. An unsupported runtime tuple or artifact resolves to
+ * `unsupported` BEFORE any publication access. The facade then opens exactly ONE client
+ * connection with no reconnect attempts, asks the broker for its published diagnostics
+ * and returns a detached frozen snapshot. It never ensures, starts, recovers, retires or spawns
+ * anything, never touches the session index, ledger or evidence store, and never hands
+ * the caller a token, socket coordinate, path, pid or environment value.
+ */
+/** Allowed unavailability reasons; messages are fixed literals keyed by the enum. */
+export type BrokerObservationUnavailableReason = "absent" | "stale" | "incompatible" | "authentication_failed" | "unsupported" | "generation_mismatch" | "transport_unavailable" | "timeout" | "invalid_response" | "unsafe_discovery";
+export interface BrokerObservationBuild {
+    readonly packageVersion: string;
+    readonly buildId: string | null;
+}
+export interface BrokerObservationSuccess {
+    readonly schema: "gjc.broker-observation";
+    readonly version: 1;
+    readonly ok: true;
+    readonly observedAt: string;
+    readonly broker: {
+        readonly generation: string;
+        readonly build: BrokerObservationBuild;
+        readonly diagnosticProtocol: 1;
+    };
+}
+export interface BrokerObservationUnavailable {
+    readonly schema: "gjc.broker-observation";
+    readonly version: 1;
+    readonly ok: false;
+    readonly observedAt: string;
+    readonly unavailable: {
+        readonly reason: BrokerObservationUnavailableReason;
+        readonly message: string;
+    };
+}
+export type BrokerObservation = BrokerObservationSuccess | BrokerObservationUnavailable;
+export interface ObserveExistingBrokerOptions {
+    readonly agentDir: string;
+    readonly expectedGeneration?: string;
+    readonly timeoutMs?: number;
+}
+/** The broker's published diagnostics operation. */
+export declare const BROKER_DIAGNOSTICS_OPERATION = "broker.diagnostics";
+/** The only diagnostic protocol this client understands. */
+export declare const BROKER_DIAGNOSTIC_PROTOCOL = 1;
+/** Contract timeout: default 2000 ms, accepted range 1..10000 ms. */
+export declare const OBSERVATION_TIMEOUT_DEFAULT_MS = 2000;
+export declare const OBSERVATION_TIMEOUT_MIN_MS = 1;
+export declare const OBSERVATION_TIMEOUT_MAX_MS = 10000;
+export declare function setObservationClockForTest(clock: (() => number) | null): void;
+/**
+ * Test-only observers for the native stage boundary. Production installs none, and the
+ * hooks never change a branch, a budget or an outcome: they only report what the
+ * observation did (`onNativeOpen`) and give a test a point to disturb the environment
+ * between the first publication read and the connection (`afterInitialRead`), which is how
+ * the pre-socket identity recheck is proven instead of argued.
+ */
+export interface ObservationTestHooks {
+    onNativeOpen?: (info: {
+        agentDir: string;
+        budgetMs: number;
+    }) => void;
+    afterInitialRead?: () => void;
+    /** Reports that the retained lease was released, on every exit path. */
+    onLeaseClosed?: () => void;
+    /**
+     * Decorates the retained lease so a test can identify the real operation phases and make
+     * a chosen phase refuse or throw. Production installs none.
+     */
+    wrapLease?: (lease: DiagnosticSnapshotLease) => DiagnosticSnapshotLease;
+    /** Replaces the loader result so loader-stage outcomes can be observed deterministically. */
+    loaderOverride?: () => DiagnosticNativeLoad;
+}
+/** Minimal shapes this facade relies on from the approved read-only loader. */
+interface DiagnosticSnapshotRead {
+    readonly ok: boolean;
+    readonly reason?: string | null;
+    readonly bytes?: Uint8Array | null;
+}
+interface DiagnosticSnapshotStatus {
+    readonly ok: boolean;
+    readonly reason?: string | null;
+}
+interface DiagnosticSnapshotLease {
+    readonly ok: boolean;
+    readonly reason?: string | null;
+    read(): DiagnosticSnapshotRead;
+    revalidate(): DiagnosticSnapshotStatus;
+    close(): void;
+}
+type DiagnosticNativeLoad = {
+    ok: true;
+    value: {
+        openDiagnosticSnapshot(agentDir: string, budgetMs: number): DiagnosticSnapshotLease;
+    };
+} | {
+    ok: false;
+    reason: string;
+};
+export declare function setObservationTestHooksForTest(hooks: ObservationTestHooks | null): void;
+/** Malformed arguments are a typed caller error, never an observed unavailability. */
+export declare class DiagnosticOptionsError extends Error {
+    readonly code: "invalid_arguments";
+    readonly field: string;
+    constructor(field: string);
+}
+export type ObservationOptionsVerdict = {
+    ok: true;
+    value: {
+        agentDir: string;
+        expectedGeneration?: string;
+        timeoutMs: number;
+    };
+} | {
+    ok: false;
+    error: {
+        code: "invalid_arguments";
+        field: string;
+    };
+};
+/** Validate the caller's options against the exact contract. Pure and total. */
+export declare function validateObservationOptions(options: unknown): ObservationOptionsVerdict;
+/** Whether the endpoint is the canonical owned loopback endpoint with an in-range port. */
+export declare function canonicalLoopbackEndpoint(url: string): boolean;
+/**
+ * Parse verdicts for the publication bytes. A publication that is well formed but
+ * carries no diagnostic capability is NOT malformed: an old broker like that is
+ * `unsupported`, never `invalid_response` and never `absent`.
+ */
+export type PublicationVerdict = {
+    kind: "ok";
+    value: ObservedPublication;
+} | {
+    kind: "no-capability";
+} | {
+    kind: "malformed";
+};
+/** The publication fields this route reads; every other field is ignored, never trusted. */
+export interface ObservedPublication {
+    readonly url: string;
+    readonly token: string;
+    readonly ownerId: string;
+    readonly pid: number;
+    readonly incarnation: string | null;
+    readonly agentRoot: string | null;
+    readonly generation: string;
+    readonly diagnosticProtocol: number;
+}
+/** Parse the publication bytes the native lease returned. Strict, bounded, total. */
+export declare function parsePublicationVerdict(bytes: Uint8Array): PublicationVerdict;
+/** Convenience wrapper for callers that only need the accepted shape. */
+export declare function parsePublication(bytes: Uint8Array): ObservedPublication | null;
+/** The exact answered payload this client accepts; unknown fields are refused. */
+interface AnsweredDiagnostics {
+    readonly generation: string;
+    readonly build: BrokerObservationBuild;
+    readonly identity: {
+        readonly ownerId: string;
+        readonly pid: number;
+        readonly agentRoot: string;
+    };
+}
+/** Strictly validate the broker's answer, mapping every refusal onto the reason enum. */
+export declare function parseAnsweredDiagnostics(response: unknown): {
+    kind: "ok";
+    value: AnsweredDiagnostics;
+} | {
+    kind: "unavailable";
+    reason: BrokerObservationUnavailableReason;
+};
+/** Two publication observations describe the same authority. */
+export declare function sameAuthority(first: ObservedPublication, second: ObservedPublication): boolean;
+/** The broker's answer agrees with the publication on generation and identity. */
+export declare function answerMatchesAuthority(answer: AnsweredDiagnostics, publication: ObservedPublication): boolean;
+/**
+ * Observe an already running broker. Never starts, ensures, recovers or retires one.
+ */
+export declare function observeExistingBroker(options: ObserveExistingBrokerOptions | unknown): Promise<BrokerObservation>;
+export {};

package/dist/types/sdk/host/control/operations.d.ts

@@ -20,7 +20,7 @@ export type ControlInput = Record<string, unknown>;
  */
 export interface ControlSurface {
     prompt(text: string, images?: ControlValue, clientRef?: string): Promise<ControlValue> | ControlValue;
-    steer(text: string, clientRef?: string): Promise<ControlValue> | ControlValue;
+    steer(text: string, clientRef?: string, expectedSdkRunToken?: string): Promise<ControlValue> | ControlValue;
     followUp(text: string): Promise<ControlValue> | ControlValue;
     abort(): Promise<ControlValue> | ControlValue;
     /** Terminal abort: stop the current root turn (and optionally exact owned work). */

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

@@ -1,6 +1,7 @@
 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 type { QueuedInputAdmission, QueuedInputDelivery, QueuedInputExecution, QueuedInputQueuePolicy, QueuedInputRemovalReason, QueuedInputSubmission, QueuedInputTerminal, SendUserMessageOptions, TrackedSendUserMessageOptions, } from "../session/agent-session";
 export * as bus from "./bus";
+export * from "./diagnostics/observe-broker";
 export * as host from "./host";
 export * as lifecycle from "./lifecycle";
 export * as mcp from "./mcp";

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

@@ -177,8 +177,17 @@ export interface SessionRouterOptions {
     agentDir: string;
     /** Limits attachment to exact ids selected by a Broker-scoped operation. */
     sessionIds?: readonly string[];
+    /** Dynamically limits attachment to sessions currently owned by the caller. */
+    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;

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

@@ -188,6 +188,12 @@ export interface CreateAgentSessionOptions {
      * @internal CLI-only ordering guard; SDK callers retain immediate startup by default.
      */
     deferMemoryBackendStartup?: boolean;
+    /**
+     * Skip optional model-catalog discovery during lifecycle startup. ACP hosts must
+     * publish their endpoint before unrelated provider credential refreshes begin.
+     * @internal lifecycle-only startup guard.
+     */
+    deferOptionalModelRefresh?: boolean;
     /** Enable LSP integration (tool, formatting, diagnostics, warmup). Default: true */
     enableLsp?: boolean;
     /** Skip Python kernel availability check and prelude warmup */
@@ -297,6 +303,13 @@ export interface CreateAgentSessionResult {
      */
     gjcRuntimeSnapshot?: GjcRuntimeSnapshotProvider;
 }
+/**
+ * Start optional provider/model discovery only when it is safe to add work to
+ * the caller's startup graph. Lifecycle hosts deliberately skip this during
+ * construction: discovery preflights every configured provider and may refresh
+ * an unrelated OAuth credential while several hosts are opening the same DB.
+ */
+export declare function startOptionalModelRefresh(modelRegistry: Pick<ModelRegistry, "refreshInBackground">, credentialSessionId: string | undefined, deferred: boolean): boolean;
 export interface DeferredMcpConfigStartupResult {
     loadedToolCount: number;
     hasErrors: boolean;

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

@@ -1111,7 +1111,11 @@ export declare class AgentSession {
     get sessionWorkLease(): SessionWorkLease;
     /** Stable resource ownership identifier for the active prompt run. */
     get activePromptHandle(): string | undefined;
-    /** All messages including custom types like BashExecutionMessage */
+    /**
+     * All messages including custom types like BashExecutionMessage. Request-scoped
+     * ephemeral copies are retained only in `agent.state.messages` to keep the provider
+     * cache prefix stable; they are never part of this public view.
+     */
     get messages(): AgentMessage[];
     get transcriptPromptGeneration(): number;
     static restoreFromMemoryGuardCheckpoint(input: AgentSessionMemoryGuardRestoreInput): Promise<AgentMemoryGuardRestoreResult>;

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

@@ -174,7 +174,7 @@ export declare class ManagedSessionDescendantStore {
     constructor(root: ManagedDirectoryRoot, baseDir: string, retained?: {
         authority: RecoveryFsRoot;
         authorityBaseDir: string;
-    }, policy?: ManagedSessionSecurityPolicy, profileAgentDir?: string);
+    }, policy?: ManagedSessionSecurityPolicy, profileAgentDir?: string, expectedSubtreeRoot?: ManagedDirectoryRoot);
     get dir(): string;
     get rootAuthority(): ManagedDirectoryRoot;
     get subtreeRootAuthority(): ManagedDirectoryRoot;
@@ -189,6 +189,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;
@@ -240,6 +245,11 @@ 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;

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

@@ -0,0 +1,17 @@
+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;
+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;

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

@@ -0,0 +1,3 @@
+import { type TaskArtifactOwnerLocator } from "../task-artifact-owner-codec";
+/** Resolve the path-free owner locator using transcript replay's header-patch semantics. */
+export declare function taskArtifactOwnerLocatorFromTranscriptBytes(bytes: Uint8Array, expectedSessionId: string): TaskArtifactOwnerLocator | undefined;

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

@@ -0,0 +1,47 @@
+import { type FileSessionStorage } from "./session-storage";
+/**
+ * Outcome of a disk-retention retirement attempt.
+ *
+ * `kept` means the transcript survived and nothing of the session was
+ * destroyed, with the exact reason so `gjc gc --disk` can report it.
+ * `cleanup_pending` means the delete authority already detached or removed the
+ * session's artifact tree (or quarantined the transcript) before it stopped:
+ * the record survives, the session does not, and a caller must NOT report that
+ * as an ordinary keep.
+ */
+export type SessionRetirementOutcome = {
+    kind: "retired";
+} | {
+    kind: "kept";
+    reason: string;
+} | {
+    kind: "cleanup_pending";
+    reason: string;
+};
+/**
+ * Non-mutating projection of {@link retireSessionTranscript}: would the
+ * retention pass's own preconditions let this transcript be retired at all?
+ *
+ * `gjc gc --disk` runs it so a dry run reports the verdict a prune would reach
+ * instead of promising bytes the delete authority will refuse to release. The
+ * 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;
+};
+/**
+ * Retire one managed session transcript through the verified hard-delete
+ * authority.
+ *
+ * This is the only supported way for a retention pass to remove a transcript:
+ * identity, containment, header id/cwd, artifact tree and parent directory are
+ * all re-verified inside {@link FileSessionStorage.deleteSessionVerified}, and
+ * anything ambiguous fails closed as `kept` rather than deleting bytes. The
+ * 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>;

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

@@ -512,50 +512,4 @@ export declare class MemorySessionStorage implements SessionStorage {
     openBufferedWriter(path: string, options?: SessionStorageWriterOpenOptions): SessionStorageBufferedWriter;
     openStagedWriter(path: string): StagedStreamingWriter;
 }
-/**
- * Outcome of a disk-retention retirement attempt.
- *
- * `kept` means the transcript survived and nothing of the session was
- * destroyed, with the exact reason so `gjc gc --disk` can report it.
- * `cleanup_pending` means the delete authority already detached or removed the
- * session's artifact tree (or quarantined the transcript) before it stopped:
- * the record survives, the session does not, and a caller must NOT report that
- * as an ordinary keep.
- */
-export type SessionRetirementOutcome = {
-    kind: "retired";
-} | {
-    kind: "kept";
-    reason: string;
-} | {
-    kind: "cleanup_pending";
-    reason: string;
-};
-/**
- * Non-mutating projection of {@link retireSessionTranscript}: would the
- * retention pass's own preconditions let this transcript be retired at all?
- *
- * `gjc gc --disk` runs it so a dry run reports the verdict a prune would reach
- * instead of promising bytes the delete authority will refuse to release. The
- * 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;
-};
-/**
- * Retire one managed session transcript through the verified hard-delete
- * authority.
- *
- * This is the only supported way for a retention pass to remove a transcript:
- * identity, containment, header id/cwd, artifact tree and parent directory are
- * all re-verified inside {@link FileSessionStorage.deleteSessionVerified}, and
- * anything ambiguous fails closed as `kept` rather than deleting bytes. The
- * 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 {};

package/dist/types/session/session-transcript-header.d.ts

@@ -0,0 +1,2 @@
+/** Parse the first JSONL line as a generic record; returns undefined on parse failure. */
+export declare function parseFirstJsonlLine(bytes: Uint8Array): Record<string, unknown> | undefined;

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

@@ -0,0 +1,107 @@
+import type { NativeExactUnlinkResult } from "@gajae-code/natives";
+import type { ManagedDirectoryRoot, ManagedSessionSecurityPolicy } from "./internal/managed-session-storage";
+import type { NativeDirectoryTreeSnapshot } from "./session-storage";
+export declare const OWNER_DIRECTORY = ".task-artifact-owners";
+export declare const OWNER_LOCK_DIRECTORY = ".task-artifact-owner-locks";
+export declare const OWNER_MANIFEST = ".gjc-task-artifact-owner-v1.json";
+export declare const OWNER_SCHEMA_VERSION: 1;
+export declare const OWNER_DELETION_SCHEMA_VERSION: 2;
+export declare const OWNER_RETIREMENT_SCHEMA_VERSION: 1;
+export declare const EMPTY_PAYLOAD_SHA256: string;
+export interface TaskArtifactOwnerLocator {
+    readonly schemaVersion: typeof OWNER_SCHEMA_VERSION;
+    readonly ownerId: string;
+    readonly directoryDev: string;
+    readonly directoryIno: string;
+}
+export interface TaskArtifactOwnerStorageContext {
+    readonly rootAuthority: ManagedDirectoryRoot;
+    readonly sessionsRoot: string;
+    readonly securityPolicy: ManagedSessionSecurityPolicy;
+    readonly profileAgentDir: string;
+}
+/** Exact parent directory identity authorizing direct native owner-tree removal. */
+export interface TaskArtifactOwnerParentIdentity {
+    readonly dev: string;
+    readonly ino: string;
+}
+/** Immutable exact deletion input retained by managed lifecycle tombstones and retries. */
+export interface TaskArtifactOwnerDeletionEvidence {
+    readonly schemaVersion: typeof OWNER_DELETION_SCHEMA_VERSION;
+    readonly sessionId: string;
+    readonly locator: TaskArtifactOwnerLocator;
+    readonly parentIdentity: TaskArtifactOwnerParentIdentity;
+    readonly treeSnapshot: NativeDirectoryTreeSnapshot;
+}
+/** Native retained-root and side-path state safe to persist for a later retirement attempt. */
+export interface TaskArtifactOwnerRetirementContinuation {
+    readonly schemaVersion: typeof OWNER_RETIREMENT_SCHEMA_VERSION;
+    /** Must remain equal to the immutable evidence's managed owner-parent identity. */
+    readonly parentIdentity: TaskArtifactOwnerParentIdentity;
+    /** Only the original owner root or its native `.removing` sibling is actionable. */
+    readonly retainedRootPath: string;
+    /** Last identity-checked tree snapshot; it may only shrink from the original evidence. */
+    readonly retainedTreeSnapshot: NativeDirectoryTreeSnapshot;
+    /** Historical exact native detached-root roles; these paths are diagnostics, not extra authority. */
+    readonly detachedPaths?: readonly string[];
+    readonly nativeCodes?: readonly string[];
+    readonly payloadDurable?: boolean;
+    readonly retainedSuccessorPaths?: readonly string[];
+    readonly retainedPlaceholderPaths?: readonly string[];
+    readonly retainedUnknownPaths?: readonly string[];
+    readonly windowsErrorCodes?: readonly string[];
+}
+/** `completed` is decoded persisted data, not proof of physical retirement or writer closure. */
+export type TaskArtifactOwnerRetirementOutcome = {
+    readonly kind: "completed";
+    readonly evidence: TaskArtifactOwnerDeletionEvidence;
+    readonly nativeOutcome?: NativeExactUnlinkResult;
+} | {
+    /** Live payload is durably destroyed; native namespace cleanup remains pending. */
+    readonly kind: "payload_retired";
+    readonly namespace: "retained";
+    readonly evidence: TaskArtifactOwnerDeletionEvidence;
+    readonly continuation: TaskArtifactOwnerRetirementContinuation;
+    readonly nativeOutcome: NativeExactUnlinkResult;
+} | {
+    /** Native explicitly retained cleanup state with a validated, non-expanding continuation. */
+    readonly kind: "cleanup_pending";
+    readonly evidence: TaskArtifactOwnerDeletionEvidence;
+    readonly continuation: TaskArtifactOwnerRetirementContinuation;
+    readonly nativeOutcome?: NativeExactUnlinkResult;
+} | {
+    /** No safe completion proof exists; callers must retain evidence and continuation. */
+    readonly kind: "uncertain";
+    readonly evidence: TaskArtifactOwnerDeletionEvidence;
+    readonly continuation: TaskArtifactOwnerRetirementContinuation;
+    readonly reason: string;
+    readonly nativeOutcome?: NativeExactUnlinkResult;
+};
+/** True only for canonical unsigned decimal strings within the native u64 range. */
+export declare function isCanonicalDecimal(value: unknown): value is string;
+export declare function isCanonicalNativeId(value: unknown): value is string;
+/** Deterministic owner identity bound to one non-empty logical session ID. */
+export declare function ownerIdForSession(sessionId: string): string;
+export declare function ownerRelativePath(ownerId: string): string;
+export declare function manifestRelativePath(ownerId: string): string;
+export declare function assertSafeRelativePath(relativePath: string): void;
+export declare function assertSessionRoot(context: TaskArtifactOwnerStorageContext): void;
+export declare function freezeTreeSnapshot(snapshot: NativeDirectoryTreeSnapshot): NativeDirectoryTreeSnapshot;
+export declare function retainedTreeDoesNotExpandAuthority(expected: NativeDirectoryTreeSnapshot, retained: NativeDirectoryTreeSnapshot): boolean;
+export declare function sameTreeContents(left: NativeDirectoryTreeSnapshot, right: NativeDirectoryTreeSnapshot): boolean;
+export declare function sameOwnerParentIdentity(left: TaskArtifactOwnerParentIdentity, right: TaskArtifactOwnerParentIdentity): boolean;
+export declare function immutableDeletionEvidence(sessionId: string, locatorValue: TaskArtifactOwnerLocator, parentIdentityValue: TaskArtifactOwnerParentIdentity, treeSnapshotValue: NativeDirectoryTreeSnapshot): TaskArtifactOwnerDeletionEvidence;
+/** Parse a persisted locator. Missing metadata returns undefined; malformed metadata fails closed. */
+export declare function parseTaskArtifactOwnerLocator(value: unknown): TaskArtifactOwnerLocator | undefined;
+/** Validate JSON-restored tombstone evidence before it is used for exact retirement. */
+export declare function parseTaskArtifactOwnerDeletionEvidence(value: unknown): TaskArtifactOwnerDeletionEvidence;
+export declare function ownerAbsolutePath(context: TaskArtifactOwnerStorageContext, ownerId: string): string;
+export declare function isOwnerRetainedRoot(context: TaskArtifactOwnerStorageContext, ownerId: string, pathname: string): boolean;
+export declare function isKnownNativeSidePath(context: TaskArtifactOwnerStorageContext, ownerId: string, pathname: string): boolean;
+/** Validate JSON-restored native continuation data against immutable owner authorization. */
+export declare function parseTaskArtifactOwnerRetirementContinuation(context: TaskArtifactOwnerStorageContext, evidenceValue: TaskArtifactOwnerDeletionEvidence, value: unknown): TaskArtifactOwnerRetirementContinuation;
+/**
+ * Strictly decode persisted managed-journal data. Parsing does not establish current physical retirement,
+ * payload destruction, or writer quiescence.
+ */
+export declare function parseTaskArtifactOwnerRetirementOutcome(context: TaskArtifactOwnerStorageContext, evidence: TaskArtifactOwnerDeletionEvidence, value: unknown): TaskArtifactOwnerRetirementOutcome;

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

@@ -0,0 +1,7 @@
+import { type TaskArtifactOwnerDeletionEvidence, type TaskArtifactOwnerRetirementContinuation, type TaskArtifactOwnerRetirementOutcome, type TaskArtifactOwnerStorageContext } from "./task-artifact-owner-codec";
+/** Confirm physical completion from a managed native proof, never from canonical absence alone. */
+export declare function verifyTaskArtifactOwnerPhysicalRetirement(context: TaskArtifactOwnerStorageContext, evidence: TaskArtifactOwnerDeletionEvidence, value: unknown): void;
+/** Revalidate a persisted remnant through managed authority without mutation or new payload proof. */
+export declare function verifyTaskArtifactOwnerRetirementContinuation(context: TaskArtifactOwnerStorageContext, evidenceValue: TaskArtifactOwnerDeletionEvidence, value: unknown): TaskArtifactOwnerRetirementContinuation;
+/** Continue exact native removal without widening the original owner-tree authority. */
+export declare function retireTaskArtifactOwner(context: TaskArtifactOwnerStorageContext, evidenceValue: TaskArtifactOwnerDeletionEvidence, continuationValue?: unknown): TaskArtifactOwnerRetirementOutcome;

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

@@ -0,0 +1,10 @@
+import { ArtifactManager } from "./artifacts";
+import { type TaskArtifactOwnerLocator, type TaskArtifactOwnerStorageContext } from "./task-artifact-owner-codec";
+export interface ManagedTaskArtifactOwner {
+    readonly locator: TaskArtifactOwnerLocator;
+    readonly manager: ArtifactManager;
+}
+/** Reopen an owner only beneath the captured managed sessions-root authority. */
+export declare function restoreManagedTaskArtifactOwner(context: TaskArtifactOwnerStorageContext, sessionId: string, locatorValue: unknown): ManagedTaskArtifactOwner;
+/** Establish or restore the logical-session owner under the captured managed sessions authority. */
+export declare function ensureManagedTaskArtifactOwner(context: TaskArtifactOwnerStorageContext, sessionId: string, locatorValue: unknown, legacyArtifactRelativePath?: string): Promise<ManagedTaskArtifactOwner>;