@hearsay-tools/squawk 0.0.0-stage → 0.17.0-dev.5682

package/dist/contract/provider-requests.d.ts

@@ -0,0 +1,77 @@
+import { z } from 'zod';
+export declare const providerConnectSchema: z.ZodObject<{
+    provider: z.ZodEnum<{
+        claude: "claude";
+        codex: "codex";
+        cursor: "cursor";
+        omp: "omp";
+        opencode: "opencode";
+        pi: "pi";
+    }>;
+    profileId: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+/** Agent-account bodies (spec 2026-07-29-agent-profiles). Bounds mirror `agentProfileSchema` in
+ *  src/workspace/config.ts exactly, so a value these accept can never be degraded away by the
+ *  next load's `.catch`. The id is allocated server-side and is never a request field. */
+export declare const createAgentProfileSchema: z.ZodObject<{
+    provider: z.ZodEnum<{
+        claude: "claude";
+        codex: "codex";
+        cursor: "cursor";
+        omp: "omp";
+        opencode: "opencode";
+        pi: "pi";
+    }>;
+    label: z.ZodOptional<z.ZodString>;
+    configDir: z.ZodString;
+}, z.core.$strict>;
+/** `POST …/agent-profiles/:id/open` — a catalog id (or `folder`) plus an optional open target. */
+export declare const openAgentAccountFileSchema: z.ZodObject<{
+    file: z.ZodString;
+    target: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export declare const updateAgentProfileSchema: z.ZodObject<{
+    label: z.ZodOptional<z.ZodString>;
+    configDir: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+/** `PUT …/agent-profiles/selection` — which account a project uses for one provider. `null`
+ *  clears it back to the discovered account. */
+export declare const selectAgentProfileSchema: z.ZodObject<{
+    projectId: z.ZodNullable<z.ZodString>;
+    provider: z.ZodEnum<{
+        claude: "claude";
+        codex: "codex";
+        cursor: "cursor";
+        omp: "omp";
+        opencode: "opencode";
+        pi: "pi";
+    }>;
+    profileId: z.ZodNullable<z.ZodString>;
+}, z.core.$strict>;
+export declare const providerParamSchema: z.ZodEnum<{
+    claude: "claude";
+    codex: "codex";
+    cursor: "cursor";
+    omp: "omp";
+    opencode: "opencode";
+    pi: "pi";
+}>;
+export declare const providerEnabledSchema: z.ZodObject<{
+    enabled: z.ZodBoolean;
+}, z.core.$strict>;
+export declare const providerRetrySchema: z.ZodObject<{
+    authFailureId: z.ZodString;
+}, z.core.$strict>;
+export declare const providerRouteParamsSchema: z.ZodObject<{
+    provider: z.ZodEnum<{
+        claude: "claude";
+        codex: "codex";
+        cursor: "cursor";
+        omp: "omp";
+        opencode: "opencode";
+        pi: "pi";
+    }>;
+}, z.core.$strip>;
+export declare const agentProfileRouteParamsSchema: z.ZodObject<{
+    id: z.ZodString;
+}, z.core.$strip>;

package/dist/contract/query-requests.d.ts

@@ -0,0 +1,52 @@
+import { z } from 'zod';
+/**
+ * Query schemas for the READ routes — deliberately permissive.
+ *
+ * These exist to make a query key VISIBLE to the route type (`hc` refuses a `query` argument for
+ * a key no validator declares), NOT to narrow what the route accepts. Every one of these handlers
+ * compares `=== '1'` and treats everything else as false, so `?refresh=0` is a successful request
+ * today; a literal schema would silently turn it into a 400. The comparison stays in the handler
+ * and the validator stays out of its way.
+ *
+ * The one route that really is strict on the wire — `GET /github/prs/:number/changes`, which 400s
+ * on `?refresh=true` — keeps its own `z.enum(['1'])` schema next to the route.
+ */
+/**
+ * One query value, matching what `c.req.query('k')` did before these routes were validated.
+ *
+ * Hono's query validator hands a REPEATED key as an array (`?wait=1&wait=1` → `['1','1']`), where
+ * `c.req.query()` silently took the first. A plain `z.string()` therefore turns a request that
+ * used to answer 200 into a 400 — a wire change no caller asked for. Collapsing to the first
+ * value keeps the old behaviour, and the client still sees a plain `key?: string`.
+ */
+export declare const queryValue: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodPipe<z.ZodArray<z.ZodString>, z.ZodTransform<string, string[]>>]>>;
+export declare const refreshQuery: z.ZodObject<{
+    refresh: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodPipe<z.ZodArray<z.ZodString>, z.ZodTransform<string, string[]>>]>>;
+}, z.core.$strip>;
+export declare const waitQuery: z.ZodObject<{
+    wait: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodPipe<z.ZodArray<z.ZodString>, z.ZodTransform<string, string[]>>]>>;
+}, z.core.$strip>;
+export declare const modelDiscoveryQuerySchema: z.ZodObject<{
+    runner: z.ZodPipe<z.ZodUnion<readonly [z.ZodString, z.ZodPipe<z.ZodArray<z.ZodString>, z.ZodTransform<string, string[]>>]>, z.ZodEnum<{
+        claude: "claude";
+        codex: "codex";
+        cursor: "cursor";
+        omp: "omp";
+        opencode: "opencode";
+        pi: "pi";
+    }>>;
+}, z.core.$strip>;
+export declare const strictRefreshQuerySchema: z.ZodObject<{
+    refresh: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodPipe<z.ZodArray<z.ZodString>, z.ZodTransform<string, string[]>>]>> & z.ZodType<"1" | undefined, string | string[] | undefined, z.core.$ZodTypeInternals<"1" | undefined, string | string[] | undefined>>;
+}, z.core.$strip>;
+export declare const browseQuerySchema: z.ZodObject<{
+    path: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodPipe<z.ZodArray<z.ZodString>, z.ZodTransform<string, string[]>>]>>;
+    showHidden: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodPipe<z.ZodArray<z.ZodString>, z.ZodTransform<string, string[]>>]>>;
+}, z.core.$strip>;
+export declare const worktreeFilesQuerySchema: z.ZodObject<{
+    path: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodPipe<z.ZodArray<z.ZodString>, z.ZodTransform<string, string[]>>]>>;
+    raw: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodPipe<z.ZodArray<z.ZodString>, z.ZodTransform<string, string[]>>]>>;
+}, z.core.$strip>;
+export declare const commitQuerySchema: z.ZodObject<{
+    structured: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodPipe<z.ZodArray<z.ZodString>, z.ZodTransform<string, string[]>>]>>;
+}, z.core.$strip>;

