@sema-agent/core 7.0.2 → 7.2.0

package/dist/agents/cross-session-judge.js

@@ -0,0 +1,184 @@
+import { isPermissionModeClass } from "./cross-session-envelope.js";
+export const CROSS_SESSION_INBOUND_SETTINGS = Object.freeze(["accept", "hold", "refuse"]);
+export function isCrossSessionInboundSetting(value) {
+    return typeof value === "string" && CROSS_SESSION_INBOUND_SETTINGS.includes(value);
+}
+const RANK = { accept: 0, hold: 1, refuse: 2 };
+function readLayer(v) {
+    if (v === undefined || v === null || v === "default")
+        return undefined;
+    return isCrossSessionInboundSetting(v) ? v : "invalid";
+}
+export function resolveCrossSessionInboundSetting(layers) {
+    const invalidLayers = [];
+    let value;
+    let decidedBy;
+    for (const [name, raw] of [
+        ["managed", layers.managed],
+        ["user", layers.user],
+    ]) {
+        const v = readLayer(raw);
+        if (v === "invalid") {
+            invalidLayers.push(name);
+            continue;
+        }
+        if (v !== undefined && value === undefined) {
+            value = v;
+            decidedBy = name;
+        }
+    }
+    for (const raw of layers.repo ?? []) {
+        const v = readLayer(raw);
+        if (v === "invalid") {
+            invalidLayers.push("repo");
+            continue;
+        }
+        if (v === undefined)
+            continue;
+        if (RANK[v] > RANK[value ?? "accept"]) {
+            value = v;
+            decidedBy = "repo";
+        }
+        else if (v !== "accept" && value !== undefined && RANK[v] === RANK[value] && decidedBy !== "managed") {
+            decidedBy = "repo";
+        }
+    }
+    if (invalidLayers.length > 0 && RANK[value ?? "accept"] < RANK.hold) {
+        value = "hold";
+        decidedBy = "invalid";
+    }
+    return { ...(value !== undefined ? { value } : {}), ...(decidedBy !== undefined ? { decidedBy } : {}), invalidLayers };
+}
+export const CROSS_SESSION_HOLD_CAUSES = Object.freeze([
+    "mode-mismatch",
+    "no-mode-asserted",
+    "explicit-setting",
+    "managed-setting",
+    "repo-setting",
+    "invalid-setting",
+    "bypass-default",
+    "mode-unknown",
+    "invalid-mode-attestation",
+]);
+export function describeCrossSessionHoldCause(cause) {
+    switch (cause) {
+        case "mode-mismatch":
+            return "The sending session's permission mode class doesn't match this session's, so it wasn't delivered automatically.";
+        case "no-mode-asserted":
+            return "The sender did not attest its permission mode, and this session bypasses permission prompts.";
+        case "explicit-setting":
+            return 'Your "crossSessionInbound" setting is "hold".';
+        case "managed-setting":
+            return `Your organization's managed settings set "crossSessionInbound" to "hold".`;
+        case "repo-setting":
+            return `This repository's settings set "crossSessionInbound" to "hold" (your own "accept" cannot override a repo tightening).`;
+        case "invalid-setting":
+            return 'A settings file has an unrecognized "crossSessionInbound" value (see the settings warning), so messages are held while it is present.';
+        case "bypass-default":
+            return "This session is not prompting for permissions.";
+        case "mode-unknown":
+            return "This session's permission mode could not be determined.";
+        case "invalid-mode-attestation":
+            return "The sender attested an unrecognized permission mode, so the message is held for your review.";
+        default: {
+            const _exhaustive = cause;
+            void _exhaustive;
+            throw new Error(`unreachable hold cause ${String(cause)}`);
+        }
+    }
+}
+function describeUnknown(value) {
+    try {
+        const text = typeof value === "string" ? JSON.stringify(value) : typeof value === "bigint" ? `${value}n` : typeof value === "object" && value !== null ? JSON.stringify(value) : String(value);
+        return text.length > 80 ? `${text.slice(0, 80)}…` : text;
+    }
+    catch {
+        return `[unrenderable ${typeof value}]`;
+    }
+}
+function holdFor(cause, warning) {
+    return { verdict: "hold", cause, message: describeCrossSessionHoldCause(cause), ...(warning !== undefined ? { warning } : {}) };
+}
+function causeOf(decidedBy) {
+    switch (decidedBy) {
+        case "managed":
+            return "managed-setting";
+        case "repo":
+            return "repo-setting";
+        case "invalid":
+            return "invalid-setting";
+        case "user":
+        case undefined:
+            return "explicit-setting";
+        default: {
+            const _exhaustive = decidedBy;
+            void _exhaustive;
+            throw new Error(`unreachable setting source ${String(decidedBy)}`);
+        }
+    }
+}
+export function judgeCrossSessionInbound(input) {
+    const { setting, selfModeClass, sender } = input;
+    if (setting.value !== undefined) {
+        switch (setting.value) {
+            case "accept":
+                return { verdict: "deliver" };
+            case "refuse":
+                return { verdict: "refuse", cause: "opt-out" };
+            case "hold": {
+                const cause = causeOf(setting.decidedBy);
+                return holdFor(cause, cause === "invalid-setting" ? `unrecognized "crossSessionInbound" value in: ${setting.invalidLayers.join(", ")}` : undefined);
+            }
+            default: {
+                const _exhaustive = setting.value;
+                void _exhaustive;
+                throw new Error(`unreachable setting value ${String(setting.value)}`);
+            }
+        }
+    }
+    if (sender?.selfSent === true)
+        return { verdict: "deliver" };
+    if (selfModeClass === "unknown")
+        return holdFor("mode-unknown");
+    if (sender === undefined)
+        return selfModeClass === "bypass" ? holdFor("bypass-default") : { verdict: "deliver" };
+    if (sender.fromMode !== undefined) {
+        if (!isPermissionModeClass(sender.fromMode)) {
+            return holdFor("invalid-mode-attestation", `sender attested from-mode=${describeUnknown(sender.fromMode)} (expected bypass|prompting)`);
+        }
+        return sender.fromMode === selfModeClass ? { verdict: "deliver" } : holdFor("mode-mismatch");
+    }
+    return selfModeClass === "bypass" ? holdFor("no-mode-asserted") : { verdict: "deliver" };
+}
+export function foldPermissionModeClass(askEffective) {
+    switch (askEffective) {
+        case "auto_allow":
+            return "bypass";
+        case "human_reachable":
+        case "park_only":
+        case "auto_deny":
+            return "prompting";
+        case "unresolved":
+            return "unknown";
+        default: {
+            const _exhaustive = askEffective;
+            void _exhaustive;
+            throw new Error(`unreachable ask effective ${String(askEffective)}`);
+        }
+    }
+}
+export const PEER_SEND_VERDICT_CODES = Object.freeze([
+    "peer_send.stale_socket",
+    "peer_send.socket_busy",
+    "peer_send.too_large",
+    "peer_send.invalid_target",
+    "peer_send.timeout",
+    "peer_send.recipient_refuses",
+    "peer_send.not_reachable",
+    "peer_send.subscription_cap",
+    "peer_send.send_uncertain",
+    "peer_send.other",
+]);
+export function peerSendVerdictSeverity(code) {
+    return code === "peer_send.send_uncertain" || code === "peer_send.recipient_refuses" || code === "peer_send.subscription_cap" ? "degraded" : "error";
+}

