@reticlehq/server 3.5.0 → 3.7.0

package/dist/command/cli/setup-mcp-cli.js

@@ -1,11 +1,12 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
-import { dirname } from 'node:path';
+import { dirname, join } from 'node:path';
 import { homedir } from 'node:os';
 import { claudeAddCommand, McpClient, probeCli, terminalWidth, wrapForTerminal, } from '@reticlehq/init';
-import { installClosing, tutorialShownSteps } from './tutorial.js';
+import { tutorialShownSteps } from './tutorial.js';
 import { setupMcp, knownClientLabels } from '../setup/setup-mcp.js';
 import { reportInstallSteps } from '../setup/setup-install.js';
 import { registerOtherAgents } from '../setup/setup-command.js';
+/** How many coding agents on this machine have Reticle's tools after this run. */
 export function handleSetupMcp(reportStep, standalone = true) {
     const io = {
         exists: (p) => existsSync(p),
@@ -35,15 +36,17 @@ export function handleSetupMcp(reportStep, standalone = true) {
     const result = setupMcp(io);
     if (0 === result.detected.length) {
         // Even with no file-backed client, the broader set may still have somewhere to write.
-        registerOtherAgents((line) => {
+        const preRegistered = registerOtherAgents((line) => {
             io.print(line);
         });
         // Named rather than a bare "none found". A person whose agent IS installed needs to know
         // whether we looked for it at all, and the list is the difference between "we did not find
-        // yours" and "we do not support yours".
-        io.print(`No coding agent config found. Looked for: ${knownClientLabels().join(', ')}.`);
-        io.print('Install one, then run `reticle setup mcp` again.');
-        return;
+        // yours" and "we do not support yours". When the broader set was written, saying "none found"
+        // right under its tick read as a contradiction: those agents are pre-registered, not found.
+        io.print(0 < preRegistered
+            ? `None of ${knownClientLabels().join(', ')} is installed here yet. The agents above are pre-registered and have Reticle's tools once installed; install one of the others, then run \`reticle setup mcp\` again.`
+            : `No coding agent config found. Looked for: ${knownClientLabels().join(', ')}. Install one, then run \`reticle setup mcp\` again.`);
+        return 0;
     }
     for (const id of result.registered)
         io.print(`  ✓ ${id}`);
@@ -90,6 +93,25 @@ export function handleSetupMcp(reportStep, standalone = true) {
         io.print('Restart your agent for it to pick up the new server.');
         io.print('Then: cd <your project> && reticle init');
     }
+    return result.registered.length + result.alreadyThere.length;
+}
+/**
+ * The one line the launchers read and strip: what they cannot know and the next steps depend on.
+ *
+ * The launchers own the closing words (served from main, so wording changes on merge) and used to
+ * print "restart your coding agent" to a machine with none, and "cd your-app" to somebody already
+ * standing in it. An older launcher shows this line as is; a launcher reading an older CLI finds no
+ * line and keeps its generic wording, so neither half has to ship first.
+ */
+export const INSTALL_RESULT_PREFIX = 'RETICLE_INSTALL';
+const APP_MARKERS = ['package.json', 'index.html'];
+/** Whether the folder the installer ran in is an app: `init` runs here, or after a `cd`. */
+export const InstallAppHere = { HERE: 'here', NONE: 'none' };
+export function installResultLine(agents, cwd) {
+    const app = APP_MARKERS.some((file) => existsSync(join(cwd, file)))
+        ? InstallAppHere.HERE
+        : InstallAppHere.NONE;
+    return `${INSTALL_RESULT_PREFIX} agents=${String(agents)} app=${app}`;
 }
 /**
  * `reticle setup install` — the Node half of the one-line installer.
@@ -100,16 +122,17 @@ export function handleSetupMcp(reportStep, standalone = true) {
  */
 export function handleSetupInstall(opts, reportStep) {
     reportInstallSteps({ runtimeSecs: opts.runtimeSecs, installSecs: opts.installSecs }, reportStep);
+    let agents = 0;
     if (opts.mcp) {
-        handleSetupMcp(reportStep, false);
+        agents = handleSetupMcp(reportStep, false);
     }
     else {
         process.stdout.write('Skipping MCP registration (--no-mcp).\n');
     }
-    // Installation and onboarding are one script, so the tour prints here and is not gated on
-    // anything — see installClosing for the heuristic this replaced and why it reached nobody.
-    process.stdout.write(`${wrapForTerminal(installClosing(opts.mcp), terminalWidth())}\n`);
-    // Shown, so the ONBOARD steps are a fact rather than a guess.
+    // No closing here: the installer prints the next step and the agent prompt itself, right after
+    // this returns, so what this prints is progress and nothing else. Those two blocks are what the
+    // ONBOARD steps below now stand for: what Reticle is for, shown before anything is asked of anyone.
     for (const step of tutorialShownSteps())
         reportStep(step);
+    process.stdout.write(`${installResultLine(agents, process.cwd())}\n`);
 }

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

@@ -19,6 +19,7 @@ export declare const StatusLabel: {
     readonly DAEMON: "daemon";
     readonly SESSIONS: "sessions";
     readonly AGENT_LINK: "agent link";
+    readonly ACCOUNT: "account";
     readonly NEXT: "next";
     readonly SPLIT_BRAIN: "split brain";
     readonly UPDATE: "update";

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

@@ -19,6 +19,7 @@ export const StatusLabel = {
     DAEMON: 'daemon',
     SESSIONS: 'sessions',
     AGENT_LINK: 'agent link',
+    ACCOUNT: 'account',
     NEXT: 'next',
     SPLIT_BRAIN: 'split brain',
     UPDATE: 'update',
@@ -101,9 +102,40 @@ export function statusLines(fields) {
         if (why !== undefined)
             lines.push(continuation(why));
     }
+    // Who is signed in, and whether this repo is linked: what `whoami` used to answer. Only when the
+    // caller looked, which is what the key being present means.
+    if ('signedInAs' in fields) {
+        const who = str(fields, 'signedInAs');
+        const project = str(fields, 'linkedProject');
+        // Signed in to one workspace, a repo can still send to another: say which it sends to.
+        const workspace = str(fields, 'linkedWorkspace');
+        // A key the platform refused at the last sync is the answer, not "not signed in": a member
+        // removed from the workspace was told to connect while the key was set, and refused.
+        const refused = str(fields, 'keyRefused');
+        lines.push(row(StatusLabel.ACCOUNT, refused !== undefined
+            ? `${NOT_OK} refused at the last sync: ${refused}`
+            : who === undefined
+                ? `${NOT_OK} not signed in`
+                : `${OK} signed in as ${who}`));
+        const apps = appLinks(fields['workspaceApps']);
+        if (project === undefined && 0 < apps.length)
+            for (const { app, project: linked } of apps)
+                lines.push(continuation(null === linked
+                    ? `${app} is not linked: run \`reticle connect\` in ${app}`
+                    : `${app} is linked to ${linked}`));
+        else
+            lines.push(continuation(project === undefined
+                ? 'this repo is not linked: run `reticle connect`'
+                : `this repo is linked to ${project}${workspace === undefined ? '' : ` in workspace "${workspace}"`}`));
+    }
     const client = str(fields, 'mcpClient');
-    if (client !== undefined)
-        lines.push(row(StatusLabel.AGENT_LINK, client));
+    if (client !== undefined) {
+        // The state in words (`mcpClientSaid`), never the record's own name for it.
+        lines.push(row(StatusLabel.AGENT_LINK, str(fields, 'mcpClientSaid') ?? client));
+        const action = str(fields, 'mcpClientAction');
+        if (action !== undefined)
+            lines.push(continuation(action));
+    }
     for (const [label, key] of [
         [StatusLabel.NEXT, 'nextAction'],
         [StatusLabel.SPLIT_BRAIN, 'splitBrain'],
@@ -115,3 +147,16 @@ export function statusLines(fields) {
     }
     return lines;
 }
+/** A workspace root's apps and their links, read defensively off the status fields. */
+function appLinks(value) {
+    if (!Array.isArray(value))
+        return [];
+    return value.flatMap((raw) => {
+        if ('object' !== typeof raw || null === raw)
+            return [];
+        const { app, project } = raw;
+        return 'string' === typeof app
+            ? [{ app, project: 'string' === typeof project ? project : null }]
+            : [];
+    });
+}

package/dist/command/cli/status/workspace-links.d.ts

@@ -0,0 +1,10 @@
+export interface AppLink {
+    /** The app's directory, relative to the root. */
+    app: string;
+    /** The project it sends to, or null when it is not linked. */
+    project: string | null;
+}
+/** Each app under `root`, in name order, with its link. Empty when `root` is no workspace. */
+export declare function workspaceAppLinks(root: string, linkOf: (appDir: string) => Promise<string | null>): Promise<AppLink[]>;
+/** The project an app folder's link file names, or null with none: local only, as status is. */
+export declare function localLinkOf(appDir: string): Promise<string | null>;

package/dist/command/cli/status/workspace-links.js

@@ -0,0 +1,29 @@
+/**
+ * The apps of a workspace root and the project each is linked to, for `reticle status` run at a root
+ * that is no app of its own: "this repo is not linked" there named nothing that could be acted on.
+ */
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { ReticleDir, asRecord, asString } from '@reticlehq/core';
+import { SILENT_HOST, buildNodeIo, findWorkspaceApps } from '@reticlehq/init';
+/** Each app under `root`, in name order, with its link. Empty when `root` is no workspace. */
+export async function workspaceAppLinks(root, linkOf) {
+    let apps;
+    try {
+        apps = findWorkspaceApps(buildNodeIo(root, SILENT_HOST));
+    }
+    catch {
+        return [];
+    }
+    return Promise.all([...apps].sort().map(async (app) => ({ app, project: await linkOf(join(root, app)) })));
+}
+/** The project an app folder's link file names, or null with none: local only, as status is. */
+export function localLinkOf(appDir) {
+    try {
+        const link = JSON.parse(readFileSync(join(appDir, ReticleDir.ROOT, ReticleDir.CLOUD_LINK_FILE), 'utf8'));
+        return Promise.resolve(asString(asRecord(link)['projectId']) ?? null);
+    }
+    catch {
+        return Promise.resolve(null);
+    }
+}

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

@@ -0,0 +1,96 @@
+import type { CloudConfig } from '../../memory/cloud/cloud-sync.js';
+import { type FreeDrive } from '../../features/harness/platform/platform-drives.js';
+export declare const MSG_SIGN_IN_FIRST = "Sign in first: reticle connect (it is free, no card)";
+/** The whole drive, model turns and browser included, before the CLI stops waiting for it. */
+export declare const TRY_BUDGET_MS = 120000;
+/** Model turns in the one free drive. Bounds what it costs, not what it may find. */
+export declare const TRY_MAX_STEPS = 40;
+export interface TryJourney {
+    title: string;
+    status: string;
+}
+/** What one drive came back with, or the sentence that says why it could not run. */
+export interface TryDrive {
+    journeys: TryJourney[];
+    runIds: string[];
+    error?: string;
+}
+export interface TryPorts {
+    /** The credential `reticle connect` filed for this folder, or null when it is not linked. */
+    linked: () => Promise<CloudConfig | null>;
+    requestDrive: (cloud: CloudConfig) => Promise<FreeDrive>;
+    drive: (request: {
+        url: string;
+        driveId: string;
+        persona?: string;
+    }) => Promise<TryDrive>;
+    /** Send the drive's run, as `reticle push` does. True when the cycle succeeded. */
+    sync: (runIds: readonly string[]) => Promise<boolean>;
+    dashboardUrl: (cloud: CloudConfig) => Promise<string | undefined>;
+    out: (line: string) => void;
+    fail: (line: string) => void;
+}
+export interface TryArgs {
+    url: string;
+    persona?: string;
+}
+/** `try <url> [--persona <who>]`, or the sentence that says what is missing. */
+export declare function parseTryArgs(argv: readonly string[]): TryArgs | {
+    error: string;
+};
+/** The summary, worst news last so it is the line a reader's eye lands on. Pure. */
+export declare function summarizeTry(journeys: readonly TryJourney[]): string[];
+export declare function runTry(args: TryArgs, ports: TryPorts): Promise<number>;
+/** The journeys out of an explore report, or one journey graded from the drive when unplanned. */
+export declare function journeysOf(report: Record<string, unknown>, persona?: string): TryJourney[];
+/** What `try` borrows from the cloud commands, passed in so neither module imports the other. */
+export interface TryCloud {
+    push: () => Promise<number>;
+    dashboardUrl: (cloud: CloudConfig) => Promise<string | undefined>;
+}
+/** `reticle try`, wired to this machine. Returns the exit code. */
+export declare function cmdTry(argv: readonly string[], cloudCommands: TryCloud): Promise<number>;
+/**
+ * How `init` ends once the connection is proved: what Reticle sees of the app, what it is missing,
+ * and the prompt that hands the rest to the coding agent, which proves the first flow. `init` never
+ * drives: the Harness is opt-in and unlocks at a coverage score (core's `instrumentation-coverage.ts`), and a
+ * freshly wired app is rarely there yet.
+ *
+ * Read from the daemon's `/status`, the same coverage `doctor` prints, so the two never disagree.
+ */
+/** What a project that is not linked is told, once, at the end. */
+export declare const UNLINKED_PITCH: string[];
+/** Prove one flow with the coding agent: the line every ending names. */
+export declare const msgProveOneFlow: (url: string) => string;
+/**
+ * The closing lines for one tab's coverage, as `/status` reports it: the score, what is missing, the
+ * Harness gate in its own sentence, and the prompt for the coding agent. Pure.
+ */
+export declare function initCoverageLines(tab: Record<string, unknown> | undefined, url: string): string[];
+/**
+ * This project's runs and flows that will never reach the dashboard as things stand, one line each:
+ * not linked, no key for its host, flow sync off, or refused. A linked root's pending runs are left
+ * out, because the daemon sends them within seconds and saying so would be noise.
+ */
+export declare function strandedWorkLines(appDir: string): Promise<string[]>;
+/** What `init` hands its ending, once the connection is proved. */
+export interface FirstFlowContext {
+    appDir: string;
+    bridgePort: number;
+    pairingToken?: string | undefined;
+    url: string;
+    sessionId: string;
+    /** The proof came from a Reticle-owned browser, now closed: its own tab cannot be measured. */
+    leased: boolean;
+    openBrowser: boolean;
+    /** False for `--no-first-run`: connect, and say nothing more. */
+    firstRun: boolean;
+    json: boolean;
+}
+/**
+ * How `init` ends: the coverage score, the gaps and the agent prompt, the pitch when the project is
+ * not linked, then what will never reach the dashboard. Nothing is driven. Never throws.
+ */
+export declare function initFirstFlow(ctx: FirstFlowContext, say: (line: string) => void): Promise<{
+    flowSaved: boolean;
+}>;

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

@@ -0,0 +1,362 @@
+/**
+ * `reticle try <url>`: one free Harness drive of somebody's app, watched in a window, ending in a
+ * plain list of which journeys work and which are broken.
+ *
+ * Sign-in comes first, and on purpose: the drive runs on the platform, so a machine that is not
+ * linked could only be told no AFTER a browser had opened, which is the worst moment to say it.
+ *
+ * The decisions (refuse, ask the platform, drive, summarise, sync) are `runTry`, behind `TryPorts`, so
+ * every branch is tested without a browser, a daemon or a network. The verdicts in the summary are the
+ * engine's: a journey that neither passed nor failed is "not proved", never rounded up to "works".
+ */
+import { existsSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { RETICLE_DEFAULT_PORT, ReticleDir, ReticleEnv, RunFlowStatus, ScriptStatus, asRecord, driveFlowStatus, } from '@reticlehq/core';
+import { FreeDriveKind, planUrl, requestFreeDrive, } from '../../features/harness/platform/platform-drives.js';
+import { linkedCloudPort, resolveProjectCloud } from '../../memory/cloud/cloud-config.js';
+import { describeUnsynced, unsyncedRoots } from '../../memory/cloud/unsynced-roots.js';
+import { createNodeFileSystem } from '../../memory/project/fs/fs-port.js';
+import { defaultPairingTokenDir, readOrCreatePairingTokenSync, } from '../../portal/bridge/pairing-token.js';
+import { spawnDaemon } from '../daemon/daemon.js';
+import { PortPresence, describePresence, presenceIsUsable, probePresence, } from '../daemon/binding/port-presence.js';
+import { fetchStatus } from '../daemon/binding/daemon-status-probe.js';
+import { probeDaemon, waitForDaemonBind } from '../../surface/mcp/mcp-proxy.js';
+import { readProjectPort } from './ports/resolve/cli-port.js';
+import { callerArtifactRoot } from '../../memory/project/link-directory.js';
+import { seeRunLine } from '../../memory/project/sync-status.js';
+import { DAEMON_INNER_COMMAND, PORT_FLAG } from './cli-parse.js';
+import { acquireLease, connectOverSse, endpointFor, exploreToEnd, refusalText, releaseLease, verdictOf, } from './adhoc-verdict.js';
+export const MSG_SIGN_IN_FIRST = 'Sign in first: reticle connect (it is free, no card)';
+const PERSONA_FLAG = '--persona';
+/** The whole drive, model turns and browser included, before the CLI stops waiting for it. */
+export const TRY_BUDGET_MS = 120_000;
+/** Model turns in the one free drive. Bounds what it costs, not what it may find. */
+export const TRY_MAX_STEPS = 40;
+/** How long to wait for the daemon to write the drive's run once the tab is closed. */
+const RUN_WRITE_WAIT_MS = 10_000;
+const RUN_WRITE_POLL_MS = 250;
+const EXIT_OK = 0;
+const EXIT_FAIL = 1;
+/** `try <url> [--persona <who>]`, or the sentence that says what is missing. */
+export function parseTryArgs(argv) {
+    let url;
+    let persona;
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        if (arg === PERSONA_FLAG) {
+            persona = argv[i + 1];
+            if (persona === undefined)
+                return { error: `${PERSONA_FLAG} needs a value` };
+            i++;
+        }
+        else if (arg !== undefined && arg.startsWith('--')) {
+            return { error: `unknown argument '${arg}'` };
+        }
+        else if (url === undefined) {
+            url = arg;
+        }
+        else {
+            return { error: `unknown argument '${String(arg)}'` };
+        }
+    }
+    if (url === undefined)
+        return { error: 'usage: reticle try <url> [--persona <who>]' };
+    return persona === undefined ? { url } : { url, persona };
+}
+const WORKS = new Set([ScriptStatus.PASSED]);
+const BROKEN = new Set([ScriptStatus.FAILED]);
+/** The summary, worst news last so it is the line a reader's eye lands on. Pure. */
+export function summarizeTry(journeys) {
+    // A branch whose condition did not hold was never a journey this app took.
+    const tried = journeys.filter((j) => ScriptStatus.NOT_TAKEN !== j.status);
+    const works = tried.filter((j) => WORKS.has(j.status)).length;
+    const broken = tried.filter((j) => BROKEN.has(j.status)).length;
+    const unproved = tried.length - works - broken;
+    const head = `Tried ${String(tried.length)} journey${1 === tried.length ? '' : 's'}: ` +
+        `${String(works)} work, ${String(broken)} broken` +
+        (0 === unproved ? '' : `, ${String(unproved)} not proved`);
+    return [
+        head,
+        ...tried.map((j) => WORKS.has(j.status)
+            ? `  ✓ works: ${j.title}`
+            : BROKEN.has(j.status)
+                ? `  ✗ broken: ${j.title}`
+                : `  ? not proved (${j.status}): ${j.title}`),
+    ];
+}
+export async function runTry(args, ports) {
+    const cloud = await ports.linked();
+    if (null === cloud) {
+        ports.fail(MSG_SIGN_IN_FIRST);
+        return EXIT_FAIL;
+    }
+    const grant = await ports.requestDrive(cloud);
+    if (!grant.granted) {
+        ports.fail(grant.message);
+        if (grant.hint !== undefined)
+            ports.fail(grant.hint);
+        if (grant.needsCard) {
+            const base = (await ports.dashboardUrl(cloud).catch(() => undefined)) ?? cloud.url;
+            ports.fail(`Plans: ${planUrl(base)}`);
+        }
+        return EXIT_FAIL;
+    }
+    ports.out(`Driving ${args.url} — watch the window Reticle opens.`);
+    const drive = await ports.drive({
+        url: args.url,
+        driveId: grant.driveId,
+        ...(args.persona === undefined ? {} : { persona: args.persona }),
+    });
+    if (drive.error !== undefined) {
+        ports.fail(drive.error);
+        return EXIT_FAIL;
+    }
+    for (const line of summarizeTry(drive.journeys))
+        ports.out(line);
+    // Saying "saved" over a sync that failed would be this command lying about its own work.
+    if (await ports.sync(drive.runIds).catch(() => false)) {
+        const dashboard = await ports.dashboardUrl(cloud).catch(() => undefined);
+        // Each run on its own page when the dashboard is known; the dashboard itself otherwise.
+        const lines = dashboard === undefined || 0 === drive.runIds.length
+            ? [`Saved to your dashboard: ${dashboard ?? cloud.url}`]
+            : drive.runIds.map((runId) => seeRunLine(dashboard, runId));
+        for (const line of lines)
+            ports.out(line);
+    }
+    else {
+        ports.fail('The run is kept on this machine; it could not be sent. Run `reticle sync` to retry.');
+    }
+    return EXIT_OK;
+}
+const str = (value) => ('string' === typeof value ? value : undefined);
+/** The journeys out of an explore report, or one journey graded from the drive when unplanned. */
+export function journeysOf(report, persona) {
+    const listed = report['journeys'];
+    if (Array.isArray(listed) && 0 < listed.length) {
+        return listed.flatMap((item) => {
+            const j = item;
+            const title = str(j['title']);
+            const status = str(j['status']);
+            return title === undefined || status === undefined ? [] : [{ title, status }];
+        });
+    }
+    // An unplanned drive is one journey, graded by the one rule every drive is: failed only when a
+    // check came back no. A missed goal or undecided checks prove nothing either way.
+    const checks = asRecord(report['checks']);
+    const count = (key) => ('number' === typeof checks[key] ? checks[key] : 0);
+    const goalMet = report['goalMet'];
+    const flow = driveFlowStatus({
+        held: count('held'),
+        failed: count('failed'),
+        ...('boolean' === typeof goalMet ? { goalMet } : {}),
+    });
+    const status = RunFlowStatus.FAIL === flow
+        ? ScriptStatus.FAILED
+        : RunFlowStatus.PASS === flow
+            ? ScriptStatus.PASSED
+            : ScriptStatus.BLOCKED;
+    return [{ title: persona ?? 'Autonomous drive', status }];
+}
+function tryPort(cwd) {
+    const fromEnv = Number(process.env[ReticleEnv.PORT]);
+    if (Number.isInteger(fromEnv) && 0 < fromEnv)
+        return fromEnv;
+    return readProjectPort(cwd) ?? RETICLE_DEFAULT_PORT;
+}
+/** A daemon serving `port`: the one already there, or one started now. Undefined when ready. */
+async function ensureTryDaemon(port) {
+    const presence = await probePresence(port, { tcpOpen: probeDaemon, status: fetchStatus });
+    if (presenceIsUsable(presence))
+        return undefined;
+    // A stranger on the port: a daemon spawned now could not bind, so say who holds it instead.
+    if (PortPresence.FREE !== presence)
+        return describePresence(presence, port);
+    const script = process.argv[1];
+    if (script === undefined)
+        return 'Cannot locate the reticle daemon script.';
+    spawnDaemon(process.execPath, script, [DAEMON_INNER_COMMAND, PORT_FLAG, String(port)], port);
+    return (await waitForDaemonBind(port))
+        ? undefined
+        : `Could not start the Reticle daemon on port ${String(port)}.`;
+}
+/** The drive itself, through the daemon: a watched window, the zero-install reader, one explore. */
+async function driveThroughDaemon(port, request, 
+/** Where the drive's run must land: the folder `try` waits on and pushes from. */
+reticleRoot) {
+    const unavailable = await ensureTryDaemon(port);
+    if (unavailable !== undefined)
+        return { journeys: [], runIds: [], error: unavailable };
+    const token = readOrCreatePairingTokenSync(defaultPairingTokenDir());
+    const caller = await connectOverSse(endpointFor(port, token));
+    try {
+        // Headed whatever the daemon was started as: the point of `try` is watching it happen. An app
+        // with no Reticle SDK gets one supplied by the lease.
+        const opened = await acquireLease(caller, request.url, true, reticleRoot);
+        if ('failed' in opened)
+            return { journeys: [], runIds: [], error: opened.failed.join('\n') };
+        try {
+            const drove = await exploreToEnd(caller, {
+                sessionId: opened.leased,
+                driveId: request.driveId,
+                maxSteps: TRY_MAX_STEPS,
+                ...(request.persona === undefined ? {} : { persona: request.persona }),
+            }, TRY_BUDGET_MS);
+            const refusal = refusalText(drove);
+            if (refusal !== undefined)
+                return { journeys: [], runIds: [], error: refusal };
+            const report = verdictOf(drove, 'stopReason') ?? {};
+            const runIds = Array.isArray(report['runIds'])
+                ? report['runIds'].filter((id) => 'string' === typeof id)
+                : [];
+            const broke = str(report['error']);
+            return {
+                journeys: journeysOf(report, request.persona),
+                runIds,
+                ...(broke === undefined ? {} : { error: `The drive broke: ${broke}` }),
+            };
+        }
+        finally {
+            // Closing the tab is what ends the session, and the session's end is what writes the run.
+            await releaseLease(caller, opened.leased);
+        }
+    }
+    finally {
+        await caller.close().catch(() => undefined);
+    }
+}
+/** Wait, bounded, for the daemon to write the drive's runs; a run that never lands is not sent. */
+async function waitForRuns(reticleRoot, runIds) {
+    const runsDir = join(reticleRoot, ReticleDir.RUNS_SUBDIR);
+    for (let waited = 0; waited < RUN_WRITE_WAIT_MS; waited += RUN_WRITE_POLL_MS) {
+        if (runIds.every((id) => existsSync(join(runsDir, `${id}.json`))))
+            return;
+        await new Promise((resolve) => setTimeout(resolve, RUN_WRITE_POLL_MS));
+    }
+}
+/** `reticle try`, wired to this machine. Returns the exit code. */
+export async function cmdTry(argv, cloudCommands) {
+    const parsed = parseTryArgs(argv);
+    if ('error' in parsed) {
+        process.stderr.write(`${parsed.error}\n`);
+        return EXIT_FAIL;
+    }
+    const cwd = process.cwd();
+    // The project this folder belongs to, else this folder: the lease writes the run here, and this is
+    // where try waits for it and pushes it from — wherever the daemon happened to be started.
+    const reticleRoot = callerArtifactRoot(cwd) ?? join(cwd, ReticleDir.ROOT);
+    const port = tryPort(cwd);
+    return runTry(parsed, {
+        linked: linkedCloudPort(createNodeFileSystem(), reticleRoot, homedir(), process.env),
+        requestDrive: (cloud) => requestFreeDrive(cloud, FreeDriveKind.TRY),
+        drive: (request) => driveThroughDaemon(port, request, reticleRoot),
+        sync: async (runIds) => {
+            await waitForRuns(reticleRoot, runIds);
+            return EXIT_OK === (await cloudCommands.push());
+        },
+        dashboardUrl: cloudCommands.dashboardUrl,
+        out: (line) => process.stdout.write(`${line}\n`),
+        fail: (line) => process.stderr.write(`${line}\n`),
+    });
+}
+// ── how `init` ends ───────────────────────────────────────────────────────────────────────
+/**
+ * How `init` ends once the connection is proved: what Reticle sees of the app, what it is missing,
+ * and the prompt that hands the rest to the coding agent, which proves the first flow. `init` never
+ * drives: the Harness is opt-in and unlocks at a coverage score (core's `instrumentation-coverage.ts`), and a
+ * freshly wired app is rarely there yet.
+ *
+ * Read from the daemon's `/status`, the same coverage `doctor` prints, so the two never disagree.
+ */
+/** What a project that is not linked is told, once, at the end. */
+export const UNLINKED_PITCH = [
+    'Results stay on this machine. `reticle connect` saves them to your dashboard and lets Reticle',
+    'Harness test the whole app: a new account gets 10 free credits.',
+];
+/** Prove one flow with the coding agent: the line every ending names. */
+export const msgProveOneFlow = (url) => `Then ask your coding agent: "Use Reticle to prove one flow in ${url}: drive it, and end with ` +
+    'reticle_act_and_wait and an until on the last step."';
+const names = (value) => Array.isArray(value)
+    ? value.flatMap((item) => {
+        const name = 'object' === typeof item && null !== item
+            ? item['capability']
+            : item;
+        return 'string' === typeof name ? [name] : [];
+    })
+    : [];
+/**
+ * The closing lines for one tab's coverage, as `/status` reports it: the score, what is missing, the
+ * Harness gate in its own sentence, and the prompt for the coding agent. Pure.
+ */
+export function initCoverageLines(tab, url) {
+    const gate = asRecord(tab?.['harnessGate']);
+    const percent = gate['percent'];
+    if (tab === undefined || 'number' !== typeof percent)
+        return [
+            'Instrumentation is measured on an open tab of the app: run `reticle doctor` with it open.',
+            msgProveOneFlow(url),
+        ];
+    const unseen = [...names(tab['missing']), ...names(tab['notSeenYet'])];
+    const reason = gate['reason'];
+    const prompt = tab['prompt'];
+    return [
+        `Instrumentation: ${String(percent)}%` +
+            (0 === unseen.length ? '' : ` — missing: ${unseen.join(', ')}`),
+        'string' === typeof reason
+            ? reason
+            : `Harness can be switched on: it is off until you switch it on in the HUD's Settings.`,
+        ...('string' === typeof prompt
+            ? [
+                'Paste this into your coding agent; it closes the gaps and proves the first flow:',
+                ...prompt.split('\n').map((line) => `  ${line}`),
+            ]
+            : [msgProveOneFlow(url)]),
+    ];
+}
+/** The project's own `.reticle`, where the drive's flow and run land and where its link lives. */
+const projectRoot = (appDir) => callerArtifactRoot(appDir) ?? join(appDir, ReticleDir.ROOT);
+/**
+ * This project's runs and flows that will never reach the dashboard as things stand, one line each:
+ * not linked, no key for its host, flow sync off, or refused. A linked root's pending runs are left
+ * out, because the daemon sends them within seconds and saying so would be noise.
+ */
+export async function strandedWorkLines(appDir) {
+    const fs = createNodeFileSystem();
+    const cloud = () => resolveProjectCloud(fs, projectRoot(appDir), homedir(), process.env);
+    const roots = await unsyncedRoots([projectRoot(appDir)], async () => {
+        const c = await cloud();
+        return null !== c.config && null !== c.projectId;
+    }, async () => (await cloud()).policy.flows);
+    return roots
+        .filter((entry) => !entry.linked || 0 < entry.flows)
+        .map((entry) => `⚠ ${describeUnsynced(entry, appDir)}`);
+}
+/** The tab `init` proved, out of `/status`: by session, else the only one on the same url. */
+function tabIn(status, sessionId, url) {
+    const list = asRecord(status)['coverage'];
+    if (!Array.isArray(list))
+        return undefined;
+    const tabs = list.map((entry) => asRecord(entry));
+    return (tabs.find((tab) => sessionId === tab['sessionId']) ??
+        tabs.find((tab) => 'string' === typeof tab['url'] && tab['url'].startsWith(url)));
+}
+/**
+ * How `init` ends: the coverage score, the gaps and the agent prompt, the pitch when the project is
+ * not linked, then what will never reach the dashboard. Nothing is driven. Never throws.
+ */
+export async function initFirstFlow(ctx, say) {
+    if (ctx.firstRun) {
+        // A leased proof's tab has closed; another open tab of the same app still answers for it.
+        const status = await fetchStatus(ctx.bridgePort).catch(() => undefined);
+        say('');
+        for (const line of initCoverageLines(tabIn(status, ctx.sessionId, ctx.url), ctx.url))
+            say(line);
+        const linked = linkedCloudPort(createNodeFileSystem(), projectRoot(ctx.appDir), homedir(), process.env);
+        if (null === (await linked().catch(() => null)))
+            for (const line of UNLINKED_PITCH)
+                say(line);
+    }
+    for (const line of await strandedWorkLines(ctx.appDir).catch(() => []))
+        say(line);
+    return { flowSaved: false };
+}