@reticlehq/server 2.11.0 → 2.13.0

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

@@ -0,0 +1,122 @@
+/**
+ * Which daemon does THIS project belong to?
+ *
+ * The system answered that two incompatible ways. Build plugins asked the registry by projectId, the
+ * way `pickDaemonPort` was designed to be asked. The CLI and the MCP proxy asked a NUMBER —
+ * `envPort ?? projectPort ?? 4400` — and then attached to whatever owned it, whoever it belonged to.
+ *
+ * So every project on a machine funnelled into one daemon. Its recorded identity was whichever
+ * project won the race to the port, which made the registry entry wrong the moment a second project
+ * attached, and made one `kill` on one well-known port a machine-wide outage for every agent at once.
+ *
+ * It worked anyway, by luck: everyone defaulted to the same number, so everyone found each other.
+ * The luck ends the moment a daemon is anywhere but the default — which is exactly when discovery was
+ * supposed to help, and exactly when it returned nothing.
+ *
+ * This module is the one answer both sides now use. It is pure and injectable: no process spawning,
+ * no port binding, nothing that needs a real `~/.reticle` to test.
+ */
+import { type DaemonRegistryEntry } from '@reticlehq/core';
+/**
+ * Every well-formed registry entry in `home`.
+ *
+ * A corrupt or half-written entry is skipped rather than thrown on: the registry is written by other
+ * processes that can be killed mid-write, and one bad file must not make a machine's daemons
+ * undiscoverable. Validated through core's schema so a shape change cannot silently pass here.
+ */
+export declare function readDaemonRegistry(home: string): DaemonRegistryEntry[];
+/**
+ * The port of the live daemon serving `projectId`, or undefined when this project has none.
+ *
+ * Undefined means "start one", never "use the default and hope". That distinction is the fix: the old
+ * path had no way to express "no daemon of mine exists", so it fell through to a number and attached
+ * to a stranger.
+ *
+ * The selection rule is core's `pickDaemonPort`, shared with every build plugin, so the daemon side
+ * and the app side cannot disagree about which daemon is ours.
+ */
+export declare function resolveDaemonForProject(projectId: string | undefined, home: string, alive: (pid: number) => boolean): number | undefined;
+/**
+ * May `caller` take over a daemon already sitting on the port it wanted?
+ *
+ * Two deliberate escape hatches, both of which keep an existing install working:
+ *
+ * A daemon that claims NO project was started somewhere without a `.reticle.json` — the global MCP
+ * registration in a directory that is not an app, which is the majority of daemons in the field. It
+ * belongs to nobody, so it belongs to whoever asks; refusing would break every user running Reticle
+ * globally, which is how it is documented to be installed.
+ *
+ * A caller with no project of its own has no identity to defend and nothing to be confused about, so
+ * it keeps the old permissive behaviour rather than being locked out of a daemon it can use.
+ *
+ * Everything else — a named daemon and a differently-named caller — is the cross-project bleed, and
+ * is the one case this refuses.
+ */
+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.
+ *
+ * Resolved once rather than per reconnect because the proxy's transport is built around a fixed
+ * number, and making it chase a moving port would mean reworking the reconnect path — the one piece
+ * of this system whose failure mode is "the MCP server disappeared mid-session". The port it settles
+ * on is this project's own, so the thing it would be chasing is a daemon it alone is responsible for.
+ *
+ * The order is the whole fix:
+ *   1. our project's live daemon, wherever it is listening — a daemon that moved is still ours;
+ *   2. the preferred port, but only if free or holding a daemon we may adopt;
+ *   3. a port the OS gives us, when the preferred one belongs to somebody else.
+ *
+ * Step 3 is what stops a second project from attaching to the first project's daemon. That single
+ * silent adoption is what made every agent on a machine share one process, one identity and one
+ * blast radius.
+ */
+export declare function resolveMcpPort(preferred: number, projectId: string | undefined, home: string, deps: {
+    alive: (pid: number) => boolean;
+    daemonPresent: (port: number) => Promise<boolean>;
+    pickPort: (preferred: number) => Promise<number>;
+}): Promise<number>;

