dsh-pause-session 0.0.0-stage → 0.2.0

package/lib/types/park-state.d.ts

@@ -0,0 +1,51 @@
+/**
+ * One session's park episode: the durable phase writes, the activity walk that
+ * settles them, and the press/release lifecycle. The control composes this with
+ * the aggregate, the resume path, and the decision list.
+ * @module dsh-pause-session/park-state
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import { SessionId } from '@deepseek-ai/dsh-session';
+import type { PauseGate } from './gate.js';
+import type { LivePark, PressResult } from './global.js';
+import type { ParkWatch } from './park.js';
+import type { ParkRegistry } from './registry.js';
+import type { ParkPhase, PauseAnswer } from './shared.js';
+/** One session's park in progress. */
+export interface ParkMark {
+    /** The phase the durable registry confirms for this session. */
+    phase: ParkPhase;
+    /** Generation of the attempt that owns this mark. */
+    generation: number;
+    /** Whether this mark is a live press or a record adopted at mount. */
+    origin: 'press' | 'registry';
+    /** Whether a settle attempt is already walking this mark. */
+    advancing: boolean;
+}
+/** The park lifecycle the session control composes. */
+export interface ParkState {
+    readonly marks: Map<SessionId, ParkMark>;
+    readonly unrecorded: Set<SessionId>;
+    readonly unheld: Set<SessionId>;
+    subscribe(listener: () => void): () => void;
+    notify(): void;
+    press(sessionId: SessionId, signal?: AbortSignal, knownResumable?: boolean): Promise<PressResult>;
+    /** Adopt one durable record as a mark that never advances in this process. */
+    adopt(sessionId: SessionId, phase: ParkPhase): void;
+    look(sessionId: SessionId): void;
+    drop(sessionId: SessionId): void;
+    sync(sessionId: SessionId): void;
+    release(sessionId: SessionId, text: string): Promise<PauseAnswer>;
+    markUnrecorded(sessionId: SessionId, unrecorded: boolean): void;
+    live(): Map<SessionId, LivePark>;
+    cleanup(): void;
+}
+/**
+ * Mount the park episode state machine over the gate, registry, and activity fold.
+ * @param ctx - host context carrying the session store and logger.
+ * @param gate - the pause gate this state drives.
+ * @param registry - the durable pause list every phase write goes to.
+ * @param watch - the activity fold the park predicate reads.
+ * @returns the park lifecycle the control composes.
+ */
+export declare function installParkState(ctx: Context, gate: PauseGate, registry: ParkRegistry, watch: ParkWatch): ParkState;

package/lib/types/park.d.ts

@@ -0,0 +1,50 @@
+/**
+ * What a session is doing between "pause was asked for" and "its next model
+ * request is standing still at the gate".
+ *
+ * Two facts decide that, and each has its own owner:
+ *
+ * - Whether a turn is open is derived state the harness already maintains:
+ *   the agent registry owns the `turnBoundary` session projection, which folds
+ *   `turn/start`, `turn/end`, `step/start`, and `step/end` into
+ *   `openTurnStartSeq`. Reading it through `ctx.agents` is a synchronous
+ *   projection read, not a scan of the event log (synchronous history reads are
+ *   prohibited for new code).
+ * - Which tool is in flight is a log-derived per-session fact, so it is a
+ *   session projection too. The projection folds each committed
+ *   `tool/call` → `tool/result` pairing and keeps the calls in order; the
+ *   framework owns replay, caching, and disposal. This module listens only to
+ *   committed events so it can wake the control, never to keep a second copy
+ *   of the state itself.
+ * @module dsh-pause-session/park
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { SessionId } from '@deepseek-ai/dsh-session';
+/** One session's current activity, as the control reports it. */
+export interface ParkActivity {
+    /** Whether the session is inside a turn — including one waiting for this very park. */
+    readonly turnOpen: boolean;
+    /** Names of the calls currently in flight, in call order; empty when no tool is running. */
+    readonly runningTools: readonly string[];
+}
+/** Both halves of the activity question for one session. */
+export interface ParkWatch {
+    /**
+     * @param sessionId - session to inspect.
+     * @returns the session's current turn and tool activity.
+     */
+    activity(sessionId: SessionId): ParkActivity;
+    /**
+     * Subscribe to activity changes.
+     * @param listener - called with the session whose activity changed; it must
+     * only record that a look is owed, never re-enter the session.
+     * @returns the unsubscribe function.
+     */
+    onChange(listener: (sessionId: SessionId) => void): () => void;
+}
+/**
+ * Mount the per-session activity projection and its notification edge.
+ * @param ctx - host context carrying the session store and the projection registry.
+ * @returns the watch the park state is derived from.
+ */
+export declare function mountParkWatch(ctx: Context): Promise<ParkWatch>;

