@reticlehq/server 3.8.1 → 3.9.0

package/dist/portal/session/no-session-diagnosis.js

@@ -178,7 +178,7 @@ const INIT_CMD = '`npx @reticlehq/server init`';
  * against it, and it has to be read before the "nothing is listening" sentence rather than after —
  * the reader acts on the first claim.
  */
-function slowListenerClause(facts) {
+function slowListenerClause(facts, after = '') {
     const slow = facts.slowListeners ?? [];
     if (0 === slow.length)
         return '';
@@ -186,7 +186,7 @@ function slowListenerClause(facts) {
     const subject = 1 === slow.length ? `Port ${ports} ACCEPTED` : `Ports ${ports} ACCEPTED`;
     return (`${subject} a connection but did not answer in time, which is what a server-rendered dev ` +
         'server compiling its first route looks like — so something IS running there and you should ' +
-        'open it rather than start it. Setting that aside: ');
+        `open it rather than start it.${after}`);
 }
 /**
  * The commonest first-run state there is (#320).
@@ -481,7 +481,7 @@ export function explainNoSession(facts) {
         // is expected rather than diagnostic.
         if (!initialized) {
             return reason(NoSessionReason.NO_LISTENER_NO_CONFIG, 'no browser session connected. Two things to weigh, and neither of them is proof. ' +
-                `(1) ${slowListenerClause(facts)}Nothing is listening on the ports Reticle scans, so the ` +
+                `(1) ${slowListenerClause(facts, ' Setting that aside: ')}Nothing is listening on the ports Reticle scans, so the ` +
                 'dev server may not be running: START IT YOURSELF, in the background, using the command ' +
                 'in `next_action`, and tell the human in one line that it is running. ' +
                 `(2) There is no \`.reticle.json\` in ${where}, which is the file ${INIT_CMD} writes, so ` +
@@ -493,6 +493,13 @@ export function explainNoSession(facts) {
                 'the Vite or Babel plugin carries the SDK without that file at all.' +
                 `${searchedClause(facts)}${siblingListenerClause(facts)} ${leaseAdvice(URL_THEN_LEASE, facts)}`);
         }
+        // A wired project whose own port accepted a connection and answered nothing yet is compiling,
+        // not down. "Start it yourself" here starts a second dev server.
+        if ((facts.slowListeners ?? []).length > 0) {
+            return reason(NoSessionReason.NO_LISTENER, `${stallClause(facts)}no browser session connected, and this daemon has never seen one. ` +
+                `${slowListenerClause(facts)} Do not start a second dev server. ` +
+                `Wait for the first compile to finish, then open the app (the command is in \`next_action\`). ${RETRY}`, `${leaseAdvice(URL_THEN_LEASE, facts)}${siblingListenerClause(facts)}`);
+        }
         return reason(NoSessionReason.NO_LISTENER, `${stallClause(facts)}no browser session connected, and this daemon has never seen one. ${openTheApp(facts)} ` +
             'Nothing is listening on the ports Reticle scans either, and the usual reason is a dev ' +
             'server that is not running: start it yourself in the background with the command in ' +

package/dist/portal/session/no-session-next-action.d.ts

@@ -102,6 +102,11 @@ interface NextActionFacts {
      * project's own runner (see `initCommandIn`). Absent means the generic npx spelling.
      */
     init?: string;
+    /**
+     * Several direct child folders are apps with a dev script, and this folder has no package.json.
+     * Absent or short means there is no choice to hand the agent. See `childDevApps`.
+     */
+    childApps?: readonly string[];
 }
 /** The port a tombstone URL names, when it names one — anything unparseable names no port. */
 export declare function portOfUrl(url: string): number | undefined;
@@ -123,6 +128,13 @@ export declare const INIT_COMMAND = "npx @reticlehq/server init";
  * agent asks first. The lease changes nothing, so it needs no question.
  */
 export declare function wiringConsent(init?: string): string;
