@proagentstore/cli 0.4.89 → 0.4.91

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

@@ -63,7 +63,7 @@ export function confirmationMarker(before, after) {
     if (after.confirmed)
         return "page_text";
     const url = urlPathAndQuery(after.url).toLowerCase();
-    if (CONFIRMATION_URL_RE.test(url) && !!before && urlPathAndQuery(before.url).toLowerCase() !== url)
+    if (CONFIRMATION_URL_RE.test(url) && before && urlPathAndQuery(before.url).toLowerCase() !== url)
         return "url_receipt";
     // The site's own duplicate notice, but ONLY if it appeared after this click: "you have already
     // applied" that was on the page beforehand is an earlier application of the owner's, and

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";
+/** Read-only job-page check used before an email lead may enter material preparation. */
+export const LOCAL_APPLY_PREFLIGHT_PATH = "/local-apply/preflight";
 /** 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"];
@@ -82,13 +84,12 @@ export const LOCAL_APPLY_BLOCK_REASONS = [
  * dispatch, naming the update, rather than silently producing the older behaviour (`apply.ts`
  * `runnerContractProblem`).
  *
- * ── Why it moved to 0.4.89 (#994)
+ * ── Why it moved to 0.4.90 (#953)
  *
- * #994 makes a post-click confirmation observable and recognises SEEK's "application sent"
- * receipt wording. It also carries only closed-vocabulary evidence when a pressed submit remains
- * unconfirmed. Those changes live in `packages/browser-runner`, which ships INSIDE the published
- * CLI. A machine below this floor cannot provide that evidence, so it must not silently look
- * equivalent to a current runner.
+ * #953 adds the read-only `/local-apply/preflight` route used before an email lead can enter
+ * tailoring. That route lives in `packages/browser-runner`, which ships INSIDE the published CLI.
+ * A machine below this floor cannot make the live/expired/unverifiable observation, so it must
+ * not silently look equivalent to a current runner.
  *
  * 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 observe a post-submit receipt is refused
@@ -99,7 +100,7 @@ export const LOCAL_APPLY_BLOCK_REASONS = [
  * 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.89";
+export const LOCAL_APPLY_CONTRACT_MIN_CLI = "0.4.90";
 export const LOCAL_APPLY_DIAGNOSTIC_CAUSES = ["bridge_unused", "engine_exited_nonzero", "timed_out", "no_engine_output", "submit_unconfirmed"];
 export const LOCAL_APPLY_CONFIRMATION_MARKERS = ["page_text", "url_receipt", "already_applied_notice"];
 export const LOCAL_APPLY_SIGNALS = [

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

@@ -15,12 +15,13 @@
  *  - the result: `awaiting_review`, `submitted` (only with the site's confirmation), `blocked`
  *    with the reason, or `failed`.
  *
- * Runs live in memory: a runner restart loses them, and `status` answers 404, which PAGS reads as
- * "the runner lost this run".
+ * Active runs live in memory: a runner restart loses them, and `status` answers 404, which PAGS
+ * reads as "the runner lost this run". Terminal typed/redacted results are journaled locally so a
+ * restart after completion does not erase observed evidence before PAGS pulls it.
  */
 import { spawn as nodeSpawn } from "node:child_process";
 import { createHash, randomBytes } from "node:crypto";
-import { existsSync, mkdirSync, readFileSync, readdirSync, realpathSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, readdirSync, realpathSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { join, resolve, sep } from "node:path";
 import { fileURLToPath } from "node:url";
@@ -34,7 +35,7 @@ import { finalText, missingLogin, signInHelp } from "../local-browser/engine.js"
 import { resolveWorkspacePath } from "../local-browser/runtime.js";
 import { ApplyBridge } from "./bridge.js";
 import { confirmationSignals } from "./confirmation.js";
-import { LOCAL_APPLY_AUTH_MODES, LOCAL_APPLY_CAPS, LOCAL_APPLY_ENGINES, LOCAL_APPLY_MODES, LOCAL_APPLY_TASK_TYPE, } from "./contract.js";
+import { LOCAL_APPLY_AUTH_MODES, LOCAL_APPLY_CAPS, LOCAL_APPLY_ENGINES, LOCAL_APPLY_MODES, LOCAL_APPLY_TASK_TYPE, parseLocalApplyResult, } from "./contract.js";
 import { applyPrompt, buildApplyEngineSpec, observedApplyAuth } from "./engine.js";
 const MAX_EVENTS = 1000;
 const OUTPUT_LINES = 400;
@@ -182,6 +183,104 @@ export class LocalApplyRuntime {
         this.now = deps.now ?? Date.now;
         this.spawn = deps.spawn ?? nodeSpawn;
         this.retentionMs = deps.retentionMs ?? 24 * 60 * 60 * 1000;
+        this.hydrateTerminalJournals();
+    }
+    /**
+     * Read a specific job page before an email alert can cause any materials to be generated.
+     * This deliberately creates no application run, launches no CLI, and never clicks/fills: the
+     * only evidence it returns is a closed, redacted vocabulary the API can durably record.
+     */
+    async preflight(raw) {
+        const input = raw && typeof raw === "object" ? raw : {};
+        const jobUrl = typeof input.jobUrl === "string" ? input.jobUrl.trim() : "";
+        let parsed;
+        try {
+            parsed = new URL(jobUrl);
+            if (parsed.protocol !== "http:" && parsed.protocol !== "https:")
+                throw new Error("scheme");
+        }
+        catch {
+            return { state: "unverifiable", jobUrl, reason: "navigation_failed" };
+        }
+        const profile = input.browserProfile === "default" ? "default" : "isolated";
+        const dir = join(this.root, "preflight", randomBytes(12).toString("hex"));
+        let browser = null;
+        try {
+            browser = await this.deps.browserFor(profile, dir);
+            const navigated = await browser.tools.callTool("browser_navigate", { url: parsed.toString() });
+            if (navigated.isError)
+                return { state: "unverifiable", jobUrl: parsed.toString(), reason: "navigation_failed" };
+            const snapshot = await browser.tools.callTool("browser_snapshot");
+            const page = (snapshot.content ?? []).map((part) => part.text ?? "").join("\n");
+            if (snapshot.isError || /captcha|verify (?:you(?:'| a)re|that you are) human|access denied|unusual traffic|checking (?:if )?your browser/i.test(page)) {
+                return { state: "unverifiable", jobUrl: parsed.toString(), reason: "access_blocked" };
+            }
+            if (/(?: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)/i.test(page)) {
+                return { state: "unavailable", jobUrl: parsed.toString(), reason: /expired/i.test(page) ? "expired" : "unavailable" };
+            }
+            // An accessible Apply control is an active path, unlike a generic careers/search URL.
+            if (/(?:button|link)\s+"[^"]{0,80}\bapply(?: now| for| here)?\b|\bapply (?:now|for (?:this )?(?:job|role|position))\b|\bstart application\b/i.test(page)) {
+                return { state: "live", jobUrl: parsed.toString(), applyUrl: parsed.toString(), evidence: "apply_control_present" };
+            }
+            return { state: "unverifiable", jobUrl: parsed.toString(), reason: "no_active_apply_path" };
+        }
+        catch {
+            return { state: "unverifiable", jobUrl: parsed.toString(), reason: "navigation_failed" };
+        }
+        finally {
+            await browser?.stop().catch(() => undefined);
+        }
+    }
+    journalPath(dir) {
+        return join(dir, "terminal-result.json");
+    }
+    /** Write-before-return: a terminal result is durable before `status` can expose it. */
+    persistTerminal(run) {
+        if (!run.result || !run.endedAt)
+            return;
+        const journal = { version: 1, envelope: run.envelope, events: run.events, seq: run.seq, result: run.result, endedAt: run.endedAt };
+        const path = this.journalPath(run.dir);
+        const tmp = `${path}.${randomBytes(8).toString("hex")}.tmp`;
+        writeFileSync(tmp, JSON.stringify(journal), { mode: 0o600 });
+        renameSync(tmp, path);
+    }
+    /** Hydrate terminal-only records. Interrupted runs remain deliberately unrecoverable. */
+    hydrateTerminalJournals() {
+        if (!existsSync(this.root))
+            return;
+        for (const instance of readdirSync(this.root)) {
+            const instanceDir = join(this.root, instance);
+            let runIds;
+            try {
+                runIds = readdirSync(instanceDir);
+            }
+            catch {
+                continue;
+            }
+            for (const runId of runIds) {
+                const dir = join(instanceDir, runId);
+                const path = this.journalPath(dir);
+                if (!existsSync(path))
+                    continue;
+                try {
+                    const raw = JSON.parse(readFileSync(path, "utf8"));
+                    if (raw.version !== 1 || !raw.envelope || !raw.result || !Array.isArray(raw.events) || typeof raw.seq !== "number" || typeof raw.endedAt !== "number")
+                        continue;
+                    const envelope = parseApplyEnvelope(raw.envelope);
+                    const parsed = parseLocalApplyResult(raw.result);
+                    if ("error" in parsed || parsed.result.runId !== envelope.runId)
+                        continue;
+                    const checked = parsed.result;
+                    this.runs.set(envelope.runId, {
+                        envelope, dir, token: "", state: "ended", events: raw.events, seq: raw.seq,
+                        result: checked, allow: new Set(envelope.policy.allowDomains), grounding: [], secrets: [], activeSince: raw.endedAt,
+                        activeMs: 0, waiters: [], output: [], engineAuth: checked.engineAuth, cancelled: false, timedOut: false,
+                        checkpoints: new Map(), endedAt: raw.endedAt,
+                    });
+                }
+                catch { /* a corrupt local cache is never an authority */ }
+            }
+        }
     }
     start(raw) {
         const envelope = parseApplyEnvelope(raw);
@@ -614,6 +713,9 @@ export class LocalApplyRuntime {
             // nothing here is text: counts, an exit code, and signal ids this platform defines.
             ...(r.diagnostic ? { diagnostic: r.diagnostic } : {}),
         };
+        // This must happen before stopping the browser or exposing `ended`: a process restart in the
+        // narrow handoff window must not turn an observed result into `runner_lost` in the cloud.
+        this.persistTerminal(run);
         if (run.child && run.child.exitCode === null)
             this.kill(run);
         void run.browser?.stop().catch(() => undefined);

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

@@ -32,6 +32,7 @@ export const LOCAL_ARTIFACT_BLOCK_REASONS = [
     "workspace_unavailable",
     "missing_information",
     "uncertain_claim",
+    "invalid_cli_output",
     "engine_not_signed_in",
     "api_key_refused",
 ];
@@ -48,6 +49,7 @@ export const LOCAL_ARTIFACT_EVENT_TYPES = [
     "note",
 ];
 export const LOCAL_ARTIFACT_ENGINE_AUTHS = ["machine-login", "subscription", "api-key", "missing_login", "unknown"];
+export const LOCAL_ARTIFACT_PARSE_ATTEMPTS = ["fenced_json", "balanced_object"];
 export const LOCAL_ARTIFACT_CAPS = { questions: 20, questionChars: 300, sources: 6, sourceBytes: 256 * 1024 };
 /** An id used as a folder name: no separators, no dots, nothing a path could be built out of. */
 export const PATH_SEGMENT = /^[A-Za-z0-9_-]{1,100}$/;
@@ -88,6 +90,7 @@ export function parseLocalArtifactLead(raw) {
     const leadUrl = str(o.leadUrl, 2000) ?? "";
     if (leadUrl && !/^https?:\/\/[^\s/]+/i.test(leadUrl))
         return { error: "the lead's URL is not an http(s) URL" };
+    const workKey = str(o.workKey, 600);
     const requestedAt = str(o.requestedAt, 40);
     if (!requestedAt || Number.isNaN(Date.parse(requestedAt)))
         return { error: "the lead has no requestedAt time" };
@@ -101,9 +104,9 @@ export function parseLocalArtifactLead(raw) {
         if (v)
             lead[f] = v;
     }
-    return { lead: { eventId, sourceInstanceId, leadId, leadUrl, lifecycleVersion, requestedAt, lead } };
+    return { lead: { eventId, sourceInstanceId, leadId, leadUrl, ...(workKey ? { workKey } : {}), lifecycleVersion, requestedAt, lead } };
 }
-const DETAIL_KEYS = new Set(["engine", "authMode", "engineAuth", "role", "path", "sha256", "bytes", "kind", "total", "unmatched", "reason", "exitCode", "count", "removed", "status"]);
+const DETAIL_KEYS = new Set(["engine", "authMode", "engineAuth", "role", "path", "sha256", "bytes", "kind", "total", "unmatched", "reason", "exitCode", "count", "removed", "status", "validationError", "parseAttempts", "rawOutputChars", "runId", "attemptNumber"]);
 /** A validated event, or null. Detail keeps only whitelisted, primitive, bounded values. */
 export function parseLocalArtifactEvent(raw) {
     if (!raw || typeof raw !== "object")
@@ -181,6 +184,25 @@ export function parseLocalArtifactResult(raw) {
             .filter((q) => typeof q === "string" && q.trim() !== "")
             .slice(0, LOCAL_ARTIFACT_CAPS.questions)
             .map((q) => q.trim().slice(0, LOCAL_ARTIFACT_CAPS.questionChars));
+        const diagnostic = o.diagnostic && typeof o.diagnostic === "object" ? o.diagnostic : null;
+        const validationError = diagnostic?.validationError;
+        if (diagnostic && (validationError === "no_json_object" || validationError === "invalid_json" || validationError === "not_draft_object" || validationError === "incomplete_draft" || validationError === "unverified_claim")) {
+            const parseAttempts = [];
+            if (Array.isArray(diagnostic.parseAttempts)) {
+                for (let index = 0; index < diagnostic.parseAttempts.length && index < 8; index += 1) {
+                    const parseAttempt = oneOf(LOCAL_ARTIFACT_PARSE_ATTEMPTS, diagnostic.parseAttempts[index]);
+                    if (parseAttempt && !parseAttempts.includes(parseAttempt))
+                        parseAttempts.push(parseAttempt);
+                }
+            }
+            out.diagnostic = {
+                validationError,
+                parseAttempts,
+                rawOutputChars: typeof diagnostic.rawOutputChars === "number" ? Math.max(0, Math.min(diagnostic.rawOutputChars, 200_000)) : 0,
+                runId: str(diagnostic.runId, 100) ?? runId,
+                attemptNumber: typeof diagnostic.attemptNumber === "number" && Number.isInteger(diagnostic.attemptNumber) && diagnostic.attemptNumber > 0 ? diagnostic.attemptNumber : 1,
+            };
+        }
     }
     if (outcome === "failed")
         out.error = str(o.error, 1000) ?? "The run failed without a reason.";

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

@@ -19,8 +19,8 @@
  */
 import { mergeEnv } from "../coding/engine-env.js";
 import { resolveEngineAuth } from "../coding/engine-auth.js";
-import { finalText, missingLogin } from "../local-browser/engine.js";
-export { finalText, missingLogin };
+import { finalText as finalTextFromEngine, missingLogin } from "../local-browser/engine.js";
+export { missingLogin };
 const PROVIDER_KEYS = ["ANTHROPIC_API_KEY", "OPENAI_API_KEY"];
 const SUBSCRIPTION_TOKEN = "CLAUDE_CODE_OAUTH_TOKEN";
 /** The engine's environment: the machine's, never with a provider API key. */
@@ -84,19 +84,64 @@ export function tailorPrompt(lead, sources) {
         '{"status":"ready","resume_markdown":"…","cover_letter_markdown":"…","claims":[{"text":"…","source":"resume","quote":"…"}]}',
     ].join("\n");
 }
-/** The CLI's answer: the first JSON object in its final text, fences and prose around it ignored. */
-export function parseDraft(text) {
-    const start = text.indexOf("{");
-    const end = text.lastIndexOf("}");
-    if (start < 0 || end <= start)
-        return null;
-    try {
-        const v = JSON.parse(text.slice(start, end + 1));
-        return v && typeof v === "object" && !Array.isArray(v) ? v : null;
+/** JSON objects from fenced blocks or prose, while respecting braces inside JSON strings. */
+function jsonCandidates(text) {
+    const candidates = [];
+    for (const match of text.matchAll(/```(?:json)?\s*([\s\S]*?)```/gi))
+        candidates.push({ source: "fenced_json", text: match[1].trim() });
+    for (let start = 0; start < text.length; start++) {
+        if (text[start] !== "{")
+            continue;
+        let quoted = false, escaped = false, depth = 0;
+        for (let end = start; end < text.length; end++) {
+            const ch = text[end];
+            if (quoted) {
+                if (escaped)
+                    escaped = false;
+                else if (ch === "\\")
+                    escaped = true;
+                else if (ch === '"')
+                    quoted = false;
+                continue;
+            }
+            if (ch === '"')
+                quoted = true;
+            else if (ch === "{")
+                depth++;
+            else if (ch === "}" && --depth === 0) {
+                candidates.push({ source: "balanced_object", text: text.slice(start, end + 1) });
+                break;
+            }
+        }
     }
-    catch {
-        return null;
+    return candidates;
+}
+/** Prefer the structured closing message, but tolerate a CLI that printed a JSON object directly.
+ * Non-JSON output must stay empty so login and process-failure handling remains fail-closed. */
+export function finalText(engine, lines) {
+    const structured = finalTextFromEngine(engine, lines);
+    if (structured)
+        return structured;
+    const raw = lines.join("\n");
+    return jsonCandidates(raw).length ? raw : "";
+}
+/** The CLI's answer, with a closed diagnostic instead of a generic parsing collapse. */
+export function parseDraft(text) {
+    const candidates = jsonCandidates(text);
+    if (!candidates.length)
+        return { draft: null, validationError: "no_json_object", parseAttempts: ["fenced_json", "balanced_object"] };
+    let invalid = false;
+    for (const candidate of candidates) {
+        try {
+            const parsed = JSON.parse(candidate.text);
+            if (parsed && typeof parsed === "object" && !Array.isArray(parsed) && "status" in parsed)
+                return { draft: parsed, parseAttempts: [candidate.source] };
+        }
+        catch {
+            invalid = true;
+        }
     }
+    return { draft: null, validationError: invalid ? "invalid_json" : "not_draft_object", parseAttempts: [...new Set(candidates.map((c) => c.source))] };
 }
 /** Case, whitespace, quote-style and dash-style insensitive — so a faithful quote is never failed on typography. */
 export function normalize(s) {
@@ -117,18 +162,19 @@ const digits = (s) => s.replace(/\D/g, "");
  * Check the CLI's draft against the sources. Questions name WHAT to confirm, bounded, and are
  * returned only to the owner's own record — never to a trace.
  */
-export function checkDraft(draft, sources) {
+export function checkDraft(parsed, sources) {
+    const draft = parsed.draft;
     if (!draft)
-        return { ok: false, reason: "uncertain_claim", questions: ["The CLI did not return a readable draft. Run it again, or check the source files."], claims: 0, unmatched: 0 };
+        return { ok: false, reason: "invalid_cli_output", questions: [`The CLI did not return a readable application JSON object (${parsed.validationError ?? "unknown"}). Retry tailoring after checking the CLI output format.`], claims: 0, unmatched: 0, validationError: parsed.validationError ?? "no_json_object", parseAttempts: parsed.parseAttempts };
     if (draft.status === "needs_human") {
         const qs = (Array.isArray(draft.questions) ? draft.questions : []).filter((q) => typeof q === "string" && q.trim() !== "").map((q) => q.trim());
-        return { ok: false, reason: "missing_information", questions: qs.length ? qs : ["The CLI needs more information but did not say what."], claims: 0, unmatched: 0 };
+        return { ok: false, reason: "missing_information", questions: qs.length ? qs : ["The CLI needs more information but did not say what."], claims: 0, unmatched: 0, validationError: "incomplete_draft", parseAttempts: parsed.parseAttempts };
     }
     const resume = typeof draft.resume_markdown === "string" ? draft.resume_markdown.trim() : "";
     const coverLetter = typeof draft.cover_letter_markdown === "string" ? draft.cover_letter_markdown.trim() : "";
     const claims = Array.isArray(draft.claims) ? draft.claims : [];
     if (draft.status !== "ready" || !resume || !coverLetter || !claims.length) {
-        return { ok: false, reason: "uncertain_claim", questions: ["The draft was incomplete (missing a document or its source citations). Run it again."], claims: claims.length, unmatched: 0 };
+        return { ok: false, reason: "invalid_cli_output", questions: ["The CLI JSON was incomplete (missing a document or its source citations). Run it again."], claims: claims.length, unmatched: 0, validationError: "incomplete_draft", parseAttempts: parsed.parseAttempts };
     }
     const byRole = new Map(sources.map((s) => [s.role, normalize(s.text)]));
     const all = normalize(sources.map((s) => s.text).join("\n"));
@@ -161,6 +207,6 @@ export function checkDraft(draft, sources) {
         if (digits(p).length >= 9 && !sourceDigits.includes(digits(p)))
             flag("Confirm the phone number in the draft — it does not appear in your sources.");
     if (unmatched)
-        return { ok: false, reason: "uncertain_claim", questions, claims: claims.length, unmatched };
+        return { ok: false, reason: "uncertain_claim", questions, claims: claims.length, unmatched, validationError: "unverified_claim", parseAttempts: parsed.parseAttempts };
     return { ok: true, resume, coverLetter, claims: claims.length };
 }

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

@@ -273,10 +273,19 @@ export class LocalArtifactRuntime {
             return;
         }
         const check = checkDraft(parseDraft(text), ctx.texts);
-        this.emit(run, { type: "claims.checked", detail: { total: check.claims, unmatched: check.ok ? 0 : check.unmatched } });
+        const retry = /:retry:(\d+)$/.exec(e.requestId);
+        const attemptNumber = retry ? Number(retry[1]) : 1;
+        const diagnostic = check.ok ? undefined : {
+            validationError: check.validationError,
+            parseAttempts: check.parseAttempts,
+            rawOutputChars: text.length,
+            runId: e.runId,
+            attemptNumber,
+        };
+        this.emit(run, { type: "claims.checked", detail: { total: check.claims, unmatched: check.ok ? 0 : check.unmatched, ...(diagnostic ? { validationError: diagnostic.validationError, parseAttempts: diagnostic.parseAttempts.join(","), rawOutputChars: diagnostic.rawOutputChars, runId: diagnostic.runId, attemptNumber } : {}) } });
         if (!check.ok) {
             this.removeIfEmpty(ctx.outDir);
-            this.pauseEnd(run, check.reason, check.questions);
+            this.pauseEnd(run, check.reason, check.questions, diagnostic);
             return;
         }
         const at = new Date(this.now()).toISOString();
@@ -340,9 +349,9 @@ export class LocalArtifactRuntime {
             return;
         run.events.push({ ...ev, at: new Date(this.now()).toISOString(), seq: ++run.seq });
     }
-    pauseEnd(run, reason, questions) {
-        this.emit(run, { type: "run.needs_human", detail: { reason, count: questions.length } });
-        this.end(run, { outcome: "needs_human", blockReason: reason, questions });
+    pauseEnd(run, reason, questions, diagnostic) {
+        this.emit(run, { type: "run.needs_human", detail: { reason, count: questions.length, ...(diagnostic ? { validationError: diagnostic.validationError, parseAttempts: diagnostic.parseAttempts.join(","), rawOutputChars: diagnostic.rawOutputChars, runId: diagnostic.runId, attemptNumber: diagnostic.attemptNumber } : {}) } });
+        this.end(run, { outcome: "needs_human", blockReason: reason, questions, diagnostic });
     }
     end(run, r) {
         if (run.state === "ended")
@@ -360,7 +369,7 @@ export class LocalArtifactRuntime {
             engineAuth: run.engineAuth,
             traceId: run.envelope.runId,
             ...(r.generatedAt ? { generatedAt: r.generatedAt } : {}),
-            ...(r.outcome === "needs_human" ? { blockReason: r.blockReason, questions: (r.questions ?? []).map((q) => redactText(q, run.secrets)) } : {}),
+            ...(r.outcome === "needs_human" ? { blockReason: r.blockReason, questions: (r.questions ?? []).map((q) => redactText(q, run.secrets)), ...(r.diagnostic ? { diagnostic: r.diagnostic } : {}) } : {}),
             // 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) } : {}),
         };

package/dist/browser-runner/server.js

@@ -226,6 +226,10 @@ async function route(runner, req, res) {
         return json(res, 200, runner.localArtifact.cancel(await readJson(req)));
     }
     // Local application execution (#957) — run, status, resume, cancel; PULL like research.
+    // The email-lead preflight is read-only and precedes Tailor material generation (#953).
+    if (req.method === "POST" && path === "/local-apply/preflight") {
+        return json(res, 200, await runner.localApply.preflight(await readJson(req)));
+    }
     if (req.method === "POST" && path === "/local-apply/run") {
         return json(res, 202, runner.localApply.start(await readJson(req)));
     }

package/dist/index.js

@@ -1406,6 +1406,316 @@ function parseStatusLine(line) {
   return status;
 }
 
+// src/commands/runner/auto-update.ts
+import { existsSync as existsSync7, mkdirSync as mkdirSync6, readFileSync as readFileSync7, renameSync as renameSync2, writeFileSync as writeFileSync5 } from "fs";
+import { dirname as dirname3, join as join8 } from "path";
+
+// src/runner-lock.ts
+import { createHash, randomUUID as randomUUID2 } from "crypto";
+import { execFileSync as execFileSync2 } from "child_process";
+import { closeSync, mkdirSync as mkdirSync5, openSync, readFileSync as readFileSync6, renameSync, unlinkSync as unlinkSync2, writeSync } from "fs";
+import { homedir as homedir3 } from "os";
+import { join as join7 } from "path";
+function configDir(env = process.env) {
+  return env.PAGS_CONFIG_DIR?.trim() || join7(homedir3(), ".config", "proagentstore");
+}
+var accountKey = (account) => createHash("sha256").update(account.trim().toLowerCase()).digest("hex").slice(0, 12);
+var lockPath = (account, env = process.env) => join7(configDir(env), `up-${accountKey(account)}.lock`);
+function classifyHolder(facts) {
+  const lock = facts.lock;
+  if (!lock) return "unknown";
+  if (lock.v !== 1) return "unknown";
+  if (!lock.pid || !Number.isInteger(lock.pid)) return "unknown";
+  if (!facts.pidAlive) return "dead";
+  if (lock.pidStartedAt && facts.pidStartedAt && lock.pidStartedAt !== facts.pidStartedAt) return "dead";
+  if (facts.healthRsid && facts.healthRsid === lock.rsid) return "live";
+  return "unresponsive";
+}
+var isTakeable = (verdict) => verdict === "dead";
+function holderWhere(lock) {
+  if (lock.launch === "tmux") return `tmux session ${lock.launchDetail || "?"}`;
+  if (lock.launch === "service") return "a background service (launchd/systemd)";
+  if (lock.launch === "headless") return "headless";
+  return lock.launchDetail ? `terminal ${lock.launchDetail}` : "a terminal";
+}
+function holderMessage(lock, verdict) {
+  const since = new Date(lock.startedAt).toLocaleString();
+  const lines = [
+    `A \`pags up\` is already running for this account on this machine.`,
+    `  pid ${lock.pid}, started ${since}, CLI ${lock.version || "?"}, in ${holderWhere(lock)}.`
+  ];
+  if (verdict === "unresponsive") {
+    lines.push(`  It is NOT answering its health check \u2014 it may be asleep, stopped, or the machine may be overloaded.`);
+  }
+  if (verdict === "unknown") {
+    lines.push(`  Its lock file could not be read (a newer CLI may have written it), so it is assumed to be running.`);
+  }
+  lines.push("", "  What you can do:");
+  if (lock.launch === "tmux" && lock.launchDetail) lines.push(`    tmux attach -t ${lock.launchDetail}   \u2014 go to the one that is running`);
+  lines.push(
+    `    pags status                      \u2014 what it is doing, and anything else running here`,
+    lock.launch === "service" ? `    (this one is a service \u2014 stop its launchd/systemd unit rather than replacing it)` : `    pags up --replace                \u2014 stop that one gracefully, then take over`
+  );
+  return lines;
+}
+function detectLaunch(env = process.env, isTty = Boolean(process.stdout.isTTY)) {
+  if (env.PAGS_SERVICE === "1") return { launch: "service", detail: env.PAGS_SERVICE_NAME?.trim() || "" };
+  if (env.TMUX) return { launch: "tmux", detail: env.TMUX_PANE?.trim() || env.TMUX.split(",")[0]?.split("/").pop() || "" };
+  if (!isTty) return { launch: "headless", detail: "" };
+  return { launch: "tty", detail: env.TERM_SESSION_ID?.trim() || env.WINDOWID?.trim() || "" };
+}
+function pidAlive(pid) {
+  if (!pid || !Number.isInteger(pid) || pid <= 0) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (e) {
+    return e.code === "EPERM";
+  }
+}
+function pidStartedAt(pid) {
+  if (!pidAlive(pid)) return "";
+  try {
+    if (process.platform === "win32") {
+      const out = execFileSync2("wmic", ["process", "where", `ProcessId=${pid}`, "get", "CreationDate", "/value"], { encoding: "utf-8", timeout: 4e3, stdio: ["ignore", "pipe", "ignore"] });
+      return (out.match(/CreationDate=(\S+)/)?.[1] ?? "").trim();
+    }
+    return execFileSync2("ps", ["-o", "lstart=", "-p", String(pid)], { encoding: "utf-8", timeout: 4e3, stdio: ["ignore", "pipe", "ignore"] }).trim();
+  } catch {
+    return "";
+  }
+}
+async function healthRsid(port, token = "", timeoutMs = 5e3, fetchImpl = fetch) {
+  if (!port) return null;
+  try {
+    const res = await fetchImpl(`http://127.0.0.1:${port}/health`, { headers: token ? { Authorization: `Bearer ${token}` } : {}, signal: AbortSignal.timeout(timeoutMs) });
+    if (!res.ok) return null;
+    const body = await res.json();
+    return typeof body.rsid === "string" && body.rsid ? body.rsid : null;
+  } catch {
+    return null;
+  }
+}
+function readLock(path) {
+  try {
+    const parsed = JSON.parse(readFileSync6(path, "utf-8"));
+    return parsed && typeof parsed === "object" && typeof parsed.rsid === "string" ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+async function inspectHolder(path, opts = {}) {
+  const lock = readLock(path);
+  if (!lock) return { lock: null, verdict: "unknown" };
+  const alive = pidAlive(lock.pid);
+  const facts = {
+    lock,
+    pidAlive: alive,
+    pidStartedAt: alive ? pidStartedAt(lock.pid) : "",
+    healthRsid: alive ? await healthRsid(lock.port, lock.runnerToken ?? "", opts.healthTimeoutMs ?? 5e3, opts.fetchImpl ?? fetch) : null
+  };
+  return { lock, verdict: classifyHolder(facts) };
+}
+async function acquireLock(input) {
+  const env = input.env ?? process.env;
+  const path = lockPath(input.account, env);
+  const rsid = input.rsid ?? randomUUID2();
+  const handoff = input.handoffFrom?.trim() || env.PAGS_LOCK_HANDOFF?.trim() || "";
+  mkdirSync5(configDir(env), { recursive: true });
+  for (let attempt = 0; attempt < 3; attempt++) {
+    const written = tryWrite(path, buildLock(input, rsid, env));
+    if (written) return { ok: true, lock: written, path, tookOver: attempt === 0 ? "none" : "stale" };
+    const { lock: lock2, verdict: verdict2 } = await inspectHolder(path);
+    if (handoff && lock2?.rsid === handoff) {
+      renameAside(path, lock2.pid);
+      const taken = tryWrite(path, buildLock(input, rsid, env));
+      if (taken) return { ok: true, lock: taken, path, tookOver: "handoff" };
+      continue;
+    }
+    if (!isTakeable(verdict2)) return { ok: false, lock: lock2, path, verdict: verdict2 };
+    if (!takeAsideIfStill(path, lock2?.rsid ?? "", lock2?.pid ?? 0)) continue;
+  }
+  const { lock, verdict } = await inspectHolder(path);
+  return { ok: false, lock, path, verdict };
+}
+function buildLock(input, rsid, env) {
+  const { launch, detail } = detectLaunch(env);
+  const now = Date.now();
+  return {
+    v: 1,
+    rsid,
+    pid: process.pid,
+    pidStartedAt: pidStartedAt(process.pid),
+    startedAt: now,
+    port: input.port,
+    node: input.node,
+    machineId: input.machineId,
+    account: input.account,
+    version: input.version,
+    launch,
+    launchDetail: detail,
+    childPids: [],
+    nonce: randomUUID2(),
+    runnerToken: input.runnerToken ?? "",
+    heartbeatAt: now
+  };
+}
+function tryWrite(path, lock) {
+  let fd = null;
+  try {
+    fd = openSync(path, "wx", 384);
+    writeSync(fd, JSON.stringify(lock, null, 2));
+    return lock;
+  } catch (e) {
+    if (e.code === "EEXIST") return null;
+    throw e;
+  } finally {
+    if (fd !== null) closeSync(fd);
+  }
+}
+function renameAside(path, pid) {
+  const aside = `${path}.stale-${pid || "unknown"}`;
+  try {
+    renameSync(path, aside);
+    return aside;
+  } catch {
+    return null;
+  }
+}
+function takeAsideIfStill(path, deadRsid, pid) {
+  const aside = renameAside(path, pid);
+  if (!aside) return false;
+  const moved = readLock(aside);
+  if (moved && deadRsid && moved.rsid !== deadRsid) {
+    try {
+      renameSync(aside, path);
+    } catch {
+    }
+    return false;
+  }
+  return true;
+}
+function releaseLock(path, rsid) {
+  const current = readLock(path);
+  if (!current || current.rsid !== rsid) return false;
+  try {
+    unlinkSync2(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// src/commands/runner/auto-update.ts
+function autoUpdateStatusWire(status) {
+  if (!status) return void 0;
+  return {
+    "waiting-for-idle": "waiting_for_idle",
+    running: "installing",
+    "verified-success": "verified_success",
+    failure: "failed"
+  }[status] ?? status;
+}
+var statuses = /* @__PURE__ */ new Set([
+  "enabled",
+  "checking",
+  "waiting-for-idle",
+  "running",
+  "restarting",
+  "verified-success",
+  "offline",
+  "unsupported",
+  "failure"
+]);
+function parseStatus(value) {
+  if (typeof value !== "string") return void 0;
+  const readable = {
+    waiting_for_idle: "waiting-for-idle",
+    installing: "running",
+    verified_success: "verified-success",
+    failed: "failure"
+  }[value] ?? value;
+  return statuses.has(readable) ? readable : void 0;
+}
+function autoUpdatePolicyKey(machineId, env = process.env) {
+  return `${env.PAGS_LOCK_ACCOUNT?.trim() || "default"}:${machineId.trim() || "unidentified"}`;
+}
+function autoUpdatePolicyPath(env = process.env) {
+  return env.PAGS_AUTO_UPDATE_POLICY_FILE?.trim() || join8(configDir(env), "auto-update.json");
+}
+function parseAutoUpdatePolicy(value) {
+  if (!value || typeof value !== "object") return null;
+  const raw = value;
+  const autoUpdate = raw.autoUpdate ?? raw.auto_update;
+  if (typeof autoUpdate !== "boolean") return null;
+  const status = parseStatus(raw.status ?? raw.autoUpdateStatus ?? raw.auto_update_status);
+  const latestVersion = raw.latestVersion ?? raw.latest_version;
+  const lastAttemptAt = raw.lastAttemptAt ?? raw.last_attempt_at;
+  const reason = raw.reason;
+  return {
+    autoUpdate,
+    ...status ? { status } : {},
+    ...typeof latestVersion === "string" ? { latestVersion } : {},
+    ...typeof lastAttemptAt === "string" ? { lastAttemptAt } : {},
+    ...typeof reason === "string" ? { reason } : {}
+  };
+}
+function policyFromResponse(value) {
+  if (!value || typeof value !== "object") return null;
+  const raw = value;
+  const direct = raw.autoUpdatePolicy ?? raw.auto_update_policy ?? raw.policy;
+  if (typeof direct === "boolean") {
+    return parseAutoUpdatePolicy({
+      autoUpdate: direct,
+      status: raw.autoUpdateStatus ?? raw.auto_update_status,
+      latestVersion: raw.latestVersion ?? raw.latest_version,
+      lastAttemptAt: raw.lastAttemptAt ?? raw.last_attempt_at,
+      reason: raw.reason
+    });
+  }
+  return parseAutoUpdatePolicy(direct) ?? parseAutoUpdatePolicy(raw.machine && typeof raw.machine === "object" ? raw.machine.autoUpdatePolicy ?? raw.machine.auto_update_policy : void 0);
+}
+function loadAutoUpdatePolicy(key, env = process.env) {
+  try {
+    const data = JSON.parse(readFileSync7(autoUpdatePolicyPath(env), "utf8"));
+    if (data.v !== 1 || !data.policies || typeof data.policies !== "object") return null;
+    return parseAutoUpdatePolicy(data.policies[key]);
+  } catch {
+    return null;
+  }
+}
+function saveAutoUpdatePolicy(key, policy, env = process.env) {
+  const path = autoUpdatePolicyPath(env);
+  try {
+    let old = { v: 1, policies: {} };
+    if (existsSync7(path)) {
+      const parsed = JSON.parse(readFileSync7(path, "utf8"));
+      if (parsed.v === 1 && parsed.policies && typeof parsed.policies === "object") old = parsed;
+    }
+    mkdirSync6(dirname3(path), { recursive: true });
+    const next = { v: 1, policies: { ...old.policies, [key]: policy } };
+    const temp = `${path}.${process.pid}.tmp`;
+    writeFileSync5(temp, JSON.stringify(next, null, 2), { mode: 384 });
+    renameSync2(temp, path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+function nextAutoUpdateDelayMs(failures, random = Math.random) {
+  const base = failures > 0 ? Math.min(60 * 6e4, 6e4 * 2 ** Math.min(failures - 1, 6)) : 6 * 60 * 6e4;
+  const jitter = 0.85 + Math.max(0, Math.min(1, random())) * 0.3;
+  return Math.round(base * jitter);
+}
+function policyScheduleAction(previous, next, wasAuthoritative) {
+  if (!next.autoUpdate) return "cancel";
+  if (!wasAuthoritative || !previous.autoUpdate) return "start";
+  return "keep";
+}
+function mayAutomaticallyRestart(input) {
+  return input.authoritative && input.enabled && input.workObserved && input.busy.length === 0;
+}
+
 // src/commands/runner/relay.ts
 var MEMBERSHIP_SYNC_PATH = "/pags/membership/sync";
 var CLI_CONTROL_PATHS = /* @__PURE__ */ new Set([MEMBERSHIP_SYNC_PATH, RUNNER_UPDATE_PATH]);
@@ -1415,13 +1725,44 @@ async function connectViaRelay(instanceIds, localUrl, runnerToken, opts, force =
   if (!pagsToken) throw new Error("PAGS token required for WebSocket relay");
   const runnerNode = hostname3();
   const machine = loadMachineIdentity(runnerNode);
+  const autoUpdateKey = machine.id ? autoUpdatePolicyKey(machine.id) : "";
+  let autoUpdatePolicy = autoUpdateKey ? loadAutoUpdatePolicy(autoUpdateKey) ?? { autoUpdate: false } : { autoUpdate: false };
+  let autoUpdatePolicyAuthoritative = false;
+  let refreshingAutomaticPolicy = false;
+  let scheduleAutomaticUpdate = () => void 0;
+  const saveAutoUpdateStatus = (status, extra = {}) => {
+    autoUpdatePolicy = {
+      ...autoUpdatePolicy,
+      ...extra,
+      status,
+      lastAttemptAt: (/* @__PURE__ */ new Date()).toISOString()
+    };
+    if (autoUpdateKey) saveAutoUpdatePolicy(autoUpdateKey, autoUpdatePolicy);
+  };
+  const acceptAutoUpdatePolicy = (response) => {
+    if (!autoUpdateKey) return;
+    const policy = policyFromResponse(response);
+    if (!policy) return;
+    const action = policyScheduleAction(autoUpdatePolicy, policy, autoUpdatePolicyAuthoritative);
+    autoUpdatePolicy = { ...autoUpdatePolicy, ...policy };
+    autoUpdatePolicyAuthoritative = true;
+    if (autoUpdateKey) saveAutoUpdatePolicy(autoUpdateKey, autoUpdatePolicy);
+    if (action === "cancel") {
+      scheduleAutomaticUpdate(false, true);
+      return;
+    }
+    if (refreshingAutomaticPolicy) return;
+    if (action === "start") {
+      scheduleAutomaticUpdate(true);
+    }
+  };
   const capabilities = await requestRunner("GET", "/capabilities", { url: localUrl, token: runnerToken, instanceId: instanceIds[0] });
   const caps = Array.isArray(capabilities.capabilities) ? capabilities.capabilities.filter((item) => typeof item === "string") : [];
   const registered = /* @__PURE__ */ new Set();
   let lastRegisterError = "";
   const registerRuntime = async (id, forceClaim = force) => {
     try {
-      await requestPags("POST", `/v1/instances/${apiPathSegment(id)}/runtime`, opts, {
+      const result = await requestPags("POST", `/v1/instances/${apiPathSegment(id)}/runtime`, opts, {
         endpointUrl: localUrl,
         token: runnerToken,
         placement: "local",
@@ -1430,8 +1771,14 @@ async function connectViaRelay(instanceIds, localUrl, runnerToken, opts, force =
         runnerNode,
         machineId: machine.id,
         machineNames: machine.names,
-        force: forceClaim
+        force: forceClaim,
+        autoUpdateStatus: {
+          status: autoUpdateStatusWire(autoUpdatePolicy.status),
+          latestVersion: autoUpdatePolicy.latestVersion,
+          error: autoUpdatePolicy.reason
+        }
       });
+      acceptAutoUpdatePolicy(result);
       registered.add(id);
       return true;
     } catch (e) {
@@ -1442,6 +1789,17 @@ async function connectViaRelay(instanceIds, localUrl, runnerToken, opts, force =
       return false;
     }
   };
+  const refreshAutomaticPolicy = async () => {
+    const id = registered.values().next().value;
+    if (!id) return false;
+    autoUpdatePolicyAuthoritative = false;
+    refreshingAutomaticPolicy = true;
+    try {
+      return await registerRuntime(id) && autoUpdatePolicyAuthoritative;
+    } finally {
+      refreshingAutomaticPolicy = false;
+    }
+  };
   const attached = /* @__PURE__ */ new Map();
   const processStartedAt = Date.now();
   const starts24h = recordRunnerStart(processStartedAt);
@@ -1455,43 +1813,179 @@ async function connectViaRelay(instanceIds, localUrl, runnerToken, opts, force =
   };
   for (const id of instanceIds) await registerRuntime(id);
   const updateFacts = async () => {
-    const sessions = await requestRunner("GET", "/coding/sessions", {
-      url: localUrl,
-      token: runnerToken,
-      instanceId: instanceIds[0]
-    }).catch(() => ({ sessions: [] }));
+    const [sessionsResult, healthResult] = await Promise.allSettled([
+      requestRunner("GET", "/coding/sessions", {
+        url: localUrl,
+        token: runnerToken,
+        instanceId: instanceIds[0]
+      }),
+      requestRunner("GET", "/health", { url: localUrl, token: runnerToken, instanceId: instanceIds[0] })
+    ]);
+    const observationsUnavailable = sessionsResult.status !== "fulfilled" || healthResult.status !== "fulfilled" || !healthResult.value.work;
+    const sessions = sessionsResult.status === "fulfilled" ? sessionsResult.value : { sessions: [] };
+    const health = healthResult.status === "fulfilled" ? healthResult.value : {};
+    const activeCoding = (sessions.sessions ?? []).filter((s) => s.alive && s.runState && s.runState !== "idle").map((s) => s.sessionId);
+    const localRuns = health.work?.localRuns ?? 0;
+    const codingTurns = health.work?.codingTurns ?? 0;
     return {
       current: CLI_VERSION,
       latest: await latestPublishedVersion(),
       fromSource: runsFromSource(),
       restarter: restarterFrom(process.env),
-      busy: (sessions.sessions ?? []).filter((s) => s.alive && s.runState && s.runState !== "idle").map((s) => s.sessionId)
+      // A restart ends browser/application work too. Give these durable names to the same
+      // planner so neither manual nor automatic update can mistake them for an idle machine.
+      busy: observationsUnavailable ? ["runner-work-observation-unavailable"] : [...activeCoding, ...Array.from({ length: codingTurns }, (_v, i) => `coding-turn-${i + 1}`), ...Array.from({ length: localRuns }, (_v, i) => health.work?.detail?.[i] || `local-run-${i + 1}`)]
     };
   };
-  const installAndRestart = async (plan) => {
-    writeLine(`Updating ${plan.current} \u2192 ${plan.latest} (runner_update)\u2026`);
-    await installVersion(plan.latest);
+  let updateInstallInFlight = false;
+  let installedPendingRestart = null;
+  let automaticRestartDraining = false;
+  const installAndRestart = async (plan, automatic = false) => {
+    if (updateInstallInFlight) return false;
+    updateInstallInFlight = true;
+    if (automatic && (!await refreshAutomaticPolicy() || !autoUpdatePolicy.autoUpdate)) {
+      updateInstallInFlight = false;
+      return false;
+    }
+    if (installedPendingRestart !== plan.latest) {
+      writeLine(`Updating ${plan.current} \u2192 ${plan.latest} (runner_update)\u2026`);
+      try {
+        await installVersion(plan.latest);
+        installedPendingRestart = plan.latest;
+      } catch (error) {
+        updateInstallInFlight = false;
+        throw error;
+      }
+    }
+    if (automatic) {
+      automaticRestartDraining = true;
+      await new Promise((resolve5) => setTimeout(resolve5, 500));
+      if (!await refreshAutomaticPolicy() || !autoUpdatePolicy.autoUpdate) {
+        automaticRestartDraining = false;
+        updateInstallInFlight = false;
+        return false;
+      }
+    }
+    const finalFacts = await updateFacts();
+    if (finalFacts.busy.length || automatic && !mayAutomaticallyRestart({ authoritative: autoUpdatePolicyAuthoritative, enabled: autoUpdatePolicy.autoUpdate, workObserved: !finalFacts.busy.includes("runner-work-observation-unavailable"), busy: finalFacts.busy })) {
+      automaticRestartDraining = false;
+      updateInstallInFlight = false;
+      return false;
+    }
     writeLine(`Installed ${plan.latest} \u2014 restarting; every agent re-attaches on the way back up.`);
-    setTimeout(() => {
-      for (const id of [...attached.keys()]) detach(id);
-      leaveForRestart(plan.restarter);
-    }, 500).unref();
+    for (const id of [...attached.keys()]) detach(id);
+    leaveForRestart(plan.restarter);
+    return true;
   };
   let updateWaiting = false;
-  const updateWhenIdle = () => {
+  const updateWhenIdle = (automatic = false) => {
     if (updateWaiting) return;
     updateWaiting = true;
     const until = Date.now() + 60 * 6e4;
     const tick = () => setTimeout(async () => {
+      if (automatic && (!await refreshAutomaticPolicy() || !autoUpdatePolicy.autoUpdate)) {
+        saveAutoUpdateStatus("offline", { reason: "The owner policy could not be refreshed; automatic update is deferred." });
+        updateWaiting = false;
+        return;
+      }
       const plan = planRunnerUpdate(await updateFacts());
       if (plan.action === "update") {
-        await installAndRestart(plan).catch((e) => writeError(`runner_update: install failed \u2014 ${e instanceof Error ? e.message : String(e)}`));
+        if (automatic && !autoUpdatePolicy.autoUpdate) {
+          updateWaiting = false;
+          return;
+        }
+        if (automatic) saveAutoUpdateStatus("running", { latestVersion: plan.latest, reason: void 0 });
+        const installed = await installAndRestart(plan, automatic).catch((e) => {
+          if (automatic) saveAutoUpdateStatus("failure", { reason: e instanceof Error ? e.message : String(e) });
+          writeError(`runner_update: install failed \u2014 ${e instanceof Error ? e.message : String(e)}`);
+          return false;
+        });
+        if (automatic && !installed && Date.now() < until) {
+          saveAutoUpdateStatus("waiting-for-idle", { latestVersion: plan.latest });
+          tick();
+        } else updateWaiting = false;
+      } else if (plan.action === "wait" && Date.now() < until) {
+        if (automatic) saveAutoUpdateStatus("waiting-for-idle", { latestVersion: plan.latest, reason: void 0 });
+        tick();
+      } else {
+        if (automatic && plan.action === "refused") saveAutoUpdateStatus("unsupported", { reason: plan.reason });
         updateWaiting = false;
-      } else if (plan.action === "wait" && Date.now() < until) tick();
-      else updateWaiting = false;
+      }
     }, 15e3).unref();
     tick();
   };
+  let automaticTimer = null;
+  let automaticChecking = false;
+  let automaticFailures = 0;
+  const runAutomaticUpdateCheck = async () => {
+    if (!autoUpdatePolicy.autoUpdate || !autoUpdatePolicyAuthoritative || automaticChecking || updateWaiting) return;
+    automaticChecking = true;
+    try {
+      if (!await refreshAutomaticPolicy() || !autoUpdatePolicy.autoUpdate) {
+        saveAutoUpdateStatus("offline", { reason: "The owner policy could not be refreshed; automatic update is deferred." });
+        scheduleAutomaticUpdate();
+        return;
+      }
+      saveAutoUpdateStatus("checking", { reason: void 0 });
+      const facts = await updateFacts();
+      if (!autoUpdatePolicy.autoUpdate || !autoUpdatePolicyAuthoritative) return;
+      if (!facts.latest) {
+        automaticFailures++;
+        saveAutoUpdateStatus("failure", { reason: "Could not check the trusted npm registry for a newer CLI release." });
+        scheduleAutomaticUpdate();
+        return;
+      }
+      automaticFailures = 0;
+      const plan = planRunnerUpdate(facts);
+      if (plan.action === "up-to-date") {
+        saveAutoUpdateStatus("verified-success", { latestVersion: facts.latest, reason: void 0 });
+        scheduleAutomaticUpdate();
+        return;
+      }
+      if (plan.action === "refused") {
+        saveAutoUpdateStatus("unsupported", { latestVersion: facts.latest, reason: plan.reason });
+        scheduleAutomaticUpdate();
+        return;
+      }
+      if (plan.action === "wait") {
+        saveAutoUpdateStatus("waiting-for-idle", { latestVersion: plan.latest, reason: void 0 });
+        updateWhenIdle(true);
+        return;
+      }
+      if (!autoUpdatePolicy.autoUpdate || !autoUpdatePolicyAuthoritative) return;
+      saveAutoUpdateStatus("running", { latestVersion: plan.latest, reason: void 0 });
+      try {
+        const installed = await installAndRestart(plan, true);
+        if (!installed) {
+          saveAutoUpdateStatus("waiting-for-idle", { latestVersion: plan.latest });
+          updateWhenIdle(true);
+          return;
+        }
+        saveAutoUpdateStatus("restarting", { latestVersion: plan.latest, reason: void 0 });
+      } catch (e) {
+        automaticFailures++;
+        saveAutoUpdateStatus("failure", { latestVersion: plan.latest, reason: e instanceof Error ? e.message : String(e) });
+        scheduleAutomaticUpdate();
+      }
+    } finally {
+      automaticChecking = false;
+    }
+  };
+  scheduleAutomaticUpdate = (initial = false, cancel = false) => {
+    if (cancel || !autoUpdatePolicy.autoUpdate || !autoUpdatePolicyAuthoritative) {
+      if (automaticTimer) clearTimeout(automaticTimer);
+      automaticTimer = null;
+      return;
+    }
+    if (automaticTimer || updateWaiting) return;
+    const delay = initial ? Math.round(5e3 + Math.random() * 25e3) : nextAutoUpdateDelayMs(automaticFailures);
+    automaticTimer = setTimeout(() => {
+      automaticTimer = null;
+      void runAutomaticUpdateCheck();
+    }, delay);
+    automaticTimer.unref();
+  };
+  if (autoUpdatePolicyAuthoritative && autoUpdatePolicy.autoUpdate) scheduleAutomaticUpdate(true);
   const answerUpdate = async (body) => {
     const dryRun = body?.dryRun === true;
     const plan = planRunnerUpdate(await updateFacts());
@@ -1501,7 +1995,7 @@ async function connectViaRelay(instanceIds, localUrl, runnerToken, opts, force =
       return { status: 200, result: { ...plan, detail: "Restarts itself as soon as these engines finish their turns \u2014 no run is cut off." } };
     }
     try {
-      await installAndRestart(plan);
+      if (!await installAndRestart(plan)) return { status: 409, result: { error: "A runner update is already installing or restarting." } };
     } catch (e) {
       return { status: 500, result: { error: `npm could not install ${plan.latest}: ${e instanceof Error ? e.message : String(e)}` } };
     }
@@ -1567,7 +2061,10 @@ async function connectViaRelay(instanceIds, localUrl, runnerToken, opts, force =
           reportRegistration();
         },
         answerControl,
-        runnerNode
+        runnerNode,
+        // The final automatic-update drain is an admission gate, not merely another poll:
+        // command work starts only when the old runner is still permitted to serve it.
+        () => !automaticRestartDraining
       )
     );
     if (label) writeLine(`Attached agent: ${label}`);
@@ -1612,7 +2109,17 @@ async function connectViaRelay(instanceIds, localUrl, runnerToken, opts, force =
       });
       for (const id of [...attached.keys()]) {
         try {
-          await requestPags("POST", `/v1/instances/${apiPathSegment(id)}/runtime/heartbeat`, opts, { runnerNode, resources });
+          const response = await requestPags("POST", `/v1/instances/${apiPathSegment(id)}/runtime/heartbeat`, opts, {
+            runnerNode,
+            machineId: machine.id,
+            resources,
+            autoUpdateStatus: {
+              status: autoUpdateStatusWire(autoUpdatePolicy.status),
+              latestVersion: autoUpdatePolicy.latestVersion,
+              error: autoUpdatePolicy.reason
+            }
+          });
+          acceptAutoUpdatePolicy(response);
         } catch (e) {
           failure = e instanceof Error ? e.message : String(e);
         }
@@ -1701,7 +2208,7 @@ async function readSessionResources(localUrl, runnerToken) {
 }
 var RTT_PROBE_PREFIX = "rtt:";
 var RTT_ECHO_PREFIX = "rtt-echo:";
-function openRelaySocket(instanceId, wsBase, mintToken, localUrl, runnerToken, force = false, onConflict, onOpen, onControl, runnerNode = hostname3()) {
+function openRelaySocket(instanceId, wsBase, mintToken, localUrl, runnerToken, force = false, onConflict, onOpen, onControl, runnerNode = hostname3(), admitMutation = () => true) {
   let backoffMs = 1e3;
   let reconnecting = false;
   let closed = false;
@@ -1769,6 +2276,13 @@ function openRelaySocket(instanceId, wsBase, mintToken, localUrl, runnerToken, f
         return;
       }
       const method = (cmd.method || "POST").toUpperCase();
+      if (method !== "GET" && method !== "HEAD" && !admitMutation()) {
+        try {
+          ws.send(JSON.stringify({ id: cmd.id, status: 503, result: { error: "Runner is draining for a safe automatic update; retry shortly." } }));
+        } catch {
+        }
+        return;
+      }
       const hasBody = method !== "GET" && method !== "HEAD" && cmd.body !== void 0;
       try {
         const headers = {};
@@ -1862,202 +2376,6 @@ function openRelaySocket(instanceId, wsBase, mintToken, localUrl, runnerToken, f
   };
 }
 
-// src/runner-lock.ts
-import { createHash, randomUUID as randomUUID2 } from "crypto";
-import { execFileSync as execFileSync2 } from "child_process";
-import { closeSync, mkdirSync as mkdirSync5, openSync, readFileSync as readFileSync6, renameSync, unlinkSync as unlinkSync2, writeSync } from "fs";
-import { homedir as homedir3 } from "os";
-import { join as join7 } from "path";
-function configDir(env = process.env) {
-  return env.PAGS_CONFIG_DIR?.trim() || join7(homedir3(), ".config", "proagentstore");
-}
-var accountKey = (account) => createHash("sha256").update(account.trim().toLowerCase()).digest("hex").slice(0, 12);
-var lockPath = (account, env = process.env) => join7(configDir(env), `up-${accountKey(account)}.lock`);
-function classifyHolder(facts) {
-  const lock = facts.lock;
-  if (!lock) return "unknown";
-  if (lock.v !== 1) return "unknown";
-  if (!lock.pid || !Number.isInteger(lock.pid)) return "unknown";
-  if (!facts.pidAlive) return "dead";
-  if (lock.pidStartedAt && facts.pidStartedAt && lock.pidStartedAt !== facts.pidStartedAt) return "dead";
-  if (facts.healthRsid && facts.healthRsid === lock.rsid) return "live";
-  return "unresponsive";
-}
-var isTakeable = (verdict) => verdict === "dead";
-function holderWhere(lock) {
-  if (lock.launch === "tmux") return `tmux session ${lock.launchDetail || "?"}`;
-  if (lock.launch === "service") return "a background service (launchd/systemd)";
-  if (lock.launch === "headless") return "headless";
-  return lock.launchDetail ? `terminal ${lock.launchDetail}` : "a terminal";
-}
-function holderMessage(lock, verdict) {
-  const since = new Date(lock.startedAt).toLocaleString();
-  const lines = [
-    `A \`pags up\` is already running for this account on this machine.`,
-    `  pid ${lock.pid}, started ${since}, CLI ${lock.version || "?"}, in ${holderWhere(lock)}.`
-  ];
-  if (verdict === "unresponsive") {
-    lines.push(`  It is NOT answering its health check \u2014 it may be asleep, stopped, or the machine may be overloaded.`);
-  }
-  if (verdict === "unknown") {
-    lines.push(`  Its lock file could not be read (a newer CLI may have written it), so it is assumed to be running.`);
-  }
-  lines.push("", "  What you can do:");
-  if (lock.launch === "tmux" && lock.launchDetail) lines.push(`    tmux attach -t ${lock.launchDetail}   \u2014 go to the one that is running`);
-  lines.push(
-    `    pags status                      \u2014 what it is doing, and anything else running here`,
-    lock.launch === "service" ? `    (this one is a service \u2014 stop its launchd/systemd unit rather than replacing it)` : `    pags up --replace                \u2014 stop that one gracefully, then take over`
-  );
-  return lines;
-}
-function detectLaunch(env = process.env, isTty = Boolean(process.stdout.isTTY)) {
-  if (env.PAGS_SERVICE === "1") return { launch: "service", detail: env.PAGS_SERVICE_NAME?.trim() || "" };
-  if (env.TMUX) return { launch: "tmux", detail: env.TMUX_PANE?.trim() || env.TMUX.split(",")[0]?.split("/").pop() || "" };
-  if (!isTty) return { launch: "headless", detail: "" };
-  return { launch: "tty", detail: env.TERM_SESSION_ID?.trim() || env.WINDOWID?.trim() || "" };
-}
-function pidAlive(pid) {
-  if (!pid || !Number.isInteger(pid) || pid <= 0) return false;
-  try {
-    process.kill(pid, 0);
-    return true;
-  } catch (e) {
-    return e.code === "EPERM";
-  }
-}
-function pidStartedAt(pid) {
-  if (!pidAlive(pid)) return "";
-  try {
-    if (process.platform === "win32") {
-      const out = execFileSync2("wmic", ["process", "where", `ProcessId=${pid}`, "get", "CreationDate", "/value"], { encoding: "utf-8", timeout: 4e3, stdio: ["ignore", "pipe", "ignore"] });
-      return (out.match(/CreationDate=(\S+)/)?.[1] ?? "").trim();
-    }
-    return execFileSync2("ps", ["-o", "lstart=", "-p", String(pid)], { encoding: "utf-8", timeout: 4e3, stdio: ["ignore", "pipe", "ignore"] }).trim();
-  } catch {
-    return "";
-  }
-}
-async function healthRsid(port, token = "", timeoutMs = 5e3, fetchImpl = fetch) {
-  if (!port) return null;
-  try {
-    const res = await fetchImpl(`http://127.0.0.1:${port}/health`, { headers: token ? { Authorization: `Bearer ${token}` } : {}, signal: AbortSignal.timeout(timeoutMs) });
-    if (!res.ok) return null;
-    const body = await res.json();
-    return typeof body.rsid === "string" && body.rsid ? body.rsid : null;
-  } catch {
-    return null;
-  }
-}
-function readLock(path) {
-  try {
-    const parsed = JSON.parse(readFileSync6(path, "utf-8"));
-    return parsed && typeof parsed === "object" && typeof parsed.rsid === "string" ? parsed : null;
-  } catch {
-    return null;
-  }
-}
-async function inspectHolder(path, opts = {}) {
-  const lock = readLock(path);
-  if (!lock) return { lock: null, verdict: "unknown" };
-  const alive = pidAlive(lock.pid);
-  const facts = {
-    lock,
-    pidAlive: alive,
-    pidStartedAt: alive ? pidStartedAt(lock.pid) : "",
-    healthRsid: alive ? await healthRsid(lock.port, lock.runnerToken ?? "", opts.healthTimeoutMs ?? 5e3, opts.fetchImpl ?? fetch) : null
-  };
-  return { lock, verdict: classifyHolder(facts) };
-}
-async function acquireLock(input) {
-  const env = input.env ?? process.env;
-  const path = lockPath(input.account, env);
-  const rsid = input.rsid ?? randomUUID2();
-  const handoff = input.handoffFrom?.trim() || env.PAGS_LOCK_HANDOFF?.trim() || "";
-  mkdirSync5(configDir(env), { recursive: true });
-  for (let attempt = 0; attempt < 3; attempt++) {
-    const written = tryWrite(path, buildLock(input, rsid, env));
-    if (written) return { ok: true, lock: written, path, tookOver: attempt === 0 ? "none" : "stale" };
-    const { lock: lock2, verdict: verdict2 } = await inspectHolder(path);
-    if (handoff && lock2?.rsid === handoff) {
-      renameAside(path, lock2.pid);
-      const taken = tryWrite(path, buildLock(input, rsid, env));
-      if (taken) return { ok: true, lock: taken, path, tookOver: "handoff" };
-      continue;
-    }
-    if (!isTakeable(verdict2)) return { ok: false, lock: lock2, path, verdict: verdict2 };
-    if (!takeAsideIfStill(path, lock2?.rsid ?? "", lock2?.pid ?? 0)) continue;
-  }
-  const { lock, verdict } = await inspectHolder(path);
-  return { ok: false, lock, path, verdict };
-}
-function buildLock(input, rsid, env) {
-  const { launch, detail } = detectLaunch(env);
-  const now = Date.now();
-  return {
-    v: 1,
-    rsid,
-    pid: process.pid,
-    pidStartedAt: pidStartedAt(process.pid),
-    startedAt: now,
-    port: input.port,
-    node: input.node,
-    machineId: input.machineId,
-    account: input.account,
-    version: input.version,
-    launch,
-    launchDetail: detail,
-    childPids: [],
-    nonce: randomUUID2(),
-    runnerToken: input.runnerToken ?? "",
-    heartbeatAt: now
-  };
-}
-function tryWrite(path, lock) {
-  let fd = null;
-  try {
-    fd = openSync(path, "wx", 384);
-    writeSync(fd, JSON.stringify(lock, null, 2));
-    return lock;
-  } catch (e) {
-    if (e.code === "EEXIST") return null;
-    throw e;
-  } finally {
-    if (fd !== null) closeSync(fd);
-  }
-}
-function renameAside(path, pid) {
-  const aside = `${path}.stale-${pid || "unknown"}`;
-  try {
-    renameSync(path, aside);
-    return aside;
-  } catch {
-    return null;
-  }
-}
-function takeAsideIfStill(path, deadRsid, pid) {
-  const aside = renameAside(path, pid);
-  if (!aside) return false;
-  const moved = readLock(aside);
-  if (moved && deadRsid && moved.rsid !== deadRsid) {
-    try {
-      renameSync(aside, path);
-    } catch {
-    }
-    return false;
-  }
-  return true;
-}
-function releaseLock(path, rsid) {
-  const current = readLock(path);
-  if (!current || current.rsid !== rsid) return false;
-  try {
-    unlinkSync2(path);
-    return true;
-  } catch {
-    return false;
-  }
-}
-
 // src/commands/runner/command.ts
 import { hostname as hostname4 } from "os";
 function collectCapability(value, previous = []) {

package/package.json

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