@reticlehq/server 3.5.0 → 3.7.0

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

@@ -10,17 +10,20 @@
  * daemon that outlives the agent by hours has no business scanning ports it does not need.
  */
 import { probeRouteStatus } from './dev-server/route-status-probe.js';
-import { probeDevServers, probeDevServerStates } from './dev-server/dev-server-probe.js';
+import { probeDevServerStates } from './dev-server/dev-server-probe.js';
+import { existsSync } from 'node:fs';
 import { homedir } from 'node:os';
+import { join, resolve } from 'node:path';
+import { callingClientDirectory } from '../../hooks/client-directory.js';
 import { registeredElsewhere } from '../../memory/recall/registered-projects.js';
 import { explainNoSession } from './no-session-diagnosis.js';
-import { detectDevCommand } from './dev-server/dev-command.js';
-import { nextActionFor, renderNextAction } from './no-session-next-action.js';
-import { readProjectFramework, readProjectId, readProjectIsDesktop, readProjectPort, } from '../../command/cli/ports/resolve/cli-port.js';
+import { detectDevCommandInProject, initCommandIn } from './dev-server/dev-command.js';
+import { nextActionFor, portOfUrl, renderNextAction } from './no-session-next-action.js';
+import { DEV_SERVER_PORTS, readProjectFramework, readProjectId, readProjectIsDesktop, readProjectPort, } from '../../command/cli/ports/resolve/cli-port.js';
 import { discoverProjectConfigs } from '../../command/cli/config/config-discovery.js';
 import { hasProjectConnectedBefore, rememberConnected, } from '../../memory/recall/prior/connection-memory.js';
 import { isAlive, reticleStateHome } from '../../command/daemon/daemon.js';
-import { daemonsServingProjectElsewhere, splitBrainNote } from '../../command/daemon/daemon-resolve.js';
+import { daemonsServingProjectElsewhere, projectDaemonsElsewhere, projectlessNote, splitBrainNote, } from '../../command/daemon/daemon-resolve.js';
 import { stallUptime } from './stall-clock.js';
 import { probeDaemon } from '../../surface/mcp/mcp-proxy.js';
 import { findOccupiedSiblings } from '../../command/cli/ports/sibling-ports.js';
