@reticlehq/server 3.2.0 → 3.3.0

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

@@ -23,7 +23,7 @@ export { AGENT_FLAG, BUG_FLAG, FEEDBACK_KINDS, KIND_FLAG, RATING_FLAG, } from '.
 export const CLI_USAGE = `usage:  npx @reticlehq/server <command>   (or \`reticle <command>\` once the bin is on your PATH)
 
   reticle init  [--dry-run] [--port N] [--no-mcp] [--no-install] [--app <dir>]
-                [--env KEY=VALUE]... [--files-only]  (wire Reticle into the project in this directory)
+                [--env KEY=VALUE]... [--files-only] [--hooks]  (wire Reticle into the project in this directory)
                 init is ONBOARDING: it wires the project, boots the app and proves a session
                 connected. It does not drive. The FIRST RUN is the stage that proves a flow:
                 reticle verify <url> --explore --persona "<who does what>", or the same thing
@@ -56,12 +56,18 @@ export const CLI_USAGE = `usage:  npx @reticlehq/server <command>   (or \`reticl
   reticle verify <url> [--port N] [--headed] [--timeout N] [--storage-state <file>] [--session-id <id>]  (one-shot: drive the URL, verify saved flows, exit 0=pass)
                        [--explore] [--persona <who>]   (no saved flows? let Reticle drive the app itself and record them)
                        [--select <label>]              (repeatable: verify only flows carrying these labels — no model, exit 0=pass)
-                [--expect '<json predicate>']            (one verdict, no saved flows needed — asks
-                the daemon that is already running, so nothing is bound and nothing is stopped. This
-                is the path when your client never loaded the reticle_* tools. exit 0 ONLY on
-                verified:"yes" — "unknown" is not a pass)
+                [--expect '<json predicate>' | --expect-file <path>]   (one verdict, no saved
+                flows needed. --expect-file is the form no shell can mangle: cmd.exe keeps the
+                single quotes the docs show, and PowerShell strips the inner double quotes, and
+                a predicate that does not parse produces no verdict at all — asks the daemon that
+                is already running, so nothing is bound and nothing is stopped. It NEEDS that
+                daemon: with none on the port it refuses and names the flag, rather than reporting
+                on your saved flows instead. Cannot be combined with --storage-state, which this
+                path has nowhere to load. This is the path when your client never loaded the
+                reticle_* tools. exit 0 ONLY on verified:"yes" — "unknown" is not a pass)
   reticle affected [--since <ref>] [file...]           (which saved flows must re-verify for the changed files)
   reticle gate [--since <ref>] [file...]               (exit non-zero unless passing artifacts cover the affected flows)
+  reticle report [--session <id>] [--hook]             (what the latest session claimed, and what held)
   reticle watch [url]                                  (on save, report which saved flows must re-verify)
   reticle drive <url> [--headless]                     (foreground mode, for debugging)
   reticle mcp   [--port N] [--drive <url>] [--headless] (MCP stdio proxy; auto-starts daemon if needed)
@@ -102,6 +108,9 @@ const CAPSULES_COMMAND = 'capsules';
 const GATE_COMMAND = 'gate';
 /** Hook mode: prose a human can read, and silence when there was simply nothing to check. */
 const HOOK_FLAG = '--hook';
+/** `reticle report [--session <id>] [--hook]` — what the latest session claimed, and what held. */
+const REPORT_COMMAND = 'report';
+const SESSION_FLAG = '--session';
 const WATCH_COMMAND = 'watch';
 const UPDATE_COMMAND = 'update';
 const ROLLBACK_COMMAND = 'rollback';
@@ -146,6 +155,7 @@ const KNOWN_COMMANDS = new Set([
     HUNT_COMMAND,
     CAPSULES_COMMAND,
     GATE_COMMAND,
+    REPORT_COMMAND,
     WATCH_COMMAND,
     UPDATE_COMMAND,
     ROLLBACK_COMMAND,
@@ -228,6 +238,8 @@ const FILES_ONLY_FLAG = '--files-only';
  * and `init` runs unattended. Whoever passes this has decided; nothing decides it for them.
  */
 const CAPTURE_BODIES_FLAG = '--capture-bodies';
+/** `--hooks`: also install the print-only Claude Code Stop hook (`reticle report --hook`). */
+const HOOKS_FLAG = '--hooks';
 /**
  * The rest of the runtime surface.
  *
@@ -410,6 +422,7 @@ function parseInitFlags(args) {
     const env = [];
     let filesOnly = false;
     let captureBodies = false;
+    let hooks = false;
     let json = false;
     let open = true;
     let relaunch = false;
@@ -457,6 +470,9 @@ function parseInitFlags(args) {
         else if (arg === CAPTURE_BODIES_FLAG) {
             captureBodies = true;
         }
+        else if (arg === HOOKS_FLAG) {
+            hooks = true;
+        }
         else if (arg === JSON_FLAG) {
             json = true;
         }
@@ -520,6 +536,7 @@ function parseInitFlags(args) {
         env,
         filesOnly,
         captureBodies,
+        hooks,
         json,
         open,
         relaunch,
@@ -606,6 +623,7 @@ export function parseCliArgs(argv, defaultPort, defaultHeadless = false) {
                 env: r.env,
                 filesOnly: r.filesOnly,
                 captureBodies: r.captureBodies,
+                hooks: r.hooks,
                 json: r.json,
                 open: r.open,
                 relaunch: r.relaunch,
@@ -772,6 +790,7 @@ export function parseCliArgs(argv, defaultPort, defaultHeadless = false) {
                 ...(r.storageState !== undefined ? { storageState: r.storageState } : {}),
                 ...(r.sessionId !== undefined ? { sessionId: r.sessionId } : {}),
                 ...(r.expect !== undefined ? { expect: r.expect } : {}),
+                ...(r.expectFile !== undefined ? { expectFile: r.expectFile } : {}),
                 ...(true === r.explore ? { explore: true } : {}),
                 ...(r.persona !== undefined ? { persona: r.persona } : {}),
                 ...(r.select !== undefined ? { select: r.select } : {}),
@@ -802,6 +821,15 @@ export function parseCliArgs(argv, defaultPort, defaultHeadless = false) {
                 ...(hook ? { hook: true } : {}),
             };
         }
+        case REPORT_COMMAND: {
+            const at = rest.indexOf(SESSION_FLAG);
+            const session = -1 === at ? undefined : rest[at + 1];
+            return {
+                kind: 'report',
+                hook: rest.includes(HOOK_FLAG),
+                ...(session === undefined ? {} : { session }),
+            };
+        }
         case WATCH_COMMAND: {
             // `reticle watch [url]` — on file save, report which saved flows must re-verify.
             const url = rest.find((arg) => !arg.startsWith('-'));

package/dist/command/cli/cli-verify.d.ts

@@ -11,6 +11,7 @@
  */
 import { type ReticleVerificationRun } from '@reticlehq/core';
 import { type RunningServer } from '../../index.js';
+import { PortPresence } from '../daemon/binding/port-presence.js';
 import { type VerifyProgressListener } from '../../judgement/runs/reticle-runner.js';
 import type { ToolDeps } from '../../surface/tools/tool-kit.js';
 /** The live capabilities runVerify needs — faked in tests so the logic runs without a browser. */
@@ -104,10 +105,68 @@ export declare function urlParts(url: string): {
  * first bullet — not this change.
  */
 export declare function portBusyMessage(port: number): string;
+/**
+ * What `--expect` is answered with when the port is not serving a daemon.
+ *
+ * It used to be answered with nothing at all. The predicate was read only inside the daemon branch,
+ * so on a free or foreign port the flag was dropped without a word and the command carried on into
+ * the saved-flows path — where it reported, accurately and about something else entirely, that there
+ * were no saved flows to verify. Byte-identical output to the same command with no `--expect` on it.
+ *
+ * That is the documented recovery for a client that never loaded the `reticle_*` tools, so it failed
+ * for the people with no other route to a verdict, and it failed in the one way they could not
+ * diagnose: the refusal they got was true.
+ */
+export declare function expectNeedsDaemonMessage(port: number, presence: PortPresence): string;
+/** What `verify` does next, once the options and the state of the port are both known. */
+export declare const VerifyRoute: {
+    /** Ask the daemon that already owns the port for a one-shot verdict on the predicate. */
+    readonly ADHOC: "adhoc";
+    /** Ask the daemon that already owns the port to replay the saved flows. See runAdhocSuite. */
+    readonly ADHOC_SUITE: "adhoc-suite";
+    /** Boot our own daemon, drive the url, replay the flows saved on disk. */
+    readonly FLOWS: "flows";
+    /** Answer the caller, and run nothing. */
+    readonly REFUSE: "refuse";
+};
+export type VerifyRoute = (typeof VerifyRoute)[keyof typeof VerifyRoute];
+export type VerifyPlan = {
+    route: typeof VerifyRoute.ADHOC;
+} | {
+    route: typeof VerifyRoute.ADHOC_SUITE;
+} | {
+    route: typeof VerifyRoute.FLOWS;
+} | {
+    route: typeof VerifyRoute.REFUSE;
+    message: string;
+};
+/**
+ * All four routes this command has, in one pure function.
+ *
+ * They used to be a pair of nested `if`s that consulted `--expect` only after the port had already
+ * answered as a daemon, which is how one of the four went missing: a predicate on any other port
+ * state fell through to a path that cannot see it. Stating the cases together is what makes an
+ * unhandled one visible, and it lets every one of them be driven with no port, no daemon and no
+ * browser — which is where an argument-level decision belongs.
+ */
+export declare function routeVerify(args: {
+    /** True when the caller supplied a predicate, by `--expect` or `--expect-file`. */
+    hasPredicate: boolean;
+    /**
+     * True when the caller asked for something only a browser of OUR OWN can do: `--explore` (a model
+     * driving a fresh page), `--headed`, or `--storage-state`. The running daemon's tab can honour
+     * none of them, so replaying there would silently ignore the request.
+     */
+    wantsOwnBrowser?: boolean;
+    presence: PortPresence;
+    port: number;
+}): VerifyPlan;
 export declare function handleVerify(parsed: {
     url: string;
     /** A parsed predicate for a flow-free, one-shot verdict against the running daemon. */
     expect?: unknown;
+    /** The same predicate in a file, which is the form no shell can mangle. Resolved below. */
+    expectFile?: string;
     headless: boolean;
     timeoutMs?: number;
     storageState?: string;

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

@@ -10,14 +10,17 @@
  * — is unit-tested without launching a real browser.
  */
 import { join, basename } from 'node:path';
+import { readFileSync } from 'node:fs';
 import { runAdhocVerdict } from './adhoc-verdict.js';
+import { runAdhocSuite } from './adhoc-suite.js';
 import { exploreApp, harnessAvailable, MSG_NO_HARNESS_KEY, } from '../../surface/tools/harness-explore.js';
 import { resolveSuiteSelection } from '../../language/flows/suite-selection.js';
 import { readOrCreatePairingTokenSync, defaultPairingTokenDir, } from '../../portal/bridge/pairing-token.js';
 import { randomUUID } from 'node:crypto';
 import { RETICLE_DEFAULT_PORT, ReticleEnv, bridgeWsUrl, isLoopbackHostname, ReticleDir, RunAgentKind, RunFramework, RunProfile, RunTrigger, VerdictStatus, VerifyPhase, } from '@reticlehq/core';
 import { start } from '../../index.js';
-import { probePresence, PortPresence } from '../daemon/binding/port-presence.js';
+import { probePresence, describePresence, PortPresence, } from '../daemon/binding/port-presence.js';
+import { EXPECT_FLAG } from './cli-parse-grammar.js';
 import { probeDaemon } from '../../surface/mcp/mcp-proxy.js';
 import { fetchStatus } from '../daemon/binding/daemon-status-probe.js';
 import { cloudFetch, createProgressReporter, resolveCloudConfig, syncProgressToCloud, syncRunToCloud, SyncOutcome, } from '../../memory/cloud/cloud-sync.js';
@@ -365,8 +368,92 @@ export function portBusyMessage(port) {
         "your agent's MCP link and the proxy usually respawns a daemon into the gap before verify can " +
         'bind — prefer one of the above.');
 }
+/**
+ * What `--expect` is answered with when the port is not serving a daemon.
+ *
+ * It used to be answered with nothing at all. The predicate was read only inside the daemon branch,
+ * so on a free or foreign port the flag was dropped without a word and the command carried on into
+ * the saved-flows path — where it reported, accurately and about something else entirely, that there
+ * were no saved flows to verify. Byte-identical output to the same command with no `--expect` on it.
+ *
+ * That is the documented recovery for a client that never loaded the `reticle_*` tools, so it failed
+ * for the people with no other route to a verdict, and it failed in the one way they could not
+ * diagnose: the refusal they got was true.
+ */
+export function expectNeedsDaemonMessage(port, presence) {
+    return (`${EXPECT_FLAG} asks the Reticle daemon that already owns port ${String(port)} for the ` +
+        'verdict — it binds nothing and launches nothing, which is what lets it answer while the port ' +
+        `is busy. Right now ${describePresence(presence, port)}.\n\n` +
+        '  The predicate did not run, and nothing was proved.\n\n' +
+        '  • Start a daemon on that port, pointed at the app, then re-run this command: ' +
+        `npx @reticlehq/server serve --port ${String(port)} --drive <url>\n` +
+        `  • Or drop ${EXPECT_FLAG}, and verify drives the url itself and replays your saved flows — ` +
+        'a different question, and it proves nothing about your predicate.');
+}
+/** What `verify` does next, once the options and the state of the port are both known. */
+export const VerifyRoute = {
+    /** Ask the daemon that already owns the port for a one-shot verdict on the predicate. */
+    ADHOC: 'adhoc',
+    /** Ask the daemon that already owns the port to replay the saved flows. See runAdhocSuite. */
+    ADHOC_SUITE: 'adhoc-suite',
+    /** Boot our own daemon, drive the url, replay the flows saved on disk. */
+    FLOWS: 'flows',
+    /** Answer the caller, and run nothing. */
+    REFUSE: 'refuse',
+};
+/**
+ * All four routes this command has, in one pure function.
+ *
+ * They used to be a pair of nested `if`s that consulted `--expect` only after the port had already
+ * answered as a daemon, which is how one of the four went missing: a predicate on any other port
+ * state fell through to a path that cannot see it. Stating the cases together is what makes an
+ * unhandled one visible, and it lets every one of them be driven with no port, no daemon and no
+ * browser — which is where an argument-level decision belongs.
+ */
+export function routeVerify(args) {
+    if (args.hasPredicate) {
+        return args.presence === PortPresence.DAEMON
+            ? { route: VerifyRoute.ADHOC }
+            : { route: VerifyRoute.REFUSE, message: expectNeedsDaemonMessage(args.port, args.presence) };
+    }
+    if (args.presence !== PortPresence.DAEMON)
+        return { route: VerifyRoute.FLOWS };
+    // No predicate, but there may be SAVED FLOWS, and a daemon already owns the port: replay them
+    // there rather than refusing, unless the request needs a browser that path never opens.
+    return true === args.wantsOwnBrowser
+        ? { route: VerifyRoute.REFUSE, message: portBusyMessage(args.port) }
+        : { route: VerifyRoute.ADHOC_SUITE };
+}
 export function handleVerify(parsed) {
     const now = () => Date.now();
+    /*
+     * `--expect-file` is `--expect` with the shell taken out of the loop.
+     *
+     * Resolved here rather than in the parser because the parser is pure and reads no disk, and
+     * because the two failures a reader can hit — the file is not there, and what is in it is not
+     * JSON — are worth saying apart. Either one ends the run before anything binds: a predicate that
+     * could not be read produces NO verdict, and exiting 1 with the reason is the only honest answer.
+     */
+    let expectation = parsed.expect;
+    if (parsed.expectFile !== undefined) {
+        let text;
+        try {
+            text = readFileSync(parsed.expectFile, 'utf8');
+        }
+        catch {
+            process.stderr.write(`--expect-file: cannot read ${parsed.expectFile}\n`);
+            process.exit(1);
+            return;
+        }
+        try {
+            expectation = JSON.parse(text);
+        }
+        catch {
+            process.stderr.write(`--expect-file: ${parsed.expectFile} is not valid JSON, so no predicate was read\n`);
+            process.exit(1);
+            return;
+        }
+    }
     const reticleRoot = join(process.cwd(), ReticleDir.ROOT);
     const projectName = basename(process.cwd()) || DEFAULT_PROJECT_NAME;
     const ports = {
@@ -389,20 +476,32 @@ export function handleVerify(parsed) {
     // this used to reach the user as a raw node stack rather than as an answer.
     void (async () => {
         const port = parsed.port ?? RETICLE_DEFAULT_PORT;
-        if ((await probePresence(port, { tcpOpen: probeDaemon, status: fetchStatus })) ===
-            PortPresence.DAEMON) {
+        const presence = await probePresence(port, { tcpOpen: probeDaemon, status: fetchStatus });
+        const plan = routeVerify({
+            hasPredicate: expectation !== undefined,
+            wantsOwnBrowser: true === parsed.explore || !parsed.headless || parsed.storageState !== undefined,
+            presence,
+            port,
+        });
+        switch (plan.route) {
+            // Either the busy port, or a predicate this state cannot answer. Both are refusals that name
+            // what was asked for — never a report about a check nobody requested.
+            case VerifyRoute.REFUSE:
+                ports.fail(plan.message);
+                ports.exit(EXIT_FAIL);
+                return;
             // A daemon owning the port is the NORMAL state after a working install, and it used to be the
             // end of the road: `verify` refused, the other verdict paths need saved flows a first-install
             // project does not have, and stopping the daemon cuts the agent's own MCP link. An agent could
             // hold a live, correctly-wired app and have no way to reach a verdict at all.
             //
-            // With `--expect` there is now a way, and it does not need the port: ask the daemon that
-            // already owns it. See runAdhocVerdict.
-            if (parsed.expect !== undefined) {
+            // With `--expect` there is a way, and it does not need the port: ask the daemon that already
+            // owns it. See runAdhocVerdict.
+            case VerifyRoute.ADHOC: {
                 const verdict = await runAdhocVerdict({
                     port,
                     ...(parsed.url !== undefined && '' !== parsed.url ? { url: parsed.url } : {}),
-                    predicate: parsed.expect,
+                    predicate: expectation,
                     ...(parsed.sessionId === undefined ? {} : { sessionId: parsed.sessionId }),
                     ...((t) => (t === undefined || 0 === t.length ? {} : { token: t }))(readOrCreatePairingTokenSync(defaultPairingTokenDir())),
                 });
@@ -411,16 +510,29 @@ export function handleVerify(parsed) {
                 ports.exit(verdict.code);
                 return;
             }
-            ports.fail(portBusyMessage(port));
-            ports.exit(1);
-            return;
+            // No predicate, a daemon on the port, and saved flows to run: the other half of the same
+            // dead end. The whole promise of a saved suite is that it runs again without an agent.
+            case VerifyRoute.ADHOC_SUITE: {
+                const suite = await runAdhocSuite({
+                    port,
+                    ...(parsed.select === undefined ? {} : { select: parsed.select }),
+                    ...(parsed.sessionId === undefined ? {} : { sessionId: parsed.sessionId }),
+                    ...((t) => (t === undefined || 0 === t.length ? {} : { token: t }))(readOrCreatePairingTokenSync(defaultPairingTokenDir())),
+                });
+                for (const line of suite.lines)
+                    ports.out(line);
+                ports.exit(suite.code);
+                return;
+            }
+            case VerifyRoute.FLOWS:
+                await runVerify({
+                    url: parsed.url,
+                    timeoutMs: parsed.timeoutMs ?? DEFAULT_SESSION_TIMEOUT_MS,
+                    ...(true === parsed.explore ? { explore: true } : {}),
+                    ...(parsed.persona === undefined ? {} : { persona: parsed.persona }),
+                    ...(parsed.select === undefined ? {} : { select: parsed.select }),
+                }, ports);
+                return;
         }
-        await runVerify({
-            url: parsed.url,
-            timeoutMs: parsed.timeoutMs ?? DEFAULT_SESSION_TIMEOUT_MS,
-            ...(true === parsed.explore ? { explore: true } : {}),
-            ...(parsed.persona === undefined ? {} : { persona: parsed.persona }),
-            ...(parsed.select === undefined ? {} : { select: parsed.select }),
-        }, ports);
     })();
 }

package/dist/command/cli/cloud-kit.d.ts

@@ -1,6 +1,4 @@
 import { type Session } from './auth/cloud-session.js';
-/** Where `reticle login` dials when nothing says otherwise: the hosted service. */
-export declare const DEFAULT_URL = "https://app.reticle.sh";
 export declare const RETICLE_DIR = ".reticle";
 export declare const SESSION_FILE = "session.json";
 export declare const CREDENTIALS_FILE = "credentials.json";

package/dist/command/cli/cloud-kit.js

@@ -16,7 +16,7 @@ import { z } from 'zod';
 import { cloudFetch } from '../../memory/cloud/cloud-sync.js';
 import { normalizeUrl, readSessionFrom, resolveSessionFor, sessionPath, } from './auth/cloud-session.js';
 /** Where `reticle login` dials when nothing says otherwise: the hosted service. */
-export const DEFAULT_URL = 'https://app.reticle.sh';
+const DEFAULT_URL = 'https://app.reticle.sh';
 export const RETICLE_DIR = '.reticle';
 export const SESSION_FILE = 'session.json';
 export const CREDENTIALS_FILE = 'credentials.json';

package/dist/command/cli/doctor/doctor-sessions-line.d.ts

@@ -1,5 +1,5 @@
 /** What this reads off `/status`. Everything is optional — an older daemon may send none of it. */
-export interface SessionFacts {
+interface SessionFacts {
     sessionCount?: unknown;
     why?: unknown;
 }
@@ -10,3 +10,4 @@ export interface SessionsLine {
     why?: string;
 }
 export declare function sessionsLine(facts: SessionFacts): SessionsLine;
+export {};

package/dist/command/cli/launch/cli-launch.d.ts

@@ -3,34 +3,7 @@
  * "show me the app" flow (`reticle open`). Split out of cli.ts so that file stays under the size cap.
  * The decision logic is pure (unit-tested); the IO (fetch, OS browser launch) is injected/isolated.
  */
-/** One connected tab as `reticle status` reports it — the at-a-glance health line. */
-interface StatusSession {
-    sessionId: string;
-    url: string;
-    throttled: boolean;
-    /**
-     * The tab is backgrounded. Reported by the daemon on every session; `false` on one too old to say,
-     * which reads as visible — the conservative answer, since it keeps the reuse this command has
-     * always done rather than opening a tab on a guess.
-     */
-    hidden: boolean;
-    stale: boolean;
-    pendingMarks: number;
-    /** The tab is attached and answering nothing — see Session.unresponsive. Absent on an older daemon. */
-    unresponsive?: true;
-}
-/**
- * Reduce the daemon's /status JSON to the compact view `reticle status` prints. Pure: narrows the
- * untrusted wire payload (never `any`) and tolerates a missing/partial body so a malformed response
- * degrades to "running, 0 sessions" instead of throwing.
- */
-export declare function summarizeStatus(payload: unknown): {
-    sessionCount: number;
-    sessions: StatusSession[];
-    why?: string;
-    /** The same diagnosis without the differential, for a surface a person reads. */
-    whyLead?: string;
-};
+export { summarizeStatus } from '../../daemon/binding/daemon-status-probe.js';
 /**
  * Warn when the daemon already on this port is a different version than this CLI, and attach anyway.
  *
@@ -97,4 +70,3 @@ export declare function openInBrowser(url: string, platform?: NodeJS.Platform, r
  * by spawning a real launcher on a developer machine.
  */
 export declare function launcherFailure(code: number | null, signal: NodeJS.Signals | null): string | null;
-export {};

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

@@ -7,47 +7,13 @@ import { SERVER_VERSION } from '../../version/identity/server-version.js';
 import { log } from '../../../log.js';
 import { fetchStatus } from '../../daemon/binding/daemon-status-probe.js';
 /**
- * Reduce the daemon's /status JSON to the compact view `reticle status` prints. Pure: narrows the
- * untrusted wire payload (never `any`) and tolerates a missing/partial body so a malformed response
- * degrades to "running, 0 sessions" instead of throwing.
+ * CLI launch + status helpers — the daemon-introspection (`reticle status`) and the one-command
+ * "show me the app" flow (`reticle open`). Split out of cli.ts so that file stays under the size cap.
+ * The decision logic is pure (unit-tested); the IO (fetch, OS browser launch) is injected/isolated.
  */
-export function summarizeStatus(payload) {
-    if (typeof payload !== 'object' || null === payload)
-        return { sessionCount: 0, sessions: [] };
-    const obj = payload;
-    // Carried through to the printed line: with no sessions this is the whole answer, and dropping it
-    // here would silently undo the reason it is on the wire.
-    const why = 'string' === typeof obj['why'] ? obj['why'] : undefined;
-    // Absent on a daemon older than this field, which is why every reader falls back to `why`.
-    const whyLead = 'string' === typeof obj['whyLead'] ? obj['whyLead'] : undefined;
-    const raw = Array.isArray(obj['sessions']) ? obj['sessions'] : [];
-    const sessions = raw
-        .map((s) => {
-        if (typeof s !== 'object' || null === s)
-            return null;
-        const r = s;
-        const sessionId = 'string' === typeof r['sessionId'] ? r['sessionId'] : '';
-        if ('' === sessionId)
-            return null;
-        return {
-            sessionId,
-            url: 'string' === typeof r['url'] ? r['url'] : '',
-            throttled: true === r['throttled'],
-            hidden: true === r['hidden'],
-            stale: true === r['stale'],
-            pendingMarks: 'number' === typeof r['pendingMarks'] ? r['pendingMarks'] : 0,
-            ...(true === r['unresponsive'] ? { unresponsive: true } : {}),
-        };
-    })
-        .filter((s) => s !== null);
-    const sessionCount = 'number' === typeof obj['sessionCount'] ? obj['sessionCount'] : sessions.length;
-    return {
-        sessionCount,
-        sessions,
-        ...(why === undefined ? {} : { why }),
-        ...(whyLead === undefined ? {} : { whyLead }),
-    };
-}
+// Parsing the daemon's /status payload lives beside the probe that fetches it; re-exported here for
+// the callers that already import it from this module.
+export { summarizeStatus } from '../../daemon/binding/daemon-status-probe.js';
 /** A string field off the /status body, or undefined on a daemon too old to report it. */
 function statusField(payload, key) {
     if (typeof payload !== 'object' || null === payload)

package/dist/command/cli/ports/resolve/cli-port.d.ts

@@ -41,6 +41,19 @@ export declare function readProjectPort(cwd: string): number | undefined;
  * undefined if the file is absent/unreadable or has no non-empty string projectId.
  */
 export declare function readProjectId(cwd: string): ProjectId | undefined;
+/**
+ * Every project id this directory can speak for, for "has THIS project ever connected".
+ *
+ * `readProjectId` knows only what `init` wrote. The build plugins derive the same id from the package
+ * name and the app root WITHOUT writing `.reticle.json`, so a monorepo root (the app lives in
+ * `apps/web`) and an app wired by the plugin alone both read `undefined`, and the handshake told a
+ * working project nothing had ever connected. Deriving the plugin's own id cannot reopen the opposite
+ * lie: an id only counts once an app with exactly that id has dialled in.
+ *
+ * Workspace discovery is init's `findWorkspaceApps`, reused so the two cannot disagree about which
+ * directories are apps. Best-effort: a directory it cannot read contributes nothing.
+ */
+export declare function projectIdsAt(cwd: string): ProjectId[];
 /**
  * The framework `reticle init` stamped into `.reticle.json`, when there is one.
  *

package/dist/command/cli/ports/resolve/cli-port.js

@@ -8,7 +8,8 @@
  * 4. RETICLE_DEFAULT_PORT (4400)
  */
 import { readFileSync } from 'node:fs';
-import { dirname, resolve } from 'node:path';
+import { dirname, join, resolve } from 'node:path';
+import { SILENT_HOST, buildNodeIo, deriveProjectId, findWorkspaceApps, packageName, } from '@reticlehq/init';
 import { asProjectId } from '@reticlehq/core';
 /** The project config `reticle init` writes. */
 export const RETICLE_CONFIG_BASENAME = '.reticle.json';
@@ -84,6 +85,49 @@ export function readProjectId(cwd) {
         return asProjectId(id);
     return undefined;
 }
+const PACKAGE_JSON = 'package.json';
+/** The package name in `dir/package.json`, or undefined when there is no readable one. */
+function packageNameAt(dir) {
+    try {
+        return packageName(JSON.parse(readFileSync(join(dir, PACKAGE_JSON), 'utf8')));
+    }
+    catch {
+        return undefined;
+    }
+}
+/** The id an app at `dir` carries: the one `init` recorded, else the one the build plugin derives. */
+function projectIdFor(dir) {
+    return readProjectId(dir) ?? asProjectId(deriveProjectId(packageNameAt(dir), dir));
+}
+/**
+ * Every project id this directory can speak for, for "has THIS project ever connected".
+ *
+ * `readProjectId` knows only what `init` wrote. The build plugins derive the same id from the package
+ * name and the app root WITHOUT writing `.reticle.json`, so a monorepo root (the app lives in
+ * `apps/web`) and an app wired by the plugin alone both read `undefined`, and the handshake told a
+ * working project nothing had ever connected. Deriving the plugin's own id cannot reopen the opposite
+ * lie: an id only counts once an app with exactly that id has dialled in.
+ *
+ * Workspace discovery is init's `findWorkspaceApps`, reused so the two cannot disagree about which
+ * directories are apps. Best-effort: a directory it cannot read contributes nothing.
+ */
+export function projectIdsAt(cwd) {
+    const recorded = readProjectId(cwd);
+    if (recorded !== undefined)
+        return [recorded];
+    const ids = [];
+    if (packageNameAt(cwd) !== undefined)
+        ids.push(projectIdFor(cwd));
+    try {
+        for (const app of findWorkspaceApps(buildNodeIo(cwd, SILENT_HOST))) {
+            ids.push(projectIdFor(join(cwd, app)));
+        }
+    }
+    catch {
+        // Discovery touches the filesystem; an unreadable tree is simply no further evidence.
+    }
+    return [...new Set(ids)];
+}
 /**
  * The framework `reticle init` stamped into `.reticle.json`, when there is one.
  *

package/dist/command/cli/report-command.d.ts

@@ -0,0 +1,16 @@
+export interface ReportInput {
+    cwd: string;
+    now: number;
+    /** Did the working tree change? The hook stays silent on a turn that edited nothing. */
+    treeChanged: boolean;
+    session?: string;
+    hook?: boolean;
+}
+export declare function reportFor(input: ReportInput): Promise<{
+    lines: string[];
+}>;
+/**
+ * The command. As a hook it prints Claude Code's `systemMessage` shape and always exits 0: it is
+ * print-only by design, so the human sees the gap and the agent is never blocked by it.
+ */
+export declare function handleReport(session: string | undefined, hook: boolean): Promise<void>;