@avantf/dsh-mission 0.3.0

package/lib/mission-core/timing.d.ts

@@ -0,0 +1,37 @@
+/**
+ * The DERIVED half of a node's three timestamps: how long it queued, how long it ran, and how long
+ * it existed. The three canonical instants live on {@link NodeRecord} (`createdAt` / `dispatchedAt`
+ * / `endedAt`); these helpers are the only arithmetic over them, so a display, a tool answer and a
+ * test cannot each round or clamp a duration their own way.
+ *
+ * Nothing here reads a clock: every quantity is a function of the record alone. A live "how long has
+ * this been waiting" is deliberately NOT offered — a duration that grows between renders belongs to
+ * the renderer, and inventing one here would make a persisted value look like a clock reading.
+ *
+ * @module @avantf/mission-core/timing
+ */
+/** The three instants, in the minimal shape every reader of them shares. */
+export interface NodeTiming {
+    readonly createdAt: number;
+    readonly dispatchedAt: number | null;
+    readonly endedAt: number | null;
+}
+/**
+ * How long this node QUEUED before its first dispatch: `dispatchedAt − createdAt`. `null` when it
+ * has never been dispatched — the honest answer, since the wait is still going and its end is not
+ * recorded. Never negative: a clock that went backwards is clamped to 0 rather than shown as a
+ * time-travelling queue.
+ */
+export declare function queueMs(node: NodeTiming): number | null;
+/**
+ * How long this node's executor ran: `endedAt − dispatchedAt`. `null` while it is still running or
+ * queued, and also for the one terminal case that has no execution to measure — a node cancelled
+ * before it ever ran (`dispatchedAt === null`). Clamped to 0 for the same reason as {@link queueMs}.
+ */
+export declare function runMs(node: NodeTiming): number | null;
+/**
+ * How long this node has existed so far: `endedAt − createdAt` once terminal, and `null` while it is
+ * still in play. Unlike {@link queueMs} and {@link runMs} this is defined even for a node that never
+ * ran — a cancelled prerequisite still spent wall-clock time in the tree.
+ */
+export declare function totalMs(node: NodeTiming): number | null;

package/lib/mission-core/tree.d.ts