package/lib/types/registry.d.ts

@@ -0,0 +1,117 @@
+/**
+ * The durable park registry: which sessions are paused, and how cleanly each
+ * one stopped.
+ *
+ * The registry lives in the profile's storage — `ctx.storageDomain`, the
+ * schema-validated domain data form over whichever backend the composition
+ * routes it to — and never in the session log: a pause is not part of a
+ * session's history, and the list has to be readable by a process that has not
+ * opened any session yet. The domain's own backend route is configuration, so
+ * this module names no path and performs no IO of its own.
+ *
+ * The domain keeps the DEFAULT whole-unit layout on purpose. The per-record
+ * layout reads a malformed or stale record document as an absent record, which
+ * here would silently drop one paused session; a whole-unit file turns any
+ * corruption into a failed `open`, and a failed open fails the plugin's mount
+ * loudly instead of resuming everything.
+ * @module dsh-pause-session/registry
+ */
+import { z } from 'zod';
+import type { Context } from '@deepseek-ai/cordis';
+import type { SessionId } from '@deepseek-ai/dsh-session';
+import type { ParkPhase } from './shared.js';
+/** Domain and backend-unit name; one document per profile under the storage root. */
+export declare const PARK_REGISTRY_DOMAIN = "pause_registry";
+/** One session's stored park outcome. */
+export declare const parkRecord: z.ZodObject<{
+    phase: z.ZodEnum<{
+        draining: "draining";
+        parking: "parking";
+        safe: "safe";
+        "flush-failed": "flush-failed";
+    }>;
+    updatedAt: z.ZodNumber;
+    rearmGoal: z.ZodDefault<z.ZodBoolean>;
+}, z.core.$strip>;
+/** One session's stored park outcome. */
+export type ParkRecord = z.infer<typeof parkRecord>;
+/**
+ * The registry declaration. `version: 1` and no `compatibleVersions`: the
+ * domain layer rejects a stored unit stamped with any other version rather than
+ * migrating it, so an unrecognized registry fails loud at open. Validation is
+ * the rejecting default for the same reason — a record this build cannot read
+ * must stop the mount, not disappear from the list.
+ */
+export declare const parkRegistryDomain: {
+    name: string;
+    version: number;
+    tables: {
+        sessions: import("@deepseek-ai/dsh-storage-domain").DomainTableSpec<SessionId, {
+            phase: "draining" | "parking" | "safe" | "flush-failed";
+            updatedAt: number;
+            rearmGoal: boolean;
+        }>;
+    };
+};
+/** One session the registry remembers. */
+export interface ParkedSession {
+    readonly sessionId: SessionId;
+    readonly phase: ParkPhase;
+    /** When the phase was written. */
+    readonly updatedAt: number;
+    /** Whether resuming this session may re-arm its goal; see {@link parkRecord}. */
+    readonly rearmGoal: boolean;
+}
+/** The durable pause list, opened over the profile's storage. */
+export interface ParkRegistry {
+    /**
+     * @returns every remembered session, in insertion order.
+     */
+    list(): readonly ParkedSession[];
+    /**
+     * The same list as {@link list}, as a lazily kept read-only view.
+     *
+     * The whole-app aggregate and the decision list read this once per status
+     * read, and a status read can happen on every native-stream notification; the
+     * view is rebuilt only when the stored entries actually changed, so a read
+     * that changes nothing does not build a second copy of the list to look at.
+     * A caller must not mutate it.
+     */
+    readonly parked: ReadonlyMap<SessionId, ParkedSession>;
+    /**
+     * @param sessionId - session to look up.
+     * @returns the remembered session, or `undefined` when nothing is parked under that id.
+     */
+    get(sessionId: SessionId): ParkedSession | undefined;
+    /**
+     * Write one session's outcome; resolves once it is durable. The goal opt-out
+     * already recorded for that session survives a phase change — the phases of
+     * one park episode all describe the same parked session.
+     * @param sessionId - the session being parked.
+     * @param phase - how far the park has got.
+     */
+    record(sessionId: SessionId, phase: ParkPhase): Promise<void>;
+    /**
+     * Set one session's goal opt-out; resolves once it is durable.
+     * @param sessionId - the parked session to change.
+     * @param rearmGoal - whether the clean resume path may re-arm its goal.
+     * @throws when no record exists for that session — the flag describes a
+     * parked session, and inventing a record would invent a park.
+     */
+    setRearmGoal(sessionId: SessionId, rearmGoal: boolean): Promise<void>;
+    /**
+     * Drop one session from the list, so a later process does not re-hold it.
+     * @param sessionId - the session being released.
+     */
+    forget(sessionId: SessionId): Promise<void>;
+}
+/**
+ * Open the registry over the mounted storage. The caller owns the handle's
+ * lifetime; this registers the close as an effect on `ctx`, so the unit is
+ * released with the plugin.
+ * @param ctx - plugin context carrying `storageDomain`.
+ * @returns the open registry.
+ * @throws whatever `open` rejects with — a `StorageError` for an unreadable
+ * unit, a `DomainError('invalid-record')` for a record this build cannot read.
+ */
+export declare function openParkRegistry(ctx: Context): Promise<ParkRegistry>;

