howtofixcli 0.7.24 → 0.7.25

package/dist/main.js

@@ -1,99 +1,574 @@
 #!/usr/bin/env node
-import{b as I,d as W,e as B}from"./chunk-3LZR7OEU.js";import{b as U}from"./chunk-YW7NORH3.js";import{a as F,b as R}from"./chunk-AGGIYXN7.js";import{D as M,K as N}from"./chunk-V656XVXV.js";import"./chunk-UTYFLLSM.js";import{a as n,b as y}from"./chunk-N3J2J7EQ.js";import"./chunk-WOT6VMZA.js";var L={rpc:!0,acp:!0},D={off:!0,minimal:!0,low:!0,medium:!0,high:!0,xhigh:!0,max:!0},G={suggest:!0,"auto-edit":!0,"full-auto":!0},H={text:!0,json:!0,"stream-json":!0};function fe(c){let e=Number(c);if(!Number.isFinite(e)||e<=0)throw new Error(`--max-budget-usd needs a positive number of dollars, got '${c}'`);return e}function $(c,e,p){let d=c[e];if(d?.includes("="))return d.slice(d.indexOf("=")+1);let l=c[e+1];if(!l||l.startsWith("-"))throw new Error(`${p} needs a value`);return c.splice(e+1,1),l}function X(c){let e={print:!1,continueSession:!1,noSession:!1,help:!1,version:!1,update:!1,checkUpdate:!1,outputFormat:"text",dangerouslySkipPermissions:!1,sandbox:!1,prompt:""},p=[],d=[...c];for(let l=0;l<d.length;l++){let s=d[l]??"";if(s==="--"){p.push(...d.slice(l+1));break}if(s==="-h"||s==="--help")e.help=!0;else if(s==="-v"||s==="--version")e.version=!0;else if(s==="-p"||s==="--print")e.print=!0;else if(s==="-c"||s==="--continue")e.continueSession=!0;else if(s==="--no-session")e.noSession=!0;else if(s==="--sandbox")e.sandbox=!0;else if(s==="--update")e.update=!0;else if(s==="--check-update")e.checkUpdate=!0;else if(s==="-r"||s==="--resume")e.continueSession=!0;else if(s==="--session"||s.startsWith("--session="))e.sessionPath=$(d,l,"--session");else if(s==="-m"||s==="--model"||s.startsWith("--model="))e.model=$(d,l,"--model");else if(s==="--thinking"||s.startsWith("--thinking="))e.thinking=$(d,l,"--thinking");else if(s==="--approval"||s.startsWith("--approval="))e.approval=$(d,l,"--approval");else if(s==="--output-format"||s.startsWith("--output-format="))e.outputFormat=$(d,l,"--output-format");else if(s==="--max-budget-usd"||s.startsWith("--max-budget-usd="))e.maxBudgetUsd=fe($(d,l,"--max-budget-usd"));else if(s==="--mode"||s.startsWith("--mode=")){let u=$(d,l,"--mode");if(!L[u])throw new Error(`--mode must be one of: ${Object.keys(L).join(", ")}`);e.mode=u}else if(s==="--acp")e.mode="acp";else if(s==="--dangerously-skip-permissions")e.dangerouslySkipPermissions=!0;else{if(s.startsWith("-"))throw new Error(`unknown option ${s}`);p.push(s)}}if(e.thinking&&!D[e.thinking])throw new Error(`thinking must be one of: ${Object.keys(D).join(", ")}`);if(e.approval&&!G[e.approval])throw new Error(`approval must be one of: ${Object.keys(G).join(", ")}`);if(!H[e.outputFormat])throw new Error(`output-format must be one of: ${Object.keys(H).join(", ")}`);if(e.outputFormat!=="text"&&!e.print)throw new Error(`--output-format ${e.outputFormat} is a machine contract; it needs --print`);if(e.dangerouslySkipPermissions&&!e.print)throw new Error("--dangerously-skip-permissions is for unattended runs; it needs --print. interactively, pick an approval mode instead (/approval, or --approval)");if(e.prompt=p.join(" ").trim(),e.update&&e.checkUpdate)throw new Error("--update installs; --check-update only looks. pick one");if((e.update||e.checkUpdate)&&(e.print||e.continueSession||e.sessionPath||e.prompt))throw new Error("--update and --check-update act on the installation, not a session; they take no prompt");if(e.continueSession&&e.noSession)throw new Error("--continue and --no-session cannot be combined");if(e.sessionPath&&e.noSession)throw new Error("--session and --no-session cannot be combined");if(e.sessionPath&&e.continueSession)throw new Error("--session and --continue cannot be combined");if(e.print&&(e.continueSession||e.sessionPath))throw new Error("--print runs one prompt in a throwaway session; it cannot be combined with --continue or --session");if(e.mode&&(e.print||e.prompt))throw new Error(`--mode ${e.mode} is a protocol server: prompts arrive over the protocol, not the command line`);if(e.mode&&(e.continueSession||e.sessionPath))throw new Error(`--mode ${e.mode} opens its own sessions; it cannot be combined with --continue or --session`);if(e.sessionPath&&!e.sessionPath.endsWith(".jsonl"))throw new Error(`--session expects a session file, got '${e.sessionPath}'`);return e}function C(){return`${n} ${y}
-coding agent. layout is a workbench, not a chat log.
-
-usage:
-  howtofix [options] [prompt]
-  howtofix -p "explain this repo"
-  howtofix acp                       serve the Agent Client Protocol on stdio
-  howtofix --mode rpc                serve JSON-line commands on stdio
-  howtofix preset new|check|pack     author a preset
-  howtofix doctor|models|sessions    inspect the installation
-  howtofix sessions --search <text> find a session by what was said in it
-  howtofix sessions --export <n>    print session n from the list as markdown
-
-options:
-  -p, --print          run one prompt and print the answer
-  -c, --continue       resume the latest session in this folder
-  -r, --resume         alias for --continue
-      --session <file> run inside a specific saved session file
-      --no-session     do not write a session file
-  -m, --model <id>     provider/model, or a fuzzy model id
-      --thinking <lv>  off | minimal | low | medium | high | xhigh | max
-      --approval <m>   suggest | auto-edit | full-auto
-      --output-format <f>  text | json | stream-json
-                       text for a person; json writes the final result only;
-                       stream-json writes every event as it happens
-      --max-budget-usd <n> stop the run once it has spent n dollars
-      --mode <m>       rpc | acp: serve a protocol on stdin/stdout, no terminal
-      --acp            same as --mode acp
-      --sandbox        run the whole session inside a filesystem sandbox:
-                       the project is writable, the rest is read-only.
-                       needs bubblewrap (Linux) or sandbox-exec (macOS)
-      --dangerously-skip-permissions
-                       run everything, including commands otherwise refused.
-                       unattended runs only; pairs with --print
-      --update         install the newest release and exit
-      --check-update   say whether a newer release exists
-  -h, --help
-  -v, --version
-
-keys:
-  enter                send
-  shift+enter          new line
-  ctrl+c               stop the run, or quit when idle
-  ctrl+d               quit
-  ctrl+l               jump to the latest line
-  ctrl+o               clear the screen (history is kept)
-  ctrl+t               raise the thinking level (wraps to off)
-  ctrl+shift+t         lower the thinking level
-  esc                  clear the draft
-  ctrl+v               paste from the clipboard
-  pgup / pgdn          scroll the transcript a page
-  home / end           jump to the top / back to the latest line
-  wheel                scroll the transcript
-
-commands:
-  /init /model /providers /thinking /approval /login /connect /logout /new
-  /resume /compact /name /stats /rtk /diff /commit /undo /rewind /review /tools /export
-  /copy /agents /goal /plan /workflow /session /help /quit /exit
-  /dcp /context /decompress /sweep
-  /update /usage /sync
-  /skills /preset /settings /trust /proxy /roblox
-/roblox login|logout|status|tunnel manages the Roblox connection: sign in with Roblox
-(no API key), see what is connected, and link this machine to the hosted workspace.
-
-/stats shows session tokens, cost, and the prompt-cache hit rate; a high read
-total alone hides re-billed context, so the rate is what tells you the truth.
-/rtk compresses long tool output (logs, diffs, greps) before the model reads it.
-Off by default: /rtk on to save tokens when skimming, /rtk off to keep every line.
-Nothing is invented by it \u2014 it drops redundant lines and says how many it dropped,
-and never touches a failed command or one already truncated.
-
-/preset lists skills bundled with this build and skills from the registry, by
-category; picking one downloads it into the project and loads it as a skill.
-An integration preset installs disabled: its skills and MCP server stay dormant
-until /preset enable <name>, and /preset disable <name> takes the server back
-out of the live session. /roblox reports that state for RoToolbox in one line.
-/skills lists what is loaded now.
-
-/proxy <url> routes requests through a proxy, /proxy off stops, /proxy env uses
-HTTPS_PROXY / HTTP_PROXY / ALL_PROXY; /proxy alone shows what is set.
-
-/agents <id> <message> messages a parked agent; /agents <id> shows one.
-
-a line starting with ! runs in the project shell.
-
-an npm install checks for a newer release at startup and can install it itself;
-/update does it on demand. config and sessions live in ~/.howtofix/agent.
-/connect signs in to howtofix.id in your browser, and falls back to a pasted
-token; /login takes another provider's key.
-`}function ge(c,e=!1){let{message:p}=F(c);if(!e)return p;let d=c instanceof Error?c.stack:void 0;return d&&d.includes(`
-`)?`${p}
-${d}`:p}function V(c,e){let p=e?.debug??process.env.HOWTOFIX_DEBUG==="1",d=e?.exit??(s=>process.exit(s)),l=s=>{console.error(`${c}: ${ge(s,p)}`),d(1)};process.on("uncaughtException",l),process.on("unhandledRejection",l)}function we(){try{return{cwd:process.cwd()}}catch{return{error:"the current directory no longer exists (it was deleted while the shell stayed in it). cd to a directory that exists, or pass one on the command line."}}}function be(){process.stdout.on("error",c=>{throw c.code==="EPIPE"&&process.exit(0),c})}async function ke(){be(),N();let c=performance.now(),e=we();if("error"in e){console.error(`${n}: ${e.error}`),process.exitCode=1;return}let p=e.cwd,d=process.env.HXF_FAKE_NODE??process.versions.node,[l,s]=d.split(".").map(o=>Number.parseInt(o,10));if(!Number.isFinite(l)||l<22||l===22&&Number.isFinite(s)&&s<19){console.error(`${n}: Node ${d} is too old. Node 22.19 or newer is required (run "node --version" to check yours), because undici needs zstd, which Node added in 22.19. Upgrade Node and run this again.`),process.exitCode=1;let o=process.argv.slice(2);if(o.some(a=>a==="-h"||a==="--help")){console.log(C());return}if(o.some(a=>a==="-v"||a==="--version")){console.log(`${n} ${y}`);return}return}let u=process.argv.slice(2);if(u[0]==="doctor"||u[0]==="models"||u[0]==="sessions"){let o=u[0];try{let a=await import("./chunk-TKROS3BE.js");o==="doctor"?process.exitCode=await a.runDoctor():o==="models"?process.exitCode=a.runModels():process.exitCode=a.runSessions(u.slice(1))}catch(a){R(n,o,a),process.exitCode=1}return}let q=u[0]==="acp"?["--acp",...u.slice(1)]:u,_;try{_=X(q)}catch(o){let a=o instanceof Error?o.message:String(o);console.error(`${n}: ${a}
-${C()}`),process.exitCode=2;return}if(_.print&&!_.prompt){console.error(`${n}: --print needs a prompt`),process.exitCode=2;return}let{repairGatewayModels:J,ensureGatewaySettings:K,repairModelFacts:Y,syncGatewayModelsOnStart:z,checkAccount:Q,fetchGatewayPrices:Z}=await import("./chunk-75P2SCOT.js"),{readCliCredential:ee,renewCliCredentialIfNeeded:se}=await import("./chunk-XW6LMQGX.js"),{AGENT_DIR:b}=await import("./chunk-GXB7RZHH.js"),j=J(b);j>0&&console.error(`${n}: repaired ${j} howtofix model(s) that the gateway would have rejected`);let P,O;try{let o=ee(b);if(o){let x=(await se(b,o)).credential.accessToken,[m,h]=await Promise.all([Z(x),Q(x)]);m.size>0&&(P=m),h.ok&&(O=h.models)}}catch{}let E=await Y(b,P?{prices:P}:void 0);if(E.changed>0?console.error(`${n}: filled in the context window, reasoning flag and price for ${E.changed} model(s)`):E.message&&console.error(`${n}: model catalogue unavailable (${E.message}); context windows stay at their conservative defaults`),K(b)&&console.error(`${n}: set httpIdleTimeoutMs in settings.json so a stalled provider recovers instead of hanging`),O)try{let o=await z(b,O,P);o.added>0&&console.error(`${n}: added ${o.added} model(s) this account can now reach`)}catch{}let t=_;if(t.help){console.log(C());return}if(t.version){console.log(`${n} ${y}`);let{cliSigningKeyMatchesPanel:o,cliSigningKeyFingerprint:a}=await import("./chunk-5AWTL34S.js");o()||(console.error(`${n}: this build's CLI signing key (${a()}) does not match the key the panel verifies against, so sign-in will be refused.`),process.exitCode=1);return}if(t.sandbox&&!process.env.HOWTOFIX_SANDBOXED){let{detectSandbox:o,enterSandbox:a,describeSandbox:x}=await import("./chunk-N345KWWK.js"),m=o();if(!m){console.error(`${n}: --sandbox needs a working bubblewrap (Linux) or sandbox-exec (macOS). Neither could be used here \u2014 on Linux this usually means unprivileged user namespaces are disabled.`),process.exitCode=1;return}console.error(x(m)),process.exitCode=a(m,{cwd:p,agentDir:M,argv:[process.execPath,...process.argv.slice(1)]});return}let{installProxy:te}=await import("./chunk-WKUJ7CFO.js");if(te(M),t.update||t.checkUpdate){let{PACKAGE_NAME:o,checkForUpdate:a,installUpdate:x,isInstalledCopy:m}=await import("./chunk-7CHDNTH6.js"),h=await a(y);if(!h.latest){console.error(`${n}: ${h.message}`),process.exitCode=t.update?1:0;return}if(console.log(h.message),t.checkUpdate||!h.available)return;if(!m()){console.error(`${n}: this copy was not installed by npm, so npm cannot replace it. install it with: npm install -g ${o}`),process.exitCode=1;return}let v=await x({version:h.latest});console.log(v.message),v.ok||(process.exitCode=1);return}let A=process.argv.slice(2);if(A[0]==="preset"){let{runPresetCommand:o}=await import("./chunk-FPXVDP32.js");process.exitCode=o(A.slice(1));return}let{expandFileReferences:oe}=await import("./chunk-TSEKPGK4.js"),{isApprovalMode:ne,setApprovalMode:re,setDangerousBypass:ie,isDangerousBypass:ae}=await import("./chunk-56SEAGAQ.js"),{openSession:de}=await import("./chunk-7PHRNXLN.js");re(t.approval&&ne(t.approval)?t.approval:"full-auto");let{readWorkbenchSettings:ce}=await import("./chunk-V3R4FYTJ.js");if((t.dangerouslySkipPermissions||ce(b).skipPermissions)&&ie(!0),ae()&&console.error(`${n}: permission checks are OFF \u2014 critical commands (filesystem wipes, fork bombs, host shutdown) and the repeated-call guard are NOT enforced for this run. Turn it off with /settings, or by removing skipPermissions from settings.json.`),t.mode){let{serveProtocol:o}=await import("./chunk-CMTKCUL5.js");await o(t.mode,{cwd:p,model:t.model,thinking:t.thinking});return}let T=o=>de({cwd:p,model:t.model,thinking:t.thinking,continueSession:o.continueSession??!1,noSession:o.noSession??!1,sessionPath:o.sessionPath,interactive:!t.print}),r=await T({continueSession:t.continueSession,sessionPath:t.sessionPath,noSession:t.noSession||t.print});if(t.print&&r.note&&console.error(r.note),t.maxBudgetUsd!==void 0&&!r.priced){console.error(`${n}: ${B(r.modelLabel,b)}`),await r.dispose(),process.exitCode=2;return}if(t.print){let o=t.prompt.trimStart();if(o.startsWith("/")){let f=o.slice(1).split(/\s+/)[0]??"",{skillInvocation:S}=await import("./chunk-ILDDDLRC.js"),g=r.session.resourceLoader.getSkills().skills.map(i=>i.name);if(!(S(o,g)!==void 0)){let{slashCommands:i}=await import("./chunk-UP7ENLEL.js");if(i(r.session).some(w=>w.name===f)){console.error(`${n}: /${f} runs in the TUI only \u2014 --print sends prompts straight to the model. Run \`howtofix\` without --print for interactive commands.`),await r.dispose(),process.exitCode=2;return}}}let a=t.outputFormat==="stream-json",x=t.outputFormat==="json",m=a||x;if(a){let f={type:"system",subtype:"init",cwd:p,session_id:r.session.sessionId,model:r.modelLabel,output_format:t.outputFormat,max_budget_usd:t.maxBudgetUsd??null,dangerously_skip_permissions:t.dangerouslySkipPermissions,cli_version:y};process.stdout.write(`${JSON.stringify(f)}
-`)}let h,v,he=()=>{if(t.maxBudgetUsd===void 0||v!==void 0)return;let f=r.session.getSessionStats().cost;f>t.maxBudgetUsd&&(v={spent:f},r.session.abort())};try{let f;h=r.session.subscribe(i=>{if(a){let w=U(i);w!==void 0&&process.stdout.write(w)}if(i.type==="turn_end"&&i.message?.role==="assistant"){let w=i.message;w.stopReason==="error"||w.stopReason==="aborted"||w.errorMessage?f={stopReason:w.stopReason??"error",errorMessage:w.errorMessage}:f=void 0}he()}),await r.session.prompt(oe(t.prompt,p));let S=r.session.getLastAssistantText()??"";if(v){if(console.error(`${n}: ${W(v.spent,t.maxBudgetUsd)}`),m){let i=r.session.getSessionStats();process.stdout.write(`${JSON.stringify({type:"result",subtype:"error_max_budget_usd",is_error:!0,result:S,session_id:r.session.sessionId,duration_ms:Math.round(performance.now()-c),num_turns:i.assistantMessages,total_cost_usd:i.cost,usage:{input_tokens:i.tokens.input,output_tokens:i.tokens.output,cache_read_input_tokens:i.tokens.cacheRead,cache_creation_input_tokens:i.tokens.cacheWrite}})}
-`)}process.exitCode=1;return}let g=r.session.state.messages.at(-1),k=f??(g?.role==="assistant"&&(g.stopReason==="error"||g.stopReason==="aborted"||g.errorMessage)?{stopReason:g.stopReason??"error",errorMessage:g.errorMessage}:void 0);if(m){let i=r.session.getSessionStats();process.stdout.write(`${JSON.stringify({type:"result",subtype:k?k.stopReason==="aborted"?"error_aborted":"error_during_execution":"success",is_error:k!==void 0,result:S,session_id:r.session.sessionId,duration_ms:Math.round(performance.now()-c),num_turns:i.assistantMessages,total_cost_usd:i.cost,usage:{input_tokens:i.tokens.input,output_tokens:i.tokens.output,cache_read_input_tokens:i.tokens.cacheRead,cache_creation_input_tokens:i.tokens.cacheWrite},stop_reason:k?.stopReason??(g?.role==="assistant"?g.stopReason:void 0)})}
-`)}else process.stdout.write(S.endsWith(`
-`)?S:`${S}
-`);if(k&&(process.exitCode=1,k.errorMessage)){console.error(`${n}: ${k.errorMessage}`);let i=I(k.errorMessage);i!==void 0&&console.error(`${n}: ${i}`)}}finally{h?.(),await r.dispose()}return}if(!process.stdin.isTTY||!process.stdout.isTTY){console.error(`${n}: interactive mode needs a terminal. use --print for pipes.`),await r.dispose(),process.exitCode=2;return}let{runWorkbench:le}=await import("./chunk-UP7ENLEL.js"),{autoUpdateEnabled:pe,isInstalledCopy:ue}=await import("./chunk-7CHDNTH6.js"),me=ue()&&pe(`${b}/settings.json`);await le({cwd:p,modelLabel:r.modelLabel,session:r.session,setCompressToolOutput:r.setCompressToolOutput,initialPrompt:t.prompt||void 0,note:r.note,maxBudgetUsd:t.maxBudgetUsd,update:me?{current:y,install:!0}:void 0,reopen:T})}V(n);ke().catch(c=>{R(n,void 0,c),process.exitCode=1});
+import { helpText, parseArgs } from "./args.js";
+import { APP_TITLE, APP_VERSION } from "./brand.js";
+import { installCrashHandlers } from "./fatal.js";
+import { reportError } from "./errors.js";
+import { AGENT_DIR, pinAgentDir } from "./paths.js";
+import { jsonLine } from "./json-events.js";
+import { diagnoseGatewayFailure } from "./gateway-errors.js";
+import { spendCapMessage, unpricedBudgetMessage } from "./spend-cap.js";
+/**
+ * The working directory to run in, or a reason the process cannot start.
+ *
+ * `process.cwd()` throws `ENOENT` when the directory it was started in has been
+ * deleted — a real case (the scratch dir is cleaned up mid-session) and an
+ * uncaught crash with a stack trace, since the throw happens while building the
+ * session options. Report it as a sentence instead.
+ */
+function workingDirectory() {
+    try {
+        return { cwd: process.cwd() };
+    }
+    catch {
+        return {
+            error: "the current directory no longer exists (it was deleted while the shell stayed in it). " +
+                "cd to a directory that exists, or pass one on the command line.",
+        };
+    }
+}
+/**
+ * A closed stdout (`howtofix --version | head -1`) makes every later write throw
+ * `EPIPE`, which the top-level handler used to report as a crash with a stack
+ * trace. A pipe that went away is not an error the user needs to see.
+ */
+function exitQuietlyOnEpipe() {
+    process.stdout.on("error", (error) => {
+        if (error.code === "EPIPE")
+            process.exit(0);
+        throw error;
+    });
+}
+async function main() {
+    exitQuietlyOnEpipe();
+    pinAgentDir();
+    const startedAt = performance.now();
+    const here = workingDirectory();
+    if ("error" in here) {
+        console.error(`${APP_TITLE}: ${here.error}`);
+        process.exitCode = 1;
+        return;
+    }
+    const cwd = here.cwd;
+    // A Node too old to be supported fails deep inside a dependency instead of here.
+    // `undici` 8 reaches `zlib.createZstdDecompress` at module load, and that function
+    // only exists from Node 22.19 — so on Node 20 the user gets
+    // `TypeError: Cannot read properties of undefined (reading 'bind')` with a stack
+    // trace pointing at `undici/lib/interceptor/decompress.js`, which explains nothing
+    // and names no fix. `engines` in `package.json` is not enough on its own: npm's
+    // `engine-strict` is false by default, so the install succeeds with a warning the
+    // user never sees.
+    //
+    // `--help` and `--version` are deliberately still served. They exit before `undici`
+    // is ever loaded, so they cannot hit the bug, and the user who most needs to read the
+    // help is the one on the runtime the CLI cannot run — refusing to answer leaves them
+    // with a command that looks broken and no way to learn why. Everything else is
+    // refused, because a session that cannot start the agent is not a usable CLI and
+    // failing here is what turns a stack trace inside a dependency into a sentence.
+    //
+    // Gated behind an env var so the check itself is what breaks under test, not the
+    // runtime: `HXF_FAKE_NODE` lets a check drive this branch on a modern Node. The
+    // same value feeds the message, so a test sees the version it asked about rather
+    // than the one it happens to be running on.
+    //
+    // The exit code says whether the ENVIRONMENT is supported, not whether output was
+    // produced: an old Node exits non-zero even for `--help`, so a script reading the
+    // code is not told the runtime is fine.
+    const reportedVersion = process.env.HXF_FAKE_NODE ?? process.versions.node;
+    const [major, minor] = reportedVersion.split(".").map((part) => Number.parseInt(part, 10));
+    if (!Number.isFinite(major) || major < 22 || (major === 22 && Number.isFinite(minor) && minor < 19)) {
+        // Same sentence on both streams, and stderr carries it in the informational case
+        // too: `--version` is often parsed by a script, and a warning on stdout would
+        // corrupt the value it is reading.
+        console.error(`${APP_TITLE}: Node ${reportedVersion} is too old. Node 22.19 or newer is required ` +
+            `(run "node --version" to check yours), because undici needs zstd, which Node added in 22.19. ` +
+            `Upgrade Node and run this again.`);
+        process.exitCode = 1;
+        const argv = process.argv.slice(2);
+        // The two flags that work on any runtime, served from here so the account repair
+        // below — which makes an HTTP call, and therefore loads undici — is never reached
+        // on a runtime that cannot load it.
+        if (argv.some((token) => token === "-h" || token === "--help")) {
+            console.log(helpText());
+            return;
+        }
+        if (argv.some((token) => token === "-v" || token === "--version")) {
+            console.log(`${APP_TITLE} ${APP_VERSION}`);
+            return;
+        }
+        return;
+    }
+    // Questions about the installation, answered without a session, a model, or
+    // any of the repairs below. They run first on purpose: `howtofix models` used
+    // to rewrite settings.json and print two notices about it before listing a
+    // single model, which reads like the command did something it did not.
+    const subArgv = process.argv.slice(2);
+    if (subArgv[0] === "doctor" || subArgv[0] === "models" || subArgv[0] === "sessions") {
+        const context = subArgv[0];
+        try {
+            const commands = await import("./commands.js");
+            if (context === "doctor")
+                process.exitCode = await commands.runDoctor();
+            else if (context === "models")
+                process.exitCode = commands.runModels();
+            else
+                process.exitCode = commands.runSessions(subArgv.slice(1));
+        }
+        catch (error) {
+            reportError(APP_TITLE, context, error);
+            process.exitCode = 1;
+        }
+        return;
+    }
+    // Arguments are read and checked before the start-up repairs. A typo must not
+    // rewrite settings.json, print a hint about a file the user never mentioned,
+    // or reach the network: the answer to "you forgot the prompt" is one line.
+    // `howtofix acp` is the subcommand spelling of `--acp`, dispatched here rather
+    // than in `parseArgs` so the word is not mistaken for the start of a prompt.
+    const argvForParse = subArgv[0] === "acp" ? ["--acp", ...subArgv.slice(1)] : subArgv;
+    let earlyArgs;
+    try {
+        earlyArgs = parseArgs(argvForParse);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        console.error(`${APP_TITLE}: ${message}\n${helpText()}`);
+        process.exitCode = 2;
+        return;
+    }
+    if (earlyArgs.print && !earlyArgs.prompt) {
+        console.error(`${APP_TITLE}: --print needs a prompt`);
+        process.exitCode = 2;
+        return;
+    }
+    // Repair a howtofix gateway entry that predates `compat.supportsDeveloperRole`.
+    // The gateway refuses the `developer` role that the SDK selects for every
+    // reasoning model, so such an entry fails every prompt silently — the spinner
+    // turns and nothing is ever reported. `/connect` writes the flag, but only for
+    // models it adds, so an account connected earlier stays broken until something
+    // repairs the file. The repair is silent: it runs on every start and only says
+    // anything when it actually changed something. Imported lazily to keep
+    // `--version` and `--help` free of the model stack.
+    const { repairGatewayModels, ensureGatewaySettings, repairModelFacts, syncGatewayModelsOnStart, checkAccount, fetchGatewayPrices } = await import("./howtofix-account.js");
+    const { readCliCredential, renewCliCredentialIfNeeded } = await import("./cli-credentials.js");
+    const { AGENT_DIR: stateDir } = await import("./paths.js");
+    const repaired = repairGatewayModels(stateDir);
+    if (repaired > 0) {
+        console.error(`${APP_TITLE}: repaired ${repaired} howtofix model(s) that the gateway would have rejected`);
+    }
+    // The gateway's own price list, read before the repair below: the repair writes
+    // the numbers the picker shows, and a picker that calls a $2/M model free is
+    // worse than one that shows no price at all. One request, once per start, and
+    // only when there is a credential to make it with. The account's model list
+    // rides along on the same token — the re-sync further down needs it, and the
+    // two calls are independent.
+    let gatewayPrices;
+    let accountModels;
+    try {
+        const stored = readCliCredential(stateDir);
+        if (stored) {
+            const renewed = await renewCliCredentialIfNeeded(stateDir, stored);
+            const token = renewed.credential.accessToken;
+            const [prices, account] = await Promise.all([fetchGatewayPrices(token), checkAccount(token)]);
+            if (prices.size > 0)
+                gatewayPrices = prices;
+            if (account.ok)
+                accountModels = account.models;
+        }
+    }
+    catch {
+        // No price list is a picker without prices, not a failed start.
+    }
+    // Repair the numbers a synced model never got: a real context window and the
+    // reasoning flag that enables thinking. Both used to be guesses — 128k for
+    // every model, and no capability at all — so a model with a 1M window read as
+    // almost full and a reasoning model showed no thinking levels. The catalogue is
+    // cached next to the agent state, so this is a file read on a normal start and
+    // a fetch only when the cache is missing or stale.
+    const facts = await repairModelFacts(stateDir, gatewayPrices ? { prices: gatewayPrices } : undefined);
+    if (facts.changed > 0) {
+        console.error(`${APP_TITLE}: filled in the context window, reasoning flag and price for ${facts.changed} model(s)`);
+    }
+    else if (facts.message) {
+        // A catalogue that could not be read is not a failure — the models keep the
+        // conservative defaults — but it is worth one line, because otherwise the
+        // wrong numbers look like the model's own.
+        console.error(`${APP_TITLE}: model catalogue unavailable (${facts.message}); context windows stay at their conservative defaults`);
+    }
+    // The SDK's HTTP idle timeout defaults to 5 minutes, so a provider that goes
+    // quiet mid-request leaves a spinner and nothing else for that long. 90s lets
+    // the SDK's own retry recover while the user is still watching. Written only
+    // when the key is missing, so a value the user set is kept.
+    if (ensureGatewaySettings(stateDir)) {
+        console.error(`${APP_TITLE}: set httpIdleTimeoutMs in settings.json so a stalled provider recovers instead of hanging`);
+    }
+    // The account's model list follows its tier, and `models.json` is a snapshot:
+    // after a tier change the file still offered what the account could reach on
+    // the day it was written, and the only refresh was a manual `/sync`. Pull the
+    // list once per start when a sign-in exists and add whatever is new — the
+    // gateway filters by the account's own group, so a free account can never
+    // collect a VIP model this way. Silent unless something was added, and never
+    // fatal: an unreachable gateway must not stop the CLI from starting.
+    if (accountModels) {
+        try {
+            const synced = await syncGatewayModelsOnStart(stateDir, accountModels, gatewayPrices);
+            if (synced.added > 0) {
+                console.error(`${APP_TITLE}: added ${synced.added} model(s) this account can now reach`);
+            }
+        }
+        catch {
+            // A start-time re-sync that fails costs the previous list, which still
+            // works; `/sync` remains the manual way to try again.
+        }
+    }
+    const args = earlyArgs;
+    // These two exit before a session exists, so they must not load the SDK.
+    if (args.help) {
+        console.log(helpText());
+        return;
+    }
+    if (args.version) {
+        console.log(`${APP_TITLE} ${APP_VERSION}`);
+        // A build whose signing key does not match the panel's would fail every
+        // sign-in with a 401 that reads like a server fault. Say it here, where it
+        // costs nothing, rather than leaving it to be discovered in the login flow.
+        const { cliSigningKeyMatchesPanel, cliSigningKeyFingerprint } = await import("./cli-auth.js");
+        if (!cliSigningKeyMatchesPanel()) {
+            console.error(`${APP_TITLE}: this build's CLI signing key (${cliSigningKeyFingerprint()}) does not match ` +
+                `the key the panel verifies against, so sign-in will be refused.`);
+            process.exitCode = 1;
+        }
+        return;
+    }
+    // The sandbox re-executes this process once, before any session exists. The
+    // guard in the environment is what stops the child from wrapping itself again.
+    if (args.sandbox && !process.env.HOWTOFIX_SANDBOXED) {
+        const { detectSandbox, enterSandbox, describeSandbox } = await import("./sandbox.js");
+        const kind = detectSandbox();
+        if (!kind) {
+            console.error(`${APP_TITLE}: --sandbox needs a working bubblewrap (Linux) or sandbox-exec (macOS). ` +
+                `Neither could be used here — on Linux this usually means unprivileged user namespaces are disabled.`);
+            process.exitCode = 1;
+            return;
+        }
+        console.error(describeSandbox(kind));
+        process.exitCode = enterSandbox(kind, { cwd, agentDir: AGENT_DIR, argv: [process.execPath, ...process.argv.slice(1)] });
+        return;
+    }
+    // Route through a proxy before the first request goes out. Here rather than at
+    // the top of `main` because this is the first line that cannot exit early:
+    // `--version` and `--help` have already returned above, and loading the proxy
+    // agent for a command that makes no request is a cost with no purpose. The
+    // update check and the sign-in exchange both go through it, and they run
+    // before any session exists — a proxy installed after them would be a setting
+    // that works only sometimes.
+    const { installProxy } = await import("./proxy.js");
+    installProxy(AGENT_DIR);
+    // `--update` installs the newest release; `--check-update` only looks. Both
+    // exit without a session, so neither loads the model stack.
+    if (args.update || args.checkUpdate) {
+        const { PACKAGE_NAME, checkForUpdate, installUpdate, isInstalledCopy } = await import("./update.js");
+        const check = await checkForUpdate(APP_VERSION);
+        if (!check.latest) {
+            // Not reaching the registry is a failure only when an install was asked
+            // for; a plain check that could not run has nothing to report.
+            console.error(`${APP_TITLE}: ${check.message}`);
+            process.exitCode = args.update ? 1 : 0;
+            return;
+        }
+        console.log(check.message);
+        if (args.checkUpdate || !check.available)
+            return;
+        if (!isInstalledCopy()) {
+            console.error(`${APP_TITLE}: this copy was not installed by npm, so npm cannot replace it. ` +
+                `install it with: npm install -g ${PACKAGE_NAME}`);
+            process.exitCode = 1;
+            return;
+        }
+        const result = await installUpdate({ version: check.latest });
+        console.log(result.message);
+        if (!result.ok)
+            process.exitCode = 1;
+        return;
+    }
+    // `howtofix preset <new|check|pack>` authors a preset and exits. It runs before
+    // anything loads the SDK, because authoring has nothing to do with a model and
+    // a preset author on a machine without credentials should still be able to
+    // validate what they wrote.
+    const presetArgv = process.argv.slice(2);
+    if (presetArgv[0] === "preset") {
+        const { runPresetCommand } = await import("./preset-command.js");
+        process.exitCode = runPresetCommand(presetArgv.slice(1));
+        return;
+    }
+    const { expandFileReferences } = await import("./at-file.js");
+    const { isApprovalMode, setApprovalMode, setDangerousBypass, isDangerousBypass } = await import("./permissions.js");
+    const { openSession } = await import("./session.js");
+    // Print mode has no dialogs, so anything that would ask must not block. The
+    // interactive default is `full-auto` too: an approval prompt that fires on
+    // every write is friction the user has to configure away, and a critical
+    // command is denied in every mode regardless.
+    setApprovalMode(args.approval && isApprovalMode(args.approval) ? args.approval : "full-auto");
+    // `--dangerously-skip-permissions` lifts the last two refusals print mode can
+    // still hit: a critical command and the loop guard. A stored preference does
+    // the same for someone who never passes flags — the flag wins when it is
+    // given, so a one-off run cannot be overridden by a file.
+    const { readWorkbenchSettings } = await import("./settings.js");
+    if (args.dangerouslySkipPermissions || readWorkbenchSettings(stateDir).skipPermissions)
+        setDangerousBypass(true);
+    // A bypass nobody can see is the dangerous kind: it removes the refusals a
+    // user relies on and leaves no trace of why. Say it is on, every run.
+    if (isDangerousBypass()) {
+        console.error(`${APP_TITLE}: permission checks are OFF — critical commands (filesystem wipes, ` +
+            `fork bombs, host shutdown) and the repeated-call guard are NOT enforced for this run. ` +
+            `Turn it off with /settings, or by removing skipPermissions from settings.json.`);
+    }
+    // A protocol server owns stdin and stdout from here on. It opens its own
+    // sessions (ACP opens one per `session/new`), so it returns before the one
+    // below is created.
+    if (args.mode) {
+        const { serveProtocol } = await import("./serve.js");
+        await serveProtocol(args.mode, { cwd, model: args.model, thinking: args.thinking });
+        return;
+    }
+    const open = (options) => openSession({
+        cwd,
+        model: args.model,
+        thinking: args.thinking,
+        continueSession: options.continueSession ?? false,
+        noSession: options.noSession ?? false,
+        sessionPath: options.sessionPath,
+        // The caller chooses the session, not the prompt. `--print` is the only
+        // route that runs without a terminal, and the prompt must say so or a
+        // skill that asks a question becomes a dead end that still exits 0.
+        interactive: !args.print,
+    });
+    const opened = await open({
+        continueSession: args.continueSession,
+        sessionPath: args.sessionPath,
+        noSession: args.noSession || args.print,
+    });
+    // The note reports how the session was opened, so a refusal below must not
+    // swallow it: print writes it here, ahead of any guard; the TUI carries it
+    // into the feed as `options.note`.
+    if (args.print && opened.note)
+        console.error(opened.note);
+    // A budget on an unpriced model can never fire, so refuse instead of
+    // pretending to guard — in *both* modes, now that the workbench enforces the
+    // cap too: a TUI drawing a cap over a model that reports $0 a turn would be
+    // the exact lie this refusal exists to prevent. See `priced` on
+    // `OpenedSession`.
+    if (args.maxBudgetUsd !== undefined && !opened.priced) {
+        console.error(`${APP_TITLE}: ${unpricedBudgetMessage(opened.modelLabel, stateDir)}`);
+        await opened.dispose();
+        process.exitCode = 2;
+        return;
+    }
+    if (args.print) {
+        // `--print` has no slash router, but the TUI routes every "/" prompt to one
+        // (submit → runSlash) and never lets those reach the model. Without this
+        // guard the same prompt is forwarded verbatim — `/connect sk-...` pasted
+        // into a script sends the credential to the provider and records it in the
+        // transcript, and the command silently does not run. Skills are exempt:
+        // the TUI forwards those as prompts too (runSlash → skillInvocation).
+        const trimmedPrompt = args.prompt.trimStart();
+        if (trimmedPrompt.startsWith("/")) {
+            const name = trimmedPrompt.slice(1).split(/\s+/)[0] ?? "";
+            const { skillInvocation } = await import("./skills.js");
+            const skillNames = opened.session.resourceLoader.getSkills().skills.map((skill) => skill.name);
+            const isSkill = skillInvocation(trimmedPrompt, skillNames) !== undefined;
+            if (!isSkill) {
+                const { slashCommands } = await import("./ui.js");
+                if (slashCommands(opened.session).some((command) => command.name === name)) {
+                    console.error(`${APP_TITLE}: /${name} runs in the TUI only — --print sends prompts straight to the model. ` +
+                        `Run \`howtofix\` without --print for interactive commands.`);
+                    await opened.dispose();
+                    process.exitCode = 2;
+                    return;
+                }
+            }
+        }
+        const stream = args.outputFormat === "stream-json";
+        const json = args.outputFormat === "json";
+        // Both machine formats end with a result record; only `stream-json` writes
+        // the events along the way.
+        const machine = stream || json;
+        // A `system`-shaped header first, so a consumer learns the model and the
+        // session id before any event that refers to them — the same courtesy the
+        // SDK's own JSON mode pays. Only the streaming format has events to head.
+        if (stream) {
+            const header = {
+                type: "system",
+                subtype: "init",
+                cwd,
+                session_id: opened.session.sessionId,
+                model: opened.modelLabel,
+                output_format: args.outputFormat,
+                max_budget_usd: args.maxBudgetUsd ?? null,
+                dangerously_skip_permissions: args.dangerouslySkipPermissions,
+                cli_version: APP_VERSION,
+            };
+            process.stdout.write(`${JSON.stringify(header)}\n`);
+        }
+        let unsubscribe;
+        let budgetHit;
+        const checkBudget = () => {
+            if (args.maxBudgetUsd === undefined || budgetHit !== undefined)
+                return;
+            const spent = opened.session.getSessionStats().cost;
+            if (spent > args.maxBudgetUsd) {
+                budgetHit = { spent };
+                void opened.session.abort();
+            }
+        };
+        try {
+            // Both machine formats and text need the same budget signal, and the only
+            // reliable one is the event stream: usage is updated as events arrive, so
+            // a timer that samples the total can miss the update entirely and let the
+            // run overspend. Subscribe in every mode; only `stream-json` writes the
+            // lines out.
+            // The failed turn is captured here, not read back from the session at the
+            // end. When the SDK's overflow recovery omits the attempt it could not
+            // recover from, `state.messages.at(-1)` is no longer the error — it is the
+            // user's prompt, or nothing — so `--print` reported success with an empty
+            // answer and exit code 0 for a run that failed. Measured against a gateway
+            // answering 400 "prompt is too long": exit 0, no output on either stream.
+            let failedTurn;
+            unsubscribe = opened.session.subscribe((event) => {
+                if (stream) {
+                    const line = jsonLine(event);
+                    if (line !== undefined)
+                        process.stdout.write(line);
+                }
+                if (event.type === "turn_end" && event.message?.role === "assistant") {
+                    const message = event.message;
+                    if (message.stopReason === "error" || message.stopReason === "aborted" || message.errorMessage) {
+                        failedTurn = { stopReason: message.stopReason ?? "error", errorMessage: message.errorMessage };
+                    }
+                    else {
+                        failedTurn = undefined;
+                    }
+                }
+                checkBudget();
+            });
+            await opened.session.prompt(expandFileReferences(args.prompt, cwd));
+            const text = opened.session.getLastAssistantText() ?? "";
+            if (budgetHit) {
+                console.error(`${APP_TITLE}: ${spendCapMessage(budgetHit.spent, args.maxBudgetUsd)}`);
+                // A consumer reading the stream needs a terminal record on this path
+                // too: without it the run just stops mid-stream and looks truncated.
+                if (machine) {
+                    const stats = opened.session.getSessionStats();
+                    process.stdout.write(`${JSON.stringify({
+                        type: "result",
+                        subtype: "error_max_budget_usd",
+                        is_error: true,
+                        result: text,
+                        session_id: opened.session.sessionId,
+                        duration_ms: Math.round(performance.now() - startedAt),
+                        num_turns: stats.assistantMessages,
+                        total_cost_usd: stats.cost,
+                        usage: {
+                            input_tokens: stats.tokens.input,
+                            output_tokens: stats.tokens.output,
+                            cache_read_input_tokens: stats.tokens.cacheRead,
+                            cache_creation_input_tokens: stats.tokens.cacheWrite,
+                        },
+                    })}\n`);
+                }
+                process.exitCode = 1;
+                return;
+            }
+            // The SDK contract: a final assistant response that ended in `error` or
+            // `aborted` produces a nonzero exit status, so scripts can branch on it.
+            //
+            // `failedTurn` is the turn the event stream saw fail; `messages.at(-1)` is
+            // the fallback for a run that failed without ever emitting one. Reading
+            // only the tail is what let an unrecovered overflow report success.
+            const last = opened.session.state.messages.at(-1);
+            const failure = failedTurn ??
+                (last?.role === "assistant" && (last.stopReason === "error" || last.stopReason === "aborted" || last.errorMessage)
+                    ? { stopReason: last.stopReason ?? "error", errorMessage: last.errorMessage }
+                    : undefined);
+            // One result record per run, written after the outcome is known. The
+            // success record used to be written first and the exit status decided
+            // afterwards, so a failed turn emitted "success" and then "error" — and a
+            // consumer reading the first record believed a failed run had worked.
+            if (machine) {
+                const stats = opened.session.getSessionStats();
+                process.stdout.write(`${JSON.stringify({
+                    type: "result",
+                    subtype: failure
+                        ? failure.stopReason === "aborted"
+                            ? "error_aborted"
+                            : "error_during_execution"
+                        : "success",
+                    is_error: failure !== undefined,
+                    result: text,
+                    session_id: opened.session.sessionId,
+                    duration_ms: Math.round(performance.now() - startedAt),
+                    num_turns: stats.assistantMessages,
+                    total_cost_usd: stats.cost,
+                    usage: {
+                        input_tokens: stats.tokens.input,
+                        output_tokens: stats.tokens.output,
+                        cache_read_input_tokens: stats.tokens.cacheRead,
+                        cache_creation_input_tokens: stats.tokens.cacheWrite,
+                    },
+                    stop_reason: failure?.stopReason ?? (last?.role === "assistant" ? last.stopReason : undefined),
+                })}\n`);
+            }
+            else {
+                process.stdout.write(text.endsWith("\n") ? text : `${text}\n`);
+            }
+            if (failure) {
+                process.exitCode = 1;
+                // A failed turn used to exit 1 with no output at all, which is
+                // indistinguishable from a crash. Say what the provider said.
+                if (failure.errorMessage) {
+                    console.error(`${APP_TITLE}: ${failure.errorMessage}`);
+                    // Same gap as the TUI: the gateway's own sentence, and the fix for it.
+                    const fix = diagnoseGatewayFailure(failure.errorMessage);
+                    if (fix !== undefined)
+                        console.error(`${APP_TITLE}: ${fix}`);
+                }
+            }
+        }
+        finally {
+            unsubscribe?.();
+            await opened.dispose();
+        }
+        return;
+    }
+    if (!process.stdin.isTTY || !process.stdout.isTTY) {
+        console.error(`${APP_TITLE}: interactive mode needs a terminal. use --print for pipes.`);
+        await opened.dispose();
+        process.exitCode = 2;
+        return;
+    }
+    const { runWorkbench } = await import("./ui.js");
+    // Only a copy npm owns can be replaced by npm, and only when the user has not
+    // turned it off. The check itself is handed to the workbench so it runs after
+    // the UI is up rather than before it.
+    const { autoUpdateEnabled, isInstalledCopy } = await import("./update.js");
+    const canSelfUpdate = isInstalledCopy() && autoUpdateEnabled(`${stateDir}/settings.json`);
+    await runWorkbench({
+        cwd,
+        modelLabel: opened.modelLabel,
+        session: opened.session,
+        // The `/rtk` command toggles the flag the tool-result extension reads; the setter
+        // lives beside that flag so the two cannot drift apart.
+        setCompressToolOutput: opened.setCompressToolOutput,
+        initialPrompt: args.prompt || undefined,
+        note: opened.note,
+        // The cap the print path enforces over one run, handed to a UI that has to
+        // enforce it over many: same flag, same dollars, different lifetime.
+        maxBudgetUsd: args.maxBudgetUsd,
+        update: canSelfUpdate ? { current: APP_VERSION, install: true } : undefined,
+        reopen: open,
+    });
+}
+installCrashHandlers(APP_TITLE);
+main().catch((error) => {
+    reportError(APP_TITLE, undefined, error);
+    process.exitCode = 1;
+});