@basein/runner 0.3.17 → 0.3.18

package/dist/control/server.js

@@ -26,19 +26,20 @@
 import { createServer } from "node:http";
 import { createHash, randomBytes, randomUUID } from "node:crypto";
 import { statSync } from "node:fs";
-import { join } from "node:path";
+import { join, resolve as resolvePath } from "node:path";
 import { BIR_CALL_ID, fingerprint, newCallId, parseQualifiedName, qualifyToolName, } from "./correlation.js";
 import { StepIndexAllocator } from "./ordering.js";
 import { pidAlive } from "./discovery.js";
 import { pinCompatible } from "./pin-guard.js";
-import { contextForToolUse, intentForToolUse, markTranscriptUsage, recentToolResults, settledLastAssistantText, settledTextAfterToolUse, thinkingForToolUse, usageSince, } from "./transcript.js";
+import { agentDayOf, contextForToolUse, intentForToolUse, markTranscriptUsage, recentToolResults, settledLastAssistantText, settledTextAfterToolUse, thinkingForToolUse, usageSince, } from "./transcript.js";
 import { isHousekeepingCall } from "../record/housekeeping.js";
 import { asSent, userText } from "../record/prompt-text.js";
 import { redact, redactText } from "../record/redact.js";
 import { DEFAULT_MAX_STRING_BYTES, serializeCapped, truncateString, truncateStrings, } from "../record/truncate.js";
 import { StepQueue } from "../record/queue.js";
-import { NullRecorder, isIntentMatcher, isMatchAware, isRecorderHealthReporter, isRunCreationAware, isScenarioReporter, isServiceProber, } from "../record/recorder.js";
-import { ReplayController, POLL_HOLD_MS, } from "../replay/controller.js";
+import { NullRecorder, isAttentionReader, isIntentMatcher, isMatchAware, isRecorderHealthReporter, isRunCreationAware, isScenarioDisputer, isScenarioReporter, isServiceProber, isToolListReporter, } from "../record/recorder.js";
+import { ReplayController, POLL_HOLD_MS, REPORT_TOOL_NAME, } from "../replay/controller.js";
+import { localDay } from "../replay/derive.js";
 import { calculateCostUsd, hasModelPricing } from "../replay/pricing.js";
 import { logDetail, logLine, logOnce, errText } from "../util/log.js";
 import { journal } from "../util/journal.js";
@@ -48,7 +49,7 @@ import { awaitWithin, serviceHealth } from "../util/service-health.js";
 import { offSource } from "../util/off-switch.js";
 import { claudeJsonPath, resolveServers } from "../config/resolve.js";
 import { SCENARIO_SERVER_KEY, isScenarioServer, projectToken, readSidecar } from "../config/generate.js";
-import { installedPath } from "./paths.js";
+import { controlKey, installedPath } from "./paths.js";
 /** How long a `/tool/post` waits for the proxy's own report before recording its own view. */
 const PROXY_REPORT_GRACE_MS = 1_500;
 /**
@@ -149,6 +150,218 @@ const DELIVERY_TOOL_REFRESH_MS = 5 * 60_000;
  * is never near this; a process that died without a word is caught by its pid.
  */
 const DELIVERY_HELLO_TTL_MS = 30 * 60_000;
