@reticlehq/server 2.12.0 → 2.13.0

package/dist/cloud/sync-disk.js

@@ -0,0 +1,191 @@
+/**
+ * The filesystem half of a sync cycle: what `.reticle/` looks like to the protocol.
+ *
+ * Kept apart from `sync-cycle.ts` on purpose. The cycle is the interesting part — what to send, what
+ * to skip, what to do when the network is down — and it stays provable only because it never touches
+ * a disk. This is the boring part, and boring is what it should be: read a file, tolerate its
+ * absence, never throw.
+ *
+ * EVERY READ IS FORGIVING. A half-written impact.json from a process that died mid-flush must cost
+ * one unsynced record, not a crashed sync. There is no state here worth defending against a parse
+ * error — the file will be rewritten on the next tool call anyway.
+ */
+import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, writeFileSync, } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { 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. */
+function readJson(path) {
+    try {
+        return existsSync(path) ? JSON.parse(readFileSync(path, 'utf8')) : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Write atomically. tmp + rename, because two daemons can serve one repo at once and a half-written
+ * cursor file is one the next read discards — which would silently re-pull the whole decision
+ * history, or worse, skip it.
+ */
+function writeJson(path, value) {
+    try {
+        mkdirSync(dirname(path), { recursive: true });
+        const tmp = `${path}.${String(process.pid)}.tmp`;
+        writeFileSync(tmp, `${JSON.stringify(value, null, 2)}\n`, 'utf8');
+        renameSync(tmp, path);
+    }
+    catch {
+        // Bookkeeping that cannot be written must never break a sync. The next cycle re-derives it; the
+        // worst case is one redundant upload, which the server dedupes anyway.
+    }
+}
+/** Every `*.json` directly inside a directory, parsed. Absent directory reads as empty. */
+function readJsonDir(dir) {
+    try {
+        if (!existsSync(dir))
+            return [];
+        return readdirSync(dir)
+            .filter((f) => f.endsWith(JSON_SUFFIX))
+            .map((f) => readJson(join(dir, f)))
+            .filter((v) => v !== undefined);
+    }
+    catch {
+        return [];
+    }
+}
+/** Flows live one directory deeper, under the app's own project id. */
+function readFlows(root) {
+    const dir = join(root, ReticleDir.FLOWS_SUBDIR);
+    try {
+        if (!existsSync(dir))
+            return [];
+        return readdirSync(dir).flatMap((scope) => readJsonDir(join(dir, scope)));
+    }
+    catch {
+        return [];
+    }
+}
+const DERIVED_FILE = {
+    impact: ReticleDir.IMPACT_FILE,
+    flake: ReticleDir.FLAKE_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';
+/**
+ * Every intent this project holds, flat file and shards merged.
+ *
+ * The store was split into one file per subject so that writing one record stops rewriting all of
+ * them. Sync was not told, and kept reading `intent.json` alone — which the migration deliberately
+ * does not delete. The result was the worst shape a sync bug can take: not an error, but a corpus
+ * that looked healthy on the dashboard and had silently stopped moving, because every intent
+ * captured after the migration stayed on the engineer's laptop.
+ *
+ * Shards WIN on a collision, matching the store's own rule: an id present in both has been migrated
+ * and possibly edited since, and letting the flat copy overwrite that would revert the edit on every
+ * cycle. `index.json` is derived from the shards and is skipped — sending it would duplicate every
+ * record as a summary of itself.
+ *
+ * Returns undefined when there is no memory at all, so a project with nothing to say sends nothing
+ * rather than an empty envelope the server has to store.
+ */
+function readIntent(reticleRoot) {
+    const legacy = readJson(join(reticleRoot, ReticleDir.INTENT_FILE));
+    const merged = {
+        ...(legacy?.intents ?? {}),
+    };
+    let shards = 0;
+    for (const file of safeReaddir(join(reticleRoot, INTENT_SUBDIR))) {
+        if (!file.endsWith(JSON_SUFFIX) || INTENT_INDEX === file)
+            continue;
+        const shard = readJson(join(reticleRoot, INTENT_SUBDIR, file));
+        // A hand-edited or half-written shard costs one subject, never the whole sync.
+        if (shard?.intents === undefined)
+            continue;
+        shards++;
+        for (const [id, record] of Object.entries(shard.intents))
+            merged[id] = record;
+    }
+    if (legacy === undefined && 0 === shards)
+        return undefined;
+    /*
+     * Stamp the SUBJECT before sending, on anything that does not already carry one.
+     *
+     * The subject ladder lives here, in the engine, and knows how to read a flow, a route and a
+     * binding predicate. The server had no access to it and had reimplemented a far weaker version —
+     * flow-or-nothing — so records this ladder files correctly arrived at the dashboard as
+     * `unsorted`. Measured on the real corpus: 105 of 163 records the engine can place were landing
+     * in the bucket of last resort, which is what made a coverage map read as one pile with six
+     * labels.
+     *
+     * Computed HERE rather than duplicated there, because two rules for one question is how the
+     * answers start disagreeing — and the one with the evidence should be the one that decides.
+     * Records that already name a subject keep it: an agent's explicit choice outranks inference.
+     */
+    const placed = Object.fromEntries(Object.entries(merged).map(([id, record]) => {
+        const held = record;
+        if ('string' === typeof held.subject && held.subject.length > 0)
+            return [id, record];
+        const subject = subjectFor({
+            surface: held.surface,
+            binding: held.binding,
+        });
+        return [id, { ...held, subject }];
+    }));
+    return { version: 1, intents: placed };
+}
+/** Directory listing that tolerates absence — an unmigrated project has no `intent/`. */
+function safeReaddir(dir) {
+    try {
+        return readdirSync(dir);
+    }
+    catch {
+        return [];
+    }
+}
+/** What the cycle reads, backed by a real `.reticle` directory. */
+export function diskSource(reticleRoot) {
+    return {
+        runs: () => readJsonDir(join(reticleRoot, ReticleDir.RUNS_SUBDIR))
+            .map((payload) => {
+            const id = payload?.runId;
+            return 'string' === typeof id ? { runId: id, 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),
+        flows: () => readFlows(reticleRoot),
+        // Intent is the only derived record that is no longer one file. See readIntent.
+        derived: (kind) => 'intent' === kind ? readIntent(reticleRoot) : readJson(join(reticleRoot, DERIVED_FILE[kind])),
+    };
+}
+/** What the cycle writes back into `.reticle/`. */
+export function diskSink(reticleRoot) {
+    return {
+        writeIssues: (issues) => {
+            // MERGED, not replaced. A pull returns only what changed since the cursor, so overwriting
+            // would drop every earlier decision the moment one new decision arrived.
+            const held = readCloudIssues(reticleRoot);
+            writeJson(join(reticleRoot, ReticleDir.ISSUES_FILE), {
+                triage: { ...held.triage, ...issues.triage },
+            });
+        },
+        writeState: (state) => {
+            writeJson(join(reticleRoot, ReticleDir.CLOUD_STATE_FILE), state);
+        },
+    };
+}
+/** This machine's side of the conversation, or a blank one on first run. */
+export function readCloudState(reticleRoot) {
+    const raw = readJson(join(reticleRoot, ReticleDir.CLOUD_STATE_FILE));
+    return 'object' === typeof raw && null !== raw ? raw : {};
+}
+/** The decisions pulled back from the dashboard, for the HUD and for the next run to read. */
+export function readCloudIssues(reticleRoot) {
+    const raw = readJson(join(reticleRoot, ReticleDir.ISSUES_FILE));
+    const triage = 'object' === typeof raw && null !== raw ? raw.triage : undefined;
+    return { triage: 'object' === typeof triage && null !== triage ? triage : {} };
+}

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

@@ -0,0 +1,2 @@
+/** A stable content hash of one derived record. Must equal the server's for the same input. */
+export declare function hashPayload(payload: unknown): string;

package/dist/cloud/sync-hash.js

@@ -0,0 +1,35 @@
+/**
+ * The content hash both halves of sync compare on.
+ *
+ * The server answers "here is a hash per record you have already sent me"; the machine hashes what
+ * it holds and sends only what differs. That only works if the two sides compute the SAME number
+ * from the same record, so this function is a CONTRACT, not a utility — it has to stay byte-for-byte
+ * equivalent to the server's, and it is separated out and tested against fixed vectors for exactly
+ * that reason.
+ *
+ * Keys are sorted before serialising because two structurally identical records must hash the same
+ * however they happened to be written out. Without that, a machine whose JSON key order differed
+ * from the server's would re-upload the same unchanged record on every cycle, forever, and the whole
+ * point of hashing — not paying for what has not moved — would be lost silently.
+ */
+import { createHash } from 'node:crypto';
+/** How much of the digest is kept. Long enough that a collision is not a practical concern here. */
+const HASH_LENGTH = 32;
+/** Recursively sort object keys so serialisation is canonical. Arrays keep their order — it is data. */
+function canonical(value) {
+    if (Array.isArray(value))
+        return value.map(canonical);
+    if (value !== null && 'object' === typeof value) {
+        return Object.fromEntries(Object.entries(value)
+            .sort(([a], [b]) => a.localeCompare(b))
+            .map(([k, v]) => [k, canonical(v)]));
+    }
+    return value;
+}
+/** A stable content hash of one derived record. Must equal the server's for the same input. */
+export function hashPayload(payload) {
+    return createHash('sha256')
+        .update(JSON.stringify(canonical(payload)))
+        .digest('hex')
+        .slice(0, HASH_LENGTH);
+}

package/dist/crawl/crawl-tools.js

@@ -1,6 +1,7 @@
 import { z } from 'zod';
 import { ReticleTool } from '../tools/tool-names.js';
 import { asNumber, asString } from '../tools/tools-helpers.js';
+import { stepCountSchema, timeoutMsSchema } from '../tools/numeric-bounds.js';
 import { crawl } from './crawl.js';
 import { routeFromUrl, routesFromEvents } from '../project/learned-routes.js';
 const nodeSleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
@@ -14,9 +15,10 @@ export const CRAWL_TOOLS = [
         name: ReticleTool.CRAWL,
         description: 'Autonomously click every reachable interactive control (bounded by maxSteps, default 25) and report anomalies WITHOUT a script. Two classes: single-channel faults (console errors, failed requests ≥400, DEAD controls that dispatched but did nothing) and CONTRADICTIONS — two channels disagreeing about the same click, e.g. the UI advanced while its write failed, a success signal fired over a failed request, a write succeeded and nothing changed, the same write fired twice, or the UI moved on over an in-flight request. Contradictions are the false greens a human cannot see, because a human watches one channel (the screen) and it looks correct. DESTRUCTIVE — it really clicks (may navigate/mutate state); use reticle_explore first for a non-destructive list. Returns { interactiveFound, stepsRun, anomalies[{kind,ref,desc,detail}], counts, visited, truncated }.',
         inputSchema: {
-            maxSteps: z.number().optional().describe('Maximum number of controls to click. Default: 25.'),
-            settleMs: z
-                .number()
+            maxSteps: stepCountSchema
+                .optional()
+                .describe('Maximum number of controls to click. Default: 25.'),
+            settleMs: timeoutMsSchema
                 .optional()
                 .describe('Milliseconds to wait after each click for the app to react. Default: 500.'),
             scope: z

package/dist/crawl/crawl.d.ts

@@ -13,6 +13,9 @@ export interface CrawlSession {
     /** Which round of source edits is in force, so a finding drawn entirely from pre-edit evidence
      *  says so. Optional for the same reason `currentDocumentId` is. */
     readonly currentEditEpoch?: number | undefined;
+    /** 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;
     /**
      * Attribution window around each click. Optional so a caller can supply a minimal session, but a real
      * session MUST provide it: without a window the click's own effects carry no actionId, and an

package/dist/crawl/crawl.js

@@ -216,6 +216,11 @@ export async function crawl(session, opts, sleep) {
         for (const c of findContradictions(events, {
             currentDocumentId: session.currentDocumentId,
             currentEditEpoch: session.currentEditEpoch,
+            appOrigin: session.url,
+            // The crawl's window IS one control's click, so it can name the floor the consequence rules
+            // need — without it a crawl would report nothing about the UI moving, which is most of what a
+            // crawl is for.
+            actionSince: since,
         })) {
             counts.contradictions += 1;
             anomalies.push({

package/dist/daemon/daemon-resolve.d.ts

@@ -55,6 +55,49 @@ export declare function resolveDaemonForProject(projectId: string | undefined, h
 export declare function adoptable(daemonProjectId: string | undefined, callerProjectId: string | undefined): boolean;
 /** The project a daemon on `port` claims, or undefined when it claims none / is not registered. */
 export declare function daemonProjectAt(port: number, home: string): string | undefined;
+/**
+ * Live daemons OTHER than `myPort` that an app for this project has connected to.
+ *
+ * The split brain this whole module was written to prevent has a second half nobody was reporting.
+ * `resolveMcpPort` correctly refuses to adopt a stranger's daemon and relocates to an OS-assigned
+ * port — and the APP, which resolves its own port independently (core's `pickDaemonPort` in the
+ * build plugin, falling back to the documented default when nothing matches), can land on the
+ * stranger. The pairing token is per USER, not per project, so that connect SUCCEEDS: the app is
+ * live on one daemon and the agent is attached to a different, empty one.
+ *
+ * Every individual check is then green. The browser shows an instrumented page, `reticle status`
+ * reports a session, the agent reports Reticle registered and enabled — and the agent's tools see
+ * nothing, with a no-session diagnosis that tells it to start a dev server that is already running.
+ *
+ * `connectedOn` is injected rather than imported so this stays free of the session layer (which
+ * imports from here) and so the rule is testable without a real `~/.reticle`. Callers pass
+ * `hasProjectConnectedBefore` bound to the same projectId.
+ *
+ * Only LIVE daemons are named: a port a session used yesterday is history, not a split.
+ */
+export declare function daemonsServingProjectElsewhere(projectId: string | undefined, myPort: number, home: string, alive: (pid: number) => boolean, connectedOn: (port: number) => boolean): readonly number[];
+/**
+ * The sentence for a split brain, or `undefined` when there is none.
+ *
+ * Stated as a fact about two ports rather than a hedge, because unlike the sibling-port observation
+ * next door this is not "something is listening somewhere" — it is this project's own connection
+ * record naming a daemon that is not the one being asked. The wording says which side is empty,
+ * since the failure is invisible precisely because both sides look healthy from where they stand.
+ */
+export declare function splitBrainNote(myPort: number, elsewhere: readonly number[]): string | undefined;
+/**
+ * The other stance on the same split, for a command standing on the port that HAS the app.
+ *
+ * `splitBrainNote` is asked from the empty daemon and reads the connection record. From the daemon
+ * the app is connected to there is nothing missing to notice — sessions are live, every check is
+ * green — and the only visible fact is that this project ALSO owns a live daemon somewhere else.
+ * One project, two daemons, is a split whichever end you are standing on, and saying it from both
+ * ends is the difference between a user inferring it from two green checkmarks and being told.
+ *
+ * Silent for a caller with no project (it owns no daemon to be split from) and silent when the port
+ * being inspected is the project's own.
+ */
+export declare function wrongDaemonNote(inspectedPort: number, ownPort: number | undefined): string | undefined;
 /**
  * The port this agent's MCP proxy should serve, decided BEFORE the proxy starts.
  *

package/dist/daemon/daemon-resolve.js

@@ -89,6 +89,75 @@ export function adoptable(daemonProjectId, callerProjectId) {
 export function daemonProjectAt(port, home) {
     return readDaemonRegistry(home).find((e) => e.port === port)?.projectId;
 }
+/**
+ * Live daemons OTHER than `myPort` that an app for this project has connected to.
+ *
+ * The split brain this whole module was written to prevent has a second half nobody was reporting.
+ * `resolveMcpPort` correctly refuses to adopt a stranger's daemon and relocates to an OS-assigned
+ * port — and the APP, which resolves its own port independently (core's `pickDaemonPort` in the
+ * build plugin, falling back to the documented default when nothing matches), can land on the
+ * stranger. The pairing token is per USER, not per project, so that connect SUCCEEDS: the app is
+ * live on one daemon and the agent is attached to a different, empty one.
+ *
+ * Every individual check is then green. The browser shows an instrumented page, `reticle status`
+ * reports a session, the agent reports Reticle registered and enabled — and the agent's tools see
+ * nothing, with a no-session diagnosis that tells it to start a dev server that is already running.
+ *
+ * `connectedOn` is injected rather than imported so this stays free of the session layer (which
+ * imports from here) and so the rule is testable without a real `~/.reticle`. Callers pass
+ * `hasProjectConnectedBefore` bound to the same projectId.
+ *
+ * Only LIVE daemons are named: a port a session used yesterday is history, not a split.
+ */
+export function daemonsServingProjectElsewhere(projectId, myPort, home, alive, connectedOn) {
+    if (projectId === undefined || 0 === projectId.length)
+        return [];
+    return readDaemonRegistry(home)
+        .filter((entry) => entry.port !== myPort && alive(entry.pid) && connectedOn(entry.port))
+        .map((entry) => entry.port)
+        .sort((a, b) => a - b);
+}
+/**
+ * The sentence for a split brain, or `undefined` when there is none.
+ *
+ * Stated as a fact about two ports rather than a hedge, because unlike the sibling-port observation
+ * next door this is not "something is listening somewhere" — it is this project's own connection
+ * record naming a daemon that is not the one being asked. The wording says which side is empty,
+ * since the failure is invisible precisely because both sides look healthy from where they stand.
+ */
+export function splitBrainNote(myPort, elsewhere) {
+    if (0 === elsewhere.length)
+        return undefined;
+    const listed = elsewhere.map((port) => `:${String(port)}`).join(', ');
+    const first = elsewhere[0] ?? myPort;
+    return (`this project's app is connected to a DIFFERENT Reticle daemon (${listed}), while this one is ` +
+        `on :${String(myPort)} — two daemons for one project, and the agent is attached to the empty ` +
+        'half. Nothing is wrong with the app or the wiring. Stop the other daemon with ' +
+        `\`reticle stop --port ${String(first)}\` and restart the dev server so the app rediscovers ` +
+        'this one, or start the agent and the dev server from the same project directory so both ' +
+        'resolve the same daemon.');
+}
+/**
+ * The other stance on the same split, for a command standing on the port that HAS the app.
+ *
+ * `splitBrainNote` is asked from the empty daemon and reads the connection record. From the daemon
+ * the app is connected to there is nothing missing to notice — sessions are live, every check is
+ * green — and the only visible fact is that this project ALSO owns a live daemon somewhere else.
+ * One project, two daemons, is a split whichever end you are standing on, and saying it from both
+ * ends is the difference between a user inferring it from two green checkmarks and being told.
+ *
+ * Silent for a caller with no project (it owns no daemon to be split from) and silent when the port
+ * being inspected is the project's own.
+ */
+export function wrongDaemonNote(inspectedPort, ownPort) {
+    if (ownPort === undefined || ownPort === inspectedPort)
+        return undefined;
+    return (`this is not this project's own daemon: the registry says it owns a live daemon on ` +
+        `:${String(ownPort)} and this command is looking at :${String(inspectedPort)}. Two daemons for ` +
+        'one project means the half your agent is attached to and the half your app is connected to can ' +
+        'be different processes, with both reporting healthy. Stop one of them and restart the dev ' +
+        'server so everything lands on the same port.');
+}
 /**
  * The port this agent's MCP proxy should serve, decided BEFORE the proxy starts.
  *

package/dist/daemon/dev-servers.d.ts

@@ -0,0 +1,15 @@
+import { type DevServerEntry } from '@reticlehq/core';
+/** Injected so the reading is unit-testable without a real home or real processes. */
+export interface DevServerIo {
+    readdir: (dir: string) => string[];
+    readFile: (path: string) => string;
+    isAlive: (pid: number) => boolean;
+}
+/**
+ * Every dev server that announced itself and is still running, lowest port first.
+ *
+ * Fails soft at every step. This runs on the path that explains to a user why setup has not worked,
+ * so a half-written file, a hand-edit, or a missing directory must degrade the answer rather than
+ * replace the diagnosis with a stack trace.
+ */
+export declare function readDevServers(home: string, io?: DevServerIo): DevServerEntry[];

package/dist/daemon/dev-servers.js

@@ -0,0 +1,68 @@
+/**
+ * Reading what dev servers have announced about themselves.
+ *
+ * The consumer half of `devserver-<port>.json`. A build plugin writes one when its dev server is
+ * actually listening; this reads them back, so `init` and `status` can tell three states apart that
+ * used to be one:
+ *
+ *   nothing announced    no dev server with Reticle loaded is running
+ *   announced, no page   the bundle is wired and no browser dialled — and the entry names the URL
+ *   announced + session  working
+ *
+ * The middle one is the case that had no message. It was folded into "restart your dev server and
+ * load the app", which is two instructions where only the second one applies, addressed to someone
+ * who has already done the first.
+ *
+ * Fs plumbing only — the selection rule is `liveDevServers` in core, shared with anything else that
+ * reads this registry, for the same reason `pickDaemonPort` lives there.
+ */
+import { readdirSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { DevServerEntrySchema, devServerRegistryPort, liveDevServers, } from '@reticlehq/core';
+/** process.kill(pid, 0) throws iff the process is gone — the same probe the daemon registry uses. */
+function isAliveNow(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+const nodeIo = {
+    readdir: (dir) => readdirSync(dir),
+    readFile: (path) => readFileSync(path, 'utf8'),
+    isAlive: isAliveNow,
+};
+/**
+ * Every dev server that announced itself and is still running, lowest port first.
+ *
+ * Fails soft at every step. This runs on the path that explains to a user why setup has not worked,
+ * so a half-written file, a hand-edit, or a missing directory must degrade the answer rather than
+ * replace the diagnosis with a stack trace.
+ */
+export function readDevServers(home, io = nodeIo) {
+    let files;
+    try {
+        files = io.readdir(home);
+    }
+    catch {
+        return []; // No state directory yet — nothing has ever run here.
+    }
+    const entries = [];
+    for (const file of files) {
+        // Strict on the filename BEFORE reading: the daemon's own `daemon-<port>.json` is a sibling, and
+        // parsing one as a dev server would report the daemon itself as an instrumented app.
+        if (null === devServerRegistryPort(file))
+            continue;
+        try {
+            const parsed = DevServerEntrySchema.safeParse(JSON.parse(io.readFile(join(home, file))));
+            if (parsed.success)
+                entries.push(parsed.data);
+        }
+        catch {
+            // Truncated, mid-write, or hand-edited. One bad file is not a reason to report none.
+        }
+    }
+    return liveDevServers(entries, io.isAlive);
+}

package/dist/daemon/wake-decision.d.ts

@@ -0,0 +1,32 @@
+/**
+ * What a woken MCP proxy may do with whatever is sitting on its port.
+ *
+ * Pulled out as a pure function because the wake path lives inside a long side-effecting closure in
+ * `mcp-command.ts`, and the decision it was getting wrong is three lines of reasoning that deserve a
+ * test of their own.
+ *
+ * `resolveMcpPort` asks the identity question at BOOT and relocates rather than adopting a stranger.
+ * The wake path asked only whether a daemon answered, so after an idle exit freed the port and
+ * another project's daemon bound it, a dormant proxy could reattach to a daemon that was not its
+ * own — and then serve an agent verdicts about a different application. `adoptable` is the same rule
+ * boot uses; this is just the wake path finally asking it.
+ */
+import { PortPresence } from './port-presence.js';
+export declare const WakeAction: {
+    /** A daemon we may use is already here. */
+    readonly USE: "use";
+    /** Nothing is listening: start one. */
+    readonly SPAWN: "spawn";
+    /** Somebody else's. Go dormant with a reason rather than pretend the wake succeeded. */
+    readonly REFUSE: "refuse";
+};
+export type WakeAction = (typeof WakeAction)[keyof typeof WakeAction];
+/**
+ * Identity is asked only of a port that actually holds a daemon.
+ *
+ * A FREE port must stay spawnable whatever the registry says about it, because a stale entry is the
+ * registry's ordinary state for the moment after any daemon exits — and refusing there would turn
+ * every idle retirement into a permanent lockout, which is the failure this whole path exists to
+ * prevent.
+ */
+export declare function decideWake(presence: PortPresence, daemonProjectId: string | undefined, callerProjectId: string | undefined): WakeAction;

package/dist/daemon/wake-decision.js

@@ -0,0 +1,38 @@
+/**
+ * What a woken MCP proxy may do with whatever is sitting on its port.
+ *
+ * Pulled out as a pure function because the wake path lives inside a long side-effecting closure in
+ * `mcp-command.ts`, and the decision it was getting wrong is three lines of reasoning that deserve a
+ * test of their own.
+ *
+ * `resolveMcpPort` asks the identity question at BOOT and relocates rather than adopting a stranger.
+ * The wake path asked only whether a daemon answered, so after an idle exit freed the port and
+ * another project's daemon bound it, a dormant proxy could reattach to a daemon that was not its
+ * own — and then serve an agent verdicts about a different application. `adoptable` is the same rule
+ * boot uses; this is just the wake path finally asking it.
+ */
+import { PortPresence } from './port-presence.js';
+import { adoptable } from './daemon-resolve.js';
+export const WakeAction = {
+    /** A daemon we may use is already here. */
+    USE: 'use',
+    /** Nothing is listening: start one. */
+    SPAWN: 'spawn',
+    /** Somebody else's. Go dormant with a reason rather than pretend the wake succeeded. */
+    REFUSE: 'refuse',
+};
+/**
+ * Identity is asked only of a port that actually holds a daemon.
+ *
+ * A FREE port must stay spawnable whatever the registry says about it, because a stale entry is the
+ * registry's ordinary state for the moment after any daemon exits — and refusing there would turn
+ * every idle retirement into a permanent lockout, which is the failure this whole path exists to
+ * prevent.
+ */
+export function decideWake(presence, daemonProjectId, callerProjectId) {
+    if (PortPresence.FREE === presence)
+        return WakeAction.SPAWN;
+    if (PortPresence.DAEMON !== presence)
+        return WakeAction.REFUSE;
+    return adoptable(daemonProjectId, callerProjectId) ? WakeAction.USE : WakeAction.REFUSE;
+}

package/dist/domain/domain-tools.js

@@ -2,6 +2,7 @@ import { z } from 'zod';
 import { sessionRoot } from '../project/session-root.js';
 import { asNumber, asString } from '../tools/tools-helpers.js';
 import { ReticleTool } from '../tools/tool-names.js';
+import { countSchema } from '../tools/numeric-bounds.js';
 import { readContract } from '../project/reticle-dir.js';
 import { buildDomainModel } from './domain-model.js';
 import { proposeInstrumentation } from '../oracles/self-instrument.js';
@@ -19,8 +20,7 @@ export const DOMAIN_TOOLS = [
         name: ReticleTool.DOMAIN,
         description: 'Read the app domain model BEFORE testing: every saved flow with its assertion grade, the consequence that MUST hold for it (mustHold = what it actually tests), the anchors/signals it exercises, plus GAPS — declared signals/testids that NO flow asserts (untested intent), and flows that assert no observable consequence. Use this to decide what to test and where the real risk is, instead of crawling the whole app. Reads .reticle/flows/ + .reticle/contract.json (no browser needed).',
         inputSchema: {
-            limit: z
-                .number()
+            limit: countSchema
                 .optional()
                 .describe('Most-recent N flows to detail. Defaults to 25 — the per-flow list grows with every saved flow (measured at ~11KB / ~2,700 tokens at 22 flows) and a large project would spend most of an agent context on flows it is not asking about. `flowCount` is always the true total, and the gaps/coverage summary is computed over ALL flows regardless, so capping the detail never changes the analysis.'),
         },

package/dist/events/contradictions.d.ts

@@ -138,6 +138,24 @@ export interface ContradictionOptions {
      * treats absence as current on both sides.
      */
     currentEditEpoch?: number | undefined;
+    /**
+     * The page under test, as the session last recorded it — the app's own origin, in URL form.
+     *
+     * The first-party/third-party axis. Every rule below asks "did the app disagree with itself", and
+     * a failed analytics beacon is not the app: reported independently from several apps, any
+     * analytics package installed was enough to grade a correct drive `contradicted`, and on one app
+     * EVERY assertion came back that way forever, because it fires a branding call on page load. A
+     * verdict field that answers "no" to everything has stopped being a verdict field.
+     *
+     * Third-party traffic is dropped here rather than reported at a lower severity, for the reason the
+     * dev-tooling split is: the rules below would each have to learn to say it. The exclusion is never
+     * silent — the URLs ride out in the same disclosure line the toolchain's do — and the calls
+     * themselves are untouched in `reticle_network` and the event timeline.
+     *
+     * Undefined disables the axis, exactly as an undefined `currentDocumentId` disables the document
+     * one: a caller that cannot say which page is under test gets the behaviour it had before this.
+     */
+    appOrigin?: string | undefined;
 }
 /**
  * Cross-channel contradictions in this window, with the edit-epoch caveat attached when it applies.