@avantf/dsh-mission 0.3.0

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

@@ -0,0 +1,331 @@
+/**
+ * The dispatch loop: pure host code that scans the tree, dispatches mission units and reclaims nodes whose worker vanished; it never calls a model.
+ * @module @avantf/mission-core/engine
+ */
+import { MissionTree } from './tree.js';
+import { type LivenessBound } from './liveness.js';
+import type { CapacityPolicy } from './dispatch.js';
+import type { ResourceProbe } from './resources.js';
+import { type NodeRecord, type WaitingFor } from './types.js';
+/** Resume a worker for one node; the engine awaits only the reservation, not the worker. */
+export interface StartWorkerInput {
+    readonly node: NodeRecord;
+    /** The session id reserved for this dispatch, already bound on the node. */
+    readonly claimId: string;
+    /**
+     * How long the CAPACITY gate deferred this node before this dispatch picked it up, in ms. Read
+     * from the engine's own aging clock at the moment the candidate was selected — the same
+     * `capacityWaits` bookkeeping `waitingFor` is built from — so the prompt's "it queued for N" can
+     * never disagree with the panel's queue marker. `0`/absent means the node never waited for
+     * capacity, and the prompt then says nothing about a queue.
+     */
+    readonly waitedMs?: number;
+}
+/** One node the host should try to CONTINUE in the session it was interrupted in (a cold wake). */
+export interface ResumeWorkerInput {
+    readonly node: NodeRecord;
+    /** The session id recorded in `lastWorkerId`: the address to deliver to, and the identity the
+     *  adoption binds if the delivery is accepted. */
+    readonly workerId: string;
+    /**
+     * The capacity policy this candidate was selected under. The host hands it straight to
+     * `adoptContinuation`, so the adoption re-runs the plan's own judgement against the live load
+     * under the tree lock exactly as `dispatch` does — a continuation is a dispatch and must not bind
+     * past a machine that filled up between the plan and the adoption. It is always supplied by
+     * `MissionEngine.pass`; the parallel parked wake builds the same object through
+     * `MissionEngine.admissionPolicy()`, so both wake paths gate identically instead of one of them
+     * opting out — which is what let a wake oversubscribe the machine.
+     */
+    readonly capacity?: CapacityPolicy;
+    /** The capacity wait this candidate served before being selected; see {@link StartWorkerInput}. */
+    readonly waitedMs?: number;
+}
+/**
+ * What a continuation attempt resolved to. Three answers, not a boolean, because "nothing to do" is
+ * not "it failed": when another delivery already owns the session, starting a fresh executor on top
+ * of it is precisely the double run this guard exists to prevent.
+ *
+ * - `resumed` — the node is bound to `workerId` and the prompt was accepted; the caller counts one
+ *   dispatch and starts nobody.
+ * - `failed` — the continuation is not going to happen: either the delivery was refused and the
+ *   host has already undone its own adoption (`reclaim(..., 'wake-failed')`, which charges no
+ *   budget), or the host declined it BEFORE adopting because the node drifted too far from what that
+ *   session last read (a material change; see `continuation`). Either way the caller takes the
+ *   ordinary fresh path with a newly reserved claim, which is the complete answer: a new executor
+ *   reads every correction and every note.
+ * - `skip` — the node must be left exactly as it is: a wake for that session is in flight, the owner
+ *   is not materialized, or the node's state moved under us. Never a reason to spawn.
+ */
+export type ResumeOutcome = 'resumed' | 'failed' | 'skip';
+export interface EngineHooks {
+    /** Reserve a child session id without creating it, which closes the spawn/bind window: the node is bound before anything is materialized. Pair with {@link releaseClaimId}: a claim reserved for a dispatch that is then refused was never bound and must be handed back, or it stays "live" as a ghost forever. */
+    reserveClaimId(): string;
+    /** Hand back a claim reserved by {@link reserveClaimId} whose dispatch did not happen; nothing was materialized for it. */
+    releaseClaimId(claimId: string): void;
+    /** Materialize the worker for a dispatched node and deliver its prompt; the prompt is built HERE from `tree.view(node.id)`, because a sibling result may have landed since the dispatch decision. */
+    startWorker(input: StartWorkerInput): Promise<void>;
+    /**
+     * Try to CONTINUE a node in the session it was interrupted in, instead of starting a fresh one
+     * (a cold wake). The host owns this because only it can reach `ctx.subagents`, and the delivery
+     * must be sent by the child's live direct parent (`authorizeLineage`).
+     *
+     * Called BEFORE a claim is reserved, so a continuation that lands consumes no claim id and a
+     * fallback reserves one exactly as any other dispatch does. See {@link ResumeOutcome} for the
+     * contract, including the rule that `skip` must never be answered with a spawn.
+     *
+     * Priority when several addresses apply — documented because it is a decision, not an accident:
+     * a parked session wins (it is an ALIVE continuation waiting to be woken), then this cold
+     * continuation, then a fresh spawn (`nextDispatchable` already excludes parked nodes).
+     */
+    resumeWorker?(input: ResumeWorkerInput): Promise<ResumeOutcome>;
+    /** Stop a worker believed to be stuck. */
+    interruptWorker(sessionId: string): Promise<void>;
+    /** Deliver a one-line signal to the tree owner; it carries no content — the guidance layer does. */
+    notifyOwner(rootId: string, reason: string): void;
+    /** Heads-up that one node keeps going silent, so the owner can decide whether to intervene — deliberately separate from {@link notifyOwner}, which means "a tree reached a terminal state". */
+    notifyStalled?(info: StallReport): void;
+    /**
+     * Diagnostic sink for a `hung` reclaim: the worker was still alive but had produced nothing for a
+     * whole window (or exceeded the round cap), so the engine interrupted it and re-queued the node
+     * WITHOUT charging any budget. Nothing here is a decision for the owner — an apparatus outage is
+     * not a mission failure — so this exists to be LOGGED, not to wake anybody.
+     */
+    notifyHung?(info: HungReport): void;
+    /**
+     * A dispatch was DEFERRED by the capacity gate (never refused). Rate-limited by the engine, one
+     * line per node per minute, so a queue waiting on a heavy mission does not flood the log while
+     * still remaining diagnosable. The host formats and logs it.
+     */
+    notifyDeferred?(info: DispatchDeferral): void;
+    /**
+     * Report nodes waiting for a parked session to be woken; the engine cannot wake anything itself, because a wake is a delivery through `ctx.subagents` that only the host owns and must be authorized by the child's live direct parent.
+     * Its whole job is to say a convergence pass is due on an idle session, as a BATCH: an owner that was offline can materialize with several parked nodes at once, and one wake per node would be a wake storm.
+     * The host performs the actual wake inside the owner's next turn; a host that cannot wake leaves the address on the node, and this reports again on the next pass.
+     */
+    notifyParkedReady?(nodes: readonly NodeRecord[]): void;
+    reportDispatchFailure?(nodeId: string, error: unknown): void;
+    trace?(message: string): void;
+}
+export interface StallReport {
+    readonly rootId: string;
+    readonly nodeId: string;
+    readonly title: string;
+    /** Dispatches so far, NOT a budget: successful rounds — including aggregate/convergence passes — raise it too. */
+    readonly attempts: number;
+    /** Failed executions so far, including the reclaim being reported; this is the counter the `failed` ceiling bounds. */
+    readonly failures: number;
+    /** Reclaims for silence so far, including the one being reported. */
+    readonly stalls: number;
+    readonly silentMs: number;
+    /**
+     * Which trouble this is. `silence` (the default, and what an older caller sees) is a stall; `hung`
+     * is the repeated-hang heads-up, which shares the channel, the {@link isTroubledNode} floor and the
+     * one-message-per-node marker precisely so the owner reads ONE vocabulary rather than two.
+     */
+    readonly cause?: 'silence' | 'hung';
+    /** Consecutive hangs at report time; present only for `cause: 'hung'`. */
+    readonly hungs?: number;
+}
+/** What a `hung` reclaim looked like, for the engine's diagnostic log. This per-reclaim report is
+ *  NOT an owner-facing message by itself — one hung round is an apparatus event, not a decision —
+ *  but a STREAK of them is (`isTroubledNode` reads `hungCount`), and that escalation travels through
+ *  {@link StallReport} with `cause: 'hung'`. */
+export interface HungReport {
+    readonly rootId: string;
+    readonly nodeId: string;
+    readonly title: string;
+    readonly attempts: number;
+    readonly failures: number;
+    readonly stalls: number;
+    /** Which bound fired: the `staleMs` output window, or the `roundMs` ceiling. */
+    readonly bound: Extract<LivenessBound, 'output' | 'round'>;
+    /** ms since the dispatch that opened this round. */
+    readonly ranMs: number;
+    /** ms since the worker last produced anything. */
+    readonly idleMs: number;
+    /** Consecutive hangs after this reclaim, including it — the streak `isTroubledNode` reads. */
+    readonly hungCount: number;
+}
+/** Why a dispatch is waiting, for the engine's rate-limited diagnostic log. This is NOT an
+ *  `isTroubled` signal: ordinary queuing is not "keeps going wrong". */
+export interface DispatchDeferral {
+    readonly nodeId: string;
+    readonly rootId: string;
+    readonly title: string;
+    readonly waitingFor: WaitingFor;
+    /** Weight of the deferred node (`capacity` reason). */
+    readonly needed: number;
+    readonly capacity: number;
+    readonly running: number;
+    /** How long the capacity gate has been deferring this node; `0` for a non-capacity reason. */
+    readonly waitedMs: number;
+    /** True when this node has aged into a reservation (no new admissions until it fits). */
+    readonly reserved: boolean;
+}
+export interface EngineOptions {
+    /**
+     * Backstop on the NUMBER of running units: with `capacity` it makes up the two-part admission
+     * rule. Capacity is the MASTER gate (how much work the machine can carry); this only stops a flood
+     * of weight-1 missions from opening more sessions than anyone wants. Both must admit a candidate.
+     */
+    readonly maxConcurrent: number;
+    /**
+     * Master gate: how many capacity units (cores-equivalent, the same unit as `NodeRecord.weight`)
+     * may run at once. Required, because the core must not guess at the hardware — the host derives it
+     * (configured → `os.availableParallelism()` → `os.cpus().length` → 4, minus one reserved core) and
+     * injects the number, which is also what makes every scheduling decision deterministic in tests.
+     */
+    readonly capacity: number;
+    /**
+     * How long a node may be repeatedly deferred by the capacity gate before it RESERVES the machine
+     * (no new admissions until it fits). See `capacity.ts` for the value and its rationale.
+     */
+    readonly capacityWaitMs: number;
+    /**
+     * Free-memory floor, in bytes, enforced through {@link ResourceProbe.memoryBudget}: below it the
+     * gate DEFERS dispatch (never refuses). `0` disables the gate; the probe itself is optional, and a
+     * probe that does not implement `memoryBudget` leaves this gate inactive (the v1 degradation path).
+     */
+    readonly minFreeMemoryBytes: number;
+    /** Machine reader, injected by the host. Absent means "no resource signal": the memory floor is
+     *  then the only gate this could arm, and with no probe it is inactive. */
+    readonly probe?: ResourceProbe;
+    /** How long a worker may produce NOTHING before it is considered stuck (see `liveness.ts`). */
+    readonly staleMs: number;
+    /** Wall-clock ceiling on one dispatch: past this the node is reclaimed as `hung` no matter how
+     *  many events refreshed its timestamps. The backstop against a transport that retries forever. */
+    readonly roundMs: number;
+    /** Clock for the stale check and the capacity aging window, injectable so tests can move time
+     *  instead of waiting for it; production leaves it at `Date.now`. */
+    readonly now?: () => number;
+}
+/**
+ * Advisory parallelism for a core that has no Node API of its own (the core builds without Node
+ * types, so the real machine reading is the HOST's job — see `resource.ts` and the plugin's probe).
+ *
+ * The lookup order is deliberate: `navigator.hardwareConcurrency` when a DOM-shaped global is
+ * present, then the family's old fallback of 4. An earlier build tried
+ * `process.availableParallelism?.()` here and that was DEAD CODE: Node has never exposed that member
+ * on `process` — the real API is `os.availableParallelism()`, which the host now calls. Core callers
+ * that need the machine number must inject `EngineOptions.capacity`; this function only exists so
+ * `DEFAULT_ENGINE_OPTIONS` (and any non-Node embedder) has a sane advisory value.
+ */
+export declare function detectConcurrency(): number;
+export declare const DEFAULT_ENGINE_OPTIONS: EngineOptions;
+export declare class MissionEngine {
+    private readonly tree;
+    private readonly hooks;
+    private readonly options;
+    private pumping;
+    private pumpRequested;
+    /** Node id → when the capacity gate first deferred it. In-memory on purpose: a restart loses the
+     *  aging clock, which re-arms it (one extra wait window) — never a correctness loss. */
+    private readonly capacityWaits;
+    /** The live `waitingFor` projection, refreshed at the end of every pass: node id → reason, or
+     *  absent for a node nothing is holding back. */
+    private readonly waiting;
+    /** Last time each node's deferral was logged, for the rate limit. */
+    private readonly deferredLogged;
+    /** Nodes whose RESERVATION transition has already been logged. A reservation overrides the rate
+     *  limit: it changes what the engine admits, so it must not be swallowed by a recent deferral line. */
+    private readonly reservedLogged;
+    constructor(tree: MissionTree, hooks: EngineHooks, options?: EngineOptions);
+    /** Why one node has not been dispatched, or `null` when nothing is holding it back. The projection
+     *  is read by the host for `mission_result` and the panel; it is live state, never persisted. */
+    waitingFor(nodeId: string): WaitingFor | null;
+    /**
+     * The admission policy THIS moment would gate on, from the engine's own single source: the same
+     * `capacityPolicy(memoryFloor())` the dispatch loop builds, carrying the engine's own aging clock
+     * (`capacityWaits`) and the live machine-wide memory block. Built, never stored: the caller gets a
+     * snapshot for one decision, exactly like a pass's policy object.
+     *
+     * It exists for the WAKE paths. `adoptParked` / `adoptContinuation` re-run the gate under the tree
+     * lock, and the rule is that a wake must be judged by the very policy the dispatch loop would use —
+     * deriving a second one in the host (its own capacity number, its own clock) is how the two drift.
+     * The continuation wake already receives the pass's policy through `resumeWorker`; this is how the
+     * parked wake, which has no plan snapshot of its own, gets the same one.
+     */
+    admissionPolicy(): CapacityPolicy;
+    /** The capacity the engine is actually gating on, for diagnostics and tests. */
+    capacity(): {
+        capacity: number;
+        maxConcurrent: number;
+        runningCount: number;
+        runningWeight: number;
+    };
+    private now;
+    /** Run one dispatch pass; `dispatch()` decides and marks in the same await, so a second pass cannot see the same node as available and no batch bookkeeping is needed. */
+    pump(): Promise<number>;
+    sweep(): Promise<{
+        reclaimed: number;
+        dispatched: number;
+    }>;
+    /**
+     * Reclaim nodes whose worker is gone or stuck; liveness is the primary signal, and the windows
+     * only cover "alive but not useful".
+     *
+     * The judgement is `judgeWorker` (see `liveness.ts`): silence measured from the last event at all
+     * is `stalled` and charges the failure budget exactly as before; a worker that keeps being heard
+     * from while producing NOTHING for `staleMs`, or that exceeds the round cap, is `hung` and charges
+     * nothing. Both interrupt the live binding before reclaiming, and both go through the same
+     * compare-and-swap `MissionTree.reclaim`, so a verdict judged against a snapshot taken outside
+     * the tree lock cannot strip a fresh binding or charge one attempt twice.
+     */
+    reclaimStale(): Promise<number>;
+    /**
+     * The ONE owner-facing "this node keeps going wrong" path, shared by every cause. Three rules make
+     * it one vocabulary rather than two: the gate is {@link isTroubledNode} (the same predicate the
+     * `isTroubled` flag reads), the report rides the `notifyStalled` channel (a heads-up, never a
+     * question), and the durable `claimStallReport` marker keeps it to one message per node whichever
+     * way the node is failing. The engine already recovered on its own in every case, so waiting for a
+     * repeat is what keeps a permanently flaky node from turning a sweep into a wake storm.
+     */
+    private escalateTrouble;
+    /** Tell the host a node was reclaimed as `hung`, so every hung round is diagnosable — a provider
+     *  that hangs (or only retries) every dispatch must never be invisible, which is exactly how W8
+     *  stayed unnoticed for 7.5 hours. This per-reclaim line is NOT the owner escalation: one hung
+     *  round is an apparatus event the engine recovered from, and only a STREAK crosses
+     *  {@link escalateTrouble}'s `isTroubledNode` floor. */
+    private reportHung;
+    /** Destroy trees whose owner session no longer exists: the owner is the authority over the tree, and a hot reload or host restart leaves it resolvable, so nothing is destroyed there. A tree whose owner merely cannot be OBSERVED is left alone and reported instead — the host being unable to answer is not evidence the owner is gone, and a destroyed tree cannot be recovered. */
+    reconcileOrphans(): Promise<readonly string[]>;
+    /**
+     * The machine-wide gates that do not depend on WHICH node is being considered: the free-memory
+     * floor. Returns the `waitingFor` every candidate carries while it is set, or `undefined` when the
+     * gate is open.
+     *
+     * A probe that does not implement `memoryBudget` leaves the gate inactive (v1: no platform
+     * adapter). A probe that implements it and answers `null` means "cannot confirm the floor", and
+     * that is a DEFER, not "plenty" — see `resource.ts`: no signal never relaxes scheduling.
+     */
+    private memoryFloor;
+    /** The capacity arithmetic for this moment, built from the tree's live load. */
+    private capacityPolicy;
+    private pass;
+    /**
+     * Publish the live `waitingFor` projection for the nodes a pass left behind, and drop entries for
+     * nodes that are no longer waiting (dispatched, terminal, or blocked by something outside
+     * admission). The map is the ONE place the host reads waiting state from, so it is rebuilt to
+     * exactly the deferred set rather than accumulated across passes.
+     */
+    private publishWaiting;
+    /**
+     * The rate-limited deferral log: one line per node per minute while the capacity gate holds it
+     * back. Deliberately not an owner wake and not an `isTroubled` fact — normal queuing is not a
+     * problem the owner can act on.
+     *
+     * Two reasons count as "waiting for capacity" here: `capacity` itself (this node does not fit) and
+     * `aging` (ANOTHER node has reserved the machine, so this one is held back while capacity may have
+     * room). The second is the one the aging mechanism exists to make visible — leaving it out is how
+     * the reservation changed what the engine admits with no line anywhere saying so.
+     */
+    private reportDeferrals;
+    /** Report the parked-ready batch to the host after the dispatch loop; the wake itself is the host's job — see {@link EngineHooks.notifyParkedReady}. */
+    private reportParkedReady;
+    /**
+     * Wake the owner about every terminal tree, exactly once each; dedup lives on the durable tree record (`claimReport`), because an in-memory set is empty after a restart and would re-report every tree that had ever reached a terminal state.
+     */
+    private reportTerminalRoots;
+    /** Forget the report marker for a tree, so a re-rooted tree can report again. */
+    forgetReport(rootId: string): void;
+}

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

