@reticlehq/server 3.4.0 → 3.6.0

package/dist/surface/tools/lease-seed.js

@@ -0,0 +1,123 @@
+/**
+ * Seeded storage for a lease, and the errors a lease's navigation throws: what a caller may see of
+ * them without seeing the secrets it seeded. Split from lease-tools.ts, which crossed the line cap.
+ */
+import { REDACTED_VALUE, scrubKnownSecrets } from '@reticlehq/core';
+function redactExactValue(text, value) {
+    if (0 === value.length)
+        return text;
+    const escaped = value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    return text.replace(new RegExp(`(^|[^a-zA-Z0-9])${escaped}(?=$|[^a-zA-Z0-9])`, 'g'), `$1${REDACTED_VALUE}`);
+}
+/**
+ * Scrub known secret shapes and raw seedStorage values (cookies, localStorage, sessionStorage)
+ * from an error string before it reaches daemon logs, metrics, or MCP error responses.
+ */
+export function scrubSeedFromError(text, seed) {
+    let out = scrubKnownSecrets(text);
+    if (undefined !== seed && null !== seed && 'object' === typeof seed) {
+        const s = seed;
+        const cookies = s['cookies'];
+        if (undefined !== cookies && null !== cookies) {
+            if (Array.isArray(cookies)) {
+                for (const c of cookies) {
+                    if (undefined !== c && null !== c && 'object' === typeof c) {
+                        const val = c['value'];
+                        if (undefined !== val && 'string' === typeof val) {
+                            out = redactExactValue(out, val);
+                        }
+                    }
+                }
+            }
+            else if ('object' === typeof cookies) {
+                for (const v of Object.values(cookies)) {
+                    if ('string' === typeof v) {
+                        out = redactExactValue(out, v);
+                    }
+                }
+            }
+        }
+        const local = s['local'];
+        if (undefined !== local && null !== local && 'object' === typeof local) {
+            for (const v of Object.values(local)) {
+                if ('string' === typeof v) {
+                    out = redactExactValue(out, v);
+                }
+            }
+        }
+        const session = s['session'];
+        if (undefined !== session && null !== session && 'object' === typeof session) {
+            for (const v of Object.values(session)) {
+                if ('string' === typeof v) {
+                    out = redactExactValue(out, v);
+                }
+            }
+        }
+    }
+    return out;
+}
+/** True for a Playwright `storageState()` export (`{ origins: [...] }`), not our seed shape. */
+export function looksLikeStorageStateExport(seed) {
+    return Array.isArray(seed?.origins);
+}
+/**
+ * Turn a raw navigation failure (Playwright's `page.goto: net::ERR_… at <url>\nCall log:…`, often
+ * with ANSI codes) into a short, clean reason — so the agent/user sees "is the app running?" instead
+ * of an internals-leaking wall of text.
+ */
+export function cleanNavError(err, seed) {
+    const rawMsg = err instanceof Error ? err.message : String(err);
+    const msg = scrubSeedFromError(rawMsg, seed);
+    // Strip ANSI color codes (ESC[…m) Playwright emits — built via fromCharCode to keep the
+    // control character out of a regex literal (no-control-regex).
+    const ansi = new RegExp(`${String.fromCharCode(27)}\\[[0-9;]*m`, 'g');
+    const firstLine = (msg.split('\n')[0] ?? msg).replace(ansi, '');
+    const netCode = /net::[A-Z_]+/.exec(firstLine);
+    if (netCode !== null)
+        return netCode[0];
+    if (/timeout/i.test(firstLine))
+        return 'navigation timed out';
+    return firstLine
+        .replace(/^page\.goto:\s*/, '')
+        .replace(/\s+at\s+https?:\/\/\S+.*$/, '')
+        .trim()
+        .slice(0, 100);
+}
+/**
+ * Determine if a required seedStorage application precondition failed.
+ *
+ * Checks strong signals:
+ * 1. HTTP 401/403 status on the initial navigation.
+ * 2. Cross-origin redirect when localStorage or sessionStorage was requested (skipped by origin-scoping).
+ * 3. Clear redirect to an authentication/login endpoint when the requested URL was not a login page.
+ *
+ * Normal app redirects (e.g. / → /dashboard) are valid and return undefined.
+ */
+export function evaluateSeedPrecondition(requestedUrl, actualUrl, seed, navStatus) {
+    if (401 === navStatus || 403 === navStatus) {
+        return `HTTP ${navStatus} returned on initial seeded navigation to ${requestedUrl}`;
+    }
+    if (actualUrl === undefined || '' === actualUrl.trim())
+        return undefined;
+    let reqParsed;
+    let actParsed;
+    try {
+        reqParsed = new URL(requestedUrl);
+        actParsed = new URL(actualUrl);
+    }
+    catch {
+        return undefined;
+    }
+    // Cross-origin redirect when local or session storage was requested
+    const hasStorage = (undefined !== seed.local && 0 < Object.keys(seed.local).length) ||
+        (undefined !== seed.session && 0 < Object.keys(seed.session).length);
+    if (hasStorage && reqParsed.origin !== actParsed.origin) {
+        return `seeded storage precondition not established: cross-origin redirect from ${reqParsed.origin} to ${actParsed.origin} skipped origin-scoped storage injection`;
+    }
+    // Clear redirect to an authentication/login endpoint when the requested URL was not a login page
+    const isAuthPath = (pathname) => /(?:^|\/)(?:login|signin|sign-in|auth\/login|auth\/signin|session\/new)(?:$|\/)/i.test(pathname);
+    if (!isAuthPath(reqParsed.pathname) && isAuthPath(actParsed.pathname)) {
+        return `seeded authentication precondition not established: redirected from ${reqParsed.pathname} to login page (${actParsed.pathname})`;
+    }
+    return undefined;
+}

