@reticlehq/server 3.9.0 → 3.10.0

package/dist/language/flows/flows.js

@@ -5,7 +5,7 @@ import { safeProjectId } from './flow-result.js';
 import { changeInPlace } from './narrow-write.js';
 import { dirname } from 'node:path';
 import { gitTracks } from '../../machine/git-tracks.js';
-import { AnchorKind, DEGRADED_ANCHOR_ROLE, DOCUMENT_ANCHOR_ROLE, FLOW_FILE_VERSION, flowFileVersionFor, FlowErrorCode, FlowFileSchema, FlowStepTool, QueryBy, defaultIsSensitiveKey, isGlobalPressCall, } from '@reticlehq/core';
+import { AnchorKind, DEGRADED_ANCHOR_ROLE, DOCUMENT_ANCHOR_ROLE, FLOW_FILE_VERSION, flowFileVersionFor, FlowErrorCode, FlowFileSchema, FlowStepTool, QueryBy, REDACTED_VALUE, isCredentialFieldName, isGlobalPressCall, } from '@reticlehq/core';
 import { ReticleTool, flowJsonReplacer, mainCheckoutTwin } from '@reticlehq/core';
 import { asRecord, asString } from '@reticlehq/core';
 import { applyHealChanges } from './heal.js';
@@ -35,25 +35,44 @@ function sourceArg(src) {
     const source = asRecord(src['source']);
     const file = source['file'];
     const line = source['line'];
-    if (typeof file !== 'string' || 0 === file.length || typeof line !== 'number')
+    if (typeof file !== 'string' || 0 === file.length || typeof line !== 'number') {
         return undefined;
+    }
     const out = { file, line };
-    if ('number' === typeof source['column'])
+    if ('number' === typeof source['column']) {
         out.column = source['column'];
+    }
     return out;
 }
 function componentAnchor(src) {
     const component = asString(src['component']);
     const source = sourceArg(src);
-    if (component === undefined && source === undefined)
+    if (component === undefined && source === undefined) {
         return null;
+    }
     const anchor = {
         kind: AnchorKind.COMPONENT,
     };
-    if (component !== undefined)
+    if (component !== undefined) {
         anchor.component = component;
-    if (source !== undefined)
+    }
+    if (source !== undefined) {
         anchor.source = source;
+    }
+    const text = asString(src['text']);
+    if (text !== undefined && text.length > 0) {
+        anchor.text = text;
+    }
+    const role = asString(src['role']);
+    if (role !== undefined && role.length > 0) {
+        anchor.role = role;
+    }
+    const nth = src['nth'];
+    const of = src['of'];
+    if ('number' === typeof nth && 'number' === typeof of && 1 < of) {
+        anchor.nth = nth;
+        anchor.of = of;
+    }
     return anchor;
 }
 /** Pick the on-disk anchor for a normalized step: testid > component(auto) > degraded role. */
@@ -66,20 +85,19 @@ export function anchorForStep(args) {
             value,
         };
         const source = sourceArg(args);
-        if (source !== undefined)
+        if (source !== undefined) {
             anchor.source = source;
+        }
         const of = args['of'];
-        if ('number' === typeof of && 1 < of)
+        if ('number' === typeof of && 1 < of) {
             anchor.of = of;
+            // Its place among them, as a role anchor keeps one (#2135).
+            Object.assign(anchor, 'number' === typeof args['nth'] ? { nth: args['nth'] } : {});
+        }
         return { anchor, degraded: false };
     }
