@reticlehq/server 3.7.0 → 3.8.1

package/dist/memory/cloud/sync-describe.d.ts

@@ -0,0 +1,28 @@
+/**
+ * What a sync cycle says about itself: one line for the CLI and the daemon log, and the failure a
+ * person reads in `reticle whoami`. Kept beside the cycle, apart from it, because the cycle is the
+ * protocol and this is only how it is reported.
+ */
+import type { SyncReport } from './sync-cycle.js';
+/**
+ * Say WHICH host failed and WHY.
+ *
+ * Node's fetch rejects with the bare string "fetch failed" and hides the real reason — a refused
+ * connection, a bad hostname, an expired certificate — one level down in `cause`. A machine that
+ * has quietly stopped syncing shows that string in `reticle whoami`, and on its own it is
+ * indistinguishable from every other network problem, so the person reading it learns nothing and
+ * checks nothing. Naming the origin and the underlying code turns it into one thing to look at.
+ */
+export declare function describeTransportError(error: unknown, url: string): string;
+/** One line a human can read, for the CLI and the daemon log. */
+export declare function describeSync(report: SyncReport): string;
+/**
+ * What went wrong, one phrase per kind of problem.
+ *
+ * One reason, not a count. A rejection count tells somebody they have a problem and nothing about
+ * which problem — and these arrive from a BACKGROUND daemon, so the summary line is often the only
+ * place anybody ever sees it. Rejections in one cycle almost always share a cause (a version skew
+ * refuses every payload the same way), so the first reason plus the count is the whole story
+ * without printing a line per item; `reticle sync` still lists them all.
+ */
+export declare function problemsOf(report: SyncReport): string[];

package/dist/memory/cloud/sync-describe.js