package/dist/surface/tools/lease-tools.d.ts

@@ -14,34 +14,14 @@ import { type StorageFixturePort } from '../../portal/input/storage-fixture.js';
 import { type NetworkMutationPort } from '../../portal/input/network-mutation.js';
 import type { Perturbation } from '@reticlehq/core';
 import { type SeedStorage } from '@reticlehq/core';
+import { HudVisibility } from '@reticlehq/core';
 import type { ToolDef } from './tool-kit.js';
 /**
  * Append Reticle identity params (__reticle_session, optional __reticle_project) to a URL so the app's own SDK
  * adopts them on connect. Pure; falls back to plain concatenation if the URL can't be parsed.
  */
-export declare function appendReticleParams(url: string, session: string, projectId?: string): string;
-/**
- * Scrub known secret shapes and raw seedStorage values (cookies, localStorage, sessionStorage)
- * from an error string before it reaches daemon logs, metrics, or MCP error responses.
- */
-export declare function scrubSeedFromError(text: string, seed?: unknown): string;
-/**
- * Turn a raw navigation failure (Playwright's `page.goto: net::ERR_… at <url>\nCall log:…`, often
- * with ANSI codes) into a short, clean reason — so the agent/user sees "is the app running?" instead
- * of an internals-leaking wall of text.
- */
-export declare function cleanNavError(err: unknown, seed?: SeedStorage): string;
-/**
- * Determine if a required seedStorage application precondition failed.
- *
- * Checks strong signals:
- * 1. HTTP 401/403 status on the initial navigation.
- * 2. Cross-origin redirect when localStorage or sessionStorage was requested (skipped by origin-scoping).
- * 3. Clear redirect to an authentication/login endpoint when the requested URL was not a login page.
- *
- * Normal app redirects (e.g. / → /dashboard) are valid and return undefined.
- */
-export declare function evaluateSeedPrecondition(requestedUrl: string, actualUrl: string | undefined, seed: SeedStorage, navStatus?: number): string | undefined;
+export declare function appendReticleParams(url: string, session: string, projectId?: string, hud?: HudVisibility): string;
+export { cleanNavError, evaluateSeedPrecondition, scrubSeedFromError } from './lease-seed.js';
 /**
  * The session a lease's tab actually registered as, or undefined while nothing has.
  *

package/dist/surface/tools/lease-tools.js

@@ -20,10 +20,10 @@ import { readProjectFramework, readProjectId } from '../../command/cli/ports/res
 import { hasAnyAppConnectedBefore } from '../../memory/recall/prior/connection-memory.js';
 import { AGENT_DRIVING_ELSEWHERE, AGENT_DRIVING_HERE_AGAIN, watchersToNotify, } from '../../portal/session/lease-visibility.js';
 import { reticleStateHome } from '../../command/daemon/daemon.js';
-import { LeaseNotReadyReason, REDACTED_VALUE, RETICLE_URL_PARAM, RETICLE_DEFAULT_PORT, ReticleCommand, SeedStorageSchema, scrubKnownSecrets, } from '@reticlehq/core';
-import { ReticleTool, SESSION_HEALTH } from '@reticlehq/core';
+import { LeaseNotReadyReason, RETICLE_URL_PARAM, RETICLE_DEFAULT_PORT, ReticleCommand, SeedStorageSchema, } from '@reticlehq/core';
+import { HudVisibility, ReticleTool, SESSION_HEALTH } from '@reticlehq/core';
 import { asString } from '@reticlehq/core';
-import { chromiumHint } from '../../command/cli/doctor/browser/chromium-hint.js';
+import { chromiumPreflightRefusal } from '../../command/cli/doctor/browser/chromium-hint.js';
 /**
  * Everything the daemon already knows about why a leased tab might not have dialled in.
  *
@@ -95,13 +95,15 @@ function alreadyHeldHint(sessionId, origin) {
  * Append Reticle identity params (__reticle_session, optional __reticle_project) to a URL so the app's own SDK
  * adopts them on connect. Pure; falls back to plain concatenation if the URL can't be parsed.
  */
