@reticlehq/server 3.9.0 → 3.10.1

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

@@ -0,0 +1,75 @@
+/**
+ * `reticle grade <snapshot|judge|tables|suggest> [flags]`: grade a finished run of an app from
+ * snapshots of its stored data. The rules are in `@/features/grade/`.
+ */
+import { JSON_FLAG, missingOperand, missingValue, unknownArgument, } from './cli-parse-grammar.js';
+export const GRADE_COMMAND = 'grade';
+export const GradeStep = {
+    SNAPSHOT: 'snapshot',
+    JUDGE: 'judge',
+    TABLES: 'tables',
+    SUGGEST: 'suggest',
+};
+/** Each flag that takes a value, and the field it fills. */
+const VALUE_FLAGS = {
+    '--state': 'state',
+    '--out': 'out',
+    '--url': 'url',
+    '--reference': 'reference',
+    '--again': 'again',
+    '--candidate': 'candidate',
+    '--expect': 'expect',
+    '--answer': 'answer',
+    '--list': 'list',
+    '--rows': 'rows',
+    '--container': 'container',
+    '--skip': 'skip',
+};
+/** The flags each step needs, and the flags it also takes. */
+const STEP_FLAGS = {
+    [GradeStep.SNAPSHOT]: { needs: ['state', 'out'], takes: ['url'] },
+    [GradeStep.JUDGE]: {
+        needs: ['reference', 'again', 'candidate'],
+        takes: ['expect', 'answer'],
+    },
+    [GradeStep.TABLES]: { needs: ['list', 'rows', 'out'], takes: ['container', 'skip'] },
+    [GradeStep.SUGGEST]: { needs: ['state', 'reference', 'again', 'out'], takes: [] },
+};
+const isStep = (word) => Object.values(GradeStep).some((step) => step === word);
+const isValueFlag = (arg) => arg in VALUE_FLAGS;
+const flagOf = (field) => Object.keys(VALUE_FLAGS).find((f) => VALUE_FLAGS[f] === field) ??
+    field;
+export function parseGradeArgs(args) {
+    const [step, ...rest] = args;
+    if (!isStep(step)) {
+        // A known flag before the step is a missing step, not an unknown flag.
+        return step === undefined || isValueFlag(step) || JSON_FLAG === step
+            ? missingOperand(GRADE_COMMAND, `a step first: ${Object.values(GradeStep).join(', ')}`)
+            : unknownArgument(step);
+    }
+    const allowed = new Set([...STEP_FLAGS[step].needs, ...STEP_FLAGS[step].takes]);
+    const values = {};
+    let json = false;
+    for (let i = 0; i < rest.length; i += 1) {
+        const arg = rest[i] ?? '';
+        if (JSON_FLAG === arg && GradeStep.JUDGE === step) {
+            json = true;
+            continue;
+        }
+        if (!isValueFlag(arg) || !allowed.has(VALUE_FLAGS[arg])) {
+            return unknownArgument(arg);
+        }
+        const value = rest[i + 1];
+        // An answer may start with "--"; every other value may not.
+        if (value === undefined || ('--answer' !== arg && value.startsWith('--'))) {
+            return missingValue(arg);
+        }
+        values[VALUE_FLAGS[arg]] = value;
+        i += 1;
+    }
+    const missing = STEP_FLAGS[step].needs.filter((field) => values[field] === undefined);
+    if (missing.length > 0) {
+        return missingOperand(`${GRADE_COMMAND} ${step}`, missing.map(flagOf).join(', '));
+    }
+    return { kind: 'ok', step, json, ...values };
+}

package/dist/command/cli/cli-parse-grammar.d.ts

@@ -26,6 +26,8 @@ export declare const missingOperand: (command: string, what: string) => ParseErr
 /** Show the browser. Shared by every command that can drive one. */
 export declare const HEADED_FLAG = "--headed";
 export declare const PORT_FLAG = "--port";
