@reticlehq/server 2.4.0 → 2.6.0

package/dist/index.js

@@ -2,10 +2,11 @@ import { join } from 'node:path';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { AGENT_STOPPED_NOTICE, RETICLE_DEFAULT_PORT, ReticleCommand, ReticleDir, ReticleEnv, LOOPBACK_HOST, ReplayStatus, EventType, } from '@reticlehq/core';
 import { originOf } from './session/session-manager.js';
+import { setBrowserMode, BrowserMode } from './telemetry/browser-mode.js';
 import { replayNamedFlow } from './flows/flow-tools.js';
 import { createSharedServer } from './http-server.js';
-import { resolveBridgeSecurityWithAutoToken } from './bridge-security.js';
-import { Bridge } from './bridge.js';
+import { resolveBridgeSecurityWithAutoToken } from './bridge/bridge-security.js';
+import { Bridge } from './bridge/bridge.js';
 import { BaselineStore } from './project/baselines.js';
 import { RecordingStore } from './flows/recordings.js';
 import { FlowStore } from './flows/flows.js';
@@ -17,15 +18,18 @@ import { ReticleRunner } from './runs/reticle-runner.js';
 import { createRunnerPort } from './runs/runner-port.js';
 import { RunStore } from './runs/run-store.js';
 import { startVerifyServer } from './runs/verify-server.js';
-import { createMcpServer } from './mcp.js';
+import { createMcpServer } from './mcp/mcp.js';
 import { SessionReaper, endAllSessions, MCP_DISCONNECT_SUMMARY } from './session/session-reaper.js';
-import { resolveToolProfile } from './tools/profiles.js';
+import { wireSessionScope } from './session/no-session-watch.js';
+import { buildIdlePredicate } from './daemon/daemon-usefulness.js';
+import { resolveToolSurface } from './tools/tool-surface.js';
+import { statusPayload } from './status-payload.js';
 import { CdpRealInputProvider, LaunchedRealInputProvider } from './input/real-input.js';
 import { cpus } from 'node:os';
 import { BrowserPool } from './pool/browser-pool.js';
 import { playwrightLauncher, resolveMaxContexts } from './pool/playwright-launcher.js';
 import { LeaseReaper } from './pool/lease-reaper.js';
-import { readJournalEnabled, readProjectId } from './cli-port.js';
+import { readJournalEnabled, readProjectId } from './cli/cli-port.js';
 import { makeJournalAttach } from './journal/attach-journal.js';
 import { makeSessionEnd } from './journal/session-end.js';
 import { AmbientStore } from './journal/ambient-store.js';
@@ -41,7 +45,7 @@ function replayVerdictLine(result) {
 }
 export { ReticleTool } from './tools/tool-names.js';
 export { RingBuffer } from './events/ring-buffer.js';
-export { Bridge } from './bridge.js';
+export { Bridge } from './bridge/bridge.js';
 export { Session, SessionManager } from './session/session.js';
 export { buildSessionRecommendation } from './session/session-recommendation.js';
 export { TOOLS } from './tools/tools.js';
@@ -61,9 +65,13 @@ export { MCP_SSE_PATH, MCP_MESSAGE_PATH } from '@reticlehq/core';
 export { BrowserPool, DEFAULT_LEASE_TTL_MS } from './pool/browser-pool.js';
 export { playwrightLauncher, resolveMaxContexts } from './pool/playwright-launcher.js';
 export { appendReticleParams } from './tools/lease-tools.js';
-export { writePid, removePid, isRunning, logPath, readPid, isAlive } from './daemon.js';
+export { writePid, removePid, isRunning, logPath, readPid, isAlive } from './daemon/daemon.js';
+// The daemon's own liveness vocabulary, exported so a GATE can read a daemon log back and say how
+// that daemon ended. Without this the battery would re-implement the rule, and a guard that
+// re-implements what it guards is insensitive to it.
+export { classifyDaemonLife, DaemonEnd, DAEMON_HEARTBEAT_EVENT, DAEMON_HEARTBEAT_MS, } from './daemon/heartbeat.js';
 export { scrollToFind } from './input/scroll-find.js';