package/lib/types/release-order.d.ts

@@ -0,0 +1,21 @@
+/**
+ * The order a tree release walks: parent before child, shallowest first.
+ * @module dsh-pause-session/release-order
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { SessionId } from '@deepseek-ai/dsh-session';
+/** How a batch release is sequenced. */
+export interface ReleaseOrder {
+    /** The tree edge each child was found under. */
+    readonly parents: ReadonlyMap<SessionId, SessionId>;
+    /** One list per depth, shallowest first. */
+    readonly levels: readonly (readonly SessionId[])[];
+}
+/**
+ * Sequence a batch release parent before child.
+ * @param ctx - host context carrying the optional subagent catalog.
+ * @param sessionIds - every recorded session, in registry order.
+ * @param signal - cancellation for each catalog read.
+ * @returns the parent of each child, and one list per depth level.
+ */
+export declare function releaseOrder(ctx: Context, sessionIds: readonly SessionId[], signal?: AbortSignal): Promise<ReleaseOrder>;

package/lib/types/remote-adapter.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Wire adapter between the pause engine and the generated Remote namespace.
+ *
+ * The engine speaks in branded Session ids and user-facing answer copy; the Remote
+ * contract is plain JSON. Mapping lives here so neither side depends on the
+ * other's types.
+ * @module dsh-pause-session/remote-adapter
+ */
+import type { SessionControl } from './control.js';
+import type { PauseRemoteApi, PauseSnapshotWire } from './remote.js';
+import type { GlobalStatus, ParkStatus } from './shared.js';
+/** Map the engine's snapshot to the wire shape. */
+export declare function snapshotOf(snapshot: {
+    global: GlobalStatus;
+    sessions: Readonly<Record<string, ParkStatus>>;
+}): PauseSnapshotWire;
+/**
+ * Build the Remote callbacks over the mounted pause control.
+ * @param control - the engine's host control surface.
+ * @returns the wire API.
+ */
+export declare function remoteApiOf(control: SessionControl): PauseRemoteApi;

package/lib/types/remote.d.ts