+/** A tool list the service took is sent again after this long (AC12): one it lost comes back. */
+const TOOL_LIST_RESEND_MS = 6 * 60 * 60_000;
+/** One whose send failed is not sent again sooner than this: a refusing service is not sent it at every session start. */
+const TOOL_LIST_RETRY_MS = 10 * 60_000;
+/** What the service keeps of a list (its agentTools.ts): beyond it a list would only be cut there, or refused. */
+const TOOL_LIST_MAX = 300;
+const TOOL_DESCRIPTION_MAX = 4_000;
+const TOOL_SCHEMA_MAX = 16_000;
+const TOOL_NAME_MAX = 300;
+/** One send's body at most: the service takes up to 5 MB. */
+const TOOL_LIST_BODY_MAX = 2_000_000;
+/** Every string of a schema with secret-shaped runs taken out. Keys stay: a property named `token` is no secret. */
+function redactStrings(value, depth = 0) {
+    if (depth > 24)
+        return null;
+    if (typeof value === "string")
+        return redactText(value);
+    if (Array.isArray(value))
+        return value.map((v) => redactStrings(v, depth + 1));
+    if (value && typeof value === "object") {
+        const out = {};
+        for (const [k, v] of Object.entries(value)) {
+            Object.defineProperty(out, k, { value: redactStrings(v, depth + 1), enumerable: true, writable: true, configurable: true });
+        }
+        return out;
+    }
+    return value;
+}
+/** A tool's `annotations.title`, at most this long. */
+const TOOL_TITLE_MAX = 200;
+/** The four hints of MCP `annotations` the service reads, all booleans. */
+const TOOL_HINTS = ["readOnlyHint", "destructiveHint", "idempotentHint", "openWorldHint"];
+/**
+ * What a server says of one tool (MCP `annotations`; the service's review of
+ * calcscenarioautocorrect.md, items 4 and 16), as the service takes it: its
+ * `title`, redacted as a description is and cut to {@link TOOL_TITLE_MAX},
+ * and the four hints when each is a boolean. Anything else a server put there
+ * is dropped; undefined when nothing is left.
+ */
+function annotationsOf(raw) {
+    if (!raw || typeof raw !== "object" || Array.isArray(raw))
+        return undefined;
+    const a = raw;
+    const out = {};
+    if (typeof a.title === "string" && a.title.trim())
+        out.title = redactText(a.title.trim()).slice(0, TOOL_TITLE_MAX);
+    for (const hint of TOOL_HINTS) {
+        if (typeof a[hint] === "boolean")
+            out[hint] = a[hint];
+    }
+    return Object.keys(out).length > 0 ? out : undefined;
+}
+/**
+ * The project a run or a tool list belongs to (the service's review of
+ * calcscenarioautocorrect.md, item 16): the first 16 hex characters of the
+ * sha256 of its folder, made absolute and — on Windows — lower-cased with
+ * forward slashes, as the discovery file's key is (paths.ts, `controlKey`).
+ * The service only compares it, so a plan's recording finds its own
+ * project's tools and never another project's server of the same name.
+ */
+export function projectKey(dir) {
+    return controlKey(resolvePath(dir));
+}
+/**
+ * The plans that need their owner are asked of the service at most this
+ * often per account (`GET /scenarios/attention`, review item 8): a session
+ * start, a `/clear` and a resume each show the line, and none of them waits
+ * on the service again within it.
+ */
+const ATTENTION_CACHE_MS = 10 * 60_000;
+/** How long a session start waits for that answer. A slower one only fills the cache for the next. */
+const ATTENTION_WAIT_MS = 1_500;
+/**
+ * How long "nothing can be said" is kept instead — no answer, a failure, a
+ * service failing just then, an older one: a minute, so a session start
+ * during a short outage does not keep the line from the next ten minutes'.
+ */
+const ATTENTION_RETRY_MS = 60_000;
+/** A `report_wrong_result` call's `PreToolUse` is matched to its report for this long. */
+const REPORT_CALL_TTL_MS = 10 * 60_000;
+/** Without such a match, the one session whose latest plan ran this recently is the one meant. */
+const REPORT_FALLBACK_MS = 30 * 60_000;
+/** What the agent may say a replay got wrong, in characters. */
+const REPORT_REASON_MAX = 2_000;
+/** Why a plan is held, in the words of the session-start line. A correction waiting says that instead. */
+const HELD_WHY = {
+    checking: ", while its result is checked",
+    rejected: ", the agent did not take its result",
+    rejected_again: ", the agent did not take its result again",
+    verifying: ", until the agent's next run checks its correction",
+    verify_failed: ", its correction did not match the agent's run",
+    verify_stale: ", its correction is still not checked",
+};
+/** A plan's title as the line quotes it: one line, no quote marks or control characters, 80 characters at most. */
+function lineTitle(title) {
+    const one = title
+        .replace(/[\u0000-\u001f\u007f-\u009f\u200b-\u200f\u202a-\u202e\u2066-\u2069]/g, " ")
+        .replace(/["“”]/g, "'")
+        .replace(/\s+/g, " ")
+        .trim();
+    return one.length > 80 ? `${one.slice(0, 79)}…` : one;
+}
+/** A link the line may show: http(s), with nothing in it a terminal would read as anything but a link. */
+function lineUrl(url) {
+    const u = url.trim();
+    return u.length <= 500 && /^https?:\/\/[^\s"'<>\u0000-\u001f\u007f]+$/.test(u) ? u : undefined;
+}
+/** "3 days", "5 hours", "20 minutes" since `iso`; "" when it is not a time in the past. */
+function heldFor(iso, now) {
+    const ms = now - Date.parse(iso);
+    if (!Number.isFinite(ms) || ms < 0)
+        return "";
+    const minutes = Math.max(1, Math.floor(ms / 60_000));
+    if (minutes < 60)
+        return `${minutes} minute${minutes === 1 ? "" : "s"}`;
+    const hours = Math.floor(minutes / 60);
+    if (hours < 48)
+        return `${hours} hour${hours === 1 ? "" : "s"}`;
+    return `${Math.floor(hours / 24)} days`;
+}
+/**
+ * The one line a session start shows the person (review item 8): which plan
+ * waits, for how long, why, and where to look —
+ * `bir: a plan needs you — "Check engaged users and reassign leads" held for 3 days, a correction is waiting: <url>`
+ * — and with more than one, how many, and the first one's page. A plan that
+ * is not held, whose correction waits, says only that.
+ */
+export function attentionText(plans, now = Date.now()) {
+    const first = plans[0];
+    if (!first)
+        return undefined;
+    const url = lineUrl(first.url);
+    const where = url ? `: ${url}` : "";
+    if (plans.length > 1)
+        return `bir: ${plans.length} plans need you${where}`;
+    const title = lineTitle(first.title);
+    const name = title ? ` "${title}"` : "";
+    if (!first.heldSince) {
+        return first.correction === "proposed"
+            ? `bir: a plan needs you —${name} has a correction waiting${where}`
+            : `bir: a plan needs you —${name}${where}`;
+    }
+    const held = heldFor(first.heldSince, now);
+    const why = first.correction === "proposed" ? ", a correction is waiting" : first.reason ? HELD_WHY[first.reason] : "";
+    return `bir: a plan needs you —${name} held${held ? ` for ${held}` : ""}${why}${where}`;
+}
+/**
+ * A server's tool list as the service takes it (AC12): each tool's name as the
+ * agent calls it, its description and input schema with secret-shaped text
+ * taken out, and what its server says of it (`annotations`, review item 4),
+ * within what the service keeps; a body too large loses schemas first, from
+ * the end, then descriptions.
+ */
+function toolListForService(serverName, raw) {
+    const tools = [];
+    for (const item of raw) {
+        if (tools.length >= TOOL_LIST_MAX)
+            break;
+        if (!item || typeof item !== "object" || Array.isArray(item))
+            continue;
+        const t = item;
+        if (typeof t.name !== "string" || !t.name.trim())
+            continue;
+        const qualifiedName = qualifyToolName(serverName, t.name);
+        if (qualifiedName.length > TOOL_NAME_MAX)
+            continue;
+        const description = typeof t.description === "string" && t.description.trim()
+            ? redactText(t.description).slice(0, TOOL_DESCRIPTION_MAX)
+            : undefined;
+        let inputSchema;
+        if (t.inputSchema && typeof t.inputSchema === "object" && !Array.isArray(t.inputSchema)) {
+            const cleaned = redactStrings(t.inputSchema);
+            const text = JSON.stringify(cleaned);
+            if (text !== undefined && text.length <= TOOL_SCHEMA_MAX)
+                inputSchema = cleaned;
+        }
+        const annotations = annotationsOf(t.annotations);
+        tools.push({
+            name: t.name,
+            qualifiedName,
+            ...(description ? { description } : {}),
+            ...(inputSchema ? { inputSchema } : {}),
+            ...(annotations ? { annotations } : {}),
+        });
+    }
+    let size = JSON.stringify(tools).length;
+    for (let i = tools.length - 1; i >= 0 && size > TOOL_LIST_BODY_MAX; i--) {
+        const schema = tools[i].inputSchema;
+        if (schema) {
+            size -= JSON.stringify(schema).length;
+            delete tools[i].inputSchema;
+        }
+    }
+    for (let i = tools.length - 1; i >= 0 && size > TOOL_LIST_BODY_MAX; i--) {
+        const description = tools[i].description;
+        if (description) {
+            size -= description.length;
+            delete tools[i].description;
+        }
+    }
+    return tools;
+}
+/** The account a recorder sends for, when it says. */
+function accountOf(recorder) {
+    const fn = recorder.accountId;
+    try {
+        return typeof fn === "function" ? fn.call(recorder) : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
 /** At most this many `bir-scenario` processes are remembered, newest kept. */
 const DELIVERY_HELLO_MAX = 256;
 /*
@@ -263,6 +476,29 @@ function positiveEnv(name, fallback) {
     const n = Number(process.env[name]);
     return Number.isFinite(n) && n > 0 ? n : fallback;
 }
+/**
+ * A recorded row's metadata, with only what it has (review item 7): a plan
+ * that pinned it, the call's id — `""` is no id — and `isError` only when
+ * true. Undefined when there is nothing, so such a row is the body it always
+ * was.
+ */
+function stepMarks(m) {
+    const out = {};
+    if (m.pinnedBy)
+        out.pinnedBy = m.pinnedBy;
+    if (m.callId)
+        out.callId = m.callId.slice(0, 200);
+    if (m.isError === true)
+        out.isError = true;
+    return Object.keys(out).length > 0 ? out : undefined;
+}
+/** Whether a tool's answer, as the hook saw it, is an MCP result that says it failed (`isError: true`). */
+function resultSaysError(response) {
+    return (response !== null &&
+        typeof response === "object" &&
+        !Array.isArray(response) &&
+        response.isError === true);
+}
 /** A relayed flag that says yes: `true`, `1`, `"1"` or `"true"` (any case). */
 function isOn(value) {
     if (value === true || value === 1)
@@ -434,6 +670,20 @@ export class ControlServer {
     proxySessions = new Map();
     /** `run_scenario` pres not yet consumed by a `/scenario/run`, oldest first. */
     directCalls = [];
+    /**
+     * `report_wrong_result` pres not yet consumed by a `/scenario/dispute`,
+     * oldest first (review item 19): how a report from `bir-scenario`, which is
+     * never told its session, finds the session — and so the plan — it is about.
+     */
+    reportCalls = [];
+    /** Plans the agent said were wrong, and the service's answer — on its way, or in. */
+    disputed = new WeakMap();
+    /**
+     * The plans that need their owner, by account, as the service last listed
+     * them (`GET /scenarios/attention`, review item 8), and the ask still on its
+     * way. Null is "nothing can be said": no service, an older one, a failure.
+     */
+    attention = new Map();
     /** Plans a `/scenario/run` is executing right now: one run per plan. */
     runningPlans = new Set();
     /**
@@ -966,6 +1216,9 @@ export class ControlServer {
                 case "/proxy/result":
                     this.send(res, 200, this.onProxyResult(body));
                     return;
+                case "/proxy/tools":
+                    this.send(res, 200, this.onProxyTools(body));
+                    return;
                 case "/scenario/run": {
                     // Like a long poll, a run can outlive its caller: bir-scenario drops
                     // the request when the host cancels the call or its timeout fires.
@@ -992,6 +1245,9 @@ export class ControlServer {
                 case "/scenario/hello":
                     this.send(res, 200, this.onScenarioHello(body));
                     return;
+                case "/scenario/dispute":
+                    this.send(res, 200, await this.onScenarioDispute(body));
+                    return;
                 default:
                     this.send(res, 404, { error: "not_found" });
                     return;
@@ -1283,7 +1539,7 @@ export class ControlServer {
     async dispatchHook(route, payload, onLate) {
         switch (route) {
             case "/session/start":
-                return this.onSessionStart(payload);
+                return await this.onSessionStart(payload);
             case "/session/prompt": {
                 // What a cancelled direct run left this session to tell (see
                 // `SessionState.stashedNote`). Claimed before the wait, so the
@@ -1639,8 +1895,24 @@ export class ControlServer {
             lossy: this.lossy,
             sessionId: session.sessionId,
             cwd: session.cwd ?? this.opts.cwd,
+            // The project's key (review item 16): what the tool lists of this
+            // project carry too, so the service offers a correction of this run's
+            // plan the tools of this project only. See {@link projectKeyHere}.
+            project: this.projectKeyHere(),
         };
     }
+    /**
+     * The project key of everything this recorder sends (review item 16): its
+     * runs and its tool lists. The folder this recorder serves — the one its
+     * discovery file is keyed by and its hooks are installed in — and not a
+     * session's `cwd`: that follows the agent's `cd` from turn to turn, and a
+     * tool list is sent when its proxy starts, before any of its calls ties it
+     * to a session. The service matches a plan's recording to its tools by
+     * equality, so both sides must hash the same folder.
+     */
+    projectKeyHere() {
+        return projectKey(this.opts.cwd);
+    }
     /**
      * A similar-prompt hit means the service created no run, so every later step
      * post would 404. Stop recording it — that half is v1 and is mandatory, and
@@ -1771,7 +2043,7 @@ export class ControlServer {
         // Awaited: a scenario with a target derives before the directive goes
         // out, so a plan that cannot find its target is never delivered
         // (segmented.md R-PARAM-4). Inside the prompt's own budget.
-        const arming = this.armOrLog(run, this.replay.arm(match, prompt || run.input, this.wrapped, "prompt", { recentResults: this.recentResultsFor(session, "prompt") }, this.hostContext(session, run)));
+        const arming = this.armOrLog(run, this.replay.arm(match, prompt || run.input, this.wrapped, "prompt", { recentResults: this.recentResultsFor(session, "prompt"), agentDay: this.agentDayFor(session) }, this.hostContext(session, run)));
         const remaining = Math.max(0, promptWaitMs - (Date.now() - startedAt));
         const state = await this.withinBudget(arming, remaining);
         if (state === undefined)
@@ -1813,9 +2085,15 @@ export class ControlServer {
         state.sessionCwd = session.cwd ?? this.opts.cwd;
         // The service offered to record this turn as the recording's newest run:
         // should the agent redo the task after the plan, the plan's own calls go
-        // into that run first, so they are kept whole as they run (AC2).
-        if (match.repeat?.runId)
+        // into that run first, so they are kept whole as they run (AC2). And in a
+        // Claude Code session, should the agent only answer, they go whole beside
+        // its answer (review item 12), where the report has 3,800 bytes of each.
+        if (match.repeat?.runId || !otherHost(session))
             state.keepCalls = true;
+        // A bundle that forbids every tool call makes one exception for `bir`'s
+        // report tool, where this session has it (review item 19).
+        if (!otherHost(session))
+            state.reportTool = () => this.reportToolServed();
         this.declineWithoutDeliveryTool(state);
         // A steer plan with a shell or file-write step can only be followed if the
         // directive shows its computed arguments (the pin guard holds those steps
@@ -2009,6 +2287,20 @@ export class ControlServer {
             return false;
         return this.liveHellos(Date.now()).some(([, h]) => h.tools >= 1 && !h.off);
     }
+    /**
+     * Whether a running `bir-scenario` here serves `report_wrong_result` right
+     * now (review item 19): one that is not off said so in its hello. What a
+     * bundle delivered beside a call of the agent's own (a divergence) is laid
+     * out by: such a bundle forbids every tool call but this one. A direct
+     * plan's bundle goes by its own `bir-scenario`'s word instead, which came
+     * with its `/scenario/run` (see {@link onScenarioRun}). Configured is not
+     * connected, as for the delivery tool.
+     */
+    reportToolServed() {
+        if (!this.deliveryConfigured())
+            return false;
+        return this.liveHellos(Date.now()).some(([, h]) => h.report === true && !h.off);
+    }
     /**
      * Whether this project's configuration has the `bir` server, as far as
      * anything here knows: a hook that named one of its tools, the caller's
@@ -2049,6 +2341,73 @@ export class ControlServer {
         }
         return out.sort((a, b) => b[1].at - a[1].at);
     }
+    /**
+     * The tool list of each wrapped server last sent to the service, by
+     * account, project and server (AC12; review item 16): its hash, when, and
+     * whether the service took it (null while the send is on its way).
+     */
+    toolListsSent = new Map();
+    /**
+     * `POST /proxy/tools` — a proxy's server listed its tools (`tools/list`;
+     * the service's autocorrect.md AC12). Its names, descriptions, input
+     * schemas and what it says of each tool (`annotations`) go to the service —
+     * secret-shaped text taken out, and within what the service keeps — with
+     * the project they are of ({@link projectKeyHere}, the key every run here
+     * carries). Sent when the list changed since that server's last one for
+     * this account and project, when the last send failed ten minutes ago, or
+     * six hours after the last one the service took. `bir off`, and a session
+     * started with BIR_OFF=1, send nothing, as for a step. Always `{ ok: true }`;
+     * never slow.
+     */
+    onProxyTools(body) {
+        if (offSource(this.opts.cwd))
+            return { ok: true, off: true };
+        const boundTo = typeof body.proxyId === "string" ? this.proxySessions.get(body.proxyId) : undefined;
+        if (this.isSessionOff(boundTo))
+            return { ok: true, off: true };
+        const serverName = typeof body.serverName === "string" ? body.serverName.trim().slice(0, 200) : "";
+        if (!serverName || !Array.isArray(body.tools) || !isToolListReporter(this.recorder))
+            return { ok: true };
+        const tools = toolListForService(serverName, body.tools);
+        // A server still starting may list nothing: that replaces no list.
+        if (tools.length === 0)
+            return { ok: true };
+        const project = this.projectKeyHere();
+        const key = `${accountOf(this.recorder) ?? ""}\u0000${project}\u0000${serverName}`;
+        const hash = createHash("sha256").update(JSON.stringify(tools)).digest("hex");
+        const now = Date.now();
+        const last = this.toolListsSent.get(key);
+        if (last &&
+            last.hash === hash &&
+            (last.ok === null || now - last.at < (last.ok ? TOOL_LIST_RESEND_MS : TOOL_LIST_RETRY_MS))) {
+            return { ok: true };
+        }
+        const entry = { hash, at: now, ok: null };
+        this.toolListsSent.delete(key);
+        this.toolListsSent.set(key, entry);
+        while (this.toolListsSent.size > 512) {
+            const oldest = this.toolListsSent.keys().next().value;
+            if (oldest === undefined)
+                break;
+            this.toolListsSent.delete(oldest);
+        }
+        let sent;
+        try {
+            sent = Promise.resolve(this.recorder.reportTools(serverName, tools, project));
+        }
+        catch {
+            sent = Promise.resolve(false);
+        }
+        void sent
+            .catch(() => false)
+            .then((ok) => {
+            if (this.toolListsSent.get(key) !== entry)
+                return;
+            entry.ok = ok === true;
+            entry.at = Date.now();
+        });
+        return { ok: true };
+    }
     /**
      * `POST /scenario/hello` — a running `bir-scenario` saying what it serves
      * (K3): on `initialize`, on `tools/list`, when its off state flips and every
@@ -2064,10 +2423,13 @@ export class ControlServer {
         const tools = Number.isFinite(toolsRaw) && toolsRaw > 0 ? Math.floor(toolsRaw) : 0;
         const off = body.off === true;
         const version = typeof body.version === "string" ? body.version.slice(0, 40) : undefined;
+        // It serves `report_wrong_result` (runner 0.3.18 on; review item 19). An
+        // older `bir-scenario` says nothing of it, and serves none.
+        const report = body.report === true;
         const before = this.scenarioHellos.get(pid);
         // Re-inserted, so the map's order is oldest hello first.
         this.scenarioHellos.delete(pid);
-        this.scenarioHellos.set(pid, { at: Date.now(), tools, off, version });
+        this.scenarioHellos.set(pid, { at: Date.now(), tools, off, version, ...(report ? { report } : {}) });
         while (this.scenarioHellos.size > DELIVERY_HELLO_MAX) {
             const oldest = this.scenarioHellos.keys().next().value;
             if (oldest === undefined)
@@ -2088,6 +2450,138 @@ export class ControlServer {
         }
         return { ok: true };
     }
+    /** Remember a `report_wrong_result` pre (see {@link reportCalls}): a few, and only for a while. */
+    noteReportCall(sessionId, toolUseId) {
+        const now = Date.now();
+        this.reportCalls = this.reportCalls.filter((c) => now - c.at < REPORT_CALL_TTL_MS && c.toolUseId !== toolUseId);
+        this.reportCalls.push({ sessionId, toolUseId, at: now });
+        if (this.reportCalls.length > 64)
+            this.reportCalls = this.reportCalls.slice(-64);
+    }
+    /**
+     * `POST /scenario/dispute` — the agent said, through `bir`'s
+     * `report_wrong_result`, that a replay's results do not answer its request
+     * (the service's review of calcscenarioautocorrect.md, item 19): the plan
+     * took the wrong half of an "if … otherwise", or acted on the wrong item. A
+     * wrong half is caught only when the agent says so, and until now there was
+     * no way to say it but in an answer nobody might read.
+     *
+     * WHOSE PLAN. The session is the one whose `PreToolUse` for the tool carried
+     * the request's `toolUseId` (`bir-scenario` forwards the host's id for the
+     * call, as for `run_scenario`); without one, the one session where such a
+     * call is waiting; without that either, the one session whose plan ran in
+     * the last half hour. Never a guess between two. The plan is the newest one
+     * that ran in that session's latest turn with a plan: this turn's, or the
+     * one before it.
+     *
+     * WHAT GOES. `POST /scenarios/:scenarioId/dispute` with the reason, `by:
+     * "agent"`, and the turn's execution ticket as `executionId` — the id its
+     * report books under when the turn ends, so the service may well have the
+     * ticket and not yet the row. Once per plan and turn: a second report of the
+     * same plan is answered from the first. Nothing here undoes anything.
+     *
+     * Answers `{ ok, held?, why? }` for `bir-scenario` to put in one sentence.
+     * Never throws, and is never slow beyond the service's own bound.
+     */
+    async onScenarioDispute(body) {
+        if (offSource(this.opts.cwd))
+            return { ok: false, why: "off" };
+        const reason = typeof body.reason === "string" ? body.reason.trim().slice(0, REPORT_REASON_MAX) : "";
+        if (!reason)
+            return { ok: false, why: "no_reason" };
+        const session = this.sessionForDispute(body);
+        if (!session || this.isSessionOff(session.sessionId))
+            return { ok: false, why: "no_plan" };
+        const state = this.disputedPlan(session);
+        if (!state?.scenarioId) {
+            logLine("replay.dispute_unplaced", {
+                sess: session.sessionId,
+                why: "the agent reported a wrong replay, and no plan ran in this session's latest turns — nothing is sent",
+            });
+            return { ok: false, why: "no_plan" };
+        }
+        const scenarioId = state.scenarioId;
+        // Once per plan and turn: a second report — also one sent while the first
+        // is on its way — is answered from the first. One that was not taken may
+        // be tried again.
+        const earlier = this.disputed.get(state);
+        if (earlier) {
+            const first = await earlier;
+            return first.ok
+                ? { ok: true, held: first.held === true, why: "already_reported", scenarioId }
+                : { ok: false, held: false, ...(first.why ? { why: first.why } : {}), scenarioId };
+        }
+        const recorder = this.recorder;
+        if (!isScenarioDisputer(recorder))
+            return { ok: false, why: "no_service", scenarioId };
+        const pending = recorder
+            .disputeScenario(scenarioId, { reason, ...(state.ticket ? { executionId: state.ticket } : {}) }, { timeoutMs: 10_000 })
+            .catch(() => ({ ok: false, why: "service_error" }));
+        this.disputed.set(state, pending);
+        const answer = await pending;
+        if (!answer.ok && this.disputed.get(state) === pending)
+            this.disputed.delete(state);
+        logLine("replay.disputed", {
+            sess: session.sessionId,
+            scenario: scenarioId,
+            ticket: state.ticket,
+            ok: answer.ok,
+            held: answer.held === true || undefined,
+            why: answer.ok
+                ? "the agent said this replay's results do not answer its request — reported to the service"
+                : `the agent's report that this replay was wrong was not taken: ${answer.why ?? "no reason given"}`,
+        });
+        return {
+            ok: answer.ok,
+            held: answer.held === true,
+            ...(answer.why ? { why: answer.why } : {}),
+            scenarioId,
+        };
+    }
+    /** The session a `/scenario/dispute` is about (see {@link onScenarioDispute}), or undefined. */
+    sessionForDispute(body) {
+        const now = Date.now();
+        this.reportCalls = this.reportCalls.filter((c) => now - c.at < REPORT_CALL_TTL_MS);
+        const toolUseId = typeof body.toolUseId === "string" && body.toolUseId ? body.toolUseId : undefined;
+        let pick = toolUseId ? this.reportCalls.find((c) => c.toolUseId === toolUseId) : undefined;
+        if (!pick && !toolUseId && new Set(this.reportCalls.map((c) => c.sessionId)).size === 1) {
+            pick = this.reportCalls[this.reportCalls.length - 1];
+        }
+        if (pick) {
+            const chosen = pick;
+            this.reportCalls = this.reportCalls.filter((c) => c !== chosen);
+            const session = this.sessions.get(chosen.sessionId);
+            if (session)
+                return session;
+        }
+        // No pre seen for it — a hook that did not arrive. The one session whose
+        // plan ran lately, or none: two would be a guess.
+        const recent = [...this.sessions.values()].filter((s) => {
+            if (otherHost(s))
+                return false;
+            const state = this.disputedPlan(s);
+            return state !== undefined && now - state.armedAt < REPORT_FALLBACK_MS;
+        });
+        return recent.length === 1 ? recent[0] : undefined;
+    }
+    /**
+     * The plan a report of a wrong replay is about: the newest that ran — a
+     * step of it did its work — in the session's latest turn with one, this
+     * turn or the one before it.
+     */
+    disputedPlan(session) {
+        for (const run of [session.run, session.previous]) {
+            if (!run)
+                continue;
+            const states = run.replays.length > 0 ? run.replays : run.replay ? [run.replay] : [];
+            for (let i = states.length - 1; i >= 0; i -= 1) {
+                const s = states[i];
+                if (s.scenarioId && (s.stepsPinned > 0 || s.ranToEnd === true))
+                    return s;
+            }
+        }
+        return undefined;
+    }
     /**
      * Re-read whether this project configures the `bir` server — only when
      * ~/.claude.json or .mcp.json changed since the last read. A file the host is
@@ -2159,6 +2653,40 @@ export class ControlServer {
             recordsOnly: this.recordsOnly(session, run) || undefined,
         };
     }
+    /**
+     * The day this session's agent was told it is (issue 1212), read from its
+     * transcript each time it is asked. A session of another host has none.
+     */
+    agentDayFor(session) {
+        if (otherHost(session))
+            return undefined;
+        return () => agentDayOf(session.transcriptPath);
+    }
+    /**
+     * What a run's finish says of its agent's day (the service's review of
+     * calcscenarioautocorrect.md, item 1): the line of the session's system
+     * prompt that gives the date — never Claude Code's own date reminder, which
+     * is only this machine's day — and this machine's day when the turn's prompt
+     * came. The service checks a corrected plan against this run, and reads its
+     * prompt with this day, as a replay would have. Undefined with neither.
+     */
+    runAgentDay(session, run) {
+        let said;
+        if (!otherHost(session)) {
+            try {
+                const day = agentDayOf(session.transcriptPath);
+                if (day?.source === "system" && day.line)
+                    said = day.line.slice(0, 400);
+            }
+            catch {
+                // An unreadable transcript says no day; the machine's still goes.
+            }
+        }
+        const local = run.promptDay;
+        if (!said && !local)
+            return undefined;
+        return { ...(said ? { said } : {}), ...(local ? { local } : {}) };
+    }
     /**
      * The earlier tool results the reading of new values may look at: this
      * prompt's own, from the transcript — and so none for a plan that is
@@ -2354,10 +2882,16 @@ export class ControlServer {
                     // "LLM $/run", and it is the service's fallback baseline for a
                     // scenario that has no samples yet. A run recorded at $0 makes
                     // every later saving measured against nothing.
+                    //
+                    // The agent's day is read here, at the finish (review item 1):
+                    // its host writes a system prompt's "Today's date is …" into the
+                    // session only after the prompt hook.
+                    const agentDay = this.runAgentDay(session, run);
                     this.recorder.finishRun(run.runId, answer || undefined, {
                         durationMs: recordedMs,
                         costUsd: recordedCost.measured ? recordedCost.usd : undefined,
                         ...closing,
+                        ...(agentDay ? { agentDay } : {}),
                     });
                 });
             });
@@ -2536,10 +3070,15 @@ export class ControlServer {
                 sealedBy === "stop" &&
                 run.lastToolUseId !== undefined &&
                 !otherHost(session)) {
+                // The plan's calls whole, beside the answer (review item 12). Taken
+                // now — the seal lets go of them as soon as this returns — and read
+                // only once there is an answer to send them with, off the hook's path.
+                const kept = this.replay.turnCallsOf(state);
                 const sent = settledTextAfterToolUse(session.transcriptPath, run.lastToolUseId)
                     .catch(() => "")
                     .then((answer) => {
-                    this.queue.push(() => recorder.reportExecution(answer ? { ...report, answer } : report));
+                    const calls = answer ? this.answerCallsOf(state.scenarioId, kept) : [];
+                    this.queue.push(() => recorder.reportExecution(answer ? { ...report, answer, ...(calls.length > 0 ? { answerCalls: calls } : {}) } : report));
                 });
                 run.sealing = run.sealing ? Promise.all([run.sealing, sent]).then(() => undefined) : sent;
                 return;
@@ -2566,6 +3105,44 @@ export class ControlServer {
                 this.queue.push(() => recorder.reportExecution(report));
         }
     }
+    /**
+     * The plan's own calls of the turn, whole, as an answered turn's report
+     * carries them (the service's review of calcscenarioautocorrect.md, item
+     * 12): what each step sent and what came back, as they were kept for the
+     * turn (replay/controller.ts, `TurnCall`) — in a recording's own form,
+     * redacted and capped at 64 KiB apiece, as a redo's copies are (AC2) —
+     * where the report's own copies have 3,800 bytes. The calls of a called sub-task are
+     * left out: their step numbers are the sub-task's own, and would read as the
+     * plan's steps of the same number. `kept` is what the turn kept, taken while
+     * the seal still had it; this runs after the answer's wait, off the hook's
+     * path. The recorder cuts them to what one report may carry when it sends
+     * them.
+     */
+    answerCallsOf(scenarioId, kept) {
+        const calls = [];
+        for (const c of kept) {
+            if (scenarioId && c.scenarioId !== scenarioId)
+                continue;
+            let input = {};
+            try {
+                const parsed = JSON.parse(c.input);
+                if (parsed && typeof parsed === "object" && !Array.isArray(parsed))
+                    input = parsed;
+            }
+            catch {
+                // Kept serialized and capped: it was JSON. Nothing to read otherwise.
+            }
+            const failed = c.error !== undefined;
+            calls.push({
+                stepIndex: c.stepIndex,
+                toolName: c.toolName,
+                input,
+                output: (failed ? c.error : c.output) ?? "",
+                ...(failed ? { isError: true } : {}),
+            });
+        }
+        return calls;
+    }
     /**
      * Seal the session's run now, and drain it to the service in the background.
      *
@@ -2631,7 +3208,7 @@ export class ControlServer {
         }
     }
     // ── hook events ──────────────────────────────────────────────────────────
-    onSessionStart(payload) {
+    async onSessionStart(payload) {
         const session = this.ensureSession(payload);
         // A resumed session is a live one again, whatever its SessionEnd said.
         session.endedAt = undefined;
@@ -2648,7 +3225,79 @@ export class ControlServer {
         // in the background, whether the service answers again.
         if (isServiceProber(this.recorder))
             this.recorder.probeIfFailing();
-        return {};
+        // A plan held for its owner saves nothing until somebody looks (review
+        // item 8): one line for the person, never for the model. `bir off` and
+        // BIR_OFF=1 never reach here — their session start is answered `{}`.
+        const line = await this.attentionLine(session, payload);
+        return line ? { systemMessage: line } : {};
+    }
+    /**
+     * The line a session start shows the person when plans of this account
+     * wait for their owner (`GET /scenarios/attention`; the service's review of
+     * calcscenarioautocorrect.md, item 8), or undefined. A `systemMessage`:
+     * Claude Code shows it to the person and adds nothing to the model's
+     * context. Asked at most once in {@link ATTENTION_CACHE_MS} per account (in
+     * {@link ATTENTION_RETRY_MS} when it could say nothing), waited for at most
+     * {@link ATTENTION_WAIT_MS}, and never while the service is failing; any
+     * failure says nothing. Not after a compaction — the
+     * session is mid-work, and was told at its start — and never in a session
+     * of another host, whose adapter shows a person nothing.
+     */
+    async attentionLine(session, payload) {
+        if (payload.source === "compact" || otherHost(session))
+            return undefined;
+        const recorder = this.recorder;
+        if (!isAttentionReader(recorder))
+            return undefined;
+        const account = accountOf(recorder);
+        if (!account)
+            return undefined;
+        let plans = null;
+        try {
+            plans = await this.attentionFor(account, () => recorder.scenarioAttention({ timeoutMs: ATTENTION_WAIT_MS }));
+        }
+        catch {
+            return undefined;
+        }
+        if (!plans || plans.length === 0)
+            return undefined;
+        const line = attentionText(plans);
+        if (line)
+            logLine("session.attention", { sess: session.sessionId, plans: plans.length, why: "plans wait for their owner — said to the person" });
+        return line;
+    }
+    /**
+     * This account's plans that need their owner: the cached answer while it is
+     * fresh, else the service's, waited for no longer than
+     * {@link ATTENTION_WAIT_MS}. An answer that comes later still fills the
+     * cache for the next session start. One ask at a time per account.
+     */
+    async attentionFor(account, ask) {
+        const cached = this.attention.get(account);
+        const fresh = cached?.plans === null ? ATTENTION_RETRY_MS : ATTENTION_CACHE_MS;
+        if (cached && !cached.pending && Date.now() - cached.at < fresh)
+            return cached.plans;
+        let pending = cached?.pending;
+        if (!pending) {
+            const asked = Promise.resolve()
+                .then(ask)
+                .catch(() => null);
+            pending = asked;
+            this.attention.set(account, { at: cached?.at ?? 0, plans: cached?.plans ?? null, pending: asked });
+            void asked.then((plans) => {
+                if (this.attention.get(account)?.pending !== asked)
+                    return;
+                this.attention.set(account, { at: Date.now(), plans });
+            });
+            // A recorder that signs in as one account after another keeps a few, not all.
+            while (this.attention.size > 16) {
+                const oldest = this.attention.keys().next().value;
+                if (oldest === undefined || oldest === account)
+                    break;
+                this.attention.delete(oldest);
+            }
+        }
+        return (await this.withinBudget(pending, ATTENTION_WAIT_MS)) ?? null;
     }
     async onPrompt(payload) {
         const session = this.ensureSession(payload);
@@ -2696,6 +3345,7 @@ export class ControlServer {
             // steps to gain a prompt is the wrong trade — and say so.
             open.promptSeen = true;
             open.input = input;
+            open.promptDay = localDay();
             // This hook announces nothing, so no plan of this run may steer.
             open.matchExpired = true;
             this.retireUnannounced(session, open);
@@ -2715,6 +3365,7 @@ export class ControlServer {
         const run = this.ensureRun(session, input, { replay: other && payload.replay === true }, prompt);
         run.promptSeen = true;
         run.input = input;
+        run.promptDay = localDay();
         session.prompts += 1;
         logDetail("session.prompt", { sess: session.sessionId, run: run.runId, chars: input.length });
         // With replay off there is nothing this hook could say, so it says nothing
@@ -2810,6 +3461,11 @@ export class ControlServer {
             if (toolUseId)
                 (run.housekeepingUses ??= new Set()).add(toolUseId);
             logDetail("tool.pre.skipped", { run: run.runId, tool: toolName, why: "host housekeeping" });
+            // The agent is about to say a replay was wrong (review item 19): which
+            // session asks is known here, and only here — `bir-scenario` is never
+            // told its session. Its `/scenario/dispute` finds it by this id.
+            if (toolName === REPORT_TOOL_NAME && toolUseId)
+                this.noteReportCall(session.sessionId, toolUseId);
             // `bir setup` lets Claude Code run every `bir` tool without asking — but a
             // change saved or taken back with `force`, past the check that refused
             // it, is the person's decision (editSteps.md D3), so Claude Code asks
@@ -3146,13 +3802,15 @@ export class ControlServer {
             : undefined;
         if (run.recording) {
             this.noteOwnCall(run, pinnedBy);
+            // The host's id for the call ties this row to its answer (review item 7).
+            const metadata = stepMarks({ pinnedBy, callId: toolUseId });
             this.queue.push(() => {
                 this.recorder.recordToolSelected(run.runId, pair.selected, {
                     toolName,
                     toolInput: serializeCapped(redact(args)),
                     context: context || undefined,
                     intent: thinkingIntent,
-                    metadata: pinnedBy ? { pinnedBy } : undefined,
+                    metadata,
                 });
             });
         }
@@ -3292,11 +3950,12 @@ export class ControlServer {
             run.builtIns.set(toolUseId, { stepIndex: pair.selected, responseIndex: pair.response, toolName });
             if (run.recording) {
                 const toolInput = serializeCapped(redact(action.input));
+                const metadata = stepMarks({ pinnedBy, callId: toolUseId });
                 this.queue.push(() => {
                     this.recorder.recordToolSelected(run.runId, pair.selected, {
                         toolName,
                         toolInput,
-                        metadata: pinnedBy ? { pinnedBy } : undefined,
+                        metadata,
                     });
                 });
             }
@@ -3379,12 +4038,14 @@ export class ControlServer {
         if (run.recording) {
             this.noteOwnCall(run);
             const toolInput = serializeCapped(redact(modelArgs));
+            const metadata = stepMarks({ callId: toolUseId });
             this.queue.push(() => {
                 this.recorder.recordToolSelected(run.runId, pair.selected, {
                     toolName,
                     toolInput,
                     context: words.context || undefined,
                     intent: words.thinking,
+                    metadata,
                 });
             });
         }
@@ -3841,7 +4502,11 @@ export class ControlServer {
         // seconds, and this call is waiting. A plan not armed in time is dropped
         // unused — it was never announced, so it never steers — and its ticket is
         // swept like any unredeemed one (R-OUT-12).
-        const arming = this.armOrLog(run, this.replay.arm(match, text, this.wrapped, "intent", { liveCall: { toolName, toolInput }, recentResults: this.recentResultsFor(session, "call") }, this.hostContext(session, run)));
+        const arming = this.armOrLog(run, this.replay.arm(match, text, this.wrapped, "intent", {
+            liveCall: { toolName, toolInput },
+            recentResults: this.recentResultsFor(session, "call"),
+            agentDay: this.agentDayFor(session),
+        }, this.hostContext(session, run)));
         const state = await this.withinBudget(arming, INTENT_ARM_DERIVE_MS);
         if (state === undefined)
             return undefined; // it threw, and said so
@@ -4243,17 +4908,20 @@ export class ControlServer {
                 // service's row schema takes a number or nothing.
                 ...(call.chainRevision !== null ? { chainRevision: call.chainRevision } : {}),
             };
+            // One id on both rows, and the failure marked (review item 7).
+            const callId = newCallId();
+            const failed = call.error !== undefined;
             this.queue.push(() => {
                 this.recorder.recordToolSelected(id, pair.selected, {
                     toolName: call.toolName,
                     toolInput: call.input,
-                    metadata: { byPlan },
+                    metadata: { byPlan, callId },
                 });
                 this.recorder.recordToolResponse(id, pair.response, {
                     toolName: call.toolName,
-                    toolOutput: call.error === undefined ? call.output : undefined,
+                    toolOutput: failed ? undefined : call.output,
                     toolError: call.error,
-                    metadata: { byPlan },
+                    metadata: failed ? { byPlan, callId, isError: true } : { byPlan, callId },
                 });
             });
         }
@@ -4522,11 +5190,15 @@ export class ControlServer {
         const responseIndex = builtIn ? builtIn.responseIndex : run.ordering.allocate();
         if (run.recording) {
             const output = serializeCapped(redact(payload.tool_response ?? {}));
+            // Its call's id, and whether it failed — the host said so, or the
+            // tool's own MCP result did (review item 7).
+            const metadata = stepMarks({ callId: toolUseId, isError: failed || resultSaysError(payload.tool_response) });
             this.queue.push(() => {
                 this.recorder.recordToolResponse(run.runId, responseIndex, {
                     toolName,
                     toolOutput: failed ? undefined : output,
                     toolError: failed ? this.errorText(payload) : undefined,
+                    metadata,
                 });
             });
         }
@@ -4850,6 +5522,13 @@ export class ControlServer {
         const hostPid = Number(body.ppid);
         if (Number.isInteger(hostPid) && hostPid > 0)
             this.replay.work.bindSiblings(hostPid, call.sessionId);
+        // The `bir-scenario` asking is this session's own: whether it serves the
+        // report tool is its word, not any hello's (review item 19). An older one
+        // says nothing, and serves none.
+        if (!otherHost(this.sessions.get(call.sessionId))) {
+            const reports = body.reports === true;
+            state.reportTool = () => reports;
+        }
         this.runningPlans.add(state);
         // The session is busy for as long as its plan runs, and sends no hook
         // meanwhile: the host is waiting on this very call.
@@ -5034,6 +5713,8 @@ export class ControlServer {
             result: report.result,
             isError: report.isError,
             errorMessage: report.errorMessage,
+            // The id a hook injected, when one did; `record` mints one otherwise.
+            callId: report.callId,
         });
         logDetail("proxy.step", {
             run: run.runId,
@@ -5285,6 +5966,9 @@ export class ControlServer {
             // from the map (segmented.md R-INTENT-7).
             pinnedBy: correlation.pinnedBy,
             intent: correlation.intent,
+            // The host's id for the call when it named one, else the one minted for
+            // it here: what ties the call to its answer (review item 7).
+            callId: correlation.toolUseId || correlation.callId,
         });
         logDetail("proxy.step.merged", {
             run: run.runId,
@@ -5294,7 +5978,16 @@ export class ControlServer {
         });
         return pair;
     }
-    /** The one place a tool step pair is written. Redaction and caps live here. */
+    /**
+     * The one place a tool step pair is written. Redaction and caps live here.
+     *
+     * Both rows carry the call's id (`metadata.callId`, review item 7) — the
+     * caller's, or one minted here for a call no hook named — and the answer
+     * of a call that failed says so (`metadata.isError`). The service pairs a
+     * call with its answer by that id, where it used to pair them by tool name
+     * in the order they came: two calls of one tool at once, answered out of
+     * order, took each other's answers.
+     */
     record(run, pair, d) {
         if (!run.recording)
             return;
@@ -5304,18 +5997,23 @@ export class ControlServer {
         const toolError = d.isError
             ? (d.errorMessage ?? serializeCapped(redact(d.result)))
             : undefined;
+        const callId = d.callId || newCallId();
+        // Failed, as its reporter said or as its own MCP result says — a hook's
+        // fallback view carries the result only. The row is otherwise as it was.
+        const failedMark = d.isError || resultSaysError(d.result);
         this.queue.push(() => {
             this.recorder.recordToolSelected(run.runId, pair.selected, {
                 toolName: d.toolName,
                 toolInput,
                 context: d.context,
                 intent: d.intent?.source === "thinking" ? { text: d.intent.text, source: "thinking" } : undefined,
-                metadata: d.pinnedBy ? { pinnedBy: d.pinnedBy } : undefined,
+                metadata: d.pinnedBy ? { pinnedBy: d.pinnedBy, callId } : { callId },
             });
             this.recorder.recordToolResponse(run.runId, pair.response, {
                 toolName: d.toolName,
                 toolOutput,
                 toolError,
+                metadata: failedMark ? { callId, isError: true } : { callId },
             });
         });
     }