@sema-agent/core 7.24.1 → 7.24.3

package/dist/core/checkpoint-store.d.ts

@@ -1288,110 +1288,135 @@ export type SerializedCheckpointState = {
     [K in keyof Required<CheckpointState>]: CheckpointState[K];
 };
 /**
- * The BASELINE {@link Checkpoint} schema version (design/49 §3, code-ready council round-2): the
- * shape a plain human-approval suspend carried before any feature raised the format. It is NOT the highest
- * a resume accepts — that is {@link MAX_SUPPORTED_CHECKPOINT_VERSION}, which the per-feature stamps
- * (RESOURCE / BINDING / TOKEN / ORG_ADMISSION) have each raised on their own, deliberately without moving
- * this constant. Resume stays forward-compatible by `<=` against MAX, never `===`. Every live mint site
- * stamps one of the feature versions, so nothing in-tree produces this value today; it is kept as the
- * floor of the version ladder and as the reading for a row written before any feature raised the format.
- */
-export declare const CURRENT_CHECKPOINT_VERSION = 1;
-/** design/74 R3-B: the schema version a `resource_limit` suspend stamps (v2 — it adds `resourceLedger` and a
- *  `resource_limit` `pendingAction`/`gate` an old worker can't handle). An old worker (`MAX_SUPPORTED`=1)
- *  rejects it pre-CAS (stays `pending`, retryable on a new worker). */
-export declare const RESOURCE_CHECKPOINT_VERSION = 2;
-/**
- * design/80 D-1 (version-skew downgrade fix): the schema version a **binding-bearing** human/irreversible_ask
- * `tool_approval` suspend stamps. These checkpoints carry the decision-action binding (`boundCallId` +
- * `boundInputHash`) whose enforcement lives ENTIRELY in the resuming worker's resume path. A pre-D-1 worker
- * (released 1.100.0: `MAX_SUPPORTED`=2, and its resume code has ZERO binding logic) would otherwise resume a
- * D-1-minted v1 checkpoint and execute the pending tool with NO decision-action verification — the exact
- * "approve vendor-A $5 → execute vendor-B $5000" circumvent the binding exists to prevent (council BLOCKER #1).
- * Stamping these at **v3 (> the old worker's MAX of 2)** forces a pre-D-1 worker to reject them PRE-CAS
- * (`unsupported_version`, stays `pending`, retried on a binding-enforcing worker) instead of silently voiding
- * the binding. A resource_limit suspend keeps stamping v2; a pre-binding (legacy 1.100.0) checkpoint is v1.
- */
-export declare const BINDING_CHECKPOINT_VERSION = 3;
-/**
- * design/164 (the BINDING_CHECKPOINT_VERSION precedent replayed a third time): the schema version a suspend
- * stamps when its ledger CARRIES a cross-slice TOKEN allocation (`resourceLedger.totalTokens` set). The
- * enforcement — window clamp against the remaining allocation, exhausted-resume fail-fast — lives ENTIRELY
- * in the resuming worker, so a pre-164 worker (MAX_SUPPORTED=4) would accept the row, ignore
- * `spentTokens` as a bound, and grant a fresh full window. Stamping v5 forces it to reject PRE-CAS
- * (`unsupported_version`, stays `pending`, retried on an enforcing worker). A ledger with NO token total
- * keeps the historic stamps (v2 resource / v3 binding) — deployments not using it see zero version movement.
+ * The checkpoint FEATURE TABLE — one row per feature that ever raised the row format. A row carries the
+ * feature's schema version, the persisted mark by which a reader tells the feature was written on a row
+ * (`recordedOn`, the READ face), and what a mint owes when the feature is present (`writes`, the WRITE
+ * face — the two faces are deliberately separate columns). Minting is derived from the rows
+ * ({@link checkpointVersionFor}: the highest version among the features present), the per-feature
+ * constants below ARE the rows' versions, and the resume screen reads the rows — so adding a feature is
+ * one row here plus an explicit answer at each mint site (the presence record's keys are mandatory).
  *
- * v4 (the retired wall-clock total) is deliberately NOT reused: this worker still READS v4 rows, and one
- * whose ledger carries the retired axis is refused with its own typed code (see
- * {@link CheckpointError} `checkpoint.walltime_axis_retired`) instead of silently resuming under a bound
- * nobody enforces any more.
- */
-export declare const TOKEN_CHECKPOINT_VERSION = 5;
-/**
- * Org-memory admission state (falsification-style round 2, 2026-08-05 — the BINDING_CHECKPOINT_VERSION
- * precedent replayed a fourth time): the schema version a suspend stamps when its state carries
- * org-admission freeze fields (`inheritedGate.admittedOrgScopes` / `ownAdmittedOrgScopes` /
- * `ownAdmittedOrgWriteScope` — the adjudicated-empty record included). The enforcement — the
- * session/delegation freeze on resume, the tenant-admission door itself — lives ENTIRELY in the
- * resuming worker, so a pre-admission worker (MAX_SUPPORTED=5) would accept the row, ignore the
- * freeze fields, and remount the raw org scopes with no admission at all. Stamping v6 forces it to
- * reject PRE-CAS (`unsupported_version`, stays `pending`, retried on an enforcing worker). A
- * checkpoint with NO org-admission state keeps the historic stamps — deployments not using org
- * memory see zero version movement.
- */
-export declare const ORG_ADMISSION_CHECKPOINT_VERSION = 6;
-/**
- * F-012 (2026-08-09 — the ORG_ADMISSION_CHECKPOINT_VERSION precedent replayed a fifth time
- * falsification-style finding): the schema version a suspend stamps when its state carries the F-012 durable
- * enforcement fields — `inheritedGate.constraintChain`/`constraintDigest` (the frozen ancestor
- * projection chain the resume-edit re-adjudication executes) or `delegationProvenance` (the monotonic
- * provenance aggregate a resume re-seeds). Both enforcements live ENTIRELY in the resuming worker: a
- * pre-F-012 worker (MAX_SUPPORTED=6) would accept the row, ignore constraintChain (so an approver-edited
- * resume executes WITHOUT the frozen ancestor deny), and restart the aggregate clean (false-clean after
- * pre-suspend external activity). Stamping v7 forces such a worker to reject PRE-CAS
- * (`unsupported_version`, stays `pending`, retried on an enforcing worker). A checkpoint with NO F-012
- * state keeps the historic stamps — deployments not delegating see zero version movement.
- */
-export declare const F012_CHECKPOINT_VERSION = 7;
-/**
- * #130/#120 (2026-08-10 — the F012_CHECKPOINT_VERSION precedent replayed a sixth time): the schema
- * version a suspend stamps when its gate carries {@link RealApprovalGateBit}. The enforcement lives
- * ENTIRELY in the resuming worker (the no-org-wiring refusal, the org_unavailable resume-belt
- * distinction): a pre-131 worker (MAX_SUPPORTED=7) would accept the row, ignore `realApproval`, and
- * either redeem a governed row with no org wiring at all (#120's exact hole, replayed through version
- * skew) or burn the approval on the unavailable belt the bit exists to soften. Stamping v8 forces it
- * to reject PRE-CAS (`unsupported_version`, stays `pending`, retried on an enforcing worker). A gate
- * with NO `realApproval` keeps the historic stamps. NOTE (erratum 2026-08-10, downstream-measured):
- * "zero version movement for ungoverned deployments" is TOO WIDE — the two always-mounted integrity
- * policies (transcript-integrity, unverifiable-delete) mint `requiresRealApproval` asks, so a park on
- * one of THOSE stamps v8 with `origin:"policy"` on ANY durable deployment, org-governed or not. What
- * stays true: rows whose gate carries no realApproval bit keep their historic stamps everywhere.
- */
-export declare const REAL_APPROVAL_CHECKPOINT_VERSION = 8;
-/**
- * design/199 (2026-08-13 — the precedent replayed a seventh time): the schema version a suspend
- * stamps when its state carries the READ-FACE section ({@link CheckpointState.readFace} — the
- * resolved open face and/or deny-set additions). The enforcement lives ENTIRELY in the resuming
- * worker (the stricter-wins face fold + the deny-entry union at prepare): a pre-199 worker
- * (MAX_SUPPORTED=8) would accept the row, ignore the section, and resume the leg under its own
- * defaults — silently DROPPING the frozen deny additions (a widening), and re-deriving the face
- * from live config alone. Stamping v9 forces it to reject PRE-CAS (`unsupported_version`, stays
- * `pending`, retried on an enforcing worker). A row whose task ran the default posture (face roots,
- * no additions) carries NO section and keeps the historic stamps — such a resume on ANY worker
- * folds to roots + built-ins, which is exactly the semantics it was cut under.
+ * Because the stamp is a maximum, the version records only the HIGHEST feature on a row; whether a lower
+ * feature is present is said by that feature's own mark, never by the number. A resume rule keyed on the
+ * version alone is therefore exact to the version at which its feature was the top: `realApproval` is
+ * version-recorded at v8 and marker-recorded (`readFace.realApproval`) from v9 on. The same law binds the
+ * NEXT feature: once a row can be stamped above v9, "v9+ ⇒ read-face section present" no longer follows
+ * from the stamp, and the face needs a mark of its own (or the row a per-feature presence record).
+ *
+ * v4 is a GAP, deliberately: the retired cross-slice wall-clock allocation. This worker still reads v4
+ * rows; a ledger carrying the retired axis is refused by FIELD (`walltime_axis_retired`) at any version.
  */
