@reticlehq/server 3.5.0 → 3.7.0

package/dist/portal/session/session.js

@@ -1,9 +1,12 @@
 import { asProjectId } from '@reticlehq/core';
+import { narrationArgs } from './narration-args.js';
 import { refusedResult } from './page-commands/undeclared-command.js';
-import { recordImpact } from '../../memory/impact/impact-recorder.js';
+import { impactSnapshot, recordImpact } from '../../memory/impact/impact-recorder.js';
+import { callingAgent } from '../../hooks/coding-agents.js';
+import { recordNotes } from './human/notes-ledger.js';
+import { commandPayload } from './command-payload.js';
 import { LastAct } from './last-act.js';
 import { GapLedger } from '@reticlehq/engine/evidence/gap-ledger.js';
-import { CaptureLedger } from '../../surface/tools/feature-capture.js';
 import { commandTimeoutMessage } from './timing/command-timeout.js';
 import { readHealthEvent, healthNotices } from './session-health.js';
 import { MIRRORED_COMMANDS, mirroredNarration } from './presence/session-mirror.js';
@@ -12,18 +15,21 @@ const IMPACT_PUSH_DEBOUNCE_MS = 700;
 import { PendingCommands, CommandTimeoutError } from './page-commands/pending-commands.js';
 import { span } from '../../trace.js';
 import { keepCallerContextInDaemon, noteToDaemonLog } from './daemon-answers.js';
-import { isKnownRealm, EventType, HumanControlDataSchema, HumanControlKind, HumanMarkDataSchema, HudUseDataSchema, ReticleCommand, MessageKind, parseEventPayload, PresenterTone, SESSION_HEALTH, SESSION_LEASE, SESSION_LIFECYCLE, SessionState, } from '@reticlehq/core';
+import { isKnownRealm, EventType, HumanControlDataSchema, HumanControlKind, HumanMarkDataSchema, HudUseDataSchema, ReticleCommand, parseEventPayload, PresenterTone, SESSION_HEALTH, SESSION_LEASE, SESSION_LIFECYCLE, SessionState, } from '@reticlehq/core';
 import { RingBuffer } from '@reticlehq/engine/window/ring-buffer.js';
 import { readJournalWriteLoss, readQueryEvents, windowLost, } from '../../memory/journal/journal-query.js';
 import {} from '@reticlehq/engine/window/ambient.js';
 import { ObservedState, controlLabelsOf } from './facts/observed-state.js';
-import { recordBrowserLatency, recordHudUse, recordSdkFailure, } from '../../telemetry/session-metrics.js';
+import { DepartureNote } from './facts/departure-note.js';
+import { recordBrowserLatency, recordSdkFailure } from '../../telemetry/session-metrics.js';
+import { noteHudTabClosed, noteHudTabHidden, reportHudUse } from '../../telemetry/hud-events.js';
 import { LiveControl } from './human/live-control.js';
 import { ReviewStore } from './human/review-store.js';
 import { buildSessionRecommendation } from './presence/session-recommendation.js';
 import { buildPresenterArgs } from './human/presenter-args.js';
 import { buildSessionLease } from './presence/session-lease.js';
 import { buildSessionInfo } from './session-info.js';
+import { notedAct, probeMarkers, withInstrumentation } from './recorded-gaps.js';
 import { MAX_SUCCESSOR_HOPS, REBINDABLE_COMMANDS } from './rebind.js';
 const DEFAULT_COMMAND_TIMEOUT_MS = 8000;
 /** Prefix on correlated command ids (c1, c2, …) — distinguishes them from mark ids. */