@@ -0,0 +1,158 @@
+/**
+ * Native Remote transport for the pause controls.
+ *
+ * This module is deliberately self-contained: it imports only Cordis and the
+ * Typert decorators. The Typert generator analyzes this file alone so a
+ * third-party package can emit its Host reflection and Client contribution
+ * without pulling the plugin's DSH-typed modules into the generation face.
+ *
+ * The UI uses this namespace on Web and Desktop alike. No slash command is
+ * registered; the stream is the live status channel and the methods below are
+ * the button actions.
+ * @module dsh-pause-session/remote
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import { TypertRemoteService } from '@deepseek-ai/dsh-typert-protocol';
+declare module '@deepseek-ai/dsh-typert-protocol' {
+    interface RemoteErrorDetailsMap {
+        /** The pause control is personal; only the owner may read or drive it. */
+        'pause/owner-only': {};
+    }
+}
+/** The phase a Session reports to the controls. */
+export type PausePhaseWire = 'active' | 'draining' | 'parking' | 'safe' | 'flush-failed';
+/** One Session's pause state. */
+export interface SessionStatusWire {
+    readonly phase: PausePhaseWire;
+    readonly runningTools: readonly string[];
+    readonly rearmGoal?: boolean;
+}
+/** The whole-app verdict. */
+export interface GlobalStatusWire {
+    readonly verdict: 'idle' | 'waiting' | 'safe';
+    readonly registered: number;
+    readonly safe: number;
+    readonly parkedAt?: string;
+    readonly draining: readonly string[];
+    readonly parking: number;
+    readonly stalled: readonly string[];
+    readonly unresumable: readonly string[];
+    readonly unreadTrees: readonly string[];
+    readonly jobs: readonly string[];
+    readonly blind: readonly string[];
+}
+/** One live status snapshot: the aggregate plus every held Session. */
+export interface PauseSnapshotWire {
+    readonly global: GlobalStatusWire;
+    readonly sessions: Readonly<Record<string, SessionStatusWire>>;
+}
+/** One row in the morning decision list. */
+export interface TriageRowWire {
+    readonly sessionId: string;
+    readonly phase: 'draining' | 'parking' | 'flush-failed';
+    readonly updatedAt: number;
+    readonly reading: 'read' | 'unreadable';
+    readonly lastEvent?: string;
+    readonly turn?: number;
+    readonly step?: number;
+    readonly traces: readonly {
+        readonly tool: string;
+        readonly callId: string;
+    }[];
+    readonly owed: boolean;
+    readonly wakeable: boolean;
+    readonly rearmGoal: boolean;
+}
+/** One button action. */
+export interface PauseActionRequest {
+    readonly action: 'pause' | 'resume' | 'pause-all' | 'resume-all' | 'cancel-all' | 'goal';
+    /** The Session the control is addressed through. */
+    readonly sessionId: string;
+}
+/** One action outcome. */
+export interface PauseActionResultWire {
+    readonly ok: boolean;
+    readonly message: string;
+}
+/** One decision-list read. */
+export interface PauseTriageRequest {
+    readonly caller: string;
+}
+/** One decision on a listed Session. */
+export interface PauseDecisionRequest {
+    readonly caller: string;
+    readonly target: string;
+    readonly decision: 'continue' | 'note' | 'review' | 'leave' | 'goal';
+}
+export interface PauseRemoteApi {
+    snapshot(signal?: AbortSignal): Promise<PauseSnapshotWire>;
+    subscribe(listener: () => void): () => void;
+    act(request: PauseActionRequest, signal?: AbortSignal): Promise<PauseActionResultWire>;
+    triage(request: PauseTriageRequest, signal?: AbortSignal): Promise<readonly TriageRowWire[]>;
+    decide(request: PauseDecisionRequest, signal?: AbortSignal): Promise<PauseActionResultWire>;
+}
+declare module '@deepseek-ai/cordis' {
+    interface Context {
+        pauseSession: PauseRemote;
+    }
+}
+/** Host service exposed to the browser as the `pauseSession` Remote namespace. */
+export declare class PauseRemote extends TypertRemoteService {
+    private readonly api;
+    /** One snapshot per host version, shared by every connected observer. */
+    private snapshotCache;
+    /** Bumped by every host notification; each observer compares it to its own cursor. */
+    private version;
+    /** Observers waiting for the next version. */
+    private readonly waiters;
+    private readonly unsubscribe;
+    /**
+     * @param ctx - host context owning the service.
+     * @param api - the pause engine behind the wire methods.
+     */
+    constructor(ctx: Context, api: PauseRemoteApi);
+    /**
+     * One exact snapshot, used by tests and by a reconnect that cannot wait for
+     * the first stream item.
+     * @param signal - carrier cancellation.
+     * @returns the current aggregate and session states.
+     */
+    snapshot(signal?: AbortSignal): Promise<PauseSnapshotWire>;
+    /**
+     * The snapshot for one host version, computed once even when several clients
+     * are watching. A new notification discards the cached promise.
+     * @param version - the host version this snapshot answers.
+     * @param signal - stream cancellation.
+     * @returns the shared snapshot promise.
+     */
+    private snapshotFor;
+    /**
+     * Live status: the opening snapshot, then one new snapshot whenever the host
+     * reports a change.
+     * @param signal - stream cancellation.
+     * @returns the snapshot stream.
+     */
+    observe(signal?: AbortSignal): AsyncIterable<PauseSnapshotWire>;
+    /**
+     * Pause, resume, press every tree, resume every clean park, or flip one
+     * Session's goal re-arm.
+     * @param request - the button action.
+     * @param signal - carrier cancellation.
+     * @returns the user-facing outcome.
+     */
+    act(request: PauseActionRequest, signal?: AbortSignal): Promise<PauseActionResultWire>;
+    /**
+     * Read the morning decision list.
+     * @param request - the calling Session whose list is read.
+     * @param signal - read cancellation.
+     * @returns the listed rows.
+     */
+    triage(request: PauseTriageRequest, signal?: AbortSignal): Promise<readonly TriageRowWire[]>;
+    /**
+     * Take one decision on one listed Session.
+     * @param request - the caller, target, and decision.
+     * @param signal - load cancellation.
+     * @returns the user-facing outcome.
+     */
+    decide(request: PauseDecisionRequest, signal?: AbortSignal): Promise<PauseActionResultWire>;
+}

