@reticlehq/server 3.5.0 → 3.7.0

package/dist/features/harness/platform/local-apps.js

@@ -0,0 +1,280 @@
+/**
+ * The apps this machine has connected, told to the platform so its chat can list them by name.
+ *
+ * The chat used to ask for a `localhost` address, and an address names nothing: two projects on
+ * `localhost:3000` are one address, and one project restarted on another port is two. So an app here
+ * is a project checkout on a machine, keyed by a hash of both, and its address is only where it was
+ * last open. Neither the project's path nor the home directory leaves the machine, only their hash.
+ *
+ * Every few seconds, with or without an app open, each linked project's credential reports its apps.
+ * The answer can name apps somebody asked to bring back (opened here, headless) and say a drive is
+ * waiting, which is how a daemon with nothing open hears about one without polling every few seconds.
+ */
+import { createHash } from 'node:crypto';
+import { relative, sep } from 'node:path';
+import { LinkReportKey, LinkPath, PLATFORM_LINK_VERSION, RETICLE_URL_PARAM, parseLinkNotices, } from '@reticlehq/core';
+import { pickDriveSession } from './remote-drive.js';
+/** How often apps are reported. The platform counts an app live for two and a half of these. */
+export const LOCAL_APPS_REPORT_MS = 10_000;
+const REQUEST_TIMEOUT_MS = 10_000;
+/** How long a drive waits for an app it opened to connect before it is refused. */
+export const APP_OPEN_WAIT_MS = 20_000;
+const APP_OPEN_POLL_MS = 250;
+const KEY_LENGTH = 16;
+/** The shell a plain browser tab reports: not worth a word on a card that says what it is built with. */
+const WEB_RUNTIME = 'web';
+/** `path` under `home` as `~/...`, so no home directory leaves the machine in a report. */
+export function homeRelative(path, home) {
+    const inside = relative(home, path);
+    if (0 === inside.length)
+        return '~';
+    if (inside.startsWith('..') || inside.startsWith(sep) || /^[a-zA-Z]:/.test(inside))
+        return path;
+    return `~/${inside.split(sep).join('/')}`;
+}
+const hash = (text) => createHash('sha256').update(text).digest('hex').slice(0, KEY_LENGTH);
+/** This machine: a stable id that is not its home path, and the name a person knows it by. */
+export const machineOf = (hostname, home) => ({
+    id: hash(`${hostname}\u0000${home}`),
+    name: hostname.replace(/\.local$/i, ''),
+});
+/**
+ * One project checkout on one machine. Its port is not part of it. The tab's projectId is: a daemon
+ * that cannot map a project to its checkout files every such project under one shared directory.
+ */
+export const appKeyOf = (machineId, projectDir, projectId) => hash(`${machineId}\u0000${projectDir}\u0000${projectId ?? ''}`);
+const LOOPBACK_HOSTS = new Set(['localhost', '127.0.0.1', '[::1]']);
+/** What a refused open is told. */
+export const NOT_AN_APP_ADDRESS = 'Reticle only opens a web address on this machine or one of the apps already open here.';
+/**
+ * Whether the daemon may open an address the platform named: a web page on this machine, or one on
+ * an origin a connected tab already has. Never a file, and never anywhere else on the network.
+ */
+export function mayOpen(url, openUrls) {
+    let target;
+    try {
+        target = new URL(url);
+    }
+    catch {
+        return false;
+    }
+    if ('http:' !== target.protocol && 'https:' !== target.protocol)
+        return false;
+    if (LOOPBACK_HOSTS.has(target.hostname) || target.hostname.endsWith('.localhost'))
+        return true;
+    return openUrls.some((open) => {
+        try {
+            return new URL(open).origin === target.origin;
+        }
+        catch {
+            return false;
+        }
+    });
+}
+/** A project id as a name: the SDK stamps `<package>-<8 hex>`, and the hash means nothing to a person. */
+export const nameFromProjectId = (projectId) => projectId.replace(/-[0-9a-f]{8}$/, '');
+const RETICLE_MARKS = new Set(Object.values(RETICLE_URL_PARAM));
+/** The address as the app knows it: the params Reticle put on it to adopt a tab are not the app's. */
+export const withoutMarks = (raw) => {
+    try {
+        const url = new URL(raw);
+        for (const mark of [...url.searchParams.keys()])
+            if (RETICLE_MARKS.has(mark))
+                url.searchParams.delete(mark);
+        return url.href;
+    }
+    catch {
+        return raw;
+    }
+};
+/** Every channel either tab announced, once each; undefined when neither said. */
+function mergedChannels(a, b) {
+    return a === undefined && b === undefined
+        ? undefined
+        : [...new Set([...(a ?? []), ...(b ?? [])])];
+}
+/** Every gap either tab recorded, once per kind + missing, the first seen kept. */
+function mergedGaps(a, b) {
+    const out = new Map();
+    for (const gap of [...(a ?? []), ...(b ?? [])]) {
+        const id = `${gap.kind}\u0000${gap.missing}`;
+        if (!out.has(id))
+            out.set(id, gap);
+    }
+    return [...out.values()];
+}
+/** `app` carrying the merged channels and gaps, omitting each when there is nothing to say. */
+function withSeen(app, channels, gaps) {
+    return {
+        ...app,
+        ...(channels === undefined ? {} : { [LinkReportKey.CHANNELS]: channels }),
+        ...(0 === gaps.length ? {} : { [LinkReportKey.GAPS]: gaps }),
+    };
+}
+/**
+ * The apps to report, grouped by the platform credential each one's project is linked with. The
+ * linked credential is reported even with no app open: it is how the chat knows the machine is there
+ * to open one. A tab whose project is not linked is left out: no chat can drive it.
+ */
+export async function appsByPlatform(tabs, linked, machineId, describe) {
+    const groups = new Map();
+    const group = (platform) => {
+        const id = `${platform.url}\u0000${platform.apiKey}`;
+        const found = groups.get(id) ?? { platform, apps: new Map() };
+        groups.set(id, found);
+        return found;
+    };
+    if (undefined !== linked)
+        group(linked);
+    // A visible tab speaks for its project over a hidden one.
+    const ordered = [...tabs].sort((a, b) => Number(a.hidden) - Number(b.hidden));
+    for (const tab of ordered) {
+        const about = await describe(tab).catch(() => undefined);
+        if (undefined === about?.platform)
+            continue;
+        const key = appKeyOf(machineId, about.dir, tab.projectId);
+        const apps = group(about.platform).apps;
+        // Of two tabs of one app, the one that has seen the most speaks for it (a tie keeps the earlier,
+        // so a visible one still speaks over a hidden one). What they have SEEN is merged, so the setup
+        // score does not depend on which tab happened to report: a fresh tab opened beside a driven one
+        // once dropped it and locked the Harness.
+        const held = apps.get(key);
+        const channels = mergedChannels(held?.[LinkReportKey.CHANNELS], tab.channels);
+        const gaps = mergedGaps(held?.[LinkReportKey.GAPS], tab.gaps);
+        if (held !== undefined &&
+            (tab.channels?.length ?? 0) <= (held[LinkReportKey.CHANNELS]?.length ?? 0)) {
+            apps.set(key, withSeen(held, channels, gaps));
+            continue;
+        }
+        const stack = [
+            ...new Set([...tab.adapters, ...(tab.runtime === undefined ? [] : [tab.runtime])]),
+        ].filter((part) => WEB_RUNTIME !== part);
+        apps.set(key, {
+            key,
+            name: about.name,
+            url: withoutMarks(tab.url),
+            ...(tab.title === undefined ? {} : { title: tab.title }),
+            stack,
+            ...(tab.sdkVersion === undefined ? {} : { sdkVersion: tab.sdkVersion }),
+            ...(0 === tab.adapters.length ? {} : { [LinkReportKey.ADAPTERS]: tab.adapters }),
+            ...(tab.notApplicable === undefined
+                ? {}
+                : { [LinkReportKey.NOT_APPLICABLE]: tab.notApplicable }),
+            ...withSeen({}, channels, gaps),
+        });
+    }
+    return [...groups.values()].map(({ platform, apps }) => ({ platform, apps: [...apps.values()] }));
+}
+export function startAppReports(deps) {
+    const doFetch = deps.fetch ?? ((url, init) => fetch(url, init));
+    let busy = false;
+    /** Notices already shown, by what they say: the platform repeats them on every report. */
+    const told = new Set();
+    const tick = async () => {
+        if (busy)
+            return;
+        busy = true;
+        try {
+            const extras = (await deps.extras?.().catch(() => undefined)) ?? {};
+            for (const { platform, apps } of await deps.apps()) {
+                try {
+                    const res = await doFetch(`${platform.url}${LinkPath.APPS}`, {
+                        method: 'POST',
+                        headers: {
+                            'content-type': 'application/json',
+                            authorization: `Bearer ${platform.apiKey}`,
+                        },
+                        body: JSON.stringify({
+                            machine: deps.machine,
+                            reticleVersion: deps.version,
+                            protocol: PLATFORM_LINK_VERSION,
+                            capabilities: deps.capabilities,
+                            apps,
+                            ...(extras.devServers === undefined
+                                ? {}
+                                : { [LinkReportKey.DEV_SERVERS]: extras.devServers }),
+                            ...(extras.helloFailure === undefined
+                                ? {}
+                                : { [LinkReportKey.HELLO_FAILURE]: extras.helloFailure }),
+                            ...(extras.unsynced === undefined
+                                ? {}
+                                : { [LinkReportKey.UNSYNCED]: extras.unsynced }),
+                        }),
+                        signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+                    });
+                    if (!res.ok)
+                        continue;
+                    const answer = (await res.json());
+                    for (const notice of parseLinkNotices(answer.notices)) {
+                        const key = `${platform.apiKey}\u0000${notice.text}`;
+                        if (told.has(key))
+                            continue;
+                        told.add(key);
+                        deps.notify?.(notice, platform);
+                    }
+                    const open = new Set(apps.map((app) => app.key));
+                    for (const wake of Array.isArray(answer.wake) ? answer.wake : []) {
+                        const { key, url } = (wake ?? {});
+                        if ('string' !== typeof key || 'string' !== typeof url || open.has(key))
+                            continue;
+                        open.add(key);
+                        deps.log?.(`reticle: opening ${url}, asked for from the platform chat`);
+                        await deps.open(url, key).catch((error) => {
+                            deps.log?.(`reticle: could not open ${url}: ${String(error)}`);
+                        });
+                    }
+                    if (true === answer.pendingDrive)
+                        deps.drivePending(platform);
+                }
+                catch {
+                    // Offline, or the platform is down: the next report tries again.
+                }
+            }
+        }
+        catch {
+            // The credentials could not be read: nothing to report this time.
+        }
+        finally {
+            busy = false;
+        }
+    };
+    const timer = setInterval(() => void tick(), deps.intervalMs ?? LOCAL_APPS_REPORT_MS);
+    timer.unref();
+    const reports = {
+        tick,
+        stop: () => {
+            clearInterval(timer);
+            if (running === reports)
+                running = undefined;
+        },
+    };
+    running = reports;
+    return reports;
+}
+/** The daemon's running reports. ponytail: one per daemon, the last one started. */
+let running;
+/**
+ * Report now rather than on the next tick: the Harness gate just learned what an app's pages carry,
+ * and the platform, which locks a drive on its last report, would otherwise refuse on the old one.
+ */
+export const reportAppsNow = () => running?.tick() ?? Promise.resolve();
+/**
+ * The tab a drive the chat attached to one app uses: a tab of that app and no other, even on the
+ * same port. None open: open the app, and wait for it to connect. Null when it never does.
+ */
+export async function pickAppTab(app, goal, tabs, keyOf, open, waitMs = APP_OPEN_WAIT_MS) {
+    const ofApp = () => tabs().filter((tab) => keyOf(tab.sessionId) === app.key);
+    const now = pickDriveSession(ofApp(), goal);
+    if (now !== undefined)
+        return now;
+    if (null === app.url)
+        return null;
+    await open(app.url).catch(() => undefined);
+    for (let waited = 0; waited <= waitMs; waited += APP_OPEN_POLL_MS) {
+        const opened = pickDriveSession(ofApp(), goal);
+        if (opened !== undefined)
+            return opened;
+        await new Promise((resolve) => setTimeout(resolve, APP_OPEN_POLL_MS));
+    }
+    return null;
+}

