@wardby/cli 0.6.0 → 0.8.0

package/dist/claude-coding-worker/tool-socket.js

@@ -1,4 +1,5 @@
 import { createConnection } from "node:net";
+import { BUDGET_MEASURE_TIMEOUT_MS, DEFAULT_TIMEOUTS, dependencyCacheTimeLimit, } from "../coding-worker/dependency-cache.mjs";
 /** Where the tool runner listens (claude-tool-runner/main.mjs) and the relay connects (tool-relay.ts). */
 export const TOOL_SOCKET_PATH = "/run/wardby/tool/runner.sock";
 /**
@@ -24,3 +25,113 @@ export async function assertToolRunnerReachable(socketPath = TOOL_SOCKET_PATH, t
         });
     });
 }
+/** The tool runner's internal tool (claude-tool-runner/main.mjs); the agent's SDK options disallow it (sdk.ts). */
+export const PREPARE_DEPENDENCIES_TOOL = "wardby_prepare_dependencies";
+/** Room for the tool runner and the socket on top of the module's own bounds. */
+const PREPARE_DEPENDENCIES_MARGIN_MS = 60_000;
+/**
+ * Derived from the dependency cache's own bounds (dependency-cache.mjs, the same file the tool runner
+ * runs): the budget walk, then the whole prepare (totalMs) and its settle grace, plus a margin. A
+ * worker that stops waiting earlier is still safe: the tool runner holds the first command until
+ * the cache has finished, and seals before it.
+ */
+export const PREPARE_DEPENDENCIES_TIMEOUT_MS = BUDGET_MEASURE_TIMEOUT_MS + DEFAULT_TIMEOUTS.totalMs + DEFAULT_TIMEOUTS.settleMs + PREPARE_DEPENDENCIES_MARGIN_MS;
+const MAX_RESPONSE_LINE_BYTES = 256 * 1024;
+/** How long the worker waits for the prepare tool on a run with this deadline. */
+export function prepareDependenciesTimeoutMs(deadlineAt, now = Date.now()) {
+    if (deadlineAt === undefined)
+        return PREPARE_DEPENDENCIES_TIMEOUT_MS;
+    return Math.min(PREPARE_DEPENDENCIES_TIMEOUT_MS, dependencyCacheTimeLimit(deadlineAt, now) + DEFAULT_TIMEOUTS.settleMs + PREPARE_DEPENDENCIES_MARGIN_MS);
+}
+/**
+ * The worker's one call to the tool runner on a dependency-cache run, before the agent starts: a
+ * minimal MCP client (newline-delimited JSON-RPC, as the relay carries) that initializes and calls
+ * PREPARE_DEPENDENCIES_TOOL once. Resolves with the tool's JSON (unchecked: the caller bounds it).
+ * Fails only with `dependency_cache_tool_unavailable` (a tool runner without the tool) or
+ * `dependency_cache_tool_failed`; never with the tool runner's text.
+ */
+export async function callPrepareDependencies({ socketPath = TOOL_SOCKET_PATH, deadlineAt, timeoutMs = prepareDependenciesTimeoutMs(deadlineAt), signal, } = {}) {
+    const failed = () => new Error("dependency_cache_tool_failed");
+    if (signal?.aborted)
+        throw failed();
+    const socket = createConnection(socketPath);
+    socket.setEncoding("utf8");
+    const pending = new Map();
+    let buffered = "";
+    let settle;
+    const broken = new Promise((_, reject) => {
+        settle = reject;
+    });
+    // Every waiter races `broken`; keep an unobserved rejection from surfacing.
+    broken.catch(() => undefined);
+    const fail = (error) => settle?.(error);
+    const timer = setTimeout(() => fail(failed()), timeoutMs);
+    const onAbort = () => fail(failed());
+    signal?.addEventListener("abort", onAbort, { once: true });
+    socket.on("error", () => fail(failed()));
+    socket.once("close", () => fail(failed()));
+    socket.on("data", (chunk) => {
+        buffered += chunk;
+        let end;
+        while ((end = buffered.indexOf("\n")) >= 0) {
+            const line = buffered.slice(0, end);
+            buffered = buffered.slice(end + 1);
+            let message;
+            try {
+                message = JSON.parse(line);
+            }
+            catch {
+                fail(failed());
+                return;
+            }
+            if (typeof message?.id === "number")
+                pending.get(message.id)?.resolve(message);
+        }
+        if (Buffer.byteLength(buffered) > MAX_RESPONSE_LINE_BYTES)
+            fail(failed());
+    });
+    let nextId = 0;
+    const request = (method, params) => {
+        const id = ++nextId;
+        const answered = new Promise((resolve) => pending.set(id, { resolve }));
+        socket.write(`${JSON.stringify({ jsonrpc: "2.0", id, method, params })}\n`);
+        return Promise.race([answered, broken]);
+    };
+    try {
+        await Promise.race([new Promise((resolve) => socket.once("connect", () => resolve())), broken]);
+        const initialized = await request("initialize", {
+            protocolVersion: "2025-03-26",
+            capabilities: {},
+            clientInfo: { name: "wardby-claude-worker", version: "1.0.0" },
+        });
+        if (!initialized.result)
+            throw failed();
+        socket.write(`${JSON.stringify({ jsonrpc: "2.0", method: "notifications/initialized" })}\n`);
+        const called = await request("tools/call", {
+            name: PREPARE_DEPENDENCIES_TOOL,
+            arguments: deadlineAt === undefined ? {} : { deadline_at: deadlineAt },
+        });
+        const result = called.result;
+        if (called.error || !result || result.isError)
+            throw new Error("dependency_cache_tool_unavailable");
+        const text = result.content?.find((item) => item.type === "text")?.text;
+        if (typeof text !== "string")
+            throw failed();
+        try {
+            return JSON.parse(text);
+        }
+        catch {
+            throw failed();
+        }
+    }
+    catch (error) {
+        if (error instanceof Error && error.message === "dependency_cache_tool_unavailable")
+            throw error;
+        throw failed();
+    }
+    finally {
+        clearTimeout(timer);
+        signal?.removeEventListener("abort", onAbort);
+        socket.destroy();
+    }
+}