package/lib/types/resume-activation.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Reactivate one parked session: restore its composition, give it the route its
+ * log recorded, deliver the wake it owes, and only then drop the gate and record.
+ * @module dsh-pause-session/resume-activation
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { Agent } from '@deepseek-ai/dsh-agent';
+import type { SessionId } from '@deepseek-ai/dsh-session';
+import type { PauseGate } from './gate.js';
+import type { ParkRegistry } from './registry.js';
+import type { ResumeAttempt, ResumeOptions, WakeRequest } from './resume-text.js';
+/** The activation entry points the resume path composes. */
+export interface Activator {
+    activate(sessionId: SessionId, request: WakeRequest, rearm: boolean, parentId?: SessionId, signal?: AbortSignal): Promise<ResumeAttempt>;
+    ensureRoute(agent: Agent): void;
+    wake(agent: Agent, request: WakeRequest): void;
+    rearmGoal(agent: Agent): void;
+}
+/**
+ * Build the activation closure.
+ * @param ctx - host context carrying the agent store and goal service.
+ * @param gate - the pause gate released after activation.
+ * @param registry - the durable list the release forgets from.
+ * @param options - the route knowledge the wake content depends on.
+ * @returns the activation methods the resume path uses.
+ */
+export declare function createActivator(ctx: Context, gate: PauseGate, registry: ParkRegistry, options: ResumeOptions): Activator;

package/lib/types/resume-text.d.ts

