dsh-pause-session 0.0.0-stage → 0.1.0

package/lib/types/client/view.d.ts

@@ -0,0 +1,137 @@
+/**
+ * The controls' phase → view mapping.
+ *
+ * Kept pure functions of the published reading so the rendering decision — what
+ * the button says, whether it accepts a press, and which state label is visible
+ * — is asserted without a browser renderer. Labels are KEYS, not copy: the
+ * visible sentence is localized, and the host's own names join it as data.
+ * @module dsh-pause-session/client/view
+ */
+import type { GlobalReading, TriageReading } from './global.js';
+import type { PauseReading } from './control.js';
+import type { PauseKey } from './locales.js';
+import type { TriageAction } from '../shared.js';
+/** What one reading renders as. */
+export interface PauseView {
+    /** Whether the host reported this session paused. */
+    readonly paused: boolean;
+    /** Whether the control accepts a press; an unknown or failed reading does not. */
+    readonly enabled: boolean;
+    /** Accessible name of the button. */
+    readonly ariaKey: PauseKey;
+    /** Label shown beside the button while the control has something to say. */
+    readonly labelKey?: PauseKey;
+    /** Tools in flight, taken verbatim from the host; rendered only with `labelKey`. */
+    readonly runningTools: readonly string[];
+    /**
+     * The host-reported goal opt-out, or `undefined` when the host did not answer
+     * it. Absent means the goal switch is not rendered at all: a switch has to
+     * state a fact, and the only fact available is the one the record holds.
+     */
+    readonly rearmGoal?: boolean;
+}
+/**
+ * Whether the pause control renders on one session at all.
+ *
+ * The control is the user's button for a session's work, and that work includes
+ * the subagents under it — which is why the press covers the tree and why the
+ * button does not belong inside the tree. The client can tell: a Session
+ * snapshot carries a `subagent` field, the same signal the read-only composer
+ * reads. A subagent's service is not the user's to pause: its parent's control
+ * already speaks for it, and a second button here would offer to stop "a
+ * session" from inside a child.
+ * @param subagent - the session snapshot's own subagent fact, absent when unknown.
+ * @returns whether this session's header renders the control.
+ */
+export declare function showsPauseControl(subagent: {
+    readonly address: unknown;
+} | null | undefined): boolean;
+/**
+ * Map one reading to its view.
+ * @param reading - the host-reported reading, or `undefined` before the first answer.
+ * @returns the view for that reading.
+ */
+export declare function pauseView(reading: PauseReading | undefined): PauseView;
+/** One named fact from the whole-app report, with the copy key that introduces it. */
+export interface GlobalCaveat {
+    /** What this list of names is. */
+    readonly key: PauseKey;
+    /** Host names, rendered verbatim. */
+    readonly names: readonly string[];
+}
+/** Which verb a whole-app press runs. */
+export type GlobalAction = 'pause-all' | 'resume-all' | 'none';
+/** One decision as the list renders it. */
+export interface TriageActionView {
+    /** The decision this button takes. */
+    readonly action: TriageAction;
+    /** Visible label. */
+    readonly labelKey: PauseKey;
+    /** What it does, for the accessible name. */
+    readonly ariaKey: PauseKey;
+}
+/** The four decisions, in the order a user reads them: least to most cautious. */
+export declare const TRIAGE_ACTION_VIEWS: readonly TriageActionView[];
+/**
+ * The fifth listed verb, rendered apart from the four decisions: it is a
+ * switch on what the NEXT resume may spend, not a way to decide this row.
+ */
+export declare const TRIAGE_GOAL_VIEW: TriageActionView;
+/** One listed session, as the panel renders it. */
+export interface TriageRowView {
+    /** Host data, rendered verbatim. */
+    readonly sessionId: string;
+    /** The durable outcome, as a word. */
+    readonly phaseKey: PauseKey;
+    /** Stop position: the event the log ends on and the step it belongs to. */
+    readonly stopped?: string;
+    /** The tools whose outcomes were never recorded. */
+    readonly unknownTools: readonly string[];
+    /** Whether the host said it can hand this session the request it owes. */
+    readonly wakeable: boolean;
+    /** Whether the log could be read at all. */
+    readonly readable: boolean;
+    /** Whether resuming this session may re-open its goal and spend its rounds. */
+    readonly rearmGoal: boolean;
+}
+/** What the decision-list panel renders. */
+export interface TriageView {
+    /** Whether the panel has anything to show; a host that cannot answer shows nothing. */
+    readonly visible: boolean;
+    /** Whether any listed session can actually be continued. */
+    readonly rows: readonly TriageRowView[];
+}
+/**
+ * Map one decision-list reading to its view.
+ * @param reading - the host-reported list, or `undefined` before the panel asked.
+ * @returns the rows as the panel renders them.
+ */
+export declare function triageView(reading: TriageReading | undefined): TriageView;
+/** What the whole-app reading renders as. */
+export interface GlobalPauseView {
+    /** Whether the control renders at all; a control with no host answer claims nothing. */
+    readonly visible: boolean;
+    /** Whether the control accepts a press. */
+    readonly enabled: boolean;
+    /** Accessible name of the button. */
+    readonly ariaKey: PauseKey;
+    /**
+     * Headline shown beside the button. Absent while there is nothing to report:
+     * an untouched park renders the bare affordance, not a sentence about itself.
+     */
+    readonly labelKey?: PauseKey;
+    /** Verb the press runs. */
+    readonly action: GlobalAction;
+    /** Host numbers, rendered verbatim beside the label. */
+    readonly detail: string;
+    /** How many decisions are waiting; shown on the panel's own entry point. */
+    readonly unclean: number;
+    /** Named facts the user must not miss; rendered on the tooltip. */
+    readonly caveats: readonly GlobalCaveat[];
+}
+/**
+ * Map one whole-app reading to its view.
+ * @param reading - the host-reported reading, or `undefined` before the first answer.
+ * @returns the view for that reading.
+ */
+export declare function globalPauseView(reading: GlobalReading | undefined): GlobalPauseView;

