@reticlehq/server 3.2.0 → 3.3.0

package/dist/language/flows/verify-change-tools.js

@@ -184,6 +184,19 @@ export const VERIFY_CHANGE_TOOLS = [
                     measured: extra.measured,
                 };
             }
+            // The mirror of `earnedNo`: a green from flows that ran only because their sources are unknown
+            // says nothing about these files either. At least one attributed flow has to have passed.
+            if (0 === attributedFailures(affected, unknownProvenance).length) {
+                return {
+                    verified: Verified.UNKNOWN,
+                    because: `the flows that ran passed, but Reticle cannot tell which sources any of them cover (${affected.join(', ')}), so this says nothing about the files you changed. Drive the change directly; the drive is saved as a flow with its sources stamped`,
+                    changedFiles,
+                    flowsRun: affected,
+                    suite,
+                    unknownProvenance,
+                    measured: extra.measured,
+                };
+            }
             return {
                 verified: Verified.YES,
                 because: `all ${String(passed)} flows covering these files passed${provenanceNote}${extra.untouched === undefined ? '' : `, with ${String(extra.untouched.length)} controls left undriven`}`,
@@ -226,6 +239,7 @@ async function inspectAfterReplay(deps, args, cursor) {
             currentDocumentId: session.currentDocumentId,
             currentEditEpoch: session.currentEditEpoch,
             appOrigin: session.url,
+            background: session.background,
             // The replay is the action, and the cursor is where it started.
             actionSince: cursor,
         });

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

