@wardby/cli 0.5.2 → 0.6.0

package/dist/viewer/event-bus.js

@@ -16,6 +16,7 @@
 import pg from "pg";
 import { poolSettings } from "../core/db.js";
 import { logger } from "../core/logger.js";
+import { databaseAuthFromEnv, pgConnectionConfig } from "../core/pg-auth.js";
 import { ViewerEventSchema } from "./api-schema.js";
 export const VIEWER_CHANNEL = "wardby_viewer";
 const DEFAULT_RECONNECT_DELAYS_MS = [500, 1000, 2000, 5000, 10_000];
@@ -25,17 +26,25 @@ const DEFAULT_HEALTH_CHECK_INTERVAL_MS = 60_000;
 const DEFAULT_HEALTH_CHECK_TIMEOUT_MS = 10_000;
 /** Upper bound on waiting for a graceful disconnect (a half-open socket never answers). */
 const END_TIMEOUT_MS = 2_000;
+/** The LISTEN client's config: auth (pg-auth.ts) plus keepAlive and the pool's connect timeout. */
+export function eventBusClientConfig(connectionString, auth, pgAuth) {
+    return {
+        ...pgConnectionConfig(connectionString, auth, pgAuth),
+        keepAlive: true,
+        keepAliveInitialDelayMillis: KEEPALIVE_INITIAL_DELAY_MS,
+        connectionTimeoutMillis: poolSettings(connectionString).connectionTimeoutMillis,
+    };
+}
 export function createViewerEventBus(options) {
     const healthIntervalMs = options.healthCheckIntervalMs ?? DEFAULT_HEALTH_CHECK_INTERVAL_MS;
     const healthTimeoutMs = options.healthCheckTimeoutMs ?? DEFAULT_HEALTH_CHECK_TIMEOUT_MS;
     const delays = options.reconnectDelaysMs?.length ? options.reconnectDelaysMs : DEFAULT_RECONNECT_DELAYS_MS;
-    const makeClient = options.connect ??
-        ((connectionString) => new pg.Client({
-            connectionString,
-            keepAlive: true,
-            keepAliveInitialDelayMillis: KEEPALIVE_INITIAL_DELAY_MS,
-            connectionTimeoutMillis: poolSettings(connectionString).connectionTimeoutMillis,
-        }));
+    // Built once, up front: a misconfigured DATABASE_AUTH fails here rather than on every reconnect,
+    // and under rds-iam every reconnect shares one token cache.
+    const clientConfig = options.connect
+        ? undefined
+        : eventBusClientConfig(options.connectionString, options.auth ?? databaseAuthFromEnv(), options.pgAuth);
+    const makeClient = options.connect ?? (() => new pg.Client({ ...clientConfig }));
     const listeners = new Set();
     const stateListeners = new Set();
     let client = null; // the current attempt/connection

package/dist/viewer/graph.d.ts

@@ -1,8 +1,6 @@
 /** The graph snapshot read model behind GET /admin/api/graph (docs/viewer-api.md). */
 import type { Prisma, PrismaClient } from "#prisma";
 import type { GraphRun, GraphSnapshot } from "./api-schema.js";
-export declare const DEFAULT_GRAPH_LIMIT = 500;
-export declare const MAX_GRAPH_LIMIT = 2000;
 /** Accepts "15m" | "1h" | "6h" | "24h" | "7d" or an ISO-8601 timestamp; null defaults to 1h. Throws otherwise. */
 export declare function parseSince(value: string | null, now: Date): Date;
 declare const runInclude: {
@@ -23,6 +21,11 @@ declare const runInclude: {
             createdAt: "asc";
         };
     };
+    nativeWarmWorker: {
+        select: {
+            name: true;
+        };
+    };
 };
 type RunRow = Prisma.RunGetPayload<{
     include: typeof runInclude;

package/dist/viewer/graph.js

@@ -1,7 +1,5 @@
 import { periodStart } from "../core/budget-groups.js";
 import { publicCodingRunResult } from "../coding/protocol.js";
-export const DEFAULT_GRAPH_LIMIT = 500;
-export const MAX_GRAPH_LIMIT = 2000;
 const DEFAULT_SINCE_MS = 60 * 60 * 1000;
 const RELATIVE_SINCE_MS = {
     "15m": 15 * 60 * 1000,
@@ -30,6 +28,7 @@ const runInclude = {
     hostStatus: true,
     issueStatus: true,
     serviceStatuses: { orderBy: { createdAt: "asc" } },
+    nativeWarmWorker: { select: { name: true } },
 };
 const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
 /** Name and version of each service in a coding run's resolved services snapshot. */
@@ -151,6 +150,12 @@ export function toGraphRun(row, pullRequests, sites = {}) {
         agentKind: row.agent.kind,
         model: row.codingRun?.model ?? row.agent.model,
         codingProvider: row.codingRun?.provider ?? null,
+        nativeExecutionMode: row.nativeExecutionMode === "sandbox"
+            ? "sandbox"
+            : row.nativeExecutionMode === "control_plane"
+                ? "control-plane"
+                : null,
+        warmWorkerName: row.nativeWarmWorker?.name ?? null,
         status: row.status,
         trigger: triggerFor(row, sites),
         turns: row.turns,

package/dist/viewer/http.d.ts

@@ -12,7 +12,6 @@ import type { InfraInfo } from "./api-schema.js";
 import { type IssueSites } from "./graph.js";
 import type { ViewerEventBus } from "./event-bus.js";
 export declare const VIEWER_API_PREFIX = "/admin/api/";
-export declare const SSE_HEARTBEAT_MS = 15000;
 /** A stream whose unsent backlog exceeds this is ended; the client reconnects and resyncs. */
 export declare const SSE_MAX_BUFFERED_BYTES: number;
 export interface ViewerApiDeps {

package/dist/viewer/http.js

@@ -1,9 +1,9 @@
 import { requireScope } from "../mcp/auth/resource-server.js";
 import { sendJson } from "../mcp/transport/streamable-http.js";
-import { DEFAULT_GRAPH_LIMIT, MAX_GRAPH_LIMIT, loadGraph, parseSince } from "./graph.js";
+import { loadGraph, parseSince } from "./graph.js";
+import { DEFAULT_GRAPH_LIMIT, MAX_GRAPH_LIMIT, SSE_HEARTBEAT_MS } from "./limits.js";
 import { loadRunDetail } from "./run-detail.js";
 export const VIEWER_API_PREFIX = "/admin/api/";
-export const SSE_HEARTBEAT_MS = 15_000;
 /** A stream whose unsent backlog exceeds this is ended; the client reconnects and resyncs. */
 export const SSE_MAX_BUFFERED_BYTES = 1024 * 1024;
 const RUN_ID = /^[A-Za-z0-9_-]{1,64}$/;

package/dist/viewer/infra.js

@@ -1,14 +1,17 @@
 /** The read model behind GET /admin/api/infra (docs/viewer-api.md): built once at startup, no cluster reads. */
-import { loadKubernetesJobConfig, loadProviderConfig } from "../config/providers.js";
+import { loadKubernetesJobConfig, loadNativeSandboxConfig, loadProviderConfig } from "../config/providers.js";
+import { NATIVE_RUN_COMPONENT_LABEL, NATIVE_RUN_SHA_LABEL, NATIVE_WARM_POOL_LABEL, NATIVE_WARM_TOKEN_LABEL, } from "../native-worker/kubernetes-isolation.js";
 import { RUN_COMPONENT_LABEL, RUN_MANAGED_BY_LABEL, RUN_SHA_CHARS, RUN_SHA_LABEL, } from "../providers/jobs/kubernetes-isolation.js";
 export function buildInfraInfo(env = process.env) {
     const raw = loadProviderConfig(env).jobs;
     const launcher = raw === "docker" || raw === "kubernetes" ? raw : "local";
+    const native = buildNativeInfo(env);
     if (launcher !== "kubernetes")
-        return { launcher, kubernetes: null };
+        return { launcher, kubernetes: null, native };
     const k8s = loadKubernetesJobConfig(env);
     return {
         launcher,
+        native,
         kubernetes: {
             namespace: k8s.namespace,
             platform: k8s.platform,
@@ -21,3 +24,23 @@ export function buildInfraInfo(env = process.env) {
         },
     };
 }
+/** Where sandbox-mode native agents run (NATIVE_SANDBOX_*); null when no sandbox launcher is configured. */
+function buildNativeInfo(env) {
+    const config = loadNativeSandboxConfig(env);
+    if (!config)
+        return null;
+    return {
+        launcher: config.launcher,
+        warmPoolSize: config.warmPoolSize,
+        kubernetes: config.launcher === "kubernetes"
+            ? {
+                namespace: config.namespace,
+                runtimeClass: config.runtimeClassName ?? null,
+                runLabel: NATIVE_RUN_SHA_LABEL,
+                componentLabel: { ...NATIVE_RUN_COMPONENT_LABEL },
+                warmPoolLabel: { ...NATIVE_WARM_POOL_LABEL },
+                warmWorkerLabel: NATIVE_WARM_TOKEN_LABEL,
+            }
+            : null,
+    };
+}

package/dist/viewer/limits.d.ts

@@ -0,0 +1,4 @@
+/** Viewer API constants shared by the server and the OpenAPI generator (no runtime imports). */
+export declare const DEFAULT_GRAPH_LIMIT = 500;
+export declare const MAX_GRAPH_LIMIT = 2000;
+export declare const SSE_HEARTBEAT_MS = 15000;

package/dist/viewer/limits.js

@@ -0,0 +1,4 @@
+/** Viewer API constants shared by the server and the OpenAPI generator (no runtime imports). */
+export const DEFAULT_GRAPH_LIMIT = 500;
+export const MAX_GRAPH_LIMIT = 2000;
+export const SSE_HEARTBEAT_MS = 15_000;

package/dist/viewer/openapi.d.ts

@@ -0,0 +1,15 @@
+export declare const OPENAPI_PATH: string;
+type Json = Record<string, unknown>;
+export interface ViewerRoute {
+    path: string;
+    operationId: string;
+    summary: string;
+    description: string;
+    parameters?: readonly Json[];
+    responses: Readonly<Record<string, Json>>;
+}
+export declare const VIEWER_ROUTES: readonly ViewerRoute[];
+export declare function buildViewerOpenApi(version: string): Json;
+export declare const HEADER = "# Generated by npm run build:viewer-schemas from src/viewer/api-schema.ts and src/viewer/openapi.ts. Do not edit.";
+export declare function renderViewerOpenApi(version: string): string;
+export {};

package/dist/viewer/openapi.js

@@ -0,0 +1,172 @@
+/**
+ * Builds the published OpenAPI 3.1 document for the admin viewer API
+ * (docs/viewer-api.openapi.yml) from the zod schemas and a route table.
+ * Generated by `npm run build:viewer-schemas`; never edit the YAML by hand.
+ */
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { stringify } from "yaml";
+import { zodToJsonSchema } from "zod-to-json-schema";
+import { VIEWER_SCHEMAS } from "./api-schema.js";
+import { DEFAULT_GRAPH_LIMIT, MAX_GRAPH_LIMIT, SSE_HEARTBEAT_MS } from "./limits.js";
+export const OPENAPI_PATH = join(dirname(fileURLToPath(import.meta.url)), "../../docs/viewer-api.openapi.yml");
+const AUTH_NOTE = "Requires a bearer token with the `admin:view` scope, held by a caller with the admin role.";
+const ref = (name) => ({ $ref: `#/components/schemas/${name}` });
+const errorBody = (codes, description) => {
+    const list = codes.split(", ");
+    return {
+        description,
+        content: {
+            "application/json": {
+                schema: { allOf: [ref("ViewerError"), { properties: { error: { enum: list } } }] },
+            },
+        },
+        "x-error-codes": list,
+    };
+};
+const wwwAuthenticate = { "WWW-Authenticate": { $ref: "#/components/headers/WWWAuthenticate" } };
+export const VIEWER_ROUTES = [
+    {
+        path: "/admin/api/graph",
+        operationId: "getGraph",
+        summary: "Graph snapshot",
+        description: "Agents, runs, coding-run services and outcomes for a time window, as a graph.",
+        parameters: [
+            {
+                name: "since",
+                in: "query",
+                required: false,
+                description: "Window start: `15m`, `1h`, `6h`, `24h`, `7d`, or an ISO-8601 timestamp. Default `1h`.",
+                schema: { type: "string", default: "1h" },
+            },
+            {
+                name: "limit",
+                in: "query",
+                required: false,
+                description: `Maximum number of runs, 1 to ${MAX_GRAPH_LIMIT}. Default ${DEFAULT_GRAPH_LIMIT}.`,
+                schema: { type: "integer", minimum: 1, maximum: MAX_GRAPH_LIMIT, default: DEFAULT_GRAPH_LIMIT },
+            },
+        ],
+        responses: {
+            "200": {
+                description: "The graph snapshot.",
+                content: { "application/json": { schema: ref("graph-snapshot") } },
+            },
+            "400": errorBody("invalid_since, invalid_limit", "A query parameter is invalid."),
+        },
+    },
+    {
+        path: "/admin/api/runs/{id}",
+        operationId: "getRun",
+        summary: "Run detail",
+        description: "Full detail for one run, including final text.",
+        parameters: [{ name: "id", in: "path", required: true, description: "Run id.", schema: { type: "string" } }],
+        responses: {
+            "200": { description: "The run.", content: { "application/json": { schema: ref("run-detail") } } },
+            "404": errorBody("not_found", "No run with that id."),
+        },
+    },
+    {
+        path: "/admin/api/infra",
+        operationId: "getInfra",
+        summary: "Infrastructure info",
+        description: "Where and how this wardby deployment runs its workloads.",
+        responses: {
+            "200": { description: "Infrastructure info.", content: { "application/json": { schema: ref("infra-info") } } },
+        },
+    },
+    {
+        path: "/admin/api/events",
+        operationId: "getEvents",
+        summary: "Live event stream",
+        description: [
+            "A Server-Sent Events stream (`text/event-stream`) of live changes. Frames:",
+            "",
+            "- `retry: 3000`: suggested client reconnect delay in milliseconds.",
+            '- `event: hello`: sent first. Data is `{"connected": <bool>}`, whether the server\'s live-event connection is up.',
+            "- `event: run`, `event: service`, `event: outcome`: a run, coding-run service, or outcome changed. Each carries an `id:` line. Payloads match the `viewer-event` schema (see `x-event-schema`).",
+            '- `event: status`: the server\'s live-event connection changed. Data is `{"connected": <bool>}`.',
+            "- `event: resync`: the live-event connection is up (again). Events may have been missed: refetch the graph.",
+            `- \`: ping\`: comment sent every ${SSE_HEARTBEAT_MS / 1000} seconds to keep the connection open.`,
+            "",
+            "There is no replay. Open the event stream first, then load `/admin/api/graph` and apply events on top of it. Refetch the graph on every `resync` and after every reconnect rather than trying to resume.",
+        ].join("\n"),
+        responses: {
+            "200": {
+                description: "The event stream.",
+                content: { "text/event-stream": { schema: { type: "string" } } },
+                "x-event-schema": ref("viewer-event"),
+            },
+        },
+    },
+];
+function componentSchemas() {
+    const schemas = {};
+    for (const [name, schema] of Object.entries(VIEWER_SCHEMAS)) {
+        const json = zodToJsonSchema(schema, { target: "jsonSchema2019-09", $refStrategy: "none" });
+        delete json.$schema;
+        schemas[name] = json;
+    }
+    schemas.ViewerError = {
+        type: "object",
+        required: ["error"],
+        properties: { error: { type: "string" } },
+        additionalProperties: false,
+    };
+    schemas.ViewerInternalError = {
+        type: "object",
+        required: ["error", "id"],
+        properties: { error: { type: "string", enum: ["internal_error"] }, id: { type: "string" } },
+        additionalProperties: false,
+    };
+    return schemas;
+}
+function operation(route) {
+    return {
+        operationId: route.operationId,
+        summary: route.summary,
+        description: `${route.description}\n\n${AUTH_NOTE}`,
+        security: [{ bearer: [] }],
+        ...(route.parameters ? { parameters: route.parameters } : {}),
+        responses: {
+            ...route.responses,
+            "401": { ...errorBody("invalid_token", "No valid bearer token."), headers: wwwAuthenticate },
+            "403": {
+                ...errorBody("invalid_token", "Token lacks the `admin:view` scope (the `WWW-Authenticate` header is present), or the caller lacks the admin role (no `WWW-Authenticate` header)."),
+                headers: wwwAuthenticate,
+            },
+            "405": {
+                ...errorBody("method_not_allowed", "Only GET is allowed."),
+                headers: { Allow: { description: "Allowed methods: GET.", schema: { type: "string", enum: ["GET"] } } },
+            },
+            default: {
+                description: "Unexpected server error (HTTP 500). `id` identifies the failure in the server log.",
+                content: { "application/json": { schema: ref("ViewerInternalError") } },
+            },
+        },
+    };
+}
+export function buildViewerOpenApi(version) {
+    const paths = {};
+    for (const route of VIEWER_ROUTES)
+        paths[route.path] = { get: operation(route) };
+    return {
+        openapi: "3.1.0",
+        info: {
+            title: "wardby admin viewer API",
+            version,
+            description: "Read-only admin API behind the wardby viewer: graph, run detail, infrastructure info and a live event stream. Response objects may gain new fields in later releases; clients should ignore unknown fields. See docs/viewer-api.md for the prose contract.",
+        },
+        servers: [{ url: "https://{host}", variables: { host: { default: "wardby.example.com" } } }],
+        paths,
+        components: {
+            securitySchemes: { bearer: { type: "http", scheme: "bearer" } },
+            headers: { WWWAuthenticate: { description: "Bearer challenge.", schema: { type: "string" } } },
+            schemas: componentSchemas(),
+        },
+    };
+}
+export const HEADER = "# Generated by npm run build:viewer-schemas from src/viewer/api-schema.ts and src/viewer/openapi.ts. Do not edit.";
+export function renderViewerOpenApi(version) {
+    return `${HEADER}\n${stringify(buildViewerOpenApi(version), { lineWidth: 0, aliasDuplicateObjects: false })}`;
+}

package/docs/README.md

@@ -18,6 +18,11 @@
 - [Architecture knowledge bundles](knowledge.md) covers `docs/knowledge/`: the
   concept format, how coding runs and reviewers use it, `wardby knowledge check`,
   and the scheduled architecture agent.
+- [Native sandbox](native-sandbox.md) (0.5.4+) runs a native agent's turn loop and user
+  tools in a single-use, credential-free container behind a native gateway.
+- [Secrets and tools](tool-secrets.md) covers readable and brokered secrets
+  (brokered secrets require 0.6.0+):
+  attaching secrets to tools, `set_secret_broker`, placements, and errors.
 - [Coding-worker isolation](coding-worker-isolation.md) documents the threat
   model and enforced worker boundary.
 - [Bring-your-own worker images](coding-worker-byo-images.md) explains how to
@@ -29,6 +34,8 @@
   the catalog, per-agent permission, variables, and errors.
 - [Jira agents](jira-agents.md) connects wardby to Jira Cloud with a service
   account and webhook, and links agents to projects.
+- [Send workflow updates to Slack](slack-notifications.md) (0.6.0+) links a Slack
+  channel to a Jira project or an agent to follow cards from pickup to merge.
 - [Observability](observability.md) covers Prometheus metrics, Grafana, cloud
   collectors, retention, and production ownership.
 - [Release verification](release-verification.md) lists the automated and live

package/docs/agent-recipes.md

@@ -336,7 +336,9 @@ toolchain, build your own image on Wardby's driver base image and point the
 agent at it with `workerImageRef`, a digest-pinned reference (a mutable tag is
 rejected). Setting it needs the `agents:admin` scope and the admin role. The
 Dockerfile shape, the driver image, and what Wardby does and does not verify are
-in [Bring-your-own worker images](coding-worker-byo-images.md).
+in [Bring-your-own worker images](coding-worker-byo-images.md). For a Claude
+Code agent, build the image on the release's tool runner image instead; see
+[Codex and Claude Code](coding-worker-byo-images.md#codex-and-claude-code).
 
 ```json
 {
@@ -423,14 +425,61 @@ the lead's `maxDelegationsPerRun` (1 to 20) with `create_agent` or
 - Wardby adds a **Related pull requests** section to each pull request the
   builders open, listing the others with links, states (open, draft, merged,
   closed) and the originating issue. With a Jira issue, the list covers every
-  pull request recorded for that issue in any run. Open ones are numbered as a
+  pull request recorded for that issue in any run. When no pull request in the
+  set carries a `mergeOrder` (see below), open ones are numbered as a
   **Suggested merge order** — the order the lead delegated in, not a
-  guarantee; merged and closed ones are listed separately as context. A pull
-  request lists the ones opened before it as soon as it is opened; when the
-  lead run finishes, and whenever a later run pushes to one of them, every
-  open one is rewritten with the full list. Text you add inside the section is
-  replaced; the rest of the description is not touched. Only pull requests the
-  App opened and that are still open are edited.
+  guarantee. When any pull request in the set carries one (open, merged or
+  closed), the open ones that have a `mergeOrder` are numbered under
+  **Merge order (set by the delegating agent; equal steps can merge in either
+  order)** and labelled "step k of n" (equal values share a step), and any
+  open pull request without one is listed after under **Not ordered**. If
+  only merged or closed pull requests carry a `mergeOrder`, the open ones are
+  all listed under **Not ordered**, with no **Merge order** heading. Steps
+  are counted over the whole set, merged and closed pull requests included,
+  so a label stays the same as earlier steps merge. Merged and closed pull
+  requests are always listed separately as context, with their step label
+  when they have one. A pull request lists the ones opened before it as
+  soon as it is opened; when the lead run finishes, and whenever a later run
+  pushes to one of them, every open one is rewritten with the full list. Text
+  you add inside the section is replaced; the rest of the description is not
+  touched. Only pull requests the App opened and that are still open are
+  edited. With Wardby 0.6.0 or later, a reviewer linked to one of these repositories
+  also holds its review of such a pull request until the lead run finishes,
+  however it ends, so every pull request of the request is open by the time
+  any of them is reviewed. When the lead finishes normally the section above
+  has been rewritten by then; when it is ended another way (for example,
+  cancelled), reviews start without that rewrite, and reviewers use
+  `repo_pr_read`'s `relatedPullRequests` either way — see
+  [Reviewing a pull request a delegated run
+  opened](code-review-agents.md#reviewing-a-pull-request-a-delegated-run-opened).
+- Each `delegate_to_<name>` call to a coding sub-agent can carry a
+  `mergeOrder`: an integer from 1 to 99, where 1 merges first. Give a
+  repository that other repositories' changes depend on a lower number than
+  the ones that call it — for example a service `1`, the API in front of it
+  `2`, the client `3` — and give two changes the same number when there is no
+  order between them. Set it whenever one change spans several repositories
+  and the pull requests must land in a particular sequence; leave it unset
+  and the set keeps the delegation-order "Suggested merge order" above. A
+  native sub-agent has no pull request to order, so it ignores `mergeOrder`
+  and the tool result notes that it did. Each pull request shows the value
+  most recently set for it, by the run that opened it or a later
+  continuation of it: a `continuePriorRun` call that omits `mergeOrder`
+  keeps that value, and one that sets `mergeOrder` replaces it. A
+  bad value (not an integer, or outside 1-99) is refused as a tool error
+  rather than silently ignored.
+- With Wardby 0.6.0 or later, once a set has more than one distinct
+  `mergeOrder`, each open or draft pull request Wardby opened in it also
+  gets a check run named exactly `wardby merge order`: `in_progress` while
+  an earlier step hasn't merged, `success` once every earlier step has
+  (or there is none), and `failure` if an earlier step was closed without
+  merging. Above the set's lowest step, a would-be `success` stays
+  `in_progress` ("waiting for the delegating run to finish") while the
+  delegating (lead) agent's run is still running — it may still add or
+  reorder steps. A coding run that continues one of the pull requests on
+  its own (a review fix round, an `@` mention) never holds it. Posting it never
+  blocks a merge by itself: add `wardby merge order` as a required status
+  check in branch protection to gate on it. See
+  [The wardby merge order check](../help/merge-order-check.md).
 - The section, and the follow-up hints below, list every pull request in the
   set by repository name and number. A request that spans repositories of
   different visibility can therefore show a private repository's name in a

package/docs/architecture-runtime.md

@@ -73,10 +73,14 @@ credentials, still reaches only the proxy, and the proxy still owns the ledger.
 
 | `JOB_LAUNCHER` | Worker runs in                   | Isolation                                            |
 | -------------- | -------------------------------- | ---------------------------------------------------- |
-| `local`        | a child process on this host     | development only, no isolation                       |
+| `local`        | nowhere: no coding launcher      | native agents only; coding runs fail before starting |
 | `docker`       | a container on a per-run network | the diagram above                                    |
 | `kubernetes`   | a pod in a namespace             | per-run NetworkPolicy, attested pod, optional gVisor |
 
+`local` is the default. It composes no coding launcher, so a coding run ends
+with "Coding agents need a container executor"; set `docker` or `kubernetes`
+to run coding agents.
+
 Under `kubernetes` the shape is the same with different nouns: the per-run
 Docker network becomes a NetworkPolicy, the keeper and worker share a pod
 instead of a volume, and the proxy is a Service rather than a container name.
@@ -88,3 +92,14 @@ or not anything enforces it. See
 [coding-worker-isolation.md](coding-worker-isolation.md) for the mechanics and
 the [Kubernetes deployment guide](../deploy/kind-coding/README.md) for the local
 and GKE Autopilot overlays.
+
+### Native agents in a sandbox
+
+Native sandbox requires Wardby 0.5.4 or later.
+
+Native agents run in the server process by default. A native agent set to
+`nativeExecutionMode=sandbox` instead runs its turn loop and user tools in a
+single-use credential-free container whose only path out is a separate native
+gateway, enabled with `NATIVE_SANDBOX_LAUNCHER=docker` or `kubernetes` (a pod
+per run, including on GKE Autopilot under gVisor; independent of
+`JOB_LAUNCHER`). See [native-sandbox.md](native-sandbox.md).