@reticlehq/server 3.6.0 → 3.7.0

package/dist/portal/session/dev-server/dev-command.js

@@ -10,7 +10,7 @@
  */
 import { readFileSync, readdirSync } from 'node:fs';
 import { join } from 'node:path';
-import { desktopLaunch, workspacePackageDirs } from '@reticlehq/init';
+import { RETICLE_NPM_PACKAGE, desktopLaunch, workspacePackageDirs } from '@reticlehq/init';
 /**
  * Script names checked, in order.
  *
@@ -23,7 +23,17 @@ const DEV_SCRIPTS = ['dev', 'develop', 'start'];
 const LOCKFILES = [
     { file: 'pnpm-lock.yaml', manager: 'pnpm' },
     { file: 'yarn.lock', manager: 'yarn' },
+    { file: 'bun.lockb', manager: 'bun' },
+    { file: 'bun.lock', manager: 'bun' },
 ];
+/** The one-off runner each manager ships, for running Reticle's CLI without installing it. */
+const RUNNER = { pnpm: 'pnpm dlx', bun: 'bunx' };
+const NPX = 'npx';
+const YARN = 'yarn';
+/** `yarn dlx` exists only on Yarn 2+, which is the yarn that writes this file; classic yarn has none. */
+const YARN_BERRY_MARKER = '.yarnrc.yml';
+const YARN_DLX = 'yarn dlx';
+const INIT_VERB = 'init';
 const DEFAULT_PACKAGE_MANAGER = 'npm';
 const PACKAGE_JSON = 'package.json';
 /** `--port 4311` / `--port=4311`, the flag every dev server in this list accepts. */
@@ -154,3 +164,19 @@ export function detectDevCommandInProject(directory, read = readTextFile, listDi
     }
     return undefined;
 }
+/**
+ * The command that wires THIS project for good: `init`, in the app's own folder, through the
+ * one-off runner the project's package manager ships.
+ *
+ * Handed to an agent whose install never ran `init` (an MCP-only route), so it has to be right first
+ * time: `init` run in a folder that is not the app stops on a missing package.json, and a runner the
+ * machine does not have is "command not found". npx whenever there is doubt — it ships with Node.
+ */
+export function initCommandIn(directory, read = readTextFile, listDirs = readDirNames) {
+    const manager = packageManager(directory, read);
+    const berry = read(join(directory, YARN_BERRY_MARKER)) !== undefined;
+    const runner = YARN === manager ? (berry ? YARN_DLX : NPX) : (RUNNER[manager] ?? NPX);
+    const command = `${runner} ${RETICLE_NPM_PACKAGE} ${INIT_VERB}`;
+    const app = detectDevCommandInProject(directory, read, listDirs)?.directory;
+    return app === undefined ? command : `cd ${app} && ${command}`;
+}

package/dist/portal/session/facts/observed-state.d.ts

@@ -1,21 +1,5 @@
 import { type ReticleEvent } from '@reticlehq/core';
 import { type AmbientCounts } from '@reticlehq/engine/window/ambient.js';
