@reticlehq/vite-plugin 3.6.0 → 3.8.0

package/dist/announce.d.ts

@@ -14,3 +14,5 @@ export interface AnnounceIo {
  * throw inside a signal handler does not degrade, it takes the shutdown with it.
  */
 export declare function announceDevServer(entry: DevServerEntry, home?: string, io?: AnnounceIo): () => void;
+/** The URL to announce: the dev proxy's when one runs this server, else the one Vite reports. */
+export declare function announcedUrl(env: Readonly<Record<string, string | undefined>>, reported: string | undefined, port: number): string;

package/dist/announce.js

@@ -58,3 +58,16 @@ export function announceDevServer(entry, home = stateHome(), io = nodeIo) {
         }
     };
 }
+/**
+ * The environment variable a dev proxy sets to the URL the app is served on. portless runs each app,
+ * and each git worktree of it, at `https://<branch>.<app>.localhost`, while the dev server listens on
+ * a port of its own. The page's origin is the proxy URL, so that is what the daemon must match.
+ */
+const DEV_PROXY_URL_ENV = 'PORTLESS_URL';
+/** The URL to announce: the dev proxy's when one runs this server, else the one Vite reports. */
+export function announcedUrl(env, reported, port) {
+    const proxied = env[DEV_PROXY_URL_ENV];
+    if (proxied !== undefined && proxied.length > 0)
+        return proxied;
+    return reported ?? `http://localhost:${String(port)}/`;
+}

package/dist/disabled-browser-stub.d.ts

@@ -12,4 +12,4 @@ export declare const RETICLE_DISABLED_STUB = "\0reticle-disabled-stub";
  * production, because the cost of guessing wrong the other way is an instrumented release.
  */
 export declare const isReticleDisabledBuild: (desktop: boolean, command: string | undefined, mode: string | undefined) => boolean;
-export declare const RETICLE_DISABLED_STUB_CODE = "\nexport class Reticle {\n  connect() {}\n  signal() {}\n  state() {}\n  renderCommit() {}\n  describe() {}\n  endSession() {}\n  observeHotUpdates() {}\n  disconnect() {}\n\n  get connected() {\n    return false;\n  }\n}\n\nexport const reticle = new Reticle();\n\nexport const SESSION_AUTO = 'auto';\n\nexport function setIgnoreSelectors() {}\n\nexport function registerAdapter() {}\nexport function identifyComponent() {\n  return null;\n}\nexport function readComponentState() {\n  return undefined;\n}\nexport function elementHasHoverHandlers() {\n  return false;\n}\nexport function adapterNames() {\n  return [];\n}\n\nexport function registerStore() {}\nexport function unregisterStore() {}\nexport function storeNames() {\n  return [];\n}\nexport function readStores() {\n  return {};\n}\nexport function readStoresWithTruncation() {\n  return { stores: {} };\n}\nexport function sourceOwner() {\n  return undefined;\n}\nexport function markAdapterSource() {}\n\nexport function tanstackQueryStore() {\n  return undefined;\n}\nexport function jotaiStore() {\n  return undefined;\n}\nexport function xstateStore() {\n  return undefined;\n}\nexport function valtioStore() {\n  return undefined;\n}\nexport function mobxStore() {\n  return undefined;\n}\nexport function recoilStore() {\n  return undefined;\n}\nexport function svelteStore() {\n  return undefined;\n}\nexport function piniaStore() {\n  return undefined;\n}\nexport function pushStore() {\n  return undefined;\n}\n\nexport function registerCapabilities() {}\nexport function getCapabilities() {\n  return {};\n}\nexport function hasCapabilities() {\n  return false;\n}\nexport function setCapabilitiesListener() {}\n\nexport function createReticleEmitter() {\n  return {\n    signal() {},\n    state() {},\n  };\n}\n\nexport function commitAndSignal() {}\nexport function registerReticleDomain() {}\n\nexport function buildSnapshot() {\n  return {};\n}\n\nexport function inspectChart() {\n  return {};\n}\nexport function canvasChartData() {\n  return {};\n}\n\nexport function matchQuery() {\n  return false;\n}\nexport function runQuery() {\n  return undefined;\n}\n\nexport function executeAction() {\n  return undefined;\n}\nexport function executeSequence() {\n  return undefined;\n}\n\nexport function describe() {\n  return undefined;\n}\nexport function getRole() {\n  return undefined;\n}\nexport function getAccessibleName() {\n  return undefined;\n}\nexport function getStates() {\n  return {};\n}\nexport function isVisible() {\n  return false;\n}\n\nexport class RefRegistry {\n  get size() {\n    return 0;\n  }\n\n  markEdited() {}\n\n  mintedBeforeLastEdit() {\n    return false;\n  }\n\n  refFor() {\n    return undefined;\n  }\n\n  resolve() {\n    return null;\n  }\n}\n\nexport const refs = new RefRegistry();\n\nexport class Annotator {\n  constructor() {}\n\n  get active() {\n    return false;\n  }\n\n  get markCount() {\n    return 0;\n  }\n\n  mount() {}\n  unmount() {}\n}\n\nexport function installAnnotator() {}\n\nexport function resolveMarkAnchor() {\n  return undefined;\n}\n";
+export declare const RETICLE_DISABLED_STUB_CODE = "\nexport class Reticle {\n  connect() {}\n  signal() {}\n  state() {}\n  renderCommit() {}\n  describe() {}\n  endSession() {}\n  observeHotUpdates() {}\n  disconnect() {}\n\n  get connected() {\n    return false;\n  }\n}\n\nexport const reticle = new Reticle();\n\nexport const SESSION_AUTO = 'auto';\n\nexport function setIgnoreSelectors() {}\n\nexport function registerAdapter() {}\nexport function identifyComponent() {\n  return null;\n}\nexport function readComponentState() {\n  return undefined;\n}\nexport function elementHasHoverHandlers() {\n  return false;\n}\nexport function adapterNames() {\n  return [];\n}\n\nexport function registerStore() {}\nexport function unregisterStore() {}\nexport function storeNames() {\n  return [];\n}\nexport function readStores() {\n  return {};\n}\nexport function readStoresWithTruncation() {\n  return { stores: {} };\n}\nexport function sourceOwner() {\n  return undefined;\n}\nexport function markAdapterSource() {}\n\nexport function tanstackQueryStore() {\n  return undefined;\n}\nexport function jotaiStore() {\n  return undefined;\n}\nexport function xstateStore() {\n  return undefined;\n}\nexport function valtioStore() {\n  return undefined;\n}\nexport function mobxStore() {\n  return undefined;\n}\nexport function recoilStore() {\n  return undefined;\n}\nexport function svelteStore() {\n  return undefined;\n}\nexport function piniaStore() {\n  return undefined;\n}\nexport function pushStore() {\n  return undefined;\n}\n\nexport function registerCapabilities() {}\nexport function getCapabilities() {\n  return {};\n}\nexport function hasCapabilities() {\n  return false;\n}\nexport function setCapabilitiesListener() {}\n\nexport function createReticleEmitter() {\n  return {\n    signal() {},\n    state() {},\n  };\n}\n\n// It wraps the APP's write, so the write still runs: Reticle does nothing in production, the app does.\nexport function commitAndSignal(_emitter, mutate) {\n  return mutate();\n}\nexport function registerReticleDomain() {}\n\nexport function buildSnapshot() {\n  return {};\n}\n\nexport function inspectChart() {\n  return {};\n}\nexport function canvasChartData() {\n  return {};\n}\n\nexport function matchQuery() {\n  return false;\n}\nexport function runQuery() {\n  return undefined;\n}\n\nexport function executeAction() {\n  return undefined;\n}\nexport function executeSequence() {\n  return undefined;\n}\n\nexport function describe() {\n  return undefined;\n}\nexport function getRole() {\n  return undefined;\n}\nexport function getAccessibleName() {\n  return undefined;\n}\nexport function getStates() {\n  return {};\n}\nexport function isVisible() {\n  return false;\n}\n\nexport class RefRegistry {\n  get size() {\n    return 0;\n  }\n\n  markEdited() {}\n\n  mintedBeforeLastEdit() {\n    return false;\n  }\n\n  refFor() {\n    return undefined;\n  }\n\n  resolve() {\n    return null;\n  }\n}\n\nexport const refs = new RefRegistry();\n\nexport class Annotator {\n  constructor() {}\n\n  get active() {\n    return false;\n  }\n\n  get markCount() {\n    return 0;\n  }\n\n  mount() {}\n  unmount() {}\n}\n\nexport function installAnnotator() {}\n\nexport function resolveMarkAnchor() {\n  return undefined;\n}\n";

