@reticlehq/server 3.5.0 → 3.7.0

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

@@ -3,102 +3,18 @@
  * The parser stays pure and unit-testable; `cli.ts` owns the side-effecting handlers and dispatch,
  * and re-exports this surface.
  */
-import { TutorialAudience } from './tutorial.js';
 import { parseFeedbackArgs } from './cli-parse-feedback.js';
 import { parseVerifySuffix } from './cli-parse-verify.js';
-import { HEADED_FLAG, PORT_FLAG, VERIFY_COMMAND, missingOperand, missingValue, notANumber, retiredFlag, unknownArgument, } from './cli-parse-grammar.js';
+import { HEADED_FLAG, PORT_FLAG, VERIFY_COMMAND, missingOperand, missingValue, notANumber, retiredFlag, unknownArgument, CLOUD_COMMANDS, REMOVED_COMMANDS, removedNote, } from './cli-parse-grammar.js';
 // Re-exported because the daemon's own argv builder reaches for these through this module, which is
 // where the grammar has always lived as far as every caller is concerned.
 export { HEADED_FLAG, PORT_FLAG };
 import { FORCE_FLAG } from './cli-kill.js';
 // Re-exported so every existing importer of these flags is unaffected by the file split.
 export { AGENT_FLAG, BUG_FLAG, FEEDBACK_KINDS, KIND_FLAG, RATING_FLAG, } from './cli-parse-feedback.js';