@@ -0,0 +1,67 @@
+/**
+ * User-facing copy and result shapes for the clean resume and tree release.
+ * @module dsh-pause-session/resume-text
+ */
+import type { SessionId } from '@deepseek-ai/dsh-session';
+import type { PauseAnswer } from './shared.js';
+/** Route knowledge the clean resume path needs. */
+export interface ResumeOptions {
+    /** Provider routes whose request conversion drops an empty user message. */
+    readonly silentWakeRoutes: readonly string[];
+}
+/**
+ * The one wake content a route that keeps an empty user message is given.
+ */
+export declare const WAKE_MARKER = "[pause: resumed from a pause]";
+/** How one resume asks the loop for the request it owes the session. */
+export type WakeRequest = {
+    readonly kind: 'silent';
+} | {
+    readonly kind: 'message';
+    readonly text: string;
+} | {
+    readonly kind: 'none';
+};
+/** Result copy for a resumed session; the model never sees it. */
+export declare const RESUMED_TEXT = "This session resumed from where it paused.";
+/** Result copy for a registered session whose park did not finish cleanly. */
+export declare const UNCLEAN_TEXT: string;
+/** Result copy when nothing is parked under that session. */
+export declare const NOT_PARKED_TEXT = "pause has no pause recorded for this session.";
+/** Result copy for a session that is parked but could not be loaded back. */
+export declare const ACTIVATION_FAILED_TEXT = "pause could not reopen this session, so it stayed paused.";
+/** Result copy for a one-shot subagent route. */
+export declare const UNRESUMABLE_TEXT = "pause did not resume this session: it is a one-shot subagent route and cannot be resumed.";
+/** Result copy for the review decision. */
+export declare const REVIEW_TEXT: string;
+/** Copy for one goal opt-out change. */
+export declare const REARM_GOAL_ON_TEXT = "pause will re-open this session's goal when it resumes it.";
+export declare const REARM_GOAL_OFF_TEXT = "pause will leave this session's goal closed when it resumes it.";
+/** Why one record did not produce a running session. */
+export type ResumeRefusal = 'not-parked' | 'not-clean' | 'activation-failed' | 'unrecorded' | 'not-activated' | 'unresumable';
+/** What one resume attempt did. */
+export interface ResumeOutcome {
+    readonly sessionId: SessionId;
+    readonly resumed: boolean;
+    readonly refusal?: ResumeRefusal;
+}
+/** One resume attempt plus the answer the caller receives. */
+export interface ResumeAttempt extends ResumeOutcome {
+    readonly answer: PauseAnswer;
+}
+/** What releasing one session's registered tree did. */
+export interface ReleaseTreeOutcome {
+    readonly members: number;
+    readonly resumed: number;
+    readonly refusals: readonly {
+        readonly sessionId: SessionId;
+        readonly refusal: ResumeRefusal;
+    }[];
+    readonly answer: PauseAnswer;
+}
+/**
+ * How one tree-wide release answers the person who pressed it.
+ * @param released - the sessions this release covered, in release order.
+ * @returns one sentence about what came back and what did not.
+ */
+export declare function summarizeTreeRelease(released: readonly ResumeAttempt[]): string;

package/lib/types/resume.d.ts