package/dist/disabled-browser-stub.js

@@ -111,7 +111,10 @@ export function createReticleEmitter() {
   };
 }
 
-export function commitAndSignal() {}
+// It wraps the APP's write, so the write still runs: Reticle does nothing in production, the app does.
+export function commitAndSignal(_emitter, mutate) {
+  return mutate();
+}
 export function registerReticleDomain() {}
 
 export function buildSnapshot() {

package/dist/index.cjs

@@ -4122,126 +4122,7 @@ var coerce = {
 };
 var NEVER = INVALID;
 
-// ../../../core/dist/wire/constants/event-types.js
-var EventType = {
-  DOM_ADDED: "dom.added",
-  DOM_REMOVED: "dom.removed",
-  DOM_ATTR: "dom.attr",
-  DOM_TEXT: "dom.text",
-  NET_REQUEST: "net.request",
-  NET_PENDING: "net.pending",
-  /** An SSE (EventSource) or WebSocket frame — a message on a long-lived streaming connection. */
-  NET_STREAM: "net.stream",
-  /** A web-perf metric a screenshot can't verify: LCP, cumulative layout shift, or a long task. */
-  PERF: "perf",
-  ROUTE_CHANGE: "route.change",
-  CONSOLE_LOG: "console.log",
-  CONSOLE_WARN: "console.warn",
-  CONSOLE_ERROR: "console.error",
-  CONSOLE_INFO: "console.info",
-  CONSOLE_DEBUG: "console.debug",
-  ERROR_UNCAUGHT: "error.uncaught",
-  VISIBLE_SHOWN: "visible.shown",
-  ANIM_START: "anim.start",
-  ANIM_END: "anim.end",
-  SCROLL_POSITION: "scroll.position",
-  REVEAL_SHOWN: "reveal.shown",
-  SIGNAL: "signal",
-  STATE_CHANGE: "state.change",
-  /** a write to localStorage/sessionStorage/cookies — `data: { area, key, old?, new? }` (values redacted). */
-  STORAGE_CHANGE: "storage.change",
-  /** page-level visibility/focus health (distinct from element-level VISIBLE_*). */
-  PAGE_HEALTH: "page.health",
-  /**
-   * synthetic: the page called window.open, so the consequence of what was just clicked may live in
-   * another browsing context this one cannot observe (an OAuth popup is the archetype).
-   * `data: { href }` — the URL the page asked to open, when it named one.
-   */
-  CONTEXT_OPENED: "context.opened",
-  /**
-   * The app opened a native `alert`/`confirm`/`prompt` while Reticle was driving it.
-   *
-   * Recorded because Reticle ANSWERS these rather than letting them block — a native dialog halts
-   * the main thread, and the SDK's own message pump is on that thread, so one `confirm` behind a
-   * driven click made the tab permanently unresponsive with no recovery from inside the session.
-   * Answering silently would trade a wedge for an invisible one, so the question the app asked, and
-   * the answer given, ride out as an event.
-   */
-  DIALOG_OPENED: "dialog.opened",
-  /** aggregated React commits over a throttle window (dev builds) — `data: { commits }`. Commit storms /
-   * wasted re-renders show up here without a per-render flood. */
-  RENDER_COMMIT: "render.commit",
-  /** element focus moved — `data: { to, from, toBody }`. Focus dropping to body after an act is a regression. */
-  FOCUS_CHANGE: "focus.change",
-  /**
-   * a form field's value moved — `data: { field, kind, value?, redacted?, length }`.
-   *
-   * The DOM observer never saw this: `value` is in its attribute allowlist, but React and every
-   * controlled input set the PROPERTY, so `MutationObserver` does not fire. `value` is omitted and
-   * `redacted` set for a password, a sensitive name, or a payment autocomplete hint; `length` is
-   * always present, because "it was wiped" is assertable without carrying anybody's data.
-   */
-  FIELD_CHANGE: "field.change",
-  /** browser → bridge: a human recording compiled in-page. */
-  FLOW_RECORDED: "flow.recorded",
-  /** synthetic: browser transport queue overflowed; events were dropped. `data: { dropped: number }`. */
-  TRANSPORT_OVERFLOW: "transport.overflow",
-  /**
-   * synthetic: a per-channel cap truncated a batch (e.g. a DOM mutation flood). `data: { channel, dropped }`.
-   * Marks downstream rollups/envelopes as built on incomplete data — a ledger that lies at scale is worse
-   * than no ledger, so truncation is never silent.
-   */
-  TRUNCATED: "truncated",
-  /**
-   * synthetic: the SDK detected a region it CANNOT observe (a cross-origin iframe, a closed shadow root).
-   * `data: { kind: BlindSpotKind, count }`. Surfaced on results as `coverage: partial` so a green never
-   * implies it saw everything.
-   */
-  BLIND_SPOT: "blind-spot",
-  /** synthetic: the SDK ITSELF failed (an observer threw). `data: { site, message, errorType }`.
-   *  Rides the existing bridge — no outbound request. See browser/observers/sdk-failure.ts. */
-  SDK_FAILED: "sdk.failed",
-  /**
-   * synthetic (driven only): CDP/Playwright-authoritative network detail for a response the in-page
-   * fetch/XHR wrapper also saw — full response headers + authoritative status/mimeType the page-side
-   * wrapper can't reach. `data: { url, method?, status, headers, resourceType? }`. Merged onto the
-   * matching in-page NET_REQUEST so the driven view never loses fidelity to an outside-in tool.
-   */
-  NET_DETAIL: "net.detail",
-  /**
-   * Live-control: browser → bridge. A human acted on the presenter panel.
-   * `data: { kind: HumanControlKind; text?: string }`. Rides the existing EventMessage.
-   */
-  HUMAN_CONTROL: "human.control",
-  /**
-   * Human review: browser → bridge. A human pinned a mistake to an element on the running page
-   * (the "annotate the bug where you see it" loop). `data` narrows to HumanMarkDataSchema — a note
-   * plus a re-resolvable element anchor (and its source file:line when the framework stamped one) so
-   * the agent that drains the mark knows exactly which element and which source to fix.
-   */
-  HUMAN_MARK: "human.mark",
-  /**
-   * The app produced a FILE — a Blob handed to `URL.createObjectURL`, usually saved by clicking an
-   * anchor with `download`. `data: { filename?, mimeType, bytes, lines?, preview? }`. The one artifact
-   * class no outside-the-browser tool can inspect: it never crosses the network, so there is no
-   * request to intercept. See `observers/download.ts` for the defect that motivated it.
-   */
-  DOWNLOAD: "download",
-  /**
-   * Browser -> bridge: a person used the HUD — pressed a control, or the HUD changed how it sits.
-   * `data` narrows to HudUseDataSchema: names only. Telemetry, not evidence: the session takes it
-   * off the wire before the buffer, so no verdict, settle or agent read ever sees it.
-   */
-  HUD_USED: "hud.used"
-};
-
-// ../../../core/dist/wire/constants/constants.js
-var RETICLE_DEFAULT_PORT = 4400;
-var RETICLE_WS_PATH = "/reticle";
-var RETICLE_CLIENT_HOST = "localhost";
-function bridgeWsUrl(port = RETICLE_DEFAULT_PORT, host = RETICLE_CLIENT_HOST) {
-  return `ws://${host}:${String(port)}${RETICLE_WS_PATH}`;
-}
+// ../../../core/dist/wire/constants/reticle-env.js
 var ReticleEnv = {
   /** "0"/"false"/"off" turns off telemetry and every optional outbound call; DO_NOT_TRACK too. */
   TELEMETRY: "RETICLE_TELEMETRY",
@@ -4330,6 +4211,8 @@ var ReticleEnv = {
   HARNESS_BASE_URL: "RETICLE_HARNESS_BASE_URL",
   /** Hard ceiling on harness model turns in one drive. Bounds cost, not value. */
   HARNESS_MAX_STEPS: "RETICLE_HARNESS_MAX_STEPS",
+  /** The free drive `reticle try` was granted, sent on every Harness call it bills. */
+  DRIVE_ID: "RETICLE_DRIVE_ID",
   /**
    * Which model backs the harness driver: `anthropic` (the default) or `jev`.
    *
@@ -4367,8 +4250,148 @@ var ReticleEnv = {
   /** The platform host. Read through `cloudUrlFrom()`, which also accepts `URL`. */
   CLOUD_URL: "RETICLE_CLOUD_URL",
   /** The short name for `CLOUD_URL`, which people type first. `CLOUD_URL` wins when both are set. */
-  URL: "RETICLE_URL"
+  URL: "RETICLE_URL",
+  /** "0"/"false"/"off" stops `reticle hook prompt` writing prompts, on this whole machine. */
+  PROMPT_CAPTURE: "RETICLE_PROMPT_CAPTURE",
+  /** "0"/"false"/"off" stops the daemon's background sync, on this whole machine. */
+  BACKGROUND_SYNC: "RETICLE_BACKGROUND_SYNC"
 };
+
+// ../../../core/dist/wire/constants/event-types.js
+var EventType = {
+  DOM_ADDED: "dom.added",
+  DOM_REMOVED: "dom.removed",
+  DOM_ATTR: "dom.attr",
+  DOM_TEXT: "dom.text",
+  NET_REQUEST: "net.request",
+  NET_PENDING: "net.pending",
+  /** An SSE (EventSource) or WebSocket frame — a message on a long-lived streaming connection. */
+  NET_STREAM: "net.stream",
+  /** A web-perf metric a screenshot can't verify: LCP, cumulative layout shift, or a long task. */
+  PERF: "perf",
+  ROUTE_CHANGE: "route.change",
+  CONSOLE_LOG: "console.log",
+  CONSOLE_WARN: "console.warn",
+  CONSOLE_ERROR: "console.error",
+  CONSOLE_INFO: "console.info",
+  CONSOLE_DEBUG: "console.debug",
+  ERROR_UNCAUGHT: "error.uncaught",
+  VISIBLE_SHOWN: "visible.shown",
+  ANIM_START: "anim.start",
+  ANIM_END: "anim.end",
+  SCROLL_POSITION: "scroll.position",
+  REVEAL_SHOWN: "reveal.shown",
+  SIGNAL: "signal",
+  STATE_CHANGE: "state.change",
+  /** a write to localStorage/sessionStorage/cookies — `data: { area, key, old?, new? }` (values redacted). */
+  STORAGE_CHANGE: "storage.change",
+  /** page-level visibility/focus health (distinct from element-level VISIBLE_*). */
+  PAGE_HEALTH: "page.health",
+  /**
+   * synthetic: the page called window.open, so the consequence of what was just clicked may live in
+   * another browsing context this one cannot observe (an OAuth popup is the archetype).
+   * `data: { href }` — the URL the page asked to open, when it named one.
+   */
+  CONTEXT_OPENED: "context.opened",
+  /**
+   * The app opened a native `alert`/`confirm`/`prompt` while Reticle was driving it.
+   *
+   * Recorded because Reticle ANSWERS these rather than letting them block — a native dialog halts
+   * the main thread, and the SDK's own message pump is on that thread, so one `confirm` behind a
+   * driven click made the tab permanently unresponsive with no recovery from inside the session.
+   * Answering silently would trade a wedge for an invisible one, so the question the app asked, and
+   * the answer given, ride out as an event.
+   */
+  DIALOG_OPENED: "dialog.opened",
+  /** aggregated React commits over a throttle window (dev builds) — `data: { commits }`. Commit storms /
+   * wasted re-renders show up here without a per-render flood. */
+  RENDER_COMMIT: "render.commit",
+  /** element focus moved — `data: { to, from, toBody }`. Focus dropping to body after an act is a regression. */
+  FOCUS_CHANGE: "focus.change",
+  /**
+   * a form field's value moved — `data: { field, kind, value?, checked?, previous?, previousChecked?, redacted?, length }`.
+   *
+   * The DOM observer never saw this: `value` is in its attribute allowlist, but React and every
+   * controlled input set the PROPERTY, so `MutationObserver` does not fire. `value` is omitted and
+   * `redacted` set for a password, a sensitive name, or a payment autocomplete hint; `length` is
+   * always present, because "it was wiped" is assertable without carrying anybody's data.
+   * `checked` is the checkbox/radio property (`value` there is the HTML value, usually `"on"`).
+   * `kind: "settled"` is a read after the action's handlers; `previous` / `previousChecked` are
+   * the pre-action reading, so a restore is distinguishable from a render.
+   */
+  FIELD_CHANGE: "field.change",
+  /** browser → bridge: a human recording compiled in-page. */
+  FLOW_RECORDED: "flow.recorded",
+  /** synthetic: browser transport queue overflowed; events were dropped. `data: { dropped: number }`. */
+  TRANSPORT_OVERFLOW: "transport.overflow",
+  /**
+   * synthetic: a per-channel cap truncated a batch (e.g. a DOM mutation flood). `data: { channel, dropped }`.
+   * Marks downstream rollups/envelopes as built on incomplete data — a ledger that lies at scale is worse
+   * than no ledger, so truncation is never silent.
+   */
+  TRUNCATED: "truncated",
+  /**
+   * synthetic: the SDK detected a region it CANNOT observe (a cross-origin iframe, a closed shadow root).
+   * `data: { kind: BlindSpotKind, count }`. Surfaced on results as `coverage: partial` so a green never
+   * implies it saw everything.
+   */
+  BLIND_SPOT: "blind-spot",
+  /** synthetic: the SDK ITSELF failed (an observer threw). `data: { site, message, errorType }`.
+   *  Rides the existing bridge — no outbound request. See browser/observers/sdk-failure.ts. */
+  SDK_FAILED: "sdk.failed",
+  /**
+   * synthetic (driven only): CDP/Playwright-authoritative network detail for a response the in-page
+   * fetch/XHR wrapper also saw — full response headers + authoritative status/mimeType the page-side
+   * wrapper can't reach. `data: { url, method?, status, headers, resourceType? }`. Merged onto the
+   * matching in-page NET_REQUEST so the driven view never loses fidelity to an outside-in tool.
+   */
+  NET_DETAIL: "net.detail",
+  /**
+   * Live-control: browser → bridge. A human acted on the presenter panel.
+   * `data: { kind: HumanControlKind; text?: string }`. Rides the existing EventMessage.
+   */
+  HUMAN_CONTROL: "human.control",
+  /**
+   * Human review: browser → bridge. A human pinned a mistake to an element on the running page
+   * (the "annotate the bug where you see it" loop). `data` narrows to HumanMarkDataSchema — a note
+   * plus a re-resolvable element anchor (and its source file:line when the framework stamped one) so
+   * the agent that drains the mark knows exactly which element and which source to fix.
+   */
+  HUMAN_MARK: "human.mark",
+  /**
+   * The app produced a FILE — a Blob handed to `URL.createObjectURL`, usually saved by clicking an
+   * anchor with `download`. `data: { filename?, mimeType, bytes, lines?, preview? }`. The one artifact
+   * class no outside-the-browser tool can inspect: it never crosses the network, so there is no
+   * request to intercept. See `observers/download.ts` for the defect that motivated it.
+   */
+  DOWNLOAD: "download",
+  /**
+   * Browser -> bridge: a person used the HUD — pressed a control, or the HUD changed how it sits.
+   * `data` narrows to HudUseDataSchema: names only. Telemetry, not evidence: the session takes it
+   * off the wire before the buffer, so no verdict, settle or agent read ever sees it.
+   */
+  HUD_USED: "hud.used",
+  /**
+   * A `<video>` or `<audio>` changed playback state: `data: { event, tag, currentTime, duration?,
+   * readyState, paused }`. The event's own `t` orders it against the network, which is what a media
+   * defect ("Ready before the response arrived") is: an ordering in time no DOM count shows.
+   */
+  MEDIA_STATE: "media.state",
+  /**
+   * A `<canvas>` drew something different: `data: { digest, width, height, mean }`. A hash of a
+   * 16x16 sample of its pixels and their mean colour, emitted only when the digest changes. What a
+   * canvas shows never reaches the DOM, so without this a canvas app's output is invisible.
+   */
+  CANVAS_DIGEST: "canvas.digest"
+};
+
+// ../../../core/dist/wire/constants/constants.js
+var RETICLE_DEFAULT_PORT = 4400;
+var RETICLE_WS_PATH = "/reticle";
+var RETICLE_CLIENT_HOST = "localhost";
+function bridgeWsUrl(port = RETICLE_DEFAULT_PORT, host = RETICLE_CLIENT_HOST) {
+  return `ws://${host}:${String(port)}${RETICLE_WS_PATH}`;
+}
 var SYNC_BATCH_LIMITS = {
   MAX_RUNS: 50,
   MAX_BYTES: 4 * 1024 * 1024
@@ -4463,6 +4486,8 @@ var ReticleDir = {
   VISUAL_SUBDIR: "visual",
   /** verification-run artifacts —.reticle/runs/<runId>.json (the OEM/CI-consumable verdict). */
   RUNS_SUBDIR: "runs",
+  /** Dev-server logs, only when the state home cannot be written. Machine-local, like `runs/`. */
+  LOGS_SUBDIR: "logs",
   /** fail-to-pass bug capsules —.reticle/capsules/<id>.json (a minimal failing flow + its evidence). */
   CAPSULES_SUBDIR: "capsules",
   /**
@@ -4477,6 +4502,11 @@ var ReticleDir = {
   PLANS_SUBDIR: "plans",
   /** durable causal journal —.reticle/sessions/<id>/{events,actions}.jsonl (the substrate). */
   SESSIONS_SUBDIR: "sessions",
+  /**
+   * Every tool call an agent made, in full, with what it did to the page —
+   * .reticle/episodes/<connection>.jsonl. Local evidence: never committed, never sent.
+   */
+  EPISODES_SUBDIR: "episodes",
   /** append-only event ledger inside a session dir (one ReticleEvent per line). */
   JOURNAL_EVENTS_FILE: "events.jsonl",
   /** append-only action ledger inside a session dir (one JournalAction per line). */
@@ -4492,20 +4522,26 @@ var ReticleDir = {
   JOURNAL_EVENTS_CLOSED_FILE: "events.closed.json",
   /** learned expected-envelopes per route, accumulated across runs (the deviation-report baseline). */
   ENVELOPES_FILE: "envelopes.json",
-  /** learned ambient (action-less churn) region map — excluded from settle/summaries/envelopes. */
   AMBIENT_FILE: "ambient.json",
+  // learned action-less churn regions, excluded from settle/summaries
   /** per-flow flake ledger — replay outcomes that decide intermittent-failure quarantine. */
   FLAKE_FILE: "flake.json",
   /** The app-wide coverage ledger — see server features/exhaust/ledger.ts. */
   COVERAGE_FILE: "coverage.json",
   /** Human review marks (HUD notes), pending and resolved — see server portal/session/human. */
   NOTES_FILE: "notes.json",
-  /** The user's latest request, as the agent relayed it. Local: it is the user's own words. */
+  /** The user's latest request: the newest prompt the hook captured, or the one the agent relayed. Local. */
   REQUEST_FILE: "request.json",
+  /** Every prompt the agent hook captured, one JSON line each, oldest first. `request.json` holds the newest. */
+  REQUESTS_LOG_FILE: "requests.jsonl",
+  /** The prompt history moved aside when `requests.jsonl` fills. The same words, so the same rule. */
+  REQUESTS_LOG_ROTATED_FILE: "requests.1.jsonl",
+  APP_NOTES_FILE: "app-notes.json",
+  // confirmed targeting hints for the next session; never evidence
   PLATFORM_MOMENTS_FILE: "platform-moments.json",
   // moments already said, so each is said once
   /**
-   * the project's cloud binding — .reticle/cloud.json, written by `reticle link`. Git-checked and
+   * the project's cloud binding — .reticle/cloud.json, written by `reticle connect`. Git-checked and
    * non-secret: the project id, the API origin, and where its dashboard lives. The KEY lives in
    * ~/.reticle/credentials.json instead, because that one must never reach a repository.
    */
@@ -4596,6 +4632,111 @@ function projectIdFrom(pkgName, rootPath, hash) {
   return `${base}-${hash(rootPath)}`;
 }
 
+// ../../../core/dist/identity/checkout.js
+var MAX_UP_LEVELS = 50;
+var GITDIR_PREFIX = "gitdir:";
+var BRANCH_PREFIX = "ref: refs/heads/";
+var WORKTREES_SEGMENT = "worktrees";
+var GIT_DIR_NAME = ".git";
+function checkoutOf(dir, readFile) {
+  const sep2 = dir.includes("\\") ? "\\" : "/";
+  let current = trimEnd(dir, sep2);
+  for (let level = 0; level <= MAX_UP_LEVELS; level += 1) {
+    const head = readFile(`${current}${sep2}${GIT_DIR_NAME}${sep2}HEAD`);
+    if (head !== void 0) {
+      return withBranch({
+        root: current,
+        mainRoot: current,
+        commonDir: `${current}${sep2}${GIT_DIR_NAME}`,
+        linked: false
+      }, head);
+    }
+    const pointer = readFile(`${current}${sep2}${GIT_DIR_NAME}`);
+    if (pointer !== void 0 && pointer.trim().startsWith(GITDIR_PREFIX)) {
+      return linkedCheckout(current, pointer.trim().slice(GITDIR_PREFIX.length).trim(), sep2, readFile);
+    }
+    const parent = parentOf(current, sep2);
+    if (parent === void 0)
+      return void 0;
+    current = parent;
+  }
+  return void 0;
+}
+function mainCheckoutTwin(path, readFile) {
+  const checkout = checkoutOf(path, readFile);
+  if (checkout === void 0 || checkout.root === checkout.mainRoot)
+    return void 0;
+  return `${checkout.mainRoot}${path.slice(checkout.root.length)}`;
+}
+function linkedCheckout(root, gitdir, sep2, readFile) {
+  const absolute = resolvePath(root, gitdir.split(/[\\/]/).join(sep2), sep2);
+  const parts = absolute.split(sep2);
+  const isWorktree = WORKTREES_SEGMENT === parts[parts.length - 2];
+  const gitDirOfRepo = parts.slice(0, -2);
+  const commonDir = isWorktree ? gitDirOfRepo.join(sep2) : absolute;
+  const mainRoot = isWorktree && GIT_DIR_NAME === gitDirOfRepo[gitDirOfRepo.length - 1] ? gitDirOfRepo.slice(0, -1).join(sep2) : root;
+  const head = readFile(`${absolute}${sep2}HEAD`);
+  const checkout = { root, mainRoot, commonDir, linked: isWorktree };
+  return head === void 0 ? checkout : withBranch(checkout, head);
+}
+function withBranch(checkout, head) {
+  const ref = head.trim();
+  return ref.startsWith(BRANCH_PREFIX) ? { ...checkout, branch: ref.slice(BRANCH_PREFIX.length) } : checkout;
+}
+function resolvePath(base, rel, sep2) {
+  const absolute = rel.startsWith(sep2) || /^[A-Za-z]:/.test(rel);
+  const parts = (absolute ? rel : `${base}${sep2}${rel}`).split(sep2);
+  const out = [];
+  for (const part of parts) {
+    if ("." === part || "" === part && out.length > 0)
+      continue;
+    if (".." === part) {
+      if (out.length > 1)
+        out.pop();
+      continue;
+    }
+    out.push(part);
+  }
+  return out.join(sep2);
+}
+function parentOf(path, sep2) {
+  const at = path.lastIndexOf(sep2);
+  if (at <= 0)
+    return void 0;
+  const parent = path.slice(0, at);
+  return /^[A-Za-z]:$/.test(parent) ? void 0 : parent;
+}
+function trimEnd(path, sep2) {
+  let end = path.length;
+  while (end > 1 && sep2 === path[end - 1])
+    end -= 1;
+  return path.slice(0, end);
+}
+
+// ../../../core/dist/identity/state-dir.js
+var stateDirNotAbsolute = (dir) => `The Reticle state folder "${dir}" is not an absolute path, so Reticle did not use it. A relative folder is made inside the folder this process runs in, which is often the project. Set ${ReticleEnv.PAIRING_TOKEN_DIR} and ${ReticleEnv.STATE_DIR} to absolute paths, or unset them.`;
+var stateDirResolvedFromCwd = (dir, resolved) => `The Reticle state folder "${dir}" is a relative path. Reticle uses "${resolved}", in the folder this process runs in. Set ${ReticleEnv.PAIRING_TOKEN_DIR} to an absolute path to remove this warning.`;
+var stateDirWindowsPathOnPosix = (dir, fallback) => `The Reticle state folder "${dir}" is a Windows path, and this system does not use Windows paths. Reticle did not use it, and uses "${fallback}". Set ${ReticleEnv.PAIRING_TOKEN_DIR} to a path for this system, or unset it.`;
+var WINDOWS_DRIVE = /^[A-Za-z]:/;
+var POSIX_SEPARATOR = "/";
+function resolveStateDir(override, fallback, rules, warn) {
+  if (override !== void 0 && override.length > 0) {
+    if (rules.isAbsolute(override)) {
+      return override;
+    }
+    if (rules.sep !== POSIX_SEPARATOR || !WINDOWS_DRIVE.test(override)) {
+      const resolved = rules.resolve(override);
+      warn(stateDirResolvedFromCwd(override, resolved));
+      return resolved;
+    }
+    warn(stateDirWindowsPathOnPosix(override, fallback));
+  }
+  if (!rules.isAbsolute(fallback)) {
+    throw new Error(stateDirNotAbsolute(fallback));
+  }
+  return fallback;
+}
+
 // ../../../core/dist/registry/daemon-registry.js
 var DAEMON_REGISTRY_PREFIX = "daemon-";
 var DAEMON_REGISTRY_SUFFIX = ".json";
@@ -4686,6 +4827,32 @@ function readNearestField(startDir, basename, field, readFile, maxDepth, accept)
   }
   return void 0;
 }
+function readConfigField(startDir, field, readFile, accept) {
+  const own = readNearestField(
+    startDir,
+    RETICLE_CONFIG_BASENAME,
+    field,
+    readFile,
+    MAX_CONFIG_SEARCH_DEPTH,
+    accept
+  );
+  if (own !== void 0) return own;
+  const twin = mainCheckoutTwin(startDir, (path) => {
+    try {
+      return readFile(path);
+    } catch {
+      return void 0;
+    }
+  });
+  return twin === void 0 ? void 0 : readNearestField(
+    twin,
+    RETICLE_CONFIG_BASENAME,
+    field,
+    readFile,
+    MAX_CONFIG_SEARCH_DEPTH,
+    accept
+  );
+}
 function readNearestPackageName(startDir, readFile = readFileOrThrow) {
   return readNearestField(
     startDir,
@@ -4697,32 +4864,16 @@ function readNearestPackageName(startDir, readFile = readFileOrThrow) {
   );
 }
 function readConfiguredProjectId(startDir, readFile = readFileOrThrow) {
-  return readNearestField(
-    startDir,
-    RETICLE_CONFIG_BASENAME,
-    "projectId",
-    readFile,
-    MAX_CONFIG_SEARCH_DEPTH,
-    nonEmptyString
-  );
+  return readConfigField(startDir, "projectId", readFile, nonEmptyString);
 }
 function readConfiguredPort(startDir, readFile = readFileOrThrow) {
-  return readNearestField(
-    startDir,
-    RETICLE_CONFIG_BASENAME,
-    "port",
-    readFile,
-    MAX_CONFIG_SEARCH_DEPTH,
-    tcpPort
-  );
+  return readConfigField(startDir, "port", readFile, tcpPort);
 }
 function readConfiguredTestIdAttribute(startDir, readFile = readFileOrThrow) {
-  return readNearestField(
+  return readConfigField(
     startDir,
-    RETICLE_CONFIG_BASENAME,
     "testIdAttribute",
     readFile,
-    MAX_CONFIG_SEARCH_DEPTH,
     (value) => "string" === typeof value && TESTID_ATTR_PATTERN.test(value) ? value : void 0
   );
 }
@@ -4831,6 +4982,12 @@ function announceDevServer(entry, home = stateHome(), io = nodeIo) {
     }
   };
 }
+var DEV_PROXY_URL_ENV = "PORTLESS_URL";
+function announcedUrl(env, reported, port) {
+  const proxied = env[DEV_PROXY_URL_ENV];
+  if (proxied !== void 0 && proxied.length > 0) return proxied;
+  return reported ?? `http://localhost:${String(port)}/`;
+}
 
 // src/svelte-source.ts
 var import_node_module = require("node:module");
@@ -5160,7 +5317,10 @@ export function createReticleEmitter() {
   };
 }
 
-export function commitAndSignal() {}
+// It wraps the APP's write, so the write still runs: Reticle does nothing in production, the app does.
+export function commitAndSignal(_emitter, mutate) {
+  return mutate();
+}
 export function registerReticleDomain() {}
 
 export function buildSnapshot() {
@@ -5377,8 +5537,18 @@ function isHtmlEntry(id, specifier, root) {
   return candidate.endsWith(target.startsWith("/") ? target : `/${target}`);
 }
 function readPairingToken() {
-  const override = process.env[ReticleEnv.PAIRING_TOKEN_DIR];
-  const dir = override !== void 0 && override.length > 0 ? override : (0, import_node_path8.join)((0, import_node_os2.homedir)(), ReticleDir.ROOT);
+  let dir;
+  try {
+    dir = resolveStateDir(
+      process.env[ReticleEnv.PAIRING_TOKEN_DIR],
+      (0, import_node_path8.join)((0, import_node_os2.homedir)(), ReticleDir.ROOT),
+      { isAbsolute: import_node_path8.isAbsolute, resolve: import_node_path8.resolve, sep: import_node_path8.sep },
+      (warning) => console.warn(`[reticle] ${warning}`)
+    );
+  } catch (error) {
+    console.warn(`[reticle] ${error instanceof Error ? error.message : String(error)}`);
+    return void 0;
+  }
   return ensurePairingToken(dir);
 }
 var tokenWarned = false;
@@ -5441,10 +5611,7 @@ function reticle(options = {}) {
   const sourceMapping = options.sourceMapping !== false;
   const inject = options.inject !== false;
   const desktop = true === options.desktop;
-  const resolved = {
-    ...options,
-    projectId: resolveProjectId(options.projectId, process.cwd())
-  };
+  const projectIdIn = (dir) => resolveProjectId(options.projectId, dir);
   let htmlEntrySpecifier;
   let root;
   let command;
@@ -5459,7 +5626,9 @@ function reticle(options = {}) {
   let connectDelivered = false;
   let lastPortWarning;
   const resolveLazy = () => {
-    const { port, warning } = resolveDaemonPort(resolved.port, resolved.projectId, process.cwd());
+    const appDir = root ?? process.cwd();
+    const resolved = { ...options, projectId: projectIdIn(appDir) };
+    const { port, warning } = resolveDaemonPort(resolved.port, resolved.projectId, appDir);
     if (warning !== void 0 && warning !== lastPortWarning) {
       lastPortWarning = warning;
       warn(warning);
@@ -5655,7 +5824,7 @@ ${code}`;
           port,
           pid: process.pid,
           root: opts.root ?? process.cwd(),
-          url: server.resolvedUrls?.local[0] ?? `http://localhost:${String(port)}/`,
+          url: announcedUrl(process.env, server.resolvedUrls?.local[0], port),
           ...opts.sdkVersion === void 0 || 0 === opts.sdkVersion.length ? {} : { sdkVersion: opts.sdkVersion },
           startedAt: Date.now(),
           ...opts.projectId === void 0 ? {} : { projectId: opts.projectId }

package/dist/index.js

@@ -2,11 +2,11 @@ import { existsSync, readFileSync } from 'node:fs';
 import { missingTokenWarning } from './token/missing-token.js';
 import { ensurePairingToken } from './token/ensure-token.js';
 import { homedir } from 'node:os';
-import { join } from 'node:path';
-import { RETICLE_RENDER_PREHOOK, ReticleDir, ReticleEnv, RETICLE_ROOT_GLOBAL, RETICLE_SDK_VERSION_GLOBAL, } from '@reticlehq/core';
+import { isAbsolute, join, resolve, sep } from 'node:path';
+import { RETICLE_RENDER_PREHOOK, ReticleDir, ReticleEnv, RETICLE_ROOT_GLOBAL, RETICLE_SDK_VERSION_GLOBAL, resolveStateDir, } from '@reticlehq/core';
 import { readConfiguredTestIdAttribute, resolveProjectId } from './project-id.js';
 import { resolveDaemonPort } from './discover-port.js';
-import { announceDevServer } from './announce.js';
+import { announceDevServer, announcedUrl } from './announce.js';
 import { stampSvelte } from './svelte-source.js';
 import { NODE_MODULES, ignoredFileNotice, optsOutOfStamping, shouldStamp, shouldStampSvelte, stamp, } from './stamping.js';
 import { resolvableChain, sdkPackageVersion, sdkBuildFingerprint, viteMajor, optimizerOptionsKey, optimizerOptions, } from './installed.js';
@@ -135,8 +135,17 @@ function isHtmlEntry(id, specifier, root) {
  * undefined if the daemon hasn't started yet (the page reloads once it has). Exported for testing.
  */
 export function readPairingToken() {
-    const override = process.env[ReticleEnv.PAIRING_TOKEN_DIR];
-    const dir = override !== undefined && override.length > 0 ? override : join(homedir(), ReticleDir.ROOT);
+    let dir;
+    try {
+        // The daemon's rule: a relative folder is resolved against the working folder, and a Windows
+        // path on POSIX is not used. Both warn, so the two sides agree on one token file.
+        dir = resolveStateDir(process.env[ReticleEnv.PAIRING_TOKEN_DIR], join(homedir(), ReticleDir.ROOT), { isAbsolute, resolve, sep }, (warning) => console.warn(`[reticle] ${warning}`));
+    }
+    catch (error) {
+        // Only a home folder that is not absolute gets here. The dev server still starts.
+        console.warn(`[reticle] ${error instanceof Error ? error.message : String(error)}`);
+        return undefined;
+    }
     // Read-or-CREATE, matching the daemon. Reading alone meant a dev server started before the daemon
     // baked in an empty token and every page it served was refused — with the SDK loading and the
     // socket opening, so nothing looked broken. See ensure-token for the bisect.
@@ -259,12 +268,10 @@ export function reticle(options = {}) {
     const sourceMapping = options.sourceMapping !== false;
     const inject = options.inject !== false;
     const desktop = true === options.desktop;
-    // Resolve the stable projectId once (explicit option, else derived from package.json + cwd) so the
-    // app is identifiable across port changes with zero config.
-    const resolved = {
-        ...options,
-        projectId: resolveProjectId(options.projectId, process.cwd()),
-    };
+    // The stable projectId (explicit option, else `.reticle.json` / package.json in VITE'S root), so the
+    // app is identifiable across port changes with zero config. Read from the root, never the cwd:
+    // `vite apps/admin` from a monorepo root announced the root's app and saved flows under it.
+    const projectIdIn = (dir) => resolveProjectId(options.projectId, dir);
     /**
      * The specifier the HTML points at, e.g. `/src/main.tsx`.
      *
@@ -315,7 +322,9 @@ export function reticle(options = {}) {
      */
     const resolveLazy = () => {
         // Wherever the daemon for this project actually is; the order is argued in discover-port.ts.
-        const { port, warning } = resolveDaemonPort(resolved.port, resolved.projectId, process.cwd());
+        const appDir = root ?? process.cwd();
+        const resolved = { ...options, projectId: projectIdIn(appDir) };
+        const { port, warning } = resolveDaemonPort(resolved.port, resolved.projectId, appDir);
         if (warning !== undefined && warning !== lastPortWarning) {
             lastPortWarning = warning;
             warn(warning);
@@ -568,7 +577,7 @@ export function reticle(options = {}) {
                     port,
                     pid: process.pid,
                     root: opts.root ?? process.cwd(),
-                    url: server.resolvedUrls?.local[0] ?? `http://localhost:${String(port)}/`,
+                    url: announcedUrl(process.env, server.resolvedUrls?.local[0], port),
                     ...(opts.sdkVersion === undefined || 0 === opts.sdkVersion.length
                         ? {}
                         : { sdkVersion: opts.sdkVersion }),

package/dist/project-id.js

@@ -9,7 +9,7 @@
 import { createHash } from 'node:crypto';
 import { dirname, join } from 'node:path';
 import { readFileSync } from 'node:fs';
-import { PROJECT_ID_HASH_LENGTH, TESTID_ATTR_PATTERN, projectIdFrom } from '@reticlehq/core';
+import { PROJECT_ID_HASH_LENGTH, TESTID_ATTR_PATTERN, mainCheckoutTwin, projectIdFrom, } from '@reticlehq/core';
 /** The project config `reticle init` writes, and the id of record it carries. */
 const RETICLE_CONFIG_BASENAME = '.reticle.json';
 export { slugifyPackageName } from '@reticlehq/core';
@@ -76,6 +76,27 @@ function readNearestField(startDir, basename, field, readFile, maxDepth, accept)
     }
     return undefined;
 }
+/**
+ * A field of the nearest `.reticle.json`, else of the main checkout's when `startDir` is in a git
+ * worktree that has none (it is git-ignored, or not committed yet). Every worktree of a project is
+ * the same project: one id, one daemon port.
+ */
+function readConfigField(startDir, field, readFile, accept) {
+    const own = readNearestField(startDir, RETICLE_CONFIG_BASENAME, field, readFile, MAX_CONFIG_SEARCH_DEPTH, accept);
+    if (own !== undefined)
+        return own;
+    const twin = mainCheckoutTwin(startDir, (path) => {
+        try {
+            return readFile(path);
+        }
+        catch {
+            return undefined;
+        }
+    });
+    return twin === undefined
+        ? undefined
+        : readNearestField(twin, RETICLE_CONFIG_BASENAME, field, readFile, MAX_CONFIG_SEARCH_DEPTH, accept);
+}
 /** Read the `name` from the nearest package.json at or above `startDir`, or undefined if none. */
 function readNearestPackageName(startDir, readFile = readFileOrThrow) {
     return readNearestField(startDir, 'package.json', 'name', readFile, MAX_PACKAGE_SEARCH_DEPTH, nonEmptyString);
@@ -87,7 +108,7 @@ function readNearestPackageName(startDir, readFile = readFileOrThrow) {
  * through `init` — it is not a second opinion, and where the two disagree the config wins.
  */
 export function readConfiguredProjectId(startDir, readFile = readFileOrThrow) {
-    return readNearestField(startDir, RETICLE_CONFIG_BASENAME, 'projectId', readFile, MAX_CONFIG_SEARCH_DEPTH, nonEmptyString);
+    return readConfigField(startDir, 'projectId', readFile, nonEmptyString);
 }
 /**
  * Read the daemon port `reticle init --port` recorded in the nearest `.reticle.json`, or undefined.
@@ -97,7 +118,7 @@ export function readConfiguredProjectId(startDir, readFile = readFileOrThrow) {
  * project's daemon — and the bridge refused it.
  */
 export function readConfiguredPort(startDir, readFile = readFileOrThrow) {
-    return readNearestField(startDir, RETICLE_CONFIG_BASENAME, 'port', readFile, MAX_CONFIG_SEARCH_DEPTH, tcpPort);
+    return readConfigField(startDir, 'port', readFile, tcpPort);
 }
 /**
  * Read `testIdAttribute` from the nearest `.reticle.json`, or undefined: the attribute this project
@@ -106,7 +127,7 @@ export function readConfiguredPort(startDir, readFile = readFileOrThrow) {
  * already agree on, so the plugin forwards it to `connect()` rather than asking for it twice.
  */
 export function readConfiguredTestIdAttribute(startDir, readFile = readFileOrThrow) {
-    return readNearestField(startDir, RETICLE_CONFIG_BASENAME, 'testIdAttribute', readFile, MAX_CONFIG_SEARCH_DEPTH, (value) => ('string' === typeof value && TESTID_ATTR_PATTERN.test(value) ? value : undefined));
+    return readConfigField(startDir, 'testIdAttribute', readFile, (value) => 'string' === typeof value && TESTID_ATTR_PATTERN.test(value) ? value : undefined);
 }
 /**
  * Resolve the projectId for a plugin instance, most-local statement of intent first: an explicit

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reticlehq/vite-plugin",
-  "version": "3.6.0",
+  "version": "3.8.0",
   "description": "Vite plugin for Reticle: dev-only source-map stamping plus auto-injected reticle.connect(). apply:'serve' guarantees it never ships to production.",
   "type": "module",
   "license": "Apache-2.0",
@@ -41,15 +41,15 @@
   ],
   "dependencies": {
     "@babel/core": "^7.26.0",
-    "@reticlehq/babel-plugin": "3.6.0",
-    "@reticlehq/core": "3.6.0"
+    "@reticlehq/core": "3.8.0",
+    "@reticlehq/babel-plugin": "3.8.0"
   },
   "devDependencies": {
     "@types/babel__core": "^7.20.5",
     "esbuild": "^0.28.2",
     "svelte": "^5.57.1",
     "vite": "^8",
-    "@reticlehq/react": "3.6.0"
+    "@reticlehq/react": "3.8.0"
   },
   "peerDependencies": {
     "vite": ">=4"