-/**
- * The two things a session learns by watching its own event stream, as opposed to storing.
- *
- * Both are LEVELS derived from a stream, and both have to outlive the ring buffer — which is what
- * separates them from the buffer's job and earns them their own unit:
- *
- *   ambient    — which regions of the page move on their own (chat, tickers, live counters). Used by
- *                the settle oracle to ignore background motion, so an action isn't held open forever
- *                by churn it did not cause.
- *   blindSpots — how much of the page the SDK cannot observe (cross-origin frames, closed shadow
- *                roots). The SDK reports these only when the count CHANGES, so a page that mounts
- *                two frames at load announces them once and is silent forever after. Anything that
- *                infers coverage from a window of events therefore sees nothing and concludes the
- *                page was fully observed — a positive claim to have seen what we cannot see. Holding
- *                the level here makes coverage something to ask rather than infer.
- */
 export declare class ObservedState {
     #private;
     /** Fold one already-attributed event into the learned state. */
@@ -57,8 +41,22 @@ export declare class ObservedState {
      * dropped before they reached the observer. Recording it here keeps the honesty contract intact —
      * a verdict over a sampled window says `coverage: partial` rather than implying it saw everything.
      */
-    noteRateLimited(dropped: number): void;
-    blindSpots(): Readonly<Record<string, number>>;
+    noteRateLimited(dropped: number, at?: number): void;
+    /**
+     * How many events the bridge sampled away at or after `since` (session-elapsed ms).
+     *
+     * A bucket is counted when any part of its second reaches the window, so a drop in the same
+     * second as the window's start still impeaches it: erring toward unclean is the safe direction.
+     */
+    rateDroppedSince(since: number): number;
+    /**
+     * The blind spots, session-wide; or, given `since`, with bridge sampling counted only from then on.
+     *
+     * Coverage reads the session-wide view: that sampling happened at all is a fact about the session.
+     * A verdict deciding whether ITS capture is clean reads the windowed one. Read session-wide there,
+     * one early burst made every later verdict on the tab `unclean_capture` (#1414).
+     */
+    blindSpots(since?: number): Readonly<Record<string, number>>;
 }
 /**
  * The snapshot-shaped labels an act reply names its control by: the testid, and `role "name"`.

package/dist/portal/session/facts/observed-state.js

@@ -16,12 +16,18 @@ import { ambientKeyOf } from '@reticlehq/engine/window/ambient.js';
  *                page was fully observed — a positive claim to have seen what we cannot see. Holding
  *                the level here makes coverage something to ask rather than infer.
  */
+/** The resolution rate-limit drops are kept at: per second of session time. */
+const RATE_DROP_BUCKET_MS = 1000;
+/** An hour of seconds; older buckets are past any window a verdict reads. */
+const MAX_RATE_DROP_BUCKETS = 3600;
 export class ObservedState {
     /** What THIS session observed. Never contains seeded history — see seedAmbient. */
     #ownAmbient = {};
     /** What previous sessions learned, kept separate so it is never re-persisted as if newly seen. */
     #seededAmbient = {};
     #blindSpots = {};
+    /** Bridge-side sampling, by second of session time. See noteRateLimited. */
+    #rateDrops = [];
     /** Fold one already-attributed event into the learned state. */
     observe(event) {
         // Only UNATTRIBUTED events count as ambient: an event caused by an action is the action's work,
@@ -124,11 +130,48 @@ export class ObservedState {
      * dropped before they reached the observer. Recording it here keeps the honesty contract intact —
      * a verdict over a sampled window says `coverage: partial` rather than implying it saw everything.
      */
-    noteRateLimited(dropped) {
+    noteRateLimited(dropped, at) {
+        const before = this.#blindSpots[BlindSpotKind.RATE_LIMITED] ?? 0;
         this.#blindSpots[BlindSpotKind.RATE_LIMITED] = dropped;
+        // WHEN, beside how many: the running total above is a fact about the session, and read as one
+        // it made every verdict after a single burst `unclean_capture`, however quiet its own window
+        // was (#1414). Bucketed per second so a sustained flood stays a bounded list.
+        if (at === undefined || dropped <= before)
+            return;
+        const second = Math.floor(at / RATE_DROP_BUCKET_MS) * RATE_DROP_BUCKET_MS;
+        const last = this.#rateDrops[this.#rateDrops.length - 1];
+        if (last !== undefined && last.at === second)
+            last.count += dropped - before;
+        else
+            this.#rateDrops.push({ at: second, count: dropped - before });
+        if (this.#rateDrops.length > MAX_RATE_DROP_BUCKETS)
+            this.#rateDrops.shift();
     }
-    blindSpots() {
-        return this.#blindSpots;
+    /**
+     * How many events the bridge sampled away at or after `since` (session-elapsed ms).
+     *
+     * A bucket is counted when any part of its second reaches the window, so a drop in the same
+     * second as the window's start still impeaches it: erring toward unclean is the safe direction.
+     */
+    rateDroppedSince(since) {
+        let total = 0;
+        for (const bucket of this.#rateDrops) {
+            if (bucket.at + RATE_DROP_BUCKET_MS > since)
+                total += bucket.count;
+        }
+        return total;
+    }
+    /**
+     * The blind spots, session-wide; or, given `since`, with bridge sampling counted only from then on.
+     *
+     * Coverage reads the session-wide view: that sampling happened at all is a fact about the session.
+     * A verdict deciding whether ITS capture is clean reads the windowed one. Read session-wide there,
+     * one early burst made every later verdict on the tab `unclean_capture` (#1414).
+     */
+    blindSpots(since) {
+        if (since === undefined)
+            return this.#blindSpots;
+        return { ...this.#blindSpots, [BlindSpotKind.RATE_LIMITED]: this.rateDroppedSince(since) };
     }
 }
 /**

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/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?
  *
@@ -37,6 +70,15 @@ function endingTurnWithNothingAttached(deps, id) {
 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,
@@ -44,9 +86,14 @@ export const LIVE_CONTROL_TOOLS = [
             '(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. ' +
             "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.',
+            '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()
@@ -59,6 +106,10 @@ export const LIVE_CONTROL_TOOLS = [
             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()
@@ -68,10 +119,13 @@ 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);
@@ -107,7 +161,13 @@ 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));
@@ -116,13 +176,24 @@ export const LIVE_CONTROL_TOOLS = [
                 session.setState(SessionState.ENDED, 0 === panel.length ? undefined : panel.join('\n'));
                 if (detach)
                     deps.sessions.park(session);
-                return {
+                const answer = {
                     ended: true,
                     sessionId: session.id,
                     ...(detach ? { disconnected: true } : {}),
                     gap,
-                    talk_to_us: DiscoveryInvite.AGENT,
+                    // 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 };
             });
         },
     },
@@ -160,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
@@ -227,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

@@ -186,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.
  *

package/dist/portal/session/no-session-diagnosis.js

@@ -17,6 +17,7 @@ import { leaseCaveat } from './presence/lease-availability.js';
 import { DEV_SERVER_PORTS } from '../../command/cli/ports/resolve/cli-port.js';
 import { siblingListenerNote } from '../../command/cli/ports/sibling-ports.js';
 import { STALL_AFTER_MS } from './stall-clock.js';
+import { departedPortGone } from './no-session-next-action.js';
 import { pageTornDownWhileOn } from '@reticlehq/engine/evidence/page-teardown.js';
 /** How every hello-refusal reason the bridge records separates its cause from its fix. */
 const CAUSE_FIX_SEPARATOR = ' — ';
@@ -29,7 +30,7 @@ const NUXT = 'nuxt';
  * recovery: a message that already carries its own next action must not be handed a second, more
  * generic one that contradicts it.
  */
-export const SELF_RECOVERING_MARKER = 'Then call reticle_sessions again — it will appear within a second of the page loading.';
+export const SELF_RECOVERING_MARKER = 'Then call reticle_session { action: "list" } again — it will appear within a second of the page loading.';
 const RETRY = SELF_RECOVERING_MARKER;
 /**
  * The no-shell path, for the branches where a BLIND lease would be wrong.
@@ -62,12 +63,21 @@ function leaseAdvice(base, facts) {
 /**
  * The way out that needs no human at all.
  *
- * Only offered when the app is known to carry the SDK: leasing an uninstrumented app just burns a
- * browser and comes back `ready:false`.
+ * Offered here when the app is known to carry the SDK. An app that carries none is offered
+ * {@link ZERO_INSTALL} instead, which says what a lease on it can and cannot see.
  */
 const SELF_SERVE = 'You do not have to wait for the human: reticle_lease {action:"acquire", url} opens a browser ' +
     'Reticle drives itself, and returns a sessionId you can use immediately (reach it with ' +
     'reticle_run {tool:"reticle_lease"} if it is not advertised directly; release it when you finish).';
+/**
+ * The way past an app nobody wired, without waiting for the wiring.
+ *
+ * A lease on a page that never dials in hands it the zero-install reader, so an MCP-only install
+ * (a plugin, a hand-written `npx … mcp` config — `init` never ran) still gets a verdict on the first
+ * call instead of a diagnosis it stops at. The URL and the command live in the next action.
+ */
+const ZERO_INSTALL = 'You can get a verdict NOW with nothing installed: reticle_lease on the app URL supplies the ' +
+    'SDK itself (no component state or source file:line until it is wired) — the next action names it.';
 /** The hedge that is true for every vanished tab we did not watch leave. */
 const TAB_GONE_WHAT = 'The tab was closed, navigated away, or hard-reloaded.';
 /**
@@ -324,11 +334,12 @@ function alreadyListeningClause(listening) {
         return '';
     if (1 === listening.length) {
         const port = listening[0];
-        return (` An app is already listening on ${String(port)}; just open http://localhost:${String(port)} ` +
-            '— do not start a second stack.');
+        return (` Something is serving a page on :${String(port)}; it may not be this app — just open ` +
+            `http://localhost:${String(port)} rather than starting a second stack.`);
     }
-    return (` An app is already listening on ${listening.join(', ')}; just open one of those URLs — do not ` +
-        'start a second stack.');
+    const ports = listening.map((p) => `:${String(p)}`).join(', ');
+    return (` Something is serving a page on ${ports}; those listeners may not be this ` +
+        'app — open the URL that belongs to this project rather than starting a second stack.');
 }
 /**
  * The diagnosis, and the CODE for the branch that produced it.
@@ -419,6 +430,16 @@ export function explainNoSession(facts) {
                 `problem. Ask the human to go back to the app${orOpenCommand(facts)}, or reload the tab. ` +
                 `${leaseAdvice(SELF_SERVE, facts)} ${RETRY}`, alreadyListeningClause(listening).trim());
         }
+        // The dev server that served this session has stopped: the departed session's own port no
+        // longer answers, so "ask the human to reopen the app" points at a dead socket. Keyed on that
+        // port, as the next action is (#1421) — the prose and the executable half agree on the story.
+        // No "already listening" clause: whatever else answers is not where this app was.
+        if (facts.lastKnownUrl !== undefined && departedPortGone(facts)) {
+            return reason(NoSessionReason.TAB_GONE, 'no browser session connected, but one WAS connected to this daemon earlier, so the wiring ' +
+                `is correct. ${tabGoneWhat(facts.lastKnownUrl)} The dev server that served it has stopped ` +
+                '— nothing answers on that port any more — so start the app again (the command is in ' +
+                `\`next_action\`). ${RETRY}`);
+        }
         return reason(NoSessionReason.TAB_GONE, 'no browser session connected, but one WAS connected to this daemon earlier, so the wiring ' +
             `is correct. ${tabGoneWhat(facts.lastKnownUrl)} Ask the human to reopen ` +
             `the app${orOpenCommand(facts)}, or reload the tab. ${leaseAdvice(SELF_SERVE, facts)} ${RETRY}`, alreadyListeningClause(listening).trim());
@@ -464,7 +485,8 @@ export function explainNoSession(facts) {
                 'dev server may not be running: START IT YOURSELF, in the background, using the command ' +
                 'in `next_action`, and tell the human in one line that it is running. ' +
                 `(2) There is no \`.reticle.json\` in ${where}, which is the file ${INIT_CMD} writes, so ` +
-                `the app may carry no Reticle SDK. Check the app's OWN directory before re-running it. ${RETRY}`, `The scan covers ${SCANNED_PORTS} and nothing else, so a server on any other port is ` +
+                `the app may carry no Reticle SDK. Check the app's OWN directory before re-running it. ` +
+                `${ZERO_INSTALL} ${RETRY}`, `The scan covers ${SCANNED_PORTS} and nothing else, so a server on any other port is ` +
                 'invisible to it: if the app IS running, ask for its URL rather than assuming it is down, ' +
                 `and open it with ${OPEN_CMD}. The missing config is not proof either — in a monorepo the ` +
                 'daemon often runs at the root while the app lives in a subdirectory, and an app wired by ' +
@@ -495,7 +517,7 @@ export function explainNoSession(facts) {
             `${INIT_CMD} writes, so the app may carry no Reticle SDK. Check the app's OWN directory: ` +
             `if it has no config, run ${INIT_CMD} ` +
             'there and restart the dev server; if it has one, the app is wired and simply has no page ' +
-            `open — ${OPEN_CMD}. ${RETRY}`, 'That absence is not proof: the same one is expected in a monorepo whose daemon runs at the ' +
+            `open — ${OPEN_CMD}. ${ZERO_INSTALL} ${RETRY}`, 'That absence is not proof: the same one is expected in a monorepo whose daemon runs at the ' +
             'root while the app lives in a subdirectory, or in an app wired by the Vite or Babel ' +
             `plugin. ${unattributedListeners(listening)}${searchedClause(facts)}${siblingListenerClause(facts)}`);
     }

package/dist/portal/session/no-session-next-action.d.ts

@@ -87,13 +87,33 @@ interface NextActionFacts {
      * its one hit is as likely to be another repo's dev server as this one's.
      */
     lastKnownUrl?: string;
+    /** Ports that accepted a connection and answered nothing in time: up, not gone. */
+    slowListeners?: readonly number[];
     /**
      * Where the departed tab was seen heading, when the SDK reported it fresh (#1256). The
      * next-action reason must agree with the diagnosis: when this is present the tab was not
      * closed, it navigated away.
      */
     departedTo?: string;
+    /**
+     * The command that wires THIS project for good — `init` in the app's own folder through the
+     * project's own runner (see `initCommandIn`). Absent means the generic npx spelling.
+     */
+    init?: string;
 }
+/** The port a tombstone URL names, when it names one — anything unparseable names no port. */
+export declare function portOfUrl(url: string): number | undefined;
+/**
+ * The departed session's own port no longer answers. Direct evidence, because the scan always
+ * covers that port — unlike an empty scan, which proves nothing the moment another project
+ * happens to be listening (#1421). A slow listener is up, not gone, and a url with no explicit
+ * port was never scanned, so neither counts.
+ */
+export declare function departedPortGone(facts: {
+    lastKnownUrl?: string;
+    listening: readonly number[];
+    slowListeners?: readonly number[];
+}): boolean;
 export declare function nextActionFor(facts: NextActionFacts): NoSessionNextAction;
 /** The same action as one sentence, for the prose message the human reads. */
 export declare function renderNextAction(next: NoSessionNextAction): string;