@reticlehq/server 3.5.0 → 3.7.0

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

@@ -0,0 +1,33 @@
+/**
+ * `reticle context --compact [--session <id>]` — the resume block, read from disk with no daemon.
+ *
+ * Installed by `reticle init` as a Claude Code SessionStart hook with matcher `compact`: right after
+ * a compaction, whatever this prints is put back into the agent's fresh context. So it must never
+ * fail loudly — a hook that throws is an error the user did not cause — and it prints nothing when
+ * this directory has no Reticle record at all.
+ */
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { ReticleDir } from '@reticlehq/core';
+import { resumeFromDisk } from '../../judgement/runs/resume.js';
+import { SessionJournal } from '../../memory/journal/session-journal.js';
+import { createNodeFileSystem } from '../../memory/project/fs/fs-port.js';
+export async function handleContext(session) {
+    const root = join(process.cwd(), ReticleDir.ROOT);
+    if (!existsSync(root))
+        return;
+    try {
+        const fs = createNodeFileSystem();
+        const lines = await resumeFromDisk({
+            root,
+            now: Date.now(),
+            fs,
+            readActions: (id) => new SessionJournal(fs, root, id).readActions(),
+            sessionId: session,
+        });
+        process.stdout.write(`${lines.join('\n')}\n`);
+    }
+    catch {
+        // Silent by design: see the header.
+    }
+}

package/dist/command/cli/daemon-start-options.d.ts

@@ -30,4 +30,7 @@ export declare function daemonStartOptions(parsed: DaemonFlags): StartOptions;
  * idea: that headless belongs to the drive URL. It belongs to the pool, which exists either way.
  */
 export declare function daemonSpawnArgs(parsed: DaemonFlags): string[];
+/** Set (to anything but '', '0' or 'false') to hide every browser Reticle opens. Batteries set it. */
+export declare const HEADLESS_ENV = "RETICLE_HEADLESS";
+export declare function headlessByDefault(env: Readonly<Record<string, string | undefined>>, platform: string): boolean;
 export {};

package/dist/command/cli/daemon-start-options.js