@@ -0,0 +1,447 @@
+import { type ContinuationDelta } from './continuation.js';
+import { type CapacityPolicy, type DispatchPlan } from './dispatch.js';
+import { type WellFormedSource } from './wellformed.js';
+import { type ChildSpec, type DecomposeOutcome, type DispatchView, type MutationResult, type NodeRecord, type TreeRecord } from './types.js';
+export interface TreeState {
+    tree: TreeRecord;
+    nodes: Map<string, NodeRecord>;
+}
+/** Durable sink for tree records; the store owns batching and durability. */
+export interface TreeStore {
+    /** Every persisted tree document, for startup reconciliation. */
+    loadAll(): Promise<TreeState[]>;
+    /** Persist one tree document. Resolves once the write is durable. */
+    put(state: TreeState): Promise<void>;
+    remove(rootId: string): Promise<void>;
+}
+/** One persisted spill artifact: where it is, and how to read it back. */
+export interface SpilledText {
+    /** Opaque model-facing locator produced by the storage backend. */
+    readonly locator: string;
+    /** The backend's retrieval guidance, shown next to the locator. */
+    readonly hint: string;
+}
+/**
+ * What asking durable storage about an owner session resolved to. Three states, not a boolean:
+ * "cannot tell" and "gone" demand different actions — a gone owner's tree is destroyed, an
+ * opaque host must never be allowed to destroy mission (a stray tree is recoverable, destroyed mission
+ * is not), yet the operator still has to hear about it.
+ */
+export type OwnerProbe = {
+    readonly kind: 'exists';
+} | {
+    readonly kind: 'missing';
+} | {
+    readonly kind: 'unobservable';
+    readonly detail: string;
+};
+/** One tree whose owner did not resolve to `exists`, with the probe that explains why. */
+export interface OrphanedTree {
+    readonly tree: TreeRecord;
+    readonly probe: OwnerProbe;
+}
+/** Injected environment facts; the core never imports the harness. */
+export interface TreeDeps {
+    isAgentLive(sessionId: string): boolean;
+    /** Whether a session still EXISTS, asked of durable storage rather than the live registry: an
+     * agent is materialized on demand, so right after a restart a live check is false. Ownership is
+     * decided by this one. `unobservable` is a THIRD answer, not a synonym for either. */
+    probeOwner(sessionId: string): Promise<OwnerProbe>;
+    /** Persist an over-long result, or return `null` when no spill backend is configured — the node
+     * then keeps the full text inline, because a locator nobody can resolve loses the tail. */
+    spill(text: string): Promise<SpilledText | null>;
+    /** Clock, injectable for tests. */
+    now(): number;
+    /** Id generator, injectable for tests. */
+    newId(): string;
+    /**
+     * The family's well-formed repair, injected by the plugin from the LOADED BASE KIT (interface v2,
+     * `wellFormedText` / `wellFormedDeep`). Absent means the base could not provide it — base missing,
+     * or older than v2 — and the tree uses its own {@link LOCAL_WELL_FORMED} copy instead. This is a
+     * degradation, never a refusal: a tree with no injected source still mounts and still repairs.
+     */
+    readonly wellFormed?: WellFormedSource;
+}
+export interface CreateRootInput {
+    readonly ownerSessionId: string;
+    readonly title: string;
+    readonly description: string;
+    /** The owner's initial analysis; stored as the root's background facts. */
+    readonly analysis: readonly string[];
+    /** The scope this mission will modify (a directory or file), or `undefined`/blank for none. The
+     * root has no parent to inherit from, so this is the only declaration site for a tree's unit. */
+    readonly unit?: string | null;
+    /** This mission's declared capacity weight (cores-equivalent); `undefined` reads as the default 1.
+     * The root has no parent to inherit from. */
+    readonly weight?: number;
+    /** This mission's declared round-cap relaxation (see {@link NodeRecord.roundMs}); the root has no
+     * parent, so this is the only declaration site for a tree's relaxed ceiling. */
+    readonly roundMs?: number | null;
+}
+/** Random 8-hex-char id, matching the short ids the tools expose. `crypto` is reached through a
+ * typed globals lookup because the core is built without DOM or Node ambient types. */
+export declare function defaultNewId(): string;
+export declare class MissionTree {
+    private readonly deps;
+    private readonly states;
+    private chain;
+    private store;
+    /** Trees whose in-memory progress moved since the last durable flush. */
+    private readonly progressDirty;
+    constructor(store: TreeStore | undefined, deps: TreeDeps);
+    /**
+     * The repair pair every INBOUND write uses: the base kit the plugin injected, or the local
+     * degradation copy. ONE accessor, so "which implementation" is decided in one place and every
+     * write-path entry below asks the same question.
+     */
+    private get wellFormed();
+    private requireStore;
+    /** Load every persisted tree and reconcile bindings against live agents: a `running` node whose
+     * `claimedBy` no longer resolves is reclaimed as `interrupted`, restart and hot reload alike. */
+    open(): Promise<void>;
+    /**
+     * Three outcomes on open, decided by what the durable record says and what this process can see:
+     *
+     * 1. SURVIVOR — `running` and the worker IS materialized (hot reload): keep the binding, only
+     *    reset `progressAt`, or a long run looks silent from the moment we open.
+     * 2. CONTINUABLE — `running` but the worker is not materialized in THIS process (a restart or a
+     *    crash): demote to `interrupted`, but FIRST park `claimedBy` in `lastWorkerId`. The binding is
+     *    the only place that session id was recorded, so dropping it here is what made every restart
+     *    unable to do anything but start over.
+     * 3. NO HANDLE — not `running`: nothing to do, and `lastWorkerId` (if any) is already spent.
+     *
+     * The survivor branch is deliberately unchanged: a live binding is authoritative, and a stale
+     * handle left beside it is only ever consulted by `adoptContinuation`, which requires the node to
+     * be dispatchable — a `running` node never is.
+     */
+    private reconcileOnOpen;
+    /** Trees whose owner session did not resolve to `exists`, each with the probe that says why.
+     * Asked of durable storage rather than the live registry, so a restart keeps its trees and only a
+     * genuinely deleted session loses them. `missing` and `unobservable` are reported separately: the
+     * caller decides what may be destroyed (see `MissionEngine.reconcileOrphans`). */
+    orphanedTrees(): Promise<readonly OrphanedTree[]>;
+    destroyTree(rootId: string): Promise<void>;
+    treeOf(rootId: string): TreeRecord | undefined;
+    node(id: string): NodeRecord | undefined;
+    /** Claim the right to report one tree's terminal state: true exactly once per transition,
+     * durably, so an engine restart cannot produce a second wake. */
+    claimReport(rootId: string): Promise<boolean>;
+    /** Allow a later terminal transition of the same tree to be reported again. */
+    clearReport(rootId: string): Promise<void>;
+    trees(): readonly TreeRecord[];
+    nodesOf(rootId: string): readonly NodeRecord[];
+    /** Ancestors of a node, root → parent. */
+    chainOf(node: NodeRecord): readonly NodeRecord[];
+    /** The current dispatch view for one node. Built at spawn time, not dispatch time, so the prompt
+     * reflects children results that landed between the dispatch decision and the spawn. */
+    view(nodeId: string): DispatchView | undefined;
+    /** Terminal children of an aggregate, in decomposition order. */
+    terminalChildren(node: NodeRecord): readonly NodeRecord[];
+    /** What changed on this node since the prompt its bound session was handed (see
+     * `@avantf/mission-core/continuation`). Read-only and synchronous, because the wake path consults
+     * it before it adopts anything: a refusal that has already consumed an address is a refusal that
+     * cannot be undone.
+     *
+     * `undefined` when the node does not exist; a node that merely has no baseline still answers, with
+     * `baselineKnown: false` — "unknown" is a fact the caller renders, not an error. */
+    continuationDelta(nodeId: string): ContinuationDelta | undefined;
+    /** The next node to dispatch: `ready`/`interrupted`, oldest first across trees, excluding ones
+     * whose binding still resolves to a live agent. A vanished worker's node is reclaimed by the
+     * engine's sweep before it becomes a candidate again.
+     *
+     * The selection itself — ordering, parked/backoff rules and the unit-lease skip — lives in
+     * `@avantf/mission-core/dispatch`; this is the state access, and the lease side of it is
+     * re-checked atomically at every transition into `running` below, so a race that slips past this
+     * filter is refused rather than run. The optional `capacity` policy arms the capacity gate; without
+     * it this is exactly the pre-capacity contract. */
+    nextDispatchable(exclude?: ReadonlySet<string>, capacity?: CapacityPolicy): NodeRecord | undefined;
+    /** The full admission plan (see `@avantf/mission-core/dispatch`): the node to dispatch AND every
+     *  candidate left waiting with its reason. The engine uses the latter half for `waitingFor` and for
+     *  the aging bookkeeping; tree-level callers that only need the answer use `nextDispatchable`. */
+    planDispatch(exclude?: ReadonlySet<string>, capacity?: CapacityPolicy): DispatchPlan;
+    /**
+     * What the capacity gate currently has in flight: a node counts once it is BOUND (`running` with a
+     * `claimedBy`), not once its worker materializes, so a pass cannot over-subscribe the pool by
+     * dispatching into a lazily-created child.
+     */
+    runningLoad(): {
+        count: number;
+        weight: number;
+    };
+    /**
+     * The lease check shared by all three transitions INTO `running` (`dispatch`, `adoptParked`,
+     * `adoptContinuation`). It has to be re-made here, under the tree lock, and not only in
+     * `nextDispatchable`: the wake paths bind from a snapshot taken outside it, and two passes can
+     * interleave between "this unit looked free" and "mark it running".
+     *
+     * `undefined` means the unit is free (or the node declared none — the no-op case that keeps
+     * undeclared records byte-for-byte as they behaved before leases existed). Reached through
+     * {@link admissionRefusal}, which pairs it with the capacity recheck; the capacity gate has the
+     * same snapshot problem and is re-made in the same breath.
+     */
+    private unitRefusal;
+    /**
+     * The capacity counterpart of {@link unitRefusal}, re-made under the tree lock at every transition
+     * INTO `running`. `planDispatch` decides from a snapshot taken OUTSIDE the lock, so two passes can
+     * each see an empty machine and both bind; the arithmetic therefore has to be re-run here, in the
+     * same place the unit lease is, and through the SAME judgement the plan uses
+     * ({@link capacityWaitingFor}) so the two can never drift.
+     *
+     * The policy supplies the machine's capacity, the slot ceiling and (when the host set it) the
+     * machine-wide block. Its `runningCount`/`runningWeight` are the CALLER'S SNAPSHOT and are
+     * deliberately ignored: trusting them is the very TOCTOU this closes. `undefined` policy means the
+     * caller opted out of the gate entirely — the pre-capacity contract, unchanged.
+     *
+     * The refusal is a DEFERRAL in the strictest sense (`capacity-busy`): the node stays `ready` and
+     * NOTHING is charged — no `attempts`, `failures`, `spawnFailures`, no cooldown, no stall. See
+     * {@link RefusalCode}.
+     */
+    private capacityRefusal;
+    /**
+     * The two RESOURCE admissions every transition into `running` must re-make under the tree lock:
+     * the unit lease first (a scope conflict), then capacity (the machine). Kept in ONE call site per
+     * transition so "what has to be rechecked before binding" is named once and the two checks cannot
+     * drift or be reordered by accident. Budgets are deliberately NOT here: a spent budget is a
+     * FAILURE (`failExhausted`), while both of these are "not yet" and must charge nothing.
+     */
+    private admissionRefusal;
+    /** Nodes waiting for their parked session to be woken: `ready` with a recorded address, i.e. all
+     * children terminal and a session to continue in. The owner's wake gate admits on this. */
+    parkedReadyNodes(rootId?: string): readonly NodeRecord[];
+    /** Claim a parked node FOR its parked session so it can be woken rather than replaced. Unlike
+     * `dispatch` it reserves no new claim id — the identity is the parked session — and consumes
+     * `parkedWorker` in the same locked step, so a concurrent pass cannot both adopt and re-dispatch
+     * it. The claim must land BEFORE the wake is delivered, because a woken session may submit or
+     * decompose immediately and both authorize on `claimedBy`; a failed delivery is undone by a
+     * `reclaim(..., 'wake-failed')`. */
+    adoptParked(nodeId: string, workerId: string, capacity?: CapacityPolicy): Promise<MutationResult<DispatchView>>;
+    /**
+     * Claim a node FOR the lost session recorded in `lastWorkerId`, so its next execution CONTINUES
+     * that session (a cold wake) rather than starting a fresh executor. The continuation counterpart
+     * of {@link adoptParked}, and the same shape: no new claim id is reserved — the identity IS the
+     * recorded session — and the handle is consumed in the same locked step.
+     *
+     * Why the ceilings ARE consulted here, unlike for a parked adoption: a continuation IS a
+     * dispatch. It hands work to a model and advances `attempts`, so a node whose failure budget is
+     * spent must fail here exactly as `dispatch` would fail it, instead of being resurrected.
+     *
+     * The handle is CONSUMED (`lastWorkerId = null`) rather than kept: this dispatch either continues
+     * that session or — through `reclaim(..., 'wake-failed')` — falls back to a fresh one, and neither
+     * outcome may try the same address again. A runtime that refused the resume once will refuse it
+     * again; the fallback is the complete answer (`note_mission` is the cross-session hand-off).
+     */
+    adoptContinuation(nodeId: string, workerId: string, capacity?: CapacityPolicy): Promise<MutationResult<DispatchView>>;
+    /**
+     * Stamp the node with what the prompt just handed to the session showed it: the snapshot a later
+     * cold wake subtracts. The HOST owns the moment (it calls this once the delivery resolved, at each
+     * of its three prompt sites), because only the host knows a prompt was actually read — a dispatch
+     * that never produced, or never delivered, a prompt must leave no baseline claiming otherwise.
+     *
+     * GUARDED on the live binding: between the delivery and this call, a sweep can reclaim the node
+     * (or another pass can re-dispatch it), and a baseline that says "this session saw this" must
+     * belong to the dispatch that is actually bound. A stamp that loses that race is refused
+     * silently: the wake that later reads a stale-or-missing baseline takes the conservative path,
+     * while a wrongly stamped one would under-report the drift to a live session.
+     *
+     * Tolerant rather than a mutation result, like {@link markCorrectionsDelivered}: it is bookkeeping
+     * about a prompt that already exists, and the caller can do nothing useful with a refusal. The
+     * return value exists so the caller (and tests) can tell a stamp from a lost race.
+     */
+    recordDispatchBaseline(nodeId: string, holder: string): Promise<boolean>;
+    /**
+     * Spend a continuation handle WITHOUT using it, so the node's next dispatch starts fresh. Used
+     * when the drift since that session's prompt is material (`isMaterialChange`): the address is not
+     * worth spending, and leaving it would make every later pass re-decide the same thing.
+     *
+     * No status change, no budget, no cooldown — the caller's ordinary `dispatch` follows in the same
+     * engine pass. The baseline is left alone: the fresh dispatch stamps its own, which is the whole
+     * point of replacing the session.
+     */
+    abandonContinuation(nodeId: string, workerId: string): Promise<MutationResult<NodeRecord>>;
+    /** Roll up every OPEN tree into the counts the guidance layer renders; closed trees are archived
+     * and no longer echo into the owner's prompt. */
+    summary(): {
+        trees: number;
+        ready: number;
+        running: number;
+        blocked: number;
+        done: number;
+        failed: number;
+    };
+    createRoot(input: CreateRootInput): Promise<MutationResult<NodeRecord>>;
+    /** Allocate an id not present in the tree (and not already reserved this call). */
+    private allocateId;
+    /** One fresh node record; the only place node defaults are written. */
+    private makeNode;
+    /** Mark one node dispatched and bind it to a reserved child session id, in the same locked step
+     * as the dispatch decision, so two engine passes cannot both dispatch it. `attempts` increments
+     * on every dispatch (the aggregate pass counts as one) and is the generation marker the
+     * `note_mission` gate reads; the failed ceiling rides `failures` instead, so a successful aggregate
+     * round is never charged against it. */
+    dispatch(nodeId: string, claimId: string, capacity?: CapacityPolicy): Promise<MutationResult<DispatchView>>;
+    /** Fail a node whose budget ran out and refuse the dispatch, so the owner is told (the engine
+     * reports terminal roots) and the node never re-enters the candidate pool. */
+    private failExhausted;
+    /** Return a dispatched node to the pool; `cause` decides which budget the reclaim charges.
+     * `vanished`/`stalled`: a worker ran (or was starting) without a result — charges `failures`,
+     * and only `stalled` also increments `stalls`. `spawn-failed`: no worker ever started — charges
+     * `spawnFailures` and pushes the next dispatch back by a cooldown. `wake-failed`: an adoption
+     * that could not be delivered — back to `ready`, charging neither budget, so the caller's fresh
+     * dispatch proceeds. `hung`: the worker was still alive but produced nothing for a whole window
+     * (or exceeded the round cap) — like `wake-failed` it charges NEITHER budget and adds no cooldown,
+     * because an apparatus outage is not a failed mission and must not spend the budget that ends the
+     * node; unlike `wake-failed` it lands in `interrupted`, the ordinary re-queue, and it advances the
+     * `hungCount` STREAK (cleared by real output, never by a re-dispatch) so a node that hangs every
+     * round eventually reaches the owner instead of re-running forever. `attempts` is never
+     * rolled back: it is the `note_mission` generation marker, not a budget.
+     *
+     * Every arm leaves `running`, so this is one of the paths that RELEASES the node's unit lease
+     * (the lease is the set of `running` nodes' units, never a separate table — see `dispatch.ts`).
+     *
+     * `expectedHolder` is a compare-and-swap for a caller that judged the node from a snapshot taken
+     * OUTSIDE this lock — `MissionEngine.reclaimStale` takes one, then awaits `interruptWorker` per
+     * node. If a second sweep reclaimed and re-dispatched the node in that window, the binding has
+     * moved on and this stale verdict must be refused: acting on it would unbind a LIVE worker (whose
+     * `submit_mission` then answers `not-owner`) and charge `failures` a second time for one attempt.
+     * `undefined` means "no expectation" — the callers that act on a value they just read use that. */
+    reclaim(nodeId: string, cause?: 'vanished' | 'stalled' | 'hung' | 'spawn-failed' | 'wake-failed', expectedHolder?: string | null): Promise<MutationResult<NodeRecord>>;
+    /** Clear the spawn-failure counter after a worker started successfully: the budget is for
+     * CONSECUTIVE start failures. Memory-only between flushes is fine — a dispatch flush follows. */
+    noteSpawnSuccess(nodeId: string): void;
+    /** Record that one worker PRODUCED something — model output, a tool call, a tool result — on a
+     * hot path from the worker's durable append feed, so it updates memory only. This is the clock the
+     * stale check reads: output is also evidence of life, so one write moves `activityAt` too. A
+     * timestamp not newer than what we have is ignored, which makes racing a dispatch safe.
+     *
+     * It is ALSO the clearing point of the hang streak: production is the one event that proves the
+     * round was not merely retrying forever, so `hungCount` goes back to 0 here (and only then — a
+     * re-dispatch sets `progressAt` without proving anything and deliberately leaves the streak). */
+    touchProgress(nodeId: string, at: number): void;
+    /** Record that a worker's session emitted SOME event without claiming it produced anything: the
+     *  transport-layer half of liveness. It moves only `activityAt`, so a worker whose events are all
+     *  retries and route snapshots is still heard from (never `stalled`) while `progressAt` stays
+     *  where its last real output left it — exactly the "alive but unproductive" state that
+     *  `judgeWorker` reclaims as `hung`. */
+    touchActivity(nodeId: string, at: number): void;
+    /** Persist progress observed since the last flush, coalesced on purpose: writing the whole tree
+     * document per worker event would cost more than the mission it guards. The usual lock keeps a
+     * stale document from landing after a newer one. */
+    flushProgress(): Promise<void>;
+    /** Claim the right to tell the owner about one node's stalls: true exactly once per node,
+     * durably, the same contract as `claimReport`. */
+    claimStallReport(nodeId: string): Promise<boolean>;
+    /**
+     * Remember the executor session a LAZY lookup resolved for one node, so the panel never pays for
+     * the same lookup twice (W18: the node id is clickable on every node, and a historical record has
+     * no `executorSessionId` — the resolution reads session logs, which is exactly the cost that must
+     * not happen at render time).
+     *
+     * Write-once: a handle already on the record is authoritative and the write is skipped. A handle
+     * that arrived while the lookup was in flight belongs to a NEWER attempt, and overwriting it with
+     * a resolved OLDER one would point the panel at the wrong session — the same "only the last
+     * attempt" rule every other writer of this field follows.
+     *
+     * Tolerant rather than a mutation result, like {@link recordDispatchBaseline} and
+     * {@link markCorrectionsDelivered}: it is bookkeeping, and the caller can do nothing useful with a
+     * refusal. The `boolean` exists so the caller knows whether to announce a change.
+     */
+    rememberExecutor(nodeId: string, sessionId: string): Promise<boolean>;
+    nodeHeldBy(sessionId: string): NodeRecord | undefined;
+    /** Record the holding executor's own analysis, attributed to the `attempts` value it is running
+     * under — that attribution is what `decompose` checks, so notes inherited from an earlier round
+     * do not authorize a split. Text is appended (duplicates dropped) and kept for every later
+     * dispatch. Refused on a terminal node. */
+    recordAnalysis(nodeId: string, callerSessionId: string, analysis: string): Promise<MutationResult<NodeRecord>>;
+    /** Split a node into children: a first decomposition, or a re-decomposition of an aggregate whose
+     * children are all terminal — the pass that read their conclusions and judged the objective
+     * unmet. A node with UNFINISHED children is refused. `submitResult` and `decompose` stay mutually
+     * exclusive through node state, never prompt discipline. The analysis is written earlier by
+     * `recordAnalysis`; this only checks the splitting dispatch wrote its own.
+     *
+     * Leaving `running` here is also what RELEASES this node's unit lease, and the children created
+     * below inherit that unit unless they declare their own — so the same-scope siblings the split
+     * just created are serialized against each other by the same state rule (see `dispatch.ts`). */
+    decompose(nodeId: string, callerSessionId: string, children: readonly ChildSpec[]): Promise<MutationResult<DecomposeOutcome>>;
+    /** Submit a terminal result; rejected while any child is unfinished. An aggregate (every child
+     * terminal) DOES submit — that pass reads the conclusions and states the outcome, which is how a
+     * decomposed node reaches `done` and the tree converges. */
+    submitResult(nodeId: string, callerSessionId: string, result: string): Promise<MutationResult<{
+        node: NodeRecord;
+        parentReady: boolean;
+    }>>;
+    /** Record one correction, on the tree owner's authority only. The text lands in the node's
+     * `corrections`, NOT in `context`: `context` is the decomposer's "why this mission exists", while a
+     * correction is the owner's instruction about mission already handed out — a different author and a
+     * different lifetime. (Rendering them together once made every correction invisible to every
+     * descendant, because the chain line only carries `context[0]`.) Either way it is a durable block
+     * that every later dispatch of this node renders, so it survives a reclaim, a retry and the
+     * aggregate round rather than living in one worker's inbox. */
+    correct(nodeId: string, callerSessionId: string, text: string): Promise<MutationResult<NodeRecord>>;
+    /**
+     * Advance the durable delivery watermark of {@link NodeRecord.correctionsDeliveredUpTo}: the
+     * first `upTo` corrections have been confirmed READ by the session that holds this node (either
+     * a live steer, or a cold-wake prompt that carried them). What it buys is the restart case — a
+     * mark kept only in memory is empty exactly when the wake that needs it happens.
+     *
+     * Deliberately tolerant rather than a mutation result: this is bookkeeping ABOUT a delivery that
+     * already happened, so it is monotone (a raced, older report can never pull the mark back) and
+     * clamped to the array's own length (a report that outran a concurrent append cannot make a later
+     * wake skip a correction nobody read). A no-op returns without writing.
+     */
+    markCorrectionsDelivered(nodeId: string, upTo: number): Promise<void>;
+    /** Cancel everything BELOW one node, strictly downward: the node itself, its ancestors and its
+     * siblings are untouched, and the cancelled nodes become `failed` so the node's aggregate pass
+     * becomes dispatchable again. The tree owner is the caller that matters, because a node with
+     * unfinished children is `blocked` and holds no claim. */
+    cancelSubworks(nodeId: string, callerSessionId: string, onReclaim?: (claimId: string) => void): Promise<MutationResult<readonly NodeRecord[]>>;
+    /** Record that the owner read a terminal result; unlocks `finish_mission`. */
+    markResultRead(nodeId: string): Promise<MutationResult<NodeRecord>>;
+    /** Close a tree out on the owner's authority; refused while results are unread or the root is not
+     * terminal. Either terminal root may be closed — a `failed` root must be reported then retired.
+     * Closing is archival: nodes, results and readers are untouched. */
+    finish(rootId: string, callerSessionId: string): Promise<MutationResult<NodeRecord>>;
+    /** Cancel a whole tree: mark every non-terminal node cancelled-as-failed. */
+    cancelTree(rootId: string, callerSessionId: string, onReclaim?: (claimId: string) => void): Promise<MutationResult<readonly NodeRecord[]>>;
+    /** Delete one whole tree. The unit is the TREE, not the node: its siblings' premises, the
+     * aggregate story and the tree's identity all live in the same record, so pruning one node out of
+     * a live tree would leave a tree that cannot converge. A live tree is refused (ending one early is
+     * `cancel_mission`); `finish_mission` archives instead. */
+    deleteTree(rootId: string): Promise<MutationResult<readonly string[]>>;
+    /** Nodes a live worker still holds, for cancellation to interrupt. */
+    heldByLiveWorkers(rootId?: string): readonly NodeRecord[];
+    private locate;
+    private replace;
+    /** A node's aggregate status: `ready` once every child is terminal. No children at all is also
+     * `ready` — an ordinary mission, not a parent stuck waiting for premises that no longer exist. */
+    private aggregateStatus;
+    private pendingChildren;
+    /** Every node that lists `id` as a child; a reused prerequisite has more than one. */
+    private parentsOf;
+    /** Propagate aggregate readiness up the dependency graph after a node changed, starting from
+     * EVERY parent that lists it (dedup reuse can give it several) rather than the `parentId` chain.
+     * A branch stops at an unchanged status, since an unchanged node cannot change its parents.
+     * Returns whether some parent is now ready, i.e. the engine has an aggregate to dispatch. */
+    private recomputeAncestors;
+    /** Recompute the given nodes' aggregate statuses and spread any change upward — the shared walk
+     * behind `recomputeAncestors` and deletion, for callers that already know what was touched. */
+    private propagateFrom;
+    /** Dedup inside the decomposer's own neighborhood — its siblings' subtrees plus its own — never
+     * the whole tree, and never the node itself or an ancestor, which would close a cycle.
+     * Equivalence is the normalized TITLE and DESCRIPTION: a shared title is common ("补充测试" is one
+     * many unrelated missions wear), and a false reuse hands a later branch a RESULT answering a
+     * different question, so a title match with a different description is created as new mission. */
+    private findEquivalent;
+    /** How many of these specs would actually ADD a node: a child that reuses an existing
+     * prerequisite must not be counted, or the ceiling would fire on the engine's own reuse path.
+     * A pre-pass, not a gate in the loop, because a refusal must leave no child behind.
+     *
+     * It has to answer the SAME question the loop answers, including the one case the loop handles
+     * through its `created` list: a spec repeated inside ONE call reuses the node that call is about to
+     * create. This used to push a `'pending'` placeholder into the equivalent-scope, and
+     * `findEquivalent` resolves ids with `nodes.get(id)` → `undefined`, so the repeat was charged as a
+     * second new node and a legal decomposition was refused with a wrong number (`node-limit`). */
+    private countNewChildren;
+    private flush;
+    /** Serialize one mutation against every other mutation. */
+    private withLock;
+}

