@reticlehq/server 3.6.0 → 3.7.0

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

@@ -5,24 +5,37 @@
  * `credentials.json` (per-project api keys from `reticle link`). The non-secret repo binding + sync policy
  * is `<repo>/.reticle/cloud.json`. Auth for a command = `RETICLE_API_KEY` env (agent) OR the login token.
  */
+import { CreatedProjectSchema } from './project-name.js';
+import { keyRefusalAtLastSync } from '../../memory/project/sync-status.js';
 import { apiKeyFrom } from '@reticlehq/core';
-import { mkdir, writeFile } from 'node:fs/promises';
+import { PlatformLinkVia } from '@reticlehq/core/telemetry';
+import { existsSync } from 'node:fs';
+import { writeFile } from 'node:fs/promises';
 import { setTimeout as sleep } from 'node:timers/promises';
 import { homedir } from 'node:os';
-import { basename, join } from 'node:path';
+import { join } from 'node:path';
 import { z } from 'zod';
 import { createNodeFileSystem } from '../../memory/project/fs/fs-port.js';
 import { CLOUD_LINK_FILE, resolveProjectCloud } from '../../memory/cloud/cloud-config.js';
 import { memoryReadUrl, MemoryResponseScope, scopeMemoryResponse, scopeOfMemoryResponse, } from '../../memory/cloud/memory-scope.js';
-import { applyCredential, findCredential } from './auth/cloud-keystore.js';
-import { defaultProjectFor } from './project-name.js';
+import { linkDirectoryFrom } from '../../memory/project/link-directory.js';
 import { RETICLE_CONFIG_BASENAME } from './ports/resolve/cli-port.js';
+import { cmdLink, validateKey } from './cloud-link.js';
+// `link` moved to its own module; the CLI entry still imports it from here.
+export { cmdLink } from './cloud-link.js';
 import { normalizeUrl } from './auth/cloud-session.js';
-import { cmdLogin, cmdLogout } from './cloud-login.js';
-import { api, baseUrl, bearer, CREDENTIALS_FILE, emit, err, flags, hint, home, readJson, readSession, readSessionFor, RETICLE_DIR, } from './cloud-kit.js';
+import { chooseWorkspace, cmdLogin, cmdLogout } from './cloud-login.js';
+import { cmdTry } from './try-command.js';
+import { CLOUD_COMMANDS } from './cli-parse-grammar.js';
+import { api, baseUrl, bearer, emit, err, flags, hint, readJson, readSession, readSessionFor, RETICLE_DIR, } from './cloud-kit.js';
 import { syncRequest } from '../../memory/cloud/cloud-sync.js';
+import { GateExit, gateExitWith } from './answers/gate-exit.js';
+import { brokenOf } from './known-regression.js';
+import { describeUnsyncedBriefly } from '../../memory/cloud/unsynced-roots.js';
+import { machineUnsyncedRoots } from '../../memory/project/sync-status.js';
 import { describeSync, runSyncCycle } from '../../memory/cloud/sync-cycle.js';
 import { diskSink, diskSource, readCloudIssues, readCloudState } from '../../memory/cloud/sync-disk.js';
+import { fetchPlatformRun } from '../../features/harness/platform/platform-drives.js';
 /**
  * Where `reticle login` dials when nothing says otherwise: the hosted service.
  *
@@ -42,25 +55,11 @@ import { diskSink, diskSource, readCloudIssues, readCloudState } from '../../mem
  * override resolves through. This directory is what makes staging and production hold at the same
  * time instead of clobbering each other, which is the whole reason a single file was not enough.
  */
-const CLOUD_COMMANDS = new Set([
-    'login',
-    'connect',
-    'logout',
-    'whoami',
-    'link',
-    'project',
-    'config',
-    'issues',
-    'memory',
-    'push',
-    'sync',
-    'runs',
-    'regression',
-    'share',
-]);
-export const isCloudCommand = (cmd) => cmd !== undefined && CLOUD_COMMANDS.has(cmd);
+const CLOUD_COMMAND_SET = new Set(CLOUD_COMMANDS);
+export const isCloudCommand = (cmd) => cmd !== undefined && CLOUD_COMMAND_SET.has(cmd);
 /** `reticle sync --watch` — keep cycling instead of exiting. */
 const WATCH_FLAG = '--watch';
