dsh-pause-session 0.1.0 → 0.2.1

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,36 @@
+/**
+ * Reactivate one parked Session and deliver the wake it owes.
+ *
+ * The two Session kinds come back through different owners. An ordinary
+ * Session is loaded by this plugin and given the route its own log recorded.
+ * A subagent child belongs to the subagent runtime: delivering the wake through
+ * `ctx.subagents.prompt` is what cold-resumes it as a managed activation, under
+ * its live tree root, with its persisted composition and tree membership
+ * restored by the runtime itself.
+ *
+ * Both paths keep the same release order: the durable record goes first, then
+ * the gate, so a record that cannot be dropped leaves the Session parked.
+ * @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, 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, subagent runtime, 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 root 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

@@ -32,10 +32,12 @@
  * @module dsh-pause-session/resume
  */
 import type { Context } from '@deepseek-ai/cordis';
-import type { CommandResult } from '@deepseek-ai/dsh-commands';
 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 {
         /**
@@ -49,78 +51,13 @@ declare module '@deepseek-ai/dsh-llm' {
         };
     }
 }
-/**
- * The one wake content a route that keeps an empty user message is given. It
- * names its producer, because it lands in the same user turn as the input the
- * model owes an answer to and must not read as part of it.
- */
-export declare const WAKE_MARKER = "[pause: resumed from a pause]";
-/**
- * How one resume asks the loop for the request it owes the session:
- *
- * - `silent`: the clean path's wake — an empty input on a route the
- *   composition declared silent, and the visible marker on any other route.
- * - `message`: the decision list's "continue, and say the tool outcome is
- *   unknown" — user-visible text on the wire by construction, and the only
- *   resume that is not invisible.
- * - `none`: no wake at all. This is what "leave it for me to read" costs: the
- *   session is not activated, nothing is asked of the model, and the park is
- *   exactly as it was.
- */
-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 this path refuses: its durable state is
- * not the outcome of a completed park, so waking it would be a guess.
- */
-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: its Session exists, but no resume may reactivate it. */
-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. It is the one answer that promises
- * nothing happened, because opening a session to read it is the user's own
- * action in their session list — and activating its agent here would start a
- * session they asked only to look at.
- */
-export declare const REVIEW_TEXT: string;
-/** Result copy for a change the durable registry refused to record. */
-export declare const UNRECORDED_TEXT = "pause could not write the pause registry, so it did not change the pause state.";
-/** 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;
-    /** Whether the session is now running from the point it stopped. */
-    readonly resumed: boolean;
-    /** Present exactly when `resumed` is false. */
-    readonly refusal?: ResumeRefusal;
-}
-/** One resume attempt plus the answer the command that asked for it receives. */
-export interface ResumeAttempt extends ResumeOutcome {
-    readonly answer: CommandResult;
-}
 /** 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<CommandResult>;
+    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
@@ -128,27 +65,16 @@ export interface ResumeDeps {
      */
     adopted(sessionId: SessionId): boolean;
 }
-/** Route knowledge this path needs from the composition. */
-export interface ResumeOptions {
-    /**
-     * Provider routes whose request conversion drops an empty user message, so an
-     * empty wake never reaches the model. Deployment-owned because it is a
-     * property of the adapter behind each route, and a third-party plugin cannot
-     * introspect an adapter.
-     */
-    readonly silentWakeRoutes: readonly string[];
-}
 /** 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>;
+    resumeSession(sessionId: SessionId, request: WakeRequest, 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
@@ -159,11 +85,10 @@ export interface ResumePath {
      * 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>;
+    decideUnclean(sessionId: SessionId, request: WakeRequest, finalize: 'release' | 'review', signal?: AbortSignal): Promise<ResumeAttempt>;
     /**
      * Resume every session the registry remembers, clean ones only. One session's
      * failure never stops the others.
@@ -177,7 +102,7 @@ export interface ResumePath {
      * @param rearmGoal - whether the clean resume path may re-arm its goal.
      * @returns the copy for whoever asked.
      */
-    setRearmGoal(sessionId: SessionId, rearmGoal: boolean): Promise<CommandResult>;
+    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.
@@ -187,28 +112,6 @@ export interface ResumePath {
      */
     releaseTree(sessionId: SessionId, signal?: AbortSignal): Promise<ReleaseTreeOutcome>;
 }
