@reticlehq/server 3.1.0 → 3.3.0

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

@@ -7,6 +7,7 @@
  * 3..reticle.json "port" field in the cwd ← per-project isolation
  * 4. RETICLE_DEFAULT_PORT (4400)
  */
+import { type ProjectId } from '@reticlehq/core';
 /** The project config `reticle init` writes. */
 export declare const RETICLE_CONFIG_BASENAME = ".reticle.json";
 /**
@@ -39,7 +40,20 @@ export declare function readProjectPort(cwd: string): number | undefined;
  * uses it as the default resolve scope so auto-selection stays within the active app. Returns
  * undefined if the file is absent/unreadable or has no non-empty string projectId.
  */
-export declare function readProjectId(cwd: string): string | undefined;
+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,9 @@
  * 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';
 /**
@@ -76,10 +78,56 @@ export function readProjectPort(cwd) {
  */
 export function readProjectId(cwd) {
     const id = findProjectConfig(cwd)?.['projectId'];
+    // MINTED HERE. The other provenance boundary: the `projectId` key of a project's own
+    // `.reticle.json`. Like HELLO's field, it is a project's id because of WHERE it was read, not
+    // because of what it looks like.
     if ('string' === typeof id && id.length > 0)
-        return id;
+        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>;

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

@@ -0,0 +1,97 @@
+/**
+ * `reticle report [--session <id>] [--hook]` — what this project's latest session claimed, and what held.
+ *
+ * Read from disk, with no daemon: the journal is on disk, and a Stop hook has to answer in the second
+ * after the agent stops, when there may be nothing running to ask. The fold is `gapSummary`, the same
+ * one `reticle_context` serves, so the terminal and the agent cannot be told two different stories.
+ */
+import { execFileSync } from 'node:child_process';
+import { existsSync, readdirSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+import { DiscoveryInvite, ReticleDir } from '@reticlehq/core';
+import { gapSummary } from '../../judgement/runs/artifact/gap-summary.js';
+import { SessionJournal } from '../../memory/journal/session-journal.js';
+import { createNodeFileSystem } from '../../memory/project/fs/fs-port.js';
+import { gapHookLine, gapReportLines } from '../../judgement/runs/artifact/gap-report.js';
+/**
+ * A session last written longer ago than this is not the turn a hook is asking about.
+ *
+ * ponytail: a fixed window, not a turn boundary — the Stop hook is not told when the turn began. A
+ * drive older than an hour reads as "no claim this session", which errs toward saying so.
+ */
+const HOOK_WINDOW_MS = 60 * 60 * 1000;
+/** The session whose action ledger was written most recently, if any. */
+function newestSession(root) {
+    const sessionsDir = join(root, ReticleDir.SESSIONS_SUBDIR);
+    if (!existsSync(sessionsDir))
+        return undefined;
+    let newest;
+    for (const id of readdirSync(sessionsDir)) {
+        const ledger = join(sessionsDir, id, ReticleDir.JOURNAL_ACTIONS_FILE);
+        if (!existsSync(ledger))
+            continue;
+        const writtenAt = statSync(ledger).mtimeMs;
+        if (newest === undefined || writtenAt > newest.writtenAt)
+            newest = { id, writtenAt };
+    }
+    return newest;
+}
+export async function reportFor(input) {
+    if (true === input.hook && !input.treeChanged)
+        return { lines: [] };
+    const root = join(input.cwd, ReticleDir.ROOT);
+    const found = input.session === undefined ? newestSession(root) : { id: input.session, writtenAt: input.now };
+    const current = found !== undefined && (true !== input.hook || input.now - found.writtenAt <= HOOK_WINDOW_MS)
+        ? found
+        : undefined;
+    const actions = current === undefined
+        ? []
+        : await new SessionJournal(createNodeFileSystem(), root, current.id).readActions();
+    const gap = gapSummary(actions);
+    if (true === input.hook) {
+        const line = gapHookLine(gap);
+        // A finish with nothing proved is the moment Reticle let somebody down: say who to tell.
+        return { lines: line === undefined ? [] : [line, DiscoveryInvite.HUMAN] };
+    }
+    const header = current === undefined ? [] : [`session ${current.id}`];
+    return { lines: [...header, ...gapReportLines(gap), DiscoveryInvite.HUMAN] };
+}
+/** Uncommitted changes in `cwd`. Outside a git repository nothing can say, so it answers yes. */
+function treeChanged(cwd) {
+    try {
+        return '' !== execFileSync('git', ['status', '--porcelain'], { cwd, encoding: 'utf8' }).trim();
+    }
+    catch {
+        return true;
+    }
+}
+/**
+ * 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 async function handleReport(session, hook) {
+    const cwd = process.cwd();
+    let lines;
+    try {
+        ({ lines } = await reportFor({
+            cwd,
+            now: Date.now(),
+            treeChanged: hook ? treeChanged(cwd) : true,
+            ...(session === undefined ? {} : { session }),
+            hook,
+        }));
+    }
+    catch (error) {
+        // A hook that throws turns the agent's stop into an error the user did not cause; it says nothing
+        // instead. Run by hand, the reason is the answer (an id that is not a session, a journal it
+        // could not read), so it is printed and the exit is non-zero.
+        if (hook)
+            return;
+        process.stderr.write(`reticle report: ${error instanceof Error ? error.message : String(error)}\n`);
+        process.exitCode = 1;
+        return;
+    }
+    if (0 === lines.length)
+        return;
+    process.stdout.write(hook ? `${JSON.stringify({ systemMessage: lines.join('\n') })}\n` : `${lines.join('\n')}\n`);
+}

package/dist/command/cli/status/status-lines.d.ts

@@ -0,0 +1,28 @@
+/**
+ * `reticle status`, rendered for a person.
+ *
+ * The command printed one line of JSON and nothing else. Its own source called it "the second-most
+ * run command and the one a HUMAN types" — and the answer to that human was
+ * `{"t":"…","event":"reticle_status","port":4400,"running":true,…}`. It is worse than that now that
+ * agents run it: an agent's terminal output is read by the person sitting behind it, so a machine
+ * line is a line two readers have to decode and only one of them can.
+ *
+ * The JSON stays, unchanged, on stderr — it is documented, and it is what a log is for. This is the
+ * same facts on stdout, in the shape `doctor` already uses, so the two commands read as one tool.
+ *
+ * Pure, and tolerant: it is handed the very object the log line is built from, narrows it without
+ * trusting it, and prints what it can recognise. A status that cannot be rendered must still be
+ * logged, so nothing here may throw.
+ */
+/** Every row label this block can print. The one spelling; nothing writes a label inline. */
+export declare const StatusLabel: {
+    readonly DAEMON: "daemon";
+    readonly SESSIONS: "sessions";
+    readonly AGENT_LINK: "agent link";
+    readonly NEXT: "next";
+    readonly SPLIT_BRAIN: "split brain";
+    readonly UPDATE: "update";
+};
+export type StatusLabel = (typeof StatusLabel)[keyof typeof StatusLabel];
+/** The block to print on stdout, one string per line, heading first. */
+export declare function statusLines(fields: Record<string, unknown>): string[];

package/dist/command/cli/status/status-lines.js

@@ -0,0 +1,117 @@
+/**
+ * `reticle status`, rendered for a person.
+ *
+ * The command printed one line of JSON and nothing else. Its own source called it "the second-most
+ * run command and the one a HUMAN types" — and the answer to that human was
+ * `{"t":"…","event":"reticle_status","port":4400,"running":true,…}`. It is worse than that now that
+ * agents run it: an agent's terminal output is read by the person sitting behind it, so a machine
+ * line is a line two readers have to decode and only one of them can.
+ *
+ * The JSON stays, unchanged, on stderr — it is documented, and it is what a log is for. This is the
+ * same facts on stdout, in the shape `doctor` already uses, so the two commands read as one tool.
+ *
+ * Pure, and tolerant: it is handed the very object the log line is built from, narrows it without
+ * trusting it, and prints what it can recognise. A status that cannot be rendered must still be
+ * logged, so nothing here may throw.
+ */
+/** Every row label this block can print. The one spelling; nothing writes a label inline. */
+export const StatusLabel = {
+    DAEMON: 'daemon',
+    SESSIONS: 'sessions',
+    AGENT_LINK: 'agent link',
+    NEXT: 'next',
+    SPLIT_BRAIN: 'split brain',
+    UPDATE: 'update',
+};
+const LABELS = Object.values(StatusLabel);
+/** The heading, so a reader can tell which command produced the block. */
+const HEADING = 'reticle status';
+const INDENT = '  ';
+/** Padded off the longest label, for the same reason `doctor` does it: the column IS the legibility. */
+const LABEL_COLUMN = LABELS.reduce((widest, l) => Math.max(widest, l.length), 0) + 2;
+const OK = '✓';
+const NOT_OK = '✗';
+function row(label, rest) {
+    return `${INDENT}${label.padEnd(LABEL_COLUMN)}${rest}`;
+}
+/** A continuation line under a row: indented past the label column, carrying no label of its own. */
+function continuation(rest) {
+    return `${INDENT}${' '.repeat(LABEL_COLUMN)}${rest}`;
+}
+function str(fields, key) {
+    const v = fields[key];
+    return 'string' === typeof v && v.length > 0 ? v : undefined;
+}
+function num(fields, key) {
+    const v = fields[key];
+    return 'number' === typeof v ? v : undefined;
+}
+function sessionViews(fields) {
+    const raw = fields['sessions'];
+    if (!Array.isArray(raw))
+        return [];
+    return raw.flatMap((s) => {
+        if ('object' !== typeof s || null === s)
+            return [];
+        const r = s;
+        // Each of these explains something a reader would otherwise call a bug: a throttled or hidden
+        // tab answers slowly, a stale one answers about a page that has moved on, and an unresponsive
+        // one does not answer at all.
+        const notes = [
+            true === r['throttled'] ? 'throttled' : undefined,
+            true === r['hidden'] ? 'hidden' : undefined,
+            true === r['stale'] ? 'stale' : undefined,
+            true === r['unresponsive'] ? 'unresponsive' : undefined,
+        ].filter((n) => n !== undefined);
+        return [{ url: str(r, 'url') ?? '(no url reported)', notes }];
+    });
+}
+/** The block to print on stdout, one string per line, heading first. */
+export function statusLines(fields) {
+    const port = num(fields, 'port');
+    const at = port === undefined ? '' : ` on :${String(port)}`;
+    const pid = num(fields, 'pid');
+    const running = true === fields['running'];
+    const lines = [HEADING];
+    lines.push(row(StatusLabel.DAEMON, running
+        ? `${OK} running${at}${pid === undefined ? '' : ` (pid ${String(pid)})`}`
+        : `${NOT_OK} not running${at}`));
+    // What was actually ON the port, when the pid file said nothing useful. "A stranger holds this"
+    // and "nothing is here" were the same output once, and the true sentence was said by nothing a
+    // person sees — so the word belongs in the prose, not only in the event.
+    const presence = str(fields, 'presence');
+    if (presence !== undefined)
+        lines.push(continuation(`port presence: ${presence}`));
+    // The refusal a FOREIGN port produces. It is the whole answer when it is present, so it rides the
+    // daemon row rather than waiting for a `next` that is not built in that branch.
+    const reason = str(fields, 'reason');
+    if (reason !== undefined)
+        lines.push(continuation(reason));
+    if (running) {
+        const count = num(fields, 'sessionCount') ?? 0;
+        lines.push(row(StatusLabel.SESSIONS, count > 0
+            ? `${OK} ${String(count)} page${1 === count ? '' : 's'} connected`
+            : `${NOT_OK} no page connected`));
+        for (const s of sessionViews(fields)) {
+            lines.push(continuation(`${s.url}${0 === s.notes.length ? '' : `  (${s.notes.join(', ')})`}`));
+        }
+        // The daemon's own explanation for an empty session list, which outranks anything this command
+        // could infer — it is the one holding the connection.
+        const why = str(fields, 'why');
+        if (why !== undefined)
+            lines.push(continuation(why));
+    }
+    const client = str(fields, 'mcpClient');
+    if (client !== undefined)
+        lines.push(row(StatusLabel.AGENT_LINK, client));
+    for (const [label, key] of [
+        [StatusLabel.NEXT, 'nextAction'],
+        [StatusLabel.SPLIT_BRAIN, 'splitBrain'],
+        [StatusLabel.UPDATE, 'updateAvailable'],
+    ]) {
+        const value = str(fields, key);
+        if (value !== undefined)
+            lines.push(row(label, value));
+    }
+    return lines;
+}

package/dist/command/cli.d.ts

@@ -2,5 +2,5 @@
 import { parseCliArgs, CLI_USAGE } from './cli/cli-parse.js';
 export { parseCliArgs, CLI_USAGE };
 export type { CliResult } from './cli/cli-parse.js';
-export declare function handleStatus(port: number): Promise<void>;
+export declare function handleStatus(port: number, json?: boolean): Promise<void>;
 export declare function main(): void;

package/dist/command/cli.js

@@ -8,15 +8,15 @@ import { openFailureNote } from './cli/answers/open-note.js';
 import { realpathSync } from 'node:fs';
 import { join } from 'node:path';
 import { installCrashGuard } from './setup/setup-command.js';
-import { stateDirProblem } from './daemon/state-dir.js';
 import { readDevServers } from './daemon/dev-servers.js';
 import { hasAnyAppConnectedBefore, hasProjectConnectedBefore, } from '../memory/recall/prior/connection-memory.js';
 import { attachStatusFields } from '../surface/mcp/attach-memory.js';
 import { splitBrainFields, withNextAction } from './cli/status-fields.js';
 import { reticleStateHome } from './daemon/daemon.js';
 import { handleMcp } from './cli/mcp-command.js';
+import { handleReport } from './cli/report-command.js';
 import { resolveDaemonForProject } from './daemon/daemon-resolve.js';
-import { daemonSpawnArgs, daemonStartOptions } from './cli/daemon-start-options.js';
+import { daemonStartOptions } from './cli/daemon-start-options.js';
 import { handleWatch, handleCapsules, handleGate, loadNamedFlows, resolveChangedFiles, } from './cli/cli-flow-commands.js';
 import { RETICLE_DEFAULT_PORT, ReticleDir, ReticleEnv, devServersForProject, } from '@reticlehq/core';
 import { loadDotEnv } from '../telemetry/dev-repo.js';
@@ -26,20 +26,20 @@ import { createNodeFileSystem } from '../memory/project/fs/fs-port.js';
 import { affectedSavedFlows } from '../language/flows/change/flow-sources.js';
 import { availableUpdate } from './update/update-nudge.js';
 import { handleUpdate, handleRollback } from './cli/cli-update-commands.js';
-import { startDaemon, RETICLE_VERIFY_DEFAULT_PORT } from '../index.js';
-import { verifyEndpointMismatch } from '../status-payload.js';
+import { startDaemon } from '../index.js';
 import { isCloudCommand, runCloudCommand } from './cli/cloud-cli.js';
 import { SERVER_VERSION } from './version/identity/server-version.js';
 import { log } from '../log.js';
-import { readPid, isAlive, removePid, spawnDaemon, discoverDaemonPort, writeDaemonRegistry, logPath, } from './daemon/daemon.js';
+import { readPid, isAlive, removePid, spawnDaemon, discoverDaemonPort, writeDaemonRegistry, } from './daemon/daemon.js';
 import { PortPresence, probePresence, presenceIsUsable, describePresence, } from './daemon/binding/port-presence.js';
 import { waitForDaemon, probeDaemon } from '../surface/mcp/mcp-proxy.js';
 import { installDaemonResilience, recordExitReason, DaemonExitReason, } from './daemon/daemon-resilience.js';
 import { IdleShutdown, resolveIdleShutdownMs, resolveIdleCheckMs } from './daemon/idle-shutdown.js';
 import { DaemonHeartbeat, resolveHeartbeatMs } from './daemon/lifetime/heartbeat.js';
 import { everServedToolCall } from './daemon/lifetime/daemon-usefulness.js';
-import { DAEMON_START_FAILED_EVENT, readDaemonStartupCause, } from './daemon/lifetime/startup-failure.js';
-import { fetchStatus, summarizeStatus, warnOnDaemonSkew, decideOpen, openInBrowser, openCommand, } from './cli/launch/cli-launch.js';
+import { DAEMON_START_FAILED_EVENT } from './daemon/lifetime/startup-failure.js';
+import { summarizeStatus, warnOnDaemonSkew, decideOpen, openInBrowser, openCommand, } from './cli/launch/cli-launch.js';
+import { fetchStatus } from './daemon/binding/daemon-status-probe.js';
 import { handleDrive } from './cli/drive/drive-command.js';
 import { handleVerify } from './cli/cli-verify.js';
 import { runKill } from './cli/cli-kill.js';
@@ -70,6 +70,7 @@ function handleInit(parsed) {
         // past a missing package manager, and could not honour that while never being told about it.
         ...(parsed.url === undefined ? {} : { url: parsed.url }),
         captureBodies: true === parsed.captureBodies,
+        hooks: true === parsed.hooks,
         // The outcome is reported by confirmInstall instead, once it knows whether an app connected —
         // `init` writing files was never the same thing as `init` working (#269).
         deferOutcome: true,
@@ -77,178 +78,26 @@ function handleInit(parsed) {
     }, io);
     void continueAfterInit(parsed, result, io, cwd);
 }
-function handleServe(parsed) {
-    void serveWithHonestExit(parsed);
-}
+// `serve`, `stop` and `restart` live in `cli/lifecycle/daemon-lifecycle.ts`: one idea, and the
+// largest group this file could give up without splitting something that belongs together.
+import { handleServe, handleStop, handleRestart } from './cli/lifecycle/daemon-lifecycle.js';
+import { statusLines } from './cli/status/status-lines.js';
 /**
- * Report the BIND, not the spawn.
- *
- * `serve` used to log `reticle_daemon_spawned` and exit 0 unconditionally, while the child died at
- * `reticle_daemon_start_failed` with an EADDRINUSE nothing joined back to the parent. Three surfaces
- * then disagreed about what was true and none of them named the port.
+ * Log the status event AND print it for a person.
  *
- * Two changes, both about saying what is actually the case: refuse up front when the port is held by
- * something that is not a Reticle daemon (a spawn there cannot succeed), and after spawning, wait
- * for the daemon to actually answer before claiming it started.
+ * Both, not either: the JSON line is documented and is what a log is for, and the block is for
+ * whoever is reading the terminal — which, once an agent is running the command, is somebody who
+ * did not type it and cannot be assumed to parse it.
  */
-async function serveWithHonestExit(parsed) {
-    const presence = await probePresence(parsed.port, {
-        tcpOpen: probeDaemon,
-        status: fetchStatus,
-    });
-    if (presence === PortPresence.DAEMON) {
-        // A daemon that is already up was started with ITS flags, not these — `serve` only attaches.
-        // Exiting 0 here regardless is how `--http-port` came to be accepted and ignored (#687): the
-        // running daemon kept serving whatever it was started with, and the flag vanished without a
-        // word. Ask the daemon which verify port it actually serves and refuse when it is not the one
-        // requested — a flag that cannot be honoured must say so, not report success.
-        if (parsed.http) {
-            const mismatch = verifyEndpointMismatch(await fetchStatus(parsed.port), parsed.httpPort ?? RETICLE_VERIFY_DEFAULT_PORT);
-            if (mismatch !== undefined) {
-                log('reticle_daemon_start_refused', { port: parsed.port, reason: mismatch });
-                process.stderr.write(`${mismatch}\n`);
-                process.exit(1);
-                return;
-            }
-        }
-        log('reticle_daemon_already_running', { port: parsed.port });
-        return;
-    }
-    if (presence === PortPresence.FOREIGN) {
-        log('reticle_daemon_start_refused', {
-            port: parsed.port,
-            presence,
-            reason: describePresence(presence, parsed.port),
-        });
-        process.stderr.write(`${describePresence(presence, parsed.port)}\n`);
-        process.exit(1);
+function reportStatus(fields, json) {
+    if (json) {
+        log('reticle_status', fields);
         return;
     }
-    const scriptPath = process.argv[1];
-    if (scriptPath === undefined) {
-        log('reticle_serve_no_script', {});
-        process.exit(1);
-        return;
-    }
-    const daemonArgs = daemonSpawnArgs(parsed);
-    const startupStartedAt = Date.now();
-    spawnDaemon(process.execPath, scriptPath, daemonArgs, parsed.port);
-    // The child binds asynchronously and, when it cannot, exits 1 long after this process would have
-    // reported success. Wait for it to ANSWER — `/status` responding is the only evidence a daemon
-    // exists that does not come from the pid file the child may never have earned.
-    const bound = await waitForPresence(parsed.port, PortPresence.DAEMON, SERVE_BIND_TIMEOUT_MS);
-    if (!bound) {
-        const settled = await probePresence(parsed.port, { tcpOpen: probeDaemon, status: fetchStatus });
-        const startupCause = readDaemonStartupCause(logPath(parsed.port), startupStartedAt);
-        log('reticle_daemon_start_failed_parent', {
-            port: parsed.port,
-            presence: settled,
-            reason: describePresence(settled, parsed.port),
-            log: logPath(parsed.port),
-            stateDir: stateDirProblem(reticleStateHome()) === undefined ? 'writable' : 'unwritable',
-            ...(startupCause === undefined ? {} : { cause: startupCause }),
-        });
-        // Name the CAUSE when we can see it. An unwritable state directory is a first-run failure mode
-        // (locked-down home, read-only container mount, managed profile) that produced only "nothing is
-        // listening" — the symptom restated — and then pointed at a log INSIDE that directory, which
-        // cannot exist. Reproduced with `chmod 555 ~/.reticle`.
-        const dirProblem = stateDirProblem(reticleStateHome());
-        process.stderr.write(dirProblem === undefined
-            ? startupCause === undefined
-                ? `the daemon did not come up on :${String(parsed.port)} — ${describePresence(settled, parsed.port)}\n` +
-                    `see ${logPath(parsed.port)}\n`
-                : `the daemon did not come up on :${String(parsed.port)}.\n${startupCause}\n` +
-                    `see ${logPath(parsed.port)}\n`
-            : `the daemon did not come up on :${String(parsed.port)}.\n${dirProblem}\n`);
-        process.exit(1);
-        return;
-    }
-    log('reticle_daemon_spawned', { port: parsed.port, ...(parsed.http ? { http: true } : {}) });
+    process.stdout.write(`${statusLines(fields).join('\n')}\n`);
 }
-/** How long `serve` waits for the child to bind. Generous: a cold daemon start is seconds. */
-const SERVE_BIND_TIMEOUT_MS = 15_000;
-const PRESENCE_POLL_MS = 150;
-/** How long a daemon gets to shut down on its own before `stop` stops asking politely. */
-const GRACEFUL_STOP_MS = 5000;
-/** How long after SIGKILL before we accept the process is not ours to kill and say so. */
-const FORCED_STOP_MS = 2000;
-async function waitForPresence(port, want, timeoutMs) {
-    const deadline = Date.now() + timeoutMs;
-    for (;;) {
-        const presence = await probePresence(port, { tcpOpen: probeDaemon, status: fetchStatus });
-        if (presence === want)
-            return true;
-        if (Date.now() >= deadline)
-            return false;
-        await new Promise((resolve) => setTimeout(resolve, PRESENCE_POLL_MS));
-    }
-}
-function handleStop(port, quiet) {
-    const pid = readPid(port);
-    if (null === pid || !isAlive(pid)) {
-        removePid(port);
-        if (!quiet)
-            log('reticle_daemon_not_running', { port });
-        return;
-    }
-    process.kill(pid, 'SIGTERM');
-    const started = Date.now();
-    let escalated = false;
-    const poll = setInterval(() => {
-        if (!isAlive(pid)) {
-            clearInterval(poll);
-            removePid(port);
-            if (!quiet)
-                log('reticle_daemon_stopped', { port, pid, ...(escalated ? { escalated } : {}) });
-            return;
-        }
-        const waited = Date.now() - started;
-        // A daemon that ignores SIGTERM is WEDGED — which is the one situation `stop` exists for. Giving
-        // up here left the port held, the pid file stale, and a human running `kill -9` by hand at the
-        // first two minutes of setup. Escalate instead: graceful first, then unconditional.
-        if (!escalated && waited > GRACEFUL_STOP_MS) {
-            escalated = true;
-            try {
-                process.kill(pid, 'SIGKILL');
-            }
-            catch {
-                // Already gone between the liveness check and here — the next tick reports it stopped.
-            }
-            return;
-        }
-        if (waited > GRACEFUL_STOP_MS + FORCED_STOP_MS) {
-            clearInterval(poll);
-            // Surviving SIGKILL means the pid is not ours to kill (permissions) or is an unkillable
-            // zombie. Neither is retryable, and both need the pid named so a human can act on it.
-            if (!quiet)
-                log('reticle_daemon_stop_timeout', { port, pid, escalated });
-            process.exit(1);
-        }
-    }, 100);
-}
-/**
- * `reticle restart` — free the port, then put a daemon back on it and prove it bound.
- *
- * The two halves are reported separately on purpose. A restart that killed the old daemon and then
- * could not start a new one leaves the user in a different place from one that could not kill
- * anything at all, and a single `ok: false` cannot tell them which happened.
- */
-async function handleRestart(port, force) {
-    const freed = await runKill(port, force);
-    if (!freed) {
-        log('reticle_restart_aborted', {
-            port,
-            reason: 'the port was not freed, so nothing was started — the old holder is still there',
-        });
-        process.exit(1);
-        return;
-    }
-    // Reuses `serve`'s path, which waits for the daemon to ANSWER before claiming it started and exits
-    // non-zero when it does not. A restart that reports success for a daemon that never bound is the
-    // same lie `serve` already stopped telling.
-    await serveWithHonestExit({ port, headless: true, http: false });
-}
-export async function handleStatus(port) {
+export async function handleStatus(port, json = false) {
+    const report = (fields) => reportStatus(fields, json);
     const pid = readPid(port);
     // Durable, so it survives the daemon idling out — which is the state `status` is most often run in.
     const projectId = readProjectId(process.cwd());
@@ -281,7 +130,7 @@ export async function handleStatus(port) {
     // process exists; a Reticle daemon is running only when the shared port probe reaches /status.
     const presence = await probePresence(port, { tcpOpen: probeDaemon, status: fetchStatus });
     if (!presenceIsUsable(presence)) {
-        log('reticle_status', {
+        report({
             port,
             running: false,
             presence,
@@ -310,7 +159,7 @@ export async function handleStatus(port) {
     const update = availableUpdate();
     const nudge = update === undefined ? {} : { updateAvailable: update };
     if (payload === undefined) {
-        log('reticle_status', {
+        report({
             port,
             running: true,
             pid,
@@ -342,7 +191,7 @@ export async function handleStatus(port) {
             devServerPorts,
         })
         : {};
-    log('reticle_status', {
+    report({
         port,
         running: true,
         pid,
@@ -752,7 +601,7 @@ export function main() {
             void handleRestart(parsed.port, parsed.force);
             break;
         case 'status':
-            void handleStatus(parsed.port);
+            void handleStatus(parsed.port, parsed.json);
             break;
         case 'license':
             handleLicense();
@@ -822,6 +671,9 @@ export function main() {
         case 'gate':
             void handleGate(parsed.files, parsed.since, parsed.hook);
             break;
+        case 'report':
+            void handleReport(parsed.session, parsed.hook);
+            break;
         case 'watch':
             handleWatch();
             break;