+/**
+ * The offer for the first session in an unwired web app: check it now with the lease, then ask
+ * before `init`. The one text for the plugin's SessionStart hook and the first tool call of each
+ * agent connection. The hook cannot import this, so it keeps a copy, and
+ * `plugin-init-nudge.test.ts` fails when the two are not the same.
+ */
+export declare function firstSessionOffer(init?: string): string;
 /** The zero-install call, with the URL only when it can be named without guessing. */
 export declare function zeroInstallLease(url: string | undefined): string;
 export declare function nextActionFor(facts: NextActionFacts): NoSessionNextAction;

package/dist/portal/session/no-session-next-action.js

@@ -18,8 +18,9 @@ import { detectNonJsEcosystem, noPackageJsonMessage } from '@reticlehq/init';
 export function portOfUrl(url) {
     try {
         const raw = new URL(url).port;
-        if ('' === raw)
+        if ('' === raw) {
             return undefined;
+        }
         const port = Number(raw);
         return Number.isSafeInteger(port) && port > 0 ? port : undefined;
     }
@@ -45,8 +46,9 @@ export function departedPortGone(facts) {
  * for a url that does not parse, or one with no port to name (a desktop webview's opaque origin).
  */
 function reopenableUrl(raw) {
-    if (raw === undefined)
+    if (raw === undefined) {
         return undefined;
+    }
     let url;
     try {
         url = new URL(raw);
@@ -54,10 +56,12 @@ function reopenableUrl(raw) {
     catch {
         return undefined;
     }
-    if ('http:' !== url.protocol && 'https:' !== url.protocol)
+    if ('http:' !== url.protocol && 'https:' !== url.protocol) {
         return undefined;
-    for (const param of Object.values(RETICLE_URL_PARAM))
+    }
+    for (const param of Object.values(RETICLE_URL_PARAM)) {
         url.searchParams.delete(param);
+    }
     const port = '' === url.port ? ('https:' === url.protocol ? 443 : 80) : Number(url.port);
     return { url: url.toString(), port };
 }
@@ -78,6 +82,17 @@ export function wiringConsent(init = INIT_COMMAND) {
         'build config and starts the dev server. Ask the user before you wire the app. If they ' +
         `agree, run \`${init}\` in the app's folder. If they decline, do not ask again.`);
 }
+/**
+ * The offer for the first session in an unwired web app: check it now with the lease, then ask
+ * before `init`. The one text for the plugin's SessionStart hook and the first tool call of each
+ * agent connection. The hook cannot import this, so it keeps a copy, and
+ * `plugin-init-nudge.test.ts` fails when the two are not the same.
+ */
+export function firstSessionOffer(init = INIT_COMMAND) {
+    return (`This web app can be checked now with no install: \`${zeroInstallLease(undefined)}\` opens ` +
+        "the running app in Reticle's own browser and changes no file. To keep Reticle wired to this " +
+        `app: ${wiringConsent(init)}`);
+}
 const OPEN_COMMAND = `${CLI} open`;
 const LOCALHOST = 'http://localhost';
 /**
@@ -243,6 +258,19 @@ export function nextActionFor(facts) {
                 'args: { action: "acquire", url, projectId } }, or restart the daemon from the app\'s own directory.',
         };
     }
+    // A wired project whose only port accepted a connection and answered nothing yet: a dev server
+    // compiling its first route. It is up, so a start command would start a second one.
+    const compiling = facts.slowListeners?.[0];
+    if (true === facts.initialized && 0 === facts.listening.length && compiling !== undefined) {
+        return {
+            action: NoSessionAction.OPEN_APP,
+            command: `${OPEN_COMMAND} ${LOCALHOST}:${String(compiling)}`,
+            port: compiling,
+            reason: `port ${String(compiling)} accepted a connection but did not answer in time, which is a dev ` +
+                'server compiling its first route. The app IS running. Do not start a second dev server. ' +
+                'Wait for the compile to finish, then open it.',
+        };
+    }
     if (0 === facts.listening.length || departedPortIsGone) {
         const dev = facts.dev;
         // The start advice below follows a departed session whose port is gone. Name it, so the restart
@@ -255,6 +283,18 @@ export function nextActionFor(facts) {
             ? "nothing answers on the port this project's app was last on, so the app is probably not running — "
             : notThisProject(facts.otherListeners);
         if (dev === undefined) {
+            const childApps = facts.childApps ?? [];
+            if (1 < childApps.length) {
+                return {
+                    action: NoSessionAction.START_DEV_SERVER,
+                    reason: notRunning +
+                        `but this folder has no package.json, and ${childApps.length} child folders are apps ` +
+                        `with a dev script: ${childApps.join(', ')}. Reticle cannot tell which one you mean, so ` +
+                        'there is no command to hand you. Pick one, then run Reticle from that folder or ask ' +
+                        'the human which app to start.' +
+                        stoppedNote,
+                };
+            }
             if (facts.exists !== undefined && !facts.exists('package.json')) {
                 const ecosystem = detectNonJsEcosystem(facts.exists);
                 if (ecosystem !== undefined) {

package/dist/portal/session/no-session-watch.js

@@ -17,7 +17,7 @@ import { join, resolve } from 'node:path';
 import { callingClientDirectory } from '../../hooks/client-directory.js';
 import { registeredElsewhere } from '../../memory/recall/registered-projects.js';
 import { explainNoSession } from './no-session-diagnosis.js';
-import { detectDevCommandInProject, initCommandIn } from './dev-server/dev-command.js';
+import { childDevApps, detectDevCommandInProject, initCommandIn, } from './dev-server/dev-command.js';
 import { nextActionFor, portOfUrl, renderNextAction } from './no-session-next-action.js';
 import { DEV_SERVER_PORTS, readProjectFramework, readProjectId, readProjectIsDesktop, readProjectPort, } from '../../command/cli/ports/resolve/cli-port.js';
 import { discoverProjectConfigs } from '../../command/cli/config/config-discovery.js';
@@ -480,6 +480,7 @@ export function startNoSessionWatch(options) {
                     ...(known.departedTo === undefined ? {} : { departedTo: known.departedTo }),
                 }),
             dev: detectDevCommandInProject(dir),
+            childApps: childDevApps(dir),
             init: initCommandIn(dir),
         });
         return { facts, next };
@@ -540,6 +541,7 @@ export function startNoSessionWatch(options) {
             // Read when asked, like everything else here: a `package.json` can gain a dev script, and a
             // daemon that cached "there is none" at boot would keep saying so for the rest of the day.
             dev: detectDevCommandInProject(directory),
+            childApps: childDevApps(directory),
             // This project's own runner and app folder, so the agent can wire it itself.
             init: initCommandIn(directory),
         });

package/dist/portal/session/page-commands/undeclared-command.d.ts

@@ -18,8 +18,14 @@
  * answers rather than a set lookup at the call site.
  */
 import { type CommandResult } from '@reticlehq/core';
-/** Why nothing was sent, in a sentence, or undefined when the command should go. */
-export declare function refusalForUndeclared(name: string, declared: readonly string[] | undefined): string | undefined;
+/**
+ * Why nothing was sent, in a sentence, or undefined when the command should go.
+ *
+ * `behind` is the caller's sentence for a page SDK older than this daemon. A newer command
+ * (`render`, `match`) is then missing because of the version, and the list of commands alone
+ * does not say that.
+ */
+export declare function refusalForUndeclared(name: string, declared: readonly string[] | undefined, behind?: string): string | undefined;
 /**
  * The refusal as a finished result, or undefined when the command should be sent.
  *
@@ -27,4 +33,4 @@ export declare function refusalForUndeclared(name: string, declared: readonly st
  * cannot get the envelope subtly wrong -- an `ok: true` refusal would be read as a command that
  * worked, which is the one shape this must never produce.
  */
-export declare function refusedResult(name: string, declared: readonly string[] | undefined, id: string): CommandResult | undefined;
+export declare function refusedResult(name: string, declared: readonly string[] | undefined, id: string, behind?: string): CommandResult | undefined;

package/dist/portal/session/page-commands/undeclared-command.js

@@ -18,16 +18,25 @@
  * answers rather than a set lookup at the call site.
  */
 import { MessageKind } from '@reticlehq/core';
-/** Why nothing was sent, in a sentence, or undefined when the command should go. */
-export function refusalForUndeclared(name, declared) {
+/**
+ * Why nothing was sent, in a sentence, or undefined when the command should go.
+ *
+ * `behind` is the caller's sentence for a page SDK older than this daemon. A newer command
+ * (`render`, `match`) is then missing because of the version, and the list of commands alone
+ * does not say that.
+ */
+export function refusalForUndeclared(name, declared, behind) {
     // Too old to say. Unknown, never "nothing".
-    if (declared === undefined)
+    if (declared === undefined) {
         return undefined;
-    if (declared.includes(name))
+    }
+    if (declared.includes(name)) {
         return undefined;
+    }
     return (`this page does not serve "${name}". It declared ${String(declared.length)} command(s) when ` +
         `it connected, and this is not one of them: ${declared.join(', ')}. Nothing was sent, so ` +
-        'nothing happened -- this is a refusal, not a failure of the app.');
+        'nothing happened -- this is a refusal, not a failure of the app.' +
+        (behind === undefined ? '' : ` ${behind}`));
 }
 /**
  * The refusal as a finished result, or undefined when the command should be sent.
@@ -36,8 +45,8 @@ export function refusalForUndeclared(name, declared) {
  * cannot get the envelope subtly wrong -- an `ok: true` refusal would be read as a command that
  * worked, which is the one shape this must never produce.
  */
-export function refusedResult(name, declared, id) {
-    const error = refusalForUndeclared(name, declared);
+export function refusedResult(name, declared, id, behind) {
+    const error = refusalForUndeclared(name, declared, behind);
     return error === undefined
         ? undefined
         : { kind: MessageKind.COMMAND_RESULT, id, ok: false, error };

package/dist/portal/session/recorded-gaps.d.ts

@@ -49,7 +49,7 @@ export declare function probeMarkers(tabs: readonly ProbedTab[]): Promise<boolea
 /**
  * The `engineBlindSpots` field for a verdict result: what this engine could not observe in the
  * session so far. Notes this verdict's own comparison first, so a `compare` clears the arithmetic
- * spot on the result that ran it. `claims`: the inline intent, then the run's declared intents.
+ * spot on the result that ran it. `claims`: the inline intent, or else the run's declared intents.
  */
 export declare function engineBlindSpotsField(sessionId: string, predicate: Predicate | undefined, intent: unknown, declared: readonly {
     statement: string;

package/dist/portal/session/recorded-gaps.js

@@ -162,12 +162,15 @@ const comparedSeen = new Set();
 /**
  * The `engineBlindSpots` field for a verdict result: what this engine could not observe in the
  * session so far. Notes this verdict's own comparison first, so a `compare` clears the arithmetic
- * spot on the result that ran it. `claims`: the inline intent, then the run's declared intents.
+ * spot on the result that ran it. `claims`: the inline intent, or else the run's declared intents.
  */
 export function engineBlindSpotsField(sessionId, predicate, intent, declared) {
     if (computesComparison(predicate))
         comparedSeen.add(sessionId);
-    const claims = [text(intent), ...declared.map((each) => each.statement)];
+    // A call that names its own intent is judged on that intent alone. The run's open intents can be
+    // an earlier task's, and judging them reported that task's claim on this one (#1938).
+    const own = text(intent);
+    const claims = own === undefined ? declared.map((each) => each.statement) : [own];
     return {
         [ENGINE_BLIND_SPOTS_FIELD]: engineBlindSpots({
             canvasSeen: canvasSeen.has(sessionId),

package/dist/portal/session/session-manager.js

@@ -1,4 +1,4 @@
-import { NO_SESSION_CONNECTED_ERROR, originOf, samePath } from '@reticlehq/core';
+import { NO_SESSION_CONNECTED_ERROR, NO_SESSION_NAVIGATE_FIX, originOf, samePath, } from '@reticlehq/core';
 import { notePendingNoSessionReason } from '../../telemetry/tool-refused.js';
 import { declareDrivenRedactionKeys, forgetDrivenRedactionKeys, } from '../input/driven-redaction.js';
 import { Session } from './session.js';
@@ -14,8 +14,9 @@ export { originOf };
  * no scope, return the list unchanged (legacy single-/multi-session behavior).
  */
 function scopeSessions(sessions, scope) {
-    if (scope === undefined)
+    if (scope === undefined) {
         return sessions;
+    }
     if (scope.projectId !== undefined) {
         return sessions.filter((s) => s.projectId === scope.projectId);
     }
@@ -124,8 +125,9 @@ export class SessionManager {
     }
     add(session) {
         this.#everConnected = true;
-        if (session.projectId !== undefined)
+        if (session.projectId !== undefined) {
             this.#connectedProjects.add(session.projectId);
+        }
         // Ordering, not lifetime: this is what makes a remembered refusal distinguishable from a live
         // one. Here for the same reason `#everConnected` is — `add` is the one method every path that
         // registers a session goes through.
@@ -177,8 +179,9 @@ export class SessionManager {
     }
     #parked = new Set();
     remove(session) {
-        if (this.#sessions.get(session.id) !== session)
+        if (this.#sessions.get(session.id) !== session) {
             return false;
+        }
         session.rejectAll(SESSION_DISCONNECTED_REASON);
         forgetDrivenRedactionKeys(session.id);
         // Recorded, not forgotten: a session that comes back needs its gap measured, and a listing after
@@ -189,10 +192,12 @@ export class SessionManager {
     }
     #rememberTombstone(session) {
         const origin = originOf(session.url);
-        if (origin === undefined)
+        if (origin === undefined) {
             return;
-        if (this.#tombstones.has(session.id))
+        }
+        if (this.#tombstones.has(session.id)) {
             this.#tombstones.delete(session.id);
+        }
         this.#siblingsAtDeparture.set(session.id, new Set([...this.#sessions.values()]
             .filter((s) => s !== session && openedBeforeDeparture(s, session))
             .map((s) => s.id)));
@@ -206,16 +211,18 @@ export class SessionManager {
         });
         while (this.#tombstones.size > MAX_TOMBSTONES) {
             const oldest = this.#tombstones.keys().next().value;
-            if (oldest === undefined)
+            if (oldest === undefined) {
                 break;
+            }
             this.#tombstones.delete(oldest);
             this.#siblingsAtDeparture.delete(oldest);
         }
     }
     #successorOf(sessionId) {
         const departed = this.#tombstones.get(sessionId);
-        if (departed === undefined)
+        if (departed === undefined) {
             return undefined;
+        }
         const siblings = this.#siblingsAtDeparture.get(sessionId);
         const picked = pickDocumentSuccessor(this.all()
             .filter((s) => true !== siblings?.has(s.id))
@@ -224,8 +231,9 @@ export class SessionManager {
             url: s.url,
             ...(s.projectId === undefined ? {} : { projectId: s.projectId }),
         })), departed);
-        if (picked === undefined)
+        if (picked === undefined) {
             return undefined;
+        }
         return this.#sessions.get(picked.id);
     }
     get(sessionId) {
@@ -396,8 +404,9 @@ export class SessionManager {
      */
     noteClosure(reason, at, page) {
         this.#recentClosures.push({ at, reason, ...(page === undefined ? {} : { page }) });
-        if (this.#recentClosures.length > MAX_REMEMBERED_CLOSURES)
+        if (this.#recentClosures.length > MAX_REMEMBERED_CLOSURES) {
             this.#recentClosures.shift();
+        }
         this.#connectedSinceLastClosure = false;
     }
     /** The most recent bridge-initiated close, if any. */
@@ -443,8 +452,9 @@ export class SessionManager {
      */
     lastKnown() {
         let last;
-        for (const record of this.#tombstones.values())
+        for (const record of this.#tombstones.values()) {
             last = record;
+        }
         return last;
     }
     /**
@@ -456,8 +466,9 @@ export class SessionManager {
     lastKnownFor(projectId) {
         let last;
         for (const record of this.#tombstones.values()) {
-            if (record.projectId === projectId)
+            if (record.projectId === projectId) {
                 last = record;
+            }
         }
         return last;
     }
@@ -496,9 +507,10 @@ export class SessionManager {
         const ended = sessionId.startsWith(LEASE_ID_PREFIX)
             ? ` Lease '${sessionId}' has ended (it expired or was released); lease a new tab to go on.`
             : '';
-        if (0 === own.length)
+        if (0 === own.length) {
             return (`no connected session with id '${sessionId}'.${ended} ` +
                 'Omit sessionId to let Reticle scope to your project, or lease a tab of your own.');
+        }
         const named = own.map((s) => `'${s.id}' (${s.url})`).join(', ');
         return (`no connected session with id '${sessionId}'.${ended} Your app's tabs: ${named}. ` +
             'Retry with one of those, or omit sessionId entirely and let Reticle scope to your project.');
@@ -528,7 +540,7 @@ export class SessionManager {
             // diagnosis is computed HERE and the refusal is classified from the message downstream, so
             // without this every no-session refusal lands in one undifferentiated bucket (#615).
             notePendingNoSessionReason(this.#noSessionReason?.());
-            throw new Error(`${hint ?? NO_SESSION_CONNECTED_ERROR}${refusal}`);
+            throw new Error(`${hint ?? NO_SESSION_CONNECTED_ERROR}${refusal}${NO_SESSION_NAVIGATE_FIX}`);
         }
         // Scope to the agent's active project FIRST, so a stray tab from another app/origin (e.g. a
         // leftover dashboard on a different port) is structurally unselectable — it never enters the
@@ -541,8 +553,9 @@ export class SessionManager {
         const byCheckout = this.#checkoutScope === undefined
             ? { sessions: inProject }
             : scopeToCallerCheckout(inProject, this.#checkoutScope.caller(), this.#checkoutScope.ofTab);
-        if (byCheckout.refusal !== undefined)
+        if (byCheckout.refusal !== undefined) {
             throw new Error(byCheckout.refusal);
+        }
         const all = byCheckout.sessions;
         if (0 === all.length) {
             // Sessions exist, but none belong to the scoped project — never fall back to a foreign tab.
@@ -553,8 +566,9 @@ export class SessionManager {
         }
         if (1 === all.length) {
             const [only] = all;
-            if (only === undefined)
+            if (only === undefined) {
                 throw new Error('session lookup failed');
+            }
             only.markAgentActivity();
             return only;
         }
@@ -601,8 +615,9 @@ export class SessionManager {
         // Sort candidates by recency (ascending lastSeenMs = most recently active first).
         candidates.sort((a, b) => a.ms - b.ms);
         const [best, runnerUp] = candidates;
-        if (best === undefined)
+        if (best === undefined) {
             throw new Error('session lookup failed');
+        }
         // Only auto-select if there is a clear winner.
         //
         // When at least one non-throttled (focused/visible) session exists, require a >1 s recency
@@ -649,18 +664,21 @@ export class SessionManager {
  * dropped. A tab whose checkout cannot be read stays, because it can be the agent's own.
  */
 export function scopeToCallerCheckout(sessions, caller, checkoutOfTab) {
-    if (caller === undefined)
+    if (caller === undefined) {
         return { sessions: [...sessions] };
+    }
     const placed = sessions.map((session) => ({ session, checkout: checkoutOfTab(session) }));
     const mine = placed.filter((p) => isSame(p.checkout?.root, caller.root)).map((p) => p.session);
-    if (mine.length > 0)
+    if (mine.length > 0) {
         return { sessions: mine };
+    }
     const siblings = placed.filter((p) => isSame(p.checkout?.commonDir, caller.commonDir));
     if (siblings.length !== placed.length) {
         return { sessions: placed.filter((p) => !siblings.includes(p)).map((p) => p.session) };
     }
-    if (0 === siblings.length)
+    if (0 === siblings.length) {
         return { sessions: [] };
+    }
     const listed = siblings
         .map((p) => `${describeCheckout(p.checkout)} (sessionId '${p.session.id}', ${p.session.url})`)
         .join(', ');
@@ -675,8 +693,9 @@ export function scopeToCallerCheckout(sessions, caller, checkoutOfTab) {
 const isSame = (a, b) => a !== undefined && samePath(a, b);
 /** `/wt/a (branch feat/a)`, or the folder alone on a detached HEAD. */
 export function describeCheckout(checkout) {
-    if (checkout === undefined)
+    if (checkout === undefined) {
         return 'an unknown folder';
+    }
     return checkout.branch === undefined
         ? checkout.root
         : `${checkout.root} (branch ${checkout.branch})`;

package/dist/portal/session/session.js

@@ -1,6 +1,7 @@
 import { noteOwnReload, notePageLoaded } from '../../features/harness/drive-runs.js';
 import { asProjectId } from '@reticlehq/core';
 import { narrationArgs } from './narration-args.js';
+import { sdkBehindNote } from '../../command/version/version-skew.js';
 import { refusedResult } from './page-commands/undeclared-command.js';
 import { impactSnapshot, recordImpact } from '../../memory/impact/impact-recorder.js';
 import { callingAgent } from '../../hooks/coding-agents.js';
@@ -580,9 +581,9 @@ export class Session {
             this.recordActedRef(ref);
         if (name === ReticleCommand.REFRESH)
             noteOwnReload(this.id, this.#clock());
-        // Refused before it is sent, when the page said it does not serve this. The rule, and why
-        // an absent declaration is not an empty list, live in `undeclared-command.ts`.
-        const refused = refusedResult(name, this.commands, `${COMMAND_ID_PREFIX}refused`);
+        // Refused before it is sent when the page did not declare it. See `undeclared-command.ts`.
+        const behind = sdkBehindNote(this.sdkVersion);
+        const refused = refusedResult(name, this.commands, `${COMMAND_ID_PREFIX}refused`, behind);
         if (refused !== undefined)
             return Promise.resolve(refused);
         // The page already re-dialled under this same id. Nothing has been sent yet, so handing the

package/dist/portal/session/zero-install-first-call.d.ts

@@ -22,10 +22,28 @@ export declare function within(child: string | undefined, parent: string): boole
 export declare function projectAppUrlFinder(io: Pick<FirstCallIo, 'project' | 'serving' | 'servingDirectory'>): () => Promise<string | undefined>;
 /** One lease per project for the daemon's life: a failure is reported once, never retried. */
 export declare function firstCallOpener(io: FirstCallIo): () => Promise<FirstCallOpened | undefined>;
+/**
+ * The first-session offer, on the first tool call of each agent connection.
+ *
+ * The plugin's SessionStart hook says it when a session starts. A plugin installed in an open
+ * session and loaded with `/reload-plugins` fires no SessionStart, so the server says it too. Only
+ * the first call of a connection looks: an offer on a later call reads as noise.
+ */
+export interface FirstSessionOfferIo {
+    /** The unwired web app this call is about; undefined when wired, not a web app, or no project. */
+    project: () => string | undefined;
+    /** Whether an app is attached now. */
+    connected: () => boolean;
+    /** Called once for each offer that goes out, with its project. */
+    offered: (dir: string) => void;
+}
+/** The offer for this connection's first call, or undefined. Each attach id gets one look. */
+export declare function firstSessionOfferGate(io: FirstSessionOfferIo): (attachId: string) => string | undefined;
 /**
  * The daemon's two answers to an app nobody wired, built together because both ask the same
  * question first — which unwired web app is this caller in. `firstRun` names it when the agent
- * lists sessions; `openUnwiredApp` opens it zero-install on a page-needing call.
+ * lists sessions; `openUnwiredApp` opens it zero-install on a page-needing call;
+ * `firstSessionOffer` says the offer on the first call of each agent connection.
  */
 export declare function agentWiring(sessions: {
     list(): readonly unknown[];
@@ -33,4 +51,5 @@ export declare function agentWiring(sessions: {
     firstRun: FirstRunWiring;
     openUnwiredApp: () => Promise<FirstCallOpened | undefined>;
     projectAppUrl: () => Promise<string | undefined>;
+    firstSessionOffer: (attachId: string) => string | undefined;
 };

package/dist/portal/session/zero-install-first-call.js

@@ -21,8 +21,11 @@ import { DEV_SERVER_PORTS } from '../../command/cli/ports/resolve/cli-port.js';
 import { callingClientDirectory } from '../../hooks/client-directory.js';
 import { detectDevCommandInProject, initCommandIn } from './dev-server/dev-command.js';
 import { probeDevServerStates } from './dev-server/dev-server-probe.js';
+import { NextStepOffered } from '@reticlehq/core';
+import { readProjectId } from '../../command/cli/ports/resolve/cli-port.js';
+import { noteNextStepOffered } from '../../telemetry/onboarding-firsts.js';
 import { firstRunWiring } from './first-run-wiring.js';
-import { wiringConsent } from './no-session-next-action.js';
+import { firstSessionOffer, wiringConsent } from './no-session-next-action.js';
 import { servingDirectoryOf } from './serving-directory.js';
 const LOCALHOST = 'http://localhost';
 /** The path with symlinks resolved when it exists (lsof reports `/private/tmp`, callers `/tmp`). */
@@ -87,10 +90,32 @@ export function firstCallOpener(io) {
         return { url, notice: openedNotice(url, initCommandIn(dir)) };
     };
 }
+/** The offer for this connection's first call, or undefined. Each attach id gets one look. */
+export function firstSessionOfferGate(io) {
+    // ponytail: one short id per MCP connection for the daemon's life; bound it if a daemon ever
+    // serves connections by the million.
+    const looked = new Set();
+    return (attachId) => {
+        if (looked.has(attachId)) {
+            return undefined;
+        }
+        looked.add(attachId);
+        if (io.connected()) {
+            return undefined;
+        }
+        const dir = io.project();
+        if (dir === undefined) {
+            return undefined;
+        }
+        io.offered(dir);
+        return firstSessionOffer(initCommandIn(dir));
+    };
+}
 /**
  * The daemon's two answers to an app nobody wired, built together because both ask the same
  * question first — which unwired web app is this caller in. `firstRun` names it when the agent
- * lists sessions; `openUnwiredApp` opens it zero-install on a page-needing call.
+ * lists sessions; `openUnwiredApp` opens it zero-install on a page-needing call;
+ * `firstSessionOffer` says the offer on the first call of each agent connection.
  */
 export function agentWiring(sessions, lease) {
     const firstRun = firstRunWiring();
@@ -107,5 +132,12 @@ export function agentWiring(sessions, lease) {
         firstRun,
         openUnwiredApp: firstCallOpener(io),
         projectAppUrl: projectAppUrlFinder({ ...io, project: callerFolder }),
+        firstSessionOffer: firstSessionOfferGate({
+            ...io,
+            // The offer leads with the lease, so it is counted as a lease offer.
+            offered: (dir) => {
+                noteNextStepOffered(NextStepOffered.LEASE, () => readProjectId(dir) !== undefined);
+            },
+        }),
     };
 }