@@ -54,8 +57,9 @@ function attachFailureClause(port, reason) {
  * through `wireSessionScope`.
  */
 export function startNoSessionWatch(options) {
-    const probe = options.probe ?? (() => probeDevServers());
     let listening = [];
+    /** Ports the last scan was asked about. A port absent from this set was not observed, so it is not "down". */
+    let probed = new Set();
     /**
      * Ports that accepted a connection and then answered nothing in time.
      *
@@ -81,6 +85,7 @@ export function startNoSessionWatch(options) {
     /** Set only when an attempt actually failed, so the diagnosis can say so instead of hiding it. */
     let attachFailure;
     const directory = options.directory ?? process.cwd();
+    const exists = options.exists ?? ((file) => existsSync(join(directory, file)));
     // The boot answer still counts (it is what the daemon scoped its sessions with), but `.reticle.json`
     // is routinely written by `init` AFTER this daemon started, so re-read rather than cache. See the
     // `initialized` comment below, which this shares.
@@ -144,8 +149,11 @@ export function startNoSessionWatch(options) {
      * this one starts, which is precisely the window the agent then spends being told to start a dev
      * server that is already running.
      */
-    const splitBrain = () => {
-        const projectId = readProjectId(directory);
+    const splitBrain = (dir = directory) => {
+        const projectId = readProjectId(dir);
+        if (projectId === undefined) {
+            return projectlessNote(options.port, projectDaemonsElsewhere(options.port, stateDir, isAlive));
+        }
         return splitBrainNote(options.port, daemonsServingProjectElsewhere(projectId, options.port, stateDir, isAlive, (port) => hasProjectConnectedBefore(stateDir, port, projectId)));
     };
     // Every path that registers a session goes through SessionManager.add, so this is the one hook
@@ -172,6 +180,36 @@ export function startNoSessionWatch(options) {
             projectId: readProjectId(directory),
             root: directory,
         }).map((entry) => entry.port));
+    /**
+     * The ports the background scan must cover: the well-known list plus the facts that name THIS
+     * repo's port without guessing it (#1367).
+     *
+     * The scan is machine-wide, so it knows 3000/5173/8080… and nothing about this checkout: with a
+     * Next app already running on :3005 (`next dev -p 3005`) the diagnosis said nothing was listening
+     * and named a command that would have started a duplicate. Three facts name the port instead —
+     * the project's own dev script pins it in its own text, the build plugins announced theirs
+     * (already trusted for auto-attach), and the last session was on one.
+     */
+    const scanPorts = () => {
+        const ports = new Set(DEV_SERVER_PORTS);
+        for (const port of ownDevServerPorts())
+            ports.add(port);
+        const pinned = detectDevCommandInProject(directory)?.port;
+        if (pinned !== undefined)
+            ports.add(pinned);
+        const known = options.sessions.lastKnown?.();
+        const knownPort = known === undefined ? undefined : portOfUrl(known.url);
+        if (knownPort !== undefined)
+            ports.add(knownPort);
+        // Every departed project, not only the newest. B can still be serving on :3005 after A leaves
+        // on :5173, and a scan that never asked :3005 would report B's app as stopped.
+        for (const url of options.sessions.tombstoneUrls?.() ?? []) {
+            const port = portOfUrl(url);
+            if (port !== undefined)
+                ports.add(port);
+        }
+        return [...ports];
+    };
     /**
      * Is `port` demonstrably this project's app? Either its dev server announced it, or this
      * project's own last session was on it. Anything else is a guess, and a guess that opens a
@@ -214,17 +252,22 @@ export function startNoSessionWatch(options) {
         }
     };
     const refresh = () => {
-        // Nothing to diagnose while a session is live, and no reason to scan.
+        // Nothing to diagnose while a session is live, and no reason to scan. What the last scan saw
+        // predates this session, so it is no observation of where the session goes on to depart from.
+        if (options.sessions.count() > 0)
+            probed = new Set();
         if (running || options.sessions.count() > 0)
             return;
         running = true;
+        const candidates = scanPorts();
         void (options.probe === undefined
-            ? probeDevServerStates().then((states) => {
+            ? probeDevServerStates(candidates).then((states) => {
                 slowListeners = states.slow;
                 return states.serving;
             })
-            : probe())
+            : options.probe(candidates))
             .then(async (ports) => {
+            probed = new Set(candidates);
             listening = ports;
             siblingListeners =
                 options.occupiedSiblings !== undefined
@@ -287,6 +330,143 @@ export function startNoSessionWatch(options) {
             return undefined;
         return { reason: closure.reason, ...closure.page };
     };
+    /**
+     * The diagnosis for a client standing in a different project than this daemon.
+     *
+     * `everConnected` and the newest tombstone are facts about the process. Spent on a second
+     * project they say that project's wiring is done and name the first project's URL. A directory
+     * that has never had a session of its own has never connected, whatever else this daemon has seen.
+     * Ports count only when this project announced them or its own last session was on them, so the
+     * reopen command cannot fall through to somebody else's dev server.
+     */
+    const diagnosisFor = (dir) => {
+        const projectId = readProjectId(dir);
+        const initialized = projectId !== undefined;
+        // A tab that reported no project cannot be another project's: it is the daemon's own last tab,
+        // never "this daemon has never seen one" beside a refusal that names where it last saw it. A
+        // tab that named another project stays that project's (a second app is not told to reopen it).
+        const newest = options.sessions.lastKnown?.();
+        const unclaimed = newest !== undefined && newest.projectId === undefined ? newest : undefined;
+        const known = (projectId === undefined ? undefined : options.sessions.lastKnownFor?.(projectId)) ??
+            unclaimed;
+        const everConnected = (projectId !== undefined && true === options.sessions.everConnectedTo?.(projectId)) ||
+            unclaimed !== undefined;
+        const ownPorts = new Set(devServersForProject(readDevServers(stateDir), { projectId, root: dir }).map((entry) => entry.port));
+        if (known !== undefined) {
+            const port = portOfUrl(known.url);
+            if (port !== undefined)
+                ownPorts.add(port);
+        }
+        const heard = listening.filter((port) => ownPorts.has(port));
+        // Not in the last scan means we have not looked, not that the server stopped. Treating the
+        // gap as "down" is what tells a still-running app to start a second one.
+        for (const port of ownPorts) {
+            if (!probed.has(port) && !heard.includes(port))
+                heard.push(port);
+        }
+        const slow = slowListeners.filter((port) => ownPorts.has(port));
+        const closure = options.sessions.lastClosure?.();
+        const refusalIsThisProject = closure !== undefined &&
+            true !== options.sessions.connectedSinceLastClosure?.() &&
+            projectId !== undefined &&
+            closure.page?.projectId === projectId;
+        const helloRefused = refusalIsThisProject &&
+            closure !== undefined &&
+            closure.page !== undefined &&
+            !isAuthRefusalReason(closure.reason)
+            ? { reason: closure.reason, ...closure.page }
+            : undefined;
+        const discovery = initialized ? undefined : discoverProjectConfigs(dir);
+        const found = discovery === undefined ? [] : discovery.found.filter((config) => config.directory !== dir);
+        const registered = 0 < found.length ? [] : registeredElsewhere(homedir(), dir);
+        const configsElsewhere = 0 < found.length
+            ? found.map((config) => ({
+                directory: config.directory,
+                ...(config.projectId === undefined ? {} : { projectId: config.projectId }),
+            }))
+            : 0 < registered.length
+                ? registered.map((project) => ({
+                    directory: project.directory,
+                    ...(project.projectId === undefined ? {} : { projectId: project.projectId }),
+                }))
+                : undefined;
+        const framework = readProjectFramework(dir);
+        const configured = readProjectPort(dir);
+        const previouslyConnected = hasProjectConnectedBefore(stateDir, options.port, projectId);
+        const authRefused = refusalIsThisProject && closure !== undefined && isAuthRefusalReason(closure.reason);
+        const status = known !== undefined && lastKnownStatus !== undefined && lastKnownStatus.url === known.url
+            ? { lastKnownStatus: lastKnownStatus.status }
+            : {};
+        const departedTo = known?.departedTo;
+        const departed = departedTo === undefined || '' === departedTo ? {} : { departedTo };
+        const upMs = stallUptime(Date.now());
+        const facts = {
+            everConnected,
+            initialized,
+            ...(configsElsewhere === undefined ? {} : { configsElsewhere }),
+            ...(discovery !== undefined && configsElsewhere === undefined
+                ? { searchedDirectories: discovery.searched }
+                : {}),
+            listening: heard,
+            slowListeners: slow,
+            port: options.port,
+            directory: dir,
+            previouslyConnected,
+            authRefused,
+            ...(helloRefused === undefined ? {} : { helloRefused }),
+            ...(framework === undefined ? {} : { framework }),
+            ...(readProjectIsDesktop(dir) ? { desktop: true } : {}),
+            leaseExpired: known !== undefined && (options.wasReapedLease?.(known.id) ?? false),
+            ...(known === undefined ? {} : { lastKnownUrl: known.url, ...status, ...departed }),
+            ...(upMs === undefined ? {} : { daemonUpMs: upMs }),
+            ...(configured === undefined ? {} : { projectPort: configured }),
+            ...(0 === siblingListeners.length ? {} : { siblingListeners }),
+        };
+        const split = splitBrain(dir);
+        const next = nextActionFor({
+            everConnected,
+            initialized,
+            ...(configsElsewhere === undefined ? {} : { configsElsewhere }),
+            previouslyConnected,
+            exists: (file) => existsSync(join(dir, file)),
+            authRefused,
+            ...(helloRefused === undefined ? {} : { helloRefused: helloRefused.reason }),
+            ...(split === undefined ? {} : { splitBrain: split }),
+            listening: heard,
+            slowListeners: slow,
+            ...(known === undefined
+                ? {}
+                : {
+                    lastKnownUrl: known.url,
+                    ...(known.departedTo === undefined ? {} : { departedTo: known.departedTo }),
+                }),
+            dev: detectDevCommandInProject(dir),
+            init: initCommandIn(dir),
+        });
+        return { facts, next };
+    };
+    /**
+     * A call that named the client's project. Undefined means nobody named one (an embed, a test, a
+     * daemon answering itself), and the path below stays the one this watch was started with.
+     */
+    const callerAnswer = () => {
+        const caller = callingClientDirectory();
+        if (caller === undefined)
+            return undefined;
+        return diagnosisFor(caller);
+    };
+    /**
+     * `listening`, plus the departed session's port when no scan has looked at it since: not looked
+     * at is not stopped. Without it `reticle status` called a running Vite stopped because the only
+     * scan ran before the app was started.
+     */
+    const observedListening = () => {
+        const known = options.sessions.lastKnown?.();
+        const port = known === undefined ? undefined : portOfUrl(known.url);
+        return port === undefined || probed.has(port) || listening.includes(port)
+            ? listening
+            : [...listening, port];
+    };
     const nextAction = (scope) => {
         const split = splitBrain();
         return nextActionFor({
@@ -294,6 +474,7 @@ export function startNoSessionWatch(options) {
             initialized: scope.initialized,
             ...(scope.configsElsewhere === undefined ? {} : { configsElsewhere: scope.configsElsewhere }),
             previouslyConnected: connectedBefore(),
+            exists,
             // Read when asked, like every other fact here: a page can dial at any moment, and a daemon
             // that cached "nothing has been refused" at boot would keep saying so.
             authRefused: lastCloseWasAuthFailure(),
@@ -302,23 +483,37 @@ export function startNoSessionWatch(options) {
                 return refused === undefined ? {} : { helloRefused: refused.reason };
             })(),
             ...(split === undefined ? {} : { splitBrain: split }),
-            listening,
+            listening: observedListening(),
+            slowListeners,
             // The url the departed tab was on — the same tombstone the prose diagnosis quotes, so the
             // command and the sentence beside it name the same page.
             ...(() => {
                 const known = options.sessions.lastKnown?.();
-                return known === undefined ? {} : { lastKnownUrl: known.url };
+                if (known === undefined)
+                    return {};
+                return {
+                    lastKnownUrl: known.url,
+                    ...(known.departedTo === undefined ? {} : { departedTo: known.departedTo }),
+                };
             })(),
             // Read when asked, like everything else here: a `package.json` can gain a dev script, and a
             // daemon that cached "there is none" at boot would keep saying so for the rest of the day.
-            dev: detectDevCommand(directory),
+            dev: detectDevCommandInProject(directory),
+            // This project's own runner and app folder, so the agent can wire it itself.
+            init: initCommandIn(directory),
         });
     };
-    options.sessions.setNoSessionNextAction(() => nextAction(projectScopeFacts()));
+    options.sessions.setNoSessionNextAction(() => {
+        const caller = callerAnswer();
+        return caller === undefined ? nextAction(projectScopeFacts()) : caller.next;
+    });
     // ONE call for both registrations below. The prose and the branch code have to come from the
     // same evaluation or they can describe different branches - the facts are read when asked, so two
     // calls a moment apart can genuinely disagree (#615).
     const explain = () => {
+        const caller = callerAnswer();
+        if (caller !== undefined)
+            return explainNoSession(caller.facts);
         const scope = projectScopeFacts();
         return explainNoSession({
             everConnected: options.sessions.everConnected(),
@@ -329,7 +524,7 @@ export function startNoSessionWatch(options) {
             // framework and its projectId, and whose real problem was a dev server older than the plugin.
             // The boot value still counts: it is the one the daemon scoped its sessions with.
             ...scope,
-            listening,
+            listening: observedListening(),
             slowListeners,
             port: options.port,
             // The directory `initialized` was decided in. Named in the message because "there is no
@@ -375,7 +570,12 @@ export function startNoSessionWatch(options) {
                 const status = lastKnownStatus !== undefined && lastKnownStatus.url === known.url
                     ? { lastKnownStatus: lastKnownStatus.status }
                     : {};
-                return { lastKnownUrl: known.url, ...status };
+                // Where the tab was seen heading, when the SDK reported it fresh. Kept separate from
+                // lastKnownUrl: the 5xx probe needs the page the tab was ON.
+                const departed = known.departedTo === undefined || '' === known.departedTo
+                    ? {}
+                    : { departedTo: known.departedTo };
+                return { lastKnownUrl: known.url, ...status, ...departed };
             })(),
             // How long this daemon has been waiting with no app. The diagnosis uses it to surface
             // "install never finished" — the same condition telemetry already knows about.
@@ -397,6 +597,16 @@ export function startNoSessionWatch(options) {
     // scope facts so a discovered workspace config cannot become an `init` recommendation below it,
     // and both come from ONE `explain()` call so they cannot describe different branches.
     const rendered = () => {
+        const caller = callerAnswer();
+        if (caller !== undefined) {
+            const { message, detail } = explainNoSession(caller.facts);
+            // The attach failure is about the daemon's own project. A call from that project still hears
+            // it. A call from another project must not be told that opening this one failed.
+            const callerDir = callingClientDirectory();
+            const ownProject = callerDir !== undefined && resolve(callerDir) === resolve(directory);
+            const lead = `${message} ${renderNextAction(caller.next)}${ownProject ? (attachFailure ?? '') : ''}`;
+            return { lead, full: undefined === detail ? lead : `${lead} ${detail}` };
+        }
         const scope = projectScopeFacts();
         const { message, detail } = explain();
         const lead = `${message} ${renderNextAction(nextAction(scope))}${attachFailure ?? ''}`;

package/dist/portal/session/presence/session-lease.js

@@ -8,7 +8,7 @@
  *
  * Any edit here is a per-session tax on every user: say it in as few words as still work.
  */
-const SESSION_LEASE_NOTICE = 'When you stop driving, call reticle_session {action:"yield", mode:"waiting"|"ask"}. The panel reads "live" until you do. {action:"end"} when the task is done; it revives on your next action.';
+const SESSION_LEASE_NOTICE = 'When you stop driving, call reticle_session {action:"yield", mode:"waiting"|"ask"}. The panel reads "live" until you do. {action:"end"} only when the task is done: it is final.';
 export function buildSessionLease(sessionId, openedAt) {
     return { sessionId, opened_at: openedAt, IMPORTANT: SESSION_LEASE_NOTICE };
 }

package/dist/portal/session/presence/session-mirror.js

@@ -19,4 +19,7 @@ export function mirroredNarration(sessionId, text) {
 export const MIRRORED_COMMANDS = new Set([
     ReticleCommand.NARRATE,
     ReticleCommand.IMPACT,
+    // A replay usually reloads the page, so its progress has to reach whichever tab is there now.
+    ReticleCommand.FLOW_PROGRESS,
+    ReticleCommand.PLAN,
 ]);

package/dist/portal/session/recorded-gaps.d.ts

@@ -0,0 +1,97 @@
+import type { InboxMessage } from './human/live-control.js';
+import { type Coverage, CoverageCapability, type ImpactSnapshot } from '@reticlehq/core';
+export interface RecordedGap {
+    kind: string;
+    missing: string;
+    fix: string;
+    seenAt: number;
+    cost?: string;
+    ref?: string;
+    source?: string;
+}
+/** Remember gaps a verdict on this session just reported. Malformed entries are skipped. */
+export declare function recordGaps(sessionId: string, gaps: readonly object[], now: number): void;
+/** A tab as the notes below key it: its session, and the app it shows. */
+export interface NotedTab {
+    readonly id: string;
+    readonly projectId?: string | undefined;
+    readonly url?: string | undefined;
+}
+/** A verdict on this tab named a file:line: source mapping is seen, whatever else lacks one. */
+export declare function noteSourceSeen(tab: NotedTab, source: string | undefined): void;
+/** An acted element carried a test id: the app uses them, whatever one control lacks. */
+export declare function noteTestidSeen(tab: NotedTab, testid: string | undefined): void;
+/** What an act result says about the element it reached: its test id and its source stamp. */
+export declare function noteActedElement(tab: NotedTab, result: unknown): void;
+/**
+ * An act's result, passed through after noting what it says about the element it reached. Every act
+ * dispatches through one function, so coverage sees test ids and source stamps from the first
+ * control acted on rather than only from a verdict.
+ */
+export declare function notedAct<T extends {
+    ok: boolean;
+    result?: unknown;
+}>(tab: NotedTab, done: T): T;
+/** A tab the daemon can ask. Absent `command`: a test double or a tab with no page to ask. */
+export interface ProbedTab extends NotedTab {
+    command?(name: string, args?: Record<string, unknown>, timeoutMs?: number): Promise<{
+        ok: boolean;
+        result?: unknown;
+    }>;
+}
+/**
+ * Ask each page whose app has not shown both markers yet what it carries. What an act happens to
+ * reach decides nothing then: an app with test ids is seen to have them before anything acted, and a
+ * hidden tab of it says the same. A page that cannot answer (an older SDK, a closed tab) is skipped.
+ * True when a page showed something not known before.
+ */
+export declare function probeMarkers(tabs: readonly ProbedTab[]): Promise<boolean>;
+/** What this session's verdicts recorded, newest first. */
+export declare function recordedGaps(sessionId: string): readonly RecordedGap[];
+/** Forget a session that ended. What its app has shown is kept: it is still that app's. */
+export declare function forgetRecordedGaps(sessionId: string): void;
+/** Forget everything, apps included. For tests. */
+export declare function forgetAllRecordedGaps(): void;
+/** What instrumentation coverage reads off a connected tab. */
+export interface InstrumentedTab extends NotedTab {
+    readonly channels?: readonly string[] | undefined;
+    readonly sourceMapping?: boolean | undefined;
+    /** What the person said to the agent from this tab. Absent on a test double. */
+    inboxHistory?(): readonly InboxMessage[];
+}
+/**
+ * The tab's HELLO channels, plus the `source` marker when an act or verdict mapped a control to
+ * its file:line (seen anywhere is seen) or its page said it carries source mapping, and the
+ * `testid` marker once an acted element carried one — the list the platform report sends and
+ * coverage reads. A build that turned the stamp off has no source marker, whatever was seen.
+ */
+export declare function announcedChannels(tab: InstrumentedTab): string[];
+/**
+ * The coverage capabilities that do not apply to this tab's app, excluded from both sides of the
+ * score: file:line on a page that said it cannot apply there (plain HTML), until a stamp shows up.
+ * The platform reads the same list from the local-apps report, so both sides move together.
+ */
+export declare function notApplicableOf(tab: NotedTab): CoverageCapability[];
+/** Whether the Harness may drive this tab's app (see core's `instrumentation-coverage.ts`), as pushed. */
+export interface TabHarnessGate {
+    percent: number;
+    unlocked: boolean;
+    reason?: string;
+}
+/**
+ * This tab's coverage and its Harness gate, with the coding-agent prompt when its verdicts recorded
+ * any gap or the gate is shut: below the gate the prompt names every unseen capability, so there is
+ * always something to hand the agent.
+ */
+export declare function instrumentationOf(tab: InstrumentedTab, 
+/** The app's other tabs: what any of them has seen or recorded counts, as on the platform. */
+siblings?: readonly InstrumentedTab[]): Coverage & {
+    prompt?: string;
+    harnessGate: TabHarnessGate;
+};
+/**
+ * The impact snapshot a tab is pushed, carrying that tab's own coverage, running drive and agent
+ * link (who is attached, and this tab's notes to them). Every
+ * push needs the drive: one without it reads as "no drive", and the drive's own tool calls push.
+ */
+export declare function withInstrumentation(tab: InstrumentedTab, snapshot: ImpactSnapshot): ImpactSnapshot;