package/lib/types/coldlog.d.ts

@@ -0,0 +1,111 @@
+/**
+ * Reading one parked session's stored log through a bound, and the facts the
+ * morning list may claim from what it read.
+ *
+ * The decision list reads the same log the wake reads, but for the opposite
+ * reason: the wake has to reproduce the session, so it reads everything. The
+ * list only has to name where the session stopped, which tool call the log
+ * never heard back from, and whether an answer is still owed — all of them
+ * facts about the log's END. Reading from seq 0 to the end for every row, on
+ * every command-registry change while the panel is open, would make a long
+ * session's cost grow with a log nobody is asking about.
+ *
+ * WHAT THE BOUND BUYS. A stored log is append-only, so the tail is stable: the
+ * read takes the last {@link TRIAGE_WINDOW_EVENTS} events, or the whole log when
+ * it is shorter, and the answer is derived from that. The window is complete
+ * whenever the log fits inside it, which is the common case; the fold the rest
+ * of this plugin reads history through is then the harness's own, over exactly
+ * the events the harness would fold.
+ *
+ * WHAT THE TAIL ALONE PROVES. A truncated window still answers the list's
+ * questions, for one reason the harness guarantees: a dangling tool call exists
+ * only inside the step that is still open, because a step's end is written
+ * after its results. So an unanswered call is always inside the final open
+ * span, and the tail that contains that span contains every one of them. What
+ * the window cannot prove — a log a replacement event rewrote from further back
+ * — is not guessed at: {@link logFacts} reports `undefined` and the row says
+ * `unreadable`, because a list that invents a stop position is worse than a
+ * list that says it could not read one.
+ * @module dsh-pause-session/coldlog
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { SessionEvent, SessionId } from '@deepseek-ai/dsh-session';
+import type { TriageTrace } from './shared.js';
+/**
+ * Events the read looks at before it gives up. Sized to hold a whole final
+ * step — the model exchange, its tool calls, and their results — with room to
+ * spare, at a cost that does not grow with the session.
+ */
+export declare const TRIAGE_WINDOW_EVENTS = 2000;
+/**
+ * The longest log the read will walk while locating where its tail starts.
+ *
+ * The window's start is found by probing for the log's length, so a log longer
+ * than this cannot be located from its end at a cost worth paying for a panel
+ * left open. Such a log — a million stored events — is reported unreadable
+ * rather than read from the front, which is the read this module exists to
+ * avoid.
+ */
+export declare const TRIAGE_LOG_MAX_EVENTS = 1000000;
+/** How one stored log was seen by the bounded read. */
+export type ColdLog =
+/** The events the read returned, and whether they are the whole stored log. */
+{
+    readonly kind: 'read';
+    readonly events: readonly SessionEvent[];
+    readonly complete: boolean;
+}
+/** The log could not be opened or read, or it is longer than this read will walk. */
+ | {
+    readonly kind: 'unreadable';
+};
+/** The facts the decision list claims, all of them read off the log's end. */
+export interface ColdFacts {
+    /** What the stored log's last event was, and the turn/step it belongs to. */
+    readonly last: SessionEvent | undefined;
+    /** Tool calls the stored events record and no stored result answers. */
+    readonly traces: readonly TriageTrace[];
+    /** Whether the stored log ends owing the model an answer. */
+    readonly owed: boolean;
+    /** Whether the log names the route a wake would be addressed to. */
+    readonly wakeable: boolean;
+}
+/**
+ * The turn and step an event belongs to, when it carries them.
+ * @param event - one stored event.
+ * @returns the position fields the event has, and nothing for the fields it does not.
+ */
+export declare function positionOf(event: SessionEvent): {
+    readonly turn?: number;
+    readonly step?: number;
+};
+/**
+ * The facts one bounded read of a stored log supports.
+ *
+ * A complete read is folded by the harness's own derivation, so the list and
+ * the wake answer the "does it still owe a reply" question through one rule.
+ * A truncated read answers from the tail, and only where the tail is proof: a
+ * replacement event that rewrote a surface range from outside the window is
+ * not visible here, so a log whose tail a later event could have rewritten is
+ * reported unreadable rather than guessed at.
+ * @param events - the stored events the read returned, in sequence order.
+ * @param complete - whether those events are the whole stored log.
+ * @param projections - this process's registered message projections.
+ * @returns the row's facts, or `undefined` when this read cannot support them.
+ */
+export declare function logFacts(events: readonly SessionEvent[], complete: boolean, projections: Context['sessions']['messageProjections']): ColdFacts | undefined;
+/**
+ * Read one session's stored log, bounded to the events the list's facts need.
+ *
+ * The window is the last `windowEvents` events, found by probing for the log's
+ * length and then reading exactly that slice. A short log is returned whole and
+ * marked complete; a log longer than {@link TRIAGE_LOG_MAX_EVENTS} is reported
+ * unreadable without being read at all.
+ * @param ctx - host context carrying the optional persistence service.
+ * @param sessionId - the stored session to read.
+ * @param windowEvents - how many events of the log's end one row may fold.
+ * @param signal - cancellation for the open, probe, and read.
+ * @returns the bounded read, or `unreadable` when no read seam exists, it refused, or the log is too long to walk.
+ * @throws the cancellation reason when `signal` aborts the read.
+ */
+export declare function coldRead(ctx: Context, sessionId: SessionId, windowEvents?: number, signal?: AbortSignal): Promise<ColdLog>;