package/dist/claude-coding-worker/transcript.d.ts

@@ -0,0 +1,18 @@
+export declare const TRANSCRIPT_OUTPUT_PATH = "/run/wardby/output/session.jsonl";
+interface WriteOptions {
+    configDir: string;
+    sessionId: string;
+    outputPath: string;
+    /** Used when Claude Code wrote no title (the worker turns off the background call that makes one). */
+    title?: string;
+}
+/** "wardby run <runId>: <first line of the request>", for the session picker. */
+export declare function runTitle(runId: string, task: string): string;
+/**
+ * Writes the run's sanitised session transcript next to its result, for the control plane to collect
+ * (it sanitises and redacts again before storing anything). Writes nothing when the SDK left no
+ * session file. Throws only fixed codes.
+ */
+export declare function writeWorkerTranscript(options: WriteOptions): Promise<void>;
+export declare function writeWorkerTranscriptWithLimit(options: WriteOptions, maxBytes: number): Promise<void>;
+export {};

package/dist/claude-coding-worker/transcript.js

@@ -0,0 +1,77 @@
+import { readdir, rename, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { readBoundedRegularFile } from "../coding-worker/artifact.js";
+import { sanitizeClaudeTranscript } from "../coding/transcript/claude-code.js";
+import { formatTranscriptFile, MAX_RAW_TRANSCRIPT_BYTES, MAX_TRANSCRIPT_BYTES, } from "../coding/transcript/format.js";
+export const TRANSCRIPT_OUTPUT_PATH = "/run/wardby/output/session.jsonl";
+const MAX_TITLE_CHARS = 80;
+/** "wardby run <runId>: <first line of the request>", for the session picker. */
+export function runTitle(runId, task) {
+    const request = task.includes("\n\nRequest:\n") ? task.slice(task.lastIndexOf("\n\nRequest:\n") + 11) : task;
+    const firstLine = request.split("\n").find((line) => line.trim()) ?? "";
+    const title = `wardby run ${runId}: ${firstLine.trim().replace(/\s+/g, " ")}`;
+    return title.length > MAX_TITLE_CHARS ? `${title.slice(0, MAX_TITLE_CHARS - 1)}…` : title;
+}
+/**
+ * Writes the run's sanitised session transcript next to its result, for the control plane to collect
+ * (it sanitises and redacts again before storing anything). Writes nothing when the SDK left no
+ * session file. Throws only fixed codes.
+ */
+export function writeWorkerTranscript(options) {
+    return writeWorkerTranscriptWithLimit(options, MAX_TRANSCRIPT_BYTES);
+}
+export async function writeWorkerTranscriptWithLimit(options, maxBytes) {
+    const source = await findSessionFile(options.configDir, options.sessionId);
+    if (!source)
+        return;
+    const header = (status) => ({
+        type: "wardby-transcript",
+        version: 1,
+        provider: "claude-code",
+        sessionId: options.sessionId,
+        status,
+    });
+    let file;
+    try {
+        const raw = await readBoundedRegularFile(source, MAX_RAW_TRANSCRIPT_BYTES, "transcript_too_large");
+        const sanitized = sanitizeClaudeTranscript(raw, options.title);
+        file = sanitized
+            ? formatTranscriptFile(header("ok"), sanitized.lines)
+            : formatTranscriptFile(header("no_complete_turn"), []);
+    }
+    catch (error) {
+        if (!(error instanceof Error && error.message === "transcript_too_large")) {
+            throw new Error("transcript_capture_failed", { cause: error });
+        }
+        file = formatTranscriptFile(header("too_large"), []);
+    }
+    if (Buffer.byteLength(file) > maxBytes)
+        file = formatTranscriptFile(header("too_large"), []);
+    const temporary = `${options.outputPath}.tmp`;
+    await writeFile(temporary, file, { mode: 0o600 });
+    await rename(temporary, options.outputPath);
+}
+const SESSION_ID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+/** The SDK's file for this session: <configDir>/projects/<encoded cwd>/<sessionId>.jsonl. */
+async function findSessionFile(configDir, sessionId) {
+    // The id comes from the SDK's init message; only a UUID is ever used to build a path.
+    if (!SESSION_ID.test(sessionId))
+        return undefined;
+    const projects = join(configDir, "projects");
+    const name = `${sessionId}.jsonl`;
+    let entries;
+    try {
+        entries = await readdir(projects, { withFileTypes: true });
+    }
+    catch {
+        return undefined;
+    }
+    for (const entry of entries) {
+        if (!entry.isDirectory())
+            continue;
+        const files = await readdir(join(projects, entry.name)).catch(() => []);
+        if (files.includes(name))
+            return join(projects, entry.name, name);
+    }
+    return undefined;
+}

package/dist/claude-plugin/command.d.ts

@@ -0,0 +1,61 @@
+export declare const PLUGIN = "wardby-runs";
+export declare const DEFAULT_MARKETPLACE = "wardby/wardby";
+export declare const MCP_SERVER = "wardby";
+/** The pane's read-only tools on a server: what auto mode needs allowed. stop_run is never added: it changes a run. */
+export declare function paneTools(server: string): string[];
+export declare const PANE_TOOLS: string[];
+export declare const CLAUDE_PLUGIN_USAGE = "usage: wardby claude-plugin install [--marketplace <owner/repo|path>] [--server-url <url>]\n                                   [--allow-tools | --no-allow-tools] [--fullscreen] [--yes]\n       wardby claude-plugin uninstall\n       wardby claude-plugin status\n\nSet up the wardby-runs Claude Code plugin: a pane listing your wardby runs.\n\n  --server-name <name> The MCP server the pane uses, as /mcp lists it (default wardby); its\n                       allow rules follow the name\n  --marketplace <src>  Where to install it from (default wardby/wardby; an operator's own\n                       marketplace repository or a local folder works too)\n  --server-url <url>   Register the wardby MCP server at this URL first (for example\n                       https://wardby.example.com/mcp) when Claude Code has none named wardby\n  --allow-tools        Allow the pane's read-only wardby tools for auto mode without asking\n  --no-allow-tools     Leave permission rules alone\n  --fullscreen         Also switch Claude Code's terminal to its fullscreen view, where the pane\n                       is a side bar that takes clicks (applies to every session)\n  --yes, -y            Answer yes to every question";
+/** The record of what install changed, so uninstall removes exactly that. */
+export type InstallRecord = {
+    settingsPath: string;
+    rules: string[];
+    tui: boolean;
+};
+export type ClaudePluginDeps = {
+    /** Runs a command; resolves its exit code and output. */
+    run: (command: string, args: string[]) => {
+        status: number;
+        stdout: string;
+        stderr: string;
+    };
+    /** Asks a yes/no question; false when there's nobody to ask. */
+    confirm: (question: string) => Promise<boolean>;
+    /** Where Claude Code keeps its settings: CLAUDE_CONFIG_DIR, else ~/.claude. */
+    claudeConfigDir: string;
+    /** Where wardby keeps the install record: ~/.wardby. */
+    wardbyDir: string;
+    out: (line: string) => void;
+};
+/** The real machine: spawns `claude`, asks on the terminal, uses CLAUDE_CONFIG_DIR or ~/.claude. */
+export declare function claudePluginDeps(): ClaudePluginDeps;
+export declare function installPlugin(options: {
+    marketplace: string;
+    serverName?: string;
+    serverUrl?: string;
+    allowTools?: boolean;
+    fullscreen: boolean;
+    yes: boolean;
+}, deps: ClaudePluginDeps): Promise<number>;
+export declare function uninstallPlugin(deps: ClaudePluginDeps): Promise<number>;
+export declare function pluginStatus(deps: ClaudePluginDeps, serverName?: string): number;
+/**
+ * Quickstart's offer of the pane, once it connected Claude Code: asks unless a flag answered it,
+ * never in a non-interactive run, and installs on a yes. A failed install is a warning, not a stop.
+ */
+export declare function quickstartPaneStep(options: {
+    client: string;
+    mcpConfigured: boolean;
+    flag?: boolean;
+    nonInteractive: boolean;
+    yes: boolean;
+}, steps: {
+    ask: (question: string) => Promise<boolean>;
+    install: (options: Parameters<typeof installPlugin>[0]) => Promise<number>;
+    warn: (line: string) => void;
+}): Promise<"skipped" | "installed" | "failed">;
+/**
+ * `wardby doctor`'s lines for the pane: none without Claude Code. The pane is optional, so nothing
+ * here is a failure (✗): a missing plugin is "○", a missing server or rule a warning ("!").
+ */
+export declare function claudePluginDoctorLines(deps: ClaudePluginDeps, serverName?: string): string[];
+export declare function claudePluginCommand(args: string[], deps?: ClaudePluginDeps): Promise<number>;

package/dist/claude-plugin/command.js

@@ -0,0 +1,376 @@
+/**
+ * `wardby claude-plugin install | uninstall | status`: sets up the wardby-runs
+ * Claude Code plugin (plugins/claude-code) on this machine. Install adds the
+ * plugin from a marketplace (wardby/wardby by default, or an operator's own),
+ * can register the wardby MCP server, and offers the allow rules auto mode
+ * needs for the pane's read-only tools. Uninstall removes the plugin and only
+ * the settings install added. Status reports all three.
+ *
+ * Runs without a database or any server configuration. It prints the commands
+ * it runs and their outcome, never a token: the MCP server's sign-in is Claude
+ * Code's own, at first use.
+ */
+import { spawnSync } from "node:child_process";
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { createInterface } from "node:readline";
+import { parseArgs } from "node:util";
+export const PLUGIN = "wardby-runs";
+export const DEFAULT_MARKETPLACE = "wardby/wardby";
+export const MCP_SERVER = "wardby";
+/** The pane's read-only tools on a server: what auto mode needs allowed. stop_run is never added: it changes a run. */
+export function paneTools(server) {
+    return ["list_runs", "list_agents", "get_run", "get_run_transcript"].map((tool) => `mcp__${server}__${tool}`);
+}
+export const PANE_TOOLS = paneTools(MCP_SERVER);
+/** How long one `claude` call may take: `claude mcp get` can check its server, which shouldn't stall doctor. */
+const CLAUDE_TIMEOUT_MS = 20_000;
+export const CLAUDE_PLUGIN_USAGE = `usage: wardby claude-plugin install [--marketplace <owner/repo|path>] [--server-url <url>]
+                                   [--allow-tools | --no-allow-tools] [--fullscreen] [--yes]
+       wardby claude-plugin uninstall
+       wardby claude-plugin status
+
+Set up the wardby-runs Claude Code plugin: a pane listing your wardby runs.
+
+  --server-name <name> The MCP server the pane uses, as /mcp lists it (default ${MCP_SERVER}); its
+                       allow rules follow the name
+  --marketplace <src>  Where to install it from (default ${DEFAULT_MARKETPLACE}; an operator's own
+                       marketplace repository or a local folder works too)
+  --server-url <url>   Register the wardby MCP server at this URL first (for example
+                       https://wardby.example.com/mcp) when Claude Code has none named ${MCP_SERVER}
+  --allow-tools        Allow the pane's read-only wardby tools for auto mode without asking
+  --no-allow-tools     Leave permission rules alone
+  --fullscreen         Also switch Claude Code's terminal to its fullscreen view, where the pane
+                       is a side bar that takes clicks (applies to every session)
+  --yes, -y            Answer yes to every question`;
+/** The real machine: spawns `claude`, asks on the terminal, uses CLAUDE_CONFIG_DIR or ~/.claude. */
+export function claudePluginDeps() {
+    return {
+        run: (command, args) => {
+            const result = spawnSync(command, args, { encoding: "utf8", timeout: CLAUDE_TIMEOUT_MS });
+            return {
+                status: result.error ? 127 : (result.status ?? 1),
+                stdout: result.stdout ?? "",
+                stderr: result.stderr ?? "",
+            };
+        },
+        confirm: async (question) => {
+            if (!process.stdin.isTTY)
+                return false;
+            const rl = createInterface({ input: process.stdin, output: process.stdout });
+            try {
+                const answer = await new Promise((resolve) => rl.question(`${question} [y/N] `, resolve));
+                return /^y(es)?$/i.test(answer.trim());
+            }
+            finally {
+                rl.close();
+            }
+        },
+        claudeConfigDir: process.env.CLAUDE_CONFIG_DIR?.trim() || join(homedir(), ".claude"),
+        wardbyDir: join(homedir(), ".wardby"),
+        out: (line) => process.stdout.write(`${line}\n`),
+    };
+}
+const recordPath = (deps) => join(deps.wardbyDir, "claude-plugin.json");
+/** A settings file as an object: {} when absent; refuses a file that isn't a JSON object rather than overwrite it. */
+function readSettings(path) {
+    if (!existsSync(path))
+        return {};
+    const text = readFileSync(path, "utf8");
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        throw new Error(`${path} isn't valid JSON; fix it, then run this again. Nothing was changed.`);
+    }
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+        throw new Error(`${path} isn't a JSON object; nothing was changed.`);
+    }
+    return parsed;
+}
+/** Writes a settings file whole, through a temporary file, so a failure never leaves half a file. */
+function writeSettings(path, settings) {
+    mkdirSync(dirname(path), { recursive: true });
+    const temp = `${path}.wardby-${process.pid}.tmp`;
+    writeFileSync(temp, `${JSON.stringify(settings, null, 2)}\n`, { mode: 0o600 });
+    renameSync(temp, path);
+}
+function allowList(settings) {
+    const permissions = settings.permissions;
+    if (typeof permissions !== "object" || permissions === null)
+        return [];
+    const allow = permissions.allow;
+    return Array.isArray(allow) ? allow.filter((rule) => typeof rule === "string") : [];
+}
+function withAllowList(settings, allow) {
+    const permissions = typeof settings.permissions === "object" && settings.permissions !== null
+        ? settings.permissions
+        : {};
+    return { ...settings, permissions: { ...permissions, allow } };
+}
+function readRecord(deps) {
+    try {
+        const record = JSON.parse(readFileSync(recordPath(deps), "utf8"));
+        return typeof record.settingsPath === "string" && Array.isArray(record.rules) ? record : null;
+    }
+    catch {
+        return null;
+    }
+}
+function claudeAvailable(deps) {
+    return deps.run("claude", ["--version"]).status === 0;
+}
+function hasMcpServer(deps, server = MCP_SERVER) {
+    return deps.run("claude", ["mcp", "get", server]).status === 0;
+}
+function pluginInstalled(deps) {
+    const list = deps.run("claude", ["plugin", "list"]);
+    return list.status === 0 && new RegExp(`\\b${PLUGIN}@`).test(list.stdout);
+}
+/** The first line of a failed command's output, for the message. */
+const firstLine = (result) => (result.stderr || result.stdout).trim().split("\n")[0]?.slice(0, 300) ?? "";
+export async function installPlugin(options, deps) {
+    if (!claudeAvailable(deps)) {
+        deps.out("Claude Code (claude) wasn't found on PATH. Install it, then run this again.");
+        return 1;
+    }
+    const server = options.serverName ?? MCP_SERVER;
+    if (!/^[A-Za-z0-9_-]{1,64}$/.test(server)) {
+        deps.out(`--server-name "${server}" isn't a server name (letters, digits, - and _).`);
+        return 1;
+    }
+    const tools = paneTools(server);
+    // Read the settings file before changing anything, so a broken one stops the install cleanly.
+    const settingsPath = join(deps.claudeConfigDir, "settings.json");
+    let settings;
+    try {
+        settings = readSettings(settingsPath);
+    }
+    catch (error) {
+        deps.out(error instanceof Error ? error.message : String(error));
+        return 1;
+    }
+    // 1. The MCP server the pane talks to.
+    if (hasMcpServer(deps, server)) {
+        deps.out(`✓ Claude Code has an MCP server named ${server}.`);
+    }
+    else if (options.serverUrl) {
+        let url;
+        try {
+            url = new URL(options.serverUrl);
+        }
+        catch {
+            deps.out(`--server-url "${options.serverUrl}" isn't a URL.`);
+            return 1;
+        }
+        if (url.protocol !== "https:" &&
+            !(url.protocol === "http:" && ["localhost", "127.0.0.1", "[::1]"].includes(url.hostname))) {
+            deps.out("--server-url must be https (or http on localhost).");
+            return 1;
+        }
+        const added = deps.run("claude", ["mcp", "add", "--transport", "http", "--scope", "user", server, url.href]);
+        if (added.status !== 0) {
+            deps.out(`Adding the ${server} MCP server failed: ${firstLine(added)}`);
+            return 1;
+        }
+        deps.out(`✓ Added the ${server} MCP server (${url.href}). Sign in with /mcp in Claude Code.`);
+    }
+    else {
+        deps.out(`! Claude Code has no MCP server named ${server}. The pane needs one: run this again with ` +
+            "--server-url <your wardby URL>/mcp, or run `wardby quickstart`.");
+    }
+    // 2. The plugin itself.
+    const installed = deps.run("claude", ["plugin", "install", PLUGIN, "--marketplace", options.marketplace]);
+    if (installed.status !== 0) {
+        deps.out(`Installing the ${PLUGIN} plugin from ${options.marketplace} failed: ${firstLine(installed)}`);
+        return 1;
+    }
+    deps.out(`✓ Installed the ${PLUGIN} plugin from ${options.marketplace}.`);
+    // 3. Allow rules for auto mode, and the fullscreen view: each only when asked for or agreed to.
+    const record = readRecord(deps) ?? { settingsPath, rules: [], tui: false };
+    let changed = false;
+    const allowTools = options.allowTools ??
+        (options.yes ||
+            (await deps.confirm(`Allow the pane's read-only wardby tools (${tools.map((t) => t.replace(`mcp__${server}__`, "")).join(", ")}) ` +
+                `in ${settingsPath}? Auto mode refuses the pane's calls without them.`)));
+    if (allowTools) {
+        const current = allowList(settings);
+        const missing = tools.filter((rule) => !current.includes(rule));
+        if (missing.length > 0) {
+            settings = withAllowList(settings, [...current, ...missing]);
+            record.rules = [...new Set([...record.rules, ...missing])];
+            changed = true;
+            deps.out(`✓ Allowed ${missing.join(", ")}.`);
+        }
+        else {
+            deps.out("✓ The pane's tools are already allowed.");
+        }
+    }
+    else {
+        deps.out(`Left permission rules alone. Under auto mode, allow ${tools.join(", ")} in /permissions.`);
+    }
+    if (options.fullscreen && settings.tui !== "fullscreen") {
+        settings = { ...settings, tui: "fullscreen" };
+        record.tui = true;
+        changed = true;
+        deps.out("✓ Switched Claude Code to its fullscreen view (restart Claude Code to see it).");
+    }
+    if (changed) {
+        writeSettings(settingsPath, settings);
+        mkdirSync(deps.wardbyDir, { recursive: true });
+        writeFileSync(recordPath(deps), `${JSON.stringify({ ...record, settingsPath }, null, 2)}\n`, { mode: 0o600 });
+    }
+    deps.out("Open the pane in Claude Code with /wardby-runs (in a new session, or after /reload-plugins).");
+    return 0;
+}
+export async function uninstallPlugin(deps) {
+    if (!claudeAvailable(deps)) {
+        deps.out("Claude Code (claude) wasn't found on PATH.");
+        return 1;
+    }
+    const removed = deps.run("claude", ["plugin", "uninstall", PLUGIN]);
+    if (removed.status === 0)
+        deps.out(`✓ Uninstalled the ${PLUGIN} plugin.`);
+    else
+        deps.out(`The ${PLUGIN} plugin wasn't uninstalled: ${firstLine(removed)}`);
+    // Only what install added: rules it added, and the fullscreen view if it switched it on. The file is
+    // written only when one of those is still there; a broken file is reported, not rewritten.
+    const record = readRecord(deps);
+    if (record && existsSync(record.settingsPath)) {
+        let settings;
+        try {
+            settings = readSettings(record.settingsPath);
+        }
+        catch (error) {
+            deps.out(`${error instanceof Error ? error.message : String(error)} Remove ${record.rules.join(", ")} yourself.`);
+            return 1;
+        }
+        const current = allowList(settings);
+        const kept = current.filter((rule) => !record.rules.includes(rule));
+        let changed = false;
+        if (kept.length !== current.length) {
+            settings = withAllowList(settings, kept);
+            changed = true;
+            deps.out(`✓ Removed the rules install added: ${current.filter((rule) => !kept.includes(rule)).join(", ")}.`);
+        }
+        if (record.tui && settings.tui === "fullscreen") {
+            const { tui: _tui, ...rest } = settings;
+            settings = rest;
+            changed = true;
+            deps.out("✓ Switched the fullscreen view back off.");
+        }
+        if (changed)
+            writeSettings(record.settingsPath, settings);
+    }
+    if (record)
+        writeFileSync(recordPath(deps), "{}\n", { mode: 0o600 });
+    deps.out(`The ${MCP_SERVER} MCP server was left in place (remove it with: claude mcp remove ${MCP_SERVER} -s user).`);
+    return removed.status === 0 ? 0 : 1;
+}
+export function pluginStatus(deps, serverName = MCP_SERVER) {
+    if (!claudeAvailable(deps)) {
+        deps.out("✗ Claude Code (claude) wasn't found on PATH.");
+        return 1;
+    }
+    const plugin = pluginInstalled(deps);
+    const server = hasMcpServer(deps, serverName);
+    const settingsPath = join(deps.claudeConfigDir, "settings.json");
+    let allowed = [];
+    try {
+        allowed = allowList(readSettings(settingsPath));
+    }
+    catch (error) {
+        deps.out(`! ${error instanceof Error ? error.message : String(error)}`);
+    }
+    const missing = paneTools(serverName).filter((rule) => !allowed.includes(rule));
+    deps.out(`${plugin ? "✓" : "✗"} ${PLUGIN} plugin ${plugin ? "installed" : "not installed"}`);
+    deps.out(`${server ? "✓" : "✗"} ${serverName} MCP server ${server ? "configured" : "not configured"}`);
+    deps.out(missing.length === 0
+        ? `✓ the pane's tools are allowed in ${settingsPath}`
+        : `! not allowed in ${settingsPath} (auto mode refuses them): ${missing.join(", ")}`);
+    return plugin && server ? 0 : 1;
+}
+/**
+ * Quickstart's offer of the pane, once it connected Claude Code: asks unless a flag answered it,
+ * never in a non-interactive run, and installs on a yes. A failed install is a warning, not a stop.
+ */
+export async function quickstartPaneStep(options, steps) {
+    if (!options.mcpConfigured || (options.client !== "claude" && options.client !== "both"))
+        return "skipped";
+    const wanted = options.flag ??
+        (!options.nonInteractive && (await steps.ask("Add the wardby runs pane to Claude Code (the wardby-runs plugin)?")));
+    if (!wanted)
+        return "skipped";
+    const status = await steps.install({ marketplace: DEFAULT_MARKETPLACE, fullscreen: false, yes: options.yes });
+    if (status === 0)
+        return "installed";
+    steps.warn("! The runs pane wasn't installed; try again with: npx @wardby/cli@latest claude-plugin install");
+    return "failed";
+}
+/**
+ * `wardby doctor`'s lines for the pane: none without Claude Code. The pane is optional, so nothing
+ * here is a failure (✗): a missing plugin is "○", a missing server or rule a warning ("!").
+ */
+export function claudePluginDoctorLines(deps, serverName = MCP_SERVER) {
+    if (!claudeAvailable(deps))
+        return [];
+    if (!pluginInstalled(deps)) {
+        return [`○ Claude Code runs pane not installed (optional: npx @wardby/cli@latest claude-plugin install)`];
+    }
+    const lines = [`✓ ${PLUGIN} Claude Code plugin installed`];
+    lines.push(hasMcpServer(deps, serverName)
+        ? `✓ ${serverName} MCP server configured in Claude Code`
+        : `! Claude Code has no MCP server named ${serverName}: the pane has nothing to show (claude-plugin install --server-url <url>)`);
+    const settingsPath = join(deps.claudeConfigDir, "settings.json");
+    let missing = paneTools(serverName);
+    try {
+        const allowed = allowList(readSettings(settingsPath));
+        missing = paneTools(serverName).filter((rule) => !allowed.includes(rule));
+    }
+    catch {
+        // An unreadable settings file reads as no rules: the warning below says what to allow.
+    }
+    lines.push(missing.length === 0
+        ? "✓ the pane's tools are allowed for auto mode"
+        : `! not allowed for auto mode in ${settingsPath}: ${missing.join(", ")} (needed only in auto mode)`);
+    return lines;
+}
+export async function claudePluginCommand(args, deps = claudePluginDeps()) {
+    const [sub, ...rest] = args;
+    if (sub === undefined || sub === "--help" || sub === "-h") {
+        deps.out(CLAUDE_PLUGIN_USAGE);
+        return sub === undefined ? 1 : 0;
+    }
+    if (sub === "install") {
+        const { values } = parseArgs({
+            args: rest,
+            allowNegative: true,
+            options: {
+                marketplace: { type: "string" },
+                "server-name": { type: "string" },
+                "server-url": { type: "string" },
+                "allow-tools": { type: "boolean" },
+                fullscreen: { type: "boolean" },
+                yes: { type: "boolean", short: "y" },
+            },
+        });
+        return installPlugin({
+            marketplace: values.marketplace ?? DEFAULT_MARKETPLACE,
+            serverName: values["server-name"],
+            serverUrl: values["server-url"],
+            allowTools: values["allow-tools"],
+            fullscreen: values.fullscreen ?? false,
+            yes: values.yes ?? false,
+        }, deps);
+    }
+    if (sub === "uninstall")
+        return uninstallPlugin(deps);
+    if (sub === "status") {
+        const { values } = parseArgs({ args: rest, options: { "server-name": { type: "string" } } });
+        return pluginStatus(deps, values["server-name"] ?? MCP_SERVER);
+    }
+    deps.out(`Unknown claude-plugin command "${sub}".\n${CLAUDE_PLUGIN_USAGE}`);
+    return 1;
+}

