@reticlehq/server 3.2.0 → 3.3.0

package/dist/command/cli/report-command.js

@@ -0,0 +1,97 @@
+/**
+ * `reticle report [--session <id>] [--hook]` — what this project's latest session claimed, and what held.
+ *
+ * Read from disk, with no daemon: the journal is on disk, and a Stop hook has to answer in the second
+ * after the agent stops, when there may be nothing running to ask. The fold is `gapSummary`, the same
+ * one `reticle_context` serves, so the terminal and the agent cannot be told two different stories.
+ */
+import { execFileSync } from 'node:child_process';
+import { existsSync, readdirSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+import { DiscoveryInvite, ReticleDir } from '@reticlehq/core';
+import { gapSummary } from '../../judgement/runs/artifact/gap-summary.js';
+import { SessionJournal } from '../../memory/journal/session-journal.js';
+import { createNodeFileSystem } from '../../memory/project/fs/fs-port.js';
+import { gapHookLine, gapReportLines } from '../../judgement/runs/artifact/gap-report.js';
+/**
+ * A session last written longer ago than this is not the turn a hook is asking about.
+ *
+ * ponytail: a fixed window, not a turn boundary — the Stop hook is not told when the turn began. A
+ * drive older than an hour reads as "no claim this session", which errs toward saying so.
+ */
+const HOOK_WINDOW_MS = 60 * 60 * 1000;
+/** The session whose action ledger was written most recently, if any. */
+function newestSession(root) {
+    const sessionsDir = join(root, ReticleDir.SESSIONS_SUBDIR);
+    if (!existsSync(sessionsDir))
+        return undefined;
+    let newest;
+    for (const id of readdirSync(sessionsDir)) {
+        const ledger = join(sessionsDir, id, ReticleDir.JOURNAL_ACTIONS_FILE);
+        if (!existsSync(ledger))
+            continue;
+        const writtenAt = statSync(ledger).mtimeMs;
+        if (newest === undefined || writtenAt > newest.writtenAt)
+            newest = { id, writtenAt };
+    }
+    return newest;
+}
+export async function reportFor(input) {
+    if (true === input.hook && !input.treeChanged)
+        return { lines: [] };
+    const root = join(input.cwd, ReticleDir.ROOT);
+    const found = input.session === undefined ? newestSession(root) : { id: input.session, writtenAt: input.now };
+    const current = found !== undefined && (true !== input.hook || input.now - found.writtenAt <= HOOK_WINDOW_MS)
+        ? found
+        : undefined;
+    const actions = current === undefined
+        ? []
+        : await new SessionJournal(createNodeFileSystem(), root, current.id).readActions();
+    const gap = gapSummary(actions);
+    if (true === input.hook) {
+        const line = gapHookLine(gap);
+        // A finish with nothing proved is the moment Reticle let somebody down: say who to tell.
+        return { lines: line === undefined ? [] : [line, DiscoveryInvite.HUMAN] };
+    }
+    const header = current === undefined ? [] : [`session ${current.id}`];
+    return { lines: [...header, ...gapReportLines(gap), DiscoveryInvite.HUMAN] };
+}
+/** Uncommitted changes in `cwd`. Outside a git repository nothing can say, so it answers yes. */
+function treeChanged(cwd) {
+    try {
+        return '' !== execFileSync('git', ['status', '--porcelain'], { cwd, encoding: 'utf8' }).trim();
+    }
+    catch {
+        return true;
+    }
+}
+/**
+ * The command. As a hook it prints Claude Code's `systemMessage` shape and always exits 0: it is
+ * print-only by design, so the human sees the gap and the agent is never blocked by it.
+ */
+export async function handleReport(session, hook) {
+    const cwd = process.cwd();
+    let lines;
+    try {
+        ({ lines } = await reportFor({
+            cwd,
+            now: Date.now(),
+            treeChanged: hook ? treeChanged(cwd) : true,
+            ...(session === undefined ? {} : { session }),
+            hook,
+        }));
+    }
+    catch (error) {
+        // A hook that throws turns the agent's stop into an error the user did not cause; it says nothing
+        // instead. Run by hand, the reason is the answer (an id that is not a session, a journal it
+        // could not read), so it is printed and the exit is non-zero.
+        if (hook)
+            return;
+        process.stderr.write(`reticle report: ${error instanceof Error ? error.message : String(error)}\n`);
+        process.exitCode = 1;
+        return;
+    }
+    if (0 === lines.length)
+        return;
+    process.stdout.write(hook ? `${JSON.stringify({ systemMessage: lines.join('\n') })}\n` : `${lines.join('\n')}\n`);
+}

package/dist/command/cli.js

@@ -14,6 +14,7 @@ import { attachStatusFields } from '../surface/mcp/attach-memory.js';
 import { splitBrainFields, withNextAction } from './cli/status-fields.js';
 import { reticleStateHome } from './daemon/daemon.js';
 import { handleMcp } from './cli/mcp-command.js';
+import { handleReport } from './cli/report-command.js';
 import { resolveDaemonForProject } from './daemon/daemon-resolve.js';
 import { daemonStartOptions } from './cli/daemon-start-options.js';
 import { handleWatch, handleCapsules, handleGate, loadNamedFlows, resolveChangedFiles, } from './cli/cli-flow-commands.js';
@@ -69,6 +70,7 @@ function handleInit(parsed) {
         // past a missing package manager, and could not honour that while never being told about it.
         ...(parsed.url === undefined ? {} : { url: parsed.url }),
         captureBodies: true === parsed.captureBodies,
+        hooks: true === parsed.hooks,
         // The outcome is reported by confirmInstall instead, once it knows whether an app connected —
         // `init` writing files was never the same thing as `init` working (#269).
         deferOutcome: true,
@@ -669,6 +671,9 @@ export function main() {
         case 'gate':
             void handleGate(parsed.files, parsed.since, parsed.hook);
             break;
+        case 'report':
+            void handleReport(parsed.session, parsed.hook);
+            break;
         case 'watch':
             handleWatch();
             break;

package/dist/command/daemon/binding/daemon-status-probe.d.ts

@@ -1,2 +1,32 @@
 /** GET the daemon's /status JSON. Resolves to the parsed body, or undefined on any failure. */
 export declare function fetchStatus(port: number): Promise<unknown>;
+/** One connected tab as `reticle status` reports it — the at-a-glance health line. */
+interface StatusSession {
+    sessionId: string;
+    url: string;
+    projectId?: string;
+    throttled: boolean;
+    /**
+     * The tab is backgrounded. Reported by the daemon on every session; `false` on one too old to say,
+     * which reads as visible — the conservative answer, since it keeps the reuse this command has
+     * always done rather than opening a tab on a guess.
+     */
+    hidden: boolean;
+    stale: boolean;
+    pendingMarks: number;
+    /** The tab is attached and answering nothing — see Session.unresponsive. Absent on an older daemon. */
+    unresponsive?: true;
+}
+/**
+ * Reduce the daemon's /status JSON to the compact view `reticle status` prints. Pure: narrows the
+ * untrusted wire payload (never `any`) and tolerates a missing/partial body so a malformed response
+ * degrades to "running, 0 sessions" instead of throwing.
+ */
+export declare function summarizeStatus(payload: unknown): {
+    sessionCount: number;
+    sessions: StatusSession[];
+    why?: string;
+    /** The same diagnosis without the differential, for a surface a person reads. */
+    whyLead?: string;
+};
+export {};

package/dist/command/daemon/binding/daemon-status-probe.js

@@ -46,3 +46,48 @@ export function fetchStatus(port) {
         });
     });
 }
