@join-pantheon/cli 0.29.1 → 0.31.0

package/dist/doctor.js

@@ -1,21 +1,24 @@
+import { parseJsonText, stripJsonc } from "./text-file.js";
 import { kiroDefaultIsPantheon, readKiroAgent, kiroAgentFile } from "./kiro-files.js";
 import { execFileSync } from "node:child_process";
 import { instructionBudget } from "./mcp-instructions.js";
 import { describeWindows, scanMcpWindows } from "./mcp-windows.js";
 import { grantsSeen, measureMcp, toolsReport, HOST_STARTUP_ALLOWANCE_MS, STARTUP_WARN_MS } from "./measure.js";
 import { FEEDBACK_ADDRESS } from "./feedback.js";
-import { loadProfile, profileInitialized } from "./profile.js";
+import { loadProfile, profileInitialized, wakeMode } from "./profile.js";
+import { isApprovedWaker, loadPolicy, relayKnowsAdmitters, unsandboxedAllowed } from "./worker-policy.js";
+import { commandState } from "./command-state.js";
 import { existsSync, readFileSync } from "node:fs";
 import { homedir, platform } from "node:os";
 import { join, resolve } from "node:path";
 import { PantheonClient } from "./client.js";
 import { load, resolveFor, loadAll, CONFIG_PATH } from "./config.js";
 import { fingerprint, signChallenge, verifyChallenge } from "./identity.js";
-import { approvalSummary, chosenApproval, onPath } from "./install.js";
+import { approvalSummary, chosenApproval, copilotMcpConfigFile, kiroMcpConfigFile, onPath } from "./install.js";
 import { hookState, readIntent, agentHookStates } from "./notify.js";
 import { loadPersonas } from "./persona.js";
 import { workerProc, menubarProc, notifierProc } from "./machine.js";
-import { chooseAgent, describeChoice, unattendedRefusal, skippedSummary } from "./agents.js";
+import { agentById, chooseAgent, describeChoice, unattendedRefusal, skippedSummary, SANDBOXED_FOR_UNATTENDED } from "./agents.js";
 import { onPathNamed } from "./which.js";
 import { VERSION } from "./version.js";
 import { serviceInstalled, servicesUnavailable } from "./service.js";