-/**
- * The lines below say `reticle <command>`, which is the bin this package installs and is correct
- * once it is on PATH. Copied into `npx`, it is not: `npx reticle` resolves the PACKAGE named
- * `reticle`, which belongs to somebody else, and npx will happily fetch and run it. The docs were
- * telling readers to do exactly that on 110 lines before it was caught, so the invocation now leads
- * the usage block rather than being a footnote somewhere else.
- */
-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] [--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
-                from an agent as reticle_verify { action: "explore", persona: "…" }
-                --app picks WHICH app in a monorepo, when several are found
-                --env is what the app needs to reach a usable state: the key from
-                .env.example, the mock backend, the variable that skips an auth wall.
-                Repeatable, and a value may contain spaces and equals signs
-                --files-only writes the files and stops, which is what init did before it
-                learned to boot the app and prove the install works
-                --relaunch prints the exact command that restarts THIS conversation with
-                the tools loaded, so the restart is not a chore handed to a human. It
-                refuses when the session id has no transcript behind it, because
-                --resume on an empty id opens a blank conversation that looks like
-                success. Works with --files-only
-                --license writes the key to .env and keeps .env out of git
-                --json puts the result on stdout, so an agent reads one object
-                --no-open / --no-agents / --url / --timeout are the runtime dials: CI, a
-                headless box, or an app you already run
-                --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]                    (stop the daemon we started, by its recorded pid)
-  reticle kill  [--port N] [--force]                   (free the port by its LISTENER, never the agent's mcp proxy)
-  reticle restart [--port N] [--force]                 (kill, then start a daemon and wait for a real bind)
-  reticle status [--port N] [--json]                   (a readable block; --json for the event)
-  reticle doctor [--port N]                            (one command to diagnose setup: Chromium, daemon, port)
-  reticle open  [url] [--port N]                        (show the app: reuse the connected tab, else open one)
-  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>' | --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>] [--accept-coverage] [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 setup mcp                                    (register the MCP server with your agents; the installer's registration half)
-  reticle capsules                                     (list the saved fail-to-pass bug capsules in .reticle/capsules)
-  reticle hunt <dir>                                   (aggregate a directory of crawl reports into one false-green rate)
-  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)
-  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)
-  reticle telemetry [status|enable|disable]            (anonymous usage metrics; status shows what's sent + the policy)
-  reticle feedback [--rating 1-5] [--bug] "message"    (tell us what worked and what didn't; prints exactly what it sends)
-  reticle feedback --agent --kind <bug|gap|ambiguity|feature_request|improvement|experience> "message"
-                                                       (agents: file from anywhere, including a setup that never finished)
-  reticle identify --context company|side_project|open_source|learning [--company N] [--email E] [--forget]
-                                                       (OPT-IN: tell us who you are, e.g. for support or an enterprise trial)
-
-Cloud (link this project to Reticle; runs/flows recorded on the dashboard):
-  reticle connect [--project <name|id>] [--url <cloud origin>]
-                                                       (wire this app if needed, sign in, link, send local history)
-  reticle login [--url <u>] [--email <e>] [--code <c>] [--org <n>]
-                                                       (browser device flow by default; --email mails a code)
-  reticle logout [--url <u>]                           (sign out of ONE host; others stay signed in)
-  reticle link  [--project <name|id>]                  (bind this repo: mints a scoped key, writes .reticle/cloud.json)
-  reticle whoami                                        (who am I signed in as, and is this repo attached?)
-  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 | sync [--watch]                        (one sync cycle: send the difference, collect decisions)
-  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.`;
+// The help text lives on its own page; re-exported so every importer of it is unaffected.
+import { CLI_USAGE } from './cli-usage.js';
+export { CLI_USAGE };
 const INIT_COMMAND = 'init';
 const SERVE_COMMAND = 'serve';
 const STOP_COMMAND = 'stop';
@@ -108,16 +24,15 @@ const STATUS_COMMAND = 'status';
 const OPEN_COMMAND = 'open';
 const DRIVE_COMMAND = 'drive';
 const AFFECTED_COMMAND = 'affected';
-const HUNT_COMMAND = 'hunt';
-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';
 const ACCEPT_COVERAGE_FLAG = '--accept-coverage';
 /** `reticle report [--session <id>] [--hook]` — what the latest session claimed, and what held. */
 const REPORT_COMMAND = 'report';
+/** `reticle context --compact`: the resume block, from disk. A SessionStart hook prints it. */
+const CONTEXT_COMMAND = 'context';
 const SESSION_FLAG = '--session';
-const WATCH_COMMAND = 'watch';
 const UPDATE_COMMAND = 'update';
 const ROLLBACK_COMMAND = 'rollback';
 const MCP_COMMAND = 'mcp';
@@ -125,11 +40,8 @@ const LICENSE_COMMAND = 'license';
 const VERSION_COMMAND = 'version';
 const TELEMETRY_COMMAND = 'telemetry';
 const FEEDBACK_COMMAND = 'feedback';
-const IDENTIFY_COMMAND = 'identify';
-const COMPANY_FLAG = '--company';
-const EMAIL_FLAG = '--email';
-const CONTEXT_FLAG = '--context';
-const FORGET_FLAG = '--forget';
+const DOCTOR_COMMAND = 'doctor';
+const SETUP_COMMAND = 'setup';
 /** The `reticle telemetry` sub-actions. Bare `reticle telemetry` means `status`. */
 export const TelemetryAction = {
     STATUS: 'status',
@@ -147,7 +59,10 @@ export const DAEMON_INNER_COMMAND = '_daemon';
  * defined; a second list somewhere else would drift the first time a command is added.
  */
 export const UNKNOWN_COMMAND = 'unknown';
-const KNOWN_COMMANDS = new Set([
+const HELP_COMMAND = 'help';
+const HELP_FLAGS = new Set(['--help', '-h']);
+/** Every command the typed parser below routes. The parser refuses any word not in this list. */
+export const LOCAL_COMMANDS = [
     INIT_COMMAND,
     SERVE_COMMAND,
     STOP_COMMAND,
@@ -158,11 +73,9 @@ const KNOWN_COMMANDS = new Set([
     DRIVE_COMMAND,
     VERIFY_COMMAND,
     AFFECTED_COMMAND,
-    HUNT_COMMAND,
-    CAPSULES_COMMAND,
     GATE_COMMAND,
     REPORT_COMMAND,
-    WATCH_COMMAND,
+    CONTEXT_COMMAND,
     UPDATE_COMMAND,
     ROLLBACK_COMMAND,
     MCP_COMMAND,
@@ -170,25 +83,23 @@ const KNOWN_COMMANDS = new Set([
     VERSION_COMMAND,
     TELEMETRY_COMMAND,
     FEEDBACK_COMMAND,
-    IDENTIFY_COMMAND,
     DAEMON_INNER_COMMAND,
-    'connect',
-    'login',
-    'logout',
-    'whoami',
-    'link',
-    'project',
-    'config',
-    'push',
-    'runs',
-    'issues',
-    'memory',
-    'regression',
-    'share',
-    'doctor',
-    'setup',
-    'tutorial',
-    'help',
+    DOCTOR_COMMAND,
+    SETUP_COMMAND,
+];
+const LOCAL_COMMAND_SET = new Set(LOCAL_COMMANDS);
+const KNOWN_COMMANDS = new Set([
+    ...LOCAL_COMMANDS,
+    ...CLOUD_COMMANDS,
+    ...REMOVED_COMMANDS.keys(),
+    HELP_COMMAND,
+]);
+/** The conventional flag spellings of two commands, reported as the command they ask for. */
+const COMMAND_FLAG_ALIASES = new Map([
+    ['--version', VERSION_COMMAND],
+    ['-v', VERSION_COMMAND],
+    ['--help', HELP_COMMAND],
+    ['-h', HELP_COMMAND],
 ]);
 /**
  * A non-negative integer flag, or 0.
@@ -207,15 +118,15 @@ function numberFlag(args, name) {
 /** The subcommand name if we recognize it, else `unknown`. Bare `reticle` reports `help`. */
 export function knownCommand(arg) {
     if (arg === undefined || '' === arg)
-        return 'help';
-    return KNOWN_COMMANDS.has(arg) ? arg : UNKNOWN_COMMAND;
+        return HELP_COMMAND;
+    return KNOWN_COMMANDS.has(arg) ? arg : (COMMAND_FLAG_ALIASES.get(arg) ?? UNKNOWN_COMMAND);
 }
 /**
  * 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 HEADLESS_FLAG = '--headless';
 export const DRIVE_FLAG = '--drive';
 const QUIET_FLAG = '--quiet';
 const DRY_RUN_FLAG = '--dry-run';
@@ -236,6 +147,8 @@ const FLOW_FLAG = '--flow';
 const FIRST_RUN_MOVED = 'onboarding wires the project, the FIRST RUN proves a flow. Drive one with reticle_verify { action: "explore", persona: "<who does what>" }, or npx @reticlehq/server verify <url> --explore --persona "<who does what>"';
 const ENV_FLAG = '--env';
 const FILES_ONLY_FLAG = '--files-only';
+/** With `--app`, also start the app: naming one app of a workspace otherwise writes its files only. */
+const START_FLAG = '--start';
 /**
  * Write `captureNetworkBodies: true` into the app's config. OFF unless asked (#705).
  *
@@ -256,6 +169,8 @@ const HOOKS_FLAG = '--hooks';
 const JSON_FLAG = '--json';
 const NO_DRIVE_FLAG = '--no-drive';
 const NO_OPEN_FLAG = '--no-open';
+/** Connect and stop: no coverage summary and no prompt at the end. */
+const NO_FIRST_RUN_FLAG = '--no-first-run';
 const NO_AGENTS_FLAG = '--no-agents';
 /**
  * Restart the calling client so IT gets the tools.
@@ -281,12 +196,6 @@ 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';
-/**
- * `serve` / `mcp` / `_daemon` own the browser POOL, which backs automated work — leased contexts for
- * parallel agents, flow replay, the spec runner. Those are batch: nobody is watching, and launching
- * them headed changed timing enough to break four e2e specs. The headed default belongs to the
- * INTERACTIVE command (`drive`), where a human asked to see the run. `--headed` still opts in here.
- */
 /**
  * A usage error names the thing that was wrong.
  *
@@ -307,10 +216,10 @@ const unknownCommand = (command) => ({
     kind: 'error',
     message: `unknown command '${command}'`,
 });
-function parseServeFlags(args, defaultPort, _defaultHeadless) {
+function parseServeFlags(args, defaultPort, defaultHeadless) {
     let port = defaultPort;
     let driveUrl;
-    let headless = true;
+    let headless = defaultHeadless;
     let http = false;
     let httpPort;
     let httpToken;
@@ -427,10 +336,12 @@ function parseInitFlags(args) {
     // Repeatable: one variable per flag, so a value containing spaces or `=` needs no quoting rules.
     const env = [];
     let filesOnly = false;
+    let start = false;
     let captureBodies = false;
     let hooks = false;
     let json = false;
     let open = true;
+    let firstRun = true;
     let relaunch = false;
     let agents = true;
     let url;
@@ -473,6 +384,9 @@ function parseInitFlags(args) {
         else if (arg === FILES_ONLY_FLAG) {
             filesOnly = true;
         }
+        else if (arg === START_FLAG) {
+            start = true;
+        }
         else if (arg === CAPTURE_BODIES_FLAG) {
             captureBodies = true;
         }
@@ -485,6 +399,9 @@ function parseInitFlags(args) {
         else if (arg === NO_OPEN_FLAG) {
             open = false;
         }
+        else if (arg === NO_FIRST_RUN_FLAG) {
+            firstRun = false;
+        }
         else if (arg === RELAUNCH_FLAG) {
             relaunch = true;
         }
@@ -540,11 +457,14 @@ function parseInitFlags(args) {
         install,
         app,
         env,
-        filesOnly,
+        // One app of a workspace, named: its files, and nothing started unless asked (`--start`). Its
+        // dev server is often run from the root, and a monorepo init started the daemon and failed it.
+        filesOnly: filesOnly || (app !== undefined && !start),
         captureBodies,
         hooks,
         json,
         open,
+        firstRun,
         relaunch,
         agents,
         url,
@@ -592,8 +512,6 @@ function parseTargetArgs(rest) {
 export function dialsTheDaemon(parsed) {
     if ('init' === parsed.kind)
         return false;
-    if ('tutorial' === parsed.kind)
-        return parsed.run;
     return 'port' in parsed;
 }
 /**
@@ -603,9 +521,9 @@ export function dialsTheDaemon(parsed) {
  *   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.
+    // Bare `reticle` is `serve`.
     if (0 === argv.length)
-        return { kind: 'serve', port: defaultPort, headless: true, http: false };
+        return { kind: 'serve', port: defaultPort, headless: defaultHeadless, 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)
@@ -623,9 +541,22 @@ export function parseCliArgs(argv, defaultPort, defaultHeadless = false) {
     // `reticle_usage_error: unknown argument '--help'` on stderr with exit 1. The usage text was
     // printed underneath it, so the request was in fact answered; it was simply answered as a failure,
     // which is the wrong first impression to give somebody who has just asked a tool what it does.
-    if ('help' === cmd || argv.some((arg) => '--help' === arg || '-h' === arg)) {
-        return { kind: 'help' };
+    //
+    // Removed commands answer before help does: `reticle hunt --help` should say it is gone, not
+    // describe something that no longer runs.
+    const removed = REMOVED_COMMANDS.get(cmd);
+    if (removed !== undefined)
+        return { kind: 'removed', message: removedNote(cmd, removed) };
+    if (HELP_COMMAND === cmd || HELP_FLAGS.has(cmd)) {
+        // `reticle help all`, `reticle --help all`, `reticle help init`.
+        const topic = rest.find((arg) => !HELP_FLAGS.has(arg));
+        return topic === undefined ? { kind: 'help' } : { kind: 'help', topic };
     }
+    if (argv.some((arg) => HELP_FLAGS.has(arg)))
+        return { kind: 'help', topic: cmd };
+    // The list is the gate, so a command cannot be routed without also being named in telemetry.
+    if (!LOCAL_COMMAND_SET.has(cmd))
+        return unknownCommand(cmd);
     switch (cmd) {
         case INIT_COMMAND: {
             const r = parseInitFlags(rest);
@@ -644,6 +575,7 @@ export function parseCliArgs(argv, defaultPort, defaultHeadless = false) {
                 hooks: r.hooks,
                 json: r.json,
                 open: r.open,
+                firstRun: r.firstRun,
                 relaunch: r.relaunch,
                 agents: r.agents,
                 url: r.url,
@@ -667,6 +599,10 @@ export function parseCliArgs(argv, defaultPort, defaultHeadless = false) {
         }
         case STOP_COMMAND: {
             const port = parsePortFlag(rest, defaultPort);
+            // `stop --force` is what `kill` was: free the port by its listener, which must still be a
+            // Reticle daemon. Overriding that refusal stays on `restart --force` and the old `kill --force`.
+            if (rest.includes(FORCE_FLAG))
+                return { kind: 'kill', port, force: false };
             const quiet = rest.includes(QUIET_FLAG);
             return { kind: 'stop', port, quiet };
         }
@@ -685,22 +621,7 @@ export function parseCliArgs(argv, defaultPort, defaultHeadless = false) {
             // parsing it knows to ask for the object.
             return { kind: 'status', port, json: rest.includes(JSON_FLAG) };
         }
-        case 'tutorial': {
-            // `--agent` is the opt-in, because a person typing this is the common case and should not have
-            // to ask for prose. An agent knows to pass the flag; a human would not know to avoid it.
-            const audience = argv.includes('--agent') ? TutorialAudience.AGENT : TutorialAudience.HUMAN;
-            // `--run` drives the demo instead of describing it. Opt-in rather than the default: the tour
-            // starts a daemon and opens a browser, and a command that did that to somebody who typed it
-            // expecting a page of text would be a surprise in the one place surprises are least welcome.
-            return {
-                kind: 'tutorial',
-                audience,
-                run: argv.includes('--run'),
-                port: parsePortFlag(rest, defaultPort),
-                headless: !argv.includes('--headed'),
-            };
-        }
-        case 'doctor': {
+        case DOCTOR_COMMAND: {
             const port = parsePortFlag(rest, defaultPort);
             return { kind: 'doctor', port };
         }
@@ -716,7 +637,7 @@ export function parseCliArgs(argv, defaultPort, defaultHeadless = false) {
          * no flag: it tells a reader a confirmation exists. What this writes is stated before it runs
          * and printed after, which is the honest version of the same reassurance.
          */
-        case 'setup': {
+        case SETUP_COMMAND: {
             const what = rest[0];
             /*
              * `setup install` — the Node half of the one-line installer.
@@ -737,7 +658,7 @@ export function parseCliArgs(argv, defaultPort, defaultHeadless = false) {
             // Only `mcp` today. A bare `reticle setup` falls to help rather than guessing, because the
             // next subcommand here will not be a synonym for this one.
             if (what !== 'mcp')
-                return { kind: 'help' };
+                return { kind: 'help', topic: SETUP_COMMAND };
             return { kind: 'setup-mcp' };
         }
         case LICENSE_COMMAND:
@@ -751,22 +672,6 @@ export function parseCliArgs(argv, defaultPort, defaultHeadless = false) {
             }
             return { kind: 'telemetry', action };
         }
-        case IDENTIFY_COMMAND: {
-            const flag = (name) => {
-                const at = rest.indexOf(name);
-                return -1 === at ? undefined : rest[at + 1];
-            };
-            const context = flag(CONTEXT_FLAG);
-            const company = flag(COMPANY_FLAG);
-            const email = flag(EMAIL_FLAG);
-            return {
-                kind: 'identify',
-                ...(context !== undefined ? { context } : {}),
-                ...(company !== undefined ? { company } : {}),
-                ...(email !== undefined ? { email } : {}),
-                forget: rest.includes(FORGET_FLAG),
-            };
-        }
         case FEEDBACK_COMMAND:
             return parseFeedbackArgs(rest);
         case OPEN_COMMAND: {
@@ -812,16 +717,10 @@ export function parseCliArgs(argv, defaultPort, defaultHeadless = false) {
                 ...(true === r.explore ? { explore: true } : {}),
                 ...(r.persona !== undefined ? { persona: r.persona } : {}),
                 ...(r.select !== undefined ? { select: r.select } : {}),
+                ...(r.resultsJson !== undefined ? { resultsJson: r.resultsJson } : {}),
+                ...(true === r.confirmDangerous ? { confirmDangerous: true } : {}),
             };
         }
-        case CAPSULES_COMMAND:
-            return { kind: 'capsules' };
-        case HUNT_COMMAND: {
-            const dir = rest.find((a) => !a.startsWith('-'));
-            return dir === undefined
-                ? { kind: 'error', message: 'usage: reticle hunt <dir-of-crawl-reports>' }
-                : { kind: 'hunt', dir };
-        }
         case AFFECTED_COMMAND: {
             const t = parseTargetArgs(rest);
             const since = t.since ?? implicitSince(t.files);
@@ -850,10 +749,11 @@ export function parseCliArgs(argv, defaultPort, defaultHeadless = false) {
                 ...(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('-'));
-            return url === undefined ? { kind: 'watch' } : { kind: 'watch', url };
+        case CONTEXT_COMMAND: {
+            // `--compact` is the only form; accepted so the hook line reads as what it does.
+            const at = rest.indexOf(SESSION_FLAG);
+            const session = -1 === at ? undefined : rest[at + 1];
+            return { kind: 'context', ...(session === undefined ? {} : { session }) };
         }
         case UPDATE_COMMAND:
             return { kind: 'update' };

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

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

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

@@ -6,15 +6,43 @@
  * for entirely different reasons.
  */
 import { checkForUpdate } from '../update/update-checker.js';
-import { updateTarget } from '../update/update-nudge.js';
+import { isNewerVersion, updateTarget } from '../update/update-nudge.js';
 import { applyUpdate, rollback } from '../update/updater.js';
-import { refreshAgentRules, detectPackageManager, buildNodeIo, SILENT_HOST } from '@reticlehq/init';
+import { refreshAgentRules, detectPackageManager, buildNodeIo, enclosingWorkspaceRoot, SILENT_HOST, } from '@reticlehq/init';
 import { SERVER_VERSION } from '../version/identity/server-version.js';
 import { log } from '../../log.js';
 import { readFileSync, writeFileSync, existsSync } from 'node:fs';
 import { join } from 'node:path';
 import { reticleDepsOf, sdkSyncCommand } from '../update/sdk-sync.js';
+import { installedSdkVersion, readTextFile } from './launch/sdk-version-match.js';
 const WINDOWS_MANUAL_UPDATE = 'irm https://raw.githubusercontent.com/reticlehq/reticle/main/install/install.ps1 | iex';
+/**
+ * What a person reads. `log` lines are JSON on stderr for the daemon's log, and a human running
+ * `reticle update` in a terminal used to see nothing else — not even that the restart was theirs.
+ */
+const MSG_SDK_SYNCED = (version) => `Updated this app's Reticle SDK to ${version}. Now restart your dev server and reload the tab: ` +
+    'a running dev server keeps serving the old SDK, overlay included.';
+const MSG_SDK_SYNC_FAILED = (command) => `Could not update this app's Reticle SDK. Run \`${command}\`, then restart your dev server.`;
+const MSG_SDK_LINKED = 'This app links its Reticle packages locally, so `reticle update` leaves them as they are.';
+/** Dependency specs that point at a local copy, not the registry: rewriting one to a pin breaks it. */
+const LOCAL_SPEC = /^(workspace|link|file|portal):/;
+function linksLocally(manifest, packages) {
+    if ('object' !== typeof manifest || null === manifest)
+        return false;
+    const m = manifest;
+    return packages.some((name) => ['dependencies', 'devDependencies'].some((field) => {
+        const deps = m[field];
+        if ('object' !== typeof deps || null === deps)
+            return false;
+        const spec = deps[name];
+        return 'string' === typeof spec && LOCAL_SPEC.test(spec);
+    }));
+}
+const MSG_NO_SDK_HERE = "No Reticle SDK in this folder, so only the CLI was checked. Run `reticle update` in your app's " +
+    'folder to bring its SDK up too.';
+function say(line) {
+    process.stdout.write(`${line}\n`);
+}
 /**
  * Bring the SDK in the CURRENT project to the version being installed.
  *
@@ -23,41 +51,65 @@ const WINDOWS_MANUAL_UPDATE = 'irm https://raw.githubusercontent.com/reticlehq/r
  * 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();
+function syncProjectSdk(target, cwd) {
     let manifest;
     try {
         manifest = JSON.parse(readFileSync(join(cwd, 'package.json'), 'utf8'));
     }
     catch {
+        say(MSG_NO_SDK_HERE);
         return; // not an app directory
     }
     const packages = reticleDepsOf(manifest);
+    if (linksLocally(manifest, packages)) {
+        say(MSG_SDK_LINKED);
+        return;
+    }
     // Nothing to trace and nothing to report: this reads the manifest and runs one package-manager
     // command. It never enters `runInit`, so there is no init outcome for a host to carry.
     const io = buildNodeIo(cwd, SILENT_HOST);
-    const pm = detectPackageManager(new Set(io.rootFiles()), new Set(io.listDirs('node_modules')));
+    // A workspace member keeps its lockfile at the workspace root: read both, or an app in a pnpm
+    // workspace looks lockfile-less and is installed with npm.
+    const workspace = enclosingWorkspaceRoot(cwd, io);
+    const rootIo = workspace === undefined ? io : buildNodeIo(workspace, SILENT_HOST);
+    const pm = detectPackageManager(new Set([...io.rootFiles(), ...rootIo.rootFiles()]), new Set([...io.listDirs('node_modules'), ...rootIo.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' });
+        say(MSG_NO_SDK_HERE);
         return;
     }
     const ok = io.exec(cmd.command, cmd.args);
     log('reticle_update_sdk', { synced: ok, packages, to: target, packageManager: pm });
     if (!ok) {
+        const line = `${cmd.command} ${cmd.args.join(' ')}`;
         log('reticle_update_sdk_failed', {
-            hint: `run \`${cmd.command} ${cmd.args.join(' ')}\` by hand, then restart the dev server`,
+            hint: `run \`${line}\` by hand, then restart the dev server`,
         });
+        say(MSG_SDK_SYNC_FAILED(line));
+        return;
     }
+    say(MSG_SDK_SYNCED(target));
 }
 /** `reticle update` — install the latest server version, sync the app's SDK, and restart. */
-export async function handleUpdate() {
+export async function handleUpdate(cwd = process.cwd()) {
     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) {
+            // The CLI being current says nothing about the app. A CLI from the installer or a fresh npx
+            // is on the latest release while the app keeps the SDK `init` pinned months ago, and this
+            // branch used to return before the sync — so the one command that should fix that pair
+            // answered "already on the latest version" and left the old overlay in the page.
+            const installed = installedSdkVersion(cwd, readTextFile);
+            if (installed === undefined)
+                say(MSG_NO_SDK_HERE);
+            // Only UP. A CLI that could not reach the registry also lands here, and an older one must
+            // never pin a newer app back to itself.
+            else if (isNewerVersion(SERVER_VERSION, installed))
+                syncProjectSdk(SERVER_VERSION, cwd);
             log('reticle_update', {
                 ok: false,
                 message: 'already on the latest version',
@@ -76,7 +128,7 @@ export async function handleUpdate() {
         // That is backwards: the people who most need better instructions are the ones already
         // installed and not getting value, and this is the moment they are touching the install anyway.
         // Only files that ALREADY carry the block are touched, and only inside the markers.
-        const refreshed = refreshAgentRules(process.cwd(), {
+        const refreshed = refreshAgentRules(cwd, {
             read: (path) => (existsSync(path) ? readFileSync(path, 'utf8') : null),
             write: (path, content) => {
                 writeFileSync(path, content, 'utf8');
@@ -91,7 +143,7 @@ export async function handleUpdate() {
         // 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);
+        syncProjectSdk(target, cwd);
         await applyUpdate(target); // calls process.exit; Claude Code restarts
     }
     catch (error) {

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

@@ -0,0 +1,33 @@
+/**
+ * The `reticle` help text.
+ *
+ * `reticle --help` is short: the commands a person needs, one line each, in four groups. Every other
+ * command is still there and still works; `reticle help all` lists it, and `reticle <command> --help`
+ * carries the detail that used to sit in the one long page.
+ *
+ * The lines say `reticle <command>`, which is the bin this package installs. Copied into `npx` it is
+ * not: `npx reticle` resolves the PACKAGE named `reticle`, which belongs to somebody else, and npx
+ * will happily fetch and run it. So the npx spelling leads every page.
+ */
+export declare const HelpGroup: {
+    readonly START: "Get started";
+    readonly CHECK: "Check your app";
+    readonly MACHINE: "Reticle on this machine";
+    readonly ACCOUNT: "Account";
+    /** Listed only by `reticle help all`. */
+    readonly MORE: "More commands";
+};
+export type HelpGroup = (typeof HelpGroup)[keyof typeof HelpGroup];
+/** `reticle help all` and `reticle --help all`. */
+export declare const HELP_ALL_TOPIC = "all";
+/** `reticle --help`: printed by `help`, `--help` and under every usage error. */
+export declare const CLI_USAGE: string;
+/** `reticle help all`. */
+export declare const CLI_USAGE_ALL: string;
+/** Every command the help names, for checks that each one really parses. */
+export declare const DOCUMENTED_COMMANDS: readonly string[];
+/**
+ * The help for one topic: the short page, every command, or one command's detail. An old name
+ * answers with the page of the command that replaced it, and says so.
+ */
+export declare function renderHelp(topic: string | undefined, renamed?: ReadonlyMap<string, string>): string;