@edspencer/paddock 0.0.1 → 0.56.0

package/packages/server/dist/herdctl-agent-config.d.ts

@@ -0,0 +1,98 @@
+import type { PaddockConfig } from "./config.js";
+import type { Project } from "./projects.js";
+import { type PaddockTrigger } from "./trigger-config.js";
+/**
+ * A project's keeper agent config. Inherits the fleet `defaults` (runtime,
+ * max_turns, permission_mode, allowed/denied tools) via addAgent's deep-merge;
+ * only project-specific fields are set here.
+ *
+ * Model resolution: `modelOverride` (a per-chat override) wins, else the
+ * project's persisted `model`, else the keeper default (Opus).
+ *
+ * System prompt: by default (`nativeSystemPrompt`, issue #176) we set NO
+ * `system_prompt`, so Claude Code's full default coding prompt applies — the SDK
+ * runtime falls back to the `claude_code` preset and the CLI runtime passes no
+ * `--system-prompt`, which amount to the same thing. It applies together with
+ * the project's CLAUDE.md hierarchy — the canonical instance-wide
+ * `<projectsRoot>/CLAUDE.md`
+ * (auto-loaded via the cwd walk-up, since a project dir is a child of the
+ * projects root) plus a per-project CLAUDE.md. This is its own decision (issue
+ * #176): an instance with no CLAUDE.md files can opt back into the terse replace
+ * prompt below with `PADDOCK_NATIVE_PROMPT=false`.
+ *
+ * This is the reading #512 settled on, and the reason it is `projectsRoot` and
+ * not `<dataDir>`: `projectsRoot` IS the instance's backing repo, so the file is
+ * version-controlled. Since #516 the ROOT project reaches it the same way —
+ * its cwd IS `projectsRoot`, so the walk-up needs no special-casing.
+ */
+export declare function buildAgentConfig(cfg: PaddockConfig, project: Project, modelOverride?: string): Record<string, unknown> & {
+    name: string;
+};
+/**
+ * The sweeper's working directory: a dedicated per-project dir under the data
+ * root, deliberately NOT the project dir (issue #548).
+ *
+ * A CLI agent's working directory is what Claude Code encodes into its
+ * transcript path, so two agents sharing a cwd share ONE session directory. The
+ * sweeper's cwd used to be `project.dir`, which for a notebook project equals the
+ * keeper's `project.workingDir` — so keeper and sweeper wrote their transcripts
+ * into the same `.chats/`. herdctl identifies a freshly-spawned session by
+ * set-difference against a pre-spawn directory snapshot, which is immune to a
+ * co-located agent *appending* to its own session but NOT to one *creating* a new
+ * file: whichever brand-new `*.jsonl` appears first is claimed as "ours". A sweep
+ * is scheduled after every keeper turn, so the sweeper's spawn raced the next
+ * keeper turn and a user's chat could be bound to the sweeper's hidden curation
+ * transcript (wrong reply streamed, wrong transcript resumed, chat missing from
+ * the project's list).
+ *
+ * The sweeper is TOOL-LESS, so its cwd is inert — nothing about curation depends
+ * on it (SweepService reads the project's files itself and inlines them in the
+ * prompt, then writes the results itself). Giving it its own directory removes
+ * the shared directory, and with it the whole class of collisions, structurally.
+ *
+ * Kept OUTSIDE `projectsRoot` on purpose: core's discovery unions every
+ * `~/.claude/projects/*` bucket whose decoded path is a strict *descendant* of an
+ * agent's cwd, and the root workspace's cwd IS `projectsRoot`.
+ */
+export declare function sweeperWorkingDir(cfg: PaddockConfig, slug: string): string;
+/**
+ * A project's sweeper (curator) agent config. TOOL-LESS: the sweeper has NO
+ * tools (`allowed_tools: []`) — it never reads or writes files. Instead it
+ * RETURNS the curated content as plain assistant text in marked sections
+ * (OVERVIEW / CHANGELOG / optional CLAUDE, issue #177); SweepService parses
+ * that text and writes OVERVIEW.md / CHANGELOG.md / CLAUDE.md itself.
+ *
+ * This is cheaper and far more predictable than letting a Haiku agent drive
+ * file edits: no tool-loop turns, no partial writes, no permission_mode /
+ * denied_tools to reason about (all irrelevant with zero tools).
+ */
+export declare function buildSweeperConfig(cfg: PaddockConfig, project: Project): Record<string, unknown> & {
+    name: string;
+};
+/**
+ * A trigger's scoped herdctl agent config (Epic T) — the unified successor to
+ * {@link hookAgentConfig}. A trigger that {@link triggerRunsOnOwnAgent} (every event
+ * trigger; a schedule trigger with a non-empty `run.tools` allow-list — T2) is
+ * registered as its OWN agent `trigger-<slug>-<name>` whose tool config
+ * (`allowed_tools`/`permission_mode`/`model`/`max_turns`, projected by
+ * {@link triggerToAgentToolConfig} from the trigger's `run`) IS its capability set.
+ * Runs in the project's WORKING dir (so a trigger's Bash/Write act on the same tree
+ * the keeper does). A tool-less trigger gets `allowed_tools: []` and can only return text.
+ */
+export declare function buildTriggerConfig(cfg: PaddockConfig, project: Project, triggerName: string, trigger: PaddockTrigger): Record<string, unknown> & {
+    name: string;
+};
+/**
+ * Write the minimal herdctl.yaml the FleetManager boots from: a fleet block
+ * plus the fleet-wide `defaults` (deep-merged into agents added at runtime),
+ * and ZERO agents. All agents are registered programmatically via
+ * `fleet.addAgent(...)` in init() — paddock no longer generates per-agent
+ * yaml files or calls `reload()`.
+ *
+ * The `fleet` block is strict (name/description only). `defaults` are deep-
+ * merged into each agent by addAgent (mergeDefaults defaults to true), so agents
+ * inherit model/max_turns/permission_mode/allowed+denied_tools from here. NOT
+ * `runtime`: core's `DefaultsSchema` has no such key, so it is stripped at parse
+ * and every agent sets its own.
+ */
+export declare function ensureConfigFile(cfg: PaddockConfig): Promise<void>;