@@ -54,13 +60,8 @@ export class Session {
     projectId;
     /**
      * The `.reticle` directory this session's evidence belongs in — impact counters AND capsules.
-     *
-     * Stamped once when the session is created, from the project it declared in HELLO, rather than
-     * resolved per call: the answer cannot change while the tab is connected, and resolving it once
-     * means every counter that fires for this session agrees about where it goes.
-     *
-     * Undefined when nothing could name a project — the caller then falls back to the daemon's own
-     * root, which is what every counter did unconditionally before this existed.
+     * Stamped once, from the project it declared in HELLO, so every counter agrees where it goes.
+     * Undefined when nothing could name a project: callers fall back to the daemon's own root.
      */
     artifactRoot;
     /**
@@ -99,6 +100,8 @@ export class Session {
     /** Which browser the page said it is (chrome/edge/arc/…). Undefined on an SDK too old to report one. */
     #brand;
     #focused = true;
+    /** The desktop window this is and its document's HTTP status, merged from every PAGE_HEALTH. */
+    page = {};
     /** Liveness: wall-clock of the last AGENT command (distinct from browser chatter / lastSeen). */
     #lastAgentActivityAt;
     /** Server-side mirror of the agent-tuned idle window, so the reaper honors reticle_session. */
@@ -107,9 +110,10 @@ export class Session {
     #autoEnded = false;
     #live = new LiveControl();
     /** Human review marks: mistakes the human pinned to elements, for the agent to drain and fix. */
-    #review = new ReviewStore();
-    /** Whether the session_lease has already been returned (fire-once per session). */
-    #firstCommandDone = false;
+    #review = new ReviewStore((marks) => recordNotes(this.artifactRoot, marks));
+    #firstCommandDone = false; // whether the session_lease has been returned (fire-once)
+    /** The newest journal action: a verdict's screenshot names it, so the run pairs it with its check. */
+    lastActionId;
     /** Durable causal-journal recorder; undefined when journaling is off (opt-out or not yet attached). */
     #journal;
     #activeActionId; // action window, held independently of the journal
@@ -129,6 +133,7 @@ export class Session {
      * A hot update advances it inside the same document. An unstamped event never clears it.
      */
     #editEpoch;
+    #departureNote = new DepartureNote();
     constructor(hello, socket, clock) {
         this.id = hello.sessionId;
         this.projectId = hello.projectId === undefined ? undefined : asProjectId(hello.projectId);
@@ -148,6 +153,9 @@ export class Session {
     elapsed() {
         return this.#clock() - this.#startedAt;
     }
+    departedTo() {
+        return this.#departureNote.read(this.elapsed());
+    }
     /** Mark that the SDK was just heard from. Called on every inbound message. */
     touch() {
         this.#lastSeenAt = this.#clock();
@@ -226,6 +234,7 @@ export class Session {
             runtime: this.#runtime,
             versionSkew: this.versionSkew,
             hidden: this.#hidden,
+            page: this.page,
             health: () => this.health(),
             staleMs: () => this.staleMs(),
             pendingMarkCount: () => this.#review.pendingCount(),
@@ -274,7 +283,7 @@ export class Session {
         if (event.type === EventType.HUD_USED) {
             const use = HudUseDataSchema.safeParse(event.data);
             if (use.success)
-                recordHudUse(use.data);
+                reportHudUse(use.data, this.id);
             return;
         }
         if (event.documentId !== undefined)
@@ -283,6 +292,10 @@ export class Session {
             this.#editEpoch = event.editEpoch;
         if (event.type === EventType.PAGE_HEALTH) {
             const r = readHealthEvent(event.data);
+            Object.assign(this.page, r.page);
+            // A hidden tab's HUD is not being looked at: its time stops until the tab is in front again.
+            if (r.hidden !== undefined)
+                noteHudTabHidden(this.id, r.hidden);
             this.applyHealth(r.hidden ?? this.#hidden, r.focused ?? this.#focused, r.runtime, r.engine, r.brand);
         }
         // The in-page half of Reticle reporting its own failure — recorded like a tool error
@@ -303,8 +316,7 @@ export class Session {
             const parsed = HumanMarkDataSchema.safeParse(event.data);
             if (parsed.success) {
                 this.#review.add(parsed.data, this.elapsed());
-                // The impact record's `marks` field existed and nothing ever wrote it: the report would
-                // have shown a permanent zero next to a page covered in pins.
+                // Without this the report shows a permanent zero next to a page covered in pins.
                 recordImpact({ marks: 1 }, {}, this.artifactRoot);
             }
         }
@@ -316,6 +328,7 @@ export class Session {
             if ('string' === typeof to && to.length > 0)
                 this.url = to;
         }
+        this.#departureNote.observe(event, this.elapsed());
         const t = this.elapsed();
         const stamped = { ...event, t, sessionId: this.id };
         // The recorder attributes the event to the in-flight action (if any) and journals it durably; the
@@ -371,10 +384,10 @@ export class Session {
         return this.#observed.actedRefs();
     }
     noteRateLimited(dropped) {
-        this.#observed.noteRateLimited(dropped);
+        this.#observed.noteRateLimited(dropped, this.elapsed());
     }
-    blindSpots() {
-        return this.#observed.blindSpots();
+    blindSpots(since) {
+        return this.#observed.blindSpots(since);
     }
     /** Learned ambient-churn counts (PredicateSession hook the settle oracle reads). */
     ambientCounts() {
@@ -408,10 +421,7 @@ export class Session {
     async journalWriteLoss() {
         return readJournalWriteLoss(this.#journalReader, this.#buffer);
     }
-    /**
-     * Open an action-attribution window: events observed until finishAction attribute to the returned
-     * action id. Ids are minted independently of command correlation ids so the journal is self-contained.
-     */
+    /** Open an attribution window: events until finishAction carry the returned (journal-own) id. */
     beginAction(tool, args) {
         const actionId = this.#mintActionId();
         // Held here, not only in the journal: with the journal off every event was unattributed, and
@@ -431,7 +441,8 @@ export class Session {
     }
     #mintActionId() {
         this.#actionSeq += 1;
-        return `${ACTION_ID_PREFIX}${String(this.#actionSeq)}`;
+        this.lastActionId = `${ACTION_ID_PREFIX}${String(this.#actionSeq)}`;
+        return this.lastActionId;
     }
     /**
      * How many actions this session has dispatched.
@@ -479,11 +490,6 @@ export class Session {
      * end of it.
      */
     gaps = new GapLedger();
-    /**
-     * The read-only calls the journal does not keep, so "was `reticle_context` ever called" has
-     * something to fold. See surface/tools/feature-capture.ts — it is the only state that instrument adds.
-     */
-    capture = new CaptureLedger();
     // ── Server-authoritative liveness (immune to browser-tab throttling) ──────────────
     /**
      * Stamp the wall-clock of the latest AGENT command (called whenever a tool resolves this session).
@@ -570,13 +576,7 @@ export class Session {
         if (successor !== undefined)
             return successor.command(name, args, timeoutMs);
         const id = this.#pending.nextId(COMMAND_ID_PREFIX);
-        const payload = JSON.stringify({
-            kind: MessageKind.COMMAND,
-            id,
-            sessionId: this.id,
-            name,
-            args,
-        });
+        const payload = commandPayload(id, this.id, name, args);
         // The timeout message is built LAZILY: health can change while a command is in flight, and the
         // diagnosis should describe the page as it was when the command actually gave up.
         const awaited = this.#pending.track(id, timeoutMs, () => commandTimeoutMessage(name, timeoutMs, {
@@ -596,7 +596,7 @@ export class Session {
             // The label is only knowable from the REPLY — the request carries a ref, and a ref dies with
             // the next re-render. Recorded here so coverage survives frameworks that replace nodes.
             if (name === ReticleCommand.ACT)
-                this.recordActedLabelFrom(result);
+                this.recordActedLabelFrom(notedAct(this, result));
             return result;
         })
             .finally(() => recordBrowserLatency(Date.now() - sentAt))
@@ -632,6 +632,7 @@ export class Session {
     /** Reject everything still in flight — used on disconnect. */
     rejectAll(reason, replaced = false) {
         this.#pending.rejectAll(reason, replaced);
+        noteHudTabClosed(this.id);
         for (const listener of this.#disconnectListeners)
             listener();
         this.#disconnectListeners.clear();
@@ -653,13 +654,9 @@ export class Session {
             this.#successor = next;
     }
     /**
-     * The replacement, but only while it can actually answer.
-     *
-     * A successor is recorded once and never cleared, so without this a session that was replaced an
-     * hour ago keeps handing commands to a socket that has since closed — and the caller pays the full
-     * timeout to learn it, turning an instant "session replaced" into a wait. The point of delegating
-     * was to save the caller a round trip; delegating to a dead socket costs them more than the error
-     * did.
+     * The replacement, but only while it can actually answer. A successor is never cleared, so without
+     * this a session replaced an hour ago hands commands to a closed socket and the caller pays the
+     * full timeout to learn it — more than the "session replaced" error it was meant to save.
      */
     #liveSuccessor() {
         // Walked, not just read one hop. Two replacements in quick succession — a page that reloads
@@ -709,13 +706,20 @@ export class Session {
         this.#live.setState(next);
         this.pushPresenter(next, text, tone);
     }
-    /** Push a human note onto the inbox (see LiveControl). */
+    /** Push a human note onto the inbox (see LiveControl); the HUD shows it as sent. */
     pushMessage(text) {
         this.#live.push(text, this.elapsed());
+        this.#repaintNotes();
     }
-    /** Queued human notes, cleared as they are read (delivered-once). */
+    /** Queued human notes, cleared as they are read (delivered-once); the HUD shows them as seen. */
     drainInbox() {
-        return this.#live.drain();
+        const taken = this.#live.drain(callingAgent());
+        if (0 < taken.length)
+            this.#repaintNotes();
+        return taken;
+    }
+    #repaintNotes() {
+        this.pushImpact(() => impactSnapshot(this.artifactRoot), true);
     }
     /** Diagnostic read of the inbox depth (does not clear). */
     inboxSize() {
@@ -755,28 +759,26 @@ export class Session {
         }
     }
     /**
-     * Push the impact record to this tab's HUD.
-     *
-     * Debounced: the record changes on every tool call, and the panel does not need 200 frames to
-     * show a counter going up. The LAST state always lands, because the timer re-reads the store
-     * when it fires rather than capturing a snapshot when it was scheduled.
+     * Push the impact record to this tab's HUD. Debounced (a counter needs no 200 frames); the LAST
+     * state always lands, because the timer re-reads the store when it fires.
      */
     pushImpact(read, immediate = false) {
-        if (immediate) {
-            // A tab that just connected has nothing to show yet, so its first record goes out at once -
-            // waiting a debounce here is a report that reads "nothing recorded" over a month of history.
-            const first = read();
-            if (first !== undefined)
-                this.#post(ReticleCommand.IMPACT, { snapshot: first });
-            return;
-        }
+        const send = () => {
+            const snapshot = read();
+            if (snapshot === undefined)
+                return; // each push carries this tab's own coverage
+            const post = () => this.#post(ReticleCommand.IMPACT, { snapshot: withInstrumentation(this, snapshot) });
+            post();
+            void probeMarkers([this]).then((learned) => learned && post()); // what the page carries
+        };
+        // A new tab's first record goes out at once: debounced, it reads "nothing recorded" over history.
+        if (immediate)
+            return send();
         if (this.#impactTimer !== undefined)
             return;
         this.#impactTimer = setTimeout(() => {
             this.#impactTimer = undefined;
-            const snapshot = read();
-            if (snapshot !== undefined)
-                this.#post(ReticleCommand.IMPACT, { snapshot });
+            send();
         }, IMPACT_PUSH_DEBOUNCE_MS);
         this.#impactTimer.unref?.();
     }
@@ -785,8 +787,17 @@ export class Session {
     }
     /** Fire-and-forget a narration row to the live panel (so a resolved mark shows "✓ fixed"). */
     #impactTimer;
-    pushNarration(text) {
-        this.#post(ReticleCommand.NARRATE, { text, level: 'info' });
+    /** `mirror: false` for a notice about THIS page (its SDK is behind), which every tab says itself. */
+    pushNarration(text, mirror = true, by) {
+        const args = narrationArgs(text, by);
+        if (mirror)
+            this.#post(ReticleCommand.NARRATE, args);
+        else
+            this.#send(ReticleCommand.NARRATE, args);
+    }
+    /** A HUD replay's progress, or the Harness's drive plan: pictures the HUD redraws as they change. */
+    pushView(name, args) {
+        this.#post(name, { ...args });
     }
     /** The one-time lease block on the first agent command, then undefined forever after. */
     takeSessionLease() {
@@ -822,12 +833,9 @@ export class Session {
         this.#viewers = read;
     }
     /**
-     * Fire-and-forget command send — NOT registered in #pending (no correlated result expected).
-     *
-     * Mirrored to this project's other tabs, for the two commands that are a REPORT of what happened
-     * (narration, impact). PRESENTER is deliberately not among them: it is the glow and the lifecycle
-     * that say "the agent is driving THIS tab", and a viewer that showed it would be claiming
-     * something untrue about itself.
+     * Fire-and-forget command send, NOT registered in #pending. Mirrored to this project's other tabs
+     * for the commands that REPORT what happened. PRESENTER is not among them: it says "the agent is
+     * driving THIS tab", and a viewer that showed it would be claiming something untrue about itself.
      */
     #post(name, args) {
         this.#send(name, args);
@@ -862,13 +870,7 @@ export class Session {
                 this.recordActedRef(ref);
         }
         const id = this.#pending.nextId(COMMAND_ID_PREFIX);
-        const payload = JSON.stringify({
-            kind: MessageKind.COMMAND,
-            id,
-            sessionId: this.id,
-            name,
-            args,
-        });
+        const payload = commandPayload(id, this.id, name, args);
         try {
             this.#socket.send(payload);
         }

package/dist/portal/session/timing/command-timeout.js

@@ -1,4 +1,4 @@
-import { realmOf, AppRuntime, isOpaqueOrigin } from '@reticlehq/core';
+import { realmOf, AppRuntime, isOpaqueOrigin, ReticleTool } from '@reticlehq/core';
 /**
  * Inbound silence beyond this means the page may genuinely be wedged; inside it, the SDK has spoken
  * recently enough that "the page is hung" is provably the wrong story. A page that is streaming
@@ -17,6 +17,24 @@ const HIDDEN_ADVICE = 'The page last reported itself hidden, and this is a WKWeb
     'observed on a hidden macOS WKWebView after a pause, even though capture still works; park it ' +
     'off-screen rather than calling hide. If neither fits, the page is reachable but not executing, ' +
     'which is worth reporting.';
+/**
+ * A hidden page in an ordinary browser. Its frames and timers are throttled, so a command can time
+ * out while the SDK keeps reporting in, which is exactly the state ONE_WAY_ADVICE reads as a
+ * transport fault. Sending the agent to debug its own network there costs attempts and finds
+ * nothing (#1416): the way out is a tab nobody else is looking at, which a lease is.
+ */
+const HIDDEN_TAB_ADVICE = 'The page last reported itself hidden: it is a background tab, and the browser throttles a hidden ' +
+    "tab's frames and timers, so commands can time out while the page still reports in. This is not a " +
+    `network fault. Bring the tab to the front, or drive a tab Reticle owns: ${ReticleTool.LEASE} ` +
+    '{ action: "acquire", url: "%URL%" }.';
+/**
+ * True only when the SDK REPORTED an ordinary browser tab. Not guessed from the URL: a Tauri or
+ * Electron dev server is http://localhost too, and an older SDK that omits the runtime would turn a
+ * hidden desktop window into "bring the tab forward", which addresses nothing there.
+ */
+function isWebTab(context) {
+    return AppRuntime.WEB === context.runtime;
+}
 /** True when this session is a WebKit desktop shell — the only runtime that suffers this. */
 function isWebKitDesktop(context) {
     if (realmOf(context.runtime).usesWebKit)
@@ -28,6 +46,12 @@ function isWebKitDesktop(context) {
 }
 export function commandTimeoutMessage(name, timeoutMs, context) {
     const base = `command '${name}' timed out after ${String(timeoutMs)}ms`;
+    // A hidden WEB tab first, before the recently-heard branch: a background tab keeps reporting in
+    // while its throttled frames miss the command, so "heard recently" is expected there and says
+    // nothing about the transport. Desktop shells keep the order below unchanged.
+    if (context.hidden && isWebTab(context)) {
+        return `${base}. ${HIDDEN_TAB_ADVICE.replace('%URL%', context.url)}`;
+    }
     // Checked FIRST, and it overrides the visibility story: a page that was heard from moments ago is
     // executing JavaScript, so "hidden, hung or never presented" cannot be the explanation whatever
     // `hidden` says. Deduced from the invariant, not from a measured incident — the Tauri case that

package/dist/portal/session/timing/wall-clock.d.ts

@@ -2,7 +2,7 @@
  * The real clock, named once.
  *
  * The logic that needs a clock takes one as an argument so a test can drive it without waiting
- * (CLAUDE.md rule 7). That leaves the production callers each constructing the same pair of
+ * (AGENTS.md rule 7). That leaves the production callers each constructing the same pair of
  * closures, which is how two of them end up with different sleep implementations. One export, one
  * place to look.
  */

package/dist/portal/session/timing/wall-clock.js

@@ -2,7 +2,7 @@
  * The real clock, named once.
  *
  * The logic that needs a clock takes one as an argument so a test can drive it without waiting
- * (CLAUDE.md rule 7). That leaves the production callers each constructing the same pair of
+ * (AGENTS.md rule 7). That leaves the production callers each constructing the same pair of
  * closures, which is how two of them end up with different sleep implementations. One export, one
  * place to look.
  */

package/dist/portal/session/zero-install-first-call.d.ts

@@ -0,0 +1,31 @@
+import { type FirstRunWiring } from './first-run-wiring.js';
+export interface FirstCallIo {
+    /** The unwired web app this call is about; undefined when wired, not a web app, or no project. */
+    project: () => string | undefined;
+    /** Which of these ports serve HTTP right now. */
+    serving: (ports: readonly number[]) => Promise<readonly number[]>;
+    /** The directory the process serving `url` runs in, when it can be observed. */
+    servingDirectory: (url: string) => string | undefined;
+    /** Open `url` in a lease — the path that supplies the SDK when the page never dials in. */
+    lease: (url: string) => Promise<unknown>;
+    /** Whether a session is connected now. */
+    connected: () => boolean;
+}
+export interface FirstCallOpened {
+    url: string;
+    /** One line for the agent: what was opened, what it cannot see, and how to wire it for good. */
+    notice: string;
+}
+/** One lease per project for the daemon's life: a failure is reported once, never retried. */
+export declare function firstCallOpener(io: FirstCallIo): () => Promise<FirstCallOpened | undefined>;
+/**
+ * The daemon's two answers to an app nobody wired, built together because both ask the same
+ * question first — which unwired web app is this caller in. `firstRun` wires it when the agent
+ * lists sessions; `openUnwiredApp` opens it zero-install on a page-needing call.
+ */
+export declare function agentWiring(port: number, sessions: {
+    list(): readonly unknown[];
+}, lease: (url: string) => Promise<unknown>): {
+    firstRun: FirstRunWiring;
+    openUnwiredApp: () => Promise<FirstCallOpened | undefined>;
+};

package/dist/portal/session/zero-install-first-call.js

@@ -0,0 +1,88 @@
+/**
+ * The first call that needs a page, on an app nobody wired: open that app ourselves, zero-install.
+ *
+ * An install through the MCP server alone (a plugin, a hand-written `npx … mcp` config) never runs
+ * `init`, so the app carries no SDK and nothing ever connects. The agent's first page-needing call
+ * then answered with a diagnosis, and the agent stopped there. A lease supplies the SDK to a page
+ * that never dials in, so the daemon can answer that call with the app itself instead.
+ *
+ * Only for a call that already asked to drive or read a page, and only on evidence: exactly one dev
+ * server whose process runs inside this project's folder. The port scan is machine-wide, and a
+ * browser opened on another repo's app produces a confident verdict about code nobody touched. It
+ * changes nothing in the repo — wiring it for good stays the agent's call, named in the notice.
+ *
+ * Where the serving process cannot be observed (no `lsof`, so Windows) nothing is opened and the
+ * no-session answer names the lease and the init command instead.
+ */
+import { realpathSync } from 'node:fs';
+import { resolve, sep } from 'node:path';
+import { DEV_SERVER_PORTS } from '../../command/cli/ports/resolve/cli-port.js';
+import { callingClientDirectory } from '../../hooks/client-directory.js';
+import { detectDevCommandInProject, initCommandIn } from './dev-server/dev-command.js';
+import { probeDevServerStates } from './dev-server/dev-server-probe.js';
+import { firstRunWiring } from './first-run-wiring.js';
+import { servingDirectoryOf } from './serving-directory.js';
+const LOCALHOST = 'http://localhost';
+/** The path with symlinks resolved when it exists (lsof reports `/private/tmp`, callers `/tmp`). */
+function real(path) {
+    try {
+        return realpathSync(path);
+    }
+    catch {
+        return resolve(path);
+    }
+}
+const inside = (c, p) => c === p || c.startsWith(`${p}${sep}`);
+/** Compared both as written and with links resolved: either spelling may be the one lsof used. */
+function within(child, parent) {
+    if (child === undefined)
+        return false;
+    return inside(resolve(child), resolve(parent)) || inside(real(child), real(parent));
+}
+function openedNotice(url, init) {
+    return (`This app is not wired for Reticle, so Reticle opened ${url} in its own browser and supplied ` +
+        'the SDK (zero-install: DOM, network, console and routes; no component state and no source ' +
+        `file:line). To wire it for good, run \`${init}\`, then ` +
+        'restart the dev server and reload the page.');
+}
+/** One lease per project for the daemon's life: a failure is reported once, never retried. */
+export function firstCallOpener(io) {
+    const tried = new Set();
+    return async () => {
+        const dir = io.project();
+        if (dir === undefined || tried.has(dir))
+            return undefined;
+        const pinned = detectDevCommandInProject(dir)?.port;
+        const candidates = new Set(DEV_SERVER_PORTS);
+        if (pinned !== undefined)
+            candidates.add(pinned);
+        const own = (await io.serving([...candidates]))
+            .map((port) => `${LOCALHOST}:${String(port)}`)
+            .filter((url) => within(io.servingDirectory(url), dir));
+        const [url] = own;
+        // ponytail: nothing serving yet is not an attempt, so a later call looks again.
+        if (url === undefined || 1 !== own.length)
+            return undefined;
+        tried.add(dir);
+        await io.lease(url).catch(() => undefined);
+        if (!io.connected())
+            return undefined;
+        return { url, notice: openedNotice(url, initCommandIn(dir)) };
+    };
+}
+/**
+ * The daemon's two answers to an app nobody wired, built together because both ask the same
+ * question first — which unwired web app is this caller in. `firstRun` wires it when the agent
+ * lists sessions; `openUnwiredApp` opens it zero-install on a page-needing call.
+ */
+export function agentWiring(port, sessions, lease) {
+    const firstRun = firstRunWiring({ port, cliPath: process.argv[1] ?? '' });
+    const openUnwiredApp = firstCallOpener({
+        project: () => firstRun.projectDirectory(callingClientDirectory() ?? process.cwd()),
+        serving: async (ports) => (await probeDevServerStates(ports)).serving,
+        servingDirectory: (url) => servingDirectoryOf(url),
+        lease,
+        connected: () => 0 < sessions.list().length,
+    });
+    return { firstRun, openUnwiredApp };
+}

package/dist/start-options.d.ts

@@ -7,6 +7,18 @@
 import type { OwnedRealInputProvider } from './portal/input/real-input.js';
 import type { InjectConnectOptions } from './portal/input/real-input.js';
 export interface StartOptions {
+    /**
+     * The panel's Sign in, supplied by the CLI door, which owns install-time code: given a repaint, it
+     * answers the handler the bridge runs on each press. An embedder of the library leaves it out, and
+     * its panel falls back to copying `reticle login`.
+     */
+    hudSignIn?: (repaint: () => void, 
+    /** Links the asking tab's project once the sign-in lands (`hudLink`). */
+    link?: (root: string) => Promise<number>) => (from?: {
+        artifactRoot?: string | undefined;
+    }) => void;
+    /** The Harness page's Link this project: link the project in this folder, as `reticle connect` does. */
+    hudLink?: (root: string) => Promise<number>;
     port?: number;
     /** Bind address. Non-loopback hosts require a token. Defaults to RETICLE_HOST or localhost. */
     host?: string;

package/dist/start-wiring.d.ts

@@ -0,0 +1,63 @@
+import type { NetworkDetail } from './portal/input/network-detail.js';
+import type { StartOptions } from './start-options.js';
+import type { Bridge } from './portal/bridge/bridge.js';
+import type { RealInputProvider } from './portal/input/real-input.js';
+import { BrowserPool } from './portal/pool/browser-pool.js';
+import { type InjectedConnect } from './portal/pool/zero-install.js';
+/**
+ * Build the shared browser pool (one headless Chromium, N capped isolated leased contexts). Lazy —
+ * no Chromium launches until the first lease — so creating it is free even when never used.
+ */
+/** Where the zero-install reader connects: this daemon's own bridge, with its pairing token. */
+export declare function readerConnect(port: number, token: string | undefined): InjectedConnect;
+export declare function createBrowserPool(headless: boolean, reader: InjectedConnect): BrowserPool;
+/**
+ * Route CDP-authoritative network detail onto the driven session's journal.
+ *
+ * The page and the SDK session share an origin, so a NET_DETAIL is pushed to the matching connected
+ * session. Shared by both entry points: `startDaemon` previously omitted it entirely, so on the path
+ * users actually take, CDP network detail was collected and then dropped on the floor.
+ */
+export declare function makeNetworkDetailRouter(bridge: Bridge, driveUrl: string | undefined): (detail: NetworkDetail) => void;
+/**
+ * Resolve the drive/real-input provider from options — shared by start and startDaemon so the
+ * precedence (driveUrl launch+own → CDP attach → none) and the storageState/injectConnect plumbing
+ * live in ONE place. `onNavigateError` is the entrypoint's own cleanup (close the bridge/shared server)
+ * so a failed launch never leaks a WS port. A past divergence between the two paths let daemon mode
+ * run with a different setup — this removes that risk.
+ */
+export declare function resolveRealInput(options: StartOptions, onNavigateError: () => Promise<void>, onNetworkDetail?: (detail: NetworkDetail) => void): Promise<{
+    realInput?: RealInputProvider;
+    owned?: {
+        dispose: () => Promise<void>;
+    };
+}>;
+/**
+ * The SDK-upgrade sentence for the package.json of the project the page announced, evaluated at
+ * each HELLO so a just-edited manifest is what we name. The daemon's cwd only when that project's
+ * directory is unknown, and the framework-neutral sensor when that is not an app either (#1135).
+ */
+export declare function sdkFixForProject(projectId?: string): string;
+/**
+ * Resolve a session's artifact root, from everything this machine knows about where projects live.
+ *
+ * Built once per daemon and closed over by every tool call. The two sources are read lazily and
+ * cheaply on each call rather than snapshotted at startup: `init` can run in another terminal while
+ * this daemon is up, and a resolution that used a startup snapshot would keep answering with a map
+ * from before the project the agent is now driving existed.
+ */
+/**
+ * Every `.reticle` root on this machine that sync should consider, from the same two sources the
+ * artifact resolver uses.
+ *
+ * Read on every call rather than snapshotted, for the same reason: `reticle link` can run in
+ * another terminal while this daemon is up, and a startup snapshot would keep that repo silent
+ * until somebody restarted a process they have no reason to suspect.
+ *
+ * Returns directories that MIGHT be linked; the caller resolves each and skips the ones that are
+ * not. Deciding that here would mean reading every cloud.json on every tick.
+ */
+export declare function knownProjectRoots(): string[];
+/** This project's platform credential (stored, else the env key), as the env the platform readers take. */
+export declare const platformEnvFor: (root: string | undefined) => () => Promise<NodeJS.ProcessEnv>;
+export declare const loadHarnessConfig: (root: string) => Promise<import("./features/harness/platform-config.js").PlatformModelConfig | undefined>;