@reticlehq/server 2.12.0 → 2.13.0

package/dist/telemetry/install-source.d.ts

@@ -54,3 +54,17 @@ export declare function declaredInstallSource(env?: NodeJS.ProcessEnv): InstallS
  * data, and a hand-edited one must not be able to put an arbitrary string on the wire.
  */
 export declare function projectInstallSource(cwd: string, env?: NodeJS.ProcessEnv): InstallSource;
+/**
+ * The same config with `installSource` added, or `undefined` when there is nothing to add.
+ *
+ * `installSource` is written only when `.reticle.json` is CREATED, and `init` reports that file as
+ * `already exists` on every re-run — so everyone who was already here when the marker shipped, and
+ * everyone who ran `init` once without one, keeps `unknown` forever with no way to fix it. That is
+ * most of the population the field exists to describe.
+ *
+ * An EXISTING value is never overwritten. The first channel is the one that brought the user in, and
+ * a later `init` through a different route must not take credit for an acquisition it did not make.
+ * Anything unparseable is left exactly as it is: a config is user data, and `init` rewriting a file
+ * it could not read would be a far worse failure than a missing dimension.
+ */
+export declare function configWithInstallSource(source: string | null | undefined, declared: string | undefined): string | undefined;

package/dist/telemetry/install-source.js

@@ -72,3 +72,33 @@ export function projectInstallSource(cwd, env = process.env) {
     }
     return resolveInstallSource(env);
 }
+/**
+ * The same config with `installSource` added, or `undefined` when there is nothing to add.
+ *
+ * `installSource` is written only when `.reticle.json` is CREATED, and `init` reports that file as
+ * `already exists` on every re-run — so everyone who was already here when the marker shipped, and
+ * everyone who ran `init` once without one, keeps `unknown` forever with no way to fix it. That is
+ * most of the population the field exists to describe.
+ *
+ * An EXISTING value is never overwritten. The first channel is the one that brought the user in, and
+ * a later `init` through a different route must not take credit for an acquisition it did not make.
+ * Anything unparseable is left exactly as it is: a config is user data, and `init` rewriting a file
+ * it could not read would be a far worse failure than a missing dimension.
+ */
+export function configWithInstallSource(source, declared) {
+    if (undefined === declared || null === source || undefined === source)
+        return undefined;
+    let parsed;
+    try {
+        parsed = JSON.parse(source);
+    }
+    catch {
+        return undefined;
+    }
+    if (null === parsed || 'object' !== typeof parsed || Array.isArray(parsed))
+        return undefined;
+    const fields = parsed;
+    if (undefined !== fields['installSource'])
+        return undefined;
+    return `${JSON.stringify({ ...fields, installSource: declared }, null, 2)}\n`;
+}

package/dist/telemetry/license-activation.d.ts

@@ -30,6 +30,12 @@ import { LicenseActivation } from '@reticlehq/core';
 export interface LicenseFacts {
     licenseId?: string;
     licenseStatus?: LicenseActivation;
+    /**
+     * A key was placed, whether or not this build could judge it. See LICENSE_KEY_PRESENT in core.
+     * Reported even in evaluation mode, which is the whole point: that is the case where every other
+     * licence property is deliberately silent.
+     */
+    licenseKeyPresent?: boolean;
 }
 /**
  * Resolve activation for one event. The clock is passed in (rule 7) and is the EVENT's clock, not a
@@ -45,4 +51,4 @@ export interface LicenseFacts {
  * Never throws. A telemetry property may not change behaviour (rule 5), and this one sits in front of
  * key parsing, which is the part most likely to be handed something malformed.
  */
-export declare function licenseFacts(now: number, env?: NodeJS.ProcessEnv): LicenseFacts;
+export declare function licenseFacts(now: number, env?: NodeJS.ProcessEnv, baked?: string): LicenseFacts;

package/dist/telemetry/license-activation.js

@@ -26,7 +26,7 @@
  * holds a customer list.
  */
 import { LicenseActivation } from '@reticlehq/core';
-import { describeLicense } from '../license/license.js';
+import { describeLicense, LICENSE_KEY_ENV } from '../license/license.js';
 /**
  * Resolve activation for one event. The clock is passed in (rule 7) and is the EVENT's clock, not a
  * value captured at startup: sessions here run to eleven hours, so a key that expires mid-session must
@@ -41,13 +41,17 @@ import { describeLicense } from '../license/license.js';
  * Never throws. A telemetry property may not change behaviour (rule 5), and this one sits in front of
  * key parsing, which is the part most likely to be handed something malformed.
  */
