e11d7c4 · 49f2ca7 · dcf1bb6 · 59769f5 · af465d4
@@ -15,7 +15,7 @@
A new read of a table that grows (`event`, `issue`, `run`, `comment`) names the
A new `/settings…` page route goes in `src/http/settings_routes.ts` (`settingsRoutes`), not `src/http/server.ts`.
State shared between modules through process memory, not the database, is named here. `src/perf/views_report.ts`: `readVisits` holds each scope and window's visits for 15 seconds (dropped by `flushViews`), so a page and its probe share one read; `src/perf/views_store.ts`: the view buffer, flushed every 10 seconds. The traffic sources view's terminal door is `src/tui/screens/trafficview.ts` (palette entry for admins, per-app command for a repository's admins). The schedules' terminal door is `src/tui/screens/schedules.ts` (per-app palette command while the repository is open; `r` runs, `p` pauses or resumes, writers only; `scheduleRows`/`steerSchedule` give the page, API, MCP tool and terminal the same rows and gates). `src/runs/held.ts`: each dispatcher pass (`src/crew/dispatch.ts`, `pump`) records which queued agent runs it held and why (valve, pace, limit), and vitals (`src/kernel/vitals.ts`) leaves those out of `queue:agent`. A record older than `HELD_FRESH_MS` is ignored, so a stopped dispatcher cannot hide its queue. `src/runs/stoppable.ts`: the checks in flight in this process by run id (`src/checks/service.ts` `start` tracks each), so a person's cancel (`cancelRepoRun`) aborts the check and its process group ends with it; agent runs keep `src/crew/running.ts`. `src/apps/egress_refused.ts`: refused-host counts per repository, flushed to disk every 5 seconds (`flushRefused` forces it). `src/spawn/usage.ts`: the last disk reading of each child's data directory (30 s), and a cell child's last reading of its own cgroup CPU (`selfUse`, #10853), from which the next reading's cores are taken; `forgetSelfCpu` drops it. `src/web/pages/flow-waiting.ts`: the unproposed-work scan (it reads git for every crew fork) is held for 60 seconds (`forgetUnproposed` drops it), so /flow and the terminal screen share one scan.
State shared between modules through process memory, not the database, is named here. `src/perf/views_report.ts`: `readVisits` holds each scope and window's visits for 15 seconds (dropped by `flushViews`), so a page and its probe share one read; `src/perf/views_store.ts`: the view buffer, flushed every 10 seconds. The traffic sources view's terminal door is `src/tui/screens/trafficview.ts` (palette entry for admins, per-app command for a repository's admins). The schedules' terminal door is `src/tui/screens/schedules.ts` (per-app palette command while the repository is open; `r` runs, `p` pauses or resumes, writers only; `scheduleRows`/`steerSchedule` give the page, API, MCP tool and terminal the same rows and gates). `src/core/chapters.ts`: a closed chapter's item list is kept per chapter id (200 at most; `forgetFrozenItems` drops them), since closed is forever. `src/runs/held.ts`: each dispatcher pass (`src/crew/dispatch.ts`, `pump`) records which queued agent runs it held and why (valve, pace, limit), and vitals (`src/kernel/vitals.ts`) leaves those out of `queue:agent`. A record older than `HELD_FRESH_MS` is ignored, so a stopped dispatcher cannot hide its queue. `src/runs/stoppable.ts`: the checks in flight in this process by run id (`src/checks/service.ts` `start` tracks each), so a person's cancel (`cancelRepoRun`) aborts the check and its process group ends with it; agent runs keep `src/crew/running.ts`. `src/apps/egress_refused.ts`: refused-host counts per repository, flushed to disk every 5 seconds (`flushRefused` forces it). `src/spawn/usage.ts`: the last disk reading of each child's data directory (30 s), and a cell child's last reading of its own cgroup CPU (`selfUse`, #10853), from which the next reading's cores are taken; `forgetSelfCpu` drops it. `src/web/pages/flow-waiting.ts`: the unproposed-work scan (it reads git for every crew fork) is held for 60 seconds (`forgetUnproposed` drops it), so /flow and the terminal screen share one scan.
`src/perf/loop_worst.ts`: `loopWorst`, the worst event-loop lag of the last 10 s in ten one-second slots, fed by one unref'd 50 ms timer that the first `serve` starts (`startLoopWorst`), and read by every response's `lag;dur` and by `/healthz` asked for JSON (`loopLagMs`). Tests listing a request's phases read `requestTiming` (`test/helpers/request-timing.ts`), which leaves `lag` out.
@@ -0,0 +1,14 @@
# Chapters: a version with an end
A chapter is a named list of a repository's issues that is finished, tagged and closed (#11603). A name (`v1.0.0`; it becomes the git tag), one sentence of what done means, and the issues in it.
- **One open, any number drafted.** A repository has at most one open chapter. Later ones (`v2`, `v3`) are drafted after it and filled with issues that wait.
- **While one is open the crew builds only what is in it.** The dispatcher (`queueAgentRun`, through `chapterHold` in `src/core/chapters.ts`) starts no builder or reviewer run on an issue outside it. The planner may split a chapter's issue (the parts stay in the chapter) and may open an issue that says `Defect of #N` for an item of the chapter (it joins the chapter); every other issue it opens waits in the next chapter, or, with none drafted, behind the Later gate. Adding or removing an issue is the owner's act, recorded as `chapter.item_added` / `chapter.item_removed`.
- **The list being crossed off.** `/<owner>/<name>/chapters/<name>`: done items struck through with the day they went live, what is building, what is left, and the date it finishes at the pace since it opened. An item is done when it is live and proven (a merged pull that closes it and a passing production release proof), never when the pull merged.
- **Closing the book.** When the last item is done, or when the owner presses **Ship it**, the forge tags the default branch with the chapter's name, writes the notes from what landed (grouped, with who built what and what it cost), moves what is left to the next chapter and marks the chapter closed. The chapter's page then says it is finished: what shipped, how long it took, what it cost. The crew then rests on that repository until a chapter is opened; nothing starts by itself.
- **Closed is forever.** A closed chapter stays readable at its own address and cannot be reopened or changed. A fix for something it shipped goes in a patch chapter (`v1.0.1`), opened with one click from the closed chapter's page.
- **No chapter, no change.** A repository that never drafted one flows continuously, as before.
Doors: the page (`/chapters`, linked from `/queue`), the terminal (`src/tui/screens/chapters.ts`, the palette's "Chapters" while an app is open: `n` drafts, `o` opens, `s` ships, `p` patches, `enter` shows the list where `a` adds an issue and `x` takes one out) and the API (`GET`/`POST /api/v1/repos/:owner/:name/chapters`, `POST …/chapters/:chapter/:verb` with `open`, `add`, `remove`, `ship`, `patch`). Only a person who administers the repository acts; an agent is refused.
A closed chapter's list is frozen, so `itemsOf` keeps it in process memory (at most 200, `forgetFrozenItems` drops them); an open chapter's list is one pass over the repository's pulls and one grouped read of its runs, however many items it holds, so the anonymous page and API read stay cheap.
@@ -0,0 +1,189 @@
/**
 * The owner's acts on chapters (#11603): draft, open, fill, close the book, patch. One door for the
 * page and the API. Only a human admin of the repository acts (an agent never adds scope: the crew
 * proposes, a person decides); each change is an event, so the queue shows who moved what.
 * The rules are in `core/chapters.ts`, the notes' words in `core/chapter_notes.ts`.
 */
import type { App } from "../app.ts";
import { chapterNotes, daysBetween } from "../core/chapter_notes.ts";
import {
  draftChapter,
  getChapter,
  itemsOf,
  nextChapterOf,
  nextName,
  openChapterOf,
  patchName,
  placeNewIssue,
  putIssue,
  startChapter,
  takeIssueOut,
  type Chapter,
  type ChapterError,
} from "../core/chapters.ts";
import { addDependency } from "../core/dependencies.ts";
import { getIssue, labelsFor, type Issue } from "../core/issues.ts";
import { laterGate } from "../crew/later.ts";
import { canAdmin, type Repo } from "../core/repos.ts";
import type { User } from "../core/users.ts";
import { runGit } from "../git/env.ts";
import { repoDir } from "../git/repos.ts";
import { err, ok, type Result } from "../kernel/result.ts";
export type ChapterActError = ChapterError | "forbidden" | "no_issue" | "unfinished" | "no_branch" | "tag_exists" | "git";
/** A person who administers the repository, never an agent. */
function owner(app: App, actor: User | undefined, repo: Repo): actor is User {
  return actor !== undefined && actor.kind !== "agent" && canAdmin(app.db, repo, actor);
}
export function draft(app: App, actor: User | undefined, repo: Repo, input: { name: string; means?: string }): Result<Chapter, ChapterActError> {
  if (!owner(app, actor, repo)) return err("forbidden");
  const made = draftChapter(app.db, repo.id, input, actor.id);
  if (made.ok) app.bus.append({ kind: "chapter.drafted", repoId: repo.id, actorId: actor.id, payload: { name: made.value.name } });
  return made;
}
export function open(app: App, actor: User | undefined, repo: Repo, name: string, now = new Date()): Result<Chapter, ChapterActError> {
  if (!owner(app, actor, repo)) return err("forbidden");
  const chapter = getChapter(app.db, repo.id, name);
  if (chapter === undefined) return err("not_found");
  const started = startChapter(app.db, chapter, now);
  if (started.ok) app.bus.append({ kind: "chapter.opened", repoId: repo.id, actorId: actor.id, payload: { name } });
  return started;
}
/** Add an issue to a chapter, or take it out (`add` false): the owner's act, recorded. */
export function fill(app: App, actor: User | undefined, repo: Repo, name: string, number: number, add: boolean): Result<void, ChapterActError> {
  if (!owner(app, actor, repo)) return err("forbidden");
  const chapter = getChapter(app.db, repo.id, name);
  if (chapter === undefined) return err("not_found");
  const issue = getIssue(app.db, repo.id, number);
  if (issue === undefined || issue.kind !== "issue") return err("no_issue");
  const done: Result<void, ChapterActError> = add
    ? putIssue(app.db, chapter, issue.id, actor.id)
    : takeIssueOut(app.db, chapter, issue.id)
      ? ok(undefined)
      : err("not_found");
  if (done.ok) app.bus.append({ kind: add ? "chapter.item_added" : "chapter.item_removed", repoId: repo.id, actorId: actor.id, payload: { name, number } });
  return done;
}
/**
 * Close the book: tag the default branch's tip with the chapter's name, write the notes from what
 * landed, move what is left (only with `ship`) to the next chapter and mark the chapter closed.
 * Nothing starts afterwards: with no chapter open the crew rests (`chapterHold`).
 */
export async function close(
  app: App,
  actor: User | undefined,
  repo: Repo,
  name: string,
  ship: boolean,
  now = new Date(),
): Promise<Result<Chapter, ChapterActError>> {
  if (!owner(app, actor, repo)) return err("forbidden");
  const chapter = getChapter(app.db, repo.id, name);
  if (chapter === undefined) return err("not_found");
  if (chapter.state === "closed") return err("closed");
  if (chapter.state !== "open") return err("not_draft");
  const items = itemsOf(app.db, chapter);
  const left = items.filter((i) => i.status !== "done");
  if (left.length > 0 && !ship) return err("unfinished");
  const dir = repoDir(app.reposRoot, repo.ownerName, repo.name);
  const tipped = await runGit(["rev-parse", "--verify", "--quiet", `refs/heads/${repo.defaultBranch}^{commit}`], { cwd: dir });
  if (!tipped.ok) return err("no_branch");
  const tip = tipped.value.trim();
  const ref = `refs/tags/${chapter.name}`;
  if ((await runGit(["rev-parse", "--verify", "--quiet", ref], { cwd: dir })).ok) return err("tag_exists");
  if (!(await runGit(["update-ref", ref, tip, ""], { cwd: dir })).ok) return err("git");
  const closedAt = now.toISOString();
  const landed = items
    .filter((i) => i.status === "done")
    .map((item) => ({ item, fix: labelsFor(app.db, item.issueId).some((l) => l.name.toLowerCase() === "bug") }));
  const costUsd = Math.round(landed.reduce((s, l) => s + l.item.costUsd, 0) * 1e4) / 1e4;
  // The tag was created only if absent, so it is ours: whatever stops the book closing takes it back,
  // or a retry would answer `tag_exists` for good.
  let next: Chapter | undefined;
  try {
    app.db.transaction(() => {
      // What is left moves on to the next chapter, drafted when there is none.
      next = left.length === 0 ? undefined : nextChapterOf(app.db, repo.id);
      if (left.length > 0 && next === undefined) {
        const made = draftChapter(app.db, repo.id, { name: nextName(chapter.name) }, actor.id);
        next = made.ok ? made.value : undefined;
      }
      const notes = chapterNotes(chapter.name, chapter.means, landed, left, next?.name, {
        opened: chapter.openedAt ?? closedAt,
        closed: closedAt,
        days: daysBetween(chapter.openedAt ?? closedAt, closedAt),
        doneCount: landed.length,
        costUsd,
      });
      if (next !== undefined) for (const i of left) putIssue(app.db, next, i.issueId, actor.id);
      const closed = app.db
        .query("UPDATE chapter SET state = 'closed', closed_at = ?2, tag_oid = ?3, notes = ?4, cost_usd = ?5 WHERE id = ?1 AND state = 'open'")
        .run(chapter.id, closedAt, tip, notes, costUsd);
      if (closed.changes !== 1) throw new Error("chapter_not_open");
    }).immediate();
  } catch {
    await runGit(["update-ref", "-d", ref, tip], { cwd: dir });
    return err(getChapter(app.db, repo.id, name)?.state === "closed" ? "closed" : "git");
  }
  app.bus.append({ kind: "chapter.closed", repoId: repo.id, actorId: actor.id, payload: { name, tag: chapter.name, shipped: landed.length, moved: left.length, ...(next === undefined ? {} : { into: next.name }) } });
  return ok(getChapter(app.db, repo.id, name)!);
}
/** Open a patch chapter for a closed one, with one click: drafted and opened together. */
export function patch(app: App, actor: User | undefined, repo: Repo, closedName: string, now = new Date()): Result<Chapter, ChapterActError> {
  if (!owner(app, actor, repo)) return err("forbidden");
  const closed = getChapter(app.db, repo.id, closedName);
  if (closed === undefined) return err("not_found");
  if (closed.state !== "closed") return err("not_draft");
  if (openChapterOf(app.db, repo.id) !== undefined) return err("already_open");
  let name = patchName(closed.name);
  while (getChapter(app.db, repo.id, name) !== undefined) name = patchName(name);
  const made = draftChapter(app.db, repo.id, { name, means: `Fixes for what ${closed.name} shipped.`, patchOf: closed.id }, actor.id);
  if (!made.ok) return made;
  const started = startChapter(app.db, made.value, now);
  if (started.ok) app.bus.append({ kind: "chapter.opened", repoId: repo.id, actorId: actor.id, payload: { name, patchOf: closed.name } });
  return started;
}
/**
 * A planner's new issue while a chapter is open: a defect of a chapter item joins the chapter; any
 * other waits in the next chapter, or, with none drafted, behind the Later gate where the owner
 * sees it queued. The planner never adds scope to the open chapter.
 */
export function keepWithinChapter(app: App, repo: Repo, issue: Issue, planner: User): void {
  const placed = placeNewIssue(app.db, repo.id, issue.id, issue.body);
  if (placed === undefined) return;
  if (placed === "later") {
    const gate = laterGate(app.db, repo.id);
    const gateIssue = gate === undefined ? undefined : getIssue(app.db, repo.id, gate);
    if (gateIssue !== undefined) addDependency(app.db, issue, gateIssue, planner.id);
    return;
  }
  putIssue(app.db, placed.chapter, issue.id, planner.id);
  app.bus.append({ kind: "chapter.item_added", repoId: repo.id, actorId: planner.id, payload: { name: placed.chapter.name, number: issue.number, scope: placed.scope } });
}
/** What each refusal says, in the words every door uses. */
export const CHAPTER_WORDS: Readonly<Record<ChapterActError, string>> = {
  invalid_name: "A chapter's name is letters, digits, dots, dashes and underscores, at most 40 (it becomes the git tag).",
  means_too_long: "What done means is one sentence, at most 300 characters.",
  exists: "A chapter with that name already exists.",
  already_open: "Another chapter is already open: a repository has one open chapter at a time.",
  not_draft: "That chapter is not open for this.",
  closed: "A closed chapter cannot be changed or reopened; open a patch chapter instead.",
  not_found: "No such chapter, or nothing to do.",
  forbidden: "Only a person who administers this repository opens, fills and closes chapters.",
  no_issue: "No such issue here.",
  unfinished: "Items are still open. Ship the chapter to move them to the next one and close the book.",
  no_branch: "The default branch has no commit to tag yet.",
  tag_exists: "A git tag with that name already exists.",
  git: "The tag could not be written.",
};
@@ -25,6 +25,8 @@
import type { App } from "../app.ts";
import { adoptResolution } from "../core/trusted_sources.ts";
import { crewRole, isCrew } from "../core/agents.ts";
import { pausedUntil } from "../core/planner_pause.ts";
import { keepWithinChapter } from "./chapters.ts";
import { inheritChapter } from "../core/chapters.ts";
import { moveBlockersToChildren } from "../core/dependencies.ts";
import {
  addComment as insertComment,
@@ -118,6 +120,9 @@
export function openIssue(
    sealed: input.sealed === true,
  });
  if (!created.ok) return created;
  // A chapter is open (#11603): the planner's issue waits in the next chapter, never in this one.
  if (user.value.kind === "agent" && crewRole(app.db, repo.id, user.value.id) === "planner")
    keepWithinChapter(app, repo, created.value, user.value);
  app.bus.append({
    kind: "issue.opened",
    repoId: repo.id,
@@ -522,8 +527,11 @@
export function setIssueState(
    return written;
  })();
  if (!changed) return ok(getIssueById(app.db, issue.id) ?? issue);
  if (children.length > 0)
  if (children.length > 0) {
    moveBlockersToChildren(app.db, issue, children, user.value.id);
    // The parts of a split stay in the chapter the issue was in (#11603).
    inheritChapter(app.db, issue, children, user.value.id);
  }
  app.bus.append({
    kind: `${issue.kind}.${state === "closed" ? "closed" : "reopened"}`,
    repoId: repo.id,
@@ -0,0 +1,3 @@
import { REPO, type Route } from "../shared.ts";
export const route: Route = { method: "get", path: `${REPO}/chapters`, summary: "The repository's chapters (a version with an end): the open one, the drafts waiting after it and the closed ones, each with its name, what done means, state, and its list of issues (done only when live and proven, building, left), progress and the date it finishes at the current pace; a closed chapter carries its tag, notes, cost and the day it closed", auth: false, role: "anonymous" };
@@ -134,6 +134,7 @@
export { route as getApiV1ReposOwnerNameBuilds } from "./getApiV1ReposOwnerNameB
export { route as getApiV1ReposOwnerNameBuildsLabelCart } from "./getApiV1ReposOwnerNameBuildsLabelCart.ts";
export { route as getApiV1ReposOwnerNameBuildsLabelShots } from "./getApiV1ReposOwnerNameBuildsLabelShots.ts";
export { route as getApiV1ReposOwnerNameBuildsLabelShotsLooks } from "./getApiV1ReposOwnerNameBuildsLabelShotsLooks.ts";
export { route as getApiV1ReposOwnerNameChapters } from "./getApiV1ReposOwnerNameChapters.ts";
export { route as getApiV1ReposOwnerNameCommits } from "./getApiV1ReposOwnerNameCommits.ts";
export { route as getApiV1ReposOwnerNameCommitsOid } from "./getApiV1ReposOwnerNameCommitsOid.ts";
export { route as getApiV1ReposOwnerNameCommitsOidCheck } from "./getApiV1ReposOwnerNameCommitsOidCheck.ts";
@@ -317,6 +318,8 @@
export { route as postApiV1ReposOwnerNameBuildsLabelShots } from "./postApiV1Rep
export { route as postApiV1ReposOwnerNameBuildsLabelShotsFile } from "./postApiV1ReposOwnerNameBuildsLabelShotsFile.ts";
export { route as postApiV1ReposOwnerNameBuildsLabelShotsLooks } from "./postApiV1ReposOwnerNameBuildsLabelShotsLooks.ts";
export { route as postApiV1ReposOwnerNameBuildsPreview } from "./postApiV1ReposOwnerNameBuildsPreview.ts";
export { route as postApiV1ReposOwnerNameChapters } from "./postApiV1ReposOwnerNameChapters.ts";
export { route as postApiV1ReposOwnerNameChaptersChapterVerb } from "./postApiV1ReposOwnerNameChaptersChapterVerb.ts";
export { route as postApiV1ReposOwnerNameChecksRecheck } from "./postApiV1ReposOwnerNameChecksRecheck.ts";
export { route as postApiV1ReposOwnerNameContents } from "./postApiV1ReposOwnerNameContents.ts";
export { route as postApiV1ReposOwnerNameContribute } from "./postApiV1ReposOwnerNameContribute.ts";
@@ -0,0 +1,3 @@
import { REPO, type Route } from "../shared.ts";
export const route: Route = { method: "post", path: `${REPO}/chapters`, summary: "Draft a chapter: `name` (the git tag it will carry, at most 40 characters) and `means`, one sentence of what done means. Only a person who administers the repository", auth: true, role: "member", body: { name: "string" } };
@@ -0,0 +1,3 @@
import { REPO, type Route } from "../shared.ts";
export const route: Route = { method: "post", path: `${REPO}/chapters/{chapter}/{verb}`, summary: "Act on a chapter. `verb` is `open` (the repository's one open chapter, from now), `add` or `remove` (`number`: an issue; the owner's act, recorded), `ship` (tag the default branch with the chapter's name, write its notes from what landed, move what is left to the next chapter and close it) or `patch` (open a patch chapter for a closed one). Only a person who administers the repository; a closed chapter cannot be reopened", auth: true, role: "member" };
@@ -17,6 +17,7 @@
const ALIAS: Readonly<Record<string, string>> = {
  contribute: "forks",
  queue: "gates",
  growth: "issues",
  chapters: "issues",
  checks: "pulls",
  conversation: "conversations",
  "conversation-confirms": "conversations",
@@ -0,0 +1,54 @@
/**
 * A closed chapter's notes (#11603), written from what landed: plain sentences, grouped, each with
 * who built it and what it cost, then what was moved on. Pure text from plain data; no model.
 */
import type { Item } from "./chapters.ts";
export interface Figures {
  readonly opened: string;
  readonly closed: string;
  readonly days: number;
  readonly doneCount: number;
  readonly costUsd: number;
}
const usd = (n: number): string => `$${n.toFixed(2)}`;
/** Whole days from `a` to `b`, at least one. */
export function daysBetween(a: string, b: string): number {
  return Math.max(1, Math.round((Date.parse(b) - Date.parse(a)) / 86_400_000));
}
/** One sentence for a landed item. */
export function sentence(i: Item): string {
  const by = i.builder === null ? "" : ` Built by ${i.builder}.`;
  const cost = i.costUsd > 0 ? ` Cost ${usd(i.costUsd)}.` : "";
  const title = i.title.trim().replace(/[.\s]+$/, "");
  return `- ${title} (#${i.number}).${by}${cost}`;
}
/** The notes: fixes and additions grouped, then what moved to the next chapter. */
export function chapterNotes(
  name: string,
  means: string,
  landed: readonly { item: Item; fix: boolean }[],
  moved: readonly Item[],
  next: string | undefined,
  figures: Figures,
): string {
  const lines = [`# ${name}`, ""];
  if (means !== "") lines.push(means, "");
  lines.push(
    `Shipped ${figures.closed.slice(0, 10)}: ${figures.doneCount} ${figures.doneCount === 1 ? "item" : "items"} in ${figures.days} ${figures.days === 1 ? "day" : "days"}, costing ${usd(figures.costUsd)}.`,
    "",
  );
  const added = landed.filter((l) => !l.fix);
  const fixed = landed.filter((l) => l.fix);
  if (added.length > 0) lines.push("## Added", ...added.map((l) => sentence(l.item)), "");
  if (fixed.length > 0) lines.push("## Fixed", ...fixed.map((l) => sentence(l.item)), "");
  if (landed.length === 0) lines.push("Nothing had landed when this chapter closed.", "");
  if (moved.length > 0 && next !== undefined)
    lines.push(`## Moved to ${next}`, ...moved.map((m) => `- ${m.title.trim()} (#${m.number})`), "");
  return `${lines.join("\n").trimEnd()}\n`;
}
@@ -0,0 +1,380 @@
/**
 * Chapters (#11603): a named list of a repository's issues that is finished, tagged and closed.
 * A repository has at most one open chapter and any number drafted after it. While one is open the
 * crew builds only what is in it; once the last is closed the crew rests until the owner opens the
 * next. A repository with no chapter is left alone: continuous flow, as before.
 *
 * Plain data in and out: the db, ids, a clock. The acts (who may, the tag, the events) are in
 * `actions/chapters.ts`; the closing words are in `core/chapter_notes.ts`.
 */
import type { Database } from "bun:sqlite";
import { releaseOfPull } from "../release/record.ts";
import { id } from "../kernel/id.ts";
import { err, ok, type Result } from "../kernel/result.ts";
import { closesFromBody, getPull } from "./pulls.ts";
import type { Issue } from "./issues.ts";
export type ChapterState = "draft" | "open" | "closed";
export interface Chapter {
  readonly id: string;
  readonly repoId: string;
  readonly name: string;
  readonly means: string;
  readonly state: ChapterState;
  readonly position: number;
  readonly patchOf: string | null;
  readonly createdAt: string;
  readonly openedAt: string | null;
  readonly closedAt: string | null;
  readonly tagOid: string | null;
  readonly notes: string;
  readonly costUsd: number | null;
}
interface Row {
  id: string;
  repo_id: string;
  name: string;
  means: string;
  state: ChapterState;
  position: number;
  patch_of: string | null;
  created_at: string;
  opened_at: string | null;
  closed_at: string | null;
  tag_oid: string | null;
  notes: string;
  cost_usd: number | null;
}
const toChapter = (r: Row): Chapter => ({
  id: r.id,
  repoId: r.repo_id,
  name: r.name,
  means: r.means,
  state: r.state,
  position: r.position,
  patchOf: r.patch_of,
  createdAt: r.created_at,
  openedAt: r.opened_at,
  closedAt: r.closed_at,
  tagOid: r.tag_oid,
  notes: r.notes,
  costUsd: r.cost_usd,
});
/** A chapter's name is also its git tag: a short, plain ref name. */
export const NAME = /^[A-Za-z0-9][A-Za-z0-9._-]{0,39}$/;
export const MAX_MEANS = 300;
export type ChapterError = "invalid_name" | "means_too_long" | "exists" | "already_open" | "not_draft" | "closed" | "not_found";
export function listChapters(db: Database, repoId: string): Chapter[] {
  return db
    .query<Row, [string]>(
      `SELECT * FROM chapter WHERE repo_id = ?1
        ORDER BY CASE state WHEN 'open' THEN 0 WHEN 'draft' THEN 1 ELSE 2 END, position, created_at`,
    )
    .all(repoId)
    .map(toChapter);
}
export function getChapter(db: Database, repoId: string, name: string): Chapter | undefined {
  const row = db.query<Row, [string, string]>("SELECT * FROM chapter WHERE repo_id = ?1 AND name = ?2").get(repoId, name);
  return row === null ? undefined : toChapter(row);
}
export function getChapterById(db: Database, chapterId: string): Chapter | undefined {
  const row = db.query<Row, [string]>("SELECT * FROM chapter WHERE id = ?1").get(chapterId);
  return row === null ? undefined : toChapter(row);
}
/** The repository's open chapter, if it has one. */
export function openChapterOf(db: Database, repoId: string): Chapter | undefined {
  const row = db.query<Row, [string]>("SELECT * FROM chapter WHERE repo_id = ?1 AND state = 'open'").get(repoId);
  return row === null ? undefined : toChapter(row);
}
/** The drafted chapter that comes next: the one first in line. */
export function nextChapterOf(db: Database, repoId: string): Chapter | undefined {
  const row = db
    .query<Row, [string]>("SELECT * FROM chapter WHERE repo_id = ?1 AND state = 'draft' ORDER BY position, created_at LIMIT 1")
    .get(repoId);
  return row === null ? undefined : toChapter(row);
}
/** Draft a chapter, last in line. A patch chapter names the closed one it fixes. */
export function draftChapter(
  db: Database,
  repoId: string,
  input: { name: string; means?: string; patchOf?: string },
  byId: string,
): Result<Chapter, ChapterError> {
  const name = input.name.trim();
  const means = (input.means ?? "").trim();
  if (!NAME.test(name) || name.endsWith(".") || name.includes("..")) return err("invalid_name");
  if (means.length > MAX_MEANS) return err("means_too_long");
  if (getChapter(db, repoId, name) !== undefined) return err("exists");
  const last = db
    .query<{ p: number | null }, [string]>("SELECT MAX(position) AS p FROM chapter WHERE repo_id = ?1")
    .get(repoId)?.p;
  const chapterId = id();
  db.query(
    `INSERT INTO chapter (id, repo_id, name, means, position, patch_of, created_by) VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7)`,
  ).run(chapterId, repoId, name, means, (last ?? 0) + 1, input.patchOf ?? null, byId);
  return ok(getChapterById(db, chapterId)!);
}
/** Open a drafted chapter: the repository's one open chapter, from now. */
export function startChapter(db: Database, chapter: Chapter, now: Date): Result<Chapter, ChapterError> {
  if (chapter.state === "closed") return err("closed");
  if (chapter.state === "open") return err("already_open");
  if (openChapterOf(db, chapter.repoId) !== undefined) return err("already_open");
  db.query("UPDATE chapter SET state = 'open', opened_at = ?2 WHERE id = ?1").run(chapter.id, now.toISOString());
  return ok(getChapterById(db, chapter.id)!);
}
/** The next name after `name`: v1.0.0 → v2.0.0. */
export function nextName(name: string): string {
  const m = /^(\D*)(\d+)(.*)$/.exec(name);
  if (m === null) return `${name}-next`;
  return `${m[1]}${Number(m[2]) + 1}${(m[3] ?? "").replace(/\d+/g, "0")}`;
}
/** A patch's name after `name`: v1.0.0 → v1.0.1; a name without three numbers gets `.1`. */
export function patchName(name: string): string {
  const m = /^(.*\d+\.\d+\.)(\d+)$/.exec(name);
  return m === null ? `${name}.1` : `${m[1]}${Number(m[2]) + 1}`;
}
// ---- items ----
/** The chapter an issue is in, if any. */
export function chapterOfIssue(db: Database, issueId: string): Chapter | undefined {
  const row = db
    .query<Row, [string]>("SELECT c.* FROM chapter c JOIN chapter_item i ON i.chapter_id = c.id WHERE i.issue_id = ?1")
    .get(issueId);
  return row === null ? undefined : toChapter(row);
}
/** Put an issue in a chapter (moving it from another that is not closed). Closed chapters hold their list. */
export function putIssue(db: Database, chapter: Chapter, issueId: string, byId: string | undefined): Result<void, ChapterError> {
  if (chapter.state === "closed") return err("closed");
  const from = chapterOfIssue(db, issueId);
  if (from?.state === "closed") return err("closed");
  db.query(
    `INSERT INTO chapter_item (issue_id, chapter_id, by_id) VALUES (?1, ?2, ?3)
     ON CONFLICT(issue_id) DO UPDATE SET chapter_id = ?2, by_id = ?3, at = strftime('%Y-%m-%dT%H:%M:%fZ','now')`,
  ).run(issueId, chapter.id, byId ?? null);
  return ok(undefined);
}
export function takeIssueOut(db: Database, chapter: Chapter, issueId: string): boolean {
  if (chapter.state === "closed") return false;
  return db.query("DELETE FROM chapter_item WHERE issue_id = ?1 AND chapter_id = ?2").run(issueId, chapter.id).changes > 0;
}
export type ItemStatus = "done" | "building" | "left";
export interface Item {
  readonly issueId: string;
  readonly number: number;
  readonly title: string;
  readonly status: ItemStatus;
  /** When it went live and proven; null until then. */
  readonly doneAt: string | null;
  /** The pull that shipped it, when one did. */
  readonly pull: number | null;
  readonly builder: string | null;
  readonly costUsd: number;
}
interface ItemRow {
  id: string;
  number: number;
  title: string;
  state: "open" | "closed";
}
interface PullFact {
  readonly id: string;
  readonly number: number;
  readonly mergedAt: string | null;
  readonly closes: readonly number[];
}
const round4 = (n: number): number => Math.round(n * 1e4) / 1e4;
/**
 * Every pull of the repository with the issue numbers it closes, read once for the whole list: the
 * list's cost is one pass over the pulls however many items it holds, never a scan per item.
 */
function pullFacts(db: Database, repoId: string): PullFact[] {
  return db
    .query<{ id: string; number: number; body: string; at: string | null }, [string]>(
      `SELECT issue.id AS id, issue.number AS number, issue.body AS body, pull.merged_at AS at
         FROM pull JOIN issue ON issue.id = pull.issue_id WHERE issue.repo_id = ?1 AND issue.body LIKE '%#%'`,
    )
    .all(repoId)
    .map((r) => ({ id: r.id, number: r.number, mergedAt: r.at, closes: closesFromBody(r.body) }));
}
/** What each issue's own runs spent, by issue id: one grouped read for the repository. */
function runSpend(db: Database, repoId: string): Map<string, number> {
  const rows = db
    .query<{ id: string; usd: number }, [string]>(
      `SELECT run.issue_id AS id, COALESCE(SUM(run.cost_usd), 0) AS usd FROM run JOIN issue ON issue.id = run.issue_id
        WHERE issue.repo_id = ?1 GROUP BY run.issue_id`,
    )
    .all(repoId);
  return new Map(rows.map((r) => [r.id, r.usd]));
}
/**
 * Where an item stands. Done is live and proven: closed, shipped by a merged pull that production's
 * release proof passed for (`release.ok`), never merely merged.
 */
function statusOf(
  db: Database,
  repoId: string,
  row: ItemRow,
  closing: readonly PullFact[],
): Pick<Item, "status" | "doneAt" | "pull" | "builder"> {
  // Merged pulls that close it, newest first: any one of them may be the one production proved.
  const merged =
    row.state === "closed"
      ? closing
          .filter((f) => f.mergedAt !== null)
          .sort((a, b) => (a.mergedAt === b.mergedAt ? b.number - a.number : a.mergedAt! < b.mergedAt! ? 1 : -1))
      : [];
  const first = merged[0];
  for (const m of merged) {
    const proof = releaseOfPull(db, repoId, m.number);
    if (proof !== undefined) return { status: "done", doneAt: proof.createdAt, pull: m.number, builder: getPull(db, repoId, m.number)?.authorName ?? null };
  }
  const active =
    db
      .query<{ n: number }, [string]>("SELECT COUNT(*) AS n FROM run WHERE issue_id = ?1 AND state IN ('queued','running')")
      .get(row.id)?.n ?? 0;
  return { status: active > 0 || first !== undefined || row.state === "closed" ? "building" : "left", doneAt: null, pull: first?.number ?? null, builder: null };
}
/**
 * A closed chapter's list never changes (its items are held, its pulls have landed), so it is read
 * once and kept: a public page or API read of a closed chapter costs a lookup after the first.
 */
const FROZEN_MAX = 200;
const frozen = new Map<string, Item[]>();
/** Forget the kept lists: a test that rebuilds a database. */
export function forgetFrozenItems(): void {
  frozen.clear();
}
/** A chapter's list, in issue order, each item with where it stands and what it cost. */
export function itemsOf(db: Database, chapter: Chapter): Item[] {
  const kept = chapter.state === "closed" ? frozen.get(chapter.id) : undefined;
  if (kept !== undefined) return kept;
  const rows = db
    .query<ItemRow, [string]>(
      `SELECT i.id, i.number, i.title, i.state FROM chapter_item c JOIN issue i ON i.id = c.issue_id
        WHERE c.chapter_id = ?1`,
    )
    .all(chapter.id)
    .sort((a, b) => a.number - b.number);
  const out: Item[] = [];
  if (rows.length > 0) {
    const facts = pullFacts(db, chapter.repoId);
    const spend = runSpend(db, chapter.repoId);
    for (const r of rows) {
      const closing = facts.filter((f) => f.id !== r.id && f.closes.includes(r.number));
      const cost = round4((spend.get(r.id) ?? 0) + closing.reduce((sum, f) => sum + round4(spend.get(f.id) ?? 0), 0));
      out.push({ issueId: r.id, number: r.number, title: r.title, ...statusOf(db, chapter.repoId, r, closing), costUsd: cost });
    }
  }
  if (chapter.state === "closed") {
    if (frozen.size >= FROZEN_MAX) frozen.delete(frozen.keys().next().value!);
    frozen.set(chapter.id, out);
  }
  return out;
}
export interface Progress {
  readonly done: number;
  readonly total: number;
  /** When the list will be finished at the pace so far, or null before there is a pace. */
  readonly finishesOn: string | null;
}
/** Items done against the list, and the day it finishes at the pace since the chapter opened. */
export function progressOf(chapter: Chapter, items: readonly Item[], now: Date): Progress {
  const done = items.filter((i) => i.status === "done").length;
  const total = items.length;
  if (chapter.openedAt === null || done === 0 || done >= total) return { done, total, finishesOn: null };
  const days = Math.max((now.getTime() - Date.parse(chapter.openedAt)) / 86_400_000, 1 / 24);
  const left = (total - done) / (done / days);
  return { done, total, finishesOn: new Date(now.getTime() + left * 86_400_000).toISOString().slice(0, 10) };
}
// ---- the crew's gate ----
/** Whether the repository has closed a chapter and opened none since: the crew rests. */
export function resting(db: Database, repoId: string): boolean {
  return (
    openChapterOf(db, repoId) === undefined &&
    db.query<{ n: number }, [string]>("SELECT COUNT(*) AS n FROM chapter WHERE repo_id = ?1 AND state = 'closed'").get(repoId)!.n > 0
  );
}
/** The issue number a body says it is a defect of: "Defect of #12". */
export function defectOf(body: string): number | undefined {
  const m = /\bdefect (?:of|in|on) #(\d+)\b/i.exec(body);
  return m === null ? undefined : Number(m[1]);
}
/**
 * Why the crew may not start work on this issue now, or null when it may: a chapter is open and the
 * issue (or, for a pull, what it closes) is not in it, or the repository rests between chapters.
 * A repository with no chapter is never held.
 */
export function chapterHold(db: Database, repoId: string, issue: Pick<Issue, "id" | "kind" | "body">): string | null {
  const open = openChapterOf(db, repoId);
  if (open === undefined) return resting(db, repoId) ? "the repository rests between chapters; the owner opens the next" : null;
  const inOpen = (issueId: string): boolean => chapterOfIssue(db, issueId)?.id === open.id;
  if (inOpen(issue.id)) return null;
  if (issue.kind === "pull") {
    const closes = closesFromBody(issue.body);
    if (closes.length === 0) return null;
    for (const n of closes) {
      const target = db.query<{ id: string }, [string, number]>("SELECT id FROM issue WHERE repo_id = ?1 AND number = ?2").get(repoId, n);
      if (target !== null && inOpen(target.id)) return null;
    }
  }
  return `outside ${open.name}: the crew builds only what the open chapter holds`;
}
/**
 * Where an issue the planner opens lands while a chapter is open: a defect of a chapter item joins the
 * chapter; anything else waits in the next chapter. Undefined when no chapter is open (nothing to do)
 * or no later chapter is drafted (the caller sends it to Later).
 */
export function placeNewIssue(db: Database, repoId: string, issueId: string, body: string): { chapter: Chapter; scope: "defect" | "next" } | "later" | undefined {
  const open = openChapterOf(db, repoId);
  if (open === undefined) return undefined;
  const n = defectOf(body);
  if (n !== undefined) {
    const parent = db.query<{ id: string }, [string, number]>("SELECT id FROM issue WHERE repo_id = ?1 AND number = ?2").get(repoId, n);
    if (parent !== null && chapterOfIssue(db, parent.id)?.id === open.id) return { chapter: open, scope: "defect" };
  }
  const next = nextChapterOf(db, repoId);
  return next === undefined ? "later" : { chapter: next, scope: "next" };
}
/** Parts of a split issue stay in its chapter. */
export function inheritChapter(db: Database, parent: Issue, children: readonly Issue[], byId: string | undefined): void {
  const chapter = chapterOfIssue(db, parent.id);
  if (chapter === undefined || chapter.state === "closed") return;
  for (const child of children) putIssue(db, chapter, child.id, byId);
}
@@ -186,6 +186,12 @@
const READER_KINDS: ReadonlySet<string> = new Set([
  "start.made",
  "start.claimed",
  "start.swept",
  // A chapter's drafting, opening, filling and closing are on its public page (#11603).
  "chapter.drafted",
  "chapter.opened",
  "chapter.item_added",
  "chapter.item_removed",
  "chapter.closed",
]);
/**
@@ -0,0 +1,1 @@
53dd8bcfb61b52ada401560dfe3c15dcc8539adda061c7a78283373e384679db
@@ -0,0 +1,32 @@
// `chapter` (#11603): a named list of a repository's issues that is finished, tagged and closed.
// At most one is open per repository (the partial unique index); any number are drafts that wait.
// `chapter_item` puts an issue in at most one chapter. A closed chapter keeps its tag, notes and
// figures forever. New tables and indexes only. Additive.
export default `
  CREATE TABLE chapter (
    id         TEXT PRIMARY KEY,
    repo_id    TEXT NOT NULL REFERENCES repo(id) ON DELETE CASCADE,
    name       TEXT NOT NULL,
    means      TEXT NOT NULL DEFAULT '',
    state      TEXT NOT NULL DEFAULT 'draft' CHECK (state IN ('draft','open','closed')),
    position   INTEGER NOT NULL DEFAULT 0,
    patch_of   TEXT REFERENCES chapter(id) ON DELETE SET NULL,
    created_by TEXT REFERENCES user(id) ON DELETE SET NULL,
    created_at TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ','now')),
    opened_at  TEXT,
    closed_at  TEXT,
    tag_oid    TEXT,
    notes      TEXT NOT NULL DEFAULT '',
    cost_usd   REAL,
    UNIQUE (repo_id, name)
  );
  CREATE UNIQUE INDEX chapter_one_open ON chapter(repo_id) WHERE state = 'open';
  CREATE INDEX chapter_repo ON chapter(repo_id, state, position);
  CREATE TABLE chapter_item (
    issue_id   TEXT PRIMARY KEY REFERENCES issue(id) ON DELETE CASCADE,
    chapter_id TEXT NOT NULL REFERENCES chapter(id) ON DELETE CASCADE,
    by_id      TEXT REFERENCES user(id) ON DELETE SET NULL,
    at         TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ','now'))
  );
  CREATE INDEX chapter_item_chapter ON chapter_item(chapter_id);
  `;
@@ -9,6 +9,7 @@
 */
import { pausedUntil } from "../core/planner_pause.ts";
import { chapterHold } from "../core/chapters.ts";
import { crewFilters, isStrangerPull } from "./stranger.ts";
import { TEMP_FULL } from "../checks/disk_full.ts";
import { freshPullFor } from "./fresh_pull.ts";
@@ -468,6 +469,14 @@
export function queueAgentRun(
  // The owner's switch (#11604): a paused planner starts nothing; builders and reviewers carry on.
  if (crewRole(app.db, repo.id, agent.user.id) === "planner" && pausedUntil(app.db, repo.id, new Date()) !== null)
    return undefined;
  // A chapter is open (#11603): builders and reviewers start only what it holds, and the crew rests
  // between chapters. A planner plans (its scope is kept where it opens issues); a run carrying on finishes.
  if (
    again === undefined &&
    crewRole(app.db, repo.id, agent.user.id) !== "planner" &&
    chapterHold(app.db, repo.id, issue) !== null
  )
    return undefined;
  // An archived repository starts nothing new; a run carrying on (`again`)
  // is one already going, and finishes. A first run
  // (`attempt` 0, as a conflict or converge run is queued) is new.
@@ -383,6 +383,7 @@
import { TEMPLATE_ERRORS } from "../apps/template_tip.ts";
import { flagsRoutes } from "./api/flags.ts";
import { appTemplateRoutes } from "./api/app_templates.ts";
import { issueRoutes, labelsHandler } from "./api/issues.ts";
import { chapterRoutes } from "./api/chapters.ts";
import { FORGE_NOT_CARRIED } from "../origins/words.ts";
import { forgeOriginRoutes } from "./api/forge_origin.ts";
import { userRoutes } from "./api/user.ts";
@@ -2171,6 +2172,7 @@
export function apiRoutes(router: Router<Handler>): void {
  // ── issues — the label-as-queue surface automation drives ────────────
  issueRoutes(router);
  chapterRoutes(router);
  reportRoutes(router);
  startRoutes(router);
@@ -0,0 +1,76 @@
/**
 * Chapters over the API (#11603), in the same words as the page: the list with each chapter's items,
 * and the owner's acts (draft, open, add, remove, ship, patch). The rules are in `core/chapters.ts`
 * and the acts in `actions/chapters.ts`; this only reads the request and answers the result.
 */
import { CHAPTER_WORDS, close, draft, fill, open, patch } from "../../actions/chapters.ts";
import { itemsOf, listChapters, progressOf, type Chapter } from "../../core/chapters.ts";
import type { Handler } from "../context.ts";
import { apiError, body, json, notFound, requireScope } from "../respond.ts";
import { loadRepo } from "../api.ts";
import { notePhase, takeSessionTime } from "../../core/route_timing.ts";
import type { Router } from "../router.ts";
const shape = (db: Parameters<typeof itemsOf>[0], c: Chapter, now: Date) => {
  const items = itemsOf(db, c);
  return {
    name: c.name,
    means: c.means,
    state: c.state,
    patchOf: c.patchOf,
    openedAt: c.openedAt,
    closedAt: c.closedAt,
    tag: c.state === "closed" ? { name: c.name, oid: c.tagOid } : null,
    notes: c.notes,
    costUsd: c.costUsd,
    progress: progressOf(c, items, now),
    items: items.map((i) => ({ number: i.number, title: i.title, status: i.status, doneAt: i.doneAt, pull: i.pull, builder: i.builder, costUsd: i.costUsd })),
  };
};
export function chapterRoutes(router: Router<Handler>): void {
  router.add("GET", "/api/v1/repos/:owner/:name/chapters", (ctx) => {
    notePhase(ctx.request, "session", takeSessionTime(ctx.request));
    const repo = loadRepo(ctx);
    if (!repo) return notFound();
    const now = new Date();
    return json({ chapters: listChapters(ctx.app.db, repo.id).map((c) => shape(ctx.app.db, c, now)) }, 200, { "cache-control": "no-store" });
  });
  router.add("POST", "/api/v1/repos/:owner/:name/chapters", async (ctx) => {
    const denied = requireScope(ctx, "rw");
    if (denied) return denied;
    const repo = loadRepo(ctx);
    if (!repo) return notFound();
    const input = await body(ctx.request);
    const made = draft(ctx.app, ctx.auth.user, repo, {
      name: typeof input["name"] === "string" ? input["name"] : "",
      means: typeof input["means"] === "string" ? input["means"] : "",
    });
    if (!made.ok) return apiError(made.error, made.error === "forbidden" ? 403 : made.error === "exists" ? 409 : 422, CHAPTER_WORDS[made.error]);
    return json(shape(ctx.app.db, made.value, new Date()), 201);
  });
  router.add("POST", "/api/v1/repos/:owner/:name/chapters/:chapter/:verb", async (ctx) => {
    const denied = requireScope(ctx, "rw");
    if (denied) return denied;
    const repo = loadRepo(ctx);
    if (!repo) return notFound();
    const input = await body(ctx.request);
    const name = ctx.params.chapter ?? "";
    const verb = ctx.params.verb ?? "";
    const number = typeof input["number"] === "number" ? input["number"] : Number.NaN;
    const done =
      verb === "open" ? open(ctx.app, ctx.auth.user, repo, name)
        : verb === "add" || verb === "remove" ? fill(ctx.app, ctx.auth.user, repo, name, number, verb === "add")
        : verb === "ship" ? await close(ctx.app, ctx.auth.user, repo, name, true)
        : verb === "patch" ? patch(ctx.app, ctx.auth.user, repo, name)
        : null;
    if (done === null) return notFound();
    if (!done.ok)
      return apiError(done.error, done.error === "forbidden" ? 403 : done.error === "not_found" || done.error === "no_issue" ? 404 : 409, CHAPTER_WORDS[done.error]);
    const value = done.value;
    return json(value === undefined ? { ok: true } : shape(ctx.app.db, value, new Date()), 200);
  });
}
@@ -172,6 +172,7 @@
import { apiPage, appApiPage } from "../web/pages/api.ts";
import { flowsCheck, flowsPage, flowsProbe, flowsUpdate } from "../web/pages/flows.ts";
import { findingAccept, findingsPage } from "../web/pages/findings.ts";
import { queuePage, queueSwitch } from "../web/pages/queue.ts";
import { chapterAct, chapterPage, chaptersPage } from "../web/pages/chapters.ts";
import { betAct, betPage, betPropose, betsPage } from "../web/pages/bets.ts";
import { changelogJson, changelogPage } from "../web/pages/changelog.ts";
import { docsFile, docsFolder } from "../web/pages/docs_link.ts";
@@ -1298,6 +1299,10 @@
export function buildRouter(): Router<Handler> {
  router.add("POST", "/:owner/:name/findings/:id/accept", findingAccept);
  router.add("GET", "/:owner/:name/queue", queuePage);
  router.add("POST", "/:owner/:name/queue/planner", queueSwitch);
  router.add("GET", "/:owner/:name/chapters", chaptersPage);
  router.add("POST", "/:owner/:name/chapters", chapterAct);
  router.add("GET", "/:owner/:name/chapters/:chapter", chapterPage);
  router.add("POST", "/:owner/:name/chapters/:chapter/:verb", chapterAct);
  router.add("GET", "/:owner/:name/bets", betsPage);
  router.add("POST", "/:owner/:name/bets/propose", betPropose);
  router.add("GET", "/:owner/:name/bets/:id", betPage);
@@ -0,0 +1,221 @@
/**
 * An app's chapters, in the terminal (#11603): the page's list (`web/pages/chapters.ts`) from the same
 * acts (`actions/chapters.ts`), so the same owner-only gate applies: anyone who can read the repository
 * sees the chapters, only a person who administers it drafts, opens, fills, ships or patches. `n`
 * drafts, `o` opens the one under the cursor, `s` ships it, `p` opens a patch chapter for a closed
 * one, `enter` shows its list, where `a` adds an issue by number and `x` takes the one under the
 * cursor out. Each act is an event on the bus, so an open web page sees it, and this screen follows
 * a change made there.
 */
import { CHAPTER_WORDS, close, draft, fill, open, patch } from "../../actions/chapters.ts";
import { getChapter, itemsOf, listChapters, progressOf, type Chapter, type Item } from "../../core/chapters.ts";
import { canAdmin, type Repo } from "../../core/repos.ts";
import type { Ctx, Screen } from "../app/app.ts";
import type { Command } from "../app/palette.ts";
import { binding } from "../app/keys.ts";
import { style } from "../term/style.ts";
import { truncate } from "../term/width.ts";
import type { Session } from "../session.ts";
import { fill as fillSpace, len, split } from "../ui/layout.ts";
import { ListState, confirmScreen, drawList, live, promptScreen, type ListRow } from "./common.ts";
const isChapterEvent = (kind: string): boolean => kind.startsWith("chapter.") || kind === "release.verified_live";
/** The words under a chapter's name: what done means, then how far it is. */
function chapterRow(f: Session, c: Chapter): ListRow {
  const p = progressOf(c, itemsOf(f.app.db, c), new Date());
  const progress = c.state === "closed" ? "finished" : `${p.done} of ${p.total} done`;
  return { title: `${c.name} — ${c.state}`, note: c.means === "" ? progress : `${c.means} (${progress})` };
}
function itemRow(i: Item): ListRow {
  const where = i.status === "done" ? `live ${(i.doneAt ?? "").slice(0, 10)}` : i.status === "building" ? "building now" : "left";
  return { title: `#${i.number} ${i.title}`, meta: where };
}
/** The mayor's check, as the acts make it: a person who administers the repository. */
const mayAct = (f: Session, repo: Repo): boolean => f.user !== undefined && f.user.kind !== "agent" && canAdmin(f.app.db, repo, f.user);
export function chapterScreen(f: Session, ctx: Ctx, repo: Repo, name: string): Screen {
  const state = new ListState();
  const items = (): Item[] => {
    const c = getChapter(f.app.db, repo.id, name);
    return c === undefined ? [] : itemsOf(f.app.db, c);
  };
  const screen: Screen = {
    title: `${repo.ownerName}/${repo.name} — ${name}`,
    keys: [binding(["j", "k"], "move cursor"), binding(["a"], "add an issue"), binding(["x"], "take it out"), binding(["o"], "open"), binding(["s"], "ship")],
    async load(signal) {
      live(f, signal, { repoId: repo.id, where: (e) => isChapterEvent(e.kind) }, () => ctx.invalidate());
    },
    render(area, s) {
      const c = ctx.theme.c;
      const chapter = getChapter(f.app.db, repo.id, name);
      const all = items();
      const [head, list] = split(area, "v", [len(1), fillSpace(1)]);
      const p = chapter === undefined ? undefined : progressOf(chapter, all, new Date());
      s.text(
        head!.x,
        head!.y,
        truncate(
          chapter === undefined ? "No such chapter." : `${chapter.state}: ${p!.done} of ${p!.total} done${p!.finishesOn === null ? "" : `, finishes ${p!.finishesOn}`}`,
          head!.w,
        ),
        style(c.mutedFg, c.bg),
        head!.x + head!.w,
      );
      drawList(s, list!, c, state, all.map(itemRow));
    },
    key(e) {
      const all = items();
      if (state.key(e, all.length)) return true;
      if (e.ctrl || e.alt) return false;
      if (e.key === "a") {
        ctx.push(
          promptScreen(ctx, screen, {
            title: `Add to ${name}`,
            label: "Issue number",
            onSubmit: (value) => {
              const n = Number(value.replace(/^#/, ""));
              if (!Number.isInteger(n) || n < 1) return "An issue number, like 12.";
              const done = fill(f.app, f.user, repo, name, n, true);
              if (!done.ok) return CHAPTER_WORDS[done.error];
              ctx.invalidate();
              return undefined;
            },
          }),
        );
        return true;
      }
      if (e.key === "x") {
        const at = all[state.index];
        if (at === undefined) return true;
        const done = fill(f.app, f.user, repo, name, at.number, false);
        ctx.toast(done.ok ? `#${at.number} is out of ${name}.` : CHAPTER_WORDS[done.error], done.ok ? undefined : "danger");
        ctx.invalidate();
        return true;
      }
      if (e.key === "o" || e.key === "s") {
        act(f, ctx, repo, screen, name, e.key);
        return true;
      }
      return false;
    },
  };
  return screen;
}
/** Open or ship a chapter by name; shipping asks first, since it tags and closes. */
function act(f: Session, ctx: Ctx, repo: Repo, parent: Screen, name: string, key: "o" | "s"): void {
  if (key === "o") {
    const done = open(f.app, f.user, repo, name);
    ctx.toast(done.ok ? `${name} is open.` : CHAPTER_WORDS[done.error], done.ok ? undefined : "danger");
    ctx.invalidate();
    return;
  }
  ctx.push(
    confirmScreen(ctx, parent, {
      title: `Ship ${name}?`,
      body: [`Tags the default branch ${name}, writes its notes and closes it;`, "what is not done moves to the next chapter."],
      actions: [{ label: "Ship it" }, { label: "Cancel", variant: "ghost" }],
      yesNo: true,
      onChoose: (i) => {
        if (i !== 0) return;
        void ctx.track(
          close(f.app, f.user, repo, name, true).then((done) => {
            ctx.toast(done.ok ? `${name} is finished.` : CHAPTER_WORDS[done.error], done.ok ? undefined : "danger");
            ctx.invalidate();
          }),
        );
      },
    }),
  );
}
export function chaptersScreen(f: Session, ctx: Ctx, repo: Repo): Screen {
  const state = new ListState();
  const all = (): Chapter[] => listChapters(f.app.db, repo.id);
  const screen: Screen = {
    title: `${repo.ownerName}/${repo.name} — Chapters`,
    keys: [
      binding(["j", "k"], "move cursor"),
      binding(["enter"], "its list"),
      binding(["n"], "draft"),
      binding(["o"], "open"),
      binding(["s"], "ship"),
      binding(["p"], "patch"),
    ],
    async load(signal) {
      live(f, signal, { repoId: repo.id, where: (e) => isChapterEvent(e.kind) }, () => ctx.invalidate());
    },
    render(area, s) {
      const c = ctx.theme.c;
      const chapters = all();
      const [head, list] = split(area, "v", [len(1), fillSpace(1)]);
      s.text(
        head!.x,
        head!.y,
        truncate(
          chapters.length === 0 ? "No chapter yet: the crew works continuously." : mayAct(f, repo) ? "n drafts, o opens, s ships, p patches, enter shows the list." : "A person who administers this app drafts and ships chapters.",
          head!.w,
        ),
        style(c.mutedFg, c.bg),
        head!.x + head!.w,
      );
      drawList(s, list!, c, state, chapters.map((ch) => chapterRow(f, ch)));
    },
    key(e) {
      const chapters = all();
      if (state.key(e, chapters.length)) return true;
      if (e.ctrl || e.alt) return false;
      const at = chapters[state.index];
      if (e.key === "n") {
        ctx.push(
          promptScreen(ctx, screen, {
            title: "Draft a chapter",
            label: "Name (it becomes the git tag)",
            placeholder: "v1.0.0",
            onSubmit: (value) => {
              const made = draft(f.app, f.user, repo, { name: value });
              if (!made.ok) return CHAPTER_WORDS[made.error];
              ctx.invalidate();
              return undefined;
            },
          }),
        );
        return true;
      }
      if (at === undefined) return e.key === "o" || e.key === "s" || e.key === "p" || e.key === "enter";
      if (e.key === "enter") {
        ctx.push(chapterScreen(f, ctx, repo, at.name));
        return true;
      }
      if (e.key === "o" || e.key === "s") {
        act(f, ctx, repo, screen, at.name, e.key);
        return true;
      }
      if (e.key === "p") {
        const done = patch(f.app, f.user, repo, at.name);
        ctx.toast(done.ok ? `${done.value.name} is open.` : CHAPTER_WORDS[done.error], done.ok ? undefined : "danger");
        ctx.invalidate();
        return true;
      }
      return false;
    },
  };
  return screen;
}
/** The palette's command while a repository is open. */
export function chaptersCommands(f: Session, ctx: Ctx, repo: Repo | undefined): Command[] {
  if (repo === undefined) return [];
  return [
    {
      id: "chapters-app",
      title: `${repo.ownerName}/${repo.name} — Chapters`,
      hint: "a version with an end: draft, fill, open, ship, patch",
      run: () => ctx.push(chaptersScreen(f, ctx, repo)),
    },
  ];
}
@@ -169,6 +169,7 @@
import { appEnvCommands } from "./appenv.ts";
import { variantsCommands } from "./variants.ts";
import { autonomyCommands } from "./autonomy.ts";
import { trafficCommands } from "./trafficview.ts";
import { chaptersCommands } from "./chapters.ts";
import { schedulesCommands } from "./schedules.ts";
import { queueCommands } from "./queuegrowth.ts";
import { blockedCommands } from "./blocked.ts";
@@ -1995,6 +1996,7 @@
export function workspaceScreen(
      ...autonomyCommands(f, ctx, repo),
      ...trafficCommands(f, ctx, repo),
      ...schedulesCommands(f, ctx, repo),
      ...chaptersCommands(f, ctx, repo),
      ...queueCommands(f, ctx, repo),
      ...blockedCommands(f, ctx, repo),
      ...statementCommands(f, ctx, repo),
@@ -0,0 +1,169 @@
/**
 * Chapters (#11603): `/:owner/:name/chapters` lists the open chapter, the drafts after it and the
 * closed ones; `/:owner/:name/chapters/:chapter` is the list being crossed off — done items struck
 * through with the day they went live, what is building, what is left, the date at the current pace —
 * or, once closed, the one page that says it is finished. Server-rendered, no script; every change
 * is a same-origin POST by a person who administers the repository.
 */
import { CHAPTER_WORDS, close, draft, fill, open, patch } from "../../actions/chapters.ts";
import { getChapter, itemsOf, listChapters, progressOf, type Chapter, type Item } from "../../core/chapters.ts";
import { canAdmin, type Repo } from "../../core/repos.ts";
import { notePhase, takeSessionTime } from "../../core/route_timing.ts";
import type { Ctx } from "../../http/context.ts";
import { crumbsFor, loadRepo, notFoundPage, pageHead, repoBase, repoHeader, repoPalette } from "../chrome.ts";
import { field, readForm } from "../form.ts";
import { html, type Html } from "../html.ts";
import { flashTo, page } from "../layout.ts";
import { badge, btn, row } from "../ui.ts";
const usd = (n: number): string => `$${n.toFixed(2)}`;
const day = (iso: string | null): string => (iso === null ? "" : iso.slice(0, 10));
const isOwner = (ctx: Ctx, repo: Repo): boolean =>
  ctx.auth.user !== undefined && ctx.auth.user.kind !== "agent" && canAdmin(ctx.app.db, repo, ctx.auth.user);
const hrefOf = (repo: Repo, c: Chapter): string => `${repoBase(repo)}/chapters/${encodeURIComponent(c.name)}`;
const STATE_WORDS = { open: "open", draft: "waiting its turn", closed: "closed" } as const;
function itemRow(repo: Repo, i: Item, may: boolean, chapter: Chapter): Html {
  const title = html`<a href="${repoBase(repo)}/issues/${i.number}">#${i.number}</a> ${i.status === "done" ? html`<s>${i.title}</s>` : i.title}`;
  const trail =
    i.status === "done"
      ? badge(`live ${day(i.doneAt)}`, { tone: "success" })
      : i.status === "building"
        ? badge("building now")
        : badge("left", { variant: "outline" });
  const out =
    may && chapter.state !== "closed"
      ? html`<form method="post" action="${hrefOf(repo, chapter)}/remove"><input type="hidden" name="number" value="${String(i.number)}">${btn("Take out", { variant: "ghost" })}</form>`
      : null;
  return html`<li data-item="${String(i.number)}" data-status="${i.status}">${row({ title, trail })}${out}</li>`;
}
// GET /:owner/:name/chapters
export function chaptersPage(ctx: Ctx): Response {
  notePhase(ctx.request, "session", takeSessionTime(ctx.request));
  const repo = loadRepo(ctx);
  if (!repo) return notFoundPage(ctx);
  const may = isOwner(ctx, repo);
  const all = listChapters(ctx.app.db, repo.id);
  const rendering = performance.now();
  const rows = all.map((c) =>
    row({
      href: hrefOf(repo, c),
      nav: true,
      title: html`${c.name}${c.means === "" ? null : html` — ${c.means}`}`,
      trail: badge(STATE_WORDS[c.state], { tone: c.state === "open" ? "success" : "default" }),
    }),
  );
  const make = may
    ? html`<h2>Draft a chapter</h2>
        <form method="post" action="${repoBase(repo)}/chapters" class="bar">
          <input class="input" name="name" placeholder="v1.0.0" aria-label="Name" required maxlength="40">
          <input class="input" name="means" placeholder="What done means, in one sentence" aria-label="What done means" maxlength="300">
          ${btn("Draft", { variant: "primary" })}
        </form>`
    : null;
  const body = html`${repoHeader(ctx, repo, "issues")}
    ${pageHead("Chapters", { sub: "A chapter is a version with an end: finished, tagged and closed." })}
    ${all.length === 0 ? html`<p>No chapter yet: the crew works continuously. Draft one to say what v1 is.</p>` : html`<ul class="list setting-list">${rows}</ul>`}
    ${make}`;
  const response = page({ ctx, title: `Chapters · ${repo.name}`, crumbs: crumbsFor(repo), palette: repoPalette(ctx, repo), body });
  notePhase(ctx.request, "render", performance.now() - rendering);
  return response;
}
const fact = (name: string, value: string): Html => html`<div class="status-row"><dt>${name}</dt><dd>${value}</dd></div>`;
function finished(repo: Repo, c: Chapter, items: readonly Item[], may: boolean): Html {
  const done = items.filter((i) => i.status === "done");
  const days = c.openedAt === null || c.closedAt === null ? 0 : Math.max(1, Math.round((Date.parse(c.closedAt) - Date.parse(c.openedAt)) / 86_400_000));
  return html`<p data-finished><strong>${c.name} is finished.</strong> ${c.means}</p>
    <dl class="status-rows">
      
        sentinelcrew
        1d ago
        outdated
      
      Principle 7: these are facts (shipped, took, cost, tag), so they are dl rows, not list rows with badges. Badges are for state, not values.
    
      ${fact("Shipped", `${done.length} ${done.length === 1 ? "item" : "items"}`)}
      ${fact("Took", `${days} ${days === 1 ? "day" : "days"}`)}
      ${fact("Cost", usd(c.costUsd ?? 0))}
      ${fact("Tag", `${c.name} ${(c.tagOid ?? "").slice(0, 8)}`)}
    </dl>
    <h2>Notes</h2>
    <pre data-notes>${c.notes}</pre>
    ${may
      ? html`<form method="post" action="${hrefOf(repo, c)}/patch">${btn(`Open a patch chapter for ${c.name}`, { variant: "primary" })}</form>`
      : null}`;
}
// GET /:owner/:name/chapters/:chapter
export function chapterPage(ctx: Ctx): Response {
  notePhase(ctx.request, "session", takeSessionTime(ctx.request));
  const repo = loadRepo(ctx);
  if (!repo) return notFoundPage(ctx);
  const c = getChapter(ctx.app.db, repo.id, ctx.params.chapter ?? "");
  if (c === undefined) return notFoundPage(ctx);
  const may = isOwner(ctx, repo);
  const items = itemsOf(ctx.app.db, c);
  const p = progressOf(c, items, new Date());
  const rendering = performance.now();
  const here = hrefOf(repo, c);
  let main: Html;
  if (c.state === "closed") main = finished(repo, c, items, may);
  else {
    const building = items.filter((i) => i.status === "building");
    const left = items.filter((i) => i.status === "left");
    const done = items.filter((i) => i.status === "done");
    main = html`<p>${c.means}</p>
      <p data-progress>${p.done} of ${p.total} done${p.finishesOn === null ? "" : `; at this pace it finishes ${p.finishesOn}`}.</p>
      
        sentinelcrew
        1d ago
        outdated
      
      Principle 1: the subtitle already says 'waiting its turn'; this paragraph says it a second time. Drop it.
    
      ${items.length === 0 ? html`<p>No issues in this chapter yet.</p>` : null}
      <ul class="list setting-list">${[...done, ...building, ...left].map((i) => itemRow(repo, i, may, c))}</ul>
      ${may
        ? html`<form method="post" action="${here}/add" class="bar">
            <input class="input" name="number" inputmode="numeric" pattern="[0-9]+" placeholder="Issue number" aria-label="Issue number" required>
            ${btn("Add to chapter")}
          </form>
          ${c.state === "draft" ? html`<form method="post" action="${here}/open">${btn("Open this chapter", { variant: "primary" })}</form>` : null}
          ${c.state === "open"
            ? html`<form method="post" action="${here}/ship">${btn(p.done === p.total && p.total > 0 ? "Close the book" : `Ship it, move ${p.total - p.done} to the next`, { variant: "primary" })}</form>`
      
        sentinelcrew
        1d ago
        outdated
      
      Principle 1: this paragraph explains the Ship it button. Put the consequence in the button's label or leave it out; nothing should explain itself twice.
    
            : null}`
        : null}`;
  }
  const body = html`${repoHeader(ctx, repo, "issues")}
    ${pageHead(c.name, { sub: STATE_WORDS[c.state] })}
    ${main}
    <p><a href="${repoBase(repo)}/chapters">All chapters</a></p>`;
  const response = page({ ctx, title: `${c.name} · ${repo.name}`, crumbs: crumbsFor(repo), palette: repoPalette(ctx, repo), body });
  notePhase(ctx.request, "render", performance.now() - rendering);
  return response;
}
/** What a chapter act answers: the page it stays on, with a flash. */
export async function chapterAct(ctx: Ctx): Promise<Response> {
  const repo = loadRepo(ctx);
  if (!repo) return notFoundPage(ctx);
  const form = await readForm(ctx, "rw");
  if (form instanceof Response) return form;
  const list = `${repoBase(repo)}/chapters`;
  const name = ctx.params.chapter;
  const user = ctx.auth.user;
  if (user === undefined) return flashTo(ctx, list, { tone: "danger", message: "Sign in first." });
  const app = ctx.app;
  if (name === undefined) {
    const made = draft(app, user, repo, { name: field(form, "name"), means: field(form, "means") });
    return made.ok
      ? flashTo(ctx, hrefOf(repo, made.value), { message: `Drafted ${made.value.name}.` })
      : flashTo(ctx, list, { tone: "danger", message: CHAPTER_WORDS[made.error] });
  }
  const at = `${list}/${encodeURIComponent(name)}`;
  const verb = ctx.params.verb ?? "";
  const number = Number(field(form, "number"));
  const result =
    verb === "open" ? open(app, user, repo, name)
      : verb === "add" || verb === "remove" ? fill(app, user, repo, name, number, verb === "add")
      : verb === "ship" ? await close(app, user, repo, name, true)
      : verb === "patch" ? patch(app, user, repo, name)
      : null;
  if (result === null) return notFoundPage(ctx);
  if (!result.ok) return flashTo(ctx, at, { tone: "danger", message: CHAPTER_WORDS[result.error] });
  const landed = verb === "patch" && result.value !== undefined ? `${list}/${encodeURIComponent(result.value.name)}` : at;
  return flashTo(ctx, landed, { message: verb === "ship" ? `${name} is shipped.` : "Done." });
}
@@ -86,6 +86,7 @@
export function queuePage(ctx: Ctx): Response {
  const body = html`${repoHeader(ctx, repo, "issues")}
    ${pageHead("Queue", { sub: "Is the work growing or shrinking?" })}
    ${switchRow(repo, until, owner)}
    <p><a href="${base}/chapters">Chapters</a></p>
      
        sentinelcrew
        1d ago
        outdated
      
      Principle 1: the sentence after the link explains what the Chapters page says again in its own subtitle. Keep the link only.
    
    ${aged.length === 0 ? null : html`<ul class="list setting-list">${aged}</ul>`}
    ${growthRows(g)}`;
  const response = page({ ctx, title: `Queue · ${repo.name}`, crumbs: crumbsFor(repo), palette: repoPalette(ctx, repo), body });
@@ -0,0 +1,374 @@
/**
 * Chapters (#11603): with one open the crew starts nothing outside it and the planner's new issues land
 * in the next; an item is struck only when its production proof passed; Ship it with items left moves
 * them, tags, writes notes and closes; afterwards the crew rests until a chapter is opened; a patch
 * chapter opens from a closed one; the owner's page walks open → cross off → ship → finished.
 */
import { afterAll, beforeAll, describe, expect, test } from "bun:test";
import { mkdtemp, rm } from "node:fs/promises";
import { tmpdir } from "node:os";
import { join } from "node:path";
import { newApp } from "../src/actions/apps.ts";
import { close, draft, fill, open, patch } from "../src/actions/chapters.ts";
import { openIssue } from "../src/actions/issues.ts";
import { createApp, type App } from "../src/app.ts";
import { addCrew, createAgentRow, getAgent } from "../src/core/agents.ts";
import { chapterOfIssue, forgetFrozenItems, getChapter, inheritChapter, itemsOf, nextName, patchName, progressOf } from "../src/core/chapters.ts";
import { createIssue, getIssue, type Issue } from "../src/core/issues.ts";
import { getRepo, type Repo } from "../src/core/repos.ts";
import { createToken } from "../src/core/tokens.ts";
import { createUser, type User } from "../src/core/users.ts";
import { queueAgentRun } from "../src/crew/dispatch.ts";
import { runGit } from "../src/git/env.ts";
import { repoDir } from "../src/git/repos.ts";
import { commitFiles } from "../src/git/write.ts";
import { serve, type Servers } from "../src/http/server.ts";
import { chapterScreen, chaptersCommands, chaptersScreen } from "../src/tui/screens/chapters.ts";
import type { Ctx, Screen } from "../src/tui/app/app.ts";
import type { Session } from "../src/tui/session.ts";
import { quietLogs } from "./helpers/globals.ts";
quietLogs();
describe("chapters", () => {
  let dataDir = "";
  let app: App;
  let servers: Servers;
  let owner: User;
  let planner: User;
  let builder: User;
  let repo: Repo;
  let token = "";
  const issues: Issue[] = [];
  const mkIssue = (title: string, body = ""): Issue => {
    const made = createIssue(app.db, { repoId: repo.id, authorId: owner.id, title, body });
    if (!made.ok) throw new Error(String(made.error));
    return made.value;
  };
  const builderAgent = () => getAgent(app.db, builder.id)!;
  /** Whether the dispatcher queues a builder run on the issue; the run is cancelled so the next probe starts clean. */
  const starts = (issue: Issue): boolean => {
    const run = queueAgentRun(app, repo, issue, builderAgent(), "assigned");
    app.db.query("UPDATE run SET state = 'cancelled' WHERE repo_id = ?1").run(repo.id);
    return run !== undefined;
  };
  /** Merge a pull that closes `issue` and, when `proven`, record production's passing proof for it. */
  let pullNo = 5000;
  const land = (issue: Issue, proven: boolean) => {
    app.db.query("UPDATE issue SET state = 'closed', closed_at = ?2 WHERE id = ?1").run(issue.id, "2026-11-10T00:00:00.000Z");
    const n = ++pullNo;
    const pid = `pull${n}`;
    app.db
      .query(`INSERT INTO issue (id, repo_id, number, kind, title, body, author_id, state) VALUES (?1, ?2, ?3, 'pull', ?4, ?5, ?6, 'closed')`)
      .run(pid, repo.id, n, `Build #${issue.number}`, `Closes #${issue.number}`, builder.id);
    app.db
      .query(`INSERT INTO pull (issue_id, base_branch, head_branch, base_oid, head_oid, merged_at) VALUES (?1, 'main', ?2, 'a', 'b', '2026-11-10T00:00:00.000Z')`)
      .run(pid, `b${n}`);
    if (proven)
      app.db
        .query(`INSERT INTO release (sha, repo_id, pull_number, ok, line, created_at) VALUES ('abc', ?1, ?2, 1, 'ok', '2026-11-11T08:00:00.000Z')`)
        .run(repo.id, n);
  };
  beforeAll(async () => {
    dataDir = await mkdtemp(join(tmpdir(), "forge-chapters-"));
    app = createApp({ dataDir, port: 0, host: "forge.test" });
    servers = await serve(app);
    const mk = async (username: string, agent: boolean, roles: string[] = []) => {
      const made = await createUser(app.db, {
        username,
        email: `${username}@forge.test`,
        ...(agent
          ? { agent: true, origin: "agent" as const }
          : { password: "a-good-passphrase", origin: "seed" as const, trusted: true, adminIfFirst: true }),
      });
      if (!made.ok) throw new Error(String(made.error));
      if (agent) createAgentRow(app.db, { userId: made.value.id, roles: roles as never });
      return made.value;
    };
    owner = await mk("alice", false);
    planner = await mk("plan", true, ["planner"]);
    builder = await mk("build", true, ["builder"]);
    const made = await newApp(app, owner, { name: "shop", description: "Words", visibility: "public" });
    if (!made.ok) throw new Error(String(made.error));
    repo = getRepo(app.db, "alice", "shop")!;
    addCrew(app.db, repo.id, planner.id, owner.id, "planner");
    addCrew(app.db, repo.id, builder.id, owner.id, "builder");
    const c = await commitFiles(repoDir(app.reposRoot, "alice", "shop"), {
      branch: repo.defaultBranch,
      message: "first",
      files: [{ path: "README.md", content: "hello" }],
      author: { name: "T", email: "[email protected]" },
    });
    if (!c.ok) throw new Error(JSON.stringify(c.error));
    token = createToken(app.db, owner.id, "t", "rw").token;
    for (const t of ["a", "b", "c"]) issues.push(mkIssue(`Item ${t}`));
  }, 30_000);
  afterAll(async () => {
    servers.stop();
    app.close();
    await rm(dataDir, { recursive: true, force: true, maxRetries: 20, retryDelay: 100 });
  });
  test("the chapter reads walk an index and sort nothing in SQL", () => {
    const sqls = [
      "SELECT i.id, i.number, i.title, i.state FROM chapter_item c JOIN issue i ON i.id = c.issue_id WHERE c.chapter_id = ?1",
      "SELECT c.* FROM chapter c JOIN chapter_item i ON i.chapter_id = c.id WHERE i.issue_id = ?1",
      "SELECT * FROM chapter WHERE repo_id = ?1 AND state = 'open'",
      "SELECT COUNT(*) AS n FROM run WHERE issue_id = ?1 AND state IN ('queued','running')",
    ];
    for (const sql of sqls) {
      const plan = app.db.query(`EXPLAIN QUERY PLAN ${sql}`).all("x").map((r) => (r as { detail: string }).detail);
      expect(plan.filter((d) => d.startsWith("SCAN") || d.includes("TEMP B-TREE"))).toEqual([]);
    }
  });
  test("names: the next chapter and the patch after one", () => {
    expect(nextName("v1.0.0")).toBe("v2.0.0");
    expect(patchName("v1.0.0")).toBe("v1.0.1");
    expect(patchName("v2")).toBe("v2.1");
  });
  test("with no chapter everything flows as before", () => {
    expect(starts(issues[0]!)).toBe(true);
  });
  test("only the owner drafts, opens and fills: a planner or a stranger is refused", () => {
    expect(draft(app, planner, repo, { name: "v1.0.0" })).toEqual({ ok: false, error: "forbidden" });
    expect(draft(app, undefined, repo, { name: "v1.0.0" })).toEqual({ ok: false, error: "forbidden" });
    expect(draft(app, owner, repo, { name: "bad name!" })).toEqual({ ok: false, error: "invalid_name" });
    expect(draft(app, owner, repo, { name: "v1.0.0", means: "x".repeat(301) })).toEqual({ ok: false, error: "means_too_long" });
    expect(draft(app, owner, repo, { name: "v1.0.0", means: "The shop takes an order." }).ok).toBe(true);
    expect(draft(app, owner, repo, { name: "v1.0.0" })).toEqual({ ok: false, error: "exists" });
    expect(draft(app, owner, repo, { name: "v2.0.0", means: "Payments." }).ok).toBe(true);
    expect(fill(app, planner, repo, "v1.0.0", issues[0]!.number, true)).toEqual({ ok: false, error: "forbidden" });
    expect(fill(app, owner, repo, "v1.0.0", issues[0]!.number, true).ok).toBe(true);
    expect(fill(app, owner, repo, "v1.0.0", issues[1]!.number, true).ok).toBe(true);
    expect(open(app, planner, repo, "v1.0.0")).toEqual({ ok: false, error: "forbidden" });
  });
  test("a drafted chapter holds nothing back until it is opened; open, the crew builds only what is in it", () => {
    expect(starts(issues[2]!)).toBe(true);
    expect(open(app, owner, repo, "v1.0.0").ok).toBe(true);
    expect(open(app, owner, repo, "v2.0.0")).toEqual({ ok: false, error: "already_open" });
    expect(starts(issues[0]!)).toBe(true);
    expect(starts(issues[1]!)).toBe(true);
    expect(starts(issues[2]!)).toBe(false);
    // The owner's act is recorded.
    const kinds = app.db.query<{ kind: string }, [string]>("SELECT kind FROM event WHERE repo_id = ?1 AND kind LIKE 'chapter.%'").all(repo.id).map((e) => e.kind);
    expect(kinds).toContain("chapter.item_added");
    expect(kinds).toContain("chapter.opened");
  });
  test("the planner's new issues land in the next chapter, a defect of a chapter item joins this one; it never adds scope", () => {
    const plain = openIssue(app, planner, repo, { title: "Someday idea" });
    const defect = openIssue(app, planner, repo, { title: "Order total is wrong", body: `Defect of #${issues[0]!.number}` });
    const elsewhere = openIssue(app, planner, repo, { title: "Odd", body: `Defect of #${issues[2]!.number}` });
    if (!plain.ok || !defect.ok || !elsewhere.ok) throw new Error("planner issues");
    expect(chapterOfIssue(app.db, plain.value.id)?.name).toBe("v2.0.0");
    expect(chapterOfIssue(app.db, defect.value.id)?.name).toBe("v1.0.0");
    expect(chapterOfIssue(app.db, elsewhere.value.id)?.name).toBe("v2.0.0");
    expect(starts(plain.value)).toBe(false);
    expect(starts(defect.value)).toBe(true);
    // A person's issue is theirs to place: it is not moved.
    const mine = openIssue(app, owner, repo, { title: "Mine" });
    if (!mine.ok) throw new Error("owner issue");
    expect(chapterOfIssue(app.db, mine.value.id)).toBeUndefined();
  });
  test("with no later chapter drafted a planner's issue waits behind Later, and parts of a split stay in their chapter", () => {
    const partOf = mkIssue("Part of a");
    inheritChapter(app.db, issues[0]!, [partOf], owner.id);
    expect(chapterOfIssue(app.db, partOf.id)?.name).toBe("v1.0.0");
    expect(chapterOfIssue(app.db, issues[0]!.id)?.name).toBe("v1.0.0");
  });
  test("an item is struck only when live and proven, not when its pull merged", () => {
    const chapter = getChapter(app.db, repo.id, "v1.0.0")!;
    const find = (n: number) => itemsOf(app.db, chapter).find((i) => i.number === n)!;
    expect(find(issues[0]!.number).status).not.toBe("done");
    land(issues[0]!, false);
    expect(find(issues[0]!.number).status).toBe("building");
    expect(find(issues[0]!.number).doneAt).toBeNull();
    land(issues[0]!, true);
    const done = find(issues[0]!.number);
    expect(done.status).toBe("done");
    expect(done.doneAt).toBe("2026-11-11T08:00:00.000Z");
    expect(done.builder).toBe("build");
    const progress = progressOf(chapter, itemsOf(app.db, chapter), new Date("2026-11-12T00:00:00.000Z"));
    expect(progress.done).toBe(1);
    expect(progress.finishesOn).not.toBeNull();
  });
  test("closing without Ship it refuses while items are left; Ship it tags, writes notes, moves what is left and closes", async () => {
    expect(await close(app, owner, repo, "v1.0.0", false)).toEqual({ ok: false, error: "unfinished" });
    expect(await close(app, planner, repo, "v1.0.0", true)).toEqual({ ok: false, error: "forbidden" });
    const shipped = await close(app, owner, repo, "v1.0.0", true, new Date("2026-11-12T12:00:00.000Z"));
    if (!shipped.ok) throw new Error(shipped.error);
    expect(shipped.value.state).toBe("closed");
    expect(shipped.value.notes).toContain("# v1.0.0");
    expect(shipped.value.notes).toContain("Item a");
    expect(shipped.value.notes).toContain("Built by build");
    expect(shipped.value.notes).toContain("## Moved to v2.0.0");
    expect(shipped.value.notes).toContain("Item b");
    const dir = repoDir(app.reposRoot, "alice", "shop");
    const tag = await runGit(["rev-parse", "refs/tags/v1.0.0^{commit}"], { cwd: dir });
    expect(tag.ok && tag.value.trim()).toBe(shipped.value.tagOid!);
    expect(chapterOfIssue(app.db, issues[1]!.id)?.name).toBe("v2.0.0");
    // The closed chapter keeps its list and cannot be reopened or changed.
    expect(chapterOfIssue(app.db, issues[0]!.id)?.name).toBe("v1.0.0");
    expect(open(app, owner, repo, "v1.0.0")).toEqual({ ok: false, error: "closed" });
    expect(fill(app, owner, repo, "v1.0.0", issues[2]!.number, true)).toEqual({ ok: false, error: "closed" });
    expect(await close(app, owner, repo, "v1.0.0", true)).toEqual({ ok: false, error: "closed" });
  });
  test("after closing the crew starts nothing until a chapter is opened; a patch chapter opens from the closed one", () => {
    expect(starts(issues[1]!)).toBe(false);
    expect(starts(issues[2]!)).toBe(false);
    const made = patch(app, owner, repo, "v1.0.0");
    if (!made.ok) throw new Error(made.error);
    expect(made.value.name).toBe("v1.0.1");
    expect(made.value.state).toBe("open");
    expect(made.value.patchOf).toBe(getChapter(app.db, repo.id, "v1.0.0")!.id);
    expect(patch(app, owner, repo, "v1.0.0")).toEqual({ ok: false, error: "already_open" });
    expect(starts(issues[1]!)).toBe(false); // in v2.0.0, which waits
    expect(fill(app, owner, repo, "v1.0.1", issues[1]!.number, true).ok).toBe(true);
    expect(starts(issues[1]!)).toBe(true);
    expect(getIssue(app.db, repo.id, issues[1]!.number)?.state).toBe("open");
  });
  test("the page and the API: open → cross off → ship → the finished page", async () => {
    const post = (path: string, form: string) =>
      fetch(`${servers.url}${path}`, {
        method: "POST",
        redirect: "manual",
        headers: { authorization: `Bearer ${token}`, "content-type": "application/x-www-form-urlencoded", origin: servers.url },
        body: form,
      });
    const get = async (path: string) => (await fetch(`${servers.url}${path}`, { headers: { authorization: `Bearer ${token}` } })).text();
    // Patch chapter v1.0.1 is open: finish its one item, then close the book on it.
    land(issues[1]!, true);
    const page = await get("/alice/shop/chapters/v1.0.1");
    expect(page).toContain("1 of 1 done");
    expect(page).toContain("<s>Item b</s>");
    expect(page).toContain("live 2026-11-11");
    expect((await fetch(`${servers.url}/alice/shop/chapters/v1.0.1/ship`, { method: "POST", redirect: "manual", headers: { authorization: `Bearer ${token}`, origin: "https://evil.example" } })).status).toBe(403);
    expect(getChapter(app.db, repo.id, "v1.0.1")?.state).toBe("open");
    expect((await post("/alice/shop/chapters/v1.0.1/ship", "")).status).toBeLessThan(400);
    const finished = await get("/alice/shop/chapters/v1.0.1");
    expect(finished).toContain("is finished");
    expect(finished).toContain("Open a patch chapter");
    expect(finished).toContain("Cost");
    const api = (await (await fetch(`${servers.url}/api/v1/repos/alice/shop/chapters`)).json()) as { chapters: { name: string; state: string; tag: { oid: string } | null }[] };
    expect(api.chapters.map((c) => `${c.name}:${c.state}`).sort()).toEqual(["v1.0.0:closed", "v1.0.1:closed", "v2.0.0:draft"]);
    expect(api.chapters.find((c) => c.name === "v1.0.1")?.tag?.oid).toHaveLength(40);
    // The API drafts and opens too, with a token and not without one.
    const json = (path: string, body: unknown, auth = true) =>
      fetch(`${servers.url}${path}`, { method: "POST", headers: { "content-type": "application/json", ...(auth ? { authorization: `Bearer ${token}` } : {}) }, body: JSON.stringify(body) });
    expect((await json("/api/v1/repos/alice/shop/chapters", { name: "v3" }, false)).status).toBe(401);
    expect((await json("/api/v1/repos/alice/shop/chapters", { name: "v3", means: "Later" })).status).toBe(201);
    expect((await json("/api/v1/repos/alice/shop/chapters/v2.0.0/open", {})).status).toBe(200);
    expect(starts(issues[2]!)).toBe(false);
    expect(getChapter(app.db, repo.id, "v2.0.0")?.state).toBe("open");
  });
  test("a public read costs one pass over the pulls, and a closed chapter's list is read once", () => {
    forgetFrozenItems();
    const closed = getChapter(app.db, repo.id, "v1.0.0")!;
    expect(closed.state).toBe("closed");
    let statements = 0;
    let scans = 0;
    const counting = new Proxy(app.db, {
      get(target, key) {
        if (key === "query")
          return (sql: string) => {
            statements++;
            if (sql.includes("LIKE")) scans++;
            return target.query(sql);
          };
        const v = Reflect.get(target, key) as unknown;
        return typeof v === "function" ? v.bind(target) : v;
      },
    });
    const first = itemsOf(counting, closed);
    expect(first.length).toBeGreaterThan(0);
    expect(scans).toBeLessThanOrEqual(1);
    const after = statements;
    expect(itemsOf(counting, closed)).toBe(first);
    expect(statements).toBe(after);
  });
  test("a ship whose database step fails takes its tag back, so a retry can close the book", async () => {
    const open2 = getChapter(app.db, repo.id, "v2.0.0")!;
    expect(open2.state).toBe("open");
    const dir = repoDir(app.reposRoot, "alice", "shop");
    const tagged = async () => (await runGit(["rev-parse", "--verify", "--quiet", "refs/tags/v2.0.0"], { cwd: dir })).ok;
    app.db.exec("CREATE TRIGGER chapter_refuses BEFORE UPDATE ON chapter BEGIN SELECT RAISE(ABORT, 'refused'); END");
    const refused = await close(app, owner, repo, "v2.0.0", true);
    expect(refused.ok).toBe(false);
    expect(await tagged()).toBe(false);
    expect(getChapter(app.db, repo.id, "v2.0.0")?.state).toBe("open");
    app.db.exec("DROP TRIGGER chapter_refuses");
    const retried = await close(app, owner, repo, "v2.0.0", true);
    expect(retried.ok).toBe(true);
    expect(await tagged()).toBe(true);
  });
  describe("the terminal door", () => {
    const session = (user: User | undefined) => ({ user, db: app.db, app }) as unknown as Session;
    const rig = () => {
      const toasts: string[] = [];
      const pushed: Screen[] = [];
      const ctx = { toast: (t: string) => toasts.push(t), invalidate() {}, push: (sc: Screen) => pushed.push(sc), pop() {}, track: (p: Promise<unknown>) => p } as unknown as Ctx;
      return { toasts, pushed, ctx };
    };
    const typed = (sc: Screen, text: string) => {
      for (const ch of text) sc.key({ key: ch } as never);
      return sc.key({ key: "enter" } as never);
    };
    test("a person who does not administer the app is refused every act", () => {
      expect(chaptersCommands(session(undefined), rig().ctx, repo)).toHaveLength(1);
      for (const who of [planner, undefined]) {
        const { ctx, pushed } = rig();
        const screen = chaptersScreen(session(who), ctx, repo);
        screen.key({ key: "n" } as never);
        typed(pushed[0]!, "v77");
        expect(getChapter(app.db, repo.id, "v77")).toBeUndefined();
      }
    });
    test("the owner drafts, fills, opens and ships from the terminal, and each act is an event", async () => {
      const heard: string[] = [];
      const off = app.bus.subscribe((e) => heard.push(e.kind));
      const { ctx, pushed, toasts } = rig();
      const screen = chaptersScreen(session(owner), ctx, repo);
      screen.key({ key: "n" } as never);
      typed(pushed[0]!, "v8");
      expect(getChapter(app.db, repo.id, "v8")?.state).toBe("draft");
      const idx = (await import("../src/core/chapters.ts")).listChapters(app.db, repo.id).findIndex((c) => c.name === "v8");
      for (let i = 0; i < idx; i++) screen.key({ key: "j" } as never);
      screen.key({ key: "enter" } as never);
      const detail = pushed.at(-1)!;
      detail.key({ key: "a" } as never);
      typed(pushed.at(-1)!, String(issues[0]!.number));
      expect(chapterOfIssue(app.db, issues[0]!.id)?.name).toBe("v1.0.0"); // closed chapters hold their list
      detail.key({ key: "a" } as never);
      const extra = mkIssue("Item d");
      typed(pushed.at(-1)!, String(extra.number));
      expect(chapterOfIssue(app.db, extra.id)?.name).toBe("v8");
      detail.key({ key: "o" } as never);
      expect(toasts.at(-1)).toBe("v8 is open.");
      expect(getChapter(app.db, repo.id, "v8")?.state).toBe("open");
      detail.key({ key: "s" } as never);
      const ask = pushed.at(-1)!;
      ask.key({ key: "enter" } as never);
      await new Promise((r) => setTimeout(r, 300));
      expect(getChapter(app.db, repo.id, "v8")?.state).toBe("closed");
      off();
      expect(heard).toEqual(expect.arrayContaining(["chapter.drafted", "chapter.item_added", "chapter.opened", "chapter.closed"]));
      expect(chapterScreen(session(owner), ctx, repo, "v8").title).toContain("v8");
    });
  });
});
@@ -289,6 +289,7 @@
const NOT_WALKED: Record<string, string> = {
  "/:owner/:name/builds/:label/cart": "needs a pinned build with a cart",
  "/:owner/:name/builds/:label/cart.png": "needs a pinned build with a cart",
  "/:owner/:name/builds/:label/shots": "needs a pinned build with pictures",
  "/:owner/:name/chapters/:chapter": "needs a drafted chapter, which the seed does not make",
  "/:owner/:name/builds/:label/shots/:file": "needs a pinned build with pictures",
  "/:owner/:name/commit/:oid": "the seed does not keep the commit id; the commit page is a plain diff with the shell script only",
  "/:owner/:name/looks/:env/:commit/:kind.png": "an image of a captured look, not a page",
@@ -43,7 +43,7 @@
const HEAVIER: Record<string, { statements?: number; git?: number }> = {
};
/** Patterns with no fixture today: lower this as fixtures are added, never raise it silently. */
const MAX_UNFIXTURED = 145;
const MAX_UNFIXTURED = 146;
/** Streams and live fragments: no page. */
const NOT_PAGES = new Set([
@@ -68,6 +68,7 @@
const UNSEEDED: Record<string, string> = {
  "/bring/:id/:job": "needs a bring job of the signed-in person; the seed brings nothing",
  "/fleet/ops/:id": FLEET,
  "/:owner/:name/bets/:id": BET,
  "/:owner/:name/chapters/:chapter": "needs a chapter, which the seed does not draft (test/chapters.test.ts covers it)",
  "/:owner/:name/builds/:label/cart": CART,
  "/:owner/:name/builds/:label/cart.png": CART,
  "/:owner/:name/builds/:label/shots": SHOT,
		@@ -15,7 +15,7 @@ A new read of a table that grows (`event`, `issue`, `run`, `comment`) names the
15	15
16	16	A new `/settings…` page route goes in `src/http/settings_routes.ts` (`settingsRoutes`), not `src/http/server.ts`.
17	17
18		State shared between modules through process memory, not the database, is named here. `src/perf/views_report.ts`: `readVisits` holds each scope and window's visits for 15 seconds (dropped by `flushViews`), so a page and its probe share one read; `src/perf/views_store.ts`: the view buffer, flushed every 10 seconds. The traffic sources view's terminal door is `src/tui/screens/trafficview.ts` (palette entry for admins, per-app command for a repository's admins). The schedules' terminal door is `src/tui/screens/schedules.ts` (per-app palette command while the repository is open; `r` runs, `p` pauses or resumes, writers only; `scheduleRows`/`steerSchedule` give the page, API, MCP tool and terminal the same rows and gates). `src/runs/held.ts`: each dispatcher pass (`src/crew/dispatch.ts`, `pump`) records which queued agent runs it held and why (valve, pace, limit), and vitals (`src/kernel/vitals.ts`) leaves those out of `queue:agent`. A record older than `HELD_FRESH_MS` is ignored, so a stopped dispatcher cannot hide its queue. `src/runs/stoppable.ts`: the checks in flight in this process by run id (`src/checks/service.ts` `start` tracks each), so a person's cancel (`cancelRepoRun`) aborts the check and its process group ends with it; agent runs keep `src/crew/running.ts`. `src/apps/egress_refused.ts`: refused-host counts per repository, flushed to disk every 5 seconds (`flushRefused` forces it). `src/spawn/usage.ts`: the last disk reading of each child's data directory (30 s), and a cell child's last reading of its own cgroup CPU (`selfUse`, #10853), from which the next reading's cores are taken; `forgetSelfCpu` drops it. `src/web/pages/flow-waiting.ts`: the unproposed-work scan (it reads git for every crew fork) is held for 60 seconds (`forgetUnproposed` drops it), so /flow and the terminal screen share one scan.
	18	State shared between modules through process memory, not the database, is named here. `src/perf/views_report.ts`: `readVisits` holds each scope and window's visits for 15 seconds (dropped by `flushViews`), so a page and its probe share one read; `src/perf/views_store.ts`: the view buffer, flushed every 10 seconds. The traffic sources view's terminal door is `src/tui/screens/trafficview.ts` (palette entry for admins, per-app command for a repository's admins). The schedules' terminal door is `src/tui/screens/schedules.ts` (per-app palette command while the repository is open; `r` runs, `p` pauses or resumes, writers only; `scheduleRows`/`steerSchedule` give the page, API, MCP tool and terminal the same rows and gates). `src/core/chapters.ts`: a closed chapter's item list is kept per chapter id (200 at most; `forgetFrozenItems` drops them), since closed is forever. `src/runs/held.ts`: each dispatcher pass (`src/crew/dispatch.ts`, `pump`) records which queued agent runs it held and why (valve, pace, limit), and vitals (`src/kernel/vitals.ts`) leaves those out of `queue:agent`. A record older than `HELD_FRESH_MS` is ignored, so a stopped dispatcher cannot hide its queue. `src/runs/stoppable.ts`: the checks in flight in this process by run id (`src/checks/service.ts` `start` tracks each), so a person's cancel (`cancelRepoRun`) aborts the check and its process group ends with it; agent runs keep `src/crew/running.ts`. `src/apps/egress_refused.ts`: refused-host counts per repository, flushed to disk every 5 seconds (`flushRefused` forces it). `src/spawn/usage.ts`: the last disk reading of each child's data directory (30 s), and a cell child's last reading of its own cgroup CPU (`selfUse`, #10853), from which the next reading's cores are taken; `forgetSelfCpu` drops it. `src/web/pages/flow-waiting.ts`: the unproposed-work scan (it reads git for every crew fork) is held for 60 seconds (`forgetUnproposed` drops it), so /flow and the terminal screen share one scan.
19	19
20	20	`src/perf/loop_worst.ts`: `loopWorst`, the worst event-loop lag of the last 10 s in ten one-second slots, fed by one unref'd 50 ms timer that the first `serve` starts (`startLoopWorst`), and read by every response's `lag;dur` and by `/healthz` asked for JSON (`loopLagMs`). Tests listing a request's phases read `requestTiming` (`test/helpers/request-timing.ts`), which leaves `lag` out.
21	21
		@@ -0,0 +1,14 @@
	1	# Chapters: a version with an end
	2
	3	A chapter is a named list of a repository's issues that is finished, tagged and closed (#11603). A name (`v1.0.0`; it becomes the git tag), one sentence of what done means, and the issues in it.
	4
	5	- One open, any number drafted. A repository has at most one open chapter. Later ones (`v2`, `v3`) are drafted after it and filled with issues that wait.
	6	- While one is open the crew builds only what is in it. The dispatcher (`queueAgentRun`, through `chapterHold` in `src/core/chapters.ts`) starts no builder or reviewer run on an issue outside it. The planner may split a chapter's issue (the parts stay in the chapter) and may open an issue that says `Defect of #N` for an item of the chapter (it joins the chapter); every other issue it opens waits in the next chapter, or, with none drafted, behind the Later gate. Adding or removing an issue is the owner's act, recorded as `chapter.item_added` / `chapter.item_removed`.
	7	- The list being crossed off. `/<owner>/<name>/chapters/<name>`: done items struck through with the day they went live, what is building, what is left, and the date it finishes at the pace since it opened. An item is done when it is live and proven (a merged pull that closes it and a passing production release proof), never when the pull merged.
	8	- Closing the book. When the last item is done, or when the owner presses Ship it, the forge tags the default branch with the chapter's name, writes the notes from what landed (grouped, with who built what and what it cost), moves what is left to the next chapter and marks the chapter closed. The chapter's page then says it is finished: what shipped, how long it took, what it cost. The crew then rests on that repository until a chapter is opened; nothing starts by itself.
	9	- Closed is forever. A closed chapter stays readable at its own address and cannot be reopened or changed. A fix for something it shipped goes in a patch chapter (`v1.0.1`), opened with one click from the closed chapter's page.
	10	- No chapter, no change. A repository that never drafted one flows continuously, as before.
	11
	12	Doors: the page (`/chapters`, linked from `/queue`), the terminal (`src/tui/screens/chapters.ts`, the palette's "Chapters" while an app is open: `n` drafts, `o` opens, `s` ships, `p` patches, `enter` shows the list where `a` adds an issue and `x` takes one out) and the API (`GET`/`POST /api/v1/repos/:owner/:name/chapters`, `POST …/chapters/:chapter/:verb` with `open`, `add`, `remove`, `ship`, `patch`). Only a person who administers the repository acts; an agent is refused.
	13
	14	A closed chapter's list is frozen, so `itemsOf` keeps it in process memory (at most 200, `forgetFrozenItems` drops them); an open chapter's list is one pass over the repository's pulls and one grouped read of its runs, however many items it holds, so the anonymous page and API read stay cheap.
		@@ -0,0 +1,189 @@
	1	/**
	2	* The owner's acts on chapters (#11603): draft, open, fill, close the book, patch. One door for the
	3	* page and the API. Only a human admin of the repository acts (an agent never adds scope: the crew
	4	* proposes, a person decides); each change is an event, so the queue shows who moved what.
	5	* The rules are in `core/chapters.ts`, the notes' words in `core/chapter_notes.ts`.
	6	*/
	7
	8	import type { App } from "../app.ts";
	9	import { chapterNotes, daysBetween } from "../core/chapter_notes.ts";
	10	import {
	11	draftChapter,
	12	getChapter,
	13	itemsOf,
	14	nextChapterOf,
	15	nextName,
	16	openChapterOf,
	17	patchName,
	18	placeNewIssue,
	19	putIssue,
	20	startChapter,
	21	takeIssueOut,
	22	type Chapter,
	23	type ChapterError,
	24	} from "../core/chapters.ts";
	25	import { addDependency } from "../core/dependencies.ts";
	26	import { getIssue, labelsFor, type Issue } from "../core/issues.ts";
	27	import { laterGate } from "../crew/later.ts";
	28	import { canAdmin, type Repo } from "../core/repos.ts";
	29	import type { User } from "../core/users.ts";
	30	import { runGit } from "../git/env.ts";
	31	import { repoDir } from "../git/repos.ts";
	32	import { err, ok, type Result } from "../kernel/result.ts";
	33
	34	export type ChapterActError = ChapterError \| "forbidden" \| "no_issue" \| "unfinished" \| "no_branch" \| "tag_exists" \| "git";
	35
	36	/** A person who administers the repository, never an agent. */
	37	function owner(app: App, actor: User \| undefined, repo: Repo): actor is User {
	38	return actor !== undefined && actor.kind !== "agent" && canAdmin(app.db, repo, actor);
	39	}
	40
	41	export function draft(app: App, actor: User \| undefined, repo: Repo, input: { name: string; means?: string }): Result<Chapter, ChapterActError> {
	42	if (!owner(app, actor, repo)) return err("forbidden");
	43	const made = draftChapter(app.db, repo.id, input, actor.id);
	44	if (made.ok) app.bus.append({ kind: "chapter.drafted", repoId: repo.id, actorId: actor.id, payload: { name: made.value.name } });
	45	return made;
	46	}
	47
	48	export function open(app: App, actor: User \| undefined, repo: Repo, name: string, now = new Date()): Result<Chapter, ChapterActError> {
	49	if (!owner(app, actor, repo)) return err("forbidden");
	50	const chapter = getChapter(app.db, repo.id, name);
	51	if (chapter === undefined) return err("not_found");
	52	const started = startChapter(app.db, chapter, now);
	53	if (started.ok) app.bus.append({ kind: "chapter.opened", repoId: repo.id, actorId: actor.id, payload: { name } });
	54	return started;
	55	}
	56
	57	/** Add an issue to a chapter, or take it out (`add` false): the owner's act, recorded. */
	58	export function fill(app: App, actor: User \| undefined, repo: Repo, name: string, number: number, add: boolean): Result<void, ChapterActError> {
	59	if (!owner(app, actor, repo)) return err("forbidden");
	60	const chapter = getChapter(app.db, repo.id, name);
	61	if (chapter === undefined) return err("not_found");
	62	const issue = getIssue(app.db, repo.id, number);
	63	if (issue === undefined \|\| issue.kind !== "issue") return err("no_issue");
	64	const done: Result<void, ChapterActError> = add
	65	? putIssue(app.db, chapter, issue.id, actor.id)
	66	: takeIssueOut(app.db, chapter, issue.id)
	67	? ok(undefined)
	68	: err("not_found");
	69	if (done.ok) app.bus.append({ kind: add ? "chapter.item_added" : "chapter.item_removed", repoId: repo.id, actorId: actor.id, payload: { name, number } });
	70	return done;
	71	}
	72
	73	/**
	74	* Close the book: tag the default branch's tip with the chapter's name, write the notes from what
	75	* landed, move what is left (only with `ship`) to the next chapter and mark the chapter closed.
	76	* Nothing starts afterwards: with no chapter open the crew rests (`chapterHold`).
	77	*/
	78	export async function close(
	79	app: App,
	80	actor: User \| undefined,
	81	repo: Repo,
	82	name: string,
	83	ship: boolean,
	84	now = new Date(),
	85	): Promise<Result<Chapter, ChapterActError>> {
	86	if (!owner(app, actor, repo)) return err("forbidden");
	87	const chapter = getChapter(app.db, repo.id, name);
	88	if (chapter === undefined) return err("not_found");
	89	if (chapter.state === "closed") return err("closed");
	90	if (chapter.state !== "open") return err("not_draft");
	91	const items = itemsOf(app.db, chapter);
	92	const left = items.filter((i) => i.status !== "done");
	93	if (left.length > 0 && !ship) return err("unfinished");
	94
	95	const dir = repoDir(app.reposRoot, repo.ownerName, repo.name);
	96	const tipped = await runGit(["rev-parse", "--verify", "--quiet", `refs/heads/${repo.defaultBranch}^{commit}`], { cwd: dir });
	97	if (!tipped.ok) return err("no_branch");
	98	const tip = tipped.value.trim();
	99	const ref = `refs/tags/${chapter.name}`;
	100	if ((await runGit(["rev-parse", "--verify", "--quiet", ref], { cwd: dir })).ok) return err("tag_exists");
	101	if (!(await runGit(["update-ref", ref, tip, ""], { cwd: dir })).ok) return err("git");
	102
	103	const closedAt = now.toISOString();
	104	const landed = items
	105	.filter((i) => i.status === "done")
	106	.map((item) => ({ item, fix: labelsFor(app.db, item.issueId).some((l) => l.name.toLowerCase() === "bug") }));
	107	const costUsd = Math.round(landed.reduce((s, l) => s + l.item.costUsd, 0) * 1e4) / 1e4;
	108	// The tag was created only if absent, so it is ours: whatever stops the book closing takes it back,
	109	// or a retry would answer `tag_exists` for good.
	110	let next: Chapter \| undefined;
	111	try {
	112	app.db.transaction(() => {
	113	// What is left moves on to the next chapter, drafted when there is none.
	114	next = left.length === 0 ? undefined : nextChapterOf(app.db, repo.id);
	115	if (left.length > 0 && next === undefined) {
	116	const made = draftChapter(app.db, repo.id, { name: nextName(chapter.name) }, actor.id);
	117	next = made.ok ? made.value : undefined;
	118	}
	119	const notes = chapterNotes(chapter.name, chapter.means, landed, left, next?.name, {
	120	opened: chapter.openedAt ?? closedAt,
	121	closed: closedAt,
	122	days: daysBetween(chapter.openedAt ?? closedAt, closedAt),
	123	doneCount: landed.length,
	124	costUsd,
	125	});
	126	if (next !== undefined) for (const i of left) putIssue(app.db, next, i.issueId, actor.id);
	127	const closed = app.db
	128	.query("UPDATE chapter SET state = 'closed', closed_at = ?2, tag_oid = ?3, notes = ?4, cost_usd = ?5 WHERE id = ?1 AND state = 'open'")
	129	.run(chapter.id, closedAt, tip, notes, costUsd);
	130	if (closed.changes !== 1) throw new Error("chapter_not_open");
	131	}).immediate();
	132	} catch {
	133	await runGit(["update-ref", "-d", ref, tip], { cwd: dir });
	134	return err(getChapter(app.db, repo.id, name)?.state === "closed" ? "closed" : "git");
	135	}
	136	app.bus.append({ kind: "chapter.closed", repoId: repo.id, actorId: actor.id, payload: { name, tag: chapter.name, shipped: landed.length, moved: left.length, ...(next === undefined ? {} : { into: next.name }) } });
	137	return ok(getChapter(app.db, repo.id, name)!);
	138	}
	139
	140	/** Open a patch chapter for a closed one, with one click: drafted and opened together. */
	141	export function patch(app: App, actor: User \| undefined, repo: Repo, closedName: string, now = new Date()): Result<Chapter, ChapterActError> {
	142	if (!owner(app, actor, repo)) return err("forbidden");
	143	const closed = getChapter(app.db, repo.id, closedName);
	144	if (closed === undefined) return err("not_found");
	145	if (closed.state !== "closed") return err("not_draft");
	146	if (openChapterOf(app.db, repo.id) !== undefined) return err("already_open");
	147	let name = patchName(closed.name);
	148	while (getChapter(app.db, repo.id, name) !== undefined) name = patchName(name);
	149	const made = draftChapter(app.db, repo.id, { name, means: `Fixes for what ${closed.name} shipped.`, patchOf: closed.id }, actor.id);
	150	if (!made.ok) return made;
	151	const started = startChapter(app.db, made.value, now);
	152	if (started.ok) app.bus.append({ kind: "chapter.opened", repoId: repo.id, actorId: actor.id, payload: { name, patchOf: closed.name } });
	153	return started;
	154	}
	155
	156	/**
	157	* A planner's new issue while a chapter is open: a defect of a chapter item joins the chapter; any
	158	* other waits in the next chapter, or, with none drafted, behind the Later gate where the owner
	159	* sees it queued. The planner never adds scope to the open chapter.
	160	*/
	161	export function keepWithinChapter(app: App, repo: Repo, issue: Issue, planner: User): void {
	162	const placed = placeNewIssue(app.db, repo.id, issue.id, issue.body);
	163	if (placed === undefined) return;
	164	if (placed === "later") {
	165	const gate = laterGate(app.db, repo.id);
	166	const gateIssue = gate === undefined ? undefined : getIssue(app.db, repo.id, gate);
	167	if (gateIssue !== undefined) addDependency(app.db, issue, gateIssue, planner.id);
	168	return;
	169	}
	170	putIssue(app.db, placed.chapter, issue.id, planner.id);
	171	app.bus.append({ kind: "chapter.item_added", repoId: repo.id, actorId: planner.id, payload: { name: placed.chapter.name, number: issue.number, scope: placed.scope } });
	172	}
	173
	174	/** What each refusal says, in the words every door uses. */
	175	export const CHAPTER_WORDS: Readonly<Record<ChapterActError, string>> = {
	176	invalid_name: "A chapter's name is letters, digits, dots, dashes and underscores, at most 40 (it becomes the git tag).",
	177	means_too_long: "What done means is one sentence, at most 300 characters.",
	178	exists: "A chapter with that name already exists.",
	179	already_open: "Another chapter is already open: a repository has one open chapter at a time.",
	180	not_draft: "That chapter is not open for this.",
	181	closed: "A closed chapter cannot be changed or reopened; open a patch chapter instead.",
	182	not_found: "No such chapter, or nothing to do.",
	183	forbidden: "Only a person who administers this repository opens, fills and closes chapters.",
	184	no_issue: "No such issue here.",
	185	unfinished: "Items are still open. Ship the chapter to move them to the next one and close the book.",
	186	no_branch: "The default branch has no commit to tag yet.",
	187	tag_exists: "A git tag with that name already exists.",
	188	git: "The tag could not be written.",
	189	};
		@@ -25,6 +25,8 @@ import type { App } from "../app.ts";
25	25	import { adoptResolution } from "../core/trusted_sources.ts";
26	26	import { crewRole, isCrew } from "../core/agents.ts";
27	27	import { pausedUntil } from "../core/planner_pause.ts";
	28	import { keepWithinChapter } from "./chapters.ts";
	29	import { inheritChapter } from "../core/chapters.ts";
28	30	import { moveBlockersToChildren } from "../core/dependencies.ts";
29	31	import {
30	32	addComment as insertComment,
		@@ -118,6 +120,9 @@ export function openIssue(
118	120	sealed: input.sealed === true,
119	121	});
120	122	if (!created.ok) return created;
	123	// A chapter is open (#11603): the planner's issue waits in the next chapter, never in this one.
	124	if (user.value.kind === "agent" && crewRole(app.db, repo.id, user.value.id) === "planner")
	125	keepWithinChapter(app, repo, created.value, user.value);
121	126	app.bus.append({
122	127	kind: "issue.opened",
123	128	repoId: repo.id,
		@@ -522,8 +527,11 @@ export function setIssueState(
522	527	return written;
523	528	})();
524	529	if (!changed) return ok(getIssueById(app.db, issue.id) ?? issue);
525		if (children.length > 0)
	530	if (children.length > 0) {
526	531	moveBlockersToChildren(app.db, issue, children, user.value.id);
	532	// The parts of a split stay in the chapter the issue was in (#11603).
	533	inheritChapter(app.db, issue, children, user.value.id);
	534	}
527	535	app.bus.append({
528	536	kind: `${issue.kind}.${state === "closed" ? "closed" : "reopened"}`,
529	537	repoId: repo.id,
		@@ -0,0 +1,3 @@
	1	import { REPO, type Route } from "../shared.ts";
	2
	3	export const route: Route = { method: "get", path: `${REPO}/chapters`, summary: "The repository's chapters (a version with an end): the open one, the drafts waiting after it and the closed ones, each with its name, what done means, state, and its list of issues (done only when live and proven, building, left), progress and the date it finishes at the current pace; a closed chapter carries its tag, notes, cost and the day it closed", auth: false, role: "anonymous" };
		@@ -134,6 +134,7 @@ export { route as getApiV1ReposOwnerNameBuilds } from "./getApiV1ReposOwnerNameB
134	134	export { route as getApiV1ReposOwnerNameBuildsLabelCart } from "./getApiV1ReposOwnerNameBuildsLabelCart.ts";
135	135	export { route as getApiV1ReposOwnerNameBuildsLabelShots } from "./getApiV1ReposOwnerNameBuildsLabelShots.ts";
136	136	export { route as getApiV1ReposOwnerNameBuildsLabelShotsLooks } from "./getApiV1ReposOwnerNameBuildsLabelShotsLooks.ts";
	137	export { route as getApiV1ReposOwnerNameChapters } from "./getApiV1ReposOwnerNameChapters.ts";
137	138	export { route as getApiV1ReposOwnerNameCommits } from "./getApiV1ReposOwnerNameCommits.ts";
138	139	export { route as getApiV1ReposOwnerNameCommitsOid } from "./getApiV1ReposOwnerNameCommitsOid.ts";
139	140	export { route as getApiV1ReposOwnerNameCommitsOidCheck } from "./getApiV1ReposOwnerNameCommitsOidCheck.ts";
		@@ -317,6 +318,8 @@ export { route as postApiV1ReposOwnerNameBuildsLabelShots } from "./postApiV1Rep
317	318	export { route as postApiV1ReposOwnerNameBuildsLabelShotsFile } from "./postApiV1ReposOwnerNameBuildsLabelShotsFile.ts";
318	319	export { route as postApiV1ReposOwnerNameBuildsLabelShotsLooks } from "./postApiV1ReposOwnerNameBuildsLabelShotsLooks.ts";
319	320	export { route as postApiV1ReposOwnerNameBuildsPreview } from "./postApiV1ReposOwnerNameBuildsPreview.ts";
	321	export { route as postApiV1ReposOwnerNameChapters } from "./postApiV1ReposOwnerNameChapters.ts";
	322	export { route as postApiV1ReposOwnerNameChaptersChapterVerb } from "./postApiV1ReposOwnerNameChaptersChapterVerb.ts";
320	323	export { route as postApiV1ReposOwnerNameChecksRecheck } from "./postApiV1ReposOwnerNameChecksRecheck.ts";
321	324	export { route as postApiV1ReposOwnerNameContents } from "./postApiV1ReposOwnerNameContents.ts";
322	325	export { route as postApiV1ReposOwnerNameContribute } from "./postApiV1ReposOwnerNameContribute.ts";
		@@ -0,0 +1,3 @@
	1	import { REPO, type Route } from "../shared.ts";
	2
	3	export const route: Route = { method: "post", path: `${REPO}/chapters`, summary: "Draft a chapter: `name` (the git tag it will carry, at most 40 characters) and `means`, one sentence of what done means. Only a person who administers the repository", auth: true, role: "member", body: { name: "string" } };
		@@ -17,6 +17,7 @@ const ALIAS: Readonly<Record<string, string>> = {
17	17	contribute: "forks",
18	18	queue: "gates",
19	19	growth: "issues",
	20	chapters: "issues",
20	21	checks: "pulls",
21	22	conversation: "conversations",
22	23	"conversation-confirms": "conversations",
		@@ -0,0 +1,54 @@
	1	/**
	2	* A closed chapter's notes (#11603), written from what landed: plain sentences, grouped, each with
	3	* who built it and what it cost, then what was moved on. Pure text from plain data; no model.
	4	*/
	5
	6	import type { Item } from "./chapters.ts";
	7
	8	export interface Figures {
	9	readonly opened: string;
	10	readonly closed: string;
	11	readonly days: number;
	12	readonly doneCount: number;
	13	readonly costUsd: number;
	14	}
	15
	16	const usd = (n: number): string => `$${n.toFixed(2)}`;
	17
	18	/** Whole days from `a` to `b`, at least one. */
	19	export function daysBetween(a: string, b: string): number {
	20	return Math.max(1, Math.round((Date.parse(b) - Date.parse(a)) / 86_400_000));
	21	}
	22
	23	/** One sentence for a landed item. */
	24	export function sentence(i: Item): string {
	25	const by = i.builder === null ? "" : ` Built by ${i.builder}.`;
	26	const cost = i.costUsd > 0 ? ` Cost ${usd(i.costUsd)}.` : "";
	27	const title = i.title.trim().replace(/[.\s]+$/, "");
	28	return `- ${title} (#${i.number}).${by}${cost}`;
	29	}
	30
	31	/** The notes: fixes and additions grouped, then what moved to the next chapter. */
	32	export function chapterNotes(
	33	name: string,
	34	means: string,
	35	landed: readonly { item: Item; fix: boolean }[],
	36	moved: readonly Item[],
	37	next: string \| undefined,
	38	figures: Figures,
	39	): string {
	40	const lines = [`# ${name}`, ""];
	41	if (means !== "") lines.push(means, "");
	42	lines.push(
	43	`Shipped ${figures.closed.slice(0, 10)}: ${figures.doneCount} ${figures.doneCount === 1 ? "item" : "items"} in ${figures.days} ${figures.days === 1 ? "day" : "days"}, costing ${usd(figures.costUsd)}.`,
	44	"",
	45	);
	46	const added = landed.filter((l) => !l.fix);
	47	const fixed = landed.filter((l) => l.fix);
	48	if (added.length > 0) lines.push("## Added", ...added.map((l) => sentence(l.item)), "");
	49	if (fixed.length > 0) lines.push("## Fixed", ...fixed.map((l) => sentence(l.item)), "");
	50	if (landed.length === 0) lines.push("Nothing had landed when this chapter closed.", "");
	51	if (moved.length > 0 && next !== undefined)
	52	lines.push(`## Moved to ${next}`, ...moved.map((m) => `- ${m.title.trim()} (#${m.number})`), "");
	53	return `${lines.join("\n").trimEnd()}\n`;
	54	}
		@@ -0,0 +1,380 @@
	1	/**
	2	* Chapters (#11603): a named list of a repository's issues that is finished, tagged and closed.
	3	* A repository has at most one open chapter and any number drafted after it. While one is open the
	4	* crew builds only what is in it; once the last is closed the crew rests until the owner opens the
	5	* next. A repository with no chapter is left alone: continuous flow, as before.
	6	*
	7	* Plain data in and out: the db, ids, a clock. The acts (who may, the tag, the events) are in
	8	* `actions/chapters.ts`; the closing words are in `core/chapter_notes.ts`.
	9	*/
	10
	11	import type { Database } from "bun:sqlite";
	12	import { releaseOfPull } from "../release/record.ts";
	13	import { id } from "../kernel/id.ts";
	14	import { err, ok, type Result } from "../kernel/result.ts";
	15	import { closesFromBody, getPull } from "./pulls.ts";
	16	import type { Issue } from "./issues.ts";
	17
	18	export type ChapterState = "draft" \| "open" \| "closed";
	19
	20	export interface Chapter {
	21	readonly id: string;
	22	readonly repoId: string;
	23	readonly name: string;
	24	readonly means: string;
	25	readonly state: ChapterState;
	26	readonly position: number;
	27	readonly patchOf: string \| null;
	28	readonly createdAt: string;
	29	readonly openedAt: string \| null;
	30	readonly closedAt: string \| null;
	31	readonly tagOid: string \| null;
	32	readonly notes: string;
	33	readonly costUsd: number \| null;
	34	}
	35
	36	interface Row {
	37	id: string;
	38	repo_id: string;
	39	name: string;
	40	means: string;
	41	state: ChapterState;
	42	position: number;
	43	patch_of: string \| null;
	44	created_at: string;
	45	opened_at: string \| null;
	46	closed_at: string \| null;
	47	tag_oid: string \| null;
	48	notes: string;
	49	cost_usd: number \| null;
	50	}
	51
	52	const toChapter = (r: Row): Chapter => ({
	53	id: r.id,
	54	repoId: r.repo_id,
	55	name: r.name,
	56	means: r.means,
	57	state: r.state,
	58	position: r.position,
	59	patchOf: r.patch_of,
	60	createdAt: r.created_at,
	61	openedAt: r.opened_at,
	62	closedAt: r.closed_at,
	63	tagOid: r.tag_oid,
	64	notes: r.notes,
	65	costUsd: r.cost_usd,
	66	});
	67
	68	/** A chapter's name is also its git tag: a short, plain ref name. */
	69	export const NAME = /^[A-Za-z0-9][A-Za-z0-9._-]{0,39}$/;
	70	export const MAX_MEANS = 300;
	71
	72	export type ChapterError = "invalid_name" \| "means_too_long" \| "exists" \| "already_open" \| "not_draft" \| "closed" \| "not_found";
	73
	74	export function listChapters(db: Database, repoId: string): Chapter[] {
	75	return db
	76	.query<Row, [string]>(
	77	`SELECT * FROM chapter WHERE repo_id = ?1
	78	ORDER BY CASE state WHEN 'open' THEN 0 WHEN 'draft' THEN 1 ELSE 2 END, position, created_at`,
	79	)
	80	.all(repoId)
	81	.map(toChapter);
	82	}
	83
	84	export function getChapter(db: Database, repoId: string, name: string): Chapter \| undefined {
	85	const row = db.query<Row, [string, string]>("SELECT * FROM chapter WHERE repo_id = ?1 AND name = ?2").get(repoId, name);
	86	return row === null ? undefined : toChapter(row);
	87	}
	88
	89	export function getChapterById(db: Database, chapterId: string): Chapter \| undefined {
	90	const row = db.query<Row, [string]>("SELECT * FROM chapter WHERE id = ?1").get(chapterId);
	91	return row === null ? undefined : toChapter(row);
	92	}
	93
	94	/** The repository's open chapter, if it has one. */
	95	export function openChapterOf(db: Database, repoId: string): Chapter \| undefined {
	96	const row = db.query<Row, [string]>("SELECT * FROM chapter WHERE repo_id = ?1 AND state = 'open'").get(repoId);
	97	return row === null ? undefined : toChapter(row);
	98	}
	99
	100	/** The drafted chapter that comes next: the one first in line. */
	101	export function nextChapterOf(db: Database, repoId: string): Chapter \| undefined {
	102	const row = db
	103	.query<Row, [string]>("SELECT * FROM chapter WHERE repo_id = ?1 AND state = 'draft' ORDER BY position, created_at LIMIT 1")
	104	.get(repoId);
	105	return row === null ? undefined : toChapter(row);
	106	}
	107
	108	/** Draft a chapter, last in line. A patch chapter names the closed one it fixes. */
	109	export function draftChapter(
	110	db: Database,
	111	repoId: string,
	112	input: { name: string; means?: string; patchOf?: string },
	113	byId: string,
	114	): Result<Chapter, ChapterError> {
	115	const name = input.name.trim();
	116	const means = (input.means ?? "").trim();
	117	if (!NAME.test(name) \|\| name.endsWith(".") \|\| name.includes("..")) return err("invalid_name");
	118	if (means.length > MAX_MEANS) return err("means_too_long");
	119	if (getChapter(db, repoId, name) !== undefined) return err("exists");
	120	const last = db
	121	.query<{ p: number \| null }, [string]>("SELECT MAX(position) AS p FROM chapter WHERE repo_id = ?1")
	122	.get(repoId)?.p;
	123	const chapterId = id();
	124	db.query(
	125	`INSERT INTO chapter (id, repo_id, name, means, position, patch_of, created_by) VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7)`,
	126	).run(chapterId, repoId, name, means, (last ?? 0) + 1, input.patchOf ?? null, byId);
	127	return ok(getChapterById(db, chapterId)!);
	128	}
	129
	130	/** Open a drafted chapter: the repository's one open chapter, from now. */
	131	export function startChapter(db: Database, chapter: Chapter, now: Date): Result<Chapter, ChapterError> {
	132	if (chapter.state === "closed") return err("closed");
	133	if (chapter.state === "open") return err("already_open");
	134	if (openChapterOf(db, chapter.repoId) !== undefined) return err("already_open");
	135	db.query("UPDATE chapter SET state = 'open', opened_at = ?2 WHERE id = ?1").run(chapter.id, now.toISOString());
	136	return ok(getChapterById(db, chapter.id)!);
	137	}
	138
	139	/** The next name after `name`: v1.0.0 → v2.0.0. */
	140	export function nextName(name: string): string {
	141	const m = /^(\D)(\d+)(.)$/.exec(name);
	142	if (m === null) return `${name}-next`;
	143	return `${m[1]}${Number(m[2]) + 1}${(m[3] ?? "").replace(/\d+/g, "0")}`;
	144	}
	145
	146	/** A patch's name after `name`: v1.0.0 → v1.0.1; a name without three numbers gets `.1`. */
	147	export function patchName(name: string): string {
	148	const m = /^(.*\d+\.\d+\.)(\d+)$/.exec(name);
	149	return m === null ? `${name}.1` : `${m[1]}${Number(m[2]) + 1}`;
	150	}
	151
	152	// ---- items ----
	153
	154	/** The chapter an issue is in, if any. */
	155	export function chapterOfIssue(db: Database, issueId: string): Chapter \| undefined {
	156	const row = db
	157	.query<Row, [string]>("SELECT c.* FROM chapter c JOIN chapter_item i ON i.chapter_id = c.id WHERE i.issue_id = ?1")
	158	.get(issueId);
	159	return row === null ? undefined : toChapter(row);
	160	}
	161
	162	/** Put an issue in a chapter (moving it from another that is not closed). Closed chapters hold their list. */
	163	export function putIssue(db: Database, chapter: Chapter, issueId: string, byId: string \| undefined): Result<void, ChapterError> {
	164	if (chapter.state === "closed") return err("closed");
	165	const from = chapterOfIssue(db, issueId);
	166	if (from?.state === "closed") return err("closed");
	167	db.query(
	168	`INSERT INTO chapter_item (issue_id, chapter_id, by_id) VALUES (?1, ?2, ?3)
	169	ON CONFLICT(issue_id) DO UPDATE SET chapter_id = ?2, by_id = ?3, at = strftime('%Y-%m-%dT%H:%M:%fZ','now')`,
	170	).run(issueId, chapter.id, byId ?? null);
	171	return ok(undefined);
	172	}
	173
	174	export function takeIssueOut(db: Database, chapter: Chapter, issueId: string): boolean {
	175	if (chapter.state === "closed") return false;
	176	return db.query("DELETE FROM chapter_item WHERE issue_id = ?1 AND chapter_id = ?2").run(issueId, chapter.id).changes > 0;
	177	}
	178
	179	export type ItemStatus = "done" \| "building" \| "left";
	180
	181	export interface Item {
	182	readonly issueId: string;
	183	readonly number: number;
	184	readonly title: string;
	185	readonly status: ItemStatus;
	186	/** When it went live and proven; null until then. */
	187	readonly doneAt: string \| null;
	188	/** The pull that shipped it, when one did. */
	189	readonly pull: number \| null;
	190	readonly builder: string \| null;
	191	readonly costUsd: number;
	192	}
	193
	194	interface ItemRow {
	195	id: string;
	196	number: number;
	197	title: string;
	198	state: "open" \| "closed";
	199	}
	200
	201	interface PullFact {
	202	readonly id: string;
	203	readonly number: number;
	204	readonly mergedAt: string \| null;
	205	readonly closes: readonly number[];
	206	}
	207
	208	const round4 = (n: number): number => Math.round(n * 1e4) / 1e4;
	209
	210	/**
	211	* Every pull of the repository with the issue numbers it closes, read once for the whole list: the
	212	* list's cost is one pass over the pulls however many items it holds, never a scan per item.
	213	*/
	214	function pullFacts(db: Database, repoId: string): PullFact[] {
	215	return db
	216	.query<{ id: string; number: number; body: string; at: string \| null }, [string]>(
	217	`SELECT issue.id AS id, issue.number AS number, issue.body AS body, pull.merged_at AS at
	218	FROM pull JOIN issue ON issue.id = pull.issue_id WHERE issue.repo_id = ?1 AND issue.body LIKE '%#%'`,
	219	)
	220	.all(repoId)
	221	.map((r) => ({ id: r.id, number: r.number, mergedAt: r.at, closes: closesFromBody(r.body) }));
	222	}
	223
	224	/** What each issue's own runs spent, by issue id: one grouped read for the repository. */
	225	function runSpend(db: Database, repoId: string): Map<string, number> {
	226	const rows = db
	227	.query<{ id: string; usd: number }, [string]>(
	228	`SELECT run.issue_id AS id, COALESCE(SUM(run.cost_usd), 0) AS usd FROM run JOIN issue ON issue.id = run.issue_id
	229	WHERE issue.repo_id = ?1 GROUP BY run.issue_id`,
	230	)
	231	.all(repoId);
	232	return new Map(rows.map((r) => [r.id, r.usd]));
	233	}
	234
	235	/**
	236	* Where an item stands. Done is live and proven: closed, shipped by a merged pull that production's
	237	* release proof passed for (`release.ok`), never merely merged.
	238	*/
	239	function statusOf(
	240	db: Database,
	241	repoId: string,
	242	row: ItemRow,
	243	closing: readonly PullFact[],
	244	): Pick<Item, "status" \| "doneAt" \| "pull" \| "builder"> {
	245	// Merged pulls that close it, newest first: any one of them may be the one production proved.
	246	const merged =
	247	row.state === "closed"
	248	? closing
	249	.filter((f) => f.mergedAt !== null)
	250	.sort((a, b) => (a.mergedAt === b.mergedAt ? b.number - a.number : a.mergedAt! < b.mergedAt! ? 1 : -1))
	251	: [];
	252	const first = merged[0];
	253	for (const m of merged) {
	254	const proof = releaseOfPull(db, repoId, m.number);
	255	if (proof !== undefined) return { status: "done", doneAt: proof.createdAt, pull: m.number, builder: getPull(db, repoId, m.number)?.authorName ?? null };
	256	}
	257	const active =
	258	db
	259	.query<{ n: number }, [string]>("SELECT COUNT(*) AS n FROM run WHERE issue_id = ?1 AND state IN ('queued','running')")
	260	.get(row.id)?.n ?? 0;
	261	return { status: active > 0 \|\| first !== undefined \|\| row.state === "closed" ? "building" : "left", doneAt: null, pull: first?.number ?? null, builder: null };
	262	}
	263
	264	/**
	265	* A closed chapter's list never changes (its items are held, its pulls have landed), so it is read
	266	* once and kept: a public page or API read of a closed chapter costs a lookup after the first.
	267	*/
	268	const FROZEN_MAX = 200;
	269	const frozen = new Map<string, Item[]>();
	270
	271	/** Forget the kept lists: a test that rebuilds a database. */
	272	export function forgetFrozenItems(): void {
	273	frozen.clear();
	274	}
	275
	276	/** A chapter's list, in issue order, each item with where it stands and what it cost. */
	277	export function itemsOf(db: Database, chapter: Chapter): Item[] {
	278	const kept = chapter.state === "closed" ? frozen.get(chapter.id) : undefined;
	279	if (kept !== undefined) return kept;
	280	const rows = db
	281	.query<ItemRow, [string]>(
	282	`SELECT i.id, i.number, i.title, i.state FROM chapter_item c JOIN issue i ON i.id = c.issue_id
	283	WHERE c.chapter_id = ?1`,
	284	)
	285	.all(chapter.id)
	286	.sort((a, b) => a.number - b.number);
	287	const out: Item[] = [];
	288	if (rows.length > 0) {
	289	const facts = pullFacts(db, chapter.repoId);
	290	const spend = runSpend(db, chapter.repoId);
	291	for (const r of rows) {
	292	const closing = facts.filter((f) => f.id !== r.id && f.closes.includes(r.number));
	293	const cost = round4((spend.get(r.id) ?? 0) + closing.reduce((sum, f) => sum + round4(spend.get(f.id) ?? 0), 0));
	294	out.push({ issueId: r.id, number: r.number, title: r.title, ...statusOf(db, chapter.repoId, r, closing), costUsd: cost });
	295	}
	296	}
	297	if (chapter.state === "closed") {
	298	if (frozen.size >= FROZEN_MAX) frozen.delete(frozen.keys().next().value!);
	299	frozen.set(chapter.id, out);
	300	}
	301	return out;
	302	}
	303
	304	export interface Progress {
	305	readonly done: number;
	306	readonly total: number;
	307	/** When the list will be finished at the pace so far, or null before there is a pace. */
	308	readonly finishesOn: string \| null;
	309	}
	310
	311	/** Items done against the list, and the day it finishes at the pace since the chapter opened. */
	312	export function progressOf(chapter: Chapter, items: readonly Item[], now: Date): Progress {
	313	const done = items.filter((i) => i.status === "done").length;
	314	const total = items.length;
	315	if (chapter.openedAt === null \|\| done === 0 \|\| done >= total) return { done, total, finishesOn: null };
	316	const days = Math.max((now.getTime() - Date.parse(chapter.openedAt)) / 86_400_000, 1 / 24);
	317	const left = (total - done) / (done / days);
	318	return { done, total, finishesOn: new Date(now.getTime() + left * 86_400_000).toISOString().slice(0, 10) };
	319	}
	320
	321	// ---- the crew's gate ----
	322
	323	/** Whether the repository has closed a chapter and opened none since: the crew rests. */
	324	export function resting(db: Database, repoId: string): boolean {
	325	return (
	326	openChapterOf(db, repoId) === undefined &&
	327	db.query<{ n: number }, [string]>("SELECT COUNT(*) AS n FROM chapter WHERE repo_id = ?1 AND state = 'closed'").get(repoId)!.n > 0
	328	);
	329	}
	330
	331	/** The issue number a body says it is a defect of: "Defect of #12". */
	332	export function defectOf(body: string): number \| undefined {
	333	const m = /\bdefect (?:of\|in\|on) #(\d+)\b/i.exec(body);
	334	return m === null ? undefined : Number(m[1]);
	335	}
	336
	337	/**
	338	* Why the crew may not start work on this issue now, or null when it may: a chapter is open and the
	339	* issue (or, for a pull, what it closes) is not in it, or the repository rests between chapters.
	340	* A repository with no chapter is never held.
	341	*/
	342	export function chapterHold(db: Database, repoId: string, issue: Pick<Issue, "id" \| "kind" \| "body">): string \| null {
	343	const open = openChapterOf(db, repoId);
	344	if (open === undefined) return resting(db, repoId) ? "the repository rests between chapters; the owner opens the next" : null;
	345	const inOpen = (issueId: string): boolean => chapterOfIssue(db, issueId)?.id === open.id;
	346	if (inOpen(issue.id)) return null;
	347	if (issue.kind === "pull") {
	348	const closes = closesFromBody(issue.body);
	349	if (closes.length === 0) return null;
	350	for (const n of closes) {
	351	const target = db.query<{ id: string }, [string, number]>("SELECT id FROM issue WHERE repo_id = ?1 AND number = ?2").get(repoId, n);
	352	if (target !== null && inOpen(target.id)) return null;
	353	}
	354	}
	355	return `outside ${open.name}: the crew builds only what the open chapter holds`;
	356	}
	357
	358	/**
	359	* Where an issue the planner opens lands while a chapter is open: a defect of a chapter item joins the
	360	* chapter; anything else waits in the next chapter. Undefined when no chapter is open (nothing to do)
	361	* or no later chapter is drafted (the caller sends it to Later).
	362	*/
	363	export function placeNewIssue(db: Database, repoId: string, issueId: string, body: string): { chapter: Chapter; scope: "defect" \| "next" } \| "later" \| undefined {
	364	const open = openChapterOf(db, repoId);
	365	if (open === undefined) return undefined;
	366	const n = defectOf(body);
	367	if (n !== undefined) {
	368	const parent = db.query<{ id: string }, [string, number]>("SELECT id FROM issue WHERE repo_id = ?1 AND number = ?2").get(repoId, n);
	369	if (parent !== null && chapterOfIssue(db, parent.id)?.id === open.id) return { chapter: open, scope: "defect" };
	370	}
	371	const next = nextChapterOf(db, repoId);
	372	return next === undefined ? "later" : { chapter: next, scope: "next" };
	373	}
	374
	375	/** Parts of a split issue stay in its chapter. */
	376	export function inheritChapter(db: Database, parent: Issue, children: readonly Issue[], byId: string \| undefined): void {
	377	const chapter = chapterOfIssue(db, parent.id);
	378	if (chapter === undefined \|\| chapter.state === "closed") return;
	379	for (const child of children) putIssue(db, chapter, child.id, byId);
	380	}