package/lib/types/composition.d.ts

@@ -0,0 +1,94 @@
+/**
+ * Rebuild the scoped Agent composition a parked Session ran under.
+ *
+ * Activation is not only a persisted Session: the Agent preset supplies the
+ * scoped tools, prompt sections, skills, and — for a subagent child — the
+ * delegation context, persona, and tool restriction that were in force before
+ * the park. A resume that loads the log without that setup starts a different
+ * Agent on the same history.
+ *
+ * The preset a Session runs is the `agentPreset` projection, never the
+ * creation-time header alone: a blank Session may select another preset before
+ * its first turn, and the projection records the selection that actually ran.
+ * A child with no independent selection joins its live parent's preset
+ * generation; one that selected independently mounts the projected preset.
+ * The durable child descriptor supplies the persona, tool filter, and route
+ * that are reapplied only on cold resume.
+ *
+ * Both services are optional. A profile without `agentPresets` has no scoped
+ * preset composition to restore, and this module leaves the resume unchanged.
+ * A profile that mounts one but cannot read the Session projection cannot
+ * prove what composition the Session ran, so it fails the resume instead of
+ * silently starting a different Agent.
+ * @module dsh-pause-session/composition
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { Agent, AgentOptions, AgentSetup } from '@deepseek-ai/dsh-agent';
+import type { SessionEvent, SessionId } from '@deepseek-ai/dsh-session';
+/** The setup and route options a resumed Agent receives from its stored composition. */
+export interface RestoredComposition {
+    /** The durable child route, when the descriptor recorded one. */
+    readonly agentOptions?: AgentOptions;
+    /** The scoped Agent world to mount before the Agent is published. */
+    readonly setup?: AgentSetup;
+}
+/**
+ * A stored subagent route that no resume may reactivate.
+ *
+ * A one-shot child is terminal by contract; activating it as a root Agent
+ * would turn a finished delegation into an ordinary conversation that happens
+ * to share its Session id.
+ */
+export declare class UnresumableSessionError extends Error {
+    constructor(sessionId: SessionId);
+}
+/**
+ * Whether the child's own log selected a preset before its descriptor.
+ *
+ * The creation-time selection precedes the first `subagent/descriptor`; a
+ * selection after the descriptor belongs to the child's own later history and
+ * does not decide which composition cold resume joins. This mirrors the
+ * subagent runtime's own cold-resume rule.
+ * @param events - the child's own log suffix, without the fork-inherited prefix.
+ * @returns whether the child carries an independent preset selection.
+ */
+export declare function hasIndependentPresetSelection(events: readonly SessionEvent[]): boolean;
+/**
+ * Whether a local Session may be parked under a promise of a later resume.
+ *
+ * A normal root Session has no child descriptor and is resumable. A local
+ * subagent child is resumable only when its own durable descriptor is
+ * `continuable`; a historical `one-shot` child is terminal and must never be
+ * registered as a park the morning path would later have to refuse. External
+ * executions have no local Session, so callers never reach this check.
+ *
+ * A profile without the optional Session-query service cannot prove the
+ * descriptor's mode; it keeps the previous permissive behavior rather than
+ * dropping every subagent. The web profile mounts the query service.
+ * @param ctx - host context carrying the optional Session-query service.
+ * @param sessionId - the local Session to inspect.
+ * @param signal - cancellation for the observation read.
+ * @returns whether a park of this Session may be resumed.
+ * @throws the cancellation reason when `signal` aborts the read.
+ */
+export declare function isResumableSession(ctx: Context, sessionId: SessionId, signal?: AbortSignal): Promise<boolean>;
+/**
+ * Read one parked Session's stored composition and build the resume options.
+ *
+ * The returned `setup` belongs to the unpublished Agent scope, so all
+ * registrations exist before `agent/created`. For a root Session the setup
+ * mounts the Session's projected preset, or the profile's default when the
+ * Session never selected one. For a child under a live parent it applies the
+ * child composition: an independent preset mounts separately, while an
+ * inherited composition joins the parent's current generation; the historical
+ * descriptor's persona and tool filter are reapplied in both cases.
+ * @param ctx - host context carrying the optional preset and Session-query services.
+ * @param sessionId - the parked Session being resumed.
+ * @param parent - the live direct parent, when a child is resumed under it.
+ * @param signal - cancellation for the observation read.
+ * @returns the Agent options and setup to pass to `agents.resume`.
+ * @throws {UnresumableSessionError} when the stored child route is one-shot.
+ * @throws when a mounted preset roster cannot read the Session projection, or
+ * a recorded preset cannot be restored.
+ */
+export declare function restoreComposition(ctx: Context, sessionId: SessionId, parent: Agent | undefined, signal?: AbortSignal): Promise<RestoredComposition>;