-export { CORE_TOOL_NAMES, TOOL_PROFILE, TOOL_PROFILE_ENV, filterTools, resolveToolProfile, } from './tools/profiles.js';
+export { CORE_TOOL_NAMES, TOOL_SURFACE, TOOL_PROFILE_ENV, filterTools, resolveToolSurface, } from './tools/tool-surface.js';
 export { AnnotationStore } from './flows/annotation-store.js';
 export { replayFlow, nearestTestid } from './flows/flow-replay.js';
 export { ensureReticleDir, writeContract, readContract, reticleDirPaths, flowPath, baselinePath, } from './project/reticle-dir.js';
@@ -84,14 +92,14 @@ export { buildReactionReport } from './events/reaction.js';
 export { CdpRealInputProvider, LaunchedRealInputProvider, DriveError, performGesture, boxCenter, isPointerAction, } from './input/real-input.js';
 /** Default localhost port for the verify HTTP endpoint (see docs/platform-integration.md). */
 export const RETICLE_VERIFY_DEFAULT_PORT = 7331;
-export { resolveBridgeSecurity } from './bridge-security.js';
+export { resolveBridgeSecurity } from './bridge/bridge-security.js';
 /**
  * Build the shared browser pool (one headless Chromium, N capped isolated leased contexts). Lazy —
  * no Chromium launches until the first lease — so creating it is free even when never used.
  */
 function createBrowserPool(headless) {
     const maxContexts = resolveMaxContexts(process.env[ReticleEnv.MAX_CONTEXTS], cpus().length);
-    const genSessionId = () => `lease-${typeof globalThis.crypto?.randomUUID === 'function'
+    const genSessionId = () => `lease-${'function' === typeof globalThis.crypto?.randomUUID
         ? globalThis.crypto.randomUUID()
         : String(Date.now())}`;
     return new BrowserPool(playwrightLauncher({ headless }), { maxContexts, genSessionId });
@@ -174,6 +182,9 @@ async function resolveRealInput(options, onNavigateError, onNetworkDetail) {
     const driveUrl = options.driveUrl;
     if (driveUrl !== undefined && driveUrl.length > 0) {
         const headless = options.headless ?? true;
+        // The one place that knows. Everything downstream reads it rather than re-deriving it, and a
+        // daemon that launches nothing keeps the default (ATTACHED) rather than guessing.
+        setBrowserMode(headless ? BrowserMode.HEADLESS : BrowserMode.HEADED);
         const injectConnect = options.injectConnect;
         const storageState = options.storageState;
         const factory = options.realInputFactory ??
@@ -254,8 +265,12 @@ export async function start(options = {}) {
             fs,
             reticleRoot,
             now,
+            bridgePort: port,
+            // The daemon's OWN project, so a tool can tell "this session is mine" from "this session
+            // belongs to a sibling app under the same daemon". contract_save refuses on the second.
+            ...(activeProjectId === undefined ? {} : { projectId: activeProjectId }),
         };
-        const profile = resolveToolProfile(options.toolProfile);
+        const profile = resolveToolSurface(options.toolProfile);
         const server = createMcpServer(realInput !== undefined ? { ...deps, realInput } : deps, profile);
         // When the agent (the MCP client) disconnects cleanly, end every active session at once so the
         // HUD doesn't linger. (If the agent instead KILLS this process, the WS dies and the browser
@@ -294,11 +309,7 @@ export async function startDaemon(options = {}) {
     // mirror rejection so a port collision can't surface as an unhandled promise rejection.
     void bridge.ready.catch(() => undefined);
     // `reticle status` GETs this for a live, at-a-glance view of connected tabs + their health.
-    shared.attachStatus(() => ({
-        running: true,
-        sessionCount: bridge.sessions.count(),
-        sessions: bridge.sessions.list(),
-    }));
+    shared.attachStatus(() => statusPayload(bridge.sessions.count(), bridge.sessions.list()));
     // Agent-independent presence: the daemon outlives any single agent, so when the LAST agent's MCP
     // connection drops (it stopped, or is waiting on the human), end every session and push a clear
     // "go to your terminal" notice to the panel — the human is on the browser and must not lose a typed
@@ -315,10 +326,11 @@ export async function startDaemon(options = {}) {
     reaper.start();
     // Scope auto-selection to the active project (from .reticle.json) so a stray tab from another app is
     // never picked when the agent omits a sessionId. Explicit per-call scope/sessionId still overrides.
-    const activeProjectId = readProjectId(process.cwd());
-    if (activeProjectId !== undefined) {
-        bridge.sessions.setDefaultScope({ projectId: activeProjectId });
-    }
+    // Scope + the no-session diagnosis: "no browser session connected" is the error that ends most
+    // sessions, and the agent is told to check two things it cannot see. See no-session-diagnosis.ts.
+    // The pool reader is passed lazily: `pool` is assigned above but may be undefined when this
+    // daemon runs without one, and the diagnosis must degrade to the tab message rather than lie.
+    wireSessionScope(bridge.sessions, readProjectId(process.cwd()), port, () => pool?.reapedLeaseCount() ?? 0);
     const { realInput, owned } = await resolveRealInput(options, () => shared.close(), makeNetworkDetailRouter(bridge, options.driveUrl));
     const fs = createNodeFileSystem();
     const reticleRoot = options.reticleRoot ?? join(process.cwd(), ReticleDir.ROOT);
@@ -342,15 +354,16 @@ export async function startDaemon(options = {}) {
         fs,
         reticleRoot,
         now,
+        bridgePort: port,
     };
-    const profile = resolveToolProfile(options.toolProfile);
+    const profile = resolveToolSurface(options.toolProfile);
     const effectiveDeps = realInput !== undefined ? { ...deps, realInput } : deps;
     shared.attachMcp(() => createMcpServer(effectiveDeps, profile));
     // Optional OEM/CI verify endpoint: a host platform POSTs to /verify and gets an ReticleVerificationRun,
     // driving the same flow-replay machinery the agent uses — no MCP stdio, no human. Each verdict is
     // persisted via RunStore. Localhost-bound + token-guarded. Off unless `reticle serve --http`.
     let verifyHttp;
-    if (options.httpVerify === true) {
+    if (true === options.httpVerify) {
         const runStore = new RunStore(fs, reticleRoot);
         const runner = new ReticleRunner(createRunnerPort(effectiveDeps));
         const token = options.httpVerifyToken ?? process.env[ReticleEnv.VERIFY_TOKEN] ?? '';
@@ -410,9 +423,12 @@ export async function startDaemon(options = {}) {
         ...(realInput !== undefined ? { realInput } : {}),
         ...(verifyHttp !== undefined ? { verifyPort: verifyHttp.port } : {}),
         ...(security.token !== undefined ? { token: security.token } : {}),
-        // Idle = nobody is using the daemon: no agent attached, no browser tab connected, no pool lease.
-        // The daemon entry self-shuts-down after this holds for the grace window (see cli.ts / IdleShutdown).
-        isIdle: () => !agentConnected && bridge.sessions.count() === 0 && pool.activeCount() === 0,
+        // Nobody is using this daemon — self-shuts-down once it holds for the grace window. See
+        // daemon-usefulness.ts for the two ways that can be true.
+        isIdle: buildIdlePredicate(() => agentConnected, bridge.sessions, pool),
+        // Exposed so the shutdown watcher can give an ATTACHED daemon a longer grace. The predicate above
+        // says WHETHER it is idle; this says how long that quiet should be tolerated — see idle-grace.
+        agentAttached: () => agentConnected,
         close: async () => {
             reaper.stop();
             const vh = verifyHttp;

package/dist/init/agent-rules.d.ts

@@ -4,6 +4,13 @@
  * it with reticle". Registering the MCP server (mcp.ts / cursor.ts) only makes the tools AVAILABLE;
  * this is the piece that makes the agent reach for them, every session, unprompted.
  *
+ * It carries a SECOND standing instruction, and that one is not about this project at all: send
+ * feedback to the Reticle maintainers, from the moment instrumentation starts. The agent is the party
+ * that experiences Reticle, and the only one who can say what it cost — and by the time anyone would
+ * think to ask, the context that knew is gone. Written into the same block, because the moment the
+ * rule lands (init, before any framework wiring) is the moment the setup itself is being lived
+ * through, which is when the reports we hear least about are actually generated.
+ *
  * The rule is framed as a definition-of-done (WHEN to verify, HOW, and the anti-reward-hacking guard),
  * written into whichever instruction file the detected agent reads: `CLAUDE.md` (Claude Code),
  * `.cursor/rules/reticle.mdc` (Cursor, `alwaysApply` so it stays in context), or `AGENTS.md` as the
@@ -15,12 +22,23 @@ export declare const CLAUDE_MD_PATH = "CLAUDE.md";
 export declare const AGENTS_MD_PATH = "AGENTS.md";
 /** Cursor project rule; the frontmatter `alwaysApply` keeps it in context on every turn. */
 export declare const CURSOR_RULE_PATH = ".cursor/rules/reticle.mdc";
+/**
+ * How the agent must INVOKE the CLI.
+ *
+ * `reticle init` installs the SDK packages, never the server — so there is no `reticle` on the
+ * agent's PATH, and every bare `reticle <cmd>` this rule named was an instruction that could not be
+ * followed. Reported from a field sweep: three of them, in the file the agent re-reads every session.
+ *
+ * `npx @reticlehq/server` is the same invocation the MCP registration uses, and it is derived from
+ * the package's own name so the two can never drift apart.
+ */
+export declare const CLI: string;
 export declare const AgentRuleStatus: {
     readonly APPLY: "apply";
     readonly ALREADY: "already";
 };
 export type AgentRuleStatus = (typeof AgentRuleStatus)[keyof typeof AgentRuleStatus];
-export interface AgentRuleResult {
+interface AgentRuleResult {
     status: AgentRuleStatus;
     /** Full file content to write when status is APPLY; the unchanged input otherwise. */
     content: string;
@@ -35,3 +53,4 @@ export declare function markedBlock(): string;
 export declare function mergeMarkedInstruction(existing: string | null | undefined): AgentRuleResult;
 /** The Cursor rule file (.mdc): `alwaysApply` keeps the rule in every turn's context. */
 export declare function cursorRuleFile(): string;
+export {};

package/dist/init/agent-rules.js

@@ -4,12 +4,21 @@
  * it with reticle". Registering the MCP server (mcp.ts / cursor.ts) only makes the tools AVAILABLE;
  * this is the piece that makes the agent reach for them, every session, unprompted.
  *
+ * It carries a SECOND standing instruction, and that one is not about this project at all: send
+ * feedback to the Reticle maintainers, from the moment instrumentation starts. The agent is the party
+ * that experiences Reticle, and the only one who can say what it cost — and by the time anyone would
+ * think to ask, the context that knew is gone. Written into the same block, because the moment the
+ * rule lands (init, before any framework wiring) is the moment the setup itself is being lived
+ * through, which is when the reports we hear least about are actually generated.
+ *
  * The rule is framed as a definition-of-done (WHEN to verify, HOW, and the anti-reward-hacking guard),
  * written into whichever instruction file the detected agent reads: `CLAUDE.md` (Claude Code),
  * `.cursor/rules/reticle.mdc` (Cursor, `alwaysApply` so it stays in context), or `AGENTS.md` as the
  * cross-agent fallback. Idempotent via a marker block — safe to append to an existing file and a
  * re-run is a no-op. Mirrors the apply/already result shape used across init (see cursor.ts).
  */
+import { NPX } from './mcp.js';
+import { RETICLE_NPM_PACKAGE } from '../version/server-version.js';
 /** Project-root instruction files the agent re-reads every session. */
 export const CLAUDE_MD_PATH = 'CLAUDE.md';
 export const AGENTS_MD_PATH = 'AGENTS.md';
@@ -18,19 +27,42 @@ export const CURSOR_RULE_PATH = '.cursor/rules/reticle.mdc';
 /** Markers delimiting the managed block so a re-run is idempotent and the block stays updatable. */
 const RULE_BEGIN = '<!-- reticle:begin (managed by `reticle init` — edit outside these markers) -->';
 const RULE_END = '<!-- reticle:end -->';
+/**
+ * How the agent must INVOKE the CLI.
+ *
+ * `reticle init` installs the SDK packages, never the server — so there is no `reticle` on the
+ * agent's PATH, and every bare `reticle <cmd>` this rule named was an instruction that could not be
+ * followed. Reported from a field sweep: three of them, in the file the agent re-reads every session.
+ *
+ * `npx @reticlehq/server` is the same invocation the MCP registration uses, and it is derived from
+ * the package's own name so the two can never drift apart.
+ */
+export const CLI = `${NPX} ${RETICLE_NPM_PACKAGE}`;
 /** The rule body (markdown). States WHEN to verify, HOW, and never-weaken-a-check. */
 const RULE_BODY = `## Verifying with Reticle
 
-This app is instrumented by **Reticle** — an in-app verification layer exposed as \`reticle_*\` MCP tools and the \`reticle\` CLI. Verifying is part of "done", not an optional extra.
+This app is instrumented by **Reticle** — an in-app verification layer exposed as \`reticle_*\` MCP tools and the \`${CLI}\` CLI (run it through npx — Reticle's server is not installed into this project). Verifying is part of "done", not an optional extra.
 
 - **When:** after you build or change any user-facing feature, flow, or UI, verify it with Reticle **before** telling the user it is complete. Reading the code or passing unit tests is not enough — drive the real running app.
 - **How:** drive the actual flow (\`reticle_act\` / \`reticle_act_and_wait\`), then read the observable effect (\`reticle_assert\`, \`reticle_snapshot\`, \`reticle_state\`, \`reticle_network\`). Confirm the change produced the effect it was meant to, with no new console errors or failed requests.
-- **Covered flows:** run \`reticle gate\` — it reports which recorded flows the changed files affect and whether they still pass.
+- **Covered flows:** run \`${CLI} gate\` — it reports which recorded flows the changed files affect and whether they still pass.
 - **Never weaken a check to make it green.** Downgrading, skipping, or deleting an assertion is a finding, not a fix.
 - **If Reticle can't run** (no daemon, or this is not a running web app), say so — do not skip verification silently.
-- **If a tool result carries \`update_available\`, say so.** Reticle checked npm and a newer version exists. Tell the human the version numbers and offer to run \`reticle update\` — between tasks, never mid-verification, because it restarts the daemon and drops the session. Finish what you are doing first.
-- **Wish Reticle could do something? Ask for it with \`reticle_feedback\`.** Reticle is built for agents, so what you find awkward or missing is what decides the roadmap — and you are the only one who can report it, because that thought disappears when your context does. File \`feature_request\` for something that does not exist, \`improvement\` for something that works but costs too many calls. Say what you are actually trying to achieve (\`need\`) and how you work around it today (\`currentApproach\`), and set \`model\` to the model you are running. File it the moment you notice, then carry on — nothing is too minor.
-- **If Reticle itself fails you, tell its maintainers with \`reticle_feedback\`.** A tool that returned something wrong, a thing Reticle could not observe at all, or a verdict you could not act on — file it with a root-cause analysis and the call trace, then carry on with the task. Working around a broken tool in silence is how the same defect survives. This is about defects in *Reticle*; a bug you find in *this app* is Reticle working, and belongs in your report to the user instead.`;
+- **If a tool result carries \`version_skew\`, act on it before trusting anything else.** Two pieces of Reticle are on different wire contracts, so tools can misbehave in ways neither side reports — a green here is not evidence. The field says which pair disagrees and names the exact fix: run \`${CLI} stop\` and retry when the DAEMON is stale, or tell the human to install the matching SDK and restart their dev server when the PAGE is. Do that first, then redo whatever you were verifying.
+- **If a tool result carries \`update_available\`, say so.** Reticle checked npm and a newer version exists. Tell the human the version numbers and offer to run \`${CLI} update\` — between tasks, never mid-verification, because it restarts the daemon and drops the session. Finish what you are doing first.
+
+## Sending feedback to the Reticle team (first-class)
+
+**Reporting your experience with Reticle is part of using Reticle, from the moment you start wiring it in — not something to do at the end if anything went wrong.** Reticle is built FOR agents, which makes you its actual user and the only one who can see what it costs you. That knowledge is gone when your context is, so it has to leave the turn it happened in.
+
+- **Send it with \`reticle_feedback\`, the moment you notice.** One call, then carry straight on with your task. Do not batch reports, do not wait until the task is done, and do not decide something is too minor — the small awkward things are what nobody ever reports, so they never get fixed.
+- **Everything counts, in both directions.** A tool that returned something wrong (\`bug\`), something Reticle could not observe at all (\`gap\`), a verdict you could not act on (\`ambiguity\`), something you wished existed (\`feature_request\`), something that works but costs too many calls or has an awkward shape (\`improvement\`).
+- **Setup and installation count too, and are the easiest to lose.** Anything that went wrong while installing, wiring, or starting Reticle — a step in the docs that did not match reality, a plugin that had to be added by hand, a daemon that would not start, an OS-specific detour. You hit these before any verification runs, which is exactly why they usually go unreported.
+- **When the tools are not reachable yet**, file the same report from the shell: \`${CLI} feedback --agent --kind <bug|gap|ambiguity|feature_request|improvement> "what happened"\`. It needs no daemon and no working install, so a Reticle that broke before it started can still be reported.
+- **Write it so it can be acted on.** For a failure: what you called, what you expected, what you got, and the call trail in \`trace\`. For a request: the GOAL in \`need\` (not your guess at the solution), what improves in \`impact\`, and how you work around it today in \`currentApproach\` — that workaround is usually the most useful line in the report. Set \`model\` to the model you are running.
+- **Working around a Reticle defect in silence is the one thing not to do.** A silent workaround is how the same defect survives to the next user.
+- **Report defects in *Reticle*, not in the app under test.** A bug you find in this app is Reticle working as intended; that belongs in your report to the user.
+- **Never include app source, secrets, user data, or customer records** in a report.`;
 export const AgentRuleStatus = {
     APPLY: 'apply',
     ALREADY: 'already',
@@ -46,19 +78,43 @@ export function markedBlock() {
  */
 export function mergeMarkedInstruction(existing) {
     if (existing !== null && existing !== undefined && existing.includes(RULE_BEGIN)) {
-        return { status: AgentRuleStatus.ALREADY, content: existing };
+        // A block that can never be updated is not managed. Returning ALREADY on sight of the marker
+        // meant a project that ran init once kept that release's rule text forever, so every improvement
+        // reached only new projects — and a rule about a field introduced later (`version_skew`) could
+        // never arrive at all. The markers promise the inside is ours; idempotence comes from comparing
+        // CONTENT instead of presence.
+        return refreshMarkedBlock(existing);
     }
     const block = markedBlock();
-    if (existing === null || existing === undefined || existing.trim().length === 0) {
+    if (null === existing || existing === undefined || 0 === existing.trim().length) {
         return { status: AgentRuleStatus.APPLY, content: block };
     }
     const separator = existing.endsWith('\n') ? '\n' : '\n\n';
     return { status: AgentRuleStatus.APPLY, content: `${existing}${separator}${block}` };
 }
+/**
+ * Swap the managed block for the current one, leaving every character outside the markers alone.
+ *
+ * A malformed file — a begin marker with no end — is left untouched and reported ALREADY. Rewriting
+ * from a marker to end-of-file would eat whatever the human wrote after it, and silently destroying
+ * someone's instruction file is far worse than a stale rule.
+ */
+function refreshMarkedBlock(existing) {
+    const start = existing.indexOf(RULE_BEGIN);
+    const endAt = existing.indexOf(RULE_END, start);
+    if (-1 === endAt)
+        return { status: AgentRuleStatus.ALREADY, content: existing };
+    const current = existing.slice(start, endAt + RULE_END.length);
+    const wanted = markedBlock().trimEnd();
+    if (current === wanted)
+        return { status: AgentRuleStatus.ALREADY, content: existing };
+    const content = `${existing.slice(0, start)}${wanted}${existing.slice(endAt + RULE_END.length)}`;
+    return { status: AgentRuleStatus.APPLY, content };
+}
 /** The Cursor rule file (.mdc): `alwaysApply` keeps the rule in every turn's context. */
 export function cursorRuleFile() {
     return `---
-description: Verify web features with Reticle after building them
+description: Verify web features with Reticle after building them, and report Reticle problems back to its maintainers
 alwaysApply: true
 ---
 

package/dist/init/app-choice.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Which app in a workspace `reticle init` should wire, when the caller says.
+ *
+ * Refusing to guess between several apps is right — instrumenting one silently would leave the rest
+ * unverified while reporting success. But "re-run inside the one you want" is not an answer a
+ * script, a CI step, or an agent that cannot change directory can act on, so the refusal was a dead
+ * end for exactly the callers most likely to hit it.
+ *
+ * A name that is not one of the discovered apps is refused rather than trusted: it is almost always
+ * a typo or a stale path, and wiring a directory that is not an app writes files nothing compiles.
+ */
+type AppChoice = {
+    ok: true;
+    app: string | undefined;
+} | {
+    ok: false;
+    message: string;
+};
+export declare function chooseWorkspaceApp(requested: string | undefined, apps: readonly string[]): AppChoice;
+export {};

package/dist/init/app-choice.js

@@ -0,0 +1,25 @@
+/**
+ * Which app in a workspace `reticle init` should wire, when the caller says.
+ *
+ * Refusing to guess between several apps is right — instrumenting one silently would leave the rest
+ * unverified while reporting success. But "re-run inside the one you want" is not an answer a
+ * script, a CI step, or an agent that cannot change directory can act on, so the refusal was a dead
+ * end for exactly the callers most likely to hit it.
+ *
+ * A name that is not one of the discovered apps is refused rather than trusted: it is almost always
+ * a typo or a stale path, and wiring a directory that is not an app writes files nothing compiles.
+ */
+export function chooseWorkspaceApp(requested, apps) {
+    if (requested === undefined || '' === requested)
+        return { ok: true, app: undefined };
+    // Tab-completion adds a trailing slash; the discovered names never carry one.
+    const wanted = requested.replace(/\/+$/, '');
+    if (apps.includes(wanted))
+        return { ok: true, app: wanted };
+    return {
+        ok: false,
+        message: 0 === apps.length
+            ? `--app ${requested} was given, but no app was found in this workspace`
+            : `--app ${requested} is not one of the apps found here: ${apps.join(', ')}`,
+    };
+}

package/dist/init/astro-host.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Which Astro file owns the document, and therefore where the SDK script belongs.
+ *
+ * The previous rule was "exactly one `.astro` file in `src/layouts/`". Measured on two real Astro
+ * projects, it fired on neither: one has no `src/layouts/` at all and renders from
+ * `src/pages/index.astro`; the other has three files there, two of which are partials. Both got a
+ * printed recipe instead of a working install.
+ *
+ * A file COUNT cannot tell a layout from a partial, and a directory NAME cannot tell you where the
+ * document shell is. `</body>` can — the file that closes the body is the one every page renders
+ * through, and the only place a script reaches the whole app.
+ *
+ * Ambiguity is still refused rather than guessed. Two document shells means two entry points, and
+ * silently instrumenting one of them would leave half the app unverified while reporting success.
+ */
+interface AstroCandidate {
+    path: string;
+    source: string;
+}
+export declare function pickAstroHost(candidates: readonly AstroCandidate[]): AstroCandidate | undefined;
+export {};

package/dist/init/astro-host.js

@@ -0,0 +1,27 @@
+/**
+ * Which Astro file owns the document, and therefore where the SDK script belongs.
+ *
+ * The previous rule was "exactly one `.astro` file in `src/layouts/`". Measured on two real Astro
+ * projects, it fired on neither: one has no `src/layouts/` at all and renders from
+ * `src/pages/index.astro`; the other has three files there, two of which are partials. Both got a
+ * printed recipe instead of a working install.
+ *
+ * A file COUNT cannot tell a layout from a partial, and a directory NAME cannot tell you where the
+ * document shell is. `</body>` can — the file that closes the body is the one every page renders
+ * through, and the only place a script reaches the whole app.
+ *
+ * Ambiguity is still refused rather than guessed. Two document shells means two entry points, and
+ * silently instrumenting one of them would leave half the app unverified while reporting success.
+ */
+/** Tolerant of whitespace and casing: `</body>`, `</BODY >`, `</body\n>`. */
+const CLOSES_BODY = /<\/\s*body\s*>/i;
+/** Layout files win over pages: a page shell is one route, a layout shell is what routes inherit. */
+const LAYOUT_DIR = 'layouts/';
+export function pickAstroHost(candidates) {
+    const owners = candidates.filter((c) => CLOSES_BODY.test(c.source));
+    if (0 === owners.length)
+        return undefined;
+    const layouts = owners.filter((c) => c.path.includes(LAYOUT_DIR));
+    const preferred = layouts.length > 0 ? layouts : owners;
+    return 1 === preferred.length ? preferred[0] : undefined;
+}

package/dist/init/astro-patch.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Pure, conservative patchers for an Astro app: the config gets the token/root `define` and the
+ * raised build target, one layout gets the dev-only connect `<script>`.
+ *
+ * Astro was the last gated framework where `init` printed a correct recipe and applied none of it —
+ * the only ⚠ left on a supported stack, and the user's first session was two hand-copied snippets
+ * away. Astro is Vite-based but renders its own HTML, so the Vite plugin's injection never fires and
+ * there is no entry module to wire: the connect has to live in a page or layout `<script>`, and the
+ * token has to be inlined by the config because nothing else is in the page's path to inject it.
+ *
+ * Both patchers bail to `manual` (the printed recipe) on any shape they do not fully recognise.
+ * Half-editing a build config is worse than a documented manual step.
+ */
+import { type SourcePatch } from './patch-kind.js';
+export declare function patchAstroConfig(source: string): SourcePatch;
+export declare function patchAstroLayout(source: string, port: number | undefined, projectId: string | undefined): SourcePatch;