@join-pantheon/cli 0.26.5 → 0.28.0

package/README.md

@@ -404,7 +404,7 @@ with no human; the cap and lock governors under two workers per member.
 
 ### Which agent answers
 
-The worker runs whichever agent CLI this machine has — `--agent claude-code|codex|cursor|copilot|auto`.
+The worker runs whichever agent CLI this machine has — `--agent claude-code|codex|cursor|copilot|kiro|auto`.
 With `auto` (the default) the order is: the agent a persona pins, then the one you chose at setup,
 then PATH order — and a candidate that is not signed in is skipped and named in the run log, so a
 run never fails on an expired session when another agent could have answered. If nothing is
@@ -418,6 +418,7 @@ actually works, with the same "no shell unless you said so" rule spelled in its
 | codex | `--sandbox read-only` (codex has no edits-without-shell mode) | `--sandbox workspace-write` |
 | cursor | proposes edits, never applies (`-p` without `--force`) | `--force` |
 | copilot | `--allow-tool=pantheon-worker --allow-tool=write` (edits without shell, Copilot's `write` kind) | `--allow-all-tools` |
+| kiro | an agent whose tools are pantheon's plus `read`, `write`, `grep`, `glob` — all pre-approved | the same, plus `shell` |
 
 Claude Code, Cursor and Codex are verified with **real live woken runs** — an idle machine answering a
 peer's ASK end to end. Codex quirks the tooling handles for
@@ -458,6 +459,58 @@ named as that, with `copilot login` as the fix.
 also restrict MCP servers to an approved registry; the server is called `pantheon` and its only job
 is moving messages between your teammates' agents — nothing here reads code or runs commands.
 
+### Kiro
+
+Kiro is one backend covering the **Kiro CLI** (`kiro-cli`) and the **Kiro IDE**, both of which read
+`~/.kiro/settings/mcp.json`; `pantheon install --user` writes pantheon there. Everything below about
+the CLI was checked live against kiro-cli 2.23.1.
+
+**Sessions report presence on their own.** The entry names its agent (`PANTHEON_AGENT=kiro`), so a Kiro
+session is labelled Kiro to your teammates and reports busy and idle through its own MCP server. Without
+that label it would take the machine's main agent as its own, and on a Claude Code machine report nothing.
+There is deliberately no repo-level Kiro file: Kiro uses a workspace-level server of the same name whole,
+so a committed copy would replace each teammate's own entry.
+
+**Approval.** The entry's `autoApprove` list carries your approval choice, and the Kiro IDE honours it.
+The Kiro CLI ignores it — its default agent asks before each Pantheon call, and has no setting that
+changes that.
+
+**The `pantheon` agent, for the CLI.** In kiro-cli the only hooks that fire are the ones inside an agent
+file; neither of its engines reads the standalone `.kiro/hooks/` files, and the built-in default agent
+cannot carry any. So `pantheon hook install` adds an agent called `pantheon`: Kiro's default — the same
+tools (`tools: ["*"]`) and your own MCP servers (`includeMcpJson: true`) — plus Pantheon's tools
+pre-approved per your choice, a `userPromptSubmit` hook that reports a turn as started and prints
+nothing, and a `stop` hook that holds the turn open while a teammate waits. It is opt-in and nothing
+makes it your default:
+
+```
+kiro-cli chat --agent pantheon           # this session
+kiro-cli agent set-default pantheon      # every session
+```
+
+Checked live: with a teammate's question waiting and a prompt that said only "reply HELLO", the agent
+replied, the stop hook held the turn, and it read, claimed and answered the question through Pantheon
+without one approval prompt. An agent called `pantheon` that you wrote yourself is never overwritten.
+
+**Woken runs.** A woken Kiro run is its own agent, `pantheon-worker`, in a `KIRO_HOME` of its own outside
+the checkout. That matters: Kiro starts every MCP server in its config whatever the agent says, so your own
+pantheon entry would otherwise join every run as a second server reporting you present. The run's home
+holds only its agent and your Kiro settings; your sign-in, which lives in Kiro's data store, still applies.
+The agent's `tools` and `allowedTools` are one list — Pantheon's server and `read`, `write`, `grep`,
+`glob`, with `shell` only under `--allow-bash` — so nothing it can reach needs approval, and no trust flag
+is passed. A repo's own committed Kiro MCP servers still start, as the repo's tooling; their tools are not
+in the run's list, and one that fails does not stop the run.
+
+**Sign in once with `kiro-cli login`, or set `KIRO_API_KEY`.** Signed out, Kiro does not fail: it opens a
+browser to log in and waits. So a woken run is never started with Kiro signed out, even when a persona pins
+Kiro or it is the only agent on the machine; the run is refused with the reason, and `pantheon doctor` says
+so first. Pantheon reads the sign-in with `kiro-cli whoami --format json`, and only once Kiro has run on the
+machine, because on a fresh install that one call creates `~/.kiro` and Kiro's data store.
+
+Not supported: Kiro Crew, which is itself an always-on agent runner and would be a second answerer beside
+Pantheon's worker, and Kiro Mobile, which has nowhere to load an MCP server. The Kiro IDE's own hooks are
+not wired, because they could not be checked here; IDE sessions get the MCP entry and presence.
+
 ### Personas — telling the worker who to be
 
 A worker with no instructions escalates too much and trusts too much. A **persona** is one

package/dist/agents.js

@@ -1,8 +1,9 @@
 import { execFileSync } from "node:child_process";
+import { randomBytes } from "node:crypto";
 import { copyFileSync, existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
 import { homedir, platform } from "node:os";
 import { join, dirname, isAbsolute } from "node:path";
-import { launcher } from "./install.js";
+import { launcher, kiroDir } from "./install.js";
 import { agentSpawn, which } from "./which.js";
 import { PANTHEON_TOOL_NAMES, PANTHEON_TOOLS } from "./tools.js";
 export function launchArgs(agent, prompt, name) {
@@ -10,6 +11,8 @@ export function launchArgs(agent, prompt, name) {
         return ["--name", name, prompt];
     if (agent === "copilot")
         return ["-n", name, "-i", prompt];
+    if (agent === "kiro")
+        return ["chat", prompt];
     return [prompt];
 }
 export const AGENTS = [
@@ -17,7 +20,11 @@ export const AGENTS = [
     { id: "codex", label: "Codex", binaries: ["codex"] },
     { id: "cursor", label: "Cursor", binaries: ["cursor-agent", "agent"] },
     { id: "copilot", label: "Copilot", binaries: ["copilot"] },
+    { id: "kiro", label: "Kiro", binaries: ["kiro-cli"] },
 ];
+export function kiroHome(home = homedir(), env = process.env) {
+    return kiroDir(home, env);
+}
 export function copilotHome(home = homedir(), env = process.env) {
     return env.COPILOT_HOME || join(home, ".copilot");
 }
@@ -57,6 +64,11 @@ export function detectForHooks(projectDir = process.cwd()) {
                 out.push(backend);
             continue;
         }
+        if (backend.id === "kiro") {
+            if (existsSync(kiroHome()) || existsSync(join(projectDir, ".kiro")))
+                out.push(backend);
+            continue;
+        }
         const userDir = backend.id === "claude-code" ? join(homedir(), ".claude")
             : backend.id === "codex" ? join(homedir(), ".codex")
                 : join(homedir(), ".cursor");
@@ -107,7 +119,28 @@ export const SIGN_IN_CHECK = {
     codex: { args: ["login", "status"], fix: "run `codex login`" },
     cursor: { args: ["status"], fix: "run `cursor-agent login`" },
     copilot: { args: [], fix: "run `copilot login` (or `gh auth login` — copilot uses gh's sign-in too)" },
+    kiro: { args: ["whoami", "--format", "json"], fix: "run `kiro-cli login` (or set KIRO_API_KEY)" },
 };
+export const NEEDS_SIGN_IN_BEFORE_SPAWN = new Set(["kiro"]);
+export function kiroSignedIn(binary, run = runStatus, env = process.env, home = homedir(), os = platform()) {
+    if (env.KIRO_API_KEY)
+        return { ok: true, detail: "signed in (KIRO_API_KEY in the environment)" };
+    if (!kiroHasRunHere(home, env, os))
+        return { ok: false, detail: "never signed in on this machine" };
+    const r = run(binary, SIGN_IN_CHECK.kiro.args);
+    if (r.status === null)
+        return { ok: false, detail: `could not tell (${(r.out.split("\n")[0] ?? "").slice(0, 60) || "no answer"}), so it is not run unattended` };
+    const line = r.out.split("\n").map((l) => l.trim()).reverse().find((l) => l.startsWith("{"));
+    try {
+        const j = JSON.parse(line ?? "");
+        if (typeof j.accountType === "string" && j.accountType)
+            return { ok: true, detail: "signed in" };
+        if ("account" in j)
+            return j.account ? { ok: true, detail: "signed in" } : { ok: false, detail: "not signed in" };
+    }
+    catch { }
+    return { ok: false, detail: "could not tell (kiro-cli whoami answered in a shape this build does not know), so it is not run unattended" };
+}
 export const COPILOT_TOKEN_VARS = ["COPILOT_GITHUB_TOKEN", "GH_TOKEN", "GITHUB_TOKEN"];
 export function copilotSignedIn(run = runStatus, env = process.env, gh = () => !!cliOnPath("gh")) {
     if (COPILOT_TOKEN_VARS.some((k) => env[k]))
@@ -132,10 +165,12 @@ const runStatus = (binary, args) => {
         return { status: err.status ?? null, out: `${err.stdout ?? ""}${err.stderr ?? ""}`.trim() || (err.message ?? "") };
     }
 };
-export const AGENT_HOME_DIR = { "claude-code": ".claude", codex: ".codex", cursor: ".cursor", copilot: ".copilot" };
+export const AGENT_HOME_DIR = { "claude-code": ".claude", codex: ".codex", cursor: ".cursor", copilot: ".copilot", kiro: ".kiro" };
 export function signedIn(backend, binary, run = runStatus, home = homedir()) {
     if (backend.id === "copilot")
         return copilotSignedIn(run);
+    if (backend.id === "kiro")
+        return kiroSignedIn(binary, run, process.env, home);
     if (!existsSync(join(home, AGENT_HOME_DIR[backend.id])))
         return { ok: false, detail: "never signed in on this machine" };
     const check = SIGN_IN_CHECK[backend.id];
@@ -159,14 +194,14 @@ export function chooseAgent(preferred, opts = {}) {
     if (preferred && preferred !== "auto") {
         const backend = agentById(preferred);
         if (!backend)
-            throw new Error(`unknown agent ${preferred} — use claude-code, codex, cursor, copilot, or auto`);
+            throw new Error(`unknown agent ${preferred} — use claude-code, codex, cursor, copilot, kiro, or auto`);
         const hit = available.find((a) => a.backend.id === backend.id);
         if (!hit)
             throw new Error(`${backend.label} is not on PATH (looked for ${backend.binaries.join(", ")})`);
         return { backend, binary: hit.binary, signIn: state(backend, hit.binary), because: "pinned", skipped: [] };
     }
     if (!available.length)
-        throw new Error("no agent CLI on PATH — install claude, codex, cursor-agent, or copilot");
+        throw new Error("no agent CLI on PATH — install claude, codex, cursor-agent, copilot, or kiro-cli");
     const order = [];
     const wanted = opts.prefer ? agentById(opts.prefer) : undefined;
     const chosen = wanted ? available.find((a) => a.backend.id === wanted.id) : undefined;
@@ -182,9 +217,14 @@ export function chooseAgent(preferred, opts = {}) {
             return { backend: c.backend, binary: c.binary, ...(s ? { signIn: s } : {}), because: c.because, skipped };
         skipped.push({ backend: c.backend, why: `${s.detail} — ${SIGN_IN_CHECK[c.backend.id].fix}` });
     }
-    const first = order[0];
+    const first = order.find((o) => !NEEDS_SIGN_IN_BEFORE_SPAWN.has(o.backend.id)) ?? order[0];
     return { backend: first.backend, binary: first.binary, signIn: state(first.backend, first.binary), because: `${first.because} (none signed in)`, skipped };
 }
+export function unattendedRefusal(c) {
+    if (!NEEDS_SIGN_IN_BEFORE_SPAWN.has(c.backend.id) || c.signIn?.ok)
+        return null;
+    return `${c.backend.label} is not signed in (${c.signIn?.detail ?? "not checked"}), and signed out it opens a browser to log in, so it is not started while you are away — ${SIGN_IN_CHECK[c.backend.id].fix}`;
+}
 export function describeChoice(c) {
     const head = `${c.backend.label}${c.signIn ? ` — ${c.signIn.detail}` : ""} (${c.because})`;
     return c.skipped.length ? `${head}; skipped ${c.skipped.map((s) => `${s.backend.label} — ${s.why}`).join("; ")}` : head;
@@ -283,6 +323,30 @@ export function headlessSpawn(opts) {
             ...(opts.runHome && existsSync(settings) ? { copyFiles: [{ from: settings, to: join(home, "settings.json") }] } : {}),
         };
     }
+    if (opts.backend.id === "kiro") {
+        const home = opts.runHome ? join(opts.runHome, "kiro") : join(opts.worktree, ".pantheon", "kiro-home");
+        const tools = [...KIRO_WORKER_TOOLS, ...(opts.allowBash ? ["shell"] : []), `@${KIRO_WORKER_SERVER}`];
+        const agentName = `${KIRO_WORKER_AGENT}-${randomBytes(8).toString("hex")}`;
+        const settings = join(kiroHome(), "settings", "cli.json");
+        return {
+            command: opts.binary,
+            args: ["chat", "--no-interactive", "--agent", agentName, "--require-mcp-startup", "--wrap", "never", opts.prompt],
+            env: { ...procEnv, KIRO_HOME: home, KIRO_NO_AUTO_UPDATE: "1" },
+            writeFiles: [{
+                    path: join(home, "agents", `${KIRO_WORKER_AGENT}.json`),
+                    contents: JSON.stringify({
+                        name: agentName,
+                        description: "A Pantheon run: answers a teammate's request on an isolated branch, while its human is away",
+                        tools,
+                        allowedTools: tools,
+                        includeMcpJson: false,
+                        mcpServers: { [KIRO_WORKER_SERVER]: { command: l.command, args: l.args, env: fileEnv } },
+                        resources: ["file://.kiro/steering/**/*.md"],
+                    }, null, 2),
+                }],
+            ...(opts.runHome && existsSync(settings) ? { copyFiles: [{ from: settings, to: join(home, "settings", "cli.json") }] } : {}),
+        };
+    }
     return {
         command: opts.binary,
         args: [
@@ -310,6 +374,20 @@ export function headlessSpawn(opts) {
     };
 }
 export const COPILOT_WORKER_SERVER = "pantheon-worker";
+export function kiroDataDir(home = homedir(), env = process.env, os = platform()) {
+    if (env.KIRO_DATA_DIR)
+        return env.KIRO_DATA_DIR;
+    if (os === "darwin")
+        return join(home, "Library", "Application Support", "kiro-cli");
+    return null;
+}
+export function kiroHasRunHere(home = homedir(), env = process.env, os = platform()) {
+    const data = kiroDataDir(home, env, os);
+    return data ? existsSync(join(data, "data.sqlite3")) : existsSync(kiroDir(home, env));
+}
+export const KIRO_WORKER_AGENT = "pantheon-worker";
+export const KIRO_WORKER_SERVER = "pantheon";
+export const KIRO_WORKER_TOOLS = ["read", "write", "grep", "glob"];
 function readCopilotConfig() {
     try {
         const doc = JSON.parse(readFileSync(join(copilotHome(), "config.json"), "utf8"));

package/dist/cli.js

@@ -29,7 +29,8 @@ import { menubarProc, notifierProc, relayProc, workerProc, wiring, logFileFor, d
 import { assess } from "./untrusted.js";
 import { report as spendReport, recentRuns } from "./spend.js";
 import { renderBrief, renderTeam } from "./brief.js";
-import { resolveDataDir } from "./config.js";
+import { resolveDataDir, saveAll } from "./config.js";
+import { currentPlan, installNetwork, redactProxy, normalizeProxy, usedSystemFallback } from "./network.js";
 import { createInterface } from "node:readline";
 import { homedir } from "node:os";
 import { removeHook, decideStop, writeIntent, clearIntent, readIntent, installHooks, agentHookStates } from "./notify.js";
@@ -442,6 +443,8 @@ function printReady(tools) {
             oneTime.set("cursor", `cursor   enable the "pantheon" MCP server if it asks`);
         if (/codex/i.test(t.tool))
             oneTime.set("codex", `codex    run /hooks inside codex once to approve the wake-up hook`);
+        if (/kiro/i.test(t.tool))
+            oneTime.set("kiro", `kiro     run kiro-cli chat --agent pantheon (or kiro-cli agent set-default pantheon) to keep working while a teammate waits; stay signed in — a woken run never starts Kiro signed out, since Kiro would open a browser`);
         if (/copilot/i.test(t.tool))
             oneTime.set("copilot", `copilot  say yes once when it asks to trust this folder; on a Copilot Business or Enterprise plan an org owner must have the "MCP servers in Copilot" policy on`);
     }
@@ -501,7 +504,7 @@ ${B("control")}
   pantheon admit <who>        let someone in       (--may-wake to allow unattended work here)
   pantheon admit <who> --revoke     remove them
   pantheon worker             stay answerable while you are away
-                            (--agent claude-code|codex|cursor|copilot|auto, --persona <name>)
+                            (--agent claude-code|codex|cursor|copilot|kiro|auto, --persona <name>)
   pantheon policy             what this machine's worker may do, in one screen (grant/revoke self-upgrade)
   pantheon persona            how a woken worker should behave: list / init <name> / show <name>
   pantheon notifier           alert you when a task requires your decision
@@ -514,11 +517,12 @@ ${B("control")}
   pantheon approvals          decisions waiting on you; show or answer one
   pantheon stop [relay|worker|notifier|menubar|all]  stop it
   pantheon hook install       your agent keeps working when a peer is waiting on it
-                            (auto-detects claude / codex / cursor / copilot on this machine)
+                            (auto-detects claude / codex / cursor / copilot / kiro on this machine)
   pantheon spend              woken runs on this machine, and what pantheon cannot see
   pantheon leave              remove what pantheon put on this machine
   pantheon panic              cut off all unattended work on this machine, now
   pantheon doctor [--share]   check this machine end to end; --share prints it without names or paths, to paste to us
+  pantheon network [--proxy <url> | --direct | --clear]   how this machine reaches the relay; save a proxy for every Pantheon process here
   pantheon setup              three questions — your name, your role, may a woken run execute commands —
                               then one screen of defaults to keep or change: who may wake this machine,
                               alerts, what you personally decide, playbook, base branch. Re-run any time.
@@ -547,7 +551,26 @@ ${B("less common")}
   pantheon version            the pantheon version this machine is running
 `;
 const QUIET = new Set(["mcp", "hook", "pending", "version", "tray-status"]);
+function rememberWorkingProxy() {
+    try {
+        const plan = currentPlan();
+        const via = plan.https ?? plan.http;
+        if (!via || (plan.source !== "env" && !(plan.fallbackOnly && usedSystemFallback())))
+            return;
+        const all = loadAll();
+        if (!all || all.network?.source === "pantheon network" || all.network?.proxy === via)
+            return;
+        const custom = plan.noProxy.filter((h) => !["localhost", "127.0.0.1", "::1", "[::1]"].includes(h));
+        saveAll({ ...all, network: { proxy: via, ...(custom.length ? { no_proxy: custom.join(",") } : {}), source: plan.source, saved_at: Date.now() } });
+        console.error(D(`  saved the proxy ${redactProxy(via)} for this machine's other Pantheon processes (worker, editors) — change it with pantheon network`));
+    }
+    catch { }
+}
 async function main() {
+    try {
+        await installNetwork();
+    }
+    catch { }
     if (!QUIET.has(cmd)) {
         try {
             console.error(D(updateBanner(VERSION)));
@@ -563,6 +586,35 @@ async function main() {
         return interactiveOnboard();
     }
     switch (cmd) {
+        case "network": {
+            const all = loadAll() ?? die("not configured — sign up or join a team first");
+            const set = flag("proxy");
+            if (set !== undefined) {
+                const p = normalizeProxy(set) ?? die(`"${set}" is not a proxy address — use http://host:port (add user:password@ if it needs a login)`);
+                saveAll({ ...all, network: { proxy: p, ...(flag("no-proxy") ? { no_proxy: flag("no-proxy") } : {}), source: "pantheon network", saved_at: Date.now() } });
+                console.error(`${B("saved")} every Pantheon process on this machine now reaches the relay through ${redactProxy(p)}`);
+                return;
+            }
+            if (argv.includes("--direct")) {
+                saveAll({ ...all, network: { proxy: "", source: "pantheon network --direct", saved_at: Date.now() } });
+                console.error(`${B("saved")} direct — set PANTHEON_PROXY=none in a shell to do the same for one command`);
+                return;
+            }
+            if (argv.includes("--clear")) {
+                const { network: _drop, ...rest } = all;
+                saveAll(rest);
+                console.error(`${B("cleared")} — Pantheon follows HTTPS_PROXY / NO_PROXY and the system settings again`);
+                return;
+            }
+            const plan = currentPlan();
+            const via = plan.https ?? plan.http;
+            console.log(`${B("network")}  ${via ? `through ${redactProxy(via)}` : "direct"}${plan.source !== "none" ? D(`   from ${plan.source}${plan.fallbackOnly ? ", used only if a direct connection fails" : ""}`) : ""}`);
+            if (via)
+                console.log(D(`  not for: ${plan.noProxy.join(", ")}`));
+            if (plan.pac)
+                console.log(D(`  this machine uses an auto-config script (${plan.pac}), which Pantheon cannot read — if the relay is unreachable, save the proxy it points to: pantheon network --proxy http://host:port`));
+            return;
+        }
         case "start": {
             const port = Number(flag("port", "8787"));
             const setupFlags = parseSetupFlags(argv);
@@ -593,6 +645,7 @@ async function main() {
             for (const w of r.warnings)
                 console.error(`\x1b[33m  ! ${w}\x1b[0m`);
             printGranted(r.granted);
+            rememberWorkingProxy();
             if (!r.claimed) {
                 console.error(`\n\x1b[31m  No team was created.\x1b[0m ${D("Fix the warning above, then run `pantheon start` again.")}`);
                 if (r.relay)
@@ -792,6 +845,7 @@ async function main() {
             for (const w of r.warnings)
                 console.error(`\x1b[33m  ! ${w}\x1b[0m`);
             printGranted(r.granted);
+            rememberWorkingProxy();
             printReady(r.tools);
             {
                 const joined = load();
@@ -1332,13 +1386,13 @@ async function main() {
             const sub = argv[1] ?? "status";
             const hookCfg = resolveForHook();
             const sessionOf = (raw) => {
+                let fromJson;
                 try {
                     const j = JSON.parse(raw);
-                    return j.session_id ?? j.sessionId ?? j.conversation_id ?? "unknown";
-                }
-                catch {
-                    return "unknown";
+                    fromJson = j.session_id ?? j.sessionId ?? j.conversation_id;
                 }
+                catch { }
+                return fromJson ?? process.env.KIRO_SESSION_ID ?? "unknown";
             };
             const reportIdle = async (session, seen) => {
                 if (!hookCfg)
@@ -1353,6 +1407,22 @@ async function main() {
                 }
                 return false;
             };
+            if (sub === "kiro-prompt") {
+                let raw = "";
+                try {
+                    for await (const chunk of process.stdin)
+                        raw += chunk;
+                }
+                catch { }
+                try {
+                    if (hookCfg) {
+                        const { reportActivity } = await import("./pending.js");
+                        await reportActivity({ cfg: hookCfg, session: `hook:${sessionOf(raw)}`, state: "busy" });
+                    }
+                }
+                catch { }
+                process.exit(0);
+            }
             if (sub === "prompt") {
                 let raw = "";
                 try {
@@ -1462,7 +1532,7 @@ async function main() {
                     process.exit(0);
                 }
             }
-            if (sub === "codex-stop" || sub === "copilot-stop") {
+            if (sub === "codex-stop" || sub === "copilot-stop" || sub === "kiro-stop") {
                 let raw = "";
                 try {
                     for await (const chunk of process.stdin)
@@ -1571,7 +1641,7 @@ async function main() {
             }
             const states = agentHookStates();
             if (!states.length) {
-                console.log(`${D("not installed")}\n  Install with: ${C("pantheon hook install")} (auto-detects claude / codex / cursor / copilot on PATH)`);
+                console.log(`${D("not installed")}\n  Install with: ${C("pantheon hook install")} (auto-detects claude / codex / cursor / copilot / kiro on PATH)`);
                 return;
             }
             for (const s of states) {
@@ -1654,7 +1724,7 @@ async function main() {
             else {
                 console.error(`  config: none to remove`);
             }
-            console.error(`\n  ${D("Not touched: the MCP entries in Claude Code and Cursor (pantheon install wrote them; remove them there),")}`);
+            console.error(`\n  ${D("Not touched: the MCP entries in Claude Code, Cursor, Copilot, VS Code and Kiro (pantheon install wrote them; remove them there),")}`);
             console.error(`  ${D("the relay's ledger on disk, and anything you pushed to git. Codex's entry and approval line were removed above.")}`);
             if (cfg) {
                 console.error(`\n  ${D(`Your teammates still list you in "${cfg.space}". Ask one of them to run:`)}`);
@@ -2021,7 +2091,7 @@ async function main() {
                 const publicChange = name !== undefined || title !== undefined || responsibilities !== undefined ||
                     humanRequired !== undefined || agentCanDecide !== undefined || capabilities !== undefined || keywords !== undefined;
                 if (!surface && !publicChange) {
-                    die("usage: pantheon profile set [--surface codex|claude-code|cursor|copilot] [--name name] [--title title] [--responsibilities a,b] [--human-required a,b] [--agent-can-decide a,b] [--keywords 'domain=word|word;domain=word']");
+                    die("usage: pantheon profile set [--surface codex|claude-code|cursor|copilot|kiro] [--name name] [--title title] [--responsibilities a,b] [--human-required a,b] [--agent-can-decide a,b] [--keywords 'domain=word|word;domain=word']");
                 }
                 if (flag("space")) {
                     const pf = loadAll() ?? die("not configured");
@@ -2462,7 +2532,7 @@ async function main() {
                 if (hud.prompt) {
                     const agent = pickExplainAgent(hud.tool ?? p.agent.primary_surface, detectAvailable());
                     if (!agent)
-                        die("no agent CLI found on this machine (claude, cursor-agent, codex, or copilot)");
+                        die("no agent CLI found on this machine (claude, cursor-agent, codex, copilot, or kiro-cli)");
                     console.error(D(`opening ${agent.id}…`));
                     const { spawnSync } = await import("node:child_process");
                     {
@@ -2494,7 +2564,7 @@ async function main() {
             }
             const agent = pickExplainAgent(loadProfile(cfg).agent.primary_surface, detectAvailable());
             if (!agent)
-                die("no agent CLI found on this machine (claude, cursor-agent, codex, or copilot)");
+                die("no agent CLI found on this machine (claude, cursor-agent, codex, copilot, or kiro-cli)");
             console.error(D(`opening ${agent.id} with the question…`));
             const { spawnSync } = await import("node:child_process");
             {

package/dist/client.js

@@ -2,6 +2,7 @@ import WebSocket from "ws";
 import { signChallenge } from "./identity.js";
 import { newId } from "./protocol.js";
 import { VERSION } from "./version.js";
+import { describeNetError, explainNetError, trySystemFallback, wsOptions } from "./network.js";
 export class PantheonClient {
     cfg;
     onEvent;
@@ -74,7 +75,28 @@ export class PantheonClient {
     connect() {
         if (!this.everConnected)
             this.closed = false;
-        return this.attempt(this.localOverride ?? this.cfg.relay).catch(async (e) => {
+        const first = this.localOverride ?? this.cfg.relay;
+        return this.attempt(first).catch(async (e) => {
+            if (!this.localOverride && trySystemFallback(first, e)) {
+                this.closed = false;
+                try {
+                    return await this.attempt(first);
+                }
+                catch (e2) {
+                    e = e2;
+                }
+            }
+            return this.afterFailure(e);
+        }).catch((e) => {
+            if (!explainNetError(e))
+                throw e;
+            const out = new Error(describeNetError(e));
+            out.code = e.code;
+            throw out;
+        });
+    }
+    async afterFailure(e) {
+        {
             if (this.localOverride)
                 throw e;
             const transport = /ETIMEDOUT|ECONNREFUSED|ENOTFOUND|EHOSTUNREACH|ENETUNREACH|handshake has timed out|socket hang up/i
@@ -88,13 +110,13 @@ export class PantheonClient {
             this.localOverride = local;
             this.usingLoopback = true;
             return this.attempt(local);
-        });
+        }
     }
     attempt(address) {
         return new Promise((resolve, reject) => {
             let settled = false;
             this.ws?.terminate();
-            const ws = new WebSocket(address, { handshakeTimeout: 6000 });
+            const ws = new WebSocket(address, { handshakeTimeout: 6000, ...wsOptions(address) });
             this.ws = ws;
             ws.on("open", () => { });
             ws.on("message", (raw) => {

package/dist/doctor.js

@@ -1,3 +1,4 @@
+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";
@@ -14,11 +15,12 @@ import { approvalSummary, chosenApproval, 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 } from "./agents.js";
+import { chooseAgent, describeChoice, unattendedRefusal } from "./agents.js";
 import { onPathNamed } from "./which.js";
 import { VERSION } from "./version.js";
 import { serviceInstalled, servicesUnavailable } from "./service.js";
 import { hostEnv, platformName } from "./host-env.js";
+import { currentPlan, explainNetError, proxyFor, redactProxy } from "./network.js";
 const HOSTED_RELAY = "relay.joinpantheon.network";
 const git = (args, cwd) => {
     try {
@@ -156,10 +158,10 @@ export async function doctor(projectDir) {
         if (branch)
             add("pass", "git branch", branch);
     }
-    const agents = ["claude", "codex", "cursor-agent", "copilot"].filter((a) => onPathNamed(a));
+    const agents = ["claude", "codex", "cursor-agent", "copilot", "kiro-cli"].filter((a) => onPathNamed(a));
     agents.length
         ? add("pass", "agent cli", agents.join(", "), undefined, agents.join(", "))
-        : add("warn", "agent cli", "found none of claude / codex / cursor-agent / copilot on PATH", "fine if you only drive agents through a GUI (Conductor, Cursor, VS Code), but `pantheon worker` needs a CLI to spawn", "none of claude / codex / cursor-agent / copilot on PATH");
+        : 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 });
@@ -167,7 +169,10 @@ export async function doctor(projectDir) {
             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 ? `; ${choice.skipped.length} skipped (not signed in)` : ""}`;
-            if (bad)
+            const refused = unattendedRefusal(choice);
+            if (refused)
+                add("warn", "worker agent", line, `woken runs are refused here, not tried: ${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, `you chose ${prof.agent.primary_surface} at setup; runs use ${choice.backend.label} until it is signed in again`, shareLine);
@@ -175,7 +180,13 @@ export async function doctor(projectDir) {
                 add("pass", "worker agent", line, undefined, shareLine);
         }
         catch (e) {
-            add("warn", "worker agent", e.message, "pantheon setup --agent <claude-code|codex|cursor|copilot> names one that is installed", "could not be chosen");
+            add("warn", "worker agent", e.message, "pantheon setup --agent <claude-code|codex|cursor|copilot|kiro> names one that is installed", "could not be chosen");
+        }
+    }
+    {
+        const here = readKiroAgent(kiroAgentFile(join(projectDir, ".kiro")));
+        if (here && !here.ours) {
+            add("warn", "kiro agent", "this repo defines its own agent called pantheon — Kiro uses it instead of yours in this repo", "workspace agents win over your own in Kiro; read .kiro/agents/pantheon.json before running kiro-cli chat --agent pantheon here", "this repo defines its own pantheon agent");
         }
     }
     const budget = instructionBudget(cfg);
@@ -212,6 +223,20 @@ export async function doctor(projectDir) {
     else {
         add("pass", "transport", url.protocol === "wss:" ? "wss:// (TLS)" : `ws:// on a private address (${url.host})`, undefined, url.protocol === "wss:" ? "wss:// (TLS)" : "ws:// on a private address");
     }
+    const plan = currentPlan();
+    const via = proxyFor(cfg.relay, plan);
+    if (via) {
+        add("pass", "network", `through the proxy ${redactProxy(via)} (from ${plan.source})`, undefined, `through a proxy (${plan.source})`);
+    }
+    else if (plan.fallbackOnly && (plan.https || plan.http)) {
+        add("pass", "network", `direct; the ${plan.source === "macos" ? "macOS" : "Windows"} proxy ${redactProxy(plan.https ?? plan.http)} is used only if a direct connection fails`, undefined, `direct, system proxy as fallback`);
+    }
+    else if (plan.pac) {
+        add("warn", "network", `direct, but this machine uses a proxy auto-config script, which Pantheon cannot read`, "if the relay turns out unreachable below, save the proxy that script points to: pantheon network --proxy http://host:port", "direct; PAC script present");
+    }
+    else {
+        add("pass", "network", "direct — no proxy set", undefined, "direct");
+    }
     const health = `${cfg.relay.replace(/^ws/, "http")}/health`;
     const where = hosted ? "hosted" : "self-hosted";
     try {
@@ -235,6 +260,11 @@ export async function doctor(projectDir) {
     }
     catch (e) {
         const msg = e.message;
+        const nx = explainNetError(e);
+        if (nx) {
+            add("fail", "relay", `cannot reach ${health} — ${nx.why}`, nx.fix, `unreachable (${where}): ${nx.share}`);
+            return out;
+        }
         add("fail", "relay", `cannot reach ${health} — ${msg}`, "start it with `pantheon relay`, or check the tunnel/tailnet. Your teammate must be able to reach the SAME address.", `unreachable (${where}): ${/abort|timeout/i.test(msg) ? "timed out" : /ECONNREFUSED/.test(msg) ? "connection refused" : /ENOTFOUND|EAI_AGAIN/.test(msg) ? "name did not resolve" : "fetch failed"}`);
         return out;
     }
@@ -242,6 +272,12 @@ export async function doctor(projectDir) {
     let joined = false;
     await client.connect().then(() => { joined = true; }).catch(() => { });
     if (!joined) {
+        const nx = client.pending ? null : explainNetError(new Error(client.lastError ?? ""));
+        if (nx) {
+            add("fail", "live link", `the health check got through but the live connection did not — ${nx.why}`, nx.fix, `live connection failed: ${nx.share}`);
+            client.close();
+            return out;
+        }
         client.pending
             ? add("fail", "membership", "registered but not admitted", `ask an admitted member to run: pantheon admit ${cfg.member} --may-wake   (confirm fingerprint ${fingerprint(cfg.publicKey)} with them by voice first)`, "registered, not admitted")
             : add("fail", "membership", `refused: ${client.lastError ?? "unknown"}`, "if this is KEY_MISMATCH, someone else already registered your member name — pick another with --me, or have them revoke it", `refused: ${String(client.lastError ?? "unknown").split(/[\s:]/)[0]}`);
@@ -302,7 +338,7 @@ export async function doctor(projectDir) {
         }
     }
     if (!hookStates.length && !hook.installed) {
-        add("warn", "wake-up hook", "not installed — your agent will not notice a peer's message until you ask it to", "pantheon hook install --user (auto-detects claude / codex / cursor / copilot on PATH)", "not installed");
+        add("warn", "wake-up hook", "not installed — your agent will not notice a peer's message until you ask it to", "pantheon hook install --user (auto-detects claude / codex / cursor / copilot / kiro on PATH)", "not installed");
     }
     else if (!reportsActivity) {
         add("warn", "wake-up hook", `installed (${hook.events?.join(", ")}) but predates the activity hook, so a worker cannot tell your idle editor from one you are using`, "re-run `pantheon hook install --user` to add the UserPromptSubmit half", `installed (${hook.events?.join(", ")}), predates the activity hook`);
@@ -316,6 +352,11 @@ export async function doctor(projectDir) {
     if (hookStates.some((s) => s.agent === "codex")) {
         add("warn", "codex hooks", "installed — but codex skips new or changed hooks until they are approved", "run /hooks inside codex once to approve them (needs codex ≥ 0.115; sessions still report presence over MCP either way)", "installed, not yet approved inside codex");
     }
+    if (hookStates.some((s) => s.agent === "kiro")) {
+        kiroDefaultIsPantheon()
+            ? add("pass", "kiro hooks", "in the pantheon agent, which is your Kiro default — every kiro-cli chat keeps working while a teammate waits", undefined, "in the pantheon agent, the default")
+            : add("warn", "kiro hooks", "in the pantheon agent — used only when you run kiro-cli chat --agent pantheon", "kiro-cli agent set-default pantheon makes it every session; without it, Kiro sessions still report presence but end their turn with a teammate waiting", "in the pantheon agent, not the default");
+    }
     const personas = loadPersonas(projectDir);
     if (personas.length) {
         const broken = personas.filter((p) => p.warnings.length);