@wardby/cli 0.2.1 → 0.4.0

package/dist/coding/profile.d.ts

@@ -1,9 +1,8 @@
 import { z } from "zod";
 export declare const MIN_CODING_TIMEOUT_SEC = 60;
 export declare const MAX_CODING_TIMEOUT_SEC = 7200;
-export declare const MAX_ALLOWED_EGRESS_HOSTS = 64;
 export declare const MAX_PROTECTED_PATHS = 128;
-export declare const DEFAULT_PROTECTED_PATHS: readonly [".github/workflows/**", ".github/CODEOWNERS", "CODEOWNERS", "docs/CODEOWNERS"];
+export declare const DEFAULT_PROTECTED_PATHS: readonly [".github/workflows/**", ".github/CODEOWNERS", "CODEOWNERS", "docs/CODEOWNERS", ".wardby/**", "!.wardby/services.yaml"];
 export declare const CodingProfileSchema: z.ZodObject<{
     provider: z.ZodDefault<z.ZodEnum<["codex", "claude-code"]>>;
     repository: z.ZodEffects<z.ZodEffects<z.ZodString, string, string>, string, string>;
@@ -11,38 +10,61 @@ export declare const CodingProfileSchema: z.ZodObject<{
     defaultTask: z.ZodDefault<z.ZodNullable<z.ZodEffects<z.ZodEffects<z.ZodEffects<z.ZodString, string, string>, string, string>, string, string>>>;
     allowWebhookTaskOverride: z.ZodDefault<z.ZodBoolean>;
     timeoutSec: z.ZodDefault<z.ZodNumber>;
-    allowedEgress: z.ZodDefault<z.ZodEffects<z.ZodArray<z.ZodEffects<z.ZodEffects<z.ZodEffects<z.ZodEffects<z.ZodEffects<z.ZodEffects<z.ZodEffects<z.ZodEffects<z.ZodString, string, string>, string, string>, string, string>, string, string>, string, string>, string, string>, string, string>, string, string>, "many">, string[], string[]>>;
-    protectedPaths: z.ZodDefault<z.ZodEffects<z.ZodArray<z.ZodEffects<z.ZodEffects<z.ZodEffects<z.ZodEffects<z.ZodEffects<z.ZodString, string, string>, string, string>, string, string>, string, string>, string, string>, "many">, string[], string[]>>;
+    protectedPaths: z.ZodDefault<z.ZodEffects<z.ZodEffects<z.ZodArray<z.ZodEffects<z.ZodEffects<z.ZodEffects<z.ZodEffects<z.ZodString, string, string>, string, string>, string, string>, string, string>, "many">, string[], string[]>, string[], string[]>>;
+    collectExclude: z.ZodDefault<z.ZodEffects<z.ZodArray<z.ZodEffects<z.ZodString, string, string>, "many">, string[], string[]>>;
     toolchain: z.ZodDefault<z.ZodEnum<["node", "node-python"]>>;
     toolchainVersion: z.ZodDefault<z.ZodNullable<z.ZodString>>;
     workerImageRef: z.ZodDefault<z.ZodNullable<z.ZodEffects<z.ZodString, string, string>>>;
     workspaceDiskMb: z.ZodDefault<z.ZodNullable<z.ZodNumber>>;
+    packageAllowlist: z.ZodDefault<z.ZodEffects<z.ZodRecord<z.ZodString, z.ZodArray<z.ZodString, "many">>, Record<string, string[]>, Record<string, string[]>>>;
+    packagePolicy: z.ZodDefault<z.ZodEffects<z.ZodObject<{
+        minReleaseAgeDays: z.ZodOptional<z.ZodNumber>;
+    }, "strict", z.ZodTypeAny, {
+        minReleaseAgeDays?: number | undefined;
+    }, {
+        minReleaseAgeDays?: number | undefined;
+    }>, {
+        minReleaseAgeDays?: number | undefined;
+    }, {
+        minReleaseAgeDays?: number | undefined;
+    }>>;
+    services: z.ZodDefault<z.ZodEffects<z.ZodArray<z.ZodString, "many">, string[], string[]>>;
 }, "strict", z.ZodTypeAny, {
     repository: string;
     baseRef: string;
+    services: string[];
     provider: "codex" | "claude-code";
-    defaultTask: string | null;
-    allowWebhookTaskOverride: boolean;
     timeoutSec: number;
-    allowedEgress: string[];
     protectedPaths: string[];
+    collectExclude: string[];
+    workspaceDiskMb: number | null;
+    packageAllowlist: Record<string, string[]>;
+    packagePolicy: {
+        minReleaseAgeDays?: number | undefined;
+    };
+    defaultTask: string | null;
+    allowWebhookTaskOverride: boolean;
     toolchain: "node-python" | "node";
     toolchainVersion: string | null;
     workerImageRef: string | null;
-    workspaceDiskMb: number | null;
 }, {
     repository: string;
     baseRef?: string | undefined;
+    services?: string[] | undefined;
     provider?: "codex" | "claude-code" | undefined;
-    defaultTask?: string | null | undefined;
-    allowWebhookTaskOverride?: boolean | undefined;
     timeoutSec?: number | undefined;
-    allowedEgress?: string[] | undefined;
     protectedPaths?: string[] | undefined;
+    collectExclude?: string[] | undefined;
+    workspaceDiskMb?: number | null | undefined;
+    packageAllowlist?: Record<string, string[]> | undefined;
+    packagePolicy?: {
+        minReleaseAgeDays?: number | undefined;
+    } | undefined;
+    defaultTask?: string | null | undefined;
+    allowWebhookTaskOverride?: boolean | undefined;
     toolchain?: "node-python" | "node" | undefined;
     toolchainVersion?: string | null | undefined;
     workerImageRef?: string | null | undefined;
-    workspaceDiskMb?: number | null | undefined;
 }>;
 export declare const CodingProfilePatchSchema: z.ZodObject<{
     provider: z.ZodOptional<z.ZodEnum<["codex", "claude-code"]>>;
@@ -51,38 +73,61 @@ export declare const CodingProfilePatchSchema: z.ZodObject<{
     defaultTask: z.ZodOptional<z.ZodNullable<z.ZodEffects<z.ZodEffects<z.ZodEffects<z.ZodString, string, string>, string, string>, string, string>>>;
     allowWebhookTaskOverride: z.ZodOptional<z.ZodBoolean>;
     timeoutSec: z.ZodOptional<z.ZodNumber>;
-    allowedEgress: z.ZodOptional<z.ZodEffects<z.ZodArray<z.ZodEffects<z.ZodEffects<z.ZodEffects<z.ZodEffects<z.ZodEffects<z.ZodEffects<z.ZodEffects<z.ZodEffects<z.ZodString, string, string>, string, string>, string, string>, string, string>, string, string>, string, string>, string, string>, string, string>, "many">, string[], string[]>>;
-    protectedPaths: z.ZodOptional<z.ZodEffects<z.ZodArray<z.ZodEffects<z.ZodEffects<z.ZodEffects<z.ZodEffects<z.ZodEffects<z.ZodString, string, string>, string, string>, string, string>, string, string>, string, string>, "many">, string[], string[]>>;
+    protectedPaths: z.ZodOptional<z.ZodEffects<z.ZodEffects<z.ZodArray<z.ZodEffects<z.ZodEffects<z.ZodEffects<z.ZodEffects<z.ZodString, string, string>, string, string>, string, string>, string, string>, "many">, string[], string[]>, string[], string[]>>;
+    collectExclude: z.ZodOptional<z.ZodEffects<z.ZodArray<z.ZodEffects<z.ZodString, string, string>, "many">, string[], string[]>>;
     toolchain: z.ZodOptional<z.ZodEnum<["node", "node-python"]>>;
     toolchainVersion: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     workerImageRef: z.ZodOptional<z.ZodNullable<z.ZodEffects<z.ZodString, string, string>>>;
     workspaceDiskMb: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    packageAllowlist: z.ZodOptional<z.ZodEffects<z.ZodRecord<z.ZodString, z.ZodArray<z.ZodString, "many">>, Record<string, string[]>, Record<string, string[]>>>;
+    packagePolicy: z.ZodOptional<z.ZodEffects<z.ZodObject<{
+        minReleaseAgeDays: z.ZodOptional<z.ZodNumber>;
+    }, "strict", z.ZodTypeAny, {
+        minReleaseAgeDays?: number | undefined;
+    }, {
+        minReleaseAgeDays?: number | undefined;
+    }>, {
+        minReleaseAgeDays?: number | undefined;
+    }, {
+        minReleaseAgeDays?: number | undefined;
+    }>>;
+    services: z.ZodOptional<z.ZodEffects<z.ZodArray<z.ZodString, "many">, string[], string[]>>;
 }, "strict", z.ZodTypeAny, {
     repository?: string | undefined;
     baseRef?: string | undefined;
+    services?: string[] | undefined;
     provider?: "codex" | "claude-code" | undefined;
-    defaultTask?: string | null | undefined;
-    allowWebhookTaskOverride?: boolean | undefined;
     timeoutSec?: number | undefined;
-    allowedEgress?: string[] | undefined;
     protectedPaths?: string[] | undefined;
+    collectExclude?: string[] | undefined;
+    workspaceDiskMb?: number | null | undefined;
+    packageAllowlist?: Record<string, string[]> | undefined;
+    packagePolicy?: {
+        minReleaseAgeDays?: number | undefined;
+    } | undefined;
+    defaultTask?: string | null | undefined;
+    allowWebhookTaskOverride?: boolean | undefined;
     toolchain?: "node-python" | "node" | undefined;
     toolchainVersion?: string | null | undefined;
     workerImageRef?: string | null | undefined;
-    workspaceDiskMb?: number | null | undefined;
 }, {
     repository?: string | undefined;
     baseRef?: string | undefined;
+    services?: string[] | undefined;
     provider?: "codex" | "claude-code" | undefined;
-    defaultTask?: string | null | undefined;
-    allowWebhookTaskOverride?: boolean | undefined;
     timeoutSec?: number | undefined;
-    allowedEgress?: string[] | undefined;
     protectedPaths?: string[] | undefined;
+    collectExclude?: string[] | undefined;
+    workspaceDiskMb?: number | null | undefined;
+    packageAllowlist?: Record<string, string[]> | undefined;
+    packagePolicy?: {
+        minReleaseAgeDays?: number | undefined;
+    } | undefined;
+    defaultTask?: string | null | undefined;
+    allowWebhookTaskOverride?: boolean | undefined;
     toolchain?: "node-python" | "node" | undefined;
     toolchainVersion?: string | null | undefined;
     workerImageRef?: string | null | undefined;
-    workspaceDiskMb?: number | null | undefined;
 }>;
 export type CodingProfile = z.infer<typeof CodingProfileSchema>;
 export type CodingProfilePatch = z.infer<typeof CodingProfilePatchSchema>;

package/dist/coding/profile.js

@@ -1,19 +1,23 @@
-import { isIP } from "node:net";
 import { z } from "zod";
 import { isImmutableDockerImage } from "../providers/jobs/docker-isolation.js";
 import { MAX_CODING_TASK_BYTES, normalizeGitHubRepository, normalizeGitRef } from "./protocol.js";
+import { MAX_COLLECT_EXCLUDE_PATHS, validateCollectExcludePath } from "./collect-exclude.js";
 import { CODING_PROVIDERS } from "./provider.js";
+import { WARDBY_PROTECTED_PATHS, isWellFormedProtectedPath, protectsSomePath } from "./protected-paths.js";
+import { parseAllowlist, resolvePolicy } from "./registry/allowlist.js";
+import { REGISTRY_ADAPTERS } from "./registry/adapters.js";
+import { AllowedServiceNamesSchema } from "./services/catalog.js";
 export const MIN_CODING_TIMEOUT_SEC = 60;
 export const MAX_CODING_TIMEOUT_SEC = 7200;
-export const MAX_ALLOWED_EGRESS_HOSTS = 64;
 export const MAX_PROTECTED_PATHS = 128;
 export const DEFAULT_PROTECTED_PATHS = [
     ".github/workflows/**",
     ".github/CODEOWNERS",
     "CODEOWNERS",
     "docs/CODEOWNERS",
+    // Enforced for every run anyway (providers/vcs/git.ts protectedPathMatcher); listed so new agents show it.
+    ...WARDBY_PROTECTED_PATHS,
 ];
-const MAX_HOST_BYTES = 253;
 const MAX_PROTECTED_PATH_BYTES = 512;
 const INVALID_MULTILINE_CONTROL = /[\u0000\u000B\u000C\u000E-\u001F\u007F]/;
 const INVALID_SINGLE_LINE_CONTROL = /[\u0000-\u001F\u007F]/;
@@ -50,27 +54,21 @@ const defaultTaskSchema = z
     .refine((value) => !INVALID_MULTILINE_CONTROL.test(value), "must not contain control characters")
     .refine((value) => value.trim().length > 0, "must not be blank")
     .nullable();
-const egressHostSchema = z
-    .string()
-    .transform((value) => value.trim().toLowerCase())
-    .refine((value) => value.length > 0 && byteLength(value) <= MAX_HOST_BYTES, "must be a bounded hostname")
-    .refine((value) => !INVALID_SINGLE_LINE_CONTROL.test(value), "must not contain control characters")
-    .refine((value) => isIP(value) === 0, "IP addresses and CIDRs are not allowed")
-    .refine((value) => !/^\d+(?:\.\d+){3}$/.test(value), "IP-like hostnames are not allowed")
-    .refine((value) => !value.includes("://") &&
-    !value.includes("/") &&
-    !value.includes("@") &&
-    !value.includes(":") &&
-    !value.includes("*"), "must be an exact hostname")
-    .refine((value) => value !== "localhost" && value.includes("."), "must be a fully qualified hostname")
-    .refine((value) => value.split(".").every((label) => /^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/.test(label)), "must be a valid ASCII hostname");
 const protectedPathSchema = z
     .string()
     .transform((value) => value.trim())
     .refine((value) => value.length > 0 && byteLength(value) <= MAX_PROTECTED_PATH_BYTES, "must be a bounded path")
     .refine((value) => !INVALID_SINGLE_LINE_CONTROL.test(value), "must not contain control characters")
-    .refine((value) => !value.startsWith("/") && !value.startsWith("./") && !value.includes("\\"), "must be a repository-relative POSIX path")
-    .refine((value) => !value.split("/").some((part) => part === "" || part === "." || part === ".."), "must not contain empty or traversal components");
+    .refine(isWellFormedProtectedPath, "must be a repository-relative POSIX path without empty or traversal components, or ! and a literal file path (no wildcards) for an exception");
+const collectExcludePathSchema = z.string().transform((value, ctx) => {
+    try {
+        return validateCollectExcludePath(value);
+    }
+    catch {
+        ctx.addIssue({ code: z.ZodIssueCode.custom, message: "must be a repository-relative path without wildcards" });
+        return z.NEVER;
+    }
+});
 const KNOWN_TOOLCHAINS = ["node", "node-python"];
 const toolchainSchema = z.enum(KNOWN_TOOLCHAINS);
 const toolchainVersionSchema = z.string().trim().min(1).max(32).nullable();
@@ -82,6 +80,30 @@ const workerImageRefSchema = z
     .refine(isImmutableDockerImage, "must be an immutable repository digest")
     .nullable();
 const workspaceDiskMbSchema = z.number().int().min(64).max(32_768).nullable();
+const packageAllowlistSchema = z
+    .record(z.string(), z.array(z.string().min(1).max(256)).max(256))
+    .superRefine((value, ctx) => {
+    try {
+        parseAllowlist(value, REGISTRY_ADAPTERS);
+    }
+    catch (error) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: error instanceof Error ? error.message : "invalid allowlist",
+        });
+    }
+});
+const packagePolicySchema = z
+    .object({ minReleaseAgeDays: z.number().int().min(0).max(30).optional() })
+    .strict()
+    .superRefine((value, ctx) => {
+    try {
+        resolvePolicy(value);
+    }
+    catch {
+        ctx.addIssue({ code: z.ZodIssueCode.custom, message: "invalid package policy" });
+    }
+});
 const codingProfileFields = {
     provider: z.enum(CODING_PROVIDERS),
     repository: repositorySchema,
@@ -93,15 +115,20 @@ const codingProfileFields = {
     toolchainVersion: toolchainVersionSchema,
     workerImageRef: workerImageRefSchema,
     workspaceDiskMb: workspaceDiskMbSchema,
-    allowedEgress: z
-        .array(egressHostSchema)
-        .max(MAX_ALLOWED_EGRESS_HOSTS)
-        .transform((hosts) => [...new Set(hosts)]),
     protectedPaths: z
         .array(protectedPathSchema)
         .min(1)
         .max(MAX_PROTECTED_PATHS)
+        .refine(protectsSomePath, "must protect at least one path; entries starting with ! are only exceptions")
+        .transform((paths) => [...new Set(paths)]),
+    collectExclude: z
+        .array(collectExcludePathSchema)
+        .max(MAX_COLLECT_EXCLUDE_PATHS)
         .transform((paths) => [...new Set(paths)]),
+    packageAllowlist: packageAllowlistSchema,
+    packagePolicy: packagePolicySchema,
+    /** Coding-run services this agent's runs may start: catalog names, any version (docs/coding-services.md). */
+    services: AllowedServiceNamesSchema,
 };
 export const CodingProfileSchema = z
     .object({
@@ -111,12 +138,15 @@ export const CodingProfileSchema = z
     defaultTask: codingProfileFields.defaultTask.default(null),
     allowWebhookTaskOverride: codingProfileFields.allowWebhookTaskOverride.default(false),
     timeoutSec: codingProfileFields.timeoutSec.default(1800),
-    allowedEgress: codingProfileFields.allowedEgress.default([]),
     protectedPaths: codingProfileFields.protectedPaths.default([...DEFAULT_PROTECTED_PATHS]),
+    collectExclude: codingProfileFields.collectExclude.default([]),
     toolchain: codingProfileFields.toolchain.default("node"),
     toolchainVersion: codingProfileFields.toolchainVersion.default(null),
     workerImageRef: codingProfileFields.workerImageRef.default(null),
     workspaceDiskMb: codingProfileFields.workspaceDiskMb.default(null),
+    packageAllowlist: codingProfileFields.packageAllowlist.default({}),
+    packagePolicy: codingProfileFields.packagePolicy.default({}),
+    services: codingProfileFields.services.default([]),
 })
     .strict();
 export const CodingProfilePatchSchema = z
@@ -127,11 +157,14 @@ export const CodingProfilePatchSchema = z
     defaultTask: codingProfileFields.defaultTask.optional(),
     allowWebhookTaskOverride: codingProfileFields.allowWebhookTaskOverride.optional(),
     timeoutSec: codingProfileFields.timeoutSec.optional(),
-    allowedEgress: codingProfileFields.allowedEgress.optional(),
     protectedPaths: codingProfileFields.protectedPaths.optional(),
+    collectExclude: codingProfileFields.collectExclude.optional(),
     toolchain: codingProfileFields.toolchain.optional(),
     toolchainVersion: codingProfileFields.toolchainVersion.optional(),
     workerImageRef: codingProfileFields.workerImageRef.optional(),
     workspaceDiskMb: codingProfileFields.workspaceDiskMb.optional(),
+    packageAllowlist: codingProfileFields.packageAllowlist.optional(),
+    packagePolicy: codingProfileFields.packagePolicy.optional(),
+    services: codingProfileFields.services.optional(),
 })
     .strict();

