@proagentstore/cli 0.4.82 → 0.4.84

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

@@ -29,7 +29,7 @@ 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"]);
 const FILL_TOOLS = new Set(["browser_type", "browser_select_option"]);
-const BRIDGE_TOOLS = ["upload_artifact", "request_answer", "ready_for_review"];
+const BRIDGE_TOOLS = ["upload_artifact", "request_answer", "ready_for_review", "supervisor_checkpoint"];
 const REFUSED = new Set([
     "browser_fill_form",
     "browser_file_upload",
@@ -70,6 +70,9 @@ const INSPECT_PAGE = `() => {
 		duplicate: /you('ve| have) already applied|already applied (for|to) this|application (already exists|has already been (submitted|received))|duplicate application/.test(text),
 		antiBot: /unusual traffic|access (is )?denied|request (has been )?blocked|bot detected|checking (if the site connection is secure|your browser)/.test(text),
 		confirmed: /thank you for (your )?appl|application (has been |was )?(received|submitted)|we('ve| have) received your application|successfully (applied|submitted)/.test(text),
+		unavailable: /(?:this |the )?(?:job|position|posting|role|opportunity).{0,120}(?:has )?(?:expired|closed|been filled|is no longer available|is no longer accepting applications)|(?:expired|closed|no longer available|no longer accepting applications).{0,120}(?:job|position|posting|role|opportunity)/.test(text)
+			? (/expired/.test(text) ? "expired" : "unavailable")
+			: null,
 	};
 }`;
 const text = (t, isError = false) => ({ content: [{ type: "text", text: t }], ...(isError ? { isError: true } : {}) });
@@ -102,14 +105,19 @@ function withQuote(schema, required) {
 export class ApplyBridge {
     browser;
     host;
+    /** Read by the runtime for the #975 diagnostic: 0 calls is the finding, not an internal detail. */
     actions = 0;
     pages = 0;
     lastSnapshot = "";
     admitted = new Set();
+    /** Fill and submit are disabled until the cloud supervisor releases the current page checkpoint. */
+    supervisorApproved = false;
     filled = 0;
     uploaded = new Set();
     reviewReady = false;
     summary = null;
+    /** Present only after the CLI explicitly reports a notice that the runner independently saw. */
+    unavailable = null;
     submitAttempted = false;
     submitted = null;
     /** The last thing that stopped the work and was not resolved — the block reason if the run ends here. */
@@ -119,7 +127,7 @@ export class ApplyBridge {
         this.host = host;
     }
     get done() {
-        return this.reviewReady || this.submitAttempted;
+        return this.reviewReady || this.submitAttempted || this.unavailable !== null;
     }
     async listTools() {
         const own = (await this.browser.listTools()).filter((t) => READ_TOOLS.has(t.name) || FILL_TOOLS.has(t.name) || t.name === "browser_click" || t.name === "browser_press_key");
@@ -149,6 +157,16 @@ export class ApplyBridge {
                 description: "The form is filled as far as the sources allow. Stop here; the owner reviews it. Call once, last.",
                 inputSchema: { type: "object", properties: { summary: { type: "string" } }, required: ["summary"] },
             },
+            {
+                name: "supervisor_checkpoint",
+                description: "Pause safely for the cloud supervisor. Use the exact checkpointId supplied in your task; do not continue until this returns continue. request_review and stop are terminally handled by the runner.",
+                inputSchema: { type: "object", properties: { checkpointId: { type: "string", minLength: 1, maxLength: 300 }, phase: { type: "string", enum: ["initial", "post_navigation", "before_submit", "uncertain"] } }, required: ["checkpointId", "phase"], additionalProperties: false },
+            },
+            {
+                name: "report_job_unavailable",
+                description: "End the run when a fresh browser snapshot shows that this job is expired, closed or unavailable. The runner independently verifies the page notice; it refuses unsupported reports.",
+                inputSchema: { type: "object", properties: { reason: { type: "string", enum: ["expired", "unavailable"] } }, required: ["reason"] },
+            },
         ];
     }
     async callTool(name, args = {}) {
@@ -158,6 +176,10 @@ export class ApplyBridge {
             return this.review(typeof args.summary === "string" ? args.summary : "");
         if (name === "request_answer")
             return this.requestAnswer(args);
+        if (name === "supervisor_checkpoint")
+            return this.supervisorCheckpoint(args);
+        if (name === "report_job_unavailable")
+            return this.reportUnavailable(args);
         if (REFUSED.has(name))
             return this.refuse(name, "read", `${name} is not available to an application run.`);
         if (!READ_TOOLS.has(name) && !FILL_TOOLS.has(name) && name !== "browser_click" && name !== "browser_press_key" && name !== "upload_artifact")
@@ -200,7 +222,8 @@ export class ApplyBridge {
         const v = res && !res.isError ? evaluateResult(textOf(res)) : null;
         if (!v || typeof v.url !== "string")
             return null;
-        return { url: v.url, title: String(v.title ?? ""), captcha: !!v.captcha, login: !!v.login, duplicate: !!v.duplicate, antiBot: !!v.antiBot, confirmed: !!v.confirmed };
+        const unavailable = v.unavailable === "expired" || v.unavailable === "unavailable" ? v.unavailable : null;
+        return { url: v.url, title: String(v.title ?? ""), captcha: !!v.captcha, login: !!v.login, duplicate: !!v.duplicate, antiBot: !!v.antiBot, confirmed: !!v.confirmed, unavailable };
     }
     blockerOf(s) {
         return s.captcha ? "captcha" : s.antiBot ? "anti_bot" : s.duplicate ? "duplicate_application" : s.login ? "login_required" : null;
@@ -213,12 +236,16 @@ export class ApplyBridge {
             return false;
         if (recheck && !(await recheck()))
             return false;
+        // A person may have changed the page or its answers while handling the pause.
+        this.supervisorApproved = false;
         this.blocked = null;
         return true;
     }
     /** After a page change: count it, trace it, and stop for a person when the page needs one. */
     async landed(toolText, known) {
         const state = known ?? (await this.inspect());
+        // A navigation can put the CLI on a materially different form, even on the same origin.
+        this.supervisorApproved = false;
         if (!state)
             return text(toolText);
         this.pages++;
@@ -316,13 +343,21 @@ 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)) {
+            const checkpoint = this.requireSupervisor("browser_click", "fill");
+            if (checkpoint)
+                return checkpoint;
             this.allow("browser_click", "fill");
             const res = await this.browser.callTool("browser_click", forward);
+            if (!res.isError && !fileInput)
+                this.supervisorApproved = false;
             return { content: [{ type: "text", text: textOf(res) }], ...(res.isError ? { isError: true } : {}) };
         }
         return this.refuse("browser_click", "read", `"${t.name || t.role}" is not a control an application run may press. Links, form-step buttons (Next, Upload, Add) and answers are allowed.`);
     }
     async fill(tool, role, forward) {
+        const checkpoint = this.requireSupervisor(tool, "fill");
+        if (checkpoint)
+            return checkpoint;
         const res = await this.browser.callTool(tool, forward);
         if (res.isError)
             return { content: [{ type: "text", text: textOf(res) }], isError: true };
@@ -368,6 +403,9 @@ export class ApplyBridge {
         return { content: [{ type: "text", text: textOf(res) }], ...(res.isError ? { isError: true } : {}) };
     }
     async upload(args) {
+        const checkpoint = this.requireSupervisor("upload_artifact", "fill");
+        if (checkpoint)
+            return checkpoint;
         const kind = args.kind === "resume" || args.kind === "cover_letter" ? args.kind : null;
         if (!kind)
             return this.refuse("upload_artifact", "fill", "kind must be resume or cover_letter.");
@@ -401,6 +439,74 @@ export class ApplyBridge {
             return text("The owner resumed without answering: leave that field empty and continue with the others.");
         return text("The owner answered. Their answer is now part of your sources — quote it as source_quote. Take a browser_snapshot and continue.");
     }
+    /**
+     * The CLI may ask to stop at a named checkpoint, but it cannot smuggle a decision through this
+     * tool. The runner waits for a separately persisted, typed directive and terminal directives are
+     * resolved by the runtime before this call returns.
+     */
+    async supervisorCheckpoint(args) {
+        const checkpointId = typeof args.checkpointId === "string" ? args.checkpointId.trim() : "";
+        if (!/^[A-Za-z0-9_.:-]{1,300}$/.test(checkpointId))
+            return text("supervisor_checkpoint needs a safe checkpointId (letters, numbers, dot, underscore, colon or hyphen).", true);
+        const phase = args.phase === "initial" || args.phase === "post_navigation" || args.phase === "before_submit" || args.phase === "uncertain" ? args.phase : null;
+        if (!phase)
+            return text("supervisor_checkpoint needs phase initial, post_navigation, before_submit or uncertain.", true);
+        const state = await this.inspect();
+        const blockers = new Set();
+        if (state?.captcha)
+            blockers.add("captcha");
+        if (state?.login)
+            blockers.add("login_required");
+        if (state?.antiBot)
+            blockers.add("anti_bot");
+        if (state?.duplicate)
+            blockers.add("duplicate_application");
+        if (this.blocked && ["missing_answer", "screening_ambiguity", "external_redirect", "duplicate_application", "anti_bot", "login_required", "captcha"].includes(this.blocked.reason))
+            blockers.add(this.blocked.reason);
+        const url = state?.url;
+        const domain = url ? hostOf(url) ?? undefined : undefined;
+        const directive = await this.host.supervisorCheckpoint({
+            schemaVersion: 1,
+            checkpointId,
+            facts: {
+                phase,
+                actions: this.actions,
+                filled: this.filled,
+                uploaded: this.uploaded.size,
+                blockers: [...blockers],
+                ...(url ? { url } : {}),
+                ...(domain ? { domain } : {}),
+                ...(state?.title ? { title: state.title.slice(0, 300) } : {}),
+            },
+        });
+        if (directive === "continue") {
+            this.supervisorApproved = true;
+            return text("The persisted supervisor directive is continue. You may continue using only the application bridge tools.");
+        }
+        return text(`The persisted supervisor directive is ${directive}. The runner has ended this application run locally; do not take any further action.`, true);
+    }
+    /**
+     * A terminal result needs the runner's own fresh observation, not the CLI's reading of a page.
+     * The snapshot requirement makes the notice visible to the CLI; the static page probe verifies
+     * its category and current URL before any evidence is retained.
+     */
+    async reportUnavailable(args) {
+        const reason = args.reason === "expired" || args.reason === "unavailable" ? args.reason : null;
+        if (!reason)
+            return text("reason must be expired or unavailable.", true);
+        if (!this.lastSnapshot)
+            return text("Take a fresh browser_snapshot that shows the listing notice before reporting it unavailable.", true);
+        const state = await this.inspect();
+        if (!state?.unavailable)
+            return text("The runner could not verify an expired or unavailable listing notice on the current page. Continue only if the page is still actionable, or take a fresh snapshot.", true);
+        if (state.unavailable !== reason)
+            return text(`The runner verified this listing as ${state.unavailable}, not ${reason}. Report that reason or take a fresh snapshot.`, true);
+        const url = state.url;
+        const domain = hostOf(url) ?? "";
+        this.unavailable = { reason, url, observedAt: new Date(this.host.now()).toISOString(), source: "page_notice" };
+        this.host.emit({ type: "job.unavailable", url, domain, detail: { reason, source: "page_notice" } });
+        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`)
@@ -409,6 +515,9 @@ export class ApplyBridge {
     }
     /** The final Submit. Never under fill_and_review; once, gated and traced, under auto_submit. */
     async submit(forward) {
+        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.");
@@ -439,4 +548,11 @@ export class ApplyBridge {
         this.host.emit({ type: "submit.unconfirmed", ...(after ? { url: after.url } : {}), domain, detail: { gateId: this.host.gateId } });
         return text("The submit was pressed but no confirmation was seen. Do not press it again. Stop now.", true);
     }
+    /** A cloud-persisted checkpoint, not a prompt instruction, authorizes each page's writes. */
+    requireSupervisor(tool, actionClass) {
+        if (this.supervisorApproved)
+            return null;
+        this.host.emit({ type: "policy.decision", detail: { tool, class: actionClass, decision: "refused", reason: "supervisor_checkpoint" } });
+        return text(`A persisted supervisor_checkpoint must return continue before ${actionClass === "submit" ? "the final submit" : "any fill or upload"}. Take a browser_snapshot if needed, then call supervisor_checkpoint.`, true);
+    }
 }

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

@@ -31,6 +31,8 @@ export const LOCAL_APPLY_RUN_PATH = "/local-apply/run";
 export const LOCAL_APPLY_STATUS_PATH = "/local-apply/status";
 export const LOCAL_APPLY_RESUME_PATH = "/local-apply/resume";
 export const LOCAL_APPLY_CANCEL_PATH = "/local-apply/cancel";
+/** Delivers a cloud-persisted supervisory decision to one paused checkpoint. */
+export const LOCAL_APPLY_DIRECTIVE_PATH = "/local-apply/directive";
 export const LOCAL_APPLY_ENGINES = ["claude", "codex"];
 export const LOCAL_APPLY_AUTH_MODES = ["machine", "subscription"];
 export const LOCAL_APPLY_MODES = ["fill_and_review", "auto_submit"];
@@ -43,6 +45,7 @@ export const LOCAL_APPLY_PAUSE_REASONS = [
     "external_redirect",
     "duplicate_application",
     "anti_bot",
+    "supervisor_checkpoint",
 ];
 export const LOCAL_APPLY_BLOCK_REASONS = [
     ...LOCAL_APPLY_PAUSE_REASONS,
@@ -52,7 +55,12 @@ export const LOCAL_APPLY_BLOCK_REASONS = [
     "api_key_refused",
     "source_unavailable",
     "artifact_changed",
+    "job_unavailable",
+    "bridge_unused",
 ];
+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"];
 export const LOCAL_APPLY_EVENT_TYPES = [
     "engine.auth_checked",
     "engine.started",
@@ -67,16 +75,21 @@ export const LOCAL_APPLY_EVENT_TYPES = [
     "submit.attempted",
     "submit.confirmed",
     "submit.unconfirmed",
+    "job.unavailable",
+    "supervisor.checkpoint",
+    "supervisor.directive",
     "run.paused",
     "run.resumed",
     "note",
 ];
 export const LOCAL_APPLY_ENGINE_AUTHS = ["machine-login", "subscription", "api-key", "missing_login", "unknown"];
+export const LOCAL_APPLY_SUPERVISOR_DIRECTIVES = ["continue", "request_review", "stop"];
+export const LOCAL_APPLY_SUPERVISOR_PHASES = ["initial", "before_submit", "post_navigation", "uncertain"];
 export const LOCAL_APPLY_CAPS = { questions: 20, questionChars: 300, answers: 20, answerChars: 2000, summary: 2000 };
 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"]);
+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"]);
 /** A validated event, or null. Detail keeps only whitelisted, primitive, bounded values. */
 export function parseLocalApplyEvent(raw) {
     if (!raw || typeof raw !== "object")
@@ -152,13 +165,45 @@ export function parseLocalApplyResult(raw) {
         out.submitted = { url, at, gateId };
         out.submitAttempted = true;
     }
+    // #975 — accepted ONLY as the closed vocabulary it declares. A runner that sends prose here gets
+    // it dropped rather than stored: the whole point of a structured diagnostic is that no new
+    // free-text channel opens between the machine and the owner's records.
+    const d = o.diagnostic && typeof o.diagnostic === "object" && !Array.isArray(o.diagnostic) ? o.diagnostic : null;
+    const cause = d ? oneOf(LOCAL_APPLY_DIAGNOSTIC_CAUSES, d.cause) : null;
+    if (d && cause) {
+        const count = (v) => (typeof v === "number" && Number.isInteger(v) && v >= 0 && v <= 1_000_000 ? v : 0);
+        out.diagnostic = {
+            cause,
+            bridgeCalls: count(d.bridgeCalls),
+            engineExit: typeof d.engineExit === "number" && Number.isInteger(d.engineExit) && d.engineExit >= -1 && d.engineExit <= 255 ? d.engineExit : 0,
+            activeMs: count(d.activeMs),
+            pages: count(d.pages),
+            filled: count(d.filled),
+            // Deduped from a closed 5-value vocabulary, so it is bounded by the enum itself — no cap needed.
+            signals: [...new Set((Array.isArray(d.signals) ? d.signals : []).filter((x) => LOCAL_APPLY_SIGNALS.includes(x)))],
+        };
+    }
     if (outcome === "blocked") {
         out.blockReason = oneOf(LOCAL_APPLY_BLOCK_REASONS, o.blockReason) ?? "incomplete";
         out.questions = (Array.isArray(o.questions) ? o.questions : [])
             .filter((q) => typeof q === "string" && q.trim() !== "")
             .slice(0, LOCAL_APPLY_CAPS.questions)
             .map((q) => q.trim().slice(0, LOCAL_APPLY_CAPS.questionChars));
+        if (out.blockReason === "job_unavailable") {
+            const evidence = (o.unavailable && typeof o.unavailable === "object" && !Array.isArray(o.unavailable) ? o.unavailable : {});
+            const reason = oneOf(LOCAL_APPLY_UNAVAILABLE_REASONS, evidence.reason);
+            const url = str(evidence.url, 2000);
+            const observedAt = str(evidence.observedAt, 40);
+            if (!reason || !url || !isHttpUrl(url) || !observedAt || Number.isNaN(Date.parse(observedAt)) || evidence.source !== "page_notice") {
+                return { error: "a job_unavailable result needs runner-verified unavailable evidence (reason, url, observedAt, source)" };
+            }
+            out.unavailable = { reason, url, observedAt, source: "page_notice" };
+        }
+        else if (o.unavailable !== undefined)
+            return { error: "unavailable evidence is only valid for a job_unavailable result" };
     }
+    else if (o.unavailable !== undefined)
+        return { error: "unavailable evidence is only valid for a job_unavailable result" };
     if (outcome === "failed")
         out.error = str(o.error, 1000) ?? "The run failed without a reason.";
     return { result: out };

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

@@ -40,10 +40,12 @@ export function applyPrompt(e, sources) {
         ...sources.map((s) => `<source name="${s.label}">\n${s.text}\n</source>\n`),
         "How to work:",
         `- Your only tools are from the ${BRIDGE_SERVER_NAME} server. Open the application page with ${t("browser_navigate")}, read it with ${t("browser_snapshot")}, and act on elements by their ref.`,
+        `- Before any fill, upload, form-step click, or final submit, call ${t("supervisor_checkpoint")} and wait for its persisted continue directive. Call it after the initial snapshot (phase initial), after every page-changing move (phase post_navigation), and immediately before a final submit (phase before_submit). Use a stable safe checkpointId for each point. A page change clears the previous approval; request_review and stop end the run locally.`,
         `- Every answer — ${t("browser_type")}, ${t("browser_select_option")}, or a click on a checkbox, radio or option — must carry source_quote: the exact text from a source above that the value comes from. Type values exactly as the source writes them.`,
         `- If a question has no answer in the sources, or is ambiguous, call ${t("request_answer")}. Never guess, never invent, never pick a "safe" default.`,
         `- To attach a document, click the field's upload control, then call ${t("upload_artifact")} with kind resume or cover_letter.`,
         "- Never sign in, solve a captcha, accept terms or work around any block; the run pauses for the owner by itself.",
+        `- If a fresh snapshot shows the job itself is expired, closed or unavailable, call ${t("report_job_unavailable")} with reason expired or unavailable. The runner will independently verify the page notice; do not report it from inference alone.`,
         `- Stay on the application's site. Limits: ${e.limits.maxPages} pages, ${e.limits.maxActions} browser actions, ${e.limits.maxMinutes} minutes.`,
         finish,
     ].join("\n");

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

@@ -147,6 +147,23 @@ export function verifyArtifact(workspace, home, a) {
         return { error: `The approved ${label} at ${a.path} could not be read.` };
     }
 }
+/**
+ * What to tell the owner when the CLI put nothing on the page (#975) — built from the diagnostic's
+ * own ids, so the advice follows the observation rather than guessing at it.
+ */
+function bridgeUnusedHelp(engine, d) {
+    if (d.signals.includes("approval_policy_blocked"))
+        return `The ${engine} CLI would not use the browser tools because its own approval policy refused them. Allow the PAGS bridge toolset for this session, then retry.`;
+    if (d.signals.includes("bridge_tools_missing"))
+        return `The ${engine} CLI never saw the browser tools. Update the CLI (npm i -g @proagentstore/cli), run \`pags up\` again, then retry.`;
+    if (d.signals.includes("auth_prompt"))
+        return `The ${engine} CLI stopped on a sign-in prompt before opening the page. Sign it in on this machine, then retry.`;
+    if (d.signals.includes("no_output"))
+        return `The ${engine} CLI produced no output at all before exiting. Check that it runs on this machine, then retry.`;
+    if (d.signals.includes("engine_refused_task"))
+        return `The ${engine} CLI declined the task and never opened the page. Its own closing message is on this run's summary.`;
+    return `The ${engine} CLI ran for ${Math.round(d.activeMs / 1000)}s and exited (code ${d.engineExit}) without opening the application page — no navigation, no checkpoint, no fill. Nothing was submitted. Retry, or run the CLI by hand on this machine to see why it stops.`;
+}
 export class LocalApplyRuntime {
     deps;
     runs = new Map();
@@ -194,6 +211,7 @@ export class LocalApplyRuntime {
             engineAuth: "unknown",
             cancelled: false,
             timedOut: false,
+            checkpoints: new Map(),
         };
         this.runs.set(envelope.runId, run);
         void this.launch(run, selfUrl).catch((err) => {
@@ -252,6 +270,7 @@ export class LocalApplyRuntime {
         run.bridge = new ApplyBridge(run.browser.tools, {
             emit: (ev) => this.emit(run, ev),
             pause: (p) => this.pause(run, p),
+            supervisorCheckpoint: (checkpointId) => this.supervisorCheckpoint(run, checkpointId),
             isAllowed: (host) => [...run.allow].some((d) => domainWithin(host, d)),
             grounding: () => run.grounding.join("\n"),
             artifactPath: (kind) => {
@@ -302,6 +321,42 @@ export class LocalApplyRuntime {
         }, 5_000);
         run.timer.unref?.();
     }
+    /**
+     * What the runner OBSERVED about its own CLI (#975), as ids this platform defines.
+     *
+     * Matched against the engine's structured output on the machine; only the matching signal's ID
+     * crosses the contract, never the line that matched it. That is what makes a diagnostic safe to
+     * persist: a CLI prints the owner's résumé prose and their typed answers while it works, and no
+     * redaction can reliably tell those from the rest of its chatter.
+     */
+    signalsOf(run) {
+        const text = run.output.join("\n");
+        const out = [];
+        if (!text.trim())
+            out.push("no_output");
+        // #952's live failure, invisible from the cloud and fixable by configuration.
+        if (/approval policy is\s*[`'"]?never|requires? approval|permission denied for tool|not allowed to use/i.test(text))
+            out.push("approval_policy_blocked");
+        if (/browser_navigate.{0,40}(not found|unknown tool|unavailable)|no such tool|tool .{0,40}is not available/i.test(text))
+            out.push("bridge_tools_missing");
+        if (missingLogin(run.envelope.engine, text))
+            out.push("auth_prompt");
+        if (/\b(i (cannot|can't|won't)|unable to) (help|assist|complete|do that|proceed)/i.test(text))
+            out.push("engine_refused_task");
+        return [...new Set(out)];
+    }
+    /** The bounded, closed-vocabulary diagnostic for a run that put nothing on the page (#975). */
+    diagnosticOf(run, code, cause) {
+        return {
+            cause,
+            bridgeCalls: run.bridge?.actions ?? 0,
+            engineExit: Number.isInteger(code) && code >= -1 && code <= 255 ? code : 0,
+            activeMs: this.activeMs(run),
+            pages: run.bridge?.pages ?? 0,
+            filled: run.bridge?.filled ?? 0,
+            signals: this.signalsOf(run),
+        };
+    }
     /** What the run amounts to when the CLI exits — decided by what the bridge did, not what the CLI says. */
     outcomeOf(run, code) {
         const e = run.envelope;
@@ -311,6 +366,8 @@ export class LocalApplyRuntime {
             return { outcome: "failed", summary, error: "Cancelled by the owner" };
         if (b?.submitted)
             return { outcome: "submitted", summary, submitted: b.submitted };
+        if (b?.unavailable)
+            return { outcome: "blocked", summary, blockReason: "job_unavailable", unavailable: b.unavailable };
         if (b?.submitAttempted)
             return { outcome: "blocked", summary, blockReason: "submit_unconfirmed", questions: b.blocked?.questions ?? [] };
         if (b?.reviewReady)
@@ -319,10 +376,26 @@ export class LocalApplyRuntime {
             return { outcome: "blocked", summary, blockReason: "engine_not_signed_in", questions: [signInHelp(e.engine)], engineAuth: "missing_login" };
         if (b?.blocked)
             return { outcome: "blocked", summary, blockReason: b.blocked.reason, questions: b.blocked.questions };
-        if (run.timedOut)
-            return { outcome: "blocked", summary, blockReason: "incomplete", questions: [`Stopped at the ${e.limits.maxMinutes}-minute limit before the form was ready for review.`] };
+        if (run.timedOut) {
+            return { outcome: "blocked", summary, blockReason: "incomplete", questions: [`Stopped at the ${e.limits.maxMinutes}-minute limit before the form was ready for review.`], diagnostic: this.diagnosticOf(run, code, "timed_out") };
+        }
+        // #975: a CLI that never called the bridge did NOTHING on the page, which is a different
+        // failure from stopping partway — different cause, different fix — and saying `incomplete`
+        // for both left the owner with a 51-second run they could not explain. The diagnostic says
+        // how long it ran, how many bridge calls it made (0) and what the runner saw it print.
+        const calls = b?.actions ?? 0;
+        if (calls === 0) {
+            const diagnostic = this.diagnosticOf(run, code, !run.output.join("").trim() ? "no_engine_output" : code !== 0 ? "engine_exited_nonzero" : "bridge_unused");
+            return { outcome: "blocked", summary, blockReason: "bridge_unused", questions: [bridgeUnusedHelp(e.engine, diagnostic)], diagnostic };
+        }
         const tail = code !== 0 ? ` (the ${e.engine} CLI exited with code ${code})` : "";
-        return { outcome: "blocked", summary, blockReason: "incomplete", questions: [`The CLI stopped before marking the form ready for review${tail}. Review the form yourself, or retry.`] };
+        return {
+            outcome: "blocked",
+            summary,
+            blockReason: "incomplete",
+            questions: [`The CLI stopped before marking the form ready for review${tail}. Review the form yourself, or retry.`],
+            diagnostic: this.diagnosticOf(run, code, code !== 0 ? "engine_exited_nonzero" : "bridge_unused"),
+        };
     }
     activeMs(run) {
         return run.activeMs + (run.state === "running" ? this.now() - run.activeSince : 0);
@@ -343,6 +416,31 @@ export class LocalApplyRuntime {
         }
         return new Promise((done) => run.waiters.push(done));
     }
+    /**
+     * Wait for a cloud-brain decision without accepting a model's prose as permission. A directive
+     * can be stored before this call reaches its pause (the delivery race), but a normal `resume`
+     * can never release this pause.
+     */
+    supervisorCheckpoint(run, supervisor) {
+        const { checkpointId } = supervisor;
+        let checkpoint = run.checkpoints.get(checkpointId);
+        if (!checkpoint) {
+            checkpoint = {};
+            run.checkpoints.set(checkpointId, checkpoint);
+        }
+        if (!checkpoint.checkpoint) {
+            checkpoint.checkpoint = supervisor;
+            this.emit(run, {
+                type: "supervisor.checkpoint",
+                ...(supervisor.facts.url ? { url: supervisor.facts.url } : {}),
+                ...(supervisor.facts.domain ? { domain: supervisor.facts.domain } : {}),
+                detail: { checkpointId, phase: supervisor.facts.phase, actions: supervisor.facts.actions, filled: supervisor.facts.filled, uploaded: supervisor.facts.uploaded },
+            });
+        }
+        if (checkpoint.directive)
+            return Promise.resolve(checkpoint.directive);
+        return this.pause(run, { reason: "supervisor_checkpoint", checkpoint: supervisor }).then(() => run.checkpoints.get(checkpointId)?.directive ?? "stop");
+    }
     release(run, outcome) {
         if (run.state === "paused") {
             run.state = "running";
@@ -360,6 +458,8 @@ export class LocalApplyRuntime {
         const run = this.get(String(o.runId ?? ""));
         if (run.state === "ended")
             throw new RunnerInputError("The run has ended", 409);
+        if (run.pause?.reason === "supervisor_checkpoint")
+            throw new RunnerInputError("This run is waiting for a persisted supervisor directive, not an owner resume", 409);
         for (const a of (Array.isArray(o.answers) ? o.answers : []).slice(0, LOCAL_APPLY_CAPS.answers)) {
             const r = (a && typeof a === "object" ? a : {});
             if (typeof r.question === "string" && typeof r.answer === "string" && r.answer.trim())
@@ -370,6 +470,41 @@ export class LocalApplyRuntime {
         this.release(run, "resumed");
         return this.status({ runId: run.envelope.runId, afterSeq: run.seq });
     }
+    /**
+     * Store then apply an immutable cloud directive. The caller persists it before this runner
+     * endpoint is reached; this in-process record makes delivery idempotent and closes the race
+     * where a directive arrives just before the bridge begins waiting.
+     */
+    directive(raw) {
+        const o = (raw && typeof raw === "object" ? raw : {});
+        const run = this.get(typeof o.runId === "string" ? o.runId : "");
+        const checkpointId = typeof o.checkpointId === "string" && SAFE_ID.test(o.checkpointId) ? o.checkpointId : null;
+        const directive = o.directive === "continue" || o.directive === "request_review" || o.directive === "stop" ? o.directive : null;
+        if (o.schemaVersion !== 1 || !checkpointId || !directive)
+            throw new RunnerInputError("directive needs schemaVersion: 1, a safe checkpointId, and directive continue, request_review or stop");
+        if (run.state === "ended")
+            throw new RunnerInputError("The run has ended", 409);
+        let checkpoint = run.checkpoints.get(checkpointId);
+        if (checkpoint?.directive) {
+            if (checkpoint.directive !== directive)
+                throw new RunnerInputError("A different directive is already recorded for this checkpoint", 409);
+            return this.status({ runId: run.envelope.runId, afterSeq: run.seq });
+        }
+        checkpoint ??= {};
+        checkpoint.directive = directive;
+        run.checkpoints.set(checkpointId, checkpoint);
+        this.emit(run, { type: "supervisor.directive", detail: { checkpointId, directive } });
+        const waitingForThis = run.state === "paused" && run.pause?.reason === "supervisor_checkpoint" && run.pause.checkpoint?.checkpointId === checkpointId;
+        if (waitingForThis && directive === "continue")
+            this.release(run, "resumed");
+        else if (waitingForThis && directive === "request_review") {
+            this.end(run, { outcome: "awaiting_review", summary: "The supervisor requested an owner review." });
+        }
+        else if (waitingForThis && directive === "stop") {
+            this.end(run, { outcome: "blocked", blockReason: "incomplete", questions: ["The supervisor stopped this run before it could continue."] });
+        }
+        return this.status({ runId: run.envelope.runId, afterSeq: run.seq });
+    }
     cancel(raw) {
         const runId = String(raw?.runId ?? "");
         const run = this.get(runId);
@@ -456,8 +591,11 @@ export class LocalApplyRuntime {
             submitAttempted: b?.submitAttempted ?? false,
             summary: redactText((r.summary ?? "").slice(0, LOCAL_APPLY_CAPS.summary), run.secrets),
             ...(r.outcome === "submitted" && r.submitted ? { submitted: r.submitted } : {}),
-            ...(r.outcome === "blocked" ? { blockReason: r.blockReason ?? "incomplete", questions: (r.questions ?? []).map((q) => redactText(q, run.secrets)) } : {}),
+            ...(r.outcome === "blocked" ? { blockReason: r.blockReason ?? "incomplete", questions: (r.questions ?? []).map((q) => redactText(q, run.secrets)), ...(r.blockReason === "job_unavailable" && r.unavailable ? { unavailable: r.unavailable } : {}) } : {}),
             ...(r.outcome === "failed" ? { error: redactText((r.error ?? "The run failed without a reason.").slice(0, 1000), run.secrets) } : {}),
+            // #975 — carried through as the closed vocabulary it is. Nothing here is redacted because
+            // nothing here is text: counts, an exit code, and signal ids this platform defines.
+            ...(r.diagnostic ? { diagnostic: r.diagnostic } : {}),
         };
         if (run.child && run.child.exitCode === null)
             this.kill(run);

package/dist/browser-runner/server.js

@@ -201,6 +201,9 @@ async function route(runner, req, res) {
     if (req.method === "POST" && path === "/local-apply/resume") {
         return json(res, 200, runner.localApply.resume(await readJson(req)));
     }
+    if (req.method === "POST" && path === "/local-apply/directive") {
+        return json(res, 200, runner.localApply.directive(await readJson(req)));
+    }
     if (req.method === "POST" && path === "/local-apply/cancel") {
         return json(res, 200, runner.localApply.cancel(await readJson(req)));
     }

package/package.json

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