-export function licenseFacts(now, env = process.env) {
+export function licenseFacts(now, env = process.env, baked) {
     try {
-        const report = describeLicense(now, env);
-        if (LicenseActivation.EVAL === report.status)
-            return {};
+        const report = baked === undefined ? describeLicense(now, env) : describeLicense(now, env, baked);
+        // Asked BEFORE the eval short-circuit, because eval is exactly the case that used to be silent.
+        const keyPresent = (env[LICENSE_KEY_ENV] ?? '').length > 0;
+        if (LicenseActivation.EVAL === report.status) {
+            return keyPresent ? { licenseKeyPresent: true } : {};
+        }
         return {
             licenseStatus: report.status,
+            ...(keyPresent ? { licenseKeyPresent: true } : {}),
             ...(report.licenseId !== undefined ? { licenseId: report.licenseId } : {}),
         };
     }

package/dist/telemetry/mcp-connection.js

@@ -11,6 +11,7 @@
  */
 import { TelemetryEventKind } from '@reticlehq/core';
 import { getTelemetry } from './telemetry.js';
+import { appEverConnected } from './app-instrumented.js';
 let connectsSeen = 0;
 /** Set when the daemon starts, so the FIRST connect can report how long Reticle sat unused. */
 let daemonStartedAt;
@@ -30,6 +31,12 @@ export function reportMcpConnected(client, now = () => Date.now()) {
                 // sat there. On a reconnect it is just how long the daemon has been up.
                 daemonAgeMs: daemonStartedAt === undefined ? 0 : Math.max(0, now() - daemonStartedAt),
                 ...(client !== undefined ? { client } : {}),
+                // WHAT THE AGENT HAD TO LOOK AT. Most clients that attach never call a tool, and that cohort
+                // emits nothing at all — an agent that reads the instructions, learns nothing is wired and
+                // stops has refused nothing, so `tool_refused` cannot see it either. Read off the same flag
+                // `app_instrumented` sets, never a second counter, so the two halves of the funnel cannot
+                // disagree about one daemon run.
+                appConnected: appEverConnected(),
             },
         });
     }

package/dist/telemetry/project-profile.d.ts

@@ -32,5 +32,16 @@ type FileReader = (path: string) => string;
  * Build the full profile. Best-effort throughout: an unreadable project yields a profile of zeroes
  * rather than an exception, because a telemetry snapshot must never be able to fail a daemon start.
  */
-export declare function profileProject(cwd: string, now: number): ProjectProfile;
+/**
+ * Facts about the install that the filesystem cannot answer.
+ *
+ * Passed in rather than read here for the same reason `previouslyConnected` is passed to the MCP
+ * server: it needs the daemon's port and the state home, and a profile that reached for those would
+ * stop being a pure function of a directory.
+ */
+export interface InstallFacts {
+    /** Has an app for this project EVER connected to Reticle, from durable state. */
+    appConnectedBefore: boolean;
+}
+export declare function profileProject(cwd: string, now: number, install?: InstallFacts): ProjectProfile;
 export {};

package/dist/telemetry/project-profile.js

@@ -15,6 +15,7 @@ import { join } from 'node:path';
 import { ProjectSize, ReticleDir } from '@reticlehq/core';
 import { gitFacts } from './git-facts.js';
 import { detectStack } from './feedback-context.js';