+/** Print one JSON object. */
+export declare const JSON_FLAG = "--json";
 export declare const VERIFY_COMMAND = "verify";
 /**
  * The predicate flag, shared for the same reason the rest of this file is: two places have to name

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

@@ -36,6 +36,8 @@ export const missingOperand = (command, what) => ({
 /** Show the browser. Shared by every command that can drive one. */
 export const HEADED_FLAG = '--headed';
 export const PORT_FLAG = '--port';
+/** Print one JSON object. */
+export const JSON_FLAG = '--json';
 export const VERIFY_COMMAND = 'verify';
 /**
  * The predicate flag, shared for the same reason the rest of this file is: two places have to name
@@ -49,37 +51,22 @@ export const EXPECT_FLAG = '--expect';
  * that the dispatcher and the telemetry vocabulary read one list instead of two.
  */
 export const CLOUD_COMMANDS = [
-    'login',
     'connect',
     'try',
     'logout',
-    'whoami',
-    'link',
-    'project',
     'config',
-    'issues',
-    'memory',
-    'push',
     'sync',
     'runs',
-    'regression',
-    'share',
 ];
 /**
  * Old command names that still run, for one release, under the name that replaced them. Each one
  * prints a single line saying so, then does what it always did.
  */
 export const RENAMED_COMMANDS = new Map([
-    ['kill', 'stop --force'],
-    ['login', 'connect'],
-    ['link', 'connect'],
-    ['project', 'connect --project <name|id>'],
-    ['whoami', 'status'],
-    ['push', 'sync'],
-    ['regression', 'runs regression'],
-    ['share', 'runs share <runId>'],
-    ['issues', 'runs issues'],
-    ['memory', 'runs memory'],
+    ['affected', 'gate --list'],
+    ['license', 'status'],
+    ['rollback', 'update --rollback'],
+    ['restart', 'serve --restart'],
 ]);
 const HELP_FLAGS = new Set(['--help', '-h']);
 /**
@@ -98,13 +85,24 @@ export function renamedCommandFor(argv) {
  */
 export const REMOVED_COMMANDS = new Map([
     ['hunt', 'it has no replacement'],
-    ['watch', 'use `reticle affected` after you save, or `reticle gate` before you commit'],
+    ['watch', 'use `reticle gate --list` after you save, or `reticle gate` before you commit'],
     ['capsules', 'it has no replacement; saved capsules stay in .reticle/capsules'],
     ['tutorial', "use `reticle init` in your app's folder, or `reticle try <url>`"],
     [
         'identify',
         'it has no replacement; delete ~/.reticle/identity.json to forget a saved identity, and use `reticle feedback` to reach us',
     ],
+    // Renamed one release earlier, and kept for that one release.
+    ['kill', 'use `reticle stop --force`'],
+    ['login', 'use `reticle connect`'],
+    ['link', 'use `reticle connect`'],
+    ['project', 'use `reticle connect --project <name|id>`'],
+    ['whoami', 'use `reticle status`'],
+    ['push', 'use `reticle sync`'],
+    ['regression', 'use `reticle runs regression`'],
+    ['share', 'use `reticle runs share <runId>`'],
+    ['issues', 'use `reticle runs issues`'],
+    ['memory', 'use `reticle runs memory`'],
 ]);
 export const removedNote = (command, instead) => `\`reticle ${command}\` was removed in this version; ${instead}`;
 const DIM = '\u001b[2m';

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

