@reticlehq/server 3.6.0 → 3.7.0

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 };
+}

package/dist/command/cli/tutorial.d.ts

@@ -1,19 +1,3 @@
-/**
- * The tutorial: one sequence, two audiences.
- *
- * A human wants to know what to do next and why it is worth doing. An agent wants the exact call and
- * the exact shape of the answer, because prose it has to interpret is a turn it has to spend. Write
- * for one and hope the other copes, and you get a page agents skip and humans skim.
- *
- * What both MUST share is the order. Two audiences taking different routes through one product is
- * how a support answer stops matching what anybody actually did.
- *
- * The sequence is not arbitrary either. It ends at a VERDICT because a tour that ends at "you can see
- * the page now" has taught the least valuable half: looking is not verifying, and an agent that
- * learns only to look will report that it looked. And it declares the consequence BEFORE acting,
- * because that ordering IS the idea — naming what should happen first is the difference between a
- * check and a rationalisation written afterwards.
- */
 import { type OnboardingStep } from '@reticlehq/core/telemetry';
 /**
  * The two ONBOARD steps a SHOWN tour can honestly answer.
@@ -30,87 +14,3 @@ import { type OnboardingStep } from '@reticlehq/core/telemetry';
  * which is the only place they are a fact.
  */
 export declare function tutorialShownSteps(): OnboardingStep[];
-export declare const TutorialAudience: {
-    /** Prose, and a reason per step. */
-    readonly HUMAN: "human";
-    /** The call, and what comes back. */
-    readonly AGENT: "agent";
-};
-export type TutorialAudience = (typeof TutorialAudience)[keyof typeof TutorialAudience];
-export interface TutorialStep {
-    id: string;
-    /** What this step is, in words. Always present: an agent reading only calls learns the what, not the why. */
-    say: string;
-    /** Why it is worth doing. The half that stops a tutorial being a list of keystrokes. */
-    why: string;
-    /** The exact call, for the audience that would otherwise have to infer it from the prose. */
-    call?: string;
-}
-/**
- * The same steps, shaped for who is reading.
- *
- * The agent form keeps the prose as well as the call. An agent that has only the call learns what to
- * type and not what it means, which is exactly the reader that later reports a green it cannot
- * explain.
- */
-export declare function tutorialScript(audience: TutorialAudience): TutorialStep[];
-/**
- * The script as text for whoever asked.
- *
- * A human gets the reason on its own line, because the reason is what makes the step worth doing and
- * a list of commands without them is a keystroke tour. An agent gets the call, because prose it has
- * to interpret is a turn it has to spend — and it gets the prose too, since an agent that has only
- * the call learns what to type and not what it means, which is the reader that later reports a green
- * it cannot explain.
- */
-/**
- * What to do now the tour is over.
- *
- * Every other stage of setup ends by naming the next command — `install.sh` points at `reticle init`
- * and this tutorial, `init` points at the dev server and `status`. This one ended at step 4 and
- * stopped, so the stage whose entire job is to teach the sequence was the only one that never said
- * how to start it. The steps above describe tools that need an instrumented, running app, and a
- * reader who has just been told that a verdict is the point and shown no way to reach one is exactly
- * where a funnel stalls.
- *
- * Split from `renderTutorial` so the closing block is a value a caller can assert on, rather than a
- * string only findable by matching rendered prose.
- */
-export declare function tutorialNextSteps(audience: TutorialAudience, restartAgent?: boolean): string;
-/**
- * What the installer prints when it has finished.
- *
- * Installation and onboarding are ONE script, so the tour is not conditional on anything. Gating it
- * on `process.stdout.isTTY` does not work: that is `undefined` through every pipe, so the tour never
- * prints. A heuristic that silently answers "nobody is watching" is worse than no heuristic.
- *
- * It ends with the tour's OWN closing. Installing changes no project: the app is wired the first time
- * an agent uses Reticle in it (see first-run-wiring.ts).
- */
-export declare function installClosing(registered?: boolean): string;
-export declare function renderTutorial(audience: TutorialAudience): string;
-export type DemoPlan = {
-    ok: true;
-    ref: string;
-    name: string;
-    call: string;
-} | {
-    ok: false;
-    because: string;
-};
-/**
- * Pick something safe on THIS page, and build the call that proves it moved.
- *
- * The sequence is the tutorial's; what this adds is a target from the app actually in front of the
- * user, because a walkthrough against a fixture teaches the fixture. The consequence is declared in
- * the call rather than checked afterwards — a demo that ends without a verdict would teach the exact
- * habit the tutorial exists to correct.
- *
- * Refusing is a real outcome. A page with nothing safe on it gets told so, because demonstrating on
- * "Delete account" to avoid an awkward message is not a trade anybody would make deliberately.
- */
-export declare function demoPlan(controls: readonly {
-    ref: string;
-    name: string;
-    role?: string;
-}[]): DemoPlan;