@@ -0,0 +1,25 @@
+/**
+ * @avantf/mission-core — the mission-tree model, dispatch loop and prompt construction; harness environment facts arrive as injected dependencies.
+ * @module @avantf/mission-core
+ */
+export * from './types.js';
+export { MissionTree, defaultNewId } from './tree.js';
+export type { TreeState, TreeStore, TreeDeps, SpilledText, CreateRootInput, OwnerProbe, OrphanedTree, } from './tree.js';
+export { MissionEngine, DEFAULT_ENGINE_OPTIONS, detectConcurrency } from './engine.js';
+export type { DispatchDeferral, EngineHooks, EngineOptions, HungReport, ResumeOutcome, ResumeWorkerInput, StartWorkerInput, StallReport, } from './engine.js';
+export { CAPACITY_CEILING, CAPACITY_FALLBACK_PARALLELISM, DEFAULT_CAPACITY_WAIT_MS, DEFAULT_MIN_FREE_MEMORY_BYTES, DEFAULT_WEIGHT, MAX_WEIGHT, MIN_CAPACITY_WAIT_MS, MIN_WEIGHT, RESERVED_CORES, clampCapacity, deriveCapacity, normalizeWeight, } from './capacity.js';
+export type { CapacityInput, CapacityReading, CapacitySource } from './capacity.js';
+export type { ResourceProbe } from './resources.js';
+export { effectiveRoundMs, heardAt, judgeWorker, MAX_DECLARED_ROUND_MS, normalizeRoundMs, producedAt, resolveChildRoundMs, storedTime } from './liveness.js';
+export type { LivenessBound, LivenessVerdict, LivenessWindows, ReclaimCause } from './liveness.js';
+export { byCreatedAtThenId, capacityWaitingFor, heldUnits, normalizeUnit, planDispatch, resolveChildUnit, resolveChildWeight, selectNextDispatchable, spawnBackoffMs, unitHolder, } from './dispatch.js';
+export type { CapacityLoad, CapacityPolicy, DeferredCandidate, DispatchPlan, DispatchPolicy, DispatchScope, } from './dispatch.js';
+export { computeContinuationDelta, isMaterialChange, nodeFingerprint } from './continuation.js';
+export type { ContinuationDelta } from './continuation.js';
+export { queueMs, runMs, totalMs } from './timing.js';
+export type { NodeTiming } from './timing.js';
+export { buildWorkerPrompt, buildProgressLine, isTroubled, PROMPT_LIMITS, spillPointer, waitedLabel } from './prompt.js';
+export type { WorkerPromptOptions } from './prompt.js';
+export { isTroubledNode, statusLabel } from './trouble.js';
+export { LOCAL_WELL_FORMED, wellFormedDeep, wellFormedText } from './wellformed.js';
+export type { WellFormedSource } from './wellformed.js';

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