package/lib/types/control.d.ts

@@ -0,0 +1,114 @@
+/**
+ * The session control the browser half drives: the pause verb, the park state
+ * machine behind it, and the live state channel that accompanies both.
+ *
+ * A third-party plugin can add neither a `ctx.remote` namespace nor a forwarded
+ * event: the Client's Remote namespaces and the forwarded-event allowlist are
+ * compiled into the harness's own API assembly. The documented Client-callable
+ * Host entry point is therefore a session command run through
+ * `ctx.remote.commands.execute`, and the one live channel such a plugin can
+ * publish through is the command registry itself — `commands/change` is a
+ * forwarded event, and `commands.list(sessionId)` is a Client-callable read.
+ *
+ * That same registry is how a phase change leaves this process: a transition
+ * re-registers the status verb, which emits the change a client needs to read
+ * the new phase. It is the only way a third-party plugin can announce anything,
+ * and it is what makes the flush that resolves `parking` into `safe` observable
+ * at all — that step changes no registration of its own.
+ *
+ * So the resume definition IS the paused marker: it is registered on a paused
+ * session's own agent context and removed on resume, and the browser half reads
+ * "paused" from that registration rather than inventing it. A descriptor cannot
+ * change after registration, so the park state rides a companion status
+ * definition (registered beside the marker) whose answer is derived per call
+ * rather than frozen into a descriptor — see `./shared.ts`. That one read
+ * carries the record's goal opt-out too, so the session-header control can show
+ * and switch it while the session is parked and clean — the state in which a
+ * silent morning resume would otherwise spend the user's rounds unasked. The
+ * switch is addressed to the session it changes, so it needs no listed row.
+ *
+ * The header control is the user's button for ONE session's work, and that work
+ * includes the subagents under it: the press registers the session and its
+ * descendant tree, the release takes the same tree back, and the status the
+ * header shows is the worst phase among the members the press registered. The
+ * whole-app control covers every running tree and answers for all of them; this
+ * one answers for the tree it owns.
+ *
+ * A mark is not a park. A session is parked only once nothing is left to drain:
+ * no call in flight AND either its next model request is held at the gate or no
+ * turn is open at all (there will be no next request to hold). Only then is the
+ * session flushed, at the session level — `SessionHandle.flush()` does not
+ * drain the routed live buffer, so it would record a park that a crash erases.
+ * The "safe to close" phase appears only after that flush resolves.
+ *
+ * Every phase a pause reaches is written to the durable registry before it is
+ * published — including the move into `parking`, which the status command may
+ * therefore never serve ahead of the record. A restart re-holds exactly the
+ * sessions the last process left parked, and a phase that could not be recorded
+ * is never shown as cleaner than the record says.
+ *
+ * A park verb changes state, so it acts only on a person's command: a command
+ * dispatched from inside a model turn is refused. The listed verbs add the
+ * one binding their target needs — the row must be one the calling session was
+ * shown — and that rule lives with the list (`./triage.ts`).
+ * @module dsh-pause-session/control
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import { SessionId } from '@deepseek-ai/dsh-session';
+import type { PauseGate } from './gate.js';
+import type { ParkWatch } from './park.js';
+import type { ParkRegistry } from './registry.js';
+import type { ResumeAttempt, ResumeOptions } from './resume.js';
+/**
+ * Result copy for a state-changing park verb issued from inside a model turn.
+ * The invocation carries no origin of its own, so this refusal is the plugin's
+ * own reading of the one signal that separates a person's command from a
+ * model's.
+ */
+export declare const UNATTENDED_TEXT: string;
+/** What one tree-wide press registered, and what it could not. */
+export interface PressTreeOutcome {
+    /** How many sessions this press covered: the session plus its descendants. */
+    readonly members: number;
+    /** How many of them now have a durable park record behind them. */
+    readonly registered: number;
+    /** Whether the pressed session itself is one of them. */
+    readonly rootRegistered: boolean;
+    /** The members whose record could not be written; they are not paused. */
+    readonly unrecorded: readonly SessionId[];
+    /** Whether the tree walk itself failed, so the session's subagents were not covered. */
+    readonly unread: boolean;
+}
+/** What mounting the session control hands back to the plugin entry. */
+export interface SessionControl {
+    /**
+     * Hold every session the registry remembers and can read, and publish the
+     * marker for the ones that already have a live agent. Called once, right
+     * after mount.
+     */
+    adopt(): Promise<void>;
+}
+/** How resuming all parked sessions answers the command that asked for it. */
+export declare function summarizeResume(attempts: readonly ResumeAttempt[]): string;
+/**
+ * Everything the session control needs from the composition: the clean resume
+ * path's route knowledge, plus the bound the decision list reads each parked
+ * log under.
+ */
+export interface SessionControlOptions extends ResumeOptions {
+    /** Events of each stored log the decision list may fold per row; see `./coldlog.ts`. */
+    readonly maxListedLogEvents?: number;
+}
+/**
+ * Contribute the session control: the pause verb, the per-session status read,
+ * the global resume verb, and — for every paused session that has a live agent
+ * — the resume marker.
+ * @param ctx - host context carrying the command registry, the agent store, the
+ * session store, and the projection registry.
+ * @param gate - the pause gate this control drives and reflects.
+ * @param watch - the per-session activity fold the park predicate reads.
+ * @param registry - the durable pause list every phase change is written to.
+ * @param options - route knowledge the clean resume path needs, and the decision list's read bound.
+ * @returns the mount-time adoption step and the morning resume path.
+ */
+export declare function installSessionControl(ctx: Context, gate: PauseGate, watch: ParkWatch, registry: ParkRegistry, options: SessionControlOptions): SessionControl;

