@ironbee-ai/cli 0.29.0 → 0.31.0

package/dist/clients/claude/process-analytics.js

@@ -1 +1 @@
-"use strict";var t=Object.defineProperty;var g=Object.getOwnPropertyDescriptor;var p=Object.getOwnPropertyNames;var u=Object.prototype.hasOwnProperty;var m=(e,s)=>{for(var n in s)t(e,n,{get:s[n],enumerable:!0})},l=(e,s,n,o)=>{if(s&&typeof s=="object"||typeof s=="function")for(let r of p(s))!u.call(e,r)&&r!==n&&t(e,r,{get:()=>s[r],enumerable:!(o=g(s,r))||o.enumerable});return e};var y=e=>l(t({},"__esModule",{value:!0}),e);var S={};m(S,{claudeProcessAnalyticsCommand:()=>f});module.exports=y(S);var c=require("commander"),i=require("../../lib/logger"),a=require("../../analytics/claude/emit"),d=require("../../analytics/claude/log");const f=new c.Command("process-analytics").description("Internal worker \u2014 project + emit a session_analytics snapshot for one Claude trigger").requiredOption("--project <dir>","project directory (where .ironbee/sessions/<sid>/ lives)").requiredOption("--session <id>","session id").requiredOption("--trigger <type>","Stop | SessionEnd").option("--end-reason <reason>","SessionEnd reason (optional)").option("--transcript-source <src>","claude-code | cursor | missing").action(async e=>{const s=e.trigger==="SessionEnd"?"SessionEnd":"Stop",n=e.transcriptSource??"claude-code";(0,i.setLogFile)(`${e.project}/.ironbee/sessions/${e.session}/session.log`);const o=new d.AnalyticsLog(e.project,e.session);o.info(`worker: claude process-analytics start (trigger=${s} session=${e.session}${e.endReason?` end_reason=${e.endReason}`:""})`);try{const r=await(0,a.emitAnalytics)({projectDir:e.project,sessionId:e.session,triggerType:s,endReason:e.endReason,transcriptSource:n,log:o});o.info(`worker: claude process-analytics done (status=${r.status} reason=${r.reason})`)}catch(r){i.logger.debug(`claude process-analytics: unexpected error: ${r instanceof Error?r.message:r}`),o.error(`worker: unexpected error: ${r instanceof Error?r.message:r}`)}});0&&(module.exports={claudeProcessAnalyticsCommand});
+"use strict";var t=Object.defineProperty;var g=Object.getOwnPropertyDescriptor;var m=Object.getOwnPropertyNames;var u=Object.prototype.hasOwnProperty;var l=(e,s)=>{for(var n in s)t(e,n,{get:s[n],enumerable:!0})},y=(e,s,n,o)=>{if(s&&typeof s=="object"||typeof s=="function")for(let r of m(s))!u.call(e,r)&&r!==n&&t(e,r,{get:()=>s[r],enumerable:!(o=g(s,r))||o.enumerable});return e};var f=e=>y(t({},"__esModule",{value:!0}),e);var w={};l(w,{claudeProcessAnalyticsCommand:()=>S});module.exports=f(w);var c=require("commander"),i=require("../../lib/logger"),a=require("../../analytics/claude/emit"),d=require("../../analytics/claude/log"),p=require("../../lib/runtime-paths");const S=new c.Command("process-analytics").description("Internal worker \u2014 project + emit a session_analytics snapshot for one Claude trigger").requiredOption("--project <dir>","project directory (where .ironbee/sessions/<sid>/ lives)").requiredOption("--session <id>","session id").requiredOption("--trigger <type>","Stop | SessionEnd").option("--end-reason <reason>","SessionEnd reason (optional)").option("--transcript-source <src>","claude-code | cursor | missing").action(async e=>{const s=e.trigger==="SessionEnd"?"SessionEnd":"Stop",n=e.transcriptSource??"claude-code";(0,i.setLogFile)((0,p.sessionLogFile)(e.project,e.session));const o=new d.AnalyticsLog(e.project,e.session);o.info(`worker: claude process-analytics start (trigger=${s} session=${e.session}${e.endReason?` end_reason=${e.endReason}`:""})`);try{const r=await(0,a.emitAnalytics)({projectDir:e.project,sessionId:e.session,triggerType:s,endReason:e.endReason,transcriptSource:n,log:o});o.info(`worker: claude process-analytics done (status=${r.status} reason=${r.reason})`)}catch(r){i.logger.debug(`claude process-analytics: unexpected error: ${r instanceof Error?r.message:r}`),o.error(`worker: unexpected error: ${r instanceof Error?r.message:r}`)}});0&&(module.exports={claudeProcessAnalyticsCommand});

package/dist/clients/claude/statusline-toggle.js

