@edspencer/paddock 0.70.0 → 0.71.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@edspencer/paddock",
-  "version": "0.70.0",
+  "version": "0.71.0",
   "description": "Project-first launchpad for Claude Code: server-hosted, persistent, resumable sessions organized by project.",
   "keywords": [
     "claude",
@@ -37,7 +37,7 @@
     "@fastify/swagger-ui": "4.2.0",
     "@fastify/websocket": "10.0.1",
     "@herdctl/chat": "0.8.0",
-    "@herdctl/core": "5.32.0",
+    "@herdctl/core": "5.33.0",
     "@modelcontextprotocol/sdk": "1.29.0",
     "fastify": "4.28.1",
     "jose": "6.2.3",

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`. */
@@ -70,6 +78,14 @@ export interface LiveBackgroundTask {
      * carried on the wire and filtered at the point of display.
      */
     skipTranscript?: boolean;
+    /**
+     * Can this task be stopped (#848)? Derived from {@link type} alongside
+     * {@link role}, at the one boundary that owns SDK task-type knowledge — see
+     * {@link UNSTOPPABLE_TASK_TYPES}. Clients gate the stop affordance on this
+     * rather than re-deriving it, so the CLI's kill-strategy table has exactly
+     * one representation in the codebase.
+     */
+    stoppable: boolean;
 }
 export type BackgroundChangeListener = (projectSlug: string, sessionId: string, tasks: LiveBackgroundTask[]) => void;
 /**
@@ -99,6 +115,22 @@ export declare class BackgroundRegistry {
      * stream ends — see the per-process caveat in the module header.
      */
     clear(sessionId: string): void;
+    /**
+     * Drop one task the way a terminal edge would, on the word of an out-of-band
+     * authority rather than the session's own stream (#848).
+     *
+     * The single caller is the stop path, for the case where
+     * `stopTaskInSession` answers `false` — no live session with that id. There
+     * is then no stream left to deliver the `task_notification` this registry
+     * normally evicts on, so without this the row would sit at `stopping…`
+     * forever describing work that is definitively gone.
+     *
+     * Safe against being wrong for the same reason {@link evict} is: the level
+     * signal remains the sole authority on membership, so a task dropped here
+     * that is somehow still running is simply put back by the next
+     * `background_tasks_changed`.
+     */
+    dropTask(sessionId: string, taskId: string): boolean;
     /**
      * Feed one raw SDK message. Returns true when the live set changed, so the
      * caller can avoid re-broadcasting on the overwhelming majority of messages

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

@@ -37,6 +37,63 @@
  */
 /** 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;
+}
+/**
+ * Task types the CLI has no kill strategy for, so `stopTask` on one REJECTS
+ * with `unsupported_type` rather than being swallowed (#848).
+ *
+ * Keyed on the RAW discriminant, and {@link TASK_ROLES} directly above is the
+ * proof that it has to be: that map sends BOTH `monitor_mcp` and `monitor_ws`
+ * to the same `monitor` role, and only the MCP flavour is unkillable. A
+ * consumer holding the derived `role` therefore cannot tell the stoppable one
+ * from the unstoppable one — so the answer is resolved here, next to the map
+ * that erases the distinction, and carried on the wire as `stoppable`.
+ *
+ * A DENYLIST, not an allowlist, and deliberately so: a task type the SDK adds
+ * after this was written gets a stop button, and if the CLI turns out not to
+ * support it the rejection surfaces in the row as "can't stop". An allowlist
+ * would silently withhold the button from every new stoppable type instead,
+ * which is the worse failure — the whole point of the issue is that there was
+ * nothing to click.
+ */
+const UNSTOPPABLE_TASK_TYPES = new Set(["monitor_mcp"]);
 const str = (v) => (typeof v === "string" && v ? v : undefined);
 const num = (v) => (typeof v === "number" && Number.isFinite(v) ? v : undefined);
 /**
@@ -96,6 +153,24 @@ export class BackgroundRegistry {
         e.tasks.clear();
         this.emit(sessionId, e);
     }
+    /**
+     * Drop one task the way a terminal edge would, on the word of an out-of-band
+     * authority rather than the session's own stream (#848).
+     *
+     * The single caller is the stop path, for the case where
+     * `stopTaskInSession` answers `false` — no live session with that id. There
+     * is then no stream left to deliver the `task_notification` this registry
+     * normally evicts on, so without this the row would sit at `stopping…`
+     * forever describing work that is definitively gone.
+     *
+     * Safe against being wrong for the same reason {@link evict} is: the level
+     * signal remains the sole authority on membership, so a task dropped here
+     * that is somehow still running is simply put back by the next
+     * `background_tasks_changed`.
+     */
+    dropTask(sessionId, taskId) {
+        return this.evict(sessionId, taskId);
+    }
     /**
      * Feed one raw SDK message. Returns true when the live set changed, so the
      * caller can avoid re-broadcasting on the overwhelming majority of messages
@@ -159,12 +234,15 @@ 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(),
+                stoppable: !UNSTOPPABLE_TASK_TYPES.has(type),
             });
         }
         if (prev && sameSet(prev.tasks, next)) {

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

@@ -71,8 +71,16 @@ export type Command = {
  *   `paddock service install --port 7299` both work, and the flag grammar is
  *   the same one in every position.
  *
- * A verb is only a verb in first position: `paddock --port start` is still a
- * missing-value error, and `paddock start start` is still `unknown option`.
+ * A verb is only a verb in first position: `paddock --port start` is an error
+ * from `--port`, not a `start` invocation, and `paddock start start` is still
+ * `unknown option`.
+ *
+ * That first half used to claim a *missing-value* error, which was wrong (#823):
+ * `next()` only rejects `undefined`, so `start` was happily consumed as the port
+ * and became `NaN` in `config.ts`. It is now a **value** error — `--port needs a
+ * number between 1 and 65535` — which is the behaviour the claim was reaching
+ * for. Corrected rather than deleted because the grammar it documents is real
+ * and load-bearing; it was only the example's error that was misdescribed.
  */
 export declare function parseCommand(argv: string[]): Command;
 export declare function parseArgs(argv: string[]): CliOptions;
@@ -92,4 +100,4 @@ export declare function nodeVersionProblem(nodeVersion: string): string | undefi
  */
 export declare function explainListenError(err: unknown, host: string, port: string): string;
 export declare const USAGE = "paddock \u2014 run a Paddock instance locally\n\nUsage\n  npx @edspencer/paddock [options]        start the server (the default)\n  paddock start [options]                 the same thing, said out loud\n  paddock service <install|uninstall|status>\n                                          run it in the background from login\n                                          (`paddock service --help`)\n\nOptions\n  -p, --port <port>       HTTP/WS port (default 7233, or $PORT)\n      --host <host>       Bind address (default 127.0.0.1)\n  -d, --data-dir <path>   Projects + state (default ~/.paddock, or $PADDOCK_DATA_DIR)\n  -o, --open              Open the app in your browser once it is listening\n      --verbose           Show the server's own logs (quiet by default)\n  -v, --version           Print the Paddock version and exit\n  -h, --help              Show this help\n\nOpening your own directories\n  Where you run this from does not matter \u2014 the instance is decided by its data\n  dir alone. Directories are added inside the app, on the Discover screen: it\n  reads your Claude Code history, lists the directories you have worked in, and\n  links the ones you tick as projects. A new instance opens on it.\n\n  Importing a directory does not write into it. No .paddock/, no .chats/, no\n  .gitignore edits, no CLAUDE.md \u2014 the project record and the copied transcripts\n  both live in the data dir, and the project just points at the path. Your own\n  ~/.claude transcripts are copied, never moved or deleted, so your terminal\n  `claude` keeps working exactly as before.\n\nCredentials\n  Paddock drives Claude Code, so it needs Claude credentials \u2014 and if you\n  already use Claude Code on this machine, it uses the login you already have.\n  That is a macOS Keychain entry on a Mac, or your ~/.claude/.credentials.json\n  elsewhere (symlinked in, never copied). Reading a login writes nothing.\n\n  Otherwise: a CLAUDE_CODE_OAUTH_TOKEN or ANTHROPIC_API_KEY in the environment,\n  or a one-off `CLAUDE_CONFIG_DIR=<data-dir>/claude-home claude login`. With no\n  login at all anywhere, run `claude setup-token`. Paddock says at startup when\n  it can find none.\n\nSharing your Claude Code state\n  Apart from that login, Paddock writes nothing outside its data dir by\n  default: transcripts go to each project's .chats/, and your ~/.claude is read\n  for config only. Each thing it can share is one key in\n  <data-dir>/paddock.config.yaml:\n\n    claude:\n      transcripts: host   # own | host, default own\n      credentials: host   # own | host, default host\n      instructions: host  # own | host, default own\n      hooks: host         # own | host, default own\n      mcpServers: host    # own | host, default own\n\n  transcripts: host makes a chat and a `claude --resume` in the same directory\n  the same file, live in both directions; deleting such a chat in Paddock\n  releases it rather than removing it, because it is your history rather than\n  Paddock's copy. credentials: own is the opt-out from sharing the login above.\n\n  instructions: host loads your ~/.claude CLAUDE.md, agents/, commands/ and\n  plugins/. Off by default, which is a change: your curated CLAUDE.md does not\n  reach Paddock's agents unless you say so. Each project's own CLAUDE.md always\n  does.\n\n  hooks: host runs the shell commands your ~/.claude/settings.json binds to\n  tool use. Off by default \u2014 inheriting someone's hooks is not something to\n  discover after the fact. Its other keys (permissions, model, statusline)\n  apply either way: under hooks: own Paddock writes its own settings.json\n  carrying them with hooks dropped, regenerated at startup.\n\n  mcpServers: host attaches the MCP servers declared in your ~/.claude.json \u2014\n  the top-level ones, plus a project's own when its directory matches. To give\n  this instance a server your machine doesn't have, declare it instead in a\n  sibling mcpServers: block of the same file; use env:VAR_NAME anywhere a\n  string goes so tokens stay out of it. That keeps a token out of the file, not\n  out of `ps`: leave driveMode on its default (session) for a server holding\n  one, since batch passes the definition to claude as a command-line argument.\n\nYour data\n  Everything lives in one directory \u2014 ~/.paddock unless you pass --data-dir.\n  Projects, chat transcripts and settings all persist there between runs. Move\n  that directory to move your instance; delete it to start over. Nothing is\n  stored anywhere else.\n\nNotes\n  Binds loopback with authentication disabled, which is safe for a laptop. To\n  expose it on a network, set PADDOCK_AUTH_MODE first \u2014 Paddock refuses to bind\n  a routable interface wide open. See AUTH.md.\n\nDocs: https://github.com/edspencer/paddock";
-export declare const SERVICE_USAGE = "paddock service \u2014 keep Paddock running in the background\n\nUsage\n  paddock service install [options]   register it and start it now\n  paddock service uninstall           stop it and deregister it\n  paddock service status              is it registered, is it running, where are the logs\n\nOptions (install only \u2014 recorded in the generated unit)\n  -p, --port <port>       HTTP/WS port (default 7233)\n      --host <host>       Bind address (default 127.0.0.1)\n  -d, --data-dir <path>   Only if you want an instance SEPARATE from your\n                          terminal one. Omitted by default on purpose, so\n                          `paddock service` and a bare `paddock` are the same\n                          ~/.paddock instance reached two ways.\n      --verbose           Record the server's own logs, not just warnings\n\nAt login, not at boot\n  This registers a per-USER service \u2014 a launchd LaunchAgent on macOS, a\n  `systemd --user` unit on Linux \u2014 so it runs as you, with your own Claude\n  login. That is not incidental: on macOS your Claude login is a Keychain item\n  that only a logged-in user session can read. A boot-time system daemon has no\n  such session and could not use it.\n\n  So Paddock starts when you LOG IN, not when the machine boots. After a\n  restart that nobody logs into, Paddock is not running. That is the design, not\n  a fault.\n\n  On Linux, a user service is also stopped when you log out. To keep it up:\n\n    loginctl enable-linger $USER\n\nWhere it lives\n  macOS   ~/Library/LaunchAgents/net.edspencer.paddock.plist\n          logs in <data-dir>/service/\n  Linux   ~/.config/systemd/user/paddock.service\n          logs via  journalctl --user -u paddock -f\n\nInstalled from npx?\n  `service install` refuses. An npx cache path is hash-keyed and npm may prune\n  it, so the unit would work until it silently didn't, at some future login.\n  Install properly first:\n\n    npm i -g @edspencer/paddock && paddock service install\n\nA note on access\n  Paddock binds loopback with authentication off, which is right for a laptop.\n  A service is up for as long as you are logged in rather than as long as a\n  terminal tab, so that window is longer \u2014 but it is not wider: any local\n  process that could reach the port could already read the same Claude login as\n  you. Set PADDOCK_AUTH_MODE if you want a credential on it anyway.\n\nDocs: https://github.com/edspencer/paddock";
+export declare const SERVICE_USAGE = "paddock service \u2014 keep Paddock running in the background\n\nUsage\n  paddock service install [options]   register it and start it now\n  paddock service uninstall           stop it and deregister it\n  paddock service status              is it registered, is it running, where are the logs\n\nOptions (install only \u2014 recorded in the generated unit)\n  -p, --port <port>       HTTP/WS port (default 7233)\n      --host <host>       Bind address (default 127.0.0.1)\n  -d, --data-dir <path>   Only if you want an instance SEPARATE from your\n                          terminal one. Left out of the unit when you omit it\n                          AND `PADDOCK_DATA_DIR` is unset in this shell, so\n                          `paddock service` and a bare `paddock` are the same\n                          ~/.paddock instance reached two ways. If\n                          `PADDOCK_DATA_DIR` IS set here, that path is recorded\n                          in the unit \u2014 the service would otherwise point\n                          somewhere your terminal does not.\n      --verbose           Record the server's own logs, not just warnings\n\nAt login, not at boot\n  This registers a per-USER service \u2014 a launchd LaunchAgent on macOS, a\n  `systemd --user` unit on Linux \u2014 so it runs as you, with your own Claude\n  login. That is not incidental: on macOS your Claude login is a Keychain item\n  that only a logged-in user session can read. A boot-time system daemon has no\n  such session and could not use it.\n\n  So Paddock starts when you LOG IN, not when the machine boots. After a\n  restart that nobody logs into, Paddock is not running. That is the design, not\n  a fault.\n\n  On Linux, a user service is also stopped when you log out. To keep it up:\n\n    loginctl enable-linger $USER\n\nWhere it lives\n  macOS   ~/Library/LaunchAgents/net.edspencer.paddock.plist\n          logs in <data-dir>/service/\n  Linux   ~/.config/systemd/user/paddock.service\n          logs via  journalctl --user -u paddock.service -f\n\nInstalled from npx?\n  `service install` refuses. An npx cache path is hash-keyed and npm may prune\n  it, so the unit would work until it silently didn't, at some future login.\n  Install properly first:\n\n    npm i -g @edspencer/paddock && paddock service install\n\nA note on access\n  Paddock binds loopback with authentication off, which is right for a laptop.\n  A service is up for as long as you are logged in rather than as long as a\n  terminal tab, so that window is longer \u2014 but it is not wider: any local\n  process that could reach the port could already read the same Claude login as\n  you. Set PADDOCK_AUTH_MODE if you want a credential on it anyway.\n\nDocs: https://github.com/edspencer/paddock";

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

@@ -49,8 +49,16 @@ function isServiceAction(token) {
  *   `paddock service install --port 7299` both work, and the flag grammar is
  *   the same one in every position.
  *
- * A verb is only a verb in first position: `paddock --port start` is still a
- * missing-value error, and `paddock start start` is still `unknown option`.
+ * A verb is only a verb in first position: `paddock --port start` is an error
+ * from `--port`, not a `start` invocation, and `paddock start start` is still
+ * `unknown option`.
+ *
+ * That first half used to claim a *missing-value* error, which was wrong (#823):
+ * `next()` only rejects `undefined`, so `start` was happily consumed as the port
+ * and became `NaN` in `config.ts`. It is now a **value** error — `--port needs a
+ * number between 1 and 65535` — which is the behaviour the claim was reaching
+ * for. Corrected rather than deleted because the grammar it documents is real
+ * and load-bearing; it was only the example's error that was misdescribed.
  */
 export function parseCommand(argv) {
     const [first, ...rest] = argv;
@@ -96,9 +104,23 @@ export function parseArgs(argv) {
         };
         switch (arg) {
             case "-p":
-            case "--port":
-                opts.port = next();
+            case "--port": {
+                // Validate here rather than letting `Number("start")` become NaN three
+                // files later, in `config.ts`, with nothing between the typo and a
+                // server asked to listen on NaN (#823).
+                //
+                // Scoped to NON-EMPTY values on purpose. `paddock --port "$PORT"` with
+                // PORT unset passes `""`, which is falsy at the one place that reads it
+                // (`paddock.ts`: `if (opts.port)`) and so correctly falls through to the
+                // default — a working invocation that a bare `/^\d+$/` guard would turn
+                // into a hard error.
+                const v = next();
+                if (v !== "" && (!/^\d+$/.test(v) || Number(v) < 1 || Number(v) > 65535)) {
+                    throw new CliError(`${arg} needs a number between 1 and 65535, got: ${v}`);
+                }
+                opts.port = v;
                 break;
+            }
             case "--host":
                 opts.host = next();
                 break;
@@ -261,9 +283,13 @@ Options (install only — recorded in the generated unit)
   -p, --port <port>       HTTP/WS port (default 7233)
       --host <host>       Bind address (default 127.0.0.1)
   -d, --data-dir <path>   Only if you want an instance SEPARATE from your
-                          terminal one. Omitted by default on purpose, so
+                          terminal one. Left out of the unit when you omit it
+                          AND \`PADDOCK_DATA_DIR\` is unset in this shell, so
                           \`paddock service\` and a bare \`paddock\` are the same
-                          ~/.paddock instance reached two ways.
+                          ~/.paddock instance reached two ways. If
+                          \`PADDOCK_DATA_DIR\` IS set here, that path is recorded
+                          in the unit — the service would otherwise point
+                          somewhere your terminal does not.
       --verbose           Record the server's own logs, not just warnings
 
 At login, not at boot
@@ -285,7 +311,7 @@ Where it lives
   macOS   ~/Library/LaunchAgents/net.edspencer.paddock.plist
           logs in <data-dir>/service/
   Linux   ~/.config/systemd/user/paddock.service
-          logs via  journalctl --user -u paddock -f
+          logs via  journalctl --user -u paddock.service -f
 
 Installed from npx?
   \`service install\` refuses. An npx cache path is hash-keyed and npm may prune

package/packages/server/dist/cli/service/index.js

@@ -130,7 +130,18 @@ function status(opts, ctx, backend) {
     const dataDir = dataFromUnit >= 0 && state.argv[dataFromUnit + 1] !== undefined
         ? state.argv[dataFromUnit + 1]
         : defaultDataDir(ctx.homeDir);
-    const { spec } = specFor(opts, { ...ctx, envDataDir: dataDir });
+    // Drop `--data-dir` before building the log-path spec (#824). `resolveDataDir`
+    // gives `opts.dataDir` precedence over `ctx.envDataDir`, which is right for
+    // `install` (see the comment there) and wrong here: this whole block reports
+    // the INSTALLED unit, so letting today's flag through printed the unit's data
+    // dir beside a `Logs:` path under a directory the service never writes to. On
+    // macOS that log path is real and load-bearing, not just cosmetic.
+    //
+    // `--data-dir` is documented as install-only (SERVICE_USAGE), so ignoring it
+    // here matches both the help text and the stated intent of this block.
+    const statusOpts = { ...opts };
+    delete statusOpts.dataDir;
+    const { spec } = specFor(statusOpts, { ...ctx, envDataDir: dataDir });
     const linger = backend.lingerNote();
     console.log([
         "",

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[]>;
 /**