package/dist/features/harness/platform/persona-credentials.d.ts

@@ -0,0 +1,20 @@
+/**
+ * The credentials a persona names, taken out of it before it leaves this machine.
+ *
+ * A persona that said "sign in as ana@acme.test, password: hunter2" was driven with the platform's
+ * default address and a 401, so every journey behind a login failed; and the persona travelled
+ * verbatim, so the password was stored in the synced run. The values become secret fields this
+ * machine fills (the platform types a placeholder for a field it knows only by name, see
+ * `server-driver.ts`), the password is redacted from the text, and the persona's own values win over
+ * a `RETICLE_SECRET_*` set in the environment, which wins over the platform's default.
+ */
+/** What stands in for a password in the text that is sent and stored. */
+export declare const REDACTED_SECRET = "[redacted]";
+export interface PersonaCredentials {
+    /** The persona with its password redacted: what may be sent to the platform and stored. */
+    persona: string;
+    /** Secret-field variables the drive fills from, persona values only. */
+    secrets: Record<string, string>;
+}
+/** Take the email and password a persona names out of it. */
+export declare function personaCredentials(persona: string): PersonaCredentials;

package/dist/features/harness/platform/persona-credentials.js

@@ -0,0 +1,69 @@
+/**
+ * The credentials a persona names, taken out of it before it leaves this machine.
+ *
+ * A persona that said "sign in as ana@acme.test, password: hunter2" was driven with the platform's
+ * default address and a 401, so every journey behind a login failed; and the persona travelled
+ * verbatim, so the password was stored in the synced run. The values become secret fields this
+ * machine fills (the platform types a placeholder for a field it knows only by name, see
+ * `server-driver.ts`), the password is redacted from the text, and the persona's own values win over
+ * a `RETICLE_SECRET_*` set in the environment, which wins over the platform's default.
+ */
+/** The prefix a secret field's variable carries; the server driver reads the same. */
+const SECRET_ENV_PREFIX = 'RETICLE_SECRET_';
+/**
+ * The field names an email is offered under, as the platform derives them from a label.
+ * ponytail: the common sign-in labels only; a form labelled otherwise gets the platform's default.
+ */
+const EMAIL_FIELDS = ['EMAIL', 'EMAIL_ADDRESS', 'WORK_EMAIL', 'YOUR_EMAIL'];
+const PASSWORD_FIELDS = [
+    'PASSWORD',
+    'CURRENT_PASSWORD',
+    'NEW_PASSWORD',
+    'CREATE_A_PASSWORD',
+    'CHOOSE_A_PASSWORD',
+    'CONFIRM_PASSWORD',
+];
+/**
+ * The person a persona is, when it opens with their name: "Nina Patel, who …". A sign-up form asks
+ * for it, and the Harness typed "reticle harness" into First name. Only a leading name followed by a
+ * comma counts; "an admin who …" names nobody and fills nothing.
+ */
+const NAME = /^\s*(\p{Lu}\p{Ll}+)(?:\s+(\p{Lu}\p{Ll}+))?\s*,/u;
+/** What stands in for a password in the text that is sent and stored. */
+export const REDACTED_SECRET = '[redacted]';
+const EMAIL = /[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}/;
+/**
+ * "password: x", "password is x", "password = x", a quoted value right after the word, or an
+ * unquoted one with a digit in it ("password Nina-pass-12345!"): a word with no digit after
+ * "password" is prose ("reset the password from the menu"), never a value.
+ */
+/**
+ * An unquoted value stops at a closing bracket, and a sentence's full stop is not part of it:
+ * "(password: x!)" typed "x!)" and every sign-in was refused.
+ */
+const PASSWORD = /\bpass(?:word|code)\b(?:\s*(?::|=|\bis\b)\s*(?:"([^"\n]+)"|“([^”\n]+)”|([^\s"“,;()]+?)(?=\.?(?:\s|$|[,;)])))|\s+(?:"([^"\n]+)"|“([^”\n]+)”)|\s+([^\s"“,;()]*\d[^\s"“,;()]*?)(?=\.?(?:\s|$|[,;)])))/i;
+/** Take the email and password a persona names out of it. */
+export function personaCredentials(persona) {
+    const secrets = {};
+    const name = NAME.exec(persona);
+    if (name?.[1] !== undefined) {
+        const full = name[2] === undefined ? name[1] : `${name[1]} ${name[2]}`;
+        secrets[`${SECRET_ENV_PREFIX}FIRST_NAME`] = name[1];
+        secrets[`${SECRET_ENV_PREFIX}FULL_NAME`] = full;
+        secrets[`${SECRET_ENV_PREFIX}NAME`] = full;
+        if (name[2] !== undefined)
+            secrets[`${SECRET_ENV_PREFIX}LAST_NAME`] = name[2];
+    }
+    const email = EMAIL.exec(persona)?.[0];
+    if (email !== undefined)
+        for (const field of EMAIL_FIELDS)
+            secrets[`${SECRET_ENV_PREFIX}${field}`] = email;
+    const match = PASSWORD.exec(persona);
+    const password = match?.slice(1).find((group) => group !== undefined);
+    if (null === match || password === undefined)
+        return { persona, secrets };
+    for (const field of PASSWORD_FIELDS)
+        secrets[`${SECRET_ENV_PREFIX}${field}`] = password;
+    const redacted = match[0].replace(password, REDACTED_SECRET);
+    return { persona: persona.replace(match[0], redacted), secrets };
+}

package/dist/features/harness/platform/platform-drives.d.ts

@@ -0,0 +1,61 @@
+/**
+ * The two platform calls a drive needs outside its own turns: the grant that pays for a drive, and
+ * the run the platform kept once the local record is gone.
+ *
+ * Both answer with a value and never throw: an unreachable platform is a sentence to show, not a
+ * crash in the CLI or in the HUD's button handler.
+ */
+/** What the grant is for: `reticle try`'s one drive, or a drive started from the HUD or an agent. */
+export declare const FreeDriveKind: {
+    readonly TRY: "try";
+    readonly EXPLORE: "explore";
+};
+export type FreeDriveKind = (typeof FreeDriveKind)[keyof typeof FreeDriveKind];
+/** One HTTP request, narrowed so a test answers it without a network. */
+export type PlatformFetch = (url: string, init: {
+    method: string;
+    headers: Record<string, string>;
+    body?: string;
+}) => Promise<{
+    status: number;
+    text(): Promise<string>;
+}>;
+/** The drive the platform granted, or why it would not. */
+export type FreeDrive = {
+    granted: true;
+    driveId: string;
+} | {
+    granted: false;
+    needsCard: boolean;
+    message: string;
+    hint?: string;
+};
+interface Platform {
+    url: string;
+    apiKey: string;
+}
+/** The dashboard page where a trial starts, at the origin of whatever link the platform gave. */
+export declare function planUrl(dashboard: string): string;
+/** Ask the platform for a drive it will pay for. Every failure is an answer, never a throw. */
+export declare function requestFreeDrive(platform: Platform, kind: FreeDriveKind, doFetch?: PlatformFetch): Promise<FreeDrive>;
+/**
+ * A synced run as the explore poll answers it, in the poll's own fields.
+ *
+ * The platform serves the run file under `run` with the authoritative verdict (a review overturn
+ * wins) beside it — the dashboard's shape. The poll's agent needs the outcome and where it came from,
+ * not the whole file; `reticle runs <id>` prints the full answer for anyone who wants it.
+ */
+export declare function platformRunAnswer(runId: string, body: Record<string, unknown>): {
+    status: string;
+    runId: string;
+    summary: string;
+};
+/** Said when the platform has no such run: it may simply not have synced yet. */
+export declare const msgRunNotOnPlatform: (runId: string) => string;
+/** The platform's answer for one run (`{ run, verdict, grade, projectName, … }`), or why not. */
+export declare function fetchPlatformRun(platform: Platform, runId: string, doFetch?: PlatformFetch): Promise<{
+    run: Record<string, unknown>;
+} | {
+    error: string;
+}>;
+export {};

package/dist/features/harness/platform/platform-drives.js

@@ -0,0 +1,114 @@
+/**
+ * The two platform calls a drive needs outside its own turns: the grant that pays for a drive, and
+ * the run the platform kept once the local record is gone.
+ *
+ * Both answer with a value and never throw: an unreachable platform is a sentence to show, not a
+ * crash in the CLI or in the HUD's button handler.
+ */
+const FREE_DRIVE_PATH = '/v1/harness/free-drive';
+const RUNS_PATH = '/v1/runs';
+const NEEDS_CARD = 'needs_card';
+const HTTP_PAYMENT_REQUIRED = 402;
+const HTTP_NOT_FOUND = 404;
+/** Where a workspace starts its trial: the dashboard's billing settings, at its origin. */
+const PLAN_PATH = '/settings?group=billing';
+/** What the grant is for: `reticle try`'s one drive, or a drive started from the HUD or an agent. */
+export const FreeDriveKind = { TRY: 'try', EXPLORE: 'explore' };
+const defaultFetch = (url, init) => fetch(url, init);
+const base = (platform) => platform.url.replace(/\/+$/, '');
+const headers = (platform) => ({
+    'content-type': 'application/json',
+    authorization: `Bearer ${platform.apiKey}`,
+});
+function record(text) {
+    try {
+        const parsed = JSON.parse(text);
+        return 'object' === typeof parsed && null !== parsed ? parsed : {};
+    }
+    catch {
+        return {};
+    }
+}
+const str = (value) => ('string' === typeof value ? value : undefined);
+/** The dashboard page where a trial starts, at the origin of whatever link the platform gave. */
+export function planUrl(dashboard) {
+    try {
+        return `${new URL(dashboard).origin}${PLAN_PATH}`;
+    }
+    catch {
+        return `${dashboard.replace(/\/+$/, '')}${PLAN_PATH}`;
+    }
+}
+/** Ask the platform for a drive it will pay for. Every failure is an answer, never a throw. */
+export async function requestFreeDrive(platform, kind, doFetch = defaultFetch) {
+    try {
+        const res = await doFetch(`${base(platform)}${FREE_DRIVE_PATH}`, {
+            method: 'POST',
+            headers: headers(platform),
+            body: JSON.stringify({ kind }),
+        });
+        const body = record(await res.text());
+        const driveId = str(body['driveId']);
+        if (true === body['granted'] && driveId !== undefined)
+            return { granted: true, driveId };
+        const message = str(body['message']) ??
+            `The Reticle platform did not grant a drive (it answered ${String(res.status)}).`;
+        const hint = str(body['hint']);
+        return {
+            granted: false,
+            needsCard: HTTP_PAYMENT_REQUIRED === res.status || NEEDS_CARD === body['error'],
+            message,
+            ...(hint === undefined ? {} : { hint }),
+        };
+    }
+    catch (error) {
+        return {
+            granted: false,
+            needsCard: false,
+            message: `Could not reach the Reticle platform: ${error instanceof Error ? error.message : String(error)}`,
+        };
+    }
+}
+const DRIVE_DONE = 'done';
+const msgFromDashboard = (verdict, checks) => `From the dashboard (the drive itself is no longer on this machine): ${verdict === undefined ? 'no verdict recorded' : `verdict ${verdict}`}, ${String(checks)} check${1 === checks ? '' : 's'}.`;
+/**
+ * A synced run as the explore poll answers it, in the poll's own fields.
+ *
+ * The platform serves the run file under `run` with the authoritative verdict (a review overturn
+ * wins) beside it — the dashboard's shape. The poll's agent needs the outcome and where it came from,
+ * not the whole file; `reticle runs <id>` prints the full answer for anyone who wants it.
+ */
+export function platformRunAnswer(runId, body) {
+    const run = body['run'];
+    const checks = 'object' === typeof run &&
+        null !== run &&
+        Array.isArray(run['checks'])
+        ? run['checks'].length
+        : 0;
+    return { status: DRIVE_DONE, runId, summary: msgFromDashboard(str(body['verdict']), checks) };
+}
+/** Said when the platform has no such run: it may simply not have synced yet. */
+export const msgRunNotOnPlatform = (runId) => `Run ${runId} is not on the Reticle platform: not synced yet, or not found.`;
+/** The platform's answer for one run (`{ run, verdict, grade, projectName, … }`), or why not. */
+export async function fetchPlatformRun(platform, runId, doFetch = defaultFetch) {
+    try {
+        const res = await doFetch(`${base(platform)}${RUNS_PATH}/${encodeURIComponent(runId)}`, {
+            method: 'GET',
+            headers: headers(platform),
+        });
+        if (HTTP_NOT_FOUND === res.status)
+            return { error: msgRunNotOnPlatform(runId) };
+        const body = record(await res.text());
+        if (200 > res.status || 300 <= res.status)
+            return {
+                error: str(body['message']) ??
+                    `The Reticle platform answered ${String(res.status)} for ${runId}.`,
+            };
+        return { run: body };
+    }
+    catch (error) {
+        return {
+            error: `Could not reach the Reticle platform: ${error instanceof Error ? error.message : String(error)}`,
+        };
+    }
+}

package/dist/features/harness/platform/refusal.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Every sentence the Harness refuses with, and the platform's refusal codes they answer.
+ *
+ * The recogniser that tells an agent "this is a deliberate refusal, here is the way out" rather than
+ * "this may be a defect in Reticle" used to match the PLATFORM's wording by regular expression. The
+ * platform reworded its lock ("Harness is locked. Setup score: …") and every locked Harness came back
+ * inviting a bug report. A refusal now carries the platform's CODE, the code picks a lead sentence
+ * owned here, and the recogniser matches these constants — never another repository's prose.
+ */
+/** The codes the platform's refusals carry (`{ error: { code, message } }`, or a flat `error`). */
+export declare const PlatformRefusalCode: {
+    readonly HARNESS_OFF: "harness_off";
+    readonly HARNESS_LOCKED: "harness_locked";
+    readonly NEEDS_CARD: "needs_card";
+};
+/** The lead sentence each code's refusal opens with: what the agent reads, and what is recognised. */
+export declare const RefusalLead: {
+    readonly harness_locked: "Reticle Harness is locked for this project.";
+    readonly harness_off: "The Reticle Harness is off for this project.";
+    readonly needs_card: "Reticle Harness credits are used up for this workspace.";
+};
+/** A platform refusal, read from its response body. Two shapes: nested `{ error: { code, message } }` and flat `{ error, message }`. */
+export declare function readRefusal(text: string): {
+    code?: string;
+    message?: string;
+};
+/** The sentence a refusal is told in: the code's own lead, then the platform's words. */
+export declare function refusalSentence(refusal: {
+    code?: string;
+    message?: string;
+}, status: number): string;
+/**
+ * What a person said about autonomous driving on the platform, honoured here.
+ *
+ * The switch existed, persisted and round-tripped, and the daemon read it and threw it away — so
+ * turning the harness OFF changed a value in a database and nothing else. A control that does not
+ * control anything is worse than no control: somebody turns it off, watches Reticle drive their app
+ * anyway, and now correctly distrusts every other switch in the product.
+ *
+ * Absent means OFF. The Harness is opt-in: a new project starts with it off, and an answer that does
+ * not say it is on is not a yes to spend credits on.
+ */
+export declare const MSG_HARNESS_DISABLED: string;
+/**
+ * The other reason a drive can be refused, and it is NOT the same reason.
+ *
+ * A drive through the platform spends Reticle's model budget, bounded by the workspace's Harness
+ * credits. The platform answers this only when something other than the switch stops it.
+ */
+export declare const MSG_HARNESS_UNCLAIMED: string;
+/** The platform could not be asked, and the drive would spend Reticle's budget without its yes. */
+export declare const MSG_HARNESS_UNCONFIRMED: string;

package/dist/features/harness/platform/refusal.js

@@ -0,0 +1,71 @@
+/**
+ * Every sentence the Harness refuses with, and the platform's refusal codes they answer.
+ *
+ * The recogniser that tells an agent "this is a deliberate refusal, here is the way out" rather than
+ * "this may be a defect in Reticle" used to match the PLATFORM's wording by regular expression. The
+ * platform reworded its lock ("Harness is locked. Setup score: …") and every locked Harness came back
+ * inviting a bug report. A refusal now carries the platform's CODE, the code picks a lead sentence
+ * owned here, and the recogniser matches these constants — never another repository's prose.
+ */
+/** The codes the platform's refusals carry (`{ error: { code, message } }`, or a flat `error`). */
+export const PlatformRefusalCode = {
+    HARNESS_OFF: 'harness_off',
+    HARNESS_LOCKED: 'harness_locked',
+    NEEDS_CARD: 'needs_card',
+};
+/** The lead sentence each code's refusal opens with: what the agent reads, and what is recognised. */
+export const RefusalLead = {
+    [PlatformRefusalCode.HARNESS_LOCKED]: 'Reticle Harness is locked for this project.',
+    [PlatformRefusalCode.HARNESS_OFF]: 'The Reticle Harness is off for this project.',
+    [PlatformRefusalCode.NEEDS_CARD]: 'Reticle Harness credits are used up for this workspace.',
+};
+/** A platform refusal, read from its response body. Two shapes: nested `{ error: { code, message } }` and flat `{ error, message }`. */
+export function readRefusal(text) {
+    try {
+        const body = JSON.parse(text);
+        const nested = 'object' === typeof body.error && null !== body.error
+            ? body.error
+            : {};
+        const code = 'string' === typeof body.error ? body.error : nested.code;
+        const message = 'string' === typeof nested.message ? nested.message : body.message;
+        return {
+            ...('string' === typeof code ? { code } : {}),
+            ...('string' === typeof message ? { message } : {}),
+        };
+    }
+    catch {
+        return {};
+    }
+}
+const leadOf = (code) => Object.entries(RefusalLead).find(([known]) => known === code)?.[1];
+/** The sentence a refusal is told in: the code's own lead, then the platform's words. */
+export function refusalSentence(refusal, status) {
+    const message = refusal.message ?? `the platform answered ${String(status)}`;
+    const lead = leadOf(refusal.code);
+    return lead === undefined || message.startsWith(lead) ? message : `${lead} ${message}`;
+}
+/**
+ * What a person said about autonomous driving on the platform, honoured here.
+ *
+ * The switch existed, persisted and round-tripped, and the daemon read it and threw it away — so
+ * turning the harness OFF changed a value in a database and nothing else. A control that does not
+ * control anything is worse than no control: somebody turns it off, watches Reticle drive their app
+ * anyway, and now correctly distrusts every other switch in the product.
+ *
+ * Absent means OFF. The Harness is opt-in: a new project starts with it off, and an answer that does
+ * not say it is on is not a yes to spend credits on.
+ */
+export const MSG_HARNESS_DISABLED = "The Reticle Harness is off for this project. The user can switch it on in the HUD's Settings " +
+    'or the Reticle dashboard (Settings → Projects → Reticle Harness on <project>); until then, drive the app yourself ' +
+    'through the MCP tools.';
+/**
+ * The other reason a drive can be refused, and it is NOT the same reason.
+ *
+ * A drive through the platform spends Reticle's model budget, bounded by the workspace's Harness
+ * credits. The platform answers this only when something other than the switch stops it.
+ */
+export const MSG_HARNESS_UNCLAIMED = 'The Reticle platform says this workspace cannot drive the Harness right now, usually because its ' +
+    'credits are spent: see Settings → Plan in the Reticle dashboard.';
+/** The platform could not be asked, and the drive would spend Reticle's budget without its yes. */
+export const MSG_HARNESS_UNCONFIRMED = 'Could not confirm Harness access with the Reticle platform, so the drive did not start. Try ' +
+    'again in a moment.';