@join-pantheon/cli 0.24.4 → 0.25.0

package/dist/relay.js

@@ -12,7 +12,7 @@ import { Accounts, normalizeUsername, validEmail, validUsername } from "./accoun
 import { emailSenderFromEnv } from "./email.js";
 import { Allowlist } from "./roster-file.js";
 import { StateStore } from "./store.js";
-import { activity, mergeActivity, feed, noteRefusal, refusalsSince, countActs, ESCALATIONS, MESSAGE_ACTS, ACT_TONE, DAY } from "./admin-stats.js";
+import { activity, mergeActivity, feed, noteRefusal, refusalsSince, countActs, spaceHealth, fleetReport, ESCALATIONS, MESSAGE_ACTS, ACT_TONE, DAY } from "./admin-stats.js";
 import { fmtLimit, parseLimits, PLAN_NAME } from "./plans.js";
 import { routeDecision } from "./profile.js";
 function workState(m, now = Date.now(), busyTtlMs = LIMITS.activityBusyTtlMs, pruneMs = LIMITS.activityPruneMs) {
@@ -361,7 +361,7 @@ export class Relay {
     onAuthHttp(req, res, url, ip) {
         if (url.pathname === "/")
             return this.landingPage(res);
-        if (url.pathname === "/admin" || url.pathname === "/admin/space" || url.pathname === "/admin/export" || url.pathname === "/admin/backup" || url.pathname === "/admin/action" || url.pathname === "/admin/login" || url.pathname === "/admin/logout") {
+        if (url.pathname === "/admin" || url.pathname === "/admin/space" || url.pathname === "/admin/export" || url.pathname === "/admin/backup" || url.pathname === "/admin/action" || url.pathname === "/admin/login" || url.pathname === "/admin/logout" || url.pathname === "/admin/report") {
             const A0 = this.accounts;
             if (!A0 || !this.adminToken)
                 return this.json(res, 404, { error: "not found" });
@@ -392,6 +392,15 @@ export class Relay {
                 return void res.end();
             }
             const authed = (fromCookie && tokenOk(fromCookie)) || (fromQuery && tokenOk(fromQuery));
+            if (url.pathname === "/admin/report") {
+                if (!authed)
+                    return this.json(res, 401, { error: "admin token required" });
+                const rows = this.fleetHealth();
+                if (url.searchParams.get("format") === "json")
+                    return this.json(res, 200, { relay: VERSION, generated: Date.now(), spaces: rows });
+                res.writeHead(200, { "content-type": "text/plain; charset=utf-8" });
+                return void res.end(fleetReport(rows, VERSION) + "\n");
+            }
             if (url.pathname === "/admin/export") {
                 if (!authed)
                     return this.json(res, 403, { error: "sign in at /admin, or append ?token=…" });
@@ -704,6 +713,37 @@ button:hover{background:#1d4ed8}.err{color:var(--bad);margin-top:12px}
     adminCsrf() {
         return createHash("sha256").update("pantheon-admin-csrf " + (this.adminToken ?? "")).digest("hex").slice(0, 32);
     }
+    fleetHealth(now = Date.now()) {
+        const out = [];
+        const seen = new Set();
+        const safeOf = (name) => name.replace(/[^a-z0-9._-]/gi, "_");
+        for (const sp of this.spaces.values()) {
+            seen.add(safeOf(sp.name));
+            out.push(spaceHealth({
+                name: sp.name, records: sp.ledger.all(), members: sp.allow.all(),
+                online: [...sp.members.values()].filter((m) => m.sessions.size > 0).length, relayPkg: VERSION, now,
+            }));
+        }
+        let files = [];
+        try {
+            files = readdirSync(this.dataDir);
+        }
+        catch { }
+        for (const f of files) {
+            if (!f.endsWith(".members.json"))
+                continue;
+            const safe = f.slice(0, -".members.json".length);
+            if (seen.has(safe))
+                continue;
+            let members = [];
+            try {
+                members = new Allowlist(this.dataDir, safe).all();
+            }
+            catch { }
+            out.push(spaceHealth({ name: safe, records: this.sleepingRecords(safe), members, online: 0, relayPkg: VERSION, now }));
+        }
+        return out;
+    }
     spacesOverview() {
         const now = Date.now();
         const out = new Map();
@@ -2455,6 +2495,7 @@ pantheon signup --email you@work.com --username you</code></pre>
         m.agent = agent;
         m.last_seen = Date.now();
         m.sessions.set(session, { id: session, role, agent, ...(pkg ? { pkg } : {}), ws });
+        sp.allow.touch(id, pkg, agent);
         return m;
     }
     work(m) {

package/dist/roster-file.js

@@ -146,6 +146,23 @@ export class Allowlist {
         this.flush();
         return true;
     }
+    static TOUCH_EVERY_MS = 10 * 60_000;
+    touch(member, pkg, agent, now = Date.now()) {
+        const e = this.entries.get(member);
+        if (!e)
+            return false;
+        const known = agent && agent !== "unknown" ? agent : undefined;
+        const changed = (pkg !== undefined && pkg !== e.last_pkg) || (known !== undefined && known !== e.last_agent);
+        if (!changed && e.last_seen !== undefined && now - e.last_seen < Allowlist.TOUCH_EVERY_MS)
+            return false;
+        e.last_seen = now;
+        if (pkg !== undefined)
+            e.last_pkg = pkg;
+        if (known !== undefined)
+            e.last_agent = known;
+        this.flush();
+        return true;
+    }
     admittedCount() { return [...this.entries.values()].filter((e) => e.admitted).length; }
     founder() {
         const f = [...this.entries.values()].filter((e) => e.admitted && (e.admitted_by === e.member || e.admitted_by === undefined)).sort((a, b) => a.first_seen - b.first_seen)[0];

package/dist/run-failure.js

@@ -0,0 +1,97 @@
+import { execFileSync } from "node:child_process";
+const sh = (dir, ...args) => execFileSync("git", ["-C", dir, ...args], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"], timeout: 5_000 }).trim();
+export const gitProbe = {
+    isRepo: (dir) => { try {
+        return sh(dir, "rev-parse", "--is-inside-work-tree") === "true";
+    }
+    catch {
+        return false;
+    } },
+    hasRemote: (dir) => { try {
+        return sh(dir, "remote").split("\n").some((r) => r.trim());
+    }
+    catch {
+        return false;
+    } },
+    dirty: (dir) => { try {
+        return sh(dir, "status", "--porcelain").split("\n").map((l) => l.trim()).filter(Boolean);
+    }
+    catch {
+        return [];
+    } },
+    branchOf: (dir) => { try {
+        return sh(dir, "rev-parse", "--abbrev-ref", "HEAD");
+    }
+    catch {
+        return "";
+    } },
+};
+export function exitLine(detail) {
+    const lines = detail.split("\n").map((l) => l.trim());
+    const first = lines[0] ?? "";
+    if (!/^exit\s+-?\d+$/.test(first))
+        return first.slice(0, 120);
+    const said = lines.slice(1).find((l) => l && !/^\s*$/.test(l));
+    return (said ? `${first}: ${said}` : first).slice(0, 120);
+}
+const list = (paths, max = 3) => paths.length <= max ? paths.join(", ") : `${paths.slice(0, max).join(", ")} and ${paths.length - max} more`;
+const ask = (fn, fallback) => { try {
+    return fn();
+}
+catch {
+    return fallback;
+} };
+export function diagnoseRun(f, probe = gitProbe) {
+    if (!f.exited) {
+        return {
+            cause: "crashed",
+            says: `The agent did not finish — ${exitLine(f.detail)}.`,
+            fix: `Read the transcript at ${f.runLog}. If the agent CLI is broken or missing, pantheon doctor names it.`,
+            dir: f.worktree,
+            lines: [`cat ${f.runLog}`],
+        };
+    }
+    if (!f.branch) {
+        return {
+            cause: "not_a_repo",
+            says: "There is no git repo here, so the run had no branch and nothing it could deliver.",
+            fix: `It can still answer and escalate. To let it deliver work, point the worker at a checkout: pantheon service install worker from inside the repo.`,
+        };
+    }
+    if (!f.allowBash) {
+        return {
+            cause: "no_commands",
+            says: "This worker may edit files but not run commands, so it could not run tests, commit or push.",
+            fix: "Allow commands if you want unattended runs to deliver work: pantheon setup --commands yes. Until then a woken run can answer and draft, never deliver.",
+            capability: "run_commands",
+        };
+    }
+    if (!ask(() => probe.hasRemote(f.project), true)) {
+        return {
+            cause: "no_remote",
+            says: "This repo has no remote, so nothing the run builds can be fetched by the teammate who asked.",
+            fix: "Add a remote your teammate can reach, then the run can push a branch and DELIVER it.",
+            dir: f.project,
+            lines: ["git remote add origin <url>", "git push -u origin HEAD"],
+        };
+    }
+    const dirty = ask(() => probe.dirty(f.project), []);
+    if (dirty.length) {
+        const on = ask(() => probe.branchOf(f.project), "");
+        return {
+            cause: "human_has_it",
+            says: `The work is uncommitted in your own checkout${on ? ` on ${on}` : ""} — a run never sees that, it starts from what origin has.`,
+            fix: "Commit and push it yourself, then the run (or your teammate) can see it. A worker deliberately never touches your working tree.",
+            dir: f.project,
+            lines: [`git status --short   # ${list(dirty)}`, "git add -A", `git commit -m "…"`, `git push${on ? ` -u origin ${on}` : ""}`],
+        };
+    }
+    return {
+        cause: "silent",
+        says: "The run finished cleanly but sent nothing back, so the request is still open.",
+        fix: `Read what it did at ${f.runLog}. If it was right to stay silent, answer the teammate yourself; if not, the transcript says where it stopped.`,
+        dir: f.worktree,
+        lines: [`cat ${f.runLog}`],
+    };
+}
+//# sourceMappingURL=run-failure.js.map

package/dist/setup-guide.js

@@ -1,4 +1,5 @@
 import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { approvalSummary, installForUser } from "./install.js";
 import { execFileSync } from "node:child_process";
 import { homedir } from "node:os";
 import { join } from "node:path";
@@ -33,6 +34,7 @@ export function guideDefaults(profile, cfg) {
     return {
         wake: profile.agent.wake_default ?? "anyone",
         commands: profile.agent.allow_bash ?? false,
+        approval: profile.agent.approval ?? "approve",
         name: profile.human.display_name || cfg.display || cfg.member,
         title: profile.human.title || "",
         decides: Object.entries(profile.authority).filter(([, m]) => m === "human_required").map(([d]) => d),
@@ -64,7 +66,7 @@ export function questionnaire() {
         "",
         "Only 3 and 4 need the person every time. Ask 2 whenever there is a repo (it is the one default people are",
         "surprised by). The rest have defaults you may take and say out loud:",
-        "  --wake anyone --decides none --alerts decisions --playbook yes --base <what origin calls its default>",
+        "  --wake anyone --decides none --alerts decisions --playbook yes --base <what origin calls its default> --approve-all",
         "Without a repo, --wake, --commands, --playbook and --base do nothing yet: skip them and say so.",
         "",
         "1. While they're away, may teammates hand work to this machine? (their agent runs here on its own,",
@@ -86,6 +88,13 @@ export function questionnaire() {
         "8. Which branch should workers start from, and deliveries be checked against? Usually the branch this",
         "   project deploys or releases from (often the default branch).     → --base <branch>",
         "",
+        "9. Should their own agent ask them before each message it sends to a teammate in their name? Default no:",
+        "   the agent coordinates for them without stopping. Reads and waiting never prompt either way.",
+        opt("approve-all", "", "No — send, open goals and claim work without asking (recommended; the default)"),
+        opt("ask-before-sending", "", "Yes — show each send, goal and claim for approval first"),
+        "   These are switches: pass --approve-all or --ask-before-sending with no value. Either way the install",
+        "   output prints the exact line written to ~/.codex/config.toml, and pantheon leave removes it.",
+        "",
         "Example:  pantheon setup --yes --wake anyone --commands yes --name \"Praneet Sinha\" --title Founder \\",
         "            --decides deployment --alerts decisions --playbook yes --base main",
     ].join("\n");
@@ -133,6 +142,12 @@ export function parseSetupFlags(argv) {
     const playbook = yn("playbook");
     if (playbook !== undefined)
         preset.persona = playbook;
+    if (argv.includes("--ask-before-sending") && argv.includes("--approve-all"))
+        errors.push("--ask-before-sending and --approve-all contradict each other; pass one");
+    else if (argv.includes("--ask-before-sending"))
+        preset.approval = "ask-before-sending";
+    else if (argv.includes("--approve-all"))
+        preset.approval = "approve";
     const base = val("base");
     if (base !== undefined && base.trim())
         preset.base = base.trim();
@@ -179,6 +194,9 @@ export async function runGuide(io, ctx, deps = {}, preset = {}) {
                 : a.wake === "anyone" ? "teammates may hand work to this machine while you're away; invites you send grant it, and you can revoke anyone (pantheon admit <name> --revoke)"
                     : "only people you approve by hand (pantheon admit <name> --may-wake)"}`);
         io.say(`  • Alerts: ${shortAlert(a.notifications).toLowerCase()}`);
+        io.say(`  • Approval: ${a.approval === "approve"
+            ? "your agent sends to teammates in your name without asking each time (Claude Code, Cursor and Codex)"
+            : "your agent asks you before each send, goal and claim; reading and waiting never prompt"}`);
         io.say(`  • Decisions: ${a.decides.length ? `you personally decide ${a.decides.join(", ")}` : "none reserved for you — your agent may decide; add an area when one comes up"}`);
         if (a.wake !== "no" && ctx.project)
             io.say(`  • Playbook: ${a.persona ? "a short starter playbook for your worker, in this repo" : "none"}`);
@@ -212,6 +230,8 @@ export async function runGuide(io, ctx, deps = {}, preset = {}) {
                 const b = await io.choose("Which branch should your worker start from, and deliveries be checked against? Usually the branch this project deploys or releases from.", [`${suggestedBase}${suggestedBase === detected ? " (what origin calls its default)" : ""}`, "A different branch"], 0);
                 a.base = b === 0 ? suggestedBase : ((await io.ask("Branch name", suggestedBase)).trim() || suggestedBase);
             }
+            const ap = await io.choose("Should your agent ask you before each message it sends to a teammate in your name? Reading the board and waiting for peers never prompt either way.", ["No — coordinate for me without stopping to ask (recommended)", "Yes — show me each send, goal and claim first"], a.approval === "approve" ? 0 : 1);
+            a.approval = ap === 0 ? "approve" : "ask-before-sending";
         }
     }
     let next = a.title ? applyProfileInit(profile, { name: a.name, title: a.title }) : { ...profile, human: { ...profile.human, display_name: a.name } };
@@ -227,7 +247,7 @@ export async function runGuide(io, ctx, deps = {}, preset = {}) {
     next = {
         ...next,
         authority,
-        agent: { ...next.agent, wake_enabled: a.wake !== "no", wake_default: a.wake, allow_bash: a.commands },
+        agent: { ...next.agent, wake_enabled: a.wake !== "no", wake_default: a.wake, allow_bash: a.commands, approval: a.approval },
         notifications: {
             decisions: a.notifications !== "none",
             deliveries: a.notifications === "deliveries" || a.notifications === "worker",
@@ -246,6 +266,14 @@ export async function runGuide(io, ctx, deps = {}, preset = {}) {
             warnings.push(`profile saved but not published (${e.message}) — run \`pantheon profile publish\` when the relay is reachable`);
         }
     }
+    const wiring = deps.applyAgentWiring ?? ((ap) => installForUser(ap).map((t) => ({ tool: t.tool, status: t.status })));
+    try {
+        const codex = wiring(a.approval).find((t) => t.tool === "codex");
+        applied.push(`approval: ${approvalSummary(a.approval)}${codex ? ` — codex: ${codex.status}` : ""}`);
+    }
+    catch (e) {
+        warnings.push(`agent wiring not re-applied (${e.message}) — run pantheon install --user`);
+    }
     if (a.wake === "no") {
         if (installed("worker")) {
             try {

package/dist/tools.js

@@ -1,6 +1,13 @@
 export const PANTHEON_TOOL_NAMES = [
-    "pantheon_status", "pantheon_brief", "pantheon_wait", "pantheon_send",
-    "pantheon_claim", "pantheon_open_goal", "pantheon_history",
+    "pantheon_status", "pantheon_brief", "pantheon_directory", "pantheon_route_decision",
+    "pantheon_wait", "pantheon_history",
+    "pantheon_send", "pantheon_open_goal", "pantheon_claim",
 ];
+export const WRITE_TOOL_NAMES = ["pantheon_send", "pantheon_open_goal", "pantheon_claim"];
+export const READ_TOOL_NAMES = PANTHEON_TOOL_NAMES.filter((t) => !WRITE_TOOL_NAMES.includes(t));
 export const PANTHEON_TOOLS = PANTHEON_TOOL_NAMES.map((t) => `mcp__pantheon__${t}`);
+export const APPROVAL_MODES = ["approve", "ask-before-sending"];
+export function toolsAllowed(approval) {
+    return approval === "ask-before-sending" ? READ_TOOL_NAMES : PANTHEON_TOOL_NAMES;
+}
 //# sourceMappingURL=tools.js.map

package/dist/tray.js

@@ -11,7 +11,7 @@ import { requireDeveloperTools } from "./notifier.js";
 import { plistPath, serviceInstalled, whichPantheon } from "./service.js";
 import { VERSION } from "./version.js";
 import { LIMITS } from "./protocol.js";
-import { allDecisionsPrompt, decisionPrompt, decisionTitle, owedPrompt, waitingPrompt, workerSummary } from "./decision-ui.js";
+import { allDecisionsPrompt, decisionPrompt, decisionTitle, owedPrompt, stripCeremony, waitingPrompt, workerSummary } from "./decision-ui.js";
 import { loadProfile, SURFACE_BUNDLE_IDS } from "./profile.js";
 const HERE = dirname(fileURLToPath(import.meta.url));
 export const trayBinaryPath = (home = CONFIG_DIR) => join(home, "bin", "pantheon-tray");
@@ -118,6 +118,7 @@ async function trayStatusOne(cfg) {
     const decisionsOk = ok;
     const decisions = mineHuman
         .map((o) => ({ id: o.id, body: decisionTitle(o.body), detail: o.body, prompt: decisionPrompt(o.id) }));
+    const senderOf = (o) => stripCeremony(o.body).from;
     const row = (o, kind, who, prompt) => ({
         id: o.id, kind, title: decisionTitle(o.body), headline: decisionTitle(o.body, 200), detail: o.body, prompt, who,
         when: o.created_at ?? 0,
@@ -127,11 +128,17 @@ async function trayStatusOne(cfg) {
     const owed = all.filter((o) => o.owner === cfg.member);
     const waiting = all.filter((o) => o.owner !== cfg.member && o.owner !== `human:${cfg.member}`);
     const items = [
-        ...mineHuman.map((o) => row(o, "decision", "you", decisionPrompt(o.id))),
+        ...mineHuman.map((o) => {
+            const from = senderOf(o);
+            return row(o, "decision", !from || from === cfg.member ? "your agent" : from, decisionPrompt(o.id));
+        }),
         ...owed.map((o) => row(o, "owed", "you", owedPrompt(decisionTitle(o.body), o.goal))),
         ...waiting.map((o) => {
             const who = o.owner.replace(/^human:/, "");
-            return row(o, "waiting", who, waitingPrompt(who, decisionTitle(o.body), o.goal));
+            const r = row(o, "waiting", who, waitingPrompt(who, decisionTitle(o.body), o.goal));
+            return o.owner.startsWith("human:")
+                ? { ...r, title: `${who} decides: ${r.title}`, headline: `${who} decides: ${r.headline}` }
+                : r;
         }),
     ];
     const profile = loadProfile(cfg);

package/dist/worker-policy.js

@@ -2,6 +2,7 @@ import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { CONFIG_PATH } from "./config.js";
 export const ASK_COOLDOWN_MS = 24 * 60 * 60 * 1_000;
+export const ASK_EXPIRY_MS = 14 * 24 * 60 * 60 * 1_000;
 export function policyHome(home) {
     return home ?? process.env.PANTHEON_HOME ?? dirname(CONFIG_PATH);
 }
@@ -41,7 +42,8 @@ export function revoke(p, cap) {
 export function mayAsk(p, cap, now = Date.now()) {
     if (p.grants[cap])
         return false;
-    if (p.asks[cap])
+    const open = p.asks[cap];
+    if (open && now - open.at < ASK_EXPIRY_MS)
         return false;
     const deniedAt = p.denied[cap];
     return deniedAt === undefined || now - deniedAt >= ASK_COOLDOWN_MS;

package/dist/worker.js

@@ -14,6 +14,7 @@ import { loadContinued, markContinued } from "./continued.js";
 import { loadProfile, reservedDecisionsNote } from "./profile.js";
 import { clip } from "./brief.js";
 import { composeWorker } from "./notice.js";
+import { diagnoseRun, gitProbe } from "./run-failure.js";
 import { installedTools, preferredTool } from "./notifier.js";
 import { loadPersonas, matchPersona, personaByName, personaMatches, effectivePolicy, personaBrief, describePersona, } from "./persona.js";
 import { isContinuationFor, LIMITS, shouldDeferToHuman } from "./protocol.js";
@@ -180,6 +181,13 @@ Act, reply if a reply is owed, then finish.`;
 }
 let fleetLock = null;
 const CONTINUATION_HORIZON_MS = 24 * 60 * 60_000;
+export function answerWindow(askSeq, hint, fullScanDue) {
+    if (askSeq !== null)
+        return Math.max(0, askSeq - 1);
+    if (fullScanDue)
+        return 0;
+    return Math.max(0, hint);
+}
 export class Worker {
     cfg;
     opts;
@@ -492,10 +500,13 @@ export class Worker {
             this.done.push(job);
             this.client?.reportWorkerState("idle");
             if (candidate && !job.ok) {
-                this.failedRuns.set(candidate.id, (this.failedRuns.get(candidate.id) ?? 0) + 1);
+                const failures = (this.failedRuns.get(candidate.id) ?? 0) + 1;
+                this.failedRuns.set(candidate.id, failures);
                 if (this.failedRuns.size > 200) {
                     this.failedRuns.delete(this.failedRuns.keys().next().value);
                 }
+                if (failures >= 2 && job.diagnosis)
+                    await this.reportStuck(client, candidate, job.diagnosis);
             }
             this.running = false;
             if (fleetLock === this)
@@ -537,11 +548,22 @@ export class Worker {
         const trigger = client.recent(act.id) ?? `(${act.act} ${act.id} is not in this session's buffer)`;
         return this.runJob(client, o, persona, policy, (branch) => buildContinuationBrief(act, trigger, branch, persona), false);
     }
+    commandGrant(persona) {
+        if (persona?.allowBash === false)
+            return false;
+        const policy = loadPolicy(this.opts.home);
+        if (!useGrant(policy, "run_commands"))
+            return false;
+        savePolicy(policy, this.opts.home);
+        this.opts.log(`  bash    on for this run — your human granted run_commands`);
+        return true;
+    }
     async runJob(client, o, persona, policy, makeBrief, requireReply) {
         const goal = o.goal ?? "adhoc";
         if (this.opts.allowBash && !policy.allowBash && persona) {
             this.opts.log(`  bash    off for this run — persona "${persona.name}" says allow_bash: false`);
         }
+        const allowBash = policy.allowBash || this.commandGrant(persona);
         let branch = branchName(this.cfg.space, goal, this.client?.goals.get(goal)?.title);
         let worktree = join(this.opts.scratch, goal);
         let baseRef = "", baseSha = "";
@@ -566,14 +588,14 @@ export class Worker {
                 const plan = headlessSpawn({
                     backend: { id: "claude-code", label: "Claude Code", binaries: ["claude"] },
                     binary: this.opts.agentCmd,
-                    prompt: brief, worktree, cfg: this.cfg, branch, allowBash: policy.allowBash, runHome, ...(baseSha ? { base: baseSha } : {}), goal,
+                    prompt: brief, worktree, cfg: this.cfg, branch, allowBash, runHome, ...(baseSha ? { base: baseSha } : {}), goal,
                 });
                 materializeSpawnFiles(worktree, plan);
                 ({ command, args, env } = { command: plan.command, args: plan.args, env: { ...env, ...plan.env } });
             }
             else {
                 const { backend, binary } = resolveAgent(policy.agent ?? this.opts.agent);
-                const plan = headlessSpawn({ backend, binary, prompt: brief, worktree, cfg: this.cfg, branch, allowBash: policy.allowBash, runHome });
+                const plan = headlessSpawn({ backend, binary, prompt: brief, worktree, cfg: this.cfg, branch, allowBash, runHome });
                 materializeSpawnFiles(worktree, plan);
                 ({ command, args, env } = { command: plan.command, args: plan.args, env: { ...env, ...plan.env } });
                 this.opts.log(`  spawn   ${command} ${args.slice(0, 3).join(" ")}…`);
@@ -607,18 +629,56 @@ export class Worker {
         }, this.opts.home);
         const sent = client.mineSince(startedAt, o.goal);
         const quiet = ok && !requireReply && sent.length === 0;
+        const diagnosis = ok ? undefined : diagnoseRun({ exited, replied, allowBash, branch, project: this.opts.project, worktree, detail, runLog }, this.opts.probe ?? gitProbe);
         if (this.opts.notify && !quiet && (!ok || loadProfile(this.cfg).notifications?.worker_done)) {
             try {
                 const reply = sent[sent.length - 1] ?? null;
-                this.opts.notify(composeWorker({ ok, triggeredBy, obligationBody: o.body, goal: o.goal ? client.goals.get(o.goal) : undefined, reply, obligationRef: o.ref }, (() => { const tools = installedTools(); return { tools, preferred: preferredTool(loadProfile(this.cfg), tools, this.opts.home) }; })()));
+                this.opts.notify(composeWorker({ ok, triggeredBy, obligationBody: o.body, goal: o.goal ? client.goals.get(o.goal) : undefined, reply, obligationRef: o.ref, ...(diagnosis ? { diagnosis } : {}) }, (() => { const tools = installedTools(); return { tools, preferred: preferredTool(loadProfile(this.cfg), tools, this.opts.home) }; })()));
             }
             catch { }
         }
         this.opts.log(quiet ? `< read ${o.id} on ${branch} — the thread was already settled, nothing sent`
             : ok ? `< handled ${o.id} on ${branch}`
-                : !exited ? `! run failed for ${o.id}: ${detail.split("\n")[0]} (see ${runLog})`
-                    : `! run exited cleanly but sent no act for ${o.id} — see ${runLog}`);
-        return { obligation: o, branch, worktree, ok, detail };
+                : `! ${o.id} stopped [${diagnosis.cause}]: ${diagnosis.says} (transcript: ${runLog})`);
+        return { obligation: o, branch, worktree, ok, detail, ...(diagnosis ? { diagnosis } : {}) };
+    }
+    async reportStuck(client, o, d) {
+        const key = `stuck:${o.id}`;
+        const space = this.spaceKey();
+        if (loadContinued(space, this.opts.home).has(key))
+            return;
+        const policy = loadPolicy(this.opts.home);
+        const asking = !!d.capability && mayAsk(policy, d.capability);
+        const what = clip(o.body, 120);
+        const lines = [
+            `Two runs on this machine could not finish ${o.kind === "CONTINUE" ? "a follow-up" : `the ${o.kind}`} it owes: ${what}`,
+            ``,
+            `WHY IT STOPPED. ${d.says}`,
+            `WHAT UNBLOCKS IT. ${d.fix}`,
+            ...(d.dir && d.lines?.length ? [``, `On this machine, in ${d.dir}:`, ...d.lines.map((l) => `  ${l}`)] : []),
+            ``,
+            `Nothing was sent to the teammate who asked, and the request is still open on them.`,
+            `It will not be retried unattended — a live session here, or you, has to move it.`,
+        ];
+        if (asking) {
+            lines.push(``, `MAY THE WORKER RUN COMMANDS ON THIS MACHINE? Answer "allow always", "allow once", or "deny".`, `Today it may edit files only, which is why it could not commit or push. Allowing it lets a woken`, `run execute tests and git in its own isolated worktree — never in your checkout.`);
+        }
+        try {
+            const sent = await client.send({
+                act: "ESCALATE", goal: o.goal, ref: o.ref, after_seq: client.readSeq,
+                summary: clip(`Stuck on you: ${d.says}`, 190),
+                body: lines.join("\n"),
+            });
+            markContinued(space, key, this.opts.home);
+            if (asking && d.capability) {
+                recordAsk(policy, d.capability, sent.id);
+                savePolicy(policy, this.opts.home);
+            }
+            this.opts.log(`* escalated ${o.id}: ${d.cause}${asking ? ` (and asked for ${d.capability})` : ""}`);
+        }
+        catch (e) {
+            this.opts.log(`! could not report the stuck obligation on the ledger: ${e.message}`);
+        }
     }
     enqueueContinuations(client, arrived) {
         this.loadContinued();
@@ -678,13 +738,18 @@ export class Worker {
         const home = this.opts.home;
         {
             const policy = loadPolicy(home);
-            const open = policy.asks.self_upgrade;
             let changed = false;
-            const fromStream = arrived.find((a) => a.act === "ANSWER" && a.ref && open && a.ref === open.act);
-            const body = fromStream?.body ?? (open ? await this.fetchGrantAnswer(open.act) : null);
-            if (open && body !== null) {
+            for (const cap of Object.keys(policy.asks)) {
+                const open = policy.asks[cap];
+                if (!open)
+                    continue;
+                const fromStream = arrived.find((a) => a.act === "ANSWER" && a.ref === open.act);
+                const body = fromStream?.body ?? await this.fetchGrantAnswer(open.act, client.head - 200);
+                if (body === null)
+                    continue;
                 const applied = applyAnswer(policy, open.act, body);
                 if (applied) {
+                    this.askAt.delete(open.act);
                     changed = true;
                     this.opts.log(`* grant request answered: ${applied.cap} -> ${applied.verdict}`);
                 }
@@ -756,10 +821,39 @@ export class Worker {
             }
         }
     }
-    async fetchGrantAnswer(askActId) {
+    askAt = new Map();
+    lastFullScan = 0;
+    async actSeq(id) {
+        try {
+            const base = this.cfg.relay.replace(/^ws/, "http").replace(/\/+$/, "");
+            const q = `space=${encodeURIComponent(this.cfg.space)}&token=${encodeURIComponent(this.cfg.token)}`;
+            const res = await fetch(`${base}/act?${q}&id=${encodeURIComponent(id)}`, { signal: AbortSignal.timeout(3000) });
+            if (!res.ok)
+                return null;
+            const j = await res.json();
+            return typeof j.act?.seq === "number" ? j.act.seq : null;
+        }
+        catch {
+            return null;
+        }
+    }
+    async fetchGrantAnswer(askActId, since = 0) {
+        let seq = this.askAt.get(askActId) ?? null;
+        if (seq === null) {
+            seq = await this.actSeq(askActId);
+            if (seq !== null)
+                this.askAt.set(askActId, seq);
+        }
+        let due = false;
+        if (seq === null) {
+            due = Date.now() - this.lastFullScan > 5 * 60_000;
+            if (due)
+                this.lastFullScan = Date.now();
+        }
+        const from = answerWindow(seq, since, due);
         try {
             const base = this.cfg.relay.replace(/^ws/, "http").replace(/\/+$/, "");
-            const url = `${base}/history?space=${encodeURIComponent(this.cfg.space)}&token=${encodeURIComponent(this.cfg.token)}&since=0`;
+            const url = `${base}/history?space=${encodeURIComponent(this.cfg.space)}&token=${encodeURIComponent(this.cfg.token)}&since=${from}`;
             const res = await fetch(url, { signal: AbortSignal.timeout(3000) });
             const j = await res.json();
             const ans = (j.acts ?? []).find((a) => a.act === "ANSWER" && a.ref === askActId);

package/helper/macos/main.swift

@@ -9,6 +9,7 @@
  *                      (the choice becomes the default), through a .command file
  *                      Terminal runs — no automation permission needed
  *   Show details       prints the act and the decision in Terminal
+ *   Fix it here        (a failed run) opens a Terminal where the work is, steps shown
  *   Done               (decisions) answers it as handled, silently — the reminders stop
  *   Dismiss / ×        closes
  *
@@ -26,13 +27,15 @@ import AppKit
 let args = CommandLine.arguments
 
 if args.count == 2, args[1] == "version" {
-  print("3")
+  print("4")
   exit(0)
 }
 
 struct Tool: Decodable { let id: String; let label: String; let kind: String?; let bundle: String?; let deeplink: String? }
 struct Primary: Decodable { let label: String; let `default`: String; let tools: [Tool]; let prompt: String }
 struct Details: Decodable { let act: String?; let decision: String? }
+/// The one thing a person could do about a failed run: where, and which steps.
+struct Fix: Decodable { let label: String; let dir: String; let lines: [String]; let why: String }
 struct Notice: Decodable {
   let kind: String
   let who: String
@@ -44,6 +47,7 @@ struct Notice: Decodable {
   let sound: Bool
   let primary: Primary?
   let details: Details?
+  let fix: Fix?
   /** where to write the chosen action and which .command files to open — supplied by the CLI */
   let bin_dir: String
   /** the pantheon CLI to run silently for one-click actions — supplied by the CLI, since this helper has no PATH worth trusting */
@@ -158,6 +162,14 @@ final class AppDelegate: NSObject, NSApplicationDelegate {
     NSApp.terminate(nil)
   }
 
+  /// Fix it here: open a Terminal where the work is, with the steps shown. The
+  /// CLI asks before running anything — a run that just failed is the wrong
+  /// moment to take another unattended action on someone's machine.
+  @objc func fixIt(_ sender: Any?) {
+    guard let f = notice.fix else { NSApp.terminate(nil); return }
+    act(["action": "fix", "dir": f.dir, "lines": f.lines, "why": f.why], command: "pantheon-details.command")
+  }
+
   @objc func legacyOpen(_ sender: Any?) {
     if !legacyPrompt.isEmpty { NSPasteboard.general.clearContents(); NSPasteboard.general.setString(legacyPrompt, forType: .string) }
     if let b = legacyBundle, let url = NSWorkspace.shared.urlForApplication(withBundleIdentifier: b) {
@@ -280,6 +292,15 @@ final class AppDelegate: NSObject, NSApplicationDelegate {
         constraints += [d.leadingAnchor.constraint(equalTo: pull.trailingAnchor, constant: 14), d.centerYAnchor.constraint(equalTo: pull.centerYAnchor)]
         trailing = d
       }
+      if notice.fix != nil {
+        let fix = NSButton(title: notice.fix!.label, target: self, action: #selector(fixIt(_:)))
+        fix.isBordered = false; fix.font = .systemFont(ofSize: 12, weight: .medium); fix.contentTintColor = .controlAccentColor
+        fix.toolTip = notice.fix!.why
+        fix.translatesAutoresizingMaskIntoConstraints = false
+        root.addSubview(fix)
+        constraints += [fix.leadingAnchor.constraint(equalTo: trailing.trailingAnchor, constant: 14), fix.centerYAnchor.constraint(equalTo: pull.centerYAnchor)]
+        trailing = fix
+      }
       if notice.details?.decision != nil {
         // A decision can be settled from the banner itself: one click, no terminal, no more reminders.
         let done = NSButton(title: "Done", target: self, action: #selector(markDone(_:)))