@@ -1,4 +1,4 @@
-import { DAEMON_INNER_COMMAND, DRIVE_FLAG, HEADED_FLAG, HTTP_FLAG, HTTP_PORT_FLAG, HTTP_TOKEN_FLAG, PORT_FLAG, } from './cli-parse.js';
+import { DAEMON_INNER_COMMAND, DRIVE_FLAG, HEADED_FLAG, HEADLESS_FLAG, HTTP_FLAG, HTTP_PORT_FLAG, HTTP_TOKEN_FLAG, PORT_FLAG, } from './cli-parse.js';
 export function daemonStartOptions(parsed) {
     return {
         port: parsed.port,
@@ -25,8 +25,9 @@ export function daemonSpawnArgs(parsed) {
     const args = [DAEMON_INNER_COMMAND, PORT_FLAG, String(parsed.port)];
     if (parsed.driveUrl !== undefined)
         args.push(DRIVE_FLAG, parsed.driveUrl);
-    if (!parsed.headless)
-        args.push(HEADED_FLAG);
+    // Said either way: the child decides its own default from its environment, so a parent that
+    // resolved hidden must say so rather than leave it to a default that may differ.
+    args.push(parsed.headless ? HEADLESS_FLAG : HEADED_FLAG);
     if (parsed.http) {
         args.push(HTTP_FLAG);
         if (parsed.httpPort !== undefined)
@@ -36,3 +37,23 @@ export function daemonSpawnArgs(parsed) {
     }
     return args;
 }
+/*
+ * Whether a browser a daemon opens is shown or hidden when no flag says. Here because both callers that
+ * decide it -- `cli.ts` and init's bring-up -- already start daemons through this module.
+ */
+/** Set (to anything but '', '0' or 'false') to hide every browser Reticle opens. Batteries set it. */
+export const HEADLESS_ENV = 'RETICLE_HEADLESS';
+/**
+ * Whether a browser Reticle opens is hidden when no flag says. Shown by default, for every command:
+ * the pool behind `serve`/`mcp` used to be hidden on the theory that nobody watches batch work, and
+ * from the field that was a person watching an agent drive their app and seeing nothing happen.
+ * Hidden where showing is impossible or unwanted: CI, the test batteries, and a Linux machine with
+ * no display server, where a headed launch fails instead of showing anything.
+ */
+const OFF = new Set(['', '0', 'false']);
+export function headlessByDefault(env, platform) {
+    const forced = env[HEADLESS_ENV];
+    if (env['CI'] !== undefined || (forced !== undefined && !OFF.has(forced)))
+        return true;
+    return ('linux' === platform && env['DISPLAY'] === undefined && env['WAYLAND_DISPLAY'] === undefined);
+}

package/dist/command/cli/doctor/browser/chromium-hint.d.ts

@@ -48,7 +48,45 @@ export interface ChromiumProbe {
      * `Microsoft Edge`) — see launch-chromium. Present only when `exists` is false and one was found.
      */
     fallback?: string | undefined;
+    /** `executablePath` came from RETICLE_CHROMIUM_PATH, so the bundled build is not in play at all. */
+    configured?: boolean | undefined;
+    /** Why that configured executable cannot be launched. Present only when `exists` is false. */
+    problem?: ChromiumPathProblem | undefined;
 }
+/** What stops the executable RETICLE_CHROMIUM_PATH names from being launched. */
+export declare const ChromiumPathProblem: {
+    readonly MISSING: "missing";
+    readonly NOT_A_FILE: "not-a-file";
+    readonly NOT_EXECUTABLE: "not-executable";
+};
+export type ChromiumPathProblem = (typeof ChromiumPathProblem)[keyof typeof ChromiumPathProblem];
+/**
+ * What stops the file at `path` from being launched, or undefined when nothing does.
+ *
+ * Existing is not enough: Playwright cannot start a directory or a file without the executable bit,
+ * and its error for that reads like a missing install. Windows has no executable bit, so only the
+ * file check applies there.
+ */
+export declare function chromiumPathProblem(path: string, platform: NodeJS.Platform): ChromiumPathProblem | undefined;
+/** The Chromium RETICLE_CHROMIUM_PATH names, or undefined when it is unset or blank. */
+export declare function configuredChromiumPath(env: NodeJS.ProcessEnv): string | undefined;
+/**
+ * What the probes report when RETICLE_CHROMIUM_PATH is set, or undefined when it is not. The user
+ * named the browser, so the bundled revision, the installed channels and the browsers root say
+ * nothing about whether a launch will work. Only the named file does.
+ */
+export declare function configuredChromiumProbe(env: NodeJS.ProcessEnv, pathProblem: (path: string) => ChromiumPathProblem | undefined): ChromiumProbe | undefined;
+/**
+ * How every RETICLE_CHROMIUM_PATH refusal begins. Error recovery keys on it, so the variable's name
+ * is read as configuration rather than as a `reticle_*` tool the call got wrong.
+ */
+export declare const CHROMIUM_PATH_REFUSAL_PREFIX: string;
+/**
+ * A RETICLE_CHROMIUM_PATH that cannot be launched. Worded apart from the missing-browser hint on
+ * purpose: that one sends the reader to install Playwright's build, which does nothing for a path
+ * typed wrong.
+ */
+export declare function configuredChromiumRefusal(path: string, problem: ChromiumPathProblem): string;
 /** The install command, pinned when we know what to pin to. */
 export declare function chromiumInstallCommand(playwrightVersion?: string): string;
 /**
@@ -83,5 +121,13 @@ export declare function parseChromiumRevision(executablePath: string): {
 export declare function probeChromium(): Promise<ChromiumProbe>;
 /** The bundled playwright's version, or undefined if it cannot be read (the hint then goes unpinned). */
 export declare function bundledPlaywrightVersion(): string | undefined;
+/**
+ * Why the lease preflight refuses, or undefined when a launch can go ahead.
+ *
+ * "Chromium is not installed" is kept in the usual message because error-recovery routes it to the
+ * install fix. A RETICLE_CHROMIUM_PATH that cannot be launched is a wrong path, not a missing
+ * install, so it says only that and the install fix is never attached.
+ */
+export declare function chromiumPreflightRefusal(probe: ChromiumProbe): string | undefined;
 /** The doctor line for the Chromium check — verdict, what was probed, and how to satisfy it. */
 export declare function chromiumHint(probe: ChromiumProbe): string;

package/dist/command/cli/doctor/browser/chromium-hint.js

@@ -20,8 +20,86 @@
  * resolves, so `PLAYWRIGHT_BROWSERS_PATH` and every platform default are honoured by construction
  * rather than by a table of roots this file would have to keep in step with Playwright's.
  */
-import { existsSync, readdirSync } from 'node:fs';
+import { accessSync, constants as fsConstants, existsSync, readdirSync, statSync } from 'node:fs';
 import { createRequire } from 'node:module';
+import { ReticleEnv } from '@reticlehq/core';
+/** What stops the executable RETICLE_CHROMIUM_PATH names from being launched. */
+export const ChromiumPathProblem = {
+    MISSING: 'missing',
+    NOT_A_FILE: 'not-a-file',
+    NOT_EXECUTABLE: 'not-executable',
+};
+/**
+ * What stops the file at `path` from being launched, or undefined when nothing does.
+ *
+ * Existing is not enough: Playwright cannot start a directory or a file without the executable bit,
+ * and its error for that reads like a missing install. Windows has no executable bit, so only the
+ * file check applies there.
+ */
+export function chromiumPathProblem(path, platform) {
+    let isFile;
+    try {
+        isFile = statSync(path).isFile();
+    }
+    catch {
+        return ChromiumPathProblem.MISSING;
+    }
+    if (!isFile)
+        return ChromiumPathProblem.NOT_A_FILE;
+    if ('win32' === platform)
+        return undefined;
+    try {
+        accessSync(path, fsConstants.X_OK);
+        return undefined;
+    }
+    catch {
+        return ChromiumPathProblem.NOT_EXECUTABLE;
+    }
+}
+/** The Chromium RETICLE_CHROMIUM_PATH names, or undefined when it is unset or blank. */
+export function configuredChromiumPath(env) {
+    const path = env[ReticleEnv.CHROMIUM_PATH]?.trim();
+    return path === undefined || 0 === path.length ? undefined : path;
+}
+/**
+ * What the probes report when RETICLE_CHROMIUM_PATH is set, or undefined when it is not. The user
+ * named the browser, so the bundled revision, the installed channels and the browsers root say
+ * nothing about whether a launch will work. Only the named file does.
+ */
+export function configuredChromiumProbe(env, pathProblem) {
+    const path = configuredChromiumPath(env);
+    if (path === undefined)
+        return undefined;
+    const problem = pathProblem(path);
+    return {
+        executablePath: path,
+        exists: problem === undefined,
+        configured: true,
+        ...(problem === undefined ? {} : { problem }),
+    };
+}
+/**
+ * How every RETICLE_CHROMIUM_PATH refusal begins. Error recovery keys on it, so the variable's name
+ * is read as configuration rather than as a `reticle_*` tool the call got wrong.
+ */
+export const CHROMIUM_PATH_REFUSAL_PREFIX = `${ReticleEnv.CHROMIUM_PATH} points at `;
+/** What each problem reads as, after the path. */
+const CHROMIUM_PATH_PROBLEM_TEXT = {
+    [ChromiumPathProblem.MISSING]: 'which does not exist',
+    [ChromiumPathProblem.NOT_A_FILE]: 'which is not a file',
+    [ChromiumPathProblem.NOT_EXECUTABLE]: 'which is not executable',
+};
+const CHROMIUM_PATH_FIX = "fix the path, or unset it to use Playwright's own Chromium";
+/** The doctor verdict for a RETICLE_CHROMIUM_PATH that can be launched. */
+const CHROMIUM_PATH_IN_USE = (path) => `✓ using ${path} (${ReticleEnv.CHROMIUM_PATH})`;
+/**
+ * A RETICLE_CHROMIUM_PATH that cannot be launched. Worded apart from the missing-browser hint on
+ * purpose: that one sends the reader to install Playwright's build, which does nothing for a path
+ * typed wrong.
+ */
+export function configuredChromiumRefusal(path, problem) {
+    return `${CHROMIUM_PATH_REFUSAL_PREFIX}${path}, ${CHROMIUM_PATH_PROBLEM_TEXT[problem]}; ${CHROMIUM_PATH_FIX}`;
+}
 /**
  * A browsers-root entry that is a chromium build.
  *
@@ -160,8 +238,28 @@ export function bundledPlaywrightVersion() {
     }
     return undefined;
 }
+/**
+ * Why the lease preflight refuses, or undefined when a launch can go ahead.
+ *
+ * "Chromium is not installed" is kept in the usual message because error-recovery routes it to the
+ * install fix. A RETICLE_CHROMIUM_PATH that cannot be launched is a wrong path, not a missing
+ * install, so it says only that and the install fix is never attached.
+ */
+export function chromiumPreflightRefusal(probe) {
+    if (probe.exists)
+        return undefined;
+    if (true === probe.configured && probe.executablePath !== undefined) {
+        return configuredChromiumRefusal(probe.executablePath, probe.problem ?? ChromiumPathProblem.MISSING);
+    }
+    return `Chromium is not installed for Playwright — ${chromiumHint(probe)}`;
+}
 /** The doctor line for the Chromium check — verdict, what was probed, and how to satisfy it. */
 export function chromiumHint(probe) {
+    if (true === probe.configured && probe.executablePath !== undefined) {
+        return probe.exists
+            ? CHROMIUM_PATH_IN_USE(probe.executablePath)
+            : `✗ ${configuredChromiumRefusal(probe.executablePath, probe.problem ?? ChromiumPathProblem.MISSING)}`;
+    }
     if (probe.exists) {
         // Naming the revision on the happy line too: it is the number the mismatch line talks about, and
         // a reader comparing two machines has nothing to compare without it.

package/dist/command/cli/doctor/doctor-coverage-line.d.ts

@@ -0,0 +1,2 @@
+/** The rows for every tab the status names; nothing when it names none. Never throws. */
+export declare function coverageLines(status: unknown): string[];

package/dist/command/cli/doctor/doctor-coverage-line.js

@@ -0,0 +1,47 @@
+/**
+ * `doctor`'s coverage rows: what Reticle sees in each connected app, read from the daemon's
+ * `/status` (`coverage`), and — once a verdict recorded a gap — the prompt to hand a coding agent.
+ * A terminal cannot copy, so the prompt is printed whole, ready to paste.
+ */
+import { DoctorRow, doctorRow } from './doctor-rows.js';
+const capabilitiesIn = (value) => Array.isArray(value)
+    ? value.flatMap((item) => {
+        const name = 'object' === typeof item && null !== item
+            ? item['capability']
+            : item;
+        return 'string' === typeof name ? [name] : [];
+    })
+    : [];
+/** The rows for every tab the status names; nothing when it names none. Never throws. */
+export function coverageLines(status) {
+    const list = 'object' === typeof status && null !== status
+        ? status['coverage']
+        : undefined;
+    if (!Array.isArray(list))
+        return [];
+    return list.flatMap((raw) => {
+        const tab = ('object' === typeof raw && null !== raw ? raw : {});
+        if ('number' !== typeof tab.covered || 'number' !== typeof tab.total)
+            return [];
+        const missing = capabilitiesIn(tab.missing);
+        const notSeen = capabilitiesIn(tab.notSeenYet);
+        const parts = [
+            `${String(tab.covered)}/${String(tab.total)}${'string' === typeof tab.url ? ` at ${tab.url}` : ''}`,
+            ...(0 === missing.length ? [] : [`missing: ${missing.join(', ')}`]),
+            ...(0 === notSeen.length ? [] : [`not seen yet: ${notSeen.join(', ')}`]),
+        ];
+        const prompt = 'string' === typeof tab.prompt
+            ? [
+                '    prompt for your coding agent (copy it):',
+                ...tab.prompt.split('\n').map((line) => `      ${line}`),
+            ]
+            : [];
+        const gate = tab.harnessGate;
+        const reason = 'object' === typeof gate && null !== gate
+            ? gate['reason']
+            : undefined;
+        // The Harness gate, in the sentence a refused drive says.
+        const locked = 'string' === typeof reason ? [`    ${reason}`] : [];
+        return [doctorRow(DoctorRow.COVERAGE, parts.join(' — ')), ...locked, ...prompt];
+    });
+}

package/dist/command/cli/doctor/doctor-project-line.d.ts

@@ -1,15 +1,3 @@
-/**
- * Whether `init` has wired THIS directory — the check `doctor` was missing.
- *
- * `doctor` already read `.reticle.json` for the port, so it knew whether the file existed and never
- * said so. In a project where `init` has not run the checklist came out clean: node fine, chromium
- * fine, a daemon that starts on demand, a bridge port. Every line true, and the app carrying no SDK
- * went unremarked — which is exactly the state that produces "the tools are here and nothing ever
- * verifies", and the state `doctor` is run to explain.
- *
- * Registering the MCP server and instrumenting the app are two different halves of the install, and
- * more than one route does the first without the second.
- */
 interface ProjectWiringFacts {
     /** The id from `.reticle.json`, or undefined when there is no config here. */
     projectId: string | undefined;

package/dist/command/cli/doctor/doctor-project-line.js

@@ -10,6 +10,7 @@
  * Registering the MCP server and instrumenting the app are two different halves of the install, and
  * more than one route does the first without the second.
  */
+import { DoctorRow, doctorRow } from './doctor-rows.js';
 /**
  * One line, in the same shape as the checks beside it.
  *
@@ -20,16 +21,16 @@
  */
 export function projectWiringLine(facts) {
     if (facts.projectId !== undefined) {
-        return `  project      ✓ wired here (${facts.projectId})`;
+        return doctorRow(DoctorRow.PROJECT, `✓ wired here (${facts.projectId})`);
     }
     if (facts.previouslyConnected) {
-        return '  project      ✓ an app has connected here before, so it is wired (no .reticle.json — a build plugin can wire an app without one)';
+        return doctorRow(DoctorRow.PROJECT, '✓ an app has connected here before, so it is wired (no .reticle.json — a build plugin can wire an app without one)');
     }
     if (true === facts.configPresent) {
-        return ('  project      ✗ .reticle.json is here but carries no readable projectId — a corrupt or ' +
+        return doctorRow(DoctorRow.PROJECT, '✗ .reticle.json is here but carries no readable projectId — a corrupt or ' +
             'hand-edited config reads the same as no config, and points this project at the default ' +
             'daemon. Run `npx @reticlehq/server init` in the app directory to rewrite it');
     }
-    return ('  project      ✗ no .reticle.json here and nothing has ever connected — the tools may be ' +
+    return doctorRow(DoctorRow.PROJECT, '✗ no .reticle.json here and nothing has ever connected — the tools may be ' +
         'registered, but this app is not instrumented. Run `npx @reticlehq/server init` in the app directory');
 }

package/dist/command/cli/doctor/doctor-rows.d.ts

@@ -40,6 +40,8 @@ export declare const DoctorRow: {
      * verification." Every row in this list checks a COMPONENT; none checked a LINK.
      */
     readonly AGENT_LINK: "agent link";
+    /** Is the APP in this folder wired, not just the tools. Printed by `doctor-project-line.ts`. */
+    readonly PROJECT: "project";
     /**
      * Which of `localhost`'s two answers reaches the bridge, printed only when they disagree.
      *
@@ -58,6 +60,10 @@ export declare const DoctorRow: {
     readonly DAEMON_LOG: "daemon log";
     readonly TRACING: "tracing";
     readonly DESKTOP: "desktop";
+    /** What Reticle sees in each connected app, out of eight capabilities. Only with a live tab. */
+    readonly COVERAGE: "coverage";
+    /** A project folder holding runs the platform never got. Only when there is one. */
+    readonly UNSYNCED: "unsynced";
 };
 type DoctorRowLabel = (typeof DoctorRow)[keyof typeof DoctorRow];
 export declare const DOCTOR_ROW_LABELS: readonly DoctorRowLabel[];

package/dist/command/cli/doctor/doctor-rows.js

@@ -40,6 +40,8 @@ export const DoctorRow = {
      * verification." Every row in this list checks a COMPONENT; none checked a LINK.
      */
     AGENT_LINK: 'agent link',
+    /** Is the APP in this folder wired, not just the tools. Printed by `doctor-project-line.ts`. */
+    PROJECT: 'project',
     /**
      * Which of `localhost`'s two answers reaches the bridge, printed only when they disagree.
      *
@@ -58,6 +60,10 @@ export const DoctorRow = {
     DAEMON_LOG: 'daemon log',
     TRACING: 'tracing',
     DESKTOP: 'desktop',
+    /** What Reticle sees in each connected app, out of eight capabilities. Only with a live tab. */
+    COVERAGE: 'coverage',
+    /** A project folder holding runs the platform never got. Only when there is one. */
+    UNSYNCED: 'unsynced',
 };
 export const DOCTOR_ROW_LABELS = Object.values(DoctorRow);
 /** Indent every row carries, before the label. */

package/dist/command/cli/doctor/doctor-signing-line.d.ts

@@ -0,0 +1,38 @@
+/** What `codesign -dv` says about one binary. */
+export interface Signature {
+    /** Ad-hoc signed, or not signed at all: no identity the keychain can recognise. */
+    adhoc: boolean;
+    identifier?: string;
+    teamId?: string;
+}
+export declare const KEYCHAIN_NOTE: string;
+/** `codesign -dv` output (it writes to stderr), or undefined when it said nothing usable. */
+export declare function parseCodesign(output: string): Signature | undefined;
+/** The note, when the build is unsigned, ad-hoc, or signed by another team than the installed app. */
+export declare function signingNote(build: Signature | undefined, installed: Signature | undefined): string | undefined;
+/**
+ * The dev binary `tauri dev` runs, the release builds `tauri build` leaves (the bundle first), and
+ * where an installed copy of the same app would be.
+ */
+export declare function tauriDevBinary(read: (path: string) => string | undefined): {
+    build: string;
+    release: string[];
+    installed?: string;
+} | undefined;
+/** How to look at a project, injected so the decision is a unit test. */
+export interface SigningProbe {
+    read: (relative: string) => string | undefined;
+    codesign?: (path: string) => Signature | undefined;
+    platform?: NodeJS.Platform;
+    /** The project folder the dev build's relative path is under. */
+    dir?: string;
+}
+/** On macOS, the keychain note for the Tauri build Reticle drives, when it applies. */
+export declare function keychainNoteFor(probe: SigningProbe): string | undefined;
+/** A project folder's files, read relative to it. */
+export declare const projectReader: (dir: string) => (relative: string) => string | undefined;
+/**
+ * The note for an agent session's first answer, then never again for that session: the person
+ * flooded with password dialogs is talking to the agent, and may never run doctor.
+ */
+export declare function keychainNoticeOnce(attach: string, probe: SigningProbe): string | undefined;

package/dist/command/cli/doctor/doctor-signing-line.js

@@ -0,0 +1,114 @@
+/**
+ * Whether macOS will ask for the keychain password every time the app Reticle drives reads it.
+ *
+ * Reported from the field: a signed macOS Tauri app driven by Reticle flooded its user with password
+ * dialogs. Reticle never touches the keychain; macOS binds each keychain item to the signature of
+ * the app that saved it, and the build Reticle runs (`tauri dev`, ad-hoc signed) is another app to
+ * the keychain. Read from `codesign -dv`, through an injected runner, so the parsing is a unit test.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
+import { isAbsolute, join, posix } from 'node:path';
+export const KEYCHAIN_NOTE = "macOS ties keychain items to the app's signature; this build is signed differently, so the " +
+    "app's keychain reads will ask for your password. Set your release identity " +
+    '(APPLE_SIGNING_IDENTITY, or signingIdentity in tauri.conf.json) and `reticle setup` signs the ' +
+    'dev build it starts with it; or use a separate keychain service in dev.';
+const NOT_SIGNED = 'code object is not signed at all';
+const NO_TEAM = 'not set';
+/** `codesign -dv` output (it writes to stderr), or undefined when it said nothing usable. */
+export function parseCodesign(output) {
+    if (output.includes(NOT_SIGNED))
+        return { adhoc: true };
+    const field = (key) => new RegExp(`^${key}=(.+)$`, 'm').exec(output)?.[1]?.trim();
+    const identifier = field('Identifier');
+    if (identifier === undefined)
+        return undefined;
+    const team = field('TeamIdentifier');
+    return {
+        adhoc: 'adhoc' === field('Signature'),
+        identifier,
+        ...(team === undefined || NO_TEAM === team ? {} : { teamId: team }),
+    };
+}
+/** The note, when the build is unsigned, ad-hoc, or signed by another team than the installed app. */
+export function signingNote(build, installed) {
+    if (build === undefined)
+        return undefined;
+    if (build.adhoc)
+        return KEYCHAIN_NOTE;
+    if (installed !== undefined && installed.teamId !== build.teamId)
+        return KEYCHAIN_NOTE;
+    return undefined;
+}
+/**
+ * The dev binary `tauri dev` runs, the release builds `tauri build` leaves (the bundle first), and
+ * where an installed copy of the same app would be.
+ */
+export function tauriDevBinary(read) {
+    const cargo = read('src-tauri/Cargo.toml');
+    const name = cargo === undefined ? undefined : /^name\s*=\s*"([^"]+)"/m.exec(cargo)?.[1];
+    if (name === undefined)
+        return undefined;
+    let product;
+    try {
+        product = JSON.parse(read('src-tauri/tauri.conf.json') ?? '{}')['productName'];
+    }
+    catch {
+        product = undefined;
+    }
+    const named = 'string' === typeof product && 0 < product.length ? product : undefined;
+    return {
+        build: `src-tauri/target/debug/${name}`,
+        release: [
+            ...(named === undefined ? [] : [`src-tauri/target/release/bundle/macos/${named}.app`]),
+            `src-tauri/target/release/${name}`,
+        ],
+        ...(named === undefined ? {} : { installed: `/Applications/${named}.app` }),
+    };
+}
+/** `codesign -dv` of one path, as it prints it (to stderr). Undefined when nothing ran. */
+function codesignOf(path) {
+    if (!existsSync(path))
+        return undefined;
+    const run = spawnSync('codesign', ['-dv', '--verbose=2', path], { encoding: 'utf8' });
+    return parseCodesign(`${run.stdout}${run.stderr}`);
+}
+/** On macOS, the keychain note for the Tauri build Reticle drives, when it applies. */
+export function keychainNoteFor(probe) {
+    if ('darwin' !== (probe.platform ?? process.platform))
+        return undefined;
+    const app = tauriDevBinary(probe.read);
+    if (app === undefined)
+        return undefined;
+    const codesign = probe.codesign ?? codesignOf;
+    const installed = app.installed === undefined ? undefined : codesign(app.installed);
+    // Every build on disk, debug and release: a person with only a release build heard nothing.
+    for (const build of [app.build, ...app.release]) {
+        // macOS only, so a POSIX path on every host the unit test runs on.
+        const note = signingNote(codesign(posix.join(probe.dir ?? process.cwd(), build)), installed);
+        if (note !== undefined)
+            return note;
+    }
+    return undefined;
+}
+/** A project folder's files, read relative to it. */
+export const projectReader = (dir) => (relative) => {
+    try {
+        return readFileSync(isAbsolute(relative) ? relative : join(dir, relative), 'utf8');
+    }
+    catch {
+        return undefined;
+    }
+};
+// ponytail: grows by one id per agent connection the daemon ever served; bound it if that matters.
+const noticed = new Set();
+/**
+ * The note for an agent session's first answer, then never again for that session: the person
+ * flooded with password dialogs is talking to the agent, and may never run doctor.
+ */
+export function keychainNoticeOnce(attach, probe) {
+    if (noticed.has(attach))
+        return undefined;
+    noticed.add(attach);
+    return keychainNoteFor(probe);
+}

package/dist/command/cli/drive/drive-attach.d.ts

@@ -44,7 +44,7 @@ export declare function decideDriveMode(presence: PortPresence): DriveMode;
 /** A driveable session the daemon opened on our behalf. */
 interface DriveSession {
     sessionId: string;
-    /** Whether the tab's SDK actually registered — false ⇒ the app may not embed @reticlehq/core. */
+    /** Whether the tab's SDK actually registered — false ⇒ the app may not embed @reticlehq/browser. */
     ready: boolean;
     /** How long the session survives untouched. Absent from a daemon that does not report it. */
     expiresInMs?: number;
@@ -76,8 +76,33 @@ export declare function readAttachResponse(port: number, url: string, res: {
 }): DriveAttachResult;
 /** Ask the daemon on `port` to open a driveable browser at `url`. */
 export declare function requestDriveSession(port: number, url: string, post?: DrivePost): Promise<DriveAttachResult>;
+/** Which app the attached page says it is, beside the project this directory names. */
+export interface AttachedApp {
+    /** What the JSON line carries. Every value is printable, see `printable`. */
+    fields: {
+        /** The project the page reported when it connected. */
+        projectId?: string;
+        title?: string;
+        /** The `projectId` in this directory's `.reticle.json`, when there is one. */
+        expectedProjectId?: string;
+    };
+    /**
+     * The two project ids differ. Decided on the raw values, before either is made printable, so two
+     * ids that differ only in a control character still count as different.
+     */
+    mismatch: boolean;
+}
+/** Nothing known about the app, as for a page that never connected. */
+export declare const NO_ATTACHED_APP: AttachedApp;
+/**
+ * Pick the attached session out of a `/status` payload. Pure.
+ *
+ * The drive answer is a lease result, which carries no project: the page reports that itself when
+ * it connects, and `/status` is where it is already listed.
+ */
+export declare function attachedApp(status: unknown, sessionId: string, expectedProjectId: string | undefined): AttachedApp;
 /** The success line. Names the session, because that is the handle everything downstream needs. */
-export declare function describeAttached(port: number, url: string, session: DriveSession): string;
+export declare function describeAttached(port: number, url: string, session: DriveSession, app?: AttachedApp): string;
 /**
  * What an attach cannot honour: the window.
  *