package/dist/agents/cross-session-ref.d.ts

@@ -0,0 +1,52 @@
+/** CC `aa` / `bmn`: a ref is 6..12 hex characters — the shortest prefix of `sha256(kind:id)` that is
+ *  unique against its sorted neighbours in the LISTING that minted it. */
+export declare const PEER_REF_MIN = 6;
+export declare const PEER_REF_MAX = 12;
+/** CC `Mz`. */
+export declare const PEER_REF_RE: RegExp;
+export interface PeerRefEntry {
+    /** The identity kind (`session`, `agent`, …): part of the hash input so two kinds with the same id
+     *  never share a ref. */
+    kind: string;
+    /** The durable id (a `session.<id>` box handle, an a* agent handle, …). */
+    id: string;
+}
+/**
+ * CC `K8` transcribed on sha256: mint the ref of EVERY entry of one listing. Refs are minted by the
+ * listing side and are valid only against that listing (a ref the model did not just read from a
+ * listing or a disambiguation error will not resolve). The optional `self` entry joins the
+ * disambiguation set (so no ref collides with the caller's own identity) but is not returned.
+ * The hash choice is local to this engine: a ref never crosses a process boundary, so the value
+ * domain (`[0-9a-f]{6,12}`) is what interoperates, not the digest.
+ */
+export declare function mintPeerRef<T extends PeerRefEntry>(entries: readonly T[], self?: PeerRefEntry): Array<T & {
+    ref: string;
+}>;
+/** CC `qN` — the display token. */
+export declare function formatPeerNameRef(name: string, ref: string): string;
+/** CC `V8`/`DO` — split a `name [ref]` token; `undefined` when no ref suffix is present. */
+export declare function parsePeerNameRef(text: string): {
+    name: string;
+    ref: string;
+} | undefined;
+/**
+ * CC `dr` — the MATCHING key of a peer/session name: NFKC → strip control/format code points → trim →
+ * lower-case → collapse whitespace runs to `-`. Every terminal resolves and compares names on this
+ * key (a display name is never the key).
+ */
+export declare function normalizePeerName(name: string): string;
+/** The box-address prefixes of design/385 (`session.<id>` per-session box, `principal.<…>` the
+ *  cross-principal inbox family). Reserved: a NAME may never spell an address. */
+export declare const PEER_ADDRESS_PREFIXES: readonly string[];
+/**
+ * design/385 §2.2 namespace protection (CC `qd` in spirit): a candidate spawn/session name is refused
+ * when its normalized key would shadow an explicit address — a reserved box prefix, a transport
+ * scheme (`uds:` / `bridge:` / `did:`), a socket path, an `@`-bearing team form, or the `*`
+ * broadcast token. Returns the reason, or `undefined` when the name is admissible. Registration-side
+ * check (loud refusal at write time); the resolution ladder ranks explicit addresses first regardless.
+ *
+ * The socket-path arm is judged on the RAW name AND on its normalized key (CC `QHe` runs its
+ * classifier over both): a name that is a socket path in either spelling is refused, since the
+ * resolution ladder would read the raw spelling as an address.
+ */
+export declare function reservedPeerNameReason(name: string): "empty" | "address_prefix" | "transport_scheme" | "socket_path" | "at_sign" | "wildcard" | undefined;

