@proagentstore/cli 0.4.84 → 0.4.86

package/dist/browser-runner/local-apply/bridge.js

@@ -24,7 +24,8 @@
  *
  * The trace carries classes, domains, decisions and artifact handles — never a typed value.
  */
-import { ELEMENT_PROBE_FN, FALLBACK_COMMIT_RE } from "../commit-guard.js";
+import { classifyApplyClick } from "./contract.js";
+import { ELEMENT_PROBE_FN } from "../commit-guard.js";
 import { normalize } from "../local-artifact/engine.js";
 import { evaluateResult, hostOf, refRole } from "../local-browser/bridge.js";
 const READ_TOOLS = new Set(["browser_navigate", "browser_navigate_back", "browser_snapshot", "browser_wait_for"]);
@@ -329,9 +330,24 @@ export class ApplyBridge {
         const facts = await this.probe(t.ref, t.name);
         if (!facts)
             return this.refuse("browser_click", "read", "That element could not be read from the page, so the click cannot be shown to be safe. Take a fresh browser_snapshot.");
-        const commits = (facts.submits && facts.method === "post") || [facts.name, t.name, String(forward.element)].some((n) => n && FALLBACK_COMMIT_RE.test(n));
-        if (commits)
-            return this.submit(forward);
+        // WHICH control is this? (#985) The rule is in the shared contract, which states the three
+        // families and why the order of the tests is the safety property. It replaced a test against
+        // `FALLBACK_COMMIT_RE` — the READ-ONLY floor, which matches bare `apply` on purpose — under
+        // which the press that OPENS a SEEK application was the final submit, and four live
+        // fill-and-review runs ended `awaiting_review` with `filled: 0` seconds after the cloud had
+        // let them through their initial checkpoint.
+        const klass = classifyApplyClick({
+            role: t.role,
+            names: [facts.name, t.name, String(forward.element)],
+            submits: facts.submits,
+            method: facts.method,
+            filled: this.filled,
+            uploaded: this.uploaded.size,
+        });
+        if (klass.klass === "submit")
+            return this.submit(forward, klass.reason);
+        if (klass.klass === "entry")
+            return this.entry(forward, t, klass.reason);
         if (NAV_ROLES.has(t.role) || (t.role === "button" && PAGINATION_NAME.test(t.name.trim()))) {
             if (this.pages >= this.host.limits.maxPages)
                 return this.refuse("browser_click", "read", `The run's limit of ${this.host.limits.maxPages} pages is reached. Call ready_for_review now.`);
@@ -342,7 +358,7 @@ export class ApplyBridge {
         }
         // A native file input opens the file chooser for upload_artifact — a DOM fact, whatever its label.
         const fileInput = facts.tag === "input" && facts.type === "file";
-        if (fileInput || (t.role === "button" && STEP_NAME.test(t.name.trim()) && !facts.submits)) {
+        if (fileInput || klass.klass === "step" || (t.role === "button" && STEP_NAME.test(t.name.trim()) && !facts.submits)) {
             const checkpoint = this.requireSupervisor("browser_click", "fill");
             if (checkpoint)
                 return checkpoint;
@@ -508,20 +524,76 @@ export class ApplyBridge {
         return text(`Recorded the runner-verified ${reason} listing notice. Stop now.`);
     }
     review(summary) {
-        this.reviewReady = true;
         this.summary = summary; // bounded where the result is built (runtime.ts `end`)
+        // #989: "ready for review" with nothing entered is not a review state.
+        //
+        // The live run ended `awaiting_review` with `filled: 0, uploaded: 0` seconds after the cloud
+        // had let it through its initial checkpoint, because a refused submit-class click called
+        // this. An owner reading that is told a form is populated and waiting for them — and the one
+        // action it invites (#981's approve-and-continue) would send an empty application. There is
+        // no form to review, so the honest terminal outcome is the recorded blocker and its remedy
+        // (`runtime.ts` `outcomeOf` reads `blocked` once `reviewReady` is false).
+        if (!this.filled && !this.uploaded.size && this.blocked) {
+            this.host.emit({ type: "policy.decision", detail: { tool: "ready_for_review", class: "review", decision: "refused", reason: this.blocked.reason, count: 0 } });
+            return text(`Nothing was entered on this application, so there is nothing to review: the run is recorded as ${this.blocked.reason.replace(/_/g, " ")}. Stop now.`, true);
+        }
+        this.reviewReady = true;
         this.host.emit({ type: "review.ready", detail: { class: "review", count: this.filled } });
         return text("Recorded. The application waits for the owner's review; nothing was submitted. Stop now.");
     }
+    /**
+     * The control that OPENS the application (#985) — pressed, never submitted.
+     *
+     * It needs the supervisor's live `continue` exactly as a fill does: it changes the page, and the
+     * cloud is the party that decides whether this page may be worked on. `afterMove` then counts the
+     * page, traces it and clears the approval, so the form that opens gets its own checkpoint — which
+     * is what keeps a multi-page ATS supervised page by page rather than once at the start.
+     */
+    async entry(forward, t, reason) {
+        const checkpoint = this.requireSupervisor("browser_click", "fill");
+        if (checkpoint)
+            return checkpoint;
+        if (this.pages >= this.host.limits.maxPages)
+            return this.refuse("browser_click", "read", `The run's limit of ${this.host.limits.maxPages} pages is reached. Call ready_for_review now.`);
+        this.host.emit({ type: "policy.decision", detail: { tool: "browser_click", class: "entry", decision: "allowed", reason, role: t.role } });
+        const res = await this.browser.callTool("browser_click", forward);
+        if (res.isError)
+            return { content: [{ type: "text", text: textOf(res) }], isError: true };
+        return this.afterMove("browser_click", textOf(res));
+    }
     /** The final Submit. Never under fill_and_review; once, gated and traced, under auto_submit. */
-    async submit(forward) {
+    async submit(forward, why = "terminal_label") {
         const checkpoint = this.requireSupervisor("browser_click", "submit");
         if (checkpoint)
             return checkpoint;
         if (this.host.mode !== "auto_submit" || !this.host.gateId) {
-            this.host.emit({ type: "policy.decision", detail: { tool: "browser_click", class: "submit", decision: "refused", reason: "fill_and_review" } });
-            this.review("Stopped at the final submit: this run fills and waits for review.");
-            return text("That control submits the application, and this run is fill-and-review: it was NOT pressed. The application waits for the owner's review. Stop now.");
+            // `reason` carries WHICH rule classified this as the submit (#985). "fill_and_review"
+            // alone left an owner with a run that stopped at `filled: 0` and no way to tell whether it
+            // had reached the end of the form or refused the button that opens it.
+            // The RULE, not the control's label: the label is the page's own prose and belongs to the
+            // machine (the contract keeps page text off the cloud trace). The rule is what an owner
+            // needs — "this was the one-click control", not "this was a submit".
+            this.host.emit({ type: "policy.decision", detail: { tool: "browser_click", class: "submit", decision: "refused", reason: "fill_and_review", rule: why } });
+            const oneClick = why === "one_click_apply";
+            // #989: a refusal with NOTHING entered is not a review state, so it is recorded as the
+            // blocker it is. `review` then declines to mark the run ready (see there), and the owner
+            // gets a terminal outcome they can act on — approve this application, or open it
+            // themselves — instead of an empty form presented as waiting for their approval. With
+            // work on the page the old reading holds: there IS a filled form to look at.
+            if (!this.filled && !this.uploaded.size) {
+                this.blocked = {
+                    reason: "incomplete",
+                    questions: [
+                        oneClick
+                            ? "This listing's apply control can send the application in one click, so a fill-and-review run may not press it, and nothing was entered. Approve this application to let it be sent, or apply on the site yourself."
+                            : "The run reached the control that submits this application without entering anything — the form may already be complete from your profile, or it may not have opened. Approve this application to let it be sent, or open it yourself.",
+                    ],
+                };
+            }
+            this.review(oneClick ? "Stopped at a one-click apply control: it can send the application outright, and this run fills and waits for review." : "Stopped at the final submit: this run fills and waits for review.");
+            return text(oneClick
+                ? 'That control ("' + String(forward.element ?? "") + '") can send the application in one click, and this run is fill-and-review: it was NOT pressed. Approve this application if you want it sent. Stop now.'
+                : "That control submits the application, and this run is fill-and-review: it was NOT pressed. The application waits for the owner's review. Stop now.");
         }
         const before = await this.inspect();
         if (!before)

package/dist/browser-runner/local-apply/contract.js

@@ -58,6 +58,53 @@ export const LOCAL_APPLY_BLOCK_REASONS = [
     "job_unavailable",
     "bridge_unused",
 ];
+/**
+ * Why a run produced nothing on the page (#975) — a CLOSED vocabulary, never free text.
+ *
+ * The production case: the CLI authenticated, exited 0 after 51 seconds, and emitted no browser,
+ * checkpoint, fill or review event. The outcome said `incomplete`, which is also what a half-filled
+ * form says, so the operator had no way to tell "it did nothing" from "it stopped partway" — and no
+ * way at all to learn WHY without reading a terminal on the machine.
+ *
+ * Deliberately NOT an output tail, redacted or otherwise. `redactText` removes credential SHAPES; it
+ * cannot remove the owner's own résumé prose, their typed answers or a quoted source document, all
+ * of which a CLI legitimately prints while it works. So nothing free-form is added here: every field
+ * is a count, a code, or an id from {@link LOCAL_APPLY_SIGNALS} that the RUNNER chose by matching
+ * its own output. The engine's closing sentence continues to cross as `summary`, where it already
+ * did — redacted and capped — so this adds diagnosis without adding a new channel for content.
+ */
+/**
+ * The first published CLI whose runner executes THIS contract (#977, raised at #989).
+ *
+ * An older runner is not broken; it simply predates the vocabulary. Left to run, it reports the
+ * same failure in the PREVIOUS shape, which is indistinguishable from a run under the new contract
+ * — exactly the live confusion #977 was filed from. So a machine below this is refused BEFORE
+ * dispatch, naming the update, rather than silently producing the older behaviour (`apply.ts`
+ * `runnerContractProblem`).
+ *
+ * ── Why it moved to 0.4.85 (#989)
+ *
+ * #985 fixed the runner's click classification — the press that OPENS a SEEK application stopped
+ * being read as the final submit ({@link classifyApplyClick}) — and that fix lives in
+ * `packages/browser-runner`, which ships INSIDE the published CLI. The commit did not bump
+ * `packages/cli/package.json`, and `publish-npm.yml` publishes only a version that is new, so
+ * nothing was published: the live machine kept running 0.4.84, whose bundled bridge still tests
+ * `FALLBACK_COMMIT_RE`. The next live run therefore reproduced the defect the fix had already
+ * removed from `main` — `browser_click → class: submit → refused: fill_and_review`, no `rule`
+ * field, three seconds after the cloud's own `continue` — and the only durable evidence that the
+ * code was old was the absence of a field nobody looks for.
+ *
+ * A behaviour change in the runner is a CONTRACT change, because the cloud's decisions assume it.
+ * So this floor moves with it: a machine that cannot tell the entry control from the final submit
+ * is refused with a sentence that says so, instead of ending `awaiting_review` having typed
+ * nothing.
+ *
+ * Bump this when the runner's half of the contract changes again, together with the CLI version
+ * that ships it — `policy.test.ts` pins the pair, so the floor cannot name a release that has not
+ * been published. `cliAtLeast` treats an unreported version as capable, which is the convention
+ * every MIN_CLI gate here follows.
+ */
+export const LOCAL_APPLY_CONTRACT_MIN_CLI = "0.4.85";
 export const LOCAL_APPLY_DIAGNOSTIC_CAUSES = ["bridge_unused", "engine_exited_nonzero", "timed_out", "no_engine_output"];
 export const LOCAL_APPLY_SIGNALS = ["approval_policy_blocked", "bridge_tools_missing", "auth_prompt", "no_output", "engine_refused_task"];
 export const LOCAL_APPLY_UNAVAILABLE_REASONS = ["expired", "unavailable"];
@@ -89,7 +136,11 @@ export const LOCAL_APPLY_CAPS = { questions: 20, questionChars: 300, answers: 20
 const str = (v, max) => (typeof v === "string" && v.trim() ? v.trim().slice(0, max) : null);
 const oneOf = (list, v) => (list.includes(v) ? v : null);
 const isHttpUrl = (v) => /^https?:\/\/[^\s/]+/i.test(v);
-const DETAIL_KEYS = new Set(["engine", "authMode", "engineAuth", "mode", "class", "tool", "decision", "reason", "role", "kind", "path", "sha256", "bytes", "gateId", "exitCode", "count", "status", "basis", "source", "checkpointId", "directive", "phase", "actions", "filled", "uploaded"]);
+// `rule` is on this list from #989: the runner has emitted WHICH rule classified a click as the
+// submit since #985, and this whitelist silently dropped it — so the one fact that tells "it
+// refused the control that opens the form" from "it refused the real submit" never reached the
+// cloud trace, which is where the live investigation needed it.
+const DETAIL_KEYS = new Set(["engine", "authMode", "engineAuth", "mode", "class", "tool", "decision", "reason", "rule", "role", "kind", "path", "sha256", "bytes", "gateId", "exitCode", "count", "status", "basis", "source", "checkpointId", "directive", "phase", "actions", "filled", "uploaded"]);
 /** A validated event, or null. Detail keeps only whitelisted, primitive, bounded values. */
 export function parseLocalApplyEvent(raw) {
     if (!raw || typeof raw !== "object")
@@ -208,3 +259,104 @@ export function parseLocalApplyResult(raw) {
         out.error = str(o.error, 1000) ?? "The run failed without a reason.";
     return { result: out };
 }
+// ── Which control is the FINAL submit, and which one opens the form (#985) ───────────────────
+/**
+ * ── The live failure
+ *
+ * Four consecutive fill-and-review runs on one SEEK posting ended `awaiting_review` with
+ * `filled: 0`. The last of them (`286bbb8a…`, 2026-10-08) got everything right up to the last
+ * step: the runner reported its `initial` checkpoint, the cloud's deterministic policy decided
+ * `continue` (#982), the directive was delivered and acknowledged and the CLI resumed — and then,
+ * three seconds later, the press that OPENS the application was classified as the final submit,
+ * refused under `fill_and_review`, and the run ended at review having typed nothing.
+ *
+ * The cause was a borrowed vocabulary. The bridge tested the control's label against the runner's
+ * `FALLBACK_COMMIT_RE` — the READ-ONLY floor, which matches bare `apply` deliberately, because for
+ * an agent that may never act, refusing a filter button called "Apply" is the cheap error. For a
+ * run whose entire capability is to fill the form it is the expensive one. The cloud's own
+ * `commit-guard.ts` had already written the distinction down twice ("Apply/Next/Continue … are the
+ * ENTRY button on most multi-page ATS"; the APPLY family is terminal "only after something has
+ * been typed") — the apply bridge just had no list of its own to reach for.
+ *
+ * ── The three families, and why the order of the tests is the safety property
+ *
+ * 1. ONE-CLICK ({@link ONE_CLICK_SUBMIT_RE}) — "Quick apply", "Easy Apply", "Apply with your
+ *    profile". On LinkedIn, and on a profile-apply SEEK listing, that control can send the
+ *    application outright. Tested FIRST and always terminal, because the two families overlap in
+ *    English and the overlap is only dangerous in one direction: reading "Quick apply" as an entry
+ *    control is how an unapproved application reaches an employer.
+ * 2. TERMINAL ({@link TERMINAL_APPLY_SUBMIT_RE}) — "Submit", "Send application", "Finish", in
+ *    twenty languages: the control that sends what has been filled.
+ * 3. ENTRY ({@link APPLY_ENTRY_RE}) — "Apply", "Apply for this job", "Next", "Continue", and their
+ *    equivalents: the control that opens or advances the form. Only ever an entry while nothing has
+ *    been entered yet and the control is not a POST submit; once a field is filled, the APPLY
+ *    family becomes terminal again, which is the rule the cloud guard already states.
+ *
+ * Everything outside the three families is decided by the DOM, as before: a native POST submit is
+ * a submit. The one case that changed is a POST submit labelled as a STEP with nothing filled yet
+ * ("Save and continue" on page 1) — that stays walkable, because a multi-page ATS cannot be filled
+ * otherwise, and the final page's control says SUBMIT.
+ */
+const applyWordish = (token) => `(?<![\\p{L}\\p{N}])${token}(?![\\p{L}\\p{N}])`;
+/** A control that can SEND the application on its own. Terminal, whatever else it looks like. */
+export const ONE_CLICK_SUBMIT_RE = new RegExp([
+    "quick apply|easy apply|instant apply|one[- ]?click|1[- ]?click|apply with (your )?(profile|r[ée]sum[ée]|cv|linkedin|indeed|seek)|apply using (your )?profile",
+    ...["schnellbewerbung", "postulation rapide", "candidatura rapida", "snelle sollicitatie"].map(applyWordish),
+    ...["快速申请", "簡単応募", "간편지원"],
+].join("|"), "iu");
+/** The control that SENDS a filled application. Mirrors the cloud guard's terminal English set. */
+export const TERMINAL_APPLY_SUBMIT_RE = new RegExp([
+    "\\b(submit|finish|done|complete|confirm)\\b|send application|submit application|send my application",
+    ...[
+        "envoyer", "soumettre", "valider", "finaliser", "terminer", "confirmer",
+        "absenden", "abschicken", "senden", "einreichen", "best[äa]tigen", "abschlie[sß]en", "fertigstellen",
+        "enviar", "confirmar", "finalizar", "completar", "submeter", "concluir",
+        "invia", "inviare", "conferma", "confermare", "completa", "termina", "finalizza",
+        "verstuur", "versturen", "verzenden", "indienen", "bevestig", "bevestigen", "voltooien", "afronden",
+        "skicka", "sende", "bekr[äae]fta", "bekreft", "bekr[æa]ft", "slutf[öo]r", "fullf[øo]r", "afslut",
+        "wy[śs]lij", "z[łl]ó[żz]", "potwierd[źz]", "zako[ńn]cz", "odeslat", "potvrdit", "dokon[čc]it",
+        "g[öo]nder", "onayla", "tamamla", "kirim", "kirimkan", "ajukan", "konfirmasi",
+        "g[ửu]i", "n[ộo]p", "отправить", "подтвердить", "завершить", "подать",
+    ].map(applyWordish),
+    ...["提交", "送出", "确认", "確認", "完成", "送信", "提出", "完了", "제출", "보내기", "확인", "완료", "إرسال", "تقديم", "تأكيد"],
+].join("|"), "iu");
+/** The control that OPENS or ADVANCES the form — never the one that sends it. */
+export const APPLY_ENTRY_RE = new RegExp([
+    "\\b(apply|apply now|apply for this job|apply for this role|view (and )?apply|start( your)? application|begin( your)? application|next|continue|save and continue|start)\\b",
+    ...["postuler", "candidater", "bewerben", "candidati", "solliciteer", "aplikuj", "aplicar", "postular", "candidatar", "ans[øo]g", "başvur", "lamar", "откликнуться"].map(applyWordish),
+    ...["申请", "应聘", "応募する", "応募", "지원하기", "التقديم"],
+].join("|"), "iu");
+/**
+ * Classify one click. PURE, so the rule that decides whether a real application is sent is
+ * assertable without a browser — and identical in both copies of this file.
+ *
+ * Order is the specification: one-click first (it can send), then terminal, then the DOM's own
+ * verdict once anything has been entered, then entry/step.
+ */
+export function classifyApplyClick(input) {
+    const names = input.names.map((n) => (n ?? "").trim()).filter((n) => n.length > 0);
+    const hit = (re) => names.find((n) => re.test(n));
+    const entered = input.filled > 0 || input.uploaded > 0;
+    const oneClick = hit(ONE_CLICK_SUBMIT_RE);
+    if (oneClick)
+        return { klass: "submit", reason: "one_click_apply" };
+    const terminal = hit(TERMINAL_APPLY_SUBMIT_RE);
+    if (terminal)
+        return { klass: "submit", reason: "terminal_label" };
+    // A native POST submit, once something HAS been entered: there is an application to send, so
+    // the benefit of the doubt goes to the employer rather than to the run.
+    if (input.submits && input.method === "post" && entered)
+        return { klass: "submit", reason: "post_submit_after_fill" };
+    const entry = hit(APPLY_ENTRY_RE);
+    // Nothing entered yet: an APPLY/NEXT control opens the form. This is the press that ended four
+    // live runs at `filled: 0` — and it cannot be the final submit, because nothing has been typed.
+    if (entry && !entered)
+        return { klass: "entry", reason: input.submits ? "entry_post_form_nothing_filled" : "entry_label_nothing_filled" };
+    if (entry)
+        return { klass: "step", reason: "step_after_fill" };
+    // A POST submit with no recognised label and nothing entered is a page-advance on a multi-page
+    // form; with something entered it was caught above.
+    if (input.submits && input.method === "post")
+        return { klass: "step", reason: "post_submit_nothing_filled" };
+    return { klass: "other", reason: "unrecognised" };
+}

package/dist/browser-runner/local-browser/contract.js

@@ -50,6 +50,7 @@ export const LOCAL_BROWSER_EVENT_TYPES = [
 export const LOCAL_BROWSER_PLATFORM_EVENT_TYPES = ["run.requested", "runner.dispatched", "run.ended", "review.decision"];
 export const LOCAL_BROWSER_ENGINE_AUTHS = ["subscription", "machine-login", "api-key", "missing_login", "unknown"];
 export const LOCAL_BROWSER_SOURCE_FAILURE_REASONS = ["login_required", "captcha", "paywall", "access_denied", "robots", "timeout", "error"];
+export const LOCAL_BROWSER_ERROR_CODES = ["browser_unavailable", "engine_not_installed", "engine_not_signed_in", "bridge_unused", "consent_declined", "time_limit", "cancelled", "engine_failed"];
 export const LOCAL_BROWSER_CAPS = { findings: 200, sourceFailures: 200, text: 4000, fieldCount: 40 };
 const SENSITIVE_KEY = /cookie|password|passwd|secret|token|authorization|api[_-]?key|otp|form[_-]?values?|credential/i;
 /** An env var NAME whose value is a credential. */
@@ -209,7 +210,13 @@ export function parseLocalBrowserResult(raw) {
     // Redacted again here, whatever the runner did: an error is CLI output, and CLIs print keys.
     const rawError = str(o.error, 1000);
     const error = rawError === null ? null : redactText(rawError);
-    if (outcome === "failed")
+    if (outcome === "failed") {
         out.error = error ?? "The run failed without a reason.";
+        // #944: the runner's own name for the cause, when it gave one. An unrecognised code is
+        // dropped rather than passed through, so the stored vocabulary stays closed.
+        const code = oneOf(LOCAL_BROWSER_ERROR_CODES, o.errorCode);
+        if (code)
+            out.errorCode = code;
+    }
     return { result: out };
 }

package/dist/browser-runner/local-browser/runtime.js

@@ -28,6 +28,26 @@ import { BrowserBridge, domainWithin } from "./bridge.js";
 import { BRIDGE_ENV } from "./bridge-stdio.js";
 import { LOCAL_BROWSER_AUTH_MODES, LOCAL_BROWSER_ENGINES, LOCAL_BROWSER_TASK_TYPE, redactDetail, redactText, secretEnvValues, } from "./contract.js";
 import { bridgeUnused, buildEngineSpec, finalText, missingLogin, observedEngineAuth, researchPrompt, signInHelp } from "./engine.js";
+/**
+ * Why the run could not be launched, in words the owner can act on (#944).
+ *
+ * Two shapes reach here: the owner declining the signed-in profile, which is a DECISION and not a
+ * fault, and the browser failing to start — the "missing browser" state the acceptance criteria
+ * ask for. Everything a browser can refuse at startup is fixed at the machine (install Chrome, free
+ * the profile another window is holding, allow the automation port), so the sentence says that; the
+ * raw message rides along, because it is the half that names which of those it was.
+ */
+function launchFailure(err) {
+    const message = err instanceof Error ? err.message : String(err);
+    if (/did not allow research in their signed-in browser profile/i.test(message)) {
+        return { outcome: "failed", error: message, errorCode: "consent_declined" };
+    }
+    return {
+        outcome: "failed",
+        error: `The browser for this run could not be started on this machine: ${message.slice(0, 400)}. Check that Chrome or Chromium is installed, that no other window is holding the profile this run uses, and that \`pags up\` may launch it — then start the run again.`,
+        errorCode: "browser_unavailable",
+    };
+}
 const MAX_EVENTS = 2000;
 const OUTPUT_LINES = 400;
 const SAFE_ID = /^[A-Za-z0-9_.:-]{1,100}$/;
@@ -172,7 +192,10 @@ export class LocalBrowserRuntime {
         this.runs.set(envelope.runId, run);
         // Not awaited: a signed-in-profile consent pause can hold the launch for minutes, and the
         // relay command that started the run must answer now. Everything after this is in `status`.
-        void this.launch(run, selfUrl).catch((err) => this.end(run, { outcome: "failed", error: err instanceof Error ? err.message : String(err) }));
+        // #944: a launch failure is the one the acceptance criteria call "missing browser", and it was
+        // the one cause with no name: it ended the run with whatever the browser threw, which the
+        // cloud then filed as `engine_failed` — the CLI blamed for a browser that never started.
+        void this.launch(run, selfUrl).catch((err) => this.end(run, launchFailure(err)));
         return { runId: envelope.runId, taskId: envelope.runId, status: run.state, existing: false };
     }
     async launch(run, selfUrl) {
@@ -230,7 +253,12 @@ export class LocalBrowserRuntime {
         child.stderr?.on("data", keep);
         child.on("error", (err) => {
             const missing = err.code === "ENOENT";
-            this.end(run, { outcome: "failed", error: missing ? `The ${e.engine === "claude" ? "Claude Code" : "Codex"} CLI is not installed on this machine (\`${spec.command}\` was not found).` : err.message });
+            this.end(run, {
+                outcome: "failed",
+                ...(missing
+                    ? { error: `The ${e.engine === "claude" ? "Claude Code" : "Codex"} CLI is not installed on this machine (\`${spec.command}\` was not found).`, errorCode: "engine_not_installed" }
+                    : { error: err.message }),
+            });
         });
         child.on("close", (code) => {
             if (buf.trim())
@@ -377,12 +405,12 @@ export class LocalBrowserRuntime {
         const summary = bridge?.summary ?? finalText(e.engine, run.output);
         const found = (bridge?.findings.length ?? 0) > 0;
         if (run.cancelled)
-            return { outcome: "failed", error: "Cancelled by the owner" };
+            return { outcome: "failed", error: "Cancelled by the owner", errorCode: "cancelled" };
         if (missingLogin(e.engine, run.output.join("\n")) && !found)
-            return { outcome: "failed", error: signInHelp(e.engine), engineAuth: "missing_login" };
+            return { outcome: "failed", error: signInHelp(e.engine), errorCode: "engine_not_signed_in", engineAuth: "missing_login" };
         const limit = `Stopped at the ${e.limits.maxMinutes}-minute limit.`;
         if (run.timedOut)
-            return { outcome: found ? "completed" : "failed", summary: summary || limit, error: limit };
+            return { outcome: found ? "completed" : "failed", summary: summary || limit, error: limit, errorCode: "time_limit" };
         if (code !== 0 && !bridge?.summary) {
             const tail = run.output.slice(-5).join("\n").slice(-800);
             return { outcome: "failed", summary, error: `The ${e.engine} CLI exited with code ${code}${tail ? `: ${tail}` : ""}` };
@@ -391,7 +419,7 @@ export class LocalBrowserRuntime {
         // says. Live run aac758dc (#952) ended `completed` with "the browser bridge required approval":
         // no page opened, and the run looked like a success with nothing found.
         if (!bridge?.calls)
-            return { outcome: "failed", summary, error: bridgeUnused(e.engine, summary) };
+            return { outcome: "failed", summary, error: bridgeUnused(e.engine, summary), errorCode: "bridge_unused" };
         return { outcome: "completed", summary };
     }
     end(run, r) {
@@ -412,7 +440,13 @@ export class LocalBrowserRuntime {
             traceId: run.envelope.runId,
             engineAuth: r.engineAuth ?? run.engineAuth,
             // CLI output becomes this text, and a CLI prints whatever it was given: redacted before it is kept.
-            ...(r.outcome === "failed" ? { error: redactText((r.error ?? "The run failed without a reason.").slice(0, 1000), run.secrets) } : {}),
+            ...(r.outcome === "failed"
+                ? {
+                    error: redactText((r.error ?? "The run failed without a reason.").slice(0, 1000), run.secrets),
+                    // #944: WHICH cause, named here rather than guessed by the cloud from `engineAuth`.
+                    errorCode: r.errorCode ?? "engine_failed",
+                }
+                : {}),
         };
         if (run.child && run.child.exitCode === null)
             this.kill(run);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@proagentstore/cli",
-  "version": "0.4.84",
+  "version": "0.4.86",
   "description": "CLI for creating, publishing, and running ProAgentStore agents",
   "license": "MIT",
   "type": "module",