-export function appendReticleParams(url, session, projectId) {
+export function appendReticleParams(url, session, projectId, hud) {
     try {
         const u = new URL(url);
         u.searchParams.set(RETICLE_URL_PARAM.SESSION, session);
         if (projectId !== undefined && projectId.length > 0) {
             u.searchParams.set(RETICLE_URL_PARAM.PROJECT, projectId);
         }
+        if (hud !== undefined)
+            u.searchParams.set(RETICLE_URL_PARAM.HUD, hud);
         return u.toString();
     }
     catch {
@@ -112,124 +114,8 @@ export function appendReticleParams(url, session, projectId) {
         return `${url}${sep}${RETICLE_URL_PARAM.SESSION}=${encodeURIComponent(session)}${proj}`;
     }
 }
-function redactExactValue(text, value) {
-    if (0 === value.length)
-        return text;
-    const escaped = value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-    return text.replace(new RegExp(`(^|[^a-zA-Z0-9])${escaped}(?=$|[^a-zA-Z0-9])`, 'g'), `$1${REDACTED_VALUE}`);
-}
-/**
- * Scrub known secret shapes and raw seedStorage values (cookies, localStorage, sessionStorage)
- * from an error string before it reaches daemon logs, metrics, or MCP error responses.
- */
-export function scrubSeedFromError(text, seed) {
-    let out = scrubKnownSecrets(text);
-    if (undefined !== seed && null !== seed && 'object' === typeof seed) {
-        const s = seed;
-        const cookies = s['cookies'];
-        if (undefined !== cookies && null !== cookies) {
-            if (Array.isArray(cookies)) {
-                for (const c of cookies) {
-                    if (undefined !== c && null !== c && 'object' === typeof c) {
-                        const val = c['value'];
-                        if (undefined !== val && 'string' === typeof val) {
-                            out = redactExactValue(out, val);
-                        }
-                    }
-                }
-            }
-            else if ('object' === typeof cookies) {
-                for (const v of Object.values(cookies)) {
-                    if ('string' === typeof v) {
-                        out = redactExactValue(out, v);
-                    }
-                }
-            }
-        }
-        const local = s['local'];
-        if (undefined !== local && null !== local && 'object' === typeof local) {
-            for (const v of Object.values(local)) {
-                if ('string' === typeof v) {
-                    out = redactExactValue(out, v);
-                }
-            }
-        }
-        const session = s['session'];
-        if (undefined !== session && null !== session && 'object' === typeof session) {
-            for (const v of Object.values(session)) {
-                if ('string' === typeof v) {
-                    out = redactExactValue(out, v);
-                }
-            }
-        }
-    }
-    return out;
-}
-/** True for a Playwright `storageState()` export (`{ origins: [...] }`), not our seed shape. */
-function looksLikeStorageStateExport(seed) {
-    return Array.isArray(seed?.origins);
-}
-/**
- * Turn a raw navigation failure (Playwright's `page.goto: net::ERR_… at <url>\nCall log:…`, often
- * with ANSI codes) into a short, clean reason — so the agent/user sees "is the app running?" instead
- * of an internals-leaking wall of text.
- */
-export function cleanNavError(err, seed) {
-    const rawMsg = err instanceof Error ? err.message : String(err);
-    const msg = scrubSeedFromError(rawMsg, seed);
-    // Strip ANSI color codes (ESC[…m) Playwright emits — built via fromCharCode to keep the
-    // control character out of a regex literal (no-control-regex).
-    const ansi = new RegExp(`${String.fromCharCode(27)}\\[[0-9;]*m`, 'g');
-    const firstLine = (msg.split('\n')[0] ?? msg).replace(ansi, '');
-    const netCode = /net::[A-Z_]+/.exec(firstLine);
-    if (netCode !== null)
-        return netCode[0];
-    if (/timeout/i.test(firstLine))
-        return 'navigation timed out';
-    return firstLine
-        .replace(/^page\.goto:\s*/, '')
-        .replace(/\s+at\s+https?:\/\/\S+.*$/, '')
-        .trim()
-        .slice(0, 100);
-}
-/**
- * Determine if a required seedStorage application precondition failed.
- *
- * Checks strong signals:
- * 1. HTTP 401/403 status on the initial navigation.
- * 2. Cross-origin redirect when localStorage or sessionStorage was requested (skipped by origin-scoping).
- * 3. Clear redirect to an authentication/login endpoint when the requested URL was not a login page.
- *
- * Normal app redirects (e.g. / → /dashboard) are valid and return undefined.
- */
-export function evaluateSeedPrecondition(requestedUrl, actualUrl, seed, navStatus) {
-    if (401 === navStatus || 403 === navStatus) {
-        return `HTTP ${navStatus} returned on initial seeded navigation to ${requestedUrl}`;
-    }
-    if (actualUrl === undefined || '' === actualUrl.trim())
-        return undefined;
-    let reqParsed;
-    let actParsed;
-    try {
-        reqParsed = new URL(requestedUrl);
-        actParsed = new URL(actualUrl);
-    }
-    catch {
-        return undefined;
-    }
-    // Cross-origin redirect when local or session storage was requested
-    const hasStorage = (undefined !== seed.local && 0 < Object.keys(seed.local).length) ||
-        (undefined !== seed.session && 0 < Object.keys(seed.session).length);
-    if (hasStorage && reqParsed.origin !== actParsed.origin) {
-        return `seeded storage precondition not established: cross-origin redirect from ${reqParsed.origin} to ${actParsed.origin} skipped origin-scoped storage injection`;
-    }
-    // Clear redirect to an authentication/login endpoint when the requested URL was not a login page
-    const isAuthPath = (pathname) => /(?:^|\/)(?:login|signin|sign-in|auth\/login|auth\/signin|session\/new)(?:$|\/)/i.test(pathname);
-    if (!isAuthPath(reqParsed.pathname) && isAuthPath(actParsed.pathname)) {
-        return `seeded authentication precondition not established: redirected from ${reqParsed.pathname} to login page (${actParsed.pathname})`;
-    }
-    return undefined;
-}
+export { cleanNavError, evaluateSeedPrecondition, scrubSeedFromError } from './lease-seed.js';
+import { cleanNavError, evaluateSeedPrecondition, looksLikeStorageStateExport, scrubSeedFromError, } from './lease-seed.js';
 /** A fresh, collision-resistant lease id. Uses crypto at the I/O boundary (not pure logic). */
 function newLeaseId() {
     const uuid = 'function' === typeof globalThis.crypto?.randomUUID
@@ -437,7 +323,15 @@ export const LEASE_ACQUIRE_TOOL = {
             .string()
             .optional()
             .describe('Stable project id to stamp on the leased tab so the agent can scope to it.'),
-        seedStorage: SeedStorageSchema.optional().describe('Initial storage state (localStorage, sessionStorage, cookies) to seed before the first navigation (e.g. to start already authenticated).'),
+        seedStorage: SeedStorageSchema.optional().describe('Initial storage state (local, session and cookies) to seed before the first navigation (e.g. `seedStorage: { local: { token: "..." } }` to start already authenticated).'),
+        headed: z
+            .boolean()
+            .optional()
+            .describe('Open it in a browser window somebody can watch, instead of headless.'),
+        hud: z
+            .enum([HudVisibility.SHOWN, HudVisibility.HIDDEN, HudVisibility.REMOVED])
+            .optional()
+            .describe('How the HUD starts on the page: shown (default), hidden, or removed.'),
     },
     outputSchema: {
         sessionId: z.string(),
@@ -487,12 +381,13 @@ export const LEASE_ACQUIRE_TOOL = {
         // fine. Say the real thing at the first refusal instead. The phrasing carries "Chromium is not
         // installed" so error-recovery routes it to the NO_POOL fix (install + drive a human tab).
         if (deps.browserProbe !== undefined) {
-            const probe = await deps.browserProbe();
-            if (!probe.exists) {
-                throw new Error(`Chromium is not installed for Playwright — ${chromiumHint(probe)}`);
-            }
+            const refusal = chromiumPreflightRefusal(await deps.browserProbe());
+            if (refusal !== undefined)
+                throw new Error(refusal);
         }
         const projectId = asString(args['projectId']);
+        const headed = true === args['headed'];
+        const hud = Object.values(HudVisibility).find((v) => v === args['hud']);
         const seedStorageArg = args['seedStorage'];
         let validatedSeed;
         if (seedStorageArg !== undefined) {
@@ -526,10 +421,12 @@ export const LEASE_ACQUIRE_TOOL = {
             await priorLock.catch(() => undefined);
         }
         try {
-            const existing = origin === undefined ? undefined : pool.leaseIdOnOrigin?.(origin);
+            // Only a lease THIS caller took: another agent's tab is never reused or released (#1226).
+            // A window asked for is never answered with the headless tab on that origin, nor the reverse.
+            const held = origin === undefined ? undefined : pool.leaseIdOnOrigin(origin, deps.attachId);
+            const existing = held !== undefined && pool.isHeaded(held) === headed ? held : undefined;
             if (validatedSeed !== undefined && existing !== undefined) {
-                // Caller explicitly requested storage seeding: do not reuse an existing context on this origin,
-                // release it so the new lease starts clean with the caller-provided state.
+                // Seeding asked for: release its own context so the new lease starts with the given state.
                 await pool.release(existing);
             }
             else if (existing !== undefined && origin !== undefined) {
@@ -574,11 +471,13 @@ export const LEASE_ACQUIRE_TOOL = {
                 await pool.release(existing);
             }
             const sessionId = newLeaseId();
-            const navUrl = appendReticleParams(url, sessionId, projectId);
+            const navUrl = appendReticleParams(url, sessionId, projectId, hud);
             let lease;
             try {
                 lease = await pool.acquire(navUrl, {
                     sessionId,
+                    ...(headed ? { headed } : {}),
+                    ...(deps.attachId === undefined ? {} : { owner: deps.attachId }),
                     ...(validatedSeed !== undefined ? { seedStorage: validatedSeed } : {}),
                 });
             }

package/dist/surface/tools/live-call-text.js

@@ -80,8 +80,8 @@ const NO_TOOL_EQUIVALENT = [
      * every session, and the longer two-route version cost 67 bytes there against a budget measured
      * in whole-session terms — for advice that is read once, on a first run.
      *
-     * `explore` needs ANTHROPIC_API_KEY and says so itself when it is missing, naming the fallback in
-     * the same breath ("flows are recorded by your own coding agent through the MCP tools"). That
+     * `explore` runs on the platform and says so itself when it is not linked, naming the fallback in
+     * the same breath (drive the journey yourself with the MCP tools). That
      * error is now recognised as ours, so the reader who hits it gets the next step instead of an
      * invitation to file a defect report. One hop, and every hop is honest.
      */

package/dist/surface/tools/next-step.d.ts

@@ -0,0 +1,19 @@
+export declare const NextText: {
+    readonly DECLARE: "Record what the user asked, once per task, verbatim: reticle_run { tool: \"reticle_intent\", args: { action: \"declare\", request: \"<their words>\" } }. It travels with every run.";
+    readonly SYNC_PROBLEM: (why: string) => string;
+    readonly CONNECT: "These runs stay on this machine. To share them on the team dashboard, the user runs once: npx @reticlehq/server connect";
+    readonly FINISH_LINKED: "Done driving? reticle_session { action: \"yield\" } hands the tab back; this run syncs to the platform on its own.";
+    readonly FINISH: "Done driving? reticle_session { action: \"yield\" } hands the tab back.";
+    readonly REPLAY: (flows: number) => string;
+};
+/** Tests only. */
+export declare function resetNextStep(): void;
+export interface NextStepInput {
+    tool: string;
+    /** Whether this result carries a verdict. */
+    verdict: boolean;
+    root: string | undefined;
+    now: number;
+}
+/** The line, or undefined when there is nothing the agent should be told right now. */
+export declare function nextStep(input: NextStepInput): string | undefined;

package/dist/surface/tools/next-step.js

@@ -0,0 +1,159 @@
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+import { ReticleDir, ReticleEnv } from '@reticlehq/core';
+/**
+ * The one thing the agent should do next, on the result of the call it just made.
+ *
+ * Every client reads tool results; few read a briefing twice, and none keep a skill in mind across a
+ * long session. So what an agent must not forget (record what the user asked, hand the tab back,
+ * notice when its runs are not reaching the platform, tell the user how to connect) is said where
+ * the agent is already looking, one short line, on the moment it applies. It is placed first in the
+ * result, because a model that truncates a long result keeps its beginning.
+ *
+ * The daemon syncs runs itself, whichever agent drove them; nothing here asks an agent to push.
+ * It only says when the sync needs a person (a refusal, a failure, a project never connected).
+ */
+/** How long a declared request counts as "the current task". Matches the run store's window. */
+const REQUEST_FRESH_MS = 6 * 60 * 60 * 1000;
+/** A reminder that is not about a verdict is repeated at most this often, per project. */
+const QUIET_CALLS = 10;
+/** An unlinked project hears how to connect on every Nth verdict, the first included. */
+const CONNECT_EVERY = 5;
+/**
+ * How often the agent is asked to record the request before the other lines get their turn. In
+ * every recorded run the agent ignored it, and because it always won, no agent was ever told its
+ * runs were not reaching the platform.
+ */
+const DECLARE_ASKS = 2;
+/** A run file this much newer than the last push, and this old, was not sent. */
+const UNSENT_AFTER_MS = 2 * 60 * 1000;
+export const NextText = {
+    DECLARE: 'Record what the user asked, once per task, verbatim: reticle_run { tool: "reticle_intent", args: { action: "declare", request: "<their words>" } }. It travels with every run.',
+    SYNC_PROBLEM: (why) => `Runs are not reaching the platform (${why}). reticle_run { tool: "reticle_project", args: { push: true } } retries and reports why.`,
+    CONNECT: 'These runs stay on this machine. To share them on the team dashboard, the user runs once: npx @reticlehq/server connect',
+    FINISH_LINKED: 'Done driving? reticle_session { action: "yield" } hands the tab back; this run syncs to the platform on its own.',
+    FINISH: 'Done driving? reticle_session { action: "yield" } hands the tab back.',
+    REPLAY: (flows) => `This app has ${String(flows)} saved flow(s). Replay them before driving anything by hand: reticle_verify { action: "flows" } re-verifies them with no model.`,
+};
+const roots = new Map();
+/** Tests only. */
+export function resetNextStep() {
+    roots.clear();
+}
+function readJson(path) {
+    try {
+        const parsed = JSON.parse(readFileSync(path, 'utf8'));
+        return 'object' === typeof parsed && null !== parsed
+            ? parsed
+            : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Declared within the window, read from the file's own stamp (or its age when it has none). */
+function requestDeclared(root, now) {
+    const path = join(root, ReticleDir.REQUEST_FILE);
+    if (!existsSync(path))
+        return false;
+    const at = readJson(path)?.['at'];
+    const when = 'number' === typeof at ? at : statSync(path).mtimeMs;
+    return now - when < REQUEST_FRESH_MS;
+}
+/** Run files written after the last push and old enough that a sync cycle should have sent them. */
+function unsentRuns(root, lastPushAt, now) {
+    try {
+        const dir = join(root, ReticleDir.RUNS_SUBDIR);
+        return readdirSync(dir).filter((name) => {
+            const at = statSync(join(dir, name)).mtimeMs;
+            return at > lastPushAt + UNSENT_AFTER_MS && now - at > UNSENT_AFTER_MS;
+        }).length;
+    }
+    catch {
+        return 0;
+    }
+}
+/**
+ * Why sync needs a person, from the sync's own bookkeeping; undefined when it is fine.
+ *
+ * Runs that were written and never sent count too. A project the sync loop never looked at has no
+ * error and no refusal, which is how a whole day of runs stayed on one machine with every check
+ * reporting fine.
+ */
+function syncProblem(root, now) {
+    const state = readJson(join(root, ReticleDir.CLOUD_STATE_FILE));
+    const pushed = state?.['lastPushAt'];
+    const unsent = unsentRuns(root, 'number' === typeof pushed ? pushed : 0, now);
+    if (0 < unsent)
+        return `${String(unsent)} run(s) written here were never sent`;
+    if (state === undefined)
+        return undefined;
+    const error = state['lastError'];
+    if ('string' === typeof error && 0 < error.length)
+        return error.slice(0, 120);
+    const refused = state['refusedRuns'];
+    const count = 'object' === typeof refused && null !== refused ? Object.keys(refused).length : 0;
+    return 0 < count ? `${String(count)} run(s) refused` : undefined;
+}
+/** Saved flow files under `flows/`, one level of project folders deep. */
+function savedFlows(dir) {
+    try {
+        return readdirSync(dir, { withFileTypes: true }).reduce((n, entry) => n +
+            (entry.isDirectory()
+                ? readdirSync(join(dir, entry.name)).filter((f) => f.endsWith('.json')).length
+                : entry.name.endsWith('.json')
+                    ? 1
+                    : 0), 0);
+    }
+    catch {
+        return 0;
+    }
+}
+/** The line, or undefined when there is nothing the agent should be told right now. */
+export function nextStep(input) {
+    const { root } = input;
+    if (root === undefined)
+        return undefined;
+    const state = roots.get(root) ?? {
+        calls: 0,
+        verdicts: 0,
+        lastQuietAt: Number.NEGATIVE_INFINITY,
+        declareAsks: 0,
+        replayTold: false,
+    };
+    roots.set(root, state);
+    state.calls += 1;
+    if (input.verdict)
+        state.verdicts += 1;
+    const linked = existsSync(join(root, ReticleDir.CLOUD_LINK_FILE));
+    // A key in the environment syncs too, so its runs not arriving is just as much a problem.
+    const sends = linked || 0 < (process.env[ReticleEnv.API_KEY] ?? '').length;
+    const quietDue = state.calls - state.lastQuietAt >= QUIET_CALLS;
+    // Measured on a whole-app drive: an agent re-drove everything by hand while saved flows sat
+    // unreplayed, though the skill says to replay first. Said on the first call, where it is in time.
+    if (!state.replayTold && !input.tool.endsWith('verify')) {
+        state.replayTold = true;
+        const saved = savedFlows(join(root, ReticleDir.FLOWS_SUBDIR));
+        if (0 < saved)
+            return NextText.REPLAY(saved);
+    }
+    const problem = sends ? syncProblem(root, input.now) : undefined;
+    if (problem !== undefined && (input.verdict || quietDue)) {
+        state.lastQuietAt = state.calls;
+        return NextText.SYNC_PROBLEM(problem);
+    }
+    // Not on the declare call itself, which is the answer to this line.
+    if (!input.tool.endsWith('intent') &&
+        state.declareAsks < DECLARE_ASKS &&
+        !requestDeclared(root, input.now) &&
+        (input.verdict || quietDue)) {
+        state.lastQuietAt = state.calls;
+        state.declareAsks += 1;
+        return NextText.DECLARE;
+    }
+    if (!input.verdict)
+        return undefined;
+    if (!sends && 1 === state.verdicts % CONNECT_EVERY)
+        return NextText.CONNECT;
+    return sends ? NextText.FINISH_LINKED : NextText.FINISH;
+}

package/dist/surface/tools/observe-tools.js

@@ -258,7 +258,7 @@ export const OBSERVE_TOOLS = [
             if (bodyRefusal !== undefined)
                 throw new Error(bodyRefusal);
             // Honesty: explicit since wins; else default to the last act's cursor; else the whole buffer.
-            let since = asNumber(args['since']) ?? session.lastAct.cursor() ?? 0;
+            const since = asNumber(args['since']) ?? session.lastAct.cursor() ?? 0;
             // See the note on the assert handler below: a wait cut off by a full-document navigation is
             // followed to the document that took over, rather than graded as a lost observation there.
             const predicateStarted = session.elapsed();
@@ -270,8 +270,6 @@ export const OBSERVE_TOOLS = [
                 predicateStarted,
                 reevaluate: (next, budget) => waitForPredicate(next, predicate, budget, 0),
             });
-            if (followed.followed)
-                since = 0;
             session = followed.session;
             const verdict = followed.verdict;
             // match reticle_assert — wrap with control + session health (throttle matters most while blocking)
@@ -452,7 +450,7 @@ export const OBSERVE_TOOLS = [
             // explicit `since` may reach back past the last step, where replay would not find it. The
             // store itself refuses when a navigation came after that step: see RecordingStore.markNavigated.
             if (Verified.YES === decision['verified'] && args['since'] === undefined) {
-                captureAssertion(deps.recordings, predicate);
+                captureAssertion(deps.recordings, predicate, session.id);
             }
             return withControl(session, {
                 ...decision,

package/dist/surface/tools/platform-moment.d.ts

@@ -0,0 +1,12 @@
+import type { ToolDeps } from './tool-kit.js';
+/** Verified runs kept only on this machine before the platform is worth a sentence. */
+export declare const LOCAL_RUNS_MOMENT = 5;
+/** A `.reticle` this large is history worth keeping somewhere other than one laptop. */
+export declare const LARGE_RETICLE_BYTES: number;
+export declare function takePlatformMoment(deps: Pick<ToolDeps, 'fs' | 'linkedCloud'> & {
+    now?: () => number;
+}, raw: Record<string, unknown>, 
+/** The `.reticle` of the project the verdict was about — the session's, not the daemon's. */
+rootOf: () => string): Promise<string | undefined>;
+/** Tests only. */
+export declare function resetPlatformMoments(): void;