@flowriki/agent 0.1.0-beta.64 → 0.1.0-beta.66

package/dist/{chunk-2MTLWAXK.js → chunk-WUK3X43D.js}

@@ -28,6 +28,8 @@ import {
   adjacentLabelPattern,
   caseDebugPlan,
   checkMobileAssertion,
+  commandFor,
+  commandSystemOf,
   describeAssertion,
   describeLocators,
   expandForRun,
@@ -66,9 +68,10 @@ import {
   stepRefusedOn,
   targetFor,
   textIndependent,
+  usageKindOf,
   validateActors,
   webCloudOf
-} from "./chunk-RI63WNGU.js";
+} from "./chunk-YD7F7JMA.js";
 
 // src/engine/machine.ts
 import fs from "fs";
@@ -76,7 +79,7 @@ import os from "os";
 import path from "path";
 import { createRequire } from "module";
 import { spawnSync } from "child_process";
-var AGENT_VERSION = "0.1.0-beta.64";
+var AGENT_VERSION = "0.1.0-beta.66";
 async function prepareBrowsers() {
   if (browsersReady()) {
     return { ok: true, already: true, message: "chromium is already installed" };
@@ -136,7 +139,7 @@ async function checkMachine() {
     }
   } catch {
   }
-  const { mobileDoctor: mobileDoctor2 } = await import("./dist-FNAQZJYU.js");
+  const { mobileDoctor: mobileDoctor2 } = await import("./dist-CUDUSTFO.js");
   return {
     agentVersion: AGENT_VERSION,
     node: process.versions.node,
@@ -235,7 +238,7 @@ function forgetConnection(service, env = process.env) {
 }
 var fingerprint = (secret2) => crypto2.createHash("sha256").update(secret2).digest("hex").slice(0, 12);
 
-// ../contracts/dist/chunk-NTBXG5EZ.js
+// ../contracts/dist/chunk-VTO4SX4J.js
 import { z } from "zod";
 var PROTOCOL_VERSION = 1;
 var PAIRING_CODE_TTL_MS = 5 * 60 * 1e3;
@@ -288,7 +291,10 @@ var CommandNameSchema = z.enum([
   // a recording's — as a picture, for the live mirror. Reading.
   "mobile.peek",
   // What this computer has installed for web and phone testing. Reading.
-  "machine.check"
+  "machine.check",
+  // A helper run HERE — "Try it" on a command helper, which only the
+  // tester's computer can run. NOT baseline.
+  "helper.run"
 ]);
 var EFFECTFUL = /* @__PURE__ */ new Set([
   "record.start",
@@ -332,7 +338,9 @@ var EFFECTFUL = /* @__PURE__ */ new Set([
   "project.claim",
   "run.cancel",
   // A phone session taps and types on somebody's device.
-  "mobile.session"
+  "mobile.session",
+  // Runs a command on somebody's computer.
+  "helper.run"
 ]);
 var CommandSchema = z.object({
   /** Unique per command. The agent stores it, so a redelivery after a
@@ -483,7 +491,7 @@ function compareAgentVersions(a, b2) {
   }
   return 0;
 }
-var agentUpdateFor = (running, latest) => Boolean(running && latest && running !== "test" && compareAgentVersions(latest, running) > 0);
+var agentUpdateFor = (running2, latest) => Boolean(running2 && latest && running2 !== "test" && compareAgentVersions(latest, running2) > 0);
 
 // src/service.ts
 var BadServiceUrl = class extends Error {
@@ -551,7 +559,9 @@ async function connect(options = {}) {
     const res = await fetch(`${service}/api/pairing-requests`, {
       method: "POST",
       headers: { "content-type": "application/json" },
-      body: JSON.stringify({ machineName, agentVersion: AGENT_VERSION }),
+      // Ask for a code to show here: the page then insists on it, so a link
+      // sent by somebody else's agent cannot be approved by mistake.
+      body: JSON.stringify({ machineName, agentVersion: AGENT_VERSION, wantsCode: true }),
       signal: options.signal ?? null
     });
     if (!res.ok) {
@@ -565,7 +575,7 @@ async function connect(options = {}) {
   options.onProgress?.({
     kind: "approve",
     message: "waiting for approval in your browser",
-    detail: { url: approve, machineName, canOpen: options.open !== false && canOpenBrowser() }
+    detail: { url: approve, machineName, canOpen: options.open !== false && canOpenBrowser(), ...asked.code ? { code: `${asked.code.slice(0, 3)}-${asked.code.slice(3)}` } : {} }
   });
   if (options.open !== false) openBrowser(approve);
   const pollMs = options.pollMs ?? 1500;
@@ -1840,7 +1850,7 @@ function installDebugPanel() {
     pendingRender = false;
     const p = root.getElementById("p");
     p.className = "p" + (vertical ? " v" : "");
-    const running = state.status === "running";
+    const running2 = state.status === "running";
     const done = state.status === "finished";
     const stCls = state.failure ? "failed" : state.recording ? "running" : state.status;
     const stLabel = state.recording ? "recording" : state.failure ? "paused at a failure" : state.status === "idle" ? "not started" : state.status;
@@ -1933,7 +1943,7 @@ function installDebugPanel() {
       });
       return;
     }
-    p.innerHTML = '<div class="bar"><span class="grip" title="Drag to move"><i></i><i></i><i></i></span><span class="st ' + esc(stCls) + '"><span class="d"></span><span>' + esc(stLabel) + '</span><span class="prog">&#160;&#183;&#160;' + ran + "/" + state.steps.length + '</span></span><span class="dv"></span><button id="play" class="primary" title="' + (state.failure ? "Give up on this step and carry on" : "Run until the next breakpoint or failure") + '" ' + (running || done ? "disabled" : "") + ">" + (state.failure ? "Skip &amp; continue" : "Play") + "</button>" + (state.failure ? '<button id="retry" title="Run this step again">Retry</button>' : "") + '<button id="step" title="Run exactly one step" ' + (running || done ? "disabled" : "") + '>Step</button><button id="pause" title="Stop after the step in flight" ' + (running ? "" : "disabled") + '>Pause</button><button id="replay" title="Start over from the first step" ' + (running ? "disabled" : "") + '>Replay</button><span class="dv"></span>' + // While armed, this is the only way to stop it — so it says so, rather
+    p.innerHTML = '<div class="bar"><span class="grip" title="Drag to move"><i></i><i></i><i></i></span><span class="st ' + esc(stCls) + '"><span class="d"></span><span>' + esc(stLabel) + '</span><span class="prog">&#160;&#183;&#160;' + ran + "/" + state.steps.length + '</span></span><span class="dv"></span><button id="play" class="primary" title="' + (state.failure ? "Give up on this step and carry on" : "Run until the next breakpoint or failure") + '" ' + (running2 || done ? "disabled" : "") + ">" + (state.failure ? "Skip &amp; continue" : "Play") + "</button>" + (state.failure ? '<button id="retry" title="Run this step again">Retry</button>' : "") + '<button id="step" title="Run exactly one step" ' + (running2 || done ? "disabled" : "") + '>Step</button><button id="pause" title="Stop after the step in flight" ' + (running2 ? "" : "disabled") + '>Pause</button><button id="replay" title="Start over from the first step" ' + (running2 ? "disabled" : "") + '>Replay</button><span class="dv"></span>' + // While armed, this is the only way to stop it — so it says so, rather
     // than reading as a status label nobody realises is a button.
     (state.recording ? '<button id="rec" class="danger" title="Stop capturing"><span class="rec"><span class="dot"></span>Stop recording</span></button>' : '<button id="rec" title="Capture new steps at the cursor">Record</button>') + // AUTHORING A CHECK BELONGS HERE MOST OF ALL. Recording had it and
     // debugging did not, which is the wrong way round: the moment worth
@@ -2130,6 +2140,12 @@ async function performHelperStep(page, step, options) {
   }
   return got;
 }
+var LOAD_CAP_MS = 3e3;
+var QUIET_CAP_MS = 1e3;
+async function settleAfterNavigation(page) {
+  await page.waitForLoadState("load", { timeout: LOAD_CAP_MS }).catch(() => void 0);
+  await page.waitForLoadState("networkidle", { timeout: QUIET_CAP_MS }).catch(() => void 0);
+}
 var secretsBehind = (auth) => [.../* @__PURE__ */ new Set([
   ...Object.values(auth.secretRefs ?? {}),
   ...auth.steps.flatMap((step) => step.secretRef ? [step.secretRef] : [])
@@ -2333,7 +2349,10 @@ var RunActors = class {
     if (switching && this.opts.headless === false) await session.page.bringToFront().catch(() => {
     });
     if (this.initialized.has(id)) return;
-    if (startUrl) await session.page.goto(startUrl, { waitUntil: "domcontentloaded" });
+    if (startUrl) {
+      await session.page.goto(startUrl, { waitUntil: "domcontentloaded" });
+      await settleAfterNavigation(session.page);
+    }
     if (actor?.startSignedIn) {
       if (kept?.state) {
         const confirmed = await confirmSignedIn(session.page, kept.auth, this.opts.reuseCheckMs ?? 3e3);
@@ -2345,7 +2364,10 @@ var RunActors = class {
         this.opts.reuse?.cache.evict(kept.key);
         this.preparations.set(id, "stale");
         session = await this.replaceWithGuest(id, session);
-        await session.page.goto(startUrl, { waitUntil: "domcontentloaded" });
+        {
+          await session.page.goto(startUrl, { waitUntil: "domcontentloaded" });
+          await settleAfterNavigation(session.page);
+        }
       }
       await executeStep(
         session.page,
@@ -2377,7 +2399,10 @@ var RunActors = class {
         } catch {
         }
       }
-      if (startUrl) await session.page.goto(startUrl, { waitUntil: "domcontentloaded" });
+      if (startUrl) {
+        await session.page.goto(startUrl, { waitUntil: "domcontentloaded" });
+        await settleAfterNavigation(session.page);
+      }
     }
     this.initialized.add(id);
   }
@@ -2456,9 +2481,9 @@ var RunActors = class {
     const previous = this.sessions.get(id);
     const round = (this.resets.get(id) ?? 0) + 1;
     this.resets.set(id, round);
-    const home = `actor-${id}-${round}`;
-    const session = await openRunSession({ ...this.opts, browser: this.main.browser, ...this.evidenceIn(home) });
-    this.homes.set(session, home);
+    const home2 = `actor-${id}-${round}`;
+    const session = await openRunSession({ ...this.opts, browser: this.main.browser, ...this.evidenceIn(home2) });
+    this.homes.set(session, home2);
     this.sessions.set(id, session);
     this.current = session;
     this.currentId = id;
@@ -2474,7 +2499,10 @@ var RunActors = class {
       this.retired.add(previous);
     }
     await this.opts.onCreate?.(session);
-    await session.page.goto(this.opts.startUrl, { waitUntil: "domcontentloaded" });
+    {
+      await session.page.goto(this.opts.startUrl, { waitUntil: "domcontentloaded" });
+      await settleAfterNavigation(session.page);
+    }
     this.initialized.add(id);
   }
   /** Back to one participant, between debug replays.
@@ -2805,7 +2833,7 @@ var ExecutionPages = class {
       await Promise.all(this.dialogTasks);
       if (this.unexpected) throw new Error(this.unexpected);
       if (this.expectedDialogs.length) throw new Error("The expected browser dialog did not appear");
-      if (step.downloads && JSON.stringify(downloads) !== JSON.stringify(step.downloads)) throw new Error(`Expected downloads ${step.downloads.join(", ")}; received ${downloads.join(", ") || "none"}`);
+      if (step.downloads && !downloadsMatch(step.downloads, downloads)) throw new Error(`Expected downloads ${step.downloads.join(", ")}; received ${downloads.join(", ") || "none"}`);
     } finally {
       page.off("download", onDownload);
       this.expectedDialogs = [];
@@ -2820,6 +2848,17 @@ var ExecutionPages = class {
     this.unexpected = null;
   }
 };
+var shapeOf = (name) => name.toLowerCase().replace(/[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}/g, "#").replace(/(?<![a-z0-9])[0-9a-f]{12,}(?![a-z0-9])/g, "#").replace(/\d+/g, "#").replace(/#([^a-z]*#)+/g, "#");
+function downloadsMatch(expected, received) {
+  if (expected.length !== received.length) return false;
+  const left = received.map(shapeOf);
+  for (const name of expected) {
+    const at = left.indexOf(shapeOf(name));
+    if (at === -1) return false;
+    left.splice(at, 1);
+  }
+  return true;
+}
 function rootFor(page, step) {
   let root = page;
   for (const frame of step.frame ?? []) root = root.frameLocator(frameSelector(frame));
@@ -2899,17 +2938,22 @@ async function scrollUntilFound(page, loc, budgetMs = 3e3) {
   for (let pass = 0; pass < PASSES && Date.now() < giveUpAt; pass++) {
     if (await loc.count() > 0) return true;
     const moved = await page.evaluate(() => {
-      const scrollable = [
-        document.scrollingElement,
-        ...Array.from(document.querySelectorAll("*"))
-      ].filter((el) => !!el && el.scrollHeight > el.clientHeight + 4);
-      let any = false;
-      for (const el of scrollable) {
+      const nudge = (el) => {
         const before = el.scrollTop;
         el.scrollTop = before + Math.max(80, el.clientHeight * 0.8);
-        if (el.scrollTop !== before) any = true;
-      }
-      return any;
+        return el.scrollTop !== before;
+      };
+      const page2 = document.scrollingElement;
+      if (page2 && page2.scrollHeight > page2.clientHeight + 4 && nudge(page2)) return true;
+      const areas = Array.from(document.querySelectorAll("*")).filter((el) => el.scrollHeight > el.clientHeight + 4 && el.clientHeight > 40).map((el) => {
+        const box = el.getBoundingClientRect();
+        const style = getComputedStyle(el);
+        const scrolls = /(auto|scroll|overlay)/.test(style.overflowY);
+        const shown = box.width > 0 && box.height > 0 && box.bottom > 0 && box.top < innerHeight && style.visibility !== "hidden";
+        return { el, area: scrolls && shown ? box.width * box.height : 0 };
+      }).filter((each) => each.area > 0).sort((a, b2) => b2.area - a.area);
+      for (const { el } of areas) if (nudge(el)) return true;
+      return false;
     }).catch(() => false);
     if (!moved) break;
     await page.waitForTimeout(120);
@@ -3422,6 +3466,7 @@ async function runStepsIn(session, steps, opts) {
   try {
     if (opts.startUrl && !opensItsOwnEntry(steps, opts)) {
       await page.goto(opts.startUrl, { waitUntil: "domcontentloaded" });
+      await settleAfterNavigation(page);
     }
     for (const recorded of steps) {
       let step = recorded;
@@ -3625,8 +3670,9 @@ async function runStepsIn(session, steps, opts) {
           // SAID OUT LOUD, on a step that passed. The element was found, but
           // not the way this step says it should be — something has moved,
           // and the run is the only place anybody would learn it.
-          onFallback: (_step, foundBy) => {
+          onFallback: (_step, foundBy, renamedTo) => {
             result.foundBy = foundBy;
+            if (renamedTo) result.renamedTo = renamedTo;
           }
         });
         try {
@@ -3815,6 +3861,7 @@ async function executeStep(main, input, options = {}) {
   const remaining = () => Math.max(1, deadline - Date.now());
   const navigationBudget = () => step.navigationTimeoutMs ?? options.navigationTimeoutMs ?? 45e3;
   page.setDefaultTimeout(remaining());
+  page.setDefaultNavigationTimeout(navigationBudget());
   const act = async () => {
     if (step.type === "unsupported") throw new Error(step.warning || step.value || "This interaction requires a supported action before replay");
     if (step.type === "assert") {
@@ -3823,6 +3870,7 @@ async function executeStep(main, input, options = {}) {
     }
     if (step.type === "navigate") {
       await page.goto(new URL(step.value, step.navigationBase === "application" ? options.baseUrl ?? page.url() : page.url()).href, { waitUntil: "domcontentloaded", timeout: navigationBudget() });
+      await settleAfterNavigation(page);
       return;
     }
     if (step.type === "closePage") {
@@ -3852,7 +3900,7 @@ async function executeStep(main, input, options = {}) {
     }
     const target = await ensureTarget(page, step, remaining());
     const loc = target.loc;
-    if (target.foundBy) options.onFallback?.(step, target.foundBy);
+    if (target.foundBy) options.onFallback?.(step, target.foundBy, target.renamedTo);
     page.setDefaultTimeout(remaining());
     await applyAction(loc, step, value, { resolveFile: options.resolveFile, dropTarget: await locateDrop(page, step) });
   };
@@ -3904,6 +3952,26 @@ async function applyScroll(page, step, timeout) {
   } catch {
   }
 }
+async function renamedFrom(page, step, found) {
+  if (!step.role || step.locator) return void 0;
+  try {
+    const first = (await found.ariaSnapshot({ timeout: 1e3 })).split("\n")[0] ?? "";
+    const parsed = /^- ([a-z]+) "((?:[^"\\]|\\.)*)"/.exec(first);
+    if (!parsed || parsed[1] !== step.role) return void 0;
+    const name = JSON.parse(`"${parsed[2]}"`).trim();
+    if (!name || name === step.name || name.length > 200) return void 0;
+    const { nameFrom: _from, candidates: _backups, ...rest } = step;
+    const [again] = await locateCandidates(page, { ...rest, name });
+    if (!again || await again.count() !== 1) return void 0;
+    const handle = await found.elementHandle({ timeout: 1e3 });
+    const same = handle ? await again.evaluate((el, other) => el === other, handle) : false;
+    await handle?.dispose().catch(() => {
+    });
+    return same ? name : void 0;
+  } catch {
+    return void 0;
+  }
+}
 async function ensureTarget(page, step, timeout) {
   const candidates = await locateCandidates(page, step);
   const described = describeLocators(step);
@@ -3920,7 +3988,10 @@ async function ensureTarget(page, step, timeout) {
   let crowded = null;
   for (let at = 1; at < candidates.length; at += 1) {
     const found = await candidates[at].count().catch(() => 0);
-    if (found === 1) return { loc: candidates[at], foundBy: described[at] ?? "another locator" };
+    if (found === 1) {
+      const renamedTo = await renamedFrom(page, step, candidates[at]);
+      return { loc: candidates[at], foundBy: described[at] ?? "another locator", ...renamedTo ? { renamedTo } : {} };
+    }
     if (found > 1 && !crowded) crowded = { where: described[at] ?? "another locator", count: found };
   }
   if (several) throw Object.assign(several, { kind: "ambiguous" });
@@ -5261,6 +5332,45 @@ async function fieldNames(page) {
     return found;
   }).catch(() => []);
 }
+async function backupsFor(page, step) {
+  if (!step.role || !step.name || step.locator) return [];
+  try {
+    const [primary] = await locateCandidates(page, step);
+    if (!primary || await primary.count() !== 1) return [];
+    return await primary.evaluate((el) => {
+      const clean = (s2) => (s2 ?? "").replace(/\s+/g, " ").trim();
+      const root = el.getRootNode();
+      const unique = (selector) => {
+        try {
+          return root.querySelectorAll(selector).length === 1;
+        } catch {
+          return false;
+        }
+      };
+      const found = [];
+      const testId = el.getAttribute("data-testid");
+      if (testId && unique(`[data-testid=${JSON.stringify(testId)}]`)) found.push({ strategy: "testId", value: testId });
+      const placeholder = el.getAttribute("placeholder");
+      if (clean(placeholder) && unique(`[placeholder=${JSON.stringify(placeholder)}]`)) found.push({ strategy: "placeholder", value: clean(placeholder) });
+      const alt = el.getAttribute("alt");
+      if (clean(alt) && unique(`[alt=${JSON.stringify(alt)}]`)) found.push({ strategy: "altText", value: clean(alt) });
+      const title = el.getAttribute("title");
+      if (clean(title) && unique(`[title=${JSON.stringify(title)}]`)) found.push({ strategy: "title", value: clean(title) });
+      if (el.id && !/:r|[a-f0-9]{12}|\d{6}/i.test(el.id) && unique(`#${CSS.escape(el.id)}`)) {
+        found.push({ strategy: "css", value: `#${CSS.escape(el.id)}` });
+      }
+      return found.slice(0, 4);
+    }, void 0, { timeout: 1e3 });
+  } catch {
+    return [];
+  }
+}
+function withBackups(target, backups) {
+  if (!backups.length) return target;
+  const seen = new Set((target.candidates ?? []).map((c) => `${c.strategy}\0${c.value}`));
+  const merged = [...target.candidates ?? [], ...backups.filter((b2) => !seen.has(`${b2.strategy}\0${b2.value}`))].slice(0, 4);
+  return { ...target, candidates: merged };
+}
 var playwrightVersion2 = () => {
   try {
     return createRequire22(import.meta.url)("playwright/package.json").version;
@@ -6106,8 +6216,18 @@ var SqliteStorage = class {
              ) AS rn FROM run
            ) WHERE rn > ?`
       ).all(keep).map((r) => String(r.id));
+      const dirOf = this.handle.prepare("SELECT artifacts_dir FROM run WHERE id=?");
       const stmt = this.handle.prepare("DELETE FROM run WHERE id=?");
-      for (const id of doomed) stmt.run(id);
+      for (const id of doomed) {
+        const dir = dirOf.get(id)?.artifacts_dir;
+        stmt.run(id);
+        if (typeof dir === "string" && dir) {
+          try {
+            fs5.rmSync(dir, { recursive: true, force: true });
+          } catch {
+          }
+        }
+      }
       return doomed;
     });
   }
@@ -6912,7 +7032,7 @@ function ensureRootCommit(root) {
 }
 
 // ../helpers/dist/index.js
-import { createHmac as createHmac2 } from "crypto";
+import { createHash, createHmac as createHmac2 } from "crypto";
 var HelperFailure = class extends Error {
   constructor(message) {
     super(message);
@@ -6978,11 +7098,12 @@ function totp(secretBase32, at, options = {}) {
   const remaining = period - Math.floor(at / 1e3 % period);
   return { code, remaining };
 }
-async function imapMailbox(config, password) {
+async function imapMailbox(config, password, target = { host: config.host }) {
   const { ImapFlow } = await import("imapflow");
   const { simpleParser } = await import("mailparser");
   const client = new ImapFlow({
-    host: config.host,
+    host: target.host,
+    ...target.servername ? { servername: target.servername } : {},
     port: config.port,
     secure: config.secure,
     auth: { user: config.username, pass: password },
@@ -7041,7 +7162,8 @@ async function runMailbox(config, ctx) {
     subject: fill(config.match.subject, ctx.inputs),
     since: ctx.since ?? null
   };
-  const mailbox = await (ctx.openMailbox ?? imapMailbox)(config, secret(ctx, config.passwordRef, "mailbox password"));
+  const password = secret(ctx, config.passwordRef, "mailbox password");
+  const mailbox = ctx.openMailbox ? await ctx.openMailbox(config, password) : await imapMailbox(config, password, ctx.connectTo ? await ctx.connectTo(config.host) : void 0);
   const deadline = now() + config.waitSeconds * 1e3;
   try {
     for (; ; ) {
@@ -7164,6 +7286,82 @@ async function runHttp(config, ctx) {
     }
   }
 }
+function commandFingerprint(config, system) {
+  const line = commandFor(config, system);
+  const written = JSON.stringify({
+    program: line.program,
+    args: line.args,
+    folder: config.folder,
+    env: config.env,
+    secretEnv: Object.keys(config.secretEnv).sort(),
+    mode: config.mode,
+    readyPattern: config.readyPattern
+  });
+  return createHash("sha256").update(written).digest("hex").slice(0, 16);
+}
+var lastLine = (text) => text.trim().split(/\r?\n/).filter(Boolean).pop() ?? "";
+async function runCommand(config, ctx, name) {
+  if (!ctx.commands) {
+    throw new HelperFailure("this helper runs a command on a tester's computer \u2014 try it, and run tests that use it, from a computer running the Flowriki agent");
+  }
+  const system = ctx.system ?? commandSystemOf(process.platform);
+  const line = commandFor(config, system);
+  const env = {};
+  for (const [key, value] of Object.entries(config.env)) env[key] = fill(value, ctx.inputs);
+  const redact2 = [];
+  for (const [key, ref] of Object.entries(config.secretEnv)) {
+    const value = secret(ctx, ref, `${key} secret`);
+    env[key] = value;
+    redact2.push(value);
+  }
+  const outcome = await ctx.commands.run({
+    name,
+    fingerprint: commandFingerprint(config, system),
+    program: fill(line.program, ctx.inputs),
+    // EACH ARGUMENT FILLED ON ITS OWN: a value is never split into two, and
+    // never read by a shell.
+    args: line.args.map((arg) => fill(arg, ctx.inputs)),
+    folder: fill(config.folder, ctx.inputs),
+    env,
+    redact: redact2,
+    mode: config.mode,
+    readyPattern: config.readyPattern,
+    timeoutMs: config.timeoutSeconds * 1e3
+  });
+  const evidence = {
+    ...outcome.exitCode === null ? { state: config.mode === "background" ? "running until the test ends" : "stopped" } : { "exit code": String(outcome.exitCode) },
+    ...lastLine(outcome.stdout) ? { "last line": lastLine(outcome.stdout).slice(0, 200) } : {}
+  };
+  if (config.mode === "run" && outcome.exitCode !== config.expectExit) {
+    const why = lastLine(outcome.stderr) || lastLine(outcome.stdout);
+    throw new HelperFailure(`the command ended with exit code ${outcome.exitCode ?? "?"}${config.expectExit ? ` (expected ${config.expectExit})` : ""}${why ? `: ${why.slice(0, 300)}` : ""}`);
+  }
+  const text = outcome.stdout;
+  switch (config.extract.take) {
+    case "nothing":
+      return { value: "", detail: config.mode === "background" ? "started, and runs until the test ends" : "it ran", evidence };
+    case "output": {
+      const value = text.trim();
+      return { value: value.length > 2e3 ? lastLine(value) : value, detail: "what the command printed", evidence };
+    }
+    case "pattern": {
+      const value = takeCode(text, config.extract.pattern);
+      if (value === null) throw new HelperFailure(`the command printed nothing matching ${config.extract.pattern}`);
+      return { value, detail: "the match in what the command printed", evidence };
+    }
+    case "json": {
+      let parsed;
+      try {
+        parsed = JSON.parse(text);
+      } catch {
+        throw new HelperFailure("the command did not print JSON");
+      }
+      const value = atPath(parsed, config.extract.path);
+      if (value === void 0 || value === null) throw new HelperFailure(`what the command printed has no "${config.extract.path}"`);
+      return { value: typeof value === "string" ? value : JSON.stringify(value), detail: `"${config.extract.path}" from what the command printed`, evidence };
+    }
+  }
+}
 async function runHelper(helper, ctx) {
   const config = "config" in helper ? helper.config : helper;
   switch (config.kind) {
@@ -7177,11 +7375,17 @@ async function runHelper(helper, ctx) {
       return runSms(config, ctx);
     case "http":
       return runHttp(config, ctx);
+    case "command":
+      return runCommand(config, ctx, "name" in helper ? helper.name : "this command");
   }
 }
 
 // ../execution/dist/index.js
+import { spawn as spawn2 } from "child_process";
 import fs24 from "fs";
+import os5 from "os";
+import path24 from "path";
+import fs34 from "fs";
 import crypto3 from "crypto";
 async function cloudBrowserFor(config, secrets, name) {
   const settings = config ?? {};
@@ -7195,6 +7399,7 @@ async function cloudBrowserFor(config, secrets, name) {
   return connectCloudBrowser(account, key, choice, name);
 }
 var LOCAL_CHROMIUM = { id: "chromium", provider: "local", engine: "chromium" };
+var KEEP_RUNS_LOCALLY = 50;
 async function executeFlow(opts) {
   const { store, storage = null, flowId, trigger, watch = false, onEvent } = opts;
   const headless = watch ? false : opts.headless ?? store.readConfig().headless;
@@ -7354,6 +7559,7 @@ async function executeFlow(opts) {
         writes.push(emit({ type: "run.step", runId: run?.id ?? "", flowId: flow.id, result }));
       }
     });
+    store.runHelper?.close?.();
     if (storage && taskId && run) {
       const reached = new Set(outcome.steps.map((r) => r.stepId));
       for (const step of flow.steps) {
@@ -7431,6 +7637,7 @@ async function executeFlow(opts) {
       artifactsDir: runDir && fs7.existsSync(runDir) ? runDir : null
     });
   }
+  if (storage) void storage.pruneRuns(KEEP_RUNS_LOCALLY).catch(() => void 0);
   await emit({ type: "run.finished", runId: run?.id ?? "", flowId: flow.id, outcome: last });
   return {
     outcome: last,
@@ -7518,27 +7725,203 @@ function toStepRow(ordinal, result, step) {
     checks
   };
 }
+var home = () => process.env["FLOWRIKI_HOME"] || path24.join(os5.homedir(), ".flowriki");
+var approvalsFile = () => path24.join(home(), "allowed-commands.json");
+function readApprovals() {
+  try {
+    const parsed = JSON.parse(fs24.readFileSync(approvalsFile(), "utf8"));
+    return { allowed: parsed.allowed ?? {}, waiting: parsed.waiting ?? {} };
+  } catch {
+    return { allowed: {}, waiting: {} };
+  }
+}
+function writeApprovals(approvals) {
+  fs24.mkdirSync(home(), { recursive: true, mode: 448 });
+  const temporary = `${approvalsFile()}.${process.pid}.tmp`;
+  fs24.writeFileSync(temporary, JSON.stringify(approvals, null, 2), { mode: 384 });
+  fs24.renameSync(temporary, approvalsFile());
+}
+function allowCommands(which) {
+  const approvals = readApprovals();
+  const wanted = which.trim().toLowerCase();
+  const chosen = Object.values(approvals.waiting).filter((c) => wanted === "all" || c.fingerprint === wanted || c.name.toLowerCase() === wanted);
+  for (const command of chosen) {
+    approvals.allowed[command.fingerprint] = { ...command, at: (/* @__PURE__ */ new Date()).toISOString() };
+    delete approvals.waiting[command.fingerprint];
+  }
+  if (chosen.length) writeApprovals(approvals);
+  return chosen;
+}
+function revokeCommands(which) {
+  const approvals = readApprovals();
+  const wanted = which.trim().toLowerCase();
+  const chosen = Object.values(approvals.allowed).filter((c) => wanted === "all" || c.fingerprint === wanted || c.name.toLowerCase() === wanted);
+  for (const command of chosen) delete approvals.allowed[command.fingerprint];
+  if (chosen.length) writeApprovals(approvals);
+  return chosen;
+}
+var CommandNotAllowed = class extends HelperFailure {
+  constructor(command) {
+    super(`"${command.name}" has not been allowed on this computer yet. In a terminal here, run: flowriki-agent allow "${command.name}" \u2014 it shows the command before allowing it.`);
+    this.command = command;
+    this.name = "CommandNotAllowed";
+  }
+  command;
+  code = "command_not_allowed";
+};
+var KEEP_BYTES = 64 * 1024;
+var BACKGROUND_LIMIT_MS = 30 * 6e4;
+var SETTLE_MS = 2e3;
+var running = /* @__PURE__ */ new Set();
+process.once("exit", () => {
+  for (const child of running) {
+    try {
+      child.kill("SIGKILL");
+    } catch {
+    }
+  }
+});
+function stop(child) {
+  if (child.exitCode !== null || child.signalCode !== null) return;
+  try {
+    child.kill("SIGTERM");
+  } catch {
+  }
+  const hard = setTimeout(() => {
+    try {
+      child.kill("SIGKILL");
+    } catch {
+    }
+  }, 2e3);
+  hard.unref();
+}
+function launchLine(program, args) {
+  if (process.platform === "win32" && /\.(cmd|bat)$/i.test(program)) {
+    const unsafe = [program, ...args].find((part) => /[&|<>^%!"]/.test(part));
+    if (unsafe !== void 0) throw new HelperFailure(`on Windows a .cmd or .bat cannot take "${unsafe}" \u2014 those characters mean something to cmd.exe`);
+    return { file: process.env["ComSpec"] || "cmd.exe", args: ["/d", "/c", program, ...args] };
+  }
+  return { file: program, args };
+}
+function localCommandRunner(opts) {
+  const mine = /* @__PURE__ */ new Set();
+  const trustAll = opts.trustAll ?? process.env["FLOWRIKI_TRUST_COMMANDS"] === "1";
+  const run = async (request) => {
+    const record = {
+      fingerprint: request.fingerprint,
+      name: request.name,
+      program: request.program,
+      args: request.args,
+      folder: request.folder,
+      env: Object.keys(request.env),
+      mode: request.mode,
+      at: (/* @__PURE__ */ new Date()).toISOString()
+    };
+    if (!trustAll) {
+      const approvals = readApprovals();
+      if (!approvals.allowed[request.fingerprint]) {
+        approvals.waiting[request.fingerprint] = record;
+        try {
+          writeApprovals(approvals);
+        } catch {
+        }
+        throw new CommandNotAllowed(record);
+      }
+    }
+    const cwd = request.folder ? path24.resolve(opts.root, request.folder) : opts.root;
+    if (!fs24.existsSync(cwd)) throw new HelperFailure(`the folder ${cwd} does not exist on this computer`);
+    const blank = (text) => request.redact.reduce((out, secret2) => secret2 ? out.split(secret2).join("\u2022\u2022\u2022") : out, text);
+    const line = launchLine(request.program, request.args);
+    return await new Promise((resolve2, reject) => {
+      let stdout = "", stderr = "", settled = false;
+      let child;
+      try {
+        child = spawn2(line.file, line.args, { cwd, env: { ...process.env, ...request.env }, shell: false, windowsHide: true, stdio: ["ignore", "pipe", "pipe"] });
+      } catch (error) {
+        reject(new HelperFailure(`${request.program} could not be started: ${error.message}`));
+        return;
+      }
+      running.add(child);
+      mine.add(child);
+      const forget = () => {
+        running.delete(child);
+        mine.delete(child);
+      };
+      const finish = (outcome) => {
+        if (settled) return;
+        settled = true;
+        clearTimeout(timer);
+        if (outcome instanceof Error) reject(outcome);
+        else resolve2(outcome);
+      };
+      const ready = request.readyPattern ? new RegExp(request.readyPattern) : null;
+      const take = (into) => (chunk) => {
+        const text = chunk.toString();
+        if (into === "out") stdout = (stdout + text).slice(-KEEP_BYTES);
+        else stderr = (stderr + text).slice(-KEEP_BYTES);
+        if (request.mode === "background" && ready && ready.test(into === "out" ? stdout : stderr)) {
+          finish({ exitCode: null, stdout: blank(stdout), stderr: blank(stderr) });
+        }
+      };
+      child.stdout?.on("data", take("out"));
+      child.stderr?.on("data", take("err"));
+      child.on("error", (error) => {
+        forget();
+        finish(new HelperFailure(error.code === "ENOENT" ? `${request.program} was not found on this computer \u2014 install it, or give its full path` : `${request.program} could not be started: ${error.message}`));
+      });
+      child.on("close", (code) => {
+        forget();
+        if (request.mode === "background" && !settled) {
+          const why = (stderr || stdout).trim().split(/\r?\n/).pop() ?? "";
+          finish(new HelperFailure(`the command stopped before it was ready (exit ${code ?? "?"})${why ? `: ${blank(why).slice(0, 300)}` : ""}`));
+          return;
+        }
+        finish({ exitCode: code, stdout: blank(stdout), stderr: blank(stderr) });
+      });
+      const timer = request.mode === "background" && !ready ? setTimeout(() => finish({ exitCode: null, stdout: blank(stdout), stderr: blank(stderr) }), Math.min(SETTLE_MS, request.timeoutMs)) : setTimeout(() => {
+        stop(child);
+        finish(new HelperFailure(request.mode === "background" ? `the command did not say it was ready within ${Math.round(request.timeoutMs / 1e3)}s` : `the command did not finish within ${Math.round(request.timeoutMs / 1e3)}s, so it was stopped`));
+      }, request.timeoutMs);
+      if (request.mode === "background") {
+        const limit = setTimeout(() => stop(child), BACKGROUND_LIMIT_MS);
+        limit.unref();
+      }
+    });
+  };
+  return {
+    run,
+    /** Stop every background command this runner started — the test is over. */
+    close: () => {
+      for (const child of mine) stop(child);
+      mine.clear();
+    }
+  };
+}
 var CLOCK_SLACK_MS = 1e4;
-function helperRunner(delivered, secrets, startedAt = /* @__PURE__ */ new Date()) {
+function helperRunner(delivered, secrets, startedAt = /* @__PURE__ */ new Date(), root = process.cwd()) {
   if (!Array.isArray(delivered) || delivered.length === 0) return void 0;
   const helpers = new Map(
     DeliveredHelperSchema.array().parse(delivered).map((helper) => [helper.id, helper])
   );
   const since = new Date(startedAt.getTime() - CLOCK_SLACK_MS);
-  return async (helperId, inputs) => {
+  const commands = [...helpers.values()].some((h) => h.config.kind === "command") ? localCommandRunner({ root }) : void 0;
+  const run = (async (helperId, inputs) => {
     const helper = helpers.get(helperId);
     if (!helper) throw new Error("that helper was deleted, or was not sent with this run \u2014 choose another");
     try {
-      const { value, detail } = await runHelper(helper.config, {
+      const { value, detail } = await runHelper(helper, {
         resolveSecret: (ref) => secrets?.[ref],
         inputs,
-        since
+        since,
+        ...commands ? { commands } : {}
       });
       return { value, detail: `${helper.name}: ${detail}` };
     } catch (error) {
       throw new Error(`${helper.name}: ${error.message}`);
     }
-  };
+  });
+  run.close = () => commands?.close();
+  return run;
 }
 var LOCAL_CHROMIUM2 = { id: "chromium", provider: "local", engine: "chromium" };
 async function summaryOf2(storage, runId) {
@@ -7712,6 +8095,7 @@ async function executeCase(opts) {
     };
   }
   await cloud?.close().catch(() => void 0);
+  helpers?.close();
   if (lane) outcome = { ...outcome, artifacts: [...outcome.artifacts ?? [], ...await lane.close(outcome.status === "passed")] };
   await Promise.all(writes);
   if (storage && run) {
@@ -7733,10 +8117,11 @@ async function executeCase(opts) {
         masked: false
       });
     }
+    void storage.pruneRuns(50).catch(() => void 0);
     await storage.finishRun(run.id, {
       status: outcome.status === "passed" ? "passed" : outcome.error === "the run was cancelled" ? "cancelled" : outcome.status === "failed" ? "failed" : "errored",
       errorMessage: outcome.error,
-      artifactsDir: runDir && fs24.existsSync(runDir) ? runDir : null
+      artifactsDir: runDir && fs34.existsSync(runDir) ? runDir : null
     });
   }
   await emit({ type: "case.finished", runId: run?.id ?? "", caseId: testCase.id, outcome });
@@ -7750,6 +8135,10 @@ function redactPanel(state) {
   return { ...panel, steps: panel.steps.map((s2) => redact(s2)) };
 }
 var START_GRACE_MS = 3e3;
+var IDLE_MS = (() => {
+  const minutes = Number(process.env["FLOWRIKI_RECORDING_IDLE_MINUTES"] ?? 30);
+  return Number.isFinite(minutes) && minutes >= 0 ? minutes * 6e4 : 30 * 6e4;
+})();
 var RecordingCoordinator = class {
   constructor(deps) {
     this.deps = deps;
@@ -7773,6 +8162,33 @@ var RecordingCoordinator = class {
    * than rebuilding it from the event, which would either lose the values or
    * publish them. */
   lastResult = null;
+  /** When somebody last did anything in the recording. */
+  touchedAt = 0;
+  panelSeen = "";
+  idleTimer = null;
+  stoppingForIdle = false;
+  touch() {
+    this.touchedAt = Date.now();
+  }
+  watchIdle() {
+    const limit = this.deps.idleMs ?? IDLE_MS;
+    this.stopWatchingIdle();
+    if (limit <= 0) return;
+    this.touch();
+    this.idleTimer = setInterval(() => {
+      if (!this.session || this.stopInFlight || Date.now() - this.touchedAt < limit) return;
+      this.stopWatchingIdle();
+      this.stoppingForIdle = true;
+      void (this.draft?.steps.length ? this.stop() : this.discard()).finally(() => {
+        this.stoppingForIdle = false;
+      });
+    }, Math.min(this.deps.idleCheckMs ?? 6e4, limit));
+    this.idleTimer.unref?.();
+  }
+  stopWatchingIdle() {
+    if (this.idleTimer) clearInterval(this.idleTimer);
+    this.idleTimer = null;
+  }
   /** What the last completed stop answered, for a caller that missed it —
    *  a dropped socket, or a Stop pressed inside the recorded page. */
   lastStop() {
@@ -7796,6 +8212,7 @@ var RecordingCoordinator = class {
   }
   async answerDialog(accept, promptText) {
     if (!this.session) throw new Error("No recording is active");
+    this.touch();
     await this.session.answerDialog(accept, promptText);
   }
   /** Open a headed browser and start capturing.
@@ -7871,18 +8288,29 @@ var RecordingCoordinator = class {
         // a file nothing ever read.
         environment: ExecutionEnvironmentSchema.parse(opts.environment ?? config.environment),
         headless: opts.headless ?? false,
-        onStep: (step) => this.upsert(step),
+        onStep: (step) => {
+          this.touch();
+          this.upsert(step);
+        },
         // The panel carries its OWN copy of every step, and it used to be
         // emitted exactly as the session built it — so while `recording.step`
         // was carefully redacted, the very next frame published the same step
         // with the password still in it. Found by a test that typed a real
         // password into a real browser; nothing about the redacted step event
         // hinted at it.
-        onState: (state) => this.deps.emit({ type: "recording.panel", state: redactPanel(state) }),
+        onState: (state) => {
+          const seen = JSON.stringify(state);
+          if (seen !== this.panelSeen) {
+            this.panelSeen = seen;
+            this.touch();
+          }
+          this.deps.emit({ type: "recording.panel", state: redactPanel(state) });
+        },
         // Stop pressed on the floating control inside the recorded page.
         onStopRequested: (commit) => void (commit ? this.stop() : this.discard()),
         onDisconnect: () => {
           this.session = null;
+          this.stopWatchingIdle();
           this.deps.lease?.release("recording");
           this.deps.emit({ type: "recording.interrupted" });
         }
@@ -7898,6 +8326,7 @@ var RecordingCoordinator = class {
     const projectOrigin = configuredBase ? new URL(normalizeStartUrl(configuredBase)).origin : "";
     this.draft.baseUrl = opened.origin === projectOrigin ? "" : opened.origin;
     this.draft.startPath = opened.pathname + opened.search;
+    this.watchIdle();
     this.deps.emit({ type: "recording.started", name: this.draft.name, url: this.session.startUrl });
     return null;
   }
@@ -7921,6 +8350,7 @@ var RecordingCoordinator = class {
    * followed by an await, so two stops arriving together could otherwise both
    * pass it and save the flow twice. */
   stop() {
+    this.stopWatchingIdle();
     if (!this.stopInFlight) {
       this.deps.lease?.beginRelease("recording");
       this.stopInFlight = this.doStop().finally(() => {
@@ -7969,7 +8399,7 @@ var RecordingCoordinator = class {
     const file2 = this.deps.store.saveFlow(doc);
     this.draft = null;
     const saved = { ...this.deps.store.getFlow(doc.id) ?? doc, path: file2 };
-    this.deps.emit({ type: "recording.stopped", flow: saved, file: file2 });
+    this.deps.emit({ type: "recording.stopped", flow: saved, file: file2, ...this.stoppingForIdle ? { reason: "idle" } : {} });
     return this.lastResult = { ok: true, flow: saved, secrets: captured };
   }
   /** Throw the recording away: close the browser, drop the draft, write
@@ -7980,6 +8410,7 @@ var RecordingCoordinator = class {
    * time — a password briefly reaches disk for a recording nobody wanted. */
   async discard() {
     if (!this.draft && !this.session) return { ok: false, error: "no recording in progress" };
+    this.stopWatchingIdle();
     this.deps.lease?.beginRelease("recording");
     const ending = this.session;
     this.session = null;
@@ -8122,15 +8553,41 @@ var COMMANDS = /* @__PURE__ */ new Set([
 ]);
 var UnknownDebugCommand = class extends Error {
 };
+var DEBUG_IDLE_MS = (() => {
+  const minutes = Number(process.env["FLOWRIKI_RECORDING_IDLE_MINUTES"] ?? 30);
+  return Number.isFinite(minutes) && minutes >= 0 ? minutes * 6e4 : 30 * 6e4;
+})();
 var DebugCoordinator = class {
   constructor(deps) {
     this.deps = deps;
   }
   deps;
+  touchedAt = 0;
+  stateSeen = "";
+  /** The steps as the session opened them: unchanged means nothing to lose. */
+  openedWith = "";
+  idleTimer = null;
   retainCompleted = false;
   lastState = null;
   lastEnd = null;
   current = null;
+  watchIdle() {
+    this.stopWatchingIdle();
+    const limit = this.deps.idleMs ?? DEBUG_IDLE_MS;
+    if (limit <= 0) return;
+    this.touchedAt = Date.now();
+    this.idleTimer = setInterval(() => {
+      if (!this.current || Date.now() - this.touchedAt < limit) return;
+      if (JSON.stringify(this.current.session.state().steps) !== this.openedWith) return;
+      this.stopWatchingIdle();
+      void this.end(false).catch(() => void 0);
+    }, Math.min(this.deps.idleCheckMs ?? 6e4, limit));
+    this.idleTimer.unref?.();
+  }
+  stopWatchingIdle() {
+    if (this.idleTimer) clearInterval(this.idleTimer);
+    this.idleTimer = null;
+  }
   status() {
     return this.current ? { flowId: this.current.flowId, state: this.current.session.state() } : this.lastEnd?.ok && this.lastEnd.flow && this.lastState ? { flowId: this.lastEnd.flow.id, state: this.lastState } : { flowId: null, state: null };
   }
@@ -8169,11 +8626,19 @@ var DebugCoordinator = class {
         // Secrets are read on THIS machine and handed to the browser here. A
         // hosted dashboard drives the session and never learns a value.
         resolveSecret: (ref) => secrets[ref],
-        onState: (state2) => this.deps.emit({ type: "debug.state", flowId: flow.id, state: state2 }),
+        onState: (state2) => {
+          const seen = JSON.stringify(state2);
+          if (seen !== this.stateSeen) {
+            this.stateSeen = seen;
+            this.touchedAt = Date.now();
+          }
+          this.deps.emit({ type: "debug.state", flowId: flow.id, state: state2 });
+        },
         // Save & close / Discard, pressed on the panel inside the page.
         onEndRequested: (commit) => void this.end(commit),
         onDisconnect: () => {
           this.current = null;
+          this.stopWatchingIdle();
           this.deps.lease?.release("debug");
           this.deps.emit({ type: "debug.ended", flowId: flow.id, committed: false });
         }
@@ -8181,6 +8646,8 @@ var DebugCoordinator = class {
       this.deps.lease?.activate("debug");
       this.current = { flowId: flow.id, session };
       const state = session.state();
+      this.openedWith = JSON.stringify(state.steps);
+      this.watchIdle();
       this.deps.emit({ type: "debug.state", flowId: flow.id, state });
       return { flowId: flow.id, state };
     } catch (err) {
@@ -8191,6 +8658,7 @@ var DebugCoordinator = class {
   async command(command, args = {}) {
     if (!this.current) throw new Error("no debug session is running");
     if (!COMMANDS.has(command)) throw new UnknownDebugCommand(`unknown command: ${command}`);
+    this.touchedAt = Date.now();
     const s2 = this.current.session;
     switch (command) {
       case "play":
@@ -8233,6 +8701,7 @@ var DebugCoordinator = class {
     }
     const { flowId, session } = this.current;
     this.current = null;
+    this.stopWatchingIdle();
     this.deps.lease?.beginRelease("debug");
     try {
       if (!commit) {
@@ -8337,10 +8806,10 @@ async function verifyFlowSteps(deps, opts) {
 }
 function deliveredRun(delivered) {
   const { flow, secrets, config } = delivered;
-  const runHelper2 = helperRunner(delivered.helpers, secrets);
+  const runHelper3 = helperRunner(delivered.helpers, secrets);
   return {
     resolveAuth: authenticationResolver(delivered.authentications),
-    ...runHelper2 ? { runHelper: runHelper2 } : {},
+    ...runHelper3 ? { runHelper: runHelper3 } : {},
     readConfig: () => config,
     // By id, and only the one that was sent. A machine serving no checkout has
     // no other flow to confuse it with.
@@ -8388,7 +8857,7 @@ function resolveCheckouts(dirs) {
 // src/engine/session.ts
 import fs12 from "fs";
 
-// ../agent-core/dist/chunk-YAPHJ4AT.js
+// ../agent-core/dist/chunk-CRKFBFSC.js
 import { WebSocket, WebSocketServer } from "ws";
 var HEARTBEAT_MS = 3e4;
 function adapt(socket) {
@@ -8565,6 +9034,27 @@ var EventJournal = class {
   }
 };
 var { DatabaseSync } = createRequire4(import.meta.url)("node:sqlite");
+var LOCAL_LIMIT = 64 * 1024;
+function fitted(value, limit = LOCAL_LIMIT) {
+  const text = JSON.stringify(value);
+  if (Buffer.byteLength(text) <= limit) return text;
+  for (const [maxText, maxItems] of [[2e3, 400], [500, 120], [200, 40], [80, 12]]) {
+    const smaller = JSON.stringify(shrink(value, maxText, maxItems));
+    if (Buffer.byteLength(smaller) <= limit) return smaller;
+  }
+  throw new Error("event exceeds local size limit even when shortened");
+}
+function shrink(value, maxText, maxItems) {
+  if (typeof value === "string") return value.length > maxText ? `${value.slice(0, maxText)}\u2026 (cut)` : value;
+  if (Array.isArray(value)) {
+    const items = value.length > maxItems ? [...value.slice(0, Math.ceil(maxItems / 2)), `\u2026 ${value.length - maxItems} left out`, ...value.slice(-Math.floor(maxItems / 2))] : value;
+    return items.map((v) => shrink(v, maxText, maxItems));
+  }
+  if (value && typeof value === "object") {
+    return Object.fromEntries(Object.entries(value).map(([k, v]) => [k, shrink(v, maxText, maxItems)]));
+  }
+  return value;
+}
 var AgentState = class {
   constructor(file2, deviceId, commandLimit = 1e5) {
     this.commandLimit = commandLimit;
@@ -8635,6 +9125,10 @@ var AgentState = class {
   begin(command, fingerprint2) {
     return this.transaction(() => {
       if (this.get(command.id)) return false;
+      if (Number(this.db.prepare("SELECT count(*) AS n FROM commands").get()?.n) >= this.commandLimit) {
+        const cutoff = (command.issuedAt ?? command.expiresAt) - 30 * 24 * 60 * 6e4;
+        if (cutoff > 0) this.db.prepare("DELETE FROM commands WHERE state IN ('completed','retired') AND finished_at < ?").run(cutoff);
+      }
       if (Number(this.db.prepare("SELECT count(*) AS n FROM commands").get()?.n) >= this.commandLimit) {
         throw new Error("command ledger capacity reached; retain state and reconcile before further work");
       }
@@ -8643,8 +9137,7 @@ var AgentState = class {
     });
   }
   finish(id, ack, now) {
-    const text = JSON.stringify(AckSchema.parse(ack));
-    if (Buffer.byteLength(text) > 64 * 1024) throw new Error("command result exceeds local size limit");
+    const text = fitted(AckSchema.parse(ack));
     const result = this.db.prepare("UPDATE commands SET state='completed', ack=?, finished_at=? WHERE id=? AND state='started'").run(text, now, id);
     if (Number(result.changes) !== 1) throw new Error("command intent is unavailable");
   }
@@ -8657,8 +9150,7 @@ var AgentState = class {
     this.db.prepare("UPDATE commands SET state='retired', ack=NULL WHERE state='completed' AND finished_at < ? AND expires_at <= ?").run(cutoff, now);
   }
   append(event, limit) {
-    const text = JSON.stringify(event);
-    if (Buffer.byteLength(text) > 64 * 1024) throw new Error("event exceeds local size limit");
+    const text = fitted(event);
     return this.transaction(() => {
       const row = this.db.prepare("INSERT INTO events(payload) VALUES (?)").run(text);
       const seq = Number(row.lastInsertRowid) - 1;
@@ -8687,6 +9179,13 @@ var AgentState = class {
     this.db.close();
   }
 };
+function withoutSecrets(value) {
+  if (Array.isArray(value)) return value.map(withoutSecrets);
+  if (value && typeof value === "object") {
+    return Object.fromEntries(Object.entries(value).map(([k, v]) => [k, k === "secrets" ? {} : withoutSecrets(v)]));
+  }
+  return value;
+}
 var Agent = class {
   constructor(opts) {
     this.opts = opts;
@@ -8785,10 +9284,10 @@ var Agent = class {
     if (!allowed.ok) return this.refuse(command.id, allowed.reason);
     if (this.closed) return this.refuse(command.id, "storage_unavailable", "the agent is closed");
     const fingerprint2 = AgentState.fingerprint(command);
-    const running = this.inFlight.get(command.id);
-    if (running) {
-      if (running.fingerprint !== fingerprint2) return this.refuse(command.id, "command_conflict", "this command ID names different work");
-      return { ...await running.promise, status: "duplicate" };
+    const running2 = this.inFlight.get(command.id);
+    if (running2) {
+      if (running2.fingerprint !== fingerprint2) return this.refuse(command.id, "command_conflict", "this command ID names different work");
+      return { ...await running2.promise, status: "duplicate" };
     }
     const previous = this.previous(command.id, fingerprint2);
     if (previous) return previous;
@@ -8824,7 +9323,7 @@ var Agent = class {
       ack = this.refuse(command.id, "failed", String(err instanceof Error ? err.message : err).split("\n")[0]);
     }
     if (EFFECTFUL.has(command.name)) {
-      this.state.finish(command.id, ack, this.now());
+      this.state.finish(command.id, withoutSecrets(ack), this.now());
     }
     return ack;
   }
@@ -8989,18 +9488,19 @@ var AgentLink = class {
 
 // ../provider-local/dist/index.js
 import fs10 from "fs";
-import os5 from "os";
+import os6 from "os";
 import path10 from "path";
 import fs25 from "fs";
-import path24 from "path";
+import path25 from "path";
 import { randomUUID } from "crypto";
 import { execFile } from "child_process";
-import fs34 from "fs";
+import fs35 from "fs";
 import path34 from "path";
 import { randomUUID as randomUUID2 } from "crypto";
+import os22 from "os";
 import { spawn as nodeSpawn } from "child_process";
 import fs43 from "fs";
-import os22 from "os";
+import os32 from "os";
 import path42 from "path";
 var NO_CHECKOUT = {
   ok: false,
@@ -9011,7 +9511,7 @@ var scratchRoots = /* @__PURE__ */ new Map();
 function scratchRoot(projectId) {
   let root = scratchRoots.get(projectId);
   if (!root) {
-    root = fs10.mkdtempSync(path10.join(os5.tmpdir(), `flowriki-record-${projectId.replace(/[^\w-]/g, "")}-`));
+    root = fs10.mkdtempSync(path10.join(os6.tmpdir(), `flowriki-record-${projectId.replace(/[^\w-]/g, "")}-`));
     scratchRoots.set(projectId, root);
   }
   return root;
@@ -9245,7 +9745,7 @@ function historyHandlers({ storage, artifactLimit }) {
       const artifact = run.artifacts.find((a) => a.id === artifactId);
       if (!artifact) return { ok: false, reason: "failed", detail: "no such artifact on that run" };
       const dir = run.artifactsDir ?? runArtifactsDir(runId, run.projectId);
-      const file2 = path24.join(dir, artifact.relPath);
+      const file2 = path25.join(dir, artifact.relPath);
       if (!isInside(dir, file2) || !fs25.existsSync(file2) || !isInside(fs25.realpathSync(dir), fs25.realpathSync(file2))) {
         return { ok: false, reason: "failed", detail: "the artifact file is not on this machine" };
       }
@@ -9676,7 +10176,7 @@ function debuggingHandlers(ctx) {
 var file = () => path34.join(flowrikiHome(), "assistant-folders.json");
 function readAll() {
   try {
-    const parsed = JSON.parse(fs34.readFileSync(file(), "utf8"));
+    const parsed = JSON.parse(fs35.readFileSync(file(), "utf8"));
     if (!parsed || typeof parsed !== "object") return {};
     const out = {};
     for (const [id, value] of Object.entries(parsed)) {
@@ -9689,18 +10189,18 @@ function readAll() {
   }
 }
 function writeAll(all) {
-  fs34.mkdirSync(path34.dirname(file()), { recursive: true, mode: 448 });
-  fs34.writeFileSync(file(), JSON.stringify(all, null, 2), { mode: 384 });
+  fs35.mkdirSync(path34.dirname(file()), { recursive: true, mode: 448 });
+  fs35.writeFileSync(file(), JSON.stringify(all, null, 2), { mode: 384 });
 }
 function gitHead(folder) {
   try {
-    const head = fs34.readFileSync(path34.join(folder, ".git", "HEAD"), "utf8").trim();
+    const head = fs35.readFileSync(path34.join(folder, ".git", "HEAD"), "utf8").trim();
     const ref = /^ref: (.+)$/.exec(head)?.[1];
     if (!ref) return { commit: /^[0-9a-f]{40}$/.test(head) ? head : null, branch: null };
     const branch = ref.replace(/^refs\/heads\//, "");
     const loose = path34.join(folder, ".git", ref);
-    if (fs34.existsSync(loose)) return { commit: fs34.readFileSync(loose, "utf8").trim(), branch };
-    const packed = fs34.readFileSync(path34.join(folder, ".git", "packed-refs"), "utf8");
+    if (fs35.existsSync(loose)) return { commit: fs35.readFileSync(loose, "utf8").trim(), branch };
+    const packed = fs35.readFileSync(path34.join(folder, ".git", "packed-refs"), "utf8");
     const line = packed.split("\n").find((l) => l.endsWith(` ${ref}`));
     return { commit: line?.split(" ")[0] ?? null, branch };
   } catch {
@@ -9710,7 +10210,7 @@ function gitHead(folder) {
 function describeFolder(folder, name = path34.basename(folder)) {
   const exists = (() => {
     try {
-      return fs34.statSync(folder).isDirectory();
+      return fs35.statSync(folder).isDirectory();
     } catch {
       return false;
     }
@@ -9859,6 +10359,12 @@ var runFile = (file2, args, timeoutMs) => new Promise((resolve2, reject) => {
 });
 var live = /* @__PURE__ */ new Map();
 var liveById = (sessionId) => [...live.values()].find((l) => l.id === sessionId);
+var IDLE_MS2 = (() => {
+  const minutes = Number(process.env["FLOWRIKI_RECORDING_IDLE_MINUTES"] ?? 30);
+  return Number.isFinite(minutes) && minutes >= 0 ? minutes * 6e4 : 30 * 6e4;
+})();
+var parked = /* @__PURE__ */ new Map();
+var PARKED_FOR_MS = 24 * 60 * 6e4;
 var ownerOf = (l) => l.draft ? "recording" : "debug";
 var SECRET_WORDS = /password|passwd|pass[-_\s]?code|pwd|secret|otp|\bpin\b|cvv|cvc/i;
 async function screenOf(l, withImage = false) {
@@ -9886,12 +10392,31 @@ async function screenOf(l, withImage = false) {
     device: l.session.deviceName
   };
 }
+async function closeIdlePhoneSessions(release, limit = IDLE_MS2, now = Date.now()) {
+  for (const [id, kept] of parked) if (now - kept.at > PARKED_FOR_MS) parked.delete(id);
+  if (limit <= 0) return;
+  for (const l of [...live.values()]) {
+    if (now - l.touchedAt < limit) continue;
+    live.delete(l.platform);
+    release(ownerOf(l), l.platform);
+    await l.session.close().catch(() => void 0);
+    if (l.draft?.steps.length) parked.set(l.id, { l, at: now });
+  }
+}
 function mobileHandlers(ctx) {
   const require2 = (command) => {
     const l = liveById(command.args["sessionId"]);
-    if (!l) throw new Error("that phone session has ended \u2014 open it again");
-    return l;
+    if (l) {
+      l.touchedAt = Date.now();
+      return l;
+    }
+    if (parked.has(String(command.args["sessionId"]))) {
+      throw new Error("this phone was let go after a long time with nothing done \u2014 press Stop to save what was recorded");
+    }
+    throw new Error("that phone session has ended \u2014 open it again");
   };
+  const sweeper = setInterval(() => void closeIdlePhoneSessions((owner, platform) => ctx.lease?.release(owner, platform)), 6e4);
+  sweeper.unref?.();
   return {
     // Everything this computer has for testing — web and phones — for the Guide.
     ...ctx.deps.machineCheck ? {
@@ -9965,6 +10490,7 @@ function mobileHandlers(ctx) {
             platform,
             values: /* @__PURE__ */ new Map(),
             typed,
+            touchedAt: Date.now(),
             resolveSecret: (ref) => typed.get(ref) ?? secrets[ref],
             resolveAuth: authenticationResolver(command.args["authentications"]),
             runHelper: helperRunner(command.args["helpers"], secrets)
@@ -9994,6 +10520,12 @@ function mobileHandlers(ctx) {
           }
           return { ok: true, result: { sessionId: l2.id, screen: await screenOf(l2) } };
         }
+        const resting = parked.get(String(command.args["sessionId"]));
+        if (resting && (op === "stop" || op === "discard")) {
+          parked.delete(String(command.args["sessionId"]));
+          if (op === "discard") return { ok: true, result: { ended: true } };
+          return { ok: true, result: finished(resting.l) };
+        }
         const l = require2(command);
         if (op === "act" || op === "run") {
           const raw = command.args["step"] ?? {};
@@ -10069,24 +10601,7 @@ function mobileHandlers(ctx) {
           ctx.lease?.release(ownerOf(l), l.platform);
           await l.session.close().catch(() => void 0);
           if (op === "discard" || !l.draft) return { ok: true, result: { ended: true } };
-          const now = (/* @__PURE__ */ new Date()).toISOString();
-          const d = l.draft;
-          const flow = {
-            schemaVersion: CURRENT_SCHEMA_VERSION,
-            id: `flw_${randomUUID2().replace(/-/g, "").slice(0, 12)}`,
-            featureId: d.featureId,
-            name: d.name,
-            slug: slugify(d.name) || "flow",
-            startPath: d.startPath,
-            platform: l.platform,
-            recordedAt: now,
-            recordedBy: d.recordedBy,
-            updatedAt: now,
-            revision: 0,
-            steps: d.steps,
-            ...d.signIn ? { signIn: d.signIn } : {}
-          };
-          return { ok: true, result: { flow, secrets: Object.fromEntries(l.typed) } };
+          return { ok: true, result: finished(l) };
         }
         return { ok: false, reason: "failed", detail: `unknown phone session operation "${op}"` };
       } catch (error) {
@@ -10096,6 +10611,52 @@ function mobileHandlers(ctx) {
     }
   };
 }
+function finished(l) {
+  const now = (/* @__PURE__ */ new Date()).toISOString();
+  const d = l.draft;
+  const flow = {
+    schemaVersion: CURRENT_SCHEMA_VERSION,
+    id: `flw_${randomUUID2().replace(/-/g, "").slice(0, 12)}`,
+    featureId: d.featureId,
+    name: d.name,
+    slug: slugify(d.name) || "flow",
+    startPath: d.startPath,
+    platform: l.platform,
+    recordedAt: now,
+    recordedBy: d.recordedBy,
+    updatedAt: now,
+    revision: 0,
+    steps: d.steps,
+    ...d.signIn ? { signIn: d.signIn } : {}
+  };
+  return { flow, secrets: Object.fromEntries(l.typed) };
+}
+function helperHandlers(_ctx) {
+  return {
+    "helper.run": async (command, project) => {
+      const parsed = DeliveredHelperSchema.safeParse(command.args["helper"]);
+      if (!parsed.success) return { ok: false, reason: "failed", detail: "that helper could not be read" };
+      const secrets = command.args["secrets"] ?? {};
+      const inputs = command.args["inputs"] ?? {};
+      const commands = localCommandRunner({ root: project.root || os22.homedir() });
+      const started = Date.now();
+      try {
+        const result = await runHelper(parsed.data, { resolveSecret: (ref) => secrets[ref], inputs, commands });
+        return { ok: true, result: { ...result, tookMs: Date.now() - started } };
+      } catch (error) {
+        const notAllowed = error instanceof CommandNotAllowed;
+        return {
+          ok: false,
+          reason: "failed",
+          detail: error instanceof HelperFailure ? error.message : `the helper failed: ${error.message}`,
+          ...notAllowed ? { code: "command_not_allowed" } : {}
+        };
+      } finally {
+        commands.close();
+      }
+    }
+  };
+}
 function buildHandlers(deps) {
   const context = {
     deps,
@@ -10124,6 +10685,7 @@ function buildHandlers(deps) {
     ...recordingHandlers(context),
     ...assistantHandlers(context),
     ...mobileHandlers(context),
+    ...helperHandlers(context),
     ...debug
   };
 }
@@ -10154,6 +10716,20 @@ function toolArgs(tool, input) {
     if (typeof value === "number" && Number.isFinite(value)) out[key] = value;
   }
   if (record["newBranch"] === true) out["newBranch"] = true;
+  if (typeof record["case"] === "string" && record["case"]) out["case"] = clip(record["case"], 40);
+  if (Array.isArray(record["features"])) {
+    const cases = [];
+    for (const feature of record["features"]) {
+      if (!feature || typeof feature !== "object") continue;
+      const f = feature;
+      const folder = typeof f["feature"] === "string" ? f["feature"] : typeof f["name"] === "string" ? f["name"] : "";
+      for (const c of Array.isArray(f["cases"]) ? f["cases"] : []) {
+        const name = c && typeof c === "object" ? c["name"] : void 0;
+        if (typeof name === "string" && name && cases.length < 40) cases.push({ folder: clip(folder), name: clip(name) });
+      }
+    }
+    if (cases.length) out["cases"] = cases;
+  }
   if (tool === "add_check" && typeof record["value"] === "string") out["value"] = clip(record["value"], 120);
   if (Array.isArray(record["after"])) {
     out["after"] = record["after"].filter((v) => typeof v === "string").slice(0, 5).map((v) => clip(v));
@@ -10185,13 +10761,65 @@ var ASK_MODE_TOOLS = [
   "list_my_branches",
   "run_insights"
 ];
+var NOT_RECORDING = [
+  "create_project",
+  "list_projects",
+  "read_import_file",
+  "save_import_cases",
+  "read_update_request",
+  "propose_case_updates",
+  "write_test_cases",
+  "gather_branches",
+  "discard_branch"
+];
+var NOT_SAVING_TESTS = [
+  "save_flow",
+  "save_case",
+  "preview_case",
+  "start_case",
+  "continue_flow",
+  "remove_step",
+  "replay_flow",
+  "add_check",
+  "use_helper",
+  "create_sign_in",
+  "create_account",
+  "create_helper",
+  "report_blocker"
+];
+var JOB_TOOLS_EXCEPT = {
+  heal: [...NOT_RECORDING, "create_sign_in", "create_account"],
+  automate: NOT_RECORDING,
+  reautomate: NOT_RECORDING,
+  update: NOT_RECORDING.filter((t) => t !== "read_update_request" && t !== "propose_case_updates"),
+  explore: [...NOT_RECORDING, ...NOT_SAVING_TESTS],
+  // Writing cases may still set up a sign-in it finds missing.
+  write: [
+    "create_project",
+    "list_projects",
+    "gather_branches",
+    "discard_branch",
+    "read_update_request",
+    "propose_case_updates",
+    ...NOT_SAVING_TESTS.filter((t) => !t.startsWith("create_"))
+  ]
+};
+function toolsExceptFor(prompt, briefGiven) {
+  const except = [...JOB_TOOLS_EXCEPT[usageKindOf(prompt)] ?? []];
+  if (briefGiven) except.push("project_brief");
+  return except;
+}
 function buildAskArgs(opts) {
   const ask = opts.mode === "ask";
   const folders = opts.folders ?? [];
   const brief = opts.brief?.trim();
   const guidance = [
-    `You are the Flowriki assistant for the project "${opts.projectName}" (id ${opts.projectId}). Use the Flowriki tools, and pass projectId "${opts.projectId}" wherever a tool takes one. ` + (brief ? "The project brief below is this project's memory for this job: read it first." : "Start with project_brief: it is this project's memory."),
-    ask ? "ASK MODE: answer the question; change nothing. Cite what you rely on as [[testCase:<its id, tc_\u2026>]], [[knowledge:features/checkout.md]] or [[file:path/in/repo.ts]]." : "DO MODE: do what is asked, on Claude's working branch, for a person to review. Ask in the chat and wait before publishing, deleting, or sending anything to another system. Work quietly: the person sees what you build and your final answer, so keep words between tool calls to a minimum and end with a short result \u2014 what was saved, and anything that needs them. When you learned something about the app the next job should know (a screen, a rule, a quirk, what failed and why), write it with write_knowledge (memory/sessions/<date>-<topic>.md, append) \u2014 Flowriki keeps it and gives it to the next job.",
+    `You are the Flowriki assistant for the project "${opts.projectName}" (id ${opts.projectId}). Use the Flowriki tools, and pass projectId "${opts.projectId}" wherever a tool takes one. ` + (brief ? "The project brief below IS project_brief for this job \u2014 do not call project_brief." : "Start with project_brief: it is this project's memory."),
+    ask ? "ASK MODE: answer the question; change nothing. Cite what you rely on as [[testCase:<its id, tc_\u2026>]], [[knowledge:features/checkout.md]] or [[file:path/in/repo.ts]]." : "DO MODE: do what is asked, on Claude's working branch, for a person to review. Ask in the chat and wait before publishing, deleting, or sending anything to another system. Work quietly: the person sees what you build and your final answer, so keep words between tool calls to a minimum and end with a short result \u2014 what was saved, and anything that needs them. Only when you learned something about the app that the brief does not already say and the next job needs (a screen, a rule, a quirk, what failed and why), write it with write_knowledge (memory/sessions/<date>-<topic>.md, append) \u2014 briefly.",
+    // SPENDING. Every turn re-reads the whole conversation, so turns are the
+    // cost: do several steps per act call, don't re-read a page a step already
+    // returned, and stop instead of retrying the same failing step.
+    ask ? "" : "Spend turns carefully: act takes several steps at once; a step's answer already shows the page \u2014 read_page only when it did not; after 3 failed tries at the same step, report_blocker and move on.",
     "Use only the tools you have: a tool is used by calling it, not by writing the call out as text. If Flowriki's tools are missing, say so in one sentence and stop.",
     folders.length ? `The project's code is in ${folders.join(" and ")}. Read it with Read, Grep and Glob when it helps; you cannot change it.` : "",
     brief ? `
@@ -10221,9 +10849,25 @@ ${brief}` : ""
     "dontAsk",
     "--append-system-prompt",
     guidance,
+    // THE MODEL, SAID — not whatever the person's default is. Recording and
+    // automating tests is what Sonnet does well; a default of Opus costs
+    // several times as much for the same tests. FLOWRIKI_ASSISTANT_MODEL
+    // overrides it.
+    "--model",
+    opts.model ?? (process.env["FLOWRIKI_ASSISTANT_MODEL"]?.trim() || "sonnet"),
+    // A ceiling, not a target: a job that has taken this many turns is going
+    // round in circles. What it saved stays; "continue" carries on.
+    "--max-turns",
+    String(opts.maxTurns ?? (ask ? 40 : 160)),
     ...opts.sessionId ? ["--resume", opts.sessionId] : []
   ];
 }
+var tokensOf = (u) => ({
+  input: u.input_tokens ?? 0,
+  output: u.output_tokens ?? 0,
+  cacheRead: u.cache_read_input_tokens ?? 0,
+  cacheWrite: u.cache_creation_input_tokens ?? 0
+});
 function clearOld(dir) {
   try {
     for (const name of fs43.readdirSync(dir)) {
@@ -10248,11 +10892,13 @@ function eventsFromLine(askId, line) {
     if (parsed.session_id) out.push({ name: "assistant.session", data: { askId, sessionId: parsed.session_id } });
   }
   if (parsed.type === "assistant") {
+    const tools = [];
     for (const block of parsed.message?.content ?? []) {
       if (block.type === "text" && block.text?.trim()) {
         out.push({ name: "assistant.text", data: { askId, text: block.text } });
       } else if (block.type === "tool_use" && block.name) {
         const tool = block.name.replace(TOOL_PREFIX, "");
+        tools.push(tool);
         out.push({
           name: "assistant.tool",
           data: {
@@ -10265,6 +10911,12 @@ function eventsFromLine(askId, line) {
         });
       }
     }
+    if (parsed.message?.usage && parsed.message.id) {
+      out.push({
+        name: "assistant.usage",
+        data: { askId, messageId: parsed.message.id, tools, ...tokensOf(parsed.message.usage), ...parsed.message.model ? { model: parsed.message.model } : {} }
+      });
+    }
   }
   if (parsed.type === "user") {
     for (const block of parsed.message?.content ?? []) {
@@ -10278,6 +10930,20 @@ function eventsFromLine(askId, line) {
       });
     }
   }
+  if (parsed.type === "rate_limit_event" && parsed.rate_limit_info) {
+    const info = parsed.rate_limit_info;
+    out.push({
+      name: "assistant.limits",
+      data: {
+        askId,
+        ...typeof info.status === "string" ? { status: info.status } : {},
+        ...typeof info.rateLimitType === "string" ? { window: info.rateLimitType } : {},
+        ...typeof info.utilization === "number" ? { utilization: info.utilization } : {},
+        ...typeof info.resetsAt === "number" ? { resetsAt: info.resetsAt } : {},
+        ...info.isUsingOverage === true ? { overage: true } : {}
+      }
+    });
+  }
   if (parsed.type === "result") {
     out.push({
       name: "assistant.done",
@@ -10285,20 +10951,43 @@ function eventsFromLine(askId, line) {
         askId,
         ok: parsed.is_error !== true,
         result: typeof parsed.result === "string" ? parsed.result : "",
-        ...parsed.session_id ? { sessionId: parsed.session_id } : {}
+        ...parsed.session_id ? { sessionId: parsed.session_id } : {},
+        // The whole job, as the model counted it.
+        ...parsed.usage ? { usage: tokensOf(parsed.usage) } : {},
+        ...typeof parsed.total_cost_usd === "number" ? { costUsd: parsed.total_cost_usd } : {},
+        ...typeof parsed.num_turns === "number" ? { turns: parsed.num_turns } : {},
+        ...typeof parsed.duration_ms === "number" ? { durationMs: parsed.duration_ms } : {}
       }
     });
   }
   return out;
 }
+function stop2(child) {
+  child.kill("SIGTERM");
+  const force = setTimeout(() => {
+    if (child.exitCode === null && child.signalCode === null) child.kill("SIGKILL");
+  }, 5e3);
+  force.unref?.();
+}
 function createClaudeCli(options) {
-  const spawn2 = options.spawn ?? nodeSpawn;
+  const spawn3 = options.spawn ?? nodeSpawn;
   const binary = options.binary ?? process.env["FLOWRIKI_CLAUDE_BIN"] ?? "claude";
   const maxAskMs = options.maxAskMs ?? 60 * 6e4;
-  const scratchRoot2 = options.scratchRoot ?? path42.join(os22.tmpdir(), "flowriki-claude");
-  const running = /* @__PURE__ */ new Map();
+  const scratchRoot2 = options.scratchRoot ?? path42.join(os32.tmpdir(), "flowriki-claude");
+  const running2 = /* @__PURE__ */ new Map();
   const MAX_AT_ONCE = 3;
-  let cancelled = null;
+  process.once("exit", () => {
+    for (const child of running2.values()) {
+      try {
+        child.kill("SIGTERM");
+      } catch {
+      }
+    }
+  });
+  const cancelled = /* @__PURE__ */ new Set();
+  const retrying = /* @__PURE__ */ new Set();
+  const sessionsInUse = /* @__PURE__ */ new Set();
+  const occupied = () => running2.size + retrying.size;
   function capture(args, timeoutMs = 15e3) {
     return new Promise((resolve2) => {
       let out = "", err = "", settled = false;
@@ -10310,7 +10999,7 @@ function createClaudeCli(options) {
       };
       let child;
       try {
-        child = spawn2(binary, args, { stdio: ["ignore", "pipe", "pipe"] });
+        child = spawn3(binary, args, { stdio: ["ignore", "pipe", "pipe"] });
       } catch {
         return resolve2({ code: null, out: "", err: "", failed: true });
       }
@@ -10328,8 +11017,8 @@ function createClaudeCli(options) {
       child.on("close", (code) => finish(code, false));
     });
   }
-  const LANE_FRESH_MS = 60 * 6e4;
-  const LANE_MAX_TOKENS = 15e4;
+  const LANE_FRESH_MS = 5 * 6e4;
+  const LANE_MAX_TOKENS = 4e4;
   const laneFile = (dir) => path42.join(dir, "lane-sessions.json");
   const readLanes = (dir) => {
     try {
@@ -10355,6 +11044,8 @@ function createClaudeCli(options) {
     }
     const kept = readLanes(dir)[ask.platform];
     if (!kept || Date.now() - kept.updatedAt > LANE_FRESH_MS || kept.tokens > LANE_MAX_TOKENS) return void 0;
+    if (sessionsInUse.has(kept.sessionId)) return void 0;
+    if ((kept.kind ?? "chat") !== usageKindOf(ask.prompt)) return void 0;
     return kept.sessionId;
   }
   return {
@@ -10368,17 +11059,17 @@ function createClaudeCli(options) {
       return { installed: true, version: version.out.trim().split(/\s+/)[0] ?? null, ...parsed };
     },
     connect(emit) {
-      if (running.size > 0) return { started: false, detail: "The assistant is busy answering a question." };
+      if (running2.size > 0) return { started: false, detail: "The assistant is busy answering a question." };
       let child;
       try {
-        child = spawn2(binary, ["auth", "login"], { stdio: ["ignore", "pipe", "pipe"] });
+        child = spawn3(binary, ["auth", "login"], { stdio: ["ignore", "pipe", "pipe"] });
       } catch {
         return { started: false, detail: "The assistant\u2019s command-line tool could not be started." };
       }
-      let finished = false;
+      let finished2 = false;
       const done = async (detail) => {
-        if (finished) return;
-        finished = true;
+        if (finished2) return;
+        finished2 = true;
         const status2 = await this.status();
         emit("assistant.connect.finished", { signedIn: status2.signedIn, ...detail ? { detail } : {} });
       };
@@ -10398,37 +11089,55 @@ function createClaudeCli(options) {
       return { started: true };
     },
     ask(ask) {
-      if (running.size >= MAX_AT_ONCE) return { started: false, detail: `The assistant is already answering ${MAX_AT_ONCE} questions on this machine \u2014 wait for one to finish.` };
+      if (occupied() >= MAX_AT_ONCE) return { started: false, detail: `The assistant is already answering ${MAX_AT_ONCE} questions on this machine \u2014 wait for one to finish.` };
       fs43.mkdirSync(scratchRoot2, { recursive: true, mode: 448 });
       const dir = path42.join(scratchRoot2, `project-${ask.projectId.replace(/[^A-Za-z0-9_-]/g, "_")}`);
       fs43.mkdirSync(dir, { recursive: true, mode: 448 });
       clearOld(dir);
       const mcpConfigPath = path42.join(dir, `mcp-${ask.askId.replace(/[^A-Za-z0-9_-]/g, "_").slice(0, 80)}.json`);
+      const session = laneSession(ask, dir);
+      const except = ask.mode === "ask" ? [] : toolsExceptFor(ask.prompt, Boolean(ask.brief && !session));
       fs43.writeFileSync(
         mcpConfigPath,
-        JSON.stringify({ mcpServers: { [MCP_SERVER_NAME]: { command: options.mcp.command, args: options.mcp.args, env: { FLOWRIKI_ASK_ID: ask.askId } } } }),
+        JSON.stringify({ mcpServers: { [MCP_SERVER_NAME]: { command: options.mcp.command, args: options.mcp.args, env: {
+          FLOWRIKI_ASK_ID: ask.askId,
+          // The project, known from the start: no "which project?" turn.
+          FLOWRIKI_PROJECT_ID: ask.projectId,
+          // The agent that launched it decides its version: the tool server
+          // does not update itself in the middle of somebody's job.
+          FLOWRIKI_NO_UPDATE: "1",
+          FLOWRIKI_MCP_CHILD: "1",
+          // A question: only the reading tools are served at all.
+          ...ask.mode === "ask" ? { FLOWRIKI_TOOLS: ASK_MODE_TOOLS.join(",") } : {},
+          // A job of a known kind: the tools it never uses are not served.
+          ...except.length ? { FLOWRIKI_TOOLS_EXCEPT: except.join(",") } : {}
+        } } } }),
         { mode: 384 }
       );
-      return launch(ask, dir, mcpConfigPath, laneSession(ask, dir));
+      return launch(ask, dir, mcpConfigPath, session);
     },
     cancel(askId) {
-      const child = running.get(askId);
+      if (retrying.has(askId)) {
+        cancelled.add(askId);
+        return true;
+      }
+      const child = running2.get(askId);
       if (!child) return false;
-      cancelled = askId;
-      child.kill("SIGTERM");
+      cancelled.add(askId);
+      stop2(child);
       setTimeout(() => child.kill("SIGKILL"), 3e3).unref?.();
       return true;
     },
     /** Full — no room for another question — rather than "something runs":
      *  a second conversation is welcome while the first works. */
     busy() {
-      return running.size >= MAX_AT_ONCE;
+      return occupied() >= MAX_AT_ONCE;
     }
   };
   function launch(ask, dir, mcpConfigPath, sessionId, attempt = 1) {
     let child;
     try {
-      child = spawn2(
+      child = spawn3(
         binary,
         buildAskArgs({
           prompt: ask.prompt,
@@ -10438,20 +11147,26 @@ function createClaudeCli(options) {
           ...sessionId ? { sessionId } : {},
           ...ask.folders?.length ? { folders: ask.folders } : {},
           ...ask.mode ? { mode: ask.mode } : {},
-          ...ask.brief ? { brief: ask.brief } : {}
+          // Resumed, the conversation already holds its brief: a changed
+          // one in the system prompt would throw away the whole cache.
+          ...ask.brief && !sessionId ? { brief: ask.brief } : {}
         }),
         // THE SCRATCH FOLDER, not the project: nothing here to read or write.
-        { cwd: dir, stdio: ["ignore", "pipe", "pipe"] }
+        // Thinking is output, priced at five times input: capped per turn,
+        // unless the person set their own.
+        { cwd: dir, stdio: ["ignore", "pipe", "pipe"], env: { ...process.env, MAX_THINKING_TOKENS: process.env["MAX_THINKING_TOKENS"] ?? "6000" } }
       );
     } catch {
       return { started: false, detail: "The assistant\u2019s command-line tool could not be started." };
     }
-    running.set(ask.askId, child);
+    running2.set(ask.askId, child);
+    if (sessionId) sessionsInUse.add(sessionId);
     let buffer = "", stderr = "", sawDone = false, ended = false;
     let silentFailure = false;
     let toolsMissing = false;
     let session;
     let spent = 0;
+    let lastContext = 0;
     const handleLine = (line) => {
       if (toolsMissing) return;
       for (const event of eventsFromLine(ask.askId, line)) {
@@ -10464,6 +11179,7 @@ function createClaudeCli(options) {
           continue;
         }
         if (event.name === "assistant.session") session = String(event.data["sessionId"] ?? "") || session;
+        if (event.name === "assistant.usage") lastContext = Number(event.data["input"] ?? 0) + Number(event.data["cacheRead"] ?? 0) + Number(event.data["cacheWrite"] ?? 0) + Number(event.data["output"] ?? 0);
         if (event.name === "assistant.done" && event.data["ok"] === false && !String(event.data["result"] ?? "").trim()) {
           silentFailure = true;
           continue;
@@ -10485,10 +11201,18 @@ function createClaudeCli(options) {
       ended = true;
       clearTimeout(timer);
       if (buffer.trim()) handleLine(buffer);
-      running.delete(ask.askId);
-      if (toolsMissing && cancelled !== ask.askId) {
+      running2.delete(ask.askId);
+      if (sessionId) sessionsInUse.delete(sessionId);
+      const stopped = cancelled.has(ask.askId);
+      if (toolsMissing && !stopped) {
         if (attempt < 3) {
+          retrying.add(ask.askId);
           setTimeout(() => {
+            retrying.delete(ask.askId);
+            if (cancelled.delete(ask.askId)) {
+              ask.emit("assistant.done", { askId: ask.askId, ok: false, result: "Stopped." });
+              return;
+            }
             const again = launch(ask, dir, mcpConfigPath, sessionId, attempt + 1);
             if (!again.started) ask.emit("assistant.done", { askId: ask.askId, ok: false, result: again.detail ?? "The assistant could not be started." });
           }, 1500 * attempt + Math.floor(Math.random() * 1e3)).unref?.();
@@ -10497,22 +11221,22 @@ function createClaudeCli(options) {
         ask.emit("assistant.done", { askId: ask.askId, ok: false, result: "Flowriki's tools did not connect to the assistant on this computer after three tries, so nothing was done. Send it again in a moment; if it keeps happening, restart the agent." });
         return;
       }
-      if (silentFailure && sessionId && /no conversation found/i.test(stderr) && cancelled !== ask.askId) {
+      if (silentFailure && sessionId && /no conversation found/i.test(stderr) && !stopped) {
         if (ask.platform) writeLane(dir, ask.platform, null);
         const again = launch(ask, dir, mcpConfigPath, void 0);
         if (again.started) return;
       }
       if (ask.platform && session && ok && !silentFailure) {
-        const before = sessionId && readLanes(dir)[ask.platform]?.sessionId === sessionId ? readLanes(dir)[ask.platform].tokens : 0;
-        writeLane(dir, ask.platform, { sessionId: session, updatedAt: Date.now(), tokens: Math.max(before, spent) });
+        writeLane(dir, ask.platform, { sessionId: session, updatedAt: Date.now(), tokens: lastContext || spent, kind: usageKindOf(ask.prompt) });
       }
       if (!sawDone) {
         const why = detail || stderr.trim().split("\n").filter((l) => l && !/^Warning:/.test(l)).slice(-3).join(" ") || "The assistant stopped without saying why.";
         ask.emit("assistant.done", { askId: ask.askId, ok: ok && !silentFailure, result: ok && !silentFailure ? "" : why });
       }
+      cancelled.delete(ask.askId);
     };
     const timer = setTimeout(() => {
-      child.kill("SIGTERM");
+      stop2(child);
       end(false, `Stopped after ${Math.max(1, Math.round(maxAskMs / 6e4))} minutes. Whatever it saved so far is on the Branches page \u2014 send \u201Ccontinue\u201D to carry on.`);
     }, maxAskMs);
     timer.unref?.();
@@ -10520,7 +11244,12 @@ function createClaudeCli(options) {
       buffer += chunk.toString();
       let at;
       while ((at = buffer.indexOf("\n")) >= 0) {
-        handleLine(buffer.slice(0, at));
+        try {
+          handleLine(buffer.slice(0, at));
+        } catch (error) {
+          stderr = `${stderr}
+${error.message}`.slice(-2e3);
+        }
         buffer = buffer.slice(at + 1);
       }
     });
@@ -10532,7 +11261,7 @@ function createClaudeCli(options) {
       "close",
       (code) => end(
         code === 0,
-        cancelled === ask.askId ? "Stopped." : code === 0 ? "" : stderr.trim().split("\n").filter((l) => l && !/^Warning:/.test(l)).slice(-3).join(" ") || `The assistant stopped (exit ${code ?? "?"}).`
+        cancelled.has(ask.askId) ? "Stopped." : code === 0 ? "" : stderr.trim().split("\n").filter((l) => l && !/^Warning:/.test(l)).slice(-3).join(" ") || `The assistant stopped (exit ${code ?? "?"}).`
       )
     );
     return { started: true };
@@ -10723,11 +11452,11 @@ function createAgentRuntime(options) {
 
 // src/lock.ts
 import fs11 from "fs";
-import os6 from "os";
+import os7 from "os";
 function takeLock(env = process.env) {
   ensureDataDir(env);
   const file2 = lockPath(env);
-  const mine = { pid: process.pid, since: (/* @__PURE__ */ new Date()).toISOString(), host: os6.hostname() };
+  const mine = { pid: process.pid, since: (/* @__PURE__ */ new Date()).toISOString(), host: os7.hostname() };
   for (let attempt = 0; attempt < 2; attempt += 1) {
     try {
       fs11.writeFileSync(file2, JSON.stringify(mine), { flag: "wx", mode: 384 });
@@ -10868,8 +11597,12 @@ async function start(options = {}) {
       if (stopped) return;
       stopped = true;
       link.stop();
-      agent.close();
-      lock.lock.release();
+      try {
+        agent.close();
+      } catch {
+      } finally {
+        lock.lock.release();
+      }
     }
   };
 }
@@ -10879,7 +11612,7 @@ function status(serviceArg) {
   const service = resolveService(serviceArg);
   const connection = connectionFor(service);
   const lock = takeLock();
-  const running = lock.ok ? null : lock.held;
+  const running2 = lock.ok ? null : lock.held;
   if (lock.ok) lock.lock.release();
   const dirs = connection?.checkouts ?? [];
   const { projects, skipped } = resolveCheckouts(dirs);
@@ -10891,7 +11624,7 @@ function status(serviceArg) {
       ...projects.map((p) => ({ root: p.root, project: p.name })),
       ...skipped.map((s2) => ({ root: s2.root, project: null, why: s2.why }))
     ],
-    running
+    running: running2
   };
 }
 async function doctor(serviceArg) {
@@ -10968,7 +11701,12 @@ export {
   executeStep,
   replayCase,
   fieldNames,
+  backupsFor,
+  withBackups,
   flowrikiHome,
+  readApprovals,
+  allowCommands,
+  revokeCommands,
   helperRunner,
   resolveCheckouts,
   start,