@reticlehq/server 2.3.0 → 2.5.0

package/dist/{cli-parse.js → cli/cli-parse.js}

@@ -5,8 +5,12 @@
  * imports are unchanged.
  */
 export const CLI_USAGE = `usage:
-  reticle init  [--dry-run] [--port N] [--no-mcp] [--no-install]  (wire Reticle into the project in this directory)
-  reticle serve [--port N] [--drive <url>] [--headed] [--http] [--http-port N] [--http-token T]
+  reticle init  [--dry-run] [--port N] [--no-mcp] [--no-install] [--app <dir>]  (wire Reticle into the project in this directory)
+                --app picks WHICH app in a monorepo, when several are found
+                --no-mcp skips MORE than the server registration: also the agent rule files
+                (CLAUDE.md / AGENTS.md / .cursor) and the /reticle command, because all three
+                only make sense once the tools are reachable.
+  reticle serve [--port N] [--drive <url>] [--headless] [--http] [--http-port N] [--http-token T]
   reticle stop  [--port N] [--quiet]
   reticle status [--port N]
   reticle doctor [--port N]                            (diagnose setup: Chromium, daemon, port — one command)
@@ -15,8 +19,8 @@ export const CLI_USAGE = `usage:
   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 watch [url]                                  (on save, report which saved flows must re-verify)
-  reticle drive <url> [--headed]                       (foreground mode — for debugging)
-  reticle mcp   [--port N] [--drive <url>] [--headed]  (MCP stdio proxy — auto-starts daemon if needed)
+  reticle drive <url> [--headless]                     (foreground mode — for debugging)
+  reticle mcp   [--port N] [--drive <url>] [--headless] (MCP stdio proxy — auto-starts daemon if needed)
   reticle update                                       (install the latest server version and restart)
   reticle rollback                                     (restore the previous server version and restart)
   reticle license                                      (show enterprise license status: active | eval | missing)