package/packages/server/dist/herdctl-agent-config.js

@@ -0,0 +1,331 @@
+/**
+ * herdctl-agent-config — the pure builders that project a Paddock `Project` (+
+ * config) into the herdctl agent-config objects `FleetManager.addAgent` accepts,
+ * plus {@link ensureConfigFile} which writes the minimal boot herdctl.yaml.
+ *
+ * Split out of {@link HerdctlService} (issue #403): every function here reads
+ * only its arguments (the `PaddockConfig` bag + the project/trigger) and the
+ * pure constants from {@link ./herdctl-agent-names.js} — no `fleet`/live-session
+ * state — so they are independently readable and testable. {@link HerdctlService}
+ * keeps thin private wrappers that delegate here (so `this.cfg` stays the single
+ * source of config and the existing private-method test seams are unchanged).
+ */
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import YAML from "yaml";
+import { DEFAULT_MODEL, SWEEPER_DEFAULT_MODEL, DEFAULT_PERMISSION_MODE, DEFAULT_MAX_TURNS, } from "./models.js";
+import { triggerToAgentToolConfig, triggersToHerdctlSchedules, curatorTriggerOf, } from "./trigger-config.js";
+import { keeperAgentName, sweeperAgentName, triggerAgentName, browserMcpServers, BROWSER_MCP_TOOL, DENIED_TOOLS, KEEPER_MAX_CONCURRENT, KEEPER_SESSION_TIMEOUT, } from "./herdctl-agent-names.js";
+/**
+ * A project's keeper agent config. Inherits the fleet `defaults` (runtime,
+ * max_turns, permission_mode, allowed/denied tools) via addAgent's deep-merge;
+ * only project-specific fields are set here.
+ *
+ * Model resolution: `modelOverride` (a per-chat override) wins, else the
+ * project's persisted `model`, else the keeper default (Opus).
+ *
+ * System prompt: by default (`nativeSystemPrompt`, issue #176) we set NO
+ * `system_prompt`, so Claude Code's full default coding prompt applies — the SDK
+ * runtime falls back to the `claude_code` preset and the CLI runtime passes no
+ * `--system-prompt`, which amount to the same thing. It applies together with
+ * the project's CLAUDE.md hierarchy — the canonical instance-wide
+ * `<projectsRoot>/CLAUDE.md`
+ * (auto-loaded via the cwd walk-up, since a project dir is a child of the
+ * projects root) plus a per-project CLAUDE.md. This is its own decision (issue
+ * #176): an instance with no CLAUDE.md files can opt back into the terse replace
+ * prompt below with `PADDOCK_NATIVE_PROMPT=false`.
+ *
+ * This is the reading #512 settled on, and the reason it is `projectsRoot` and
+ * not `<dataDir>`: `projectsRoot` IS the instance's backing repo, so the file is
+ * version-controlled. Since #516 the ROOT project reaches it the same way —
+ * its cwd IS `projectsRoot`, so the walk-up needs no special-casing.
+ */
+export function buildAgentConfig(cfg, project, modelOverride) {
+    const config = {
+        name: keeperAgentName(project.slug),
+        description: project.summary || `Claude Code agent for project ${project.name}.`,
+        // Repo-backed projects (issue #187): the keeper runs INSIDE the cloned
+        // checkout (project.workingDir), so the repo's own CLAUDE.md + git tooling
+        // apply. For a notebook project workingDir === dir, so this is unchanged.
+        working_directory: project.workingDir,
+        // `runtime` governs the ONE-SHOT `trigger()` path only — it does NOT decide
+        // how chats run. `openChatSession` (session drive-mode, the default) hard-codes
+        // `new SDKRuntime()` and never reads this field, so a normal chat runs on the
+        // Claude Agent SDK regardless. This value bites only when a project is set to
+        // `driveMode: batch`, whose turns go through `RuntimeFactory.create`. Set here
+        // per-agent because core's `DefaultsSchema` has no `runtime` key: the fleet
+        // `defaults.runtime` we write below is stripped when the file is parsed, so
+        // there is nothing for addAgent's deep-merge to hand down. Same for the
+        // sweeper and trigger copies.
+        runtime: "cli",
+        model: modelOverride ?? project.model ?? DEFAULT_MODEL,
+        // Per-project keeper settings (issue #12). The project DTO always carries
+        // concrete values (fleet defaults resolved in projects.ts), so setting
+        // them here just overrides the inherited fleet `defaults` per project.
+        permission_mode: project.permissionMode ?? DEFAULT_PERMISSION_MODE,
+        max_turns: project.maxTurns ?? DEFAULT_MAX_TURNS,
+        // Allow parallel chats per project (forks, and just multiple open chats)
+        // instead of herdctl's serialize-by-default max_concurrent: 1.
+        instances: { max_concurrent: KEEPER_MAX_CONCURRENT },
+        // Session retention (Paddock#111): keep an agent-level session alive long
+        // enough that a scheduler-fired wake can still resume its transcript. Note
+        // Paddock always resumes by EXPLICIT session id, which bypasses this
+        // timeout — and the transcript itself is governed by Claude Code's
+        // `cleanupPeriodDays` (default 30d, adequate for realistic wake horizons;
+        // set out-of-band via .claude/settings.json if longer horizons are needed).
+        // So this is defense-in-depth for the fallback-resume path, sized to the
+        // reaper's 7-day recurring-wake expiry.
+        session: { timeout: KEEPER_SESSION_TIMEOUT },
+        default_prompt: "Summarize the current state of this project.",
+    };
+    // Docker isolation: only set it when the project opts in, so a project that
+    // leaves it off keeps inheriting the fleet default (no Docker) unchanged.
+    if (project.docker)
+        config.docker = { enabled: true };
+    // Native by default: omit the replace prompt so the default coding prompt +
+    // CLAUDE.md hierarchy apply (issue #176). Only a non-native instance
+    // (PADDOCK_NATIVE_PROMPT=false) gets the terse replace prompt.
+    if (!cfg.nativeSystemPrompt) {
+        config.system_prompt =
+            "You are a Claude Code agent for this project directory. " +
+                "Honor any CLAUDE.md present. Keep CHANGELOG.md current. " +
+                "Create branches for significant changes; never force-push.";
+    }
+    // Unified triggers (Epic T / T1): SCHEDULE-type triggers are forwarded into the
+    // keeper agent's `schedules` block, in herdctl's OWN `ScheduleSchema` shape,
+    // UNMOLESTED — herdctl's cron engine reads `agent.schedules` live every tick, so
+    // declaring them here arms them with no translation. The Paddock-only `promptFile`
+    // is stripped (the schedule-trigger handler resolves it at fire time). Event/webhook
+    // triggers are excluded by triggersToHerdctlSchedules. Only set the key when
+    // non-empty so a trigger-less project stays byte-identical to before.
+    const schedules = triggersToHerdctlSchedules(project.triggers);
+    if (schedules)
+        config.schedules = schedules;
+    // Browser MCP (headless Chromium) when enabled for this box; `mcp__playwright__*`
+    // is already on the inherited defaults.allowed_tools.
+    const browser = browserMcpServers(cfg.browserMcp);
+    if (browser)
+        config.mcp_servers = browser;
+    return config;
+}
+/**
+ * The sweeper's working directory: a dedicated per-project dir under the data
+ * root, deliberately NOT the project dir (issue #548).
+ *
+ * A CLI agent's working directory is what Claude Code encodes into its
+ * transcript path, so two agents sharing a cwd share ONE session directory. The
+ * sweeper's cwd used to be `project.dir`, which for a notebook project equals the
+ * keeper's `project.workingDir` — so keeper and sweeper wrote their transcripts
+ * into the same `.chats/`. herdctl identifies a freshly-spawned session by
+ * set-difference against a pre-spawn directory snapshot, which is immune to a
+ * co-located agent *appending* to its own session but NOT to one *creating* a new
+ * file: whichever brand-new `*.jsonl` appears first is claimed as "ours". A sweep
+ * is scheduled after every keeper turn, so the sweeper's spawn raced the next
+ * keeper turn and a user's chat could be bound to the sweeper's hidden curation
+ * transcript (wrong reply streamed, wrong transcript resumed, chat missing from
+ * the project's list).
+ *
+ * The sweeper is TOOL-LESS, so its cwd is inert — nothing about curation depends
+ * on it (SweepService reads the project's files itself and inlines them in the
+ * prompt, then writes the results itself). Giving it its own directory removes
+ * the shared directory, and with it the whole class of collisions, structurally.
+ *
+ * Kept OUTSIDE `projectsRoot` on purpose: core's discovery unions every
+ * `~/.claude/projects/*` bucket whose decoded path is a strict *descendant* of an
+ * agent's cwd, and the root workspace's cwd IS `projectsRoot`.
+ */
+export function sweeperWorkingDir(cfg, slug) {
+    // The root workspace's key is "" (see project-paths.ts); reuse the same
+    // `_root` spelling the agent namespace uses so every sweeper dir is non-empty.
+    // Any other slug is SLUG_RE-validated upstream, so it holds no separators.
+    return path.join(cfg.dataDir, "sweepers", slug === "" ? "_root" : slug);
+}
+/**
+ * A project's sweeper (curator) agent config. TOOL-LESS: the sweeper has NO
+ * tools (`allowed_tools: []`) — it never reads or writes files. Instead it
+ * RETURNS the curated content as plain assistant text in marked sections
+ * (OVERVIEW / CHANGELOG / optional CLAUDE, issue #177); SweepService parses
+ * that text and writes OVERVIEW.md / CHANGELOG.md / CLAUDE.md itself.
+ *
+ * This is cheaper and far more predictable than letting a Haiku agent drive
+ * file edits: no tool-loop turns, no partial writes, no permission_mode /
+ * denied_tools to reason about (all irrelevant with zero tools).
+ */
+export function buildSweeperConfig(cfg, project) {
+    // T5: the sweeper IS the default `curate-overview` (event/afterTurn) trigger. When a
+    // project declares that trigger with a `run.model`, honor it as the sweeper agent's
+    // model (design §2.1 #4). herdctl's per-fire trigger API has no model override, so
+    // the per-project `sweeper-<slug>` agent carries it — applied at (re-)registration
+    // (boot / `ensureProjectAgent`). Absent ⇒ the cheap curation default, unchanged.
+    const curatorModel = curatorTriggerOf(project.triggers)?.run.model;
+    return {
+        name: sweeperAgentName(project.slug),
+        description: `Overview/changelog curator (sweeper) for project ${project.name}.`,
+        // NOT project.dir — see sweeperWorkingDir (issue #548).
+        working_directory: sweeperWorkingDir(cfg, project.slug),
+        // The sweeper only ever runs via the one-shot `trigger()` path, so unlike the
+        // keeper's copy this one really does take effect on every sweep: a `claude -p`
+        // CLI subprocess. Set here per-agent because core's `DefaultsSchema` has no
+        // `runtime` key — the fleet `defaults.runtime` never survives parsing, so
+        // there is nothing to inherit (registering via addAgent is not the reason:
+        // addAgent does deep-merge the loaded defaults, they just never carry it).
+        runtime: "cli",
+        model: curatorModel ?? SWEEPER_DEFAULT_MODEL,
+        // Tool-less: a handful of turns is plenty since there are no tool loops.
+        max_turns: 4,
+        // NO tools. The sweeper returns text only; SweepService does the writing.
+        allowed_tools: [],
+        system_prompt: "You are a concise project curator. You DO NOT use any tools — you only " +
+            "return text. From the recent activity, the current OVERVIEW.md, the " +
+            "recent CHANGELOG.md, and the current CLAUDE.md provided in the user " +
+            "message, produce these three sections wrapped in these literal markers, " +
+            "and NOTHING else:\n" +
+            "\n" +
+            "<<<OVERVIEW>>>\n" +
+            "<the full markdown OVERVIEW.md, which REPLACES the current one wholesale: " +
+            "a synthesized snapshot of the project's CURRENT state for an LLM to read " +
+            "at the start of a new chat — what the project is, key decisions/facts, " +
+            "open questions, and next steps. No changelog or per-session history here. " +
+            "Output exactly NOCHANGE only if the current one is already accurate.>\n" +
+            "<<<CHANGELOG>>>\n" +
+            "<the full markdown CHANGELOG.md, which REPLACES the current one wholesale. " +
+            "PRESERVE the existing dated entries and add at most ONE new bullet under a " +
+            "`## YYYY-MM-DD` heading at the TOP (newest-first), reusing today's heading " +
+            "if present; coalesce near-duplicate recent bullets. What you return becomes " +
+            "the ENTIRE file, so never emit a bare sentence or a lone bullet here — that " +
+            "would destroy the file's history. If this activity is already captured by a " +
+            "recent entry, output exactly NOCHANGE and change nothing.>\n" +
+            "<<<CLAUDE>>>\n" +
+            "<the full curated-notes body for CLAUDE.md — everything that belongs under " +
+            "the `## Curated notes` heading — which REPLACES that managed section " +
+            "wholesale (human-authored content above it is preserved for you). ONLY " +
+            "long-lived identity/conventions: what the project fundamentally is, key " +
+            "decisions, how we work on it. You are shown the whole current file, so " +
+            "DEDUP — fold near-duplicate notes into one and drop stale ones. Never " +
+            "restate current state/tasks/history (those are OVERVIEW/CHANGELOG). If " +
+            "nothing durable changed, output exactly NOCHANGE.>\n" +
+            "<<<END>>>\n" +
+            "\n" +
+            "OVERVIEW.md describes the PROJECT, not the box it runs on: never record " +
+            "box/environment operational conventions (how to run/build/expose a dev " +
+            "server, ports, localhost vs. dev hostnames/URLs, where to clone, process " +
+            "managers) — those are owned by the box's own CLAUDE.md and must not be " +
+            "re-described or contradicted here.\n" +
+            "\n" +
+            "Be factual and terse. Do not invent details not present in the provided " +
+            "activity. Output ONLY the three sections between the markers — no preamble, " +
+            "no explanation, no tool use.",
+        default_prompt: "Curate OVERVIEW.md, CHANGELOG.md and CLAUDE.md from recent activity.",
+    };
+}
+/**
+ * A trigger's scoped herdctl agent config (Epic T) — the unified successor to
+ * {@link hookAgentConfig}. A trigger that {@link triggerRunsOnOwnAgent} (every event
+ * trigger; a schedule trigger with a non-empty `run.tools` allow-list — T2) is
+ * registered as its OWN agent `trigger-<slug>-<name>` whose tool config
+ * (`allowed_tools`/`permission_mode`/`model`/`max_turns`, projected by
+ * {@link triggerToAgentToolConfig} from the trigger's `run`) IS its capability set.
+ * Runs in the project's WORKING dir (so a trigger's Bash/Write act on the same tree
+ * the keeper does). A tool-less trigger gets `allowed_tools: []` and can only return text.
+ */
+export function buildTriggerConfig(cfg, project, triggerName, trigger) {
+    const config = {
+        name: triggerAgentName(project.slug, triggerName),
+        description: `Trigger "${triggerName}" (${trigger.trigger.type}) for project ${project.name}.`,
+        working_directory: project.workingDir,
+        // Triggers fire through the one-shot `trigger()` path, so this takes effect on
+        // every fire: a `claude -p` CLI subprocess. Set here per-agent for the same
+        // reason as the keeper/sweeper copies: core's `DefaultsSchema` has no
+        // `runtime` key, so the fleet `defaults.runtime` is stripped at parse and
+        // never merged in.
+        runtime: "cli",
+        // Model defaults to the keeper default unless the run pins one;
+        // triggerToAgentToolConfig sets `model` only when the run specifies it, so
+        // provide the fallback here so a trigger never boots without a concrete model.
+        model: trigger.run.model ?? project.model ?? DEFAULT_MODEL,
+        // run → tool config (allowed tools, permission mode, model, max_turns).
+        ...triggerToAgentToolConfig(trigger.run),
+    };
+    if (project.docker)
+        config.docker = { enabled: true };
+    const browser = browserMcpServers(cfg.browserMcp);
+    if (browser)
+        config.mcp_servers = browser;
+    return config;
+}
+/**
+ * Write the minimal herdctl.yaml the FleetManager boots from: a fleet block
+ * plus the fleet-wide `defaults` (deep-merged into agents added at runtime),
+ * and ZERO agents. All agents are registered programmatically via
+ * `fleet.addAgent(...)` in init() — paddock no longer generates per-agent
+ * yaml files or calls `reload()`.
+ *
+ * The `fleet` block is strict (name/description only). `defaults` are deep-
+ * merged into each agent by addAgent (mergeDefaults defaults to true), so agents
+ * inherit model/max_turns/permission_mode/allowed+denied_tools from here. NOT
+ * `runtime`: core's `DefaultsSchema` has no such key, so it is stripped at parse
+ * and every agent sets its own.
+ */
+export async function ensureConfigFile(cfg) {
+    const configDir = path.dirname(cfg.herdctlConfigPath);
+    await fs.mkdir(configDir, { recursive: true });
+    const doc = {
+        version: 1,
+        fleet: {
+            name: "paddock",
+            description: "Paddock agent fleet (agents registered at runtime).",
+        },
+        defaults: {
+            // Currently INERT: core's `DefaultsSchema` has no `runtime` key, so this is
+            // stripped when the file is parsed and never reaches an agent — which is
+            // exactly why the keeper/sweeper/trigger configs above each set `runtime`
+            // themselves. Left in place because it costs nothing and records the
+            // fleet-wide intent; if core ever accepts it, every agent still overrides
+            // it. And even honoured it would govern the one-shot `trigger()` path only:
+            // chats opened via `openChatSession` always run the SDK runtime.
+            runtime: "cli",
+            // The default model, so any agent that doesn't set its own runs on it;
+            // in practice every agent above sets `model` explicitly anyway.
+            model: DEFAULT_MODEL,
+            // ~200 turns: enough for real multi-step coding sessions while still
+            // bounding runaway agents (CLAUDE.md: always set max_turns). A project
+            // can override this per-project (issue #12); this is the inherited
+            // default (shared constant so the DTO resolution stays in sync).
+            max_turns: DEFAULT_MAX_TURNS,
+            // Keeper agents run native (no Docker) with acceptEdits + denied
+            // dangerous bash patterns by default; a project can opt into Docker
+            // isolation or a different permission mode per-project (issue #12).
+            permission_mode: DEFAULT_PERMISSION_MODE,
+            // `Skill` MUST be in the allowlist or every skill invocation is
+            // permission-denied — both runtimes pass this list through verbatim (CLI:
+            // `--allowedTools`; SDK: `options.allowedTools`) and auto-deny any tool not
+            // on it, with no prompt. Built-in skills (claude-api,
+            // code-review, deep-research, ...) ship inside the CLI binary and are
+            // registered/visible regardless of setting-sources, so the ONLY thing
+            // blocking them was this missing tool. Skills routinely fan out to
+            // sub-agents (`Task`), track progress (`TodoWrite`), and edit notebooks
+            // (`NotebookEdit`), each of which is likewise permission-checked against
+            // this same allowlist — so include them here to keep skills functional
+            // end-to-end (adds no capability the keeper's existing tools don't).
+            // BROWSER_MCP_TOOL (mcp__playwright__*) is listed unconditionally: it is a
+            // no-op unless the keeper agent actually attaches the playwright
+            // server (gated by PADDOCK_BROWSER_MCP), and having it on the allowlist
+            // means enabling the browser is a per-box env flip with no code change.
+            // Timer-class autonomy tools (Paddock#111): `ScheduleWakeup` + the
+            // session-only `Cron*` set + `Monitor` must be on the allowlist or the
+            // runtime auto-denies them, so a keeper couldn't schedule a wake even in
+            // session mode. `ToolSearch` is the harness's deferred-tool loader —
+            // several of these surface as deferred tools reached through it. These
+            // only actually DO anything in session drive-mode (the reaper re-fires
+            // them); in batch mode they're inert (documented in the box CLAUDE.md).
+            allowed_tools: ["Read", "Edit", "Write", "Bash", "Glob", "Grep", "WebFetch", "WebSearch", "Task", "TodoWrite", "Skill", "NotebookEdit", "ToolSearch", "ScheduleWakeup", "Monitor", "CronCreate", "CronList", "CronDelete", BROWSER_MCP_TOOL],
+            // Best-effort denylist (#179): narrow, honest catastrophic-wipe patterns
+            // that do NOT block legitimate absolute-path cleanup. See DENIED_TOOLS.
+            denied_tools: [...DENIED_TOOLS],
+        },
+    };
+    const header = "# GENERATED by paddock-server. Do NOT hand-edit. Agents are NOT listed\n" +
+        "# here — they are registered at runtime via FleetManager.addAgent(). This\n" +
+        "# file only carries the fleet identity + the defaults merged into them.\n";
+    await fs.writeFile(cfg.herdctlConfigPath, header + YAML.stringify(doc), "utf8");
+}