+/**
+ * Reduce the daemon's /status JSON to the compact view `reticle status` prints. Pure: narrows the
+ * untrusted wire payload (never `any`) and tolerates a missing/partial body so a malformed response
+ * degrades to "running, 0 sessions" instead of throwing.
+ */
+export function summarizeStatus(payload) {
+    if (typeof payload !== 'object' || null === payload)
+        return { sessionCount: 0, sessions: [] };
+    const obj = payload;
+    // Carried through to the printed line: with no sessions this is the whole answer, and dropping it
+    // here would silently undo the reason it is on the wire.
+    const why = 'string' === typeof obj['why'] ? obj['why'] : undefined;
+    // Absent on a daemon older than this field, which is why every reader falls back to `why`.
+    const whyLead = 'string' === typeof obj['whyLead'] ? obj['whyLead'] : undefined;
+    const raw = Array.isArray(obj['sessions']) ? obj['sessions'] : [];
+    const sessions = raw
+        .map((s) => {
+        if (typeof s !== 'object' || null === s)
+            return null;
+        const r = s;
+        const sessionId = 'string' === typeof r['sessionId'] ? r['sessionId'] : '';
+        if ('' === sessionId)
+            return null;
+        return {
+            sessionId,
+            url: 'string' === typeof r['url'] ? r['url'] : '',
+            ...('string' === typeof r['projectId'] && 0 < r['projectId'].length
+                ? { projectId: r['projectId'] }
+                : {}),
+            throttled: true === r['throttled'],
+            hidden: true === r['hidden'],
+            stale: true === r['stale'],
+            pendingMarks: 'number' === typeof r['pendingMarks'] ? r['pendingMarks'] : 0,
+            ...(true === r['unresponsive'] ? { unresponsive: true } : {}),
+        };
+    })
+        .filter((s) => s !== null);
+    const sessionCount = 'number' === typeof obj['sessionCount'] ? obj['sessionCount'] : sessions.length;
+    return {
+        sessionCount,
+        sessions,
+        ...(why === undefined ? {} : { why }),
+        ...(whyLead === undefined ? {} : { whyLead }),
+    };
+}

