@wardby/cli 0.5.3 → 0.7.0

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

@@ -1,9 +1,11 @@
 #!/usr/bin/env node
 import { readCodingInput, writeCodingOutputAtomic } from "../coding-worker/artifact.js";
+import { describeError, workerDebugTracer } from "../coding-worker/debug-trace.js";
 import { safeOutputIssues, safeWorkerErrorCode } from "../coding-worker/errors.js";
-import { runClaudeCodingWorker } from "./driver.js";
+import { CLAUDE_CONFIG_DIR, runClaudeCodingWorker } from "./driver.js";
 import { createClaudeSdkQuery } from "./sdk.js";
-import { assertToolRunnerReachable } from "./tool-socket.js";
+import { assertToolRunnerReachable, callPrepareDependencies } from "./tool-socket.js";
+import { runTitle, TRANSCRIPT_OUTPUT_PATH, writeWorkerTranscript } from "./transcript.js";
 const INPUT_PATH = "/run/wardby/input/input.json";
 const OUTPUT_PATH = "/run/wardby/output/result.json";
 function required(name) {
@@ -16,22 +18,36 @@ const controller = new AbortController();
 for (const signal of ["SIGTERM", "SIGINT"])
     process.once(signal, () => controller.abort());
 let stage = "input";
+// Only for a run the operator asked to trace; see coding-worker/debug-trace.ts. Pod log only.
+let trace;
+let input;
+let sessionId;
 try {
-    const input = await readCodingInput(INPUT_PATH);
+    const task = await readCodingInput(INPUT_PATH);
+    input = task;
     stage = "execution";
+    const proxyBaseUrl = required("WARDBY_PROXY_URL");
+    const capability = required("WARDBY_RUN_CAPABILITY");
+    trace = workerDebugTracer(task, capability, (line) => process.stdout.write(line));
     await assertToolRunnerReachable();
     const output = await runClaudeCodingWorker({
-        input,
-        proxyBaseUrl: required("WARDBY_PROXY_URL"),
-        capability: required("WARDBY_RUN_CAPABILITY"),
+        input: task,
+        proxyBaseUrl,
+        capability,
         signal: controller.signal,
         createQuery: createClaudeSdkQuery,
+        prepareDependencies: () => callPrepareDependencies({ signal: controller.signal, deadlineAt: task.deadlineAt }),
         onProgress: (event) => process.stdout.write(`${JSON.stringify(event)}\n`),
+        trace,
+        onSessionId: (id) => {
+            sessionId ??= id;
+        },
     });
     stage = "output";
     await writeCodingOutputAtomic(OUTPUT_PATH, output);
 }
 catch (error) {
+    trace?.record("worker_error", { stage, error: describeError(error) });
     const safeCode = safeWorkerErrorCode(error);
     const code = controller.signal.aborted
         ? "worker_cancelled"
@@ -42,3 +58,15 @@ catch (error) {
     process.stderr.write(`${JSON.stringify({ error: code, ...(issues ? { issues } : {}) })}\n`);
     process.exitCode = controller.signal.aborted ? 143 : 1;
 }
+// Session resume: after the result (or failure) is written, so a capture problem never changes the
+// run's outcome or exit code. Not on cancellation: the pod is being stopped.
+if (input?.sessionResume && sessionId && !controller.signal.aborted) {
+    await writeWorkerTranscript({
+        configDir: CLAUDE_CONFIG_DIR,
+        sessionId,
+        outputPath: TRANSCRIPT_OUTPUT_PATH,
+        title: runTitle(input.runId, input.task),
+    }).catch(() => {
+        process.stderr.write(`${JSON.stringify({ warning: "transcript_capture_failed" })}\n`);
+    });
+}

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

@@ -1,20 +1,33 @@
 import { createRequire } from "node:module";
+import { PREPARE_DEPENDENCIES_TOOL } from "./tool-socket.js";
 const runtimeRequire = createRequire(import.meta.url);
 const TOOL_NAME = "mcp__wardby_tools__run_command";
+/**
+ * The tool runner's internal dependency-cache tool (PREPARE_DEPENDENCIES_TOOL, tool-socket.ts): the
+ * worker calls it itself before the query. Disallowed, so it never reaches the model's context;
+ * dontAsk plus allowedTools would already deny it, this keeps it out of the tool list as well.
+ */
+const PREPARE_DEPENDENCIES_TOOL_NAME = `mcp__wardby_tools__${PREPARE_DEPENDENCIES_TOOL}`;
 export function buildClaudeSdkOptions(config) {
     const abortController = new AbortController();
     if (config.signal.aborted)
         abortController.abort();
     else
         config.signal.addEventListener("abort", () => abortController.abort(), { once: true });
+    const context = config.contextDirectory;
+    const skills = context !== null && config.skills;
     return {
         abortController,
-        cwd: "/opt/wardby/empty-workspace",
+        // Native mode with repo context: Claude Code loads CLAUDE.md (and skills) from a directory the
+        // worker wrote (context.ts), which holds only allowlisted Markdown files: no settings, hooks,
+        // or MCP config. Otherwise an empty directory and no setting sources.
+        cwd: context ?? "/opt/wardby/empty-workspace",
         model: config.model,
         maxTurns: config.maxTurns,
         maxBudgetUsd: config.budgetUsd,
-        tools: [],
-        allowedTools: [TOOL_NAME],
+        tools: skills ? ["Skill"] : [],
+        allowedTools: skills ? [TOOL_NAME, "Skill"] : [TOOL_NAME],
+        disallowedTools: [PREPARE_DEPENDENCIES_TOOL_NAME],
         strictMcpConfig: true,
         mcpServers: {
             wardby_tools: {
@@ -25,12 +38,19 @@ export function buildClaudeSdkOptions(config) {
                 alwaysLoad: true,
             },
         },
-        settingSources: [],
+        settingSources: context ? ["project"] : [],
+        // Second layer for native mode: only hooks from managed settings may run, and there are none, so
+        // a hook in any project file (settings or SKILL.md frontmatter) is ignored. This SDK's
+        // managedSettings keeps only restrictive keys; allowManagedHooksOnly is the hook lock it accepts.
+        ...(context ? { managedSettings: { allowManagedHooksOnly: true } } : {}),
         systemPrompt: config.developerInstructions,
         outputFormat: { type: "json_schema", schema: config.outputSchema },
         permissionMode: "dontAsk",
-        persistSession: false,
+        // Only a session-resume run keeps the session file (under CLAUDE_CONFIG_DIR) for transcript capture.
+        persistSession: config.persistSession,
         env: config.environment,
+        // Only on a traced run; otherwise the SDK's default handling is unchanged.
+        ...(config.stderr ? { stderr: config.stderr } : {}),
     };
 }
 /** Loads the pinned SDK from the worker image's private dependency directory. */

package/dist/claude-coding-worker/tool-socket.d.ts

@@ -7,3 +7,30 @@ export declare const TOOL_SOCKET_PATH = "/run/wardby/tool/runner.sock";
  * a socket bound on a volume the two containers don't share is simply absent from this side.)
  */
 export declare function assertToolRunnerReachable(socketPath?: string, timeoutMs?: number): Promise<void>;
+/** The tool runner's internal tool (claude-tool-runner/main.mjs); the agent's SDK options disallow it (sdk.ts). */
+export declare const PREPARE_DEPENDENCIES_TOOL = "wardby_prepare_dependencies";
+/**
+ * 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 declare const PREPARE_DEPENDENCIES_TIMEOUT_MS: number;
+export interface PrepareDependenciesCall {
+    socketPath?: string;
+    /** Defaults to the cache's bound for `deadlineAt` (dependencyCacheTimeLimit) plus its settle grace and a margin. */
+    timeoutMs?: number;
+    signal?: AbortSignal;
+    /** The run's deadline (CodingTaskInput.deadlineAt), passed to the tool: the cache takes at most half the time left. */
+    deadlineAt?: string;
+}
+/** How long the worker waits for the prepare tool on a run with this deadline. */
+export declare function prepareDependenciesTimeoutMs(deadlineAt?: string, now?: number): number;
+/**
+ * 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 declare function callPrepareDependencies({ socketPath, deadlineAt, timeoutMs, signal, }?: PrepareDependenciesCall): Promise<unknown>;

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/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]\n      (owned by --owner or LOCAL_PRINCIPAL; --public shares it with everyone at execute)\n  wardby agent list\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 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] [--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 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";

package/dist/cli-help.js

@@ -5,12 +5,15 @@ export const CLI_USAGE = `usage:
   wardby logs [--tail N] [--follow]
   wardby down [--volumes]
   wardby knowledge check [dir] [--root <dir>] [--strict] [--json]   Validate a knowledge bundle (offline)
+  wardby resume - [--dir <path> | --here] [--force] [--print]   Continue a coding run's Claude Code session locally (paste the get_run_transcript link)
   wardby help [list]
   wardby help search <terms>
   wardby help open <article-id>
-  wardby agent create --name <n> --model <m> --prompt <p> --budget <usd> [--schedule "<cron>"] [--timezone <tz>] [--max-turns <n>] [--owner <subject>] [--public]
-      (owned by --owner or LOCAL_PRINCIPAL; --public shares it with everyone at execute)
+  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]
+      (owned by --owner or LOCAL_PRINCIPAL; --public shares it with everyone at execute;
+       sandbox needs NATIVE_SANDBOX_LAUNCHER set in this environment)
   wardby agent list
+  wardby agent mode <name> control-plane|sandbox   (native agents; applies to runs created after the change)
   wardby agent schedule <name> --cron "<expr>" [--timezone <tz>] [--disable]
   wardby tool create --name <n> --description <d> --params <file> --code <file>
   wardby tool attach <tool-name|tool-id> <agent-name>   (grants the capabilities in the agent owner's name)
@@ -23,6 +26,7 @@ export const CLI_USAGE = `usage:
   wardby coding preflight   (JOB_LAUNCHER=docker or kubernetes)
   wardby coding cleanup --run-id <id>
   wardby scheduler [--scope default]
+  wardby native-gateway   (the native sandbox gateway only; NATIVE_GATEWAY_LISTEN, default 0.0.0.0:8790)
   wardby mcp   (MCP_TRANSPORT=stdio|http selects the transport)
   wardby serve [--scope default]   (mcp + scheduler + reconciler in one process; http only)
   wardby grants migration-report [--json]

package/dist/cli-native-mode.d.ts

@@ -0,0 +1,9 @@
+import type { NativeExecutionMode } from "#prisma";
+/**
+ * `--native-execution-mode` for the CLI: the operator spelling MCP takes
+ * (`control-plane` | `sandbox`) mapped to the stored enum. `sandbox` is
+ * refused unless this process's environment configures a native sandbox, the
+ * same rule `create_agent`/`update_agent` apply, so the CLI never stores a
+ * mode whose every run would fail closed. Throws with the message to print.
+ */
+export declare function parseCliNativeExecutionMode(value: string, env?: NodeJS.ProcessEnv): NativeExecutionMode;

package/dist/cli-native-mode.js

@@ -0,0 +1,20 @@
+import { loadNativeSandboxConfig } from "./config/providers.js";
+/**
+ * `--native-execution-mode` for the CLI: the operator spelling MCP takes
+ * (`control-plane` | `sandbox`) mapped to the stored enum. `sandbox` is
+ * refused unless this process's environment configures a native sandbox, the
+ * same rule `create_agent`/`update_agent` apply, so the CLI never stores a
+ * mode whose every run would fail closed. Throws with the message to print.
+ */
+export function parseCliNativeExecutionMode(value, env = process.env) {
+    if (value === "control-plane")
+        return "control_plane";
+    if (value !== "sandbox") {
+        throw new Error(`the native execution mode must be "control-plane" or "sandbox" (got "${value}").`);
+    }
+    if (loadNativeSandboxConfig(env) === undefined) {
+        throw new Error("native_sandbox_unavailable: this environment has no native sandbox configured (set NATIVE_SANDBOX_LAUNCHER), " +
+            'so an agent cannot use native execution mode "sandbox".');
+    }
+    return "sandbox";
+}

package/dist/cli.d.ts

@@ -2,12 +2,14 @@
 /**
  * Minimal CLI.
  *
- *   wardby agent create --name <n> --model <m> --prompt <p> --budget <usd> [--schedule "<cron>"] [--timezone <tz>] [--memory-enabled] [--effort <level>]
+ *   wardby agent create --name <n> --model <m> --prompt <p> --budget <usd> [--schedule "<cron>"] [--timezone <tz>] [--memory-enabled] [--effort <level>] [--native-execution-mode control-plane|sandbox]
  *   wardby agent list
+ *   wardby agent mode <name> control-plane|sandbox
  *   wardby agent schedule <name> --cron "<expr>" [--timezone <tz>] [--disable]
  *   wardby run <name>
  *   wardby runs [--agent <name>] [--limit N] [--status <s>]
  *   wardby scheduler [--scope default]
+ *   wardby native-gateway   (the native sandbox gateway only; NATIVE_GATEWAY_LISTEN)
  *   wardby mcp   (MCP_TRANSPORT=stdio|http selects the transport; authoring/
  *                control is MCP-first from here — this floor keeps working
  *                before/without an MCP client)