@ironbee-ai/cli 0.29.0 → 0.30.0

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/require-verification.js

@@ -1,9 +1,9 @@
-"use strict";var u=Object.defineProperty;var j=Object.getOwnPropertyDescriptor;var F=Object.getOwnPropertyNames;var K=Object.prototype.hasOwnProperty;var R=(o,e)=>u(o,"name",{value:e,configurable:!0});var q=(o,e)=>{for(var s in e)u(o,s,{get:e[s],enumerable:!0})},B=(o,e,s,n)=>{if(e&&typeof e=="object"||typeof e=="function")for(let t of F(e))!K.call(o,t)&&t!==s&&u(o,t,{get:()=>e[t],enumerable:!(n=j(e,t))||n.enumerable});return o};var J=o=>B(u({},"__esModule",{value:!0}),o);var H={};q(H,{run:()=>L});module.exports=J(H);var C=require("crypto"),$=require("../../../hooks/core/activity"),i=require("../../../hooks/core/session-state"),x=require("../../../hooks/core/actions"),N=require("../../../hooks/core/verification-lifecycle"),E=require("../../../hooks/core/verification-context"),O=require("../../../lib/config"),m=require("../../../lib/logger"),U=require("../../../lib/recording-tools"),A=require("../../../lib/stdin"),f=require("../util");async function L(o,e){const s=e?.soft===!0,n=(0,f.parseCodexHookStdin)((0,A.readStdin)()),t=n.session_id??"default",r=`${o}/.ironbee/sessions/${t}`,y=`${r}/actions.jsonl`;(0,m.setLogFile)(`${r}/session.log`);const b=(0,i.getActiveVerificationId)(r);if(!b&&!s){const p=`BLOCKED: You must start a verification cycle before using devtools tools.
+"use strict";var u=Object.defineProperty;var K=Object.getOwnPropertyDescriptor;var q=Object.getOwnPropertyNames;var B=Object.prototype.hasOwnProperty;var C=(o,e)=>u(o,"name",{value:e,configurable:!0});var J=(o,e)=>{for(var s in e)u(o,s,{get:e[s],enumerable:!0})},L=(o,e,s,n)=>{if(e&&typeof e=="object"||typeof e=="function")for(let t of q(e))!B.call(o,t)&&t!==s&&u(o,t,{get:()=>e[t],enumerable:!(n=K(e,t))||n.enumerable});return o};var H=o=>L(u({},"__esModule",{value:!0}),o);var M={};J(M,{run:()=>z});module.exports=H(M);var $=require("crypto"),x=require("../../../hooks/core/activity"),i=require("../../../hooks/core/session-state"),N=require("../../../hooks/core/actions"),E=require("../../../hooks/core/verification-lifecycle"),O=require("../../../hooks/core/verification-context"),U=require("../../../lib/config"),m=require("../../../lib/logger"),A=require("../../../lib/recording-tools"),D=require("../../../hooks/core/scenario-tools"),V=require("../../../lib/stdin"),f=require("../util");async function z(o,e){const s=e?.soft===!0,n=(0,f.parseCodexHookStdin)((0,V.readStdin)()),t=n.session_id??"default",r=`${o}/.ironbee/sessions/${t}`,y=`${r}/actions.jsonl`;(0,m.setLogFile)(`${r}/session.log`);const g=(0,D.isScenarioTool)(n.tool_name),h=(0,i.getActiveVerificationId)(r);if(!h&&!s&&!g){const p=`BLOCKED: You must start a verification cycle before using devtools tools.
 
 Start verification first:
   echo '{"session_id":"${t}"}' | ironbee hook verification-start
 
-Then use the verification tools for the active cycle(s) \u2014 mcp__browser-devtools__bdt_* for browser, mcp__node-devtools__ndt_* for node, mcp__backend-devtools__bedt_* for backend, mcp__android-devtools__adt_* for android.`;process.stdout.write(JSON.stringify({hookSpecificOutput:{hookEventName:"PreToolUse",permissionDecision:"deny",permissionDecisionReason:p}})),process.exit(0);return}const g=n.tool_name??"",h=(0,f.extractCodexMcpServer)(g),c=(0,U.recordingToolsForServer)(h),D=c!==null?(0,f.canonicalizeCodexToolName)(g.split("__").pop()??""):"";if(!s&&c!==null&&(0,i.isRecordingRequired)(r)&&!(0,i.isRecordingActive)(r)&&D!==c.startTool){const p=`BLOCKED: Recording is required but not started.
+Then use the verification tools for the active cycle(s) \u2014 mcp__browser-devtools__bdt_* for browser, mcp__node-devtools__ndt_* for node, mcp__backend-devtools__bedt_* for backend, mcp__android-devtools__adt_* for android.`;process.stdout.write(JSON.stringify({hookSpecificOutput:{hookEventName:"PreToolUse",permissionDecision:"deny",permissionDecisionReason:p}})),process.exit(0);return}const _=n.tool_name??"",S=(0,f.extractCodexMcpServer)(_),c=(0,A.recordingToolsForServer)(S),P=c!==null?(0,f.canonicalizeCodexToolName)(_.split("__").pop()??""):"";if(!s&&!g&&c!==null&&(0,i.isRecordingRequired)(r)&&!(0,i.isRecordingActive)(r)&&P!==c.startTool){const p=`BLOCKED: Recording is required but not started.
 
 1. Start recording NOW:
      Use mcp__${c.server}__${c.startTool}
@@ -12,4 +12,4 @@ Then use the verification tools for the active cycle(s) \u2014 mcp__browser-devt
 
 3. **Stop recording BEFORE submitting verdict:**
      Use mcp__${c.server}__${c.stopTool}
-   submit-verdict will reject with "recording is still active" if you skip this.`;process.stdout.write(JSON.stringify({hookSpecificOutput:{hookEventName:"PreToolUse",permissionDecision:"deny",permissionDecisionReason:p}})),process.exit(0);return}await(0,$.startActivity)({sessionDir:r,actionsFile:y,source:"pre_tool_use"});let l=b;s&&!l&&(l=(await(0,N.startVerification)({sessionId:t,sessionDir:r,actionsFile:y,recordingEnabled:!1})).verificationId);const V=(0,i.getActiveTraceId)(r),_=(0,i.getActiveActivityId)(r),k=(0,x.resolveProjectName)(o),v=[`prj:${k}`,`sid:${t}`];_&&v.push(`aid:${_}`),l&&v.push(`vid:${l}`);const P=`ironbee=${v.join(";")}`,a=(0,O.loadConfig)(o),S={...n.tool_input&&typeof n.tool_input=="object"?n.tool_input:{}},d={projectName:k,sessionId:t,activityId:_,verificationId:l,traceId:V,traceState:P,toolCallId:(0,C.randomUUID)()};n.tool_use_id&&(d.toolUseId=n.tool_use_id),d.mcpServer=h??"browser-devtools";const T=(0,i.getUserEmail)(r);T&&(d.userEmail=T),a.collector?.url&&(d.collectorUrl=a.collector.url),a.collector?.oauthToken?d.collectorOAuthToken=a.collector.oauthToken:a.collector?.apiKey&&(d.collectorApiKey=a.collector.apiKey),S._metadata=d;const w={hookEventName:"PreToolUse",permissionDecision:"allow",updatedInput:S},I=(0,E.buildVerificationContextOnceForCycle)({projectDir:o,sessionId:t,sessionDir:r,activeVerificationId:l,config:a});I.length>0&&(w.additionalContext=I),process.stdout.write(JSON.stringify({hookSpecificOutput:w})),m.logger.debug(`require-verification: allowed ${g} with _metadata`),process.exit(0)}R(L,"run");0&&(module.exports={run});
+   submit-verdict will reject with "recording is still active" if you skip this.`;process.stdout.write(JSON.stringify({hookSpecificOutput:{hookEventName:"PreToolUse",permissionDecision:"deny",permissionDecisionReason:p}})),process.exit(0);return}await(0,x.startActivity)({sessionDir:r,actionsFile:y,source:"pre_tool_use"});let d=h;s&&!d&&!g&&(d=(await(0,E.startVerification)({sessionId:t,sessionDir:r,actionsFile:y,recordingEnabled:!1})).verificationId);const j=(0,i.getActiveTraceId)(r),v=(0,i.getActiveActivityId)(r),k=(0,N.resolveProjectName)(o),b=[`prj:${k}`,`sid:${t}`];v&&b.push(`aid:${v}`),d&&b.push(`vid:${d}`);const F=`ironbee=${b.join(";")}`,a=(0,U.loadConfig)(o),T={...n.tool_input&&typeof n.tool_input=="object"?n.tool_input:{}},l={projectName:k,sessionId:t,activityId:v,verificationId:d,traceId:j,traceState:F,toolCallId:(0,$.randomUUID)()};n.tool_use_id&&(l.toolUseId=n.tool_use_id),l.mcpServer=S??"browser-devtools";const w=(0,i.getUserEmail)(r);w&&(l.userEmail=w),a.collector?.url&&(l.collectorUrl=a.collector.url),a.collector?.oauthToken?l.collectorOAuthToken=a.collector.oauthToken:a.collector?.apiKey&&(l.collectorApiKey=a.collector.apiKey),T._metadata=l;const I={hookEventName:"PreToolUse",permissionDecision:"allow",updatedInput:T},R=(0,O.buildVerificationContextOnceForCycle)({projectDir:o,sessionId:t,sessionDir:r,activeVerificationId:d,config:a});R.length>0&&(I.additionalContext=R),process.stdout.write(JSON.stringify({hookSpecificOutput:I})),m.logger.debug(`require-verification: allowed ${_} with _metadata`),process.exit(0)}C(z,"run");0&&(module.exports={run});

package/dist/clients/codex/hooks/track-action.js