@@ -0,0 +1,92 @@
+/**
+ * Say WHICH host failed and WHY.
+ *
+ * Node's fetch rejects with the bare string "fetch failed" and hides the real reason — a refused
+ * connection, a bad hostname, an expired certificate — one level down in `cause`. A machine that
+ * has quietly stopped syncing shows that string in `reticle whoami`, and on its own it is
+ * indistinguishable from every other network problem, so the person reading it learns nothing and
+ * checks nothing. Naming the origin and the underlying code turns it into one thing to look at.
+ */
+export function describeTransportError(error, url) {
+    if (!(error instanceof Error))
+        return String(error);
+    const cause = error.cause;
+    if (!(cause instanceof Error))
+        return `${error.message} (${url})`;
+    const code = cause.code;
+    // The code and the message are each sometimes empty — an aggregate DNS failure carries a code and
+    // no text, a TLS failure the reverse. Joined only when both are there, so the line never trails
+    // off into a dangling separator.
+    const parts = ['string' === typeof code && code.length > 0 ? code : '', cause.message].filter((part) => part.length > 0);
+    const detail = parts.join(': ');
+    return 0 === detail.length
+        ? `${error.message} (${url})`
+        : `${error.message} — ${detail} (${url})`;
+}
+/** One line a human can read, for the CLI and the daemon log. */
+export function describeSync(report) {
+    if (report.error !== undefined)
+        return `sync failed — ${report.error}`;
+    const sent = [];
+    if (report.runsSent > 0)
+        sent.push(`${String(report.runsSent)} run(s)`);
+    if (report.flowsSent > 0)
+        sent.push(`${String(report.flowsSent)} flow(s)`);
+    if (report.capsulesSent > 0)
+        sent.push(`${String(report.capsulesSent)} capsule(s)`);
+    if ((report.screenshotsSent ?? 0) > 0)
+        sent.push(`${String(report.screenshotsSent)} screenshot(s)`);
+    if (report.derivedSent.length > 0)
+        sent.push(report.derivedSent.join(', '));
+    /*
+     * "Nothing to send" is a statement about the QUEUE, and it is false the moment the queue was full
+     * and the server threw it away. Built from what was accepted, the sentence used to read "nothing
+     * to send, 3 rejected" — something was very much sent, and the reader is told both that it was
+     * not and nothing about why.
+     */
+    const rejectedCount = report.runsRejected.length + report.refused.length;
+    const push = sent.length > 0
+        ? `sent ${sent.join(' + ')}`
+        : rejectedCount > 0
+            ? 'nothing accepted'
+            : true === report.localIsEmpty
+                ? // Not the same statement as "nothing to send", which describes a repo that is simply up
+                    // to date. This one has never recorded anything, which for a LINKED repo usually means
+                    // the app announces no projectId and its runs are landing under a different root.
+                    'nothing recorded here yet — if this app has been driven, it is reporting somewhere else'
+                : 'nothing to send';
+    const pull = 0 === report.pulled
+        ? ''
+        : `, pulled ${String(report.pulled)} decision(s)${report.morePending ? ' (more waiting)' : ''}`;
+    return `${push}${pull}${problemsOf(report)
+        .map((problem) => `, ${problem}`)
+        .join('')}`;
+}
+/**
+ * What went wrong, one phrase per kind of problem.
+ *
+ * One reason, not a count. A rejection count tells somebody they have a problem and nothing about
+ * which problem — and these arrive from a BACKGROUND daemon, so the summary line is often the only
+ * place anybody ever sees it. Rejections in one cycle almost always share a cause (a version skew
+ * refuses every payload the same way), so the first reason plus the count is the whole story
+ * without printing a line per item; `reticle sync` still lists them all.
+ */
+export function problemsOf(report) {
+    const problems = [];
+    const count = report.runsRejected.length + report.refused.length;
+    if (count > 0) {
+        const first = report.runsRejected[0]?.reason ?? report.refused[0]?.reason ?? 'no reason given';
+        problems.push(`${String(count)} rejected — ${first}`);
+    }
+    const firstRefusal = report.notRetried[0];
+    if (firstRefusal !== undefined)
+        problems.push(`refused, not retried: ${String(report.notRetried.length)} run(s) (${firstRefusal.reason})`);
+    for (const set of report.setsNotRetried)
+        problems.push(`refused, not retried: ${String(set.count)} ${set.part}(s) (${set.reason})`);
+    if (report.held.length > 0)
+        problems.push(`not sent: ${report.held.join('; ')}`);
+    const copies = report.flowConflicts ?? [];
+    if (copies.length > 0)
+        problems.push(`${String(copies.length)} flow conflict(s): another machine saved first, so this edit is kept as ${copies.join(', ')}; merge or delete it`);
+    return problems;
+}

package/dist/memory/cloud/sync-disk.d.ts

@@ -1,6 +1,14 @@
 import { type CloudSyncState, type PulledIssues, type SyncSink, type SyncSource } from './sync-cycle.js';
 /** What the cycle reads, backed by a real `.reticle` directory. */
-export declare function diskSource(reticleRoot: string): SyncSource;
+export declare function diskSource(reticleRoot: string, env?: NodeJS.ProcessEnv): SyncSource;
+/**
+ * The screenshot reader a sync policy allows: none with `screenshots` off, and none for a frame with
+ * `video` off. A frame held back this way is offered again each cycle, so turning video on sends it.
+ */
+export declare function policyScreenshots(read: SyncSource['screenshot'], policy: {
+    screenshots: boolean;
+    video: boolean;
+}): Pick<SyncSource, 'screenshot'>;
 /** What the cycle writes back into `.reticle/`. */
 export declare function diskSink(reticleRoot: string): SyncSink;
 /** This machine's side of the conversation, or a blank one on first run. */

package/dist/memory/cloud/sync-disk.js

@@ -11,10 +11,12 @@
  * error — the file will be rewritten on the next tool call anyway.
  */
 import { shareableRun } from '@reticlehq/core/artifacts';
+import { agentContextFor } from '../journal/episode-log.js';
+import { agentCaptureOff, agentCaptureOffIn, sharesRequests, } from '../intent/record-request.js';
 import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, writeFileSync, } from 'node:fs';
 import { basename, dirname, join } from 'node:path';
 import { stepShotDir } from '../project/dir/reticle-dir.js';
