@reticlehq/server 3.7.0 → 3.8.1

package/dist/portal/session/serving-directory.js

@@ -8,14 +8,55 @@
  * which `memory/project` has no business knowing. The resolver takes the answer as an injected
  * function; the composition roots pass this one.
  */
-import { isLoopbackHostname } from '@reticlehq/core';
+import { isLocalhostSubdomain, isLoopbackHostname, } from '@reticlehq/core';
+import { readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { z } from 'zod';
 import { captureLookup, findListenerCwd } from '../../command/cli/ports/port-holder.js';
 import { reticleStateHome } from '../../command/daemon/daemon.js';
 import { readDevServers } from '../../command/daemon/dev-servers.js';
+import { checkoutAt, hasLinkedWorktrees } from '../../command/cli/config/checkout.js';
+import { callingClientDirectory } from '../../hooks/client-directory.js';
+import { originOf } from './session-manager.js';
 const DEFAULT_PORT = { 'http:': 80, 'https:': 443 };
+/** portless keeps its route table here: `$PORTLESS_STATE_DIR`, else `~/.portless`. */
+const PORTLESS_STATE_DIR_ENV = 'PORTLESS_STATE_DIR';
+const PORTLESS_STATE_DIR = '.portless';
+const PORTLESS_ROUTES_FILE = 'routes.json';
+const PORTLESS_PORT_FILE = 'proxy.port';
+const PortlessRoutesSchema = z.array(z.object({ hostname: z.string(), port: z.number().int() }).passthrough());
+/** A file's text, or undefined when it cannot be read. */
+function readOrUndefined(path) {
+    try {
+        return readFileSync(path, 'utf8');
+    }
+    catch {
+        // Missing or unreadable: not there for this purpose.
+        return undefined;
+    }
+}
+/** The portless proxy on this machine, read from its state folder. Undefined when none runs. */
+function readPortless() {
+    const dir = process.env[PORTLESS_STATE_DIR_ENV] ?? join(homedir(), PORTLESS_STATE_DIR);
+    const port = Number(readOrUndefined(join(dir, PORTLESS_PORT_FILE))?.trim());
+    if (!Number.isInteger(port))
+        return undefined;
+    let routes = [];
+    try {
+        const parsed = PortlessRoutesSchema.safeParse(JSON.parse(readOrUndefined(join(dir, PORTLESS_ROUTES_FILE)) ?? '[]'));
+        if (parsed.success)
+            routes = parsed.data;
+    }
+    catch {
+        // A table being rewritten reads as empty: the page stays unplaced, never placed wrong.
+    }
+    return { ports: [port], routes };
+}
 const liveIo = {
     devServers: () => readDevServers(reticleStateHome()),
     listenerCwd: (port) => findListenerCwd(port, captureLookup),
+    devProxy: readPortless,
 };
 /**
  * The directory of the dev server that served `origin`, or undefined when it cannot be observed.
@@ -23,7 +64,8 @@ const liveIo = {
  * Two observations, exact one first. A dev server whose plugin announced this port names its own
  * root and works on every platform. Otherwise the process listening on the port is asked for its
  * working directory, which covers frameworks with no announcing plugin (Next.js) wherever `lsof`
- * runs. Loopback only: a remote page's port says nothing about any process on this machine.
+ * runs. Behind a dev proxy, the proxy's route table first names the dev server's own port. Loopback
+ * only: a remote page's port says nothing about any process on this machine.
  */
 export function servingDirectoryOf(origin, io = liveIo) {
     let url;
@@ -33,13 +75,59 @@ export function servingDirectoryOf(origin, io = liveIo) {
     catch {
         return undefined;
     }
-    if (!isLoopbackHostname(url.hostname))
+    if (!isLoopbackHostname(url.hostname) && !isLocalhostSubdomain(url.hostname))
         return undefined;
-    const port = '' === url.port ? DEFAULT_PORT[url.protocol] : Number(url.port);
-    if (port === undefined)
+    // Exact first: a dev proxy serves every worktree on one port, under the name it announced.
+    const byUrl = io.devServers().find((entry) => originOf(entry.url) === url.origin);
+    if (byUrl !== undefined)
+        return byUrl.root;
+    const pagePort = '' === url.port ? DEFAULT_PORT[url.protocol] : Number(url.port);
+    if (pagePort === undefined)
         return undefined;
+    // Behind a dev proxy the page's port is the proxy's, and `lsof` on it names the proxy's folder.
+    // The proxy's route table names the dev server's own port.
+    const proxy = isLocalhostSubdomain(url.hostname) ? io.devProxy?.() : undefined;
+    const route = proxy?.routes.find((r) => r.hostname === url.hostname.toLowerCase());
+    if (route === undefined && true === proxy?.ports.includes(pagePort))
+        return undefined;
+    const port = route?.port ?? pagePort;
     const announced = io.devServers().find((entry) => entry.port === port);
     if (announced !== undefined)
         return announced.root;
     return io.listenerCwd(port) ?? undefined;
 }
+/** The checkout whose dev server serves `origin` right now, or undefined. */
+function checkoutServing(origin) {
+    const serving = servingDirectoryOf(origin);
+    return serving === undefined ? undefined : checkoutAt(serving);
+}
+/**
+ * The live answers for a worktree-scoped resolve: the calling agent's checkout (from the directory
+ * its MCP proxy runs in) and each tab's checkout (from the dev server that served it).
+ *
+ * A tab is placed once for each connection. A page that a different dev server serves has reloaded,
+ * and a reload is a new connection. A cache by origin and time named a port that moved to another
+ * worktree after the old one for its whole lifetime.
+ * ponytail: a lookup that failed stays failed for that connection; the tab then counts as unknown.
+ */
+export function liveCheckoutSource(placeOrigin = checkoutServing) {
+    const placed = new WeakMap();
+    return {
+        caller: () => {
+            const dir = callingClientDirectory();
+            const checkout = dir === undefined ? undefined : checkoutAt(dir);
+            // A repository with no linked worktree has nothing to tell apart: skip the serving lookups.
+            return checkout !== undefined && hasLinkedWorktrees(checkout.commonDir)
+                ? checkout
+                : undefined;
+        },
+        ofTab: (tab) => {
+            if (placed.has(tab))
+                return placed.get(tab);
+            const origin = originOf(tab.url);
+            const checkout = origin === undefined ? undefined : placeOrigin(origin);
+            placed.set(tab, checkout);
+            return checkout;
+        },
+    };
+}

package/dist/portal/session/session-info.d.ts

@@ -6,6 +6,11 @@ export interface SessionInfo {
     url: string;
     /** Stable build-stamped project identity; absent for v1.0 SDKs that don't send it. */
     projectId?: string;
+    /**
+     * The linked git worktree whose dev server served this tab, with its branch. Present only when the
+     * daemon can tell, and only for a worktree, not the main checkout.
+     */
+    worktree?: string;
     /** Absent when the page has no title — never the empty string. Fall back to `url`. */
     title?: string;
     adapters: string[];
@@ -19,12 +24,24 @@ export interface SessionInfo {
      * not render like it.
      */
     runtime?: string;
+    /**
+     * `injected` when a hosted verifier put the SDK in this page from outside. Absent means the app
+     * installed it. A reader must not count an injected session as the app having the SDK.
+     */
+    instrumentation?: string;
     /** The desktop window's own name (Tauri's label: `main`, `setup`) — absent on a web page. */
     window?: string;
     /** Present only when the document was served as an error (4xx/5xx): a 404 page is not the app. */
     documentStatus?: number;
     /** Present only when the page's SDK version differs from the daemon's — see version-skew.ts. */
     versionSkew?: string;
+    /** The page's SDK version, when the page said. */
+    sdkVersion?: string;
+    /**
+     * Present only when the page SDK is a minor release or more behind the daemon. The page still
+     * connects, but the commands and fixes added since are not in it. Says how to update it.
+     */
+    sdkBehind?: string;
     /** ms since the SDK last reported anything (silence ⇒ likely throttled). */
     lastSeenMs: number;
     hidden: boolean;
@@ -76,7 +93,9 @@ interface SessionView {
     adapters: string[];
     hasCapabilities: boolean;
     runtime: string | undefined;
+    instrumentation?: string | undefined;
     versionSkew: string | undefined;
+    sdkVersion?: string | undefined;
     hidden: boolean;
     page?: PageIdentity;
     health: () => SessionHealth;
@@ -84,6 +103,13 @@ interface SessionView {
     pendingMarkCount: () => number;
     unresponsive: () => boolean;
 }
+/**
+ * The note for a page whose SDK is behind the daemon, or undefined. One sentence for the listing
+ * and for each verdict on that page, so the two never disagree.
+ */
+export declare function sdkBehindNote(session: {
+    readonly sdkVersion?: string | undefined;
+}): string | undefined;
 /**
  * Project a live Session into the shape the tools return.
  *

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

@@ -6,10 +6,26 @@
  * it, and separating them keeps the wire-facing shape reviewable on its own.
  */
 import { SESSION_LEASE } from '@reticlehq/core';
+import { SERVER_VERSION } from '../../command/version/identity/server-version.js';
+import { SDK_BEHIND_NARRATION, sdkIsBehind } from '../../command/version/version-skew.js';
 /** A document served as 4xx/5xx — a dev server's 404 page that still mounted the SDK, say. */
 export function isErrorDocument(page) {
     return (page?.documentStatus ?? 0) >= 400;
 }
+/**
+ * The note for a page whose SDK is behind the daemon, or undefined. One sentence for the listing
+ * and for each verdict on that page, so the two never disagree.
+ */
+export function sdkBehindNote(session) {
+    const sdk = session.sdkVersion;
+    return sdk !== undefined && sdkIsBehind(sdk, SERVER_VERSION)
+        ? SDK_BEHIND_NARRATION(sdk, SERVER_VERSION)
+        : undefined;
+}
+function sdkBehindField(session) {
+    const note = sdkBehindNote(session);
+    return note === undefined ? {} : { sdkBehind: note };
+}
 /**
  * Project a live Session into the shape the tools return.
  *
@@ -31,10 +47,14 @@ export function buildSessionInfo(session) {
         hasCapabilities: session.hasCapabilities,
         // Omitted when the page never said, so absence stays readable as "unknown" rather than "web".
         ...(session.runtime === undefined ? {} : { runtime: session.runtime }),
+        // Said only when injected: an installed SDK is the default every older page meant.
+        ...(session.instrumentation === undefined ? {} : { instrumentation: session.instrumentation }),
         ...(session.page?.windowLabel === undefined ? {} : { window: session.page.windowLabel }),
         ...(isErrorDocument(session.page) ? { documentStatus: session.page?.documentStatus ?? 0 } : {}),
         // On every listing, not buried in a log — skew explains failures that read as app bugs.
         ...(session.versionSkew === undefined ? {} : { versionSkew: session.versionSkew }),
+        ...(session.sdkVersion === undefined ? {} : { sdkVersion: session.sdkVersion }),
+        ...sdkBehindField(session),
         hidden: session.hidden,
         ...session.health(),
     };

package/dist/portal/session/session-manager.d.ts

@@ -1,8 +1,16 @@
+import { originOf, type Checkout } from '@reticlehq/core';
 import type { NoSessionReason } from '@reticlehq/core/telemetry';
 import { Session, type SessionInfo } from './session.js';
 import { AttachmentHistory } from './presence/attachment-history.js';
 import type { NoSessionNextAction } from './no-session-next-action.js';
 import { type SessionIdentity } from './session-successor.js';
+/** The two checkout facts a worktree-scoped resolve needs. */
+export interface CheckoutSource {
+    /** The git checkout of the agent making this call. */
+    caller: () => Checkout | undefined;
+    /** The git checkout whose dev server served this tab connection. */
+    ofTab: (tab: Tab) => Checkout | undefined;
+}
 /**
  * The agent's active project, used to scope auto-selection. `projectId` is the stable build-stamped
  * identity (authoritative when present); `url` is the app origin, a fallback hint for older SDKs that
@@ -12,8 +20,8 @@ interface ResolveScope {
     projectId?: string;
     url?: string;
 }
-/** The scheme://host:port of a URL, or undefined if it can't be parsed. Used to compare origins. */
-export declare function originOf(url: string | undefined): string | undefined;
+/** Core's `originOf`, re-exported for this module's existing importers. */
+export { originOf };
 /**
  * Honest, scoped error when sessions exist but none match the agent's project.
  *
@@ -40,6 +48,8 @@ export declare class SessionManager {
     #private;
     /** Set the active project's default resolve scope (called once at daemon wiring). */
     setDefaultScope(scope: ResolveScope | undefined): void;
+    /** Scope id-less calls to the calling agent's own git worktree (called once at daemon wiring). */
+    setCheckoutScope(scope: CheckoutSource | undefined): void;
     setConnectionRecorder(record: ((projectId: string | undefined) => void) | undefined): void;
     add(session: Session): Session | undefined;
     /**
@@ -140,4 +150,26 @@ export declare class SessionManager {
     tombstoneUrls(): readonly string[];
     resolve(sessionId?: string, scope?: ResolveScope): Session;
 }
-export {};
+export interface Tab {
+    id: string;
+    url: string;
+}
+export interface CheckoutScope<S> {
+    sessions: S[];
+    /** Set when every tab is known to be served from another worktree of the agent's repository. */
+    refusal?: string;
+}
+/**
+ * Which of a project's tabs belong to the agent's own git checkout.
+ *
+ * Every worktree of a project declares the same projectId, so the project scope lets an agent in
+ * worktree A land on the tab worktree B serves. That tab runs B's code, and a verdict on it is about
+ * code agent A never touched. The agent's checkout comes from the directory its MCP proxy runs in;
+ * a tab's checkout comes from the dev server that served it.
+ *
+ * It narrows only on facts. A tab known to come from another worktree of the agent's repository is
+ * dropped. A tab whose checkout cannot be read stays, because it can be the agent's own.
+ */
+export declare function scopeToCallerCheckout<S extends Tab>(sessions: readonly S[], caller: Checkout | undefined, checkoutOfTab: (tab: S) => Checkout | undefined): CheckoutScope<S>;
+/** `/wt/a (branch feat/a)`, or the folder alone on a detached HEAD. */
+export declare function describeCheckout(checkout: Checkout | undefined): string;

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

@@ -1,4 +1,4 @@
-import { NO_SESSION_CONNECTED_ERROR } from '@reticlehq/core';
+import { NO_SESSION_CONNECTED_ERROR, 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';
@@ -6,17 +6,8 @@ import { AttachmentHistory } from './presence/attachment-history.js';
 import { claimedSessionOf, openedBeforeDeparture, pickDocumentSuccessor, } from './session-successor.js';
 import { SESSION_DISCONNECTED_REASON, SESSION_PARKED_REASON } from './facts/session-replaced.js';
 import { isErrorDocument } from './session-info.js';
-/** The scheme://host:port of a URL, or undefined if it can't be parsed. Used to compare origins. */
-export function originOf(url) {
-    if (url === undefined)
-        return undefined;
-    try {
-        return new URL(url).origin;
-    }
-    catch {
-        return undefined;
-    }
-}
+/** Core's `originOf`, re-exported for this module's existing importers. */
+export { originOf };
 /**
  * Narrow a session list to those belonging to the scoped project. With a `projectId` the match is by
  * that stable id (origin ignored — it survives port swaps). With only a `url`, match by origin. With
@@ -114,6 +105,12 @@ export class SessionManager {
     setDefaultScope(scope) {
         this.#defaultScope = scope;
     }
+    /** Where the calling agent's checkout and each tab's checkout come from. Unset: no worktree scope. */
+    #checkoutScope;
+    /** Scope id-less calls to the calling agent's own git worktree (called once at daemon wiring). */
+    setCheckoutScope(scope) {
+        this.#checkoutScope = scope;
+    }
     /**
      * Told about every session that registers, so the fact outlives this process.
      *
@@ -246,10 +243,17 @@ export class SessionManager {
         return this.#tombstones.get(sessionId);
     }
     list() {
+        // Only an agent whose repository has worktrees pays for the serving lookups.
+        const worktreeOf = this.#checkoutScope?.caller() === undefined ? undefined : this.#checkoutScope.ofTab;
         return [...this.#sessions.values()].map((s) => {
             const info = s.info();
             const attachment = this.#attachment.of(s.id);
-            return attachment === undefined ? info : { ...info, attachment };
+            const served = worktreeOf?.(s);
+            return {
+                ...info,
+                ...(attachment === undefined ? {} : { attachment }),
+                ...(true === served?.linked ? { worktree: describeCheckout(served) } : {}),
+            };
         });
     }
     /** Continuity for one session — "has this been attached the whole time I am reasoning about?" */
@@ -532,7 +536,14 @@ export class SessionManager {
         // An explicit per-call scope wins; otherwise the daemon's active-project default applies.
         const effectiveScope = scope ?? this.#defaultScope;
         const connected = [...this.#sessions.values()];
-        const all = scopeSessions(connected, effectiveScope);
+        const inProject = scopeSessions(connected, effectiveScope);
+        // Then to the agent's own worktree: every worktree of a project declares the same projectId.
+        const byCheckout = this.#checkoutScope === undefined
+            ? { sessions: inProject }
+            : scopeToCallerCheckout(inProject, this.#checkoutScope.caller(), this.#checkoutScope.ofTab);
+        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.
             // ponytail: still a refusal, deliberately. Auto-targeting the only connected tab would be the
@@ -626,3 +637,47 @@ export class SessionManager {
         return best.s;
     }
 }
+/**
+ * Which of a project's tabs belong to the agent's own git checkout.
+ *
+ * Every worktree of a project declares the same projectId, so the project scope lets an agent in
+ * worktree A land on the tab worktree B serves. That tab runs B's code, and a verdict on it is about
+ * code agent A never touched. The agent's checkout comes from the directory its MCP proxy runs in;
+ * a tab's checkout comes from the dev server that served it.
+ *
+ * It narrows only on facts. A tab known to come from another worktree of the agent's repository is
+ * 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)
+        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)
+        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)
+        return { sessions: [] };
+    const listed = siblings
+        .map((p) => `${describeCheckout(p.checkout)} (sessionId '${p.session.id}', ${p.session.url})`)
+        .join(', ');
+    return {
+        sessions: [],
+        refusal: `every tab of this app is served from another worktree: ${listed}. This agent runs in ` +
+            `${describeCheckout(caller)}. A verdict on another worktree's tab is about code this agent ` +
+            'did not change. Start the dev server in this worktree, or pass sessionId to drive that tab ' +
+            'on purpose.',
+    };
+}
+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)
+        return 'an unknown folder';
+    return checkout.branch === undefined
+        ? checkout.root
+        : `${checkout.root} (branch ${checkout.branch})`;
+}

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

@@ -9,20 +9,12 @@
  * Unique at the departed origin (and project, when known). Two live tabs at that origin is still a
  * guess, and a guess here would drive the wrong app.
  */
-import { RETICLE_URL_PARAM } from '@reticlehq/core';
+import { RETICLE_URL_PARAM, originOf } from '@reticlehq/core';
 const POLL_MS = 25;
 const REAL_CLOCK = {
     now: () => Date.now(),
     sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
 };
-function originOf(url) {
-    try {
-        return new URL(url).origin;
-    }
-    catch {
-        return undefined;
-    }
-}
 /**
  * The session a URL explicitly CLAIMS to be, via `__reticle_session`.
  *

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

@@ -1,8 +1,15 @@
 import { z } from 'zod';
-import { HudCorner, HudVisibility, ReticleCommand } from '@reticlehq/core';
+import { HudCorner, HudVisibility, HUD_MIN_SDK_VERSION, HUD_RELOAD_TO_RESTORE, ReticleCommand, } from '@reticlehq/core';
 import { ReticleTool } from '@reticlehq/core';
 import { asNumber, asString } from '@reticlehq/core';
+import { compareVersions } from '../../command/version/version-skew.js';
 import { idleMsSchema } from '../../surface/tools/args/numeric-bounds.js';
+function sdkPredatesHud(version) {
+    if (version === undefined)
+        return true;
+    const order = compareVersions(version, HUD_MIN_SDK_VERSION);
+    return order === undefined || order < 0;
+}
 /**
  * Session lifecycle controls. The presenter session begins on the agent's first action and ends
  * either when the agent ends it (reticle_end_session) or after an idle window — and the human keeps the
@@ -22,7 +29,8 @@ export const SESSION_TOOLS = [
                 ...Object.values(HudVisibility),
                 ...Object.values(HudCorner),
             ])
-                .optional(),
+                .optional()
+                .describe('Hide, show or remove the HUD, or move it to a corner.'),
             sessionId: z
                 .string()
                 .optional()
@@ -57,8 +65,18 @@ export const SESSION_TOOLS = [
             // no HUD mounted. Reported, never `applied: true`: an agent told the HUD moved would test a
             // control it is still covering.
             const applied = res.result?.hud;
-            if ((hud !== undefined || corner !== undefined) && !Array.isArray(applied))
-                throw new Error('the page did not apply `hud`: its Reticle SDK predates it, or no HUD is mounted. Update the SDK (npx @reticlehq/server update) or test with the HUD where it is.');
+            if (hud !== undefined || corner !== undefined) {
+                if (Array.isArray(applied) && applied.includes(HUD_RELOAD_TO_RESTORE)) {
+                    throw new Error(`the HUD on session ${session.id} was removed; reload the page to restore it.`);
+                }
+                if (!Array.isArray(applied)) {
+                    if (sdkPredatesHud(session.sdkVersion)) {
+                        const versionText = session.sdkVersion !== undefined ? `page SDK ${session.sdkVersion}` : 'the page SDK';
+                        throw new Error(`${versionText} on session ${session.id} predates \`hud\` (needs ${HUD_MIN_SDK_VERSION}+). Update the SDK (npx @reticlehq/server update) or test with the HUD where it is.`);
+                    }
+                    throw new Error(`the page did not apply \`hud\`: no HUD is mounted on session ${session.id}, so no HUD covers the page. Continue without \`hud\`.`);
+                }
+            }
             return res.result ?? { applied: true };
         },
     },

package/dist/portal/session/session.d.ts

@@ -2,6 +2,7 @@ import type { WebSocket } from 'ws';
 import { type ChannelId, type ImpactSnapshot, type ProjectId } from '@reticlehq/core';
 import { type NarrationBy } from './narration-args.js';
 import type { HandshakeFacts } from './facts/handshake-facts.js';
+import type { ProductionDrive } from '../production/production-drive.js';
 import { LastAct } from './last-act.js';
 import { GapLedger } from '@reticlehq/engine/evidence/gap-ledger.js';
 import { type PageRuntime } from './timing/command-timeout.js';
@@ -31,18 +32,18 @@ export declare class Session implements HandshakeFacts {
      * MINTED HERE. This is one of the two places a projectId enters the daemon with its provenance
      * intact: the field is `projectId` on a zod-parsed HELLO, so the page said what it is. Every
      * downstream reader takes the brand from this property rather than re-blessing a string.
+     * Set once more, by `adoptProject`, when a page that said nothing names its project later.
      */
-    readonly projectId: ProjectId | undefined;
+    projectId: ProjectId | undefined;
+    /** Take a later HELLO's project id when the first carried none. A set project is kept. */
+    adoptProject(projectId: string): boolean;
     /**
      * The `.reticle` directory this session's evidence belongs in — impact counters AND capsules.
      * Stamped once, from the project it declared in HELLO, so every counter agrees where it goes.
      * Undefined when nothing could name a project: callers fall back to the daemon's own root.
      */
     artifactRoot: string | undefined;
-    /**
-     * Same-origin endpoints this session's project declared as background (`.reticle.json`
-     * `background`). Stamped with `artifactRoot`, from the same project. Empty excludes nothing.
-     */
+    /** Same-origin `background` endpoints of this session's project, stamped with `artifactRoot`. */
     background: readonly string[];
     url: string;
     title: string;
@@ -54,11 +55,14 @@ export declare class Session implements HandshakeFacts {
     channels?: readonly ChannelId[] | undefined;
     commands?: readonly string[] | undefined;
     sourceMapping?: boolean | undefined;
+    instrumentation?: HandshakeFacts['instrumentation'];
     readonly redactKeys: readonly string[];
     /** The desktop window this is and its document's HTTP status, merged from every PAGE_HEALTH. */
     readonly page: ReturnType<typeof readHealthEvent>['page'];
     /** The newest journal action: a verdict's screenshot names it, so the run pairs it with its check. */
     lastActionId: string | undefined;
+    /** Set when a production nonce opened this session: every act then passes the production policy. */
+    production: ProductionDrive | undefined;
     constructor(hello: HelloMessage, socket: WebSocket, clock: Clock);
     /** Milliseconds since this session connected — the authoritative buffer clock. */
     elapsed(): number;
@@ -267,11 +271,7 @@ export declare class Session implements HandshakeFacts {
     pushView(name: typeof ReticleCommand.FLOW_PROGRESS | typeof ReticleCommand.PLAN, args: object): void;
     /** The one-time lease block on the first agent command, then undefined forever after. */
     takeSessionLease(): SessionLease | undefined;
-    /**
-     * Returns a human-readable age warning after SESSION_LEASE.WARN_AFTER_MS (10 min), else undefined.
-     * Spliced onto every session-bound tool result so the agent is passively reminded to clean up
-     * without needing an explicit polling loop.
-     */
+    /** The age reminder spliced onto session-bound results, so the agent cleans up without polling. */
     ageWarning(): string | undefined;
     /** Wired by SessionManager.add, the one place every session registers. */
     setViewers(read: () => Session[]): void;