package/dist/coding/protected-path-wording.d.ts

@@ -0,0 +1,24 @@
+/**
+ * What a host (a builder continuation comment, a mention status comment) is
+ * told when a coding run's changes touched a path this agent may not edit
+ * (protectedPathMatcher in src/providers/vcs/git.ts). Public repositories
+ * read these, so the path -- taken from the run's own diff -- is treated as
+ * untrusted text: it never carries a backtick, a control character, or more
+ * than MAX_PATH_CHARS.
+ */
+/** CodingRun.failureCategory for a run whose collected changes touched a protected path. */
+export declare const PROTECTED_PATH_CATEGORY = "protected_path";
+/** The path a `vcs_protected_path:<path>` error names, or null for any other error. */
+export declare function protectedPathFromError(error: unknown): string | null;
+/**
+ * The host sentence for a run stopped because its changes touched a
+ * protected path. Named the file when `path` sanitises to something usable;
+ * otherwise falls back to a sentence that doesn't try to name it.
+ */
+export declare function protectedPathSentence(path: string | null | undefined): string;
+/**
+ * The fixed line for a mention status comment naming a failed protected_path
+ * sub-run (host-status.ts). That comment reads children from the database,
+ * which has no path -- only the category -- so this line never names a file.
+ */
+export declare const PROTECTED_PATH_HOST_LINE = "A sub-run could not open its changes: it changed a file its agent may not edit, so none of its changes were kept.";