@@ -33,7 +36,7 @@ const git = (args, cwd) => {
 };
 function claudeLocalOverride(projectDir) {
     try {
-        const doc = JSON.parse(readFileSync(join(homedir(), ".claude.json"), "utf8"));
+        const doc = parseJsonText(readFileSync(join(homedir(), ".claude.json"), "utf8"));
         const norm = (x) => resolve(x).replace(/\\/g, "/").replace(/\/+$/, "").toLowerCase();
         const want = norm(projectDir);
         return Object.entries(doc.projects ?? {}).some(([k, v]) => norm(k) === want && !!v?.mcpServers?.["pantheon"]);
@@ -42,6 +45,46 @@ function claudeLocalOverride(projectDir) {
         return false;
     }
 }
+export function userScopeWiring(home = homedir(), present = onPathNamed, env = process.env) {
+    const json = (file, pick) => {
+        if (!existsSync(file))
+            return "missing";
+        try {
+            return pick(parseJsonText(stripJsonc(readFileSync(file, "utf8")))) ? "wired" : "missing";
+        }
+        catch {
+            return "invalid";
+        }
+    };
+    const server = (key) => (d) => !!d[key]?.["pantheon"];
+    const out = [];
+    if (present("claude")) {
+        const f = join(home, ".claude.json");
+        out.push({ agent: "Claude Code", file: f, state: json(f, server("mcpServers")) });
+    }
+    if (present("cursor-agent") || existsSync(join(home, ".cursor"))) {
+        const f = join(home, ".cursor", "mcp.json");
+        out.push({ agent: "Cursor", file: f, state: json(f, server("mcpServers")) });
+    }
+    if (present("codex")) {
+        const f = join(home, ".codex", "config.toml");
+        let state = "missing";
+        try {
+            state = /^\s*\[mcp_servers\.pantheon\]/m.test(readFileSync(f, "utf8")) ? "wired" : "missing";
+        }
+        catch { }
+        out.push({ agent: "Codex", file: f, state });
+    }
+    if (present("copilot")) {
+        const f = copilotMcpConfigFile(home, env);
+        out.push({ agent: "Copilot", file: f, state: json(f, server("mcpServers")) });
+    }
+    if (present("kiro-cli")) {
+        const f = kiroMcpConfigFile(home, env);
+        out.push({ agent: "Kiro", file: f, state: json(f, server("mcpServers")) });
+    }
+    return out;
+}
 function isPrivate(host) {
     const h = host.replace(/:\d+$/, "");
     if (/^(localhost|127\.0\.0\.1|\[::1\]|::1)$/.test(h))
@@ -62,13 +105,16 @@ function isPrivate(host) {
         return true;
     return false;
 }
+export function nodeSupported(version) {
+    const [major = 0, minor = 0] = version.replace(/^v/, "").split(".").map(Number);
+    return major > 23 || (major === 23 && minor >= 4) || (major === 22 && minor >= 13);
+}
 export async function doctor(projectDir) {
     const out = [];
     const add = (level, name, detail, fix, share) => out.push({ level, name, detail, ...(fix ? { fix } : {}), ...(share ? { share } : {}) });
-    const major = Number(process.versions.node.split(".")[0]);
-    major >= 22
+    nodeSupported(process.versions.node)
         ? add("pass", "node", `v${process.versions.node}`, undefined, `v${process.versions.node}`)
-        : add("fail", "node", `v${process.versions.node} is too old`, "pantheon needs Node 22 or newer (the relay uses node:sqlite) — install it and re-run", `v${process.versions.node}, too old`);
+        : add("fail", "node", `v${process.versions.node} is too old`, "pantheon needs Node 22.13 or newer — node:sqlite, which the relay uses, is behind a flag through 22.12 — install a current Node LTS and re-run", `v${process.versions.node}, too old`);
     const host = hostEnv();
     if (host.ephemeral) {
         add("warn", "machine", `${platformName(host.platform)} in ${host.kind === "container" ? "a container" : "a cloud workspace"} — ${host.evidence.join("; ")}`, `this is not the computer you work on, which is why it reports ${platformName(host.platform)} to someone who may be sitting at a Mac. The team and your account are fine here, but the menu bar, desktop alerts and the worker belong on your own machine — run the setup from a terminal there.`, `${host.platform} in ${host.kind === "container" ? "a container" : "a cloud workspace"}`);
@@ -92,14 +138,15 @@ export async function doctor(projectDir) {
     add("pass", "config", `${cfg.member} in "${cfg.space}" via ${cfg.relay}  (${CONFIG_PATH})`, undefined, "present");
     const here = resolveFor(projectDir, { strict: true });
     const nTeams = Object.keys(loadAll()?.spaces ?? {}).length;
+    const folderHere = here.reason === "binding" && !here.repo;
     if (here.reason === "binding")
-        add("pass", "team", `this repo is bound to "${here.cfg.space}"${here.repo?.origin ? ` (${here.repo.origin})` : ""}`, undefined, `this repo is bound to a team (${nTeams} on this machine)`);
+        add("pass", "team", folderHere ? `this folder is bound to "${here.cfg.space}" (${here.binding?.path ?? projectDir}) — no git needed` : `this repo is bound to "${here.cfg.space}"${here.repo?.origin ? ` (${here.repo.origin})` : ""}`, undefined, `this ${folderHere ? "folder" : "repo"} is bound to a team (${nTeams} on this machine)`);
     else if (here.reason === "single")
         add("pass", "team", `"${cfg.space}" — your only team, so every folder resolves to it`, undefined, "one team on this machine");
     else if (here.reason === "unbound")
         add("fail", "team", `this folder is not bound to any of your ${nTeams} teams — agents opened here will refuse to send`, `from the team's checkout: pantheon use <team> --here   (pantheon spaces lists them)`, `folder not bound to any of ${nTeams} teams`);
     else if (here.reason === "stale")
-        add("fail", "team", `this repo is bound to a team this machine has left (${here.binding?.space})`, "pantheon use <team> --here, or pantheon join <invite>", "bound to a team this machine has left");
+        add("fail", "team", `this ${here.repo ? "repo" : "folder"} is bound to a team this machine has left (${here.binding?.space})`, "pantheon use <team> --here, or pantheon join <invite>", "bound to a team this machine has left");
     if (here.repo && !here.repo.shared)
         add("warn", "team", "this repo has no origin remote", "DELIVERED must name a commit a teammate can fetch; add a remote before delivering", "repo has no origin remote");
     const nonce = "doctor-selftest";
@@ -117,12 +164,12 @@ export async function doctor(projectDir) {
     }
     const mcpFile = join(projectDir, ".mcp.json");
     if (!existsSync(mcpFile)) {
-        add("warn", "mcp entry", "no .mcp.json in this project", "run `pantheon install`", "no .mcp.json in this project");
+        add("pass", "mcp entry", "no .mcp.json in this project — your agents are wired for your user (see below), so there is nothing to commit", undefined, "none in the project (user scope)");
     }
     else {
         let entry = {};
         try {
-            entry = (JSON.parse(readFileSync(mcpFile, "utf8")).mcpServers ?? {}).pantheon ?? {};
+            entry = (parseJsonText(stripJsonc(readFileSync(mcpFile, "utf8"))).mcpServers ?? {}).pantheon ?? {};
         }
         catch { }
         if (!entry.command) {
@@ -143,11 +190,29 @@ export async function doctor(projectDir) {
             add("fail", "mcp entry", `hard-codes this machine: ${entry.command}`, "make sure `pantheon` is on your PATH, then run `pantheon install` again — it writes the portable `pantheon mcp` entry. Committed as-is it silently fails on the other machine: the MCP server never starts and no error is shown.", "hard-codes a path on this machine");
         }
     }
+    {
+        const rows = userScopeWiring();
+        const wired = rows.filter((r) => r.state === "wired");
+        const bad = rows.filter((r) => r.state !== "wired");
+        if (rows.length && !bad.length) {
+            add("pass", "user wiring", `pantheon is wired at user scope for ${wired.map((r) => r.agent).join(", ")}`, undefined, `wired for ${wired.length} agent${wired.length === 1 ? "" : "s"}`);
+        }
+        else if (rows.length) {
+            const said = bad.map((r) => `${r.agent}: ${r.state === "invalid" ? `${r.file} does not parse` : `no pantheon server in ${r.file}`}`).join("; ");
+            const fix = bad.some((r) => r.state === "invalid")
+                ? "fix the file that does not parse (setup never overwrites it), then run `pantheon install --user`"
+                : "run `pantheon install --user` — and if it says failed, the line it prints is why";
+            add(wired.length || existsSync(mcpFile) ? "warn" : "fail", "user wiring", said, fix, `${bad.length} of ${rows.length} agent${rows.length === 1 ? "" : "s"} not wired at user scope`);
+        }
+    }
     onPath()
         ? add("pass", "PATH", "`pantheon` resolves by name", undefined, "pantheon resolves by name")
         : add("warn", "PATH", "`pantheon` is not on PATH", "install it globally (`npm install -g @join-pantheon/cli`) and make sure your npm global bin dir (`npm bin -g`) is on PATH", "pantheon is not on PATH");
     const inRepo = git(["rev-parse", "--is-inside-work-tree"], projectDir) === "true";
-    if (!inRepo) {
+    if (!inRepo && folderHere) {
+        add("pass", "git", "a plain folder — messages, questions and decisions work here; code is handed over from a repo", undefined, "plain folder, no git needed");
+    }
+    else if (!inRepo) {
         add("warn", "git", `${projectDir} is not a git repo`, "DELIVERED requires a pushed branch + commit, so the work needs to live in a repo you both clone", "not a git repo");
     }
     else {
@@ -165,20 +230,28 @@ export async function doctor(projectDir) {
         : add("warn", "agent cli", "found none of claude / codex / cursor-agent / copilot / kiro-cli on PATH", "fine if you only drive agents through a GUI (Conductor, Cursor, VS Code, the Kiro IDE), but `pantheon worker` needs a CLI to spawn", "none of claude / codex / cursor-agent / copilot / kiro-cli on PATH");
     if (agents.length) {
         try {
-            const choice = chooseAgent("auto", { prefer: prof.agent.primary_surface });
+            let unsandboxedOk = false;
+            try {
+                unsandboxedOk = unsandboxedAllowed(loadPolicy());
+            }
+            catch { }
+            const choice = chooseAgent("auto", { prefer: prof.agent.primary_surface, unsandboxedOk });
             const line = describeChoice(choice);
             const bad = choice.signIn && !choice.signIn.ok && !choice.signIn.unknown;
             const fellBack = !!prof.agent.primary_surface && choice.backend.id !== prof.agent.primary_surface && agents.length > 0;
             const shareLine = `${choice.backend.label} — ${choice.signIn?.detail ?? "not checked"}${choice.skipped.length ? `; ${skippedSummary(choice)}` : ""}`;
-            const refused = unattendedRefusal(choice);
+            const refused = unattendedRefusal(choice, { unsandboxedOk });
+            const surface = prof.agent.primary_surface ? agentById(prof.agent.primary_surface) : undefined;
             if (refused)
-                add("warn", "worker agent", line, `woken runs are refused here, not tried: ${refused}`, shareLine);
+                add("warn", "worker agent", line, `teammates' requests wait for your next session here: ${refused}`, shareLine);
             else if (bad)
                 add("warn", "worker agent", line, `nothing is signed in, so every woken run here fails until you sign in: ${choice.skipped.map((x) => x.why).join("; ") || "sign in to the agent CLI"}`, shareLine);
             else if (fellBack)
                 add("warn", "worker agent", line, prof.agent.primary_surface === "kiro"
-                    ? `you chose Kiro at setup; Kiro cannot yet be fenced to its worktree for unattended runs, so runs use ${choice.backend.label}`
-                    : `you chose ${prof.agent.primary_surface} at setup; runs use ${choice.backend.label} until it is signed in again`, shareLine);
+                    ? `you chose Kiro at setup; Kiro answers in your live sessions, and runs while you're away use ${choice.backend.label}`
+                    : surface && !SANDBOXED_FOR_UNATTENDED.has(surface.id) && !unsandboxedOk
+                        ? `you chose ${surface.label} at setup; runs while you're away use ${choice.backend.label} in its sandbox (to have ${surface.label} answer them: pantheon policy grant unsandboxed-runs)`
+                        : `you chose ${prof.agent.primary_surface} at setup; runs use ${choice.backend.label} until it is signed in again`, shareLine);
             else
                 add("pass", "worker agent", line, undefined, shareLine);
         }
@@ -245,11 +318,17 @@ export async function doctor(projectDir) {
     try {
         const res = await fetch(health, { signal: AbortSignal.timeout(5000) });
         const body = (await res.json());
-        if (!body.ok) {
+        if (!body.ok && body.storage) {
+            const since = body.storage.at ? ` (since ${new Date(body.storage.at).toLocaleString()})` : "";
+            add("fail", "relay", `the relay cannot write to its disk: ${body.storage.error ?? "unknown error"}${since}`, hosted ? `this is on the hosted relay's side — nothing on this machine can fix it; tell us at ${FEEDBACK_ADDRESS}` : "free space or fix permissions on the relay host's data folder, then restart the relay", `cannot write to its disk (${where})`);
+        }
+        else if (!body.ok) {
             add("fail", "relay", `answered but not healthy: ${JSON.stringify(body)}`, undefined, `answered but not healthy (${where})`);
         }
         else {
             add("pass", "relay", `reachable at ${health}`, undefined, `reachable (${where})`);
+        }
+        if (body.ok || body.storage) {
             if (body.pkg && body.pkg !== VERSION) {
                 add("warn", "version", `this machine is ${VERSION}, the relay is ${body.pkg}`, "run `pantheon upgrade` on the older side — features land on both halves of the wire, and the protocol version cannot tell you they are missing", `this machine ${VERSION}, relay ${body.pkg}`);
             }
@@ -298,18 +377,66 @@ export async function doctor(projectDir) {
             .map((p) => `${p.member}[${online.has(p.member) ? "online" : "no session open"}]`).join("  "), undefined, `${admittedPeers.length} admitted, ${peersOnline} with a session open`)
         : add("warn", "peers", "nobody else is admitted to this space yet", "send your teammate an invite from `pantheon invite` (or the one `pantheon start` printed)", "nobody else admitted yet");
     if (pending.length) {
-        add("warn", "pending", pending.map((p) => `${p.member} (${p.fingerprint})`).join("  "), `confirm the fingerprint by voice, then: pantheon admit ${pending[0].member}   (add --may-wake only if they should be able to wake this machine)`, `${pending.length} waiting to be admitted`);
+        add("warn", "pending", pending.map((p) => `${p.member} (${p.fingerprint})`).join("  "), `confirm the fingerprint by voice, then: pantheon admit ${pending[0].member}   (add --may-wake only if the team should let them wake workers; each of you then allows them on your own machine: pantheon wake allow <name>)`, `${pending.length} waiting to be admitted`);
     }
     const wakers = client.members.filter((m) => m.admitted && m.may_wake && m.member !== cfg.member);
     const hookStates = agentHookStates(projectDir);
     const hook = hookStates[0] ?? hookState(projectDir);
     const reportsActivity = hookStates.some((s) => s.events?.some((e) => /prompt|UserPromptSubmit|beforeSubmitPrompt/i.test(e))) || (hook.events?.includes("UserPromptSubmit") ?? false);
+    {
+        const { loadPins, pinsPath } = await import("./pins.js");
+        const { brokenStateFiles, brokenStateFix } = await import("./file-lock.js");
+        const { dirname } = await import("node:path");
+        const broken = brokenStateFiles(dirname(pinsPath()));
+        if (broken.length)
+            add("fail", "signing", `${broken.join(", ")} in ${dirname(pinsPath())} cannot be read and written — they are what stops a request being run twice, so the worker holds every unattended run until they are fixed`, brokenStateFix(broken), "state files broken");
+        const all = loadPins();
+        if (all.corrupt)
+            add("fail", "signing", `${pinsPath()} could not be read — no message is trusted until it can be`, "restore it from a backup, or remove it to pin teammates' keys afresh (then check each with them: pantheon trust)", "keys.json unreadable");
+        const t = all.teams[client.pinKey()];
+        const pending = Object.entries(t?.members ?? {}).filter(([, p]) => p.pending).map(([m]) => m);
+        const n = Object.keys(t?.members ?? {}).filter((m) => m !== cfg.member).length;
+        if (client.features.includes("act-sig")) {
+            if (pending.length)
+                add("warn", "signing", `${pending.join(", ")}'s key changed — their messages are not trusted here until you check the new key with them`, `pantheon trust ${pending[0]}`, `${pending.length} key change${pending.length === 1 ? "" : "s"} waiting`);
+            else
+                add("pass", "signing", `messages are signed; this machine checks them against ${n} teammate key${n === 1 ? "" : "s"} it pinned (pantheon trust lists them)`, undefined, `signed; ${n} keys pinned`);
+        }
+        else if (t?.sigs || client.signaturesExpected()) {
+            add("fail", "signing", "this team's relay does not carry signatures, though this machine expects them (it signed before, or you joined with 0.31+) — requests are not run here until it does", "check the relay's version with its operator (pantheon doctor on a teammate's machine)", "relay stopped carrying signatures");
+        }
+        else {
+            add("warn", "signing", "this team's relay does not carry signatures yet (a relay before 0.31), so messages cannot be checked against their senders' keys", "upgrade the relay", "relay without signatures");
+        }
+    }
     const workerUp = workerProc().running;
-    if (!wakers.length) {
-        add("warn", "wake rights", "no peer may wake a worker on this machine", "that is a safe default; grant it with `pantheon admit <them> --may-wake` when you want unattended replies", `no peer may wake; worker ${workerUp ? "running" : "not running"}`);
+    const mode = wakeMode(loadProfile(cfg));
+    const anyoneWhy = loadProfile(cfg).agent.wake_default === "anyone" ? "you chose \"anyone\"" : "\"anyone\" is the default";
+    const policy = loadPolicy();
+    const approvedHere = admittedPeers.filter((m) => isApprovedWaker(policy, [client.spaceId ?? cfg.spaceId, cfg.space], m.member));
+    const teamKey = client.spaceId ?? cfg.spaceId ?? cfg.space;
+    const notCarried = mode === "approved" && !policy.wakersCarried?.[teamKey] && !policy.wakersCarried?.[cfg.space] && !relayKnowsAdmitters(client.members, cfg.member);
+    const effective = mode === "anyone" || notCarried ? wakers : mode === "no" ? [] : approvedHere.filter((m) => m.may_wake);
+    const blockedByTeam = mode === "approved" ? approvedHere.filter((m) => !m.may_wake) : [];
+    const noSvcHere = servicesUnavailable(host.platform);
+    if (!effective.length && mode === "approved" && !blockedByTeam.length && !notCarried) {
+        if (workerUp)
+            add("pass", "wake rights", "nobody approved yet — you are asked the first time a teammate's request needs this machine (Always / Just this once / No)", undefined, "ask on first request; worker running");
+        else
+            add("warn", "wake rights", "no worker is running here, so teammates' requests wait for you — and nobody is asked", noSvcHere ? "Pantheon does not run in the background on Windows yet, so a peer's act waits until your agent is open" : "start it: pantheon service install worker (it serves every repo and folder bound here)", "ask on first request; worker not running");
+    }
+    else if (!effective.length) {
+        const why = mode === "no" ? "this machine is set not to be woken"
+            : mode === "anyone" ? `${anyoneWhy}, and the team lets nobody wake workers`
+                : blockedByTeam.length ? `approved here: ${blockedByTeam.map((m) => m.member).join(", ")}, but the team does not let them wake workers yet`
+                    : "nobody is approved on this machine";
+        add("warn", "wake rights", `no teammate can wake a worker on this machine — ${why}`, mode === "no" ? "that is what you chose; pantheon setup to change it"
+            : blockedByTeam.length ? `a member runs: pantheon admit ${blockedByTeam[0].member} --may-wake`
+                : "that is a safe default; let one teammate wake this machine with `pantheon wake allow <name>` when you want unattended replies", `nobody can wake this machine (${mode}); worker ${workerUp ? "running" : "not running"}`);
     }
     else {
-        const who = `${wakers.map((m) => m.member).join(", ")} may wake a worker (space-wide grant)`;
+        const who = `${effective.map((m) => m.member).join(", ")} can wake a worker here (${mode === "anyone" ? anyoneWhy : notCarried ? "the team's may_wake decides until this relay is 0.30 or newer" : "approved on this machine"})`;
+        const wakers = effective;
         if (workerUp) {
             add("pass", "wake rights", `${who} — worker is running`, undefined, `${wakers.length} may wake; worker running`);
         }
@@ -317,7 +444,48 @@ export async function doctor(projectDir) {
             const noSvc = servicesUnavailable(host.platform);
             add("warn", "wake rights", `${who}, but no worker is running here, so nothing can be woken`, noSvc
                 ? "Pantheon does not run in the background on Windows yet, so a peer's act waits until your agent is open"
-                : "start one with `pantheon service install worker --project <a git repo>`; until then a peer's act waits for you to type", `${wakers.length} may wake; worker not running`);
+                : "start one with `pantheon service install worker` (it serves every repo and folder bound here); until then a peer's act waits for you to type", `${wakers.length} may wake; worker not running`);
+        }
+    }
+    {
+        const f = loadAll();
+        const m = f && Object.values(f.spaces ?? {}).find((x) => x.id === (client.spaceId ?? cfg.spaceId) || x.name === cfg.space);
+        if (f && m) {
+            const { teamWorkspaces } = await import("./worker-fleet.js");
+            const ws = teamWorkspaces(f, m.id);
+            const fps = new Set(ws.map((w) => w.fp).filter(Boolean));
+            const missing = (m.repos ?? []).filter((r) => !fps.has(r.fp)).map((r) => r.name);
+            if (ws.length) {
+                add("pass", "worker serves", `${ws.map((w) => `${w.name}${w.kind === "folder" ? " (folder)" : ""}`).join(", ")}${missing.length ? ` — not on this machine: ${missing.join(", ")}` : ""}`, missing.length ? "requests about those are told they wait for you; clone them, then: pantheon repo find" : undefined, `${ws.length} workspace${ws.length === 1 ? "" : "s"}${missing.length ? `, ${missing.length} team repo${missing.length === 1 ? "" : "s"} not here` : ""}`);
+            }
+        }
+    }
+    {
+        const cs = commandState({ project: projectDir });
+        let servesRepo = true;
+        try {
+            const f = loadAll();
+            const m = f && Object.values(f.spaces ?? {}).find((x) => x.id === (client.spaceId ?? cfg.spaceId) || x.name === cfg.space);
+            if (f && m) {
+                const ws = (await import("./worker-fleet.js")).teamWorkspaces(f, m.id);
+                servesRepo = !ws.length || ws.some((w) => w.kind === "repo");
+            }
+        }
+        catch { }
+        if (!servesRepo)
+            add("pass", "commands", "not used here — a docs folder is read and answered from, never run in", undefined, "docs folder only; commands not used");
+        else {
+            const { commandCaveat } = await import("./command-state.js");
+            const caveat = cs.level !== "off" ? commandCaveat() : "";
+            if (caveat)
+                add("warn", "commands", `woken runs: ${cs.summary} — ${caveat}`, undefined, "how woken runs here use commands");
+            else
+                add("pass", "commands", `woken runs: ${cs.summary}`, undefined, cs.level === "off" ? "woken runs edit files only" : `woken runs may run commands (${cs.allowBash ? "--allow-bash" : "granted here"})`);
+        }
+        if (cs.level !== "off" && host.platform === "linux") {
+            const missing = ["bwrap", "socat"].filter((b) => !onPathNamed(b, "linux"));
+            if (missing.length)
+                add("warn", "sandbox", `${missing.join(" and ")} not found — Claude Code's sandbox cannot start, so every woken command run will be refused`, "install them: sudo apt install bubblewrap socat (Debian/Ubuntu) or sudo dnf install bubblewrap socat (Fedora)", `sandbox tools missing: ${missing.join(", ")}`);
         }
     }
     if (host.desktop) {

package/dist/file-lock.js

@@ -0,0 +1,197 @@
+import { closeSync, existsSync, linkSync, mkdirSync, openSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { randomBytes } from "node:crypto";
+import { dirname, join } from "node:path";
+const STALE_MS = 15_000;
+const WAIT_MS = 20_000;
+const sleepSync = (ms) => { try {
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+catch { } };
+const readLock = (lock) => { try {
+    return readStateFile(lock);
+}
+catch {
+    return null;
+} };
+function alive(pid) {
+    if (!Number.isInteger(pid) || pid <= 0)
+        return false;
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (e) {
+        return e.code === "EPERM";
+    }
+}
+function stale(lock, content) {
+    let age;
+    try {
+        age = Math.abs(Date.now() - statSync(lock).mtimeMs);
+    }
+    catch {
+        return false;
+    }
+    if (age > STALE_MS)
+        return true;
+    const m = /^(\d+) [0-9a-f]{24}$/.exec(content ?? "");
+    if (!m)
+        return age > 1_000;
+    return !alive(Number(m[1])) && age > 50;
+}
+const clear = (p) => { try {
+    rmSync(p, { recursive: true, force: true });
+}
+catch { } };
+function takeOver(lock, seen) {
+    const brk = `${lock}.break`;
+    const mine = `${brk}.${process.pid}.${randomBytes(4).toString("hex")}`;
+    try {
+        writeFileSync(mine, "", { flag: "wx", mode: 0o600 });
+    }
+    catch {
+        return;
+    }
+    try {
+        try {
+            linkSync(mine, brk);
+        }
+        catch {
+            try {
+                const st = statSync(brk);
+                if (!st.isFile() || Math.abs(Date.now() - st.mtimeMs) > 5_000)
+                    clear(brk);
+            }
+            catch { }
+            return;
+        }
+        try {
+            const now = readLock(lock);
+            if (now !== seen || !stale(lock, now))
+                return;
+            const aside = `${lock}.stale.${process.pid}.${randomBytes(4).toString("hex")}`;
+            try {
+                renameSync(lock, aside);
+            }
+            catch {
+                clear(lock);
+                return;
+            }
+            if (readLock(aside) !== seen) {
+                try {
+                    linkSync(aside, lock);
+                }
+                catch { }
+            }
+            clear(aside);
+        }
+        finally {
+            try {
+                rmSync(brk, { force: true });
+            }
+            catch { }
+        }
+    }
+    finally {
+        try {
+            rmSync(mine, { force: true });
+        }
+        catch { }
+    }
+}
+export function readStateFile(p) {
+    let st;
+    try {
+        st = statSync(p);
+    }
+    catch {
+        return null;
+    }
+    if (!st.isFile())
+        throw new Error(`${p} is not a plain file`);
+    return readFileSync(p, "utf8");
+}
+export function brokenStateFiles(dir) {
+    const out = [];
+    if (existsSync(dir)) {
+        const probe = join(dir, `.write-check.${randomBytes(4).toString("hex")}`);
+        try {
+            writeFileSync(probe, "", { flag: "wx", mode: 0o600 });
+            rmSync(probe, { force: true });
+        }
+        catch {
+            out.push("(the folder)");
+        }
+    }
+    for (const f of ["nonces.json", "continued.json", "keys.json"]) {
+        const p = join(dir, f);
+        try {
+            const text = readStateFile(p);
+            if (text === null)
+                continue;
+            JSON.parse(text);
+            closeSync(openSync(p, "r+"));
+        }
+        catch {
+            out.push(f);
+        }
+    }
+    return out;
+}
+export function brokenStateFix(broken) {
+    const files = broken.filter((b) => b !== "(the folder)");
+    const parts = [];
+    if (broken.includes("(the folder)"))
+        parts.push("make the Pantheon folder writable again (its permissions) — do not delete it: it holds your key and memberships");
+    if (files.length)
+        parts.push(`repair or delete ${files.join(", ")} (one made read-only or locked: make it writable again; one that is a folder or not a file: delete it)`);
+    return parts.join("; ");
+}
+export function withFileLock(f, fn) {
+    mkdirSync(dirname(f), { recursive: true, mode: 0o700 });
+    const lock = `${f}.lock`;
+    const token = `${process.pid} ${randomBytes(12).toString("hex")}`;
+    const deadline = Date.now() + WAIT_MS;
+    const made = `${lock}.${randomBytes(6).toString("hex")}.new`;
+    writeFileSync(made, token, { mode: 0o600, flag: "wx" });
+    try {
+        for (;;) {
+            let got = false;
+            try {
+                linkSync(made, lock);
+                got = true;
+            }
+            catch (e) {
+                const code = e.code;
+                if (code !== "EEXIST" && !(process.platform === "win32" && (code === "EPERM" || code === "EACCES" || code === "EBUSY")))
+                    throw e;
+            }
+            if (got)
+                break;
+            const content = readLock(lock);
+            if (stale(lock, content))
+                takeOver(lock, content);
+            if (Date.now() > deadline)
+                throw new Error(`${f} is locked by another pantheon process (${lock})`);
+            sleepSync(2 + Math.floor(Math.random() * 8));
+        }
+    }
+    finally {
+        try {
+            rmSync(made, { force: true });
+        }
+        catch { }
+    }
+    try {
+        return fn();
+    }
+    finally {
+        if (readLock(lock) === token) {
+            try {
+                rmSync(lock, { force: true });
+            }
+            catch { }
+        }
+    }
+}
+//# sourceMappingURL=file-lock.js.map

package/dist/grants.js

@@ -18,7 +18,7 @@ function readJson(file) {
     if (!existsSync(file))
         return null;
     try {
-        return JSON.parse(readFileSync(file, "utf8"));
+        return JSON.parse(readFileSync(file, "utf8").replace(/^\uFEFF/, ""));
     }
     catch {
         return "invalid";

package/dist/history-view.js

@@ -34,7 +34,8 @@ export function resolveRef(acts, ref, act, goal, me) {
     }
     const others = acts.filter((a) => a.from !== me && a.act !== "JOIN" && a.act !== "LEAVE" && inGoal(a));
     if (ref === "last") {
-        const hit = others[others.length - 1];
+        const can = REPLIES_TO[act];
+        const hit = (can ? [...others].reverse().find((a) => can.includes(a.act)) : undefined) ?? others[others.length - 1];
         return hit ? { id: hit.id, goal: hit.goal ?? goal, note: `replying to [${hit.seq}] ${hit.act} from ${hit.from}` } : { id: null, goal, error: "nothing from a peer to reply to" };
     }
     if (ref)