-/** What releasing one session's registered tree did. */
-export interface ReleaseTreeOutcome {
-    /** How many sessions this release covered: the session plus its registered descendants. */
-    readonly members: number;
-    /** How many of them are running again. */
-    readonly resumed: number;
-    /** How many could not be resumed, and why the release did not take them back. */
-    readonly refusals: readonly {
-        readonly sessionId: SessionId;
-        readonly refusal: ResumeRefusal;
-    }[];
-    /** The copy for whoever pressed the release. */
-    readonly answer: CommandResult;
-}
-/**
- * How one tree-wide release answers the person who pressed it. One release, one
- * sentence about all of it: what came back, and — by name, because those rows
- * are what the morning list is for — what did not.
- * @param released - the sessions this release covered, in release order.
- * @returns the result text, e.g. `pause resumed 2 sessions from where they stopped; "child" did not pause completely`.
- */
-export declare function summarizeTreeRelease(released: readonly ResumeAttempt[]): string;
 /**
  * Build the clean resume path.
  * @param ctx - host context carrying the agent store, the session store, and the goal service when one is mounted.

package/lib/types/shared.d.ts

@@ -1,81 +1,22 @@
 /**
- * The identities both halves of dsh-pause-session name, the status encodings they
- * share, and the one spelling a host log line gives a caught value.
+ * The identities both halves of dsh-pause-session name, the phase vocabulary
+ * they share, and the one spelling a host log line gives a caught value.
  *
  * The browser bundle may value-import only the shell's baseline module table,
- * so this module imports nothing: the client half reads command names and the
- * decode functions from it directly, and the host half derives the branded
- * identities from the same strings.
- *
- * A third-party plugin's only live channel to the browser is the command
- * registry — it can add neither a `ctx.remote` namespace nor a forwarded event,
- * both of which are compiled into the harness's own API assembly. A command
- * descriptor's only free-form field is its `description`, and a command
- * result's only free-form field is its `text`, so the park state travels as a
- * prefix plus `;`-separated fields on one of those. The text stays
- * human-readable: the same words are what the slash-command menu shows.
- *
- * Every value inside a field is escaped, so a decoded name is the exact name
- * that was encoded. Session ids, tool names, and call ids are the host's own
- * data and may contain the `;`, `,`, `/`, or newline a field is separated by; a
- * folded spelling would decode as a different name — a different row, looked up
- * again.
+ * so this module imports nothing. The native Remote payloads are the live
+ * vocabulary; there is no command encoding or slash-command surface here.
  * @module dsh-pause-session/shared
  */