@@ -1,3 +1,9 @@
+/** A missing step 1 control on a freshly loaded start page fails the flow (#2061). */
+export declare const REQUIRE_START_CONTROL_FLAG = "--require-start-control";
+/** Keep judging after a step whose consequence failed, so every step gets a verdict (the score). */
+export declare const SWEEP_FLAG = "--sweep";
+/** Compare the url with this reference build, and report each difference in what users see. */
+export declare const AGAINST_FLAG = "--against";
 export type VerifySuffix = {
     kind: 'ok';
     url: string;
@@ -14,6 +20,10 @@ export type VerifySuffix = {
     select?: string[];
     resultsJson?: string;
     confirmDangerous?: boolean;
+    requireStartControl?: boolean;
+    sweep?: boolean;
+    /** The reference build's url, when the url is to be compared with it. */
+    against?: string;
 } | {
     kind: 'error';
     message: string;

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

@@ -38,6 +38,18 @@ const SELECT_FLAG = '--select';
 const RESULTS_JSON_FLAG = '--results-json';
 /** Acknowledge, for this run only, the steps the replay guard holds as destructive ("Place order"). */
 const CONFIRM_DANGEROUS_FLAG = '--confirm-dangerous';
+/** A missing step 1 control on a freshly loaded start page fails the flow (#2061). */
+export const REQUIRE_START_CONTROL_FLAG = '--require-start-control';
+/** Keep judging after a step whose consequence failed, so every step gets a verdict (the score). */
+export const SWEEP_FLAG = '--sweep';
+/** Compare the url with this reference build, and report each difference in what users see. */
+export const AGAINST_FLAG = '--against';
+/**
+ * `--against` compares two builds with the same actions. A predicate asks another question, and a
+ * model drive does not repeat its actions, so neither can join it.
+ */
+const MSG_AGAINST_ALONE = `${AGAINST_FLAG} compares two builds with the same actions. It cannot be combined with ` +
+    `${EXPECT_FLAG}, ${EXPECT_FILE_FLAG}, ${EXPLORE_FLAG} or ${PERSONA_FLAG}. Run them as two commands.`;
 /**
  * Parse `verify <url> [--port N] [--headed] [--timeout N] [--storage-state <file>]
  * [--session-id <id>]`. The first non-flag token is the preview URL. `defaultPort` is already
@@ -96,54 +108,65 @@ export function parseVerifySuffix(args, defaultPort) {
     const select = [];
     let resultsJson;
     let confirmDangerous = false;
+    let requireStartControl = false;
+    let sweep = false;
+    let against;
     let port = defaultPort;
     let i = 0;
     while (i < args.length) {
         const arg = args[i];
-        if (arg === undefined)
+        if (arg === undefined) {
             break;
+        }
         if (arg === HEADED_FLAG) {
             headless = false;
         }
         else if (arg === PORT_FLAG) {
             i++;
             const n = args[i];
-            if (n === undefined)
+            if (n === undefined) {
                 return missingValue(PORT_FLAG);
+            }
             const parsed = parseInt(n, 10);
-            if (isNaN(parsed))
+            if (isNaN(parsed)) {
                 return notANumber(PORT_FLAG, n);
+            }
             port = parsed;
         }
         else if (arg === TIMEOUT_FLAG) {
             i++;
             const n = args[i];
-            if (n === undefined)
+            if (n === undefined) {
                 return missingValue(TIMEOUT_FLAG);
+            }
             const parsed = parseInt(n, 10);
-            if (isNaN(parsed))
+            if (isNaN(parsed)) {
                 return notANumber(TIMEOUT_FLAG, n);
+            }
             timeoutMs = parsed;
         }
         else if (arg === STORAGE_STATE_FLAG) {
             i++;
             const v = args[i];
-            if (v === undefined)
+            if (v === undefined) {
                 return missingValue(STORAGE_STATE_FLAG);
+            }
             storageState = v;
         }
         else if (arg === SESSION_ID_FLAG) {
             i++;
             const v = args[i];
-            if (v === undefined)
+            if (v === undefined) {
                 return missingValue(SESSION_ID_FLAG);
+            }
             sessionId = v;
         }
         else if (arg === SELECT_FLAG) {
             i++;
             const v = args[i];
-            if (v === undefined)
+            if (v === undefined) {
                 return missingValue(SELECT_FLAG);
+            }
             // Repeatable rather than comma-split: a label is free-form, and a comma inside one would
             // silently become two selections that match nothing.
             select.push(v);
@@ -151,21 +174,37 @@ export function parseVerifySuffix(args, defaultPort) {
         else if (arg === RESULTS_JSON_FLAG) {
             i++;
             const v = args[i];
-            if (v === undefined)
+            if (v === undefined) {
                 return missingValue(RESULTS_JSON_FLAG);
+            }
             resultsJson = v;
         }
+        else if (arg === AGAINST_FLAG) {
+            i++;
+            const v = args[i];
+            if (v === undefined) {
+                return missingValue(AGAINST_FLAG);
+            }
+            against = v;
+        }
         else if (arg === EXPLORE_FLAG) {
             explore = true;
         }
         else if (arg === CONFIRM_DANGEROUS_FLAG) {
             confirmDangerous = true;
         }
+        else if (arg === REQUIRE_START_CONTROL_FLAG) {
+            requireStartControl = true;
+        }
+        else if (arg === SWEEP_FLAG) {
+            sweep = true;
+        }
         else if (arg === PERSONA_FLAG) {
             i++;
             const v = args[i];
-            if (v === undefined)
+            if (v === undefined) {
                 return missingValue(PERSONA_FLAG);
+            }
             // A persona is what to explore AS, so naming one is asking for the drive. Requiring both
             // flags would only give a user a way to say something they cannot mean.
             persona = v;
@@ -174,18 +213,21 @@ export function parseVerifySuffix(args, defaultPort) {
         else if (arg === EXPECT_FLAG) {
             i++;
             const v = args[i];
-            if (v === undefined)
+            if (v === undefined) {
                 return missingValue(EXPECT_FLAG);
+            }
             const read = parseExpect(v);
-            if ('error' === read.kind)
+            if ('error' === read.kind) {
                 return read;
+            }
             expect = read.value;
         }
         else if (arg === EXPECT_FILE_FLAG) {
             i++;
             const v = args[i];
-            if (v === undefined)
+            if (v === undefined) {
                 return missingValue(EXPECT_FILE_FLAG);
+            }
             expectFile = v;
         }
         else if (arg.startsWith('--')) {
@@ -199,8 +241,9 @@ export function parseVerifySuffix(args, defaultPort) {
         }
         i++;
     }
-    if (url === undefined)
+    if (url === undefined) {
         return missingOperand(VERIFY_COMMAND, 'a url');
+    }
     // Two ways to say the same thing, and no way to say two different things. Preferring one
     // silently is how a run asserts something the person did not write.
     if (expect !== undefined && expectFile !== undefined) {
@@ -209,6 +252,9 @@ export function parseVerifySuffix(args, defaultPort) {
             message: `${EXPECT_FLAG} and ${EXPECT_FILE_FLAG} both name the predicate; pass one`,
         };
     }
+    if (against !== undefined && (expect !== undefined || expectFile !== undefined || explore)) {
+        return { kind: 'error', message: MSG_AGAINST_ALONE };
+    }
     // Refused here, where nothing has been bound and no browser exists yet, because the damage this
     // pair does is a verdict taken against the wrong user. A predicate from a file is the same
     // predicate, so it is refused the same way.
@@ -230,5 +276,8 @@ export function parseVerifySuffix(args, defaultPort) {
         ...(select.length > 0 ? { select } : {}),
         ...(resultsJson !== undefined ? { resultsJson } : {}),
         ...(confirmDangerous ? { confirmDangerous } : {}),
+        ...(requireStartControl ? { requireStartControl } : {}),
+        ...(sweep ? { sweep } : {}),
+        ...(against !== undefined ? { against } : {}),
     };
 }

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

@@ -4,6 +4,9 @@
  * and re-exports this surface.
  */
 import { type ParsedFeedback } from './cli-parse-feedback.js';
+import { type VerifySuffix } from './cli-parse-verify.js';
+import { type CompareArgs } from './cli-parse-compare.js';
+import { type GradeArgs } from './cli-parse-grade.js';
 import { DAEMON_INNER_COMMAND } from '../daemon/daemon-argv.js';
 import { HEADED_FLAG, PORT_FLAG } from './cli-parse-grammar.js';
 export { DAEMON_INNER_COMMAND, HEADED_FLAG, PORT_FLAG };
@@ -138,22 +141,21 @@ export type CliResult = {
     port: number;
     driveUrl: string;
     headless: boolean;
-} | {
+} | ({
     kind: 'verify';
-    url: string;
-    headless: boolean;
-    port: number;
-    timeoutMs?: number;
-    storageState?: string;
-    sessionId?: string;
-    expect?: unknown;
-    expectFile?: string;
-    explore?: boolean;
-    persona?: string;
-    select?: string[];
-    resultsJson?: string;
-    confirmDangerous?: boolean;
-} | {
+} & Omit<Extract<VerifySuffix, {
+    kind: 'ok';
+}>, 'kind'>) | ({
+    kind: 'compare';
+} & Omit<Extract<CompareArgs, {
+    kind: 'ok';
+}>, 'kind'>) | ({
+    kind: 'grade';
+} & {
+    args: Extract<GradeArgs, {
+        kind: 'ok';
+    }>;
+}) | {
     kind: 'affected';
     files: string[];
     since?: string;

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

@@ -6,8 +6,10 @@
 import { parseFeedbackArgs } from './cli-parse-feedback.js';
 import { HEADLESS_FLAG, parseServeFlags } from './cli-parse-serve.js';
 import { parseVerifySuffix } from './cli-parse-verify.js';
+import { COMPARE_COMMAND, parseCompareArgs } from './cli-parse-compare.js';
+import { GRADE_COMMAND, parseGradeArgs } from './cli-parse-grade.js';
 import { DAEMON_INNER_COMMAND } from '../daemon/daemon-argv.js';
-import { HEADED_FLAG, PORT_FLAG, VERIFY_COMMAND, missingOperand, missingValue, notANumber, retiredFlag, unknownArgument, CLOUD_COMMANDS, REMOVED_COMMANDS, removedNote, } from './cli-parse-grammar.js';
+import { HEADED_FLAG, JSON_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 { DAEMON_INNER_COMMAND, HEADED_FLAG, PORT_FLAG };
@@ -21,13 +23,18 @@ export { CLI_USAGE };
 const INIT_COMMAND = 'init';
 const SERVE_COMMAND = 'serve';
 const STOP_COMMAND = 'stop';
-const KILL_COMMAND = 'kill';
+/** Kept for one release as `serve --restart`. */
 const RESTART_COMMAND = 'restart';
+/** `serve --restart`: stop the daemon, then start it and wait until it listens. */
+const RESTART_FLAG = '--restart';
 const STATUS_COMMAND = 'status';
 const OPEN_COMMAND = 'open';
 const DRIVE_COMMAND = 'drive';
+/** Kept for one release as `gate --list`. */
 const AFFECTED_COMMAND = 'affected';
 const GATE_COMMAND = 'gate';
+/** `gate --list`: name the saved flows the changes touch, and check nothing. */
+const LIST_FLAG = '--list';
 /** 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';
@@ -37,7 +44,9 @@ const REPORT_COMMAND = 'report';
 const CONTEXT_COMMAND = 'context';
 const SESSION_FLAG = '--session';
 const UPDATE_COMMAND = 'update';
+/** Kept for one release as `update --rollback`. */
 const ROLLBACK_COMMAND = 'rollback';
+const ROLLBACK_FLAG = '--rollback';
 const MCP_COMMAND = 'mcp';
 const LICENSE_COMMAND = 'license';
 const VERSION_COMMAND = 'version';
@@ -80,12 +89,13 @@ export const LOCAL_COMMANDS = [
     INIT_COMMAND,
     SERVE_COMMAND,
     STOP_COMMAND,
-    KILL_COMMAND,
     RESTART_COMMAND,
     STATUS_COMMAND,
     OPEN_COMMAND,
     DRIVE_COMMAND,
     VERIFY_COMMAND,
+    COMPARE_COMMAND,
+    GRADE_COMMAND,
     AFFECTED_COMMAND,
     GATE_COMMAND,
     REPORT_COMMAND,
@@ -179,7 +189,6 @@ const NO_PROMPT_CAPTURE_FLAG = '--no-prompt-capture';
  * and reading one object is one turn where interpreting a report is several. The three opt-outs are
  * what a machine without a browser, or a caller already running their app, actually needs.
  */
-const JSON_FLAG = '--json';
 const NO_DRIVE_FLAG = '--no-drive';
 const NO_OPEN_FLAG = '--no-open';
 /** `reticle open <url> --navigate`: move a tab already on the origin to the url (#1140). */
@@ -550,6 +559,16 @@ export function parseCliArgs(argv, defaultPort, defaultHeadless = false) {
             };
         }
         case SERVE_COMMAND: {
+            if (rest.includes(RESTART_FLAG)) {
+                return {
+                    kind: 'restart',
+                    port: parsePortFlag(rest, defaultPort),
+                    force: rest.includes(FORCE_FLAG),
+                };
+            }
+            if (rest.includes(FORCE_FLAG)) {
+                return { kind: 'error', message: `${FORCE_FLAG} works only with ${RESTART_FLAG}` };
+            }
             const r = parseServeFlags(rest, defaultPort, defaultHeadless);
             if ('error' === r.kind) {
                 return r;
@@ -567,17 +586,13 @@ 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`.
+            // Reticle daemon. Overriding that refusal stays on `serve --restart --force`.
             if (rest.includes(FORCE_FLAG)) {
                 return { kind: 'kill', port, force: false };
             }
             const quiet = rest.includes(QUIET_FLAG);
             return { kind: 'stop', port, quiet };
         }
-        case KILL_COMMAND: {
-            const port = parsePortFlag(rest, defaultPort);
-            return { kind: 'kill', port, force: rest.includes(FORCE_FLAG) };
-        }
         case RESTART_COMMAND: {
             const port = parsePortFlag(rest, defaultPort);
             return { kind: 'restart', port, force: rest.includes(FORCE_FLAG) };
@@ -682,22 +697,21 @@ export function parseCliArgs(argv, defaultPort, defaultHeadless = false) {
             if ('error' === r.kind) {
                 return r;
             }
-            return {
-                kind: 'verify',
-                url: r.url,
-                headless: r.headless,
-                port: r.port,
-                ...(r.timeoutMs !== undefined ? { timeoutMs: r.timeoutMs } : {}),
-                ...(r.storageState !== undefined ? { storageState: r.storageState } : {}),
-                ...(r.sessionId !== undefined ? { sessionId: r.sessionId } : {}),
-                ...(r.expect !== undefined ? { expect: r.expect } : {}),
-                ...(r.expectFile !== undefined ? { expectFile: r.expectFile } : {}),
-                ...(true === r.explore ? { explore: true } : {}),
-                ...(r.persona !== undefined ? { persona: r.persona } : {}),
-                ...(r.select !== undefined ? { select: r.select } : {}),
-                ...(r.resultsJson !== undefined ? { resultsJson: r.resultsJson } : {}),
-                ...(true === r.confirmDangerous ? { confirmDangerous: true } : {}),
-            };
+            // Every parsed field, so a flag the suffix parser reads cannot be lost here.
+            const { kind: _ok, ...fields } = r;
+            return { kind: 'verify', ...fields };
+        }
+        case COMPARE_COMMAND: {
+            const r = parseCompareArgs(rest, defaultPort);
+            if ('error' === r.kind) {
+                return r;
+            }
+            const { kind: _ok, ...fields } = r;
+            return { kind: 'compare', ...fields };
+        }
+        case GRADE_COMMAND: {
+            const r = parseGradeArgs(rest);
+            return 'error' === r.kind ? r : { kind: 'grade', args: r };
         }
         case AFFECTED_COMMAND: {
             const t = parseTargetArgs(rest);
@@ -708,8 +722,11 @@ export function parseCliArgs(argv, defaultPort, defaultHeadless = false) {
             // Flags are stripped before target parsing, which would reject them as unknown.
             const hook = rest.includes(HOOK_FLAG);
             const acceptCoverage = rest.includes(ACCEPT_COVERAGE_FLAG);
-            const t = parseTargetArgs(rest.filter((a) => a !== HOOK_FLAG && a !== ACCEPT_COVERAGE_FLAG));
+            const t = parseTargetArgs(rest.filter((a) => a !== HOOK_FLAG && a !== ACCEPT_COVERAGE_FLAG && a !== LIST_FLAG));
             const since = t.since ?? implicitSince(t.files);
+            if (rest.includes(LIST_FLAG)) {
+                return { kind: 'affected', files: t.files, ...(since === undefined ? {} : { since }) };
+            }
             return {
                 kind: 'gate',
                 files: t.files,
@@ -737,7 +754,7 @@ export function parseCliArgs(argv, defaultPort, defaultHeadless = false) {
             return { kind: 'context', ...(session === undefined ? {} : { session }) };
         }
         case UPDATE_COMMAND:
-            return { kind: 'update' };
+            return rest.includes(ROLLBACK_FLAG) ? { kind: 'rollback' } : { kind: 'update' };
         case ROLLBACK_COMMAND:
             return { kind: 'rollback' };
         case MCP_COMMAND: {

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(cwd?: string): Promise<void>;
-/** `reticle rollback` — restore the previous server version and restart. */
+/** `reticle update --rollback` — restore the previous server version and restart. */
 export declare function handleRollback(): Promise<void>;

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

@@ -1,5 +1,5 @@
 /**
- * The self-update command pair — `reticle update` and `reticle rollback`.
+ * The self-update command pair — `reticle update` and `reticle update --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
@@ -91,6 +91,29 @@ function syncProjectSdk(target, cwd) {
     }
     say(MSG_SDK_SYNCED(target));
 }
+/**
+ * Bring this project's agent rules up with the version.
+ *
+ * The managed block has always been updatable — marker-delimited, idempotent by comparing content —
+ * and nothing called it after the first install. `mergeMarkedInstruction` is reachable from
+ * `buildPlan` alone, so a project set up on an older release kept that release's instructions
+ * forever and every improvement to them reached new projects only.
+ *
+ * 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.
+ */
+function refreshProjectRules(cwd, version) {
+    const refreshed = refreshAgentRules(cwd, {
+        read: (path) => (existsSync(path) ? readFileSync(path, 'utf8') : null),
+        write: (path, content) => {
+            writeFileSync(path, content, 'utf8');
+        },
+    });
+    if (0 !== refreshed.updated.length) {
+        log('reticle_rules_refreshed', { files: refreshed.updated, to: version });
+    }
+}
 /** `reticle update` — install the latest server version, sync the app's SDK, and restart. */
 export async function handleUpdate(cwd = process.cwd()) {
     try {
@@ -103,6 +126,9 @@ export async function handleUpdate(cwd = process.cwd()) {
             // 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.
+            // The same holds for the agent rules: a project on the latest CLI kept the block that its
+            // first `init` wrote, because this branch returned before the refresh (#1948).
+            refreshProjectRules(cwd, SERVER_VERSION);
             const installed = installedSdkVersion(cwd, readTextFile);
             if (installed === undefined)
                 say(MSG_NO_SDK_HERE);
@@ -118,24 +144,7 @@ export async function handleUpdate(cwd = process.cwd()) {
             return;
         }
         log('reticle_update', { ok: true, from: SERVER_VERSION, to: target });
-        // Bring this project's agent rules up with the version.
-        //
-        // The managed block has always been updatable — marker-delimited, idempotent by comparing
-        // content — and nothing called it after the first install. `mergeMarkedInstruction` is reachable
-        // from `buildPlan` alone, so a project set up on an older release kept that release's
-        // instructions forever and every improvement to them reached new projects only.
-        //
-        // 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(cwd, {
-            read: (path) => (existsSync(path) ? readFileSync(path, 'utf8') : null),
-            write: (path, content) => {
-                writeFileSync(path, content, 'utf8');
-            },
-        });
-        if (0 !== refreshed.updated.length)
-            log('reticle_rules_refreshed', { files: refreshed.updated, to: target });
+        refreshProjectRules(cwd, 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.
@@ -157,7 +166,7 @@ export async function handleUpdate(cwd = process.cwd()) {
         process.exitCode = 1;
     }
 }
-/** `reticle rollback` — restore the previous server version and restart. */
+/** `reticle update --rollback` — restore the previous server version and restart. */
 export async function handleRollback() {
     try {
         await rollback(); // calls process.exit