package/lib/types/gate.d.ts

@@ -0,0 +1,110 @@
+/**
+ * The pause gate: one session's hold at the model-request waterfall.
+ *
+ * The hold sits on the `llm/stream` waterfall, which is the only point that
+ * satisfies all four conditions at once: the previous step's tool calls have
+ * drained, the request is already built, the session's pending input is
+ * committed, and — because nothing pulls the adapter — no timer is armed
+ * anywhere. Machine sleep, network loss, and the adapter's stream-idle
+ * watchdog therefore cannot touch a parked request.
+ * @module dsh-pause-session/gate
+ */
+import type { GenerateOptions, StreamChunk } from '@deepseek-ai/dsh-llm';
+import type { SessionId } from '@deepseek-ai/dsh-session';
+/** Message of the failure a held request ends with when its plugin unloads first. */
+export declare const PLUGIN_UNLOADED = "pause: plugin lifetime ended while a request was held";
+/** Options of {@link PauseGate}. */
+export interface PauseGateOptions {
+    /** Aborted when the owning plugin unloads; a held request must never delegate after that. */
+    readonly lifetime: AbortSignal;
+}
+/** Per-session pause state and the waterfall listener that enforces it. */
+export declare class PauseGate {
+    private readonly options;
+    /** Paused sessions; membership IS the pause state. */
+    private readonly paused;
+    private readonly listeners;
+    private readonly heldListeners;
+    /**
+     * @param options - the plugin-lifetime signal every held request races.
+     */
+    constructor(options: PauseGateOptions);
+    /**
+     * Subscribe to pause-state changes.
+     * @param listener - called with the session whose state changed and its new state.
+     * @returns the unsubscribe function.
+     */
+    onChange(listener: (sessionId: SessionId, paused: boolean) => void): () => void;
+    /**
+     * Subscribe to "a request arrived at / left the gate" for a paused session.
+     *
+     * This is the moment a session can become parked, so it is also the moment a
+     * park observer has to look. Listeners run synchronously inside the request
+     * path: they must only record that a look is owed.
+     * @param listener - called with the session and whether it now holds a request.
+     * @returns the unsubscribe function.
+     */
+    onHeld(listener: (sessionId: SessionId, held: boolean) => void): () => void;
+    /**
+     * @param sessionId - session to inspect.
+     * @returns whether the session is currently paused.
+     */
+    isPaused(sessionId: SessionId): boolean;
+    /**
+     * @param sessionId - session to inspect.
+     * @returns whether a model request of that session is waiting at the gate
+     * right now. False for a session that is paused but whose loop has not built
+     * its next request yet — a running tool, for instance, is still draining.
+     */
+    isHeld(sessionId: SessionId): boolean;
+    /**
+     * Enter one request that is about to wait. The count rises synchronously with
+     * {@link hold}, so an observer notified at that moment reads `isHeld` as true.
+     * @param pause - the session's pause record.
+     * @returns the exit that lowers the count again.
+     */
+    private enter;
+    /**
+     * Pause one session: its next model request is held until {@link resume}. A
+     * request already past the waterfall keeps running — pausing never
+     * interrupts a model call or a tool call that has started.
+     * @param sessionId - session to pause.
+     * @returns whether this call changed the state.
+     */
+    pause(sessionId: SessionId): boolean;
+    /**
+     * Resume one session: release everything it holds and stop holding what
+     * follows. The requests sent from then on are the ones built before the
+     * hold, so a resumed session continues from the point it stopped.
+     * @param sessionId - session to resume.
+     * @returns whether this call changed the state.
+     */
+    resume(sessionId: SessionId): boolean;
+    /**
+     * The wait one model request must finish before it may delegate, and the exit
+     * that reports the request as no longer waiting.
+     * @param request - the request reaching the waterfall.
+     * @returns the wait plus its release, or `undefined` when this gate does not
+     * hold that request.
+     */
+    hold(request: GenerateOptions): {
+        readonly wait: Promise<void>;
+        readonly left: () => void;
+    } | undefined;
+    /**
+     * The `llm/stream` listener.
+     *
+     * `ctx.waterfall` composes listeners synchronously, so this returns an async
+     * iterator synchronously — an `async` listener would hand the loop a promise
+     * where it iterates a stream. One generator body reaches `next()` at most
+     * once, which is what makes delegation single-shot per HELD request; a flag
+     * shared across requests would also short-circuit everything issued after
+     * the release.
+     * @param request - the full request, already built and frozen by the loop.
+     * @param next - the downstream waterfall chain.
+     * @returns the stream, delayed until this request may delegate.
+     */
+    readonly stream: (request: GenerateOptions, next: () => AsyncIterable<StreamChunk>) => AsyncIterable<StreamChunk>;
+    private notify;
+    private notifyHeld;
+}