-/** Command that pauses the receiving session before its next model request. */
-export declare const PAUSE_COMMAND = "pause";
-/** Command that resumes the receiving session; registered only while that session is paused. */
-export declare const RESUME_COMMAND = "pause-resume";
-/** Command that resumes every parked session the registry remembers. */
-export declare const RESUME_ALL_COMMAND = "pause-resume-all";
-/** Command that registers and parks every running session tree in one action. */
-export declare const PAUSE_ALL_COMMAND = "pause-all";
-/** Command that reports the whole-app park state; registered globally, always. */
-export declare const STATE_ALL_COMMAND = "pause-state-all";
-/** Command that reports the receiving session's park state; registered only while it is paused. */
-export declare const STATUS_COMMAND = "pause-state";
-/** Command that turns the receiving session's own goal re-arm on or off; registered only while it is paused. */
-export declare const GOAL_COMMAND = "pause-goal";
-/** Command that reports every session that did not stop cleanly. */
-export declare const TRIAGE_COMMAND = "pause-triage";
-/** Command that resumes one session from the decision list exactly as the clean path would. */
-export declare const TRIAGE_CONTINUE_COMMAND = "pause-triage-continue";
-/** Command that resumes one session from the decision list with the unknown-outcome note. */
-export declare const TRIAGE_NOTE_COMMAND = "pause-triage-note";
-/** Command that opens one session from the decision list without spending a request. */
-export declare const TRIAGE_REVIEW_COMMAND = "pause-triage-review";
-/** Command that leaves one session from the decision list exactly as it is. */
-export declare const TRIAGE_LEAVE_COMMAND = "pause-triage-leave";
-/** Command that turns one listed session's goal re-arm on or off. */
-export declare const TRIAGE_GOAL_COMMAND = "pause-triage-goal";
-/** Stable definition id of the pause command, matched by identity rather than by copy. */
-export declare const PAUSE_DEFINITION_ID = "dsh-pause-session/pause";
-/** Stable definition id of the resume command: the host's own "this session is paused" fact. */
-export declare const RESUME_DEFINITION_ID = "dsh-pause-session/resume";
-/** Stable definition id of the global resume command, matched by identity rather than by copy. */
-export declare const RESUME_ALL_DEFINITION_ID = "dsh-pause-session/resume-all";
-/** Stable definition id of the whole-app pause command. */
-export declare const PAUSE_ALL_DEFINITION_ID = "dsh-pause-session/pause-all";
-/** Stable definition id of the whole-app status read. */
-export declare const STATE_ALL_DEFINITION_ID = "dsh-pause-session/state-all";
-/** Stable definition id of the status read, matched by identity rather than by copy. */
-export declare const STATUS_DEFINITION_ID = "dsh-pause-session/status";
-/** Stable definition id of the paused session's own goal re-arm toggle. */
-export declare const GOAL_DEFINITION_ID = "dsh-pause-session/goal";
-/** Stable definition id of the decision-list read. */
-export declare const TRIAGE_DEFINITION_ID = "dsh-pause-session/triage";
-/** Stable definition id of the decision-list "continue" verb. */
-export declare const TRIAGE_CONTINUE_DEFINITION_ID = "dsh-pause-session/triage-continue";
-/** Stable definition id of the decision-list "continue with the unknown-outcome note" verb. */
-export declare const TRIAGE_NOTE_DEFINITION_ID = "dsh-pause-session/triage-note";
-/** Stable definition id of the decision-list "open without activating" verb. */
-export declare const TRIAGE_REVIEW_DEFINITION_ID = "dsh-pause-session/triage-review";
-/** Stable definition id of the decision-list "leave it alone today" verb. */
-export declare const TRIAGE_LEAVE_DEFINITION_ID = "dsh-pause-session/triage-leave";
-/** Stable definition id of the decision-list goal re-arm toggle. */
-export declare const TRIAGE_GOAL_DEFINITION_ID = "dsh-pause-session/triage-goal";
-/** First token of every encoded status, so a descriptor is never parsed by accident. */
-export declare const STATUS_PREFIX = "pause: ";
+/** Result copy for a press or a release the durable registry refused to record. */
+export declare const UNRECORDED_TEXT = "pause could not write the pause registry, so it did not change the pause state.";
+/**
+ * One user-facing answer from an action. The controls render `text` verbatim;
+ * `kind` only says whether the press succeeded.
+ */
+export interface PauseAnswer {
+    readonly kind: 'success' | 'error';
+    readonly text: string;
+}
 /**
  * One log line's text for a caught value.
  * @param error - the caught value.
@@ -137,24 +78,11 @@ export interface ParkStatus {
      */
     readonly rearmGoal?: boolean;
 }
-/**
- * Encode one status for a command descriptor.
- * @param status - the state to publish.
- * @returns the descriptor text, e.g. `pause: draining; tools: edit, bash; goal: on`.
- */
-export declare function encodeParkStatus(status: ParkStatus): string;
-/**
- * Decode a status previously written by {@link encodeParkStatus}.
- * @param text - a command descriptor's description.
- * @returns the status, or `undefined` when this text carries none — a foreign
- * command, or a reading taken before the host published anything.
- */
-export declare function decodeParkStatus(text: string): ParkStatus | undefined;
-/**
- * First token of every encoded whole-app status. A different prefix from the
- * per-session status on purpose: one decoder must never read the other's text.
- */
-export declare const GLOBAL_STATUS_PREFIX = "pause all: ";
+/** One JSON snapshot: the whole-app verdict plus every live paused session. */
+export interface PauseSnapshot {
+    readonly global: GlobalStatus;
+    readonly sessions: Readonly<Record<string, ParkStatus>>;
+}
 /** The whole-app answer to "can I close the lid?". */
 export type GlobalVerdict = 'idle' | 'waiting' | 'safe';
 /** A surface the whole-app report could not read at all. */