+const MOVE_HISTORY_FLAG = '--move-history';
 /**
  * How often `--watch` cycles.
  *
@@ -70,78 +69,15 @@ const WATCH_FLAG = '--watch';
  */
 const DEFAULT_SYNC_INTERVAL_MS = 60_000;
 /**
- * How a key is named out loud: enough to match it against the dashboard, never enough to use.
- *
- * The same shape the web console shows, so the two name one key identically and somebody can tell
- * at a glance which row this repo is using.
- */
-const KEY_HINT_CHARS = 16;
-const keyHint = (key) => key.length <= KEY_HINT_CHARS ? key : `${key.slice(0, KEY_HINT_CHARS)}…`;
-/**
- * The api key this machine already holds for a project ON THIS CLOUD, if any.
- *
- * Two shapes, matching the resolver: `{ key, url }` is what `link` writes now and is only returned
- * when the URL matches, and a bare string is the legacy shape with no URL to check. Without the URL
- * check this would happily reuse a production key for a self-hosted link, because `link` names
- * every project "default" and the two collide in one slot.
- */
-const storedCredential = async (projectId, url, orgId) => findCredential(await readJson(join(home(), CREDENTIALS_FILE)), projectId, url, orgId);
-/**
- * What a key is good for, or undefined when the cloud will not accept it.
- *
- * Never throws: a revoked key, a rotated one and an unreachable cloud are all "cannot reuse this",
- * and the caller's answer to every one of them is the same — mint a fresh one.
- */
-const validateKey = async (url, key) => {
-    try {
-        return WhoamiSchema.parse(await api('GET', `${url}/v1/cloud/whoami`, key));
-    }
-    catch {
-        return undefined;
-    }
-};
-const KeySchema = z.object({ projectId: z.string(), projectName: z.string(), key: z.string() });
-const WhoamiSchema = z.object({
-    projectId: z.string(),
-    projectName: z.string(),
-    /**
-     * Which tenant the key belongs to. Optional for the same reason `dashboardUrl` is — an older
-     * cloud does not send it — and when it is missing a stored key cannot be proved to be ours, which
-     * is why the reuse path below mints instead of guessing.
-     */
-    orgId: z.string().optional(),
-    /**
-     * Where this project's dashboard lives. Optional because an older cloud does not send it, and a
-     * CLI that refused to link against one would break the thing it is supposed to connect.
-     */
-    dashboardUrl: z.string().optional(),
-});
-const CreatedProjectSchema = z.object({ projectId: z.string(), name: z.string() });
-const ProjectsListSchema = z.object({
-    projects: z.array(z.object({ projectId: z.string(), name: z.string() })),
-});
-/** Resolve a --project value that may be a slug id OR a display name into the canonical projectId. */
-/**
- * The id for the project the caller named, creating it if it does not exist yet.
- *
- * It used to refuse — "create it with `reticle project create`" — which made naming a project a
- * two-command bookkeeping ritual for the COMMON case: a first repo, whose project has of course not
- * been created yet. That refusal is also the only reason the magic path existed: bare `link` binds
- * to a project called `Default` precisely so nobody has to meet this error.
- *
- * Creating is announced rather than silent. A tool that quietly invents a durable, billable object
- * is its own surprise, and the whole point of this change is that the automatic path SAYS what it
- * did.
+ * The `.reticle` this folder's commands read and write: the project `link` binds (see
+ * `linkDirectoryFor`), so `sync` from a monorepo root reaches the app it linked — unless only this
+ * folder holds a link, made before `link` followed the project, which keeps working.
  */