package/dist/coding/protected-path-wording.js

@@ -0,0 +1,55 @@
+/**
+ * What a host (a builder continuation comment, a mention status comment) is
+ * told when a coding run's changes touched a path this agent may not edit
+ * (protectedPathMatcher in src/providers/vcs/git.ts). Public repositories
+ * read these, so the path -- taken from the run's own diff -- is treated as
+ * untrusted text: it never carries a backtick, a control character, or more
+ * than MAX_PATH_CHARS.
+ */
+/** CodingRun.failureCategory for a run whose collected changes touched a protected path. */
+export const PROTECTED_PATH_CATEGORY = "protected_path";
+/** git.ts's finalizeChanges throws this when the collected diff touches a protected path. */
+const PROTECTED_PATH_ERROR_PREFIX = "vcs_protected_path:";
+/** The path a `vcs_protected_path:<path>` error names, or null for any other error. */
+export function protectedPathFromError(error) {
+    const message = error instanceof Error ? error.message : typeof error === "string" ? error : "";
+    if (!message.startsWith(PROTECTED_PATH_ERROR_PREFIX))
+        return null;
+    const path = message.slice(PROTECTED_PATH_ERROR_PREFIX.length);
+    return path.length > 0 ? path : null;
+}
+const MAX_PATH_CHARS = 200;
+/**
+ * A single-line, backtick-free rendering of a repository path safe to drop
+ * into one Markdown code span: control characters and backticks (which would
+ * otherwise close the span early) are neutralised, runs of whitespace
+ * collapse to one line, and the result is capped with an ellipsis. Null when
+ * nothing usable is left.
+ */
+function sanitizePath(path) {
+    // eslint-disable-next-line no-control-regex -- deliberately stripping C0/DEL control characters.
+    const withoutControls = path.replace(/[\u0000-\u001f\u007f]+/g, " ");
+    const oneLine = withoutControls.replace(/\s+/g, " ").trim();
+    const withoutBackticks = oneLine.replace(/`/g, "'");
+    if (withoutBackticks.length === 0)
+        return null;
+    return withoutBackticks.length > MAX_PATH_CHARS ? `${withoutBackticks.slice(0, MAX_PATH_CHARS)}…` : withoutBackticks;
+}
+/**
+ * The host sentence for a run stopped because its changes touched a
+ * protected path. Named the file when `path` sanitises to something usable;
+ * otherwise falls back to a sentence that doesn't try to name it.
+ */
+export function protectedPathSentence(path) {
+    const safe = path ? sanitizePath(path) : null;
+    const named = safe
+        ? `its changes include \`${safe}\`, which this agent may not edit`
+        : "its changes include a file this agent may not edit";
+    return `${named}, so none of its changes were kept. Ask again without changing that file, or have the repository owner make that change.`;
+}
+/**
+ * The fixed line for a mention status comment naming a failed protected_path
+ * sub-run (host-status.ts). That comment reads children from the database,
+ * which has no path -- only the category -- so this line never names a file.
+ */
+export const PROTECTED_PATH_HOST_LINE = "A sub-run could not open its changes: it changed a file its agent may not edit, so none of its changes were kept.";

package/dist/coding/protected-paths.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Protected for every coding run, whatever an agent's own protectedPaths say
+ * (docs/coding-services.md): wardby's own configuration under .wardby/, except
+ * the service declaration, which any builder may propose in its pull request
+ * (it takes effect only after a person merges it, since dispatch reads it from
+ * the base branch). Part of DEFAULT_PROTECTED_PATHS so new agents show it, and
+ * always added by protectedPathMatcher (providers/vcs/git.ts) so agents created
+ * before it existed get it too. The matcher applies it ahead of the agent's own
+ * list: the declaration is never protected, and nothing else under .wardby/ can
+ * be unprotected by an agent's exceptions.
+ */
+export declare const WARDBY_PROTECTED_PATHS: readonly [".wardby/**", "!.wardby/services.yaml"];
+/**
+ * A leading "!" makes a protectedPaths entry an exception (providers/vcs/git.ts
+ * protectedPathMatcher): one literal file path carved out of the agent's own
+ * patterns. Exceptions take no wildcards, so "!**" or "!.github/**" cannot
+ * switch a whole protected tree off.
+ */
+export declare const PROTECTED_PATH_EXCEPTION = "!";
+export declare function isProtectedPathException(path: string): boolean;
+/** The glob of a protectedPaths entry: the entry itself, or what follows an exception's leading "!". */
+export declare function protectedPathBody(path: string): string;
+/**
+ * Whether a trimmed protectedPaths entry has a valid shape: a repository-relative
+ * POSIX glob with no empty or traversal components, or, behind one leading "!",
+ * such a path with no glob metacharacters. Length and control-character bounds
+ * are the caller's.
+ */
+export declare function isWellFormedProtectedPath(path: string): boolean;
+/** Exceptions only carve paths out; a list of nothing but exceptions protects nothing. */
+export declare function protectsSomePath(paths: readonly string[]): boolean;

package/dist/coding/protected-paths.js

@@ -0,0 +1,48 @@
+/**
+ * Protected for every coding run, whatever an agent's own protectedPaths say
+ * (docs/coding-services.md): wardby's own configuration under .wardby/, except
+ * the service declaration, which any builder may propose in its pull request
+ * (it takes effect only after a person merges it, since dispatch reads it from
+ * the base branch). Part of DEFAULT_PROTECTED_PATHS so new agents show it, and
+ * always added by protectedPathMatcher (providers/vcs/git.ts) so agents created
+ * before it existed get it too. The matcher applies it ahead of the agent's own
+ * list: the declaration is never protected, and nothing else under .wardby/ can
+ * be unprotected by an agent's exceptions.
+ */
+export const WARDBY_PROTECTED_PATHS = [".wardby/**", "!.wardby/services.yaml"];
+/**
+ * A leading "!" makes a protectedPaths entry an exception (providers/vcs/git.ts
+ * protectedPathMatcher): one literal file path carved out of the agent's own
+ * patterns. Exceptions take no wildcards, so "!**" or "!.github/**" cannot
+ * switch a whole protected tree off.
+ */
+export const PROTECTED_PATH_EXCEPTION = "!";
+export function isProtectedPathException(path) {
+    return path.startsWith(PROTECTED_PATH_EXCEPTION);
+}
+/** The glob of a protectedPaths entry: the entry itself, or what follows an exception's leading "!". */
+export function protectedPathBody(path) {
+    return isProtectedPathException(path) ? path.slice(PROTECTED_PATH_EXCEPTION.length) : path;
+}
+/** Glob metacharacters an exception may not contain: it names one literal file. */
+const EXCEPTION_GLOB_CHARACTERS = /[*?[\]{}]/;
+/**
+ * Whether a trimmed protectedPaths entry has a valid shape: a repository-relative
+ * POSIX glob with no empty or traversal components, or, behind one leading "!",
+ * such a path with no glob metacharacters. Length and control-character bounds
+ * are the caller's.
+ */
+export function isWellFormedProtectedPath(path) {
+    const body = protectedPathBody(path);
+    return (body.length > 0 &&
+        !isProtectedPathException(body) &&
+        !(isProtectedPathException(path) && EXCEPTION_GLOB_CHARACTERS.test(body)) &&
+        !body.startsWith("/") &&
+        !body.startsWith("./") &&
+        !body.includes("\\") &&
+        !body.split("/").some((part) => part === "" || part === "." || part === ".."));
+}
+/** Exceptions only carve paths out; a list of nothing but exceptions protects nothing. */
+export function protectsSomePath(paths) {
+    return paths.some((path) => !isProtectedPathException(path));
+}

package/dist/coding/protocol.d.ts

@@ -1,11 +1,27 @@
 import { z } from "zod";
 export declare const CODING_PROTOCOL_VERSION: 1;
+/** The code host every coding run's repository and pull request live on (see pullRequestUrlSchema); the one place to change when another is added. */
+export declare const CODING_CODE_PROVIDER = "github";
 export declare const MAX_CODING_ARTIFACT_BYTES: number;
 export declare const MAX_CODING_TASK_BYTES: number;
+/** Room reserved at the end of a composed task for lines the executor appends (e.g. the base commit). */
+export declare const CODING_TASK_TRAILER_RESERVE_BYTES = 256;
 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;
+/**
+ * Coding-run services (docs/coding-services.md): the catalog name and version
+ * grammar, shared by the repository's .wardby/services.yaml, the catalog, and
+ * the worker input.
+ */
+export declare const CODING_SERVICE_NAME: RegExp;
+export declare const CODING_SERVICE_VERSION: RegExp;
+export declare const MAX_CODING_SERVICES = 5;
+/** A variable a service hands the agent's shells (DATABASE_URL, PGHOST, REDIS_URL, ...). */
+export declare const CODING_SERVICE_ENV_NAME: RegExp;
+export declare const MAX_CODING_SERVICE_ENV = 16;
+export declare const MAX_CODING_SERVICE_ENV_VALUE_BYTES = 1024;
 /**
  * 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
@@ -14,18 +30,36 @@ export declare const MAX_TAG_BYTES = 32;
  */
 export declare const MAX_CODING_OUTPUT_ISSUES = 8;
 export declare const SAFE_CODING_OUTPUT_ISSUE: RegExp;
+export declare const INVALID_SINGLE_LINE_CONTROL: RegExp;
+export declare function byteLength(value: string): number;
+export declare function isReservedServiceEnvName(name: string): boolean;
+/** The variables one service hands the agent's shells: upper-case names wardby does not reserve. */
+export declare const CodingServiceTestEnvSchema: z.ZodEffects<z.ZodRecord<z.ZodString, z.ZodEffects<z.ZodEffects<z.ZodString, string, string>, string, string>>, Record<string, string>, Record<string, string>>;
 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 section rendered to fit whatever room the task leaves (the knowledge note:
+ * src/knowledge/note.ts). Declared structurally so this module, which coding
+ * workers ship as a single file, imports nothing new.
+ */
+export interface FittedSection {
+    /** The section text within `maxBytes`, or undefined when it does not fit. */
+    render(maxBytes: number): string | undefined;
+}
 /**
  * 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.
+ * request, followed by any note wardby generates for the run (the services it
+ * started: src/coding/services/note.ts). Blank instructions and no note 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.
+ * A knowledge note, when given, goes between the standing instructions and the
+ * request and is fitted into whatever room is left: it is cut, or dropped,
+ * never the cause of an error.
  */
-export declare function composeCodingTask(instructions: string | null | undefined, task: string): string;
+export declare function composeCodingTask(instructions: string | null | undefined, task: string, note?: string, knowledge?: FittedSection): 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
@@ -35,6 +69,8 @@ export declare function composeCodingTask(instructions: string | null | undefine
  * re-validates whatever survives.
  */
 export declare function normalizeCodingTag(value: unknown): string | null | undefined;
+/** Longest line a debug-traced worker writes to its log (src/coding-worker/debug-trace.ts). */
+export declare const MAX_DEBUG_TRACE_LINE_BYTES: number;
 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>;
@@ -60,6 +96,33 @@ export declare const CodingTaskInputSchema: z.ZodEffects<z.ZodObject<{
     }, {
         runId: string;
     }>>;
+    /**
+     * Admin-requested debug trace (CodingAgentProfile.debugTraceUntil): the
+     * worker writes its full stream trace to its own log. Absent means off;
+     * the control plane writes the key only when true, so an input for an
+     * untraced run is unchanged for workers that predate it.
+     */
+    debugTrace: z.ZodOptional<z.ZodBoolean>;
+    /**
+     * Coding-run services started next to this run (docs/coding-services.md):
+     * each one's catalog name and version, and the variables the agent's shells
+     * receive. Absent means none; the control plane writes the key only when a
+     * run has services, so every other input is unchanged for workers that
+     * predate it.
+     */
+    services: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        version: z.ZodString;
+        testEnv: z.ZodEffects<z.ZodRecord<z.ZodString, z.ZodEffects<z.ZodEffects<z.ZodString, string, string>, string, string>>, Record<string, string>, Record<string, string>>;
+    }, "strict", z.ZodTypeAny, {
+        name: string;
+        version: string;
+        testEnv: Record<string, string>;
+    }, {
+        name: string;
+        version: string;
+        testEnv: Record<string, string>;
+    }>, "many">>;
 }, "strict", z.ZodTypeAny, {
     repository: string;
     schemaVersion: 1;
@@ -73,6 +136,12 @@ export declare const CodingTaskInputSchema: z.ZodEffects<z.ZodObject<{
     continuationOf?: {
         runId: string;
     } | undefined;
+    debugTrace?: boolean | undefined;
+    services?: {
+        name: string;
+        version: string;
+        testEnv: Record<string, string>;
+    }[] | undefined;
 }, {
     repository: string;
     schemaVersion: 1;
@@ -86,6 +155,12 @@ export declare const CodingTaskInputSchema: z.ZodEffects<z.ZodObject<{
     continuationOf?: {
         runId: string;
     } | undefined;
+    debugTrace?: boolean | undefined;
+    services?: {
+        name: string;
+        version: string;
+        testEnv: Record<string, string>;
+    }[] | undefined;
 }>, {
     repository: string;
     schemaVersion: 1;
@@ -99,6 +174,12 @@ export declare const CodingTaskInputSchema: z.ZodEffects<z.ZodObject<{
     continuationOf?: {
         runId: string;
     } | undefined;
+    debugTrace?: boolean | undefined;
+    services?: {
+        name: string;
+        version: string;
+        testEnv: Record<string, string>;
+    }[] | undefined;
 }, {
     repository: string;
     schemaVersion: 1;
@@ -112,6 +193,12 @@ export declare const CodingTaskInputSchema: z.ZodEffects<z.ZodObject<{
     continuationOf?: {
         runId: string;
     } | undefined;
+    debugTrace?: boolean | undefined;
+    services?: {
+        name: string;
+        version: string;
+        testEnv: Record<string, string>;
+    }[] | undefined;
 }>;
 export declare const CodingAgentOutputSchema: z.ZodEffects<z.ZodObject<{
     schemaVersion: z.ZodLiteral<1>;