-export declare const FACE_CHECKPOINT_VERSION = 9;
-/** The highest {@link Checkpoint.version} `runner.resume` will act on; a higher one is rejected pre-CAS with
- *  {@link CheckpointError} `unsupported_version` (the checkpoint stays `pending`, retryable on a newer worker).
- *  Raised to 8 for realApproval-bearing gates — this worker reads v1 (legacy human), v2 (resource), v3
- *  (binding human/irreversible_ask), v4 (a pre-164 row, refused only when it carries the retired
- *  wall-clock allocation), v5 (token-allocation-bearing resource/approval), v6 (org-admission freeze
- *  state), v7 (F-012 constraint-chain / delegation-provenance enforcement state), v8 (a
- *  non-budgetable `realApproval` gate bit with its org-origin resume semantics), v9 (the
- *  design/199 read-face section: resolved face + deny-set additions, folded stricter-wins on
- *  resume). */
-export declare const MAX_SUPPORTED_CHECKPOINT_VERSION = 9;
+export declare const CHECKPOINT_FEATURES: {
+    /** The baseline shape: a plain human-approval suspend before any feature raised the format. No live
+     *  mint stamps it today; it is the floor of the ladder and the reading of a row written before any feature. */
+    readonly baseline: {
+        readonly version: 1;
+        readonly introduced: "design/49";
+        readonly recordedOn: (_cp: Checkpoint) => boolean;
+        readonly writes: "the row itself";
+    };
+    /** A `resource_limit` suspend: `resourceLedger` plus a `resource_limit` gate/pendingAction an older worker
+     *  cannot handle (it rejects pre-CAS; the row stays `pending`, retryable on a newer worker). */
+    readonly resource: {
+        readonly version: 2;
+        readonly introduced: "design/74";
+        readonly recordedOn: (cp: Checkpoint) => boolean;
+        readonly writes: "resourceLedger; gate/pendingAction kind resource_limit";
+    };
+    /** A HUMAN-DECISION park (tool approval or plan_review) of the binding era: the decision-action binding
+     *  (`boundCallId` + `boundInputHash` on a tool_approval) is enforced ENTIRELY by the resuming worker, so a
+     *  pre-binding worker must reject the row rather than execute the pending tool unverified. Like `resource`,
+     *  this row is a park-kind FLOOR: a plan_review park carries it with no binding (it was introduced above it);
+     *  whether a tool_approval row carries its hash is the resume binding rung's own conjunction. */
+    readonly binding: {
+        readonly version: 3;
+        readonly introduced: "design/80";
+        readonly recordedOn: (cp: Checkpoint) => boolean;
+        readonly writes: "pendingAction.boundCallId + boundInputHash on a tool_approval; a plan_review carries the stamp only";
+    };
+    /** A ledger carrying a cross-slice TOKEN allocation: the window clamp and the exhausted-resume fail-fast
+     *  live in the resuming worker. A ledger with no token total keeps the historic stamps. */
+    readonly token: {
+        readonly version: 5;
+        readonly introduced: "design/164";
+        readonly recordedOn: (cp: Checkpoint) => boolean;
+        readonly writes: "resourceLedger.totalTokens";
+    };
+    /** Org-memory admission freeze state (the adjudicated-empty record included): the session/delegation
+     *  freeze on resume and the tenant-admission door live in the resuming worker. */
+    readonly orgAdmission: {
+        readonly version: 6;
+        readonly introduced: "org-admission";
+        readonly recordedOn: (cp: Checkpoint) => boolean;
+        readonly writes: "inheritedGate.admittedOrgScopes / ownAdmittedOrgScopes / ownAdmittedOrgWriteScope / orgAdmissionGoverned";
+    };
+    /** The F-012 durable enforcement fields: the frozen ancestor projection chain + its digest (one write, the
+     *  resume-edit re-adjudication executes it) and/or the delegation-provenance aggregate a resume re-seeds. */
+    readonly f012: {
+        readonly version: 7;
+        readonly introduced: "F-012";
+        readonly recordedOn: (cp: Checkpoint) => boolean;
+        readonly writes: "inheritedGate.constraintChain + constraintDigest together; delegationProvenance";
+    };
+    /** A gate carrying {@link RealApprovalGateBit}: the no-org-wiring refusal and the org_unavailable resume
+     *  belt live in the resuming worker. Minted at ONE site (the approval park); the two always-mounted
+     *  integrity policies mint it on any durable deployment, org-governed or not. */
+    readonly realApproval: {
+        readonly version: 8;
+        readonly introduced: "#130/#120";
+        readonly recordedOn: (cp: Checkpoint) => boolean;
+        readonly writes: "gate.realApproval (a well-formed bit) + pendingAction.requiresRealApproval; from v9: readFace.realApproval = true beside it";
+    };
+    /** The READ-face section ({@link CheckpointState.readFace}): resolved face + normalized deny-set additions,
+     *  written only for a non-default posture; the stricter-wins fold lives in the resuming worker. Carries the
+     *  redundant governance marker for `realApproval` (see the table note above). Absent ⇒ default posture. */
+    readonly face: {
+        readonly version: 9;
+        readonly introduced: "design/199";
+        readonly recordedOn: (cp: Checkpoint) => boolean;
+        readonly writes: "state.readFace { face, denyEntries? } for a non-default posture; realApproval: true only at the mint whose gate carries the bit (a hands-less re-park never carries the seed's marker forward)";
+    };
+};
+/** One row of {@link CHECKPOINT_FEATURES}. */
+export interface CheckpointFeatureRow {
+    readonly version: number;
+    /** Where the feature came from — a design or ticket tag, documentation only. */
+    readonly introduced: string;
+    /** READ face: true iff the row carries the feature's persisted mark. */
+    readonly recordedOn: (cp: Checkpoint) => boolean;
+    /** WRITE face: what a mint must write when the feature is present (prose; the mint sites are the code). */
+    readonly writes: string;
+}
+/** The feature words — the row keys of {@link CHECKPOINT_FEATURES}. */
+export type CheckpointFeature = keyof typeof CHECKPOINT_FEATURES;
+/** The BASELINE {@link Checkpoint} schema version — the `baseline` row. NOT the highest a resume accepts (that
+ *  is {@link MAX_SUPPORTED_CHECKPOINT_VERSION}); resume stays forward-compatible by `<=` against MAX, never `===`. */
+export declare const CURRENT_CHECKPOINT_VERSION: 1;
+/** The `resource` row's version. */
+export declare const RESOURCE_CHECKPOINT_VERSION: 2;
+/** The `binding` row's version. */
+export declare const BINDING_CHECKPOINT_VERSION: 3;
+/** The `token` row's version. v4 (the retired wall-clock total) is deliberately not reused. */
+export declare const TOKEN_CHECKPOINT_VERSION: 5;
+/** The `orgAdmission` row's version. */
+export declare const ORG_ADMISSION_CHECKPOINT_VERSION: 6;
+/** The `f012` row's version. */
+export declare const F012_CHECKPOINT_VERSION: 7;
+/** The `realApproval` row's version. */
+export declare const REAL_APPROVAL_CHECKPOINT_VERSION: 8;
+/** The `face` row's version. */
+export declare const FACE_CHECKPOINT_VERSION: 9;
+/** The highest {@link Checkpoint.version} `runner.resume` will act on — the top row of the table; a higher one
+ *  is rejected pre-CAS with {@link CheckpointError} `unsupported_version` (the row stays `pending`, retryable on
+ *  a newer worker). This is the CEILING entrance: the storage-faithfulness probe stamps it directly on a
+ *  synthetic row that is never resumed, and does not go through feature detection. */
+export declare const MAX_SUPPORTED_CHECKPOINT_VERSION: 9;
+/** What a mint site answers for: every row but the baseline, every key MANDATORY — a new row is a compile
+ *  error at each mint site until that site says whether its rows carry the feature. */
+export type CheckpointFeaturePresence = Record<Exclude<CheckpointFeature, "baseline">, boolean>;
+/** The schema version a mint stamps: the highest version among the features PRESENT on the row, the baseline
+ *  when none is. One rule for every mint site — the precedence between features is the version numbers. */
+export declare function checkpointVersionFor(presence: CheckpointFeaturePresence): number;
 /**
  * Read a checkpoint's schema version, defaulting an absent field to **legacy `0`** (a 1.67-era checkpoint
  * written before the field existed — it carries no `workspaceHandle`, so resuming it the v1 way is safe).

package/dist/core/checkpoint-store.js

@@ -186,15 +186,39 @@ export function realApprovalOrgFact(bit) {
         return bit.org;
     return bit.origin === "org_rule" ? "rule" : bit.origin === "org_unavailable" ? "unavailable" : undefined;
 }
-export const CURRENT_CHECKPOINT_VERSION = 1;
-export const RESOURCE_CHECKPOINT_VERSION = 2;
-export const BINDING_CHECKPOINT_VERSION = 3;
-export const TOKEN_CHECKPOINT_VERSION = 5;
-export const ORG_ADMISSION_CHECKPOINT_VERSION = 6;
-export const F012_CHECKPOINT_VERSION = 7;
-export const REAL_APPROVAL_CHECKPOINT_VERSION = 8;
-export const FACE_CHECKPOINT_VERSION = 9;
-export const MAX_SUPPORTED_CHECKPOINT_VERSION = 9;
+export const CHECKPOINT_FEATURES = {
+    baseline: { version: 1, introduced: "design/49", recordedOn: (_cp) => true, writes: "the row itself" },
+    resource: { version: 2, introduced: "design/74", recordedOn: (cp) => cp.gate.kind === "resource_limit", writes: "resourceLedger; gate/pendingAction kind resource_limit" },
+    binding: { version: 3, introduced: "design/80", recordedOn: (cp) => cp.pendingAction.kind === "tool_approval" || cp.pendingAction.kind === "plan_review", writes: "pendingAction.boundCallId + boundInputHash on a tool_approval; a plan_review carries the stamp only" },
+    token: { version: 5, introduced: "design/164", recordedOn: (cp) => cp.resourceLedger?.totalTokens !== undefined, writes: "resourceLedger.totalTokens" },
+    orgAdmission: {
+        version: 6,
+        introduced: "org-admission",
+        recordedOn: (cp) => cp.state.inheritedGate?.admittedOrgScopes !== undefined || cp.state.inheritedGate?.ownAdmittedOrgScopes !== undefined || cp.state.inheritedGate?.ownAdmittedOrgWriteScope !== undefined || cp.state.inheritedGate?.orgAdmissionGoverned === true,
+        writes: "inheritedGate.admittedOrgScopes / ownAdmittedOrgScopes / ownAdmittedOrgWriteScope / orgAdmissionGoverned",
+    },
+    f012: { version: 7, introduced: "F-012", recordedOn: (cp) => cp.state.inheritedGate?.constraintChain !== undefined || cp.state.delegationProvenance !== undefined, writes: "inheritedGate.constraintChain + constraintDigest together; delegationProvenance" },
+    realApproval: { version: 8, introduced: "#130/#120", recordedOn: (cp) => cp.gate.kind === "irreversible_ask" && cp.gate.realApproval !== undefined, writes: "gate.realApproval (a well-formed bit) + pendingAction.requiresRealApproval; from v9: readFace.realApproval = true beside it" },
+    face: { version: 9, introduced: "design/199", recordedOn: (cp) => cp.state.readFace !== undefined, writes: "state.readFace { face, denyEntries? } for a non-default posture; realApproval: true only at the mint whose gate carries the bit (a hands-less re-park never carries the seed's marker forward)" },
+};
+export const CURRENT_CHECKPOINT_VERSION = CHECKPOINT_FEATURES.baseline.version;
+export const RESOURCE_CHECKPOINT_VERSION = CHECKPOINT_FEATURES.resource.version;
+export const BINDING_CHECKPOINT_VERSION = CHECKPOINT_FEATURES.binding.version;
+export const TOKEN_CHECKPOINT_VERSION = CHECKPOINT_FEATURES.token.version;
+export const ORG_ADMISSION_CHECKPOINT_VERSION = CHECKPOINT_FEATURES.orgAdmission.version;
+export const F012_CHECKPOINT_VERSION = CHECKPOINT_FEATURES.f012.version;
+export const REAL_APPROVAL_CHECKPOINT_VERSION = CHECKPOINT_FEATURES.realApproval.version;
+export const FACE_CHECKPOINT_VERSION = CHECKPOINT_FEATURES.face.version;
+export const MAX_SUPPORTED_CHECKPOINT_VERSION = CHECKPOINT_FEATURES.face.version;
+export function checkpointVersionFor(presence) {
+    let version = CHECKPOINT_FEATURES.baseline.version;
+    for (const feature of Object.keys(CHECKPOINT_FEATURES)) {
+        const row = CHECKPOINT_FEATURES[feature];
+        if (presence[feature] === true && row.version > version)
+            version = row.version;
+    }
+    return version;
+}
 export function checkpointVersionOf(cp) {
     return cp.version ?? 0;
 }

package/dist/core/mcp-failure.d.ts

@@ -46,6 +46,79 @@ export declare const DELIVERED_BY_KIND: {
 };
 /** The fence over the delivery table: `never` while every kind has a verdict. */
 export type DeliveryTableCoversEveryMcpFailureKind = AssertAllKeysHandled<Exclude<McpFailureKind, keyof typeof DELIVERED_BY_KIND>>;