@@ -0,0 +1,99 @@
+/**
+ * The liveness verdict for ONE running node: is its worker still making progress, or has the round
+ * become something the engine must take back?
+ *
+ * Two clocks, because "no events" and "no output" are different failures — and conflating them is
+ * what let a transport-layer hang sit `running` for 7.5 hours (2026-10-02):
+ *
+ * - `progressAt` — the last PRODUCTION: the model's committed output (`assistant/message`), a tool
+ *   it asked for (`tool/call`), or a tool that finished (`tool/result`). The plugin classifies the
+ *   host's durable event feed (see its `workerEvents` module) and only those refresh it.
+ * - `activityAt` — the last durable event of ANY kind, including transport-layer noise: provider
+ *   retry attempts (`assistant/attempt`) and the log-only per-request route snapshots
+ *   (`request/header`, `request/context`). Noise proves the session object is alive; it does not
+ *   prove the mission moved.
+ *
+ * Three bounds come out of that, in this order:
+ *
+ * - **silence** (`now - max(activityAt, progressAt, claimedAt) > staleMs`) → `stalled`. Nothing was
+ *   heard at all. This is the original verdict with its original budget charge, and it is checked
+ *   first so a node the old build would have called silent is still called silent.
+ * - **round** (`now - claimedAt > roundMs`) → `hung`. A wall-clock ceiling on the dispatch itself,
+ *   which no timestamp can veto. It fires before the output bound on purpose: when a productive
+ *   worker reaches it, "the round hit its ceiling" is the accurate description, not "no output".
+ * - **output** (activity fresh but `now - (progressAt || claimedAt) > staleMs`) → `hung`. The W8
+ *   shape exactly: the worker keeps being heard from while producing nothing.
+ *
+ * Both `hung` bounds are reclaimed WITHOUT charging the failure budget: a stuck provider is not a
+ * failed mission, and letting retries eat the budget would turn a recoverable node `failed`. What
+ * keeps that leniency from becoming an unbounded loop is `hungCount` — the engine's own consecutive
+ * hang counter, cleared by real output — which at `CAPACITY.maxHungsBeforeReport` makes the node
+ * visible to the owner through the same trouble channel `stalled` uses (see `MissionTree.reclaim`
+ * and `MissionEngine.reclaimStale`).
+ *
+ * A record written before `activityAt` existed has no value there, and its `progressAt` was
+ * refreshed by ANY event. {@link heardAt}/{@link producedAt} then fall back to `progressAt` for
+ * both clocks, so such a node is judged exactly as the previous build judged it — plus the round
+ * cap, which is the one bound that still catches the old records.
+ *
+ * @module @avantf/mission-core/liveness
+ */
+import type { NodeRecord } from './types.js';
+/** Why a running node's worker must be taken back. `stalled` charges the failure budget; `hung` does not. */
+export type ReclaimCause = 'stalled' | 'hung';
+/** Which bound produced a `hung` (or `stalled`) verdict. */
+export type LivenessBound = 'silence' | 'output' | 'round';
+export interface LivenessVerdict {
+    readonly cause: ReclaimCause;
+    readonly bound: LivenessBound;
+    /** ms since the worker was last heard from at all. */
+    readonly silentMs: number;
+    /** ms since the worker last PRODUCED something. */
+    readonly idleMs: number;
+    /** ms since the dispatch that opened this round. */
+    readonly ranMs: number;
+}
+export interface LivenessWindows {
+    readonly staleMs: number;
+    readonly roundMs: number;
+}
+/**
+ * Hard ceiling on a DECLARED round cap: 24 hours. The declaration exists to relax the cap for
+ * genuinely heavy work, not to opt out of it — a single round longer than a day is indistinguishable
+ * from a hang, and the mission can always be re-entered by the ordinary retry. An operator's own
+ * configured `roundMs` is NOT clamped by this; only a node's declaration is.
+ */
+export declare const MAX_DECLARED_ROUND_MS: number;
+/**
+ * Read a node's declared round-cap relaxation into shape: a finite number > 0, or `null` for
+ * "declared nothing". Missing, dirty and non-positive values all read as `null`, the same direction
+ * as a record written before the field existed — a declaration that cannot be believed must not
+ * change when a round is taken back. Anything past {@link MAX_DECLARED_ROUND_MS} falls to it.
+ */
+export declare function normalizeRoundMs(raw: unknown): number | null;
+/**
+ * A decomposed child's round-cap relaxation. `undefined` — the spec said nothing — does NOT inherit
+ * the parent's declaration: a parent that needs hours says nothing about one child, and the same
+ * reasoning already governs `weight` (`resolveChildWeight`).
+ */
+export declare function resolveChildRoundMs(declared: number | null | undefined): number | null;
+/**
+ * The round cap actually applied to one node: the engine's configured ceiling, RELAXED by the node's
+ * own declaration and never shortened by it. Relaxation-only is the whole rule — the cap is the
+ * backstop against a transport that retries forever, so a mission may ask for more room but may not
+ * opt out of the backstop, and a smaller declaration (a countdown a model could otherwise set for
+ * itself) is a no-op.
+ */
+export declare function effectiveRoundMs(node: NodeRecord, configured: number): number;
+/** A timestamp as stored. A record written before the field existed has `undefined` at runtime even
+ *  though the type says `number`, and `Math.max(undefined, …)` is `NaN` — which would compare false
+ *  against every window and keep a dead node running forever. */
+export declare function storedTime(value: number | undefined): number;
+/** When the worker was last heard from at all; the dispatch that opened the round is the floor, so
+ *  a node that never reported anything is "silent since it started" rather than "silent since 0". */
+export declare function heardAt(node: NodeRecord): number;
+/** When the worker last PRODUCED something. Falls back to the dispatch: a node that has produced
+ *  nothing yet has been unproductive since it was bound, which is the reading `hung` needs. */
+export declare function producedAt(node: NodeRecord): number;
+/** The verdict for one running node, or `undefined` when it is still doing fine. */
+export declare function judgeWorker(node: NodeRecord, at: number, windows: LivenessWindows): LivenessVerdict | undefined;

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

