@reticlehq/server 3.6.0 → 3.7.0

package/dist/surface/tools/chat-drives.js

@@ -6,20 +6,29 @@
  * app, and keeping them together is what stops a drive attached to one app landing in another that
  * happens to be on the same port. See `local-apps.ts` and `remote-drive.ts` for each half.
  */
-import { basename, join } from 'node:path';
+import { isUnmatchedRoot } from '../../memory/project/dir/reticle-dir.js';
+import { readProjectId } from '../../command/cli/ports/resolve/cli-port.js';
+import { basename, dirname, join } from 'node:path';
 import { homedir, hostname } from 'node:os';
-import { LinkCapability, ReticleTool, asRecord } from '@reticlehq/core';
+import { LinkCapability, ReticleDir, ReticleTool, asRecord, } from '@reticlehq/core';
 import { prepareDrive } from '../../features/harness/platform/drive-target.js';
 import { reticleToolset } from './harness-toolset.js';
-import { projectDirFor } from '../../memory/project/session-root.js';
+import { projectDirFor, sessionRoot } from '../../memory/project/session-root.js';
+import { readDashboardUrl } from '../../memory/project/sync-status.js';
 import { driveFrame } from '../../features/visual/visual-tools.js';
 import { LEASE_ACQUIRE_TOOL } from './lease-tools.js';
 import { REMOTE_DRIVE_JPEG_QUALITY, endDrivenTab, pickOwnDriveSession, startRemoteDrives, } from '../../features/harness/platform/remote-drive.js';
-import { appKeyOf, appsByPlatform, machineOf, mayOpen, NOT_AN_APP_ADDRESS, nameFromProjectId, pickAppTab, startAppReports, } from '../../features/harness/platform/local-apps.js';
+import { appKeyOf, appsByPlatform, homeRelative, machineOf, mayOpen, NOT_AN_APP_ADDRESS, nameFromProjectId, pickAppTab, startAppReports, withoutMarks, } from '../../features/harness/platform/local-apps.js';
 import { serverOptionsFromEnv } from '../../features/harness/platform/server-driver.js';
-import { driveForChat } from './explore-tools.js';
-import { withLinkedCredential } from './harness-explore.js';
+import { EXPLORE_TOOLS, driveForChat } from './explore-tools.js';
+import { MSG_NO_HARNESS_KEY, harnessLockRefusal, withLinkedCredential } from './harness-explore.js';
 import { runTool } from './invoke-tool.js';
+import { announcedChannels, probeMarkers, notApplicableOf, recordedGaps, } from '../../portal/session/recorded-gaps.js';
+import { probeDevServers } from '../../portal/session/dev-server/dev-server-probe.js';
+import { DriveOrigin, onDriveChange, onDriveStep, runningDrive, stopDrive, } from '../../features/harness/drive-runs.js';
+import { FreeDriveKind, planUrl, requestFreeDrive, } from '../../features/harness/platform/platform-drives.js';
+import { HumanControlKind } from '@reticlehq/core';
+import { onAgentsChange } from '../../hooks/coding-agents.js';
 /** Why a platform drive with no tab of its own runs no tool. */
 const NO_DRIVEN_TAB = 'No tab was picked for this drive, so no tool runs.';
 /** What this daemon does for the platform's chat. Each one is listed only once it is built. */
@@ -48,6 +57,31 @@ const nameOf = async (fs, dir, projectId) => {
         return nameFromProjectId(projectId);
     return basename(dir) || dir;
 };