package/lib/mission-core/trouble.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Trouble vocabulary: one node status in the language the model and the panel read, and the ONE
+ * predicate that decides whether a node carries trouble worth reporting.
+ *
+ * It lives in its own module because neither member is a RENDERING concern, even though both used to
+ * sit inside `prompt.ts`:
+ *
+ * - `statusLabel` is what every refusal the STATE MACHINE writes names a status with
+ *   (`tree.ts`: "任务 X 处于「执行中」，不能…") — the state machine reaching up into the prompt
+ *   renderer for a word is a layer inversion, not a dependency it needs.
+ * - `isTroubledNode` is the ENGINE's reading of a durable record, shared by four channels (the
+ *   owner-facing `isTroubled` flag, and the stall / repeated-hang / failed-start heads-ups), none of
+ *   which is a prompt.
+ *
+ * `prompt.ts` still owns the text that RENDERS trouble; it imports this module, never the other way
+ * round.
+ *
+ * @module @avantf/mission-core/trouble
+ */
+import { type NodeRecord } from './types.js';
+/** One node status in the language the model and the panel read. */
+export declare function statusLabel(status: string | undefined): string;
+/**
+ * Whether ONE node carries trouble worth telling the owner about: four durable counters, each at the
+ * ENGINE's own floor — silent reclaims (`stalls`), consecutive hangs (`hungCount`), failed attempts
+ * (`failures`), starts that never got a worker (`spawnFailures`).
+ *
+ * ONE definition, because four channels ask this question: the owner-facing flag (`isTroubled`), and
+ * the three heads-ups (`escalateTrouble` for stalls and repeated hangs, and the failed-start one in
+ * the host). They used to disagree — the flag counted `spawnFailures` while the stall gate did not —
+ * so a mission that could not get a worker started read as 「反复出过问题」 in `list_missions` and the
+ * owner was never told why. Splitting the predicate out is what makes "both channels speak one
+ * vocabulary" true by construction rather than by comment.
+ *
+ * `hungCount` is the one member that is a STREAK rather than a history: any real output clears it, so
+ * a node that hung three times and then made progress stops reading as troubled. That is deliberate —
+ * the flag answers "is this happening to it NOW", and the other three counters (`stalls`, `failures`,
+ * `spawnFailures`) are the ones that never clear.
+ */
+export declare function isTroubledNode(node: NodeRecord): boolean;