@edspencer/paddock 0.69.0 → 0.70.1

package/package.json

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

package/packages/server/dist/agent-errors.js

@@ -44,8 +44,14 @@ const KNOWN_CAUSES = [
         // Anchored to `claude` specifically. A bare /ENOENT/ would claim a missing
         // CLI for any file the engine failed to open, which is a confident wrong
         // answer — worse than the raw error it replaces.
+        //
+        // Name only what actually reads PATH (#771): the CLI runtime. The sweeper
+        // is always on it; triggers and chat turns only on `driveMode: batch`. An
+        // earlier wording said "the sweeper and triggers", which sent an operator
+        // on the default `session` mode to check the wrong thing.
         pattern: /ENOENT[^\n]{0,40}claude|claude: (command )?not found/i,
-        cause: "the `claude` CLI is not on PATH (needed by the sweeper and triggers)",
+        cause: "the `claude` CLI is not on PATH (needed by the sweeper, and by " +
+            "triggers/turns on `driveMode: batch`)",
     },
 ];
 /**

package/packages/server/dist/background-live.d.ts

@@ -35,29 +35,37 @@
  * a restart is correct, because Paddock stops the fleet with
  * `waitForJobs: false` and the tasks are genuinely dead.
  */
+/**
+ * The role for an SDK task type. Identity for anything unrecognised, which also
+ * means a future SDK that starts sending friendly names needs no change here.
+ */
+export declare function roleForTaskType(type: string): string;
 /**
  * One live background task, as broadcast to clients.
  *
- * `type` is the SDK's friendly label (`shell` | `subagent` | `monitor` |
- * `workflow`), falling back to the raw discriminant for kinds we do not know
- * about yet — deliberately a plain `string` rather than a union so a new SDK
- * task type renders as an unlabelled row instead of being dropped.
+ * `type` is the RAW SDK discriminant (`local_bash`, `local_agent`, …), kept
+ * verbatim so an unexpected kind is diagnosable from the wire. `role` is the
+ * rendering role derived from it by {@link roleForTaskType}. Both are plain
+ * `string`s rather than unions on purpose: a new SDK task type should render as
+ * a generic row, not be dropped.
  */
 export interface LiveBackgroundTask {
     id: string;
     type: string;
+    /** Rendering role derived from {@link type} — see {@link roleForTaskType}. */
+    role: string;
     description: string;
     /** Epoch-ms this task was first observed. Stamped here; the SDK sends no start time. */
     startedAt: number;
     /** Links the task to its launching tool card, when an edge has told us. */
     toolUseId?: string;
-    /** `subagent` only. */
+    /** `subagent` role only. */
     agentType?: string;
-    /** `shell` only. */
+    /** `shell` role only. */
     command?: string;
-    /** `workflow` only. */
+    /** `workflow` role only. */
     workflowName?: string;
-    /** `monitor` / MCP-task only. */
+    /** `monitor` / MCP-task role only. */
     server?: string;
     tool?: string;
     /** Latest tool the task ran, from `task_progress`. */

package/packages/server/dist/background-live.js

@@ -37,6 +37,44 @@
  */
 /** Terminal task statuses — a task in one of these is no longer live. */
 const TERMINAL_STATUSES = new Set(["completed", "failed", "stopped", "killed"]);
+/**
+ * SDK task-type discriminant → the role clients render (issue #846).
+ *
+ * This module used to document `type` as "the SDK's friendly label (`shell` |
+ * `subagent` | `monitor` | `workflow`)" and pass `task_type` straight through.
+ * **The CLI does no such mapping.** Its level payload is built by
+ *
+ * ```js
+ * .map((t) => ({ task_id: t.id, task_type: t.type, description: t.description }))
+ * ```
+ *
+ * — the INTERNAL discriminant verbatim. None of the four friendly names is in
+ * the CLI's own id-prefix table, so before this map every row fell through the
+ * client's unknown-kind fallback to a raw `local_bash` and a neutral clock.
+ * There was no case in which the friendly-name branches fired.
+ *
+ * The translation lives HERE, at the registry boundary, so one mapping serves
+ * every consumer rather than each of them re-deriving it. An unrecognised kind
+ * still falls through to its raw string — that fallback was always right, it
+ * just should not have been the only path.
+ */
+const TASK_ROLES = {
+    local_bash: "shell",
+    local_agent: "subagent",
+    remote_agent: "subagent",
+    in_process_teammate: "subagent",
+    local_workflow: "workflow",
+    monitor_mcp: "monitor",
+    monitor_ws: "monitor",
+    mcp_task: "task",
+};
+/**
+ * The role for an SDK task type. Identity for anything unrecognised, which also
+ * means a future SDK that starts sending friendly names needs no change here.
+ */
+export function roleForTaskType(type) {
+    return TASK_ROLES[type] ?? type;
+}
 const str = (v) => (typeof v === "string" && v ? v : undefined);
 const num = (v) => (typeof v === "number" && Number.isFinite(v) ? v : undefined);
 /**
@@ -159,10 +197,12 @@ export class BackgroundRegistry {
             if (!id)
                 continue;
             const existing = prev?.tasks.get(id);
+            const type = str(rt.task_type) ?? existing?.type ?? "task";
             next.set(id, {
                 ...existing,
                 id,
-                type: str(rt.task_type) ?? existing?.type ?? "task",
+                type,
+                role: roleForTaskType(type),
                 description: str(rt.description) ?? existing?.description ?? "",
                 startedAt: existing?.startedAt ?? this.now(),
             });

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

@@ -78,14 +78,19 @@ function readVersion() {
 /**
  * Put our bundled `claude` on PATH for child processes.
  *
- * Chat turns do NOT need this: they run herdctl's SDK runtime, which resolves
- * the binary from the Claude Agent SDK's own platform package via
- * `require.resolve` and never consults PATH. But the post-turn sweeper and all
- * triggers are one-shot `trigger()` calls on the CLI runtime, which does
- * `execa("claude", …)` — by name, without execa's `preferLocal`, so a local
- * install is invisible to it unless PATH says otherwise.
+ * Chat turns do NOT need this on the default `driveMode: session`: they run
+ * herdctl's SDK runtime, which resolves the binary from the Claude Agent SDK's
+ * own platform package via `require.resolve` and never consults PATH. The
+ * post-turn sweeper is the one unconditional user: always a one-shot
+ * `trigger()` call on the CLI runtime, which does `execa("claude", …)` — by
+ * name, without execa's `preferLocal`, so a local install is invisible to it
+ * unless PATH says otherwise. Triggers join it there only on `driveMode:
+ * batch`: a trigger resolves its drive mode exactly like a chat does
+ * (per-project override else `cfg.driveMode` — `resolveDriveMode` in
+ * ws-triggers.ts), so on a stock instance no trigger consults PATH either.
  *
- * Without this, chats work and every sweep/trigger fails (logged, non-fatal).
+ * Without this, chats work and every sweep fails (logged, non-fatal) — plus
+ * every trigger and turn on `driveMode: batch`.
  */
 function addBundledBinsToPath() {
     const owner = findUp(path.join("node_modules", ".bin"));

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

@@ -386,11 +386,14 @@ export interface PaddockConfig {
         warnings: string[];
     };
     /**
-     * Instance default for the hook-management MCP (Epic G / G5, GG-4) — the
-     * `mcp__paddock_manage__{list,set,remove}_hook` tools that let a project agent
-     * declare/edit/delete its own event hooks. A sibling of {@link selfMcpWriteEnabled}:
+     * Instance default for the hook-management MCP (Epic G / G5, GG-4) — now the
+     * unified TRIGGER tools `mcp__paddock_manage__{list_triggers,set_trigger,
+     * remove_trigger,run_trigger}` that let a project agent declare/edit/delete/fire
+     * its own triggers. Epic T / T3 collapsed the former `*_hook` and `*_schedule`
+     * verbs into these; the flag and its env var kept the `hooks` spelling.
+     * A sibling of {@link selfMcpWriteEnabled}:
      * OFF by default (opt-in), and only surfaces when the self-MCP write tools are also
-     * present (the hook tools live on the same injected server, appended in the write
+     * present (the trigger tools live on the same injected server, appended in the write
      * block). Driven by `PADDOCK_HOOKS_MCP`; accepts 1/true/yes. A per-project
      * `hooksMcpEnabled` override wins at dispatch (resolved via
      * {@link import("./hook-config.js").resolveHooksMcpEnabled}), the same
@@ -580,7 +583,6 @@ export interface PaddockConfigFile {
         autoReDrive?: boolean | string;
         debounceMs?: number | string;
         maxRetries?: number | string;
-        limboTimeoutMs?: number | string;
     };
     /**
      * Inbound composer-attachment config (issue #328). Every field optional; a

package/packages/server/dist/config.js

@@ -456,7 +456,6 @@ function loadRecoveryConfig(file) {
         autoReDrive: loadRecoveryBool("PADDOCK_RECOVERY_AUTODRIVE", f.autoReDrive, DEFAULT_RECOVERY.autoReDrive),
         debounceMs: loadRecoveryInt("PADDOCK_RECOVERY_DEBOUNCE_MS", f.debounceMs, DEFAULT_RECOVERY.debounceMs),
         maxRetries: loadRecoveryInt("PADDOCK_RECOVERY_MAX_RETRIES", f.maxRetries, DEFAULT_RECOVERY.maxRetries),
-        limboTimeoutMs: loadRecoveryInt("PADDOCK_RECOVERY_LIMBO_MS", f.limboTimeoutMs, DEFAULT_RECOVERY.limboTimeoutMs),
     };
 }
 /**

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

@@ -65,10 +65,11 @@ export declare class GitService {
      * successful check (repo-ness doesn't change under a running server); a thrown
      * git / missing-binary error resolves to `false`.
      *
-     * Store-wide, so it still gates the store-wide operations ({@link dirtyCounts},
-     * {@link remote}, {@link push}). The PER-PROJECT surface asks
-     * {@link isRepoAt} about the project's own working directory instead — see
-     * that method for why the two had to be separated.
+     * Store-wide, so it still gates the one genuinely store-wide operation,
+     * {@link dirtyCounts} — a single `git status` over the whole root. Everything
+     * else asks {@link isRepoAt} about the directory it is about to act on: the
+     * project's own working directory for status/diff/commit (#597, #206) and for
+     * remote/push (#710). See {@link isRepoAt} for why the two had to be separated.
      */
     isRepo(): Promise<boolean>;
     /**
@@ -101,6 +102,40 @@ export declare class GitService {
      * `projectDir`.
      */
     projectStatus(projectDir: string): Promise<GitProjectStatus>;
+    /**
+     * Whether `relPath` is a file git currently reports as UNTRACKED in
+     * `projectDir` — the read gate for the Changes tab's new-file view (#710).
+     *
+     * ## Why git's own answer, and not a path guard
+     *
+     * The Changes tab renders an untracked file's CONTENT (it has no diff), and
+     * until #710 it did so through the metadata-dir file surface — which 404'd for
+     * every project whose working directory is somewhere else. Serving the file
+     * from the working directory instead needs a guard, and the obvious one to
+     * reach for is `project-files.ts`'s: refuse any path descending through a
+     * dot-prefixed directory. That guard is right for the metadata dir and wrong
+     * here, in both directions:
+     *
+     *  - **It under-blocks on a worktree.** A linked worktree's `.git` is a FILE,
+     *    not a directory, so it is the LEAF — and the leaf is deliberately allowed
+     *    there (an untracked `.gitignore` has to render). The file is only a
+     *    `gitdir:` pointer, but serving it discloses the main checkout's path for
+     *    no reason.
+     *  - **It over-blocks on a real repo.** A brand-new untracked
+     *    `.github/workflows/ci.yml` is an ordinary Changes-tab row, and a
+     *    dot-directory rule refuses to render exactly the file the UI is listing.
+     *
+     * Asking git is both tighter and looser in the right places. `git status`
+     * never reports `.git` (file or directory), never reports an IGNORED path —
+     * so `.chats/` and anything else the repo excludes stays unreadable — and does
+     * report `.github/…`. The set the route may serve is then, by construction,
+     * exactly the set the pane already displays: no third notion of "allowed" to
+     * keep in step with the other two.
+     *
+     * `:(literal)` disables pathspec magic, so a filename containing `*` or `[` is
+     * matched as itself rather than as a pattern. False on any git failure.
+     */
+    isUntrackedFile(projectDir: string, relPath: string): Promise<boolean>;
     /**
      * `git diff --numstat` for a project's tracked working-tree changes, keyed by
      * PROJECT-relative path (`--relative` makes git emit paths relative to the
@@ -116,8 +151,23 @@ export declare class GitService {
     projectDiff(projectDir: string, file?: string): Promise<string>;
     /** Commit identity (from config, no global git config needed). */
     private identity;
-    /** Origin remote info + ahead/behind vs upstream (best-effort). */
-    remote(): Promise<{
+    /**
+     * Origin remote info + ahead/behind vs upstream (best-effort) for ONE
+     * directory's repository, defaulting to the backing store.
+     *
+     * The `dir` parameter is issue #710. `remote()` and {@link push} were the last
+     * two members of the per-project Changes surface still hard-wired to
+     * `projectsRoot` after #597/#709 moved status/diff/commit onto the project's
+     * `workingDir` — which made the pane's header self-contradictory: it showed the
+     * WORKTREE's branch beside an ahead-count, a remote URL and a Push button that
+     * all belonged to Paddock's own notes repo. Passing the working directory makes
+     * every field in that header describe one repository.
+     *
+     * For a notebook project (and for the root workspace) the working directory is
+     * inside `projectsRoot`, so this resolves to the same repo, same branch, same
+     * upstream as before — the generalisation costs those shapes nothing.
+     */
+    remote(dir?: string): Promise<{
         repo: boolean;
         configured: boolean;
         url?: string;
@@ -163,8 +213,13 @@ export declare class GitService {
      * Returns 0 for a directory that isn't a repo, matching "nothing to report".
      */
     dirtyCountAt(dir: string): Promise<number>;
-    /** Push the current branch to origin (sets upstream on first push). */
-    push(): Promise<{
+    /**
+     * Push one directory's current branch to origin (sets upstream on first push),
+     * defaulting to the backing store. See {@link remote} for why `dir` exists —
+     * in a linked WORKTREE `--abbrev-ref HEAD` is per-worktree, so this pushes the
+     * branch the user is actually looking at rather than the store's.
+     */
+    push(dir?: string): Promise<{
         pushed: boolean;
         error?: string;
     }>;

package/packages/server/dist/git.js

@@ -77,10 +77,11 @@ export class GitService {
      * successful check (repo-ness doesn't change under a running server); a thrown
      * git / missing-binary error resolves to `false`.
      *
-     * Store-wide, so it still gates the store-wide operations ({@link dirtyCounts},
-     * {@link remote}, {@link push}). The PER-PROJECT surface asks
-     * {@link isRepoAt} about the project's own working directory instead — see
-     * that method for why the two had to be separated.
+     * Store-wide, so it still gates the one genuinely store-wide operation,
+     * {@link dirtyCounts} — a single `git status` over the whole root. Everything
+     * else asks {@link isRepoAt} about the directory it is about to act on: the
+     * project's own working directory for status/diff/commit (#597, #206) and for
+     * remote/push (#710). See {@link isRepoAt} for why the two had to be separated.
      */
     async isRepo() {
         if (this.repoFlag !== null)
@@ -198,6 +199,70 @@ export class GitService {
         }
         return { repo: true, branch, files, clean: files.length === 0 };
     }
+    /**
+     * Whether `relPath` is a file git currently reports as UNTRACKED in
+     * `projectDir` — the read gate for the Changes tab's new-file view (#710).
+     *
+     * ## Why git's own answer, and not a path guard
+     *
+     * The Changes tab renders an untracked file's CONTENT (it has no diff), and
+     * until #710 it did so through the metadata-dir file surface — which 404'd for
+     * every project whose working directory is somewhere else. Serving the file
+     * from the working directory instead needs a guard, and the obvious one to
+     * reach for is `project-files.ts`'s: refuse any path descending through a
+     * dot-prefixed directory. That guard is right for the metadata dir and wrong
+     * here, in both directions:
+     *
+     *  - **It under-blocks on a worktree.** A linked worktree's `.git` is a FILE,
+     *    not a directory, so it is the LEAF — and the leaf is deliberately allowed
+     *    there (an untracked `.gitignore` has to render). The file is only a
+     *    `gitdir:` pointer, but serving it discloses the main checkout's path for
+     *    no reason.
+     *  - **It over-blocks on a real repo.** A brand-new untracked
+     *    `.github/workflows/ci.yml` is an ordinary Changes-tab row, and a
+     *    dot-directory rule refuses to render exactly the file the UI is listing.
+     *
+     * Asking git is both tighter and looser in the right places. `git status`
+     * never reports `.git` (file or directory), never reports an IGNORED path —
+     * so `.chats/` and anything else the repo excludes stays unreadable — and does
+     * report `.github/…`. The set the route may serve is then, by construction,
+     * exactly the set the pane already displays: no third notion of "allowed" to
+     * keep in step with the other two.
+     *
+     * `:(literal)` disables pathspec magic, so a filename containing `*` or `[` is
+     * matched as itself rather than as a pattern. False on any git failure.
+     */
+    async isUntrackedFile(projectDir, relPath) {
+        if (!isSafeRelPath(relPath))
+            return false;
+        if (!(await this.isRepoAt(projectDir)))
+            return false;
+        // Porcelain paths are REPO-ROOT relative; the caller's path is PROJECT
+        // relative. Rebase with the same `--show-prefix` the status route uses, so
+        // a project dir below the repo root compares like for like.
+        let prefix = "";
+        try {
+            prefix = (await this.git(projectDir, ["rev-parse", "--show-prefix"])).trim();
+        }
+        catch {
+            /* project dir is the repo root */
+        }
+        try {
+            const out = await this.git(projectDir, [
+                "status",
+                "--porcelain=v1",
+                "-z",
+                "--untracked-files=all",
+                "--",
+                `:(literal)${relPath}`,
+            ]);
+            return parsePorcelainZ(out).some((f) => f.untracked &&
+                (prefix && f.path.startsWith(prefix) ? f.path.slice(prefix.length) : f.path) === relPath);
+        }
+        catch {
+            return false;
+        }
+    }
     /**
      * `git diff --numstat` for a project's tracked working-tree changes, keyed by
      * PROJECT-relative path (`--relative` makes git emit paths relative to the
@@ -248,13 +313,28 @@ export class GitService {
     identity() {
         return this.author;
     }
-    /** Origin remote info + ahead/behind vs upstream (best-effort). */
-    async remote() {
-        if (!(await this.isRepo()))
+    /**
+     * Origin remote info + ahead/behind vs upstream (best-effort) for ONE
+     * directory's repository, defaulting to the backing store.
+     *
+     * The `dir` parameter is issue #710. `remote()` and {@link push} were the last
+     * two members of the per-project Changes surface still hard-wired to
+     * `projectsRoot` after #597/#709 moved status/diff/commit onto the project's
+     * `workingDir` — which made the pane's header self-contradictory: it showed the
+     * WORKTREE's branch beside an ahead-count, a remote URL and a Push button that
+     * all belonged to Paddock's own notes repo. Passing the working directory makes
+     * every field in that header describe one repository.
+     *
+     * For a notebook project (and for the root workspace) the working directory is
+     * inside `projectsRoot`, so this resolves to the same repo, same branch, same
+     * upstream as before — the generalisation costs those shapes nothing.
+     */
+    async remote(dir = this.projectsRoot) {
+        if (!(await this.isRepoAt(dir)))
             return { repo: false, configured: false };
         let branch;
         try {
-            branch = (await this.git(this.projectsRoot, ["rev-parse", "--abbrev-ref", "HEAD"])).trim();
+            branch = (await this.git(dir, ["rev-parse", "--abbrev-ref", "HEAD"])).trim();
             if (branch === "HEAD")
                 branch = undefined;
         }
@@ -263,7 +343,7 @@ export class GitService {
         }
         let url;
         try {
-            url = (await this.git(this.projectsRoot, ["remote", "get-url", "origin"])).trim();
+            url = (await this.git(dir, ["remote", "get-url", "origin"])).trim();
         }
         catch {
             return { repo: true, configured: false, branch };
@@ -271,12 +351,7 @@ export class GitService {
         let ahead;
         let behind;
         try {
-            const counts = (await this.git(this.projectsRoot, [
-                "rev-list",
-                "--left-right",
-                "--count",
-                "@{upstream}...HEAD",
-            ])).trim();
+            const counts = (await this.git(dir, ["rev-list", "--left-right", "--count", "@{upstream}...HEAD"])).trim();
             const [b, a] = counts.split(/\s+/).map((n) => Number.parseInt(n, 10));
             behind = Number.isFinite(b) ? b : undefined;
             ahead = Number.isFinite(a) ? a : undefined;
@@ -393,13 +468,18 @@ export class GitService {
             return 0;
         }
     }
-    /** Push the current branch to origin (sets upstream on first push). */
-    async push() {
-        if (!(await this.isRepo()))
+    /**
+     * Push one directory's current branch to origin (sets upstream on first push),
+     * defaulting to the backing store. See {@link remote} for why `dir` exists —
+     * in a linked WORKTREE `--abbrev-ref HEAD` is per-worktree, so this pushes the
+     * branch the user is actually looking at rather than the store's.
+     */
+    async push(dir = this.projectsRoot) {
+        if (!(await this.isRepoAt(dir)))
             return { pushed: false, error: "not a repo" };
         try {
-            const branch = (await this.git(this.projectsRoot, ["rev-parse", "--abbrev-ref", "HEAD"])).trim();
-            await this.git(this.projectsRoot, ["push", "--set-upstream", "origin", branch]);
+            const branch = (await this.git(dir, ["rev-parse", "--abbrev-ref", "HEAD"])).trim();
+            await this.git(dir, ["push", "--set-upstream", "origin", branch]);
             return { pushed: true };
         }
         catch (err) {

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

@@ -66,10 +66,36 @@ export declare function listProjectRuns(stateDir: string, project: Project, limi
  * the data source for the Triggers tab's per-trigger last-run column. Used to pull
  * one project's keeper AND every scoped `trigger-<slug>-<name>` agent in a single
  * pass so {@link import("./trigger-runtime.js").buildTriggerRuntime} can attribute a
- * scoped trigger's newest run by agent name. `listJobs` has no multi-agent filter,
- * so this scans the jobs dir once (unfiltered) and keeps only the requested agents;
- * order (started_at descending) is preserved. Errors swallow to `[]` so the runtime
- * view degrades to config-only rather than failing to render.
+ * scoped trigger's newest run by agent name. Order (started_at descending) is
+ * preserved. Errors swallow to `[]` so the runtime view degrades to config-only
+ * rather than failing to render.
+ *
+ * ## Why the filter is pushed down (#535)
+ *
+ * This used to call `listJobs(jobsDir)` with NEITHER filter nor limit, then
+ * filter and slice in JS — because `ListJobsFilter` had `agent` (exactly one)
+ * and no multi-agent form. That defeats core's job index completely: with
+ * `filter.limit === undefined` core sets `retain = matches`, so EVERY record in
+ * the shared, never-pruned, fleet-wide jobs dir is read, YAML-parsed and
+ * Zod-validated, then thrown away. Measured on a 2,016-record dir:
+ *
+ * | call | warm |
+ * |---|---|
+ * | `listJobs(dir)` + JS filter + slice | 1,935–2,095 ms |
+ * | `listJobs(dir, { agents, limit })` | 125–146 ms |
+ *
+ * That ~2 s was essentially the whole cost of `GET /triggers/runtime`, which the
+ * Triggers tab polls every 10 s.
+ *
+ * Both `agents` AND `limit` are load-bearing. `agents` alone still leaves
+ * `limit` undefined, so `retain = matches` and every match is hydrated anyway —
+ * the win comes from the pair. `limit <= 0` keeps its documented "no cap"
+ * meaning and is passed as no `limit`, which costs more but is still filtered.
+ *
+ * Requires `@herdctl/core` >= 5.28.0 (herdctl#418). On an older core `agents` is
+ * an unknown key and would be silently ignored, returning the newest `limit`
+ * records across ALL agents — hence the version floor in package.json rather
+ * than a defensive re-filter here, which would mask the mismatch.
  */
 export declare function listRunsForAgents(stateDir: string, agents: string[], limit?: number): Promise<JobMetadata[]>;
 /**

package/packages/server/dist/herdctl-jobs.js

@@ -124,19 +124,46 @@ export async function listProjectRuns(stateDir, project, limit = 100) {
  * the data source for the Triggers tab's per-trigger last-run column. Used to pull
  * one project's keeper AND every scoped `trigger-<slug>-<name>` agent in a single
  * pass so {@link import("./trigger-runtime.js").buildTriggerRuntime} can attribute a
- * scoped trigger's newest run by agent name. `listJobs` has no multi-agent filter,
- * so this scans the jobs dir once (unfiltered) and keeps only the requested agents;
- * order (started_at descending) is preserved. Errors swallow to `[]` so the runtime
- * view degrades to config-only rather than failing to render.
+ * scoped trigger's newest run by agent name. Order (started_at descending) is
+ * preserved. Errors swallow to `[]` so the runtime view degrades to config-only
+ * rather than failing to render.
+ *
+ * ## Why the filter is pushed down (#535)
+ *
+ * This used to call `listJobs(jobsDir)` with NEITHER filter nor limit, then
+ * filter and slice in JS — because `ListJobsFilter` had `agent` (exactly one)
+ * and no multi-agent form. That defeats core's job index completely: with
+ * `filter.limit === undefined` core sets `retain = matches`, so EVERY record in
+ * the shared, never-pruned, fleet-wide jobs dir is read, YAML-parsed and
+ * Zod-validated, then thrown away. Measured on a 2,016-record dir:
+ *
+ * | call | warm |
+ * |---|---|
+ * | `listJobs(dir)` + JS filter + slice | 1,935–2,095 ms |
+ * | `listJobs(dir, { agents, limit })` | 125–146 ms |
+ *
+ * That ~2 s was essentially the whole cost of `GET /triggers/runtime`, which the
+ * Triggers tab polls every 10 s.
+ *
+ * Both `agents` AND `limit` are load-bearing. `agents` alone still leaves
+ * `limit` undefined, so `retain = matches` and every match is hydrated anyway —
+ * the win comes from the pair. `limit <= 0` keeps its documented "no cap"
+ * meaning and is passed as no `limit`, which costs more but is still filtered.
+ *
+ * Requires `@herdctl/core` >= 5.28.0 (herdctl#418). On an older core `agents` is
+ * an unknown key and would be silently ignored, returning the newest `limit`
+ * records across ALL agents — hence the version floor in package.json rather
+ * than a defensive re-filter here, which would mask the mismatch.
  */
 export async function listRunsForAgents(stateDir, agents, limit = 200) {
     if (agents.length === 0)
         return [];
     const jobsDir = jobsDirOf(stateDir);
-    const wanted = new Set(agents);
-    const { jobs } = await listJobs(jobsDir).catch(() => ({ jobs: [], errors: 0 }));
-    const filtered = jobs.filter((j) => wanted.has(j.agent));
-    return limit > 0 ? filtered.slice(0, limit) : filtered;
+    // Core dedupes `agents` into a Set internally, so the caller's keeper +
+    // per-trigger list may repeat the keeper (unscoped schedule triggers run
+    // under it) exactly as it did when this deduped locally.
+    const { jobs } = await listJobs(jobsDir, limit > 0 ? { agents, limit } : { agents }).catch(() => ({ jobs: [], errors: 0 }));
+    return jobs;
 }
 /**
  * Delete every job record matching `match`, plus each one's sibling `.jsonl`

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

@@ -254,7 +254,7 @@ export const FIELDS = [
     { 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 },
+    { key: "selfMcpProjectsEnabled", group: "capabilities", label: "Self-management MCP (projects)", help: "Let keepers create new projects and promote existing ones — including a git clone of a repo URL the agent supplies (needs self-MCP write).", type: "boolean", envVars: ["PADDOCK_SELF_MCP_PROJECTS"], default: false, editable: true, coerce: asBool },
     { key: "maxSpawnDepth", group: "capabilities", label: "Max spawn depth", help: "How deep a spawn tree may grow before children lose the self-MCP.", type: "number", envVars: ["PADDOCK_MAX_SPAWN_DEPTH"], default: DEFAULT_MAX_SPAWN_DEPTH, editable: true, coerce: spawnDepth },
     { key: "scheduleMutationEnabled", group: "capabilities", label: "Schedule mutation", help: "Allow programmatic schedule add/remove at runtime.", type: "boolean", envVars: ["PADDOCK_SCHEDULE_MUTATION"], default: false, editable: true, coerce: asBool },
     { key: "hooksMcpEnabled", group: "capabilities", label: "Hooks MCP", help: "Let agents declare/edit their own event hooks (needs self-MCP write).", type: "boolean", envVars: ["PADDOCK_HOOKS_MCP"], default: false, editable: true, coerce: asBool },
@@ -264,7 +264,6 @@ export const FIELDS = [
     { key: "recovery.autoReDrive", group: "recovery", label: "Auto re-drive", type: "boolean", envVars: ["PADDOCK_RECOVERY_AUTODRIVE"], default: DEFAULT_RECOVERY.autoReDrive, editable: true, coerce: asBool },
     { key: "recovery.debounceMs", group: "recovery", label: "Debounce (ms)", type: "number", envVars: ["PADDOCK_RECOVERY_DEBOUNCE_MS"], default: DEFAULT_RECOVERY.debounceMs, editable: true, coerce: nonNegInt },
     { key: "recovery.maxRetries", group: "recovery", label: "Max retries", type: "number", envVars: ["PADDOCK_RECOVERY_MAX_RETRIES"], default: DEFAULT_RECOVERY.maxRetries, editable: true, coerce: nonNegInt },
-    { key: "recovery.limboTimeoutMs", group: "recovery", label: "Limbo timeout (ms)", type: "number", envVars: ["PADDOCK_RECOVERY_LIMBO_MS"], default: DEFAULT_RECOVERY.limboTimeoutMs, editable: true, coerce: nonNegInt },
     // Attachments (issue #328).
     { key: "attachments.enabled", group: "attachments", label: "Enabled", type: "boolean", envVars: ["PADDOCK_ATTACHMENTS_ENABLED"], default: DEFAULT_ATTACHMENTS.enabled, editable: true, coerce: asBool },
     { key: "attachments.maxFileSizeMb", group: "attachments", label: "Max file size (MB)", type: "number", envVars: ["PADDOCK_ATTACHMENTS_MAX_FILE_SIZE_MB"], default: DEFAULT_ATTACHMENTS.maxFileSizeMb, editable: true, coerce: posInt },

package/packages/server/dist/project-files.d.ts

@@ -33,8 +33,18 @@ import type { FileEntry, FileKind } from "./project-types.js";
  * reachable there either. This is worth closing because "hidden in the listing"
  * should not be the only thing standing between an API and a transcript, not
  * because it grants anything new.
+ *
+ * **`hiddenSegments: "allow"`** turns the dot-directory half off, leaving only
+ * containment (issue #710). It exists for exactly one caller: `/git/file`, which
+ * serves a file from the project's WORKING directory and has already checked
+ * that `git status` reports that path as untracked. A git-verified allowlist is
+ * strictly stronger than this heuristic — git never names `.git` and never names
+ * an ignored path — and the heuristic is actively wrong out there, because a new
+ * `.github/workflows/ci.yml` is an ordinary Changes-tab row that a dot-directory
+ * rule refuses to render. Every other caller keeps the default. Pass it only
+ * with an independent allowlist in hand.
  */
-export declare function resolveInProject(root: string, slug: string, name: string): string;
+export declare function resolveInProject(dir: string, name: string, hiddenSegments?: "refuse" | "allow"): string;
 /**
  * List one level of a project directory (issue #259). `subpath` is a
  * project-relative directory ("" = the project root); the returned entries
@@ -46,16 +56,16 @@ export declare function resolveInProject(root: string, slug: string, name: strin
  * doesn't exist and `ProjectError("not_directory")` when `subpath` is a file —
  * the latter lets the caller fall back to rendering that file.
  */
-export declare function listFiles(root: string, slug: string, subpath?: string): Promise<FileEntry[]>;
+export declare function listFiles(dir: string, subpath?: string): Promise<FileEntry[]>;
 /** Read a freeform file's contents as UTF-8 text (path-traversal guarded). */
-export declare function readProjectFile(root: string, slug: string, name: string): Promise<string>;
+export declare function readProjectFile(dir: string, name: string, hiddenSegments?: "refuse" | "allow"): Promise<string>;
 /**
  * Read a file's raw bytes + its MIME type (issue #61), for the binary/image
  * endpoint. Path-traversal guarded; throws ProjectError("not_found") if the
  * file is missing so the route can 404 cleanly. NOT decoded as text, so binary
- * (image) bytes survive intact.
+ * (image) bytes survive intact. See {@link resolveInProject} for `hiddenSegments`.
  */
-export declare function readFileBytes(root: string, slug: string, name: string): Promise<{
+export declare function readFileBytes(dir: string, name: string, hiddenSegments?: "refuse" | "allow"): Promise<{
     bytes: Buffer;
     mime: string;
 }>;
@@ -67,9 +77,10 @@ export declare function readFileBytes(root: string, slug: string, name: string):
  * For an IMAGE the raw bytes are NOT returned here (decoding binary as UTF-8
  * would mangle it): `content` is empty and the client fetches the bytes from
  * the raw endpoint. We still stat the file so a missing image 404s. Path-
- * traversal guarded; throws ProjectError("not_found") when missing.
+ * traversal guarded; throws ProjectError("not_found") when missing. See
+ * {@link resolveInProject} for `hiddenSegments`.
  */
-export declare function readFileWithKind(root: string, slug: string, name: string): Promise<{
+export declare function readFileWithKind(dir: string, name: string, hiddenSegments?: "refuse" | "allow"): Promise<{
     name: string;
     kind: FileKind;
     content: string;