@@ -175,8 +175,6 @@ export declare function submitServerVerification(body: {
  * allowed to influence a verdict or an exit code.
  */
 export declare function syncProgressToCloud(runId: string, events: readonly VerifyProgressEvent[], config: CloudConfig | null, fetchImpl: FetchLike): Promise<SyncResult>;
-/** How long events accumulate before a flush. See the batching note above. */
-export declare const PROGRESS_FLUSH_MS = 2000;
 /**
  * A listener that buffers progress and ships it on a timer.
  *

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

@@ -293,7 +293,7 @@ export async function syncProgressToCloud(runId, events, config, fetchImpl) {
     }
 }
 /** How long events accumulate before a flush. See the batching note above. */
-export const PROGRESS_FLUSH_MS = 2_000;
+const PROGRESS_FLUSH_MS = 2_000;
 /**
  * A listener that buffers progress and ships it on a timer.
  *

package/dist/memory/cloud/harness-config.d.ts

@@ -3,6 +3,8 @@ export interface HarnessConfigView {
     provider: string;
     harnessEnabled: boolean;
     harnessEntitled: boolean;
+    /** Whether the platform holds a key for `provider`. Entitlement is not readiness — see the offer. */
+    providerReady: boolean;
 }
 export interface ConfigSource {
     read(): HarnessConfigView | undefined;

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

@@ -61,8 +61,20 @@ export interface CloudSyncState {
     lastPullAt?: number;
     /** The last failure, kept so `reticle sync` can say why it is behind instead of just "0 sent". */
     lastError?: string;
+    /**
+     * Run ids this machine has watched the server accept, kept only for the runs still held locally.
+     *
+     * Read ONLY when the server says its own `knownRunIds` was truncated. A complete list is a
+     * complete answer — a run missing from one is genuinely missing and must be re-sent — so this
+     * fills the gap the server declared and never overrides the server on a question it answered.
+     */
+    sentRunIds?: string[];
 }
 export interface SyncReport {
+    /**
+     * False if the cycle failed or any offered run was rejected. A completed HTTP exchange alone
+     * is not a successful push. Accepted counts and rejection reasons still describe partial success.
+     */
     ok: boolean;
     /** Runs the server accepted this cycle. */
     runsSent: number;

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

@@ -99,9 +99,20 @@ export async function runSyncCycle(deps) {
          * something the server does not have. Silent data loss is the one failure this protocol must
          * not have, and an unreadable answer has to mean "it knows nothing", never "it knows this".
          */
-        const known = new Set(Array.isArray(held.knownRunIds)
-            ? held.knownRunIds.filter((id) => 'string' === typeof id)
-            : []);
+        const onlyStrings = (value) => Array.isArray(value) ? value.filter((id) => 'string' === typeof id) : [];
+        /*
+         * The server may answer "here are the ids I hold, and there are more than I listed". Read as the
+         * whole truth, that short list made every run past the server's page look unsent, so a project
+         * with enough runs to truncate it re-uploaded its history on every single cycle, forever. The
+         * field was declared on this response and read nowhere.
+         *
+         * Only then is the machine's own record consulted, and it is subject to the same rule as the
+         * server's: anything that is not a list of strings reads as "nothing is known".
+         */
+        const known = new Set([
+            ...onlyStrings(held.knownRunIds),
+            ...(true === held.truncated ? onlyStrings(deps.state.sentRunIds) : []),
+        ]);
         // Same rule for the hashes: only a string can equal a hash we computed, so anything else reads
         // as "unknown" and the record is sent once. Re-sending costs a request; skipping costs the data.
         const hashes = isRecord(held.stateHashes) ? held.stateHashes : {};
@@ -158,7 +169,20 @@ export async function runSyncCycle(deps) {
                 ? runs['rejected']
                 : [];
             nextState.lastPushAt = deps.now();
+            // Accepted means the server has it. A rejected run was refused by index, so it is exactly as
+            // unsent as it was before and must never be remembered as delivered.
+            const refused = new Set(runsRejected.map((r) => r.index));
+            unsent.forEach((run, index) => {
+                if (!refused.has(index))
+                    known.add(run.runId);
+            });
         }
+        /*
+         * Bounded by the runs still on disk rather than by a cap. Retention already decides how many
+         * runs a workspace keeps, and an id for a run nobody holds any more cannot stop an upload that
+         * will never be attempted — so the record follows the artifacts and needs no number of its own.
+         */
+        nextState.sentRunIds = allRuns.map((r) => r.runId).filter((id) => known.has(id));
         // 3. COLLECT — always, even when there was nothing to send.
         const query = nextState.cursor === undefined ? '' : `?since=${encodeURIComponent(nextState.cursor)}`;
         const pull = await call(`${SYNC_PULL_PATH}${query}`);
@@ -199,7 +223,8 @@ export async function runSyncCycle(deps) {
         delete nextState.lastError;
         deps.sink.writeState(nextState);
         return {
-            ok: true,
+            // Keep transport errors separate: rejection reasons already identify the failed artifacts.
+            ok: 0 === runsRejected.length,
             runsSent,
             runsRejected,
             flowsSent,

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

@@ -45,6 +45,19 @@ export interface SyncDaemon {
      */
     nudge: () => void;
     stop: () => void;
+    /**
+     * Stop, but send what is still owed first.
+     *
+     * `stop()` cancels the pending timer, and the last thing a session writes is the run artifact the
+     * whole drive produced — so a daemon asked to close moments after a verdict dropped the one push
+     * anybody was waiting on. Measured against app.reticle.sh: a drive wrote its run, the daemon
+     * exited, and the dashboard's newest row stayed three weeks old.
+     *
+     * Bounded, because shutdown is not allowed to hang: an in-flight cycle is waited out only until
+     * the deadline, and a cycle that cannot finish in time is simply the interval's problem next
+     * time — the artifact is still on disk and the next daemon for this project sends it.
+     */
+    flush: () => Promise<void>;
 }
 /**
  * Start the loop. Safe to call for an UNLINKED project: it resolves the link on every tick and does

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

@@ -54,6 +54,15 @@ const FIRST_CYCLE_DELAY_MS = 5_000;
  * written just after, so cycling on the very first byte would ship a bundle that is missing them.
  */
 const NUDGE_DELAY_MS = 1_500;
+/**
+ * How long a flush waits for a cycle already in flight before running its own.
+ *
+ * Shutdown budget, not a sync budget: every call inside a cycle already carries its own timeout, so
+ * this only bounds the WAIT. Generous enough for an ordinary cycle to finish, short enough that a
+ * stalled one cannot hold a daemon open.
+ */
+const FLUSH_WAIT_MS = 3_000;
+const FLUSH_POLL_MS = 25;
 const defaultRequest = async (url, init) => {
     const res = await fetch(url, init);
     return { status: res.status, text: await res.text() };
@@ -270,6 +279,18 @@ export function startSyncDaemon(deps) {
                 clearTimeout(timer);
             timer = undefined;
         },
+        flush: async () => {
+            stopped = true;
+            if (timer !== undefined)
+                clearTimeout(timer);
+            timer = undefined;
+            // A cycle already running may have started BEFORE the write being flushed, so its report says
+            // nothing about that artifact. Wait it out rather than skipping on the overlap guard.
+            const deadline = Date.now() + FLUSH_WAIT_MS;
+            while (running && Date.now() < deadline)
+                await new Promise((resolve) => setTimeout(resolve, FLUSH_POLL_MS));
+            await cycle();
+        },
     };
 }
 /**

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

@@ -12,7 +12,7 @@
  */
 import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, writeFileSync, } from 'node:fs';
 import { dirname, join } from 'node:path';
-import { ReticleDir } from '@reticlehq/core';
+import { IntentDir, ReticleDir } from '@reticlehq/core';
 import { subjectFor } from '../intent/intent-subject.js';
 const JSON_SUFFIX = '.json';
 /** Read + parse, or undefined for absent/unreadable/malformed. Never throws. */
@@ -73,8 +73,8 @@ const DERIVED_FILE = {
     intent: ReticleDir.INTENT_FILE,
 };
 /** The directory the sharded intent store writes into, beside the legacy flat file. */
-const INTENT_SUBDIR = 'intent';
-const INTENT_INDEX = 'index.json';
+const INTENT_SUBDIR = ReticleDir.INTENT_SUBDIR;
+const INTENT_INDEX = IntentDir.INDEX_FILE;
 /**
  * Every intent this project holds, flat file and shards merged.
  *
@@ -98,10 +98,15 @@ function readIntent(reticleRoot) {
         ...(legacy?.intents ?? {}),
     };
     let shards = 0;
-    for (const file of safeReaddir(join(reticleRoot, INTENT_SUBDIR))) {
-        if (!file.endsWith(JSON_SUFFIX) || INTENT_INDEX === file)
+    for (const entry of safeReaddir(join(reticleRoot, INTENT_SUBDIR))) {
+        if (INTENT_INDEX === entry)
             continue;
-        const shard = readJson(join(reticleRoot, INTENT_SUBDIR, file));
+        // `<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)
+            ? join(reticleRoot, INTENT_SUBDIR, entry)
+            : 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)
             continue;

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

@@ -221,7 +221,13 @@ export class ImpactStore {
         if (this.#dashboardUrl !== undefined)
             snap.dashboardUrl = this.#dashboardUrl;
         snap.account = this.#account();
+        const cfgForOffer = this.#config.read();
         const offer = this.#offer.read();
+        // Joined here because this is the one place that holds BOTH the offer and the platform config.
+        // The card reads the offer, so readiness has to travel on it rather than being re-derived in a
+        // presenter that has no business knowing what a provider key is.
+        if (offer !== undefined && cfgForOffer !== undefined)
+            offer.drivable = cfgForOffer.providerReady;
         // Absent means "we have not heard", which the HUD renders as nothing at all. Never defaulted to
         // `{claimed:false}`: that would advertise the offer to everyone who is offline.
         if (offer !== undefined)

package/dist/memory/intent/inline-intent.js

@@ -9,7 +9,7 @@ import { sessionRoot } from '../project/session-root.js';
  * and it does. `reticle_act_and_wait` and `reticle_assert` are in every agent's tool list already,
  * so one optional argument there makes the declaration free and discoverable by construction.
  *
- * This is a shortcut into the EXISTING ledger, never a second one. It writes `.reticle/intent.json`
+ * This is a shortcut into the EXISTING ledger, never a second one. It writes `.reticle/intent/`
  * through `IntentStore` exactly as `reticle_intent { action: "declare" }` does, so a reviewer reads
  * one file in one vocabulary and cannot tell from the row which door the intent came in by. The
  * pattern is `flows/flow-intent.ts`, which does the same job for a saved flow.
@@ -146,8 +146,13 @@ binding) {
         // Declared WITHOUT a surface on purpose: see dischargeInlineIntent for why the route that
         // describes this record only exists after the action it is about.
         const declaredHere = existing === undefined;
-        if (declaredHere)
-            await store.declare([{ id, statement: intent }]);
+        if (declaredHere) {
+            // Nothing stored (a step label is refused) means nothing to link: no verdict may then claim
+            // to have proved an intent that was never written.
+            const stored = await store.declare([{ id, statement: intent }]);
+            if (0 === stored.length)
+                return undefined;
+        }
         /*
          * A binding may be INVENTED only for a row this call also declared.
          *

package/dist/memory/intent/intent-shard-store.d.ts

@@ -1,29 +1,31 @@
 /**
- * Reading and writing the sharded intent store, and migrating the flat one into it.
+ * The intent ledger on disk: one directory per subject, and a flow's name IS its subject.
  *
- * The operations an agent actually performs, and what each is allowed to cost:
+ *   .reticle/intent/index.json               every id, its subject and one line — derived
+ *   .reticle/intent/<subject>/intent.json    the full records for that subject
  *
- *   index()            every id + one line, always affordable — the session-start read
- *   subject(name)      the full records for one subject, when it is about to work on that
- *   get(id)            one record, via the index rather than by scanning shards
- *   record()/update()  a write that touches ONE shard file plus the index
+ * The ONE place intents are stored. `IntentStore` is the domain API over it (declare, bind,
+ * discharge) and never writes a file of its own; `reticle_intent`'s record/get/index/subject read
+ * this directly. Two stores kept in two files is how an intent written through one action became
+ * invisible to the other, and an agent told its own intent does not exist concludes it does not.
  *
- * The last one is the reason for the whole design. Under the flat file, changing one intent rewrote
- * all 141, so two sessions touching unrelated subjects raced each other and the loser's write
- * vanished. Sharded, they only collide when they genuinely edit the same subject.
+ * Git-checked on purpose: a human sees in review when an intent is narrowed to match what was easy
+ * to prove. Writes are byte-stable, and a write that changes nothing writes nothing, because a ledger
+ * that churns on every run is one whose diffs nobody reads.
  *
- * ## Migration is automatic, and it does not delete
+ * ## Migration happens on the first write, and it removes what it moved
  *
- * `.reticle/intent.json` is read on every load and folded in when the sharded copy has nothing for
- * an id. That makes the move invisible: an agent on the new store sees old intents immediately, and
- * an older build still reading the flat file keeps working, because nothing removes it. Deleting it
- * is a separate decision somebody can take once they believe the migration.
+ * The old single `.reticle/intent.json` (and any interim `intent/<subject>.json`) is read until then,
+ * so nothing is invisible before the move. The first write folds every record into its directory and
+ * deletes the old files, so the change shows up in one reviewable diff. A legacy file that does not
+ * PARSE is never deleted: a hand-merge leaves conflict markers, it reads as empty, and removing it
+ * would destroy the only copy of every intent inside.
  */
 import { type Intent } from '@reticlehq/core/artifacts';
 import type { FileSystemPort } from '../project/fs/fs-port.js';
 import type { Clock } from '../../machine/clock.js';
 import { IntentStatus, type IntentIndex, type IntentRecord } from './intent-shard.js';
-/** What a caller supplies to write an intent. Everything optional is genuinely optional. */
+/** What a caller supplies to write an intent through `record`. Everything optional is optional. */
 interface IntentInput {
     id: string;
     statement: string;
@@ -34,51 +36,35 @@ interface IntentInput {
     surface?: Intent['surface'];
     binding?: unknown;
 }
+/** The ledger-level facts a write may set beside the intent itself. */
+export interface RecordFacts {
+    subject?: string | undefined;
+    status?: IntentStatus | undefined;
+    why?: string | undefined;
+    source?: string | undefined;
+}
 export declare class IntentShardStore {
     #private;
     constructor(fs: FileSystemPort, root: string, clock: Clock);
-    /**
-     * Every record: the shards, plus any legacy intent the shards have not absorbed.
-     *
-     * Sharded wins on a collision. An id present in both has been migrated and possibly edited since,
-     * and letting the flat copy overwrite that would silently revert the edit.
-     */
-    /**
-     * Every record this ledger holds, from BOTH files, deduped by id.
-     *
-     * Public because the ledger is one logical thing kept in two places, and the tool that offers
-     * `list` has to be able to see all of it. It was private while `record` wrote to shards and `list`
-     * read the flat file, which meant an intent written through one action was invisible to the other
-     * — and an agent told its own recorded intent does not exist concludes the intent does not exist,
-     * not that there are two stores.
-     */
+    /** Every record: the directories, plus any legacy intent not yet moved. Directories win. */
     all(): Promise<IntentRecord[]>;
-    /**
-     * The cheap read: one line per intent, and the call an agent makes at the start of a session.
-     *
-     * Includes anything still only in the legacy flat file, so the very first call on an unmigrated
-     * project already answers completely — which is what makes the migration invisible rather than a
-     * step somebody has to remember to run.
-     */
+    /** The cheap read: one line per intent. Derived from disk, never from the stored copy. */
     index(): Promise<IntentIndex>;
     /** Every record for one subject — the working read, once an agent knows what it is touching. */
     subject(name: string): Promise<IntentRecord[]>;
     /** One record by id, or null. */
     get(id: string): Promise<IntentRecord | null>;
     /**
-     * Write one intent, creating or updating it.
+     * Create or change ONE intent atomically: read, transform, write, under the ledger's lock.
      *
-     * Merges onto whatever is already stored, so a caller adding a `why` to a migrated record does not
-     * have to restate its binding — and cannot silently drop it by omission, which is the failure mode
-     * that makes agents afraid to touch a store.
+     * `transform` returns the next intent, or undefined for "leave it as it is". A result equal to
+     * what is stored writes nothing. Returns the stored record, or undefined when nothing was there
+     * and nothing was created.
      */
+    upsert(id: string, transform: (existing: IntentRecord | undefined) => Intent | undefined, facts?: RecordFacts): Promise<IntentRecord | undefined>;
+    /** Write one intent through `reticle_intent { action: "record" }`, merging onto what is stored. */
     record(input: IntentInput): Promise<IntentRecord>;
-    /**
-     * Fold the flat file into shards on disk, so the move is visible in a diff rather than implicit.
-     *
-     * Idempotent, and it does not delete `.reticle/intent.json`: an older build still reads it, and a
-     * migration that removes its own source cannot be checked afterwards.
-     */
+    /** `reticle_intent { action: "migrate" }`: do now what the next write would do anyway. */
     migrate(): Promise<{
         migrated: number;
         subjects: string[];