package/dist/command/cli/tutorial.js

@@ -1,34 +1,4 @@
-/**
- * The tutorial: one sequence, two audiences.
- *
- * A human wants to know what to do next and why it is worth doing. An agent wants the exact call and
- * the exact shape of the answer, because prose it has to interpret is a turn it has to spend. Write
- * for one and hope the other copes, and you get a page agents skip and humans skim.
- *
- * What both MUST share is the order. Two audiences taking different routes through one product is
- * how a support answer stops matching what anybody actually did.
- *
- * The sequence is not arbitrary either. It ends at a VERDICT because a tour that ends at "you can see
- * the page now" has taught the least valuable half: looking is not verifying, and an agent that
- * learns only to look will report that it looked. And it declares the consequence BEFORE acting,
- * because that ordering IS the idea — naming what should happen first is the difference between a
- * check and a rationalisation written afterwards.
- */
 import { OnboardingPhase, OnboardingStepStatus, } from '@reticlehq/core/telemetry';
-import { TOUR_STEPS } from '@reticlehq/core/tour';
-/**
- * The steps, from the one place both surfaces read them.
- *
- * They used to be a private array here, which is why the browser could not render the same tour:
- * nothing outside this package could see them. `title` and `anchor` are the carousel's business and
- * a terminal ignores them.
- */
-const STEPS = TOUR_STEPS.map((s) => ({
-    id: s.id,
-    say: s.say,
-    why: s.why,
-    ...(undefined === s.call ? {} : { call: s.call }),
-}));
 /**
  * The two ONBOARD steps a SHOWN tour can honestly answer.
  *
@@ -50,151 +20,3 @@ export function tutorialShownSteps() {
         status: OnboardingStepStatus.COMPLETED,
     }));
 }
-export const TutorialAudience = {
-    /** Prose, and a reason per step. */
-    HUMAN: 'human',
-    /** The call, and what comes back. */
-    AGENT: 'agent',
-};
-/**
- * The same steps, shaped for who is reading.
- *
- * The agent form keeps the prose as well as the call. An agent that has only the call learns what to
- * type and not what it means, which is exactly the reader that later reports a green it cannot
- * explain.
- */
-export function tutorialScript(audience) {
-    return STEPS.map((step) => TutorialAudience.AGENT === audience
-        ? { ...step, call: step.call ?? '' }
-        : // A human is not handed a raw call to paste without understanding it; the prose carries it.
-            { id: step.id, say: step.say, why: step.why });
-}
-/**
- * The script as text for whoever asked.
- *
- * A human gets the reason on its own line, because the reason is what makes the step worth doing and
- * a list of commands without them is a keystroke tour. An agent gets the call, because prose it has
- * to interpret is a turn it has to spend — and it gets the prose too, since an agent that has only
- * the call learns what to type and not what it means, which is the reader that later reports a green
- * it cannot explain.
- */
-/**
- * What to do now the tour is over.
- *
- * Every other stage of setup ends by naming the next command — `install.sh` points at `reticle init`
- * and this tutorial, `init` points at the dev server and `status`. This one ended at step 4 and
- * stopped, so the stage whose entire job is to teach the sequence was the only one that never said
- * how to start it. The steps above describe tools that need an instrumented, running app, and a
- * reader who has just been told that a verdict is the point and shown no way to reach one is exactly
- * where a funnel stalls.
- *
- * Split from `renderTutorial` so the closing block is a value a caller can assert on, rather than a
- * string only findable by matching rendered prose.
- */
-export function tutorialNextSteps(audience, restartAgent = false) {
-    const lines = TutorialAudience.AGENT === audience
-        ? [
-            'Next:',
-            '  reticle_session list    # the first call wires this project: Reticle runs init itself',
-            '                          # and names every file it changed — tell the user which',
-            '  then run the four steps above against it, and report the verdict',
-        ]
-        : [
-            'Next:',
-            ...(restartAgent
-                ? ['  restart your agent                 # it loads new tools only when it starts']
-                : []),
-            '',
-            // One line: the terminal wraps it at the reader's width, not ours.
-            'Ask your agent to verify one real flow in your project. Nothing in your app changed at install: the first time the agent uses Reticle there, Reticle wires the app, starts it, and tells you which files it changed.',
-        ];
-    return lines.join('\n');
-}
-/**
- * What the installer prints when it has finished.
- *
- * Installation and onboarding are ONE script, so the tour is not conditional on anything. Gating it
- * on `process.stdout.isTTY` does not work: that is `undefined` through every pipe, so the tour never
- * prints. A heuristic that silently answers "nobody is watching" is worse than no heuristic.
- *
- * It ends with the tour's OWN closing. Installing changes no project: the app is wired the first time
- * an agent uses Reticle in it (see first-run-wiring.ts).
- */
-export function installClosing(registered = true) {
-    // One line a step. The reasons are for `reticle tutorial`; right after an install they turned a
-    // four-step idea into twenty-five lines of prose between the reader and the next command.
-    const steps = tutorialScript(TutorialAudience.HUMAN).map((step, index) => `  ${String(index + 1)}. ${INSTALL_SAYS[step.id] ?? step.say}`);
-    return [
-        '',
-        '✓ Reticle is installed. How it works:',
-        ...steps,
-        '',
-        tutorialNextSteps(TutorialAudience.HUMAN, registered),
-    ].join('\n');
-}
-/**
- * Tour steps reworded for a reader who has no app wired yet. The in-app tour's "That panel is
- * Reticle" points at a panel on screen; straight after an install there is none to point at.
- */
-const INSTALL_SAYS = {
-    connect: 'The first time your agent uses Reticle in a project, it wires the app and a Reticle panel appears in it: your proof the SDK is connected.',
-};
-export function renderTutorial(audience) {
-    const steps = tutorialScript(audience)
-        .map((step, index) => {
-        const head = `${String(index + 1)}. ${step.say}`;
-        const why = `   why: ${step.why}`;
-        return step.call === undefined || 0 === step.call.length
-            ? `${head}\n${why}`
-            : `${head}\n${why}\n   ${step.call}`;
-    })
-        .join('\n\n');
-    return `${steps}\n\n${tutorialNextSteps(audience)}`;
-}
-/**
- * Names that must never be demonstrated on.
- *
- * Deliberately broad, and deliberately matched on the NAME a user reads rather than on anything
- * structural. A demo runs unattended against an app whose author has never seen this code, so the
- * cost of being wrong is asymmetric: refusing a harmless button wastes a demo, clicking a harmful
- * one costs somebody their data. When those are the two errors available, take the first one every
- * time.
- *
- * `cancel` is here for the case that reads backwards: "Cancel subscription" is destructive, and a
- * word-boundary match on a dismissive "Cancel" would be a false refusal — which is the cheap error.
- */
-const UNSAFE_TO_DEMO = /delete|remove|deploy|publish|pay|purchase|buy|checkout|cancel|revoke|archive|reset|destroy|drop|send|submit|confirm/i;
-/**
- * Pick something safe on THIS page, and build the call that proves it moved.
- *
- * The sequence is the tutorial's; what this adds is a target from the app actually in front of the
- * user, because a walkthrough against a fixture teaches the fixture. The consequence is declared in
- * the call rather than checked afterwards — a demo that ends without a verdict would teach the exact
- * habit the tutorial exists to correct.
- *
- * Refusing is a real outcome. A page with nothing safe on it gets told so, because demonstrating on
- * "Delete account" to avoid an awkward message is not a trade anybody would make deliberately.
- */
-export function demoPlan(controls) {
-    const safe = controls.find((c) => !UNSAFE_TO_DEMO.test(c.name));
-    if (safe === undefined) {
-        return {
-            ok: false,
-            because: 0 === controls.length
-                ? 'nothing interactive is on this page yet — load the app and try again'
-                : 'no control here is safe to demonstrate on: every one reads as something that commits. ' +
-                    'Drive it yourself with a consequence you choose.',
-        };
-    }
-    return {
-        ok: true,
-        ref: safe.ref,
-        name: safe.name,
-        // `{ element: { testid } }` reads naturally and is REFUSED: a consequence is a predicate with a
-        // `kind`, and act_and_wait says so in its own refusal text. This line is a call the reader is
-        // meant to paste, so a plausible-but-unparseable spelling here teaches the exact mistake that
-        // tool exists to catch.
-        call: `reticle_act_and_wait { ref: "${safe.ref}", action: "click", ` +
-            `until: { kind: "element", by: "testid", value: "<what should appear>" } }`,
-    };
-}

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

@@ -0,0 +1,19 @@
+/**
+ * `reticle verify --results-json <file>`: the run, one line per journey, for a machine to read.
+ *
+ * The rendered report is for a person, and a CI step that has to post per-journey verdicts somewhere
+ * else would otherwise scrape it. Three words only, the engine's own: a skipped flow is `unknown`,
+ * never rounded up to `yes`, and the run is `yes` only when every journey is.
+ */
+import { Verified, type ReticleVerificationRun } from '@reticlehq/core';
+type JourneyVerdict = typeof Verified.YES | typeof Verified.NO | typeof Verified.UNKNOWN;
+export interface VerifyResults {
+    verdict: JourneyVerdict;
+    results: {
+        journey: string;
+        verdict: JourneyVerdict;
+        reason?: string;
+    }[];
+}
+export declare function verifyResults(run: ReticleVerificationRun): VerifyResults;
+export {};