@@ -0,0 +1,112 @@
+/**
+ * Worker prompt construction: one template, branching on the node's state for the trailing section; the tail is derived from the node at dispatch time, exists only in this dispatch's input and never enters a conversation.
+ * @module @avantf/mission-core/prompt
+ */
+import { type DispatchView, type NodeRecord } from './types.js';
+import type { ContinuationDelta } from './continuation.js';
+import { type WellFormedSource } from './wellformed.js';
+/**
+ * Whether a mission should read as TROUBLED to its owner: some unfinished node trips {@link isTroubledNode}.
+ * The wording has to say this is HISTORY, because a flag that never clears would invite the owner to steer or cancel a mission that is running fine, and both actions are destructive.
+ * Deliberately NOT here: which mission it was, how often, and how much budget is left — those belong to the engine's retry policy, and the owner's two actions (`adjust_mission`, `cancel_mission`) take the whole mission, not a node inside it.
+ */
+export declare function isTroubled(nodes: readonly NodeRecord[]): boolean;
+/**
+ * The prompt's size guardrails. The tail is rewritten on every dispatch and everything here is paid
+ * for in model tokens, so each of these bounds one axis that could grow without limit:
+ *
+ *  - {@link chainLine} rendered EVERY correction of EVERY ancestor (a correction is written on the
+ *    root, so one long-lived root steered repeatedly made every descendant carry all of them);
+ *  - {@link analysisSection} rendered every note an executor had ever appended;
+ *  - {@link childrenBlock} rendered every terminal child's conclusion. Per-child size is already
+ *    bounded by the engine (`CAPACITY.maxInlineResultChars`, longer results are spilled with a
+ *    pointer), but the COUNT is not: `children` accumulates across re-decompositions, and 50
+ *    children × the 2 KB inline cap was a measured ~100 KB (~50k tokens) aggregate prompt.
+ *
+ * What the model still sees after a bound bites is stated IN the prompt at each site, so a judge can
+ * tell "this child said nothing" from "this child's text was summarized here".
+ */
+export declare const PROMPT_LIMITS: {
+    /** Corrections rendered per mission-chain ancestor (the NEWEST ones; the rest are counted). */
+    readonly chainCorrections: 2;
+    readonly chainCorrectionChars: 200;
+    /** Corrections rendered verbatim on the node being executed (the newest ones; the rest counted). */
+    readonly currentCorrections: 10;
+    /** `note_mission` notes rendered (the newest ones; the rest counted). */
+    readonly analysisNotes: 8;
+    readonly analysisNoteChars: 400;
+    /** Terminal children whose conclusion is rendered in full — the newest ones. Older children still
+     *  list id, title, status and the head of their conclusion. The count is what accumulates across
+     *  re-decompositions, so this is the bound that stops a 50-child aggregate from growing without end. */
+    readonly childrenBody: 10;
+    /** Safety clip on one child's conclusion; equal to the engine's inline cap, so a well-formed record
+     *  is never actually cut (an older/foreign record could exceed it). */
+    readonly childBodyChars: 2000;
+    /** How much of an older child's conclusion survives in the compact form. */
+    readonly childExcerptChars: 120;
+};
+/**
+ * Where a spilled full result lives, with the backend's own retrieval guidance; one definition for both renderers — the worker prompt and `mission_result` — because a locator without its hint is a pointer nobody can follow.
+ */
+export declare function spillPointer(node: NodeRecord): string;
+/** How one dispatch renders the node it is about; the default is the fresh-executor reading. */
+export interface WorkerPromptOptions {
+    /** This dispatch CONTINUES the session that was interrupted: the hand-off notice says which
+     * execution this is and points at the resumed session's own history. */
+    readonly resumed?: boolean;
+    /** Corrections to render on the CURRENT node. Defaults to every recorded correction, because a
+     * fresh executor has read none. A continuation wake passes
+     * `node.corrections.slice(node.correctionsDeliveredUpTo)`: a correction already delivered to that
+     * same session must not be argued to it twice. The chain's ancestor lines keep their own text —
+     * they are a different node's corrections, and none of them is repeated by this override. */
+    readonly corrections?: readonly string[];
+    /** What changed on this node since the session's own last prompt, for the delta section. Passed
+     * by a CONTINUATION only: a fresh executor has never executed this mission, so "since you last
+     * executed" would be a lie, and it reads every correction, note and child conclusion anyway. */
+    readonly delta?: ContinuationDelta;
+    /** How long the CAPACITY gate deferred this node before the dispatch that built this prompt
+     * picked it up, in ms. Passed by the engine (through `StartWorkerInput`/`ResumeWorkerInput`) from
+     * its own aging clock; `0`/absent means "never waited", and then no queue line is rendered at all.
+     * It exists because an executor with no such fact reports "I did not wait" — a real answer from a
+     * run that had in fact queued for two minutes behind a full machine. */
+    readonly capacityWaitedMs?: number;
+}
+/**
+ * How a capacity wait reads in the prompt. A stopwatch would be false precision: the number is one
+ * reading of the engine's aging clock, so it is rounded and says 约. Seconds below a minute (a node
+ * can be skipped for a few seconds and that is still "it queued"), minutes above it.
+ */
+export declare function waitedLabel(ms: number): string;
+/**
+ * Build the complete prompt for one dispatch; the mission chain carries only titles and one-line context, so its size is bounded by the depth limit, and the full `description`/`context` is included for the current node only.
+ * The tail branches on the CHILDREN in the view, not on the node's status: the prompt is built after `dispatch()` has already marked the node `running`, so a status test can never see the aggregate case, and a `failed` node is never dispatched at all.
+ *
+ * ── the OUTBOUND well-formed boundary ──
+ * Everything this function writes lands in the executor's context, and the tree it reads may hold a
+ * lone surrogate that an OLDER build persisted (before the inbound funnel existed) or that a foreign
+ * writer put there. So the whole view (node, chain, children) and the whole options record are
+ * recursively repaired BEFORE a single line is assembled: `wellFormedDeep` leaves numbers, booleans
+ * and `null` untouched, so nothing but lone surrogates can change. `wellFormed` is the plugin's
+ * loaded base kit when it has one and {@link LOCAL_WELL_FORMED} otherwise.
+ *
+ * @param view - the node/chain/children this dispatch renders.
+ * @param options - how this dispatch differs from a fresh executor's.
+ * @param wellFormed - the repair pair; the plugin injects the loaded base's.
+ */
+export declare function buildWorkerPrompt(view: DispatchView, options?: WorkerPromptOptions, wellFormed?: WellFormedSource): string;
+/**
+ * The compact per-tree progress line the guidance layer carries; every clause is anchored so it stays true when read late — the counts are a statement about a moment, not about "now".
+ * Granularity is deliberate: the owner is told WHETHER mission is still running and WHETHER any of it has a history of trouble, never how the mission is distributed across states, because no owner action depends on that distribution, so a per-state breakdown would only invite it to reason about a layer it cannot touch.
+ * Trouble is the one fact that changes what it should do, and it is counted in WORKS, not in nodes, so the size of anything stays inside the engine.
+ *
+ * The SAME outbound rule as {@link buildWorkerPrompt}: this line is assembled into the owner's
+ * context, so titles are repaired first (see the note there). The plugin injects the loaded base's
+ * repair pair; the core's local copy is the degradation path.
+ */
+export declare function buildProgressLine(input: {
+    readonly roots: readonly NodeRecord[];
+    /** How many missions have not finished yet. */
+    readonly ongoing: number;
+    /** Whether any unfinished mission carries a history of stalls or failures at the engine's floors. */
+    readonly troubled: boolean;
+}, wellFormed?: WellFormedSource): string;

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

