@reticlehq/server 3.6.0 → 3.7.0

package/dist/features/harness/platform/local-apps.d.ts

@@ -1,4 +1,4 @@
-import { type LinkCapability, type LinkNotice } from '@reticlehq/core';
+import { type CoverageCapability, type LinkAppGap, type LinkDevServer, type LinkHelloFailure, type LinkUnsyncedRoot, type LinkCapability, type LinkNotice } from '@reticlehq/core';
 import { type DriveCandidate } from './remote-drive.js';
 /** How often apps are reported. The platform counts an app live for two and a half of these. */
 export declare const LOCAL_APPS_REPORT_MS = 10000;
@@ -18,6 +18,14 @@ export interface AppTab extends DriveCandidate {
     projectId?: string;
     adapters: string[];
     runtime?: string;
+    /** The SDK the page announced. The dashboard compares it with `reticleVersion` per app. */
+    sdkVersion?: string;
+    /** The page's HELLO channels, plus the coverage markers (`source`, `testid`) it earned. */
+    channels?: string[];
+    /** Instrumentation gaps this tab's verdicts recorded, newest first. */
+    gaps?: LinkAppGap[];
+    /** Coverage capabilities that do not apply to this app. */
+    notApplicable?: CoverageCapability[];
 }
 export interface ReportedApp {
     key: string;
@@ -25,7 +33,20 @@ export interface ReportedApp {
     url: string;
     title?: string;
     stack: string[];
+    sdkVersion?: string;
+    channels?: string[];
+    gaps?: LinkAppGap[];
+    adapters?: string[];
+    notApplicable?: CoverageCapability[];
 }
+/** What a report carries beside its apps. Every field additive; see `LinkReportKey`. */
+export interface ReportExtras {
+    devServers?: LinkDevServer[];
+    helloFailure?: LinkHelloFailure;
+    unsynced?: LinkUnsyncedRoot[];
+}
+/** `path` under `home` as `~/...`, so no home directory leaves the machine in a report. */
+export declare function homeRelative(path: string, home: string): string;
 /** This machine: a stable id that is not its home path, and the name a person knows it by. */
 export declare const machineOf: (hostname: string, home: string) => Machine;
 /**
@@ -42,6 +63,8 @@ export declare const NOT_AN_APP_ADDRESS = "Reticle only opens a web address on t
 export declare function mayOpen(url: string, openUrls: readonly string[]): boolean;
 /** A project id as a name: the SDK stamps `<package>-<8 hex>`, and the hash means nothing to a person. */
 export declare const nameFromProjectId: (projectId: string) => string;
+/** The address as the app knows it: the params Reticle put on it to adopt a tab are not the app's. */
+export declare const withoutMarks: (raw: string) => string;
 /**
  * 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
@@ -65,10 +88,15 @@ export interface AppReportDeps {
         platform: Platform;
         apps: ReportedApp[];
     }[]>;
-    /** Open an app so it connects: one somebody asked to bring back. A throw is logged, never fatal. */
-    open: (url: string) => Promise<void>;
+    /**
+     * Open an app so it connects: one somebody asked to bring back, named by its app key so the tab
+     * writes into that app's own `.reticle`. A throw is logged, never fatal.
+     */
+    open: (url: string, appKey?: string) => Promise<void>;
     /** A drive is waiting for the project this credential is for. */
     drivePending: (platform: Platform) => void;
+    /** Dev servers, the last refused hello and unsent runs: read once per report. */
+    extras?: () => Promise<ReportExtras>;
     /**
      * Something the platform wants the person told ("update Reticle"), for the project this credential
      * is for. Called once per notice for the daemon's life, however often the platform repeats it.
@@ -83,6 +111,11 @@ export interface AppReports {
     stop: () => void;
 }
 export declare function startAppReports(deps: AppReportDeps): AppReports;
+/**
+ * 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 declare const reportAppsNow: () => Promise<void>;
 /**
  * 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.

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

@@ -11,7 +11,8 @@
  * waiting, which is how a daemon with nothing open hears about one without polling every few seconds.
  */
 import { createHash } from 'node:crypto';
-import { LinkPath, PLATFORM_LINK_VERSION, RETICLE_URL_PARAM, parseLinkNotices, } from '@reticlehq/core';
+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;
@@ -22,6 +23,15 @@ 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) => ({
@@ -65,7 +75,7 @@ export function mayOpen(url, openUrls) {
 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. */
-const withoutMarks = (raw) => {
+export const withoutMarks = (raw) => {
     try {
         const url = new URL(raw);
         for (const mark of [...url.searchParams.keys()])
@@ -77,6 +87,30 @@ const withoutMarks = (raw) => {
         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
@@ -100,8 +134,18 @@ export async function appsByPlatform(tabs, linked, machineId, describe) {
             continue;
         const key = appKeyOf(machineId, about.dir, tab.projectId);
         const apps = group(about.platform).apps;
-        if (apps.has(key))
+        // 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);
@@ -111,6 +155,12 @@ export async function appsByPlatform(tabs, linked, machineId, describe) {
             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()] }));
@@ -125,6 +175,7 @@ export function startAppReports(deps) {
             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}`, {
@@ -139,6 +190,15 @@ export function startAppReports(deps) {
                             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),
                     });
@@ -159,7 +219,7 @@ export function startAppReports(deps) {
                             continue;
                         open.add(key);
                         deps.log?.(`reticle: opening ${url}, asked for from the platform chat`);
-                        await deps.open(url).catch((error) => {
+                        await deps.open(url, key).catch((error) => {
                             deps.log?.(`reticle: could not open ${url}: ${String(error)}`);
                         });
                     }
@@ -180,8 +240,24 @@ export function startAppReports(deps) {
     };
     const timer = setInterval(() => void tick(), deps.intervalMs ?? LOCAL_APPS_REPORT_MS);
     timer.unref();
-    return { tick, stop: () => clearInterval(timer) };
+    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.

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.';

package/dist/features/harness/platform/remote-drive.d.ts

@@ -109,7 +109,7 @@ export interface RemoteDriveDeps {
     /** How a session ask waits before it is sent again. */
     sleep?: (ms: number) => Promise<void>;
     /** Drive the app toward `goal`, in `sessionId`. A throw is reported as a failed drive, in its own words. */
-    drive: (goal: string, sessionId: string | undefined) => Promise<RemoteDriveOutcome>;
+    drive: (goal: string, sessionId: string | undefined, spec?: DriveSpec) => Promise<RemoteDriveOutcome>;
     /**
      * What the driven tab shows now, as a JPEG, or undefined when it cannot be captured (a tab this
      * daemon did not launch). Absent: the drive runs with no picture, and the chat shows its steps.
@@ -146,7 +146,13 @@ export declare const NO_OWN_TAB = "No tab of this project is connected to Reticl
  * daemon serves every project on the machine but polls with ONE credential, so without this a
  * request made in project A drove project B's tab and sent pictures of it to A's chat.
  */
-export declare function pickOwnDriveSession(tabs: readonly DriveCandidate[], goal: string, apiKey: string, keyOf: (sessionId: string) => Promise<string | undefined>): Promise<string | null>;
+export declare function pickOwnDriveSession(tabs: readonly DriveCandidate[], goal: string, apiKey: string, keyOf: (sessionId: string) => Promise<string | undefined>, 
+/**
+ * Open the project's app when none of its tabs is connected, and the session it opened. A
+ * dashboard Re-verify with the dev server up and no tab open was answered "Open this project's
+ * app, then ask again" by a daemon that knew the app's address.
+ */
+reopen?: () => Promise<string | undefined>): Promise<string | null>;
 export interface DriveCandidate {
     sessionId: string;
     url: string;