package/packages/server/dist/herdctl-agent-names.d.ts

@@ -0,0 +1,172 @@
+/**
+ * herdctl-agent-names — the pure, stateless name/visibility helpers and
+ * constants that map a project slug (+ hook/trigger name) to the deterministic
+ * herdctl agent names Paddock registers, plus the small tool/model constants the
+ * agent-config builders lean on.
+ *
+ * These are split out of {@link HerdctlService} (issue #403) because they only
+ * read their arguments — no `fleet`/`cfg`/live-session state — so they are
+ * independently readable and unit-testable. Everything here is re-exported from
+ * `./herdctl.js` so external importers keep resolving via that path unchanged.
+ */
+import type { Project } from "./projects.js";
+/**
+ * Maps a workspace key to its keeper agent name. Kept deterministic so the
+ * runtime registration and runtime lookups always agree.
+ *
+ * The key is encoded through {@link agentKeyFor}, because the root workspace's
+ * key is `""` and a bare `keeper-` is not a legal herdctl agent name. Every
+ * builder below goes through the same encoding, so none of them needs a root
+ * branch. See `project-paths.ts` for why the encoding lives at this boundary
+ * rather than in the identity.
+ */
+export declare function keeperAgentName(slug: string): string;
+/**
+ * Inverse of {@link keeperAgentName}: recover a workspace key from a keeper
+ * agent name (`keeper-<agentKey>` → `<key>`). Returns `null` for a non-keeper
+ * agent (e.g. a sweeper or a trigger agent), which is how a scheduler-fired wake
+ * tells "this is a chat to route back to a workspace" from "this is not a chat
+ * at all".
+ *
+ * **Callers must distinguish `null` from `""`.** The root workspace's key IS the
+ * empty string, so a falsy check (`if (!key) return;`) silently drops every root
+ * chat from wake/turn/job routing. Compare against `null` explicitly.
+ */
+export declare function keeperSlugFromAgent(agentName: string): string | null;
+/**
+ * The lightweight curator agent used by the post-turn sweep. Runs on a cheap
+ * model (Haiku 4.5) with only read/write tools, no Bash.
+ *
+ * NOTE: herdctl agents bind working_directory per agent. Because a single
+ * shared sweeper can only have one cwd, the SweepService registers ONE sweeper
+ * agent PER PROJECT (keeper-style) so each has the right cwd. The name is
+ * derived from the slug; the agent reads/writes that project's files.
+ */
+export declare const SWEEPER_PREFIX = "sweeper-";
+/** Maps a project slug to its sweeper agent name. */
+export declare function sweeperAgentName(slug: string): string;
+/**
+ * The agent-name prefix for event hooks (Epic G / G1). Each hook is its OWN herdctl
+ * agent `hook-<slug>-<name>` (GG-1) — registered alongside the keeper/sweeper — whose
+ * tool config IS the hook's capability set.
+ */
+export declare const HOOK_AGENT_PREFIX = "hook-";
+/**
+ * Maps a project slug + hook name to its agent name `hook-<slug>-<name>`. Kept
+ * deterministic so runtime registration and firing (`startAgentTurn`) always agree.
+ * (`slug` is a kebab id and `name` matches `[A-Za-z0-9._-]+`, so the composed name is
+ * a valid herdctl agent name; the reverse mapping for visibility (G3) is resolved
+ * from a project's declared hooks, not by parsing this string.)
+ */
+export declare function hookAgentName(slug: string, hookName: string): string;
+/**
+ * The agent-name prefix for unified triggers (Epic T / T1). An EVENT trigger is its
+ * OWN herdctl agent `trigger-<slug>-<name>` (tool config = capability), registered
+ * alongside the keeper/sweeper — exactly like a hook agent. Schedule triggers run on
+ * the keeper (T1) and webhook triggers are reserved, but every trigger carries this
+ * deterministic name in its DTO so the mapping is stable across T2–T5.
+ */
+export declare const TRIGGER_AGENT_PREFIX = "trigger-";
+/**
+ * Maps a project slug + trigger name to its agent name `trigger-<slug>-<name>`. Kept
+ * deterministic so runtime registration and firing always agree. The reverse mapping
+ * (for visibility) is resolved from a project's declared triggers, not by parsing this
+ * string (a slug may contain hyphens). Mirrors {@link hookAgentName}.
+ */
+export declare function triggerAgentName(slug: string, triggerName: string): string;
+/**
+ * The agents whose chats are VISIBLE in a project's chat list (Epic G / G3, GG-5):
+ * the keeper plus every event hook the project declares (`hook-<slug>-<name>`). This
+ * is the generalization of the old hard "keeper-only" listing — "all of a project's
+ * agents EXCEPT those marked hidden."
+ *
+ * The **sweeper** (`sweeper-<slug>`) is the one hidden agent: it is deliberately
+ * omitted here so its post-turn curation chats never surface (the `hideChats` case),
+ * exactly as before. Disabled hooks are still included — a hook chat that already ran should stay
+ * visible regardless of whether the hook is currently armed.
+ *
+ * Kept pure + exported so the listing filter is unit-testable in isolation (the
+ * sweeper-stays-hidden regression lives here), and so future callers have ONE place
+ * that answers "which of a project's agents' chats do we show?".
+ */
+export declare function visibleProjectAgentNames(project: Project): string[];
+/**
+ * The Claude Code tool pattern for the Playwright browser MCP. Must live on the
+ * agent allowlist (both runtimes auto-deny any tool not on the allow-list —
+ * `--allowedTools` on the CLI, `options.allowedTools` on the SDK — same reason
+ * `Skill` is listed) — so it is added to `defaults.allowed_tools`,
+ * which the keeper agents inherit and the tool-less sweeper overrides
+ * away. Harmless when the server isn't enabled: an allowed-but-absent tool is a
+ * no-op.
+ */
+export declare const BROWSER_MCP_TOOL = "mcp__playwright__*";
+/**
+ * The keeper's default `denied_tools` — a **best-effort, defence-in-depth**
+ * denylist, NOT a sandbox. Real isolation (per-agent filesystem confinement)
+ * is tracked in #7; these string patterns are trivially bypassable (a relative
+ * path, a `$VAR`, a `find -delete`) and are here only to make the obvious
+ * catastrophic footguns require deliberate rephrasing.
+ *
+ * Claude Code Bash patterns are prefix-with-`*` matches: `Bash(foo *)` denies
+ * any command starting with `foo `, and `Bash(foo)` denies EXACTLY `foo`.
+ *
+ * History (#179): this list used to carry `Bash(rm -rf /*)`, intended as "don't
+ * wipe root". But `/*` is a trailing wildcard, so it actually denied
+ * `rm -rf /<ANYTHING>` — i.e. every absolute-path delete, including the keeper
+ * cleaning up its OWN scratch/clone dirs (`rm -rf /tmp/foo`,
+ * `rm -rf /var/lib/.../clones/x`). That was both over-broad (blocked legitimate
+ * work, wasted turns, confusing "denied" cards) and false security (the agent
+ * just switched to a relative `rm -rf clones/x` and it went through).
+ *
+ * The honest replacement targets genuinely-catastrophic *bare* roots:
+ * - `rm -rf /` and `rm -rf / *` (root, incl. `--no-preserve-root` variants),
+ * - `rm -rf ~` / `rm -rf $HOME` (home, exact — a trailing wildcard would block
+ *   `rm -rf ~/.cache/foo`, which is legitimate),
+ * - bare top-level system dirs matched EXACTLY (`Bash(rm -rf /etc)`, …) so that
+ *   real subpath deletes under them (notably `/var/lib/paddock/...` and
+ *   `/tmp/...`) are NOT denied.
+ *
+ * Note the deliberate gaps: a literal `rm -rf /*` glob command and
+ * `rm -rf /usr/local/...` are NOT caught, because the only pattern that would
+ * catch them (`Bash(rm -rf /*)`, `Bash(rm -rf /usr*)`) also re-blocks the
+ * legitimate absolute-path deletes we exist to allow. Narrow-and-honest beats
+ * broad-and-leaky; the sandbox (#7) is the real fix.
+ */
+export declare const DENIED_TOOLS: readonly string[];
+/**
+ * The Playwright browser MCP server given to the keeper agents so
+ * Claude Code can drive a headless Chromium (navigate / click / fill / snapshot
+ * / screenshot). Returns `undefined` when `enabled` is false (sourced from
+ * `cfg.browserMcp`, i.e. `PADDOCK_BROWSER_MCP=1` — issue #269), so a box WITHOUT
+ * the browser stack simply omits the server (no failed spawns) and enabling it
+ * is a per-box env flip — no code change.
+ *
+ * The browser is installed box-side by the homelab `paddock` Ansible role
+ * (`npm i -g @playwright/mcp` + `playwright install chromium`, exposing the
+ * `playwright-mcp` bin on PATH). The boxes are unprivileged LXCs, so Chromium
+ * must run headless + `--no-sandbox` (the container is the isolation boundary);
+ * `--isolated` keeps each session's profile in-memory (no persisted user-data
+ * dir). `--browser chromium` is REQUIRED: @playwright/mcp defaults to the
+ * `chrome` channel (branded Google Chrome), which isn't installed — without this
+ * flag the server tries to `playwright install chrome` at first use and stalls.
+ * The role installs the open-source `chromium` engine, so we select it here.
+ * The tool-less sweeper deliberately never receives this server.
+ */
+export declare function browserMcpServers(enabled: boolean): Record<string, unknown> | undefined;
+/**
+ * How many chat turns a project's keeper may run at once. herdctl defaults an
+ * agent to `max_concurrent: 1`, which would serialize a project's chats and make
+ * a second turn (e.g. the first message of a freshly *forked* chat sent while the
+ * parent is still streaming) fail with a ConcurrencyLimitError. Paddock is a
+ * single-user box that explicitly wants parallel chats per project — especially
+ * forks — so we lift the keeper's limit. (The shared-keeper model is still
+ * last-write-wins across concurrent chats of the same project; forks default to
+ * the parent's model, so that caveat rarely bites in practice.)
+ */
+export declare const KEEPER_MAX_CONCURRENT = 10;
+/**
+ * How long herdctl keeps a keeper's fallback session alive (Paddock#111). Sized
+ * to the reaper's 7-day recurring-wake expiry so a fallback resume still finds
+ * the session; explicit-id resume (Paddock's norm) bypasses this anyway.
+ */
+export declare const KEEPER_SESSION_TIMEOUT = "168h";