package/dist/daemon/daemon-resolve.js

@@ -0,0 +1,187 @@
+/**
+ * Which daemon does THIS project belong to?
+ *
+ * The system answered that two incompatible ways. Build plugins asked the registry by projectId, the
+ * way `pickDaemonPort` was designed to be asked. The CLI and the MCP proxy asked a NUMBER —
+ * `envPort ?? projectPort ?? 4400` — and then attached to whatever owned it, whoever it belonged to.
+ *
+ * So every project on a machine funnelled into one daemon. Its recorded identity was whichever
+ * project won the race to the port, which made the registry entry wrong the moment a second project
+ * attached, and made one `kill` on one well-known port a machine-wide outage for every agent at once.
+ *
+ * It worked anyway, by luck: everyone defaulted to the same number, so everyone found each other.
+ * The luck ends the moment a daemon is anywhere but the default — which is exactly when discovery was
+ * supposed to help, and exactly when it returned nothing.
+ *
+ * This module is the one answer both sides now use. It is pure and injectable: no process spawning,
+ * no port binding, nothing that needs a real `~/.reticle` to test.
+ */
+import { readdirSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { DaemonRegistryEntrySchema, daemonRegistryPort, pickDaemonPort, } from '@reticlehq/core';
+/**
+ * Every well-formed registry entry in `home`.
+ *
+ * A corrupt or half-written entry is skipped rather than thrown on: the registry is written by other
+ * processes that can be killed mid-write, and one bad file must not make a machine's daemons
+ * undiscoverable. Validated through core's schema so a shape change cannot silently pass here.
+ */
+export function readDaemonRegistry(home) {
+    let files;
+    try {
+        files = readdirSync(home);
+    }
+    catch {
+        return []; // no ~/.reticle yet: no daemon has ever run here
+    }
+    const entries = [];
+    for (const file of files) {
+        if (null === daemonRegistryPort(file))
+            continue;
+        try {
+            const parsed = DaemonRegistryEntrySchema.safeParse(JSON.parse(readFileSync(join(home, file), 'utf8')));
+            if (parsed.success)
+                entries.push(parsed.data);
+        }
+        catch {
+            continue;
+        }
+    }
+    return entries;
+}
+/**
+ * The port of the live daemon serving `projectId`, or undefined when this project has none.
+ *
+ * Undefined means "start one", never "use the default and hope". That distinction is the fix: the old
+ * path had no way to express "no daemon of mine exists", so it fell through to a number and attached
+ * to a stranger.
+ *
+ * The selection rule is core's `pickDaemonPort`, shared with every build plugin, so the daemon side
+ * and the app side cannot disagree about which daemon is ours.
+ */
+export function resolveDaemonForProject(projectId, home, alive) {
+    return pickDaemonPort(readDaemonRegistry(home), projectId, alive) ?? undefined;
+}
+/**
+ * May `caller` take over a daemon already sitting on the port it wanted?
+ *
+ * Two deliberate escape hatches, both of which keep an existing install working:
+ *
+ * A daemon that claims NO project was started somewhere without a `.reticle.json` — the global MCP
+ * registration in a directory that is not an app, which is the majority of daemons in the field. It
+ * belongs to nobody, so it belongs to whoever asks; refusing would break every user running Reticle
+ * globally, which is how it is documented to be installed.
+ *
+ * A caller with no project of its own has no identity to defend and nothing to be confused about, so
+ * it keeps the old permissive behaviour rather than being locked out of a daemon it can use.
+ *
+ * Everything else — a named daemon and a differently-named caller — is the cross-project bleed, and
+ * is the one case this refuses.
+ */
+export function adoptable(daemonProjectId, callerProjectId) {
+    if (daemonProjectId === undefined || 0 === daemonProjectId.length)
+        return true;
+    if (callerProjectId === undefined || 0 === callerProjectId.length)
+        return true;
+    return daemonProjectId === callerProjectId;
+}
+/** The project a daemon on `port` claims, or undefined when it claims none / is not registered. */
+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.
+ *
+ * Resolved once rather than per reconnect because the proxy's transport is built around a fixed
+ * number, and making it chase a moving port would mean reworking the reconnect path — the one piece
+ * of this system whose failure mode is "the MCP server disappeared mid-session". The port it settles
+ * on is this project's own, so the thing it would be chasing is a daemon it alone is responsible for.
+ *
+ * The order is the whole fix:
+ *   1. our project's live daemon, wherever it is listening — a daemon that moved is still ours;
+ *   2. the preferred port, but only if free or holding a daemon we may adopt;
+ *   3. a port the OS gives us, when the preferred one belongs to somebody else.
+ *
+ * Step 3 is what stops a second project from attaching to the first project's daemon. That single
+ * silent adoption is what made every agent on a machine share one process, one identity and one
+ * blast radius.
+ */
+export async function resolveMcpPort(preferred, projectId, home, deps) {
+    const mine = resolveDaemonForProject(projectId, home, deps.alive);
+    if (mine !== undefined)
+        return mine;
+    if (!(await deps.daemonPresent(preferred)))
+        return preferred;
+    return adoptable(daemonProjectAt(preferred, home), projectId)
+        ? preferred
+        : deps.pickPort(preferred);
+}

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/free-port.d.ts

@@ -0,0 +1,29 @@
+/**
+ * A port this machine will actually let us bind.
+ *
+ * Once daemons are per-project, "which port" stops being a constant and becomes a question. The
+ * answer must not be "the next number up": probing 4401, 4402, 4403 races every other agent doing
+ * the same arithmetic at the same moment, and the loser finds out at bind time, which is after it has
+ * already told the caller which port to use.
+ *
+ * So the OS assigns it. Binding port 0 asks the kernel for a free one and hands back the number it
+ * chose, and nothing else can be holding it at that instant. There is still a window between closing
+ * the probe socket and the daemon binding for real — unavoidable without passing the listener itself
+ * to the child — but it is microseconds wide and loses to a retry, where a guessed number loses every
+ * time on a busy machine.
+ *
+ * The preferred port is tried first so the ordinary single-project install keeps landing on the
+ * documented default, and every doc, log line and troubleshooting page that says 4400 stays true.
+ */
+/** Can we bind `port` on the loopback interface right now? */
+export declare function portIsFree(port: number, host?: string): Promise<boolean>;
+/** Ask the kernel for a free port. Rejects only if the machine cannot bind loopback at all. */
+export declare function osAssignedPort(host?: string): Promise<number>;
+/**
+ * `preferred` when it is free, otherwise whatever the OS gives us.
+ *
+ * Injectable so the decision is unit-testable without binding anything: the interesting case is the
+ * one where the preferred port is taken, and a test must be able to say so without racing a real
+ * socket.
+ */
+export declare function pickDaemonPortToBind(preferred: number, isFree?: (port: number) => Promise<boolean>, assign?: () => Promise<number>): Promise<number>;

package/dist/daemon/free-port.js

@@ -0,0 +1,55 @@
+/**
+ * A port this machine will actually let us bind.
+ *
+ * Once daemons are per-project, "which port" stops being a constant and becomes a question. The
+ * answer must not be "the next number up": probing 4401, 4402, 4403 races every other agent doing
+ * the same arithmetic at the same moment, and the loser finds out at bind time, which is after it has
+ * already told the caller which port to use.
+ *
+ * So the OS assigns it. Binding port 0 asks the kernel for a free one and hands back the number it
+ * chose, and nothing else can be holding it at that instant. There is still a window between closing
+ * the probe socket and the daemon binding for real — unavoidable without passing the listener itself
+ * to the child — but it is microseconds wide and loses to a retry, where a guessed number loses every
+ * time on a busy machine.
+ *
+ * The preferred port is tried first so the ordinary single-project install keeps landing on the
+ * documented default, and every doc, log line and troubleshooting page that says 4400 stays true.
+ */
+import { createServer } from 'node:net';
+import { LOOPBACK_HOST } from '@reticlehq/core';
+/** Can we bind `port` on the loopback interface right now? */
+export function portIsFree(port, host = LOOPBACK_HOST) {
+    return new Promise((resolve) => {
+        const probe = createServer();
+        probe.once('error', () => resolve(false));
+        probe.listen(port, host, () => {
+            probe.close(() => resolve(true));
+        });
+    });
+}
+/** Ask the kernel for a free port. Rejects only if the machine cannot bind loopback at all. */
+export function osAssignedPort(host = LOOPBACK_HOST) {
+    return new Promise((resolve, reject) => {
+        const probe = createServer();
+        probe.once('error', reject);
+        probe.listen(0, host, () => {
+            const address = probe.address();
+            if (null === address || 'string' === typeof address) {
+                probe.close(() => reject(new Error('could not read an OS-assigned port')));
+                return;
+            }
+            const { port } = address;
+            probe.close(() => resolve(port));
+        });
+    });
+}
+/**
+ * `preferred` when it is free, otherwise whatever the OS gives us.
+ *
+ * Injectable so the decision is unit-testable without binding anything: the interesting case is the
+ * one where the preferred port is taken, and a test must be able to say so without racing a real
+ * socket.
+ */
+export async function pickDaemonPortToBind(preferred, isFree = portIsFree, assign = osAssignedPort) {
+    return (await isFree(preferred)) ? preferred : assign();
+}

package/dist/daemon/heartbeat.d.ts

@@ -19,10 +19,6 @@
  */
 /** The event name a beat carries. One `grep` separates liveness from everything else in the file. */
 export declare const DAEMON_HEARTBEAT_EVENT = "reticle_daemon_alive";
-/** Written by installExitTrace when the process exits through Node. */
-export declare const DAEMON_EXIT_EVENT = "reticle_daemon_exiting";
-/** Written by installExitTrace when a signal arrives, which is a CAUSE the exit line does not carry. */
-export declare const DAEMON_SIGNAL_EVENT = "reticle_daemon_signalled";
 /**
  * How often a live daemon says so.
  *

package/dist/daemon/heartbeat.js

@@ -20,9 +20,9 @@
 /** The event name a beat carries. One `grep` separates liveness from everything else in the file. */
 export const DAEMON_HEARTBEAT_EVENT = 'reticle_daemon_alive';
 /** Written by installExitTrace when the process exits through Node. */
-export const DAEMON_EXIT_EVENT = 'reticle_daemon_exiting';
+const DAEMON_EXIT_EVENT = 'reticle_daemon_exiting';
 /** Written by installExitTrace when a signal arrives, which is a CAUSE the exit line does not carry. */
-export const DAEMON_SIGNAL_EVENT = 'reticle_daemon_signalled';
+const DAEMON_SIGNAL_EVENT = 'reticle_daemon_signalled';
 /**
  * How often a live daemon says so.
  *

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/dev/stale-issue-guard.d.ts

@@ -27,8 +27,6 @@ export interface IssueState {
     state: 'open' | 'closed';
     labels: readonly string[];
 }
-/** The label that means "fixed, waiting for a release" — an honest reason to still be open. */
-export declare const PENDING_RELEASE_LABEL = "fixed-pending-release";
 export declare function closedRefsIn(commitMessage: string): number[];
 /**
  * Of the issues these commits claimed to close, the ones still reading as available work.

package/dist/dev/stale-issue-guard.js

@@ -23,7 +23,7 @@
  * below testable without a network or a repo.
  */
 /** The label that means "fixed, waiting for a release" — an honest reason to still be open. */
-export const PENDING_RELEASE_LABEL = 'fixed-pending-release';
+const PENDING_RELEASE_LABEL = 'fixed-pending-release';
 /**
  * Issue numbers a commit message CLAIMS to have closed.
  *

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.'),
         },