@@ -1 +1 @@
-"use strict";var N=Object.defineProperty;var K=Object.getOwnPropertyDescriptor;var W=Object.getOwnPropertyNames;var X=Object.prototype.hasOwnProperty;var b=(t,e)=>N(t,"name",{value:e,configurable:!0});var Z=(t,e)=>{for(var o in e)N(t,o,{get:e[o],enumerable:!0})},ee=(t,e,o,n)=>{if(e&&typeof e=="object"||typeof e=="function")for(let i of W(e))!X.call(t,i)&&i!==o&&N(t,i,{get:()=>e[i],enumerable:!(n=K(e,i))||n.enumerable});return t};var te=t=>ee(N({},"__esModule",{value:!0}),t);var se={};Z(se,{run:()=>ie});module.exports=te(se);var T=require("../../../hooks/core/actions"),v=require("../../../hooks/core/nested-tools"),R=require("../../../import/ids"),r=require("../../../hooks/core/session-state"),P=require("../../../hooks/core/tool-use-stash"),U=require("../../../lib/config"),a=require("../../../lib/logger"),A=require("../../../lib/output"),q=require("../../../lib/recording-tools"),H=require("../../../lib/stdin"),x=require("../../../queue"),l=require("../util");function h(t){if(t==null)return 0;if(typeof t=="string")try{return Buffer.byteLength(t,"utf8")}catch{return 0}try{return Buffer.byteLength(JSON.stringify(t),"utf8")}catch{return 0}}b(h,"safeStringifyBytes");function oe(t){if(t==null)return{isError:!1,errorText:void 0};if(typeof t=="object"&&t!==null){const e=t;if(e.isError===!0||e.is_error===!0){const o=e.error??e.message??e.errorMessage;return{isError:!0,errorText:typeof o=="string"?o:JSON.stringify(e).slice(0,500)}}}if(typeof t=="string"){const e=t;if(/(?:^|\n)Process exited with code [1-9]/.test(e)||/^Exit code:\s*[1-9]/m.test(e)||/apply_patch verification failed/i.test(e)||/failed to find expected lines/i.test(e)||/^\s*Error\b/.test(e)||/(?:^|\n)\[Request interrupted by user\]/.test(e)||/modified since (?:last )?read|stale read/i.test(e)||/file (?:is )?too large|exceeds/i.test(e)||/file not found|No such file or directory|does not exist/i.test(e))return{isError:!0,errorText:e.slice(0,500)}}return{isError:!1,errorText:void 0}}b(oe,"detectFailure");function ne(t){if(t===null||typeof t!="object")return;const e=t._metadata;if(e===null||typeof e!="object")return;const o=e.toolCallId;if(typeof o=="string"&&/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(o))return o}b(ne,"extractMetadataToolCallId");function re(t,e){const o=(0,P.consumeToolUseData)(t,e);if(!o?.start_ns)return null;try{const n=process.hrtime.bigint()-BigInt(o.start_ns);return Number(n/1000000n)}catch(n){return a.logger.debug(`failed to derive duration from stash: ${n}`),null}}b(re,"deriveDurationMs");async function ie(t){const e=(0,l.parseCodexHookStdin)((0,H.readStdin)()),o=e.session_id??"default",n=`${t}/.ironbee/sessions/${o}`,i=`${n}/actions.jsonl`;(0,a.setLogFile)(`${n}/session.log`);const y=e.tool_name??"",d=e.tool_use_id??"",m=e.tool_input,$=m&&typeof m=="object"?{...m,_metadata:void 0}:void 0,w=e.tool_response,s=(0,l.extractCodexMcpServer)(y),z=s==="browser-devtools"||s==="node-devtools"||s==="backend-devtools"||s==="android-devtools",F=re(o,d),c=(0,l.classifyCodexTool)(y),J=z&&(0,v.isNestedToolContainer)(c.tool_name,s),D=J?(0,v.extractNestedToolCallsFromResponse)(w,s):null,g=D!==null?{isError:!1,errorText:void 0}:oe(w);if(z){const C=c.tool_name,f=(0,q.recordingToolsForServer)(s);f!==null&&(C===f.startTool?(0,r.setRecordingActive)(n,!0):C===f.stopTool&&(0,r.setRecordingActive)(n,!1));const E=(0,r.getActiveActivityId)(n),u={...(0,T.baseFields)(i),type:"tool_call",timestamp:Date.now(),tool_type:c.tool_type,tool_name:c.tool_name,mcp_server:c.mcp_server??s,tool_input:$,tool_input_size:h($),tool_response_size:g.isError?0:h(w),duration:F};E&&(u.activity_id=E);const B=ne(m);B!==void 0?u.id=B:d.length>0&&(u.id=(0,R.deriveToolCallEventIdFromToolUseId)(o,d)),d&&(u.tool_use_id=d);const k=(0,r.getActiveVerificationId)(n);k&&(u.verification_id=k);const S=(0,r.getActiveTraceId)(n);if(S&&(u.trace_id=S),g.isError&&(u.error=g.errorText),await(0,T.appendAction)(i,u),J&&!g.isError){const G=D??(0,v.extractNestedToolCalls)($??m,s),L=new Set;for(const _ of G){if(f!==null&&(_.name===f.startTool?((0,r.setRecordingActive)(n,!0),a.logger.debug(`track-action (nested): recording started (${f.cycle})`)):_.name===f.stopTool&&((0,r.setRecordingActive)(n,!1),a.logger.debug(`track-action (nested): recording stopped (${f.cycle})`))),L.has(_.name))continue;L.add(_.name);const I={...(0,T.baseFields)(i),type:"tool_call",timestamp:Date.now(),tool_name:_.name,tool_type:"mcp",tool_input:_.args,duration:null,mcp_server:s};E&&(I.activity_id=E),k&&(I.verification_id=k),S&&(I.trace_id=S),await(0,T.appendAction)(i,I),a.logger.debug(`track-action (nested): ${_.name}`)}}(0,A.writeAndExit)(JSON.stringify({}),0);return}if(!(0,U.isJobQueueEnabled)(t)){(0,A.writeAndExit)(JSON.stringify({}),0);return}const M=(0,r.getActiveActivityId)(n),V=(0,l.extractCodexToolInput)(y,m),Q=h(m),Y=g.isError?0:h(w),p={...(0,T.baseFields)(i),type:"tool_call",timestamp:Date.now(),tool_type:c.tool_type,tool_name:c.tool_name||(0,l.normalizeCodexToolName)(y),mcp_server:c.mcp_server,tool_input:V,tool_input_size:Q,tool_response_size:Y,duration:F};M&&(p.activity_id=M),d.length>0&&(p.id=(0,R.deriveToolCallEventIdFromToolUseId)(o,d)),d&&(p.tool_use_id=d);const O=(0,r.getActiveVerificationId)(n);O&&(p.verification_id=O);const j=(0,r.getActiveTraceId)(n);j&&(p.trace_id=j),g.isError&&(p.error=g.errorText);try{(0,x.submit)(t,o,x.SEND_EVENT_TYPE,p)}catch(C){C instanceof x.JobTooLargeError?a.logger.debug(`track-action: wire event too large for tool_call ${y}; dropping`):a.logger.debug(`queue submit failed for tool_call ${y}: ${C}`)}(0,A.writeAndExit)(JSON.stringify({}),0)}b(ie,"run");0&&(module.exports={run});
+"use strict";var N=Object.defineProperty;var G=Object.getOwnPropertyDescriptor;var K=Object.getOwnPropertyNames;var W=Object.prototype.hasOwnProperty;var b=(t,e)=>N(t,"name",{value:e,configurable:!0});var X=(t,e)=>{for(var o in e)N(t,o,{get:e[o],enumerable:!0})},Z=(t,e,o,n)=>{if(e&&typeof e=="object"||typeof e=="function")for(let i of K(e))!W.call(t,i)&&i!==o&&N(t,i,{get:()=>e[i],enumerable:!(n=G(e,i))||n.enumerable});return t};var ee=t=>Z(N({},"__esModule",{value:!0}),t);var ie={};X(ie,{run:()=>re});module.exports=ee(ie);var T=require("../../../hooks/core/actions"),v=require("../../../hooks/core/nested-tools"),R=require("../../../import/ids"),r=require("../../../hooks/core/session-state"),L=require("../../../hooks/core/tool-use-stash"),P=require("../../../lib/config"),a=require("../../../lib/logger"),h=require("../../../lib/output"),U=require("../../../lib/recording-tools"),q=require("../../../lib/stdin"),x=require("../../../queue"),d=require("../util");function A(t){if(t==null)return 0;if(typeof t=="string")try{return Buffer.byteLength(t,"utf8")}catch{return 0}try{return Buffer.byteLength(JSON.stringify(t),"utf8")}catch{return 0}}b(A,"safeStringifyBytes");function te(t){if(t==null)return{isError:!1,errorText:void 0};if(typeof t=="object"&&t!==null){const e=t;if(e.isError===!0||e.is_error===!0){const o=e.error??e.message??e.errorMessage;return{isError:!0,errorText:typeof o=="string"?o:JSON.stringify(e).slice(0,500)}}}if(typeof t=="string"){const e=t;if(/(?:^|\n)Process exited with code [1-9]/.test(e)||/^Exit code:\s*[1-9]/m.test(e)||/apply_patch verification failed/i.test(e)||/failed to find expected lines/i.test(e)||/^\s*Error\b/.test(e)||/(?:^|\n)\[Request interrupted by user\]/.test(e)||/modified since (?:last )?read|stale read/i.test(e)||/file (?:is )?too large|exceeds/i.test(e)||/file not found|No such file or directory|does not exist/i.test(e))return{isError:!0,errorText:e.slice(0,500)}}return{isError:!1,errorText:void 0}}b(te,"detectFailure");function oe(t){if(t===null||typeof t!="object")return;const e=t._metadata;if(e===null||typeof e!="object")return;const o=e.toolCallId;if(typeof o=="string"&&/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(o))return o}b(oe,"extractMetadataToolCallId");function ne(t,e){const o=(0,L.consumeToolUseData)(t,e);if(!o?.start_ns)return null;try{const n=process.hrtime.bigint()-BigInt(o.start_ns);return Number(n/1000000n)}catch(n){return a.logger.debug(`failed to derive duration from stash: ${n}`),null}}b(ne,"deriveDurationMs");async function re(t){const e=(0,d.parseCodexHookStdin)((0,q.readStdin)()),o=e.session_id??"default",n=`${t}/.ironbee/sessions/${o}`,i=`${n}/actions.jsonl`;(0,a.setLogFile)(`${n}/session.log`);const y=e.tool_name??"",s=e.tool_use_id??"",g=e.tool_input,$=g&&typeof g=="object"?{...g,_metadata:void 0}:void 0,C=e.tool_response,l=(0,d.extractCodexMcpServer)(y),z=l==="browser-devtools"||l==="node-devtools"||l==="backend-devtools"||l==="android-devtools",F=ne(o,s),c=(0,d.classifyCodexTool)(y),J=z&&(0,v.isNestedToolContainer)(c.tool_name,l),D=J?(0,v.extractNestedToolCallsFromResponse)(C,l):null,u=D!==null?{isError:!1,errorText:void 0}:te(C);if(z){const w=c.tool_name,f=(0,U.recordingToolsForServer)(l);f!==null&&(w===f.startTool?(0,r.setRecordingActive)(n,!0):w===f.stopTool&&(0,r.setRecordingActive)(n,!1));const E=(0,r.getActiveActivityId)(n),m={...(0,T.baseFields)(i),type:"tool_call",timestamp:Date.now(),tool_type:c.tool_type,tool_name:c.tool_name,mcp_server:c.mcp_server??l,tool_input:$,tool_input_size:A($),tool_response:u.isError?void 0:C,tool_response_size:u.isError?0:A(C),duration:F};E&&(m.activity_id=E);const B=oe(g);B!==void 0?m.id=B:s.length>0&&(m.id=(0,R.deriveToolCallEventIdFromToolUseId)(o,s)),s&&(m.tool_use_id=s);const k=(0,r.getActiveVerificationId)(n);k&&(m.verification_id=k);const I=(0,r.getActiveTraceId)(n);if(I&&(m.trace_id=I),u.isError&&(m.error=u.errorText),await(0,T.appendAction)(i,m),J&&!u.isError){const Y=D??(0,v.extractNestedToolCalls)($??g,l);for(const _ of Y){f!==null&&(_.name===f.startTool?((0,r.setRecordingActive)(n,!0),a.logger.debug(`track-action (nested): recording started (${f.cycle})`)):_.name===f.stopTool&&((0,r.setRecordingActive)(n,!1),a.logger.debug(`track-action (nested): recording stopped (${f.cycle})`)));const S={...(0,T.baseFields)(i),type:"tool_call",timestamp:_.startTime??Date.now(),tool_name:_.name,tool_type:"mcp",tool_input:_.args,duration:_.duration??null,mcp_server:l,nested:!0,...s?{parent_tool_use_id:s}:{}};E&&(S.activity_id=E),k&&(S.verification_id=k),I&&(S.trace_id=I),await(0,T.appendAction)(i,S),a.logger.debug(`track-action (nested): ${_.name}`)}}(0,h.writeAndExit)(JSON.stringify({}),0);return}if(!(0,P.isJobQueueEnabled)(t)){(0,h.writeAndExit)(JSON.stringify({}),0);return}const M=(0,r.getActiveActivityId)(n),H=(0,d.extractCodexToolInput)(y,g),V=A(g),Q=u.isError?0:A(C),p={...(0,T.baseFields)(i),type:"tool_call",timestamp:Date.now(),tool_type:c.tool_type,tool_name:c.tool_name||(0,d.normalizeCodexToolName)(y),mcp_server:c.mcp_server,tool_input:H,tool_input_size:V,tool_response_size:Q,duration:F};M&&(p.activity_id=M),s.length>0&&(p.id=(0,R.deriveToolCallEventIdFromToolUseId)(o,s)),s&&(p.tool_use_id=s);const O=(0,r.getActiveVerificationId)(n);O&&(p.verification_id=O);const j=(0,r.getActiveTraceId)(n);j&&(p.trace_id=j),u.isError&&(p.error=u.errorText);try{(0,x.submit)(t,o,x.SEND_EVENT_TYPE,p)}catch(w){w instanceof x.JobTooLargeError?a.logger.debug(`track-action: wire event too large for tool_call ${y}; dropping`):a.logger.debug(`queue submit failed for tool_call ${y}: ${w}`)}(0,h.writeAndExit)(JSON.stringify({}),0)}b(re,"run");0&&(module.exports={run});

package/dist/clients/codex/index.js

