@wardby/cli 0.2.0 → 0.2.1

package/README.md

@@ -2,16 +2,17 @@
   <img align="left" hspace="24" src="https://raw.githubusercontent.com/wardby/wardby/main/docs/assets/brand/wardby-mascot.png" alt="Wardby guardian robot protecting an agent budget" width="280">
   <h3><big><big>Wardby</big></big> <small><em>(pronounced&nbsp;“WARD&#8209;bee”)</em></small></h3>
   <h3>Autonomous agents, bounded by design.</h3>
-  <p><strong>Most agent runners focus on helping a model complete a task. Wardby is the self-hosted control plane that decides whether the task should run, limits what it can access, and returns a reviewable outcome governed by explicit policy.</strong></p>
+  <p><strong>Agent runners help a model complete a task. Wardby is the self-hosted control plane that governs the work around it: whether it may run, what it may access, what it may spend, and what reviewable outcome it may produce.</strong></p>
   <br clear="left">
   <p><strong>Budgets are enforced before spend: every model request must fit within a hard run limit before it reaches the provider.</strong></p>
+  <p><strong>Bring your providers. Keep your infrastructure. Govern agents in one place.</strong></p>
   <p>
+    <a href="#get-started">Get started</a> ·
     <a href="#why-wardby">Why Wardby</a> ·
-    <a href="#why-wardby-instead-of-another-agent-runner">Why it is different</a> ·
+    <a href="#where-wardby-fits">Where it fits</a> ·
     <a href="#a-full-cycle-agent-from-one-conversation">Full-cycle example</a> ·
     <a href="#host-it-in-your-cloud">Deployments</a> ·
     <a href="#bring-your-own-observability">Observability</a> ·
-    <a href="https://github.com/wardby/wardby/blob/main/docs/getting-started.md">Getting started</a> ·
     <a href="#security-boundaries">Security</a>
   </p>
 </div>
@@ -37,50 +38,138 @@ there resolves against npmjs.com instead of this repository. -->
 > and local observability stack are implemented and tested. Production
 > readiness and cloud deployment coverage are still being expanded.
 
+## Get started
+
+### Run locally in five minutes
+
+Requirements: Node.js 24 or newer, Docker, and an OpenAI or Anthropic API key.
+You do not need to clone Wardby or install PostgreSQL.
+
+1. From the project where you want to use Wardby, run:
+
+   ```sh
+   npx --yes @wardby/cli@latest quickstart
+   ```
+
+2. Follow the prompts to choose a provider, start PostgreSQL, create a `$1`
+   demo agent, and optionally connect Codex or Claude Code through MCP.
+
+3. Verify the installation:
+
+   ```sh
+   npx --yes @wardby/cli@latest doctor
+   ```
+
+Quickstart keeps credentials and local state under `.wardby/` in the current
+project. Read the [local getting-started guide](https://github.com/wardby/wardby/blob/main/docs/getting-started.md)
+for unattended setup, lifecycle commands, MCP configuration, and cleanup.
+
+### Develop Wardby from source
+
+Clone the repository only when you want to contribute to Wardby, inspect its
+deployment assets, or build images yourself:
+
+```sh
+git clone https://github.com/wardby/wardby.git
+cd wardby
+npm ci
+npm run build
+npm test
+```
+
+Continue with [CONTRIBUTING.md](https://github.com/wardby/wardby/blob/main/CONTRIBUTING.md)
+for the development database, migrations, required checks, and contribution
+expectations.
+
+### Deploy for a team
+
+- Follow the [GKE guide](https://github.com/wardby/wardby/blob/main/docs/getting-started-gke.md)
+  for the supported Google Cloud reference deployment.
+- Start from the [portable production boundary](https://github.com/wardby/wardby/blob/main/deploy/production/README.md)
+  for another cloud, VM, or container platform.
+- Follow [Bring your own identity provider](https://github.com/wardby/wardby/blob/main/docs/getting-started-identity-provider.md)
+  to protect remote MCP with your existing OAuth/OIDC provider.
+
 ## Why Wardby
 
 AI agents are easy to demo and harder to operate. Once an agent can spend
 money, use credentials, change a repository, or run without a person watching,
 teams need more than a prompt and a cron job.
 
+### One control plane instead of scattered automation
+
+Teams often begin with Claude Code or Codex on developer machines,
+repository-specific automation, and separate provider dashboards. As adoption
+grows, agent definitions, ownership, credentials, budgets, schedules, and run
+history become fragmented across tools and repositories.
+
+Wardby gives every Wardby-managed agent one durable operational identity: who
+owns it, why it exists, what it may access, when it runs, what it may spend,
+and what outcome it produced.
+
 Wardby provides the control plane around the model:
 
-| For engineering leaders                                                     | For developers                                                                             |
-| --------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ |
-| Put explicit cost, ownership, and approval boundaries around agent work.    | Create and manage agents from Claude or Codex through MCP.                                 |
-| Keep execution, data, and credentials in infrastructure your team controls. | Choose OpenAI, Anthropic, or Bedrock-backed models per agent.                              |
-| Turn one-off experiments into scheduled, observable operating processes.    | Attach scoped tools, secrets, schedules, memory, and sub-agents.                           |
-| Keep approval and action authority explicit for consequential outcomes.     | Run optional coding tasks in isolated Codex or Claude Code workers that produce draft PRs. |
+| For engineering leaders                                                      | For developers                                                                             |
+| ---------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ |
+| Keep an inventory of owned agents, purposes, schedules, limits, and results. | Create and manage agents from Claude or Codex through MCP.                                 |
+| See reserved budget and actual usage across Wardby-managed agents.           | Choose OpenAI, Anthropic, or Bedrock-backed models per agent.                              |
+| Keep execution, data, and credentials in infrastructure your team controls.  | Switch approved models or builders without rewriting the governance contract.              |
+| Turn one-off experiments into scheduled, observable operating processes.     | Attach scoped tools, secrets, schedules, memory, and sub-agents.                           |
+| Keep approval and action authority explicit for consequential outcomes.      | Run optional coding tasks in isolated Codex or Claude Code workers that produce draft PRs. |
 
 The result is not another autonomous black box. It is a way to make agent work
 repeatable, bounded, inspectable, and reviewable.
 
-## Why Wardby instead of another agent runner?
+## Where Wardby fits
 
 Agent tools solve different layers of the problem. Wardby does not need to
 replace them: it provides the self-hosted operating boundary around agents and
 the work they perform.
 
-| Category                   | What it primarily helps you do                              | What Wardby adds                                                                           |
-| -------------------------- | ----------------------------------------------------------- | ------------------------------------------------------------------------------------------ |
-| **Agent frameworks**       | Build reasoning loops, tool calls, and multi-agent logic.   | Persistent ownership, schedules, budgets, credentials, run history, and lifecycle control. |
-| **Coding agents**          | Plan, edit, and test code for an interactive task.          | Isolated managed workers, admission-time budgets, scoped access, and optional draft PRs.   |
-| **Hosted agent platforms** | Start quickly on infrastructure operated by another vendor. | A control plane, data, credentials, and execution boundary you can host in your own cloud. |
-| **Workflow orchestrators** | Make application jobs durable, retryable, and observable.   | Agent-specific policy, model usage, capabilities, budgets, and MCP-native operations.      |
+| Category                    | What it primarily helps you do                              | What Wardby adds                                                                           |
+| --------------------------- | ----------------------------------------------------------- | ------------------------------------------------------------------------------------------ |
+| **Repository automation**   | Run jobs for one repository in response to delivery events. | One agent catalog, budget model, and policy boundary across repositories and triggers.     |
+| **Agent frameworks**        | Build reasoning loops, tool calls, and multi-agent logic.   | Persistent ownership, schedules, budgets, credentials, run history, and lifecycle control. |
+| **Coding agents**           | Plan, edit, and test code for an interactive task.          | Isolated managed workers, admission-time budgets, scoped access, and optional draft PRs.   |
+| **Provider dashboards**     | Report usage and cost within one model provider.            | Agent-owned budgets, capabilities, runs, and outcomes across approved providers.           |
+| **LLM gateways**            | Route model requests, manage keys, and enforce quotas.      | Budgets tied to named agents, owned runs, capabilities, schedules, and outcomes.           |
+| **Observability platforms** | Trace requests, evaluate quality, and explain cost.         | Admission and execution controls applied before work occurs, plus a durable agent catalog. |
+| **Vendor control planes**   | Govern agents inside one provider or cloud ecosystem.       | A self-hosted boundary spanning approved providers, builders, repositories, and clouds.    |
+| **Workflow orchestrators**  | Make application jobs durable, retryable, and observable.   | Agent-specific policy, model usage, capabilities, budgets, and MCP-native operations.      |
+
+The distinction is governed work, not just model calls or execution. Rather
+than assembling a gateway, scheduler, agent catalog, budget service,
+capability registry, and run database, Wardby provides one operating boundary.
+It reserves spend before a run starts, grants only assigned capabilities,
+records what happened, and keeps downstream action authority separate from the
+worker that produced the result.
+
+> **Scope:** Wardby's inventory and budget views cover work managed through
+> Wardby. Provider reconciliation and unmanaged-agent discovery are required
+> before those views can represent every AI agent or expense in an
+> organization.
+
+## One operational contract, the full lifecycle
+
+![Wardby workflow: ask in Claude or Codex, define an agent through MCP, govern it in Wardby, execute it in isolation, and apply review policy to its outcome](https://raw.githubusercontent.com/wardby/wardby/main/docs/assets/wardby-workflow.svg)
 
-The distinction is control, not just execution. Wardby reserves spend before a
-run starts, grants only assigned capabilities, records what happened, and
-keeps downstream action authority separate from the worker that produced the
-result.
+Claude and Codex are the operator experience. Wardby is the durable operating
+boundary between intent and agent execution: it stores agent definitions,
+triggers work, reserves budget, mediates tools and credentials, records
+outcomes, and exposes run state through MCP. Nothing runs until identity,
+policy, and available budget agree.
 
-## One control plane, the full lifecycle
+### Governed shared state for agent teams
 
-![Wardby workflow: ask in Claude or Codex, define an agent through MCP, govern it in Wardby, execute it in isolation, and apply review policy to its outcome](https://raw.githubusercontent.com/wardby/wardby/main/docs/assets/wardby-workflow.svg)
+Named Wardby datastores let related agents exchange persistent structured data
+without sharing an unrestricted database credential. Datastores are owned and
+attached to agents explicitly; each sandboxed tool can reach only approved
+bound names and key prefixes.
 
-Claude and Codex are the operator experience. Wardby is the durable system
-behind them: it stores agent definitions, triggers work, reserves budget,
-mediates tools and credentials, records outcomes, and exposes run state through
-MCP.
+A planner can publish a feature plan, a builder can record implementation
+state, and a reviewer or QA agent can add findings to the same governed
+workspace. Datastores provide bounded coordination state, not a replacement
+for authoritative source systems or searchable agent memory.
 
 ## A full-cycle agent from one conversation
 
@@ -107,13 +196,17 @@ Claude or Codex can translate that request into Wardby MCP operations such as
 
 The same agent can be updated, paused, triggered, inspected, or deleted from an
 MCP conversation. The CLI remains available as the bootstrap and operations
-floor.
+floor. The result is autonomy with a receipt: an owned run with bounded spend,
+assigned capabilities, durable status, and a reviewable outcome.
 
 ## Agent ecosystems you can compose
 
 Wardby provides lifecycle primitives rather than prescribing one fixed catalog.
 These are example systems a team can build and manage through MCP:
 
+**Builders can vary. The controls do not.** Each system inherits the same
+budget, capability, identity, evidence, and review contract.
+
 | Agent system             | Typical cycle                                                      | Governed outcome                     |
 | ------------------------ | ------------------------------------------------------------------ | ------------------------------------ |
 | **Delivery pipeline**    | Work request → plan → implementation → tests → review              | Optional draft feature or bug-fix PR |
@@ -129,9 +222,15 @@ own model, tools, schedule, and run history.
 
 ## Host it in your cloud
 
+**Bring your providers. Keep your infrastructure. Govern agents in one place.**
+
 The core does not import a cloud SDK. Jobs, model access, email, secrets,
 authentication, and object storage sit behind provider interfaces so operators
-can choose the infrastructure boundary that fits their environment.
+can choose the infrastructure boundary that fits their environment. Models,
+coding executors, cloud platforms, and observability systems can change
+independently instead of defining the agent architecture. This reduces
+control-plane lock-in without pretending that source control, model providers,
+or monitoring systems disappear.
 
 | Target                               | Current support                                                                                                  |
 | ------------------------------------ | ---------------------------------------------------------------------------------------------------------------- |
@@ -146,14 +245,10 @@ Start with [deployment targets](https://github.com/wardby/wardby/blob/main/deplo
 [GKE getting-started guide](https://github.com/wardby/wardby/blob/main/docs/getting-started-gke.md). Reference deployments are examples,
 not a requirement to use one vendor.
 
-**A complete deployment runs more than `wardby mcp`.** `mcp` serves the MCP
-surface; the scheduler that fires due agents and the reconciler that recovers
-orphaned runs live in `wardby scheduler`. Run **`wardby serve`** to get all three
-in one process. It is the container image's default command and what a
-single-container deployment (Cloud Run, a lone VM) should run. Alternatively,
-run `mcp` and `scheduler` as two processes, as `deploy/production/compose.yml`
-does. Running `mcp` alone logs a startup warning if enabled schedules exist
-that nothing will fire.
+For a single-container deployment, run **`wardby serve`** to start MCP, the
+scheduler, and reconciliation together. Split deployments can run `wardby mcp`
+and `wardby scheduler` separately; `mcp` alone does not fire schedules. See the
+deployment guides above for the complete process boundary.
 
 ## Bring your own observability
 
@@ -211,44 +306,24 @@ Review policy is designed to support designated agents as well as people.
 Agent approvals will be recorded as workflow evidence; operators will decide
 whether that evidence permits an automated action or still requires a person.
 
-## Quickstart
+## Optional npm installation
 
-Requirements: Node.js 24 or newer, Docker, and one supported model-provider
-credential.
-
-```sh
-npx --yes @wardby/cli@latest quickstart
-```
-
-The guided command checks prerequisites, creates private project-local
-configuration, starts PostgreSQL in Docker, applies migrations, and offers to
-run a small agent with a `$1` maximum budget. It can also register Wardby as a
-local MCP server in Codex, Claude Code, or both.
-
-Read the [Getting started guide](https://github.com/wardby/wardby/blob/main/docs/getting-started.md) for unattended setup,
-MCP usage, lifecycle commands, and the boundary between the native demo and
-isolated coding agents. For a shared cloud installation, follow the full
-[GKE getting-started guide](https://github.com/wardby/wardby/blob/main/docs/getting-started-gke.md).
-
-### Installing from npm
+The `npx` quickstart above requires no installation. To pin Wardby as a local
+project dependency instead:
 
 ```sh
 npm install @wardby/cli
 ```
 
-`npm audit` will report a high-severity advisory in `deepmerge-ts`
-([GHSA-ggr8-5vv4-36mx](https://github.com/advisories/GHSA-ggr8-5vv4-36mx)). It
-is reached only through Prisma's CLI while it loads your own Prisma
-configuration, and Prisma has not patched it in the 6.x line. This repository
-clears it with an override, but npm does not apply a package's overrides to the
-projects that install it — so add the same entry to your own `package.json`:
-
-```json
-"overrides": { "deepmerge-ts": "8.0.2" }
-```
+That install is audit-clean: the published package carries no Prisma CLI,
+`@prisma/config`, `deepmerge-ts`, or `mysql2`, so `npm audit` reports nothing
+and no `overrides` entry is needed in your own `package.json`.
 
-That override is tested against Prisma 6 and the CLI; the reasoning and the
-retirement plan are in [SR-009](https://github.com/wardby/wardby/blob/main/docs/security-deployment.md#images-and-dependency-exception).
+`wardby quickstart` and `wardby doctor` separately fetch the pinned Prisma CLI
+(`prisma@7.10.0`) on demand via `npx` to run migrations, so the machine running
+them needs npm registry access at that moment. See
+[Images and dependencies](https://github.com/wardby/wardby/blob/main/docs/security-deployment.md#images-and-dependencies)
+for the repository's own dependency-override policy.
 
 ## What is implemented
 

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

@@ -20,6 +20,7 @@ export declare const CLAUDE_OUTPUT_JSON_SCHEMA: {
         };
         readonly tag: {
             readonly type: "string";
+            readonly description: "Optional short label shown in the pull request title, such as a ticket id. At most 32 characters: letters, digits, '.', '_', '/', '-', starting with a letter or digit, with no spaces. Example: \"add-jokes\". Omit it when there is no natural label.";
         };
         readonly tests: {
             readonly type: "array";

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

@@ -13,7 +13,10 @@ export const CLAUDE_OUTPUT_JSON_SCHEMA = {
         runId: { type: "string" },
         outcome: { type: "string", enum: ["changes_ready", "no_changes", "budget_exhausted"] },
         summary: { type: "string" },
-        tag: { type: "string" },
+        tag: {
+            type: "string",
+            description: "Optional short label shown in the pull request title, such as a ticket id. At most 32 characters: letters, digits, '.', '_', '/', '-', starting with a letter or digit, with no spaces. Example: \"add-jokes\". Omit it when there is no natural label.",
+        },
         tests: {
             type: "array",
             maxItems: 64,

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

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 import { readCodingInput, writeCodingOutputAtomic } from "../coding-worker/artifact.js";
-import { safeWorkerErrorCode } from "../coding-worker/errors.js";
+import { safeOutputIssues, safeWorkerErrorCode } from "../coding-worker/errors.js";
 import { runClaudeCodingWorker } from "./driver.js";
 import { createClaudeSdkQuery } from "./sdk.js";
 const INPUT_PATH = "/run/wardby/input/input.json";
@@ -36,6 +36,7 @@ catch (error) {
         : safeCode === "worker_failed"
             ? `worker_${stage}_failed`
             : safeCode;
-    process.stderr.write(`${JSON.stringify({ error: code })}\n`);
+    const issues = code === "coding_output_invalid" ? safeOutputIssues(error) : undefined;
+    process.stderr.write(`${JSON.stringify({ error: code, ...(issues ? { issues } : {}) })}\n`);
     process.exitCode = controller.signal.aborted ? 143 : 1;
 }

package/dist/coding/protocol.d.ts

@@ -6,10 +6,35 @@ export declare const MAX_CODING_SUMMARY_BYTES: number;
 export declare const MAX_CODING_TESTS = 64;
 export declare const MAX_CODING_TEST_COMMAND_BYTES: number;
 export declare const MAX_TAG_BYTES = 32;
+/**
+ * A worker's output-schema failure, reduced to where and how it failed, never
+ * what the model wrote: `<path>:<zod issue code>`, where the path is dot-joined
+ * schema keys and array indices (`$` for the root). Unrecognized keys the model
+ * invented are carried only as the `unrecognized_keys` code, never by name.
+ */
+export declare const MAX_CODING_OUTPUT_ISSUES = 8;
+export declare const SAFE_CODING_OUTPUT_ISSUE: RegExp;
 export declare function normalizeGitHubRepository(value: string): string;
 export declare function normalizeGitRef(value: string): string;
 export declare const CodingBaseRefSchema: z.ZodEffects<z.ZodEffects<z.ZodString, string, string>, string, string>;
 export declare const CodingTaskOverrideSchema: z.ZodEffects<z.ZodEffects<z.ZodEffects<z.ZodString, string, string>, string, string>, string, string>;
+/**
+ * A coding worker receives only its task text, so a coding agent's own
+ * instructions (its systemPrompt) travel inside that text, ahead of the
+ * request. Blank instructions leave the task unchanged. The combination must
+ * still fit MAX_CODING_TASK_BYTES; exceeding it is an error naming both parts
+ * rather than a silent truncation of either.
+ */
+export declare function composeCodingTask(instructions: string | null | undefined, task: string): string;
+/**
+ * The tag only labels a pull request title, so a model's malformed tag must not
+ * sink an otherwise finished run. A tag that already passes is kept as-is; any
+ * other string becomes a lowercase slug (runs of disallowed characters to "-",
+ * no leading or trailing punctuation, at most MAX_TAG_BYTES), and one with
+ * nothing usable left, or a non-string, becomes null. GitHub finalization still
+ * re-validates whatever survives.
+ */
+export declare function normalizeCodingTag(value: unknown): string | null | undefined;
 export declare const CodingTaskInputSchema: z.ZodEffects<z.ZodObject<{
     schemaVersion: z.ZodLiteral<1>;
     runId: z.ZodEffects<z.ZodEffects<z.ZodEffects<z.ZodEffects<z.ZodString, string, string>, string, string>, string, string>, string, string>;
@@ -103,7 +128,7 @@ export declare const CodingAgentOutputSchema: z.ZodEffects<z.ZodObject<{
         command: string;
         outcome: "passed" | "failed" | "skipped";
     }>, "many">;
-    tag: z.ZodEffects<z.ZodOptional<z.ZodNullable<z.ZodString>>, string | undefined, string | null | undefined>;
+    tag: z.ZodEffects<z.ZodEffects<z.ZodOptional<z.ZodNullable<z.ZodString>>, string | undefined, string | null | undefined>, string | undefined, unknown>;
 }, "strict", z.ZodTypeAny, {
     outcome: "changes_ready" | "no_changes" | "budget_exhausted";
     schemaVersion: 1;
@@ -123,7 +148,7 @@ export declare const CodingAgentOutputSchema: z.ZodEffects<z.ZodObject<{
         command: string;
         outcome: "passed" | "failed" | "skipped";
     }[];
-    tag?: string | null | undefined;
+    tag?: unknown;
 }>, {
     tag?: string | undefined;
     summary: string;
@@ -143,7 +168,7 @@ export declare const CodingAgentOutputSchema: z.ZodEffects<z.ZodObject<{
         command: string;
         outcome: "passed" | "failed" | "skipped";
     }[];
-    tag?: string | null | undefined;
+    tag?: unknown;
 }>;
 export declare const CodingRunResultSchema: z.ZodEffects<z.ZodEffects<z.ZodObject<{
     schemaVersion: z.ZodLiteral<1>;

package/dist/coding/protocol.js

@@ -6,6 +6,14 @@ export const MAX_CODING_SUMMARY_BYTES = 8 * 1024;
 export const MAX_CODING_TESTS = 64;
 export const MAX_CODING_TEST_COMMAND_BYTES = 2 * 1024;
 export const MAX_TAG_BYTES = 32;
+/**
+ * A worker's output-schema failure, reduced to where and how it failed, never
+ * what the model wrote: `<path>:<zod issue code>`, where the path is dot-joined
+ * schema keys and array indices (`$` for the root). Unrecognized keys the model
+ * invented are carried only as the `unrecognized_keys` code, never by name.
+ */
+export const MAX_CODING_OUTPUT_ISSUES = 8;
+export const SAFE_CODING_OUTPUT_ISSUE = /^(?:\$|[a-z][A-Za-z]{0,31}(?:\.(?:[a-z][A-Za-z]{0,31}|\d{1,3})){0,7}):[a-z_]{1,32}$/;
 const MAX_REPOSITORY_INPUT_BYTES = 512;
 const MAX_REF_BYTES = 255;
 const MAX_MODEL_BYTES = 128;
@@ -108,6 +116,24 @@ const repositorySchema = z
     .transform(normalizeGitHubRepository);
 export const CodingBaseRefSchema = z.string().refine(isGitRef, "must be a safe branch ref").transform(normalizeGitRef);
 export const CodingTaskOverrideSchema = boundedText(MAX_CODING_TASK_BYTES);
+/**
+ * A coding worker receives only its task text, so a coding agent's own
+ * instructions (its systemPrompt) travel inside that text, ahead of the
+ * request. Blank instructions leave the task unchanged. The combination must
+ * still fit MAX_CODING_TASK_BYTES; exceeding it is an error naming both parts
+ * rather than a silent truncation of either.
+ */
+export function composeCodingTask(instructions, task) {
+    const standing = instructions?.trim();
+    if (!standing)
+        return task;
+    const composed = `Standing instructions for this coding agent:\n${standing}\n\nRequest:\n${task}`;
+    if (byteLength(composed) > MAX_CODING_TASK_BYTES) {
+        throw new Error(`The coding agent's instructions (${byteLength(standing)} bytes) plus this task (${byteLength(task)} bytes) ` +
+            `exceed the ${MAX_CODING_TASK_BYTES}-byte coding task limit; shorten one of them.`);
+    }
+    return composed;
+}
 const runIdSchema = boundedText(MAX_RUN_ID_BYTES, true).refine((value) => /^[A-Za-z0-9][A-Za-z0-9_-]*$/.test(value), "must be an opaque identifier");
 const modelSchema = boundedText(MAX_MODEL_BYTES, true).refine((value) => /^[A-Za-z0-9][A-Za-z0-9._:-]*$/.test(value), "must be a model identifier");
 const usageSchema = z
@@ -117,6 +143,30 @@ const usageSchema = z
     costUsd: z.number().finite().nonnegative().max(MAX_COST_USD),
 })
     .strict();
+const SAFE_TAG = new RegExp(`^[A-Za-z0-9][A-Za-z0-9._/-]{0,${MAX_TAG_BYTES - 1}}$`);
+/**
+ * The tag only labels a pull request title, so a model's malformed tag must not
+ * sink an otherwise finished run. A tag that already passes is kept as-is; any
+ * other string becomes a lowercase slug (runs of disallowed characters to "-",
+ * no leading or trailing punctuation, at most MAX_TAG_BYTES), and one with
+ * nothing usable left, or a non-string, becomes null. GitHub finalization still
+ * re-validates whatever survives.
+ */
+export function normalizeCodingTag(value) {
+    if (value === undefined || value === null)
+        return value;
+    if (typeof value !== "string")
+        return null;
+    if (SAFE_TAG.test(value))
+        return value;
+    const slug = value
+        .toLowerCase()
+        .replace(/[^a-z0-9._/-]+/g, "-")
+        .replace(/^[^a-z0-9]+/, "")
+        .slice(0, MAX_TAG_BYTES)
+        .replace(/[^a-z0-9]+$/, "");
+    return SAFE_TAG.test(slug) ? slug : null;
+}
 /**
  * A short, caller-visible reference (e.g. a ticket ID) surfaced in the PR title. Never free text.
  * Accepts null as well as undefined: OpenAI's strict Structured Outputs mode requires every
@@ -126,7 +176,7 @@ const usageSchema = z
  */
 const tagSchema = z
     .string()
-    .regex(new RegExp(`^[A-Za-z0-9][A-Za-z0-9._/-]{0,${MAX_TAG_BYTES - 1}}$`), "must be a short, safe tag")
+    .regex(SAFE_TAG, "must be a short, safe tag")
     .nullable()
     .optional()
     .transform((value) => value ?? undefined);
@@ -175,7 +225,8 @@ export const CodingAgentOutputSchema = z
     outcome: z.enum(["changes_ready", "no_changes", "budget_exhausted"]),
     summary: boundedText(MAX_CODING_SUMMARY_BYTES),
     tests: z.array(testResultSchema).max(MAX_CODING_TESTS),
-    tag: tagSchema,
+    // Model-written, so normalized rather than rejected; see normalizeCodingTag.
+    tag: z.preprocess(normalizeCodingTag, tagSchema),
 })
     .strict()
     .transform((value) => ({

package/dist/coding-worker/artifact.d.ts

@@ -1,4 +1,16 @@
 import { type CodingAgentOutput } from "../coding/protocol.js";
+/**
+ * Reads a regular file of at most `maxBytes`, refusing symlinks and anything
+ * that is not a regular file.
+ *
+ * Every check runs against the open handle, never against the path before
+ * opening it: an lstat followed by a read of the same path leaves a window in
+ * which the file can be swapped for a symlink or a larger file. O_NOFOLLOW
+ * refuses a symlink at open time, O_NONBLOCK keeps a FIFO from hanging the
+ * open, and fstat on the descriptor checks what was actually opened. The lstat
+ * afterwards covers platforms without O_NOFOLLOW: it must be the same inode.
+ */
+export declare function readBoundedRegularFile(path: string, maxBytes: number, errorCode: string): Promise<string>;
 export declare function readCodingInput(path: string): Promise<{
     repository: string;
     schemaVersion: 1;

package/dist/coding-worker/artifact.js

@@ -1,12 +1,54 @@
-import { lstat, mkdir, open, readFile, rename, unlink } from "node:fs/promises";
+import { constants } from "node:fs";
+import { lstat, mkdir, open, rename, unlink } from "node:fs/promises";
 import { dirname, join } from "node:path";
 import { MAX_CODING_ARTIFACT_BYTES, parseCodingTaskInputJson } from "../coding/protocol.js";
-export async function readCodingInput(path) {
-    const metadata = await lstat(path);
-    if (!metadata.isFile() || metadata.isSymbolicLink() || metadata.size > MAX_CODING_ARTIFACT_BYTES) {
-        throw new Error("coding_input_invalid_file");
+/**
+ * Reads a regular file of at most `maxBytes`, refusing symlinks and anything
+ * that is not a regular file.
+ *
+ * Every check runs against the open handle, never against the path before
+ * opening it: an lstat followed by a read of the same path leaves a window in
+ * which the file can be swapped for a symlink or a larger file. O_NOFOLLOW
+ * refuses a symlink at open time, O_NONBLOCK keeps a FIFO from hanging the
+ * open, and fstat on the descriptor checks what was actually opened. The lstat
+ * afterwards covers platforms without O_NOFOLLOW: it must be the same inode.
+ */
+export async function readBoundedRegularFile(path, maxBytes, errorCode) {
+    let file;
+    try {
+        file = await open(path, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0) | (constants.O_NONBLOCK ?? 0));
+    }
+    catch (error) {
+        // ELOOP: the path is a symlink.
+        if (error.code === "ELOOP")
+            throw new Error(errorCode, { cause: error });
+        throw error;
+    }
+    try {
+        const metadata = await file.stat();
+        if (!metadata.isFile() || metadata.size > maxBytes)
+            throw new Error(errorCode);
+        const link = await lstat(path);
+        if (link.isSymbolicLink() || link.ino !== metadata.ino || link.dev !== metadata.dev)
+            throw new Error(errorCode);
+        const buffer = Buffer.alloc(maxBytes + 1);
+        let length = 0;
+        while (length < buffer.length) {
+            const { bytesRead } = await file.read(buffer, length, buffer.length - length, length);
+            if (bytesRead === 0)
+                break;
+            length += bytesRead;
+        }
+        if (length > maxBytes)
+            throw new Error(errorCode);
+        return buffer.subarray(0, length).toString("utf8");
+    }
+    finally {
+        await file.close();
     }
-    return parseCodingTaskInputJson(await readFile(path, "utf8"));
+}
+export async function readCodingInput(path) {
+    return parseCodingTaskInputJson(await readBoundedRegularFile(path, MAX_CODING_ARTIFACT_BYTES, "coding_input_invalid_file"));
 }
 export async function writeCodingOutputAtomic(path, output) {
     const directory = dirname(path);

package/dist/coding-worker/driver.d.ts

@@ -20,6 +20,7 @@ export declare const CODING_OUTPUT_JSON_SCHEMA: {
         };
         readonly tag: {
             readonly type: readonly ["string", "null"];
+            readonly description: "Optional short label shown in the pull request title, such as a ticket id. At most 32 characters: letters, digits, '.', '_', '/', '-', starting with a letter or digit, with no spaces. Example: \"add-jokes\". Use null when there is no natural label.";
         };
         readonly tests: {
             readonly type: "array";

package/dist/coding-worker/driver.js

@@ -20,7 +20,10 @@ export const CODING_OUTPUT_JSON_SCHEMA = {
         runId: { type: "string" },
         outcome: { type: "string", enum: ["changes_ready", "no_changes", "budget_exhausted"] },
         summary: { type: "string" },
-        tag: { type: ["string", "null"] },
+        tag: {
+            type: ["string", "null"],
+            description: "Optional short label shown in the pull request title, such as a ticket id. At most 32 characters: letters, digits, '.', '_', '/', '-', starting with a letter or digit, with no spaces. Example: \"add-jokes\". Use null when there is no natural label.",
+        },
         tests: {
             type: "array",
             maxItems: 64,

package/dist/coding-worker/errors.d.ts

@@ -1 +1,8 @@
+/**
+ * For `coding_output_invalid`, where the model's final answer failed the output
+ * schema: the failing schema paths and issue codes, so the operator log can say
+ * which field was wrong without ever carrying the value. Undefined when the
+ * cause is not a schema failure.
+ */
+export declare function safeOutputIssues(error: unknown): string[] | undefined;
 export declare function safeWorkerErrorCode(error: unknown): string;

package/dist/coding-worker/errors.js

@@ -1,3 +1,5 @@
+import { ZodError } from "zod";
+import { MAX_CODING_OUTPUT_ISSUES, SAFE_CODING_OUTPUT_ISSUE } from "../coding/protocol.js";
 const SAFE_WORKER_ERROR_CODES = new Set([
     "wardby_proxy_url_missing",
     "wardby_run_capability_missing",
@@ -13,6 +15,22 @@ const SAFE_WORKER_ERROR_CODES = new Set([
     "coding_output_invalid",
     "coding_output_run_mismatch",
 ]);
+/**
+ * For `coding_output_invalid`, where the model's final answer failed the output
+ * schema: the failing schema paths and issue codes, so the operator log can say
+ * which field was wrong without ever carrying the value. Undefined when the
+ * cause is not a schema failure.
+ */
+export function safeOutputIssues(error) {
+    const cause = error instanceof Error ? error.cause : undefined;
+    if (!(cause instanceof ZodError))
+        return undefined;
+    const issues = cause.issues
+        .map((issue) => `${issue.path.length === 0 ? "$" : issue.path.join(".")}:${issue.code}`)
+        .filter((issue) => SAFE_CODING_OUTPUT_ISSUE.test(issue))
+        .slice(0, MAX_CODING_OUTPUT_ISSUES);
+    return issues.length > 0 ? issues : undefined;
+}
 export function safeWorkerErrorCode(error) {
     if (!(error instanceof Error))
         return "worker_failed";