@reticlehq/server 3.6.0 → 3.7.0

package/dist/portal/session/session.d.ts

@@ -1,9 +1,9 @@
 import type { WebSocket } from 'ws';
 import { type ChannelId, type ImpactSnapshot, type ProjectId } from '@reticlehq/core';
+import { type NarrationBy } from './narration-args.js';
 import type { HandshakeFacts } from './facts/handshake-facts.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 { type PageRuntime } from './timing/command-timeout.js';
 import { readHealthEvent, type SessionHealth } from './session-health.js';
 export type { SessionHealth };
@@ -15,8 +15,8 @@ import { type InboxMessage } from './human/live-control.js';
 export type { InboxMessage } from './human/live-control.js';
 import { type ReviewMark } from './human/review-store.js';
 import { type SessionLease } from './presence/session-lease.js';
-import type { SessionInfo } from './session-info.js';
 export type { SessionInfo } from './session-info.js';
+import { type SessionInfo } from './session-info.js';
 type Clock = () => number;
 /**
  * One connected browser tab. Owns its socket, a ring buffer of observations, and the
@@ -35,13 +35,8 @@ export declare class Session implements HandshakeFacts {
     readonly projectId: ProjectId | undefined;
     /**
      * 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: string | undefined;
     /**
@@ -62,6 +57,8 @@ export declare class Session implements HandshakeFacts {
     readonly redactKeys: readonly string[];
     /** The desktop window this is and its document's HTTP status, merged from every PAGE_HEALTH. */
     readonly page: ReturnType<typeof readHealthEvent>['page'];
+    /** The newest journal action: a verdict's screenshot names it, so the run pairs it with its check. */
+    lastActionId: string | undefined;
     constructor(hello: HelloMessage, socket: WebSocket, clock: Clock);
     /** Milliseconds since this session connected — the authoritative buffer clock. */
     elapsed(): number;
@@ -107,7 +104,7 @@ export declare class Session implements HandshakeFacts {
     preconditionFailure(): string | undefined;
     /** What the rules that decide a verdict need from the daemon. See daemon-answers.ts. */
     readonly note: typeof import("../../log.js").log;
-    readonly keepCallerContext: typeof import("../../trace.js").bindSpanContext;
+    readonly keepCallerContext: <A extends unknown[]>(fn: (...args: A) => void) => ((...args: A) => void);
     /** Re-stamp an incoming event with server-relative time, buffer it, and fan out. */
     pushEvent(event: ReticleEvent, byteSize?: number): void;
     recordActedRef(ref: string): void;
@@ -124,7 +121,7 @@ export declare class Session implements HandshakeFacts {
     provedLabels(): ReadonlySet<string>;
     actedRefs(): ReadonlySet<string>;
     noteRateLimited(dropped: number): void;
-    blindSpots(): Readonly<Record<string, number>>;
+    blindSpots(since?: number): Readonly<Record<string, number>>;
     /** Learned ambient-churn counts (PredicateSession hook the settle oracle reads). */
     ambientCounts(): AmbientCounts;
     /** Only what THIS session observed — what teardown accumulates onto the persisted map. */
@@ -144,10 +141,7 @@ export declare class Session implements HandshakeFacts {
     queryEvents(options: EventQueryOptions): Promise<ReticleEvent[]>;
     /** What the durable ledger could not WRITE — see `readJournalWriteLoss` for the rule and why. */
     journalWriteLoss(): Promise<JournalWriteLoss | undefined>;
-    /**
-     * 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: string, args: Record<string, unknown>): string;
     /**
      * Record one action WITHOUT opening an attribution window — for a tool that returns a verdict but
@@ -189,11 +183,6 @@ export declare class Session implements HandshakeFacts {
      * end of it.
      */
     readonly gaps: 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.
-     */
-    readonly capture: CaptureLedger;
     /**
      * Stamp the wall-clock of the latest AGENT command (called whenever a tool resolves this session).
      * If the reaper had auto-ended the session, a fresh command means the agent is alive again, so the
@@ -245,9 +234,9 @@ export declare class Session implements HandshakeFacts {
      * summary) so a transition never emits two PRESENTER commands.
      */
     setState(next: SessionState, text?: string, tone?: PresenterTone): void;
-    /** 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: string): void;
-    /** 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(): InboxMessage[];
     /** Diagnostic read of the inbox depth (does not clear). */
     inboxSize(): number;
@@ -267,15 +256,13 @@ export declare class Session implements HandshakeFacts {
      */
     applyHumanControl(data: HumanControlData): void;
     /**
-     * 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: () => ImpactSnapshot | undefined, immediate?: boolean): void;
     pushPresenter(state: SessionState, text?: string, tone?: PresenterTone): void;
-    pushNarration(text: string): void;
+    /** `mirror: false` for a notice about THIS page (its SDK is behind), which every tab says itself. */
+    pushNarration(text: string, mirror?: boolean, by?: NarrationBy): void;
     /** A HUD replay's progress, or the Harness's drive plan: pictures the HUD redraws as they change. */
     pushView(name: typeof ReticleCommand.FLOW_PROGRESS | typeof ReticleCommand.PLAN, args: object): void;
     /** The one-time lease block on the first agent command, then undefined forever after. */

package/dist/portal/session/session.js

@@ -1,11 +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';
@@ -20,13 +21,15 @@ import { readJournalWriteLoss, readQueryEvents, windowLost, } from '../../memory
 import {} from '@reticlehq/engine/window/ambient.js';
 import { ObservedState, controlLabelsOf } from './facts/observed-state.js';
 import { DepartureNote } from './facts/departure-note.js';
-import { recordBrowserLatency, recordHudUse, recordSdkFailure, } from '../../telemetry/session-metrics.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. */
@@ -57,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;
     /**
@@ -113,8 +111,9 @@ export class Session {
     #live = new LiveControl();
     /** Human review marks: mistakes the human pinned to elements, for the agent to drain and fix. */
     #review = new ReviewStore((marks) => recordNotes(this.artifactRoot, marks));
-    /** Whether the session_lease has already been returned (fire-once per session). */
-    #firstCommandDone = false;
+    #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
@@ -284,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)
@@ -294,6 +293,9 @@ export class Session {
         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
@@ -382,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() {
@@ -419,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
@@ -442,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.
@@ -490,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).
@@ -601,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))
@@ -637,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();
@@ -658,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
@@ -714,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() {
@@ -760,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?.();
     }
@@ -790,8 +787,13 @@ 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) {
@@ -831,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);

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

@@ -12,7 +12,13 @@ export interface StartOptions {
      * 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) => () => void;
+    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>;