package/dist/agents/cross-session-ref.js

@@ -0,0 +1,64 @@
+import { createHash } from "node:crypto";
+export const PEER_REF_MIN = 6;
+export const PEER_REF_MAX = 12;
+export const PEER_REF_RE = /^[0-9a-f]{6,12}$/;
+function refHash(e) {
+    return createHash("sha256").update(`${e.kind}:${e.id}`).digest("hex");
+}
+function commonPrefixLen(a, b) {
+    let n = 0;
+    while (n < a.length && n < b.length && a[n] === b[n])
+        n++;
+    return n;
+}
+export function mintPeerRef(entries, self) {
+    const hashes = entries.map(refHash);
+    const universe = [...new Set([...hashes, ...(self !== undefined ? [refHash(self)] : [])])].sort();
+    const lengths = new Map();
+    for (let i = 0; i < universe.length; i++) {
+        const h = universe[i];
+        const shared = Math.max(i > 0 ? commonPrefixLen(h, universe[i - 1]) : 0, i + 1 < universe.length ? commonPrefixLen(h, universe[i + 1]) : 0);
+        lengths.set(h, Math.min(h.length, Math.max(PEER_REF_MIN, shared + 1)));
+    }
+    return entries.map((e, i) => {
+        const h = hashes[i];
+        return { ...e, ref: h.slice(0, Math.min(lengths.get(h), PEER_REF_MAX)) };
+    });
+}
+export function formatPeerNameRef(name, ref) {
+    return `${name} [${ref}]`;
+}
+export function parsePeerNameRef(text) {
+    const m = /^(.*\S)\s*\[([0-9a-f]{6,12})\]$/.exec(text.trim());
+    return m === null ? undefined : { name: m[1], ref: m[2] };
+}
+export function normalizePeerName(name) {
+    return name
+        .normalize("NFKC")
+        .replace(/[\p{Cc}\p{Cf}]/gu, "")
+        .trim()
+        .toLowerCase()
+        .replace(/\s+/g, "-");
+}
+export const PEER_ADDRESS_PREFIXES = Object.freeze(["session.", "principal."]);
+const SOCKET_PATH_RE = /^\/\S*\.sock/;
+const NAMED_PIPE_RE = /^[\\/]{2}[.?][\\/]pipe[\\/]/i;
+function isSocketPathSpelling(text) {
+    return SOCKET_PATH_RE.test(text) || NAMED_PIPE_RE.test(text);
+}
+export function reservedPeerNameReason(name) {
+    const key = normalizePeerName(name);
+    if (key === "")
+        return "empty";
+    if (key === "*")
+        return "wildcard";
+    if (key.includes("@"))
+        return "at_sign";
+    if (PEER_ADDRESS_PREFIXES.some((p) => key.startsWith(p)))
+        return "address_prefix";
+    if (/^(?:uds|bridge|did):/.test(key))
+        return "transport_scheme";
+    if (isSocketPathSpelling(name) || isSocketPathSpelling(key))
+        return "socket_path";
+    return undefined;
+}