@@ -0,0 +1,57 @@
+/**
+ * `ResourceProbe` — the port through which the engine reads the machine, and the one place the
+ * family's `null`-is-not-zero rule is stated. Node-free: the core declares the interface and never
+ * implements it; the plugin/host supplies a probe built on `node:os` (see `host.ts`), which is also
+ * the ONLY seam allowed to contain platform branches.
+ *
+ * ## `null` is a first-class answer: "no signal on this platform"
+ *
+ * **"No signal" ≠ "idle".** A `null` must never be read as evidence that resources are free, so it
+ * may only ever make scheduling MORE conservative — never more permissive. Concretely:
+ *
+ * - `memoryBudget()` returning `null` while the free-memory floor is armed means "cannot confirm the
+ *   floor", and the gate DEFERS dispatch. It is not "plenty of memory".
+ * - `pressure()` returning `null` means "cannot tell"; no caller may treat it as `0` to widen
+ *   concurrency or lower a weight. v1 has no pressure-driven widening at all, so the honest reading
+ *   is "no adjustment".
+ * - `workerUsage()` returning `null` means "this process's CPU is unknown"; it is not `0`, and v2's
+ *   correction loop must treat it as "do not correct from this sample".
+ *
+ * The distinction between an OPTIONAL member that is absent and one that returns `null` is
+ * deliberate: absent = this port has no implementation for that signal at all (the v1 degradation
+ * path — no platform adapter), while `null` = implemented but the platform will not say. The former
+ * leaves the corresponding gate inactive; the latter keeps the gate conservative.
+ *
+ * ## v1 scope
+ *
+ * Only the interface, the wiring, and a host implementation over the UNIFIED Node API
+ * (`os.availableParallelism()`, `os.totalmem()`, `process.constrainedMemory()`, `os.freemem()`).
+ * Platform adapters (POSIX/Windows `pressure`, per-worker process attribution) and measured
+ * correction of weights are v2; every unimplemented branch answers `null`.
+ *
+ * @module @avantf/mission-core/resources
+ */
+export interface ResourceProbe {
+    /**
+     * How much independent work this machine will ACTUALLY run in parallel — i.e.
+     * `os.availableParallelism()`, which honours cgroup CPU quotas and CPU affinity, rather than the
+     * raw core count. Required, because every host can answer it: Node falls back to `os.cpus()`.
+     */
+    parallelism(): number;
+    /**
+     * A LOWER BOUND, in bytes, on the memory this process may still use, or `null` when the platform
+     * will not say. "Lower bound" is the whole contract: the value may understate what is available,
+     * which is the safe direction for a floor gate, and it includes the cgroup cap when one exists
+     * (a cgroup limit below `os.totalmem()` is the real budget). Never an exact figure, never "free
+     * memory" in the leaving-room sense.
+     */
+    memoryBudget?(): number | null;
+    /**
+     * A coarse 0..1 pressure reading (sustained CPU contention / memory pressure), or `null` when the
+     * platform cannot produce one. v1 never widens from it; the member exists so v2's adapters and the
+     * scheduler can be written against a stable signature.
+     */
+    pressure(): number | null;
+    /** CPU usage of one worker process, or `null` when this platform cannot attribute it (v2). */
+    workerUsage?(pid: number): number | null;
+}