@reticlehq/server 3.5.0 → 3.7.0

package/dist/portal/session/first-run-wiring.js

@@ -0,0 +1,132 @@
+/**
+ * Wiring the app the first time an agent needs it, instead of at installation.
+ *
+ * Installing Reticle puts a CLI and an MCP server on the machine and touches no project. The app is
+ * instrumented the first time an agent actually uses Reticle against it: the daemon runs its own
+ * CLI's `init` in the project directory, the same codemod, dev-server start and connect a person
+ * would have run by hand, and reports what it changed.
+ *
+ * A child process rather than an import: the daemon never imports `@reticlehq/init`
+ * (library-path-boundary.test.ts), and running the CLI keeps that line where it is.
+ *
+ * Once per directory for the life of the daemon. A second call returns the first answer, so an agent
+ * that asks again after a failure is told the same thing rather than re-running a codemod on files
+ * the first run already changed.
+ */
+import { spawn } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join, resolve } from 'node:path';
+import { isWebApp } from '@reticlehq/init';
+import { readProjectId } from '../../command/cli/ports/resolve/cli-port.js';
+/** init has a dev server to start and a page to wait for; past this it is not coming. */
+const WIRE_TIMEOUT_MS = 120_000;
+/** A plan line as init prints it: `[✓] Vite plugin → vite.config.ts`. */
+const PLAN_LINE = /^\s*\[(.)\]\s+(.+?)\s+→\s+(.+)$/;
+export function projectDirectoryOf(cwd, home = homedir(), wired = (dir) => readProjectId(dir) !== undefined) {
+    const dir = resolve(cwd);
+    if (dir === resolve(home) || dir === resolve('/'))
+        return undefined;
+    // Already wired: nothing for a first run to do, and init over a wired app proves nothing.
+    if (wired(dir))
+        return undefined;
+    // Only an app with a page: a daemon started in a library or API package wrote a config there.
+    return isWebApp('.', {
+        exists: (p) => existsSync(join(dir, p)),
+        readFile: (p) => {
+            try {
+                return readFileSync(join(dir, p), 'utf8');
+            }
+            catch {
+                return null;
+            }
+        },
+    })
+        ? dir
+        : undefined;
+}
+/** init's plan lines, and the one JSON object it prints last under `--json`. */
+export function readInitOutput(stdout) {
+    const steps = stdout
+        .split('\n')
+        .map((line) => PLAN_LINE.exec(line))
+        .flatMap((m) => null === m
+        ? []
+        : [{ mark: m[1] ?? '', title: (m[2] ?? '').trim(), target: (m[3] ?? '').trim() }]);
+    const at = stdout.lastIndexOf('\n{\n') + 1;
+    let result;
+    try {
+        result = JSON.parse(stdout.slice(at));
+    }
+    catch {
+        result = undefined;
+    }
+    return { steps, result };
+}
+function nodeRun(cliPath) {
+    return (args, cwd) => new Promise((done) => {
+        const child = spawn(process.execPath, [cliPath, ...args], {
+            cwd,
+            stdio: ['ignore', 'pipe', 'pipe'],
+            env: process.env,
+        });
+        let stdout = '';
+        let stderr = '';
+        child.stdout.on('data', (chunk) => (stdout += chunk.toString('utf8')));
+        child.stderr.on('data', (chunk) => (stderr += chunk.toString('utf8')));
+        const timer = setTimeout(() => child.kill(), WIRE_TIMEOUT_MS);
+        child.on('error', (error) => {
+            clearTimeout(timer);
+            done({ code: 1, stdout, stderr: `${stderr}${error.message}` });
+        });
+        child.on('close', (code) => {
+            clearTimeout(timer);
+            done({ code: code ?? 1, stdout, stderr });
+        });
+    });
+}
+export function firstRunWiring(options) {
+    const run = options.run ?? nodeRun(options.cliPath);
+    const done = new Map();
+    return {
+        projectDirectory: (cwd) => projectDirectoryOf(cwd),
+        wire(directory) {
+            const held = done.get(directory);
+            if (held !== undefined)
+                return held;
+            const outcome = run(['init', '--no-mcp', '--json', '--port', String(options.port)], directory)
+                .then(({ code, stdout, stderr }) => {
+                // Under --json the plan lines may go to stderr, keeping stdout for the one object.
+                const { result } = readInitOutput(stdout);
+                const { steps } = readInitOutput(`${stdout}\n${stderr}`);
+                const record = 'object' === typeof result && null !== result
+                    ? result
+                    : {};
+                const url = 'string' === typeof record['url'] ? record['url'] : undefined;
+                const ok = 0 === code && true === record['ok'];
+                const lastError = stderr.trim().split('\n').at(-1);
+                return {
+                    ok,
+                    directory,
+                    steps,
+                    ...(url === undefined ? {} : { url }),
+                    ...(ok
+                        ? {}
+                        : {
+                            error: lastError !== undefined && 0 < lastError.length
+                                ? lastError
+                                : `init exited ${String(code)}`,
+                        }),
+                };
+            })
+                .catch((error) => ({
+                ok: false,
+                directory,
+                steps: [],
+                error: error instanceof Error ? error.message : String(error),
+            }));
+            done.set(directory, outcome);
+            return outcome;
+        },
+    };
+}