@@ -1,2 +1,2 @@
-"use strict";var d=Object.defineProperty;var L=Object.getOwnPropertyDescriptor;var T=Object.getOwnPropertyNames;var k=Object.prototype.hasOwnProperty;var u=(e,n)=>d(e,"name",{value:n,configurable:!0});var x=(e,n)=>{for(var t in n)d(e,t,{get:n[t],enumerable:!0})},E=(e,n,t,r)=>{if(n&&typeof n=="object"||typeof n=="function")for(let o of T(n))!k.call(e,o)&&o!==t&&d(e,o,{get:()=>n[o],enumerable:!(r=L(n,o))||r.enumerable});return e};var F=e=>E(d({},"__esModule",{value:!0}),e);var R={};x(R,{applyStatusLineToggle:()=>O,syncChainedStatusLine:()=>P});module.exports=F(R);var i=require("fs"),c=require("path"),S=require("../registry"),$=require("./hooks/session-status"),s=require("../../lib/config"),y=require("../../lib/gitignore"),C=require("../../lib/logger"),f=require("../../lib/output"),m=require("../../hooks/core/session-state");function N(e){if(!(0,i.existsSync)(e))return{};try{return JSON.parse((0,i.readFileSync)(e,"utf-8"))}catch(n){throw C.logger.debug(`failed to read ${e}: ${n}`),new Error(`Config at ${e} is not valid JSON: ${n instanceof Error?n.message:n}`)}}u(N,"readConfigFile");function J(e,n){(0,i.mkdirSync)((0,c.join)(e,".."),{recursive:!0}),(0,i.writeFileSync)(e,JSON.stringify(n,null,2)+`
-`)}u(J,"writeConfigFile");function O(e,n,t,r){const o=(0,s.getTargetConfigPath)(t,n),a=N(o),g=e?"enabled":"disabled",l=(0,s.loadConfig)(n);l.statusLine={...l.statusLine,enable:e};const b=(0,s.isSessionStatusEnabled)((0,s.loadConfig)(n)),w=(0,s.isSessionStatusEnabled)(l);if(b===w&&a.statusLine?.enable===e){console.log(`${f.pc.dim("\xB7")}  Statusline already ${g} in ${t} config (${f.pc.dim(o)}). No-op.`);return}const h=(0,S.resolveTargetClients)(n,r);for(const B of h)B.install(n,l);t!=="global"&&(0,y.ensureIronBeeGitignored)(n);const p={...a,statusLine:{...a.statusLine,enable:e}};J(o,p);const v=e?"Enabled":"Disabled",I=e?"The statusline wrapper now emits session_status events and chains your existing statusline.":"Your original statusline is restored; no session_status events are emitted.";console.log(`${f.pc.green("\u2713")}  ${v} statusline in ${t} config (${f.pc.dim(o)}).`),console.log(`   ${f.pc.dim(I)}`),console.log(`   ${f.pc.yellow("\u26A0")}  Restart your editor / agent session for the change to take effect.`)}u(O,"applyStatusLineToggle");function P(e){const n=(0,$.resolveChainTarget)(e)??null,t=(0,c.join)(e,".ironbee","sessions");if(!(0,i.existsSync)(t))return 0;let r=0,o;try{o=(0,i.readdirSync)(t)}catch(a){return C.logger.debug(`statusline sync: failed to list ${t}: ${a}`),0}for(const a of o){const g=(0,c.join)(t,a);!(0,i.existsSync)((0,c.join)(g,"state.json"))||(0,m.readState)(g).chainedStatusLine===n||((0,m.setChainedStatusLine)(g,n),r++)}return r}u(P,"syncChainedStatusLine");0&&(module.exports={applyStatusLineToggle,syncChainedStatusLine});
+"use strict";var c=Object.defineProperty;var T=Object.getOwnPropertyDescriptor;var k=Object.getOwnPropertyNames;var x=Object.prototype.hasOwnProperty;var u=(e,n)=>c(e,"name",{value:n,configurable:!0});var E=(e,n)=>{for(var o in n)c(e,o,{get:n[o],enumerable:!0})},F=(e,n,o,r)=>{if(n&&typeof n=="object"||typeof n=="function")for(let t of k(n))!x.call(e,t)&&t!==o&&c(e,t,{get:()=>n[t],enumerable:!(r=T(n,t))||r.enumerable});return e};var N=e=>F(c({},"__esModule",{value:!0}),e);var _={};E(_,{applyStatusLineToggle:()=>O,syncChainedStatusLine:()=>P});module.exports=N(_);var i=require("fs"),d=require("path"),S=require("../registry"),$=require("./hooks/session-status"),y=require("../../lib/runtime-paths"),s=require("../../lib/config"),b=require("../../lib/gitignore"),C=require("../../lib/logger"),f=require("../../lib/output"),m=require("../../hooks/core/session-state");function R(e){if(!(0,i.existsSync)(e))return{};try{return JSON.parse((0,i.readFileSync)(e,"utf-8"))}catch(n){throw C.logger.debug(`failed to read ${e}: ${n}`),new Error(`Config at ${e} is not valid JSON: ${n instanceof Error?n.message:n}`)}}u(R,"readConfigFile");function J(e,n){(0,i.mkdirSync)((0,d.join)(e,".."),{recursive:!0}),(0,i.writeFileSync)(e,JSON.stringify(n,null,2)+`
+`)}u(J,"writeConfigFile");function O(e,n,o,r){const t=(0,s.getTargetConfigPath)(o,n),a=R(t),g=e?"enabled":"disabled",l=(0,s.loadConfig)(n);l.statusLine={...l.statusLine,enable:e};const p=(0,s.isSessionStatusEnabled)((0,s.loadConfig)(n)),v=(0,s.isSessionStatusEnabled)(l);if(p===v&&a.statusLine?.enable===e){console.log(`${f.pc.dim("\xB7")}  Statusline already ${g} in ${o} config (${f.pc.dim(t)}). No-op.`);return}const w=(0,S.resolveTargetClients)(n,r);for(const L of w)L.install(n,l);o!=="global"&&(0,b.ensureIronBeeGitignored)(n);const h={...a,statusLine:{...a.statusLine,enable:e}};J(t,h);const I=e?"Enabled":"Disabled",B=e?"The statusline wrapper now emits session_status events and chains your existing statusline.":"Your original statusline is restored; no session_status events are emitted.";console.log(`${f.pc.green("\u2713")}  ${I} statusline in ${o} config (${f.pc.dim(t)}).`),console.log(`   ${f.pc.dim(B)}`),console.log(`   ${f.pc.yellow("\u26A0")}  Restart your editor / agent session for the change to take effect.`)}u(O,"applyStatusLineToggle");function P(e){const n=(0,$.resolveChainTarget)(e)??null,o=(0,y.sessionsRoot)(e);if(!(0,i.existsSync)(o))return 0;let r=0,t;try{t=(0,i.readdirSync)(o)}catch(a){return C.logger.debug(`statusline sync: failed to list ${o}: ${a}`),0}for(const a of t){const g=(0,d.join)(o,a);!(0,i.existsSync)((0,d.join)(g,"state.json"))||(0,m.readState)(g).chainedStatusLine===n||((0,m.setChainedStatusLine)(g,n),r++)}return r}u(P,"syncChainedStatusLine");0&&(module.exports={applyStatusLineToggle,syncChainedStatusLine});

package/dist/clients/claude/trust.js

@@ -0,0 +1 @@
+"use strict";var g=Object.defineProperty;var m=Object.getOwnPropertyDescriptor;var b=Object.getOwnPropertyNames;var k=Object.prototype.hasOwnProperty;var p=(t,e)=>g(t,"name",{value:e,configurable:!0});var w=(t,e)=>{for(var r in e)g(t,r,{get:e[r],enumerable:!0})},h=(t,e,r,c)=>{if(e&&typeof e=="object"||typeof e=="function")for(let o of b(e))!k.call(t,o)&&o!==r&&g(t,o,{get:()=>e[o],enumerable:!(c=m(e,o))||c.enumerable});return t};var j=t=>h(g({},"__esModule",{value:!0}),t);var S={};w(S,{ensureWorkspaceTrusted:()=>$});module.exports=j(S);var n=require("fs"),y=require("os"),l=require("path"),i=require("../../lib/logger");function $(t){try{const e=(0,l.join)((0,y.homedir)(),".claude.json");if(!(0,n.existsSync)(e))return i.logger.debug(`trust: ${e} absent \u2014 skipping workspace trust`),!1;let r;try{r=JSON.parse((0,n.readFileSync)(e,"utf-8"))}catch(s){return i.logger.debug(`trust: cannot read/parse ${e}: ${s instanceof Error?s.message:s}`),!1}if(r===null||typeof r!="object")return!1;const c=(0,l.resolve)(t);let o=c;try{o=(0,n.realpathSync)(c)}catch{}const u=typeof r.projects=="object"&&r.projects!==null?r.projects:{},d=[o,c].find(s=>u[s]!==void 0&&u[s]!==null)??o,f=u[d]??{};if(f.hasTrustDialogAccepted===!0)return!1;f.hasTrustDialogAccepted=!0,u[d]=f,r.projects=u;const a=`${e}.ironbee-tmp-${process.pid}`;try{(0,n.writeFileSync)(a,JSON.stringify(r,null,2)),(0,n.renameSync)(a,e)}catch(s){try{(0,n.existsSync)(a)&&(0,n.unlinkSync)(a)}catch{}return i.logger.debug(`trust: write failed for ${e}: ${s instanceof Error?s.message:s}`),!1}return i.logger.debug(`trust: set hasTrustDialogAccepted=true for ${d}`),!0}catch(e){return i.logger.debug(`trust: unexpected failure: ${e instanceof Error?e.message:e}`),!1}}p($,"ensureWorkspaceTrusted");0&&(module.exports={ensureWorkspaceTrusted});