+import { readProjectId } from '../cli/cli-port.js';
 /**
  * The feature FAMILIES, and the on-disk evidence that a project has adopted each. Named rather than
  * counted so the vocabulary stays stable as tools are added, renamed, or merged into action-dispatched
@@ -151,11 +152,7 @@ function exists(path) {
         return false;
     }
 }
-/**
- * Build the full profile. Best-effort throughout: an unreadable project yields a profile of zeroes
- * rather than an exception, because a telemetry snapshot must never be able to fail a daemon start.
- */
-export function profileProject(cwd, now) {
+export function profileProject(cwd, now, install) {
     const reticleRoot = join(cwd, ReticleDir.ROOT);
     const flowCount = countIn(reticleRoot, ReticleDir.FLOWS_SUBDIR, /\.json$/);
     const baselineCount = countIn(reticleRoot, ReticleDir.BASELINES_SUBDIR);
@@ -180,7 +177,7 @@ export function profileProject(cwd, now) {
         featuresUsed.push(FeatureFamily.BUG_CAPSULES);
     if (hasHistory)
         featuresUsed.push(FeatureFamily.CROSS_RUN_HISTORY);
-    const { stack, stackMajor, stackSource } = detectStack(cwd);
+    const { stack, stackMajor, stackSource, stackUnknownReason } = detectStack(cwd);
     const ageWeeks = projectAgeWeeks(cwd, now);
     const git = gitFacts(cwd);
     return {
@@ -189,6 +186,8 @@ export function profileProject(cwd, now) {
         ...(stack !== undefined ? { stack } : {}),
         ...(stackSource !== undefined ? { stackSource } : {}),
         ...(stackMajor !== undefined ? { stackMajor } : {}),
+        // Present only when `stack` is absent, so the field's presence marks the unknown bucket.
+        ...(stackUnknownReason !== undefined ? { stackUnknownReason } : {}),
         size: sizeBucket(countSourceFiles(cwd)),
         monorepo: isMonorepo(cwd),
         ...(ageWeeks !== undefined ? { ageWeeks } : {}),
@@ -202,5 +201,11 @@ export function profileProject(cwd, now) {
         // Rounded to 2dp: the exact ratio is a function of the counts above, and an unrounded float would
         // just be a higher-cardinality restatement of them.
         featureDepth: Math.round((featuresUsed.length / ALL_FAMILIES.length) * 100) / 100,
+        // WHERE the install stopped, for the daemons that never see an app. `daemon_started` minus
+        // `app_instrumented` says one happened and cannot say why; these two bits split that silence
+        // into "never ran init", "ran it and no page has ever reached us", and "works, just not up
+        // right now". See the fields on ProjectProfileSchema.
+        initialized: readProjectId(cwd) !== undefined,
+        ...(install === undefined ? {} : { appConnectedBefore: install.appConnectedBefore }),
     };
 }

package/dist/telemetry/proxy-telemetry.d.ts

@@ -0,0 +1,3 @@
+import { type SessionMetrics } from './session-metrics.js';
+import { type Telemetry } from './telemetry.js';
+export declare function flushProxySessionMetrics(telemetry?: Telemetry, metrics?: SessionMetrics): Promise<void>;

package/dist/telemetry/proxy-telemetry.js

@@ -0,0 +1,21 @@
+/**
+ * The MCP proxy's session rollup.
+ *
+ * POST socket failures (`ENOBUFS`, `EMFILE`, `ECONNREFUSED` before any bytes were sent) happen in
+ * this process, not the daemon's. `tool_refused` never fires (the handler never ran) and
+ * `mcp_connection_lost` never fires (the SSE stream is fine). Counts live on SessionMetrics here
+ * and leave as one `session_progress` — an existing kind, omitted when nothing happened.
+ *
+ * The send is awaited. Fire-and-forget microseconds before `process.exit` is how `daemon_stopped`
+ * never arrived: the POST was killed every time and nothing threw.
+ */
+import { TelemetryEventKind } from '@reticlehq/core';
+import { getSessionMetrics } from './session-metrics.js';
+import { getTelemetry } from './telemetry.js';
+export async function flushProxySessionMetrics(telemetry = getTelemetry(), metrics = getSessionMetrics()) {
+    if (metrics.empty)
+        return;
+    await telemetry.emit(TelemetryEventKind.SESSION_PROGRESS, {
+        session: metrics.summarize(true),
+    });
+}

package/dist/telemetry/session-metrics.d.ts

@@ -65,6 +65,18 @@ export declare class SessionMetrics {
      * one inside a much larger pile. Same treatment otherwise — fingerprinted, variables stripped.
      */
     recordSdkFailure(site: string, message: string): void;
+    /**
+     * The MCP proxy could not POST a tool call because the TCP socket itself failed (`ENOBUFS`,
+     * `EMFILE`, `ECONNREFUSED` before any bytes left). The SSE stream is still up, so this is
+     * invisible to `mcp_connection_lost`, and the handler never ran, so it is invisible to
+     * `tool_refused`. Counted so a dashboard can see it without a new event kind.
+     */
+    recordPostSocketFailure(): void;
+    /**
+     * A bounded retry of an unsent POST then delivered. The pair against `recordPostSocketFailure`:
+     * the retry that quietly saved a call is a different fact from the one that never ran.
+     */
+    recordPostRetrySaved(): void;
     /** The agent's recent approach run + the call in flight — context for a crash report. */
     get trail(): {
         breadcrumb: string[];

package/dist/telemetry/session-metrics.js

@@ -123,6 +123,12 @@ export class SessionMetrics {
      * call a tool, and of the sessions that made exactly one call, most bounced on this.
      */
     #noSessionErrors = 0;
+    /** Connection-level MCP POST failures the SSE stream cannot see. See SessionSummary. */
+    #postSocketFailures = 0;
+    #lifetimePostSocketFailures = 0;
+    /** Retries of those POSTs that then delivered. */
+    #postRetriesSaved = 0;
+    #lifetimePostRetriesSaved = 0;
     /** Longest back-to-back run per tool — a retry loop, which `toolCounts` cannot distinguish. */
     #repeatRuns = new Map();
     #lastTool;
@@ -325,6 +331,24 @@ export class SessionMetrics {
             tool: site,
         });
     }
+    /**
+     * The MCP proxy could not POST a tool call because the TCP socket itself failed (`ENOBUFS`,
+     * `EMFILE`, `ECONNREFUSED` before any bytes left). The SSE stream is still up, so this is
+     * invisible to `mcp_connection_lost`, and the handler never ran, so it is invisible to
+     * `tool_refused`. Counted so a dashboard can see it without a new event kind.
+     */
+    recordPostSocketFailure() {
+        this.#postSocketFailures += 1;
+        this.#lifetimePostSocketFailures += 1;
+    }
+    /**
+     * A bounded retry of an unsent POST then delivered. The pair against `recordPostSocketFailure`:
+     * the retry that quietly saved a call is a different fact from the one that never ran.
+     */
+    recordPostRetrySaved() {
+        this.#postRetriesSaved += 1;
+        this.#lifetimePostRetriesSaved += 1;
+    }
     /** The agent's recent approach run + the call in flight — context for a crash report. */
     get trail() {
         return { breadcrumb: [...this.#breadcrumb], inFlight: this.#inFlight };
@@ -469,12 +493,16 @@ export class SessionMetrics {
                 toolErrors: this.#lifetimeToolErrors,
                 verifications: this.#lifetimeVerifications,
                 bugsFound: this.#lifetimeBugsFound,
+                postSocketFailures: this.#lifetimePostSocketFailures,
+                postRetriesSaved: this.#lifetimePostRetriesSaved,
             }
             : {
                 toolCalls: this.#toolCalls,
                 toolErrors: this.#toolErrors,
                 verifications: this.#verifications,
                 bugsFound: this.#bugsFound,
+                postSocketFailures: this.#postSocketFailures,
+                postRetriesSaved: this.#postRetriesSaved,
             };
         return {
             durationMs: Math.max(0, this.#now() - this.#startedAt),
@@ -488,6 +516,8 @@ export class SessionMetrics {
             bugsFound: scalars.bugsFound,
             ...(this.#bugKinds.size > 0 ? { bugKinds: Object.fromEntries(this.#bugKinds) } : {}),
             ...(this.#noSessionErrors > 0 ? { noSessionErrors: this.#noSessionErrors } : {}),
+            ...(scalars.postSocketFailures > 0 ? { postSocketFailures: scalars.postSocketFailures } : {}),
+            ...(scalars.postRetriesSaved > 0 ? { postRetriesSaved: scalars.postRetriesSaved } : {}),
             ...(this.#repeatRuns.size > 0
                 ? { consecutiveRepeats: Object.fromEntries(this.#repeatRuns) }
                 : {}),
@@ -588,7 +618,9 @@ export class SessionMetrics {
             0 === this.#verifications &&
             0 === this.#toolErrors &&
             0 === this.#bugsFound &&
-            0 === this.#sdkFailures);
+            0 === this.#sdkFailures &&
+            0 === this.#postSocketFailures &&
+            0 === this.#postRetriesSaved);
     }
     /** Zero the counters after a non-final flush so the next flush reports the NEXT window, not a total. */
     reset() {
@@ -596,6 +628,8 @@ export class SessionMetrics {
         this.#toolErrors = 0;
         this.#verifications = 0;
         this.#noSessionErrors = 0;
+        this.#postSocketFailures = 0;
+        this.#postRetriesSaved = 0;
         this.#repeatRuns.clear();
         this.#lastTool = undefined;
         this.#currentRun = 0;

package/dist/telemetry/telemetry.js

@@ -9,7 +9,7 @@
  *   - it is best-effort and non-blocking: a send failure NEVER changes what the tool does.
  *
  * Events are `@reticlehq/core`'s `TelemetryEventSchema`, mapped at the wire into PostHog's capture
- * format (https://posthog.com/docs/api/capture) — PostHog is the analytics backend until Reticle Cloud
+ * format (https://posthog.com/docs/api/capture) — PostHog is the analytics backend until the hosted service
  * grows its own; a project API key is WRITE-ONLY by design, so embedding it in an OSS client is safe.
  * Everything here is wrapped so a telemetry bug can never surface to a user — a broken metric must not
  * break a verification.
@@ -76,8 +76,23 @@ export const FEEDBACK_RETRY_BACKOFF_MS = 750;
  * (`reticle version`/`gate`) ~800ms. Long-lived daemon events still send in-process: a spawn per tool
  * call would be far heavier than a fetch inside an already-running server.
  */
+/**
+ * The budget the DISOWNED child gets, and why it is not `SEND_TIMEOUT_MS`.
+ *
+ * 2s is right for an in-process send: the daemon is waiting on it, so the budget is a latency cost
+ * somebody pays. A detached child pays nobody — the parent has already exited — so the only thing a
+ * short budget there buys is a lost event.
+ *
+ * And it loses the worst ones. Every detached send comes from a SHORT-LIVED CLI process, which pays
+ * cold DNS and a cold TLS route by definition; measured on the feedback path with a WARM cache it
+ * was already 0.694s before any payload moved. `reticle_installed` is the extreme case: it fires
+ * once per machine, on the first Reticle command that machine ever runs, which is the single coldest
+ * network call it will ever make to the collector — so the top of the funnel is the event most
+ * likely to be dropped, and it fails silently like everything else here.
+ */
+const DETACHED_SEND_TIMEOUT_MS = 15_000;
 const DETACHED_SEND_SCRIPT = "fetch(process.argv[1],{method:'POST',headers:{'content-type':'application/json'}," +
-    `body:process.argv[2],signal:AbortSignal.timeout(${SEND_TIMEOUT_MS})})` +
+    `body:process.argv[2],signal:AbortSignal.timeout(${DETACHED_SEND_TIMEOUT_MS})})` +
     '.catch(()=>{}).finally(()=>process.exit(0))';
 /** Env var names — mirror cloud-sync's `RETICLE_*` convention. */
 import { isReticleSourceCheckout } from './dev-repo.js';

package/dist/telemetry/tool-refused.d.ts

@@ -10,7 +10,9 @@
  * Emitted from `runTool`, which is the one place both dispatch paths cross, so a tool added later is
  * covered without anybody remembering to cover it.
  */
-import { type RefusalReason } from '@reticlehq/core';
+import { RefusalReason, type NoSessionReason } from '@reticlehq/core';
+/** Record the branch code for the no-session error being thrown right now. */
+export declare function notePendingNoSessionReason(reason: NoSessionReason | undefined): void;
 /** A call that was served. Breaks the retry chain: what follows it is not a retry of anything. */
 export declare function noteToolServed(): void;
 /** One refused call, reported with its cause and whether it was itself a retry. */

package/dist/telemetry/tool-refused.js

@@ -10,7 +10,7 @@
  * Emitted from `runTool`, which is the one place both dispatch paths cross, so a tool added later is
  * covered without anybody remembering to cover it.
  */
-import { TelemetryActor, TelemetryEventKind } from '@reticlehq/core';
+import { RefusalReason, TelemetryActor, TelemetryEventKind, } from '@reticlehq/core';
 import { getTelemetry } from './telemetry.js';
 /**
  * Refusal events one daemon run will send.
@@ -32,6 +32,24 @@ let sent = 0;
  * describe — so the flag lands on the RETRY instead of on the first refusal.
  */
 let lastRefusedTool;
+/**
+ * The no-session branch code for the refusal about to be reported, set by whoever threw it.
+ *
+ * `no_session` is the largest refusal cohort and on its own it is a set difference: nothing
+ * connected, and no word on which of several opposite situations that was. The diagnosis that CAN
+ * say is computed where the error is thrown, and the refusal is classified downstream from the
+ * message, so the two never met (#615).
+ *
+ * Module-level and consumed once, like `lastRefusedTool` above and for the same reason: the
+ * producer and the consumer are one hop apart on the same call, and threading a field through every
+ * refusal path to carry it would touch a dozen call sites that have nothing to do with sessions.
+ * Cleared on read so a later refusal cannot inherit a stale reason.
+ */
+let pendingNoSessionReason;
+/** Record the branch code for the no-session error being thrown right now. */
+export function notePendingNoSessionReason(reason) {
+    pendingNoSessionReason = reason;
+}
 /** A call that was served. Breaks the retry chain: what follows it is not a retry of anything. */
 export function noteToolServed() {
     lastRefusedTool = undefined;
@@ -40,16 +58,30 @@ export function noteToolServed() {
 export function reportToolRefused(tool, reason) {
     const retried = lastRefusedTool === tool;
     lastRefusedTool = tool;
+    // Read and clear whatever the throw left, whether or not this refusal can use it: a reason left
+    // sitting would attach itself to an unrelated refusal later in the session.
+    const noSessionReason = pendingNoSessionReason;
+    pendingNoSessionReason = undefined;
     if (sent >= MAX_REFUSALS_PER_SESSION)
         return;
     sent += 1;
     void getTelemetry().emit(TelemetryEventKind.TOOL_REFUSED, {
         actor: TelemetryActor.AGENT,
-        refusal: { tool, reason, retried },
+        refusal: {
+            tool,
+            reason,
+            retried,
+            // Only where it means something. On any other refusal reason this field would be answering
+            // a question nobody asked of it.
+            ...(RefusalReason.NO_SESSION === reason && noSessionReason !== undefined
+                ? { noSessionReason }
+                : {}),
+        },
     });
 }
 /** Tests only — the counters are process-lifetime, so each case has to start from zero. */
 export function resetToolRefusals() {
     sent = 0;
     lastRefusedTool = undefined;
+    pendingNoSessionReason = undefined;
 }

package/dist/tools/act-capsule.d.ts

@@ -17,6 +17,16 @@ interface CapsuleSaveInputs {
         file: string;
         line: number;
     };
+    /**
+     * The `.reticle` this capsule belongs in, from the session the act ACTUALLY drove.
+     *
+     * Passed in rather than re-resolved here, because re-resolving loses twice: `args.sessionId` is
+     * frequently absent, and `sessions.resolve(undefined)` throws whenever more than one tab is
+     * connected — which is precisely the multi-project case this routing exists for, so it failed in
+     * exactly the situation it was written to fix. The caller also knows about a session the act
+     * FOLLOWED through a navigation; this file cannot.
+     */
+    root?: string | undefined;
 }
 /** Returns the capsule id when one was written, or undefined when there was nothing to save. */
 export declare function saveFailedAssertCapsule(inputs: CapsuleSaveInputs): Promise<string | undefined>;

package/dist/tools/act-capsule.js

@@ -13,16 +13,22 @@ import { ActionType, AnchorKind } from '@reticlehq/core';
 import { CapsuleStore, capsuleId, CAPSULE_VERSION } from '../capsule/capsule-store.js';
 import { ReticleTool } from './tool-names.js';
 import { asRecord, asString } from './tools-helpers.js';
+import { sessionRoot } from '../project/session-root.js';
 /** Returns the capsule id when one was written, or undefined when there was nothing to save. */
 export async function saveFailedAssertCapsule(inputs) {
-    const { deps, verdict, capsule, links, args, actResult, actedSource } = inputs;
+    const { deps, verdict, capsule, links, args, actResult, actedSource, root: given } = inputs;
     if (verdict.pass || capsule === undefined)
         return undefined;
     const id = capsuleId(deps.now(), asString(args['ref']) ?? 'assert');
     const expectedText = links
         .map((l) => ('name' in l ? `${l.kind} ${String(l.name)}` : l.kind))
         .join(' AND ');
-    const saved = await new CapsuleStore(deps.fs, deps.reticleRoot).save({
+    // The capsule belongs to the project whose app just failed, not to wherever the daemon stands.
+    // Same rule and same resolver as every other artifact: a capsule written into a sibling repo is
+    // evidence filed against a codebase that did not produce it, and it outlives the turn.
+    // The caller's answer wins; the resolver is the fallback for callers that have no session.
+    const root = given ?? sessionRoot(deps, asString(args['sessionId']));
+    const saved = await new CapsuleStore(deps.fs, root).save({
         version: CAPSULE_VERSION,
         id,
         createdAt: deps.now(),

package/dist/tools/act-danger.d.ts

@@ -2,7 +2,8 @@ import { ActionType } from '@reticlehq/core';
 export declare function assertNotDestructive(action: ActionType, innerArgs: Record<string, unknown>, inspected: unknown): void;
 /**
  * A drag is judged on BOTH ends. Dropping a harmless row onto "Delete" is destructive, and the
- * source alone never says so.
+ * source alone never says so. Each end is classified on its own text and role, so a Payment
+ * option dragged onto Save is not a payment.
  */
 export declare function assertDragNotDestructive(innerArgs: Record<string, unknown>, from: unknown, to: unknown): void;
 /**

package/dist/tools/act-danger.js

@@ -22,23 +22,31 @@ function descriptorText(value) {
         asString(descriptor['formText']) ?? '',
     ].join(' ');
 }
+function descriptorRole(value) {
+    const role = asString(asRecord(value)['role']);
+    return role !== undefined && role.length > 0 ? role : undefined;
+}
+function isDestructiveDescriptor(value) {
+    return isDangerousActionText(descriptorText(value), descriptorRole(value));
+}
 export function assertNotDestructive(action, innerArgs, inspected) {
     if (action !== ActionType.CLICK && action !== ActionType.DBLCLICK)
         return;
     if (true === innerArgs[DANGEROUS_ACTION_CONFIRM_ARG])
         return;
-    if (!isDangerousActionText(descriptorText(inspected)))
+    if (!isDestructiveDescriptor(inspected))
         return;
     throw new Error(`potentially destructive native action blocked; retry with args.${DANGEROUS_ACTION_CONFIRM_ARG}=true`);
 }
 /**
  * A drag is judged on BOTH ends. Dropping a harmless row onto "Delete" is destructive, and the
- * source alone never says so.
+ * source alone never says so. Each end is classified on its own text and role, so a Payment
+ * option dragged onto Save is not a payment.
  */
 export function assertDragNotDestructive(innerArgs, from, to) {
     if (true === innerArgs[DANGEROUS_ACTION_CONFIRM_ARG])
         return;
-    if (!isDangerousActionText(`${descriptorText(from)} ${descriptorText(to)}`))
+    if (!isDestructiveDescriptor(from) && !isDestructiveDescriptor(to))
         return;
     throw new Error(`potentially destructive native action blocked; retry with args.${DANGEROUS_ACTION_CONFIRM_ARG}=true`);
 }

package/dist/tools/act-observation.d.ts

@@ -0,0 +1,41 @@
+/**
+ * What to do when the observer left in the middle of an act.
+ *
+ * A full-document navigation — often the very thing the act CAUSED — tears the SDK down. The page
+ * re-announces, and whatever this call still had in flight is gone. That is a fact about the
+ * observer, never about the application, and the difference matters: every honest verdict this
+ * engine can give depends on not converting "I stopped watching" into "your app is broken".
+ *
+ * Extracted from act-tools.ts, which had reached the file-size cap. It earns its own module because
+ * it is one idea — follow the document that took over, and re-ask there — used from the two points
+ * where observation can be lost: a write rejected at dispatch, and a wait cut off mid-predicate.
+ */
+import type { Session } from '../session/session.js';
+import { type SuccessorRegistry } from '../session/session-successor.js';
+import type { EvalResult } from '../events/predicate-eval.js';
+export interface FollowSuccessor {
+    sessions: SuccessorRegistry;
+    session: Session;
+    verdict: EvalResult;
+    /** Total budget the CALLER granted, in ms. */
+    timeout: number;
+    /** `session.elapsed()` at the moment the predicate started. */
+    predicateStarted: number;
+    /** Re-ask the declared consequence on `next`, with whatever budget is left. */
+    reevaluate: (next: Session, budgetMs: number) => Promise<EvalResult>;
+}
+export interface FollowedOutcome {
+    session: Session;
+    verdict: EvalResult;
+    /** True when the wait moved to a new document, so the caller must reset its event cursor. */
+    followed: boolean;
+}
+/**
+ * Follow the unique same-origin successor and re-ask there, or leave the verdict untouched.
+ *
+ * `navigate` already waits for the HELLO and returns the new id; this path used to grade
+ * `observation_lost` and leave the agent holding a DEAD id, so the next assert failed even though
+ * the new page had loaded perfectly. Two live tabs at that origin is still a guess, and
+ * `awaitDocumentSuccessor` refuses to guess — a wrong follow drives somebody else's app.
+ */
+export declare function followLostObservation(input: FollowSuccessor): Promise<FollowedOutcome>;

package/dist/tools/act-observation.js

@@ -0,0 +1,36 @@
+/**
+ * What to do when the observer left in the middle of an act.
+ *
+ * A full-document navigation — often the very thing the act CAUSED — tears the SDK down. The page
+ * re-announces, and whatever this call still had in flight is gone. That is a fact about the
+ * observer, never about the application, and the difference matters: every honest verdict this
+ * engine can give depends on not converting "I stopped watching" into "your app is broken".
+ *
+ * Extracted from act-tools.ts, which had reached the file-size cap. It earns its own module because
+ * it is one idea — follow the document that took over, and re-ask there — used from the two points
+ * where observation can be lost: a write rejected at dispatch, and a wait cut off mid-predicate.
+ */
+import { awaitDocumentSuccessor } from '../session/session-successor.js';
+/**
+ * Follow the unique same-origin successor and re-ask there, or leave the verdict untouched.
+ *
+ * `navigate` already waits for the HELLO and returns the new id; this path used to grade
+ * `observation_lost` and leave the agent holding a DEAD id, so the next assert failed even though
+ * the new page had loaded perfectly. Two live tabs at that origin is still a guess, and
+ * `awaitDocumentSuccessor` refuses to guess — a wrong follow drives somebody else's app.
+ */
+export async function followLostObservation(input) {
+    const { sessions, session, verdict, timeout, predicateStarted, reevaluate } = input;
+    if (true !== verdict.observationLost || 0 >= timeout)
+        return { session, verdict, followed: false };
+    const remaining = timeout - (session.elapsed() - predicateStarted);
+    const next = remaining > 0 ? await awaitDocumentSuccessor(sessions, session, remaining) : null;
+    if (null === next)
+        return { session, verdict, followed: false };
+    // Computed on the DEPARTED session, before the caller points at the successor: the new session's
+    // elapsed() starts at 0 and would silently refund the whole budget the caller had already spent.
+    const leftover = timeout - (session.elapsed() - predicateStarted);
+    if (leftover <= 0)
+        return { session: next, verdict, followed: true };
+    return { session: next, verdict: await reevaluate(next, leftover), followed: true };
+}

package/dist/tools/act-preflight.d.ts

@@ -0,0 +1,20 @@
+export declare function assertSequenceSteps(steps: readonly unknown[]): void;
+/**
+ * Throws if this call cannot honestly be driven. Call it after the args are parsed and before the
+ * first dispatch — anything that depends on what is actually rendered belongs after the action.
+ */
+export declare function preflightAct(actArgs: Record<string, unknown>, until: unknown): void;
+/**
+ * Dispatch a write, or report that its outcome went unobserved.
+ *
+ * Returns null — never throws — when the transport was displaced by a newer connection claiming the
+ * same id. That happens on any full-document navigation the act itself causes: the page unloads,
+ * re-announces, and the write in flight is rejected by the handle that just died.
+ *
+ * The write is deliberately NOT re-sent. Re-asking a READ on the successor is free; re-sending a
+ * WRITE is not, because nothing can prove the first one did not reach the page — and a duplicated
+ * click on a button that charges a card is a far worse outcome than a verdict of "I could not see".
+ * Every other failure propagates unchanged: only a replacement is an observation problem, and
+ * treating a timeout or a refusal as one would launder a real failure into a shrug.
+ */
+export declare function dispatchAct<T>(send: () => Promise<T>): Promise<T | null>;