-import { IntentDir, ReticleDir } from '@reticlehq/core';
+import { IntentDir, ReticleDir, STEP_SCREENSHOT } from '@reticlehq/core';
 import { DERIVED_RECORDS, } from './sync-cycle.js';
 import { subjectFor } from '../intent/intent-subject.js';
 const JSON_SUFFIX = '.json';
@@ -47,8 +49,9 @@ function writeJson(path, value) {
 /** Every `*.json` directly inside a directory, parsed. Absent directory reads as empty. */
 function readJsonDir(dir) {
     try {
-        if (!existsSync(dir))
+        if (!existsSync(dir)) {
             return [];
+        }
         return readdirSync(dir)
             .filter((f) => f.endsWith(JSON_SUFFIX))
             .map((f) => readJson(join(dir, f)))
@@ -62,25 +65,52 @@ function readJsonDir(dir) {
  * Flows: one directory deeper under the app's own project id, and also flat in `.reticle/flows/`,
  * which the flow store still saves and loads (a flow saved with no project id, or from before flows
  * were kept per project). Reading only the subfolders skipped every flat flow while the cycle
- * reported ok.
+ * reported ok. At any depth: a namespaced name (`onboarding/signup`) is a folder of its own, and
+ * reading one level down left every such flow on the machine.
  */
-function readFlows(root) {
-    const dir = join(root, ReticleDir.FLOWS_SUBDIR);
-    try {
-        if (!existsSync(dir))
+function readFlowFiles(root) {
+    const walk = (dir) => {
+        try {
+            return readdirSync(dir, { withFileTypes: true }).flatMap((entry) => {
+                const path = join(dir, entry.name);
+                if (entry.isDirectory()) {
+                    return walk(path);
+                }
+                if (!entry.name.endsWith(JSON_SUFFIX)) {
+                    return [];
+                }
+                const flow = readJson(path);
+                return flow === undefined ? [] : [{ path, flow }];
+            });
+        }
+        catch {
             return [];
-        return readdirSync(dir, { withFileTypes: true }).flatMap((entry) => {
-            if (entry.isDirectory())
-                return readJsonDir(join(dir, entry.name));
-            if (!entry.name.endsWith(JSON_SUFFIX))
-                return [];
-            const flow = readJson(join(dir, entry.name));
-            return flow === undefined ? [] : [flow];
-        });
+        }
+    };
+    return walk(join(root, ReticleDir.FLOWS_SUBDIR));
+}
+const readFlows = (root) => readFlowFiles(root).map(({ flow }) => flow);
+/**
+ * Keep this machine's edit of `name` as `<name>-conflict-<n>` in a file beside it, and write the
+ * platform's version in its place. Answers the copy's name, or undefined when the flow is not here.
+ */
+function keepConflictCopy(root, name, theirs) {
+    const held = readFlowFiles(root).find(({ flow }) => 'object' === typeof flow && null !== flow && flow.name === name);
+    if (held === undefined || 'object' !== typeof theirs || null === theirs) {
+        return undefined;
     }
-    catch {
-        return [];
+    const stem = held.path.slice(0, -JSON_SUFFIX.length);
+    let n = 1;
+    while (existsSync(`${stem}-conflict-${String(n)}${JSON_SUFFIX}`)) {
+        n += 1;
     }
+    const copy = `${name}-conflict-${String(n)}`;
+    writeJson(`${stem}-conflict-${String(n)}${JSON_SUFFIX}`, {
+        ...held.flow,
+        name: copy,
+    });
+    writeJson(held.path, theirs);
+    return copy;
 }
 const DERIVED_FILE = Object.fromEntries(DERIVED_RECORDS.map((record) => [record.kind, record.file]));
 /** The directory the sharded intent store writes into, beside the legacy flat file. */
@@ -112,8 +142,9 @@ function readIntent(reticleRoot) {
     };
     let shards = 0;
     for (const entry of safeReaddir(join(reticleRoot, INTENT_SUBDIR))) {
-        if (INTENT_INDEX === entry)
+        if (INTENT_INDEX === entry) {
             continue;
+        }
         // `<subject>/intent.json` is the layout; a bare `<subject>.json` is an interim shard the store
         // has not migrated yet, and is still this project's memory until it has.
         const path = entry.endsWith(JSON_SUFFIX)
@@ -121,14 +152,17 @@ function readIntent(reticleRoot) {
             : join(reticleRoot, INTENT_SUBDIR, entry, IntentDir.SHARD_FILE);
         const shard = readJson(path);
         // A hand-edited or half-written shard costs one subject, never the whole sync.
-        if (shard?.intents === undefined)
+        if (shard?.intents === undefined) {
             continue;
+        }
         shards++;
-        for (const [id, record] of Object.entries(shard.intents))
+        for (const [id, record] of Object.entries(shard.intents)) {
             merged[id] = record;
+        }
     }
-    if (legacy === undefined && 0 === shards)
+    if (legacy === undefined && 0 === shards) {
         return undefined;
+    }
     /*
      * Stamp the SUBJECT before sending, on anything that does not already carry one.
      *
@@ -153,8 +187,9 @@ function readIntent(reticleRoot) {
             ...('string' === typeof run && 0 < run.length ? { provedBy: run } : {}),
         };
         const held = record;
-        if ('string' === typeof held.subject && held.subject.length > 0)
+        if ('string' === typeof held.subject && held.subject.length > 0) {
             return [id, record];
+        }
         const subject = subjectFor({
             surface: held.surface,
             binding: held.binding,
@@ -172,18 +207,68 @@ function safeReaddir(dir) {
         return [];
     }
 }
+/**
+ * A run with the agent's model and the claim that closed its turn, from the agent hooks' records
+ * (see `agentContextFor`). Filled only where the run says nothing. The claim goes into the prompt
+ * context, so it leaves the machine under the same share decision as the request: a context the
+ * run did not have takes the project's setting.
+ */
+function withAgentContext(payload, reticleRoot) {
+    if ('object' !== typeof payload || null === payload) {
+        return payload;
+    }
+    const run = payload;
+    const found = agentContextFor(reticleRoot, run);
+    let out = { ...run };
+    if (found.model !== undefined && run.agent !== undefined && run.agent.model === undefined) {
+        out = { ...out, agent: { ...run.agent, model: found.model } };
+    }
+    if (found.claim !== undefined && run.context?.closingClaim === undefined) {
+        const shared = 'boolean' === typeof run.context?.shared
+            ? run.context.shared
+            : sharesRequests(dirname(reticleRoot), reticleRoot);
+        out = {
+            ...out,
+            context: {
+                statements: [],
+                ...run.context,
+                closingClaim: found.claim.text,
+                closingClaimAt: found.claim.at,
+                shared,
+            },
+        };
+    }
+    return out;
+}
+/**
+ * A run with nothing the agent hooks kept: no prompt context. Agent capture is off, so the files
+ * that the hooks wrote before the switch went off do not leave the machine either.
+ */
+function withoutAgentCapture(payload) {
+    if ('object' !== typeof payload || null === payload) {
+        return payload;
+    }
+    const { context: _context, ...rest } = payload;
+    return rest;
+}
 /** What the cycle reads, backed by a real `.reticle` directory. */
-export function diskSource(reticleRoot) {
+export function diskSource(reticleRoot, env = process.env) {
     return {
-        runs: () => readJsonDir(join(reticleRoot, ReticleDir.RUNS_SUBDIR))
-            .map((payload) => {
-            const id = payload?.runId;
-            // The prompt context leaves the machine only when the project opted in.
-            return 'string' === typeof id ? { runId: id, payload: shareableRun(payload) } : undefined;
-        })
-            // A run artifact with no id cannot be diffed against the server's list, so sending it would
-            // mean re-sending it every cycle forever. Dropped rather than uploaded repeatedly.
-            .filter((r) => r !== undefined),
+        runs: () => {
+            const captureOff = agentCaptureOff(env) || agentCaptureOffIn(dirname(reticleRoot));
+            return (readJsonDir(join(reticleRoot, ReticleDir.RUNS_SUBDIR))
+                .map((payload) => {
+                const id = payload?.runId;
+                // The prompt context leaves the machine only when the project opted in.
+                const sent = captureOff
+                    ? withoutAgentCapture(payload)
+                    : shareableRun(withAgentContext(payload, reticleRoot));
+                return 'string' === typeof id ? { runId: id, payload: sent } : undefined;
+            })
+                // A run artifact with no id cannot be diffed against the server's list, so sending it
+                // would mean re-sending it every cycle forever. Dropped rather than uploaded repeatedly.
+                .filter((r) => r !== undefined));
+        },
         flows: () => readFlows(reticleRoot),
         // Flat directory of `<id>.json`, which is exactly what readJsonDir walks — unlike flows, which
         // sit one level deeper under the app's project id.
@@ -194,8 +279,9 @@ export function diskSource(reticleRoot) {
         // own directory before it is read.
         screenshot: (runId, file) => {
             try {
-                if (basename(file) !== file)
+                if (basename(file) !== file) {
                     return undefined;
+                }
                 return new Uint8Array(readFileSync(join(stepShotDir(reticleRoot, runId), file)));
             }
             catch {
@@ -204,6 +290,23 @@ export function diskSource(reticleRoot) {
         },
     };
 }
+/** A frame's file name ends in its tool: `<seq>-frame.jpg`. */
+const FRAME_FILE_SUFFIX = `-${STEP_SCREENSHOT.FRAME_TOOL}.jpg`;
+/**
+ * The screenshot reader a sync policy allows: none with `screenshots` off, and none for a frame with
+ * `video` off. A frame held back this way is offered again each cycle, so turning video on sends it.
+ */
+export function policyScreenshots(read, policy) {
+    if (!policy.screenshots || read === undefined) {
+        return {};
+    }
+    if (policy.video) {
+        return { screenshot: read };
+    }
+    return {
+        screenshot: (runId, file) => (file.endsWith(FRAME_FILE_SUFFIX) ? undefined : read(runId, file)),
+    };
+}
 /** What the cycle writes back into `.reticle/`. */
 export function diskSink(reticleRoot) {
     return {
@@ -218,6 +321,7 @@ export function diskSink(reticleRoot) {
         writeState: (state) => {
             writeJson(join(reticleRoot, ReticleDir.CLOUD_STATE_FILE), state);
         },
+        resolveFlowConflict: (name, theirs) => keepConflictCopy(reticleRoot, name, theirs),
     };
 }
 /** This machine's side of the conversation, or a blank one on first run. */

package/dist/memory/cloud/sync-flow-versions.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Compare-and-set for flows. Each pushed flow names the platform version it was based on; a push based
+ * on a version another machine has since replaced comes back as a conflict carrying the platform's
+ * version. This machine then keeps its own edit as a named copy beside the flow and takes the
+ * platform's, so nothing is lost and nothing diverges silently. Kept apart from the cycle, which is the
+ * protocol; this is the one rule about flow versions.
+ */
+/** The platform's code for a flow pushed on a version it no longer holds (its HTTP 409). */
+export declare const FLOW_CONFLICT_CODE = "conflict";
+/** Versions by name, as kept in the state: only strings count. */
+export declare function versionsIn(value: unknown): Record<string, string>;
+/**
+ * What each pending flow was based on: the version last taken here; null for a flow this machine never
+ * sent; nothing for one an older client sent without a version (stored unconditionally, as it was).
+ */
+export declare function flowBases(pending: ReadonlyArray<{
+    name: string;
+}>, versions: Record<string, string>, sentHashes: Record<string, string>): Record<string, string | null>;
+/** A refusal that is a conflict this machine can settle, with the platform's version. */
+export declare function conflictOf(r: {
+    code: unknown;
+    current: unknown;
+}): {
+    version: string;
+    flow: unknown;
+} | undefined;

package/dist/memory/cloud/sync-flow-versions.js

@@ -0,0 +1,42 @@
+/**
+ * Compare-and-set for flows. Each pushed flow names the platform version it was based on; a push based
+ * on a version another machine has since replaced comes back as a conflict carrying the platform's
+ * version. This machine then keeps its own edit as a named copy beside the flow and takes the
+ * platform's, so nothing is lost and nothing diverges silently. Kept apart from the cycle, which is the
+ * protocol; this is the one rule about flow versions.
+ */
+/** The platform's code for a flow pushed on a version it no longer holds (its HTTP 409). */
+export const FLOW_CONFLICT_CODE = 'conflict';
+const isRecord = (v) => 'object' === typeof v && null !== v;
+/** Versions by name, as kept in the state: only strings count. */
+export function versionsIn(value) {
+    const out = {};
+    if (isRecord(value))
+        for (const [name, v] of Object.entries(value))
+            if ('string' === typeof v)
+                out[name] = v;
+    return out;
+}
+/**
+ * What each pending flow was based on: the version last taken here; null for a flow this machine never
+ * sent; nothing for one an older client sent without a version (stored unconditionally, as it was).
+ */
+export function flowBases(pending, versions, sentHashes) {
+    const out = {};
+    for (const { name } of pending) {
+        const v = versions[name];
+        if (v !== undefined)
+            out[name] = v;
+        else if (sentHashes[name] === undefined)
+            out[name] = null;
+    }
+    return out;
+}
+/** A refusal that is a conflict this machine can settle, with the platform's version. */
+export function conflictOf(r) {
+    const current = isRecord(r.current) ? r.current : undefined;
+    const version = current?.['version'];
+    return FLOW_CONFLICT_CODE === r.code && 'string' === typeof version
+        ? { version, flow: current?.['flow'] }
+        : undefined;
+}

package/dist/memory/impact/impact-store.js

@@ -2,6 +2,7 @@ import { mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
 import { SyncStatus, dashboardRunUrl, describeSync, keyRefusalAtLastSync, overallStatus, readSyncSummary, } from '../project/sync-status.js';
 import { describeUnsynced, unsentFlowCount, unsentRunCount, } from '../cloud/unsynced-roots.js';
 import { readDashboardUrl } from '../project/sync-status.js';
+import { mayWriteIntoRoot } from '../project/artifact-root-resolver.js';
 import { dirname, join } from 'node:path';
 import { homedir } from 'node:os';
 import { readAccountState } from '../cloud/account-state.js';
@@ -107,10 +108,12 @@ function streakEndingAtLatest(sortedDates) {
     let later;
     for (let i = sortedDates.length - 1; i >= 0; i -= 1) {
         const date = sortedDates[i];
-        if (date === undefined)
+        if (date === undefined) {
             break;
-        if (later !== undefined && !isNextDay(date, later))
+        }
+        if (later !== undefined && !isNextDay(date, later)) {
             break;
+        }
         streak += 1;
         later = date;
     }
@@ -131,8 +134,9 @@ export function applyDelta(scope, delta, now, meta = {}) {
     byDate.set(today, todayCounts);
     const dates = [...byDate.keys()].sort();
     const days = dates.map((date) => ({ date, counts: byDate.get(date) ?? emptyImpactCounts() }));
-    while (days.length > IMPACT_DAILY_BUCKETS)
+    while (days.length > IMPACT_DAILY_BUCKETS) {
         days.shift();
+    }
     const records = { ...scope.records };
     records.bestVerdictDay = Math.max(records.bestVerdictDay, todayCounts.verdicts);
     records.bestDefectDay = Math.max(records.bestDefectDay, todayCounts.failed);
@@ -165,8 +169,9 @@ export function applyDelta(scope, delta, now, meta = {}) {
 /** The larger of two counters, key by key. */
 function maxEach(a, b) {
     const out = { ...a };
-    for (const key of Object.keys(b))
+    for (const key of Object.keys(b)) {
         out[key] = Math.max(a[key] ?? 0, b[key] ?? 0);
+    }
     return out;
 }
 /**
@@ -254,8 +259,9 @@ export class ImpactStore {
     }
     #syncStatus(dashboardUrl) {
         const now = this.#now();
-        if (this.#sync !== undefined && now - this.#sync.at < SYNC_STATUS_EVERY_MS)
+        if (this.#sync !== undefined && now - this.#sync.at < SYNC_STATUS_EVERY_MS) {
             return this.#sync.value;
+        }
         // Not linked: one line when runs or flows sit here that nothing will send, and nothing otherwise.
         // `pending` counts both, so the HUD's existing "N not sent" includes a flow saved with no run.
         if (dashboardUrl === undefined) {
@@ -312,18 +318,21 @@ export class ImpactStore {
             project: this.#project,
             global: atLeastProject(this.#global, this.#project),
         };
-        if (this.#projectName !== undefined)
+        if (this.#projectName !== undefined) {
             snap.projectName = this.#projectName;
+        }
         // Re-read, like the account: `reticle link` runs in another terminal while this store lives as
         // long as the daemon, so a construction-time read said "Not linked" until a restart.
         this.#dashboardUrl = readDashboardUrl(this.#root);
-        if (this.#dashboardUrl !== undefined)
+        if (this.#dashboardUrl !== undefined) {
             snap.dashboardUrl = this.#dashboardUrl;
+        }
         snap.account = this.#account();
         // Absent stays absent: the HUD reads that as "we have not heard" and renders no control.
         const cfg = this.#config.read();
-        if (cfg !== undefined)
+        if (cfg !== undefined) {
             snap.harnessConfig = configForHud(cfg, this.#now());
+        }
         // Chosen here, where the account and the entitlement are both known. Absent when nothing applies,
         // so the HUD falls back to the slides bundled with the SDK.
         const notices = selectNotices(this.#notices.read(), {
@@ -332,16 +341,19 @@ export class ImpactStore {
             sdkVersion: this.#sdkVersion,
             now: this.#now(),
         });
-        if (0 < notices.length)
+        if (0 < notices.length) {
             snap.notices = notices;
+        }
         const coverage = this.#coverage?.();
-        if (coverage !== undefined)
+        if (coverage !== undefined) {
             snap.coverage = coverage;
+        }
         // Only for a linked project: an unlinked one has nothing on the platform, and the HUD already
         // offers the way to link it.
         const sync = this.#syncStatus(this.#dashboardUrl);
-        if (sync !== undefined)
+        if (sync !== undefined) {
             snap.sync = sync;
+        }
         return snap;
     }
     /** Write now (process exit, tests). */
@@ -350,8 +362,11 @@ export class ImpactStore {
             clearTimeout(this.#timer);
             this.#timer = undefined;
         }
-        // One writer: the in-memory copy IS the truth.
-        writeScope(this.#paths.project, this.#project);
+        // One writer: the in-memory copy IS the truth. A project with no Reticle wiring gets no
+        // `.reticle/`: its scope stays in memory, and the first flush after `init` writes all of it.
+        if (mayWriteIntoRoot(this.#root)) {
+            writeScope(this.#paths.project, this.#project);
+        }
         this.#flushGlobal();
     }
     /**
@@ -367,16 +382,18 @@ export class ImpactStore {
      * plus a stale timeout) if the counters are ever load-bearing for anything but the HUD.
      */
     #flushGlobal() {
-        if (0 === this.#pendingGlobal.length)
+        if (0 === this.#pendingGlobal.length) {
             return;
+        }
         const merged = this.#pendingGlobal.reduce((scope, p) => applyDelta(scope, p.delta, p.now, p.meta), readScope(this.#paths.global, this.#now()));
         writeScope(this.#paths.global, merged);
         this.#global = merged;
         this.#pendingGlobal = [];
     }
     #scheduleFlush() {
-        if (this.#timer !== undefined)
+        if (this.#timer !== undefined) {
             return;
+        }
         this.#timer = setTimeout(() => {
             this.#timer = undefined;
             this.flush();