@edspencer/paddock 0.56.0 → 0.58.0

package/package.json

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

package/packages/server/dist/cli/import-chats.js

@@ -37,6 +37,7 @@
  *                      Applied to the environment BEFORE the config is read.
  *   --json             Emit the raw result as JSON instead of prose.
  */
+import { pathToFileURL } from "node:url";
 import { loadPaddockConfig } from "../config.js";
 import { ProjectStore, ROOT_KEY } from "../projects.js";
 import { HerdctlService } from "../herdctl.js";
@@ -187,7 +188,11 @@ async function main() {
     }
 }
 // Only run when invoked directly, so the arg parser stays unit-testable.
-if (process.argv[1] !== undefined && import.meta.url === `file://${process.argv[1]}`) {
+// `pathToFileURL`, not `"file://" + argv[1]`: the naive concatenation leaves any
+// space or non-ASCII character in the path un-encoded, so the comparison fails
+// and the script silently does nothing when run from such a directory — the same
+// percent-encoding trap as #636.
+if (process.argv[1] !== undefined && pathToFileURL(process.argv[1]).href === import.meta.url) {
     main()
         .then((code) => process.exit(code))
         .catch((err) => {

package/packages/server/dist/cli/paddock.d.ts

@@ -1,2 +1,30 @@
 #!/usr/bin/env node
-export {};
+export interface CliOptions {
+    port?: string;
+    host?: string;
+    dataDir?: string;
+    open: boolean;
+    verbose: boolean;
+    help: boolean;
+    version: boolean;
+}
+/** A usage error. Thrown rather than exiting, so `parseArgs` stays testable. */
+export declare class CliError extends Error {
+}
+export declare function parseArgs(argv: string[]): CliOptions;
+/**
+ * Why this Node is unusable, or `undefined` if it is fine.
+ *
+ * Split from the exit so it can be tested. `engines` only warns by default, and
+ * the failure it eventually produces is an unexplained syntax error deep inside
+ * a dependency — which is nobody's idea of a first-run experience.
+ */
+export declare function nodeVersionProblem(nodeVersion: string): string | undefined;
+/**
+ * Translate a listen failure into something a human can act on.
+ *
+ * `EADDRINUSE` on 4000 is the single most likely first-run failure — it is a
+ * popular port and Paddock's own default — and Node's raw error names neither
+ * the port nor the flag that fixes it.
+ */
+export declare function explainListenError(err: unknown, host: string, port: string): string;

package/packages/server/dist/cli/paddock.js

@@ -1,34 +1,28 @@
 #!/usr/bin/env node
 /**
- * `paddock` — the npx / global-install entrypoint (#TBD).
+ * `paddock` — the npx / global-install entrypoint (#637, #638).
  *
- * PROTOTYPE. This is the user-facing front door for `npx @edspencer/paddock`:
- * someone who has never seen this repo runs one command and gets a working
- * instance on localhost. Everything here is preflight and defaults — the server
- * itself is unchanged, and `start()` is the same lifecycle `node dist/index.js`
- * uses.
+ * The user-facing front door for `npx @edspencer/paddock`: someone who has never
+ * seen this repo runs one command and gets a working instance on localhost.
+ * Everything here is preflight, defaults and presentation — the server itself is
+ * untouched, and `start()` is the same lifecycle `node dist/index.js` uses.
  *
- * The design constraint that shapes this file: the server is already
- * *tolerant* — every setting has a default, an empty data dir self-initializes,
- * and auth defaults to `none` on a loopback bind. So a bare `start()` would in
- * fact boot. What it would NOT do is tell a first-time user why their chats
- * fail, or where their data went. Hence:
+ * The design constraint that shapes this file: the server is already *tolerant*
+ * — every setting has a default, an empty data dir self-initializes, and auth
+ * defaults to `none` on a loopback bind. So a bare `start()` would in fact boot.
+ * What it would NOT do is tell a first-time user why their chats fail, where
+ * their data went, or which of the several hundred lines of JSON that just
+ * scrolled past contained the URL.
  *
- *   1. Node version — checked explicitly, because the `engines` field only
- *      warns and the eventual failure is an opaque syntax error.
- *   2. Data dir — defaults to `~/.paddock`, NOT the server's `./data`, which is
- *      relative to cwd and would litter whatever directory you happened to run
- *      npx from (and silently give you a different instance next time).
- *   3. `claude` on PATH — prepended from our own node_modules/.bin. Chats do not
- *      need it (the SDK runtime resolves its own bundled binary), but the
- *      sweeper and triggers shell out to `claude` by name.
- *   4. Credentials — a warning, never a hard failure: we cannot reliably detect
- *      a macOS Keychain login, so refusing to start would lock out valid users.
+ * Everything below the arg parser is side-effecting by nature, so the pure parts
+ * (`parseArgs`, `nodeVersionProblem`, `explainListenError`) are exported and
+ * unit-tested; the rest is exercised by running the built binary.
  */
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
-import { fileURLToPath } from "node:url";
+import { spawn } from "node:child_process";
+import { fileURLToPath, pathToFileURL } from "node:url";
 const MIN_NODE_MAJOR = 22;
 /** This module's own directory: `<…>/packages/server/dist/cli`. */
 const moduleDir = path.dirname(fileURLToPath(import.meta.url));
@@ -43,8 +37,7 @@ const moduleDir = path.dirname(fileURLToPath(import.meta.url));
  *              deps at `<pkg>/node_modules` only — two levels FURTHER up
  *
  * A fixed `../..` hop is right for the repo and wrong for the published tarball,
- * where it lands on `packages/server` and finds no `node_modules` at all. Walking
- * up is correct for both without branching on which one we are in.
+ * where it lands on `packages/server` and finds no `node_modules` at all.
  */
 function findUp(rel) {
     let dir = moduleDir;
@@ -59,14 +52,17 @@ function findUp(rel) {
 }
 /** Nearest ancestor holding a `package.json` — `packages/server` in both layouts. */
 const packageRoot = findUp("package.json") ?? path.resolve(moduleDir, "../..");
-function parseArgs(argv) {
-    const opts = { help: false, version: false };
+/** A usage error. Thrown rather than exiting, so `parseArgs` stays testable. */
+export class CliError extends Error {
+}
+export function parseArgs(argv) {
+    const opts = { open: false, verbose: false, help: false, version: false };
     for (let i = 0; i < argv.length; i++) {
         const arg = argv[i];
         const next = () => {
             const v = argv[++i];
             if (v === undefined)
-                fail(`${arg} needs a value`);
+                throw new CliError(`${arg} needs a value`);
             return v;
         };
         switch (arg) {
@@ -81,6 +77,13 @@ function parseArgs(argv) {
             case "--data-dir":
                 opts.dataDir = next();
                 break;
+            case "-o":
+            case "--open":
+                opts.open = true;
+                break;
+            case "--verbose":
+                opts.verbose = true;
+                break;
             case "-h":
             case "--help":
                 opts.help = true;
@@ -90,7 +93,7 @@ function parseArgs(argv) {
                 opts.version = true;
                 break;
             default:
-                fail(`unknown option: ${arg}\nRun \`paddock --help\` for usage.`);
+                throw new CliError(`unknown option: ${arg}\nRun \`paddock --help\` for usage.`);
         }
     }
     return opts;
@@ -117,6 +120,8 @@ Options
   -p, --port <port>       HTTP/WS port (default 4000, or $PORT)
       --host <host>       Bind address (default 127.0.0.1)
   -d, --data-dir <path>   Projects + state (default ~/.paddock, or $PADDOCK_DATA_DIR)
+  -o, --open              Open the app in your browser once it is listening
+      --verbose           Show the server's own logs (quiet by default)
   -v, --version           Print the Paddock version and exit
   -h, --help              Show this help
 
@@ -126,20 +131,31 @@ Credentials
   billing). If you already use Claude Code on this machine, an existing login
   under ~/.claude is picked up automatically. Otherwise run \`claude setup-token\`.
 
+Your data
+  Everything lives in one directory — ~/.paddock unless you pass --data-dir.
+  Projects, chat transcripts and settings all persist there between runs. Move
+  that directory to move your instance; delete it to start over. Nothing is
+  stored anywhere else.
+
 Notes
   Binds loopback with authentication disabled, which is safe for a laptop. To
   expose it on a network, set PADDOCK_AUTH_MODE first — Paddock refuses to bind
   a routable interface wide open. See AUTH.md.
 
 Docs: https://github.com/edspencer/paddock`;
-/** Node's own version gate. `engines` only warns by default, and the failure it
- *  eventually produces is an unexplained syntax error deep in a dependency. */
-function checkNodeVersion() {
-    const major = Number(process.versions.node.split(".")[0]);
-    if (Number.isFinite(major) && major < MIN_NODE_MAJOR) {
-        fail(`Node ${process.versions.node} is too old — Paddock needs Node ${MIN_NODE_MAJOR}+.\n` +
-            `Upgrade Node, then re-run. (nodejs.org, or \`nvm install ${MIN_NODE_MAJOR}\`)`);
-    }
+/**
+ * Why this Node is unusable, or `undefined` if it is fine.
+ *
+ * Split from the exit so it can be tested. `engines` only warns by default, and
+ * the failure it eventually produces is an unexplained syntax error deep inside
+ * a dependency — which is nobody's idea of a first-run experience.
+ */
+export function nodeVersionProblem(nodeVersion) {
+    const major = Number(nodeVersion.split(".")[0]);
+    if (!Number.isFinite(major) || major >= MIN_NODE_MAJOR)
+        return undefined;
+    return (`Node ${nodeVersion} is too old — Paddock needs Node ${MIN_NODE_MAJOR}+.\n` +
+        `Upgrade Node, then re-run. (nodejs.org, or \`nvm install ${MIN_NODE_MAJOR}\`)`);
 }
 /**
  * Put our bundled `claude` on PATH for child processes.
@@ -209,8 +225,54 @@ function noteFirstRun(dataDir) {
         "",
     ].join("\n"));
 }
+/** Open `url` in the default browser. Best-effort: failing is never fatal. */
+function openBrowser(url) {
+    const cmd = process.platform === "darwin" ? "open" : process.platform === "win32" ? "start" : "xdg-open";
+    try {
+        const child = spawn(cmd, [url], {
+            stdio: "ignore",
+            detached: true,
+            shell: process.platform === "win32", // `start` is a cmd builtin, not a binary
+        });
+        // A headless box has no xdg-open. The URL is printed either way, so an
+        // unopenable browser is a non-event rather than a failed run.
+        child.on("error", () => { });
+        child.unref();
+    }
+    catch {
+        /* as above */
+    }
+}
+/**
+ * Translate a listen failure into something a human can act on.
+ *
+ * `EADDRINUSE` on 4000 is the single most likely first-run failure — it is a
+ * popular port and Paddock's own default — and Node's raw error names neither
+ * the port nor the flag that fixes it.
+ */
+export function explainListenError(err, host, port) {
+    const code = err?.code;
+    if (code === "EADDRINUSE") {
+        return (`port ${port} is already in use.\n` +
+            `Something else is listening on ${host}:${port} — possibly another Paddock.\n` +
+            `Pick a different port:  paddock --port ${Number(port) + 1}`);
+    }
+    if (code === "EACCES") {
+        return (`not allowed to bind ${host}:${port}.\n` +
+            `Ports below 1024 need elevated privileges — use a higher one:  paddock --port 4000`);
+    }
+    return String(err?.message ?? err);
+}
 async function main() {
-    const opts = parseArgs(process.argv.slice(2));
+    let opts;
+    try {
+        opts = parseArgs(process.argv.slice(2));
+    }
+    catch (err) {
+        if (err instanceof CliError)
+            fail(err.message);
+        throw err;
+    }
     if (opts.help) {
         console.log(USAGE);
         return;
@@ -219,7 +281,9 @@ async function main() {
         console.log(readVersion());
         return;
     }
-    checkNodeVersion();
+    const problem = nodeVersionProblem(process.versions.node);
+    if (problem !== undefined)
+        fail(problem);
     addBundledBinsToPath();
     // Apply CLI defaults as env vars. This is the whole integration surface: the
     // server resolves config inside `buildApp()`, so anything set before the
@@ -232,16 +296,44 @@ async function main() {
         process.env.PORT = opts.port;
     if (opts.host)
         process.env.HOST = opts.host;
+    // Quiet by default. The server emits a few hundred lines on the way up, which
+    // scrolls the one line the user actually needs — the URL — off the top of the
+    // terminal. TWO loggers have to be told, and they are unrelated:
+    //   LOG_LEVEL          Paddock's own pino logger (config.ts).
+    //   HERDCTL_LOG_LEVEL  @herdctl/core's `createLogger`, which writes the
+    //                      `[fleet-manager] …` lines via console.info — pino's
+    //                      level cannot reach those.
+    // An explicit value for either is left alone, and `--verbose` skips both.
+    if (!opts.verbose) {
+        if (process.env.LOG_LEVEL === undefined)
+            process.env.LOG_LEVEL = "warn";
+        if (process.env.HERDCTL_LOG_LEVEL === undefined)
+            process.env.HERDCTL_LOG_LEVEL = "warn";
+    }
     warnIfNoCredentials(process.env.CLAUDE_HOME ?? path.join(os.homedir(), ".claude"));
     const port = process.env.PORT ?? "4000";
     const host = process.env.HOST ?? "127.0.0.1";
     // Imported dynamically, AFTER the env above is set: a static import would
     // pull in app.ts -> config.ts and resolve config against the wrong data dir.
     const { start } = await import("../start.js");
-    await start();
-    console.log(`\n  Paddock is running at http://${host}:${port}\n  Press Ctrl-C to stop.\n`);
+    try {
+        await start();
+    }
+    catch (err) {
+        fail(explainListenError(err, host, port));
+    }
+    const url = `http://${host}:${port}`;
+    console.log(`\n  Paddock is running at ${url}\n  Data: ${dataDir}\n  Press Ctrl-C to stop.\n`);
+    if (opts.open)
+        openBrowser(url);
+}
+// Run only when executed directly, so the unit tests can import the pure parts.
+// `pathToFileURL`, not `"file://" + argv[1]`: the naive concatenation breaks on
+// any path containing a space or non-ASCII character — the same percent-encoding
+// trap as #636.
+if (process.argv[1] !== undefined && pathToFileURL(process.argv[1]).href === import.meta.url) {
+    main().catch((err) => {
+        console.error("fatal:", err);
+        process.exit(1);
+    });
 }
-main().catch((err) => {
-    console.error("fatal:", err);
-    process.exit(1);
-});

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