@@ -1,3 +1,3 @@
-"use strict";var _=Object.defineProperty;var Z=Object.getOwnPropertyDescriptor;var j=Object.getOwnPropertyNames;var ee=Object.prototype.hasOwnProperty;var y=(f,e)=>_(f,"name",{value:e,configurable:!0});var oe=(f,e)=>{for(var o in e)_(f,o,{get:e[o],enumerable:!0})},ne=(f,e,o,s)=>{if(e&&typeof e=="object"||typeof e=="function")for(let i of j(e))!ee.call(f,i)&&i!==o&&_(f,i,{get:()=>e[i],enumerable:!(s=Z(e,i))||s.enumerable});return f};var te=f=>ne(_({},"__esModule",{value:!0}),f);var le={};oe(le,{CodexClient:()=>se});module.exports=te(le);var r=require("fs"),g=require("path"),O=require("../../lib/gitignore"),b=require("../../lib/logger"),d=require("../../lib/output"),P=require("../../lib/fs-prune"),c=require("../../lib/config"),C=require("../../lib/platform-section"),n=require("./util"),M=require("./thread-map"),L=require("./hooks/verify-gate"),F=require("./hooks/activity-end"),G=require("./hooks/session-start"),J=require("./hooks/activity-start"),K=require("./hooks/require-verification"),U=require("./hooks/require-verdict"),q=require("./hooks/clear-verdict"),D=require("./hooks/track-action"),X=require("./hooks/track-action-monitor"),W=require("./hooks/track-action-pre"),Y=require("./hooks/subagent-start"),z=require("./hooks/subagent-stop");const x="browser-devtools",w="node-devtools",E="backend-devtools",T="android-devtools",ie="ironbee",k="ironbee-verifier",R=30,V="Verifies recent code changes through real browser/runtime/backend tools and submits the IronBee verdict. Spawn this custom agent (by agent_type) after editing code to run the verification cycle out-of-band \u2014 it drives the devtools tools, judges the result, and records the verdict in the shared session. It does NOT edit code.";function A(f){return(0,g.join)(__dirname,"..",f,"platforms")}y(A,"platformsDirFor");function h(f){return d.pc.dim(f)}y(h,"codexColor");function B(f){return f.hooks.some(e=>e.command.includes(ie))}y(B,"isIronBeeHookGroup");function re(f){const e=Object.keys(f);return e.length===0?!0:e.length===1&&e[0]==="hooks"?Object.keys(f.hooks??{}).length===0:!1}y(re,"isCodexHooksEmpty");class se{constructor(){this.name="codex";this.supportsVerifierModel=!0}static{y(this,"CodexClient")}detect(e){return(0,r.existsSync)((0,g.join)(e,".agents","skills","ironbee-verify"))}resolveProjectDir(){return process.env.CODEX_PROJECT_DIR??process.env.IRONBEE_PROJECT_DIR??process.cwd()}install(e,o){const s=o??(0,c.loadConfig)(e),i=(0,c.getVerificationMode)(s),t=i!=="monitor",a=(0,c.getCodexVerifierMode)(s);this.cleanupArtifacts(e);const l=(0,n.codexHooksJsonPath)(e);if(this.mergeHooksConfig(l,i,a),this.mergeConfigToml(e,s,t,a),t&&(i==="enforce"&&this.writeAgentsMdBlock(e,s,a),this.writeSkills(e,i==="enforce",s,a),(0,C.syncPlatformSectionsToConfig)(e,A)),(0,O.ensureIronBeeGitignored)(e),console.log(`  ${d.pc.dim("\u2192")} ${h("[codex]")} hooks    ${d.pc.dim("\u2192")} ${d.pc.dim(l)}`),console.log(`  ${d.pc.dim("\u2192")} ${h("[codex]")} config   ${d.pc.dim("\u2192")} ${d.pc.dim((0,n.codexConfigTomlPath)(e))}`),t){const p=a==="main-agent"?`${d.pc.yellow("main-agent")} (the main agent drives the devtools tools directly)`:`${d.pc.bold("sub-agent")} (delegated to the ironbee-verifier custom agent)`;console.log(`  ${d.pc.dim("\u2192")} ${h("[codex]")} verify   ${d.pc.dim("\u2192")} ${p}`)}i==="enforce"?(console.log(`  ${d.pc.dim("\u2192")} ${h("[codex]")} agents   ${d.pc.dim("\u2192")} ${d.pc.dim((0,g.join)(e,"AGENTS.md"))}`),console.log(`  ${d.pc.dim("\u2192")} ${h("[codex]")} skill    ${d.pc.dim("\u2192")} ${d.pc.dim((0,g.join)(e,".agents","skills","ironbee-verification","SKILL.md"))}`),console.log(`  ${d.pc.dim("\u2192")} ${h("[codex]")} command  ${d.pc.dim("\u2192")} ${d.pc.dim((0,g.join)(e,".agents","skills","ironbee-verify","SKILL.md"))}`)):i==="assist"?(console.log(`  ${d.pc.dim("\u2192")} ${h("[codex]")} ${d.pc.yellow("assist mode")} (verification.auto: false) \u2014 manual $ironbee-verify only, no enforcement`),console.log(`  ${d.pc.dim("\u2192")} ${h("[codex]")} command  ${d.pc.dim("\u2192")} ${d.pc.dim((0,g.join)(e,".agents","skills","ironbee-verify","SKILL.md"))}`)):console.log(`  ${d.pc.dim("\u2192")} ${h("[codex]")} ${d.pc.yellow("monitoring-only mode")} (verification.enable: false)`),console.log(),console.log(`  ${d.pc.yellow("\u26A0")} ${d.pc.yellow("Codex requires one-time TUI setup:")}`),console.log(`    ${d.pc.yellow("1.")} Run ${d.pc.bold("/hooks")} in a fresh Codex session to review and trust IronBee hooks`),console.log(`    ${d.pc.yellow("2.")} Restart any open Codex sessions to pick up new hook config`)}uninstall(e){this.cleanupArtifacts(e),(0,r.existsSync)((0,n.codexHooksJsonPath)(e))||this.removeFeaturesHooksFlag(e),(0,P.pruneEmptyDirs)((0,g.join)(e,".codex"));const o=(0,M.codexThreadMapPath)(e);if((0,r.existsSync)(o))try{(0,r.unlinkSync)(o)}catch(s){b.logger.debug(`failed to remove codex thread map: ${s}`)}console.log(`  ${d.pc.dim("\u2192")} ${h("[codex]")} removed hooks, MCP entries, AGENTS.md block, and skills`)}removeFeaturesHooksFlag(e){const o=(0,n.codexConfigTomlPath)(e);if((0,r.existsSync)(o))try{const s=(0,r.readFileSync)(o,"utf-8"),i=(0,n.removeFeaturesHooks)(s);i.trim().length===0?(0,r.unlinkSync)(o):i!==s&&(0,r.writeFileSync)(o,i)}catch(s){b.logger.debug(`failed to strip [features] hooks from config.toml: ${s}`)}}cleanupArtifacts(e){this.migrateAwayFromUserLevel();const o=(0,n.codexHooksJsonPath)(e);this.removeIronBeeHooks(o),this.maybeDeleteEmptyHooks(o),this.removeIronBeeMcpServers(e),this.removeVerifierAgentToml(e);const s=(0,g.join)(e,"AGENTS.md");if((0,r.existsSync)(s))try{const t=(0,r.readFileSync)(s,"utf-8"),a=(0,n.stripAgentsMdBlock)(t);a===null?(0,r.unlinkSync)(s):a!==t&&(0,r.writeFileSync)(s,a)}catch(t){b.logger.debug(`failed to strip AGENTS.md block: ${t}`)}const i=(0,g.join)(e,".agents","skills");this.removeDir((0,g.join)(i,"ironbee-verification")),this.removeDir((0,g.join)(i,"ironbee-verify")),(0,P.pruneEmptyDirs)((0,g.join)(e,".agents"))}async runVerifyGate(e){await(0,L.run)(e)}async runActivityEnd(e){await(0,F.run)(e)}async runSessionStart(e){await(0,G.run)(e)}async runActivityStart(e){await(0,J.run)(e)}async runRequireVerification(e,o){await(0,K.run)(e,o)}async runRequireVerdict(e,o){await(0,U.run)(e,o)}async runClearVerdict(e){await(0,q.run)(e)}async runTrackAction(e){await(0,D.run)(e)}async runTrackActionMonitor(e){await(0,X.run)(e)}async runTrackActionPre(e){await(0,W.run)(e)}async runSubagentStart(e){await(0,Y.run)(e)}async runSubagentStop(e){await(0,z.run)(e)}resolveAgentSessionId(e,o){const s=process.env.CODEX_THREAD_ID;if(typeof s=="string"&&s.length>0&&o)return(0,M.lookupThreadSession)(o,s)}async runSessionEnd(e){b.logger.debug("session-end: no-op on Codex (no SessionEnd hook event)")}mergeHooksConfig(e,o,s){const i=o!=="monitor",t=o==="assist"?" --soft":"";(0,r.mkdirSync)((0,g.dirname)(e),{recursive:!0});let a={hooks:{}};if((0,r.existsSync)(e))try{a=JSON.parse((0,r.readFileSync)(e,"utf-8")),a.hooks||(a.hooks={})}catch(u){b.logger.debug(`failed to parse ${e}: ${u}`),a={hooks:{}}}for(const u of Object.keys(a.hooks)){const m=a.hooks[u].filter(S=>!B(S));m.length===0?delete a.hooks[u]:a.hooks[u]=m}const l=y((u,m,S)=>{a.hooks[u]||(a.hooks[u]=[]),a.hooks[u].push({matcher:m,hooks:[{type:"command",command:S}]})},"addGroup");l("SessionStart",".*","ironbee hook session-start --client codex"),l("UserPromptSubmit",".*","ironbee hook activity-start --client codex"),l("PreToolUse",".*","ironbee hook track-action-pre --client codex"),i&&(l("PreToolUse","^mcp__(browser|node|backend|android)[-_]devtools__.*",`ironbee hook require-verification --client codex${t}`),l("PreToolUse","^apply_patch$",`ironbee hook require-verdict --client codex${t}`),l("PostToolUse","^apply_patch$","ironbee hook clear-verdict --client codex"),s==="sub-agent"&&l("SubagentStart",".*","ironbee hook subagent-start --client codex")),l("SubagentStop",".*","ironbee hook subagent-stop --client codex"),l("PostToolUse",".*",i?"ironbee hook track-action --client codex":"ironbee hook track-action-monitor --client codex"),l("Stop",".*",o==="enforce"?"ironbee hook verify-gate --client codex":"ironbee hook activity-end --client codex"),(0,r.writeFileSync)(e,JSON.stringify(a,null,2))}removeIronBeeHooks(e){if((0,r.existsSync)(e))try{const o=(0,r.readFileSync)(e,"utf-8"),s=JSON.parse(o);if(!s.hooks)return;let i=!1;for(const t of Object.keys(s.hooks)){const a=s.hooks[t].filter(l=>!B(l));a.length!==s.hooks[t].length&&(i=!0),a.length===0?delete s.hooks[t]:s.hooks[t]=a}i&&(0,r.writeFileSync)(e,JSON.stringify(s,null,2))}catch(o){b.logger.debug(`failed to strip IronBee hooks from ${e}: ${o}`)}}maybeDeleteEmptyHooks(e){if((0,r.existsSync)(e))try{const o=JSON.parse((0,r.readFileSync)(e,"utf-8"));re(o)&&(0,r.unlinkSync)(e)}catch(o){b.logger.debug(`failed to inspect ${e} for emptiness: ${o}`)}}mergeConfigToml(e,o,s,i){(0,r.mkdirSync)((0,g.join)(e,".codex"),{recursive:!0});let t=(0,n.readCodexConfigToml)(e);if(t=(0,n.ensureFeaturesHooksTrue)(t),t=(0,n.removeMcpServer)(t,x),t=(0,n.removeMcpServer)(t,w),t=(0,n.removeMcpServer)(t,E),t=(0,n.removeMcpServer)(t,T),s&&i==="main-agent"){t=this.upsertSessionMcpServers(t,e,o),t=(0,n.removeAgentsTable)(t,k),t=(0,n.removeMultiAgentV2SpawnMetadata)(t),this.removeVerifierAgentToml(e),(0,n.writeCodexConfigToml)(e,t);return}if(s){const a=(0,c.getVerificationModel)(o,"codex"),l=(0,r.existsSync)((0,n.userCodexConfigTomlPath)())?(0,r.readFileSync)((0,n.userCodexConfigTomlPath)(),"utf-8"):"",p=(0,n.extractTomlTopLevelModel)(t)===null&&(0,n.extractTomlTopLevelModel)(l)===null;a===void 0&&p&&console.log(`  ${d.pc.dim("\u2192")} ${h("[codex]")} ${d.pc.yellow("\u26A0 no model for the verifier")} \u2014 the ${d.pc.bold("ironbee-verifier")} sub-agent inherits the session model, but neither this project's .codex/config.toml nor ~/.codex/config.toml has a top-level ${d.pc.bold("model")}, so it may fail to spawn ("could not resolve the child model"). Fix: set ${d.pc.bold("model")} in ~/.codex/config.toml, or set ${d.pc.bold("verification.model")} in your ironbee config.`),this.writeVerifierAgentToml(e,o,a),t=(0,n.upsertAgentsTable)(t,k,[`description = ${JSON.stringify(V)}`,`config_file = ${JSON.stringify(`agents/${k}.toml`)}`]),t=(0,n.ensureMultiAgentV2SpawnMetadataExposed)(t)}else t=(0,n.removeAgentsTable)(t,k),t=(0,n.removeMultiAgentV2SpawnMetadata)(t),this.removeVerifierAgentToml(e);(0,n.writeCodexConfigToml)(e,t)}writeVerifierAgentToml(e,o,s){const i=(0,g.join)(__dirname,"agents",`${k}.md`);let t;try{t=(0,r.readFileSync)(i,"utf-8")}catch(u){b.logger.debug(`failed to read verifier agent source ${i}: ${u}`);return}const a=A("codex");for(const u of c.ALL_CYCLES){const S=(0,c.isCycleEnabled)(o,u)?H=>{const $=(0,g.join)(a,(0,C.fragmentFilename)("skill",u,H));return(0,r.existsSync)($)?(0,r.readFileSync)($,"utf-8").trimEnd():null}:null;t=(0,C.applyPlatformSection)(t,u,S,`${k}.toml`)}const l=[];l.push(`name = ${JSON.stringify(k)}`),l.push(`description = ${JSON.stringify(V)}`),l.push('sandbox_mode = "read-only"'),s&&l.push(`model = ${JSON.stringify(s)}`),l.push("developer_instructions = '''"),l.push(t.replace(/'''/g,"```").trimEnd()),l.push("'''");const p=y((u,m,S)=>{u&&(l.push(""),l.push(`[mcp_servers.${m}]`),l.push(...N(S)),l.push(`startup_timeout_sec = ${R}`),l.push("required = true"),l.push('default_tools_approval_mode = "approve"'))},"addCycle");p((0,c.isCycleEnabled)(o,"browser"),x,(0,c.getMcpServerEntry)(e)),p((0,c.isCycleEnabled)(o,"node"),w,(0,c.getNodeDevToolsMcpEntry)(e)),p((0,c.isCycleEnabled)(o,"backend"),E,(0,c.getBackendDevToolsMcpEntry)(e)),p((0,c.isCycleEnabled)(o,"android"),T,(0,c.getAndroidDevToolsMcpEntry)(e));const v=(0,n.codexAgentTomlPath)(e,k);(0,r.mkdirSync)((0,g.dirname)(v),{recursive:!0}),(0,r.writeFileSync)(v,l.join(`
+"use strict";var R=Object.defineProperty;var te=Object.getOwnPropertyDescriptor;var ie=Object.getOwnPropertyNames;var re=Object.prototype.hasOwnProperty;var S=(f,e)=>R(f,"name",{value:e,configurable:!0});var se=(f,e)=>{for(var o in e)R(f,o,{get:e[o],enumerable:!0})},ae=(f,e,o,r)=>{if(e&&typeof e=="object"||typeof e=="function")for(let i of ie(e))!re.call(f,i)&&i!==o&&R(f,i,{get:()=>e[i],enumerable:!(r=te(e,i))||r.enumerable});return f};var le=f=>ae(R({},"__esModule",{value:!0}),f);var me={};se(me,{CodexClient:()=>ge});module.exports=le(me);var s=require("fs"),g=require("path"),K=require("../../lib/gitignore"),p=require("../../lib/logger"),l=require("../../lib/output"),B=require("../../lib/fs-prune"),d=require("../../lib/config"),C=require("../../lib/platform-section"),n=require("./util"),H=require("./thread-map"),U=require("./hooks/verify-gate"),q=require("./hooks/activity-end"),D=require("./hooks/session-start"),X=require("./hooks/activity-start"),W=require("./hooks/require-verification"),Y=require("./hooks/require-verdict"),z=require("./hooks/clear-verdict"),Q=require("./hooks/track-action"),Z=require("./hooks/track-action-monitor"),j=require("./hooks/track-action-pre"),ee=require("./hooks/subagent-start"),oe=require("./hooks/subagent-stop");const E="browser-devtools",A="node-devtools",_="backend-devtools",I="android-devtools",ce="ironbee",$="ironbee-verifier",V=30,N="Verifies recent code changes through real browser/runtime/backend tools and submits the IronBee verdict. Spawn this custom agent (by agent_type) after editing code to run the verification cycle out-of-band \u2014 it drives the devtools tools, judges the result, and records the verdict in the shared session. It does NOT edit code.",x="ironbee-scenario",L=["ironbee-manage-scenario","ironbee-search-scenario","ironbee-sync-scenario"],J="Manages and searches reusable IronBee verification scenarios via the devtools scenario tools. Spawn this custom agent (by agent_type) from the scenario slash commands to author/update/delete saved scenarios and find them by name/description/metadata. NOT a verification cycle (running a saved scenario to verify is done via $ironbee-verify scenario:<name>).";function P(f){return(0,g.join)(__dirname,"..",f,"platforms")}S(P,"platformsDirFor");function y(f){return l.pc.dim(f)}S(y,"codexColor");function F(f){return f.hooks.some(e=>e.command.includes(ce))}S(F,"isIronBeeHookGroup");function de(f){const e=Object.keys(f);return e.length===0?!0:e.length===1&&e[0]==="hooks"?Object.keys(f.hooks??{}).length===0:!1}S(de,"isCodexHooksEmpty");class ge{constructor(){this.name="codex";this.supportsVerifierModel=!0}static{S(this,"CodexClient")}detect(e){return(0,s.existsSync)((0,g.join)(e,".agents","skills","ironbee-verify"))}resolveProjectDir(){return process.env.CODEX_PROJECT_DIR??process.env.IRONBEE_PROJECT_DIR??process.cwd()}install(e,o){const r=o??(0,d.loadConfig)(e),i=(0,d.getVerificationMode)(r),t=i!=="monitor",a=(0,d.getCodexVerifierMode)(r);this.cleanupArtifacts(e);const m=(0,n.codexHooksJsonPath)(e);if(this.mergeHooksConfig(m,i,a),this.mergeConfigToml(e,r,t,a),t&&(i==="enforce"&&this.writeAgentsMdBlock(e,r,a),this.writeSkills(e,i==="enforce",r,a),(0,C.syncPlatformSectionsToConfig)(e,P)),(0,K.ensureIronBeeGitignored)(e),console.log(`  ${l.pc.dim("\u2192")} ${y("[codex]")} hooks    ${l.pc.dim("\u2192")} ${l.pc.dim(m)}`),console.log(`  ${l.pc.dim("\u2192")} ${y("[codex]")} config   ${l.pc.dim("\u2192")} ${l.pc.dim((0,n.codexConfigTomlPath)(e))}`),t){const b=a==="main-agent"?`${l.pc.yellow("main-agent")} (the main agent drives the devtools tools directly)`:`${l.pc.bold("sub-agent")} (delegated to the ironbee-verifier custom agent)`;console.log(`  ${l.pc.dim("\u2192")} ${y("[codex]")} verify   ${l.pc.dim("\u2192")} ${b}`)}i==="enforce"?(console.log(`  ${l.pc.dim("\u2192")} ${y("[codex]")} agents   ${l.pc.dim("\u2192")} ${l.pc.dim((0,g.join)(e,"AGENTS.md"))}`),console.log(`  ${l.pc.dim("\u2192")} ${y("[codex]")} skill    ${l.pc.dim("\u2192")} ${l.pc.dim((0,g.join)(e,".agents","skills","ironbee-verification","SKILL.md"))}`),console.log(`  ${l.pc.dim("\u2192")} ${y("[codex]")} command  ${l.pc.dim("\u2192")} ${l.pc.dim((0,g.join)(e,".agents","skills","ironbee-verify","SKILL.md"))}`)):i==="assist"?(console.log(`  ${l.pc.dim("\u2192")} ${y("[codex]")} ${l.pc.yellow("assist mode")} (verification.auto: false) \u2014 manual $ironbee-verify only, no enforcement`),console.log(`  ${l.pc.dim("\u2192")} ${y("[codex]")} command  ${l.pc.dim("\u2192")} ${l.pc.dim((0,g.join)(e,".agents","skills","ironbee-verify","SKILL.md"))}`)):console.log(`  ${l.pc.dim("\u2192")} ${y("[codex]")} ${l.pc.yellow("monitoring-only mode")} (verification.enable: false)`),console.log(),console.log(`  ${l.pc.yellow("\u26A0")} ${l.pc.yellow("Codex requires one-time TUI setup:")}`),console.log(`    ${l.pc.yellow("1.")} Run ${l.pc.bold("/hooks")} in a fresh Codex session to review and trust IronBee hooks`),console.log(`    ${l.pc.yellow("2.")} Restart any open Codex sessions to pick up new hook config`)}uninstall(e){this.cleanupArtifacts(e),(0,s.existsSync)((0,n.codexHooksJsonPath)(e))||this.removeFeaturesHooksFlag(e),(0,B.pruneEmptyDirs)((0,g.join)(e,".codex"));const o=(0,H.codexThreadMapPath)(e);if((0,s.existsSync)(o))try{(0,s.unlinkSync)(o)}catch(r){p.logger.debug(`failed to remove codex thread map: ${r}`)}console.log(`  ${l.pc.dim("\u2192")} ${y("[codex]")} removed hooks, MCP entries, AGENTS.md block, and skills`)}removeFeaturesHooksFlag(e){const o=(0,n.codexConfigTomlPath)(e);if((0,s.existsSync)(o))try{const r=(0,s.readFileSync)(o,"utf-8"),i=(0,n.removeFeaturesHooks)(r);i.trim().length===0?(0,s.unlinkSync)(o):i!==r&&(0,s.writeFileSync)(o,i)}catch(r){p.logger.debug(`failed to strip [features] hooks from config.toml: ${r}`)}}cleanupArtifacts(e){this.migrateAwayFromUserLevel();const o=(0,n.codexHooksJsonPath)(e);this.removeIronBeeHooks(o),this.maybeDeleteEmptyHooks(o),this.removeIronBeeMcpServers(e),this.removeVerifierAgentToml(e),this.removeScenarioAgentToml(e);const r=(0,g.join)(e,"AGENTS.md");if((0,s.existsSync)(r))try{const t=(0,s.readFileSync)(r,"utf-8"),a=(0,n.stripAgentsMdBlock)(t);a===null?(0,s.unlinkSync)(r):a!==t&&(0,s.writeFileSync)(r,a)}catch(t){p.logger.debug(`failed to strip AGENTS.md block: ${t}`)}const i=(0,g.join)(e,".agents","skills");this.removeDir((0,g.join)(i,"ironbee-verification")),this.removeDir((0,g.join)(i,"ironbee-verify"));for(const t of L)this.removeDir((0,g.join)(i,t));this.removeDir((0,g.join)(i,"ironbee-run-scenario")),(0,B.pruneEmptyDirs)((0,g.join)(e,".agents"))}async runVerifyGate(e){await(0,U.run)(e)}async runActivityEnd(e){await(0,q.run)(e)}async runSessionStart(e){await(0,D.run)(e)}async runActivityStart(e){await(0,X.run)(e)}async runRequireVerification(e,o){await(0,W.run)(e,o)}async runRequireVerdict(e,o){await(0,Y.run)(e,o)}async runClearVerdict(e){await(0,z.run)(e)}async runTrackAction(e){await(0,Q.run)(e)}async runTrackActionMonitor(e){await(0,Z.run)(e)}async runTrackActionPre(e){await(0,j.run)(e)}async runSubagentStart(e){await(0,ee.run)(e)}async runSubagentStop(e){await(0,oe.run)(e)}resolveAgentSessionId(e,o){const r=process.env.CODEX_THREAD_ID;if(typeof r=="string"&&r.length>0&&o)return(0,H.lookupThreadSession)(o,r)}async runSessionEnd(e){p.logger.debug("session-end: no-op on Codex (no SessionEnd hook event)")}mergeHooksConfig(e,o,r){const i=o!=="monitor",t=o==="assist"?" --soft":"";(0,s.mkdirSync)((0,g.dirname)(e),{recursive:!0});let a={hooks:{}};if((0,s.existsSync)(e))try{a=JSON.parse((0,s.readFileSync)(e,"utf-8")),a.hooks||(a.hooks={})}catch(v){p.logger.debug(`failed to parse ${e}: ${v}`),a={hooks:{}}}for(const v of Object.keys(a.hooks)){const c=a.hooks[v].filter(h=>!F(h));c.length===0?delete a.hooks[v]:a.hooks[v]=c}const m=S((v,c,h)=>{a.hooks[v]||(a.hooks[v]=[]),a.hooks[v].push({matcher:c,hooks:[{type:"command",command:h}]})},"addGroup");m("SessionStart",".*","ironbee hook session-start --client codex"),m("UserPromptSubmit",".*","ironbee hook activity-start --client codex"),m("PreToolUse",".*","ironbee hook track-action-pre --client codex"),i&&(m("PreToolUse","^mcp__(browser|node|backend|android)[-_]devtools__.*",`ironbee hook require-verification --client codex${t}`),m("PreToolUse","^apply_patch$",`ironbee hook require-verdict --client codex${t}`),m("PostToolUse","^apply_patch$","ironbee hook clear-verdict --client codex"),r==="sub-agent"&&m("SubagentStart",".*","ironbee hook subagent-start --client codex")),m("SubagentStop",".*","ironbee hook subagent-stop --client codex"),m("PostToolUse",".*",i?"ironbee hook track-action --client codex":"ironbee hook track-action-monitor --client codex"),m("Stop",".*",o==="enforce"?"ironbee hook verify-gate --client codex":"ironbee hook activity-end --client codex"),(0,s.writeFileSync)(e,JSON.stringify(a,null,2))}removeIronBeeHooks(e){if((0,s.existsSync)(e))try{const o=(0,s.readFileSync)(e,"utf-8"),r=JSON.parse(o);if(!r.hooks)return;let i=!1;for(const t of Object.keys(r.hooks)){const a=r.hooks[t].filter(m=>!F(m));a.length!==r.hooks[t].length&&(i=!0),a.length===0?delete r.hooks[t]:r.hooks[t]=a}i&&(0,s.writeFileSync)(e,JSON.stringify(r,null,2))}catch(o){p.logger.debug(`failed to strip IronBee hooks from ${e}: ${o}`)}}maybeDeleteEmptyHooks(e){if((0,s.existsSync)(e))try{const o=JSON.parse((0,s.readFileSync)(e,"utf-8"));de(o)&&(0,s.unlinkSync)(e)}catch(o){p.logger.debug(`failed to inspect ${e} for emptiness: ${o}`)}}mergeConfigToml(e,o,r,i){(0,s.mkdirSync)((0,g.join)(e,".codex"),{recursive:!0});let t=(0,n.readCodexConfigToml)(e);if(t=(0,n.ensureFeaturesHooksTrue)(t),t=(0,n.removeMcpServer)(t,E),t=(0,n.removeMcpServer)(t,A),t=(0,n.removeMcpServer)(t,_),t=(0,n.removeMcpServer)(t,I),r&&i==="main-agent"){t=this.upsertSessionMcpServers(t,e,o),t=(0,n.removeAgentsTable)(t,$),t=(0,n.removeAgentsTable)(t,x),t=(0,n.removeMultiAgentV2SpawnMetadata)(t),this.removeVerifierAgentToml(e),this.removeScenarioAgentToml(e),(0,n.writeCodexConfigToml)(e,t);return}if(r){const a=(0,d.getVerificationModel)(o,"codex"),m=(0,s.existsSync)((0,n.userCodexConfigTomlPath)())?(0,s.readFileSync)((0,n.userCodexConfigTomlPath)(),"utf-8"):"",b=(0,n.extractTomlTopLevelModel)(t)===null&&(0,n.extractTomlTopLevelModel)(m)===null;a===void 0&&b&&console.log(`  ${l.pc.dim("\u2192")} ${y("[codex]")} ${l.pc.yellow("\u26A0 no model for the verifier")} \u2014 the ${l.pc.bold("ironbee-verifier")} sub-agent inherits the session model, but neither this project's .codex/config.toml nor ~/.codex/config.toml has a top-level ${l.pc.bold("model")}, so it may fail to spawn ("could not resolve the child model"). Fix: set ${l.pc.bold("model")} in ~/.codex/config.toml, or set ${l.pc.bold("verification.model")} in your ironbee config.`),this.writeVerifierAgentToml(e,o,a),t=(0,n.upsertAgentsTable)(t,$,[`description = ${JSON.stringify(N)}`,`config_file = ${JSON.stringify(`agents/${$}.toml`)}`]),t=(0,n.ensureMultiAgentV2SpawnMetadataExposed)(t),this.writeScenarioAgentToml(e,o,a),t=(0,n.upsertAgentsTable)(t,x,[`description = ${JSON.stringify(J)}`,`config_file = ${JSON.stringify(`agents/${x}.toml`)}`])}else t=(0,n.removeAgentsTable)(t,$),t=(0,n.removeAgentsTable)(t,x),t=(0,n.removeMultiAgentV2SpawnMetadata)(t),this.removeVerifierAgentToml(e),this.removeScenarioAgentToml(e);(0,n.writeCodexConfigToml)(e,t)}writeVerifierAgentToml(e,o,r){this.writeCustomAgentToml(e,o,r,$,N,"skill","read-only")}writeScenarioAgentToml(e,o,r){this.writeCustomAgentToml(e,o,r,x,J,"scenario","read-only")}writeCustomAgentToml(e,o,r,i,t,a,m){const b=(0,g.join)(__dirname,"agents",`${i}.md`);let u;try{u=(0,s.readFileSync)(b,"utf-8")}catch(k){p.logger.debug(`failed to read agent source ${b}: ${k}`);return}const v=P("codex");for(const k of d.ALL_CYCLES){const w=(0,d.isCycleEnabled)(o,k)?ne=>{const O=(0,g.join)(v,(0,C.fragmentFilename)(a,k,ne));return(0,s.existsSync)(O)?(0,s.readFileSync)(O,"utf-8").trimEnd():null}:null;u=(0,C.applyPlatformSection)(u,k,w,`${i}.toml`)}const c=[];c.push(`name = ${JSON.stringify(i)}`),c.push(`description = ${JSON.stringify(t)}`),c.push(`sandbox_mode = ${JSON.stringify(m)}`),r&&c.push(`model = ${JSON.stringify(r)}`),c.push("developer_instructions = '''"),c.push(u.replace(/'''/g,"```").trimEnd()),c.push("'''");const h=S((k,T,w)=>{k&&(c.push(""),c.push(`[mcp_servers.${T}]`),c.push(...G(w)),c.push(`startup_timeout_sec = ${V}`),c.push("required = true"),c.push('default_tools_approval_mode = "approve"'))},"addCycle");h((0,d.isCycleEnabled)(o,"browser"),E,(0,d.getMcpServerEntry)(e)),h((0,d.isCycleEnabled)(o,"node"),A,(0,d.getNodeDevToolsMcpEntry)(e)),h((0,d.isCycleEnabled)(o,"backend"),_,(0,d.getBackendDevToolsMcpEntry)(e)),h((0,d.isCycleEnabled)(o,"android"),I,(0,d.getAndroidDevToolsMcpEntry)(e));const M=(0,n.codexAgentTomlPath)(e,i);(0,s.mkdirSync)((0,g.dirname)(M),{recursive:!0}),(0,s.writeFileSync)(M,c.join(`
 `)+`
-`)}upsertSessionMcpServers(e,o,s){let i=e;const t=y((a,l,p)=>{if(!a)return;const v=[...N(p),`startup_timeout_sec = ${R}`,'default_tools_approval_mode = "approve"'];i=(0,n.upsertMcpServer)(i,l,v)},"addCycle");return t((0,c.isCycleEnabled)(s,"browser"),x,(0,c.getMcpServerEntry)(o)),t((0,c.isCycleEnabled)(s,"node"),w,(0,c.getNodeDevToolsMcpEntry)(o)),t((0,c.isCycleEnabled)(s,"backend"),E,(0,c.getBackendDevToolsMcpEntry)(o)),t((0,c.isCycleEnabled)(s,"android"),T,(0,c.getAndroidDevToolsMcpEntry)(o)),i}removeVerifierAgentToml(e){const o=(0,n.codexAgentTomlPath)(e,k);if((0,r.existsSync)(o))try{(0,r.unlinkSync)(o)}catch(s){b.logger.debug(`failed to remove verifier agent toml: ${s}`)}}removeIronBeeMcpServers(e){let o=(0,n.readCodexConfigToml)(e);o&&(o=(0,n.removeMcpServer)(o,x),o=(0,n.removeMcpServer)(o,w),o=(0,n.removeMcpServer)(o,E),o=(0,n.removeMcpServer)(o,T),o=(0,n.removeAgentsTable)(o,k),o=(0,n.removeMultiAgentV2SpawnMetadata)(o),(0,n.writeCodexConfigToml)(e,o))}migrateAwayFromUserLevel(){const e=(0,n.userCodexHooksJsonPath)();this.removeIronBeeHooks(e),this.maybeDeleteEmptyHooks(e);const o=(0,n.userCodexConfigTomlPath)();if((0,r.existsSync)(o))try{let i=(0,r.readFileSync)(o,"utf-8");const t=i;i=(0,n.removeMcpServer)(i,x),i=(0,n.removeMcpServer)(i,w),i=(0,n.removeMcpServer)(i,E),i=(0,n.removeMcpServer)(i,T),i=(0,n.removeAgentsTable)(i,k),i=(0,n.removeMultiAgentV2SpawnMetadata)(i),i!==t&&(0,r.writeFileSync)(o,i)}catch(i){b.logger.debug(`migrate: failed to clean user-level config.toml: ${i}`)}const s=(0,n.userCodexAgentTomlPath)(k);if((0,r.existsSync)(s))try{(0,r.unlinkSync)(s)}catch(i){b.logger.debug(`migrate: failed to remove user-level verifier toml: ${i}`)}}writeAgentsMdBlock(e,o,s){const i=(0,g.join)(e,"AGENTS.md"),t=s==="main-agent"?"ironbee-verification.main.md":"ironbee-verification.md",a=(0,g.join)(__dirname,"rules",t);let l;try{l=(0,r.readFileSync)(a,"utf-8")}catch(m){b.logger.debug(`failed to read rule source ${a}: ${m}`);return}const p=A("codex");for(const m of c.ALL_CYCLES){const H=(0,c.isCycleEnabled)(o,m)?$=>{const I=(0,g.join)(p,(0,C.fragmentFilename)("rule",m,$));if(!(0,r.existsSync)(I)){const Q=$.length>0?`${m}:${$}`:m;return b.logger.debug(`AGENTS.md platform-section ${Q}: missing fragment ${I}, using placeholder`),null}return(0,r.readFileSync)(I,"utf-8").trimEnd()}:null;l=(0,C.applyPlatformSection)(l,m,H,"AGENTS.md")}const v=(0,r.existsSync)(i)?(0,r.readFileSync)(i,"utf-8"):"",u=(0,n.upsertAgentsMdBlock)(v,l);(0,r.writeFileSync)(i,u)}writeSkills(e,o,s,i){const t=(0,g.join)(e,".agents","skills"),a=i==="main-agent";if(o){const v=(0,g.join)(t,"ironbee-verification");(0,r.mkdirSync)(v,{recursive:!0});const u=(0,g.join)(__dirname,"skills",a?"ironbee-verification.main.md":"ironbee-verification.md");try{let m=(0,r.readFileSync)(u,"utf-8");a&&(m=this.spliceCycleFragments(m,"skill",s,"ironbee-verification/SKILL.md")),(0,r.writeFileSync)((0,g.join)(v,"SKILL.md"),m)}catch(m){b.logger.debug(`failed to copy skill ${u}: ${m}`)}}const l=(0,g.join)(t,"ironbee-verify");(0,r.mkdirSync)(l,{recursive:!0});const p=(0,g.join)(__dirname,"commands","ironbee-verify",a?"SKILL.main.md":"SKILL.md");try{let v=(0,r.readFileSync)(p,"utf-8");a&&(v=this.spliceCycleFragments(v,"command-verify",s,"ironbee-verify/SKILL.md")),(0,r.writeFileSync)((0,g.join)(l,"SKILL.md"),v)}catch(v){b.logger.debug(`failed to copy verify command ${p}: ${v}`)}}spliceCycleFragments(e,o,s,i){const t=A("codex");let a=e;for(const l of c.ALL_CYCLES){const v=(0,c.isCycleEnabled)(s,l)?u=>{const m=(0,g.join)(t,(0,C.fragmentFilename)(o,l,u));return(0,r.existsSync)(m)?(0,r.readFileSync)(m,"utf-8").trimEnd():null}:null;a=(0,C.applyPlatformSection)(a,l,v,i)}return a}removeDir(e){if((0,r.existsSync)(e))try{(0,r.rmSync)(e,{recursive:!0,force:!0})}catch(o){b.logger.debug(`failed to remove ${e}: ${o}`)}}}function N(f){return(0,n.tomlBodyFromRecord)(f)}y(N,"mcpEntryToTomlBody");0&&(module.exports={CodexClient});
+`)}upsertSessionMcpServers(e,o,r){let i=e;const t=S((a,m,b)=>{if(!a)return;const u=[...G(b),`startup_timeout_sec = ${V}`,'default_tools_approval_mode = "approve"'];i=(0,n.upsertMcpServer)(i,m,u)},"addCycle");return t((0,d.isCycleEnabled)(r,"browser"),E,(0,d.getMcpServerEntry)(o)),t((0,d.isCycleEnabled)(r,"node"),A,(0,d.getNodeDevToolsMcpEntry)(o)),t((0,d.isCycleEnabled)(r,"backend"),_,(0,d.getBackendDevToolsMcpEntry)(o)),t((0,d.isCycleEnabled)(r,"android"),I,(0,d.getAndroidDevToolsMcpEntry)(o)),i}removeVerifierAgentToml(e){const o=(0,n.codexAgentTomlPath)(e,$);if((0,s.existsSync)(o))try{(0,s.unlinkSync)(o)}catch(r){p.logger.debug(`failed to remove verifier agent toml: ${r}`)}}removeScenarioAgentToml(e){const o=(0,n.codexAgentTomlPath)(e,x);if((0,s.existsSync)(o))try{(0,s.unlinkSync)(o)}catch(r){p.logger.debug(`failed to remove scenario agent toml: ${r}`)}}removeIronBeeMcpServers(e){let o=(0,n.readCodexConfigToml)(e);o&&(o=(0,n.removeMcpServer)(o,E),o=(0,n.removeMcpServer)(o,A),o=(0,n.removeMcpServer)(o,_),o=(0,n.removeMcpServer)(o,I),o=(0,n.removeAgentsTable)(o,$),o=(0,n.removeAgentsTable)(o,x),o=(0,n.removeMultiAgentV2SpawnMetadata)(o),(0,n.writeCodexConfigToml)(e,o))}migrateAwayFromUserLevel(){const e=(0,n.userCodexHooksJsonPath)();this.removeIronBeeHooks(e),this.maybeDeleteEmptyHooks(e);const o=(0,n.userCodexConfigTomlPath)();if((0,s.existsSync)(o))try{let i=(0,s.readFileSync)(o,"utf-8");const t=i;i=(0,n.removeMcpServer)(i,E),i=(0,n.removeMcpServer)(i,A),i=(0,n.removeMcpServer)(i,_),i=(0,n.removeMcpServer)(i,I),i=(0,n.removeAgentsTable)(i,$),i=(0,n.removeMultiAgentV2SpawnMetadata)(i),i!==t&&(0,s.writeFileSync)(o,i)}catch(i){p.logger.debug(`migrate: failed to clean user-level config.toml: ${i}`)}const r=(0,n.userCodexAgentTomlPath)($);if((0,s.existsSync)(r))try{(0,s.unlinkSync)(r)}catch(i){p.logger.debug(`migrate: failed to remove user-level verifier toml: ${i}`)}}writeAgentsMdBlock(e,o,r){const i=(0,g.join)(e,"AGENTS.md"),t=r==="main-agent"?"ironbee-verification.main.md":"ironbee-verification.md",a=(0,g.join)(__dirname,"rules",t);let m;try{m=(0,s.readFileSync)(a,"utf-8")}catch(c){p.logger.debug(`failed to read rule source ${a}: ${c}`);return}const b=P("codex");for(const c of d.ALL_CYCLES){const M=(0,d.isCycleEnabled)(o,c)?k=>{const T=(0,g.join)(b,(0,C.fragmentFilename)("rule",c,k));if(!(0,s.existsSync)(T)){const w=k.length>0?`${c}:${k}`:c;return p.logger.debug(`AGENTS.md platform-section ${w}: missing fragment ${T}, using placeholder`),null}return(0,s.readFileSync)(T,"utf-8").trimEnd()}:null;m=(0,C.applyPlatformSection)(m,c,M,"AGENTS.md")}const u=(0,s.existsSync)(i)?(0,s.readFileSync)(i,"utf-8"):"",v=(0,n.upsertAgentsMdBlock)(u,m);(0,s.writeFileSync)(i,v)}writeSkills(e,o,r,i){const t=(0,g.join)(e,".agents","skills"),a=i==="main-agent";if(o){const u=(0,g.join)(t,"ironbee-verification");(0,s.mkdirSync)(u,{recursive:!0});const v=(0,g.join)(__dirname,"skills",a?"ironbee-verification.main.md":"ironbee-verification.md");try{let c=(0,s.readFileSync)(v,"utf-8");a&&(c=this.spliceCycleFragments(c,"skill",r,"ironbee-verification/SKILL.md")),(0,s.writeFileSync)((0,g.join)(u,"SKILL.md"),c)}catch(c){p.logger.debug(`failed to copy skill ${v}: ${c}`)}}const m=(0,g.join)(t,"ironbee-verify");(0,s.mkdirSync)(m,{recursive:!0});const b=(0,g.join)(__dirname,"commands","ironbee-verify",a?"SKILL.main.md":"SKILL.md");try{let u=(0,s.readFileSync)(b,"utf-8");a&&(u=this.spliceCycleFragments(u,"command-verify",r,"ironbee-verify/SKILL.md")),(0,s.writeFileSync)((0,g.join)(m,"SKILL.md"),u)}catch(u){p.logger.debug(`failed to copy verify command ${b}: ${u}`)}for(const u of L){const v=(0,g.join)(t,u);(0,s.mkdirSync)(v,{recursive:!0});const c=(0,g.join)(__dirname,"commands",u,a?"SKILL.main.md":"SKILL.md");try{let h=(0,s.readFileSync)(c,"utf-8");a&&(h=this.spliceCycleFragments(h,"scenario",r,`${u}/SKILL.md`)),(0,s.writeFileSync)((0,g.join)(v,"SKILL.md"),h)}catch(h){p.logger.debug(`failed to copy scenario command ${c}: ${h}`)}}}spliceCycleFragments(e,o,r,i){const t=P("codex");let a=e;for(const m of d.ALL_CYCLES){const u=(0,d.isCycleEnabled)(r,m)?v=>{const c=(0,g.join)(t,(0,C.fragmentFilename)(o,m,v));return(0,s.existsSync)(c)?(0,s.readFileSync)(c,"utf-8").trimEnd():null}:null;a=(0,C.applyPlatformSection)(a,m,u,i)}return a}removeDir(e){if((0,s.existsSync)(e))try{(0,s.rmSync)(e,{recursive:!0,force:!0})}catch(o){p.logger.debug(`failed to remove ${e}: ${o}`)}}}function G(f){return(0,n.tomlBodyFromRecord)(f)}S(G,"mcpEntryToTomlBody");0&&(module.exports={CodexClient});

package/dist/clients/codex/platforms/scenario.android.md

@@ -0,0 +1,31 @@
+### android platform (enabled)
+- **Use for**: Android app scenarios on a real device / emulator.
+- **Server**: `android-devtools` · **scenario tools**: the `adt_scenario-*` tools
+  (`adt_scenario-add` / `-update` / `-delete` / `-list` / `-search` / `-run`).
+- **Store**: project → `.ironbee/scenarios/adt`, global → `~/.ironbee/scenarios/adt` (the
+  server's `SCENARIOS_DIR`; you pass `scope`, the server resolves the path).
+- Scenario **scripts** call this platform's tools via `callTool('<bare-tool>', {...})` — discover
+  the available `adt_*` tool names from your connected MCP tool schemas; don't guess.
+
+**What to test & how — capture the SAME evidence the verifier would** (a scenario runs FOR
+verification, so its script must collect what the android cycle collects). In the script:
+1. **Connect + launch** — `adt_device_connect` (list targets with `adt_device_list-targets`; an
+   emulator is usually `emulator-5554`), then `adt_device_launch-app` with the package name.
+2. Pick an **evidence path** for the changed code area:
+   - **Device-evidence path** — drive the UI to exercise the change (`adt_interaction_tap` /
+     `adt_interaction_input-text` / `adt_interaction_swipe` / `adt_interaction_scroll`; locate elements
+     with `adt_a11y_find-element` / the UI-snapshot's element refs — do NOT hand-parse the snapshot
+     TEXT with regex), then capture **BOTH**: a screenshot (`adt_content_take-screenshot`
+     **with `returnOutput: true`** — put the returned `filePath` in your result; the verifier `Read`s
+     that file to judge the pixels. **Do NOT set `includeBase64`** — a nested scenario screenshot isn't
+     surfaced as an inline image and base64 only bloats the result) **AND** a UI snapshot
+     (`adt_a11y_take-ui-snapshot`, `returnOutput: true` — its TEXT view hierarchy / labels is what the
+     verifier reads). Both are MANDATORY (visual + structural, like the browser screenshot + aria pair).
+   - **Log-evidence path** — `adt_o11y_log-read` / `adt_o11y_log-follow` (with `returnOutput: true`)
+     for the tag(s) relevant to the change; confirm expected lines appear AND no FATAL / crash (E/
+     entries) for the app package.
+
+`return` the evidence — UI-snapshot text, log lines, the screenshot `filePath`s — **plus explicit
+pass/fail assertions**. That returned result is what `$ironbee-verify scenario:<name>` reads to judge
+functional + structural (from the text) and **visual** (by `Read`ing the returned screenshot files).
+**`android-devtools` is Android-only.**

package/dist/clients/codex/platforms/scenario.backend.md

@@ -0,0 +1,26 @@
+### backend platform (enabled)
+- **Use for**: backend protocol scenarios (HTTP / gRPC / GraphQL / WebSocket / DB).
+- **Server**: `backend-devtools` · **scenario tools**: the `bedt_scenario-*` tools
+  (`bedt_scenario-add` / `-update` / `-delete` / `-list` / `-search` / `-run`).
+- **Store**: project → `.ironbee/scenarios/bedt`, global → `~/.ironbee/scenarios/bedt` (the
+  server's `SCENARIOS_DIR`; you pass `scope`, the server resolves the path).
+- Scenario **scripts** call this platform's tools via `callTool('<bare-tool>', {...})` — discover
+  the available `bedt_*` tool names from your connected MCP tool schemas; don't guess.
+
+**What to test & how — capture the SAME evidence the verifier would** (a scenario runs FOR
+verification, so its script must collect what the backend cycle collects). At least ONE evidence path
+is required — in the script, exercise one+:
+- **Protocol-call** — `bedt_request_http` / `bedt_request_grpc` / `bedt_request_graphql` /
+  `bedt_request_websocket-open…` / `bedt_request_replay`; inspect the response `status` / body /
+  headers (4xx/5xx and gRPC non-OK are NORMAL results, not transport errors — decide pass/fail by what
+  the task requires). Chain POST→GET to confirm side effects.
+- **Log-evidence** — `bedt_log_register-source` then `bedt_log_read` / `bedt_log_read-multi` /
+  `bedt_log_follow` (filter by level / pattern / trace-id) when an external driver hits the endpoint.
+- **DB-evidence** — `bedt_db_connect` (read-only by default) then `bedt_db_query` /
+  `bedt_db_describe-table` / `bedt_db_snapshot` + `bedt_db_diff` to inspect state after a migration /
+  write.
+
+`return` the responses / log lines / rows (capture each read with `returnOutput: true` so the data
+reaches the script's `return`) **plus explicit pass/fail assertions** so a later verify run can judge
+them. Runtime-agnostic —
+works for any backend language (Node, Java, Python, Go, Rust, Ruby, .NET, …).

package/dist/clients/codex/platforms/scenario.browser.md

@@ -0,0 +1,40 @@
+### browser platform (enabled)
+- **Use for**: UI / frontend scenarios driven through a real browser.
+- **Server**: `browser-devtools` · **scenario tools**: the `bdt_scenario-*` tools
+  (`bdt_scenario-add` / `-update` / `-delete` / `-list` / `-search` / `-run`).
+- **Store**: project → `.ironbee/scenarios/bdt`, global → `~/.ironbee/scenarios/bdt` (the
+  server's `SCENARIOS_DIR`; you pass `scope`, the server resolves the path).
+- Scenario **scripts** call this platform's tools via `callTool('<bare-tool>', {...})` — discover
+  the available `bdt_*` tool names from your connected MCP tool schemas; don't guess.
+
+**What to test & how — capture the SAME evidence the verifier would** (a scenario runs FOR
+verification, so its script must collect what the browser cycle collects). In the script:
+1. **Navigate** — `bdt_navigation_go-to` to the affected page(s), then **actually interact** (click
+   buttons, fill forms, submit data, trigger the workflow that changed). A click-through that asserts
+   nothing verifies nothing — the interaction is what makes the evidence meaningful. **Target elements
+   with the `selector`/`ref` the aria-snapshot returns for each** (e.g. `getByRole(...)` or `@e12`) —
+   do NOT hand-parse the snapshot TEXT with regex/string-matching: embedded quotes or special chars in
+   labels make that brittle (it silently misses elements). This includes deriving a positional
+   **`.nth(i)`** index by parsing the snapshot — a quote or special char in any earlier label shifts
+   every index, so the click lands on the wrong element (or none). Pick each element by its own
+   `getByRole(...)`/`ref`, or scope it to the matching card/row with a CSS `:has()` selector (e.g.
+   `.product-card:has(h4:has-text('Widget')) button:has-text('Add to cart')`). NOTE: the
+   browser-devtools resolver accepts only a flat `getByXYZ(...)` expression OR a CSS string — Playwright
+   locator chaining like `.filter({ hasText })` does NOT parse. Never compute element positions from
+   snapshot text.
+2. **Screenshot** — `bdt_content_take-screenshot` (or `includeScreenshot: true` on a nav/interaction
+   call) **with `returnOutput: true`, and put the returned `filePath` (absolute path to the saved PNG)
+   in your result**. The later verifier opens that file with its `Read` tool to judge the pixels
+   (readability, layout, cut-off content, expected render). **Do NOT set `includeBase64`** — a nested
+   scenario screenshot is NOT surfaced as an inline MCP image (`scenario-run` strips nested image data)
+   and base64 only bloats the result; the returned `filePath` is how visual judging works.
+3. **Accessibility** — `bdt_a11y_take-aria-snapshot` (or `includeSnapshot: true`), called with
+   `returnOutput: true` — the snapshot TEXT is what the verifier reads to judge page structure.
+4. **Console** — `bdt_o11y_get-console-messages` with `returnOutput: true` to surface errors.
+
+`return` the evidence — aria-snapshot text, page text (`bdt_content_get-as-text`), console errors, the
+screenshot `filePath`s — **plus explicit pass/fail assertions**. That returned result is what
+`$ironbee-verify scenario:<name>` reads to judge the run: functional + structural from the text, and
+**visual by `Read`ing the returned screenshot files**. Capture the evidence AFTER the interactions
+whose state you want to assert; for an intermediate state (a modal that opens then closes) capture at
+that point too.

package/dist/clients/codex/platforms/scenario.node.md

@@ -0,0 +1,27 @@
+### node platform (enabled)
+- **Use for**: Node.js runtime-debug scenarios (V8 inspector probes / logs).
+- **Server**: `node-devtools` · **scenario tools**: the `ndt_scenario-*` tools
+  (`ndt_scenario-add` / `-update` / `-delete` / `-list` / `-search` / `-run`).
+- **Store**: project → `.ironbee/scenarios/ndt`, global → `~/.ironbee/scenarios/ndt` (the
+  server's `SCENARIOS_DIR`; you pass `scope`, the server resolves the path).
+- Scenario **scripts** call this platform's tools via `callTool('<bare-tool>', {...})` — discover
+  the available `ndt_*` tool names from your connected MCP tool schemas; don't guess.
+
+**What to test & how — capture the SAME evidence the verifier would** (a scenario runs FOR
+verification, so its script must collect what the node cycle collects). In the script:
+1. **Connect** — `ndt_debug_connect` (one of `pid` / `processName` / `containerName` /
+   `inspectorPort` / `wsUrl`).
+2. Pick an **evidence path** for the changed code path:
+   - **Probe path** (proves the code path executed) — set a probe at the changed location
+     (`ndt_debug_put-tracepoint` / `ndt_debug_put-logpoint` / `ndt_debug_put-exceptionpoint`),
+     **exercise the path** (drive it via a request / CLI / another platform's call — without this the
+     probe never fires), then read `ndt_debug_get-probe-snapshots`; at least one probe must come back
+     `triggered: true`.
+   - **Log path** (proves no errors during execution) — exercise the path, then `ndt_debug_get-logs`
+     filtered to the error level (no ERROR-level entries = pass).
+
+`return` the probe snapshots / logs (read them with `returnOutput: true` so their data reaches the
+script's `return`) **plus explicit pass/fail assertions** so a later verify run can judge them.
+**`node-devtools` is
+Node.js ONLY** — never author `ndt_*` scenarios for Java / Python / Go / Rust / Ruby / .NET / PHP
+backends; use the **backend** platform for those.

package/dist/clients/codex/util.js

@@ -1,21 +1,21 @@
-"use strict";var k=Object.defineProperty;var E=Object.getOwnPropertyDescriptor;var L=Object.getOwnPropertyNames;var W=Object.prototype.hasOwnProperty;var o=(n,t)=>k(n,"name",{value:t,configurable:!0});var M=(n,t)=>{for(var e in t)k(n,e,{get:t[e],enumerable:!0})},P=(n,t,e,s)=>{if(t&&typeof t=="object"||typeof t=="function")for(let r of L(t))!W.call(n,r)&&r!==e&&k(n,r,{get:()=>t[r],enumerable:!(s=E(t,r))||s.enumerable});return n};var J=n=>P(k({},"__esModule",{value:!0}),n);var mn={};M(mn,{AGENTS_MD_END_MARKER:()=>x,AGENTS_MD_START_MARKER:()=>I,canonicalizeCodexServerName:()=>C,canonicalizeCodexToolName:()=>$,classifyCodexTool:()=>V,codexAgentTomlPath:()=>rn,codexConfigTomlPath:()=>T,codexHooksJsonPath:()=>cn,decodeJwtPayload:()=>A,ensureFeaturesHooksTrue:()=>Z,ensureMultiAgentV2SpawnMetadataExposed:()=>Q,extractBashBinary:()=>j,extractCodexMcpServer:()=>S,extractCodexToolInput:()=>D,extractTomlTopLevelModel:()=>sn,findTomlSection:()=>_,normalizeCodexToolName:()=>R,parseCodexHookStdin:()=>B,readCodexConfigToml:()=>ln,removeAgentsTable:()=>en,removeFeaturesHooks:()=>q,removeMcpServer:()=>nn,removeMultiAgentV2SpawnMetadata:()=>Y,resolveCodexUsage:()=>U,stripAgentsMdBlock:()=>an,tomlBodyFromRecord:()=>on,upsertAgentsMdBlock:()=>un,upsertAgentsTable:()=>tn,upsertMcpServer:()=>N,userCodexAgentTomlPath:()=>pn,userCodexConfigTomlPath:()=>gn,userCodexHooksJsonPath:()=>fn,writeCodexConfigToml:()=>dn});module.exports=J(mn);var m=require("fs"),b=require("os"),p=require("path"),y=require("../../lib/logger");function B(n){try{return JSON.parse(n)}catch(t){return y.logger.debug(`failed to parse Codex hook stdin: ${t}`),{}}}o(B,"parseCodexHookStdin");const h="mcp__",z={browser_devtools:"browser-devtools",node_devtools:"node-devtools",backend_devtools:"backend-devtools",android_devtools:"android-devtools"},H=["bdt_","ndt_","bedt_","adt_"];function C(n){return z[n]??n}o(C,"canonicalizeCodexServerName");function $(n){if(!H.some(e=>n.startsWith(e)))return n;const t=n.split("_");return t.length<=3?n:`${t[0]}_${t[1]}_${t.slice(2).join("-")}`}o($,"canonicalizeCodexToolName");const F=[["bdt_","browser-devtools"],["ndt_","node-devtools"],["bedt_","backend-devtools"],["adt_","android-devtools"]];function S(n){if(!n)return null;if(n.startsWith(h)){const t=n.slice(h.length),e=t.indexOf("__");return e<0?null:C(t.slice(0,e))}for(const[t,e]of F)if(n.startsWith(t))return e;return null}o(S,"extractCodexMcpServer");function R(n){return n==="exec_command"?"Bash":n==="apply_patch"?"Edit":n==="update_plan"?"TodoWrite":n==="read_file"?"Read":n==="web_search"?"WebSearch":n==="web_fetch"?"WebFetch":n}o(R,"normalizeCodexToolName");function V(n){if(!n)return{tool_type:null,tool_name:"",mcp_server:null};if(n.startsWith(h)){const s=n.slice(h.length),r=s.indexOf("__");if(r>=0){const i=s.slice(0,r),u=C(i),a=s.slice(r+2);return{tool_type:"mcp",tool_name:$(a),mcp_server:u}}}const t=S(n);if(t!==null&&!n.startsWith(h))return{tool_type:"mcp",tool_name:$(n),mcp_server:t};const e=R(n);return n==="spawn_agent"||n==="wait_agent"||n==="close_agent"?{tool_type:"sub_agent",tool_name:e,mcp_server:null}:{tool_type:null,tool_name:e,mcp_server:null}}o(V,"classifyCodexTool");function D(n,t){if(!n||t===void 0)return;if(n==="apply_patch"){if(typeof t=="string")return{input_size:t.length};if(typeof t=="object"&&t!==null){const r=t,i=r.command??r.input;if(typeof i=="string")return{input_size:i.length}}return{input_size:void 0}}if(typeof t!="object"||t===null)return;const e=t;if(R(n)==="Bash"){const r=e.cmd??e.command,i=typeof r=="string"?j(r):void 0;return{workdir:e.workdir,binary:i}}if(n==="update_plan"){const r=e.explanation,i=e.plan;return{explanation:typeof r=="string"?r:void 0,plan_step_count:Array.isArray(i)?i.length:void 0}}if(n==="spawn_agent"){const r=e.agent_type,i=e.message,u=e.fork_context;return{agent_type:typeof r=="string"?r:void 0,message_size:typeof i=="string"?i.length:void 0,fork_context:typeof u=="boolean"?u:void 0}}if(n==="wait_agent"){const r=e.targets,i=e.timeout_ms;return{target_count:Array.isArray(r)?r.length:void 0,timeout_ms:typeof i=="number"?i:void 0}}if(n==="close_agent"){const r=e.target;return{target:typeof r=="string"?r:void 0}}if(n==="view_image"){const r=e.path,i=e.detail;return{path:typeof r=="string"?r:void 0,detail:typeof i=="string"?i:void 0}}if(n==="write_stdin"){const r=e.session_id,i=e.chars,u=e.yield_time_ms,a=e.max_output_tokens;return{session_id:typeof r=="number"?r:void 0,chars_size:typeof i=="string"?i.length:void 0,yield_time_ms:typeof u=="number"?u:void 0,max_output_tokens:typeof a=="number"?a:void 0}}if(n.startsWith(h)||S(n)!==null){if("_metadata"in e){const{_metadata:r,...i}=e;return i}return e}}o(D,"extractCodexToolInput");function j(n){const t=n.trim();if(!t)return;const e=t.split(/\s+/);for(const s of e)if(!/^[A-Za-z_][A-Za-z0-9_]*=/.test(s)&&s.length>0)return s.split(/[\\/]/).pop()??s}o(j,"extractBashBinary");function A(n){const t=n.split(".");if(t.length!==3)return null;try{const e=Buffer.from(t[1],"base64url").toString("utf-8"),s=JSON.parse(e);return typeof s!="object"||s===null?null:s}catch{return null}}o(A,"decodeJwtPayload");function K(n){if(typeof n=="string"){const t=A(n);return t?{email:t.email,planType:t["https://api.openai.com/auth"]?.chatgpt_plan_type}:{}}if(typeof n=="object"&&n!==null){const t=n;return{email:t.email,planType:t.chatgpt_plan_type}}return{}}o(K,"extractIdTokenFields");function U(n){const t=n??(0,p.join)((0,b.homedir)(),".codex","auth.json");if(!(0,m.existsSync)(t))return{};try{const e=JSON.parse((0,m.readFileSync)(t,"utf-8")),s=e.auth_mode==="chatgpt"||e.auth_mode==="swic"?"subscription":e.auth_mode==="api"?"api":void 0,{email:r,planType:i}=K(e.tokens?.id_token);return{usageType:s,usagePlan:i?.toLowerCase(),userEmail:r}}catch(e){return y.logger.debug(`failed to parse ${t}: ${e}`),{}}}o(U,"resolveCodexUsage");function X(n,t){return n.trim()===`[${t}]`}o(X,"tableHeaderLineExact");function G(n){const t=n.trim();return/^\[\[?[^\]]+\]\]?$/.test(t)}o(G,"isAnyTableHeader");function O(n){const e=n.trim().match(/^\[([^[\]]+)\]$/);return e===null?null:e[1]}o(O,"tableHeaderName");function _(n,t){let e=-1;for(let r=0;r<n.length;r+=1)if(X(n[r],t)){e=r;break}if(e<0)return null;let s=n.length;for(let r=e+1;r<n.length;r+=1)if(G(n[r])){s=r;break}return{startIdx:e,endIdx:s}}o(_,"findTomlSection");function v(n){const t=[...n];for(;t.length>0&&t[t.length-1].trim()==="";)t.pop();return t}o(v,"trimTrailingBlanks");function w(n,t){return n.length===0?t.join(`
+"use strict";var k=Object.defineProperty;var E=Object.getOwnPropertyDescriptor;var L=Object.getOwnPropertyNames;var W=Object.prototype.hasOwnProperty;var o=(n,t)=>k(n,"name",{value:t,configurable:!0});var M=(n,t)=>{for(var e in t)k(n,e,{get:t[e],enumerable:!0})},P=(n,t,e,s)=>{if(t&&typeof t=="object"||typeof t=="function")for(let r of L(t))!W.call(n,r)&&r!==e&&k(n,r,{get:()=>t[r],enumerable:!(s=E(t,r))||s.enumerable});return n};var J=n=>P(k({},"__esModule",{value:!0}),n);var mn={};M(mn,{AGENTS_MD_END_MARKER:()=>x,AGENTS_MD_START_MARKER:()=>I,canonicalizeCodexServerName:()=>v,canonicalizeCodexToolName:()=>C,classifyCodexTool:()=>V,codexAgentTomlPath:()=>rn,codexConfigTomlPath:()=>T,codexHooksJsonPath:()=>cn,decodeJwtPayload:()=>A,ensureFeaturesHooksTrue:()=>Z,ensureMultiAgentV2SpawnMetadataExposed:()=>Q,extractBashBinary:()=>O,extractCodexMcpServer:()=>S,extractCodexToolInput:()=>D,extractTomlTopLevelModel:()=>sn,findTomlSection:()=>_,normalizeCodexToolName:()=>R,parseCodexHookStdin:()=>B,readCodexConfigToml:()=>ln,removeAgentsTable:()=>en,removeFeaturesHooks:()=>q,removeMcpServer:()=>nn,removeMultiAgentV2SpawnMetadata:()=>Y,resolveCodexUsage:()=>U,stripAgentsMdBlock:()=>an,tomlBodyFromRecord:()=>on,upsertAgentsMdBlock:()=>un,upsertAgentsTable:()=>tn,upsertMcpServer:()=>N,userCodexAgentTomlPath:()=>pn,userCodexConfigTomlPath:()=>gn,userCodexHooksJsonPath:()=>fn,writeCodexConfigToml:()=>dn});module.exports=J(mn);var m=require("fs"),b=require("os"),p=require("path"),y=require("../../lib/logger");function B(n){try{return JSON.parse(n)}catch(t){return y.logger.debug(`failed to parse Codex hook stdin: ${t}`),{}}}o(B,"parseCodexHookStdin");const h="mcp__",z={browser_devtools:"browser-devtools",node_devtools:"node-devtools",backend_devtools:"backend-devtools",android_devtools:"android-devtools"},H=["bdt_","ndt_","bedt_","adt_"];function v(n){return z[n]??n}o(v,"canonicalizeCodexServerName");function C(n){if(!H.some(e=>n.startsWith(e)))return n;const t=n.split("_");return t.length>=3&&t[1]==="scenario"?`${t[0]}_scenario-${t.slice(2).join("-")}`:t.length<=3?n:`${t[0]}_${t[1]}_${t.slice(2).join("-")}`}o(C,"canonicalizeCodexToolName");const F=[["bdt_","browser-devtools"],["ndt_","node-devtools"],["bedt_","backend-devtools"],["adt_","android-devtools"]];function S(n){if(!n)return null;if(n.startsWith(h)){const t=n.slice(h.length),e=t.indexOf("__");return e<0?null:v(t.slice(0,e))}for(const[t,e]of F)if(n.startsWith(t))return e;return null}o(S,"extractCodexMcpServer");function R(n){return n==="exec_command"?"Bash":n==="apply_patch"?"Edit":n==="update_plan"?"TodoWrite":n==="read_file"?"Read":n==="web_search"?"WebSearch":n==="web_fetch"?"WebFetch":n}o(R,"normalizeCodexToolName");function V(n){if(!n)return{tool_type:null,tool_name:"",mcp_server:null};if(n.startsWith(h)){const s=n.slice(h.length),r=s.indexOf("__");if(r>=0){const i=s.slice(0,r),u=v(i),a=s.slice(r+2);return{tool_type:"mcp",tool_name:C(a),mcp_server:u}}}const t=S(n);if(t!==null&&!n.startsWith(h))return{tool_type:"mcp",tool_name:C(n),mcp_server:t};const e=R(n);return n==="spawn_agent"||n==="wait_agent"||n==="close_agent"?{tool_type:"sub_agent",tool_name:e,mcp_server:null}:{tool_type:null,tool_name:e,mcp_server:null}}o(V,"classifyCodexTool");function D(n,t){if(!n||t===void 0)return;if(n==="apply_patch"){if(typeof t=="string")return{input_size:t.length};if(typeof t=="object"&&t!==null){const r=t,i=r.command??r.input;if(typeof i=="string")return{input_size:i.length}}return{input_size:void 0}}if(typeof t!="object"||t===null)return;const e=t;if(R(n)==="Bash"){const r=e.cmd??e.command,i=typeof r=="string"?O(r):void 0;return{workdir:e.workdir,binary:i}}if(n==="update_plan"){const r=e.explanation,i=e.plan;return{explanation:typeof r=="string"?r:void 0,plan_step_count:Array.isArray(i)?i.length:void 0}}if(n==="spawn_agent"){const r=e.agent_type,i=e.message,u=e.fork_context;return{agent_type:typeof r=="string"?r:void 0,message_size:typeof i=="string"?i.length:void 0,fork_context:typeof u=="boolean"?u:void 0}}if(n==="wait_agent"){const r=e.targets,i=e.timeout_ms;return{target_count:Array.isArray(r)?r.length:void 0,timeout_ms:typeof i=="number"?i:void 0}}if(n==="close_agent"){const r=e.target;return{target:typeof r=="string"?r:void 0}}if(n==="view_image"){const r=e.path,i=e.detail;return{path:typeof r=="string"?r:void 0,detail:typeof i=="string"?i:void 0}}if(n==="write_stdin"){const r=e.session_id,i=e.chars,u=e.yield_time_ms,a=e.max_output_tokens;return{session_id:typeof r=="number"?r:void 0,chars_size:typeof i=="string"?i.length:void 0,yield_time_ms:typeof u=="number"?u:void 0,max_output_tokens:typeof a=="number"?a:void 0}}if(n.startsWith(h)||S(n)!==null){if("_metadata"in e){const{_metadata:r,...i}=e;return i}return e}}o(D,"extractCodexToolInput");function O(n){const t=n.trim();if(!t)return;const e=t.split(/\s+/);for(const s of e)if(!/^[A-Za-z_][A-Za-z0-9_]*=/.test(s)&&s.length>0)return s.split(/[\\/]/).pop()??s}o(O,"extractBashBinary");function A(n){const t=n.split(".");if(t.length!==3)return null;try{const e=Buffer.from(t[1],"base64url").toString("utf-8"),s=JSON.parse(e);return typeof s!="object"||s===null?null:s}catch{return null}}o(A,"decodeJwtPayload");function K(n){if(typeof n=="string"){const t=A(n);return t?{email:t.email,planType:t["https://api.openai.com/auth"]?.chatgpt_plan_type}:{}}if(typeof n=="object"&&n!==null){const t=n;return{email:t.email,planType:t.chatgpt_plan_type}}return{}}o(K,"extractIdTokenFields");function U(n){const t=n??(0,p.join)((0,b.homedir)(),".codex","auth.json");if(!(0,m.existsSync)(t))return{};try{const e=JSON.parse((0,m.readFileSync)(t,"utf-8")),s=e.auth_mode==="chatgpt"||e.auth_mode==="swic"?"subscription":e.auth_mode==="api"?"api":void 0,{email:r,planType:i}=K(e.tokens?.id_token);return{usageType:s,usagePlan:i?.toLowerCase(),userEmail:r}}catch(e){return y.logger.debug(`failed to parse ${t}: ${e}`),{}}}o(U,"resolveCodexUsage");function X(n,t){return n.trim()===`[${t}]`}o(X,"tableHeaderLineExact");function G(n){const t=n.trim();return/^\[\[?[^\]]+\]\]?$/.test(t)}o(G,"isAnyTableHeader");function j(n){const e=n.trim().match(/^\[([^[\]]+)\]$/);return e===null?null:e[1]}o(j,"tableHeaderName");function _(n,t){let e=-1;for(let r=0;r<n.length;r+=1)if(X(n[r],t)){e=r;break}if(e<0)return null;let s=n.length;for(let r=e+1;r<n.length;r+=1)if(G(n[r])){s=r;break}return{startIdx:e,endIdx:s}}o(_,"findTomlSection");function $(n){const t=[...n];for(;t.length>0&&t[t.length-1].trim()==="";)t.pop();return t}o($,"trimTrailingBlanks");function w(n,t){return n.length===0?t.join(`
 `)+`
 `:n.replace(/\n+$/,"")+`
 
 `+t.join(`
 `)+`
 `}o(w,"appendBlockWithSeparator");function Z(n){const t=n.split(`
-`),e=_(t,"features");if(e===null)return w(n,["[features]","hooks = true"]);const s=t.slice(e.startIdx+1,e.endIdx),r=/^\s*hooks\s*=/;let i=!1;for(let l=0;l<s.length;l+=1)if(r.test(s[l])){s[l]="hooks = true",i=!0;break}i||s.unshift("hooks = true");const u=v(s),d=[...t.slice(0,e.startIdx),t[e.startIdx],...u,...e.endIdx<t.length?[""]:[],...t.slice(e.endIdx)].join(`
+`),e=_(t,"features");if(e===null)return w(n,["[features]","hooks = true"]);const s=t.slice(e.startIdx+1,e.endIdx),r=/^\s*hooks\s*=/;let i=!1;for(let l=0;l<s.length;l+=1)if(r.test(s[l])){s[l]="hooks = true",i=!0;break}i||s.unshift("hooks = true");const u=$(s),d=[...t.slice(0,e.startIdx),t[e.startIdx],...u,...e.endIdx<t.length?[""]:[],...t.slice(e.endIdx)].join(`
 `);return d.endsWith(`
 `)?d:d+`
 `}o(Z,"ensureFeaturesHooksTrue");function q(n){const t=n.split(`
-`),e=_(t,"features");if(e===null)return n;const s=t.slice(e.startIdx+1,e.endIdx),r=/^\s*hooks\s*=\s*true\s*$/,i=s.filter(l=>!r.test(l));if(i.length===s.length)return n;const u=i.some(l=>l.trim().length>0);let a;if(u){const l=v(i);a=[...t.slice(0,e.startIdx),t[e.startIdx],...l,...e.endIdx<t.length?[""]:[],...t.slice(e.endIdx)]}else a=[...t.slice(0,e.startIdx),...t.slice(e.endIdx)];const d=a.join(`
+`),e=_(t,"features");if(e===null)return n;const s=t.slice(e.startIdx+1,e.endIdx),r=/^\s*hooks\s*=\s*true\s*$/,i=s.filter(l=>!r.test(l));if(i.length===s.length)return n;const u=i.some(l=>l.trim().length>0);let a;if(u){const l=$(i);a=[...t.slice(0,e.startIdx),t[e.startIdx],...l,...e.endIdx<t.length?[""]:[],...t.slice(e.endIdx)]}else a=[...t.slice(0,e.startIdx),...t.slice(e.endIdx)];const d=a.join(`
 `).replace(/\n{3,}/g,`
 
 `);return d.endsWith(`
 `)?d:d+`
 `}o(q,"removeFeaturesHooks");function Q(n){const t=n.split(`
-`),e=_(t,"features.multi_agent_v2");if(e===null)return w(n,["[features.multi_agent_v2]","hide_spawn_agent_metadata = false"]);const s=t.slice(e.startIdx+1,e.endIdx),r=/^\s*hide_spawn_agent_metadata\s*=/;let i=!1;for(let l=0;l<s.length;l+=1)if(r.test(s[l])){s[l]="hide_spawn_agent_metadata = false",i=!0;break}i||s.unshift("hide_spawn_agent_metadata = false");const u=v(s),d=[...t.slice(0,e.startIdx),t[e.startIdx],...u,...e.endIdx<t.length?[""]:[],...t.slice(e.endIdx)].join(`
+`),e=_(t,"features.multi_agent_v2");if(e===null)return w(n,["[features.multi_agent_v2]","hide_spawn_agent_metadata = false"]);const s=t.slice(e.startIdx+1,e.endIdx),r=/^\s*hide_spawn_agent_metadata\s*=/;let i=!1;for(let l=0;l<s.length;l+=1)if(r.test(s[l])){s[l]="hide_spawn_agent_metadata = false",i=!0;break}i||s.unshift("hide_spawn_agent_metadata = false");const u=$(s),d=[...t.slice(0,e.startIdx),t[e.startIdx],...u,...e.endIdx<t.length?[""]:[],...t.slice(e.endIdx)].join(`
 `);return d.endsWith(`
 `)?d:d+`
 `}o(Q,"ensureMultiAgentV2SpawnMetadataExposed");function Y(n){const t=n.split(`
@@ -29,7 +29,7 @@
 `);return c.endsWith(`
 `)?c:c+`
 `}o(N,"upsertMcpServer");function nn(n,t){const e=`mcp_servers.${t}`,s=`${e}.`,r=n.split(`
-`),i=[];let u=!1,a=!1;for(const c of r){const g=O(c);if(g!==null&&(u=g===e||g.startsWith(s),u)){a=!0;continue}u||i.push(c)}if(!a)return n;const d=[];let l=!1;for(const c of i){const g=c.trim().length===0;g&&l||(d.push(c),l=g)}const f=d.join(`
+`),i=[];let u=!1,a=!1;for(const c of r){const g=j(c);if(g!==null&&(u=g===e||g.startsWith(s),u)){a=!0;continue}u||i.push(c)}if(!a)return n;const d=[];let l=!1;for(const c of i){const g=c.trim().length===0;g&&l||(d.push(c),l=g)}const f=d.join(`
 `);return f.endsWith(`
 `)||f.length===0?f:f+`
 `}o(nn,"removeMcpServer");function tn(n,t,e){const s=`agents.${t}`,r=n.split(`
@@ -37,7 +37,7 @@
 `);return c.endsWith(`
 `)?c:c+`
 `}o(tn,"upsertAgentsTable");function en(n,t){const e=`agents.${t}`,s=`${e}.`,r=n.split(`
-`),i=[];let u=!1,a=!1;for(const c of r){const g=O(c);if(g!==null&&(u=g===e||g.startsWith(s),u)){a=!0;continue}u||i.push(c)}if(!a)return n;const d=[];let l=!1;for(const c of i){const g=c.trim().length===0;g&&l||(d.push(c),l=g)}const f=d.join(`
+`),i=[];let u=!1,a=!1;for(const c of r){const g=j(c);if(g!==null&&(u=g===e||g.startsWith(s),u)){a=!0;continue}u||i.push(c)}if(!a)return n;const d=[];let l=!1;for(const c of i){const g=c.trim().length===0;g&&l||(d.push(c),l=g)}const f=d.join(`
 `);return f.endsWith(`
 `)||f.length===0?f:f+`
 `}o(en,"removeAgentsTable");function rn(n,t){return(0,p.join)(n,".codex","agents",`${t}.toml`)}o(rn,"codexAgentTomlPath");function sn(n){for(const t of n.split(`

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

@@ -0,0 +1,100 @@
+---
+name: ironbee-manage-scenario
+description: "Add, update, or delete a reusable IronBee verification scenario. Authors the script in the devtools format and saves it to the right platform's store (or finds and updates/deletes an existing one) using the scenario-* MCP tools."
+disable-model-invocation: true
+---
+
+# IronBee — Manage scenario
+
+Add / update / delete a reusable verification **scenario** using the devtools `scenario-*` MCP
+tools directly. A scenario is a named, parameterizable script (`callTool('<tool>', {...})` JS) that
+drives ONE platform's tools. 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/cursor/commands/ironbee-search-scenario/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: ironbee-search-scenario
+description: "Find reusable IronBee verification scenarios by name, description, or metadata across every enabled platform's store, using the scenario-search / scenario-list MCP tools."
+disable-model-invocation: true
+---
+
+# IronBee — Search scenarios
+
+Find saved verification **scenarios** using the devtools scenario tools directly. 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-->