package/dist/clients/codex/agents/ironbee-scenario.md

@@ -0,0 +1,179 @@
+# IronBee Scenario manager (manage / search)
+
+You are a dedicated scenario-management sub-agent. The main agent delegated a scenario operation
+to you. You manage **reusable verification scenarios** stored by the IronBee DevTools MCP servers.
+A scenario is a named, parameterizable script (`callTool('<tool>', {...})` JS) that drives ONE
+platform's tools. Do exactly the operation named in the delegating prompt and return a short
+summary.
+
+You drive ONLY the `*_scenario-*` tools (`scenario-add` / `scenario-update` / `scenario-delete`
+/ `scenario-list` / `scenario-search` / `scenario-run`) for scenario work. The platform tools a
+scenario *script* calls run INSIDE the sandbox at run time — you never call them directly.
+You run under a **read-only sandbox** (same as the verifier) — you **never edit/fix project code**.
+You may run shell commands to build / start / stop the app for live authoring (start it only if it
+isn't already running; stop only what YOU started) and READ files you're pointed at to author a
+script or derive metadata. Scenarios are authored ONLY through the `scenario-*` MCP tools (their
+store write happens server-side, not in your sandbox).
+
+This is NOT a verification cycle — you submit no verdict and do not gate completion.
+
+## Operation: the delegating prompt names ONE of these
+
+### `manage` — add / update / delete
+- **Resolve intent.** Scenario CONTENT to save (a prompt or a file path) → add/update. A TARGET
+  only described → delete.
+- **Add vs update (never duplicate).** Before adding, **`scenario-search` / `scenario-list`** to
+  check whether a same-name or clearly-the-same scenario already exists on the target platform. If
+  it does → **update** it instead of creating a duplicate.
+- **Author the script** from the given content into the devtools format. Pick the **right platform**
+  from what the scenario does (see the platform sections for which platform fits) and call `scenario-add`/`scenario-update` on **that
+  platform's server**. A high-level scenario that spans platforms → split into one sub-scenario per
+  platform, linked by metadata (see "Metadata"). **By default author it against the LIVE app — see
+  "Live authoring" below** (skip with `Mode: draft`). Script form: §Script format.
+- **Delete is destructive — always confirm.** Resolve the target via search/list, then show the
+  matched **name + description + platform** and ask the user to confirm before deleting. Multiple
+  candidates / low score → list them and ask which.
+- **Update resolved by fuzzy description also confirms** (the script is overwritten — same risk as
+  delete). An **exact-name** match proceeds without a confirm prompt.
+- **Scope**: write to `project` scope (default) unless the user asked for `global`. Pass `scope` on
+  every call.
+- **Rename** isn't a devtools op (name is the key) → delete-old + add-new (with the delete confirm).
+
+### `search` — find scenarios
+- **`scenario-search`** (fuzzy, ranked over name + description) for discovery ("find login
+  scenarios"). **`scenario-list` with `metadataMatch`** for precise structural lookup ("which
+  scenarios cover `src/auth/login.ts`") — metadata is NOT indexed by `scenario-search`.
+- **Search every enabled platform's server** and union the results (each platform is a separate
+  server with its own store). Report name + description + platform + score; surface scope.
+
+### `sync` — re-validate an existing scenario against current code, repair drift
+- **Target.** `all` → every STALE scenario (those whose `ironbee.coveredPaths` changed since their
+  `ironbee.commit`, or authored as drafts); **`all force`** (a leading `force` token) → EVERY saved
+  scenario regardless of freshness; a name / description → resolve that one (`scenario-search` /
+  `scenario-list`). **Before a batch, list the targets + count first** (e.g. "syncing 3 stale of 7")
+  so the blast radius is visible.
+- **Grouped scenarios.** When several targets share an `ironbee.group` (one high-level flow split
+  across platforms), run them in ascending `ironbee.order` — earlier steps set up state later ones need.
+- **`Mode: check`** (a leading `check` token) → DRY-RUN: run + report drift, do NOT repair or update.
+  Otherwise: run + repair + `scenario-update`.
+- **Run it** (`scenario-run`, against the live app — start it if needed, tear down what you started,
+  same discipline as live authoring) and classify the outcome:
+  - **passes** → still current. (non-check) `scenario-update` to stamp `ironbee.commit` → current HEAD
+    (read via `git rev-parse HEAD`) + `ironbee.liveValidated: true`; done. `scenario-update`
+    shallow-replaces metadata, so read the current metadata and re-send it MERGED with these two
+    keys — don't drop `coveredPaths` / `group` / `argsSchema`.
+  - **fails due to DRIFT** (the *mechanics* broke — the way to reach / drive the flow changed, not the
+    expected outcome) → repair the SCRIPT mechanics only, `scenario-update`, re-run until green, then
+    stamp commit / liveValidated.
+  - **fails due to a real DEFECT** (the app genuinely broke — the expected outcome is unreachable) →
+    **STOP, report the defect to the user, do NOT touch the scenario** (it correctly caught the bug;
+    leave it as-is). This is the "a genuine defect is a STOP, not a workaround" rule.
+  - **the expected outcome legitimately CHANGED** (a deliberate behavior / spec change) → **do NOT
+    auto-edit the assertion**; ask the user — changing *what* a scenario verifies is an authoring
+    decision, not a sync.
+- **Classifying drift vs defect — the load-bearing call.** Repair is the ONLY branch that edits a
+  scenario, so a defect mistaken for drift silently masks a regression. Apply two rules before you
+  repair:
+  1. **HOW-vs-WHAT self-check:** would the fix change *how* the flow reaches its point (driving /
+     locating / navigating steps) or *what* it asserts (the expected terminal outcome / value /
+     state)? Only a HOW change is drift. A WHAT change is never drift — it's a defect (STOP) or a
+     deliberate expectation change (ask). Never edit the assertion to make a run pass.
+  2. **Failure-locus heuristic:** a failure while *reaching / driving* the flow (a step can't locate
+     or progress) leans drift; a failure at the *terminal assertion* after the flow completed (the
+     outcome was reached but is wrong) leans defect.
+  **When uncertain, treat it as a defect and STOP** — never auto-repair on a guess.
+- **Hard rule: sync repairs MECHANICS, never the ASSERTION / expected outcome.** Silently relaxing an
+  assertion to make a stale scenario pass would mask a regression.
+- **Scope / teardown / metadata**: same as `manage` live authoring (project scope by default; stop
+  only what you started; stamp metadata). Report per scenario: repaired / still-fresh / defect-reported
+  / needs-user-decision.
+
+(There is no `run` operation here. Running a saved scenario to **verify** is the verifier's job, via
+`$ironbee-verify scenario:<name>` — not this agent. This agent **manages, searches, and syncs**
+(re-validates + repairs drift in) scenarios; it runs them only to author / validate / repair, never to
+gate completion.)
+
+## Live authoring (default for add / update) — build it against the running app
+
+Don't author a runtime scenario from source guesses (source rarely matches the running system exactly). By **default, drive the app to
+understand it — exactly what you'd do when verifying** (exercise the relevant flow through this platform's tools, whatever it takes) — author from what you actually observe, then validate by running it.
+
+1. **`draft` → skip:** if the prompt says `Mode: draft` (or "source only"), author from source, save,
+   note *"not live-validated — run it to verify"*. Done.
+2. **Start the app only if it isn't already running** (check `docker compose ps` / process / config;
+   track whether YOU started it). Genuinely can't start it → **source-only draft + say so**, don't fail.
+3. **Understand it by running probe scenarios:** `scenario-add` the draft **under the FINAL scenario
+   name** (step 4 then iterates that SAME entry via `scenario-update` — do NOT spawn a separate
+   `*-probe` / throwaway scenario in the store) and `scenario-run` it to exercise the relevant flow —
+   whatever it takes to learn how the real system behaves — and READ the returned snapshots/results.
+4. **Author the full flow** from what you observed → `scenario-update`. Make it a **verification flow**,
+   not a superficial run: exercise the cycle's evidence tools, capture their output with
+   `returnOutput: true`, and assert / return the expected outcomes — so running it later via
+   `/ironbee-verify scenario:<name>` can judge it and satisfy the gate.
+5. **Validate:** `scenario-run` end-to-end; fix the **SCRIPT** + `scenario-update` until it runs
+   cleanly, and **assert the real terminal outcome — not an optimistic intermediate signal**. Same
+   app/env considerations as any verification run (use a test/staging target for flows with real side
+   effects).
+6. **Teardown — leave a clean store:** `scenario-delete` ANY temporary / probe / throwaway scenario you
+   added this session (anything named `*-probe`, a draft you decided not to keep, an exploratory copy);
+   the store must end with ONLY the finished deliverable scenario(s), never a leftover probe. THEN stop
+   ONLY the app / processes you started.
+7. Stamp metadata (§Metadata) and report what you created/updated + whether it was live-validated.
+
+> **A genuine defect is a STOP, not a workaround.** If validating shows the flow can't legitimately
+> succeed — a real bug makes the expected outcome unreachable (an error, a failed state, wrong
+> resulting data) — do NOT engineer the scenario around it: don't cherry-pick inputs / args / data that
+> dodge the bug, and don't weaken the assertion to an optimistic intermediate signal instead of the
+> real terminal outcome. That yields a green scenario that masks a broken flow and produces a FALSE
+> PASS when it's later run to verify. Instead STOP and report the defect to the user **in your summary,
+> not inside the scenario** — keep the saved scenario a clean verification flow (it asserts the real
+> outcome and will simply fail until the bug is fixed; that's it doing its job). Do NOT bake bug /
+> defect commentary into the scenario's `description` or metadata; `liveValidated: false` is the only
+> signal needed when you couldn't get a passing run — or leave the scenario unsaved. ("Fix until it
+> passes" means fixing the SCRIPT, never working around the app.)
+
+Do all of this through `scenario-add` / `scenario-update` / `scenario-run` — do NOT open a verification
+cycle or call the platform tools directly. That keeps the work gate-orthogonal (no `verification_id`,
+can't false-block a later edit); `scenario-run` runs the platform tools inside the sandbox and returns
+their results.
+
+## Script format
+A scenario `script` is JS run in the devtools sandbox (async — top-level `await`/`return` work).
+It reads params from the `args` binding and invokes the platform's tools via `callTool`:
+
+```js
+const { baseUrl } = args;            // declared via argsSchema
+const result = await callTool('<bare-tool-name>', { /* tool input */ });
+return { ok: true };
+```
+
+`args` is opaque to devtools — document the expected shape in the scenario's `description` and the
+`argsSchema` metadata. **Discover the available `callTool` tool names for a platform from your
+connected MCP tool schemas** (the bare names) — don't guess.
+
+## Metadata conventions (stamp these on add/update)
+- `ironbee.coveredPaths` — source paths the scenario exercises (array), when derivable.
+- `argsSchema` — declared params, e.g. `{ "baseUrl": "string" }`.
+  **Mandatory for any parametric scenario** (run reads it to know what to ask).
+- `ironbee.liveValidated` — `true` when you validated the scenario by running it end-to-end against
+  the live app this session; `false` when authored source-only (`draft`, or the app couldn't be
+  started). Always stamp it.
+- `ironbee.commit` — the commit the scenario was authored against (`git rev-parse HEAD`).
+- `ironbee.group` / `ironbee.order` — for a high-level scenario split across platforms: a shared
+  group slug + integer run order.
+- `scenario-update` does a **shallow replace** of metadata — to change one key, re-send the FULL
+  metadata object (read it first, merge, write back).
+
+The platform sections below tell you each enabled cycle's server, tool prefix, and store dir.
+
+<!--IRONBEE:PLATFORM:browser-->
+<!--/IRONBEE:PLATFORM:browser-->
+
+<!--IRONBEE:PLATFORM:node-->
+<!--/IRONBEE:PLATFORM:node-->
+
+<!--IRONBEE:PLATFORM:backend-->
+<!--/IRONBEE:PLATFORM:backend-->
+
+<!--IRONBEE:PLATFORM:android-->
+<!--/IRONBEE:PLATFORM:android-->

package/dist/clients/codex/agents/ironbee-verifier.md

@@ -15,11 +15,28 @@ session, so the main agent's completion gate sees your work.
   devtools tools; a code-reading "pass" is banned.
 
 ## Scenario
-If the delegating prompt includes a verification **scenario**, it is authoritative — verify
-exactly what it describes, driving each active cycle's tools to exercise precisely the flows,
-states, and endpoints it names (this replaces the default "exercise the changed
-pages/endpoints"). Map each `checks` entry to a scenario step, each `issues` entry to a step
-that failed. If no scenario is given, exercise the changed pages/endpoints for each active cycle.
+The delegating prompt may tell you what to verify in one of two ways:
+
+- **A SAVED scenario** — the prompt says `Saved scenario: <ref>` (`<ref>` is an exact name OR a
+  semantic description; optional `args:` may follow). RESOLVE it: try an exact-name match
+  (`*_scenario-list`) AND a semantic `*_scenario-search` across the enabled platforms, then pick the
+  single strong match. Several plausible matches → ask which; **no match → say so and fall back to
+  discovery** (the free-text path below). Then **run it in ONE call: `*_scenario-run <name>`** (pass
+  any given `args`) — this executes the whole pre-recorded flow, so you do NOT re-discover or drive it
+  step by step (that's the speed win). **JUDGE the result**: functional (the script's returned
+  values / assertions / errors) AND any visual evidence it returned (e.g. screenshots) — then submit the verdict as
+  usual. The scenario's nested tool calls run inside THIS verification cycle, so they satisfy the
+  gate's required-tools for you (as long as the scenario exercises them).
+  **On a PASS verdict, also keep the scenario fresh:** `*_scenario-update` its `ironbee.commit`
+  → current HEAD (`git rev-parse HEAD`) + `liveValidated: true` — read the current metadata and
+  re-send it MERGED (shallow replace; don't drop `coveredPaths` / `group` / `argsSchema`). On a
+  FAIL / defect, do NOT stamp (leave it for `$ironbee-sync-scenario scenario:<name>` or the user).
+- **A FREE-TEXT scenario / file path** — anything else is authoritative: verify exactly what it
+  describes, driving each active cycle's tools to exercise precisely the flows, states, and endpoints
+  it names (this replaces the default "exercise the changed pages/endpoints").
+
+Map each `checks` entry to a scenario step, each `issues` entry to a step that failed. If no scenario
+is given at all, exercise the changed pages/endpoints for each active cycle.
 
 ## Session id — you don't need it
 The `ironbee hook` commands resolve the session automatically from your environment

package/dist/clients/codex/commands/ironbee-manage-scenario/SKILL.main.md

@@ -0,0 +1,102 @@
+---
+name: ironbee-manage-scenario
+description: >
+  Add, update, or delete a reusable IronBee verification scenario by driving the scenario-* MCP
+  tools yourself. Use when the user types `$ironbee-manage-scenario`. Authors the script in the
+  devtools format and saves it to the right platform's store (or finds and updates/deletes one).
+---
+
+# IronBee — Manage scenario
+
+This project runs IronBee in **main-agent** mode — the devtools `*_scenario-*` MCP tools are wired
+into THIS session, so **you** drive them (there is no scenario sub-agent). Add / update / delete a
+reusable verification **scenario**. This is NOT a verification cycle — it submits no verdict and does
+not gate completion.
+
+## Steps
+1. **Resolve intent.** Content to save (inline text or a file path you read) → add/update. A target
+   only described → delete.
+2. **Add vs update (never duplicate).** Before adding, `*_scenario-search` / `*_scenario-list` to
+   check for a same-name / clearly-the-same scenario on the target platform; if it exists → update
+   it instead of creating a duplicate.
+3. **Pick the platform** from what the scenario does (see the platform sections for which platform fits) and author the script (see "Script
+   format"). Call `*_scenario-add` / `*_scenario-update` on **that platform's** server. A high-level
+   scenario spanning platforms → split into one sub-scenario per platform, linked by `ironbee.group`
+   + `ironbee.order` metadata.
+4. **Delete is destructive — always confirm.** Resolve the target, show the matched
+   **name + description + platform**, and ask the user before deleting. Multiple / low-score
+   candidates → list them and ask which. An **update resolved by fuzzy description** also confirms
+   (the script is overwritten); an exact-name update proceeds without confirm.
+5. **Scope**: pass `scope: "project"` (default) unless the user asked for `global`.
+
+## Live authoring (default for add / update) — build it against the running app
+
+Don't author a runtime scenario from source guesses (source rarely matches the running system exactly). By **default, drive the app to
+understand it — exactly what you'd do when verifying** (exercise the relevant flow through this platform's tools, whatever it takes) — author from what you actually observe, then validate by running it. Do this
+entirely through the `*_scenario-*` tools (run discovery via `*_scenario-run`, don't call the platform
+tools directly: that keeps it gate-orthogonal — no `verification_id`, can't false-block a later edit).
+
+1. **`draft` → skip:** if the request begins with `draft` (or says "source only"), author from source,
+   save, note *"not live-validated — run it to verify"*. Done.
+2. **Start the app only if it isn't already running** (track whether YOU started it). Can't start it
+   (missing env/DB/secrets, broken build) → **source-only draft + say so**, don't fail.
+3. **Understand it by running probe scenarios:** `*_scenario-add` the draft **under the FINAL scenario
+   name** (step 4 then iterates that SAME entry via `*_scenario-update` — do NOT spawn a separate
+   `*-probe` / throwaway scenario in the store) and `*_scenario-run` it to exercise the relevant flow —
+   whatever it takes to learn how the real system behaves — and read the returned snapshots/results.
+4. **Author the full flow** from what you observed → `*_scenario-update`. Make it a **verification flow**,
+   not a superficial run: exercise the cycle's evidence tools, capture their output with
+   `returnOutput: true`, and assert / return the expected outcomes — so running it later via
+   `$ironbee-verify scenario:<name>` can judge it and satisfy the gate.
+5. **Validate:** `*_scenario-run` end-to-end; fix the **SCRIPT** + update until it runs cleanly, and
+   **assert the real terminal outcome — not an optimistic intermediate signal**. Same app/env
+   considerations as any verification run (use a test/staging target for flows with real side effects).
+6. **Teardown — leave a clean store:** `*_scenario-delete` ANY temporary / probe / throwaway scenario you
+   added this session (anything named `*-probe`, a draft you decided not to keep, an exploratory copy);
+   the store must end with ONLY the finished deliverable scenario(s), never a leftover probe. THEN stop
+   ONLY the app / processes you started.
+
+> **A genuine defect is a STOP, not a workaround.** If validating shows the flow can't legitimately
+> succeed — a real bug makes the expected outcome unreachable (an error, a failed state, wrong
+> resulting data) — do NOT engineer the scenario around it: don't cherry-pick inputs / args / data that
+> dodge the bug, and don't weaken the assertion to an optimistic intermediate signal instead of the
+> real terminal outcome. That yields a green scenario that masks a broken flow and produces a FALSE
+> PASS when it's later run to verify. Instead STOP and report the defect to the user **in your summary,
+> not inside the scenario** — keep the saved scenario a clean verification flow (it asserts the real
+> outcome and will simply fail until the bug is fixed; that's it doing its job). Do NOT bake bug /
+> defect commentary into the scenario's `description` or metadata; `liveValidated: false` is the only
+> signal needed when you couldn't get a passing run — or leave the scenario unsaved. ("Fix until it
+> passes" means fixing the SCRIPT, never working around the app.)
+
+## Script format
+JS run in the devtools sandbox (async — top-level `await`/`return` work); reads params from `args`:
+
+```js
+const { baseUrl } = args;            // declared via argsSchema
+const result = await callTool('<bare-tool-name>', { /* tool input */ });
+return { ok: true };
+```
+
+Discover the available `callTool` tool names for a platform from your connected MCP schemas — don't
+guess. Document the expected `args` in the `description` + the `argsSchema` metadata.
+
+## Metadata conventions (stamp on add/update)
+- `argsSchema` — declared params, e.g. `{ "baseUrl": "string" }`. **Mandatory for parametric scenarios.**
+- `ironbee.coveredPaths` — source paths exercised (array), when derivable.
+- `ironbee.group` / `ironbee.order` — for a cross-platform split.
+- `*_scenario-update` does a **shallow replace** of metadata — to change one key, re-send the FULL
+  metadata object (read it first, merge, write back).
+
+The platform sections below list each enabled cycle's server, tool prefix, and store dir.
+
+<!--IRONBEE:PLATFORM:browser-->
+<!--/IRONBEE:PLATFORM:browser-->
+
+<!--IRONBEE:PLATFORM:node-->
+<!--/IRONBEE:PLATFORM:node-->
+
+<!--IRONBEE:PLATFORM:backend-->
+<!--/IRONBEE:PLATFORM:backend-->
+
+<!--IRONBEE:PLATFORM:android-->
+<!--/IRONBEE:PLATFORM:android-->

package/dist/clients/codex/commands/ironbee-manage-scenario/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: ironbee-manage-scenario
+description: >
+  Add, update, or delete a reusable IronBee verification scenario by delegating to the
+  ironbee-scenario custom agent. Use when the user types `$ironbee-manage-scenario`. The sub-agent
+  authors the script in the devtools format and saves it to the right platform's store (or finds and
+  updates/deletes an existing one).
+---
+
+# IronBee — Manage scenario
+
+> **Delegate — do NOT run the scenario tools inline.** Spawn the **`ironbee-scenario` custom agent**
+> via `spawn_agent` with `agent_type="ironbee-scenario"` **and `fork_turns="none"`** (the default
+> `fork_turns="all"` silently drops the agent_type → a generic toolless agent). The sub-agent owns
+> the devtools `scenario-*` tools; you don't have them.
+
+Add / update / delete a reusable verification **scenario** by delegating to the `ironbee-scenario`
+custom agent. This is NOT a verification cycle — it submits no verdict and does not gate completion.
+
+## Steps
+1. **If the request points to a file path** (scenario content to save), read that file now and pass
+   its **contents** into the sub-agent's prompt. If a given path doesn't resolve, stop and report
+   `scenario file not found: <path>`.
+2. **Spawn** `spawn_agent` with `agent_type="ironbee-scenario"` and `fork_turns="none"`, passing in
+   `message`:
+   > Operation: manage
+   > Request: \<the user's request — content to add/update, or the target to update/delete>
+   > Scope: \<`global` if the user asked, else `project`>
+   > Mode: \<include `Mode: draft` ONLY if the request begins with a `draft` token (source-only, no app
+   >        run) — otherwise OMIT so the sub-agent authors against the live app>
+   The sub-agent decides add vs update (checks for an existing same-name scenario first), picks the
+   right platform, authors the script — **against the live app by default** (starts the app if needed,
+   observes the real behavior, validates by running once, then cleans up — deletes any probe /
+   throwaway scenarios it added and stops what it started; `draft` skips this)
+   — and stamps metadata (`argsSchema` for parametric ones).
+   **Delete and fuzzy-resolved update ask you to confirm** the matched scenario first — relay that
+   to the user and pass their answer back. **Wait for the sub-agent in the same turn.**
+3. **Relay** the sub-agent's summary (what it created / updated / deleted, on which platform).

package/dist/clients/codex/commands/ironbee-search-scenario/SKILL.main.md

@@ -0,0 +1,37 @@
+---
+name: ironbee-search-scenario
+description: >
+  Find reusable IronBee verification scenarios by name, description, or metadata by driving the
+  scenario-search / scenario-list MCP tools yourself. Use when the user types
+  `$ironbee-search-scenario`. Searches every enabled platform's store.
+---
+
+# IronBee — Search scenarios
+
+This project runs IronBee in **main-agent** mode — the devtools scenario MCP tools are wired into
+THIS session, so **you** drive them. Find saved verification **scenarios**. Read-only.
+
+## Steps
+1. **Pick the surface:**
+   - **`*_scenario-search`** (fuzzy, ranked over name + description) — discovery ("find login
+     scenarios").
+   - **`*_scenario-list` with `metadataMatch`** — precise structural lookup ("which scenarios cover
+     `src/auth/login.ts`"). Metadata is NOT indexed by `scenario-search`, so path/tag lookups use
+     `scenario-list`.
+2. **Search every enabled platform's server** (each platform is a separate server with its own
+   store) and union the results.
+3. **Report** name + description + platform + (for fuzzy search) relevance score; surface scope.
+
+The platform sections below list each enabled cycle's server, tool prefix, and store dir.
+
+<!--IRONBEE:PLATFORM:browser-->
+<!--/IRONBEE:PLATFORM:browser-->
+
+<!--IRONBEE:PLATFORM:node-->
+<!--/IRONBEE:PLATFORM:node-->
+
+<!--IRONBEE:PLATFORM:backend-->
+<!--/IRONBEE:PLATFORM:backend-->
+
+<!--IRONBEE:PLATFORM:android-->
+<!--/IRONBEE:PLATFORM:android-->

package/dist/clients/codex/commands/ironbee-search-scenario/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: ironbee-search-scenario
+description: >
+  Find reusable IronBee verification scenarios by name, description, or metadata by delegating to
+  the ironbee-scenario custom agent. Use when the user types `$ironbee-search-scenario`. The
+  sub-agent searches every enabled platform's store and returns the matches.
+---
+
+# IronBee — Search scenarios
+
+> **Delegate** — spawn the **`ironbee-scenario` custom agent** via `spawn_agent` with
+> `agent_type="ironbee-scenario"` **and `fork_turns="none"`**. The sub-agent owns the scenario tools.
+
+Find saved verification **scenarios**. Read-only.
+
+## Steps
+1. **Spawn** `spawn_agent` with `agent_type="ironbee-scenario"` and `fork_turns="none"`, passing in
+   `message`:
+   > Operation: search
+   > Query: \<the user's description — a name/topic for fuzzy search, or a path/tag for metadata match>
+   The sub-agent picks the right surface (fuzzy name+description vs precise `metadataMatch`), searches
+   **every enabled platform's store**, and unions the results. **Wait for the sub-agent in the same turn.**
+2. **Relay** the matches — name, description, platform, and (for fuzzy search) relevance score.

package/dist/clients/codex/commands/ironbee-sync-scenario/SKILL.main.md

@@ -0,0 +1,55 @@
+---
+name: ironbee-sync-scenario
+description: >
+  Re-validate saved IronBee verification scenarios against the current code and repair MECHANICAL
+  drift, by driving the scenario-* MCP tools yourself. Use when the user types
+  `$ironbee-sync-scenario`. A leading `check` token = dry-run (report drift, no repair).
+---
+
+# IronBee — Sync scenario(s)
+
+This project runs IronBee in **main-agent** mode — the devtools `*_scenario-*` MCP tools are wired
+into THIS session, so **you** drive them. Re-validate + repair saved verification **scenarios**. This
+is NOT a verification cycle — no verdict, no gate.
+
+## Steps
+1. **Resolve mode + target**: strip a leading `check` token (→ dry-run) and a leading `force` token
+   (→ include ALL scenarios, not just stale); remainder = `all` (stale ones; with `force`, every one)
+   or a name / description (one). Empty → `all`. **Print the target list + count before running.**
+   Run targets that share an `ironbee.group` in ascending `ironbee.order` (a flow split across platforms).
+2. **For each target scenario** (resolve via `*_scenario-search` / `*_scenario-list`; `all` = the stale
+   ones — covered files changed since their `ironbee.commit`, or authored as drafts) **run it**
+   (`*_scenario-run`, against the live app — start it if needed, tear down what you started) and classify:
+   - **passes** → still current; (non-check) `*_scenario-update` to stamp `ironbee.commit` → HEAD
+     (read via `git rev-parse HEAD`) + `ironbee.liveValidated: true`. `*_scenario-update`
+     shallow-replaces metadata — read current metadata and re-send it MERGED with these two keys
+     (don't drop `coveredPaths` / `group` / `argsSchema`).
+   - **mechanical DRIFT** (the way to reach / drive the flow changed, not the expected outcome) →
+     repair the SCRIPT mechanics only, `*_scenario-update`, re-run until green, then stamp.
+   - **real DEFECT** (the expected outcome is unreachable — the app broke) → **STOP, report, do NOT
+     touch the scenario.**
+   - **expectation CHANGED** (a deliberate behavior / spec change) → do NOT auto-edit the assertion;
+     ask the user.
+   - **`check` mode** → only run + report drift; never repair / update.
+   - **Classify safely** (repair is the only branch that edits a scenario, so a defect mistaken for
+     drift masks a regression): before repairing, self-check whether the fix changes *how* the flow
+     is driven (drift — OK to repair) or *what* it asserts (never drift — a defect → STOP, or a
+     deliberate change → ask). A failure while reaching / driving the flow leans drift; a failure at
+     the terminal assertion leans defect. **Uncertain → treat as a defect and STOP.**
+3. **Report** per scenario: repaired / still-fresh / defect-reported / needs decision.
+
+**Hard rule: repair MECHANICS, never the ASSERTION / expected outcome** — silently relaxing an
+assertion to make a stale scenario pass would mask a regression. (To just *detect* staleness without
+running anything, use `ironbee scenario status`.)
+
+<!--IRONBEE:PLATFORM:browser-->
+<!--/IRONBEE:PLATFORM:browser-->
+
+<!--IRONBEE:PLATFORM:node-->
+<!--/IRONBEE:PLATFORM:node-->
+
+<!--IRONBEE:PLATFORM:backend-->
+<!--/IRONBEE:PLATFORM:backend-->
+
+<!--IRONBEE:PLATFORM:android-->
+<!--/IRONBEE:PLATFORM:android-->

package/dist/clients/codex/commands/ironbee-sync-scenario/SKILL.md

@@ -0,0 +1,33 @@
+---
+name: ironbee-sync-scenario
+description: >
+  Re-validate saved IronBee verification scenarios against the current code and repair MECHANICAL
+  drift, by delegating to the ironbee-scenario custom agent (operation sync). Use when the user types
+  `$ironbee-sync-scenario`. A leading `check` token = dry-run (report drift, no repair).
+---
+
+# IronBee — Sync scenario(s)
+
+> **Delegate** — spawn the **`ironbee-scenario` custom agent** via `spawn_agent` with
+> `agent_type="ironbee-scenario"` **and `fork_turns="none"`** (the default `fork_turns="all"` silently
+> drops the agent_type → a generic toolless agent). The sub-agent owns the `scenario-*` tools.
+
+Re-validate + repair saved verification **scenarios**. This is NOT a verification cycle.
+
+## Steps
+1. **Resolve the mode + target**: strip a leading `check` token (→ dry-run) and a leading `force` token
+   (→ sync ALL scenarios, not just stale); remainder = `all` (stale ones; `force` = every one) or a
+   name / description (one). Empty → `all`.
+2. **Spawn** `spawn_agent` with `agent_type="ironbee-scenario"` and `fork_turns="none"`, passing in
+   `message`:
+   > Operation: sync
+   > Target: \<`all`, or the name / description>
+   > Force: \<include `Force: all` ONLY if the request began with `force`>
+   > Mode: \<include `Mode: check` ONLY if the request began with `check`; otherwise OMIT>
+   The sub-agent runs each target against the live app, classifies (still-fresh / mechanical drift →
+   repair the SCRIPT only / real defect → STOP + report / expectation changed → ask), and on a
+   non-check run stamps repaired scenarios current. **It repairs MECHANICS, never what a scenario
+   verifies. Wait for the sub-agent in the same turn.**
+3. **Relay** the summary (per scenario: repaired / still-fresh / defect-reported / needs decision).
+
+(To just *detect* staleness without running anything, use `ironbee scenario status`.)

package/dist/clients/codex/commands/ironbee-verify/SKILL.main.md

@@ -42,9 +42,18 @@ A custom verification scenario may be supplied — either **inline text** or a *
 (read at run time). The scenario is whatever the user provided alongside the command, after
 stripping a leading `fix` / `report` mode token.
 
-- **If a scenario is supplied, it is authoritative**: verify exactly what it describes, exercising
-  precisely the flows/states/endpoints it names — this **replaces** the default "exercise the
-  changed pages/endpoints" guidance.
+- **If the scenario part starts with `scenario:`** (after the mode token), everything after `scenario:`
+  (to the end) is a **SAVED scenario reference** (exact name OR semantic description). Resolve it across
+  enabled platforms (`*_scenario-search` for the description + an exact-name `*_scenario-list` match),
+  pick the single strong match (ambiguous → ask; none → say so + fall back to the default flow), then
+  **run it in ONE `*_scenario-run` call** (no re-discovery) and **judge its result (functional) +
+  any returned visual evidence (e.g. screenshots)**. Its nested tool calls satisfy each active cycle's required tools.
+  No exact name needed — e.g. `scenario: the full purchase flow`.
+  **On PASS, keep it fresh:** `*_scenario-update` its `ironbee.commit` → HEAD (`git rev-parse HEAD`)
+  + `liveValidated: true` (re-send the full metadata merged); on FAIL / defect, don't stamp.
+- **If a scenario is supplied (free text), it is authoritative**: verify exactly what it describes,
+  exercising precisely the flows/states/endpoints it names — this **replaces** the default "exercise
+  the changed pages/endpoints" guidance.
 - **If the scenario is (or points to) a file path**, read that file and treat its contents as the
   scenario. Do not assume a fixed location or format.
 - **If the path does not resolve**, stop and report `scenario file not found: <path>`, then ask how

package/dist/clients/codex/commands/ironbee-verify/SKILL.md

@@ -29,18 +29,19 @@ A custom verification scenario may be supplied when this command is invoked —
 
 > The scenario is whatever the user provided alongside `$ironbee-verify`, after stripping a leading `fix` / `report` mode token — the remainder is the scenario; empty remainder → the verifier uses its default flow.
 
-- **If a scenario is supplied, it is authoritative**: the verifier must verify exactly what it describes, exercising precisely the flows/states/endpoints it names — this **replaces** the default "exercise the changed pages/endpoints" guidance.
+- **If the scenario part starts with `scenario:`** (after the mode token), everything after `scenario:` (to the end) is a **SAVED scenario reference** (exact name OR semantic description). Do NOT read a file / treat as free text — relay it to the verifier verbatim as a `Saved scenario: <ref>` line. The verifier resolves it (`scenario-search` + exact-name), runs it in one `scenario-run` call (no re-discovery), and judges the result (functional + any visual evidence). No exact name needed — e.g. `scenario: the full purchase flow`.
+- **If a scenario is supplied (free text), it is authoritative**: the verifier must verify exactly what it describes, exercising precisely the flows/states/endpoints it names — this **replaces** the default "exercise the changed pages/endpoints" guidance.
 - **If the scenario is (or points to) a file path**, read that file with your file-read tool yourself and pass its **contents** into the verifier's prompt (the verifier has no file-read tool). Do not assume a fixed location or format — read whatever path was given.
 - **If the path does not resolve to an existing file**, stop and report `scenario file not found: <path>`, then ask how to proceed — do not delegate with the literal path string or guess a target.
 - **If no scenario is supplied**, the verifier falls back to exercising the changed pages/endpoints per the active cycles.
 
 ## Steps
 
-1. **Resolve the mode and scenario**: strip a leading `fix` / `report` token (see **Mode**); then file path → read it now; inline text → use as-is; empty → none.
+1. **Resolve the mode and scenario**: strip a leading `fix` / `report` token (see **Mode**); then on the remainder — starts with `scenario:` → SAVED scenario reference (the rest after `scenario:`); a file path → read it now; inline text → use as-is; empty → none.
 2. **Spawn the `ironbee-verifier` custom agent** — call `spawn_agent` with **`agent_type="ironbee-verifier"`** AND **`fork_turns="none"`**. The `fork_turns="none"` is REQUIRED: the default `fork_turns="all"` is a full-history fork that silently DROPS the `agent_type` override, giving you a generic agent *without* the verification tools. (Do NOT "act as" the verifier or use a plain generic fork either.) Put the task, the mode, and the resolved scenario in the `message`, e.g.:
    > Verify the current code changes.
    > Mode: \<`fix` in fix mode — OMIT this line entirely in verify-only mode>
-   > Scenario: \<the resolved scenario text, or "none — exercise the changed pages/endpoints">
+   > \<ONE of: `Saved scenario: <ref>` (when `scenario:` was given — the verifier resolves + runs it) — OR — `Scenario: <resolved text>` (free text / file contents) — OR — `Scenario: none — exercise the changed pages/endpoints`>
    The verifier runs `verification-start` (relaying the fix intent to IronBee's completion gate, which then enforces fix-until-pass on you) → drives every active cycle's tools → submits the single verdict, all in this shared session. It resolves the session id from the environment, so you don't pass one.
    **Wait for the verifier in the same turn — do NOT background it.** Let it run to completion and read its verdict before responding; a backgrounded verifier can let your turn end (and the Stop gate fire) before its verdict is recorded.
 3. **Relay the verifier's summary** — the verdict status and, on fail, the issues it found.

package/dist/clients/codex/hooks/activity-end.js

@@ -1 +1 @@
-"use strict";var d=Object.defineProperty;var v=Object.getOwnPropertyDescriptor;var A=Object.getOwnPropertyNames;var w=Object.prototype.hasOwnProperty;var p=(i,t)=>d(i,"name",{value:t,configurable:!0});var E=(i,t)=>{for(var n in t)d(i,n,{get:t[n],enumerable:!0})},b=(i,t,n,o)=>{if(t&&typeof t=="object"||typeof t=="function")for(let e of A(t))!w.call(i,e)&&e!==n&&d(i,e,{get:()=>t[e],enumerable:!(o=v(t,e))||o.enumerable});return i};var h=i=>b(d({},"__esModule",{value:!0}),i);var x={};E(x,{run:()=>k});module.exports=h(x);var a=require("../../../hooks/core/actions"),m=require("../../../hooks/core/activity-end"),r=require("../../../lib/logger"),u=require("../../../lib/output"),f=require("../../../lib/stdin"),l=require("../../../analytics/codex/spawn"),c=require("../../../hooks/core/session-state"),y=require("../util");async function k(i){const t=(0,y.parseCodexHookStdin)((0,f.readStdin)()),n=t.session_id??"default",o=`${i}/.ironbee/sessions/${n}`,e=`${o}/actions.jsonl`;(0,r.setLogFile)(`${o}/session.log`);const g=(0,c.readState)(o)?.activeActivityId??"";if(await(0,m.runActivityEnd)({sessionDir:o,actionsFile:e,projectDir:i,sessionId:n})){const s=Date.now(),S={...(0,a.baseFields)(e),id:(0,a.deterministicSessionEndId)(n),type:"session_end",timestamp:s,session_id:n,duration:(0,a.findDurationSinceLastAction)(e,"session_start",s),reason:"checkpoint"};await(0,a.appendAction)(e,S)}try{const s=(0,c.readState)(o);(0,l.spawnDetachedCodexAnalyticsWorker)({projectDir:i,sessionId:n,rolloutPath:t.transcript_path,userEmail:s?.userEmail??void 0,usageType:s?.usageType??void 0,usagePlan:s?.usagePlan??void 0,activityId:g})}catch(s){r.logger.debug(`codex analytics spawn failed: ${s instanceof Error?s.message:s}`)}r.logger.debug(`activity-end: ${n}`),(0,u.writeAndExit)(JSON.stringify({}),0)}p(k,"run");0&&(module.exports={run});
+"use strict";var d=Object.defineProperty;var A=Object.getOwnPropertyDescriptor;var w=Object.getOwnPropertyNames;var E=Object.prototype.hasOwnProperty;var p=(i,t)=>d(i,"name",{value:t,configurable:!0});var h=(i,t)=>{for(var n in t)d(i,n,{get:t[n],enumerable:!0})},k=(i,t,n,o)=>{if(t&&typeof t=="object"||typeof t=="function")for(let e of w(t))!E.call(i,e)&&e!==n&&d(i,e,{get:()=>t[e],enumerable:!(o=A(t,e))||o.enumerable});return i};var x=i=>k(d({},"__esModule",{value:!0}),i);var C={};h(C,{run:()=>b});module.exports=x(C);var r=require("../../../hooks/core/actions"),m=require("../../../hooks/core/activity-end"),a=require("../../../lib/logger"),u=require("../../../lib/output"),f=require("../../../lib/stdin"),l=require("../../../analytics/codex/spawn"),c=require("../../../hooks/core/session-state"),y=require("../util"),g=require("../../../lib/runtime-paths");async function b(i){const t=(0,y.parseCodexHookStdin)((0,f.readStdin)()),n=t.session_id??"default",o=(0,g.sessionDir)(i,n),e=`${o}/actions.jsonl`;(0,a.setLogFile)(`${o}/session.log`);const S=(0,c.readState)(o)?.activeActivityId??"";if(await(0,m.runActivityEnd)({sessionDir:o,actionsFile:e,projectDir:i,sessionId:n})){const s=Date.now(),v={...(0,r.baseFields)(e),id:(0,r.deterministicSessionEndId)(n),type:"session_end",timestamp:s,session_id:n,duration:(0,r.findDurationSinceLastAction)(e,"session_start",s),reason:"checkpoint"};await(0,r.appendAction)(e,v)}try{const s=(0,c.readState)(o);(0,l.spawnDetachedCodexAnalyticsWorker)({projectDir:i,sessionId:n,rolloutPath:t.transcript_path,userEmail:s?.userEmail??void 0,usageType:s?.usageType??void 0,usagePlan:s?.usagePlan??void 0,activityId:S})}catch(s){a.logger.debug(`codex analytics spawn failed: ${s instanceof Error?s.message:s}`)}a.logger.debug(`activity-end: ${n}`),(0,u.writeAndExit)(JSON.stringify({}),0)}p(b,"run");0&&(module.exports={run});