@edspencer/paddock 0.56.0 → 0.57.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@edspencer/paddock",
-  "version": "0.56.0",
+  "version": "0.57.0",
   "description": "Project-first launchpad for Claude Code: server-hosted, persistent, resumable sessions organized by project.",
   "keywords": [
     "claude",

package/packages/server/dist/config.d.ts

@@ -168,6 +168,25 @@ export interface PaddockConfig {
      * instance CLAUDE.md up by walk-up. That closes #512.
      */
     nativeSystemPrompt: boolean;
+    /**
+     * The **environment** prompt appended to every keeper turn's system prompt
+     * (issue #635) — the short note telling the agent it renders into a browser as
+     * GFM, not a terminal. Resolved from `PADDOCK_ENVIRONMENT_PROMPT` over the
+     * `environmentPrompt:` file key over
+     * {@link import("./environment-prompt.js").DEFAULT_ENVIRONMENT_PROMPT}.
+     *
+     * This is the RESOLVED, effective text, so it has only two meaningful states
+     * at the point of use: non-empty (append it) and `""` (append nothing — the
+     * instance opted out). The three *authoring* states — unset, a string, an
+     * empty string — collapse here, which is deliberate: every consumer just asks
+     * "is there anything to append?" and the Settings screen shows the text that
+     * is actually in force rather than a tri-state it would have to explain.
+     *
+     * Orthogonal to {@link nativeSystemPrompt}: that switch chooses the agent's
+     * *role* prompt (native preset vs Paddock's terse replace text); this states
+     * environmental fact about the deployment and applies on top of either.
+     */
+    environmentPrompt: string;
     /**
      * Whether keeper turns are handed the read-only self-management MCP server
      * (issue #214 Phase 1) — the `mcp__paddock_manage__*` tools that let a keeper
@@ -378,6 +397,13 @@ export interface PaddockConfigFile {
     models?: string[] | string;
     driveMode?: string;
     nativeSystemPrompt?: boolean | string;
+    /**
+     * Environment system prompt override (issue #635). Absent ⇒ Paddock's built-in
+     * text; a non-empty string ⇒ that text instead; an EMPTY string ⇒ append
+     * nothing. Unlike almost every other key here, blank is meaningful and is NOT
+     * folded to the default — see {@link loadEnvironmentPrompt}.
+     */
+    environmentPrompt?: string;
     selfMcpEnabled?: boolean | string;
     selfMcpWriteEnabled?: boolean | string;
     selfMcpProjectsEnabled?: boolean | string;

package/packages/server/dist/config.js

@@ -24,6 +24,7 @@ import { fileURLToPath } from "node:url";
 import YAML from "yaml";
 import { DEFAULT_DRIVE_MODE, isKnownDriveMode, isKnownModel, } from "./models.js";
 import { DEFAULT_MAX_SPAWN_DEPTH, isValidMaxSpawnDepth } from "./spawn-capability.js";
+import { DEFAULT_ENVIRONMENT_PROMPT } from "./environment-prompt.js";
 import { DEFAULT_RECOVERY } from "./recovery-config.js";
 import { DEFAULT_CURATION } from "./curation-config.js";
 import { resolveManagementApiConfig, } from "./management-config.js";
@@ -290,6 +291,7 @@ export function loadPaddockConfig() {
         models: loadModels(file.models),
         driveMode: loadDriveMode(file.driveMode),
         nativeSystemPrompt: loadNativeSystemPrompt(file.nativeSystemPrompt),
+        environmentPrompt: loadEnvironmentPrompt(file.environmentPrompt),
         selfMcpEnabled: loadSelfMcpEnabled(file.selfMcpEnabled),
         selfMcpWriteEnabled: loadSelfMcpEnabled(file.selfMcpEnabled) && loadSelfMcpWriteEnabled(file.selfMcpWriteEnabled),
         // Projects tool implies write implies read — the tool is appended in the write
@@ -534,6 +536,36 @@ function loadNativeSystemPrompt(file) {
     const raw = envOr("PADDOCK_NATIVE_PROMPT", fileOr(file, "true")).toLowerCase();
     return !(raw === "0" || raw === "false" || raw === "no");
 }
+/**
+ * Resolve the environment system prompt (issue #635): env
+ * `PADDOCK_ENVIRONMENT_PROMPT` over the `environmentPrompt:` file key over the
+ * built-in {@link DEFAULT_ENVIRONMENT_PROMPT}.
+ *
+ * Deliberately does NOT use `envOr`/`fileOr`. Those fold a blank value to the
+ * fallback, which would make opting out impossible — blank is the opt-out here,
+ * so precedence is decided on *definedness*, not on emptiness:
+ *
+ *  - `PADDOCK_ENVIRONMENT_PROMPT` **defined at all** (even empty) wins outright.
+ *    That is why the field is declared `envShadowWhenDefined` in
+ *    instance-config.ts — same rule as `PADDOCK_BROWSER_MCP` — so the Settings
+ *    screen renders it read-only in exactly the cases where it really is.
+ *  - Otherwise a `string` file value wins, empty included. A non-string (a YAML
+ *    number, a mapping, `null` from a bare `environmentPrompt:`) is ignored
+ *    rather than stringified — `"null"` is not a prompt anyone meant to write.
+ *  - Otherwise the built-in default.
+ *
+ * The value is used verbatim: no trimming, no normalization. An operator's
+ * trailing newline or leading indentation survives the round-trip, because the
+ * text is going into a prompt where whitespace is content.
+ */
+function loadEnvironmentPrompt(file) {
+    const env = process.env.PADDOCK_ENVIRONMENT_PROMPT;
+    if (env !== undefined)
+        return env;
+    if (typeof file === "string")
+        return file;
+    return DEFAULT_ENVIRONMENT_PROMPT;
+}
 /**
  * Resolve the instance model allow-list (issue #457 Step 2), precedence
  * env `PADDOCK_MODELS` (comma-separated ids) over YAML `models:` (a string array,

package/packages/server/dist/environment-prompt.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Paddock's built-in **environment** system prompt (issue #635).
+ *
+ * Paddock injects no system prompt of its own: on a default instance the keeper
+ * runs on Claude Code's stock `claude_code` preset, which is written for a
+ * terminal. Nothing anywhere tells the model that its replies are rendered as
+ * GitHub-Flavored Markdown in a browser (`MarkdownRenderer.tsx` = react-markdown
+ * + remark-gfm), or that `mcp__paddock__send_file` renders a file inline.
+ *
+ * This text is a small **append** to whatever system prompt the agent already
+ * has — it states environmental fact about the deployment, and deliberately does
+ * not instruct on role, tone or workflow (that is the `CLAUDE.md` hierarchy's
+ * layer, and it stays the user's).
+ *
+ * ## Why exactly two rules
+ *
+ * The text is not written from first principles — an earlier draft was, and the
+ * audit in issue #635 refuted most of it. It comes from auditing the 100 most
+ * recent chats on the dogfood instance (3,944 assistant text blocks, 2.1 MB of
+ * user-facing prose). Two findings carried ~90% of the measured value:
+ *
+ *  - **`#123` is dead text.** 4,440 bare refs vs 155 markdown links. Bare URLs
+ *    autolink under GFM and came out fine (only 4 inert, all backticked), so the
+ *    defect is specifically issue/PR refs — and it is not inability: single
+ *    messages link some refs and leave others bare.
+ *  - **Visual work is described, never shown.** 194 image reads, 138
+ *    screenshots, and **zero** images ever sent to a user. `send_file` was used
+ *    10 times, none of them an image. In one chat this cost a full re-work round
+ *    — the agent read 17 QC frames, showed none, misread one, and shipped a
+ *    regression the user then had to screenshot themselves.
+ *
+ * Things measured and deliberately **cut**, so they don't get re-added: "no ANSI
+ * colour" (0 escapes in 2.1 MB), "don't paste long content" (0 fences ≥40 lines;
+ * median fence is 3), "use markdown structure" (580 headings, 892 bullets, 101
+ * well-formed tables — already excellent), `file.ts:123` guidance (real but
+ * low-stakes; 72 of 75 sampled sit in backticks beside the symbol name), and
+ * mermaid (0 genuine missed opportunities; an instruction would over-trigger).
+ *
+ * ## Keep in sync
+ *
+ * The `send_file` tool description (`send-file-mcp.ts`) is the only other
+ * Paddock-aware signal in a normal turn. These two are the same message told
+ * twice; change one and re-read the other.
+ */
+/**
+ * The default environment prompt appended to every keeper turn unless the
+ * instance overrides or opts out (see `environmentPrompt` in config.ts).
+ *
+ * Kept verbatim from issue #635's evidence pass. Resist adding a third rule
+ * without measurement — several plausible candidates were cut above.
+ */
+export declare const DEFAULT_ENVIRONMENT_PROMPT = "You are running in Paddock, a web app \u2014 your replies render as GitHub-Flavored\nMarkdown in a browser, not as terminal output.\n\n- Show, don't describe. A screenshot, rendering, chart or file the user is meant\n  to look at should be sent with `mcp__paddock__send_file`, which renders it\n  inline. A filesystem path, or \"it's up on port 5026\", leaves them unable to see\n  your evidence \u2014 or to catch you misreading it.\n- Make clickable things clickable. Bare URLs autolink; `#123` does not \u2014 write\n  `[#123](https://github.com/owner/repo/issues/123)`. Prefer a full URL to a bare\n  port number, and link a chat or project rather than quoting its id.";

package/packages/server/dist/environment-prompt.js

@@ -0,0 +1,61 @@
+/**
+ * Paddock's built-in **environment** system prompt (issue #635).
+ *
+ * Paddock injects no system prompt of its own: on a default instance the keeper
+ * runs on Claude Code's stock `claude_code` preset, which is written for a
+ * terminal. Nothing anywhere tells the model that its replies are rendered as
+ * GitHub-Flavored Markdown in a browser (`MarkdownRenderer.tsx` = react-markdown
+ * + remark-gfm), or that `mcp__paddock__send_file` renders a file inline.
+ *
+ * This text is a small **append** to whatever system prompt the agent already
+ * has — it states environmental fact about the deployment, and deliberately does
+ * not instruct on role, tone or workflow (that is the `CLAUDE.md` hierarchy's
+ * layer, and it stays the user's).
+ *
+ * ## Why exactly two rules
+ *
+ * The text is not written from first principles — an earlier draft was, and the
+ * audit in issue #635 refuted most of it. It comes from auditing the 100 most
+ * recent chats on the dogfood instance (3,944 assistant text blocks, 2.1 MB of
+ * user-facing prose). Two findings carried ~90% of the measured value:
+ *
+ *  - **`#123` is dead text.** 4,440 bare refs vs 155 markdown links. Bare URLs
+ *    autolink under GFM and came out fine (only 4 inert, all backticked), so the
+ *    defect is specifically issue/PR refs — and it is not inability: single
+ *    messages link some refs and leave others bare.
+ *  - **Visual work is described, never shown.** 194 image reads, 138
+ *    screenshots, and **zero** images ever sent to a user. `send_file` was used
+ *    10 times, none of them an image. In one chat this cost a full re-work round
+ *    — the agent read 17 QC frames, showed none, misread one, and shipped a
+ *    regression the user then had to screenshot themselves.
+ *
+ * Things measured and deliberately **cut**, so they don't get re-added: "no ANSI
+ * colour" (0 escapes in 2.1 MB), "don't paste long content" (0 fences ≥40 lines;
+ * median fence is 3), "use markdown structure" (580 headings, 892 bullets, 101
+ * well-formed tables — already excellent), `file.ts:123` guidance (real but
+ * low-stakes; 72 of 75 sampled sit in backticks beside the symbol name), and
+ * mermaid (0 genuine missed opportunities; an instruction would over-trigger).
+ *
+ * ## Keep in sync
+ *
+ * The `send_file` tool description (`send-file-mcp.ts`) is the only other
+ * Paddock-aware signal in a normal turn. These two are the same message told
+ * twice; change one and re-read the other.
+ */
+/**
+ * The default environment prompt appended to every keeper turn unless the
+ * instance overrides or opts out (see `environmentPrompt` in config.ts).
+ *
+ * Kept verbatim from issue #635's evidence pass. Resist adding a third rule
+ * without measurement — several plausible candidates were cut above.
+ */
+export const DEFAULT_ENVIRONMENT_PROMPT = `You are running in Paddock, a web app — your replies render as GitHub-Flavored
+Markdown in a browser, not as terminal output.
+
+- Show, don't describe. A screenshot, rendering, chart or file the user is meant
+  to look at should be sent with \`mcp__paddock__send_file\`, which renders it
+  inline. A filesystem path, or "it's up on port 5026", leaves them unable to see
+  your evidence — or to catch you misreading it.
+- Make clickable things clickable. Bare URLs autolink; \`#123\` does not — write
+  \`[#123](https://github.com/owner/repo/issues/123)\`. Prefer a full URL to a bare
+  port number, and link a chat or project rather than quoting its id.`;

package/packages/server/dist/herdctl.d.ts

@@ -147,6 +147,57 @@ export declare class HerdctlService {
     private jobsIndexOrNull;
     private get jobsIndex();
     constructor(cfg: PaddockConfig);
+    /**
+     * The environment system prompt to append to a keeper turn (issue #635), or
+     * `undefined` when the instance opted out (`environmentPrompt: ""`) — herdctl
+     * treats a falsy `systemPromptAppend` as "don't touch the system prompt", so
+     * an opted-out instance is byte-identical to pre-#635 behaviour.
+     *
+     * Read from `this.cfg` here rather than taken as a per-turn option **on
+     * purpose**. Every user-visible turn shape — a human send, a slash command, a
+     * scheduled wake, a spawned sub-chat, a `driveMode: batch` trigger — funnels
+     * through {@link chat}, {@link chatSession} or {@link runCommand}, so applying
+     * it at that choke point makes coverage structural. Threading it through
+     * `ChatTurnOptions` instead would make it one more thing five call sites have
+     * to remember, which is exactly how `isSidechainMessage` ended up wired into
+     * 1 of 5 turn paths.
+     *
+     * It is orthogonal to `nativeSystemPrompt`: herdctl appends to whatever prompt
+     * the agent has, so this rides on top of the native preset AND of Paddock's
+     * terse replace prompt (see `buildSystemPrompt` in core's sdk-runtime, which
+     * folds an append into a preset's `append` field or concatenates onto a
+     * literal string).
+     */
+    private get environmentPromptAppend();
+    /**
+     * The same value for the **CLI** runtime (`driveMode: batch`), where it is NOT
+     * always safe to send.
+     *
+     * herdctl's CLI runtime has no `--append-system-prompt`; it folds
+     * `systemPromptAppend` into the single `--system-prompt` flag
+     * (`cli-runtime.ts`), and `--system-prompt` REPLACES Claude Code's preset:
+     *
+     *     agent.system_prompt && append  →  --system-prompt "<agent>\n\n<append>"   ✅ appends
+     *     append only                    →  --system-prompt "<append>"              ❌ REPLACES
+     *
+     * Paddock sets `agent.system_prompt` only when `nativeSystemPrompt` is false
+     * (herdctl-agent-config.ts), so on a DEFAULT batch instance the second branch
+     * fires and a two-rule environment note would silently become the agent's
+     * entire system prompt — the whole coding preset gone. That is the same
+     * replace-vs-append trap #635 warns about, one layer down.
+     *
+     * So: on the CLI path we send the append only when it will genuinely be
+     * appended. A default (native) batch instance is left byte-identical to
+     * pre-#635 and simply doesn't get the environment prompt — a missing hint is
+     * survivable; a missing coding prompt is not. The SDK runtime has no such
+     * problem (it folds the text into the preset's `append` field), and the SDK
+     * runtime is what every chat actually uses: `openChatSession` hard-codes it,
+     * and `session` is the default drive mode. Batch is the legacy path.
+     *
+     * Lifting this needs `--append-system-prompt` support in core's CLI runtime;
+     * tracked upstream in edspencer/herdctl.
+     */
+    private get environmentPromptAppendForCli();
     /**
      * Construct + initialize the FleetManager against a minimal zero-agent
      * config (fleet + defaults only). Agents are then registered programmatically

package/packages/server/dist/herdctl.js

@@ -208,6 +208,61 @@ export class HerdctlService {
     constructor(cfg) {
         this.cfg = cfg;
     }
+    /**
+     * The environment system prompt to append to a keeper turn (issue #635), or
+     * `undefined` when the instance opted out (`environmentPrompt: ""`) — herdctl
+     * treats a falsy `systemPromptAppend` as "don't touch the system prompt", so
+     * an opted-out instance is byte-identical to pre-#635 behaviour.
+     *
+     * Read from `this.cfg` here rather than taken as a per-turn option **on
+     * purpose**. Every user-visible turn shape — a human send, a slash command, a
+     * scheduled wake, a spawned sub-chat, a `driveMode: batch` trigger — funnels
+     * through {@link chat}, {@link chatSession} or {@link runCommand}, so applying
+     * it at that choke point makes coverage structural. Threading it through
+     * `ChatTurnOptions` instead would make it one more thing five call sites have
+     * to remember, which is exactly how `isSidechainMessage` ended up wired into
+     * 1 of 5 turn paths.
+     *
+     * It is orthogonal to `nativeSystemPrompt`: herdctl appends to whatever prompt
+     * the agent has, so this rides on top of the native preset AND of Paddock's
+     * terse replace prompt (see `buildSystemPrompt` in core's sdk-runtime, which
+     * folds an append into a preset's `append` field or concatenates onto a
+     * literal string).
+     */
+    get environmentPromptAppend() {
+        return this.cfg.environmentPrompt || undefined;
+    }
+    /**
+     * The same value for the **CLI** runtime (`driveMode: batch`), where it is NOT
+     * always safe to send.
+     *
+     * herdctl's CLI runtime has no `--append-system-prompt`; it folds
+     * `systemPromptAppend` into the single `--system-prompt` flag
+     * (`cli-runtime.ts`), and `--system-prompt` REPLACES Claude Code's preset:
+     *
+     *     agent.system_prompt && append  →  --system-prompt "<agent>\n\n<append>"   ✅ appends
+     *     append only                    →  --system-prompt "<append>"              ❌ REPLACES
+     *
+     * Paddock sets `agent.system_prompt` only when `nativeSystemPrompt` is false
+     * (herdctl-agent-config.ts), so on a DEFAULT batch instance the second branch
+     * fires and a two-rule environment note would silently become the agent's
+     * entire system prompt — the whole coding preset gone. That is the same
+     * replace-vs-append trap #635 warns about, one layer down.
+     *
+     * So: on the CLI path we send the append only when it will genuinely be
+     * appended. A default (native) batch instance is left byte-identical to
+     * pre-#635 and simply doesn't get the environment prompt — a missing hint is
+     * survivable; a missing coding prompt is not. The SDK runtime has no such
+     * problem (it folds the text into the preset's `append` field), and the SDK
+     * runtime is what every chat actually uses: `openChatSession` hard-codes it,
+     * and `session` is the default drive mode. Batch is the legacy path.
+     *
+     * Lifting this needs `--append-system-prompt` support in core's CLI runtime;
+     * tracked upstream in edspencer/herdctl.
+     */
+    get environmentPromptAppendForCli() {
+        return this.cfg.nativeSystemPrompt ? undefined : this.environmentPromptAppend;
+    }
     /**
      * Construct + initialize the FleetManager against a minimal zero-agent
      * config (fleet + defaults only). Agents are then registered programmatically
@@ -581,6 +636,8 @@ export class HerdctlService {
             onMessage: opts.onMessage,
             onJobCreated: opts.onJobCreated,
             injectedMcpServers: opts.injectedMcpServers,
+            // CLI runtime — see the getter: only safe when it will append, not replace.
+            systemPromptAppend: this.environmentPromptAppendForCli,
         });
     }
     /**
@@ -629,6 +686,7 @@ export class HerdctlService {
                 prompt: opts.prompt,
                 manageLifecycle: true,
                 injectedMcpServers: opts.injectedMcpServers,
+                systemPromptAppend: this.environmentPromptAppend,
                 // Stream assistant text token-by-token: the SDK emits `stream_event` /
                 // `text_delta` chunks that the translator surfaces as incremental
                 // `chat:response` frames (edspencer/herdctl#382, paddock#315).
@@ -781,6 +839,9 @@ export class HerdctlService {
             resume: opts.resume,
             // Stream the command's assistant text token-by-token (paddock#315).
             includePartialMessages: true,
+            // A slash command's output renders in the same chat bubble as any other
+            // turn, so it gets the same environment context (#635).
+            systemPromptAppend: this.environmentPromptAppend,
         });
         let sessionId = isResume ? opts.resume : null;
         try {

package/packages/server/dist/instance-config.d.ts

@@ -5,7 +5,12 @@ export declare const GROUPS: {
     label: string;
     description?: string;
 }[];
-type FieldType = "number" | "boolean" | "string" | "enum" | "string-list";
+/**
+ * How the Settings screen renders a field. `text` is `string` with a multi-line
+ * control (a `<textarea>`) — same wire shape, same coercion contract; the only
+ * difference is that the UI stops squashing paragraphs into one line.
+ */
+type FieldType = "number" | "boolean" | "string" | "text" | "enum" | "string-list";
 /** Outcome of coercing a raw patch value into a persistable one. */
 type Coerced = {
     ok: true;
@@ -32,10 +37,13 @@ interface FieldSpec {
     envVars: readonly string[];
     /**
      * Env-shadow semantics. Default (`false`) = the var shadows only when set to a
-     * non-blank value, matching `envOr`/`envOpt` in config.ts. Set `true` for
-     * `browserMcp`, whose loader (`loadBrowserMcp`) treats ANY defined value —
-     * including blank — as authoritative (`env !== undefined`), so a defined-but-
-     * blank `PADDOCK_BROWSER_MCP` forces `false` and must render read-only here too.
+     * non-blank value, matching `envOr`/`envOpt` in config.ts. Set `true` for the
+     * fields whose loaders key on `env !== undefined` instead, so a defined-but-
+     * blank var is still authoritative and must render read-only here too:
+     *  - `browserMcp` (`loadBrowserMcp`) — a blank `PADDOCK_BROWSER_MCP` forces
+     *    `false`;
+     *  - `environmentPrompt` (`loadEnvironmentPrompt`, #635) — a blank
+     *    `PADDOCK_ENVIRONMENT_PROMPT` IS the opt-out.
      */
     envShadowWhenDefined?: boolean;
     /** Built-in default (what you get with neither env nor file). `null` ⇒ unset. */

package/packages/server/dist/instance-config.js

@@ -35,6 +35,7 @@ import { DEFAULT_MAX_SPAWN_DEPTH, isValidMaxSpawnDepth } from "./spawn-capabilit
 import { DEFAULT_RECOVERY } from "./recovery-config.js";
 import { DEFAULT_ATTACHMENTS, sanitizeAllowedTypes } from "./attachments-config.js";
 import { DEFAULT_CURATION } from "./curation-config.js";
+import { DEFAULT_ENVIRONMENT_PROMPT } from "./environment-prompt.js";
 /** Groups the Settings screen renders, in display order. */
 export const GROUPS = [
     { id: "curation", label: "Curation", description: "Per-file token budgets the post-turn sweeper keeps its curated files under." },
@@ -76,6 +77,39 @@ const nonEmptyString = (raw) => typeof raw === "string" && raw.trim().length > 0
     : { ok: false, error: "must be a non-empty string" };
 /** A string that may be blank (blank clears the override → falls back to default). */
 const optString = (raw) => typeof raw === "string" ? { ok: true, value: raw.trim() } : { ok: false, error: "must be a string" };
+/**
+ * Upper bound on a prompt-shaped field, in characters. Nothing enforces a limit
+ * downstream — the text is concatenated into the system prompt of every single
+ * turn — so an accidental paste of a whole file would quietly tax every request
+ * on the instance forever. 32 KiB is ~50× the built-in default and far more than
+ * any deliberate environment note; past that, a 400 is kinder than silence.
+ */
+const MAX_PROMPT_CHARS = 32 * 1024;
+/**
+ * A free-text prompt body. Unlike {@link optString} this is **verbatim**: no
+ * trimming, because leading/trailing whitespace is content in a prompt and the
+ * operator's text must round-trip through YAML byte-for-byte.
+ *
+ * The three authoring states map onto the wire like this:
+ *  - `null` → delete the key → fall back to Paddock's built-in default,
+ *  - `""` → written as an empty string → append nothing (opt out),
+ *  - any other string → written verbatim → appended instead of the default.
+ *
+ * Rejects a NUL byte: it survives neither the repo's no-NUL invariant
+ * (`scripts/check-no-nul-bytes.mjs`) nor any useful reading of "a prompt".
+ */
+const promptText = (raw) => {
+    if (raw === null || raw === undefined)
+        return { ok: true, value: null };
+    if (typeof raw !== "string")
+        return { ok: false, error: "must be a string (or null to restore the default)" };
+    if (raw.length > MAX_PROMPT_CHARS) {
+        return { ok: false, error: `must be at most ${MAX_PROMPT_CHARS} characters (got ${raw.length})` };
+    }
+    if (raw.includes("\0"))
+        return { ok: false, error: "must not contain NUL bytes" };
+    return { ok: true, value: raw };
+};
 const oneOf = (values) => (raw) => typeof raw === "string" && values.includes(raw)
     ? { ok: true, value: raw }
     : { ok: false, error: `must be one of: ${values.join(", ")}` };
@@ -139,6 +173,12 @@ export const FIELDS = [
     { key: "driveMode", group: "capabilities", label: "Keeper drive mode", help: "session = persistent (streaming + cross-turn autonomy); batch = legacy one-shot.", type: "enum", enumValues: DRIVE_MODES, envVars: ["PADDOCK_DRIVE_MODE"], default: DEFAULT_DRIVE_MODE, editable: true, coerce: oneOf(DRIVE_MODES) },
     { key: "models", group: "capabilities", label: "Offered models", help: "Which built-in catalog models the picker offers, by id (e.g. claude-opus-5, claude-sonnet-5). Blank = offer all catalog models.", type: "string-list", envVars: ["PADDOCK_MODELS"], default: MODELS.map((m) => m.id), editable: true, coerce: modelList },
     { key: "nativeSystemPrompt", group: "capabilities", label: "Native system prompt", help: "Use Claude Code's native prompt + CLAUDE.md hierarchy (recommended).", type: "boolean", envVars: ["PADDOCK_NATIVE_PROMPT"], default: true, editable: true, coerce: asBool },
+    // Issue #635. `envShadowWhenDefined` because loadEnvironmentPrompt keys on
+    // definedness, not emptiness — a defined-but-empty PADDOCK_ENVIRONMENT_PROMPT
+    // IS the env-level opt-out, so it genuinely shadows the file and must render
+    // read-only. `default` carries the built-in text so the UI can offer a
+    // one-click restore (a `null` PUT deletes the key) without duplicating it.
+    { key: "environmentPrompt", group: "capabilities", label: "Environment prompt", help: "Appended to every keeper turn's system prompt: what the agent should know about rendering into Paddock rather than a terminal. Clear it to append nothing.", type: "text", envVars: ["PADDOCK_ENVIRONMENT_PROMPT"], envShadowWhenDefined: true, default: DEFAULT_ENVIRONMENT_PROMPT, editable: true, coerce: promptText },
     { key: "selfMcpEnabled", group: "capabilities", label: "Self-management MCP (read)", help: "Let keepers list/read projects and other chats.", type: "boolean", envVars: ["PADDOCK_SELF_MCP"], default: false, editable: true, coerce: asBool },
     { key: "selfMcpWriteEnabled", group: "capabilities", label: "Self-management MCP (write)", help: "Let keepers create/fork/message chats (needs read enabled too).", type: "boolean", envVars: ["PADDOCK_SELF_MCP_WRITE"], default: false, editable: true, coerce: asBool },
     { key: "selfMcpProjectsEnabled", group: "capabilities", label: "Self-management MCP (projects)", help: "Let keepers create whole new projects, cloning a repo when repo-backed (needs self-MCP write).", type: "boolean", envVars: ["PADDOCK_SELF_MCP_PROJECTS"], default: false, editable: true, coerce: asBool },

package/packages/server/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@paddock/server",
-  "version": "0.56.0",
+  "version": "0.57.0",
   "private": true,
   "type": "module"
 }

package/packages/web/dist/assets/InstanceConfigPage-Bypd_quL.js

@@ -0,0 +1,2 @@
+import{r as o,b as f,j as e,A as b,k as E,l as A,m as O,M as F,n as I}from"./index-B-YuzkF6.js";function $(){const[t,s]=o.useState(null),[l,i]=o.useState(!0),[r,c]=o.useState(null),[d,m]=o.useState({}),[h,k]=o.useState(!1),[j,p]=o.useState(null),[N,u]=o.useState(!1);o.useEffect(()=>{let a=!0;return i(!0),f.getInstanceConfig().then(n=>{a&&(s(n),c(null))}).catch(n=>a&&c(n instanceof Error?n.message:String(n))).finally(()=>a&&i(!1)),()=>{a=!1}},[]);const v=(a,n)=>{u(!1),p(null),m(g=>({...g,[a]:n}))},S=a=>Object.prototype.hasOwnProperty.call(d,a.key)?d[a.key]:a.value,y=o.useMemo(()=>t?t.groups.flatMap(a=>a.fields):[],[t]),x=o.useMemo(()=>y.filter(a=>a.editable&&!a.envOverridden).filter(a=>Object.prototype.hasOwnProperty.call(d,a.key)).filter(a=>!B(d[a.key],a.value)).map(a=>a.key),[y,d]),w=async()=>{if(x.length===0)return;const a={};for(const n of x)a[n]=d[n];k(!0),p(null);try{await f.updateInstanceConfig(a);const n=await f.getInstanceConfig();s(n),m({}),u(!0)}catch(n){p(n instanceof A||n instanceof Error?n.message:String(n))}finally{k(!1)}},C=()=>{m({}),p(null),u(!1)};return e.jsxs(e.Fragment,{children:[e.jsx("div",{className:"min-h-0 flex-1 overflow-y-auto px-4 py-5 sm:px-6",children:e.jsxs("div",{className:"mx-auto max-w-2xl",children:[e.jsx(L,{saved:N,configPath:t==null?void 0:t.configPath}),l&&e.jsx("p",{className:"text-sm text-paddock-500",children:"Loading…"}),r&&e.jsxs("p",{className:"text-sm text-red-600 dark:text-red-400",role:"alert",children:["Failed to load settings: ",r]}),t&&t.groups.map(a=>e.jsx(M,{title:a.label,description:a.description,children:e.jsx("div",{className:"grid grid-cols-1 gap-4",children:a.fields.map(n=>e.jsx(P,{field:n,value:S(n),onChange:g=>v(n.key,g)},n.key))})},a.id))]})}),t&&e.jsxs("footer",{className:"flex items-center gap-3 border-t border-paddock-200 px-4 py-3 dark:border-paddock-800 sm:px-6",children:[j&&e.jsxs("span",{className:"flex items-center gap-1.5 text-[13px] text-red-600 dark:text-red-400",role:"alert",children:[e.jsx(b,{width:14,height:14,className:"shrink-0"}),j]}),e.jsx("span",{className:"ml-auto text-[12px] text-paddock-400",children:x.length>0?`${x.length} unsaved change${x.length===1?"":"s"}`:"No changes"}),e.jsx("button",{type:"button",className:"btn-subtle",onClick:C,disabled:x.length===0||h,children:"Reset"}),e.jsx("button",{type:"button",className:"btn-primary",onClick:w,disabled:x.length===0||h,children:h?"Saving…":"Save changes"})]})]})}function L({saved:t,configPath:s}){return e.jsxs("div",{role:"status",className:`mb-6 flex items-start gap-2 rounded-lg border px-3 py-2.5 text-[13px] leading-snug ${t?"border-emerald-300 bg-emerald-50 text-emerald-800 dark:border-emerald-700/60 dark:bg-emerald-900/20 dark:text-emerald-300":"border-amber-300 bg-amber-50 text-amber-800 dark:border-amber-700/60 dark:bg-amber-900/20 dark:text-amber-300"}`,children:[t?e.jsx(E,{width:15,height:15,className:"mt-0.5 shrink-0"}):e.jsx(b,{width:15,height:15,className:"mt-0.5 shrink-0"}),e.jsx("span",{children:t?e.jsxs(e.Fragment,{children:[e.jsx("strong",{children:"Saved to disk."})," These changes take effect only after the server restarts."]}):e.jsxs(e.Fragment,{children:["Changes here are written to ",e.jsx("code",{className:"font-mono text-[12px]",children:T(s)})," ","and take effect only after the server restarts — the running instance keeps its current config until then."]})})]})}function M({title:t,description:s,children:l}){return e.jsxs("section",{className:"mb-6",children:[e.jsx("h2",{className:"text-sm font-semibold uppercase tracking-wide text-paddock-500",children:t}),s&&e.jsx("p",{className:"mb-3 mt-0.5 text-[13px] text-paddock-500",children:s}),e.jsx("div",{className:`card ${s?"":"mt-2"}`,children:l})]})}function P({field:t,value:s,onChange:l}){const i=!t.editable||t.envOverridden,r=`cfg-${t.key}`;return e.jsxs("div",{children:[e.jsxs("div",{className:"flex items-center justify-between gap-3",children:[e.jsxs("label",{htmlFor:i?void 0:r,className:"text-sm font-medium",children:[t.label,t.sensitive&&e.jsx("span",{className:"ml-1.5 align-middle text-[10px] font-semibold uppercase tracking-wide text-amber-600 dark:text-amber-400",children:"sensitive"})]}),t.type==="boolean"&&!i&&e.jsx("input",{id:r,type:"checkbox",className:"h-4 w-4 accent-accent",checked:!!s,onChange:c=>l(c.target.checked)})]}),t.help&&e.jsx("p",{className:"mt-0.5 text-[12px] leading-snug text-paddock-500",children:t.help}),i?e.jsx(V,{field:t,value:s}):t.type!=="boolean"&&e.jsx(R,{field:t,value:s,onChange:l,inputId:r}),t.envOverridden&&e.jsxs("p",{className:"mt-1 flex items-start gap-1.5 text-[12px] leading-snug text-amber-600 dark:text-amber-400",children:[e.jsx(b,{width:13,height:13,className:"mt-0.5 shrink-0"}),e.jsxs("span",{children:["Overridden by environment variable ",e.jsx("code",{className:"font-mono",children:t.envVar})," — edit that env var (and restart) to change it."]})]})]})}function R({field:t,value:s,onChange:l,inputId:i}){if(t.type==="enum")return e.jsx("select",{id:i,className:"input mt-1.5",value:String(s??""),onChange:r=>l(r.target.value),children:(t.enumValues??[]).map(r=>e.jsx("option",{value:r,children:r},r))});if(t.type==="number")return e.jsx("input",{id:i,type:"number",className:"input mt-1.5",value:s==null?"":String(s),placeholder:t.default===null?"default":String(t.default),onChange:r=>l(r.target.value===""?null:Number(r.target.value))});if(t.type==="text"){const r=s==null||s===t.default,c=s==null?String(t.default??""):String(s),d=typeof t.default=="string"&&!r;return e.jsxs("div",{className:"mt-1.5",children:[e.jsx("textarea",{id:i,className:"input min-h-[9rem] resize-y font-mono text-[12px] leading-relaxed",rows:10,spellCheck:!1,value:c,onChange:m=>l(m.target.value)}),e.jsxs("div",{className:"mt-1 flex items-center justify-between gap-3 text-[12px] text-paddock-500",children:[e.jsx("span",{children:r?"Using the built-in default.":s===""?"Empty — nothing will be appended.":`${c.length.toLocaleString()} characters.`}),d&&e.jsx("button",{type:"button",className:"shrink-0 underline underline-offset-2 hover:text-paddock-700 dark:hover:text-paddock-300",onClick:()=>l(null),children:"Restore default"})]})]})}if(t.type==="string-list"){const r=Array.isArray(s)?s.join(", "):String(s??"");return e.jsx("input",{id:i,type:"text",className:"input mt-1.5",value:r,onChange:c=>l(c.target.value.split(",").map(d=>d.trim()).filter(Boolean))})}return e.jsx("input",{id:i,type:"text",className:"input mt-1.5",value:s==null?"":String(s),placeholder:t.default===null?"":String(t.default),onChange:r=>l(r.target.value)})}function V({field:t,value:s}){return e.jsx("div",{className:"mt-1.5 rounded-md border border-dashed border-paddock-300 bg-paddock-50 px-2.5 py-1.5 text-[13px] text-paddock-600 dark:border-paddock-700 dark:bg-paddock-900/40 dark:text-paddock-300",children:t.type==="boolean"?e.jsx("span",{className:"font-mono",children:s?"true":"false"}):s==null||s===""?e.jsx("span",{className:"italic text-paddock-400",children:t.type==="text"&&s===""?"(empty — nothing appended)":"(not set)"}):t.type==="text"?e.jsx("span",{className:"block max-h-64 overflow-y-auto whitespace-pre-wrap font-mono text-[12px] leading-relaxed",children:String(s)}):e.jsx("span",{className:"break-all font-mono",children:Array.isArray(s)?s.join(", "):String(s)})})}function B(t,s){return Array.isArray(t)&&Array.isArray(s)?t.length===s.length&&t.every((l,i)=>l===s[i]):t===s}function T(t){if(!t)return"paddock.config.yaml";const s=t.split("/");return s[s.length-1]||t}function z(){const t=O(),s=(t==null?void 0:t.openNav)??(()=>{});return e.jsxs("div",{className:"flex h-full min-h-0 flex-col",children:[e.jsxs("header",{className:"pt-safe flex items-center gap-2 border-b border-paddock-200 px-3 pb-2.5 dark:border-paddock-800 sm:px-6 lg:py-4",children:[e.jsx("button",{type:"button",onClick:s,"aria-label":"Open menu",className:"btn-subtle -ml-1 shrink-0 px-2 py-1.5 lg:hidden",children:e.jsx(F,{width:20,height:20})}),e.jsx(I,{width:18,height:18,className:"shrink-0 text-paddock-400"}),e.jsx("h1",{className:"text-[15px] font-semibold tracking-tight",children:"Config"})]}),e.jsx($,{})]})}export{z as InstanceConfigPage};
+