@avantf/dsh-mission 0.3.0

package/lib/types/host.d.ts

@@ -0,0 +1,752 @@
+import { Context } from '@deepseek-ai/cordis';
+import { TypertRemoteService } from '@deepseek-ai/dsh-typert-protocol';
+import type { Agent } from '@deepseek-ai/dsh-agent';
+import { type CapacityReading, type ChildSpec, type ContinuationDelta, type MutationResult, type NodeRecord, type OwnerProbe, type ResourceProbe, type TreeRecord, type WaitingFor, type WellFormedSource } from '../mission-core/index.js';
+import { type MissionLogger } from './log.js';
+/**
+ * The v1 host implementation of the core's {@link ResourceProbe}. It uses ONLY the unified Node API
+ * — `os.availableParallelism()` (respects cgroup CPU quotas and affinity), `os.totalmem()` /
+ * `os.freemem()`, and `process.constrainedMemory()` — and this function is the ONE seam where a
+ * platform branch is allowed to exist. Platform adapters (POSIX/Windows pressure, per-worker process
+ * attribution) are deliberately NOT implemented here: `pressure()` answers `null` ("no signal on
+ * this platform"), which no caller may read as "idle".
+ */
+export declare function createHostResourceProbe(): ResourceProbe;
+/** Whether the tree owner should be allowed into a proposed step. */
+interface AdmitDecision {
+    readonly admit: boolean;
+    readonly reason: string;
+}
+/** One node as the browser half renders it — the ROW projection. Deliberately without `description`
+ *  or the submitted result: both are re-sent on every engine change and a row renders neither. */
+interface NodeView {
+    readonly id: string;
+    /** Where this node was BORN (`null` for a root), NOT the dependency edge: a reused prerequisite
+     *  keeps its birth parent while appearing in several parents' `children` — read the graph via `children`. */
+    readonly parentId: string | null;
+    /** The ids this node actually depends on — the authoritative edge (see `parentId`). */
+    readonly children: readonly string[];
+    readonly depth: number;
+    readonly title: string;
+    /** Legacy: the row sends `[]` (the texts are in {@link NodeDetail.context}); an OLDER host still
+     *  sends them, which is why the field is still on the wire. Read the count, not this. */
+    readonly context: readonly string[];
+    /** How many premises this mission carries. The row renders the count; the texts are in the detail. */
+    readonly contextCount: number;
+    /** The owner's corrections, newest last. Carried in the ROW projection (unlike `description` and
+     *  the submitted result) because a row has to say the mission was steered: `title` is frozen at
+     *  creation, so a corrected mission otherwise reads as "goal X, result of Y" with nothing between
+     *  them to explain the difference. Bounded to the newest {@link ROW_CORRECTIONS_MAX}: a row renders
+     *  only the count, and every text is in the detail. */
+    readonly corrections: readonly string[];
+    /** The owner's FULL correction count, independent of the capped array above. */
+    readonly correctionCount: number;
+    readonly status: string;
+    readonly attempts: number;
+    readonly createdAt: number;
+    /** When this node was FIRST dispatched, or `null` while it is still queued (see
+     *  `@avantf/mission-core`'s `NodeRecord.dispatchedAt`). Carried in the ROW projection: the row's
+     *  compact timing marker is derived from it, and an older host omitting it reads as `null`. */
+    readonly dispatchedAt: number | null;
+    /** When this node entered a terminal status, or `null` while it is still in play. Carried in the
+     *  ROW projection for the same reason as {@link dispatchedAt}. */
+    readonly endedAt: number | null;
+    readonly hasResult: boolean;
+    readonly resultRef: string | null;
+    /** The session that ran this node LAST, or `null` when none ever did (see `workerSessionIdOf`). */
+    readonly workerSessionId: string | null;
+    /** Whether that handle is still running (see `workerLiveOf`), so the panel can say 进行中 / 已结束. */
+    readonly workerLive: boolean;
+    /** Declared capacity weight (cores-equivalent); persisted, so it survives a restart. */
+    readonly weight: number;
+    /** Why the engine has not dispatched this node yet, or `null`. Carried in the ROW projection
+     *  because a queued mission that looks identical to a ready one is exactly the confusion the
+     *  `waitingFor` projection exists to remove. */
+    readonly waitingFor: WaitingFor | null;
+}
+/** One mission's full detail, as the expanded row renders it. */
+export interface NodeDetail {
+    readonly id: string;
+    readonly rootId: string;
+    readonly title: string;
+    readonly description: string;
+    readonly context: readonly string[];
+    /** The owner's corrections, newest last: the direction changes this mission has been given, in the
+     *  order they arrived. Rendered as its own block so the goal above and the result below are read
+     *  in the light of them, and so a mission can be traced back to why it ended up where it did. */
+    readonly corrections: readonly string[];
+    /** What this mission's executors recorded, oldest first; exposed so an operator reads the judgement a
+     *  re-dispatched executor sees (the panel does not render it yet). */
+    readonly analysisNotes: readonly string[];
+    /** The dispatch (`attempts`) that wrote the last entry; `0` when none. */
+    readonly analysisAttempt: number;
+    readonly status: string;
+    readonly attempts: number;
+    readonly depth: number;
+    /** When this node was accepted into the tree. Carried in the detail projection (not the row) because
+     *  the dialog's full timing line is the only place the 受理 instant is shown. */
+    readonly createdAt: number;
+    /** When this node was FIRST dispatched, or `null` while it is still queued. The detail dialog shows
+     *  it beside `createdAt`/`endedAt`; the row carries the compact form. */
+    readonly dispatchedAt: number | null;
+    /** When this node entered a terminal status, or `null` while it is still in play. */
+    readonly endedAt: number | null;
+    /** The submitted conclusion, when there is one (inline; a long one is truncated). */
+    readonly result: string | null;
+    /** Where a spilled full result lives, joined with its retrieval hint. */
+    readonly resultPointer: string | null;
+    /** The session that ran this node LAST, or `null` when none ever did (see `workerSessionIdOf`). */
+    readonly workerSessionId: string | null;
+    /** Whether that handle is still running (see `workerLiveOf`), so the panel can say 进行中 / 已结束. */
+    readonly workerLive: boolean;
+    /** Declared capacity weight (cores-equivalent). */
+    readonly weight: number;
+    /** Why this node is queued rather than running, or `null`. */
+    readonly waitingFor: WaitingFor | null;
+}
+/** One sub-mission of a node, with the conclusion it submitted. */
+interface NodeDetailChild {
+    readonly id: string;
+    readonly title: string;
+    readonly status: string;
+    readonly result: string | null;
+    readonly resultPointer: string | null;
+}
+/** One tree with its nodes, as the browser half renders it. */
+interface TreeView {
+    readonly rootId: string;
+    readonly nodes: readonly NodeView[];
+    readonly closedAt: number | null;
+}
+/** One tree summarized for the owner-facing tools. */
+interface MissionSummary {
+    readonly tree: TreeRecord;
+    readonly root: NodeRecord | undefined;
+    readonly counts: Readonly<Record<string, number>>;
+    /** Whether the owner closed the tree out; its results stay readable. */
+    readonly closed: boolean;
+    /**
+     * Whether this mission carries a HISTORY of trouble (stalls/failures at the engine's floors). The
+     * counters never reset, so it stays true for the mission's life — hence the past tense. The one engine
+     * state an owner tool surfaces (only one it can act on); per-state `counts` stay for the human-facing
+     * surfaces — the `/mission` command and the "任务" view.
+     */
+    readonly troubled: boolean;
+}
+/** One orphaned tree as `/clean orphans` renders it: the durable record, the probe that says why,
+ *  and the root's status. `unobservable` is the operator's business; `missing` is already cleaned
+ *  by the next reconciliation and is listed only so the count adds up. */
+export interface OrphanTreeReport {
+    readonly rootId: string;
+    readonly ownerSessionId: string;
+    readonly createdAt: number;
+    readonly closedAt: number | null;
+    /** The root mission's status at read time, so a closed-but-orphaned tree reads differently. */
+    readonly rootStatus: string;
+    readonly probe: OwnerProbe;
+}
+declare module '@deepseek-ai/cordis' {
+    interface Context {
+        avantfMission: AvantfMissionHost;
+    }
+}
+interface HostOptions {
+    /** Slot ceiling on the NUMBER of concurrent units; omitted means "CPU cores minus one". Capacity is
+     *  the master gate — both must admit a dispatch (see `@avantf/mission-core`'s `EngineOptions`). */
+    readonly maxConcurrent?: number;
+    /** The capacity gate, in cores-equivalent. Omitted means "derive it from this machine"
+     *  (`availableParallelism` → `cpus().length` → 4, minus one reserved core). */
+    readonly capacity?: number;
+    /** How long a node may be deferred by the capacity gate before it reserves the machine; omitted
+     *  means the core default, and a value below the floor is raised to it with a warning. */
+    readonly capacityWaitMs?: number;
+    /** Free-memory floor in bytes; omitted means the core default, `0` disables the gate. */
+    readonly minFreeMemoryBytes?: number;
+    /** Machine reader; omitted means the host's Node implementation ({@link createHostResourceProbe}).
+     *  Injectable so a composition or test can fix every signal deterministically. */
+    readonly probe?: ResourceProbe;
+    /** How long a worker may produce nothing before it counts as stuck. */
+    readonly staleMs?: number;
+    /** Wall-clock ceiling on one dispatch round, however much it keeps reporting; omitted means one hour. */
+    readonly roundMs?: number;
+}
+export declare class AvantfMissionHost extends TypertRemoteService {
+    private tree?;
+    private engine?;
+    private domain?;
+    private sweepDispose?;
+    /**
+     * Extra best-effort passes to run after every sweep. Automatic worker retention registers here so
+     * it rides the EXISTING sweep cadence instead of arming a second timer. The host never awaits a
+     * pass: a slow or failing one must not delay dispatch, and a rejection is reported, not surfaced.
+     */
+    private readonly sweepListeners;
+    private readonly workerAborts;
+    /** Every child session id reserved for a worker, for the process lifetime: answers "is this settling
+     *  agent one of ours?" even after the node's binding is gone. */
+    private readonly issuedClaims;
+    /** Owner session ids this host has dispatched a worker for (hook scoping). */
+    private readonly dispatchedFor;
+    /** Claims bound but not yet accepted by the child. A worker is "live" from reservation: a sweep in
+     *  that gap would otherwise reclaim a starting worker and pay for a duplicate run per node. */
+    private readonly startingClaims;
+    /**
+     * Sessions whose WAKE is in flight: live from the adoption that binds them until the resumed
+     * agent is observed, the delivery reports a failure, or the engine gives up on the binding.
+     *
+     * Two wakes use this one guard, for the same reason — the target session is IDLE, so the liveness
+     * check alone reads a freshly adopted binding as vanished:
+     *
+     * - a PARKED session (it decomposed and ended its turn, which is exactly what "parked" means);
+     * - a session recorded in `lastWorkerId` that a restart demoted (`cold wake`).
+     *
+     * The sweep triggered by the LAST CHILD's own `subagent/end` runs in the same moment as the
+     * owner's wake, so without this guard it reclaims the binding the wake is delivering into: the
+     * cold resume still lands, the old executor burns a whole extra round, and its `submit_mission` is
+     * refused because the node was already re-dispatched to a fresh claim. Measured in a real run
+     * (2026-09-22): 8 wasted minutes, two `not-owner` refusals, and `attempts`/`failures` charged an
+     * extra time each — the failures are the dangerous half, because they spend the budget that ends a
+     * node.
+     */
+    private readonly wakingClaims;
+    /** Per-owner change counters and the open `watch` streams waiting on them: how "the tree changed"
+     *  reaches the browser without polling or session-log writes. */
+    private readonly revisions;
+    private readonly waiters;
+    /** Recent durable owner-probe answers, so a sweep cannot hammer storage. `unobservable` is cached
+     *  like any other verdict for the TTL; a delete re-probes fresh rather than trusting it. */
+    private readonly ownerChecks;
+    /** The orphan set the last aggregate report described, so a sweep that changes nothing is silent.
+     *  Missing trees are absent from it: reconciliation destroys them in the same pass that reports. */
+    private orphanReportSignature;
+    /** Parked nodes the owner has already been told about. `reportParkedReady` fires on every pump, so
+     *  without this the owner's inbox accumulates one wake per pass; an entry is dropped when the node
+     *  leaves the parked state, so it never outlives its condition. In-memory on purpose: after a restart
+     *  one extra signal is harmless. */
+    private readonly parkedSignaled;
+    /** Sweep failures fold into the next warning; `undefined` means none has been logged yet. */
+    private sweepFailureWarnedAt;
+    private sweepFailuresSinceWarn;
+    /** Own workers that settled this process; the retention pass reads it to skip empty sweeps. */
+    private workerSettlements;
+    private readonly log;
+    /**
+     * @param wellFormed - the family's well-formed repair, resolved by `apply()` from the loaded base
+     * kit (`resolveWellFormed(compat?.kit)`) and defaulted to the core's local copy. It is threaded to
+     * the three boundaries this host owns — the tree's inbound funnel (via `TreeDeps.wellFormed`), the
+     * worker prompt and the progress line (via `buildWorkerPrompt`'s third argument), and the model
+     * tool results (read by `defineWorkTools`) — so one resolution decides all of them.
+     */
+    constructor(ctx: Context, options?: HostOptions, log?: MissionLogger, wellFormed?: WellFormedSource);
+    /** The repair pair every model-visible boundary of this host uses; see the constructor. */
+    readonly wellFormed: WellFormedSource;
+    private readonly maxConcurrent;
+    private readonly capacityOption;
+    private readonly capacityWaitMsOption;
+    private readonly minFreeMemoryBytesOption;
+    /** The machine reader; injectable, always present (the Node implementation is the default). */
+    readonly probe: ResourceProbe;
+    private readonly staleMs;
+    private readonly roundMs;
+    private ready;
+    /** Record the start-up promise for a caller that wants a fully opened tree; the tools never need it,
+     *  but a composition or test may. */
+    markReady(ready: Promise<void>): void;
+    /** Diagnostic sink for dispatch decisions: the host logger is buffered in some compositions, so a
+     *  mount test needs an observable channel. Unset means silent. */
+    onDispatchTrace?: (message: string) => void;
+    private trace;
+    /** Resolve once storage is open, trees are loaded and orphans reconciled. */
+    whenReady(): Promise<void>;
+    /** Workers allowed at once: the configured value, or cores minus one (the owner's own turns are not
+     *  the only agent here). This is the SLOT ceiling, not the capacity gate — see {@link capacityReading}. */
+    concurrency(): number;
+    /**
+     * The capacity the engine gates on, plus WHERE it came from (the start-up line reports the source).
+     *
+     * The derivation chain lives in the core (`deriveCapacity`), so it is testable without a machine:
+     * ① explicit config → ② `os.availableParallelism()` (honours cgroup quotas and affinity) →
+     * ③ `os.cpus().length` → ④ a default of 4; then one core is reserved for the host/UI. An explicit
+     * config is used AS GIVEN, clamped: the operator's number already is the answer.
+     */
+    capacityReading(): CapacityReading;
+    /** How long a node may be repeatedly deferred by capacity before it reserves the machine. Floored
+     *  like the other windows: below a minute a reservation is indistinguishable from jitter. */
+    capacityWaitWindowMs(): number;
+    /** The free-memory floor in bytes; `0` disables the gate. The probe may still answer `null`, which
+     *  DEFERS dispatch — "cannot confirm the floor" is never read as "plenty of memory". */
+    freeMemoryFloorBytes(): number;
+    /** Silent time before the engine calls a worker stuck. The 60 s floor exists because the check rides
+     *  a 60-second sweep: a shorter window would interrupt every worker on its first pass. */
+    staleWindowMs(): number;
+    /** Wall-clock ceiling on one dispatch round. Deliberately generous, and floored like `staleMs`:
+     *  it is the backstop for a worker that keeps being HEARD FROM (retries, route snapshots) while
+     *  producing nothing, so a small configured value must not interrupt a round that is merely slow.
+     *
+     *  The floor is `max(10 min, staleMs)`, not a bare constant: a round cap BELOW the output window
+     *  would fire before `stalled` ever can, which would quietly retire the rule that a repeatedly
+     *  silent node runs out of failure budget. Tying it to the window the caller actually configured
+     *  keeps that rule true for every configuration, not just the defaults. `staleMs` is passed in so
+     *  the two windows are resolved from ONE reading (and one warning) during open. */
+    roundWindowMs(staleMs?: number): number;
+    /**
+     * Open storage, reconcile, and arm the sweep. The domain opens exactly once (`storage-domain`
+     * refuses a second open).
+     *
+     * **This promise NEVER rejects.** Measured on the installed loader, a start-up failure has exactly
+     * three outcomes, and all three argue for absorbing it here:
+     * - `apply` throws, or awaits a rejection → only THIS entry fails (0.1.7 / 0.2.0 lines). That is
+     *   contained, but it still costs the whole plugin row over what is an environmental fault.
+     * - an UNHANDLED rejection → a process-level fatal (`installFailLoud` → `exit(1)`) on every
+     *   generation. A storage hiccup must never take down the host.
+     * - on the 0.1.5 line, any inactive row makes the whole boot throw.
+     *
+     * So a failure that lands while the fiber is alive is recorded as {@link degradedReason} and the
+     * plugin mounts DEGRADED: the tools stay registered and answer the reason, `/mission` reports it,
+     * and the process keeps running. A failure that lands after unmount is teardown noise.
+     */
+    start(): Promise<void>;
+    private starting?;
+    /** Why start-up ended DEGRADED, or `undefined` while healthy (or still opening). Set at most once. */
+    private degradedReasonValue?;
+    /**
+     * The DEGRADED marker the tool surface and `/mission` read: `undefined` means the engine opened
+     * normally, a string is the cause the storage domain could not be opened. Kept separate from
+     * `whenReady()` on purpose — readiness still RESOLVES on the degraded path, so nothing that awaits
+     * it can mistake a degraded mount for a rejected one.
+     */
+    degradedReason(): string | undefined;
+    private open;
+    /** Whether this plugin's Cordis fiber is still active: Cordis clears `fiber.uid` on disposal, after
+     *  which a required-service read throws `INACTIVE_EFFECT`. Reads the FIBER-SCOPED `this.ctx` from
+     *  construction; a context without a readable fiber (a test stub) counts as active. */
+    private stillActive;
+    stop(): Promise<void>;
+    /** Run one dispatch pass. Every trigger funnels here. */
+    pump(): Promise<number>;
+    /** Reclaim vanished bindings, then dispatch. Called on worker lifecycle edges (a `running` node may
+     *  have lost its worker without submitting) and by the periodic sweep. */
+    sweep(): Promise<{
+        reclaimed: number;
+        dispatched: number;
+    }>;
+    /**
+     * Register one best-effort pass to run after every {@link sweep}. Used by automatic worker
+     * retention, which must ride the existing cadence rather than arm a second timer. The pass is
+     * never awaited: it cannot delay or fail a sweep, and a rejection becomes one warning.
+     */
+    onSweep(pass: () => void | Promise<void>): void;
+    /** Fire each registered post-sweep pass without awaiting it. A throw or rejection is a warning. */
+    private runSweepListeners;
+    /**
+     * Report a background sweep that threw. The chain the two fire-and-forget callers start is not
+     * cosmetic: it flushes progress (a durable write), probes storage for orphans and then reclaims
+     * and dispatches. Silently swallowing it hid a store that refuses `put` (a full disk, a domain
+     * gone) failing once a minute with zero evidence. Rate-limited, because the same condition
+     * repeats on every 60 s tick: the first failure speaks, later ones fold into one line per window.
+     */
+    private reportSweepFailure;
+    /** Every tree whose owner session did not resolve to `exists`, with the probe that says why.
+     *  `fresh` bypasses the probe cache: a listing a person acts on must not be up to five minutes
+     *  stale about whether a session came back. The startup/sweep path keeps the cache, because it
+     *  asks the same question about the same trees every sixty seconds. */
+    orphanTreeReports(options?: {
+        fresh?: boolean;
+    }): Promise<readonly OrphanTreeReport[]>;
+    /** Re-probe ONE tree's owner from durable storage, ignoring the cache: the check a delete must
+     *  make, so a session that came back between the listing and the delete keeps its tree.
+     *  `undefined` means the tree is gone (already destroyed, or an id that never named one). */
+    probeOrphanTree(rootId: string): Promise<OrphanTreeReport | undefined>;
+    /** Destroy one orphan tree: stop the workers it still holds, then remove it through the store.
+     *  Refuses nothing — the caller has already re-probed the owner and may only reach here for a
+     *  tree whose owner is missing or unobservable. */
+    destroyOrphanTree(rootId: string): Promise<boolean>;
+    /** Destroy the trees of owners that are PROVEN gone, and report the orphan set as one line.
+     *  Returns the destroyed root ids (the shape the engine's reconcile has always had). */
+    private reconcileOrphans;
+    /** The orphan set, probed one tree at a time with the cache bypassed. */
+    private probeEveryTreeFresh;
+    private orphanReportOf;
+    /** ONE line per distinct orphan set — never one per tree. The per-tree WARN this replaces was the
+     *  noise the user saw on every start: twelve old trees, twelve lines, for one host-side condition.
+     *  WARN when somebody has to decide (`unobservable`); INFO when reconciliation already cleaned up. */
+    private reportOrphans;
+    /** Record one worker's activity if the session is ours. The feed carries every session in the
+     *  process, so the claim check comes first; only "making no progress" is a stall.
+     *
+     *  The check is `isWorkerClaim`, NOT membership in `issuedClaims`: that set is in-memory and is
+     *  never refilled from the durable tree at start-up, while `MissionTree.reconcileOnOpen` explicitly
+     *  keeps a hot-reload survivor `running` and resets its clocks. A worker that survived the
+     *  reload therefore had every later progress event dropped, and after `staleMs` was interrupted and
+     *  reclaimed as stalled — burning one attempt and a `failures` slot on a worker that was working.
+     *  `nodeHeldBy` below still requires an actual binding, so the shape check cannot touch a stranger.
+     *
+     *  `output` is the CLASSIFICATION the caller made (see `workerEvents.ts`): every event is recorded
+     *  as life (`touchActivity`), but only real output moves the clock the stale check reads. That
+     *  split is what turns "the worker is still answering retries" from evidence of progress into what
+     *  it is — a worker the engine should reclaim as `hung`. */
+    touchWorkerProgress(sessionId: string, at: number, output: boolean): void;
+    /** A subagent run ended. For one of our workers this is the earliest moment its node can be judged —
+     *  reclaim now, not at the next sweep; the claim check comes first so foreign runs cost nothing. */
+    onSubagentEnd(childSessionId: string): void;
+    /**
+     * How many of this session's own workers have settled since start-up. Monotonic; the retention
+     * pass compares it against the value it last ran at, so a periodic sweep with no settlement does
+     * no session listing at all. A restart resets it, which is why the mount pass also runs once
+     * unconditionally.
+     */
+    get workerSettlementCount(): number;
+    /**
+     * Whether a claim resolves to a worker that is alive, still starting, or being WOKEN. A continuable
+     * child materializes asynchronously, and treating that window as "vanished" made a sweep reclaim the
+     * starting worker, re-dispatch, and leave the first with every `submit_mission` refused — two LLM runs
+     * for one attempt. A claim is live from reservation until the child accepts its prompt.
+     *
+     * The parked case is the same window with a different cause: the session is idle (that is what
+     * parking means) while the wake is being delivered, so a claim is live from the adoption until the
+     * resumed agent shows up. Seeing the agent ends the guard — it must not outlive the evidence.
+     */
+    workerLive(sessionId: string): boolean;
+    /**
+     * Steer one RUNNING root mission: record the correction and, when somebody holds it, hand it over now.
+     * The record is durable (a root outlives each dispatch while waiting for children); the live message
+     * reaches the executor already running. A finished root has nothing to steer and a non-root is
+     * refused — the owner steers what it handed out, not somebody's sub-tree.
+     */
+    adjustWork(agent: Agent, rootId: string, adjustment: string): Promise<MutationResult<{
+        readonly delivered: boolean;
+        readonly voided: number;
+    }>>;
+    /**
+     * Cancel the sub-tree below one held node. Live holders are captured BEFORE the mutation clears them,
+     * or a cancelled worker keeps burning a model call whose `submit_mission` can only be refused.
+     */
+    cancelSubworks(agent: Agent, nodeId: string): Promise<MutationResult<readonly string[]>>;
+    /** Whether a session id is a worker this host dispatched (this or a past generation). */
+    isWorkerClaim(sessionId: string): boolean;
+    /** Root a new mission. `unit` is the scope the mission will modify (a directory or file), or
+     *  `undefined`/blank for none: a tree whose root declares a scope serializes every one of its
+     *  executors against any other `running` mission declaring the same scope, across trees. `roundMs`
+     *  is the declared round-cap relaxation (see `NodeRecord.roundMs`); `undefined` keeps the engine's
+     *  configured cap. */
+    createWork(agent: Agent, title: string, description: string, analysis: readonly string[], unit?: string | null, weight?: number, roundMs?: number | null): Promise<MutationResult<NodeRecord>>;
+    /** The node is the durable carrier: the writing round is gone by the aggregate pass, which reads the
+     *  node's prompt. The write also stamps the `attempts` that `decompose` checks. */
+    recordAnalysis(agent: Agent, nodeId: string, analysis: string): Promise<MutationResult<NodeRecord>>;
+    decompose(agent: Agent, nodeId: string, children: readonly ChildSpec[]): Promise<MutationResult<{
+        created: readonly string[];
+        reused: readonly string[];
+    }>>;
+    submitResult(agent: Agent, nodeId: string, result: string): Promise<MutationResult<{
+        node: NodeRecord;
+        parentReady: boolean;
+    }>>;
+    /** Read a node's result, recording the read so the finish gate can open. */
+    readResult(agent: Agent, nodeId: string): Promise<MutationResult<NodeRecord>>;
+    /** Trees owned by one session, newest first, with status rollups and closure. */
+    listWorks(agent: Agent): readonly MissionSummary[];
+    finishWork(agent: Agent, rootId: string): Promise<MutationResult<NodeRecord>>;
+    cancelWork(agent: Agent, rootId: string): Promise<MutationResult<readonly NodeRecord[]>>;
+    /**
+     * Whether a proposed step should reach the model. The wake carries only a signal, so this decides on
+     * STATE: a tree this session owns must have something actionable. Otherwise the step is refused,
+     * which also discards the trigger message.
+     */
+    admitStep(agent: Agent): AdmitDecision;
+    /** Whether this plugin's wake/notice filtering applies: a session that owns a tree (closed included —
+     *  its worker may still settle) or one this host dispatched for. */
+    ownsTrees(agent: Agent): boolean;
+    /** Whether this agent may root a tree. One predicate for the tool's authority check and the prompt
+     *  section that teaches it: a session that cannot root must not be told how. */
+    canCreateTree(agent: Agent): boolean;
+    /**
+     * The guidance text for one owner, or `''` when it has nothing open. Closed trees are left out: their
+     * conclusions live in `mission_result`, and re-stating a finished tree is the snapshot churn the anchored
+     * wording avoids. Granularity matches `list_missions`: running count plus trouble history, nothing deeper.
+     */
+    guidanceFor(agent: Agent): string;
+    /**
+     * Everything the "任务" view renders for one session: one Remote method, so the client makes one call.
+     * The session id IS a parameter because a Remote invocation carries no caller identity; the trust
+     * model is "the local UI asks for the session it is showing", in the user's own host process.
+     *
+     * `wire` is the panel's version marker (see `wire.ts`): the client reads it to say "the two halves
+     * are out of step" instead of blanking the panel. `trees` keeps its shape, so an older client that
+     * has never heard of `wire` simply drops the extra key.
+     */
+    snapshot(args: {
+        sessionId?: string;
+    }): Promise<{
+        wire: number;
+        trees: readonly TreeView[];
+    }>;
+    /**
+     * One node's FULL result, read back from where an over-long one was spilled. On demand, never part
+     * of `detail`: a result that was spilled is spilled because it is big, and `detail` is re-read on
+     * every engine change while the dialog is open.
+     *
+     * The locator is the spill backend's, and the backend's contract says it is OPAQUE — `SpillStore`
+     * defines `saveText` and nothing else, on purpose. The one backend in use (`dsh-spill-local`) hands
+     * out an absolute path, so that is the case this reads; anything else answers with an error and the
+     * pane keeps the locator for a reader that knows the substrate (which is what the locator is FOR).
+     */
+    result(args: {
+        sessionId?: string;
+        nodeId: string;
+    }): Promise<{
+        text: string;
+        error?: string;
+    }>;
+    /** One node's full detail: a second read rather than more snapshot, since results run to 2 KB and the
+     *  summary is re-read on every change. Children's results feed an aggregate's conclusion. */
+    detail(args: {
+        sessionId?: string;
+        nodeId: string;
+    }): Promise<{
+        node?: NodeDetail;
+        children: readonly NodeDetailChild[];
+        error?: string;
+    }>;
+    /** The detail read itself, kept synchronous so a test can call it directly. */
+    detailOf(sessionId: string | undefined, nodeId: string): {
+        node?: NodeDetail;
+        children: readonly NodeDetailChild[];
+        error?: string;
+    };
+    /** The engine's live `waitingFor` for one node, or `null` when the engine is not up yet or nothing
+     *  is holding the node back. One accessor, so the row projection, the detail read and the tool
+     *  result cannot disagree about why a mission is queued. Public because the model-facing tools
+     *  render it too. */
+    waitingForOf(nodeId: string): WaitingFor | null;
+    /**
+     * W18: resolve the executor session of a node whose record has no `executorSessionId` — the
+     * historical nodes dispatched before that field existed. Called ONLY from a click; the panel's
+     * mount/render path never reaches it, which is the invariant that keeps a page load free of
+     * session-log reads.
+     *
+     * Resolution is `executorSession.ts`'s (three metadata filters, then a few log reads), and a hit
+     * is written back once so the next click costs nothing. The reply carries a REASON rather than an
+     * exception for every way it can fail: a miss is an ordinary outcome, and the panel has to be able
+     * to say which one it was ("never dispatched" and "the session is gone" are different sentences).
+     */
+    resolveExecutorSession(args: {
+        sessionId?: string;
+        nodeId: string;
+    }): Promise<{
+        sessionId?: string;
+        status?: 'resolved' | 'never-dispatched' | 'not-found' | 'unsupported';
+        error?: string;
+    }>;
+    /** The optional session-log reader, read at USE time (a headless deployment has none). Structural
+     *  typing, like every other optional service here: the plugin must not require it to mount. */
+    private sessionLogQuery;
+    /** Delete one WHOLE tree — the panel's "remove this mission" (the argument is a root id; a node is not an
+     *  addressable target). `finish_mission` is the other ending and keeps the record (archived). */
+    delete(args: {
+        sessionId?: string;
+        rootId: string;
+    }): Promise<{
+        deleted: readonly string[];
+        error?: string;
+    }>;
+    /**
+     * Delete EVERY closed tree this session owns, in one pass — the panel's "清理已完成" and
+     * `/clean missions all`.
+     *
+     * Guardrails, per tree: `ownerSessionId` must equal the caller (another session's tree is never
+     * even a candidate), and `closedAt` must be set (a tree that has not been retired through
+     * `finish_mission` is skipped and reported, never deleted). `finish` can only set `closedAt` on a
+     * terminal root, and `deleteTree` re-checks terminality, so a running tree cannot slip through —
+     * but a refusal is still bucketed rather than thrown. Deletion goes through the same
+     * `tree.deleteTree` the single-tree `delete` uses; the panel is told once, by owner.
+     */
+    cleanFinished(args: {
+        sessionId?: string;
+    }): Promise<{
+        deleted: readonly string[];
+        skipped: readonly string[];
+    }>;
+    /** Root ids of every tree one session owns, newest first (empty before the engine is ready). */
+    ownedTreeIds(sessionId: string): readonly string[];
+    /**
+     * Distinct owner session ids the task library knows about: the scope of per-owner background
+     * passes (automatic worker retention runs once per owner). Read from the durable trees, so it
+     * covers owners whose trees survived a restart, not just the ones seen this process. Empty before
+     * the engine is ready.
+     */
+    ownerSessionIds(): readonly string[];
+    /**
+     * Root ids of the trees one session owns and has CLOSED OUT (`finish_mission`): the batch-clean
+     * candidates. A tree whose nodes all reached a terminal status but which was never retired is
+     * deliberately NOT a candidate — completion is the owner's `finish_mission`, and such a tree stays
+     * deletable one at a time from the panel (the per-tree "删除" button).
+     */
+    finishedTreeIds(sessionId: string): readonly string[];
+    watch(args: {
+        sessionId?: string;
+    }, signal: AbortSignal): AsyncGenerator<{
+        revision: number;
+    }>;
+    /** Publish one change to every open stream of an owner. In-memory on purpose: a lost revision costs a
+     *  re-read, never correctness — nothing but the tree is authoritative. */
+    private announceOwner;
+    /** Publish a change for one tree, by its root id. */
+    private announceTree;
+    /** Publish a change for every tree the engine may have moved. */
+    private announceAllTrees;
+    /** Publish a change for the tree that holds one node. */
+    private announceNode;
+    /** Resolve on the next change for one owner, or as soon as the caller aborts. */
+    private nextChange;
+    /** Trees one session owns, flattened the way the view renders them. */
+    treesForSession(sessionId: string | undefined): readonly TreeView[];
+    /** Rollup of every tree this session owns, for diagnostics and tests. */
+    summary(agent: Agent): Record<string, number>;
+    /** Snapshot for the `/mission` command. */
+    describe(agent: Agent): string;
+    private requireTree;
+    /**
+     * What every exit of one start attempt must leave behind. A claim left in `startingClaims` reports its
+     * node live forever — a ghost holds a concurrency slot until the stall window — so both maps are
+     * cleared from every exit through this one definition.
+     */
+    private endStartAttempt;
+    /**
+     * Hand back a claim reserved for a dispatch that was then REFUSED: it was never bound to a node and
+     * no child was ever created for it, so it must neither stay "live" (a ghost in `startingClaims`
+     * reports its lane occupied) nor stay remembered as one of ours — nothing will ever settle under it.
+     */
+    private releaseUnboundClaim;
+    /** The parked-session address on one node, or `null`; exposed for tests proving a wake did NOT consume it. */
+    parkedWorkerOf(nodeId: string): string | null | undefined;
+    /**
+     * The drift a cold wake of this node would report right now, or `undefined` when the node is gone.
+     * Read-only and cheap: a test (and, later, the panel) can ask what the wake would say without
+     * performing one. The DECISION to continue or replace lives in `coldResume.ts`'s `resumeWorker`,
+     * which consults `isMaterialChange` on exactly this value.
+     */
+    continuationDeltaOf(nodeId: string): ContinuationDelta | undefined;
+    /** Test seam: the real code clears an entry only when the node leaves the parked state, so a test
+     *  driving ONE `notifyParkedReady` batch must remove its own setup's entries. */
+    forgetParkedSignals(): void;
+    /** Test seam: how many claim ids are remembered and how many count as live-but-still-starting. A
+     *  dispatch that was REFUSED must add to neither — otherwise the reservation leaks one per refusal. */
+    claimCounts(): {
+        issued: number;
+        starting: number;
+    };
+    /** The parked-and-ready nodes of one tree (test seam; the engine uses the tree's own query). */
+    parkedReadyNodesOf(rootId: string): readonly NodeRecord[];
+    /** One node's durable record as stored; for tests proving a wake charged NO budget. */
+    nodeFor(nodeId: string): NodeRecord | undefined;
+    /**
+     * Report the parked nodes whose children have all landed as ONE owner signal. Batched on purpose: an
+     * owner returning offline can find several ready at once, and one wake per node would be a storm.
+     * Delivery is per owner and state-based, so a pass with nothing to act on is dropped by the pre-step
+     * gate at zero model cost.
+     */
+    notifyParkedReady(nodes: readonly NodeRecord[]): void;
+    /**
+     * The port the continuation wake works through (see `coldResume.ts`): the host hands in the state
+     * and callbacks the delivery needs, and keeps the private members private. Rebuilt per call, which
+     * is a handful of references — and the mutable sets are passed by REFERENCE on purpose, because
+     * they are the same guards the rest of the host (and the sweep) reads.
+     */
+    private coldResumeDeps;
+    /**
+     * Wake every parked session whose children have landed; the protocol (guard → adopt → deliver,
+     * with `wake-failed` on a refused delivery) lives in `coldResume.ts`, and this is the delegation
+     * `index.ts` calls from the owner's pre-step.
+     */
+    wakeParkedWorkers(agent?: Agent): Promise<number>;
+    /**
+     * Try to continue a node in the session that was interrupted in it (the "cold wake"); the
+     * decision and the delivery live in `coldResume.ts`.
+     */
+    private resumeWorker;
+    /**
+     * Stamp the node with what the prompt that was just ACCEPTED shows the session, so a later cold
+     * wake can subtract it (`continuation.ts`). Called at the three places that hand a session its
+     * dispatch prompt, and only after the delivery resolved: a prompt the runtime refused was never
+     * read, so nothing may claim otherwise — and the bound-but-not-started window (`startingClaims`)
+     * must not grow an extra awaited writable step.
+     *
+     * Tolerant on purpose. This is bookkeeping ABOUT a prompt that already exists, so a refused or
+     * failed stamp (the node was reclaimed and re-dispatched in between; the store refused the write)
+     * must not fail the delivery. The cost is one conservative wake later: a missing baseline renders
+     * "the drift cannot be determined", never "nothing changed".
+     *
+     * Kept on the host rather than moved with the wakes: `startWorker` (a fresh spawn) stamps through
+     * the same method, so it belongs to the host's delivery bookkeeping, not to the continuation seam.
+     */
+    private recordBaseline;
+    private startWorker;
+    /**
+     * Start one child, dropping tool names the runtime refuses to restrict. The runtime's answer is
+     * authoritative and the pre-check cannot be exact: a child inherits its parent's PRESET composition,
+     * not the parent agent's own scope, so a name the parent can see may still fail the whole filter for
+     * the child. Dropping it loses isolation, which beats a tree that cannot dispatch at all.
+     */
+    private startChild;
+    /**
+     * The subset of one face's names this deployment offers. `toolFilter` (and `restrict()`) THROWS on a
+     * name no tool provides, so a hardcoded list would fail every dispatch in a composition without (say)
+     * the goal tools. Names a child cannot inherit are caught by the retry in `startChild`.
+     */
+    private deniableFor;
+    /** The owner-side face: executor-only tools, filtered to the names this deployment offers
+     *  (`restrict()` throws, and one throw would cost the owner its whole turn). */
+    ownerFaceFor(agent: Agent): readonly string[];
+    private interruptWorker;
+    /** The owner session of the tree that holds a given worker, if any. */
+    private findHolderTree;
+    /** Wake the owner: the message carries a signal only, the guidance layer supplying the content.
+     *
+     *  The timing rides along because this is the one message the owner reads at the moment a mission
+     *  ends, and a long run's whole question is "when did it start, and how long did it take?" — the
+     *  answer is already on the record by the time the engine reports a terminal root, so demanding a
+     *  separate `/mission` read would be pure friction. `describeTiming` also prints 等待中/进行中, but a
+     *  terminal root always has a concrete 派发→结束 pair. */
+    private notifyOwner;
+    /** Tell the owner that one node cannot get a worker started at all. Same shape as the stall heads-up
+     *  — the engine keeps retrying on its own (with a cooldown), so this is information, not a request —
+     *  and the same durable marker keeps either kind of trouble to one message per node. */
+    private notifySpawnTrouble;
+    /** Tell the owner that one node keeps going wrong. A heads-up, not a request: the engine has already
+     *  interrupted the worker and re-queued the mission. Two causes share the channel (the engine's
+     *  `escalateTrouble`), because both are the same fact from the owner's side — this mission keeps
+     *  needing to be taken back — and the wording names which one so the remedy is legible. */
+    private notifyStalled;
+    /** Log a `hung` reclaim. The engine recovered on its own and charged nothing, so there is nothing
+     *  for the owner to decide HERE and no wake is sent — but the line MUST be there, or a provider that
+     *  hangs (or only retries) every dispatch is invisible, which is exactly how W8 stayed unnoticed
+     *  for 7.5 hours. The streak is logged with it, because that is the number the owner escalation
+     *  (a few lines up in the engine) counts. */
+    private reportHung;
+    /**
+     * Log a capacity deferral. The engine already rate-limits to one line per node per minute, so this
+     * only formats: the exact line is `dispatch deferred: <node> needs N, capacity C, running R`, with
+     * the wait and reservation appended because the whole point of the aging rule is to be observable.
+     * Deliberately NOT a wake and NOT an `isTroubled` fact — queuing is normal.
+     */
+    private reportDeferred;
+    private deliverToOwner;
+    /** Persist an over-long result and hand back its locator WITH the backend's retrieval guidance: a
+     *  locator alone leaves the reader unable to fetch the text. No backend returns `null`. */
+    private spillText;
+    /**
+     * What durable storage says about the tree's owner, in three states rather than a boolean. The agent
+     * registry is the wrong question: agents are materialized on demand, so right after a restart every
+     * owner is absent from it while its session data is intact — treating that as "gone" would destroy
+     * every tree. `sessionQuery` answers the durable question instead, live-preferred; "cannot tell" stays
+     * its own answer (an opaque host is not evidence the owner is gone) and is only ever REPORTED.
+     */
+    private ownerProbe;
+    /** Ask durable storage whether the session exists. Only session-query's own "not found" means
+     *  `missing`; every other failure is `unobservable`, carrying a one-line reason for the operator —
+     *  NO log line here, because one line per tree per probe is exactly the noise the aggregate report
+     *  replaced. */
+    private probeOwnerByStorage;
+}
+export type { NodeRecord, TreeRecord, OwnerProbe };
+//# sourceMappingURL=host.d.ts.map