@edspencer/paddock 0.70.0 → 0.70.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@edspencer/paddock",
-  "version": "0.70.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/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/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/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;