package/dist/agents/repair-loop.d.ts

@@ -13,7 +13,7 @@ import { type OracleIsolationVerdict } from "../core/oracle-isolation.js";
  * `oracleIsolation` boundary that this slice deliberately does not build — SAFE-tier escalates to a human
  * (`needs_human_oracle`) or surfaces a candidate, but never clears its own work.
  *
- * Like {@link verifyCompleted}, this is a **thin composition** over `runner.runTask` (verify.ts:18-21 posture)
+ * Like {@link verifyCompleted}, this is a **thin composition** over `runner.runTask` (verify.ts's DEPLOYMENT POSTURE section)
  * — it adds no Runner-core surface, touches no vendored code, and is called by a leader/profile (the sibling
  * of {@link runWithVerification}). The oracle internals (which gate/judge/property-harness to compose) live
  * in the PROFILE-injected {@link RepairOracle} closure; core only fixes the {@link OracleResult} shape and the
@@ -75,12 +75,13 @@ export interface OracleResult {
 }
 /**
  * The PROFILE-injected oracle (§1 裁决①). The profile composes the actual grading inside this closure —
- * `runExecGate(graderEnv, steps)` (exec-gate.ts:185, env is the FIRST param = L2 provenance bound to the
- * grader) → `verifyCompleted` (verify.ts:212, the read-only L3 judge) → `checkInvariants`
- * (property-harness.ts:217, explore-only) — and maps the composite to an {@link OracleResult}. Core never
+ * `runExecGate(graderEnv, steps)` (core/exec-gate.ts, env is the FIRST param = L2 provenance bound to the
+ * grader) → `verifyCompleted` (agents/verify.ts, the read-only L3 judge) → `checkInvariants`
+ * (core/property-harness.ts, explore-only) — and maps the composite to an {@link OracleResult}. Core never
  * composes these internals (so the oracle type can't grow a long discriminated union); it only fixes the
  * `OracleResult` shape and the read-only/identity contract. `graderEnv` is the isolated grader env; `evidence`
- * is the diff/results to judge (recompute it from the post-resume working tree on a resume — verify.ts:328 BUG5).
+ * is the diff/results to judge (recompute it from the post-resume working tree on a resume — threat BUG5, the
+ * same freshness duty verify.ts states on its own `evidence` config field).
  */
 export type RepairOracle = (graderEnv: ExecutionEnv, evidence: string | undefined) => Promise<OracleResult>;
 /**
@@ -166,12 +167,12 @@ export interface RepairLoopConfig {
      */
     resumeBundle?: RepairBundle;
     /**
-     * Stop the loop once cumulative cost reaches this (verify.ts:278 backstop). HRD-AGO-6 — "cumulative" is
+     * Stop the loop once cumulative cost reaches this (verify.ts's `costCeilingMicroUsd` backstop). HRD-AGO-6 — "cumulative" is
      * every leg the loop pays for: each attempt's own + nested `runTask` cost PLUS each verdict's
      * {@link OracleResult.costMicroUsd} (an LLM-judge oracle is charged per attempt too).
      */
     costCeilingMicroUsd?: number;
-    /** Overall ACTIVE wall-clock ceiling for the whole loop (verify.ts:277 backstop). F1: both ceilings
+    /** Overall ACTIVE wall-clock ceiling for the whole loop (verify.ts's `totalTimeoutMs` backstop). F1: both ceilings
      *  are CROSS-RESUME — the carried {@link RepairBundle.spentMicroUsd}/{@link RepairBundle.activeElapsedMs}
      *  re-seed the accounts, so a durable resume continues the budget rather than restarting it. */
     totalTimeoutMs?: number;

package/dist/agents/roster-store.d.ts

@@ -12,8 +12,13 @@ export interface RosterEntry {
      *  key; equals the spawner's session at depth 1). Stored verbatim; no predicate arm consumes it
      *  yet (enumeration/recovery is the reader). */
     rootSessionId?: string;
-    /** design/151 S3b — the RESOLVED model id at spawn (revival lookup key; display/model-routing
-     *  hints only, never a serialized spec). */
+    /** design/151 S3b — the model RECORD KEY at spawn (revival lookup key; display/model-routing hints
+     *  only, never a serialized spec). NOT the resolved model id: a spawn that named a model in WORDS
+     *  records the caller's spelling VERBATIM (a catalog key, tier word or CC alias), because a revival
+     *  re-resolves this value against the catalog in force at WAKE time and a resolved id would only
+     *  ever resolve again on deployments whose catalog keys happen to equal model ids. A spawn that
+     *  carried a Model OBJECT (definition/tool-level/inherited ref) records that object's id, which on
+     *  such a deployment is not a catalog key and degrades softly on the revival lane. */
     model?: string;
     /** Ruled 2026-08-05: the spawn requested a model word that did not bind — the row runs on its
      *  inherited default. Closed set, single member today; absent = bound normally (or no word). */

package/dist/agents/send-message-tool.d.ts

@@ -44,6 +44,19 @@ export interface SendMessageToolOptions {
      *  this run's process exits when the turn ends, so no completion notification can ever land — checked
      *  AHEAD of {@link notificationWired}, since no amount of wiring makes a later turn exist. */
     oneShot?: boolean;
+    /**
+     * Whether a RETRIEVAL tool (`TaskOutput`) is mounted beside this tool on the same face. Every
+     * degraded completion promise on this face (the one-shot and silent arms of the description and
+     * the receipt/refusal texts) tells the model how to collect a continued agent's result; naming
+     * `TaskOutput(task_id, block: true)` as an imperative is only true where that tool exists. Since
+     * design/385 §1.5 this tool also mounts on the delegated-child arm WITHOUT the background door
+     * TaskOutput/TaskStop keep, so the two can no longer be assumed to travel together. Three states:
+     * `true` — the advice names TaskOutput plainly; `false` — this face has no retrieval tool, and the
+     * advice says the result cannot be collected by this run instead of naming a tool the model cannot
+     * call (an unknown-tool error on a one-shot run is the turn where the result is lost); absent — the
+     * mount did not say, and the advice is hedged ("where that tool is mounted").
+     */
+    retrievalToolMounted?: boolean;
     /** Steer-handle sink: the revived run re-emits a FRESH handle (design/122 risk-table contract). */
     sink?: (handle: SubagentSteerHandle) => void;
     /**

package/dist/agents/send-message-tool.js

@@ -6,6 +6,7 @@ import { uuidv7 } from "../internal/harness.js";
 import { MAILBOX_TOMBSTONED_RECIPIENT_CODE } from "../core/mailbox-store.js";
 import { escapeAttributeValue, escapeEnvelopeTag, isObserverTaskId, OBSERVER_SENDMESSAGE_SENDER_REFUSAL, OBSERVER_SENDMESSAGE_TARGET_REFUSAL, } from "./observer.js";
 import { inlineUntrusted } from "../core/untrusted-text.js";
+import { neutralizePeerBody } from "./cross-session-envelope.js";
 import { SUBAGENT_RESUME_CAP, SubagentRetainLedger, getSessionRetainLedger } from "./retain-ledger.js";
 import { createSubagentResume } from "./subagent.js";
 import { appendHopToken, judgePeerAdmission, peerAxisToken, resolvePeerAdmissionConfig, PEER_MESSAGE_NOTICE, } from "./peer-admission.js";
@@ -24,7 +25,7 @@ export function clipSendMessageSummary(raw) {
 const TEAMMATE_MESSAGE_TAG = "teammate-message";
 function frameTeammateMessage(args) {
     const summaryAttr = args.summary !== undefined ? ` summary="${escapeAttributeValue(args.summary)}"` : "";
-    const body = escapeEnvelopeTag(TEAMMATE_MESSAGE_TAG, args.text);
+    const body = escapeEnvelopeTag(TEAMMATE_MESSAGE_TAG, neutralizePeerBody(args.text));
     return `<${TEAMMATE_MESSAGE_TAG} teammate_id="${escapeAttributeValue(args.from)}"${summaryAttr}>\n${body}\n</${TEAMMATE_MESSAGE_TAG}>`;
 }
 const REVIVE_LEASE_TTL_MS = 5 * 60_000;
@@ -46,21 +47,36 @@ function targetLaneKey(scope, targetId) {
 const OPERATOR_CONTINUATION_CTX = Symbol("sema.operator_continuation");
 export function createSendMessageTool(opts) {
     const tier3Capable = opts.agentStore !== undefined && opts.mailbox !== undefined && opts.reviveSpawn !== undefined;
+    const retrievalMounted = opts.retrievalToolMounted;
+    const retrievalHedge = retrievalMounted === undefined ? " (where that tool is mounted)" : "";
+    const RETRIEVE_NOW = retrievalMounted === false
+        ? "its result cannot be collected by this run (no TaskOutput is mounted beside this tool) — do not wait for it, and say so in your answer if the result matters"
+        : `retrieve its result NOW with TaskOutput(task_id, block: true)${retrievalHedge} rather than ending your turn`;
+    const RETRIEVE_LATER = retrievalMounted === false
+        ? "its result cannot be collected by this run (no TaskOutput is mounted beside this tool)"
+        : "retrieve its status and result with TaskOutput(task_id) where mounted";
+    const WAIT_NOW = retrievalMounted === false
+        ? "do not wait for it — this face has no TaskOutput to block on, and"
+        : `wait for it NOW with TaskOutput(task_id, block: true)${retrievalHedge} —`;
+    const CHECK_LATER = retrievalMounted === false
+        ? "its completion cannot be checked from this face (no TaskOutput is mounted beside this tool)"
+        : "check for its completion with TaskOutput(task_id) where mounted";
+    const capitalize = (text) => `${text.charAt(0).toUpperCase()}${text.slice(1)}`;
     const completionMode = opts.oneShot === true ? "one_shot" : (opts.notificationWired ?? opts.notify !== undefined) ? "notified" : "silent";
     const notifyWired = completionMode === "notified";
     const NO_COMPLETION_NOTICE = completionMode === "one_shot"
-        ? "this is a ONE-SHOT submission — there is no later turn for a completion notification to land in, so retrieve its result NOW with TaskOutput(task_id, block: true) rather than ending your turn"
-        : "its completion is NOT announced on this mount — retrieve its status and result with TaskOutput(task_id) where mounted";
+        ? `this is a ONE-SHOT submission — there is no later turn for a completion notification to land in, so ${RETRIEVE_NOW}`
+        : `its completion is NOT announced on this mount — ${RETRIEVE_LATER}`;
     const AWAIT_COMPLETION = notifyWired
         ? "Wait for its completion notification"
         : completionMode === "one_shot"
-            ? "Wait for it NOW with TaskOutput(task_id, block: true) — this one-shot submission ends with this turn"
-            : "Check for its completion with TaskOutput(task_id) where mounted";
+            ? `${capitalize(WAIT_NOW)} this one-shot submission ends with this turn`
+            : capitalize(CHECK_LATER);
     const awaitCompletion = notifyWired
         ? "wait for its completion notification"
         : completionMode === "one_shot"
-            ? "wait for it NOW with TaskOutput(task_id, block: true) — this one-shot submission ends with this turn"
-            : "check for its completion with TaskOutput(task_id) where mounted";
+            ? `${WAIT_NOW} this one-shot submission ends with this turn`
+            : CHECK_LATER;
     const sendMessagePins = new Map();
     const pinGuard = (targetId, targetName, rung, to) => {
         if (rung === "other")
@@ -104,8 +120,12 @@ export function createSendMessageTool(opts) {
             (notifyWired
                 ? `You will be notified automatically when it completes — prefer ending your turn; do not poll. `
                 : completionMode === "one_shot"
-                    ? `This is a ONE-SHOT submission: there is no later turn for a completion notification to land in, so do NOT end your turn expecting one — wait actively with TaskOutput(task_id, block: true) when you need a continued agent's result. `
-                    : `A finished agent is NOT announced on this mount — check on it with TaskOutput(task_id) where mounted rather than ending your turn to wait for a notification that never comes. `) +
+                    ? `This is a ONE-SHOT submission: there is no later turn for a completion notification to land in, so do NOT end your turn expecting one${retrievalMounted === false
+                        ? "; a continued agent's result cannot be collected by this run (no TaskOutput is mounted beside this tool) — say so if the result matters"
+                        : ` — wait actively with TaskOutput(task_id, block: true)${retrievalHedge} when you need a continued agent's result`}. `
+                    : `A finished agent is NOT announced on this mount${retrievalMounted === false
+                        ? ", and its result cannot be collected by this run (no TaskOutput is mounted beside this tool) — do not end your turn to wait for a notification that never comes"
+                        : " — check on it with TaskOutput(task_id) where mounted rather than ending your turn to wait for a notification that never comes"}. `) +
             (tier3Capable
                 ? `Continuing a finished agent works for agents with a durable record — by name or task_id, even across restarts — and for runs that retain sub-agent sessions; when neither covers it you get an honest error and should launch a new agent with the needed context instead.`
                 : `Continuing a finished agent requires the run to retain sub-agent sessions; when the session was not ` +
@@ -191,15 +211,19 @@ export function createSendMessageTool(opts) {
                         if (!verdict.ok)
                             return admissionRefusal(verdict.reason, "main");
                     }
+                    const uplinkBody = message.length > UPLINK_RESULT_MAX ? `${message.slice(0, UPLINK_RESULT_MAX)}\n[uplink truncated: ${message.length} chars total — read the agent's transcript for the rest]` : message;
+                    const uplinkSeq = ++uplinkSeqGlobal;
                     try {
                         opts.uplink({
                             task_id: senderId,
                             task_type: "background_agent",
                             status: "event",
                             summary: `message from ${senderLabel}: ${summary}`,
-                            result: `${message.length > UPLINK_RESULT_MAX ? `${message.slice(0, UPLINK_RESULT_MAX)}\n[uplink truncated: ${message.length} chars total — read the agent's transcript for the rest]` : message}\n\n${PEER_MESSAGE_NOTICE}`,
-                            seq: ++uplinkSeqGlobal,
+                            result: `${uplinkBody}\n\n${PEER_MESSAGE_NOTICE}`,
+                            seq: uplinkSeq,
                             peer: { hopChain: prospectiveChain },
+                            agentMessage: { from: senderLabel, body: uplinkBody },
+                            _sema_provenance: { kind: "agent_message", from: senderLabel, taskId: senderId, seq: uplinkSeq },
                         }, { priority: "next" });
                     }
                     catch (e) {
@@ -207,7 +231,7 @@ export function createSendMessageTool(opts) {
                     }
                     return {
                         content: `Message sent to main — queued for the spawning conversation at its next turn boundary. If that conversation finishes before reading it, the message may not survive. Continue with your task; do not wait for a reply.`,
-                        details: { type: "send-message", status: "uplinked", to: "main", seq: uplinkSeqGlobal },
+                        details: { type: "send-message", status: "uplinked", to: "main", seq: uplinkSeq },
                     };
                 }
                 if (!senderIsChild) {

package/dist/brain/errors.d.ts

@@ -82,6 +82,24 @@ export declare function readProviderRequestId(res: {
         get?: (name: string) => string | null;
     };
 } | undefined): string | undefined;
+/**
+ * Does this HTTP status NAME the failure it is being attached to? The one predicate governing every
+ * seat on which this engine publishes a provider status — the terminal assistant frame's
+ * `apiErrorStatus` and the retry-wait status frame's `errorStatus` (#506 ㋑). One helper on purpose:
+ * both seats promise the same three-state discipline, and two copies of the rule would drift.
+ *
+ * Two distinct shapes are refused, and both are reachable:
+ *  · The engine's "no status" SENTINEL, 0 — the terminal HTTP throw carries `r?.status ?? 0` when a
+ *    transport hands back neither a response nor a throw. Publishing it would be absence rendered as a
+ *    number a consumer may format, which is worse than silence.
+ *  · A SUCCESS status. The connect loop only streams a response that is `ok` AND has a body, so an
+ *    `ok` response with a NULL body (an empty 200 from a proxy, a 204) reaches the terminal throw
+ *    carrying 200 — and a provider's own `x-should-retry` verdict can send that same 2xx into a RETRY
+ *    wait. The boundary really did fail, but the status is not what failed, and a consumer routing or
+ *    rendering by a 2xx is exactly the misreading these seats exist to prevent.
+ * Stalls, connect failures and in-band error frames inside a 200 leave the seat absent by the same rule.
+ */
+export declare function namesTheFailure(status: number | undefined): status is number;
 /** Map an HTTP status to an error class. 401/403 = auth (don't retry); 429 = rate limit; 5xx = server. */
 export declare function classifyHttp(status: number): BrainErrorCode;
 /** Lift the machine-readable code back out of a `[code] …` prefixed `errorMessage` (the single shared

package/dist/brain/errors.js

@@ -45,6 +45,9 @@ export function readProviderRequestId(res) {
     }
     return undefined;
 }
+export function namesTheFailure(status) {
+    return status !== undefined && status >= 100 && !(status >= 200 && status < 300);
+}
 export function classifyHttp(status) {
     if (status === 401 || status === 403)
         return "auth";

package/dist/brain/stream-engine.js

@@ -1,6 +1,6 @@
 import { createAssistantMessageEventStream, } from "../internal/llm.js";
 import { FLOOR_OUTPUT_TOKENS, parseContextOverflow, planOutputCapAdjustment } from "./context-overflow.js";
-import { BrainError, classifyConnectFailure, classifyHttp, describeNetworkError, readProviderRequestId } from "./errors.js";
+import { BrainError, classifyConnectFailure, classifyHttp, describeNetworkError, namesTheFailure, readProviderRequestId } from "./errors.js";
 import { classifyInputTooLong } from "./input-too-long.js";
 import { FAST_MAX_BACKOFF_MS, providerWaitHint, retryBackoffMs } from "./retry.js";
 import { emitBrainStatus, emitBrainTelemetry } from "./status-sink.js";
@@ -267,9 +267,8 @@ export function runStreamingBrain(args) {
                 errorMsg.inputTooLongRuledOut = true;
             if (err.apiError === true) {
                 errorMsg.isApiErrorMessage = true;
-                const st = err.status;
-                if (st !== undefined && st >= 100 && !(st >= 200 && st < 300))
-                    errorMsg.apiErrorStatus = st;
+                if (namesTheFailure(err.status))
+                    errorMsg.apiErrorStatus = err.status;
                 if (requestIdSeen !== undefined)
                     errorMsg.requestId = requestIdSeen;
             }
@@ -376,6 +375,7 @@ export function runStreamingBrain(args) {
                                         attempt: attempt + 1,
                                         maxRetries,
                                         errClass: "output_cap",
+                                        ...(namesTheFailure(r?.status) ? { errorStatus: r.status } : {}),
                                     });
                                     continue;
                                 }
@@ -428,6 +428,7 @@ export function runStreamingBrain(args) {
                         discardResponseBody(r);
                         cc.abort();
                         cc.dispose();
+                        const retryStatus = namesTheFailure(r?.status) ? r.status : undefined;
                         await sleepAnnouncingRetry(delayMs, signal, (remainingMs) => ({
                             phase: statusPhase,
                             detail: statusPhase === "rate_limited"
@@ -440,6 +441,7 @@ export function runStreamingBrain(args) {
                             attempt: attempt + 1,
                             maxRetries: laneMaxRetries,
                             errClass,
+                            ...(retryStatus !== undefined ? { errorStatus: retryStatus } : {}),
                         }));
                         continue;
                     }