package/dist/portal/session/human/live-control.d.ts

@@ -3,6 +3,10 @@ import { SessionState, type HumanControlData } from '@reticlehq/core';
 export interface InboxMessage {
     text: string;
     t: number;
+    /** Set once an agent's tool call took it: what lets the HUD say "Seen" and never before. */
+    seen?: boolean;
+    /** The agent whose call took it, when the daemon knows. */
+    by?: string;
 }
 export declare class LiveControl {
     #private;
@@ -20,8 +24,11 @@ export declare class LiveControl {
      * while I was away", which a destructive drain can never give twice.
      */
     history(): readonly InboxMessage[];
-    /** Return the queued notes AND clear them — delivered once, so a hint never repeats. */
-    drain(): InboxMessage[];
+    /**
+     * Return the queued notes AND clear them — delivered once, so a hint never repeats. Each is marked
+     * seen (by `by` when known) on the same object the history holds, so the HUD can show it.
+     */
+    drain(by?: string): InboxMessage[];
     /** Diagnostic read of the inbox depth (does not clear). */
     size(): number;
     /**

package/dist/portal/session/human/live-control.js

@@ -64,9 +64,18 @@ export class LiveControl {
     history() {
         return this.#history;
     }
-    /** Return the queued notes AND clear them — delivered once, so a hint never repeats. */
-    drain() {
-        return this.#inbox.splice(0, this.#inbox.length);
+    /**
+     * Return the queued notes AND clear them — delivered once, so a hint never repeats. Each is marked
+     * seen (by `by` when known) on the same object the history holds, so the HUD can show it.
+     */
+    drain(by) {
+        const taken = this.#inbox.splice(0, this.#inbox.length);
+        for (const message of taken) {
+            message.seen = true;
+            if (by !== undefined)
+                message.by = by;
+        }
+        return taken;
     }
     /** Diagnostic read of the inbox depth (does not clear). */
     size() {

package/dist/portal/session/human/notes-ledger.d.ts

@@ -0,0 +1,20 @@
+import type { ReviewMark } from './review-store.js';
+/** One note as it lands on disk: the mark without its session-local id and clock. */
+type StoredNote = Omit<ReviewMark, 'id' | 'at'>;
+/** What `.reticle/notes.json` holds. Keyed by content, so a note survives the session it was made in. */
+export interface NotesFile {
+    notes: Record<string, StoredNote>;
+}
+/**
+ * Mark ids (`m1`, `m2`, …) restart with the daemon, so they cannot name a note across sessions.
+ * The route, anchor and words can: the same complaint on the same element is the same note.
+ */
+export declare function noteKey(mark: Pick<ReviewMark, 'route' | 'anchor' | 'note'>): string;
+/**
+ * Merge one session's marks into the project's notes file, so the HUD notes a human left reach the
+ * platform with the rest of `.reticle/` instead of dying with the session that held them.
+ *
+ * Never throws: a note that cannot be written must not break the event that carried it.
+ */
+export declare function recordNotes(reticleRoot: string | undefined, marks: readonly ReviewMark[]): void;
+export {};

package/dist/portal/session/human/notes-ledger.js

@@ -0,0 +1,55 @@
+import { createHash } from 'node:crypto';
+import { mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { ReticleDir } from '@reticlehq/core';
+/** Enough for a project's review history; the oldest fall off first. */
+const MAX_NOTES = 500;
+/**
+ * Mark ids (`m1`, `m2`, …) restart with the daemon, so they cannot name a note across sessions.
+ * The route, anchor and words can: the same complaint on the same element is the same note.
+ */
+export function noteKey(mark) {
+    return createHash('sha256')
+        .update(`${mark.route ?? ''}\n${mark.anchor}\n${mark.note}`)
+        .digest('hex')
+        .slice(0, 16);
+}
+function read(path) {
+    try {
+        const parsed = JSON.parse(readFileSync(path, 'utf8'));
+        return { notes: 'object' === typeof parsed.notes && null !== parsed.notes ? parsed.notes : {} };
+    }
+    catch {
+        return { notes: {} };
+    }
+}
+/**
+ * Merge one session's marks into the project's notes file, so the HUD notes a human left reach the
+ * platform with the rest of `.reticle/` instead of dying with the session that held them.
+ *
+ * Never throws: a note that cannot be written must not break the event that carried it.
+ */
+export function recordNotes(reticleRoot, marks) {
+    if (reticleRoot === undefined || 0 === marks.length)
+        return;
+    const path = join(reticleRoot, ReticleDir.NOTES_FILE);
+    try {
+        const held = read(path).notes;
+        for (const { id: _id, at: _at, ...note } of marks) {
+            const key = noteKey(note);
+            // Re-inserted so a note touched now counts as the newest when the oldest are dropped.
+            delete held[key];
+            held[key] = note;
+        }
+        const keys = Object.keys(held);
+        for (const stale of keys.slice(0, Math.max(0, keys.length - MAX_NOTES)))
+            delete held[stale];
+        mkdirSync(reticleRoot, { recursive: true });
+        const tmp = `${path}.${String(process.pid)}.tmp`;
+        writeFileSync(tmp, `${JSON.stringify({ notes: held }, null, 2)}\n`, 'utf8');
+        renameSync(tmp, path);
+    }
+    catch {
+        // Disk full or read-only checkout: the note is still in the session, just not on the platform.
+    }
+}

package/dist/portal/session/human/review-store.d.ts

@@ -30,8 +30,20 @@ interface ResolveOutcome {
     /** The retired mark's note. Absent when nothing was resolved. */
     note?: string;
 }
+/**
+ * Per-session store of human review marks (the "annotate the bug where you see it" inbox). A mark is
+ * added when a HUMAN_MARK event arrives, listed by the agent via reticle_review, and retired with
+ * resolve when the agent claims the fix — distinct from the live-control inbox, which is drained
+ * (delivered-once) on read. Marks persist (read does not consume) so the agent can list, fix, and
+ * THEN resolve, and a fix can be verified against the same mark.
+ *
+ * No IO of its own and no clock: `onChange` is how a caller keeps it on disk (see notes-ledger.ts).
+ * The id is a monotonic counter (m1, m2, …) so it is deterministic and never depends on
+ * Math.random/Date.now; the timestamp is passed in by the caller.
+ */
 export declare class ReviewStore {
     #private;
+    constructor(onChange?: (marks: ReviewMark[]) => void);
     /** Store a new mark (status pending) stamped with the caller-supplied session-relative time. */
     add(data: HumanMarkData, at: number): ReviewMark;
     /** All marks still awaiting a fix, oldest first. Reading never consumes — resolve retires a mark. */

package/dist/portal/session/human/review-store.js

@@ -1,14 +1,4 @@
 import { MarkStatus } from '@reticlehq/core';
-/**
- * Per-session store of human review marks (the "annotate the bug where you see it" inbox). A mark is
- * added when a HUMAN_MARK event arrives, listed by the agent via reticle_review, and retired with
- * resolve when the agent claims the fix — distinct from the live-control inbox, which is drained
- * (delivered-once) on read. Marks persist (read does not consume) so the agent can list, fix, and
- * THEN resolve, and a fix can be verified against the same mark.
- *
- * Pure in-memory state: no IO, no clock. The id is a monotonic counter (m1, m2, …) so it is
- * deterministic and never depends on Math.random/Date.now; the timestamp is passed in by the caller.
- */
 /** Prefix on review-mark ids (m1, m2, …) — distinguishes them from command ids. */
 const MARK_ID_PREFIX = 'm';
 /**
@@ -29,8 +19,24 @@ let nextMarkId = 0;
 export function resetMarkIdsForTest() {
     nextMarkId = 0;
 }
+/**
+ * Per-session store of human review marks (the "annotate the bug where you see it" inbox). A mark is
+ * added when a HUMAN_MARK event arrives, listed by the agent via reticle_review, and retired with
+ * resolve when the agent claims the fix — distinct from the live-control inbox, which is drained
+ * (delivered-once) on read. Marks persist (read does not consume) so the agent can list, fix, and
+ * THEN resolve, and a fix can be verified against the same mark.
+ *
+ * No IO of its own and no clock: `onChange` is how a caller keeps it on disk (see notes-ledger.ts).
+ * The id is a monotonic counter (m1, m2, …) so it is deterministic and never depends on
+ * Math.random/Date.now; the timestamp is passed in by the caller.
+ */
 export class ReviewStore {
     #marks = [];
+    /** Told the full history after every add and resolve, so a caller can keep it on disk. */
+    #onChange;
+    constructor(onChange) {
+        this.#onChange = onChange;
+    }
     /** Store a new mark (status pending) stamped with the caller-supplied session-relative time. */
     add(data, at) {
         nextMarkId += 1;
@@ -49,6 +55,7 @@ export class ReviewStore {
         if (data.route !== undefined)
             mark.route = data.route;
         this.#marks.push(mark);
+        this.#onChange?.(this.all());
         return mark;
     }
     /** All marks still awaiting a fix, oldest first. Reading never consumes — resolve retires a mark. */
@@ -84,6 +91,7 @@ export class ReviewStore {
         if (mark === undefined || mark.status === MarkStatus.RESOLVED)
             return { resolved: false, id };
         mark.status = MarkStatus.RESOLVED;
+        this.#onChange?.(this.all());
         return { resolved: true, id, note: mark.note };
     }
 }

package/dist/portal/session/live-control-tools.d.ts

@@ -1,15 +1,2 @@
 import type { ToolDef } from '../../surface/tools/tool-kit.js';
-/**
- * Live-control agent tools: the agent's side of the human-in-the-loop control surface.
- *
- * - reticle_end_session: terminal stop. Sets state `ended` and syncs the panel (PRESENTER) with an
- * optional summary. Idempotent — ending an already-ended session is a safe no-op.
- * - reticle_resume: clears a human pause. Sets state `active` and syncs the panel.
- * - reticle_messages: explicit poll — drains and returns the queued human notes.
- *
- * State changes go through `setState`, which echoes the state to the panel in a SINGLE PRESENTER
- * push (optionally carrying human-facing text, e.g. the end summary) — a transition never emits two
- * PRESENTER commands. No clock is read here — inbox stamps were assigned by the session's injected
- * elapsed clock at enqueue time.
- */
 export declare const LIVE_CONTROL_TOOLS: ToolDef[];

package/dist/portal/session/live-control-tools.js

@@ -1,12 +1,45 @@
 import { z } from 'zod';
 import { noteEmptyRead } from '../../surface/tools/gaps/observed-nothing.js';
-import { AGENT_ASK_NOTICE, AGENT_WAITING_NOTICE, PresenterTone, SessionState, YIELD_WITHOUT_SESSION_NOTE, } from '@reticlehq/core';
+import { AGENT_ASK_NOTICE, AGENT_WAITING_NOTICE, PresenterTone, SessionState, VerdictStatus, YIELD_WITHOUT_SESSION_NOTE, } from '@reticlehq/core';
 import { ReticleTool } from '@reticlehq/core';
 import { sessionIdShape } from '../../surface/tools/tool-kit.js';
 import { asString } from '@reticlehq/core';
+import { releaseLease } from '../../surface/tools/lease-tools.js';
 import { gapReportLines } from '../../judgement/runs/artifact/gap-report.js';
 import { gapSummary } from '../../judgement/runs/artifact/gap-summary.js';
-import { DiscoveryInvite } from '@reticlehq/core';
+import { RESULT_FIELD, claimAgainstGrade, endedAgentSession, verdictsSettled, resultField, sessionResult, } from '../../surface/tools/reticle-result.js';
+/** The tab's journal once every verdict in flight has been decided and written. */
+async function settledJournal(session) {
+    await verdictsSettled();
+    await session.flushJournal?.();
+    return session.readJournalActions();
+}
+/**
+ * The session an id-less yield hands back.
+ *
+ * Yield is non-destructive: it only gives the tab back to the human. With several projects connected,
+ * an id-less call hit the same "which session?" refusal a destructive action gets, so an agent that
+ * had just finished driving one tab had to look its id up in order to let go of it (#1258). When the
+ * ordinary resolution refuses, the one connected session this caller has DRIVEN (it holds a
+ * remembered act) is the clear candidate. None, or more than one, and the refusal stands: guessing
+ * which of two driven tabs to release is still a guess.
+ */
+function resolveYieldTarget(sessions, requested) {
+    if (requested !== undefined)
+        return sessions.resolve(requested);
+    try {
+        return sessions.resolve();
+    }
+    catch (refusal) {
+        // In scope only: a tab the project scope refuses to hand over is not this caller's to release.
+        const driven = sessions.inScope().filter((s) => s.lastAct.cursor() !== undefined);
+        const [only] = driven;
+        if (1 !== driven.length || only === undefined)
+            throw refusal;
+        only.markAgentActivity();
+        return only;
+    }
+}
 /**
  * Is this a turn ending with nothing attached, rather than a call about a specific tab?
  *
@@ -34,18 +67,49 @@ function endingTurnWithNothingAttached(deps, id) {
  * PRESENTER commands. No clock is read here — inbox stamps were assigned by the session's injected
  * elapsed clock at enqueue time.
  */
+const DISCONNECT_NEEDS_SESSION_ID = '`disconnect: true` needs the `sessionId` of the page to detach — list them with ' +
+    'reticle_session{action:"list"}; it is never picked for you, because detaching the wrong window ' +
+    'cuts you off from the app.';
+/** The agent's claim, when it is one of the words a run verdict uses. */
+function claimOf(value) {
+    const claims = [
+        VerdictStatus.PASS,
+        VerdictStatus.FAIL,
+        VerdictStatus.PARTIAL,
+    ];
+    return claims.includes(value) ? value : undefined;
+}
 export const LIVE_CONTROL_TOOLS = [
     {
         name: ReticleTool.END_SESSION,
         description: 'End this session for good — use ONLY when the whole task is complete. Sets state "ended" ' +
             '(calm, terminal) and shows the optional `summary` on the panel. If you are just finishing a ' +
-            'turn or waiting on the human, call reticle_session{action:"yield"} instead (revivable). Idempotent.',
-        inputSchema: { summary: z.string().optional(), ...sessionIdShape },
+            'turn or waiting on the human, call reticle_session{action:"yield"} instead (revivable). Idempotent. ' +
+            "With `disconnect: true` and a `sessionId` it also closes that page's connection and refuses it " +
+            'until the daemon restarts — for a stray window (a hidden desktop webview, a 404 page) that keeps coming back. ' +
+            'Ending a tab you leased also releases that lease (`leaseReleased: true`).',
+        inputSchema: {
+            summary: z.string().optional(),
+            claim: z
+                .enum([VerdictStatus.PASS, VerdictStatus.FAIL, VerdictStatus.PARTIAL])
+                .optional()
+                .describe('What YOU claim this session showed. Compared with the graded checks, never used as them.'),
+            disconnect: z
+                .boolean()
+                .optional()
+                .describe('Also detach this page for good (needs sessionId). Reloads stay detached.'),
+            ...sessionIdShape,
+        },
         // `sessionId` is optional because there may genuinely not be one — see the no-op below. An
         // empty string would read as a real id in a log, which is worse than its absence.
         outputSchema: {
             ended: z.boolean(),
             sessionId: z.string().optional(),
+            disconnected: z.boolean().optional(),
+            leaseReleased: z
+                .boolean()
+                .optional()
+                .describe('True when the ended tab was your lease: its context is closed and its slot freed.'),
             note: z.string().optional(),
             talk_to_us: z
                 .string()
@@ -55,9 +119,16 @@ export const LIVE_CONTROL_TOOLS = [
                 .array(z.string())
                 .optional()
                 .describe('What this session claimed and what held — an `unknown` is never counted as held.'),
+            [RESULT_FIELD]: z.string().optional(),
+            claim: z.object({ claimed: z.string(), graded: z.string(), agrees: z.boolean() }).optional(),
         },
         handler: (deps, args) => {
             const requested = asString(args['sessionId']);
+            const detach = true === args['disconnect'];
+            const claim = claimOf(args['claim']);
+            // Named, never auto-picked: detaching the wrong window cuts the agent off from the app.
+            if (detach && requested === undefined)
+                throw new Error(DISCONNECT_NEEDS_SESSION_ID);
             if (endingTurnWithNothingAttached(deps, requested)) {
                 return Promise.resolve({ ended: true, note: YIELD_WITHOUT_SESSION_NOTE });
             }
@@ -90,14 +161,39 @@ export const LIVE_CONTROL_TOOLS = [
             // rather than becoming a rejected promise the caller did not expect.
             const session = deps.sessions.resolve(requested);
             const summary = asString(args['summary']);
-            return session.readJournalActions().then((actions) => {
+            // A verdict still being decided (an assert waiting out its budget) is one of this session's
+            // checks: decided and journaled before the session's result is folded, never after it.
+            return settledJournal(session).then(async (all) => {
+                // This agent session only: its own calls since its last end, never the Harness drives the
+                // tab also holds, and under its own run id so a later end does not overwrite this run.
+                const ended = endedAgentSession(session.id, all, session.elapsed?.(), claim);
+                const actions = ended.actions;
                 // The moment the agent calls the task complete is when "and what did not hold" is worth a
                 // line: the same fold `reticle_context` and `reticle report` serve, so they cannot disagree.
                 const gap = gapReportLines(gapSummary(actions));
                 const panel = [summary, gap[0]].filter((line) => line !== undefined);
                 // One PRESENTER push for the transition; the summary and the gap headline ride together.
                 session.setState(SessionState.ENDED, 0 === panel.length ? undefined : panel.join('\n'));
-                return { ended: true, sessionId: session.id, gap, talk_to_us: DiscoveryInvite.AGENT };
+                if (detach)
+                    deps.sessions.park(session);
+                const answer = {
+                    ended: true,
+                    sessionId: session.id,
+                    ...(detach ? { disconnected: true } : {}),
+                    gap,
+                    // No founder's-call invite here: it is offered to someone stuck (an error, an empty
+                    // session list), never at the end of every task.
+                    ...(claim === undefined ? {} : { claim: claimAgainstGrade(claim, actions) }),
+                    ...resultField(() => sessionResult(deps, session.id, actions, ended.wallMs, ended.runId)),
+                };
+                // An ended lease left connected kept the tab registered until the reaper took it, so the
+                // next agent's every id-less call was refused as ambiguous. Released after the answer is
+                // folded, because releasing closes the tab. Only this caller's own lease, never another's.
+                const pool = deps.pool;
+                if (pool === undefined || !pool.heldBy(session.id, deps.attachId))
+                    return answer;
+                await releaseLease(deps, pool, session.id);
+                return { ...answer, leaseReleased: true };
             });
         },
     },
@@ -135,7 +231,7 @@ export const LIVE_CONTROL_TOOLS = [
                     note: YIELD_WITHOUT_SESSION_NOTE,
                 });
             }
-            const session = deps.sessions.resolve(requested);
+            const session = resolveYieldTarget(deps.sessions, requested);
             const note = asString(args['note']);
             const tone = ask ? PresenterTone.ASK : PresenterTone.WAITING;
             const text = ask && note !== undefined && note.trim().length > 0
@@ -202,12 +298,10 @@ export const LIVE_CONTROL_TOOLS = [
             // said nothing; the second means an agent is waiting on a channel that does not exist.
             return Promise.resolve(noteEmptyRead({ messages }, 'messages', {
                 noun: 'messages from the human since the last poll',
-                // The HUD no longer carries a text input — two boxes on one screen, and nothing said which
-                // was which. Nothing in the shipped product produces one of these today, so an empty queue
-                // here is structural rather than a quiet human, and a caller polling it deserves to know
-                // that rather than infer silence.
-                caveat: 'the HUD has no message box, so nothing currently sends on this channel — an empty ' +
-                    'queue here is not evidence about what the human thinks',
+                // The HUD's note box is the one producer, and every tool result already carries what it
+                // sends, so polling this is rarely needed and silence here is only silence so far.
+                caveat: 'notes from the HUD also arrive inline on any Reticle tool result (`control.guidance`), ' +
+                    'so an empty queue means nothing new since the last call, not that the human agrees',
             }));
         },
     },

package/dist/portal/session/narration-args.d.ts

@@ -0,0 +1,5 @@
+export interface NarrationBy {
+    harness: true;
+    summary?: boolean;
+}
+export declare function narrationArgs(text: string, by?: NarrationBy): Record<string, unknown>;

package/dist/portal/session/narration-args.js

@@ -0,0 +1,17 @@
+/**
+ * A narration line for the HUD, and who it is from.
+ *
+ * A Harness line names the Harness, so the HUD files it in the Harness log rather than the Agent
+ * Log: two drivers in one log read as one muddle and credited the agent with the Harness's steps. A
+ * `summary` line (a run starting or ending) is shown in the Agent Log too, because the agent that
+ * asked for the run reports its result.
+ */
+import { CommandActor } from '@reticlehq/core';
+export function narrationArgs(text, by) {
+    return {
+        text,
+        level: 'info',
+        ...(by === undefined ? {} : { actor: CommandActor.HARNESS }),
+        ...(true === by?.summary ? { summary: true } : {}),
+    };
+}

package/dist/portal/session/no-session-diagnosis.d.ts

@@ -166,6 +166,13 @@ export interface NoSessionFacts {
      * or the ring has forgotten — inventing a URL is worse than the silence this exists to end.
      */
     lastKnownUrl?: string;
+    /**
+     * Where the departed tab was seen heading, when the SDK reported a navigation just before the
+     * socket closed (#1256). Separate from `lastKnownUrl` — the old origin — because the 5xx probe
+     * and successor matching need the page the tab was ON, while the diagnosis needs where it was
+     * GOING. Absent unless the departure note arrived fresh.
+     */
+    departedTo?: string;
     /**
      * What a plain GET of `lastKnownUrl` answered, done out of band by the watch after the session
      * went. The one fact that separates a server error from a closed tab and from an install
@@ -179,7 +186,7 @@ export interface NoSessionFacts {
  * recovery: a message that already carries its own next action must not be handed a second, more
  * generic one that contradicts it.
  */
-export declare const SELF_RECOVERING_MARKER = "Then call reticle_sessions again \u2014 it will appear within a second of the page loading.";
+export declare const SELF_RECOVERING_MARKER = "Then call reticle_session { action: \"list\" } again \u2014 it will appear within a second of the page loading.";
 /**
  * The diagnosis, and the CODE for the branch that produced it.
  *