package/lib/types/global.d.ts

@@ -0,0 +1,101 @@
+/**
+ * The whole-app park: one action that registers every running session tree,
+ * and the aggregate answer to "can I close the lid?".
+ *
+ * The per-session control owns one session's park; this module owns the set.
+ * It reads three real sources and never infers what they can say themselves:
+ *
+ * - `ctx.agents.list()` plus the park activity fold decide which sessions are
+ *   running. A session with no live agent is not running, and a session with
+ *   nothing unfinished — no tool in flight, no turn open, no delivery the loop
+ *   has not claimed — is left alone.
+ * - The subagent runtime's descendant rows decide the tree and the one-shot
+ *   fact. A row's `mode` is the harness's own durable record of whether that
+ *   child can be resumed after a restart; a branch the walk could not read is
+ *   reported as unread rather than assumed clean.
+ * - The job registry decides which background jobs belong to the registered
+ *   trees. Those run outside the agent loop: this plugin cannot stop them, so
+ *   it names them.
+ *
+ * The aggregate is derived in one place so the host's answer and the browser's
+ * reading of it cannot disagree, and it is a promise about the durable
+ * registry: a session is `safe` only when its recorded phase says so.
+ * @module dsh-pause-session/global
+ */
+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 { ParkWatch } from './park.js';
+import type { ParkRegistry } from './registry.js';
+import type { ParkPhase } from './shared.js';
+/** One session's live park state, as the per-session control sees it. */
+export interface LivePark {
+    readonly phase: ParkPhase;
+    /** Whether this process can still walk the session to a flushed park. */
+    readonly moving: boolean;
+}
+/** What one press of the per-session control did. */
+export type PressResult = 'registered' | 'unrecordable' | 'not-live' | 'not-resumable' | 'already-paused';
+/** What the whole-app control needs from the per-session control. */
+export interface GlobalPauseDeps {
+    /**
+     * @param sessionId - session to inspect.
+     * @returns whether a press already owns this session.
+     */
+    isPaused(sessionId: SessionId): boolean;
+    /**
+     * Press one session's pause and make it durable.
+     * @param sessionId - session to register.
+     * @param signal - cancellation for the resumability and registry reads.
+     * @returns what the press did; only `registered` created a new park.
+     */
+    press(sessionId: SessionId, signal?: AbortSignal): Promise<PressResult>;
+    /**
+     * Look at one session's mark now that it is paused.
+     * @param sessionId - the session that was just pressed.
+     */
+    look(sessionId: SessionId): void;
+    /**
+     * @returns every session a live mark owns, with the phase it reports now.
+     */
+    live(): ReadonlyMap<SessionId, LivePark>;
+    /**
+     * @returns every registered session this process could not hold again — a
+     * record whose session cannot be read here, so nothing in this process can
+     * park it, release it, or act on it.
+     */
+    unheld(): ReadonlySet<SessionId>;
+}
+/** The whole-app park, as the plugin entry drives it. */
+export interface GlobalPause {
+    /**
+     * Register and park every running session tree in one action. Sessions this
+     * pause already owns are left where they are; an idle session is not touched.
+     * @param signal - cancellation for the tree reads this action performs.
+     * @returns the aggregate as of this action's end.
+     */
+    pressAll(signal?: AbortSignal): Promise<CommandResult>;
+    /**
+     * @param signal - cancellation for the tree reads this read performs.
+     * @returns the aggregate as of this read.
+     */
+    readStatus(signal?: AbortSignal): Promise<CommandResult>;
+    /**
+     * Report one session a press could not register, so the aggregate names it.
+     * The whole-app action records that fact for its own targets; a press of a
+     * session's tree reports the members the registry refused through here.
+     * @param sessionId - the session a press tried and failed to register.
+     * @param unrecorded - whether it is now known to be unparked for that reason.
+     */
+    markUnrecorded(sessionId: SessionId, unrecorded: boolean): void;
+}
+/**
+ * Mount the whole-app park.
+ * @param ctx - host context carrying the agent store and the optional subagent
+ * and job services.
+ * @param watch - the activity fold that says whether a session has unfinished work.
+ * @param registry - the durable list this aggregate is a promise about.
+ * @param deps - the per-session press and the live phase of every mark.
+ * @returns the one-press action and the aggregate read.
+ */
+export declare function mountGlobalPause(ctx: Context, watch: ParkWatch, registry: ParkRegistry, deps: GlobalPauseDeps): GlobalPause;