+/** How often the localhost dev-server scan may run: never more than this, however often we report. */
+const DEV_SERVER_SCAN_EVERY_MS = 30_000;
+/**
+ * Dev servers listening on localhost with no connected Reticle page — an app that is up and not
+ * instrumented, or not dialling. The same probe `doctor` and the no-session diagnosis use, cached.
+ */
+function devServerScan(connectedUrls, now) {
+    let last;
+    return async () => {
+        if (last === undefined || now() - last.at >= DEV_SERVER_SCAN_EVERY_MS)
+            last = { at: now(), ports: await probeDevServers() };
+        const connected = new Set(connectedUrls().map((url) => {
+            try {
+                return Number(new URL(url).port);
+            }
+            catch {
+                return 0;
+            }
+        }));
+        return last.ports
+            .filter((port) => !connected.has(port))
+            .map((port) => ({ url: `http://${LOCALHOST_HOST}:${String(port)}`, port }));
+    };
+}
+const LOCALHOST_HOST = 'localhost';
 export function startChatDrives(deps, sessions, fs, cloud, log) {
     const env = process.env;
     const machine = machineOf(hostname(), homedir());
@@ -69,13 +103,36 @@ export function startChatDrives(deps, sessions, fs, cloud, log) {
         if (!mayOpen(url, sessions.list().map((tab) => tab.url)))
             throw new Error(NOT_AN_APP_ADDRESS);
     };
-    const open = async (url) => {
+    /**
+     * The `.reticle` each reported app writes into, learned from its tabs. A tab the chat opens for an
+     * app is leased into that root: resolved from the page alone, an app with no project id would land
+     * in `unmatched/`, which nothing syncs.
+     */
+    const rootByApp = new Map();
+    /**
+     * The root AND the project a tab the daemon opens for an app is stamped with. Stamped with the
+     * root alone, a page that reports no project of its own opened as nobody's: its run fell to
+     * `unmatched/` and the drive answered a linked project "run reticle connect".
+     */
+    const claimFor = (appKey) => (appKey === undefined ? undefined : rootByApp.get(appKey)) ?? {};
+    /** Where each credential's project was last open on this machine, from the reports. */
+    const lastUrlByKey = new Map();
+    /** Lease the app a credential's project was last open at, for a drive no tab of it can take. */
+    const reopenFor = async (key) => {
+        const last = lastUrlByKey.get(key);
+        if (last === undefined)
+            return undefined;
+        openable(last.url);
+        const id = asRecord(await runTool(LEASE_ACQUIRE_TOOL, deps, { ...last }))['sessionId'];
+        return 'string' === typeof id ? id : undefined;
+    };
+    const open = async (url, appKey) => {
         openable(url);
-        await runTool(LEASE_ACQUIRE_TOOL, deps, { url });
+        await runTool(LEASE_ACQUIRE_TOOL, deps, { url, ...claimFor(appKey) });
     };
     const pick = (goal, key, app) => undefined === app
-        ? pickOwnDriveSession(sessions.list(), goal, key, sessionKey)
-        : pickAppTab(app, goal, () => sessions.list(), appOf, open).then(async (id) => 
+        ? pickOwnDriveSession(sessions.list(), goal, key, sessionKey, () => reopenFor(key))
+        : pickAppTab(app, goal, () => sessions.list(), appOf, (url) => open(url, app.key)).then(async (id) => 
         // The app the platform named must be one this credential's project owns.
         'string' === typeof id && (await sessionKey(id)) !== key ? null : id);
     const drives = startRemoteDrives({
@@ -91,6 +148,7 @@ export function startChatDrives(deps, sessions, fs, cloud, log) {
                     url,
                     ...(headed ? { headed } : {}),
                     ...(hud === undefined ? {} : { hud }),
+                    ...claimFor(app?.key),
                 }));
                 const id = lease['sessionId'];
                 if ('string' !== typeof id)
@@ -110,9 +168,9 @@ export function startChatDrives(deps, sessions, fs, cloud, log) {
             const tools = reticleToolset(deps, { sessionId, locked: true });
             return { tools: tools.tools, invoke: (tool, args) => tools.invoke(tool, args) };
         },
-        drive: async (goal, sessionId) => {
+        drive: async (goal, sessionId, spec) => {
             const url = sessions.list().find((tab) => tab.sessionId === sessionId)?.url;
-            const outcome = await driveForChat(deps, goal, sessionId);
+            const outcome = await driveForChat(deps, goal, sessionId, spec?.plan, spec?.confirmDangerous);
             return url === undefined ? outcome : { ...outcome, url };
         },
         // The leased tab, or a desktop window's own capture. A web tab only the SDK reaches has no camera.
@@ -122,22 +180,80 @@ export function startChatDrives(deps, sessions, fs, cloud, log) {
         settle: (id, outcome) => endDrivenTab(id === undefined ? undefined : sessions.get(id), outcome),
         log,
     });
+    const scanDevServers = devServerScan(() => sessions.list().map((tab) => tab.url), () => Date.now());
     const reports = startAppReports({
         machine,
         version: cloud.version,
         capabilities: CHAT_CAPABILITIES,
-        apps: async () => appsByPlatform(sessions.list(), serverOptionsFromEnv(await withLinkedCredential(deps, env)), machine.id, async (tab) => {
-            const dir = projectDirFor(deps, tab.sessionId);
-            const platform = await sessionCloud(tab.sessionId);
+        apps: async () => {
+            // The setup score the dashboard shows is what the app's pages carry, asked of each page
+            // until its app has shown both markers: never only what an act happened to reach.
+            await probeMarkers(sessions.list().flatMap((tab) => {
+                const live = sessions.get(tab.sessionId);
+                const command = live?.command?.bind(live);
+                return command === undefined
+                    ? []
+                    : [{ id: tab.sessionId, url: tab.url, projectId: tab.projectId, command }];
+            }));
+            return appsByPlatform(sessions.list().map((tab) => {
+                const live = sessions.get(tab.sessionId);
+                const sdkVersion = live?.sdkVersion;
+                // What the page announced plus the gaps its verdicts paid for: what the dashboard's
+                // coverage line and coding-agent prompt are built from.
+                const channels = announcedChannels({
+                    id: tab.sessionId,
+                    url: tab.url,
+                    projectId: tab.projectId,
+                    channels: live?.channels,
+                    sourceMapping: live?.sourceMapping,
+                });
+                const gaps = recordedGaps(tab.sessionId).map(({ kind, missing, fix, seenAt }) => ({
+                    kind,
+                    missing,
+                    fix,
+                    seenAt,
+                }));
+                return {
+                    ...tab,
+                    ...(sdkVersion === undefined ? {} : { sdkVersion }),
+                    ...(0 === channels.length ? {} : { channels }),
+                    gaps,
+                    notApplicable: notApplicableOf({
+                        id: tab.sessionId,
+                        url: tab.url,
+                        projectId: tab.projectId,
+                    }),
+                };
+            }), serverOptionsFromEnv(await withLinkedCredential(deps, env)), machine.id, async (tab) => {
+                const root = sessionRoot(deps, tab.sessionId);
+                const dir = dirname(root);
+                const projectId = tab.projectId ?? readProjectId(dir);
+                const stamp = { root, ...(projectId === undefined ? {} : { projectId }) };
+                rootByApp.set(appKeyOf(machine.id, dir, tab.projectId), stamp);
+                const platform = await sessionCloud(tab.sessionId);
+                if (undefined !== platform)
+                    lastUrlByKey.set(platform.apiKey, { url: withoutMarks(tab.url), ...stamp });
+                return {
+                    dir,
+                    name: await nameOf(fs, dir, tab.projectId),
+                    ...(undefined === platform
+                        ? {}
+                        : { platform: { url: platform.url.replace(/\/+$/, ''), apiKey: platform.apiKey } }),
+                };
+            });
+        },
+        open,
+        extras: async () => {
+            const closure = sessions.lastClosure?.();
+            const unsynced = cloud.unsynced?.();
             return {
-                dir,
-                name: await nameOf(fs, dir, tab.projectId),
-                ...(undefined === platform
+                devServers: await scanDevServers(),
+                ...(closure === undefined
                     ? {}
-                    : { platform: { url: platform.url.replace(/\/+$/, ''), apiKey: platform.apiKey } }),
+                    : { helloFailure: { reason: closure.reason, at: closure.at } }),
+                ...unsyncedReport(unsynced, homedir()),
             };
-        }),
-        open,
+        },
         drivePending: (platform) => void drives.tick(platform),
         // What the platform wants the person told: in the daemon's log, and on the HUD of each open tab
         // of that project, so somebody who never reads the log still sees "update Reticle".
@@ -163,3 +279,131 @@ export function startChatDrives(deps, sessions, fs, cloud, log) {
         },
     };
 }
+/** The dashboard the tab's project is linked to, when its link names one. */
+function dashboardOf(deps, sessionId) {
+    try {
+        return readDashboardUrl(sessionRoot(deps, sessionId));
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Said on the HUD when Link this project ends. */
+const MSG_LINKED = 'Linked. This project now reports to your dashboard.';
+const MSG_LINK_FAILED = 'Could not link this project. Run `reticle connect` in its folder.';
+/** A page with no projectId: linking it would bind a hash-named project nothing here reads. */
+const MSG_LINK_NEEDS_PROJECT = 'This page did not say which project it is, so there is nothing to link yet. Run `npx @reticlehq/server init` in your app (or pass `projectId` to `connect()`), then Link.';
+const MSG_LINK_UNAVAILABLE = 'This Reticle cannot link from the panel. Run `reticle connect` in the project folder.';
+/** Said on the HUD when Stop finds nothing to stop. */
+const MSG_NOTHING_DRIVING = 'No Harness drive is running in this tab.';
+const msgStartTrial = (url) => `Start your trial: ${url}`;
+/**
+ * The panel's Harness controls. The switch is the platform's autonomous mode, unchanged. Run Harness
+ * and Stop drive. A run asks the platform for the drive's grant, then starts it
+ * through the same explore an agent calls (counted, recorded, polled the same way); its lines and
+ * steps reach the HUD log as the drive narrates them. A refused grant says why, and where to start
+ * a trial when it wants a card.
+ */
+export async function hudDrive(deps, sessionId, 
+/** The panel's control, as the bridge narrowed it (`harness-request.ts`). */
+request, 
+/** The autonomous switch: written through to the platform, which the daemon owns. */
+applySwitch, grant = (platform) => requestFreeDrive(platform, FreeDriveKind.EXPLORE)) {
+    if (HumanControlKind.HARNESS === request.kind)
+        return applySwitch(request.enabled);
+    // What the panel's Run and Stop answer belongs in the Harness log, and in the Agent Log as a summary.
+    const say = (text) => deps.sessions.get?.(sessionId)?.pushNarration(text, true, { harness: true, summary: true });
+    if (HumanControlKind.HARNESS_STOP === request.kind) {
+        const running = runningDrive(sessionId);
+        if (running === undefined || !stopDrive(running.harnessRun))
+            say(MSG_NOTHING_DRIVING);
+        return;
+    }
+    // Before the grant: a drive the gate refuses must not take one. The panel shows the prompt.
+    const env = await withLinkedCredential(deps, process.env, { sessionId });
+    const locked = await harnessLockRefusal(deps, sessionId, env);
+    if (locked !== undefined)
+        return say(locked.split('\n')[0] ?? locked);
+    const platform = serverOptionsFromEnv(env);
+    if (platform === undefined)
+        return say(MSG_NO_HARNESS_KEY);
+    const granted = await grant(platform);
+    if (!granted.granted) {
+        say(granted.message);
+        // At the console's origin (the tab's link names it), never the API's, which 404s when split.
+        if (granted.needsCard)
+            say(msgStartTrial(planUrl(dashboardOf(deps, sessionId) ?? platform.url)));
+        return;
+    }
+    const explore = EXPLORE_TOOLS.find((tool) => ReticleTool.VERIFY_EXPLORE === tool.name);
+    if (explore === undefined)
+        return;
+    try {
+        await runTool(explore, deps, {
+            sessionId,
+            driveId: granted.driveId,
+            origin: DriveOrigin.HUD,
+            wait: 0,
+            ...(request.persona === undefined ? {} : { persona: request.persona }),
+        });
+    }
+    catch (error) {
+        say(error instanceof Error ? error.message : String(error));
+    }
+}
+/**
+ * The link a panel sign-in makes once it lands: the tab's project, never a page that did not say
+ * which project it is (that would bind a hash-named project nothing here reads).
+ */
+export function projectLinkOnly(link) {
+    return link === undefined
+        ? undefined
+        : (root) => (isUnmatchedRoot(root) ? Promise.resolve(0) : link(root));
+}
+/**
+ * The panel's Harness controls on a bridge: the switch writes through to the platform, so console
+ * and panel cannot disagree; Run and Stop drive, in the project of the tab that asked.
+ */
+export function attachHudHarness(bridge, daemon, applySwitch, 
+/** Link this project: what `reticle connect` does from that folder. Absent: the button says so. */
+link) {
+    bridge.attachHarnessRequest((request, s) => {
+        const root = s.artifactRoot ?? daemon.root;
+        if (HumanControlKind.HARNESS_LINK === request.kind) {
+            const say = (text) => daemon.deps().sessions.get?.(s.id)?.pushNarration(text);
+            if (link === undefined)
+                return say(MSG_LINK_UNAVAILABLE);
+            if (isUnmatchedRoot(root))
+                return say(MSG_LINK_NEEDS_PROJECT);
+            void link(root)
+                .then((code) => say(0 === code ? MSG_LINKED : MSG_LINK_FAILED))
+                .catch(() => say(MSG_LINK_FAILED))
+                .finally(daemon.repaint);
+            return;
+        }
+        void hudDrive(daemon.deps(), s.id, request, (on) => applySwitch(root, on));
+    });
+    onDriveChange(daemon.repaint);
+    // Each step too, so the panel's "N steps so far" counts up instead of sitting at zero.
+    onDriveStep(daemon.repaint);
+    // And "Connected: Claude Code" follows an agent attaching or leaving.
+    onAgentsChange(daemon.repaint);
+}
+/**
+ * The `unsynced` field of a report. Sent empty too, once this daemon has counted: the platform reads
+ * an absent list as "no news" and kept a "never sent" banner for runs that had long been sent.
+ */
+export function unsyncedReport(unsynced, home) {
+    if (unsynced === undefined)
+        return {};
+    return {
+        // A folder no project claimed cannot be connected, so no board should tell anyone to.
+        unsynced: unsynced
+            .filter((u) => !isUnmatchedRoot(u.root))
+            .map((u) => ({
+            ...u,
+            // The project, not its `.reticle`: the dashboard tells the person to run a command there.
+            root: homeRelative(ReticleDir.ROOT === basename(u.root) ? dirname(u.root) : u.root, home),
+        })),
+    };
+}

package/dist/surface/tools/coverage-tools.d.ts

@@ -5,14 +5,6 @@ interface Control {
 }
 /** Parse the interactive snapshot into {ref,label} controls, preserving document order. */
 export declare function parseControls(tree: string): Control[];
-/**
- * Build the coverage tool over the dispatchable tool table.
- *
- * The table arrives as a thunk rather than an import: `tools.ts` assembles it FROM this module, so
- * importing it back would close a cycle whose failure mode is a load-order-dependent crash rather
- * than an error anyone sees while writing it. The thunk is called inside the handler, long after the
- * table exists. It carries the merged names — the ones `reticle_run` will actually accept — because
- * a tool that merged into a parent is not something an agent can call or a maintainer can cut.
- */
-export declare function buildCoverageTools(toolNames: () => readonly string[]): ToolDef[];
+/** Build the coverage tool. */
+export declare function buildCoverageTools(): ToolDef[];
 export {};

package/dist/surface/tools/coverage-tools.js

@@ -2,9 +2,6 @@ import { z } from 'zod';
 import { sessionRoot } from '../../memory/project/session-root.js';
 import { projectForRoot } from '../../memory/project/project-for-root.js';
 import { coverageRegressed, observabilityOf } from '@reticlehq/engine/evidence/observability.js';
-import { foldFeatureCapture } from './feature-capture.js';
-import { foldToolHitRate } from './tool-hit-rate.js';
-import { allSessionIntents } from '../../memory/intent/open-intents.js';
 import { ReticleCommand, SnapshotMode } from '@reticlehq/core';
 import { ReticleTool } from '@reticlehq/core';
 import { asString } from '@reticlehq/core';
@@ -55,16 +52,8 @@ export function parseControls(tree) {
     }
     return controls;
 }
-/**
- * Build the coverage tool over the dispatchable tool table.
- *
- * The table arrives as a thunk rather than an import: `tools.ts` assembles it FROM this module, so
- * importing it back would close a cycle whose failure mode is a load-order-dependent crash rather
- * than an error anyone sees while writing it. The thunk is called inside the handler, long after the
- * table exists. It carries the merged names — the ones `reticle_run` will actually accept — because
- * a tool that merged into a parent is not something an agent can call or a maintainer can cut.
- */
-export function buildCoverageTools(toolNames) {
+/** Build the coverage tool. */
+export function buildCoverageTools() {
     return [
         {
             name: ReticleTool.COVERAGE,
@@ -100,25 +89,6 @@ export function buildCoverageTools(toolNames) {
                     .object({ driven: z.number(), observable: z.number(), percent: z.number().optional() })
                     .optional()
                     .describe('Of the controls you DROVE, how many Reticle could fully observe. `untouched` above is work left for you; this is work left in the APP, and driving more controls does not move it. `percent` is OMITTED when nothing was driven, because 0/0 is not 100%.'),
-                featureUse: z
-                    .object({
-                    observed: z.boolean(),
-                    truncated: z.boolean().optional(),
-                    context: z.unknown().optional(),
-                    intents: z.unknown().optional(),
-                    missed: z.unknown().optional(),
-                })
-                    .optional()
-                    .describe('Whether this session used `reticle_context` and `reticle_intent` at all, and what it cost when it did not: `context` counts the calls and what followed each one, `intents` the ledger, `missed` the verdicts drawn against an empty ledger and the reads that re-fetched a fact already established. `observed:false` means nothing was recorded for this session — NOT that nothing was used. An instrument for deciding whether those two features earn their place; nothing here is a fault of yours.'),
-                toolHitRate: z
-                    .object({
-                    observed: z.boolean(),
-                    cells: z.unknown().optional(),
-                    called: z.unknown().optional(),
-                    neverCalled: z.unknown().optional(),
-                })
-                    .optional()
-                    .describe('Which Reticle tools THIS session called, and how reachable each one was: `called` lists every tool with its call count, `neverCalled` the rest of the table, and both carry a `tier` — `default` (advertised to every agent), `extended` (advertised only on the full surface) or `run-only` (reachable solely by naming it to reticle_run). `cells` counts each tier on both sides. `observed:false` means nothing was recorded for this session, NOT that nothing was called. THREE LIMITS, all load-bearing: this is ONE session, so it is evidence about this run and is not a hit rate — a hit rate is a distribution over many sessions. A never-called tool is not a useless tool; one used once a month in an emergency looks identical here to one nobody has ever called, so frequency alone cannot decide a cut. And the counts describe how this run went, never how it should have gone — nothing here is a fault of yours.'),
                 observabilityRegressed: z
                     .object({ was: z.number(), now: z.number() })
                     .optional()
@@ -143,25 +113,6 @@ export function buildCoverageTools(toolNames) {
                 // first without the second is how an agent finishes a pass believing it verified something the
                 // app was never able to confirm.
                 const gaps = session.gaps?.open() ?? [];
-                // Folded here rather than given a tool of its own: this is already the "am I done, and what is
-                // this verdict worth" read, and a number nobody has a reason to ask for separately is one
-                // nobody ever sees. It is a fold over the journal and the intent ledger plus the one thing
-                // neither records — see surface/tools/feature-capture.ts.
-                const featureUse = foldFeatureCapture({
-                    calls: session.capture.calls(),
-                    dropped: session.capture.dropped,
-                    actions: await session.readJournalActions(),
-                    intents: await allSessionIntents(deps, sessionId),
-                    finalActions: session.actionCount,
-                });
-                // Same fold, same reason, one level out: which of the whole tool table this session reached
-                // for, crossed with how reachable each name was. See surface/tools/tool-hit-rate.ts for what it can
-                // and cannot establish — the limits matter more than usual, because this is the number a
-                // decision to DELETE tools would be made on.
-                const toolHitRate = foldToolHitRate({
-                    calls: session.capture?.toolCalls(),
-                    allTools: toolNames(),
-                });
                 // The number, and the floor under it, together. A coverage figure that can only ever be
                 // reported and never contradicted is one an agent learns to satisfy rather than to earn.
                 const observability = observabilityOf(session.actedRefs(), gaps);
@@ -179,8 +130,6 @@ export function buildCoverageTools(toolNames) {
                     ...(gaps.length > 0 ? { instrumentationGaps: gaps, unproven: true } : {}),
                     observability,
                     ...(regressed === undefined ? {} : { observabilityRegressed: regressed }),
-                    featureUse,
-                    toolHitRate,
                     ...(true === args['app']
                         ? {
                             app: await foldAppCoverage({

package/dist/surface/tools/dynamic-tools.js

@@ -8,13 +8,41 @@ import { ReticleTool } from '@reticlehq/core';
 import { ADVERTISE_ALL_ENV } from './tool-surface.js';
 import { getSessionMetrics } from '../../telemetry/session-metrics.js';
 import { isPredicateParam, predicateGrammar, } from '@reticlehq/engine/question/predicate/predicate-eval.js';
+/**
+ * A numeric parameter's enforced bounds, read off the schema that enforces them (#1537).
+ *
+ * The descriptions name a default and rarely a ceiling, so `timeout_ms: 60000` on act_and_wait was
+ * refused and the agent learned the 55000 cap from the error. Read here rather than written into
+ * prose, so the number shown is the number checked and cannot drift from it.
+ */
+function boundsOf(schema) {
+    let inner = schema;
+    for (;;) {
+        if (inner instanceof z.ZodOptional || inner instanceof z.ZodNullable) {
+            inner = inner.unwrap();
+        }
+        else if (inner instanceof z.ZodDefault) {
+            inner = inner.removeDefault();
+        }
+        else if (inner instanceof z.ZodEffects) {
+            inner = inner.innerType();
+        }
+        else
+            break;
+    }
+    if (!(inner instanceof z.ZodNumber))
+        return {};
+    const { minValue: min, maxValue: max } = inner;
+    return { ...(null === min ? {} : { min }), ...(null === max ? {} : { max }) };
+}
 /** Compact param list from a tool's zod shape — name/required/description (the description already
- * carries the type and any enum hints, so no JSON-Schema machinery is needed). */
+ * carries the type and any enum hints, so no JSON-Schema machinery is needed), plus numeric bounds. */
 function paramInfo(shape) {
     return Object.entries(shape).map(([name, schema]) => ({
         name,
         required: !schema.isOptional(),
         description: schema.description ?? '',
+        ...boundsOf(schema),
     }));
 }
 /**

package/dist/surface/tools/empty-session-list.d.ts

@@ -38,4 +38,14 @@ export declare const EMPTY_SESSION_LIST_OUTPUT: {
         url: string;
     }>>;
 };
+/**
+ * Wire the calling project when another project's tab is the one currently connected.
+ *
+ * The list handler only used to reach {@link emptySessionList} when the daemon's whole list was
+ * empty. A live tab in project A then answered project B's first call with A's sessions, and B
+ * was never wired.
+ */
+export declare function wireCallerBesideLiveSessions(deps: ToolDeps, sessions: readonly {
+    projectId?: string;
+}[]): Promise<unknown>;
 export declare function emptySessionList(deps: ToolDeps, sessions: unknown[]): Promise<Record<string, unknown>>;

package/dist/surface/tools/empty-session-list.js

@@ -9,6 +9,8 @@
 import { dirname } from 'node:path';
 import { z } from 'zod';
 import { DiscoveryInvite, NoSessionAction } from '@reticlehq/core';
+import { readProjectId } from '../../command/cli/ports/resolve/cli-port.js';
+import { callingClientDirectory } from '../../hooks/client-directory.js';
 /** The answers that mean "this app is not set up yet", which a first run can settle by wiring it. */
 const FIRST_RUN_ACTIONS = new Set([
     NoSessionAction.RUN_INIT,
@@ -46,18 +48,56 @@ export const EMPTY_SESSION_LIST_OUTPUT = {
         .optional()
         .describe('Present ONLY when `sessions` is empty AND a tab was connected to this daemon earlier: the last sessionId and URL that tab was on when it disappeared. A route that 500s tears the page down and the SDK never reconnects — this is the last thing we knew, not a route-500 verdict. An empty list with no lastKnown is a tab that never arrived.'),
 };
+/**
+ * Wire the calling project when another project's tab is the one currently connected.
+ *
+ * The list handler only used to reach {@link emptySessionList} when the daemon's whole list was
+ * empty. A live tab in project A then answered project B's first call with A's sessions, and B
+ * was never wired.
+ */
+export async function wireCallerBesideLiveSessions(deps, sessions) {
+    const dir = callingClientDirectory();
+    if (dir === undefined)
+        return undefined;
+    const projectId = readProjectId(dir);
+    if (projectId !== undefined && sessions.some((session) => session.projectId === projectId)) {
+        return undefined;
+    }
+    const next = deps.sessions.noSessionNextAction();
+    const target = next !== undefined && FIRST_RUN_ACTIONS.has(next.action)
+        ? deps.firstRun?.projectDirectory(dir)
+        : undefined;
+    if (target === undefined || deps.firstRun === undefined)
+        return undefined;
+    return deps.firstRun.wire(target);
+}
+/** The departed tab for this call: the caller's own project when it named one, else the daemon's newest. */
+function departedForCaller(deps) {
+    const dir = callingClientDirectory();
+    if (dir === undefined)
+        return deps.sessions.lastKnown?.();
+    const projectId = readProjectId(dir);
+    if (projectId === undefined)
+        return undefined;
+    return deps.sessions.lastKnownFor?.(projectId);
+}
 export async function emptySessionList(deps, sessions) {
-    const why = deps.sessions.noSessionHint();
+    // The lead and its next action: the full differential (~3 KB of ranked causes) read as
+    // speculation on the call an agent makes first. Optional-call: test stubs predate the lead.
+    const why = deps.sessions.noSessionLead?.() ?? deps.sessions.noSessionHint();
     // The executable half. `why` is for the human reading the transcript; this is the one the
     // agent acts on, so it never has to parse a paragraph to find a command inside it.
     const next = deps.sessions.noSessionNextAction();
-    // The first run wires the app, not the installation: the daemon runs init itself, once,
-    // in its own project, and says what it changed. A daemon outside any project asks instead.
+    // The first run wires the app the client is in, not the directory the daemon was started in.
+    // One daemon serves every project; the proxy names its cwd on the call. With no caller (an
+    // embed, a test) it is still the daemon's own project. A daemon outside any project asks instead.
+    // ponytail: cwd, not an MCP roots/list round trip. A proxy started outside the project still
+    // answers run_init; roots are the upgrade when a client launches there but names the project.
     // Not only on `run_init`: an unwired app whose dev server is not running yet answers
     // `start_dev_server`, which is the commonest first run of all, and init starts that server itself.
     // `projectDirectory` refuses a project that is already wired, so a wired app is never re-run.
     const dir = next !== undefined && FIRST_RUN_ACTIONS.has(next.action)
-        ? deps.firstRun?.projectDirectory(dirname(deps.reticleRoot))
+        ? deps.firstRun?.projectDirectory(callingClientDirectory() ?? dirname(deps.reticleRoot))
         : undefined;
     if (dir !== undefined && deps.firstRun !== undefined) {
         const wired = await deps.firstRun.wire(dir);
@@ -67,7 +107,7 @@ export async function emptySessionList(deps, sessions) {
         return { sessions, wired, ...(why === undefined ? {} : { why }) };
     }
     // The last tab, when one was here. Optional-call: test stubs of SessionManager predate it.
-    const known = deps.sessions.lastKnown?.();
+    const known = departedForCaller(deps);
     const lastKnown = undefined === known ? undefined : { sessionId: known.id, url: known.url };
     return {
         sessions,

package/dist/surface/tools/error-recovery.d.ts

@@ -18,6 +18,7 @@ export declare const RECOVERY: {
     readonly MISSING_BASELINE: string;
     readonly MISSING_RECORDING: string;
     readonly STALE_REF: string;
+    readonly UNISSUED_REF: string;
     readonly STALE_REF_AFTER_EDIT: string;
     readonly INVALID_NAME: string;
     /**
@@ -78,6 +79,13 @@ export declare const RECOVERY: {
      * who deliberately switched the harness off gets a bug report filed about their own decision.
      */
     readonly HARNESS_OFF: string;
+    /**
+     * The Harness asked for on a project that is not linked to the platform. The call was valid, and
+     * the refusal names reticle_act_and_wait as the alternative, which the catch-all below read as an
+     * agent's malformed call: it was then told to fix arguments that were never wrong.
+     */
+    readonly HARNESS_LOCKED: string;
+    readonly HARNESS_NOT_LINKED: string;
 };
 /**
  * The actionable next move for a known error message, or undefined when none is recognized.