@sema-agent/core 7.54.1 → 7.55.0

package/dist/core/roles.js

@@ -5,12 +5,15 @@ function catalogModel(ref, models) {
     const m = models != null && (typeof models === "object" || typeof models === "function") && Object.hasOwn(models, ref) ? models[ref] : undefined;
     return m || undefined;
 }
-function modelBindingRefusal(seat, reason, message) {
+function modelBindingRefusal(field, reason, message) {
     const e = new Error(message);
     e.code = "config.unknown_role";
-    e.detail = { field: seat, reason };
+    e.detail = { field, reason };
     return e;
 }
+function isBindingObject(value) {
+    return (typeof value === "object" && value !== null) || typeof value === "function";
+}
 function bindingShown(value) {
     if (typeof value === "string")
         return JSON.stringify(value.length > 80 ? `${value.slice(0, 80)}…` : value);
@@ -19,15 +22,27 @@ function bindingShown(value) {
 function unknownModelRefRefusal(ref, seat) {
     return modelBindingRefusal(seat, "unknown_model_ref", `Unknown model ref ${bindingShown(ref)} in ${seat}. Provide it in RunnerDeps.models or pass a Model object.`);
 }
-export function resolveModel(ref, models) {
-    if (typeof ref !== "string") {
-        return ref;
+function modelOfBinding(value, models, seat, binds) {
+    assertModelBindingShape(value, seat, binds);
+    if (typeof value === "string") {
+        const held = catalogModel(value, models);
+        if (held === undefined)
+            throw unknownModelRefRefusal(value, seat);
+        return held;
     }
-    const m = catalogModel(ref, models);
-    if (!m) {
-        throw new Error(`Unknown model ref "${ref}". Provide it in RunnerDeps.models or pass a Model object.`);
+    return value;
+}
+function assertModelBindingShape(value, seat, binds) {
+    if (typeof value === "string")
+        return;
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        throw modelBindingRefusal(seat, "not_a_model_ref", `${seat} is ${bindingShown(value)}, not a model reference — ${binds}.`);
     }
-    return m;
+}
+const ROLE_BINDS = "a role binds a catalog model name or a Model object";
+const roleModelSeat = (named, seat) => (typeof named === "string" ? seat : `${seat}.model`);
+export function resolveModel(ref, models, seat = "model") {
+    return modelOfBinding(ref, models, seat, "a model is named by a catalog model name or a Model object");
 }
 export const DEFAULT_TIER_ORDER = ["ultra", "max", "pro", "flash", "lite"];
 export const CC_MODEL_TIER_ALIASES = {
@@ -53,17 +68,7 @@ export function expandTiers(models, tiers) {
         const b = Object.hasOwn(tiers, name) ? tiers[name] : undefined;
         if (b === undefined)
             return undefined;
-        const seat = `tiers.${name}`;
-        if (typeof b === "string") {
-            const held = catalogModel(b, models);
-            if (held === undefined)
-                throw unknownModelRefRefusal(b, seat);
-            return held;
-        }
-        if (typeof b !== "object" || b === null || Array.isArray(b)) {
-            throw modelBindingRefusal(seat, "not_a_model_ref", `${seat} is ${bindingShown(b)}, not a model reference — a tier binds a catalog model name or a Model object.`);
-        }
-        return b;
+        return modelOfBinding(b, models, `tiers.${name}`, "a tier binds a catalog model name or a Model object");
     };
     const ownKey = (k) => models !== undefined && Object.hasOwn(models, k) && Boolean(models[k]);
     const landing = (t, self) => {
@@ -162,13 +167,13 @@ const FALLBACK = {
     consolidate: ["summarize"],
 };
 function specParts(s, seat = "a role seat") {
-    if (s == null) {
+    if (s === undefined) {
         return {};
     }
     if (typeof s === "string") {
         return { model: s };
     }
-    if (typeof s !== "object" && typeof s !== "function") {
+    if (!isBindingObject(s)) {
         throw modelBindingRefusal(seat, "not_a_model_ref", `${seat} is ${bindingShown(s)}, not a model reference — a role binds a catalog model name, a Model object or a { model, select, thinking, systemPrompt } record.`);
     }
     if ("id" in s && "api" in s) {
@@ -182,7 +187,7 @@ export function roleSpecNamesModel(spec) {
     return parts.model !== undefined || parts.select !== undefined;
 }
 function toConfig(s) {
-    if (s == null) {
+    if (s === undefined) {
         return undefined;
     }
     if (typeof s === "string" || ("id" in s && "api" in s)) {
@@ -205,19 +210,25 @@ function mergeRoleSpec(base, over) {
         systemPrompt: o.systemPrompt ?? b.systemPrompt,
     };
 }
-function assertKnownRole(word, seat) {
+function assertKnownRole(word, field, ofKey = false) {
     if (typeof word === "string" && MODEL_ROLES.includes(word))
         return;
     const shown = typeof word === "string" ? JSON.stringify(word).slice(0, 80) : `<${word === null ? "null" : typeof word}>`;
-    const e = new Error(`${seat} names the model role ${shown}, which is not one of ${MODEL_ROLES.join(" / ")} — a word outside the vocabulary binds nothing and resolves nothing; bind the model on one of these roles, or name it on TaskSpec.model`);
-    e.code = "config.unknown_role";
-    throw e;
+    throw modelBindingRefusal(field, "unknown_role_word", `${ofKey ? `${field} key` : field} names the model role ${shown}, which is not one of ${MODEL_ROLES.join(" / ")} — a word outside the vocabulary binds nothing and resolves nothing; bind the model on one of these roles, or name it on TaskSpec.model`);
 }
 function mergeRoles(base, over) {
     for (const key of Object.keys(base ?? {}))
-        assertKnownRole(key, "RunnerDeps.roles key");
+        assertKnownRole(key, "RunnerDeps.roles", true);
     for (const key of Object.keys(over ?? {}))
-        assertKnownRole(key, "TaskSpec.roles key");
+        assertKnownRole(key, "TaskSpec.roles", true);
+    for (const roles of [base, over]) {
+        for (const [key, value] of Object.entries(roles ?? {})) {
+            const seat = `roles.${key}`;
+            const named = specParts(value, seat).model;
+            if (named !== undefined)
+                assertModelBindingShape(named, roleModelSeat(named, seat), ROLE_BINDS);
+        }
+    }
     const out = { ...base };
     for (const role of Object.keys(over ?? {})) {
         out[role] = mergeRoleSpec(base?.[role], over?.[role]);
@@ -225,8 +236,8 @@ function mergeRoles(base, over) {
     return out;
 }
 function partsModel(parts, models, seat = "a role seat") {
-    if (parts.model) {
-        return resolveModel(parts.model, models);
+    if (parts.model !== undefined) {
+        return modelOfBinding(parts.model, models, roleModelSeat(parts.model, seat), ROLE_BINDS);
     }
     if (parts.select) {
         const needs = parts.select.needs;
@@ -239,12 +250,12 @@ function partsModel(parts, models, seat = "a role seat") {
     return undefined;
 }
 export function resolveTaskModel(spec, deps) {
-    const start = spec.modelRole ?? "default";
+    const start = spec.modelRole === undefined ? "default" : spec.modelRole;
     assertKnownRole(start, "modelRole");
-    if (spec.model) {
+    if (spec.model !== undefined) {
         const startParts = specParts(mergeRoles(deps.roles, spec.roles)[start], `roles.${start}`);
         return {
-            model: resolveModel(spec.model, deps.models),
+            model: resolveModel(spec.model, deps.models, "TaskSpec.model"),
             modelRef: spec.model,
             thinking: spec.thinking ?? startParts.thinking,
             systemPrompt: startParts.systemPrompt,
@@ -267,15 +278,5 @@ export function roleModelIfSet(role, spec, deps) {
     const merged = mergeRoles(deps.roles, spec.roles);
     const seat = `roles.${role}`;
     const parts = specParts(merged[role], seat);
-    const named = parts.model;
-    if (named) {
-        if (typeof named === "string") {
-            if (catalogModel(named, deps.models) === undefined)
-                throw unknownModelRefRefusal(named, seat);
-        }
-        else if (typeof named !== "object" || Array.isArray(named)) {
-            throw modelBindingRefusal(seat, "not_a_model_ref", `${seat}.model is ${bindingShown(named)}, not a model reference — a role binds a catalog model name or a Model object.`);
-        }
-    }
     return partsModel(parts, deps.models, seat) ?? roleTierModel(role, deps.models);
 }

package/dist/core/rule-offer-read.d.ts

@@ -0,0 +1,53 @@
+/**
+ * The read-back judge of a stored rule-offer list: the {@link RuleOffer} array core mints beside an approval
+ * (`AskRequest.ruleOffers`, a parked row's `pendingAction.ruleOffers`). Core mints the shape, so its reading lives
+ * here; a backend or a surface that reads the list back calls {@link readRuleOffers} instead of keeping a schema of
+ * its own. Display caps (how many offers, members or detail rows a surface shows) stay with the surface.
+ */
+import { type RuleOffer } from "./permission-rule-model.js";
+/**
+ * Why a stored rule-offer value, or one element of it, is not read:
+ *  · `not_an_array` — the value itself (present, and not a list): no element is read;
+ *  · `unknown_word` — a closed-set member holds a word this engine does not know: the offer `kind`, a batch member's
+ *    `kind`, a `match` (a newer minter, or another writer);
+ *  · `malformed` — not an object, a member missing or of the wrong type, a batch with no members, an uncovered count
+ *    that is not a non-negative safe integer.
+ * The first defect in reading order names the element's problem.
+ */
+export declare const RULE_OFFER_SHAPE_PROBLEMS: readonly ["not_an_array", "unknown_word", "malformed"];
+export type RuleOfferShapeProblem = (typeof RULE_OFFER_SHAPE_PROBLEMS)[number];
+/** One element read. `index` is its position in the stored list — the selection key a card and its redemption keep. */
+export interface RuleOfferRead {
+    readonly index: number;
+    /** A fresh object holding only the members the type declares (additive members the minter wrote are not copied). */
+    readonly offer: RuleOffer;
+    /** Present when the batch's `uncoveredDetail` seat was not one well-formed row per counted segment and was left out
+     *  (the count is the truth source and an absent seat claims nothing); the caller owes that loss a disclosure. */
+    readonly uncoveredDetailDropped?: true;
+    /** Present when at least one batch member was read through the kind-less stored form (no `kind`, the four command
+     *  text members). A backend counts these to know whether its rows still carry the form that retirement line
+     *  RL-2164-kindless-batch-member waits on. */
+    readonly kindlessForm?: true;
+}
+/** One element not read, and why. The rest of the list is read regardless. */
+export interface RuleOfferDropped {
+    readonly index: number;
+    readonly problem: Exclude<RuleOfferShapeProblem, "not_an_array">;
+}
+/** {@link readRuleOffers}' answer. */
+export type RuleOffersReading = {
+    readonly offers: readonly RuleOfferRead[];
+    readonly dropped: readonly RuleOfferDropped[];
+} | {
+    readonly problem: "not_an_array";
+};
+/**
+ * Read a stored rule-offer list. `undefined` (the member absent) reads as no offers; any other non-list is
+ * `not_an_array`. Each element is judged alone and keeps its original index: an element that is not an offer this
+ * engine reads is dropped WHOLE (a batch with one unreadable member is dropped, never shortened — a conjunction one
+ * member short would render "yes to N" as "yes to N−1") and its siblings stand. Every member is read once.
+ * The input domain is a decoded JSON value or a list core minted: a value carrying accessors or a Proxy is outside it,
+ * and such a value may be refused as malformed or may throw while it is read. A record is a plain one
+ * ({@link isPlainRecord}, the reading the risk-descriptor axes take too).
+ */
+export declare function readRuleOffers(raw: unknown): RuleOffersReading;

package/dist/core/rule-offer-read.js

@@ -0,0 +1,146 @@
+import { PERSISTED_RULE_MATCHES, RULE_OFFER_BATCH_MEMBER_KINDS, RULE_OFFER_KINDS, UNCOVERED_SEGMENT_REASONS, } from "./permission-rule-model.js";
+import { isPlainRecord } from "./checkpoint-store.js";
+export const RULE_OFFER_SHAPE_PROBLEMS = Object.freeze(["not_an_array", "unknown_word", "malformed"]);
+const MALFORMED = Object.freeze({ problem: "malformed" });
+const UNKNOWN_WORD = Object.freeze({ problem: "unknown_word" });
+export function readRuleOffers(raw) {
+    if (raw === undefined)
+        return { offers: [], dropped: [] };
+    if (!Array.isArray(raw))
+        return { problem: "not_an_array" };
+    const offers = [];
+    const dropped = [];
+    const length = raw.length;
+    for (let index = 0; index < length; index++) {
+        const verdict = readOfferElement(raw[index]);
+        if ("problem" in verdict)
+            dropped.push({ index, problem: verdict.problem });
+        else
+            offers.push({ index, ...verdict });
+    }
+    return { offers, dropped };
+}
+function wordOf(value, words) {
+    if (typeof value !== "string")
+        return MALFORMED;
+    return words.some((w) => w === value) ? value : UNKNOWN_WORD;
+}
+function readOfferElement(value) {
+    if (!isPlainRecord(value))
+        return MALFORMED;
+    const kind = wordOf(value.kind, RULE_OFFER_KINDS);
+    if (typeof kind !== "string")
+        return kind;
+    switch (kind) {
+        case "single": {
+            const rule = value.rule;
+            const match = wordOf(value.match, PERSISTED_RULE_MATCHES);
+            const command = value.command;
+            if (typeof rule !== "string")
+                return MALFORMED;
+            if (typeof match !== "string")
+                return match;
+            if (typeof command !== "string")
+                return MALFORMED;
+            return { offer: { kind: "single", rule, match, command } };
+        }
+        case "batch":
+            return readBatch(value);
+        default: {
+            const unhandled = kind;
+            return unhandled;
+        }
+    }
+}
+function readBatch(value) {
+    const rules = value.rules;
+    const count = value.uncoveredSegments;
+    const detail = value.uncoveredDetail;
+    if (!Array.isArray(rules))
+        return MALFORMED;
+    const length = rules.length;
+    if (length === 0)
+        return MALFORMED;
+    const members = [];
+    let kindless = false;
+    for (let i = 0; i < length; i++) {
+        const verdict = readBatchMember(rules[i]);
+        if ("problem" in verdict)
+            return verdict;
+        members.push(verdict.member);
+        if (verdict.kindlessForm === true)
+            kindless = true;
+    }
+    if (typeof count !== "number" || !Number.isSafeInteger(count) || count < 0)
+        return MALFORMED;
+    const offer = { kind: "batch", rules: members, uncoveredSegments: count };
+    const marks = kindless ? { kindlessForm: true } : {};
+    if (detail === undefined)
+        return { offer, ...marks };
+    const rows = detailRowsOf(detail, count);
+    return rows !== undefined ? { offer: { ...offer, uncoveredDetail: rows }, ...marks } : { offer, uncoveredDetailDropped: true, ...marks };
+}
+function readBatchMember(value) {
+    if (!isPlainRecord(value))
+        return MALFORMED;
+    if (!("kind" in value))
+        return readKindlessBatchMember(value);
+    const kind = wordOf(value.kind, RULE_OFFER_BATCH_MEMBER_KINDS);
+    if (typeof kind !== "string")
+        return kind;
+    switch (kind) {
+        case "command":
+            return commandMember(value.rule, value.match, value.command, value.segment);
+        case "directoryRead": {
+            const rule = value.rule;
+            const directory = value.directory;
+            const segment = value.segment;
+            if (typeof rule !== "string" || typeof directory !== "string" || typeof segment !== "string")
+                return MALFORMED;
+            return { member: { kind: "directoryRead", rule, directory, segment } };
+        }
+        default: {
+            const unhandled = kind;
+            return unhandled;
+        }
+    }
+}
+function readKindlessBatchMember(value) {
+    const rule = value.rule;
+    const match = value.match;
+    const command = value.command;
+    const segment = value.segment;
+    if (typeof rule !== "string" || typeof match !== "string" || typeof command !== "string" || typeof segment !== "string")
+        return MALFORMED;
+    const verdict = commandMember(rule, match, command, segment);
+    return "problem" in verdict ? verdict : { ...verdict, kindlessForm: true };
+}
+function commandMember(rule, rawMatch, command, segment) {
+    if (typeof rule !== "string")
+        return MALFORMED;
+    const match = wordOf(rawMatch, PERSISTED_RULE_MATCHES);
+    if (typeof match !== "string")
+        return match;
+    if (typeof command !== "string" || typeof segment !== "string")
+        return MALFORMED;
+    return { member: { kind: "command", rule, match, command, segment } };
+}
+function detailRowsOf(detail, count) {
+    if (!Array.isArray(detail))
+        return undefined;
+    const length = detail.length;
+    if (length !== count)
+        return undefined;
+    const rows = [];
+    for (let i = 0; i < length; i++) {
+        const row = detail[i];
+        if (!isPlainRecord(row))
+            return undefined;
+        const segment = row.segment;
+        const reason = wordOf(row.reason, UNCOVERED_SEGMENT_REASONS);
+        if (typeof segment !== "string" || typeof reason !== "string")
+            return undefined;
+        rows.push({ segment, reason });
+    }
+    return rows;
+}

package/dist/core/rule-owner.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Who a permission-rule bucket belongs to: the owner type, its discriminant words, the one reading of an owner from a
+ * value the engine did not just build, and the one equality between two owners.
+ *
+ * The faces that read an owner out of data — the two adoption markers read back from disk, the two adoption entries'
+ * source, a stored approval record's identity and the consent entries' `owner` option — read it through
+ * {@link readRuleOwner}, so the source an adoption entry writes into its marker is one that marker's reader reads back.
+ * Its one run-time import is the import-free record judge — the root adoption marker reader, which every file store
+ * loads, depends on this module and is kept free of the rule store's own imports.
+ */
+import type { AssertAllKeysHandled } from "./ask-origin.js";
+/**
+ * Who a rule bucket belongs to, as a STRUCTURAL position.
+ *
+ * Identity absence is spelled as a distinct union member, never as a sentinel string flowing through
+ * `forPrincipal` — every consumer of a principal string is an identity surface, and a made-up name on an
+ * identity surface is indistinguishable from a real one downstream. Cloud sync and cloud tickets accept
+ * ONLY the `principal` kind: syncing is an authenticated act, and a local-owner bucket has no cloud home
+ * until it is adopted (`adoptFilePermissionRuleStore`).
+ */
+export type RuleOwner = {
+    kind: "principal";
+    principal: string;
+} | {
+    kind: "local-owner";
+};
+/** The owner discriminants as a value: the `kind` words of {@link RuleOwner}, both directions fenced at compile time
+ *  ({@link RuleOwnerKindsCoverEveryArm} / {@link RuleOwnerArmsCoverEveryKind}). */
+export declare const RULE_OWNER_KINDS: readonly ["principal", "local-owner"];
+/** Compile fence: an arm whose `kind` is not in {@link RULE_OWNER_KINDS} turns the argument into that word. */
+export type RuleOwnerKindsCoverEveryArm = AssertAllKeysHandled<Exclude<RuleOwner["kind"], (typeof RULE_OWNER_KINDS)[number]>>;
+/** Compile fence, the other direction: a word in {@link RULE_OWNER_KINDS} that no arm carries. */
+export type RuleOwnerArmsCoverEveryKind = AssertAllKeysHandled<Exclude<(typeof RULE_OWNER_KINDS)[number], RuleOwner["kind"]>>;
+/** Do two owners name the same bucket? */
+export declare function sameRuleOwner(a: RuleOwner, b: RuleOwner): boolean;
+/**
+ * Read an owner from a value the engine did not just build, or `undefined` when it is not one: not a plain record (an
+ * object whose prototype is `Object.prototype` or none, so no member comes from a prototype it was given), a `kind`
+ * outside {@link RULE_OWNER_KINDS}, or a `principal` arm whose name is not a string with a non-whitespace character (an
+ * identity-less bucket is the `local-owner` kind, never a blank name). Fail-closed: a caller treats `undefined` as
+ * "owns nothing" or refuses — never as either arm. The answer is a fresh object holding only the members the type
+ * declares; `kind` and `principal` are each read once.
+ */
+export declare function readRuleOwner(raw: unknown): RuleOwner | undefined;
+/** An owner as an operator's sentence names it: `principal "<name>"`, or `the local owner`. */
+export declare function ruleOwnerText(owner: RuleOwner): string;

package/dist/core/rule-owner.js

@@ -0,0 +1,28 @@
+import { isPlainRecord } from "./mods/kernel/receive.js";
+export const RULE_OWNER_KINDS = Object.freeze(["principal", "local-owner"]);
+export function sameRuleOwner(a, b) {
+    return a.kind === "principal" ? b.kind === "principal" && a.principal === b.principal : b.kind === "local-owner";
+}
+export function readRuleOwner(raw) {
+    if (!isPlainRecord(raw))
+        return undefined;
+    const kind = raw.kind;
+    const word = RULE_OWNER_KINDS.find((k) => k === kind);
+    if (word === undefined)
+        return undefined;
+    switch (word) {
+        case "local-owner":
+            return { kind: "local-owner" };
+        case "principal": {
+            const principal = raw.principal;
+            return typeof principal === "string" && principal.trim() !== "" ? { kind: "principal", principal } : undefined;
+        }
+        default: {
+            const unhandled = word;
+            return unhandled;
+        }
+    }
+}
+export function ruleOwnerText(owner) {
+    return owner.kind === "principal" ? `principal "${owner.principal}"` : "the local owner";
+}

package/dist/core/runner/advisor-instructions.d.ts

@@ -0,0 +1,70 @@
+/**
+ * The advisor tool's instructions to the model — the reference's text, verbatim — its two short forms (a re-attach after a
+ * withdrawal, and the withdrawal), the one transition that says which a leg owes, and the leg's seat for them. The frame is
+ * the `advisor_tool` attachment kind: it rides a fresh leg's first request, and a compaction inside a leg that mounts the
+ * tool restates the full text right after it lands. Model lane only: no `steering_injected` echo.
+ */
+import type { AnnouncedAdvisorState, AnnouncedListingSnapshotInput } from "../../internal/harness.js";
+import type { PostureFrameRef } from "../auto-mode-directive.js";
+import type { StoredSession } from "../session.js";
+import type { FrameReceiptLedger } from "./contracts.js";
+export declare const ADVISOR_TOOL_INSTRUCTIONS = "# Advisor Tool\n\nYou have access to an `advisor` tool backed by a stronger reviewer model. It takes NO parameters -- when you call advisor(), your entire conversation history is automatically forwarded. They see the task, every tool call you've made, every result you've seen.\n\nCall advisor BEFORE substantive work -- before writing, before committing to an interpretation, before building on an assumption. If the task requires orientation first (finding files, fetching a source, seeing what's there), do that, then call advisor. Orientation is not substantive work. Writing, editing, and declaring an answer are.\n\nAlso call advisor:\n- When you believe the task is complete. BEFORE this call, make your deliverable durable: write the file, save the result, commit the change. The advisor call takes time; if the session ends during it, a durable result persists and an unwritten one doesn't.\n- When stuck -- errors recurring, approach not converging, results that don't fit.\n- When considering a change of approach.\n\nOn tasks longer than a few steps, call advisor at least once before committing to an approach and once before declaring done. On short reactive tasks where the next action is dictated by tool output you just read, you don't need to keep calling -- the advisor adds most of its value on the first call, before the approach crystallizes.\n\nGive the advice serious weight. If you follow a step and it fails empirically, or you have primary-source evidence that contradicts a specific claim (the file says X, the paper states Y), adapt. A passing self-test is not evidence the advice is wrong -- it's evidence your test doesn't check what the advice is checking.\n\nIf you've already retrieved data pointing one way and the advisor points another: don't silently switch. Surface the conflict in one more advisor call -- \"I found X, you suggest Y, which constraint breaks the tie?\" The advisor saw your evidence but may have underweighted it; a reconcile call is cheaper than committing to the wrong branch.";
+export declare const ADVISOR_TOOL_ABBREVIATED = "The advisor tool is available; the advisor instructions announced earlier apply.";
+export declare const ADVISOR_TOOL_REMOVED = "The advisor tool is no longer available; disregard the earlier advisor instructions.";
+/** What the model has been told about the advisor in the conversation's current segment (since the latest compaction): the session record's own word. */
+export type AdvisorInstructionState = AnnouncedAdvisorState["state"];
+/**
+ * The advisor instructions a leg owes, from what the model was told and whether the tool is mounted now: nothing told and
+ * mounted ⇒ the full text; told and not mounted ⇒ the withdrawal; withdrawn and mounted again ⇒ the short re-attach; every
+ * other pair owes nothing. `state` is what the model has been told once the frame is delivered.
+ */
+export declare function advisorInstructionFrame(told: AdvisorInstructionState | undefined, mounted: boolean): {
+    body: string;
+    state: AdvisorInstructionState;
+} | undefined;
+/** A leg's advisor-instructions seat: the frame its first request owes, the segment that was judged in, whether the tool is mounted. */
+export interface AdvisorInstructionSeat {
+    owed?: {
+        readonly body: string;
+        readonly state: AdvisorInstructionState;
+    };
+    readonly segment: string | null;
+    readonly mounted: boolean;
+}
+/** The owed frame as one engine-marked reminder — what a fresh leg's first message and a resumed leg's continuation both
+ *  carry — or `undefined` when nothing is owed. */
+export declare function advisorFrameText(prepared: {
+    readonly advisorInstruction?: AdvisorInstructionSeat;
+    readonly reminderMark: string;
+}): string | undefined;
+/** Register the owed frame's receipt on the message that carries it (`text`, the exact first text block): its commit
+ *  records what the model was told only once that message is in the transcript. Nothing owed ⇒ nothing registered. */
+export declare function registerAdvisorReceipt(prepared: {
+    readonly advisorInstruction?: AdvisorInstructionSeat;
+    readonly announcedListingsRef: AnnouncedListingSnapshotInput;
+    readonly frameReceipts: FrameReceiptLedger;
+}, text: string): void;
+/** The owed frame was delivered (its carrying message is in the transcript): what the model was told is recorded for the
+ *  segment it was told in, and the snapshot write is parked like every listing commit's. */
+export declare function settleAdvisorInstruction(prepared: {
+    readonly advisorInstruction?: AdvisorInstructionSeat;
+    readonly announcedListingsRef: AnnouncedListingSnapshotInput;
+    readonly frameReceipts: {
+        listingSnapshotOwed: boolean;
+    };
+}): void;
+/**
+ * A compaction landed on a leg that mounts the advisor: the full instructions it summarized away are appended to the
+ * transcript as one engine-minted message, before any reader of the new baseline — the posture's compaction rule, halt
+ * included (no engine message enters the transcript ahead of a person's next words). The record is left as it was: it names
+ * the segment before this compaction, so the next leg tells the model again (a duplicate, never a gap). Never throws.
+ */
+export declare function appendAdvisorRestate(prepared: {
+    readonly advisorInstruction?: AdvisorInstructionSeat;
+    readonly reminderMark: string;
+    readonly session: Pick<StoredSession, "appendMessage">;
+    readonly batchHaltRef: {
+        readonly current?: unknown;
+    };
+    readonly postureFrameRef: Pick<PostureFrameRef, "report">;
+}): Promise<void>;

package/dist/core/runner/advisor-instructions.js

@@ -0,0 +1,61 @@
+import { mintSystemReminder } from "../reminder-mint.js";
+import { thrownText } from "../thrown-value.js";
+export const ADVISOR_TOOL_INSTRUCTIONS = `# Advisor Tool
+
+You have access to an \`advisor\` tool backed by a stronger reviewer model. It takes NO parameters -- when you call advisor(), your entire conversation history is automatically forwarded. They see the task, every tool call you've made, every result you've seen.
+
+Call advisor BEFORE substantive work -- before writing, before committing to an interpretation, before building on an assumption. If the task requires orientation first (finding files, fetching a source, seeing what's there), do that, then call advisor. Orientation is not substantive work. Writing, editing, and declaring an answer are.
+
+Also call advisor:
+- When you believe the task is complete. BEFORE this call, make your deliverable durable: write the file, save the result, commit the change. The advisor call takes time; if the session ends during it, a durable result persists and an unwritten one doesn't.
+- When stuck -- errors recurring, approach not converging, results that don't fit.
+- When considering a change of approach.
+
+On tasks longer than a few steps, call advisor at least once before committing to an approach and once before declaring done. On short reactive tasks where the next action is dictated by tool output you just read, you don't need to keep calling -- the advisor adds most of its value on the first call, before the approach crystallizes.
+
+Give the advice serious weight. If you follow a step and it fails empirically, or you have primary-source evidence that contradicts a specific claim (the file says X, the paper states Y), adapt. A passing self-test is not evidence the advice is wrong -- it's evidence your test doesn't check what the advice is checking.
+
+If you've already retrieved data pointing one way and the advisor points another: don't silently switch. Surface the conflict in one more advisor call -- "I found X, you suggest Y, which constraint breaks the tie?" The advisor saw your evidence but may have underweighted it; a reconcile call is cheaper than committing to the wrong branch.`;
+export const ADVISOR_TOOL_ABBREVIATED = "The advisor tool is available; the advisor instructions announced earlier apply.";
+export const ADVISOR_TOOL_REMOVED = "The advisor tool is no longer available; disregard the earlier advisor instructions.";
+export function advisorInstructionFrame(told, mounted) {
+    if (mounted && told === undefined)
+        return { body: ADVISOR_TOOL_INSTRUCTIONS, state: "announced" };
+    if (mounted && told === "withdrawn")
+        return { body: ADVISOR_TOOL_ABBREVIATED, state: "announced" };
+    if (!mounted && told === "announced")
+        return { body: ADVISOR_TOOL_REMOVED, state: "withdrawn" };
+    return undefined;
+}
+export function advisorFrameText(prepared) {
+    const owed = prepared.advisorInstruction?.owed;
+    return owed === undefined ? undefined : mintSystemReminder(owed.body, prepared.reminderMark);
+}
+export function registerAdvisorReceipt(prepared, text) {
+    if (prepared.advisorInstruction?.owed !== undefined)
+        prepared.frameReceipts.pending.push({ source: "advisor_tool", text, commit: () => settleAdvisorInstruction(prepared) });
+}
+export function settleAdvisorInstruction(prepared) {
+    const seat = prepared.advisorInstruction;
+    const owed = seat?.owed;
+    if (seat === undefined || owed === undefined)
+        return;
+    seat.owed = undefined;
+    prepared.announcedListingsRef.advisor = { state: owed.state, segment: seat.segment };
+    prepared.frameReceipts.listingSnapshotOwed = true;
+}
+export async function appendAdvisorRestate(prepared) {
+    if (prepared.advisorInstruction?.mounted !== true || prepared.batchHaltRef.current !== undefined)
+        return;
+    const text = mintSystemReminder(ADVISOR_TOOL_INSTRUCTIONS, prepared.reminderMark);
+    try {
+        await prepared.session.appendMessage({ role: "user", content: [{ type: "text", text }], timestamp: Date.now(), engineMinted: true });
+    }
+    catch (err) {
+        try {
+            prepared.postureFrameRef.report?.(new Error(`the advisor instructions could not be restated after compaction (the next leg states them): ${thrownText(err)}`));
+        }
+        catch {
+        }
+    }
+}

package/dist/core/runner/advisor-tool.d.ts

@@ -0,0 +1,33 @@
+import type { AgentTool, SessionTreeEntry } from "../../internal/harness-types.js";
+import type { Model } from "../../internal/llm.js";
+import { type AdvisorFailure, type AdvisorOutcome } from "../advisor-verdict.js";
+import type { CompactionForkContext } from "../auto-compaction.js";
+import { type SideQueryResult } from "../side-query.js";
+import type { Brain, TaskSpec } from "../types.js";
+/** The advisor's own system prompt (the agent's system prompt follows it, marked as context). */
+export declare const ADVISOR_SYSTEM_PROMPT = "You are the advisor: a stronger reviewer model consulted by an agent in the middle of its task. Above is the agent's conversation as it stood in the agent's last request \u2014 its task, every tool call it made and every result it saw \u2014 ending at the point where it asked for advice.\n\nReply in plain text only. Do not call tools: any tool call you make is discarded and counts as no answer. Be concrete and short: name the decision the agent is facing, say what you would do and why, point at the specific evidence in the conversation that supports it, and flag anything the agent has assumed without checking. If the agent asked before declaring the task done, review the deliverable against the task as stated and list what is missing or wrong. If something you need is not in the conversation, say what is missing and what the agent should check first \u2014 that is still guidance.";
+/** The closing result the projection ends on: the asking call is answered, so both wire protocols take the list. */
+export declare const ADVISOR_HANDOFF = "You are the advisor now. Review everything above and reply with your guidance.";
+/** Everything one leg's advisor needs: the advisor model, the lane's accounted brain, and the leg's own readers. */
+export interface AdvisorSeat {
+    readonly model: Model;
+    readonly brain: Brain;
+    /** The request the main lane last sent on this leg (the engine-level context, before provider serialization). */
+    readonly lastSentRequest: () => CompactionForkContext | undefined;
+    readonly readBranch: () => Promise<ReadonlyArray<SessionTreeEntry>>;
+    readonly getApiKeyAndHeaders: TaskSpec["getApiKeyAndHeaders"];
+    /** Marks the run's totals a lower bound: a thrown request spent an amount nobody learned. */
+    readonly markUsageUnknown: () => void;
+}
+/** The `tool_end.structured` card of one advisor call. */
+export interface AdvisorCard extends AdvisorFailure {
+    readonly type: "advisor";
+    readonly outcome: AdvisorOutcome;
+    readonly model: string;
+    readonly servedModel?: string;
+    readonly stopReason?: string;
+    readonly hold?: true;
+    readonly usage?: SideQueryResult["usage"];
+}
+/** The leg's `advisor` tool over its seat; its label is the advisor model's id (it rides `tool_start` / `tool_end`). */
+export declare function createAdvisorTool(seat: AdvisorSeat): AgentTool;