-const resolveProjectId = async (url, token, wanted) => {
-    const { projects } = ProjectsListSchema.parse(await api('GET', `${url}/v1/projects`, token));
-    const lc = wanted.toLowerCase();
-    const match = projects.find((p) => p.projectId === wanted || p.name.toLowerCase() === lc);
-    if (match !== undefined)
-        return match.projectId;
-    const created = CreatedProjectSchema.parse(await api('POST', `${url}/v1/projects`, token, { name: wanted }));
-    hint(`created project "${wanted}" (${created.projectId}) — it did not exist yet`);
-    return created.projectId;
+const linkedRoot = () => {
+    const project = join(linkDirectoryFrom(process.cwd()), RETICLE_DIR);
+    const here = join(process.cwd(), RETICLE_DIR);
+    const onlyHere = !existsSync(join(project, CLOUD_LINK_FILE)) && existsSync(join(here, CLOUD_LINK_FILE));
+    return onlyHere ? here : project;
 };
 /**
  * `reticle whoami` — the one call an agent (or a confused human) makes to know its state: who am I logged
@@ -150,13 +86,13 @@ const resolveProjectId = async (url, token, wanted) => {
 const cmdWhoami = async () => {
     const session = await readSession();
     const fs = createNodeFileSystem();
-    const cloud = await resolveProjectCloud(fs, join(process.cwd(), RETICLE_DIR), homedir(), process.env);
+    const cloud = await resolveProjectCloud(fs, linkedRoot(), homedir(), process.env);
     /*
      * The sync half of "what is my state". Without it the honest answer to "why does the dashboard
      * look old?" was to go and read a JSON file — and the two failure modes a person actually hits
      * (nothing has synced yet, and the last attempt errored) looked identical from out here.
      */
-    const reticleRoot = join(process.cwd(), RETICLE_DIR);
+    const reticleRoot = linkedRoot();
     const state = readCloudState(reticleRoot);
     const decisions = Object.keys(readCloudIssues(reticleRoot).triage).length;
     emit({
@@ -182,9 +118,31 @@ const cmdWhoami = async () => {
     if (null === cloud.config)
         hint(null === session
             ? 'this repo is not attached — run `reticle connect` (signs in and links in one step)'
-            : 'this repo is not attached — run `reticle link`');
+            : 'this repo is not attached — run `reticle connect`');
     return 0;
 };
+/**
+ * Who is signed in and which project this repo is linked to, for `reticle status`. Local files
+ * only: status must answer with no network.
+ */
+export const accountStatusFields = async () => {
+    const session = await readSession();
+    const cloud = await resolveProjectCloud(createNodeFileSystem(), linkedRoot(), homedir(), process.env);
+    // What the last sync heard, from local state, in the platform's words when it named the reason.
+    const refused = keyRefusalAtLastSync(linkedRoot());
+    const link = await readJson(join(linkedRoot(), CLOUD_LINK_FILE));
+    const workspace = 'object' === typeof link && null !== link
+        ? link['workspace']
+        : undefined;
+    return {
+        signedInAs: session?.orgName ?? null,
+        linkedProject: null === cloud.config ? null : cloud.projectId,
+        ...(null !== cloud.config && 'string' === typeof workspace && 0 < workspace.length
+            ? { linkedWorkspace: workspace }
+            : {}),
+        ...(refused === undefined ? {} : { keyRefused: refused }),
+    };
+};
 /** `reticle project ls` / `reticle project create <name>` — key- or session-authed. */
 const cmdProject = async (argv) => {
     const active = await readSession();
@@ -195,8 +153,8 @@ const cmdProject = async (argv) => {
         // Name BOTH hosts when there is a session for a different one. "Run reticle login" on its own is
         // baffling to somebody who just did — the useful fact is that they logged in somewhere else.
         err(null !== active && normalizeUrl(active.url) !== url
-            ? `signed in to ${normalizeUrl(active.url)}, but this command targets ${url} — run \`reticle login --url ${url}\`, or set RETICLE_API_KEY`
-            : `not signed in to ${url} — run \`reticle login --url ${url}\`, or set RETICLE_API_KEY`);
+            ? `signed in to ${normalizeUrl(active.url)}, but this command targets ${url} — run \`reticle connect --url ${url}\`, or set RETICLE_API_KEY`
+            : `not signed in to ${url} — run \`reticle connect --url ${url}\`, or set RETICLE_API_KEY`);
         return 2;
     }
     const sub = argv[0];
@@ -212,7 +170,7 @@ const cmdProject = async (argv) => {
         }
         const created = CreatedProjectSchema.parse(await api('POST', `${url}/v1/projects`, token, { name }));
         emit(created);
-        hint(`next: \`reticle link --project ${created.projectId}\` to bind this repo`);
+        hint(`next: \`reticle connect --project ${created.projectId}\` to bind this repo`);
         return 0;
     }
     if ('rename' === sub) {
@@ -237,229 +195,24 @@ const cmdProject = async (argv) => {
     err('usage: reticle project <ls|create <name>|rename <id> <name>|rm <id>>');
     return 2;
 };
+const NO_INSTALL = '--no-install';
+/** Whether `reticle connect`'s init half installs the packages: not under `--no-install`. */
+export const connectInstalls = (argv) => !argv.includes(NO_INSTALL);
 /**
- * `reticle link [--project <id>]` — bind THIS repo to a cloud project. With a login token it MINTS a
- * project-scoped key (no pasting); with a pre-set RETICLE_API_KEY it resolves the key's project via
- * whoami. Writes the non-secret binding to <repo>/.reticle/cloud.json and the secret key to
- * ~/.reticle/credentials.json (keyed by projectId).
+ * `reticle connect`: the cloud half of first-run setup in one go. A saved login is checked against
+ * this host first; it links once, in the workspace chosen, then sends local history.
  */
-const cmdLink = async (argv) => {
-    const f = flags(argv);
-    const url = baseUrl(await readSession(), f['url']);
-    // Same rule as every other authed verb: the token is looked up by the host it will be sent to.
-    const session = await readSessionFor(url);
-    const envKey = apiKeyFrom(process.env);
-    /*
-     * Read the existing binding FIRST, because it decides which project a bare `link` targets.
-     * Re-running `link` is ordinary — rotating a key, repointing an environment — and it must land in
-     * the project this repo already reports to, or its history splits in two without saying so.
-     */
-    const priorLink = await readJson(join(process.cwd(), RETICLE_DIR, CLOUD_LINK_FILE));
-    const priorProjectId = 'object' === typeof priorLink && priorLink !== null
-        ? priorLink['projectId']
-        : undefined;
-    let projectId;
-    let projectName;
-    let key;
-    /**
-     * The tenant this binding belongs to, recorded so the credential can be filed and found per-org.
-     * Undefined against an older cloud, where the slot stays cloud+project as it always was.
-     */
-    let orgId;
-    /** The key this machine already had for the slot, and whether it provably belongs to another tenant. */
-    let priorKey;
-    let priorIsForeign = false;
-    /*
-     * Where this project's dashboard lives. Asked of the cloud rather than derived from `url`: the API
-     * origin and the console origin are different hosts in every deployment that is not a laptop, so a
-     * link the CLI guessed would be wrong exactly where it matters.
-     */
-    let dashboardUrl;
-    /** Whether the key was already on this machine — so the report can say so instead of "minted". */
-    let reusedKey = false;
-    // Tracked separately from the value: an OLDER cloud answers whoami without a dashboardUrl, and
-    // keying the fallback off the value would ask the same question twice every time.
-    let askedWhoami = false;
-    if (envKey !== undefined && envKey.length > 0) {
-        const who = WhoamiSchema.parse(await api('GET', `${url}/v1/cloud/whoami`, envKey));
-        projectId = who.projectId;
-        projectName = who.projectName;
-        dashboardUrl = who.dashboardUrl;
-        orgId = who.orgId;
-        askedWhoami = true;
-        key = envKey;
-    }
-    else if (session !== null) {
-        // --project accepts a slug id OR a display name; default when omitted. Resolve to the canonical id.
-        const wanted = f['project'];
-        /*
-         * A repo is named after itself, not "Default".
-         *
-         * When every repo binds to one project called "Default", two unrelated checkouts on one account
-         * merge their runs, issues and impact into a single bucket and the per-project view describes
-         * nothing. It is also what lets two TENANTS collide, since a credential slot built from a
-         * project id is only as distinct as the ids are.
-         */
-        const fallback = defaultProjectFor(basename(process.cwd()), 'string' === typeof priorProjectId ? priorProjectId : undefined);
-        const targetId = wanted === undefined
-            ? await resolveProjectId(url, session.token, fallback)
-            : await resolveProjectId(url, session.token, wanted);
-        /*
-         * Reuse the key this machine already holds for the project, rather than minting another.
-         *
-         * `link` was idempotent about the BINDING and not about the KEY: two runs against one project
-         * left two live `reticle-cli` keys on the account, each valid, neither identifiable to a repo.
-         * Agents retry — that is what agents do — so it accumulates silently until somebody has a key
-         * list they cannot reason about and revokes the wrong one.
-         *
-         * Validated before trusting, because a stored key can have been revoked or rotated from the
-         * dashboard and a stale credential must not strand the repo. The check is the whoami call the
-         * mint path already makes for `dashboardUrl`, so the common path costs no extra round trip —
-         * and a key that fails it is replaced rather than reported.
-         */
-        const existing = await storedCredential(targetId, url, session.orgId);
-        const validated = existing === undefined ? undefined : await validateKey(url, existing);
-        /*
-         * A valid key is not the same as OUR key.
-         *
-         * `validateKey` only asks whether the cloud still accepts it, and a key belonging to another
-         * organisation on the same cloud passes that question perfectly. With every project named
-         * "default", the slot `<url>::default` was shared across tenants — so a brand-new workspace
-         * signing in on a machine that had linked a different account reused that account's key and
-         * would have pushed its runs into a stranger's dashboard. Measured, not hypothesised.
-         *
-         * So reuse now requires PROOF of a tenant match, and treats anything less as no match: an older
-         * cloud that omits `orgId`, or a session file written before we recorded one, both fall through
-         * to minting. Minting a second key is a tidiness problem; pushing to the wrong tenant is a
-         * disclosure, and only one of those is worth defaulting to.
-         */
-        const sameTenant = validated !== undefined &&
-            session.orgId !== undefined &&
-            validated.orgId !== undefined &&
-            validated.orgId === session.orgId;
-        const reusable = sameTenant ? validated : undefined;
-        priorKey = existing;
-        // Provably somebody else's: it still works on this cloud AND whoami names a different org. A key
-        // that merely FAILED validation is our own revoked one, and overwriting that is the point.
-        priorIsForeign =
-            validated !== undefined &&
-                validated.orgId !== undefined &&
-                session.orgId !== undefined &&
-                validated.orgId !== session.orgId;
-        if (existing !== undefined && reusable !== undefined) {
-            projectId = reusable.projectId;
-            projectName = reusable.projectName;
-            dashboardUrl = reusable.dashboardUrl;
-            orgId = reusable.orgId;
-            askedWhoami = true;
-            key = existing;
-            reusedKey = true;
-        }
-        else {
-            const minted = KeySchema.parse(await api('POST', `${url}/v1/keys`, session.token, {
-                name: 'reticle-cli',
-                projectId: targetId,
-            }));
-            projectId = minted.projectId;
-            projectName = minted.projectName;
-            key = minted.key;
-            // The key was minted WITH this session, so its tenant is this session's by construction.
-            orgId = session.orgId;
-        }
-    }
-    else {
-        err('run `reticle login` first, or set RETICLE_API_KEY to link with an existing key');
-        return 2;
-    }
-    const reticleDir = join(process.cwd(), RETICLE_DIR);
-    await mkdir(reticleDir, { recursive: true });
-    const linkPath = join(reticleDir, CLOUD_LINK_FILE);
-    const prev = await readJson(linkPath);
-    const prevObj = 'object' === typeof prev && prev !== null ? prev : {};
-    // The minted-key path has not asked yet. Best-effort: a link that works is worth more than a link
-    // that also has a link in it, and an older cloud simply does not send one.
-    if (!askedWhoami) {
-        try {
-            const who = WhoamiSchema.parse(await api('GET', `${url}/v1/cloud/whoami`, key));
-            dashboardUrl = who.dashboardUrl;
-            // Only FILL IN a tenant we do not have. The session we minted with is the authority on which
-            // org this key belongs to; letting a later lookup overwrite it is how the answer drifts.
-            orgId = orgId ?? who.orgId;
-        }
-        catch {
-            // Older cloud, or a transient failure. The HUD shows its list without a link.
-        }
-    }
-    const cloudJson = {
-        projectId,
-        projectName,
-        // Recorded so the daemon resolves the credential in the ORG slot rather than the ambiguous
-        // cloud+project one, which two tenants on one cloud both answer to.
-        ...(orgId === undefined ? {} : { orgId }),
-        url,
-        ...(dashboardUrl === undefined ? {} : { dashboardUrl }),
-        sync: prevObj['sync'] ?? { runs: true, memory: true, flows: true },
-        verify: prevObj['verify'] ?? 'local',
-    };
-    await writeFile(linkPath, `${JSON.stringify(cloudJson, null, 2)}\n`);
-    await mkdir(home(), { recursive: true });
-    const credPath = join(home(), CREDENTIALS_FILE);
-    const creds = (await readJson(credPath)) ?? {};
-    const credObj = applyCredential('object' === typeof creds && creds !== null ? creds : {}, { projectId, url, key, orgId, priorKey, priorIsForeign });
-    await writeFile(credPath, `${JSON.stringify(credObj, null, 2)}\n`);
-    emit({ linked: projectName, projectId, cloudJson: linkPath, credentials: credPath });
-    /*
-     * Say what just happened, in the vocabulary of somebody who has used other tools.
-     *
-     * `link` mints the key and stores it for you, which is the product's whole edge — and it is
-     * invisible, which is its whole cost. A real report: somebody pasted a masked placeholder key
-     * into a `.env` because their mental model said "I must make a key and put it somewhere". One had
-     * already been minted and filed outside the repo. They did not need another step; they needed to
-     * be told the step had happened.
-     *
-     * The key is identified the way the dashboard identifies it — a prefix, never the secret — so
-     * this can be read aloud, pasted into an issue, or left in a terminal without leaking anything.
-     */
-    hint(`bound this repo to project "${projectName}"`);
-    hint(reusedKey
-        ? `reusing key ${keyHint(key)} — already stored in ${credPath}, not in your repo`
-        : `minted key ${keyHint(key)} — stored in ${credPath}, not in your repo`);
-    hint('to change it: `reticle link --project <other>`; to inspect: `reticle whoami`');
-    hint('linked ✓ runs auto-push on `reticle verify`; `reticle push` sends existing local runs; `reticle whoami` shows state');
-    /*
-     * A binding is not a connection.
-     *
-     * Without `.reticle.json` the app's bundle carries no projectId, so the daemon cannot attribute a
-     * session to this repo: its runs pool into whichever root the daemon itself was started in, and
-     * `sync` here reports "nothing to send" however much was actually recorded. Measured on this
-     * repo's bench app — two verdicts driven, then a sync that claimed there was nothing.
-     *
-     * Said AFTER the success line rather than refusing: the binding really was written and really is
-     * correct, and the missing half is one command away. Refusing would strand somebody who links
-     * before they install, which is a legitimate order to work in.
-     */
-    if (!(await createNodeFileSystem().exists(join(process.cwd(), RETICLE_CONFIG_BASENAME)))) {
-        hint(`no ${RETICLE_CONFIG_BASENAME} here: this app's runs reach this binding only while its dev ` +
-            'server runs with the Reticle build plugin, which announces it. Run `reticle init` in the app ' +
-            'to make the binding hold without it.');
-    }
-    return 0;
-};
-/**
- * `reticle connect` finishes the cloud half of first-run setup in one invocation. The CLI entry
- * initializes an unwired app before calling this verb. A saved login is checked against this exact
- * host before reuse; an expired one opens the normal browser approval flow. Login does not auto-link
- * here because this command links once, to the project the caller named, then sends local history.
- */
-const cmdConnect = async (argv) => {
+const cmdConnect = async (given) => {
+    // `--no-install` is the init half's (see `connectInstalls`); the cloud half takes it and moves on.
+    const argv = given.filter((arg) => NO_INSTALL !== arg);
     for (let i = 0; i < argv.length; i += 2) {
         const flag = argv[i];
         const value = argv[i + 1];
-        if ((flag !== '--project' && flag !== '--url') ||
+        if ((flag !== '--project' && flag !== '--url' && flag !== '--workspace') ||
             value === undefined ||
             0 === value.length ||
             value.startsWith('--')) {
-            err('usage: reticle connect [--project <name|id>] [--url <cloud origin>]');
+            err('usage: reticle connect [--project <name|id>] [--workspace <name|id>] [--url <origin>] [--no-install]');
             return 2;
         }
     }
@@ -487,12 +240,15 @@ const cmdConnect = async (argv) => {
                 return code;
         }
     }
+    const chosen = await chooseWorkspace(url, f['workspace']);
+    if (chosen !== 0)
+        return chosen;
     const linkArgs = [
         '--url',
         url,
         ...(f['project'] === undefined ? [] : ['--project', f['project']]),
     ];
-    const linked = await cmdLink(linkArgs);
+    const linked = await cmdLink(linkArgs, process.cwd(), PlatformLinkVia.CONNECT);
     if (linked !== 0)
         return linked;
     const pushed = await cmdPush();
@@ -504,10 +260,10 @@ const cmdConnect = async (argv) => {
 /** `reticle config [--runs on|off] [--memory on|off] [--flows on|off] [--verify local|server]`. */
 const cmdConfig = async (argv) => {
     const f = flags(argv);
-    const linkPath = join(process.cwd(), RETICLE_DIR, CLOUD_LINK_FILE);
+    const linkPath = join(linkedRoot(), CLOUD_LINK_FILE);
     const raw = await readJson(linkPath);
     if (null === raw || typeof raw !== 'object') {
-        err('no .reticle/cloud.json here — run `reticle link` first');
+        err('no .reticle/cloud.json here — run `reticle connect` first');
         return 2;
     }
     const cfg = raw;
@@ -538,7 +294,7 @@ const cmdConfig = async (argv) => {
     return 0;
 };
 /**
- * `reticle sync [--watch]` — one full cycle: send the difference, collect what came back.
+ * `reticle sync [--watch] [--move-history]` — one full cycle: send the difference, collect what came back.
  *
  * This replaced a `push` that re-uploaded every run artifact on every invocation. That was fine with
  * three runs and absurd with three hundred, and it only ever went one way — so a bug somebody
@@ -549,12 +305,15 @@ const cmdConfig = async (argv) => {
  */
 const cmdSync = async (argv) => {
     const fs = createNodeFileSystem();
-    const reticleRoot = join(process.cwd(), RETICLE_DIR);
+    const reticleRoot = linkedRoot();
     const cloud = await resolveProjectCloud(fs, reticleRoot, homedir(), process.env);
     if (null === cloud.config) {
-        err(cloud.reason ?? 'cloud not attached here: run `reticle link`, or set RETICLE_API_KEY');
+        err(cloud.reason ?? 'cloud not attached here: run `reticle connect`, or set RETICLE_API_KEY');
+        await reportUnsynced(fs);
         return 1;
     }
+    if (cloud.note !== undefined)
+        err(cloud.note);
     const config = cloud.config;
     const full = diskSource(reticleRoot);
     const source = {
@@ -563,10 +322,16 @@ const cmdSync = async (argv) => {
         capsules: () => (cloud.policy.capsules ? full.capsules() : []),
         // `memory` is the project's cross-run history and the derived records that summarise it.
         derived: (kind) => cloud.policy.memory ? full.derived(kind) : undefined,
+        ...(cloud.policy.screenshots && full.screenshot !== undefined
+            ? { screenshot: full.screenshot }
+            : {}),
     };
     const once = async () => {
         const report = await runSyncCycle({
             config,
+            ...(cloud.link === undefined ? {} : { link: cloud.link }),
+            // Runs made under a folder's previous link go only when the person says so.
+            ...(argv.includes(MOVE_HISTORY_FLAG) ? { moveHistory: true } : {}),
             source,
             sink: diskSink(reticleRoot),
             state: readCloudState(reticleRoot),
@@ -590,6 +355,7 @@ const cmdSync = async (argv) => {
             ...(report.error === undefined ? {} : { error: report.error }),
         });
         hint(describeSync(report));
+        await reportUnsynced(fs);
         return report.ok ? 0 : 1;
     };
     const watch = argv.includes(WATCH_FLAG);
@@ -602,6 +368,14 @@ const cmdSync = async (argv) => {
         await sleep(everyMs);
     }
 };
+/**
+ * Every other folder on this machine holding runs the platform never got, one line each. `sync` only
+ * ever sends the folder it runs in, so a monorepo app's unlinked `.reticle` was invisible from here.
+ */
+const reportUnsynced = async (fs) => {
+    for (const line of describeUnsyncedBriefly(await machineUnsyncedRoots(fs, homedir(), process.env), process.cwd()))
+        hint(line);
+};
 /** `reticle push` — the name people already type. One cycle, same as `reticle sync`. */
 const cmdPush = async () => cmdSync([]);
 /**
@@ -619,15 +393,32 @@ const cmdPush = async () => cmdSync([]);
  */
 const repoCloud = async () => {
     const fs = createNodeFileSystem();
-    const cloud = await resolveProjectCloud(fs, join(process.cwd(), RETICLE_DIR), homedir(), process.env);
+    const cloud = await resolveProjectCloud(fs, linkedRoot(), homedir(), process.env);
     if (null === cloud.config)
-        throw new Error(cloud.reason ?? 'cloud not attached here: run `reticle link`, or set RETICLE_API_KEY');
+        throw new Error(cloud.reason ?? 'cloud not attached here: run `reticle connect`, or set RETICLE_API_KEY');
     return { ...cloud.config, projectId: cloud.projectId };
 };
 /** `reticle runs` — the linked project's recent run artifacts (the key scopes it server-side). */
-const cmdRuns = async () => {
+/**
+ * `reticle runs [<id>]` — the project's runs, or one of them by id.
+ *
+ * With an id it is the way back to a Harness drive whose local record is gone (another machine, a
+ * cleaned checkout): the platform keeps the run. A 404 is "not synced yet, or not found", never a
+ * crash, since a run written a minute ago may simply not have been pushed.
+ */
+const cmdRuns = async (argv) => {
     const { url, apiKey } = await repoCloud();
-    emit(await api('GET', `${url}/v1/runs`, apiKey));
+    const id = argv[0];
+    if (id === undefined) {
+        emit(await api('GET', `${url}/v1/runs`, apiKey));
+        return 0;
+    }
+    const got = await fetchPlatformRun({ url, apiKey }, id);
+    if ('error' in got) {
+        err(got.error);
+        return 1;
+    }
+    emit(got.run);
     return 0;
 };
 /**
@@ -648,7 +439,7 @@ const cmdIssues = async (argv) => {
     const fixAt = argv.indexOf('--fix');
     const wanted = -1 === fixAt ? undefined : argv[fixAt + 1];
     if (fixAt !== -1 && wanted === undefined) {
-        err('usage: reticle issues --fix <fingerprint>');
+        err('usage: reticle runs issues --fix <fingerprint>');
         return 2;
     }
     const body = await api('GET', `${url}/v1/issues`, apiKey);
@@ -667,7 +458,7 @@ const cmdIssues = async (argv) => {
     }
     const found = parsed.data.issues.find((i) => i.fingerprint === wanted);
     if (found === undefined) {
-        err(`no issue with fingerprint '${wanted}' — run \`reticle issues\` to list them`);
+        err(`no issue with fingerprint '${wanted}' — run \`reticle runs issues\` to list them`);
         return 2;
     }
     const prompt = found.fixPrompt;
@@ -698,7 +489,7 @@ const cmdMemory = async (argv) => {
     const at = argv.indexOf('--subject');
     const subject = -1 === at ? undefined : argv[at + 1];
     if (-1 !== at && subject === undefined) {
-        err('usage: reticle memory [--subject <name>]');
+        err('usage: reticle runs memory [--subject <name>]');
         return 2;
     }
     // Scoped to the LINKED project, on the way out AND on the way back. Without the parameter
@@ -734,20 +525,35 @@ const cmdRegression = async () => {
     const { url, apiKey } = await repoCloud();
     const report = await api('GET', `${url}/v1/project/regression`, apiKey);
     emit(report);
-    const parsed = z.object({ broken: z.array(z.unknown()) }).safeParse(report);
-    return parsed.success && parsed.data.broken.length > 0 ? 3 : 0;
+    return gateExitWith(GateExit.PASS, brokenOf(report)?.length);
 };
 /** `reticle share <runId>` — mint a public proof link for one run. */
 const cmdShare = async (argv) => {
     const runId = argv[0];
     if (runId === undefined) {
-        err('usage: reticle share <runId>');
+        err('usage: reticle runs share <runId>');
         return 2;
     }
     const { url, apiKey } = await repoCloud();
     emit(await api('POST', `${url}/v1/runs/${encodeURIComponent(runId)}/share`, apiKey));
     return 0;
 };
+/** `reticle runs <regression|share|issues|memory>`, and `reticle runs [<runId>]` otherwise. */
+const cmdRunsFamily = async (argv) => {
+    const [sub, ...rest] = argv;
+    switch (sub) {
+        case 'regression':
+            return cmdRegression();
+        case 'share':
+            return cmdShare(rest);
+        case 'issues':
+            return cmdIssues(rest);
+        case 'memory':
+            return cmdMemory(rest);
+        default:
+            return cmdRuns(argv);
+    }
+};
 /** Dispatch a cloud subcommand. Returns the process exit code. */
 export const runCloudCommand = async (argv) => {
     const [cmd, ...rest] = argv;
@@ -759,6 +565,11 @@ export const runCloudCommand = async (argv) => {
                 return await cmdLogin(rest, cmdLink);
             case 'connect':
                 return await cmdConnect(rest);
+            case 'try':
+                return await cmdTry(rest, {
+                    push: () => cmdSync([]),
+                    dashboardUrl: async (c) => (await validateKey(c.url, c.apiKey))?.dashboardUrl,
+                });
             case 'logout':
                 return await cmdLogout(rest);
             case 'whoami':
@@ -769,12 +580,13 @@ export const runCloudCommand = async (argv) => {
                 return await cmdLink(rest);
             case 'config':
                 return await cmdConfig(rest);
+            // `push` is the name people type, so it takes `--watch` too: the help and the README say so.
             case 'push':
-                return await cmdPush();
+                return await cmdSync(rest);
             case 'sync':
                 return await cmdSync(rest);
             case 'runs':
-                return await cmdRuns();
+                return await cmdRunsFamily(rest);
             case 'issues':
                 return await cmdIssues(rest);
             case 'memory':