@edspencer/paddock 0.70.0 → 0.71.0

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/herdctl.d.ts

@@ -79,6 +79,26 @@ export interface ChatDeletion {
     /** The transcript was deliberately left on disk because it is not paddock's. */
     retained: boolean;
 }
+/**
+ * What happened to a request to stop one background task (#848).
+ *
+ * Three cases, kept apart on purpose — see
+ * {@link HerdctlService.stopBackgroundTask} for why only `error` is a failure.
+ */
+export type StopTaskOutcome = 
+/** Accepted. The SDK's own terminal notification is what removes the row. */
+{
+    outcome: "stopping";
+}
+/** No live session — the work died with it. The caller drops the row. */
+ | {
+    outcome: "gone";
+}
+/** The stop did not happen and the task is still running. */
+ | {
+    outcome: "error";
+    message: string;
+};
 /** Options passed through to a streamed trigger. */
 export interface ChatTurnOptions {
     prompt: string;
@@ -768,6 +788,35 @@ export declare class HerdctlService {
      * failure, so a broken Stop looked like a no-op).
      */
     cancel(jobId: string): Promise<boolean>;
+    /**
+     * Stop ONE background task, by session id and SDK task id (issue #848).
+     *
+     * Deliberately keyed on the SESSION, not on {@link liveSessions}. That map is
+     * emptied in a `finally` the moment the primary turn's result lands, while the
+     * background tasks it launched keep running — so a `liveSessions`-keyed stop
+     * would go inert during exactly the phase the running-work bar exists for.
+     * `stopTaskInSession` is herdctl's answer to that gap: the reaper holds the
+     * session across it.
+     *
+     * There is deliberately NO liveness pre-check. A reap landing between render
+     * and click is a routine race, and `false` already describes it precisely.
+     *
+     * The three outcomes are kept DISTINCT all the way to the UI, because they
+     * mean genuinely different things and only one of them is a failure:
+     *
+     *  - `stopping` — the request was accepted. Nothing is evicted here: the SDK
+     *    emits the terminal `task_notification{status:"stopped"}` on the session's
+     *    own stream and {@link BackgroundRegistry} already evicts on it. This is
+     *    also the idempotent case — the CLI answers `not_found` / `not_running`
+     *    with a success, so a click racing a natural completion lands here.
+     *  - `gone` — no live session with that id. NOT a failure: the tasks died with
+     *    the session, so the user's intent is already satisfied. The caller drops
+     *    the row itself, because there is no stream left to notify on.
+     *  - `error` — the stop did NOT happen and the task is still running. Notably
+     *    a `monitor_mcp` task, which the CLI has no kill strategy for and rejects
+     *    with `unsupported_type`. Surfaced rather than reported as success.
+     */
+    stopBackgroundTask(sessionId: string, taskId: string): Promise<StopTaskOutcome>;
     /**
      * End a managed chat SESSION outright, by session id (issue #731). Where
      * {@link cancel} ends the model turn — and on the session runtime deliberately

package/packages/server/dist/herdctl.js

@@ -1397,6 +1397,48 @@ export class HerdctlService {
             return false;
         }
     }
+    /**
+     * Stop ONE background task, by session id and SDK task id (issue #848).
+     *
+     * Deliberately keyed on the SESSION, not on {@link liveSessions}. That map is
+     * emptied in a `finally` the moment the primary turn's result lands, while the
+     * background tasks it launched keep running — so a `liveSessions`-keyed stop
+     * would go inert during exactly the phase the running-work bar exists for.
+     * `stopTaskInSession` is herdctl's answer to that gap: the reaper holds the
+     * session across it.
+     *
+     * There is deliberately NO liveness pre-check. A reap landing between render
+     * and click is a routine race, and `false` already describes it precisely.
+     *
+     * The three outcomes are kept DISTINCT all the way to the UI, because they
+     * mean genuinely different things and only one of them is a failure:
+     *
+     *  - `stopping` — the request was accepted. Nothing is evicted here: the SDK
+     *    emits the terminal `task_notification{status:"stopped"}` on the session's
+     *    own stream and {@link BackgroundRegistry} already evicts on it. This is
+     *    also the idempotent case — the CLI answers `not_found` / `not_running`
+     *    with a success, so a click racing a natural completion lands here.
+     *  - `gone` — no live session with that id. NOT a failure: the tasks died with
+     *    the session, so the user's intent is already satisfied. The caller drops
+     *    the row itself, because there is no stream left to notify on.
+     *  - `error` — the stop did NOT happen and the task is still running. Notably
+     *    a `monitor_mcp` task, which the CLI has no kill strategy for and rejects
+     *    with `unsupported_type`. Surfaced rather than reported as success.
+     */
+    async stopBackgroundTask(sessionId, taskId) {
+        const fleet = this.fleet;
+        if (!fleet)
+            return { outcome: "gone" };
+        try {
+            const stopped = await fleet.stopTaskInSession(sessionId, taskId);
+            return stopped ? { outcome: "stopping" } : { outcome: "gone" };
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            console.warn(`[herdctl] stopTaskInSession failed for ${sessionId}/${taskId}:`, err);
+            return { outcome: "error", message };
+        }
+    }
     /**
      * End a managed chat SESSION outright, by session id (issue #731). Where
      * {@link cancel} ends the model turn — and on the session runtime deliberately

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;

package/packages/server/dist/project-files.js

@@ -3,31 +3,23 @@
  *
  * Extracted from projects.ts (issue #403): the path-traversal guard plus the
  * directory listing + file readers (text / raw bytes / kind-hinted). Pure free
- * functions taking `(root, slug, …)` — no `ProjectStore` state beyond the
- * projects root — so `ProjectStore` keeps thin delegate methods over these and
- * the public API is unchanged. `ProjectError` codes are preserved exactly.
+ * functions taking `(dir, …)` — no `ProjectStore` state at all — so
+ * `ProjectStore` keeps thin delegate methods over these and the public API is
+ * unchanged. `ProjectError` codes are preserved exactly.
+ *
+ * **`dir` is the project's CONTENT dir, not `projectsRoot/<slug>`** (issue #710).
+ * These used to take `(root, slug)` and re-derive the directory by joining, which
+ * was right only while a project's content lived under the projects root. A
+ * MANAGED project with a `path:` (issue #206) keeps its curated trio out at that
+ * path, so the join addressed a directory holding nothing but `project.yaml` and
+ * the whole Files tab came back empty. Taking the directory the caller already
+ * resolved removes the second copy of that resolution rather than teaching it a
+ * new case — see {@link import("./project-paths.js").contentDirFor}.
  */
 import { promises as fs } from "node:fs";
 import path from "node:path";
 import { ProjectError } from "./project-paths.js";
 import { fileKind, contentTypeFor } from "./project-mime.js";
-/**
- * The directory backing a workspace key — a second copy of
- * `ProjectStore.dirFor`'s resolution, kept in step by being the same one-liner.
- *
- * A key is a path relative to the projects root and the root workspace's key is
- * `""`, so `path.join` handles both with no branch. That matters historically:
- * the previous design DID need a branch here for a reserved slug, this copy was
- * missed, and every root file route 404'd until it was found in live QA. There
- * is no longer a branch to miss.
- *
- * The traversal guard below is unaffected: it compares against whatever this
- * returns, so at the root "inside the workspace dir" means "inside the projects
- * root" — exactly the scope of a keeper whose cwd is that directory.
- */
-function dirFor(root, key) {
-    return path.join(root, key);
-}
 /**
  * Resolve a freeform file name to an absolute path inside the project dir,
  * rejecting path traversal AND traversal *through* a hidden (dot-prefixed)
@@ -62,13 +54,24 @@ function dirFor(root, key) {
  * 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 function resolveInProject(root, slug, name) {
-    const dir = dirFor(root, slug);
+export function resolveInProject(dir, name, hiddenSegments = "refuse") {
     const resolved = path.resolve(dir, name);
     if (resolved !== dir && !resolved.startsWith(dir + path.sep)) {
         throw new ProjectError("Invalid file path", "invalid");
     }
+    if (hiddenSegments === "allow")
+        return resolved;
     // Check the RESOLVED path's segments relative to the project dir, not the
     // caller's raw string: `a/./.git/config` and `a/../.git/config` both normalise
     // to a hidden directory segment the raw string doesn't literally contain. The
@@ -100,11 +103,11 @@ function isHidden(segment) {
  * doesn't exist and `ProjectError("not_directory")` when `subpath` is a file —
  * the latter lets the caller fall back to rendering that file.
  */
-export async function listFiles(root, slug, subpath = "") {
-    const target = resolveInProject(root, slug, subpath);
+export async function listFiles(dir, subpath = "") {
+    const target = resolveInProject(dir, subpath);
     // A LISTING target is a directory, so unlike a read the leaf gets no pass:
     // `?path=.chats` is exactly how every transcript filename was enumerable.
-    const leaf = relSegments(dirFor(root, slug), target).at(-1);
+    const leaf = relSegments(dir, target).at(-1);
     if (leaf && isHidden(leaf)) {
         throw new ProjectError("Invalid file path", "invalid");
     }
@@ -126,17 +129,17 @@ export async function listFiles(root, slug, subpath = "") {
         .sort((a, b) => a.kind === b.kind ? a.name.localeCompare(b.name) : a.kind === "dir" ? -1 : 1);
 }
 /** Read a freeform file's contents as UTF-8 text (path-traversal guarded). */
-export async function readProjectFile(root, slug, name) {
-    return fs.readFile(resolveInProject(root, slug, name), "utf8");
+export async function readProjectFile(dir, name, hiddenSegments = "refuse") {
+    return fs.readFile(resolveInProject(dir, name, hiddenSegments), "utf8");
 }
 /**
  * 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 async function readFileBytes(root, slug, name) {
-    const resolved = resolveInProject(root, slug, name);
+export async function readFileBytes(dir, name, hiddenSegments = "refuse") {
+    const resolved = resolveInProject(dir, name, hiddenSegments);
     try {
         const bytes = await fs.readFile(resolved);
         return { bytes, mime: contentTypeFor(name) };
@@ -156,14 +159,15 @@ export async function readFileBytes(root, slug, name) {
  * 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 async function readFileWithKind(root, slug, name) {
+export async function readFileWithKind(dir, name, hiddenSegments = "refuse") {
     const kind = fileKind(name);
     if (kind === "image") {
         // Existence check only — the bytes go over the raw endpoint.
         try {
-            await fs.stat(resolveInProject(root, slug, name));
+            await fs.stat(resolveInProject(dir, name, hiddenSegments));
         }
         catch (err) {
             if (err instanceof ProjectError)
@@ -177,7 +181,7 @@ export async function readFileWithKind(root, slug, name) {
     }
     let content;
     try {
-        content = await readProjectFile(root, slug, name);
+        content = await readProjectFile(dir, name, hiddenSegments);
     }
     catch (err) {
         if (err instanceof ProjectError)

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

@@ -311,7 +311,7 @@ export declare class ProjectStore {
      */
     writeChangelog(slug: string, body: string): Promise<void>;
     /**
-     * List one level of a project directory (issue #259). See
+     * List one level of a project's content directory (issue #259). See
      * {@link import("./project-files.js").listFiles}.
      */
     listFiles(slug: string, subpath?: string): Promise<FileEntry[]>;

package/packages/server/dist/projects.js

@@ -1066,32 +1066,39 @@ export class ProjectStore {
         await fs.writeFile(file, `${title}\n\n${withoutTitle.trim()}\n`, "utf8");
     }
     // --- freeform file serving (delegated to project-files.ts, issue #403) ---
-    // Thin wrappers over the pure `(root, slug, …)` helpers so `ProjectStore`'s
-    // public file-read API (and its ProjectError codes) is unchanged.
+    // Thin wrappers over the pure `(dir, …)` helpers so `ProjectStore`'s public
+    // file-read API (and its ProjectError codes) is unchanged.
+    //
+    // Every one of them browses the project's CONTENT dir (issue #710). That is
+    // the metadata dir for a notebook and for any UNMANAGED project — unchanged —
+    // but for a MANAGED project with a `path:` (issue #206) the curated trio lives
+    // out at that path, and joining `root + slug` addressed a directory holding
+    // only `project.yaml`, so the Files tab listed nothing and every note 404'd.
+    // `contentDirOf` is the single resolution both this and the sweeper use.
     /**
-     * List one level of a project directory (issue #259). See
+     * List one level of a project's content directory (issue #259). See
      * {@link import("./project-files.js").listFiles}.
      */
     async listFiles(slug, subpath = "") {
-        return projectFiles.listFiles(this.root, slug, subpath);
+        return projectFiles.listFiles(await this.contentDirOf(slug), subpath);
     }
     /** Read a freeform file's contents as UTF-8 text (path-traversal guarded). */
     async readFile(slug, name) {
-        return projectFiles.readProjectFile(this.root, slug, name);
+        return projectFiles.readProjectFile(await this.contentDirOf(slug), name);
     }
     /**
      * Read a file's raw bytes + its MIME type (issue #61), for the binary/image
      * endpoint. See {@link import("./project-files.js").readFileBytes}.
      */
     async readFileBytes(slug, name) {
-        return projectFiles.readFileBytes(this.root, slug, name);
+        return projectFiles.readFileBytes(await this.contentDirOf(slug), name);
     }
     /**
      * Read a file plus a render-kind hint derived from its extension (issues #3 /
      * #61). See {@link import("./project-files.js").readFileWithKind}.
      */
     async readFileWithKind(slug, name) {
-        return projectFiles.readFileWithKind(this.root, slug, name);
+        return projectFiles.readFileWithKind(await this.contentDirOf(slug), name);
     }
     // --- internals ---------------------------------------------------------
     /**

package/packages/server/dist/routes/chats.js

@@ -1436,8 +1436,8 @@ export function registerChatWorkspaceRoutes(app, ctx) {
     app.get("/adoptable-chats", {
         schema: {
             tags: ["Chats"],
-            summary: "Count the native Claude Code chats this project could import",
-            description: "Returns the terminal `claude` sessions that could be imported into this project but are not yet visible in it: the project's own working directory, plus any Claude transcript folder whose recorded working directory matches the project (by checkout name for a repo-backed project, by exact path for a notebook project). Sidechains, already-imported sessions and sessions belonging to a real Paddock run are excluded by the engine; empty transcripts, slash-command-only transcripts and Paddock's own sweeper curation runs (`too-small` / `slash-command-only` / `sweeper-run`) are additionally withheld as noise and reported under `filtered`, so a count lower than the raw total always has an explanation. Response: `{ count, sources: [{ sourceCwd, sessionIds }], filtered: [{ sessionId, sourceCwd, reason }] }`. The count is LIVE — re-read it after an import rather than remembering a dismissal.",
+            summary: "Count the native Claude Code chats this project could adopt",
+            description: "Returns the terminal `claude` sessions that could be adopted into this project but are not yet visible in it: the project's own working directory, plus any Claude transcript folder whose recorded working directory matches the project (by checkout name when the project has a `repo:` key, by exact path otherwise). Sidechains, already-adopted sessions and sessions belonging to a real Paddock run are excluded by the engine; empty transcripts, slash-command-only transcripts and Paddock's own sweeper curation runs (`too-small` / `slash-command-only` / `sweeper-run`) are additionally withheld as noise and reported under `filtered`, so a count lower than the raw total always has an explanation. Response: `{ count, sources: [{ sourceCwd, sessionIds }], filtered: [{ sessionId, sourceCwd, reason }] }`. The count is LIVE — re-read it after an adoption rather than remembering a dismissal.",
             params: {
                 type: "object",
                 properties: {
@@ -1474,8 +1474,8 @@ export function registerChatWorkspaceRoutes(app, ctx) {
     app.post("/adopt-chats", {
         schema: {
             tags: ["Chats"],
-            summary: "Import native Claude Code chats into this project",
-            description: "Imports the terminal `claude` sessions reported by GET …/adoptable-chats. With no body (or no `sourceCwd`) every detected source is imported; with `sourceCwd` only that source is, and it must be one this project actually offers — an unrecognised path is a 400 rather than an invitation to scan arbitrary directories. `sessionIds` narrows the import to a chosen SUBSET of what is on offer (what the confirmation dialog sends); ids that are not on offer are simply not imported, and anything the engine adopts as a side effect of taking a whole source is released again. Transcripts are COPIED, never moved: the user's own `~/.claude` history is left intact and the copies keep their original mtimes, so imported chats sort by when they really happened. Afterwards the session, run-record and detection caches are dropped, so the chats appear on the very next list request with no restart. Response: `{ adopted, skipped }` — `skipped` carries the engine's reason per session (`sidechain`, `already-adopted`, `destination-exists`, `attributed-to-run`, `unreadable`, `placement-failed`, `record-failed`).",
+            summary: "Adopt native Claude Code chats into this project",
+            description: "Adopts the terminal `claude` sessions reported by GET …/adoptable-chats. With no body (or no `sourceCwd`) every detected source is adopted; with `sourceCwd` only that source is, and it must be one this project actually offers — an unrecognised path is a 400 rather than an invitation to scan arbitrary directories. `sessionIds` narrows the adoption to a chosen SUBSET of what is on offer (what the confirmation dialog sends); ids that are not on offer are simply not imported, and anything the engine adopts as a side effect of taking a whole source is released again. Transcripts are COPIED, never moved: the user's own `~/.claude` history is left intact and the copies keep their original mtimes, so imported chats sort by when they really happened. Afterwards the session, run-record and detection caches are dropped, so the chats appear on the very next list request with no restart. Response: `{ adopted, skipped }` — `skipped` carries the engine's reason per session (`sidechain`, `already-adopted`, `destination-exists`, `attributed-to-run`, `unreadable`, `placement-failed`, `record-failed`).",
             params: {
                 type: "object",
                 properties: {
@@ -1500,7 +1500,7 @@ export function registerChatWorkspaceRoutes(app, ctx) {
             },
             response: {
                 200: {
-                    description: "Object `{ adopted, skipped }` describing what was imported.",
+                    description: "Object `{ adopted, skipped }` describing what was adopted.",
                     type: "object",
                     additionalProperties: true,
                 },
@@ -1549,8 +1549,8 @@ export function registerChatWorkspaceRoutes(app, ctx) {
     app.post("/unadopt-chats", {
         schema: {
             tags: ["Chats"],
-            summary: "Undo the most recent native-chat import into this project",
-            description: "Reverses the import this server most recently performed into the workspace: each adoption is released and the copies that import placed are deleted, leaving the user's own `~/.claude` history untouched. `sessionIds` undoes part of that import; omit it to undo all of it. Deliberately scoped to the LAST import and remembered in memory — undo may delete files, so the paths it can touch come from what this process actually did rather than from the request body, and a restart forgets the offer rather than acting on a stale one. Response: `{ released }`, the session ids actually released; an empty array means there was nothing to undo (nothing imported, already undone, or the server restarted since).",
+            summary: "Undo the most recent native-chat adoption into this project",
+            description: "Reverses the adoption this server most recently performed into the workspace: each adoption is released and the copies that adoption placed are deleted, leaving the user's own `~/.claude` history untouched. `sessionIds` undoes part of that adoption; omit it to undo all of it. Deliberately scoped to the LAST adoption and remembered in memory — undo may delete files, so the paths it can touch come from what this process actually did rather than from the request body, and a restart forgets the offer rather than acting on a stale one. Response: `{ released }`, the session ids actually released; an empty array means there was nothing to undo (nothing imported, already undone, or the server restarted since).",
             params: {
                 type: "object",
                 properties: {

package/packages/server/dist/routes/discover.js

@@ -73,7 +73,7 @@ export function registerDiscoverRoutes(app, ctx) {
         schema: {
             tags: ["System"],
             summary: "Directories on this machine that could become projects",
-            description: "Scans `<claudeHome>/projects/*` for directories with existing Claude Code history and returns the ones worth importing, ranked by how many non-noise sessions each holds. Never walks the filesystem: the only directories it can name are ones a transcript already records, and each is put through the same path floor a linked project must clear (no system directories, no temp roots, nothing inside Paddock's own data dir, nothing overlapping an existing project). Two rules are relaxable: `includeNonGit=1` offers directories that are not git checkouts, `includeOutsideHome=1` offers directories outside `$HOME`. `excluded` reports how many folders each rule ate — a container whose Claude home is empty reports `scanned: 0`, which is what distinguishes 'no history' from 'all of it was filtered'. Response: `{ claudeHome, homeDir, scanned, candidates, excluded }`.",
+            description: "Scans `<claudeHome>/projects/*` for directories with existing Claude Code history and returns the ones worth importing, ranked by how many non-noise sessions each holds. Never walks the filesystem: the only directories it can name are ones a transcript already records, and each is put through the same path floor a linked project must clear (no system directories, no temp roots, nothing inside Paddock's own data dir, nothing overlapping an existing project). Two rules are relaxable: `includeNonGit=1` offers directories that are not git checkouts, `includeOutsideHome=1` offers directories outside `$HOME`. Note the two counts are in DIFFERENT units and do not reconcile by subtraction: `scanned` counts transcript FOLDERS, while `excluded` reports how many DIRECTORIES each rule ate — one directory routinely has two transcript folders (the user's own and Paddock's copy), so a rule that ate one directory may account for two scanned folders. The single exception is `no-recorded-cwd`, which is necessarily per-folder: a folder with no recorded cwd has no directory to be counted under. A container whose Claude home is empty reports `scanned: 0`, which is what distinguishes 'no history' from 'all of it was filtered'. Response: `{ claudeHome, homeDir, scanned, candidates, excluded }`.",
             querystring: {
                 type: "object",
                 properties: {

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

@@ -1,7 +1,7 @@
 /**
  * Git routes: the fleet-level remote + GitHub device-flow auth, plus the
- * per-project working-tree status / diff / commit surface (#258). Push is a
- * separate explicit action from a project commit.
+ * per-project working-tree status / diff / commit / remote / push surface
+ * (#258, #710). Push is a separate explicit action from a project commit.
  */
 import type { FastifyInstance } from "fastify";
 import type { RouteCtx } from "../route-context.js";

package/packages/server/dist/routes/git.js

@@ -1,4 +1,6 @@
 import { sendProjectError } from "../route-errors.js";
+import { ProjectError } from "../project-paths.js";
+import { readFileWithKind, readFileBytes } from "../project-files.js";
 export function registerGitRoutes(app, ctx) {
     const { git, githubAuth } = ctx;
     // --- git (backing store): fleet-level remote + connection state --------
@@ -118,7 +120,7 @@ export function registerGitRoutes(app, ctx) {
  * and per project) — see `workspace-mount.ts`. Paths are relative to the mount.
  */
 export function registerGitWorkspaceRoutes(app, ctx) {
-    const { git, projects } = ctx;
+    const { git, projects, githubAuth } = ctx;
     // --- git (backing-store capability, phase 1: read surface) -------------
     // Uncommitted changes confined to this project's subtree. Returns
     // `{ repo: false }` when the projects dir isn't a git working tree, so the
@@ -236,4 +238,134 @@ export function registerGitWorkspaceRoutes(app, ctx) {
             return sendProjectError(reply, err);
         }
     });
+    // This project's own remote + ahead/behind, with the (genuinely fleet-level)
+    // GitHub connection state folded in so the Changes header is one fetch (#710).
+    // Same payload shape as `GET /api/git`, which now differs only in WHICH repo it
+    // describes: that one always speaks for the backing store, this one for the
+    // directory the project actually works in.
+    app.get("/git/remote", {
+        schema: {
+            tags: ["Git"],
+            summary: "Get a project's git remote and GitHub connection state",
+            description: "Returns the remote details for the project's OWN working directory (a linked checkout or worktree has its own origin, branch and ahead/behind — issue #710) merged with a `github` object describing the fleet-level GitHub device-flow connection status.",
+            params: {
+                type: "object",
+                properties: {
+                    slug: { type: "string", description: "The project slug." },
+                },
+                required: ["slug"],
+            },
+            response: {
+                200: {
+                    description: "Object containing the remote configuration fields plus a nested `github` object with connection state.",
+                    type: "object",
+                    additionalProperties: true,
+                },
+            },
+        },
+    }, async (req, reply) => {
+        try {
+            const project = await projects.get(req.params.slug);
+            const [remote, github] = await Promise.all([
+                git.remote(project.workingDir),
+                githubAuth.status(),
+            ]);
+            return { ...remote, github };
+        }
+        catch (err) {
+            return sendProjectError(reply, err);
+        }
+    });
+    // Push THIS project's working directory to its origin (#710). The fleet-level
+    // `POST /api/git/push` still pushes the backing store; for a notebook project
+    // the two are the same repo, and for a linked one they are emphatically not —
+    // the Changes header's Push button used to push Paddock's notes repo while
+    // showing the user's worktree branch beside it.
+    app.post("/git/push", {
+        schema: {
+            tags: ["Git"],
+            summary: "Push a project's working directory to its remote",
+            description: "Pushes the current branch of the project's own working directory to its `origin`, setting upstream on first push. Returns an object describing the push result.",
+            params: {
+                type: "object",
+                properties: {
+                    slug: { type: "string", description: "The project slug." },
+                },
+                required: ["slug"],
+            },
+            response: {
+                200: {
+                    description: "Object describing the outcome of the push operation.",
+                    type: "object",
+                    additionalProperties: true,
+                },
+            },
+        },
+    }, async (req, reply) => {
+        try {
+            const project = await projects.get(req.params.slug);
+            return await git.push(project.workingDir);
+        }
+        catch (err) {
+            return sendProjectError(reply, err);
+        }
+    });
+    // An UNTRACKED file's content, read from the project's WORKING directory
+    // (#710). The Changes tab shows a new file's content in place of a diff, and
+    // used to fetch it from `/files/:name` — the metadata-dir surface, which for a
+    // repo-backed or linked project is a different directory entirely, so every
+    // new file in the pane rendered "File not found".
+    //
+    // The gate is `isUntrackedFile`, i.e. git's own answer, NOT the dot-segment
+    // guard `/files/:name` uses — see {@link GitService.isUntrackedFile} for why a
+    // path-shape rule is wrong in both directions once the target is a work tree.
+    // A path git does not report as untracked 404s, so the servable set is exactly
+    // the set the pane lists.
+    app.get("/git/file", {
+        schema: {
+            tags: ["Git"],
+            summary: "Get an untracked file's content from the project's working directory",
+            description: "Returns the content of a file git reports as UNTRACKED in the project's working directory — what the Changes tab renders in place of a diff for a brand-new file. `?path=` is the project-relative path; anything git does not currently report as untracked 404s. With `?raw=1` it streams raw bytes with the correct Content-Type (sandbox CSP + nosniff + inline disposition), how the pane loads a new image.",
+            params: {
+                type: "object",
+                properties: {
+                    slug: { type: "string", description: "The project slug." },
+                },
+                required: ["slug"],
+            },
+            querystring: {
+                type: "object",
+                additionalProperties: true,
+                properties: {
+                    path: { type: "string", description: "Project-relative path of the untracked file." },
+                    raw: {
+                        type: "string",
+                        description: "Set to a truthy value (e.g. `1`) to stream raw bytes instead of JSON.",
+                    },
+                },
+            },
+        },
+    }, async (req, reply) => {
+        try {
+            const project = await projects.get(req.params.slug);
+            const name = req.query.path ?? "";
+            if (!(await git.isUntrackedFile(project.workingDir, name))) {
+                throw new ProjectError(`File not found: ${name}`, "not_found");
+            }
+            if (req.query.raw !== undefined && req.query.raw !== "0" && req.query.raw !== "false") {
+                const { bytes, mime } = await readFileBytes(project.workingDir, name, "allow");
+                return reply
+                    .header("content-type", mime)
+                    .header("content-disposition", "inline")
+                    .header("x-content-type-options", "nosniff")
+                    .header("content-security-policy", "sandbox; default-src 'none'")
+                    .header("cache-control", "private, max-age=60")
+                    .send(bytes);
+            }
+            return await readFileWithKind(project.workingDir, name, "allow");
+        }
+        catch (err) {
+            return sendProjectError(reply, err);
+        }
+    });
 }