+/**
+ * The closed set of {@link McpServerLiveness.state} — the engine's answer to ONE question, "can this
+ * client complete an exchange with this server":
+ *  · `reachable`   — an exchange COMPLETED (the dial handshaked and listed, a re-dial succeeded, or the
+ *                    server itself answered — an MCP-level rejection is an answer, so it proves reach
+ *                    even though it failed);
+ *  · `unreachable` — an exchange was attempted and lost at the transport or the clock (refused, reset,
+ *                    closed, unspawnable, timed out);
+ *  · `unknown`     — an exchange was attempted and what came back does not answer the question (a status
+ *                    a gateway in front of the server may have written, a non-MCP payload, a thrown value
+ *                    with no structure this table reads).
+ * ABSENCE is the fourth reading and is NOT one of these words: no observation exists at all (the leg
+ * never reached this server, or the declaration could not be dialed). A consumer must not fold an absent
+ * record into either `unknown` or a health verdict — absent means indeterminate, and `unknown` means
+ * "we looked and could not tell".
+ */
+export declare const MCP_LIVENESS_STATES: readonly ["reachable", "unreachable", "unknown"];
+export type McpLivenessState = (typeof MCP_LIVENESS_STATES)[number];
+/**
+ * One liveness OBSERVATION about one server (see {@link MCP_LIVENESS_STATES} for the words). It answers
+ * what the engine last LEARNED, at `observedAt` (epoch ms) — never what is true now, and never a poll:
+ * the engine makes no probe of its own, so every record here is a by-product of work the task already
+ * did (the dial, a re-dial, a transport close).
+ *
+ * `errorCode` rides `unreachable` ONLY, and names the failure class that decided it (a `spawn_failed` is
+ * a missing binary, a `connect_refused` a closed port). It is deliberately absent on `unknown`: the whole
+ * point of that word is that the failure did NOT decide reachability, so carrying its class there would
+ * invite a consumer to key a reach action off evidence that says nothing about reach. The connect-time
+ * class is still reported in its own right beside this record (the status / manifest row's `errorCode`).
+ */
+export interface McpServerLiveness {
+    state: McpLivenessState;
+    observedAt: number;
+    errorCode?: McpFailureKind;
+}
+/**
+ * What each failure CLASS says about reachability — the second disposition table over
+ * {@link MCP_FAILURE_KINDS}, beside {@link DELIVERED_BY_KIND}, and deliberately NOT derived from it:
+ * delivery asks "did the caller's request run", reachability asks "did an exchange complete", and the two
+ * part company on both edges — a `timeout` leaves delivery `unknown` while the exchange provably did not
+ * complete, and a `protocol` rejection is a failure the caller must handle while being the strongest
+ * proof of reach there is.
+ *
+ * `invalid_config` maps to `undefined` — the one class that is NOT an observation: a declaration that
+ * could not be dialed means no transport was ever attempted, so the honest record is no record (see the
+ * absence reading in {@link MCP_LIVENESS_STATES}), not a third-hand `unknown`.
+ */
+export declare const LIVENESS_BY_FAILURE_KIND: {
+    readonly connect_refused: "unreachable";
+    readonly connection_failed: "unreachable";
+    readonly connection_closed: "unreachable";
+    readonly http_status: "unknown";
+    readonly not_mcp_response: "unknown";
+    readonly spawn_failed: "unreachable";
+    readonly timeout: "unreachable";
+    readonly protocol: "reachable";
+    readonly invalid_config: undefined;
+    readonly unknown: "unknown";
+};
+/** The fence over the liveness table: `never` while every kind has a verdict. */
+export type LivenessTableCoversEveryMcpFailureKind = AssertAllKeysHandled<Exclude<McpFailureKind, keyof typeof LIVENESS_BY_FAILURE_KIND>>;
+/**
+ * What ONE exchange with a server tells the liveness record: the CLASS of the failure it ended in, or
+ * `"completed"` when it finished. Every round trip the engine makes — a dial, a tool call, a resource
+ * read, a listing, a refresh — reports exactly this, so the engine needs no second vocabulary and no
+ * per-site judgment about which failures "count".
+ */
+export type McpExchangeOutcome = McpFailureKind | "completed";
+/** The liveness observation an exchange supports, or `undefined` when the outcome is not an observation
+ *  at all (see {@link LIVENESS_BY_FAILURE_KIND}: a declaration that could never be dialed). THE single
+ *  mint of the record — no two sites can disagree about the word, about which words may carry
+ *  `errorCode`, or about what a completed exchange proves. */
+export declare function livenessOf(outcome: McpExchangeOutcome, observedAt: number): McpServerLiveness | undefined;
 /** Where the failure was judged: at the dial (connect + initial listing), where an errno on a stdio
  *  transport is the child process failing to spawn, or on a request over an established connection. */
 export type McpFailureSite = {

package/dist/core/mcp-failure.js

@@ -25,6 +25,27 @@ export const DELIVERED_BY_KIND = {
     invalid_config: "no",
     unknown: "unknown",
 };
+export const MCP_LIVENESS_STATES = ["reachable", "unreachable", "unknown"];
+export const LIVENESS_BY_FAILURE_KIND = {
+    connect_refused: "unreachable",
+    connection_failed: "unreachable",
+    connection_closed: "unreachable",
+    http_status: "unknown",
+    not_mcp_response: "unknown",
+    spawn_failed: "unreachable",
+    timeout: "unreachable",
+    protocol: "reachable",
+    invalid_config: undefined,
+    unknown: "unknown",
+};
+export function livenessOf(outcome, observedAt) {
+    if (outcome === "completed")
+        return { state: "reachable", observedAt };
+    const state = LIVENESS_BY_FAILURE_KIND[outcome];
+    if (state === undefined)
+        return undefined;
+    return state === "unreachable" ? { state, observedAt, errorCode: outcome } : { state, observedAt };
+}
 const CONNECT_KEEPS_THE_TABLE_VERDICT = new Set(["protocol", "http_status"]);
 const NETWORK_CODES_NEVER_DELIVERED = new Set([
     "ECONNREFUSED",

package/dist/core/mcp.d.ts

@@ -1,5 +1,5 @@
 import { type ProtocolId } from "./protocol-table.js";
-import { type McpDelivered, type McpFailureKind } from "./mcp-failure.js";
+import { type McpDelivered, type McpFailureKind, type McpServerLiveness } from "./mcp-failure.js";
 import type { AgentTool } from "../internal/harness-types.js";
 import type { ImageContent, TextContent } from "../internal/llm.js";
 import { type McpImageResizer } from "./image-downsample.js";
@@ -344,6 +344,23 @@ export interface McpServerStatus {
      * server name and the outcome) and this field stays absent.
      */
     transportClosed?: boolean;
+    /**
+     * The engine's last liveness OBSERVATION about this server ({@link McpServerLiveness}) — a different
+     * question from all three of its neighbours, and the note each of them carries says so:
+     *  · {@link status} is the CONNECT-TIME verdict of this leg, frozen at the dial — it is not this;
+     *  · {@link transportClosed} is one EVENT (a close notification arrived), on the transports that have
+     *    one — it is not this (this record also carries an `unreachable` that no close ever announced);
+     *  · `McpReconnectResult.outcome` is one ACTION's judgment — it is not this (it says what a re-dial
+     *    did, this says what the connection layer last learned).
+     * Written where the connection layer establishes or loses a connection (the dial, a re-dial, a close,
+     * a request that comes back with the transport gone), never on a timer and never by a probe: the
+     * engine adds no traffic of its own to answer it.
+     *
+     * ABSENT = no observation ({@link import("./mcp-failure.js").MCP_LIVENESS_STATES}): a declaration that could not be dialed
+     * (`invalid_config`) never touched a transport, and an older / foreign record predates the field. A
+     * consumer must read absence as indeterminate — never as healthy, never as off.
+     */
+    liveness?: McpServerLiveness;
 }
 /**
  * design/108 ① (CC 2.1.187 parity) — the GLOBAL `mcp__` marker prefix. CC names every MCP tool

package/dist/core/mcp.js

@@ -6,7 +6,7 @@ import { findNamespacePrefixCollision, mintNamespacePrefix, mintNamespacedToolNa
 import { Client } from "@modelcontextprotocol/sdk/client/index.js";
 import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
 import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
-import { classifyMcpFailure, describeHttpTransportFailure } from "./mcp-failure.js";
+import { classifyMcpFailure, describeHttpTransportFailure, livenessOf } from "./mcp-failure.js";
 import { lstat, mkdir, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
@@ -213,6 +213,7 @@ function rethrowHonestMcpError(err, ctx) {
     };
     sanitizeMcpErrorTextInPlace(err);
     if (ctx.idle?.signal.reason === IDLE_WATCHDOG_ABORT_REASON) {
+        ctx.liveness?.observe?.("timeout");
         const serverLabel = inlineUntrusted(ctx.server);
         finish(markMcpFailure(new Error(`${ctx.what} on MCP server "${serverLabel}" received no response for ${ctx.idle.idleMs}ms (idle watchdog — ` +
             `distinct from the ${ctx.timeoutMs}ms total ceiling above). The server may still be alive but is not ` +
@@ -224,6 +225,7 @@ function rethrowHonestMcpError(err, ctx) {
     const serverLabel = inlineUntrusted(ctx.server);
     const fenceServerText = (label, raw) => delimitUntrusted(label, truncateMcpErrorText(raw));
     const failure = classifyMcpFailure(err, { phase: "request" });
+    ctx.liveness?.observe?.(failure.kind);
     const details = (extra) => ({ code: failure.kind, delivered: failure.delivered, server: ctx.server, ...extra });
     switch (failure.kind) {
         case "timeout": {
@@ -721,10 +723,19 @@ export async function materializeMcpTools(specs, principal, onElicit, imageResiz
         else
             serverHandles[hIdx] = handle;
         const hasInstructions = s.instructions !== undefined;
+        const observe = (outcome) => {
+            if (disposing)
+                return;
+            const observed = livenessOf(outcome, Date.now());
+            if (observed !== undefined)
+                s.status.liveness = observed;
+        };
+        s.health.observe = observe;
         const announceClose = () => {
             if (disposing)
                 return;
             s.status.transportClosed = true;
+            observe("connection_closed");
             if (hasInstructions)
                 instructionsDelta.pendingRemovals.push(spec.name);
         };
@@ -807,7 +818,8 @@ export async function materializeMcpTools(specs, principal, onElicit, imageResiz
             else {
                 warnings.push(asServerWarning(spec, r.reason));
                 const { kind, delivered, httpStatus } = classifyMcpFailure(r.reason, { phase: "connect", transport: dialKinds[i] });
-                statuses.push({ name: spec.name, status: "failed", errorCode: kind, delivered, ...(httpStatus !== undefined ? { httpStatus } : {}), error: namedMcpFailureText(r.reason) });
+                const liveness = livenessOf(kind, Date.now());
+                statuses.push({ name: spec.name, status: "failed", errorCode: kind, delivered, ...(httpStatus !== undefined ? { httpStatus } : {}), error: namedMcpFailureText(r.reason), ...(liveness !== undefined ? { liveness } : {}) });
             }
         }
         const resourceTools = buildResourceTools(resourceServers, isServerRevoked);
@@ -838,6 +850,7 @@ export async function materializeMcpTools(specs, principal, onElicit, imageResiz
             const priorInstructions = prior?.instructions;
             if (prior) {
                 prior.announce.fn = undefined;
+                prior.health.observe = undefined;
                 serverHandles.splice(hIdx, 1);
                 const cIdx = clients.indexOf(prior.client);
                 if (cIdx !== -1)
@@ -851,7 +864,8 @@ export async function materializeMcpTools(specs, principal, onElicit, imageResiz
             }
             catch (err) {
                 const { kind, delivered, httpStatus } = classifyMcpFailure(err, { phase: "connect", transport: dialKind });
-                const status = { name: server, status: "failed", errorCode: kind, delivered, ...(httpStatus !== undefined ? { httpStatus } : {}), error: namedMcpFailureText(err) };
+                const redialLiveness = livenessOf(kind, Date.now());
+                const status = { name: server, status: "failed", errorCode: kind, delivered, ...(httpStatus !== undefined ? { httpStatus } : {}), error: namedMcpFailureText(err), ...(redialLiveness !== undefined ? { liveness: redialLiveness } : {}) };
                 const sIdx = statuses.findIndex((st) => st.name === server);
                 if (sIdx === -1)
                     statuses.push(status);
@@ -953,6 +967,7 @@ export async function materializeMcpTools(specs, principal, onElicit, imageResiz
                     });
                 }
                 catch (err) {
+                    h.health.observe?.(classifyMcpFailure(err, { phase: "request" }).kind);
                     results.push({
                         server: h.name,
                         prefix: prefixOf(h.name),
@@ -1334,7 +1349,8 @@ function buildResourceTools(resourceServers, isServerRevoked = () => false) {
                 try {
                     res = await rs.client
                         .readResource({ uri }, { signal: watchdog.combinedSignal, timeout: timeoutMs })
-                        .catch((err) => rethrowHonestMcpError(err, { server, what, timeoutMs, writeEffect: false, signal, attributeServer: true, idle: { signal: watchdog.idleSignal, idleMs } }));
+                        .catch((err) => rethrowHonestMcpError(err, { server, what, timeoutMs, writeEffect: false, signal, attributeServer: true, idle: { signal: watchdog.idleSignal, idleMs }, liveness: rs.health }));
+                    rs.health.observe?.("completed");
                 }
                 finally {
                     watchdog.dispose();
@@ -1393,7 +1409,7 @@ function buildResourceTools(resourceServers, isServerRevoked = () => false) {
                 try {
                     const ext = rs.client.getServerCapabilities()?.extensions?.[MCP_SKILLS_EXTENSION];
                     if (ext?.directoryRead === true) {
-                        const r = await readDirViaExtension(rs, uri, signal, timeoutMs, watchdog).catch((err) => rethrowHonestMcpError(err, { server, what, timeoutMs, writeEffect: false, signal, attributeServer: true, idle: { signal: watchdog.idleSignal, idleMs } }));
+                        const r = await readDirViaExtension(rs, uri, signal, timeoutMs, watchdog).catch((err) => rethrowHonestMcpError(err, { server, what, timeoutMs, writeEffect: false, signal, attributeServer: true, idle: { signal: watchdog.idleSignal, idleMs }, liveness: rs.health }));
                         const serverSaid = (detail) => `\nThe server's error text follows as external/untrusted data:\n${delimitUntrusted(`${server} error`, truncateMcpErrorText(detail))}`;
                         if (r.kind === "not_found") {
                             return {
@@ -1421,7 +1437,8 @@ function buildResourceTools(resourceServers, isServerRevoked = () => false) {
                     const walk = await walkMcpListPages(async (cursor, remainingMs) => {
                         const page = await rs.client
                             .listResources(cursor === undefined ? undefined : { cursor }, { signal: watchdog.combinedSignal, timeout: remainingMs })
-                            .catch((err) => rethrowHonestMcpError(err, { server, what, timeoutMs: remainingMs, writeEffect: false, signal, attributeServer: true, idle: { signal: watchdog.idleSignal, idleMs } }));
+                            .catch((err) => rethrowHonestMcpError(err, { server, what, timeoutMs: remainingMs, writeEffect: false, signal, attributeServer: true, idle: { signal: watchdog.idleSignal, idleMs }, liveness: rs.health }));
+                        rs.health.observe?.("completed");
                         return { items: page.resources, ...(page.nextCursor !== undefined ? { nextCursor: page.nextCursor } : {}) };
                     }, { budgetMs: timeoutMs, onPage: () => watchdog.rearm(), fingerprintOf: listEntryFingerprint, ...(signal !== undefined ? { signal } : {}) });
                     const dirPrefix = uri.endsWith("/") ? uri : `${uri}/`;
@@ -1552,13 +1569,15 @@ async function connectServer(spec, principal, onElicit, imageResizer, reminderDi
         const rawInstructions = client.getInstructions();
         const instructions = rawInstructions && rawInstructions.trim() ? sanitizeUntrustedText(rawInstructions.trim()) : undefined;
         const info = client.getServerVersion();
+        const status = {
+            name: spec.name,
+            status: "connected",
+            ...(info ? { serverInfo: { name: info.name, version: info.version } } : {}),
+            toolNames: serverTools.map((t) => t.name),
+            liveness: livenessOf("completed", Date.now()),
+        };
         return {
-            status: {
-                name: spec.name,
-                status: "connected",
-                ...(info ? { serverInfo: { name: info.name, version: info.version } } : {}),
-                toolNames: serverTools.map((t) => t.name),
-            },
+            status,
             client,
             health,
             announce,
@@ -1693,10 +1712,12 @@ function intakeListedTools(listed, spec, client, health, imageResizer, reminderD
                         writeEffect,
                         signal,
                         idle: { signal: watchdog.idleSignal, idleMs },
+                        liveness: health,
                         ...(reminderDisclosure !== undefined
                             ? { reminder: { mark: reminderDisclosure.mark, outlet: "mcp", ...(reminderDisclosure.counts !== undefined ? { counts: reminderDisclosure.counts } : {}) } }
                             : {}),
                     }));
+                    health.observe?.("completed");
                 }
                 finally {
                     watchdog.dispose();

package/dist/core/memory-engine/distiller.js

@@ -1,5 +1,5 @@
 import { readMember, thrownText } from "../thrown-value.js";
-import { assertServableRequestRoot } from "../../brain/route-adjudicator.js";
+import { assertServableRequestRoot, joinRequestUrl } from "../../brain/route-adjudicator.js";
 export const DISTILLER_DEFAULT_MAX_INPUTS_PER_PRODUCT = 32;
 const SIZE_CLAUSE = {
     "dl-2": "- the index should be as small as it can be made without losing either of the above.",
@@ -146,7 +146,7 @@ export function openAiCompatChatSeat(seat) {
         throw distillerConfigRefusal("memory consolidation driver chat seat needs a non-empty baseUrl.");
     let requestRoot;
     try {
-        requestRoot = (assertServableRequestRoot(seat.baseUrl, "memory consolidation driver chat seat baseUrl") ?? "").replace(/\/+$/, "");
+        requestRoot = assertServableRequestRoot(seat.baseUrl, "memory consolidation driver chat seat baseUrl") ?? "";
     }
     catch (e) {
         throw distillerConfigRefusal(thrownText(e), e);
@@ -157,7 +157,7 @@ export function openAiCompatChatSeat(seat) {
         throw distillerConfigRefusal(`memory consolidation driver chat seat needs an EXPLICIT model id, got ${JSON.stringify(seat.model)} — an alias can be re-pointed upstream and would move the driver with no trace in the plan.`);
     }
     return async (req) => {
-        const res = await fetch(`${requestRoot}/chat/completions`, {
+        const res = await fetch(joinRequestUrl(requestRoot, "/chat/completions"), {
             method: "POST",
             headers: { "content-type": "application/json", authorization: `Bearer ${seat.apiKey}` },
             body: JSON.stringify({