@@ -0,0 +1,126 @@
+/**
+ * The clean resume path: bring back a session a previous process parked, and
+ * let it answer the input that was already pending when it stopped.
+ *
+ * A resume invents no turn. At the park point the loop had claimed the
+ * session's pending input onto the surface and built the request the gate then
+ * held; after a restart that input is still the last thing the session says and
+ * the model still owes it an answer. What is missing is only a reason for the
+ * loop to build a request again, and the documented way to ask for one is a
+ * wake input — a user message the loop claims.
+ *
+ * The wake is invisible only on the routes the composition declares in
+ * `silentWakeRoutes`, whose conversion drops an empty user message. On every
+ * other route the loop's request carries one visible marker instead, and the
+ * marker reaches the model; that is an accepted cost of resuming at all.
+ * Whether an empty user message survives is a property of the route's
+ * conversion rather than of the loop, so the route is resolved per session —
+ * from the request header the session itself persisted.
+ *
+ * The wake message is attributed to this plugin, never to the user: it is text
+ * this module synthesized on the session's behalf, in the session's own log and
+ * in front of the model, and a downstream consumer has to be able to tell it
+ * apart from something the human typed.
+ *
+ * Only a cleanly parked session takes this path. A record that never reached
+ * the park point, or whose flush did not finish, describes work whose durable
+ * state nobody knows; waking it would spend its owner's money on a guess, and
+ * deciding those sessions is the morning list's job, not this path's. That
+ * holds whether or not the recorded session happens to be live in this process:
+ * liveness is not the park outcome, and a session can be live without ever
+ * having stopped.
+ * @module dsh-pause-session/resume
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { SessionId } from '@deepseek-ai/dsh-session';
+import type { PauseGate } from './gate.js';
+import type { ParkRegistry } from './registry.js';
+import type { PauseAnswer } from './shared.js';
+export * from './resume-text.js';
+import type { ReleaseTreeOutcome, ResumeAttempt, ResumeOptions, WakeRequest } from './resume-text.js';
+declare module '@deepseek-ai/dsh-llm' {
+    interface MessageSourceMap {
+        /**
+         * Text dsh-pause-session synthesized on the session's behalf: the wake this
+         * path delivers and the unknown-outcome note a decision adds. Declared so
+         * the log, and anything reading it, can tell plugin-authored input from the
+         * user's own.
+         */
+        'pause': {
+            kind: 'pause';
+        };
+    }
+}
+/** How this path is wired into the session control that owns the pause state. */
+export interface ResumeDeps {
+    /**
+     * Take a live session's pause back: the durable record goes first, then the
+     * gate. Owned by the session control so there is one release order.
+     */
+    release(sessionId: SessionId, text: string): Promise<PauseAnswer>;
+    /**
+     * Whether the pause this process holds was adopted from the registry rather
+     * than pressed here. Only an adopted pause is a restart: a press this process
+     * made and took back must never wake a model.
+     */
+    adopted(sessionId: SessionId): boolean;
+}
+/** The clean resume path, as the session control drives it. */
+export interface ResumePath {
+    /**
+     * Resume one session the registry remembers.
+     * @param sessionId - the session to resume.
+     * @param request - which wake this resume delivers; see {@link WakeRequest}.
+     * @param parentId - the direct parent a batch release already brought back, when there is one.
+     * @param signal - cancellation for the cold load and setup.
+     * @returns what happened, and the copy for whoever asked.
+     */
+    resumeSession(sessionId: SessionId, request: WakeRequest, parentId?: SessionId, signal?: AbortSignal): Promise<ResumeAttempt>;
+    /**
+     * Resume one session the decision list officially owns — a record that is
+     * known NOT to be clean, which the clean path above must refuse and this entry
+     * exists to carry out. Same release order, same wake vocabulary.
+     * @param sessionId - the listed session to bring back.
+     * @param request - which wake the decision delivers; see {@link WakeRequest}.
+     * @param finalize - whether the decision continues the session (`'release'`)
+     * or only answers it (`'review'`). A review activates nothing and writes
+     * nothing: opening a session to read it is the user's own action, not this
+     * plugin's.
+     * @param parentId - the direct parent a batch release already brought back, when there is one.
+     * @param signal - cancellation for the cold load and setup.
+     * @returns what happened, and the copy for whoever asked.
+     */
+    decideUnclean(sessionId: SessionId, request: WakeRequest, finalize: 'release' | 'review', parentId?: SessionId, signal?: AbortSignal): Promise<ResumeAttempt>;
+    /**
+     * Resume every session the registry remembers, clean ones only. One session's
+     * failure never stops the others.
+     * @param signal - cancellation checked between release levels and forwarded to each load.
+     * @returns one attempt per recorded session, in registry order.
+     */
+    resumeParked(signal?: AbortSignal): Promise<readonly ResumeAttempt[]>;
+    /**
+     * Record or clear one session's goal opt-out.
+     * @param sessionId - the parked session to change.
+     * @param rearmGoal - whether the clean resume path may re-arm its goal.
+     * @returns the copy for whoever asked.
+     */
+    setRearmGoal(sessionId: SessionId, rearmGoal: boolean): Promise<PauseAnswer>;
+    /**
+     * Release one parked session and the registered members of its tree: the
+     * counterpart of a press that registered a whole tree.
+     * @param sessionId - the session whose tree the user released.
+     * @param signal - cancellation for the tree read and each member's load.
+     * @returns what happened to the tree, and the copy for whoever asked.
+     */
+    releaseTree(sessionId: SessionId, signal?: AbortSignal): Promise<ReleaseTreeOutcome>;
+}
+/**
+ * Build the clean resume path.
+ * @param ctx - host context carrying the agent store, the session store, and the goal service when one is mounted.
+ * @param gate - the pause gate the resume releases.
+ * @param registry - the durable list this path reads and forgets from.
+ * @param options - the route knowledge the wake content depends on.
+ * @param deps - the control-owned release order and the adopted-pause fact.
+ * @returns the path the session control exposes.
+ */
+export declare function installResumePath(ctx: Context, gate: PauseGate, registry: ParkRegistry, options: ResumeOptions, deps: ResumeDeps): ResumePath;