package/dist/contract/repo-requests.d.ts

@@ -0,0 +1,12 @@
+import { z } from 'zod';
+export declare const gitCommitSchema: z.ZodObject<{
+    message: z.ZodString;
+}, z.core.$strip>;
+export declare const reclaimBodySchema: z.ZodObject<{}, z.core.$loose>;
+export declare const repoBranchSchema: z.ZodObject<{
+    name: z.ZodString;
+    from: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export declare const reclaimRunParamsSchema: z.ZodObject<{
+    runId: z.ZodString;
+}, z.core.$strip>;

package/dist/contract/repo.d.ts

@@ -0,0 +1,515 @@
+import { z } from 'zod';
+/**
+ * The repo / git family of `/api/v1` — the Repo view, the structured diff shapes the Changes and
+ * Files tabs read, and the worktree-retention panel.
+ *
+ * `RepoInfo` is NOT redeclared here: health already owns it (`./health.ts`), and the Repo view
+ * serves the very same record.
+ */
+/** One `git status --porcelain` row. */
+export declare const statusEntrySchema: z.ZodObject<{
+    status: z.ZodString;
+    path: z.ZodString;
+}, z.core.$strip>;
+export type StatusEntry = z.infer<typeof statusEntrySchema>;
+/** The task a base-branch commit came from (issue 08 §B5). Best effort: a merge commit maps its
+ *  second parent to a run by `branch`, a squash commit maps a trailing `(#123)` to a run by
+ *  `pullRequestUrl`. `prNumber` is the PR that landed it, when one is known. */
+export declare const logEntrySourceSchema: z.ZodObject<{
+    runId: z.ZodString;
+    title: z.ZodString;
+    prNumber: z.ZodNullable<z.ZodNumber>;
+}, z.core.$strip>;
+export type LogEntrySource = z.infer<typeof logEntrySourceSchema>;
+/** One `git log` row; `when` is git's relative `%cr` ("3 hours ago"), `at` the committer date as
+ *  strict ISO 8601 (`%cI`), which is what a client groups by day. `source` is ABSENT (never
+ *  `null`) when no task is known to have produced the commit. */
+export declare const logEntrySchema: z.ZodObject<{
+    hash: z.ZodString;
+    subject: z.ZodString;
+    author: z.ZodString;
+    when: z.ZodString;
+    at: z.ZodString;
+    source: z.ZodOptional<z.ZodObject<{
+        runId: z.ZodString;
+        title: z.ZodString;
+        prNumber: z.ZodNullable<z.ZodNumber>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type LogEntry = z.infer<typeof logEntrySchema>;
+/**
+ * `GET /api/v1/repo` — the Repo view's one read.
+ *
+ * A union, and deliberately so: the handler answers a DIFFERENT object when the project root is
+ * not a repository (`server.ts:3481`) than when it is (`server.ts:3494`), and the empty branch's
+ * `[]` literals make its arrays `never[]` in the route type. Modelling this as the flat
+ * `{ info: RepoInfo | null; status: StatusEntry[]; … }` the hand-written DTO used would be WIDER
+ * than the route — the parity guard rejects it. Both members still parse the real wire bytes
+ * (an empty array satisfies `z.array(z.never())`), so nothing is lost at runtime; it is the
+ * compile-time shape that is oddly precise. See the report note on `server.ts:3481`.
+ */
+/**
+ * How the base branch stands against its upstream (issue 08 §B1), as of the LAST FETCH: no request
+ * ever fetches. `ref` is the upstream's short name (`origin/main`); `ahead`/`behind` count commits
+ * only on the base / only on the upstream; `fetchedAt` is the mtime of `FETCH_HEAD`, or null when
+ * the repository has never fetched. The whole field is null when the base has no upstream.
+ */
+export declare const repoTrackingSchema: z.ZodObject<{
+    ref: z.ZodString;
+    ahead: z.ZodNumber;
+    behind: z.ZodNumber;
+    fetchedAt: z.ZodNullable<z.ZodString>;
+}, z.core.$strip>;
+export type RepoTracking = z.infer<typeof repoTrackingSchema>;
+export declare const repoResponseSchema: z.ZodUnion<readonly [z.ZodObject<{
+    info: z.ZodNull;
+    status: z.ZodArray<z.ZodNever>;
+    log: z.ZodArray<z.ZodNever>;
+    branches: z.ZodArray<z.ZodNever>;
+    baseBranch: z.ZodNull;
+    tracking: z.ZodNull;
+}, z.core.$strip>, z.ZodObject<{
+    info: z.ZodObject<{
+        root: z.ZodString;
+        branch: z.ZodString;
+        remote: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+    status: z.ZodArray<z.ZodObject<{
+        status: z.ZodString;
+        path: z.ZodString;
+    }, z.core.$strip>>;
+    log: z.ZodArray<z.ZodObject<{
+        hash: z.ZodString;
+        subject: z.ZodString;
+        author: z.ZodString;
+        when: z.ZodString;
+        at: z.ZodString;
+        source: z.ZodOptional<z.ZodObject<{
+            runId: z.ZodString;
+            title: z.ZodString;
+            prNumber: z.ZodNullable<z.ZodNumber>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+    branches: z.ZodArray<z.ZodString>;
+    baseBranch: z.ZodNullable<z.ZodString>;
+    tracking: z.ZodNullable<z.ZodObject<{
+        ref: z.ZodString;
+        ahead: z.ZodNumber;
+        behind: z.ZodNumber;
+        fetchedAt: z.ZodNullable<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>]>;
+export type RepoResponse = z.infer<typeof repoResponseSchema>;
+/** `POST /api/v1/repo/branch` — switch to an existing branch, or create one and switch. Every
+ *  predictable git failure (invalid name, unknown `from`, dirty-tree conflict) is a 409. */
+export declare const repoBranchResponseSchema: z.ZodObject<{
+    branch: z.ZodString;
+    created: z.ZodBoolean;
+}, z.core.$strip>;
+export type RepoBranchResponse = z.infer<typeof repoBranchResponseSchema>;
+/**
+ * Where a local branch stands (issue 08 §A). Classified once, on the server:
+ *
+ * - `active` — its run is live or not yet finished (queued, running, waiting, monitoring, `review`),
+ *   it is protected by an owned-workspace receipt, it is checked out in any worktree, or it is the
+ *   current or base branch. Never deletable.
+ * - `not-landed` — its run is finished (or archived), it has commits the base does not, and no PR
+ *   from it merged. Deletable one at a time, with a typed confirmation.
+ * - `orphan` — a `cez/*` branch no run names, with commits the base does not and no merged PR.
+ *   Same deletion rule as `not-landed`: the branch may be the only copy of the work.
+ * - `merged` — its tip is reachable from the base, or a PR from it merged (squash merges are not
+ *   ancestors). Bulk-deletable, and swept automatically once no worktree checks it out. A branch
+ *   outside `cez/*` is `merged` only as the exact merged PR a finished run recorded; `runId` then
+ *   names that run.
+ * - `empty` — its run exists and the tip is still the run's fork point. Bulk-deletable.
+ * - `empty` and `merged` are what the automatic branch sweep deletes (hearsay-tools/cezarion#2268).
+ * - `other` — not `cez/*`: the user's own branch. Never deletable from this surface.
+ */
+export declare const branchClassSchema: z.ZodEnum<{
+    active: "active";
+    empty: "empty";
+    merged: "merged";
+    "not-landed": "not-landed";
+    orphan: "orphan";
+    other: "other";
+}>;
+export type BranchClass = z.infer<typeof branchClassSchema>;
+export declare const branchPrStateSchema: z.ZodEnum<{
+    closed: "closed";
+    draft: "draft";
+    merged: "merged";
+    open: "open";
+}>;
+export type BranchPrState = z.infer<typeof branchPrStateSchema>;
+export declare const repoBranchEntrySchema: z.ZodObject<{
+    name: z.ZodString;
+    class: z.ZodEnum<{
+        active: "active";
+        empty: "empty";
+        merged: "merged";
+        "not-landed": "not-landed";
+        orphan: "orphan";
+        other: "other";
+    }>;
+    runId: z.ZodNullable<z.ZodString>;
+    title: z.ZodNullable<z.ZodString>;
+    runStatus: z.ZodNullable<z.ZodEnum<{
+        cancelled: "cancelled";
+        done: "done";
+        failed: "failed";
+        queued: "queued";
+        review: "review";
+        running: "running";
+        waiting: "waiting";
+    }>>;
+    ahead: z.ZodNumber;
+    lastCommit: z.ZodObject<{
+        sha: z.ZodString;
+        subject: z.ZodString;
+        at: z.ZodString;
+    }, z.core.$strip>;
+    diffStat: z.ZodNullable<z.ZodObject<{
+        additions: z.ZodNumber;
+        deletions: z.ZodNumber;
+    }, z.core.$strip>>;
+    pr: z.ZodNullable<z.ZodObject<{
+        number: z.ZodNumber;
+        url: z.ZodString;
+        state: z.ZodEnum<{
+            closed: "closed";
+            draft: "draft";
+            merged: "merged";
+            open: "open";
+        }>;
+    }, z.core.$strip>>;
+    keptReason: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type RepoBranchEntry = z.infer<typeof repoBranchEntrySchema>;
+/**
+ * `GET /api/v1/repo/branches` — every local branch, classified. `base` is the ref the classes were
+ * measured against (`origin/<base>` when the local base is behind it). `prStateKnown` is false when
+ * the forge could not answer (no `gh`, offline, no remote): squash-merged branches may then read as
+ * `not-landed`, never the other way round. `counts.cleanup` is `merged` + `empty`. A directory that
+ * is not a repository answers an empty list, never an error.
+ */
+export declare const repoBranchesResponseSchema: z.ZodObject<{
+    base: z.ZodString;
+    prStateKnown: z.ZodBoolean;
+    branches: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        class: z.ZodEnum<{
+            active: "active";
+            empty: "empty";
+            merged: "merged";
+            "not-landed": "not-landed";
+            orphan: "orphan";
+            other: "other";
+        }>;
+        runId: z.ZodNullable<z.ZodString>;
+        title: z.ZodNullable<z.ZodString>;
+        runStatus: z.ZodNullable<z.ZodEnum<{
+            cancelled: "cancelled";
+            done: "done";
+            failed: "failed";
+            queued: "queued";
+            review: "review";
+            running: "running";
+            waiting: "waiting";
+        }>>;
+        ahead: z.ZodNumber;
+        lastCommit: z.ZodObject<{
+            sha: z.ZodString;
+            subject: z.ZodString;
+            at: z.ZodString;
+        }, z.core.$strip>;
+        diffStat: z.ZodNullable<z.ZodObject<{
+            additions: z.ZodNumber;
+            deletions: z.ZodNumber;
+        }, z.core.$strip>>;
+        pr: z.ZodNullable<z.ZodObject<{
+            number: z.ZodNumber;
+            url: z.ZodString;
+            state: z.ZodEnum<{
+                closed: "closed";
+                draft: "draft";
+                merged: "merged";
+                open: "open";
+            }>;
+        }, z.core.$strip>>;
+        keptReason: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    counts: z.ZodObject<{
+        notLanded: z.ZodNumber;
+        cleanup: z.ZodNumber;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export type RepoBranchesResponse = z.infer<typeof repoBranchesResponseSchema>;
+/** `GET /api/v1/repo/branches/counts` — the same classification's counts, without the rows and
+ *  without a diff stat per branch: what the always-mounted Git sidebar reads
+ *  (hearsay-tools/cezarion#2029). `allBranches` counts what the All branches list shows: every
+ *  name `GET /repo` lists plus every local branch, so the `cez/*` ones too. */
+export declare const repoBranchCountsResponseSchema: z.ZodObject<{
+    base: z.ZodString;
+    prStateKnown: z.ZodBoolean;
+    counts: z.ZodObject<{
+        notLanded: z.ZodNumber;
+        cleanup: z.ZodNumber;
+    }, z.core.$strip>;
+    allBranches: z.ZodNumber;
+}, z.core.$strip>;
+export type RepoBranchCountsResponse = z.infer<typeof repoBranchCountsResponseSchema>;
+/** `POST /api/v1/repo/branches/delete`. `confirm` must equal the branch name to delete a
+ *  `not-landed` or `orphan` branch, which is only ever deleted alone. */
+export declare const deleteBranchesInputSchema: z.ZodObject<{
+    names: z.ZodArray<z.ZodString>;
+    confirm: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type DeleteBranchesInput = z.infer<typeof deleteBranchesInputSchema>;
+export declare const branchRefusalSchema: z.ZodObject<{
+    name: z.ZodString;
+    reason: z.ZodString;
+}, z.core.$strip>;
+export type BranchRefusal = z.infer<typeof branchRefusalSchema>;
+/**
+ * The delete answer. The server re-classifies every name at delete time and never trusts the
+ * client: `merged`/`empty` go in bulk, everything else lands in `refused` with its reason.
+ * `dropped` names the commits a confirmed `not-landed`/`orphan` delete threw away (newest first,
+ * at most 100) and is absent on every other answer. 200 when anything was deleted; 409 with the
+ * same `refused` list and an `error` when nothing was.
+ */
+export declare const deleteBranchesResponseSchema: z.ZodObject<{
+    deleted: z.ZodArray<z.ZodString>;
+    refused: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        reason: z.ZodString;
+    }, z.core.$strip>>;
+    dropped: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        sha: z.ZodString;
+        subject: z.ZodString;
+    }, z.core.$strip>>>;
+}, z.core.$strip>;
+export type DeleteBranchesResponse = z.infer<typeof deleteBranchesResponseSchema>;
+export declare const deleteBranchesErrorSchema: z.ZodObject<{
+    error: z.ZodString;
+    refused: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        reason: z.ZodString;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type DeleteBranchesError = z.infer<typeof deleteBranchesErrorSchema>;
+/** Local branches eligible for the project checkout's Pull picker. */
+export declare const repoPullBranchesResponseSchema: z.ZodObject<{
+    branches: z.ZodArray<z.ZodString>;
+}, z.core.$strip>;
+export type RepoPullBranchesResponse = z.infer<typeof repoPullBranchesResponseSchema>;
+export declare const repoPullInputSchema: z.ZodObject<{
+    branch: z.ZodOptional<z.ZodString>;
+    confirm: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+export type RepoPullInput = z.infer<typeof repoPullInputSchema>;
+export declare const repoPullResponseSchema: z.ZodObject<{
+    branch: z.ZodString;
+    pulled: z.ZodLiteral<true>;
+    summary: z.ZodString;
+}, z.core.$strip>;
+export type RepoPullResponse = z.infer<typeof repoPullResponseSchema>;
+/** A 409 that can be retried after acknowledging the named risks. */
+export declare const repoPullConfirmationSchema: z.ZodObject<{
+    error: z.ZodString;
+    branch: z.ZodString;
+    risks: z.ZodArray<z.ZodEnum<{
+        active_runs: "active_runs";
+        dirty_tree: "dirty_tree";
+    }>>;
+}, z.core.$strip>;
+export type RepoPullConfirmation = z.infer<typeof repoPullConfirmationSchema>;
+export declare const repoPullErrorSchema: z.ZodUnion<readonly [z.ZodObject<{
+    error: z.ZodString;
+    branch: z.ZodString;
+    risks: z.ZodArray<z.ZodEnum<{
+        active_runs: "active_runs";
+        dirty_tree: "dirty_tree";
+    }>>;
+}, z.core.$strip>, z.ZodObject<{
+    error: z.ZodString;
+}, z.core.$strip>]>;
+export type RepoPullError = z.infer<typeof repoPullErrorSchema>;
+/** One changed file of a structured diff (`/runs/:id/changes`, `/repo/changes`, the commit
+ *  routes). Assignable to the diff facade's `DiffFileChange` by construction. */
+export declare const changedFileSchema: z.ZodObject<{
+    path: z.ZodString;
+    oldPath: z.ZodOptional<z.ZodString>;
+    status: z.ZodEnum<{
+        added: "added";
+        copied: "copied";
+        deleted: "deleted";
+        modified: "modified";
+        renamed: "renamed";
+    }>;
+    adds: z.ZodNumber;
+    dels: z.ZodNumber;
+    binary: z.ZodBoolean;
+    image: z.ZodOptional<z.ZodBoolean>;
+    patch: z.ZodString;
+}, z.core.$strip>;
+export type ChangedFile = z.infer<typeof changedFileSchema>;
+/** `GET /api/v1/runs/:id/changes` and `GET /api/v1/repo/changes` — the structured diff.
+ *  409 (+ reason) when the run's backing directory is unavailable or git itself refuses; never HTML. */
+export declare const changesPayloadSchema: z.ZodObject<{
+    files: z.ZodArray<z.ZodObject<{
+        path: z.ZodString;
+        oldPath: z.ZodOptional<z.ZodString>;
+        status: z.ZodEnum<{
+            added: "added";
+            copied: "copied";
+            deleted: "deleted";
+            modified: "modified";
+            renamed: "renamed";
+        }>;
+        adds: z.ZodNumber;
+        dels: z.ZodNumber;
+        binary: z.ZodBoolean;
+        image: z.ZodOptional<z.ZodBoolean>;
+        patch: z.ZodString;
+    }, z.core.$strip>>;
+    stat: z.ZodObject<{
+        adds: z.ZodNumber;
+        dels: z.ZodNumber;
+        files: z.ZodNumber;
+    }, z.core.$strip>;
+    repointedHead: z.ZodOptional<z.ZodObject<{
+        headBranch: z.ZodString;
+        taskBranch: z.ZodString;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type ChangesPayload = z.infer<typeof changesPayloadSchema>;
+/** `GET /api/v1/repo/commit/:sha?structured=1` (and `/runs/:id/commit/:sha`) — one commit's
+ *  metadata plus the same `{files, stat}` shape the /changes routes serve. A merge commit
+ *  honestly answers zero files. The bare (unstructured) route keeps its legacy text shape. */
+export declare const repoCommitPayloadSchema: z.ZodObject<{
+    sha: z.ZodString;
+    subject: z.ZodString;
+    author: z.ZodString;
+    when: z.ZodString;
+    files: z.ZodArray<z.ZodObject<{
+        path: z.ZodString;
+        oldPath: z.ZodOptional<z.ZodString>;
+        status: z.ZodEnum<{
+            added: "added";
+            copied: "copied";
+            deleted: "deleted";
+            modified: "modified";
+            renamed: "renamed";
+        }>;
+        adds: z.ZodNumber;
+        dels: z.ZodNumber;
+        binary: z.ZodBoolean;
+        image: z.ZodOptional<z.ZodBoolean>;
+        patch: z.ZodString;
+    }, z.core.$strip>>;
+    stat: z.ZodObject<{
+        adds: z.ZodNumber;
+        dels: z.ZodNumber;
+        files: z.ZodNumber;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export type RepoCommitPayload = z.infer<typeof repoCommitPayloadSchema>;
+/** One row of a `GET /api/v1/runs/:id/files` directory listing. */
+export declare const worktreeDirEntrySchema: z.ZodObject<{
+    name: z.ZodString;
+    type: z.ZodEnum<{
+        dir: "dir";
+        file: "file";
+    }>;
+    size: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+export type WorktreeDirEntry = z.infer<typeof worktreeDirEntrySchema>;
+/**
+ * `GET /api/v1/runs/:id/files?path=` — a directory listing or one file (size-capped, binary
+ * flagged). `content` is absent exactly when `binary` or `tooLarge`.
+ *
+ * A discriminated union on `type`. Both handlers now build their literal with `as const`; without
+ * it the property widened to `string` during Hono's route-type inference and the route lost the
+ * discriminant, so a consumer narrowing on `entry.type === 'dir'` was left with `never`.
+ */
+export declare const worktreeEntrySchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    type: z.ZodLiteral<"dir">;
+    path: z.ZodString;
+    entries: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        type: z.ZodEnum<{
+            dir: "dir";
+            file: "file";
+        }>;
+        size: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"file">;
+    path: z.ZodString;
+    size: z.ZodNumber;
+    binary: z.ZodBoolean;
+    tooLarge: z.ZodBoolean;
+    content: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>], "type">;
+export type WorktreeEntry = z.infer<typeof worktreeEntrySchema>;
+/** One materialized task worktree in the management panel (#483). `sizeBytes` is null when `du`
+ *  is unavailable (Windows / missing). `reclaimable` = finished, has a directory, not yet
+ *  reclaimed (retention's rule). `pastKeep` = reclaimable AND outside the newest `keep`, i.e.
+ *  exactly the rows a "Reclaim now" would take; a reclaimable row that is not past it is kept. */
+export declare const worktreeInfoSchema: z.ZodObject<{
+    runId: z.ZodString;
+    title: z.ZodString;
+    status: z.ZodEnum<{
+        cancelled: "cancelled";
+        done: "done";
+        failed: "failed";
+        queued: "queued";
+        review: "review";
+        running: "running";
+        waiting: "waiting";
+    }>;
+    branch: z.ZodNullable<z.ZodString>;
+    sizeBytes: z.ZodNullable<z.ZodNumber>;
+    finishedAt: z.ZodNullable<z.ZodString>;
+    reclaimable: z.ZodBoolean;
+    pastKeep: z.ZodBoolean;
+}, z.core.$strip>;
+export type WorktreeInfo = z.infer<typeof worktreeInfoSchema>;
+/** `GET /api/v1/worktrees` (#483): the worktrees on disk, their total size (null when any
+ *  degraded), and the current keep-limit (0 = unlimited). */
+export declare const worktreesResponseSchema: z.ZodObject<{
+    worktrees: z.ZodArray<z.ZodObject<{
+        runId: z.ZodString;
+        title: z.ZodString;
+        status: z.ZodEnum<{
+            cancelled: "cancelled";
+            done: "done";
+            failed: "failed";
+            queued: "queued";
+            review: "review";
+            running: "running";
+            waiting: "waiting";
+        }>;
+        branch: z.ZodNullable<z.ZodString>;
+        sizeBytes: z.ZodNullable<z.ZodNumber>;
+        finishedAt: z.ZodNullable<z.ZodString>;
+        reclaimable: z.ZodBoolean;
+        pastKeep: z.ZodBoolean;
+    }, z.core.$strip>>;
+    totalBytes: z.ZodNullable<z.ZodNumber>;
+    keep: z.ZodNumber;
+}, z.core.$strip>;
+export type WorktreesResponse = z.infer<typeof worktreesResponseSchema>;
+/** `POST /api/v1/worktrees/:runId/reclaim` (issue 08 §B4): one run's worktree DIRECTORY reclaimed
+ *  by retention's own rule and helper; the `cez/<id8>` branch is kept. 409 + `{error}` when the
+ *  run is not reclaimable (live, at `review`, an owned worker mid-destroy, already reclaimed). */
+export declare const reclaimWorktreeResponseSchema: z.ZodObject<{
+    runId: z.ZodString;
+    worktreeReclaimedAt: z.ZodString;
+}, z.core.$strip>;
+export type ReclaimWorktreeResponse = z.infer<typeof reclaimWorktreeResponseSchema>;
+/** `POST /api/v1/worktrees/reclaim` (#483): the run ids whose directory was reclaimed. */
+export declare const reclaimWorktreesResponseSchema: z.ZodObject<{
+    reclaimed: z.ZodArray<z.ZodString>;
+}, z.core.$strip>;
+export type ReclaimWorktreesResponse = z.infer<typeof reclaimWorktreesResponseSchema>;

package/dist/contract/report-title.d.ts

@@ -0,0 +1,3 @@
+import type { PublishedArtifact } from './artifacts.ts';
+/** Shared display name for a published HTML snapshot. */
+export declare function reportTitle(artifact: Pick<PublishedArtifact, 'name' | 'title'>): string;