package/dist/command/daemon/binding/port-presence.d.ts

@@ -65,7 +65,7 @@ export declare function probePresence(port: number, probes: {
  * these lets the sentence tell them apart when — and only when — the recorded pid for the port
  * matches the process actually holding it.
  */
-export interface PortHolder {
+interface PortHolder {
     /** The pid we recorded for this port, from the daemon pid file. `null` when there is none. */
     ourPid: number | null;
     /** The pid actually holding the port, when the caller could determine it. */

package/dist/command/daemon/idle-shutdown.d.ts

@@ -1,4 +1,4 @@
-export interface IdleShutdownOptions {
+interface IdleShutdownOptions {
     /** True when nothing is using the daemon: no agent connected, no browser session, no pool lease. */
     isIdle: () => boolean;
     /** Clean teardown + process exit. Called at most once. */
@@ -52,3 +52,4 @@ export declare function resolveIdleCheckMs(raw: string | undefined): number;
  * broken.
  */
 export declare function resolveIdleShutdownMs(raw: string | undefined): number;
+export {};

package/dist/command/setup/init/init-host.js

@@ -3,6 +3,9 @@ import { reportInitOutcome } from '../../../telemetry/init-telemetry.js';
 import { reportOnboardingStep } from '../../../telemetry/onboarding-funnel.js';
 import { defaultPairingTokenDir, readOrCreatePairingTokenSync, } from '../../../portal/bridge/pairing-token.js';
 import { declaredInstallSource } from '../../../telemetry/install-source.js';
+/** The variable Claude Code sets on every process it spawns, and the value it sets it to. */
+const CLAUDE_CODE_MARKER_ENV = 'CLAUDECODE';
+const CLAUDE_CODE_MARKER_VALUE = '1';
 export function serverInitHost() {
     return {
         span(name, fields, fn) {
@@ -33,5 +36,10 @@ export function serverInitHost() {
         installSource() {
             return declaredInstallSource();
         },
+        // Claude Code marks every process it spawns. If the marker ever changes, init falls back to the
+        // notice it printed before, which is the safe direction.
+        insideClaudeCode() {
+            return CLAUDE_CODE_MARKER_VALUE === process.env[CLAUDE_CODE_MARKER_ENV];
+        },
     };
 }

package/dist/features/crawl/crawl.d.ts

@@ -16,6 +16,8 @@ export interface CrawlSession {
     /** The page under test, so a third-party beacon cannot be reported against a control. Optional
      *  for the same reason `currentDocumentId` is. */
     readonly url?: string | undefined;
+    /** Same-origin endpoints the project declared as background. Optional like `url`. */
+    readonly background?: readonly string[] | undefined;
     /**
      * Is the page BACKGROUNDED? A hidden tab has its rAF clamped and the DOM observer flushes on rAF,
      * so real renders emit nothing and every absence-derived contradiction reads that silence as a

package/dist/features/crawl/crawl.js

@@ -347,6 +347,7 @@ export async function crawl(session, opts, sleep) {
             currentDocumentId: session.currentDocumentId,
             currentEditEpoch: session.currentEditEpoch,
             appOrigin: session.url,
+            background: session.background,
             // A hidden tab cannot be observed, so its silence is not evidence. Stated from the session
             // rather than left to a heartbeat landing inside a 300ms window.
             pageHidden: session.throttled?.(),

package/dist/features/harness/jev-driver.js

@@ -496,12 +496,10 @@ export function jevDriver(options) {
             const unsaved = drive.unsaved[0];
             if (unsaved !== undefined)
                 return only(
-                // `intent` is not decoration. A flow saved without one still replays, but when it goes
-                // red the report can only name the step that broke, not the thing that stopped being true.
-                request(Tool.FLOW_SAVE, {
-                    flowName: unsaved,
-                    intent: `Autonomous coverage drive of ${slugAfter(unsaved)}: ${String(drive.acted.length)} actions.`,
-                }), `save ${unsaved}`);
+                // No intent. A drive has no business rule of its own to state, and what it used to send
+                // ("Autonomous coverage drive: N actions") was a count of what it did, filed in the ledger
+                // as a rule and re-amended every time the count changed.
+                request(Tool.FLOW_SAVE, { flowName: unsaved }), `save ${unsaved}`);
             /*
              * THE PLAN'S CHEAP HALF, and it runs before the model is asked anything.
              *
@@ -640,9 +638,8 @@ export function jevDriver(options) {
                 ref: picked.ref,
                 action,
                 ...(wasRefused ? { args: { [DANGEROUS_ARG]: true } } : {}),
-                // The element's own description, so the drive reads back as a journey rather than as refs.
-                // A ref is a handle that expired when the page changed; this survives being read tomorrow.
-                intent: `${action} ${picked.desc}`,
+                // No `intent`: "click button \"Save\"" describes a step, not a rule, and the ledger refuses it.
+                // The recorded step keeps the element's role and name, which is what reads back as a journey.
                 ...(consequence === undefined ? {} : { until: consequence.predicate }),
             };
             if ('fill' === action) {

package/dist/features/harness/platform-config.d.ts

@@ -30,6 +30,16 @@ export interface PlatformModelConfig {
      * report "you turned this off" to somebody whose free months quietly ran out.
      */
     harnessEntitled: boolean;
+    /**
+     * Whether the platform actually holds a key for the provider this project is pointed at.
+     *
+     * Entitlement and readiness are different facts and the HUD needs both. A workspace can be fully
+     * entitled -- claimed period, `harnessEnabled` on -- against a deployment that has no provider key
+     * configured, and every signal then reads healthy while a drive cannot run. Absent reads as READY,
+     * on the same rule as the two booleans above: an older API that does not report availability must
+     * not have its silence treated as a refusal.
+     */
+    providerReady: boolean;
 }
 /** A GET, narrowed to what this file uses, so a test can answer it without a network. */
 export type ConfigFetch = (url: string, init: {

package/dist/features/harness/platform-config.js

@@ -41,10 +41,18 @@ function parse(body) {
         // Same rule for both, for the same reason: an older API that reports neither must not have its
         // silence read as a refusal.
         const entitled = record['harnessEntitled'];
+        // `available` is keyed by provider and says which ones the platform holds a key for. Read only
+        // the entry for the provider this project uses: another provider being configured says nothing
+        // about whether THIS one can drive.
+        const available = record['available'];
+        const ready = 'object' === typeof available && null !== available
+            ? available[provider]
+            : undefined;
         return {
             provider,
             harnessEnabled: 'boolean' === typeof enabled ? enabled : true,
             harnessEntitled: 'boolean' === typeof entitled ? entitled : true,
+            providerReady: 'boolean' === typeof ready ? ready : true,
         };
     }
     catch {

package/dist/index.d.ts

@@ -21,7 +21,7 @@ export type { RecordedStep, CompiledProgram } from './language/flows/recording/t
 export { FlowStore, recordedStepToFlowStep } from './language/flows/flows.js';
 export type { FlowResult } from './language/flows/flows.js';
 export type { Clock } from './machine/clock.js';
-export { assertSuccess, successToPredicate, dynamicTestids, successLabel, } from './language/flows/flow-success.js';
+export { assertSuccess, dynamicTestids, successLabel, successToPredicate, } from './language/flows/flow-success.js';
 export { classifyFlowAssertions, FlowAssertionGrade } from './language/flows/flow-classify.js';
 export type { FlowAssertionClassification } from './language/flows/flow-classify.js';
 export { buildDomainModel } from './judgement/domain/domain-model.js';

package/dist/index.js

@@ -11,7 +11,7 @@ import { PROJECT_REGISTRY_FILE, parseProjectRegistry, projectCandidates, } from
 import { discoverProjectConfigs } from './command/cli/config/config-discovery.js';
 import { artifactRootResolver } from './memory/project/artifact-root-resolver.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
-import { AGENT_STOPPED_NOTICE, RETICLE_DEFAULT_PORT, ReticleCommand, ReticleDir, ReticleEnv, LOOPBACK_HOST, ReplayStatus, EventType, } from '@reticlehq/core';
+import { AGENT_STOPPED_NOTICE, RETICLE_DEFAULT_PORT, bridgeWsUrl, ReticleCommand, ReticleDir, ReticleEnv, LOOPBACK_HOST, ReplayStatus, EventType, } from '@reticlehq/core';
 import { originOf } from './portal/session/session-manager.js';
 import { setBrowserMode, BrowserMode } from './telemetry/browser-mode.js';
 import { replayAndLearn } from './language/flows/flow-learning.js';
@@ -51,19 +51,16 @@ import { BrowserPool } from './portal/pool/browser-pool.js';
 import { AGENT_ALREADY_DRIVING_ELSEWHERE, shouldGreetWithLeaseNotice, } from './portal/session/lease-visibility.js';
 import { playwrightLauncher, resolveMaxContexts } from './portal/pool/playwright-launcher.js';
 import { LeaseReaper } from './portal/pool/lease-reaper.js';
-import { readJournalEnabled, readProjectId } from './command/cli/ports/resolve/cli-port.js';
-import { hasProjectConnectedBefore } from './memory/recall/prior/connection-memory.js';
+import { findProjectConfig, projectIdsAt, readJournalEnabled, readProjectId, } from './command/cli/ports/resolve/cli-port.js';
+import { hasAnyProjectConnectedBefore } from './memory/recall/prior/connection-memory.js';
 import { reticleStateHome } from './command/daemon/daemon.js';
 import { probeChromium } from './command/cli/doctor/browser/chromium-hint.js';
-import { makeJournalAttach } from './memory/journal/attach-journal.js';
-import { makeSessionEnd, recordDriveRun } from './memory/journal/session-end.js';
-import { attachDriveRunFlush } from './memory/journal/drive-run-flush.js';
+import { attachJournal } from './wire-journal.js';
 import { reportOnboardingStep } from './telemetry/onboarding-funnel.js';
 import { AMBIENT_RECORDING } from './language/flows/recording/tape/recordings.js';
-import { AmbientStore } from './memory/journal/ambient-store.js';
-import { ensureWorkspaceGitignore } from './memory/journal/on-disk/workspace-gitignore.js';
-import { pruneFeedback, pruneSessions, pruneVisualDiffs, } from './memory/journal/on-disk/retention.js';
+import { readRetainPolicy } from './memory/journal/on-disk/retain-policy.js';
 import { log } from './log.js';
+import { readReaderBundle, zeroInstallScript as zeroInstallScriptFor, } from './portal/pool/zero-install.js';
 /** A human-facing one-liner for a panel replay verdict — ✓ passed / ⚠ drifted / ✗ errored. */
 function replayVerdictLine(result) {
     if (result.status === ReplayStatus.OK)
@@ -86,7 +83,7 @@ export { runTool, SESSION_BOUND_TOOLS, SESSION_EXEMPT_TOOLS } from './surface/to
 export { BaselineStore, normalizeLines, diffLines } from './memory/project/baselines.js';
 export { RecordingStore } from './language/flows/recording/tape/recordings.js';
 export { FlowStore, recordedStepToFlowStep } from './language/flows/flows.js';
-export { assertSuccess, successToPredicate, dynamicTestids, successLabel, } from './language/flows/flow-success.js';
+export { assertSuccess, dynamicTestids, successLabel, successToPredicate, } from './language/flows/flow-success.js';
 export { classifyFlowAssertions, FlowAssertionGrade } from './language/flows/flow-classify.js';
 export { buildDomainModel } from './judgement/domain/domain-model.js';
 export { ProjectStore } from './memory/project/project-store.js';
@@ -108,12 +105,29 @@ export { resolveBridgeSecurity } from './portal/bridge/bridge-security.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.
  */
-function createBrowserPool(headless) {
+/** Where the zero-install reader connects: this daemon's own bridge, with its pairing token. */
+function readerConnect(port, token) {
+    return { url: bridgeWsUrl(port), ...(token === undefined ? {} : { token }) };
+}
+function createBrowserPool(headless, reader) {
     const maxContexts = resolveMaxContexts(process.env[ReticleEnv.MAX_CONTEXTS], cpus().length);
     const genSessionId = () => `lease-${'function' === typeof globalThis.crypto?.randomUUID
         ? globalThis.crypto.randomUUID()
         : String(Date.now())}`;
-    return new BrowserPool(playwrightLauncher({ headless }), { maxContexts, genSessionId });
+    // Built on first use and kept: the page that needs it is one whose app never connected.
+    let script;
+    const zeroInstallScript = () => {
+        if (script === undefined) {
+            const bundle = readReaderBundle();
+            script = bundle === undefined ? null : zeroInstallScriptFor(bundle, reader);
+        }
+        return script ?? undefined;
+    };
+    return new BrowserPool(playwrightLauncher({ headless }), {
+        maxContexts,
+        genSessionId,
+        zeroInstallScript,
+    });
 }
 /**
  * Route CDP-authoritative network detail onto the driven session's journal.
@@ -153,82 +167,6 @@ function makeNetworkDetailRouter(bridge, driveUrl) {
         }
     };
 }
-/**
- * Wire journal capture, ambient seeding and the journal-tail flush onto a bridge.
- *
- * Both entry points need all three, and both used to hand-roll them. `startDaemon` only ever wired the
- * first, so on the path every user actually takes (`reticle serve` / `reticle mcp`) the journal tail was
- * dropped at session end and the learned ambient map was never persisted OR seeded — meaning ambient
- * learning could not converge across sessions and the last events of every session were lost. The two
- * call sites had already drifted once before, which is why this is one function rather than a
- * copy-paste both are asked to keep in step.
- */
-function attachJournal(bridge, deps) {
-    const journalAttach = makeJournalAttach(deps);
-    const ambientStore = new AmbientStore(deps.fs, deps.reticleRoot);
-    // Built once, not per session: the resolver walks config discovery and the user-level registry,
-    // and neither changes between two tabs connecting a second apart.
-    const resolveArtifactRoot = artifactRootResolver(deps.reticleRoot);
-    bridge.attachSessionCreate((session) => {
-        // Stamp the project's own `.reticle` before ANY counter fires for this session. Without it every
-        // verdict is recorded against wherever the daemon was started, which is how one app's evidence
-        // reached a different account's production dashboard.
-        // The origin is passed for the case where the page never stamped a project id: it is the only
-        // distinguishing fact left, and without it every such app shares one bucket.
-        session.artifactRoot = resolveArtifactRoot(session.projectId, originOf(session.url)).root;
-        // Here rather than on the start path, which was neither the moment we were about to write into a
-        // repository nor the root we were about to write into: it created `.reticle/` — holding nothing
-        // but the ignore file — wherever the daemon was launched, coming back every boot after the user
-        // deleted it, while the journals this ignore protects landed in another tree, uncovered.
-        if (deps.enabled)
-            void ensureWorkspaceGitignore(deps.fs, session.artifactRoot);
-        journalAttach(session);
-        // Seed the learned ambient map so a fresh session starts knowing which regions churn, instead of
-        // re-learning from zero. Best-effort + async: a late seed still helps, a failure is silent.
-        if (deps.enabled) {
-            void ambientStore
-                .load()
-                .then((counts) => session.seedAmbient(counts))
-                .catch(() => undefined);
-        }
-    });
-    // Teardown: flush the journal tail to disk + persist what this session learned.
-    bridge.attachSessionEnd(makeSessionEnd({
-        ...deps,
-        // Retention runs from teardown, and it must not delete the journal of a session that is still
-        // being written. The registry is the only thing that knows which those are.
-        liveSessionIds: () => new Set(bridge.sessions.all().map((s) => s.id)),
-    }));
-    /*
-     * And the same write, DURING the session rather than only at the end of it.
-     *
-     * Teardown was the only writer of a run artifact, so every verdict produced while a tab stayed
-     * open was invisible to cloud sync — which can only push artifacts that exist. Reported as "sync
-     * is not happening" and diagnosed as the agent forgetting to sync; there is no sync command to
-     * forget. The evidence simply was not on disk yet.
-     *
-     * Safe to call repeatedly because the run id is derived from the session, so this rewrites one
-     * artifact rather than accumulating them — a property `recordDriveRun` already had, for the
-     * unrelated reason that a reconnecting tab must not publish two overlapping rows.
-     */
-    if (deps.enabled) {
-        attachDriveRunFlush({
-            resolve: (sessionId) => bridge.sessions.get(sessionId),
-            write: (session) => recordDriveRun(deps, session),
-        });
-    }
-    if (deps.enabled) {
-        // Empty in the ordinary case (nothing has connected yet), but this path also runs on a daemon
-        // that is already serving sessions.
-        void pruneSessions(deps.fs, deps.reticleRoot, {
-            live: new Set(bridge.sessions.all().map((s) => s.id)),
-        });
-        // The largest thing in the workspace, and until now the only one with no delete path at all.
-        void pruneVisualDiffs(deps.fs, deps.reticleRoot);
-        // Write-only local copies of reports the outbox already carries.
-        void pruneFeedback(deps.fs, deps.reticleRoot);
-    }
-}
 /**
  * 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
@@ -364,12 +302,16 @@ export async function start(options = {}) {
         const fs = createNodeFileSystem();
         const reticleRoot = options.reticleRoot ?? join(process.cwd(), ReticleDir.ROOT);
         const now = options.now ?? (() => Date.now());
-        const journalEnabled = readJournalEnabled(process.cwd(), process.env[ReticleEnv.JOURNAL]);
+        const retain = readRetainPolicy(findProjectConfig(process.cwd()));
+        // `retain.sessions: 0` says keep no journals. Honoured at CAPTURE as well as at the sweep —
+        // writing a directory in order to delete it on the way out is work nobody asked for.
+        const journalEnabled = readJournalEnabled(process.cwd(), process.env[ReticleEnv.JOURNAL]) && 0 < retain.sessions;
         const flows = new FlowStore(fs, reticleRoot, { now });
         attachJournal(bridge, {
             fs,
             reticleRoot,
             enabled: journalEnabled,
+            retain,
             // Bound HERE, where the recorder is already in hand: teardown gets the tape, not the recorder.
             takeAmbientTape: () => recordings.stop(AMBIENT_RECORDING),
             reportStep: reportOnboardingStep,
@@ -378,7 +320,7 @@ export async function start(options = {}) {
         const project = new ProjectStore(fs, reticleRoot, { now });
         attachRouteLearning(bridge, projectStoreResolver(fs, project, reticleRoot, now));
         const annotations = new AnnotationStore();
-        pool = createBrowserPool(options.headless ?? true);
+        pool = createBrowserPool(options.headless ?? true, readerConnect(port, security.token));
         leaseReaper = new LeaseReaper(pool);
         leaseReaper.start();
         /*
@@ -419,7 +361,7 @@ export async function start(options = {}) {
             ...(activeProjectId === undefined ? {} : { projectId: activeProjectId }),
         };
         const profile = resolveToolSurface(options.toolProfile);
-        const server = createMcpServer(realInput !== undefined ? { ...deps, realInput } : deps, profile, hasProjectConnectedBefore(reticleStateHome(), port, activeProjectId));
+        const server = createMcpServer(realInput !== undefined ? { ...deps, realInput } : deps, profile, hasAnyProjectConnectedBefore(reticleStateHome(), port, projectIdsAt(process.cwd())));
         // When the agent (the MCP client) disconnects cleanly, end every active session at once so the
         // HUD doesn't linger. (If the agent instead KILLS this process, the WS dies and the browser
         // self-ends via SESSION_LIFECYCLE.BRIDGE_LOST_MS — see transport.ts.)
@@ -497,7 +439,9 @@ export async function startDaemon(options = {}) {
     const fs = createNodeFileSystem();
     const reticleRoot = options.reticleRoot ?? join(process.cwd(), ReticleDir.ROOT);
     const now = options.now ?? (() => Date.now());
-    const journalEnabled = readJournalEnabled(process.cwd(), process.env[ReticleEnv.JOURNAL]);
+    const retain = readRetainPolicy(findProjectConfig(process.cwd()));
+    // See the sibling path: `retain.sessions: 0` stops the capture too, not only the sweep.
+    const journalEnabled = readJournalEnabled(process.cwd(), process.env[ReticleEnv.JOURNAL]) && 0 < retain.sessions;
     const flows = new FlowStore(fs, reticleRoot, { now });
     // Built here rather than inside `deps` below, so teardown can save what a drive recorded. Both
     // paths pass the same pair — `daemon-parity.test.ts` is what keeps them from drifting apart.
@@ -514,6 +458,7 @@ export async function startDaemon(options = {}) {
         fs,
         reticleRoot,
         enabled: journalEnabled,
+        retain,
         takeAmbientTape: () => recordings.stop(AMBIENT_RECORDING),
         reportStep: reportOnboardingStep,
         flows,
@@ -522,7 +467,7 @@ export async function startDaemon(options = {}) {
     const project = new ProjectStore(fs, reticleRoot, { now });
     attachRouteLearning(bridge, projectStoreResolver(fs, project, reticleRoot, now));
     const annotations = new AnnotationStore();
-    const pool = createBrowserPool(options.headless ?? true);
+    const pool = createBrowserPool(options.headless ?? true, readerConnect(port, security.token));
     const leaseReaper = new LeaseReaper(pool);
     leaseReaper.start();
     /*
@@ -596,7 +541,7 @@ export async function startDaemon(options = {}) {
     const effectiveDeps = realInput !== undefined ? { ...deps, realInput } : deps;
     // Read per attach, not once: a project that gets wired while this daemon is alive should stop
     // being told to wire itself on the next agent that connects.
-    shared.attachMcp(() => createMcpServer(effectiveDeps, profile, hasProjectConnectedBefore(reticleStateHome(), port, readProjectId(process.cwd()))));
+    shared.attachMcp(() => createMcpServer(effectiveDeps, profile, hasAnyProjectConnectedBefore(reticleStateHome(), port, projectIdsAt(process.cwd()))));
     // `reticle drive <url>` when this daemon already owns the port: it asks HERE instead of trying to
     // bind a port we are holding, and gets the same pooled context an agent's reticle_lease returns —
     // through runTool, so it is counted and reported like any other call rather than being a second,
@@ -698,7 +643,7 @@ export async function startDaemon(options = {}) {
             if (vh !== undefined)
                 await new Promise((resolve) => vh.server.close(() => resolve()));
             leaseReaper.stop();
-            cloudSync.stop();
+            await cloudSync.flush(); // not stop(): the last run written is the one nobody has yet
             await loopbackAlias.close?.();
             await pool.shutdown();
             await owned?.dispose();