package/dist/cli-help.d.ts

@@ -1 +1 @@
-export declare const CLI_USAGE = "usage:\n  wardby quickstart [--provider openai|anthropic] [--model <m>] [--budget <usd>] [--client none|codex|claude|both] [--skip-demo] [--non-interactive --yes]\n  wardby doctor\n  wardby status\n  wardby logs [--tail N] [--follow]\n  wardby down [--volumes]\n  wardby knowledge check [dir] [--root <dir>] [--strict] [--json]   Validate a knowledge bundle (offline)\n  wardby help [list]\n  wardby help search <terms>\n  wardby help open <article-id>\n  wardby agent create --name <n> --model <m> --prompt <p> --budget <usd> [--schedule \"<cron>\"] [--timezone <tz>] [--max-turns <n>] [--owner <subject>] [--public] [--native-execution-mode control-plane|sandbox]\n      (owned by --owner or LOCAL_PRINCIPAL; --public shares it with everyone at execute;\n       sandbox needs NATIVE_SANDBOX_LAUNCHER set in this environment)\n  wardby agent list\n  wardby agent mode <name> control-plane|sandbox   (native agents; applies to runs created after the change)\n  wardby agent schedule <name> --cron \"<expr>\" [--timezone <tz>] [--disable]\n  wardby tool create --name <n> --description <d> --params <file> --code <file>\n  wardby tool attach <tool-name|tool-id> <agent-name>   (grants the capabilities in the agent owner's name)\n  wardby tool detach <tool-name|tool-id> <agent-name>\n  wardby tool update <tool-name|tool-id> [--description <d>] [--params <file>] [--code <file>]\n  wardby tool delete <tool-name|tool-id> [--detach]\n  wardby tool list [--agent <name>]\n  wardby run <name>\n  wardby runs [--agent <name>] [--limit N] [--status <s>]\n  wardby coding preflight   (JOB_LAUNCHER=docker or kubernetes)\n  wardby coding cleanup --run-id <id>\n  wardby scheduler [--scope default]\n  wardby native-gateway   (the native sandbox gateway only; NATIVE_GATEWAY_LISTEN, default 0.0.0.0:8790)\n  wardby mcp   (MCP_TRANSPORT=stdio|http selects the transport)\n  wardby serve [--scope default]   (mcp + scheduler + reconciler in one process; http only)\n  wardby grants migration-report [--json]\n  wardby grants adopt-public --owner <subject> [--dry-run] [--keep-everyone-execute]\n  wardby grants prune-bindings [--dry-run]\n  wardby import <bundle-dir> [--owner <subject>] [--public] [--include-secrets --transfer-key <pem>] [--default-budget <usd>] [--dry-run] [--prefix <p>] [--on-conflict fail|skip|rename] [--allow-open-fetch]\n\noptions:\n  -h, --help       Show this help\n  -v, --version    Show the installed Wardby version";
+export declare const CLI_USAGE = "usage:\n  wardby quickstart [--provider openai|anthropic] [--model <m>] [--budget <usd>] [--client none|codex|claude|both] [--claude-plugin | --no-claude-plugin] [--skip-demo] [--non-interactive --yes]\n  wardby doctor\n  wardby status\n  wardby logs [--tail N] [--follow]\n  wardby down [--volumes]\n  wardby knowledge check [dir] [--root <dir>] [--strict] [--json]   Validate a knowledge bundle (offline)\n  wardby resume - [--dir <path> | --here] [--force] [--print]   Continue a coding run's Claude Code session locally (paste the get_run_transcript link)\n  wardby claude-plugin install|uninstall|status [options]   Set up the wardby-runs Claude Code pane (plugin, MCP server, allow rules)\n  wardby help [list]\n  wardby help search <terms>\n  wardby help open <article-id>\n  wardby agent create --name <n> --model <m> --prompt <p> --budget <usd> [--schedule \"<cron>\"] [--timezone <tz>] [--max-turns <n>] [--owner <subject>] [--public] [--native-execution-mode control-plane|sandbox]\n      (owned by --owner or LOCAL_PRINCIPAL; --public shares it with everyone at execute;\n       sandbox needs NATIVE_SANDBOX_LAUNCHER set in this environment)\n  wardby agent list\n  wardby agent mode <name> control-plane|sandbox   (native agents; applies to runs created after the change)\n  wardby agent schedule <name> --cron \"<expr>\" [--timezone <tz>] [--disable]\n  wardby tool create --name <n> --description <d> --params <file> --code <file>\n  wardby tool attach <tool-name|tool-id> <agent-name>   (grants the capabilities in the agent owner's name)\n  wardby tool detach <tool-name|tool-id> <agent-name>\n  wardby tool update <tool-name|tool-id> [--description <d>] [--params <file>] [--code <file>]\n  wardby tool delete <tool-name|tool-id> [--detach]\n  wardby tool list [--agent <name>]\n  wardby run <name>\n  wardby runs [--agent <name>] [--limit N] [--status <s>]\n  wardby coding preflight   (JOB_LAUNCHER=docker or kubernetes)\n  wardby coding cleanup --run-id <id>\n  wardby scheduler [--scope default]\n  wardby native-gateway   (the native sandbox gateway only; NATIVE_GATEWAY_LISTEN, default 0.0.0.0:8790)\n  wardby mcp   (MCP_TRANSPORT=stdio|http selects the transport)\n  wardby serve [--scope default]   (mcp + scheduler + reconciler in one process; http only)\n  wardby grants migration-report [--json]\n  wardby grants adopt-public --owner <subject> [--dry-run] [--keep-everyone-execute]\n  wardby grants prune-bindings [--dry-run]\n  wardby import <bundle-dir> [--owner <subject>] [--public] [--include-secrets --transfer-key <pem>] [--default-budget <usd>] [--dry-run] [--prefix <p>] [--on-conflict fail|skip|rename] [--allow-open-fetch]\n\noptions:\n  -h, --help       Show this help\n  -v, --version    Show the installed Wardby version";