-    // Role + NAME is a real anchor, not a degraded placeholder.
-    //
-    // The vocabulary has always described `{ kind:'role', role, name }` as an addressable anchor, and
-    // nothing ever produced one — the only ROLE anchor written to disk was the degraded placeholder
-    // that means "add a data-testid". So a step the recorder anchored by accessible name arrived here
-    // and had that name thrown away, which is precisely the anchor that distinguishes one row's
-    // control from another's when a shared JSX source location cannot.
+    // Role + NAME is a real anchor, not a degraded placeholder: the name separates one row's control
+    // from another's when a shared JSX source location cannot.
     // A document-key press compiled with no element (#1559): a real anchor, not a degraded one. It is
     // nameless on purpose, because it names no element; the press is what replay dispatches.
     if (by === QueryBy.ROLE &&
@@ -88,20 +106,30 @@ export function anchorForStep(args) {
         isGlobalPressCall({ action: args['action'], args: args['args'] })) {
         return { anchor: { kind: AnchorKind.ROLE, role: DOCUMENT_ANCHOR_ROLE }, degraded: false };
     }
-    if (by === QueryBy.ROLE && value !== undefined) {
+    if (by === QueryBy.ROLE && value !== undefined && value !== DEGRADED_ANCHOR_ROLE) {
         const name = asString(args['name']);
+        // Provenance lives on the step, not the anchor; the position among namesakes is identity.
+        const nth = args['nth'];
+        const of = args['of'];
+        const among = 'number' === typeof nth && 'number' === typeof of ? { nth, of } : {};
         if (name !== undefined && name.length > 0) {
-            // Provenance lives on the step, not the anchor; the position among namesakes is identity.
-            const nth = args['nth'];
-            const of = args['of'];
-            const among = 'number' === typeof nth && 'number' === typeof of ? { nth, of } : {};
-            return { anchor: { kind: AnchorKind.ROLE, role: value, name, ...among }, degraded: false };
+            // The nearest containers' roles: where a replay looks when a correct build renamed it.
+            const within = Array.isArray(args['within']) ? { within: args['within'].map(String) } : {};
+            return {
+                anchor: { kind: AnchorKind.ROLE, role: value, name, ...among, ...within },
+                degraded: false,
+            };
         }
+        // A control with a role and no accessible name (an icon-only button) is addressed by its
+        // position among the nameless controls of its role. Saving it as the degraded placeholder made
+        // every step on an icon-only button unreplayable.
+        return { anchor: { kind: AnchorKind.ROLE, role: value, ...among }, degraded: false };
     }
     if (by === QueryBy.COMPONENT) {
         const anchor = componentAnchor(args);
-        if (anchor !== null)
+        if (anchor !== null) {
             return { anchor, degraded: false };
+        }
     }
     return { anchor: degradedAnchor(), degraded: true };
 }
@@ -122,8 +150,9 @@ function subStepToFlowStep(raw) {
      * exactly this, so dropping it here made the grader count assertions that were never saved.
      */
     const expect = sub['expect'];
-    if (expect !== undefined)
+    if (expect !== undefined) {
         step.expect = expect;
+    }
     return step;
 }
 /**
@@ -137,24 +166,55 @@ function subStepToFlowStep(raw) {
  * WHERE it was typed rather than by guessing whether the characters look secret — a guess that both
  * over-redacts a search box and misses a password that happens to be a dictionary word.
  *
- * `defaultIsSensitiveKey` is the same rule the network channel redacts by, so a field considered
- * sensitive on the wire cannot be considered safe on disk.
+ * `isCredentialFieldName` is the network key rule plus the word for a password in other
+ * languages. An SDK before 3.8.0 sends no secret mark, and then the name is the only signal.
  */
 function redactSecretFill(anchor, args, 
 /** The SDK said the target holds a secret: redact whatever the field is called. */
 secret = false) {
-    if (typeof args['value'] !== 'string')
+    if (typeof args['value'] !== 'string') {
         return args;
+    }
     const field = anchorFieldName(anchor);
-    const sensitive = secret || (field !== undefined && defaultIsSensitiveKey(field));
-    if (!sensitive)
+    const sensitive = secret || (field !== undefined && isCredentialFieldName(field));
+    if (!sensitive) {
         return args;
+    }
     // ponytail: a secret field with no name (a component anchor) gets no variable; replay then refuses it.
-    if (field === undefined)
+    if (field === undefined) {
         return { ...args, value: REDACTED_FILL };
+    }
     // The variable that supplies it, beside the placeholder: the file alone says what to set.
     return { ...args, value: REDACTED_FILL, [SECRET_NAME_ARG]: secretEnvKey(field) };
 }
+/**
+ * An anchored flow with each credential fill redacted by its field name.
+ *
+ * An in-page recorder of an older SDK redacts by an English rule only, and its flow arrives here
+ * already anchored. A value that is already a placeholder is left as it is, with its variable name.
+ */
+function redactSavedFills(flow) {
+    let redacted = false;
+    const redact = (step) => {
+        const value = step.args?.['value'];
+        let out = step;
+        if (step.args !== undefined &&
+            'string' === typeof value &&
+            REDACTED_FILL !== value &&
+            REDACTED_VALUE !== value) {
+            const args = redactSecretFill(step.anchor, step.args);
+            if (args !== step.args) {
+                redacted = true;
+                out = { ...step, args };
+            }
+        }
+        return step.steps === undefined ? out : { ...out, steps: step.steps.map(redact) };
+    };
+    const steps = flow.steps.map(redact);
+    // Only a fill redacted here needs a variable name. A flow that already names its variables keeps
+    // them: two fills that share one older name must not be renamed.
+    return redacted ? withDistinctSecretKeys({ ...flow, steps }) : flow;
+}
 /** Whether a recorded step's args carry the SDK's secret mark. */
 const markedSecret = (args) => true === args[SECRET_FIELD_ARG];
 /**
@@ -176,8 +236,9 @@ export function redactRecordedSteps(steps) {
 /** One normalized act's args with its inner fill `args` redacted by the anchor it would save as. */
 function redactNormalizedArgs(normalized) {
     const inner = normalized['args'];
-    if ('object' !== typeof inner || null === inner)
+    if ('object' !== typeof inner || null === inner) {
         return normalized;
+    }
     const redacted = redactSecretFill(anchorForStep(normalized).anchor, asRecord(inner), markedSecret(normalized));
     return redacted === inner ? normalized : { ...normalized, args: redacted };
 }
@@ -195,12 +256,15 @@ function redactNormalizedArgs(normalized) {
  * the placeholder into the form. One function decides it for both sides, or the two drift again.
  */
 export function anchorFieldName(anchor) {
-    if (AnchorKind.TESTID === anchor.kind)
+    if (AnchorKind.TESTID === anchor.kind) {
         return anchor.value;
-    if (AnchorKind.ROLE === anchor.kind)
+    }
+    if (AnchorKind.ROLE === anchor.kind) {
         return anchor.name;
-    if (AnchorKind.SIGNAL === anchor.kind)
+    }
+    if (AnchorKind.SIGNAL === anchor.kind) {
         return anchor.name;
+    }
     return undefined;
 }
 /**
@@ -216,10 +280,12 @@ function keepRoleSource(step, src) {
 }
 function buildStep(tool, anchor, action, args, degraded, secret = false) {
     const step = { tool, anchor, args: redactSecretFill(anchor, args, secret) };
-    if (action !== undefined)
+    if (action !== undefined) {
         step.action = action;
-    if (degraded)
+    }
+    if (degraded) {
         step.degraded = true;
+    }
     return step;
 }
 /**
@@ -229,44 +295,51 @@ function buildStep(tool, anchor, action, args, degraded, secret = false) {
  */
 export function recordedStepToFlowStep(step) {
     const out = anchoredStep(step);
-    if (step.timeoutMs !== undefined)
+    if (step.timeoutMs !== undefined) {
         out.timeoutMs = step.timeoutMs;
-    if (step.page !== undefined)
+    }
+    if (step.burstMs !== undefined) {
+        out.burstMs = step.burstMs;
+    }
+    if (step.page !== undefined) {
         out.page = step.page;
-    if (step.endPage !== undefined && step.endPage !== step.page)
+    }
+    if (step.endPage !== undefined && step.endPage !== step.page) {
         out.endPage = step.endPage;
-    if (true === step.writes)
+    }
+    if (true === step.writes) {
         out.writes = true;
+    }
     return out;
 }
 function anchoredStep(step) {
     if (step.invoke !== undefined) {
         // An invocation drives nothing: no action, no args, and an anchor only because every step
-        // carries one. Falling through to the action path below would give it an `action` and a
-        // replayer would try to dispatch a step whose whole meaning is "go and run that document".
+        // carries one. Below, it would get an `action` that a replayer would try to dispatch.
         const out = {
             tool: FlowStepTool.INVOKE,
             anchor: { kind: AnchorKind.TESTID, value: step.invoke },
             invoke: step.invoke,
         };
-        if (step.expect !== undefined)
+        if (step.expect !== undefined) {
             out.expect = step.expect;
+        }
         return out;
     }
     if (step.tool === ReticleTool.ACT_SEQUENCE) {
         const rawSubs = Array.isArray(step.args['steps']) ? step.args['steps'] : [];
         const subs = rawSubs.map(subStepToFlowStep);
         const degraded = subs.some((s) => true === s.degraded);
-        // The first sub-step that HAS an anchor, not blindly the first. Taking subs[0] handed the whole
-        // sequence the degraded sentinel whenever sub-step 0 lacked a testid — even with every later
-        // sub-step perfectly anchored — and replay then queried the DOM for a testid literally named
-        // "unresolved", so the step drifted on all 5 apps, every replay.
+        // The first sub-step that HAS an anchor: subs[0] gave a sequence the degraded sentinel whenever
+        // sub-step 0 lacked a testid, and replay looked for a testid named "unresolved" on every app.
         const anchor = subs.find((s) => s.degraded !== true)?.anchor ?? subs[0]?.anchor ?? degradedAnchor();
         const out = { tool: ReticleTool.ACT_SEQUENCE, anchor, steps: subs };
-        if (degraded)
+        if (degraded) {
             out.degraded = true;
-        if (step.expect !== undefined)
+        }
+        if (step.expect !== undefined) {
             out.expect = step.expect;
+        }
         return out;
     }
     const action = asString(step.args['action']);
@@ -274,14 +347,16 @@ function anchoredStep(step) {
     const { anchor, degraded } = anchorForStep(step.args);
     const out = buildStep(step.tool, anchor, action, args, degraded, markedSecret(step.args));
     keepRoleSource(out, step.args);
-    if (step.expect !== undefined)
+    if (step.expect !== undefined) {
         out.expect = step.expect;
+    }
     return out;
 }
 /** Apply folded annotations onto an anchored flow (pure): per-step expect, dynamic[], success, intent. */
 function withAnnotations(flow, ann) {
-    if (ann === undefined)
+    if (ann === undefined) {
         return flow;
+    }
     const steps = flow.steps.map((step, i) => {
         const expect = ann.stepExpect.get(i);
         return expect === undefined ? step : { ...step, expect };
@@ -290,10 +365,12 @@ function withAnnotations(flow, ann) {
     if (ann.dynamic.length > 0) {
         out.dynamic = ann.dynamic.map((value) => ({ kind: AnchorKind.TESTID, value }));
     }
-    if (ann.success !== undefined)
+    if (ann.success !== undefined) {
         out.success = ann.success;
-    if (ann.intent !== undefined)
+    }
+    if (ann.intent !== undefined) {
         out.intent = ann.intent;
+    }
     return out;
 }
 const JSON_INDENT = 2;
@@ -429,18 +506,21 @@ export class FlowStore {
      * fill its gaps and are removed. The same scan collapses copies saved before this existed.
      */
     async saveJourney(program, projectId, prefix) {
-        if (!isValidFlowName(program.name))
+        if (!isValidFlowName(program.name)) {
             return { ok: false, code: FlowErrorCode.INVALID_NAME };
+        }
         const pid = safeProjectId(projectId);
         const fresh = this.#build(program, undefined, pid);
         const saved = [];
         const freshPrint = journeyFingerprint(fresh);
         for (const name of await this.list(pid)) {
             const loaded = await this.load(name, pid);
-            if (!loaded.ok)
+            if (!loaded.ok) {
                 continue;
-            if (name.startsWith(prefix))
+            }
+            if (name.startsWith(prefix)) {
                 saved.push(loaded.value);
+            }
             // The agent already saved this journey under its own name: one journey, one flow. A web drive
             // saved its named flow and an automatic `drive-saved-<email>` beside it, every time.
             else if (journeyFingerprint(loaded.value) === freshPrint) {
@@ -456,11 +536,13 @@ export class FlowStore {
         const taken = new Map(saved.map((flow) => [flow.name, journeyFingerprint(flow)]));
         // The same name holding this journey driven with a step more or less: one file, the fuller drive.
         const same = saved.find((flow) => flow.name === fresh.name && taken.get(flow.name) !== print);
-        if (same !== undefined && withinJourney(same, fresh))
+        if (same !== undefined && withinJourney(same, fresh)) {
             return { ok: true, value: this.#summary(same) };
+        }
         const extended = same !== undefined && withinJourney(fresh, same);
-        if (extended)
+        if (extended) {
             taken.delete(fresh.name);
+        }
         const named = {
             ...fresh,
             ...(extended && fresh.intent === undefined && same.intent !== undefined
@@ -471,19 +553,23 @@ export class FlowStore {
         byPrint.set(print, [...(byPrint.get(print) ?? []), named]);
         let result = named;
         for (const [groupPrint, group] of byPrint) {
-            if (group.length < 2 && groupPrint !== print)
+            if (group.length < 2 && groupPrint !== print) {
                 continue;
+            }
             const [kept, ...rest] = [...group].sort((a, b) => a.createdAt - b.createdAt);
-            if (kept === undefined)
+            if (kept === undefined) {
                 continue;
+            }
             const merged = await this.#linkIntent(rest.reduce(mergeJourney, kept));
             await this.#writeInPlace(merged, pid);
             for (const dropped of rest) {
-                if (dropped.name !== merged.name && dropped !== named)
+                if (dropped.name !== merged.name && dropped !== named) {
                     await this.remove(dropped.name, pid);
+                }
             }
-            if (groupPrint === print)
+            if (groupPrint === print) {
                 result = merged;
+            }
         }
         this.#onWrote?.();
         return { ok: true, value: this.#summary(result) };
@@ -501,8 +587,9 @@ export class FlowStore {
      * re-run FlowFileSchema before writing. save is left untouched.
      */
     async saveFlow(flow, projectId) {
-        if (!isValidFlowName(flow.name))
+        if (!isValidFlowName(flow.name)) {
             return { ok: false, code: FlowErrorCode.INVALID_NAME };
+        }
         const pid = safeProjectId(projectId);
         // Stamp the project INTO the file (so a flow carries its own scope) and route it to the matching
         // per-project subdir. Both come from the same `pid`, so on-disk location and content always agree.
@@ -517,7 +604,7 @@ export class FlowStore {
                 detail: describeFlowZodFailure(parsed.error),
             };
         }
-        const valid = await this.#linkIntent(readyForReplay(parsed.data));
+        const valid = await this.#linkIntent(readyForReplay(redactSavedFills(parsed.data)));
         await this.#fs.mkdir(flowParentDir(this.#root, asFlowName(valid.name), pid));
         await this.#fs.writeFile(flowPath(this.#root, asFlowName(valid.name), pid), this.#serialize(valid));
         this.#onWrote?.();
@@ -578,8 +665,9 @@ export class FlowStore {
     }
     /** The `.json` basenames (no extension) directly inside `dir`. [] if the dir is absent/unreadable. */
     async #namesIn(dir) {
-        if (!(await this.#fs.exists(dir)))
+        if (!(await this.#fs.exists(dir))) {
             return [];
+        }
         let entries;
         try {
             entries = await this.#fs.readdir(dir);
@@ -603,8 +691,9 @@ export class FlowStore {
      */
     async list(projectId) {
         const own = await this.#listOwn(projectId);
-        if (this.#main === undefined)
+        if (this.#main === undefined) {
             return own;
+        }
         return [...new Set([...own, ...(await this.#main.list(projectId))])].sort();
     }
     async #listOwn(projectId) {
@@ -615,8 +704,9 @@ export class FlowStore {
             const own = await this.#namesIn(flowDir(this.#root, pid));
             return [...new Set([...own, ...legacy])].sort();
         }
-        if (!(await this.#fs.exists(flowsDir)))
+        if (!(await this.#fs.exists(flowsDir))) {
             return [];
+        }
         let entries;
         try {
             entries = await this.#fs.readdir(flowsDir);
@@ -635,24 +725,28 @@ export class FlowStore {
     async #resolveReadPath(name, pid) {
         if (pid !== undefined) {
             const nested = flowPath(this.#root, name, pid);
-            if (await this.#fs.exists(nested))
+            if (await this.#fs.exists(nested)) {
                 return nested;
+            }
         }
         const flat = flowPath(this.#root, name);
-        if (await this.#fs.exists(flat))
+        if (await this.#fs.exists(flat)) {
             return flat;
+        }
         // No projectId (CLI/CI/contract callers, e.g. reticle_domain): mirror list's subdir union on
         // the read side too — a flow saved under .reticle/flows/<projectId>/ must still load, else it is
         // listed and then silently dropped by `if (loaded.ok)` (reticle_domain reports flowCount:0).
-        if (pid === undefined)
+        if (pid === undefined) {
             return this.#resolveNestedPath(name);
+        }
         return null;
     }
     /** Scan the per-project subdirs for a flow by name — the read-side of list's no-pid union. */
     async #resolveNestedPath(name) {
         const flowsDir = reticleDirPaths(this.#root).flows;
-        if (!(await this.#fs.exists(flowsDir)))
+        if (!(await this.#fs.exists(flowsDir))) {
             return null;
+        }
         let entries;
         try {
             entries = await this.#fs.readdir(flowsDir);
@@ -663,8 +757,9 @@ export class FlowStore {
         // Same provenance as `#namesIn`'s scan above: a subdir of `.reticle/flows/` is a projectId.
         for (const dir of entries.filter((e) => !e.endsWith(FLOW_SUFFIX))) {
             const nested = flowPath(this.#root, name, asProjectId(dir));
-            if (await this.#fs.exists(nested))
+            if (await this.#fs.exists(nested)) {
                 return nested;
+            }
         }
         return null;
     }
@@ -674,16 +769,19 @@ export class FlowStore {
      */
     async load(name, projectId) {
         const own = await this.#loadOwn(name, projectId);
-        if (own.ok || own.code !== FlowErrorCode.NOT_FOUND || this.#main === undefined)
+        if (own.ok || own.code !== FlowErrorCode.NOT_FOUND || this.#main === undefined) {
             return own;
+        }
         return this.#main.load(name, projectId);
     }
     async #loadOwn(name, projectId) {
-        if (!isValidFlowName(name))
+        if (!isValidFlowName(name)) {
             return { ok: false, code: FlowErrorCode.INVALID_NAME };
+        }
         const path = await this.#resolveReadPath(name, safeProjectId(projectId));
-        if (null === path)
+        if (null === path) {
             return { ok: false, code: FlowErrorCode.NOT_FOUND };
+        }
         let text;
         try {
             text = await this.#fs.readFile(path);
@@ -703,11 +801,13 @@ export class FlowStore {
      * not a silent no-op, so a typo doesn't read as success.
      */
     async remove(name, projectId) {
-        if (!isValidFlowName(name))
+        if (!isValidFlowName(name)) {
             return { ok: false, code: FlowErrorCode.INVALID_NAME };
+        }
         const path = await this.#resolveReadPath(name, safeProjectId(projectId));
-        if (null === path)
+        if (null === path) {
             return { ok: false, code: FlowErrorCode.NOT_FOUND };
+        }
         await this.#fs.rm(path);
         return { ok: true, value: undefined };
     }

package/dist/language/flows/recording/tape/recordings.d.ts

@@ -9,6 +9,8 @@ export interface RecordedStep {
     stable: boolean;
     /** The caller's per-step wait budget, when one was explicitly provided. */
     timeoutMs?: number;
+    /** The act_sequence `burst` gap, when the sequence was driven with one. See FlowStep.burstMs. */
+    burstMs?: number;
     /** Optional post-condition annotation carried into the on-disk flow's expect. */
     expect?: Predicate;
     /**
@@ -130,8 +132,12 @@ export declare const isAmbient: (name: string) => boolean;
 export declare class RecordingStore {
     #private;
     private readonly byHarness;
-    /** `byHarness`: whether the step being captured was driven by the Harness, which tapes its own. */
-    constructor(byHarness?: () => boolean);
+    private readonly successorOf;
+    /**
+     * `byHarness`: whether the step being captured was driven by the Harness, which tapes its own.
+     * `successorOf`: the session that the same tab connected as after a page load, if any.
+     */
+    constructor(byHarness?: () => boolean, successorOf?: (session: string) => string | undefined);
     start(name: string, cursor: number, startPath?: string, session?: string, document?: string): void;
     isRecording(name: string): boolean;
     /**
@@ -201,7 +207,17 @@ export declare class RecordingStore {
     saveCompiled(program: CompiledProgram): void;
     getCompiled(name: string): CompiledProgram | undefined;
     active(): string[];
-    /** The ambient tape of one tab (or of steps no tab named), taken: what its session end saves. */
+    /**
+     * The ambient tape of one tab (or of steps no tab named), taken: what its session end saves.
+     *
+     * A session also ends when the app itself loads a page (a form post on a server-rendered app), and
+     * the journey goes on in the page that loaded. A tape with no check is not saved, so the next
+     * page's tape starts with a copy of it: a fill and the submit that proves it are then one flow, not
+     * a fill that is dropped and a submit on an empty form. When Reticle navigated away, the agent
+     * started a new journey, and nothing is carried.
+     * ponytail: only a tape with NO check is carried; unchecked steps after a check stay behind.
+     * ponytail: kept for the last CARRY_CAP ended pages; a tab that never loads a successor drops them.
+     */
     takeAmbient(session: string | undefined): ActiveRecording | undefined;
     /**
      * Names of recordings that have been STOPPED and compiled.