@@ -32,7 +36,10 @@ Cloud (link this project to Reticle Cloud — runs/flows recorded on the dashboa
   reticle project <ls|create <name>>                   (list or create cloud projects)
   reticle config [--runs on|off] [--memory on|off] [--flows on|off] [--verify local|server]
   reticle push                                          (send local run artifacts to the dashboard)
-  reticle runs | regression | share <runId>            (read cloud state; regression exits 3 if any flow broke)`;
+  reticle runs | regression | share <runId>            (read cloud state; regression exits 3 if any flow broke)
+
+'drive' shows the browser; everything else is hidden (serve/mcp own the pool behind leases, replay
+and the spec runner — batch work). --headed opts any of them in, --headless hides drive, CI hides it.`;
 const INIT_COMMAND = 'init';
 const SERVE_COMMAND = 'serve';
 const STOP_COMMAND = 'stop';
@@ -53,10 +60,10 @@ const VERSION_COMMAND = 'version';
 const TELEMETRY_COMMAND = 'telemetry';
 const FEEDBACK_COMMAND = 'feedback';
 const IDENTIFY_COMMAND = 'identify';
-export const COMPANY_FLAG = '--company';
-export const EMAIL_FLAG = '--email';
-export const CONTEXT_FLAG = '--context';
-export const FORGET_FLAG = '--forget';
+const COMPANY_FLAG = '--company';
+const EMAIL_FLAG = '--email';
+const CONTEXT_FLAG = '--context';
+const FORGET_FLAG = '--forget';
 /** `reticle feedback --rating 4 "the words"` — the human half of the channel. */
 export const RATING_FLAG = '--rating';
 export const BUG_FLAG = '--bug';
@@ -115,24 +122,51 @@ const KNOWN_COMMANDS = new Set([
 ]);
 /** The subcommand name if we recognize it, else `unknown`. Bare `reticle` reports `help`. */
 export function knownCommand(arg) {
-    if (arg === undefined || arg === '')
+    if (arg === undefined || '' === arg)
         return 'help';
     return KNOWN_COMMANDS.has(arg) ? arg : UNKNOWN_COMMAND;
 }
 export const HEADED_FLAG = '--headed';
+/**
+ * Force a hidden browser. The default is now HEADED: a run nobody can see is a run nobody trusts,
+ * and every "did it actually do anything?" question cost a round-trip. CI passes this (or just sets
+ * CI, which flips the default) because there is no display there to be headed on.
+ */
+const HEADLESS_FLAG = '--headless';
 export const PORT_FLAG = '--port';
 export const DRIVE_FLAG = '--drive';
 const QUIET_FLAG = '--quiet';
 const DRY_RUN_FLAG = '--dry-run';
 const YES_FLAG = '--yes';
 const NO_MCP_FLAG = '--no-mcp';
+const APP_FLAG = '--app';
 const NO_INSTALL_FLAG = '--no-install';
 export const HTTP_FLAG = '--http';
 export const HTTP_PORT_FLAG = '--http-port';
 export const HTTP_TOKEN_FLAG = '--http-token';
 const TIMEOUT_FLAG = '--timeout';
 const STORAGE_STATE_FLAG = '--storage-state';
-function parseServeFlags(args, defaultPort) {
+const unknownArgument = (arg) => ({
+    kind: 'error',
+    message: `unknown argument '${arg}'`,
+});
+const missingValue = (flag) => ({
+    kind: 'error',
+    message: `${flag} needs a value`,
+});
+const notANumber = (flag, value) => ({
+    kind: 'error',
+    message: `${flag} expects a number, got '${value}'`,
+});
+const missingOperand = (command, what) => ({
+    kind: 'error',
+    message: `${command} needs ${what}`,
+});
+const unknownCommand = (command) => ({
+    kind: 'error',
+    message: `unknown command '${command}'`,
+});
+function parseServeFlags(args, defaultPort, _defaultHeadless) {
     let port = defaultPort;
     let driveUrl;
     let headless = true;
@@ -142,25 +176,32 @@ function parseServeFlags(args, defaultPort) {
     let i = 0;
     while (i < args.length) {
         const arg = args[i];
+        // `i < args.length` already guarantees this, but the index signature does not say so and the
+        // unknown-argument error needs a real string to name.
+        if (arg === undefined)
+            break;
         if (arg === PORT_FLAG) {
             i++;
             const n = args[i];
             if (n === undefined)
-                return { kind: 'error', message: CLI_USAGE };
+                return missingValue(PORT_FLAG);
             const parsed = parseInt(n, 10);
             if (isNaN(parsed))
-                return { kind: 'error', message: CLI_USAGE };
+                return notANumber(PORT_FLAG, n);
             port = parsed;
         }
         else if (arg === DRIVE_FLAG) {
             i++;
             driveUrl = args[i];
             if (driveUrl === undefined)
-                return { kind: 'error', message: CLI_USAGE };
+                return missingValue(DRIVE_FLAG);
         }
         else if (arg === HEADED_FLAG) {
             headless = false;
         }
+        else if (arg === HEADLESS_FLAG) {
+            headless = true;
+        }
         else if (arg === HTTP_FLAG) {
             http = true;
         }
@@ -168,20 +209,20 @@ function parseServeFlags(args, defaultPort) {
             i++;
             const n = args[i];
             if (n === undefined)
-                return { kind: 'error', message: CLI_USAGE };
+                return missingValue(HTTP_PORT_FLAG);
             const parsed = parseInt(n, 10);
             if (isNaN(parsed))
-                return { kind: 'error', message: CLI_USAGE };
+                return notANumber(HTTP_PORT_FLAG, n);
             httpPort = parsed;
         }
         else if (arg === HTTP_TOKEN_FLAG) {
             i++;
             httpToken = args[i];
             if (httpToken === undefined)
-                return { kind: 'error', message: CLI_USAGE };
+                return missingValue(HTTP_TOKEN_FLAG);
         }
         else {
-            return { kind: 'error', message: CLI_USAGE };
+            return unknownArgument(arg);
         }
         i++;
     }
@@ -197,7 +238,7 @@ function parseServeFlags(args, defaultPort) {
 }
 function parsePortFlag(args, defaultPort) {
     const idx = args.indexOf(PORT_FLAG);
-    if (idx === -1)
+    if (-1 === idx)
         return defaultPort;
     const n = args[idx + 1];
     if (n === undefined)
@@ -205,25 +246,28 @@ function parsePortFlag(args, defaultPort) {
     const parsed = parseInt(n, 10);
     return isNaN(parsed) ? defaultPort : parsed;
 }
-function parseDriveSuffix(args, port) {
-    let headless = true;
+function parseDriveSuffix(args, port, defaultHeadless) {
+    let headless = defaultHeadless;
     let driveUrl;
     for (const arg of args) {
         if (arg === HEADED_FLAG) {
             headless = false;
         }
+        else if (arg === HEADLESS_FLAG) {
+            headless = true;
+        }
         else if (arg.startsWith('--')) {
-            return { kind: 'error', message: CLI_USAGE };
+            return unknownArgument(arg);
         }
         else if (driveUrl === undefined) {
             driveUrl = arg;
         }
         else {
-            return { kind: 'error', message: CLI_USAGE };
+            return unknownArgument(arg);
         }
     }
     if (driveUrl === undefined)
-        return { kind: 'error', message: CLI_USAGE };
+        return missingOperand(DRIVE_COMMAND, 'a url');
     return { kind: 'ok', port, driveUrl, headless };
 }
 /**
@@ -247,32 +291,32 @@ function parseVerifySuffix(args) {
             i++;
             const n = args[i];
             if (n === undefined)
-                return { kind: 'error', message: CLI_USAGE };
+                return missingValue(TIMEOUT_FLAG);
             const parsed = parseInt(n, 10);
             if (isNaN(parsed))
-                return { kind: 'error', message: CLI_USAGE };
+                return notANumber(TIMEOUT_FLAG, n);
             timeoutMs = parsed;
         }
         else if (arg === STORAGE_STATE_FLAG) {
             i++;
             const v = args[i];
             if (v === undefined)
-                return { kind: 'error', message: CLI_USAGE };
+                return missingValue(STORAGE_STATE_FLAG);
             storageState = v;
         }
         else if (arg.startsWith('--')) {
-            return { kind: 'error', message: CLI_USAGE };
+            return unknownArgument(arg);
         }
         else if (url === undefined) {
             url = arg;
         }
         else {
-            return { kind: 'error', message: CLI_USAGE };
+            return unknownArgument(arg);
         }
         i++;
     }
     if (url === undefined)
-        return { kind: 'error', message: CLI_USAGE };
+        return missingOperand(VERIFY_COMMAND, 'a url');
     return {
         kind: 'ok',
         url,
@@ -286,19 +330,31 @@ function parseInitFlags(args) {
     let mcp = true;
     let dryRun = false;
     let install = true;
+    let app;
     let i = 0;
     while (i < args.length) {
         const arg = args[i];
+        // `i < args.length` already guarantees this, but the index signature does not say so and the
+        // unknown-argument error needs a real string to name.
+        if (arg === undefined)
+            break;
         if (arg === PORT_FLAG) {
             i++;
             const n = args[i];
             if (n === undefined)
-                return { kind: 'error', message: CLI_USAGE };
+                return missingValue(PORT_FLAG);
             const parsed = parseInt(n, 10);
             if (isNaN(parsed))
-                return { kind: 'error', message: CLI_USAGE };
+                return notANumber(PORT_FLAG, n);
             port = parsed;
         }
+        else if (arg === APP_FLAG) {
+            i++;
+            const value = args[i];
+            if (value === undefined)
+                return missingValue(APP_FLAG);
+            app = value;
+        }
         else if (arg === NO_MCP_FLAG) {
             mcp = false;
         }
@@ -312,15 +368,29 @@ function parseInitFlags(args) {
             // Accepted for scripting/CI; init has no interactive prompts today.
         }
         else {
-            return { kind: 'error', message: CLI_USAGE };
+            return unknownArgument(arg);
         }
         i++;
     }
-    return { kind: 'ok', port, mcp, dryRun, install };
+    return { kind: 'ok', port, mcp, dryRun, install, app };
 }
 /** Pure CLI arg parser — exported for unit tests. argv = process.argv.slice(2). */
 const SINCE_FLAG = '--since';
 /** Parse `[--since <ref>] [file...]` shared by `affected` and `gate`. */
+/**
+ * What `reticle gate` / `reticle affected` mean with NOTHING after them: the working tree.
+ *
+ * They used to mean a usage error — while the rule `reticle init` writes into the agent's own
+ * instruction file says, in as many words, "run `reticle gate`". An instruction the tool rejects is
+ * worse than no instruction: the agent spends a turn on it and concludes Reticle is broken.
+ *
+ * HEAD is the ref that answers the question being asked. Explicit files or an explicit --since still
+ * win; this only fills the empty case.
+ */
+const WORKING_TREE_REF = 'HEAD';
+function implicitSince(files) {
+    return 0 === files.length ? WORKING_TREE_REF : undefined;
+}
 function parseTargetArgs(rest) {
     const files = [];
     let since;
@@ -336,28 +406,45 @@ function parseTargetArgs(rest) {
     }
     return since === undefined ? { files } : { files, since };
 }
-export function parseCliArgs(argv, defaultPort) {
-    if (argv.length === 0)
+/**
+ * @param defaultHeadless Whether a browser Reticle launches should be hidden when no flag says
+ *   otherwise. Injected rather than read from the environment here, because this module is pure —
+ *   `cli.ts` decides it from `CI`. The product default is FALSE: showing the run is what makes it
+ *   trustworthy, and asking people to opt into seeing their own app was backwards.
+ */
+export function parseCliArgs(argv, defaultPort, defaultHeadless = false) {
+    // Bare `reticle` is `serve` — a pool-owning command, so headless like the rest of that family.
+    if (0 === argv.length)
         return { kind: 'serve', port: defaultPort, headless: true, http: false };
     const [cmd, ...rest] = argv;
+    // Guaranteed by the bare-argv check above; restated so the unknown-command error can name it.
+    if (cmd === undefined)
+        return { kind: 'error', message: CLI_USAGE };
     // `version` (or the conventional -v/--version flags) prints the running version — the diagnostic the
     // troubleshooting docs lean on to confirm which npx-resolved build is actually executing.
-    if (cmd === VERSION_COMMAND || cmd === '--version' || cmd === '-v')
+    if (cmd === VERSION_COMMAND || '--version' === cmd || '-v' === cmd)
         return { kind: 'version' };
     // `help` (and the conventional -h/--help) print usage to stdout and exit 0 — the universal first move
     // for a new user, which otherwise fell through to a JSON error with exit 1.
-    if (cmd === 'help' || cmd === '--help' || cmd === '-h')
+    if ('help' === cmd || '--help' === cmd || '-h' === cmd)
         return { kind: 'help' };
     switch (cmd) {
         case INIT_COMMAND: {
             const r = parseInitFlags(rest);
-            if (r.kind === 'error')
+            if ('error' === r.kind)
                 return r;
-            return { kind: 'init', port: r.port, mcp: r.mcp, dryRun: r.dryRun, install: r.install };
+            return {
+                kind: 'init',
+                port: r.port,
+                mcp: r.mcp,
+                dryRun: r.dryRun,
+                install: r.install,
+                app: r.app,
+            };
         }
         case SERVE_COMMAND: {
-            const r = parseServeFlags(rest, defaultPort);
-            if (r.kind === 'error')
+            const r = parseServeFlags(rest, defaultPort, defaultHeadless);
+            if ('error' === r.kind)
                 return r;
             return {
                 kind: 'serve',
@@ -396,7 +483,7 @@ export function parseCliArgs(argv, defaultPort) {
         case IDENTIFY_COMMAND: {
             const flag = (name) => {
                 const at = rest.indexOf(name);
-                return at === -1 ? undefined : rest[at + 1];
+                return -1 === at ? undefined : rest[at + 1];
             };
             const context = flag(CONTEXT_FLAG);
             const company = flag(COMPANY_FLAG);
@@ -411,13 +498,13 @@ export function parseCliArgs(argv, defaultPort) {
         }
         case FEEDBACK_COMMAND: {
             const ratingAt = rest.indexOf(RATING_FLAG);
-            const rating = ratingAt === -1 ? undefined : Number(rest[ratingAt + 1]);
+            const rating = -1 === ratingAt ? undefined : Number(rest[ratingAt + 1]);
             if (rating !== undefined && (!Number.isInteger(rating) || rating < 1 || rating > 5)) {
                 return { kind: 'error', message: `${RATING_FLAG} takes a whole number from 1 to 5` };
             }
             // Everything that is not a flag or the rating's value is the message. Quoting is the user's
             // job for shell reasons, but joining the remainder means an unquoted sentence still works.
-            const consumed = new Set(ratingAt === -1 ? [] : [ratingAt, ratingAt + 1]);
+            const consumed = new Set(-1 === ratingAt ? [] : [ratingAt, ratingAt + 1]);
             const text = rest
                 .filter((arg, i) => !consumed.has(i) && !arg.startsWith('--'))
                 .join(' ')
@@ -436,14 +523,14 @@ export function parseCliArgs(argv, defaultPort) {
             return url !== undefined ? { kind: 'open', port, url } : { kind: 'open', port };
         }
         case DRIVE_COMMAND: {
-            const r = parseDriveSuffix(rest, defaultPort);
-            if (r.kind === 'error')
+            const r = parseDriveSuffix(rest, defaultPort, defaultHeadless);
+            if ('error' === r.kind)
                 return r;
             return { kind: 'drive', port: r.port, driveUrl: r.driveUrl, headless: r.headless };
         }
         case DAEMON_INNER_COMMAND: {
-            const r = parseServeFlags(rest, defaultPort);
-            if (r.kind === 'error')
+            const r = parseServeFlags(rest, defaultPort, defaultHeadless);
+            if ('error' === r.kind)
                 return r;
             return {
                 kind: '_daemon',
@@ -457,7 +544,7 @@ export function parseCliArgs(argv, defaultPort) {
         }
         case VERIFY_COMMAND: {
             const r = parseVerifySuffix(rest);
-            if (r.kind === 'error')
+            if ('error' === r.kind)
                 return r;
             return {
                 kind: 'verify',
@@ -477,21 +564,13 @@ export function parseCliArgs(argv, defaultPort) {
         }
         case AFFECTED_COMMAND: {
             const t = parseTargetArgs(rest);
-            if (t.files.length === 0 && t.since === undefined) {
-                return { kind: 'error', message: 'usage: reticle affected [--since <ref>] [file...]' };
-            }
-            return {
-                kind: 'affected',
-                files: t.files,
-                ...(t.since === undefined ? {} : { since: t.since }),
-            };
+            const since = t.since ?? implicitSince(t.files);
+            return { kind: 'affected', files: t.files, ...(since === undefined ? {} : { since }) };
         }
         case GATE_COMMAND: {
             const t = parseTargetArgs(rest);
-            if (t.files.length === 0 && t.since === undefined) {
-                return { kind: 'error', message: 'usage: reticle gate [--since <ref>] [file...]' };
-            }
-            return { kind: 'gate', files: t.files, ...(t.since === undefined ? {} : { since: t.since }) };
+            const since = t.since ?? implicitSince(t.files);
+            return { kind: 'gate', files: t.files, ...(since === undefined ? {} : { since }) };
         }
         case WATCH_COMMAND: {
             // `reticle watch [url]` — on file save, report which saved flows must re-verify.
@@ -503,8 +582,8 @@ export function parseCliArgs(argv, defaultPort) {
         case ROLLBACK_COMMAND:
             return { kind: 'rollback' };
         case MCP_COMMAND: {
-            const r = parseServeFlags(rest, defaultPort);
-            if (r.kind === 'error')
+            const r = parseServeFlags(rest, defaultPort, defaultHeadless);
+            if ('error' === r.kind)
                 return r;
             return {
                 kind: 'mcp',
@@ -517,6 +596,8 @@ export function parseCliArgs(argv, defaultPort) {
             };
         }
         default:
-            return { kind: 'error', message: CLI_USAGE };
+            // A bare `reticle` never lands here — it defaults to `serve` above — so `cmd` is always a real
+            // word somebody typed, and naming it is strictly more useful than reprinting the whole help.
+            return unknownCommand(cmd);
     }
 }

package/dist/{cli-port.d.ts → cli/cli-port.d.ts}

@@ -7,6 +7,21 @@
  * 3..reticle.json "port" field in the cwd ← per-project isolation
  * 4. RETICLE_DEFAULT_PORT (4400)
  */
+/**
+ * Ports that belong to a DEV SERVER, not to Reticle's bridge. Next defaults to 3000, Vite to 5173,
+ * Astro to 4321, and so on.
+ *
+ * `.reticle.json`'s `port` is the bridge — the daemon ↔ SDK channel, default 4400 — and it has
+ * nothing to do with the port the app is served on. Setting it to the dev-server port makes the
+ * daemon try to bind the port the app already holds; what the user sees is either a bind failure or
+ * a daemon that never connects, neither of which mentions the actual mistake. The old setup skill
+ * asked "what port does your dev server run on?" a few lines before showing this field, which is how
+ * the confusion got manufactured in the first place.
+ */
+export declare const DEV_SERVER_PORTS: ReadonlySet<number>;
+export declare function isLikelyDevServerPort(port: number): boolean;
+/** The warning printed when a project pins the bridge to something that looks like its dev server. */
+export declare function devServerPortWarning(port: number): string;
 /**
  * Read the port stored in the project's .reticle.json (written by `reticle init`).
  * Returns undefined if the file is absent, unreadable, or has no valid numeric port.

package/dist/{cli-port.js → cli/cli-port.js}

@@ -8,6 +8,27 @@
  * 4. RETICLE_DEFAULT_PORT (4400)
  */
 import { readFileSync } from 'node:fs';
+/**
+ * Ports that belong to a DEV SERVER, not to Reticle's bridge. Next defaults to 3000, Vite to 5173,
+ * Astro to 4321, and so on.
+ *
+ * `.reticle.json`'s `port` is the bridge — the daemon ↔ SDK channel, default 4400 — and it has
+ * nothing to do with the port the app is served on. Setting it to the dev-server port makes the
+ * daemon try to bind the port the app already holds; what the user sees is either a bind failure or
+ * a daemon that never connects, neither of which mentions the actual mistake. The old setup skill
+ * asked "what port does your dev server run on?" a few lines before showing this field, which is how
+ * the confusion got manufactured in the first place.
+ */
+export const DEV_SERVER_PORTS = new Set([
+    3000, 3001, 4200, 4321, 5000, 5173, 5174, 8000, 8080, 8100, 9000,
+]);
+export function isLikelyDevServerPort(port) {
+    return DEV_SERVER_PORTS.has(port);
+}
+/** The warning printed when a project pins the bridge to something that looks like its dev server. */
+export function devServerPortWarning(port) {
+    return `[reticle] .reticle.json sets "port": ${port}, which is a common DEV-SERVER port. That field is the Reticle BRIDGE port (default 4400), not the port your app is served on — they must be different, or the daemon fights your dev server for it. Remove "port" unless you are running several apps at once.`;
+}
 /**
  * Read the port stored in the project's .reticle.json (written by `reticle init`).
  * Returns undefined if the file is absent, unreadable, or has no valid numeric port.
@@ -16,9 +37,9 @@ export function readProjectPort(cwd) {
     try {
         const raw = readFileSync(`${cwd}/.reticle.json`, 'utf8');
         const config = JSON.parse(raw);
-        if (typeof config === 'object' && config !== null) {
+        if ('object' === typeof config && config !== null) {
             const p = config['port'];
-            if (typeof p === 'number' && Number.isInteger(p) && p > 0 && p < 65536)
+            if ('number' === typeof p && Number.isInteger(p) && p > 0 && p < 65536)
                 return p;
         }
     }
@@ -36,9 +57,9 @@ export function readProjectId(cwd) {
     try {
         const raw = readFileSync(`${cwd}/.reticle.json`, 'utf8');
         const config = JSON.parse(raw);
-        if (typeof config === 'object' && config !== null) {
+        if ('object' === typeof config && config !== null) {
             const id = config['projectId'];
-            if (typeof id === 'string' && id.length > 0)
+            if ('string' === typeof id && id.length > 0)
                 return id;
         }
     }
@@ -55,16 +76,16 @@ export function readProjectId(cwd) {
 export function readJournalEnabled(cwd, env) {
     if (env !== undefined) {
         const v = env.trim().toLowerCase();
-        if (v === '0' || v === 'false' || v === 'off')
+        if ('0' === v || 'false' === v || 'off' === v)
             return false;
-        if (v === '1' || v === 'true' || v === 'on')
+        if ('1' === v || 'true' === v || 'on' === v)
             return true;
     }
     try {
         const raw = readFileSync(`${cwd}/.reticle.json`, 'utf8');
         const config = JSON.parse(raw);
-        if (typeof config === 'object' && config !== null) {
-            if (config['journal'] === false)
+        if ('object' === typeof config && config !== null) {
+            if (false === config['journal'])
                 return false;
         }
     }

package/dist/cli/cli-update-commands.d.ts

@@ -0,0 +1,4 @@
+/** `reticle update` — install the latest server version, sync the app's SDK, and restart. */
+export declare function handleUpdate(): Promise<void>;
+/** `reticle rollback` — restore the previous server version and restart. */
+export declare function handleRollback(): Promise<void>;

package/dist/cli/cli-update-commands.js

@@ -0,0 +1,93 @@
+/**
+ * The self-update command pair — `reticle update` and `reticle rollback`.
+ *
+ * Split out of cli.ts, which sits at the 600-line cap: these two are one cohesive unit (swap the
+ * installed version, restart) and the file they came from is the CLI's dispatch table, which grows
+ * for entirely different reasons.
+ */
+import { checkForUpdate } from '../update/update-checker.js';
+import { updateTarget } from '../update/update-nudge.js';
+import { applyUpdate, rollback } from '../update/updater.js';
+import { SERVER_VERSION } from '../version/server-version.js';
+import { log } from '../log.js';
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { reticleDepsOf, sdkSyncCommand } from '../update/sdk-sync.js';
+import { detectPackageManager } from '../init/detect.js';
+import { buildNodeIo } from '../init/node-io.js';
+/**
+ * Bring the SDK in the CURRENT project to the version being installed.
+ *
+ * Best-effort and non-fatal on purpose: `reticle update` is run from wherever the human happens to
+ * be, which is often not an app at all. A directory with no manifest, or one that has none of our
+ * packages, simply has nothing to sync — that is a normal outcome, not a failure, and it must never
+ * stop the CLI half from happening.
+ */
+function syncProjectSdk(target) {
+    const cwd = process.cwd();
+    let manifest;
+    try {
+        manifest = JSON.parse(readFileSync(join(cwd, 'package.json'), 'utf8'));
+    }
+    catch {
+        return; // not an app directory
+    }
+    const packages = reticleDepsOf(manifest);
+    const io = buildNodeIo(cwd);
+    const pm = detectPackageManager(new Set(io.rootFiles()), new Set(io.listDirs('node_modules')));
+    const cmd = sdkSyncCommand(pm, packages, target);
+    if (null === cmd) {
+        log('reticle_update_sdk', { synced: false, reason: 'no @reticlehq packages in this project' });
+        return;
+    }
+    const ok = io.exec(cmd.command, cmd.args);
+    log('reticle_update_sdk', { synced: ok, packages, to: target, packageManager: pm });
+    if (!ok) {
+        log('reticle_update_sdk_failed', {
+            hint: `run \`${cmd.command} ${cmd.args.join(' ')}\` by hand, then restart the dev server`,
+        });
+    }
+}
+/** `reticle update` — install the latest server version, sync the app's SDK, and restart. */
+export async function handleUpdate() {
+    try {
+        const manifest = await checkForUpdate(SERVER_VERSION, () => Date.now());
+        // Direction, not inequality: the registry being DIFFERENT is not the registry being newer, and
+        // the old gate happily installed a downgrade — reported by a user. See updateTarget.
+        const target = updateTarget(manifest);
+        if (target === undefined) {
+            log('reticle_update', {
+                ok: false,
+                message: 'already on the latest version',
+                version: SERVER_VERSION,
+            });
+            return;
+        }
+        log('reticle_update', { ok: true, from: SERVER_VERSION, to: target });
+        // The app's SDK FIRST, then the CLI. `reticle update` used to swap only the CLI, so the command
+        // whose job is keeping an install current was itself a way to produce a version-skewed pair —
+        // and the skew message told people to run it to fix an outdated SDK, which it could not do.
+        //
+        // Before the CLI swap because `applyUpdate` never returns (it execs and exits). If this half
+        // fails the daemon is still the older one, which is the direction the HELLO check names clearly
+        // and a re-run fixes; the reverse would leave a new daemon talking to an old page.
+        syncProjectSdk(target);
+        await applyUpdate(target); // calls process.exit; Claude Code restarts
+    }
+    catch (error) {
+        log('reticle_update_failed', { error: error instanceof Error ? error.message : String(error) });
+        process.exitCode = 1;
+    }
+}
+/** `reticle rollback` — restore the previous server version and restart. */
+export async function handleRollback() {
+    try {
+        await rollback(); // calls process.exit
+    }
+    catch (error) {
+        log('reticle_rollback_failed', {
+            error: error instanceof Error ? error.message : String(error),
+        });
+        process.exitCode = 1;
+    }
+}