@@ -193,7 +121,7 @@ export interface GlobalStatus {
     readonly parkedAt?: string;
     /**
      * Registered sessions still working: a tool is in flight or a turn is between
-     * steps. Their park point is announced by the marker commands the park
+     * steps. Their park point is announced on the native stream the park
      * registers, so a reader has nothing to watch here.
      */
     readonly draining: readonly string[];
@@ -221,25 +149,6 @@ export interface GlobalStatus {
     /** Whole surfaces the report could not read, so their emptiness is not a fact. */
     readonly blind: readonly GlobalBlindSpot[];
 }
-/**
- * Encode one whole-app status for a command result.
- * @param status - the state to publish.
- * @returns the result text, e.g.
- * `pause all: waiting; registered: 3; safe: 1; parked-at: overnight; draining: overnight; parking: 1; stalled: -; unresumable: -; unread-trees: -; jobs: bash-1; blind: -`.
- */
-export declare function encodeGlobalStatus(status: GlobalStatus): string;
-/**
- * Decode a whole-app status previously written by {@link encodeGlobalStatus}.
- * @param text - a command result's text.
- * @returns the status, or `undefined` when this text carries none.
- */
-export declare function decodeGlobalStatus(text: string): GlobalStatus | undefined;
-/**
- * First token of every encoded decision list. Separate from the per-session and
- * whole-app status prefixes on purpose, for the same reason those two are
- * separate: one decoder must never read another's text.
- */
-export declare const TRIAGE_PREFIX = "pause triage: ";
 /** How one decision-list row was read out of the session's own stored log. */
 export type TriageReading = 'read' | 'unreadable';
 /**
@@ -310,15 +219,3 @@ export interface TriageList {
 export declare const TRIAGE_ACTIONS: readonly ["continue", "note", "review", "leave", "goal"];
 /** One decision the list offers. */
 export type TriageAction = (typeof TRIAGE_ACTIONS)[number];
-/**
- * Encode one decision list for a command result.
- * @param list - the rows to publish.
- * @returns the result text, e.g. `pause triage: 1; row: overnight; phase: draining; stopped: tool/call/turn 1 step 1; tools: gated; wake: yes`.
- */
-export declare function encodeTriageList(list: TriageList): string;
-/**
- * Decode a decision list previously written by {@link encodeTriageList}.
- * @param text - a command result's text.
- * @returns the list, or `undefined` when this text carries none.
- */
-export declare function decodeTriageList(text: string): TriageList | undefined;

package/lib/types/snapshot.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Pure projection of the durable park and each live tree into the native
+ * snapshot. This module owns the phase fold and the goal opt-out; it does not
+ * press, release, or decide anything.
+ * @module dsh-pause-session/snapshot
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { SessionId } from '@deepseek-ai/dsh-session';
+import type { ParkWatch } from './park.js';
+import type { ParkRegistry } from './registry.js';
+import type { TreeWalk } from './tree.js';
+import type { ParkMark } from './park-state.js';
+import type { GlobalStatus, PauseSnapshot } from './shared.js';
+/** What the snapshot projection needs from the control. */
+export interface SnapshotDeps {
+    readonly ctx: Context;
+    readonly marks: ReadonlyMap<SessionId, ParkMark>;
+    readonly watch: ParkWatch;
+    readonly registry: ParkRegistry;
+    /** Read the whole-app aggregate, reusing the walks this projection already paid for. */
+    readGlobal(signal?: AbortSignal, walks?: ReadonlyMap<SessionId, TreeWalk>): Promise<GlobalStatus>;
+}
+/**
+ * Read every live mark and the whole-app aggregate in one pass.
+ * @param deps - the control-owned marks, watch, registry, and aggregate reader.
+ * @param signal - cancellation for the tree walks and aggregate.
+ * @returns the native snapshot.
+ */
+export declare function readSnapshot(deps: SnapshotDeps, signal?: AbortSignal): Promise<PauseSnapshot>;