abea9a3 · ee2d3a9 · 2a96a7f
@@ -0,0 +1,3 @@
# The week
On Next up (`src/web/pages/next.ts`) `.cut-line` is the separator row drawn between what this week's capacity can ship and what reads as next week: a dashed rule in `--series-1` with muted words under it. `.estimate` is a row's cost range, in `--fg` with tabular figures so ranges line up down the list. `/:owner/:name/week` uses only existing components (`card`, `row`, `btn`).
@@ -11,3 +11,16 @@
- A rank is cleared when the issue closes. Dependencies order within the list and are shown, never edited here.
**Terminal:** the palette's "Next up in a repository" opens the same list; `t`, `u`, `d` and `n` are Top, Up, Down and Not now on the row under the cursor, through the same action as the page and MCP. A reader sees the order and the keys do nothing; a move made anywhere reorders an open screen live. At most 200 issues are ranked; a move past that is refused and says so.
## The week is the sprint (#8704)
The subscription's weekly reset is the sprint boundary; what the crew may still spend before it is the capacity (`flow/week.ts`, from `core/standing.ts`). No ceremony and no locked scope: rerank any time and the line moves on the next paint.
- **Estimates:** each row shows a cost range (the 25th to 75th percentile of what past closed issues of the same size and kind cost, every agent run on them summed, `flow/estimate.ts`). With fewer than three comparable issues it falls back to size alone, then says "too little history". Measured, never asked of an agent: no run is spent.
- **Cut line:** walking from the top, the running median estimate is held against the capacity; the line falls before the first issue that does not fit and everything under it reads as next week. An issue with no estimate counts as the median of the others; with none estimated, or no capacity read, there is no line and the sentence says why. Same list and history, same line.
- **Projection:** one sentence above the list: how many should ship by the reset, as a range from the high and low ends of the estimates, and a confidence (high at eight or more samples on every row).
- **Retrospective:** once an hour the forge keeps the projection of the open window (`week_projection`) and, for a window that has ended, writes `week_retro` once (`flow/retro.ts`): what shipped against the projection, how many shipped issues cost inside their range, what open work cost most, what is stuck (two failed runs or more, and the class of the last failure, never the run's own output), and at most three proposals. `/:owner/:name/week` and the MCP `week` tool show it. A proposal is one tap (`POST /:owner/:name/week`, or `week { app, take }`) by a writer who is a person; it puts the issue behind the Later gate, the same move as `Not now`, and is taken at most once. Nothing changes without that tap. Only a person who writes can take one: `takeProposal` refuses an agent and a reader for every door.
- **Not done here:** the line falls between issues, not whole scopes, because bets and scopes (#8713) are not in the forge yet; when they land the line moves to their edges. The health mark per group is left for the same reason.
- **Live:** a drag posts the move and the page reloads itself from the server, which redraws the line; there is no manual reload, but it is a reload, not a client-side recompute.
- **Terminal:** Next up shows each row's range and a muted "this week ends here" line under the last issue that fits, with the projection in the header. "The week in a repository" (palette) shows the retrospective; `j`/`k` choose a proposal and `enter` or `a` takes it, through the same `takeProposal`. A reader or an agent sees it and the key does nothing; a new retrospective (`week.retro`) or a proposal taken anywhere updates the open screen. MCP `next_up` rows carry `estimate` and `thisWeek`, with a `projection` sentence.
- Sealed issues are left out of history and of the retrospective, so their cost never shapes a visible range.
@@ -0,0 +1,41 @@
/**
 * Taking a proposal from the week's retrospective (#8704): one tap by a person
 * who writes here, and it is the same move as the Next up page's `Not now`
 * (`actions/next.ts`). Each proposal is taken at most once; nothing else in
 * the retrospective ever changes anything.
 */
import type { App } from "../app.ts";
import { getIssue } from "../core/issues.ts";
import { canWrite, type Repo } from "../core/repos.ts";
import type { User } from "../core/users.ts";
import { err, ok, type Result } from "../kernel/result.ts";
import { latestRetro, takenOf } from "../flow/retro.ts";
import { rankIssue, type NextError } from "./next.ts";
export const WEEK_PERSON = "Only a person takes a proposal; an agent proposes and a person lands.";
export const WEEK_FORBIDDEN = "Only someone with write access can take a proposal.";
export function takeProposal(
  app: App,
  actor: User,
  repo: Repo,
  weekEnd: string,
  idx: number,
): Result<string, NextError> {
  // A person's tap, whatever the door: an agent proposes and never takes, a reader cannot.
  if (actor.kind === "agent") return err({ kind: "forbidden", message: WEEK_PERSON });
  if (!canWrite(app.db, repo, actor)) return err({ kind: "forbidden", message: WEEK_FORBIDDEN });
  const retro = latestRetro(app.db, repo.id);
  const proposal = retro?.weekEnd === weekEnd ? retro.proposals[idx] : undefined;
  if (proposal === undefined) return err({ kind: "not_found", message: "No such proposal." });
  if (takenOf(app.db, repo.id, weekEnd).has(idx))
    return err({ kind: "invalid", message: "That proposal was already taken." });
  const issue = getIssue(app.db, repo.id, proposal.number);
  if (issue === undefined) return err({ kind: "not_found", message: "No such issue." });
  const moved = rankIssue(app, actor, repo, proposal.number, { to: "not_now" });
  if (!moved.ok) return moved;
  app.db
    .query("INSERT OR IGNORE INTO week_retro_taken (repo_id, week_end, idx, actor_id, at) VALUES (?1, ?2, ?3, ?4, ?5)")
    .run(repo.id, weekEnd, idx, actor.id, new Date().toISOString());
  return ok(`#${proposal.number} is not now.`);
}
@@ -38,6 +38,7 @@
const READER_KINDS: ReadonlySet<string> = new Set([
  "issue.labeled",
  "issue.first",
  "issue.ranked",
  "week.retro",
  "issue.closed",
  "issue.gate_reviewed",
  "issue.commented",
@@ -0,0 +1,1 @@
8d5ade86821784d4cf4fc987b5e843b7df9f3855e8640fb54c34d73be83cc70f
@@ -0,0 +1,28 @@
// The week as the sprint (#8704): the projection the forge made when a weekly
// window opened, and the retrospective it wrote when that window closed,
// frozen once. A proposal in a retrospective is accepted at most once, by a
// person: `week_retro_taken` holds who and when.
export default `
  CREATE TABLE IF NOT EXISTS week_projection (
    repo_id  TEXT NOT NULL REFERENCES repo(id) ON DELETE CASCADE,
    week_end TEXT NOT NULL,
    body     TEXT NOT NULL,
    at       TEXT NOT NULL,
    PRIMARY KEY (repo_id, week_end)
  );
  CREATE TABLE IF NOT EXISTS week_retro (
    repo_id  TEXT NOT NULL REFERENCES repo(id) ON DELETE CASCADE,
    week_end TEXT NOT NULL,
    body     TEXT NOT NULL,
    at       TEXT NOT NULL,
    PRIMARY KEY (repo_id, week_end)
  );
  CREATE TABLE IF NOT EXISTS week_retro_taken (
    repo_id  TEXT NOT NULL,
    week_end TEXT NOT NULL,
    idx      INTEGER NOT NULL,
    actor_id TEXT NOT NULL,
    at       TEXT NOT NULL,
    PRIMARY KEY (repo_id, week_end, idx)
  );
  `;
@@ -0,0 +1,92 @@
/**
 * What an issue will cost, as a range, from what past issues of its size and
 * kind cost (#8704). Measured, never guessed, and no agent run is spent: the
 * history is the ledger of finished work. Same history, same range. Plain data
 * in and out; `issueHistory` is the one read.
 */
import type { Database } from "bun:sqlite";
import type { Issue } from "../core/issues.ts";
/** Samples a group needs before it may speak; fewer and the estimate says so. */
export const MIN_SAMPLES = 3;
/** Samples at which a group is trusted. */
export const SURE_SAMPLES = 8;
/** The most past issues one estimate reads. */
const HISTORY_MAX = 400;
export type Size = "small" | "medium" | "large";
export interface Sample {
  readonly size: Size;
  readonly kind: string;
  readonly usd: number;
}
export type Estimate =
  | { readonly known: true; readonly low: number; readonly mid: number; readonly high: number; readonly samples: number; readonly basis: string }
  | { readonly known: false; readonly samples: number; readonly basis: string };
/** How big an issue reads, from the words written on it. */
export function sizeOf(issue: Pick<Issue, "title" | "body">): Size {
  const n = issue.title.length + issue.body.length;
  return n < 400 ? "small" : n < 1500 ? "medium" : "large";
}
const quantile = (sorted: readonly number[], q: number): number => sorted[Math.round((sorted.length - 1) * q)]!;
const cents = (n: number): number => Math.round(n * 100) / 100;
function rangeOf(group: readonly Sample[], basis: string): Estimate {
  const usd = group.map((s) => s.usd).sort((a, b) => a - b);
  return {
    known: true,
    low: cents(quantile(usd, 0.25)),
    mid: cents(quantile(usd, 0.5)),
    high: cents(quantile(usd, 0.75)),
    samples: usd.length,
    basis,
  };
}
/** Past issues of the same size and kind; if too few, of the same size; if still too few, no estimate. */
export function estimate(history: readonly Sample[], size: Size, kind: string): Estimate {
  const same = history.filter((s) => s.size === size && s.kind === kind);
  if (same.length >= MIN_SAMPLES) return rangeOf(same, `${same.length} past ${size} ${kind === "" ? "issues" : `“${kind}” issues`}`);
  const sized = history.filter((s) => s.size === size);
  if (sized.length >= MIN_SAMPLES) return rangeOf(sized, `${sized.length} past ${size} issues`);
  return { known: false, samples: sized.length, basis: `too little history: ${sized.length} past ${size} issues` };
}
/** The kind of an issue: its first label by name, lowercase, or "". */
export const kindOf = (labels: readonly string[]): string => [...labels].map((l) => l.toLowerCase()).sort()[0] ?? "";
/** Labels of the given issues, by issue id (the issue_label key leads with the issue). */
export function labelsOf(db: Database, issueIds: readonly string[]): Map<string, string[]> {
  const out = new Map<string, string[]>();
  for (let at = 0; at < issueIds.length; at += 200) {
    const part = issueIds.slice(at, at + 200);
    const rows = db
      .query<{ issue_id: string; name: string }, string[]>(
        `SELECT il.issue_id, l.name FROM issue_label il JOIN label l ON l.id = il.label_id
          WHERE il.issue_id IN (${part.map((_, i) => `?${i + 1}`).join(",")})`,
      )
      .all(...part);
    for (const r of rows) out.set(r.issue_id, [...(out.get(r.issue_id) ?? []), r.name]);
  }
  return out;
}
/** What closed issues cost: every agent run on each, summed; the latest {@link HISTORY_MAX} by number. */
export function issueHistory(db: Database, repoId: string): Sample[] {
  const rows = db
    .query<{ id: string; title: string; body: string; usd: number }, [string, number]>(
      `SELECT i.id, i.title, i.body,
              (SELECT SUM(r.cost_usd) FROM run r WHERE r.issue_id = i.id AND r.kind = 'agent') AS usd
         FROM issue i
        WHERE i.repo_id = ?1 AND i.kind = 'issue' AND i.state = 'closed' AND i.sealed = 0 AND i.close_reason = 'done' AND usd > 0
        ORDER BY i.number DESC LIMIT ?2`,
    )
    .all(repoId, HISTORY_MAX);
  const labels = labelsOf(db, rows.map((r) => r.id));
  return rows.map((r) => ({ size: sizeOf(r), kind: kindOf(labels.get(r.id) ?? []), usd: r.usd }));
}
@@ -0,0 +1,263 @@
/**
 * The week's retrospective (#8704): when a weekly window closes the forge
 * writes one frozen screen per repository, unasked — what shipped against the
 * projection it made when the window opened, how close the estimates ran,
 * what cost most for least, what got stuck and why — and ends it in at most
 * three proposals. A proposal changes nothing until a person takes it
 * (`actions/week.ts`). Plain code over the ledger, no model, no agent run.
 */
import type { Database } from "bun:sqlite";
import type { Repo } from "../core/repos.ts";
import { nextUp } from "../core/next_up.ts";
import type { Estimate } from "./estimate.ts";
import { cutLine, priceRows, projection, weekCapacity, type Confidence } from "./week.ts";
export const WEEK_MS = 7 * 86_400_000;
export const MAX_PROPOSALS = 3;
/** A run that ended failed this many times in the window marks an issue stuck. */
const STUCK_FAILS = 2;
export interface Projected {
  readonly sentence: string;
  readonly fits: readonly number[];
  readonly shipLow: number;
  readonly shipHigh: number;
  readonly confidence: Confidence;
  readonly ranges: Readonly<Record<string, { low: number; high: number }>>;
}
export interface Line {
  readonly number: number;
  readonly title: string;
  readonly usd: number;
  readonly why: string;
}
export interface Proposal {
  /** The one change a tap makes: put the issue behind the Later gate. */
  readonly kind: "not_now";
  readonly number: number;
  readonly words: string;
}
export interface Retro {
  readonly weekEnd: string;
  readonly shipped: readonly Line[];
  readonly projected: Projected | null;
  /** Shipped issues that had a range, and how many cost inside it. */
  readonly accuracy: { readonly compared: number; readonly inside: number };
  readonly costly: readonly Line[];
  readonly stuck: readonly Line[];
  readonly proposals: readonly Proposal[];
}
const usd = (n: number): string => `$${n.toFixed(2)}`;
/** The projection made now for the open window; null while no weekly reset is known. */
export function projectNow(db: Database, repo: Repo, now: Date): { weekEnd: string; projected: Projected } | null {
  const capacity = weekCapacity(db, now);
  if (capacity?.resetsAt == null) return null;
  const rows = nextUp(db, repo).rows;
  const priced = priceRows(db, repo.id, rows);
  const cut = cutLine(priced, capacity);
  const ranges: Record<string, { low: number; high: number }> = {};
  for (const p of priced) if (p.estimate.known) ranges[String(p.number)] = rangeOf(p.estimate);
  return {
    weekEnd: capacity.resetsAt,
    projected: {
      sentence: projection(cut, rows.length, capacity),
      fits: cut.fits,
      shipLow: cut.shipLow,
      shipHigh: cut.shipHigh,
      confidence: cut.confidence,
      ranges,
    },
  };
}
const rangeOf = (e: Estimate & { known: true }) => ({ low: e.low, high: e.high });
interface SpentRow {
  number: number;
  title: string;
  state: string;
  usd: number;
  failed: number;
  last: string;
}
/** What each issue touched in the window cost, and how its runs ended; the dearest first. */
export function windowSpend(db: Database, repoId: string, from: string, to: string): SpentRow[] {
  const runs = db
    .query<{ id: string; issue_id: string; cost_usd: number; state: string; summary: string }, [string, string, string]>(
      `SELECT r.id, r.issue_id, r.cost_usd, r.state, r.summary FROM run r
        WHERE r.kind = 'agent' AND r.started_at >= ?2 AND r.started_at < ?3 AND r.repo_id = ?1 AND r.issue_id IS NOT NULL`,
    )
    .all(repoId, from, to);
  const by = new Map<string, { usd: number; failed: number; last: string; lastId: string }>();
  for (const r of runs) {
    const was = by.get(r.issue_id) ?? { usd: 0, failed: 0, last: "", lastId: "" };
    was.usd += r.cost_usd;
    if (r.state === "failed") {
      was.failed++;
      if (r.id > was.lastId) {
        was.lastId = r.id;
        was.last = r.summary;
      }
    }
    by.set(r.issue_id, was);
  }
  const out: SpentRow[] = [];
  for (const [issueId, w] of by) {
    const i = db
      .query<{ number: number; title: string; state: string; sealed: number }, [string]>(
        "SELECT number, title, state, sealed FROM issue WHERE id = ?1 AND kind = 'issue'",
      )
      .get(issueId);
    if (i !== null && i.sealed === 0) out.push({ number: i.number, title: i.title, state: i.state, usd: w.usd, failed: w.failed, last: w.last });
  }
  return out.sort((a, b) => b.usd - a.usd || a.number - b.number);
}
/** Issues closed done in the window, with the spend of every run on each. */
export function windowShipped(db: Database, repoId: string, from: string, to: string): Line[] {
  return db
    .query<{ number: number; title: string; usd: number }, [string, string, string]>(
      `SELECT i.number, i.title, COALESCE((SELECT SUM(cost_usd) FROM run WHERE issue_id = i.id AND kind = 'agent'), 0) AS usd
         FROM issue i
        WHERE i.repo_id = ?1 AND i.kind = 'issue' AND i.state = 'closed' AND i.sealed = 0 AND i.close_reason = 'done'
          AND i.closed_at >= ?2 AND i.closed_at < ?3
        ORDER BY i.number`,
    )
    .all(repoId, from, to)
    .map((r) => ({ number: r.number, title: r.title, usd: r.usd, why: `cost ${usd(r.usd)}` }));
}
/** A failed run's words reduced to a class: its own output is never copied, since it may hold anything. */
export function failureClass(summary: string): string {
  const t = summary.toLowerCase();
  if (/time ?out|timed out/.test(t)) return "timed out";
  if (/limit|quota|rate/.test(t)) return "hit a usage limit";
  if (/check|ci\b|lint|type/.test(t)) return "its check failed";
  if (/test/.test(t)) return "its tests failed";
  if (/conflict|merge/.test(t)) return "hit a merge conflict";
  return "ended without finishing";
}
/** Pure: the retrospective from what was read. */
export function composeRetro(
  weekEnd: string,
  shipped: readonly Line[],
  spent: readonly SpentRow[],
  projected: Projected | null,
): Retro {
  let compared = 0;
  let inside = 0;
  for (const s of shipped) {
    const range = projected?.ranges[String(s.number)];
    if (range === undefined) continue;
    compared++;
    if (s.usd >= range.low && s.usd <= range.high) inside++;
  }
  const open = spent.filter((s) => s.state === "open" && s.usd > 0);
  const costly = open
    .slice(0, MAX_PROPOSALS)
    .map((s) => ({ number: s.number, title: s.title, usd: s.usd, why: `spent ${usd(s.usd)} and is still open` }));
  const stuck = open
    .filter((s) => s.failed >= STUCK_FAILS)
    .map((s) => ({
      number: s.number,
      title: s.title,
      usd: s.usd,
      why: `${s.failed} failed runs, the last ${failureClass(s.last)}`,
    }));
  const picked = new Map<number, Proposal>();
  for (const l of [...stuck, ...costly]) {
    if (picked.size >= MAX_PROPOSALS) break;
    if (!picked.has(l.number))
      picked.set(l.number, {
        kind: "not_now",
        number: l.number,
        words: `Put #${l.number} behind the Later gate: it ${l.why.startsWith("spent") ? l.why : `has ${l.why}`}.`,
      });
  }
  return { weekEnd, shipped, projected, accuracy: { compared, inside }, costly, stuck, proposals: [...picked.values()] };
}
/** Write the retrospective of the window that ended at `weekEnd`, once. True when this call wrote it. */
export function writeRetro(db: Database, repo: Repo, weekEnd: string, now: Date): boolean {
  const had = db
    .query<{ n: number }, [string, string]>("SELECT COUNT(*) AS n FROM week_retro WHERE repo_id = ?1 AND week_end = ?2")
    .get(repo.id, weekEnd);
  if (had !== null && had.n > 0) return false;
  const from = new Date(Date.parse(weekEnd) - WEEK_MS).toISOString();
  const stored = db
    .query<{ body: string }, [string, string]>("SELECT body FROM week_projection WHERE repo_id = ?1 AND week_end = ?2")
    .get(repo.id, weekEnd);
  const projected = stored === null ? null : (JSON.parse(stored.body) as Projected);
  const retro = composeRetro(weekEnd, windowShipped(db, repo.id, from, weekEnd), windowSpend(db, repo.id, from, weekEnd), projected);
  db.query("INSERT OR IGNORE INTO week_retro (repo_id, week_end, body, at) VALUES (?1, ?2, ?3, ?4)").run(
    repo.id,
    weekEnd,
    JSON.stringify(retro),
    now.toISOString(),
  );
  return true;
}
/** The latest retrospective of a repository, or undefined. */
export function latestRetro(db: Database, repoId: string): Retro | undefined {
  const row = db
    .query<{ body: string }, [string]>("SELECT body FROM week_retro WHERE repo_id = ?1 ORDER BY week_end DESC LIMIT 1")
    .get(repoId);
  return row === null ? undefined : (JSON.parse(row.body) as Retro);
}
/** Which proposals of a retrospective have been taken. */
export function takenOf(db: Database, repoId: string, weekEnd: string): Set<number> {
  return new Set(
    db
      .query<{ idx: number }, [string, string]>("SELECT idx FROM week_retro_taken WHERE repo_id = ?1 AND week_end = ?2")
      .all(repoId, weekEnd)
      .map((r) => r.idx),
  );
}
/**
 * Each hour: close the retrospective of every window that has ended, then keep
 * the projection of the window that is open. Only repositories with a ranked
 * list take part. Safe to call as often as you like.
 */
export function tickWeeks(db: Database, repos: readonly Repo[], now: Date): Repo[] {
  const wrote: Repo[] = [];
  for (const repo of repos) {
    const due = db
      .query<{ week_end: string }, [string, string]>(
        `SELECT p.week_end FROM week_projection p
          WHERE p.repo_id = ?1 AND p.week_end <= ?2
            AND NOT EXISTS (SELECT 1 FROM week_retro r WHERE r.repo_id = p.repo_id AND r.week_end = p.week_end)`,
      )
      .all(repo.id, now.toISOString());
    for (const d of due) if (writeRetro(db, repo, d.week_end, now)) wrote.push(repo);
    const open = projectNow(db, repo, now);
    if (open !== null)
      db.query("INSERT OR IGNORE INTO week_projection (repo_id, week_end, body, at) VALUES (?1, ?2, ?3, ?4)").run(
        repo.id,
        open.weekEnd,
        JSON.stringify(open.projected),
        now.toISOString(),
      );
  }
  return wrote;
}
/** Repositories that have a ranked list: the ones whose week is planned. */
export function plannedRepoIds(db: Database): string[] {
  return db
    .query<{ repo_id: string }, []>(
      `SELECT DISTINCT i.repo_id FROM issue_rank k JOIN issue i ON i.id = k.issue_id WHERE i.state = 'open'`,
    )
    .all()
    .map((r) => r.repo_id);
}
@@ -0,0 +1,127 @@
/**
 * The week is the sprint (#8704): the subscription's weekly reset is the
 * boundary and what the crew may still spend before it is the capacity. The
 * cut line falls on the owner's ranked list after the last issue whose
 * running estimate still fits, building strictly from the top, so reranking
 * moves it. Same list, same history, same capacity: same line. No agent run
 * is spent. `cutLine` is plain data in and out; `weekCapacity` is the one read.
 */
import type { Database } from "bun:sqlite";
import type { NextRow } from "../core/next_up.ts";
import { standings } from "../core/standing.ts";
import { listCredentials } from "../core/subscriptions.ts";
import { estimate, issueHistory, kindOf, labelsOf, MIN_SAMPLES, SURE_SAMPLES, sizeOf, type Estimate, type Sample } from "./estimate.ts";
export interface Capacity {
  /** What the crew may still spend before the reset, in US dollars. */
  readonly usd: number;
  /** The soonest weekly reset among the accounts that report one, ISO. */
  readonly resetsAt: string | null;
}
/** The crew's remaining weekly capacity over every account whose cap is known; null when none is. */
export function weekCapacity(db: Database, now: Date): Capacity | null {
  const ids = listCredentials(db).map((c) => c.id);
  let usd = 0;
  let resetsAt: string | null = null;
  let any = false;
  for (const s of standings(db, ids, now).values()) {
    const week = s.windows.find((w) => w.window === "week");
    if (week?.crewRemaining == null) continue;
    any = true;
    usd += week.crewRemaining.value;
    const at = week.resetsAt?.value ?? null;
    if (at !== null && (resetsAt === null || at < resetsAt)) resetsAt = at;
  }
  return any ? { usd: Math.round(usd * 100) / 100, resetsAt } : null;
}
export interface Priced {
  readonly number: number;
  readonly estimate: Estimate;
}
export type Confidence = "high" | "medium" | "low";
export interface Cut {
  /** Issue numbers that fit this week, in list order; the rest read as next week. */
  readonly fits: readonly number[];
  /** The least and most that should ship by the reset, from the range's two ends. */
  readonly shipLow: number;
  readonly shipHigh: number;
  readonly confidence: Confidence;
  /** Why there is no line: capacity or history missing. Null when drawn. */
  readonly unsure: string | null;
}
/** Walk the list from the top, adding each row's cost while it fits `usd`; stop at the first that does not. */
function fitting(rows: readonly Priced[], cost: (e: Estimate & { known: true }) => number, fill: number, usd: number): number[] {
  const out: number[] = [];
  let used = 0;
  for (const r of rows) {
    used += r.estimate.known ? cost(r.estimate) : fill;
    if (used > usd) break;
    out.push(r.number);
  }
  return out;
}
/**
 * Where the week's capacity ends on the ranked list. An issue with no
 * estimate counts as the median of those that have one; with none at all
 * there is no line, and it says so.
 */
export function cutLine(rows: readonly Priced[], capacity: Capacity | null): Cut {
  const none = (unsure: string): Cut => ({ fits: [], shipLow: 0, shipHigh: 0, confidence: "low", unsure });
  if (capacity === null) return none("the weekly capacity has not been read yet");
  const known = rows.flatMap((r) => (r.estimate.known ? [r.estimate] : []));
  if (known.length === 0) return none("there is too little history to estimate any issue");
  const mids = known.map((e) => e.mid).sort((a, b) => a - b);
  const fill = mids[Math.floor((mids.length - 1) / 2)]!;
  const fits = fitting(rows, (e) => e.mid, fill, capacity.usd);
  const least = fitting(rows, (e) => e.high, fill, capacity.usd).length;
  const most = fitting(rows, (e) => e.low, fill, capacity.usd).length;
  const weakest = Math.min(...rows.map((r) => r.estimate.samples));
  const confidence: Confidence =
    known.length < rows.length ? "low" : weakest >= SURE_SAMPLES ? "high" : weakest >= MIN_SAMPLES ? "medium" : "low";
  return { fits, shipLow: least, shipHigh: most, confidence, unsure: null };
}
/** The projection in one sentence. */
export function projection(cut: Cut, total: number, capacity: Capacity | null): string {
  if (cut.unsure !== null) return `No projection yet: ${cut.unsure}.`;
  const by = capacity?.resetsAt == null ? "the reset" : `the reset on ${capacity.resetsAt.slice(0, 10)}`;
  const count = cut.shipLow === cut.shipHigh ? `${cut.shipHigh}` : `${cut.shipLow} to ${cut.shipHigh}`;
  return `At the current rate ${count} of the ${total} issues on the list should ship by ${by}; ${cut.confidence} confidence.`;
}
/** Price each row of the list from the repository's history. */
export function priceRows(db: Database, repoId: string, rows: readonly NextRow[], history?: readonly Sample[]): Priced[] {
  const past = history ?? issueHistory(db, repoId);
  const labels = labelsOf(db, rows.map((r) => r.issue.id));
  return rows.map((r) => ({
    number: r.issue.number,
    estimate: estimate(past, sizeOf(r.issue), kindOf(labels.get(r.issue.id) ?? [])),
  }));
}
/** "$1.20–$3.40" or why there is none. */
export function rangeWords(e: Estimate): string {
  return e.known ? `$${e.low.toFixed(2)}–$${e.high.toFixed(2)} (${e.basis})` : e.basis;
}
/** Everything the page, the terminal and MCP draw of the week on Next up, from one read. */
export interface WeekView {
  readonly priced: readonly Priced[];
  readonly cut: Cut;
  readonly capacity: Capacity | null;
  readonly sentence: string;
}
export function weekView(db: Database, repoId: string, rows: readonly NextRow[], now: Date): WeekView {
  const capacity = weekCapacity(db, now);
  const priced = priceRows(db, repoId, rows);
  const cut = cutLine(priced, capacity);
  return { priced, cut, capacity, sentence: projection(cut, rows.length, capacity) };
}
@@ -174,5 +174,6 @@
export { tool as vision } from "./vision.ts";
export { tool as wait_for } from "./wait_for.ts";
export { tool as watch } from "./watch.ts";
export { tool as waves } from "./waves.ts";
export { tool as week } from "./week.ts";
export { tool as whoami_can } from "./whoami_can.ts";
export { tool as write_file } from "./write_file.ts";
@@ -1,9 +1,16 @@
import { placeOf, rankIssue } from "../../../actions/next.ts";
import { nextUp, TOP, type NextRow } from "../../../core/next_up.ts";
import { weekView, type WeekView } from "../../../flow/week.ts";
import { sealedScope } from "../../../core/sealed.ts";
import { bad, good, type Tool, APP_ARG, planRepo, isAnswer, issueArg } from "../shared.ts";
const brief = (r: NextRow) => ({
const brief = (r: NextRow, week?: WeekView) => ({
  ...(week === undefined
    ? {}
    : {
        estimate: week.priced.find((p) => p.number === r.issue.number)?.estimate,
        thisWeek: week.cut.fits.includes(r.issue.number),
      }),
  issue: r.issue.number,
  title: r.issue.title,
  place: r.place,
@@ -15,7 +22,7 @@
const brief = (r: NextRow) => ({
export const tool: Tool = {
  name: "next_up",
  doc: "an app's one ranked list, the crew builds strictly from the top (`app`; with `issue` and `to` — `top`, `not-now` or `after:<number>` — a writer moves that issue and it saves at once; `top` lifts a gated issue past the Later gate; `all` lists beyond the top ten)",
  doc: "an app's one ranked list, the crew builds strictly from the top (`app`; with `issue` and `to` — `top`, `not-now` or `after:<number>` — a writer moves that issue and it saves at once; `top` lifts a gated issue past the Later gate; `all` lists beyond the top ten; each row carries its cost `estimate` range and `thisWeek`, and `projection` is one sentence on what the week can ship)",
  description: "The ranked list the crew builds from; `issue` + `to` (top, not-now, after:N) moves one.",
  inputSchema: {
    type: "object",
@@ -43,11 +50,13 @@
export const tool: Tool = {
    }
    const next = nextUp(ctx.app.db, repo, sealedScope(ctx.app.db, repo, user));
    const all = args["all"] === true;
    const week = weekView(ctx.app.db, repo.id, next.rows, new Date());
    return good({
      next: (all ? next.rows : next.rows.slice(0, TOP)).map(brief),
      projection: week.sentence,
      next: (all ? next.rows : next.rows.slice(0, TOP)).map((r) => brief(r, week)),
      more: all ? 0 : Math.max(0, next.rows.length - TOP),
      notNow: next.notNowTotal,
      ...(all ? { notNowRows: next.notNow.map(brief) } : {}),
      ...(all ? { notNowRows: next.notNow.map((r) => brief(r)) } : {}),
    });
  },
};
@@ -0,0 +1,30 @@
import { takeProposal } from "../../../actions/week.ts";
import { latestRetro, takenOf } from "../../../flow/retro.ts";
import { bad, good, type Tool, APP_ARG, planRepo, isAnswer } from "../shared.ts";
export const tool: Tool = {
  name: "week",
  doc: "an app's last weekly retrospective, the same page as /:owner/:name/week (`app`): `{ weekEnd, shipped, projected, accuracy, costly, stuck, proposals: [{ number, words, taken }] }`; with `take` (a proposal's index, 0 to 2) a writer who is a person (never an agent) takes that one proposal, which puts its issue behind the Later gate; nothing else ever changes",
  description: "The week's retrospective; `take` accepts one proposal.",
  inputSchema: {
    type: "object",
    properties: { app: APP_ARG, take: { type: "integer", minimum: 0, maximum: 2 } },
    required: ["app"],
  },
  writes: true,
  readsWithout: "take",
  run(ctx, user, args) {
    const repo = planRepo(ctx, user, args);
    if (isAnswer(repo)) return repo;
    const retro = latestRetro(ctx.app.db, repo.id);
    if (retro === undefined) return good({ says: "No weekly window has closed yet." });
    if (args["take"] !== undefined) {
      const idx = args["take"];
      if (typeof idx !== "number" || !Number.isInteger(idx) || idx < 0 || idx > 2) return bad("invalid_take", "take is a proposal's index, 0 to 2");
      const took = takeProposal(ctx.app, user, repo, retro.weekEnd, idx);
      
        sentinelcrew
        11d ago
        
      
      No check that user is a person (not an agent) before taking a proposal. Move the person-and-writer check into takeProposal so page, MCP and terminal all share it, and test it.
    
      if (!took.ok) return bad(took.error.kind === "not_found" ? "no_such_proposal" : took.error.kind, took.error.message);
    }
    const taken = takenOf(ctx.app.db, repo.id, retro.weekEnd);
    return good({ ...retro, proposals: retro.proposals.map((p, i) => ({ number: p.number, words: p.words, taken: taken.has(i) })) });
  },
};
@@ -201,6 +201,7 @@
import { globalMapPage } from "../web/pages/global-map.ts";
import { mapPage } from "../web/pages/map.ts";
import { firstSubmit } from "../web/pages/first.ts";
import { nextPage, nextSubmit } from "../web/pages/next.ts";
import { weekPage, weekSubmit } from "../web/pages/week.ts";
import {
  milestonePage,
  milestonesPage,
@@ -1033,6 +1034,8 @@
export function buildRouter(): Router<Handler> {
  router.add("GET", "/:owner/:name/map", mapPage);
  router.add("GET", "/:owner/:name/next", nextPage);
  router.add("POST", "/:owner/:name/next", nextSubmit);
  router.add("GET", "/:owner/:name/week", weekPage);
  router.add("POST", "/:owner/:name/week", weekSubmit);
  router.add("POST", "/:owner/:name/issues/:number/first", firstSubmit);
  router.add("GET", "/:owner/:name/bets", betsPage);
  router.add("POST", "/:owner/:name/bets/propose", betPropose);
@@ -5,6 +5,8 @@
 */
import { runModelReview } from "./actions/model_review.ts";
import { getRepoById } from "./core/repos.ts";
import { plannedRepoIds, tickWeeks } from "./flow/retro.ts";
import { BOOT_ACTOR, setSignup, signupFromEnv } from "./settings/signup.ts";
import { startMemorySampler } from "./boards/memory.ts";
import { startSampler } from "./boards/sampler.ts";
@@ -640,6 +642,16 @@
const modelReviewTimer = setInterval(() => {
    app.log.warn("model review failed", { error: String(error) });
  }
}, 3_600_000);
// The week is the sprint (#8704): at each weekly reset the forge writes its retrospective, unasked.
const weekTimer = setInterval(() => {
  try {
    const repos = plannedRepoIds(app.db).flatMap((id) => getRepoById(app.db, id) ?? []);
    for (const repo of tickWeeks(app.db, repos, new Date()))
      app.bus.append({ kind: "week.retro", repoId: repo.id, payload: {} });
  } catch (error) {
    app.log.warn("week retrospective failed", { error: String(error) });
  }
}, 3_600_000);
const processTimer = setInterval(processTick, 60_000);
processTick();
// A new version proves itself against the public URL; a failed one again, 5 min after and backing off to hourly (release/prove.ts).
@@ -791,6 +803,7 @@
function drain(signal: NodeJS.Signals): Promise<unknown> {
  clearInterval(processTimer);
  clearInterval(holdTimer);
  clearInterval(modelReviewTimer);
  clearInterval(weekTimer);
  clearInterval(leaseTimer);
  // The platform's SIGTERM: the listener stays open while routers learn
  // this process is going. A person's Ctrl-C does not wait for routers.
@@ -78,6 +78,7 @@
import { stalledScreen } from "./screens/stalled.ts";
import { issuesScreen, newIssueScreen } from "./screens/issues.ts";
import { limbsScreen } from "./screens/limbs.ts";
import { nextScreen } from "./screens/next.ts";
import { weekScreen } from "./screens/week.ts";
import { newPullScreen } from "./screens/newpull.ts";
import { newForgeScreen } from "./screens/newforge.ts";
import { newOrgScreen } from "./screens/neworg.ts";
@@ -133,6 +134,12 @@
const REPO_VERBS: readonly {
    title: "Next up in a repository",
    open: (f, ctx, repo) => nextScreen(f, ctx, repo),
  },
  {
    // The retrospective the forge wrote at the last weekly reset, and its proposals (#8704).
    id: "week",
    title: "The week in a repository",
    open: (f, ctx, repo) => weekScreen(f, ctx, repo),
  },
  {
    // What the crew's tokens bought on one app, as MCP `returns` with `repo` (#7271).
    id: "repo-usage",
@@ -15,6 +15,7 @@
import { rankedWords, rankIssue, stepTo, type Place, placeOf } from "../../actio
import { nextUp, type NextRow } from "../../core/next_up.ts";
import { canRead, canWrite, type Repo } from "../../core/repos.ts";
import { sealedScope } from "../../core/sealed.ts";
import { rangeWords, weekView, type WeekView } from "../../flow/week.ts";
import type { Ctx, Screen } from "../app/app.ts";
import { binding } from "../app/keys.ts";
import { fill, len, split } from "../ui/layout.ts";
@@ -32,6 +33,7 @@
export function nextScreen(f: Session, ctx: Ctx, repo: Repo): Screen {
  const state = new ListState();
  let rows: readonly NextRow[] = [];
  let away = 0;
  let week: WeekView | undefined;
  let loaded = false;
  // Read at use, not at open: access can change under a session.
  const may = (): boolean =>
@@ -41,10 +43,12 @@
export function nextScreen(f: Session, ctx: Ctx, repo: Repo): Screen {
    if (!canRead(f.db, repo, f.user)) {
      rows = [];
      away = 0;
      week = undefined;
    } else {
      const next = nextUp(f.db, repo, sealedScope(f.db, repo, f.user));
      rows = next.rows;
      away = next.notNowTotal;
      week = weekView(f.db, repo.id, rows, new Date());
    }
    loaded = true;
    if (follow !== undefined) {
@@ -78,12 +82,21 @@
export function nextScreen(f: Session, ctx: Ctx, repo: Repo): Screen {
    if (row !== undefined) ctx.push(issueScreen(f, ctx, local(f, repo), row.issue.number));
  };
  // The cut line is a muted line under the last row that fits, as on the page.
  const listRows = (): ListRow[] =>
    rows.map((r) => ({
      title: `${r.place === null ? "·" : r.place}. #${r.issue.number} ${r.issue.title}`,
      secondary: r.role === "blocker" ? "Blocker" : "Enabler",
      meta: [r.onIt === null ? "" : `on it: ${r.onIt}`, r.why ?? ""].filter((x) => x !== "").join(" · "),
    }));
    rows.map((r, at) => {
      const estimate = week?.priced.find((p) => p.number === r.issue.number)?.estimate;
      const cut = week?.cut;
      const ends = cut !== undefined && cut.unsure === null && cut.fits.length > 0 && at === cut.fits.length - 1;
      return {
        title: `${r.place === null ? "·" : r.place}. #${r.issue.number} ${r.issue.title}`,
        secondary: r.role === "blocker" ? "Blocker" : "Enabler",
        meta: [estimate === undefined ? "" : rangeWords(estimate), r.onIt === null ? "" : `on it: ${r.onIt}`, r.why ?? ""]
          .filter((x) => x !== "")
          .join(" · "),
        ...(ends ? { note: `── this week ends here (${cut.fits.length} fit): below reads as next week ──` } : {}),
      };
    });
  const screen: Screen = {
    title: "Next up",
@@ -110,7 +123,7 @@
export function nextScreen(f: Session, ctx: Ctx, repo: Repo): Screen {
        ? "Loading…"
        : rows.length === 0
          ? "Nothing is ready: everything open waits for something."
          : `The crew builds strictly from the top${may() ? "" : " · you can read this order, not change it"}${away > 0 ? ` · ${away} not now` : ""}`;
          : `${week?.sentence ?? ""}${may() ? "" : " · you can read this order, not change it"}${away > 0 ? ` · ${away} not now` : ""}`;
      s.text(head!.x, head!.y, truncate(note, head!.w), style(c.mutedFg, c.bg), head!.x + head!.w);
      drawList(s, list!, c, state, listRows());
      hitList(ctx, list!, state, rows.length, { open });
@@ -0,0 +1,114 @@
/**
 * The week in the terminal (#8704): the retrospective the forge wrote at the
 * last weekly reset, the page's door and not a second implementation. Its
 * proposals are the list; `enter` or `a` takes the one under the cursor
 * through `takeProposal`, the action the page and MCP `week` reach, so who may
 * take one is decided there: a reader or an agent sees the proposals and the
 * key does nothing. Subscribed to the bus while on the stack, so a new
 * retrospective (`week.retro`) or a proposal taken anywhere (`issue.ranked`)
 * updates the screen here.
 */
import { takeProposal } from "../../actions/week.ts";
import { canRead, canWrite, type Repo } from "../../core/repos.ts";
import { latestRetro, takenOf, type Retro } from "../../flow/retro.ts";
import type { Ctx, Screen } from "../app/app.ts";
import { binding } from "../app/keys.ts";
import { fill, len, split } from "../ui/layout.ts";
import { style } from "../term/style.ts";
import { truncate } from "../term/width.ts";
import type { Session } from "../session.ts";
import { ListState, drawList, hitList, live, type ListRow } from "./common.ts";
const LIVE_KINDS = ["week.retro", "issue.ranked"];
/** The retrospective's screen of facts, one line each. */
export function summaryLines(retro: Retro): string[] {
  const p = retro.projected;
  return [
    `Week ending ${retro.weekEnd.slice(0, 10)}`,
    p === null
      ? `${retro.shipped.length} shipped; no projection was made.`
      : `${retro.shipped.length} shipped against a projection of ${p.shipLow === p.shipHigh ? p.shipHigh : `${p.shipLow} to ${p.shipHigh}`} (${p.confidence} confidence).`,
    retro.accuracy.compared === 0
      ? "No shipped issue had an estimate to compare."
      : `${retro.accuracy.inside} of ${retro.accuracy.compared} shipped issues cost inside their range.`,
    `Cost most, still open: ${retro.costly.length === 0 ? "none" : retro.costly.map((l) => `#${l.number}`).join(", ")}`,
    `Stuck: ${retro.stuck.length === 0 ? "none" : retro.stuck.map((l) => `#${l.number} (${l.why})`).join("; ")}`,
  ];
}
export function weekScreen(f: Session, ctx: Ctx, repo: Repo): Screen {
  const state = new ListState();
  let retro: Retro | undefined;
  let taken: ReadonlySet<number> = new Set();
  let loaded = false;
  // Read at use, not at open: access can change under a session.
  const may = (): boolean => f.user !== undefined && f.user.kind === "user" && canWrite(f.db, repo, f.user);
  const reload = (): void => {
    if (!canRead(f.db, repo, f.user)) {
      retro = undefined;
      taken = new Set();
    } else {
      retro = latestRetro(f.db, repo.id);
      taken = retro === undefined ? new Set() : takenOf(f.db, repo.id, retro.weekEnd);
    }
    loaded = true;
    state.clamp(retro?.proposals.length ?? 0);
    ctx.invalidate();
  };
  const take = (): void => {
    if (retro === undefined || !may() || taken.has(state.index)) return;
    const done = takeProposal(f.app, f.user!, repo, retro.weekEnd, state.index);
    if (!done.ok) {
      ctx.toast(done.error.message, "danger");
      return;
    }
    reload();
    ctx.toast(done.value, "success");
  };
  const listRows = (): ListRow[] =>
    (retro?.proposals ?? []).map((p, i) => ({
      title: p.words,
      secondary: taken.has(i) ? "Taken" : "Proposed",
    }));
  const screen: Screen = {
    title: "The week",
    get keys() {
      const on = may() && retro !== undefined && !taken.has(state.index) && retro.proposals.length > 0;
      return [binding(["j", "k"], "move cursor"), binding(["enter", "a"], "take it", { disabled: !on })];
    },
    load(signal) {
      live(f, signal, { repoId: repo.id, kinds: LIVE_KINDS }, () => reload());
      reload();
      return Promise.resolve();
    },
    render(area, s) {
      const c = ctx.theme.c;
      const lines = !loaded
        ? ["Loading…"]
        : retro === undefined
          ? ["The forge writes this when the weekly window closes. None has closed yet."]
          : summaryLines(retro);
      const [head, list] = split(area, "v", [len(lines.length + 1), fill(1)]);
      lines.forEach((line, i) =>
        s.text(head!.x, head!.y + i, truncate(line, head!.w), style(c.mutedFg, c.bg), head!.x + head!.w),
      );
      drawList(s, list!, c, state, listRows());
      hitList(ctx, list!, state, retro?.proposals.length ?? 0, { open: take });
    },
    key(e) {
      const n = retro?.proposals.length ?? 0;
      if (state.key(e, n)) return true;
      if (e.ctrl || e.alt) return false;
      if (e.key === "enter" || e.key === "a") take();
      else return false;
      return true;
    },
  };
  return screen;
}
@@ -11,6 +11,7 @@
import { nextUp, TOP, type NextRow } from "../../core/next_up.ts";
import { canWrite, type Repo } from "../../core/repos.ts";
import { notePhase, takeSessionTime } from "../../core/route_timing.ts";
import { sealedScope } from "../../core/sealed.ts";
import { rangeWords, weekView, type Cut, type Priced } from "../../flow/week.ts";
import type { Ctx } from "../../http/context.ts";
import { crumbsFor, loadRepo, notFoundPage, repoBase, repoHeader, repoPalette, signInFirst } from "../chrome.ts";
import { backTo, field, readForm } from "../form.ts";
@@ -75,7 +76,15 @@
function move(base: string, number: number, to: string, label: string, key: stri
  </form>`;
}
function line(base: string, rows: readonly NextRow[], at: number, writer: boolean, back: string, away: boolean): Html {
function line(
  base: string,
  rows: readonly NextRow[],
  at: number,
  writer: boolean,
  back: string,
  away: boolean,
  priced: readonly Priced[] = [],
): Html {
  const r = rows[at]!;
  const n = r.issue.number;
  const numbers = rows.map((x) => x.issue.number);
@@ -94,13 +103,20 @@
function line(base: string, rows: readonly NextRow[], at: number, writer: boolea
    titleAttr: r.issue.title,
    lead: html`${r.place === null ? "·" : String(r.place)}`,
    meta: html`${badge(r.role === "blocker" ? "Blocker" : "Enabler", { variant: r.role === "blocker" ? "secondary" : "outline" })}
      #${n} · ${r.roleWhy}${r.onIt === null ? "" : ` · on it: ${r.onIt}`}${r.why === null ? "" : ` · ${r.why}`}`,
      #${n} · ${r.roleWhy}${away ? null : html` · <span class="estimate">${rangeWords(priced.find((p) => p.number === n)?.estimate ?? { known: false, samples: 0, basis: "no estimate" })}</span>`}${r.onIt === null ? "" : ` · on it: ${r.onIt}`}${r.why === null ? "" : ` · ${r.why}`}`,
    nav: true,
    data: { number: String(n) },
    ...(controls === null ? {} : { after: controls }),
  });
}
/** The cut line: everything above it fits this week's capacity, everything below reads as next week. */
function cutMark(cut: Cut, top: boolean): Html {
  return html`<li class="cut-line" role="separator">${top
    ? "Nothing here fits what is left of this week: all of this reads as next week."
    : `This week ends here (${cut.fits.length} fit): below this line reads as next week.`}</li>`;
}
export function nextPage(ctx: Ctx): Response {
  notePhase(ctx.request, "session", takeSessionTime(ctx.request));
  const repo = loadRepo(ctx);
@@ -113,6 +129,15 @@
export function nextPage(ctx: Ctx): Response {
  const rest = next.rows.length - shown.length;
  const back = all ? `${base}/next?all=1` : `${base}/next`;
  const rendering = performance.now();
  const { priced, cut, sentence } = weekView(ctx.app.db, repo.id, next.rows, new Date());
  const rowsHtml = (): Html[] => {
    const out: Html[] = [];
    shown.forEach((_, at) => {
      if (at === cut.fits.length && cut.unsure === null) out.push(cutMark(cut, at === 0));
      out.push(line(base, next.rows, at, writer, back, false, priced));
    });
    return out;
  };
  const body = html`${repoHeader(ctx, repo, "issues")}
    <div class="page-head mt">
      <h1>Next up</h1>
@@ -124,12 +149,13 @@
export function nextPage(ctx: Ctx): Response {
        Dependencies order work within the list; they are shown, not edited.
      </p>
    </div>
    <p class="muted" id="next-week">${sentence} <a href="${base}/week">The week</a></p>
    <p class="error" id="next-flash" role="alert" hidden></p>
    ${next.rows.length === 0
      ? html`<p class="muted">Nothing is ready: everything open waits for something. <a href="${base}/map">See the map</a>.</p>`
      : card(
          html`<ul class="list setting-list" id="next-list">
            ${shown.map((_, at) => line(base, next.rows, at, writer, back, false))}
            ${rowsHtml()}
          </ul>`,
          { pad: false },
        )}
@@ -0,0 +1,104 @@
/**
 * The week (#8704): `/:owner/:name/week`, the retrospective the forge wrote
 * when the last weekly window closed, on one screen. It ends in at most three
 * proposals, each its own form: one tap by someone who writes here takes it,
 * and nothing else on the page changes anything.
 */
import { takeProposal } from "../../actions/week.ts";
import { canWrite } from "../../core/repos.ts";
import { notePhase, takeSessionTime } from "../../core/route_timing.ts";
import { latestRetro, takenOf, type Line, type Retro } from "../../flow/retro.ts";
import type { Ctx } from "../../http/context.ts";
import { crumbsFor, loadRepo, notFoundPage, repoBase, repoHeader, repoPalette, signInFirst } from "../chrome.ts";
import { backTo, field, readForm } from "../form.ts";
import { html, type Html } from "../html.ts";
import { flashOrJson, page } from "../layout.ts";
import { btn, card, row } from "../ui.ts";
const lines = (base: string, ls: readonly Line[], none: string): Html =>
  ls.length === 0
    ? html`<p class="muted">${none}</p>`
    : card(
        html`<ul class="list setting-list">${ls.map((l) =>
          row({ href: `${base}/issues/${l.number}`, title: l.title, meta: html`#${String(l.number)} · ${l.why}` }),
        )}</ul>`,
        { pad: false },
      );
function screen(base: string, retro: Retro, taken: ReadonlySet<number>, writer: boolean): Html {
  const p = retro.projected;
  const shipped = retro.shipped.length;
  const acc = retro.accuracy;
  return html`<h2>What shipped</h2>
    <p>${p === null
      ? `${shipped} shipped. No projection was made for this week.`
      : `${shipped} shipped against a projection of ${p.shipLow === p.shipHigh ? p.shipHigh : `${p.shipLow} to ${p.shipHigh}`} (${p.confidence} confidence).`}</p>
    ${lines(base, retro.shipped, "Nothing shipped this week.")}
    <h2>Estimate accuracy</h2>
    <p>${acc.compared === 0
      ? "No shipped issue had an estimate to compare."
      : `${acc.inside} of ${acc.compared} shipped issues cost inside their estimated range.`}</p>
    <h2>Cost most for least</h2>
    ${lines(base, retro.costly, "Nothing open spent money this week.")}
    <h2>Stuck</h2>
    ${lines(base, retro.stuck, "Nothing is stuck.")}
    <h2>Proposed changes</h2>
    ${retro.proposals.length === 0
      ? html`<p class="muted">Nothing to propose.</p>`
      : html`<ul class="list setting-list">${retro.proposals.map((pr, idx) =>
          row({
            title: html`${pr.words}`,
            meta: html`${taken.has(idx) ? "Taken." : writer ? "Nothing changes until you tap." : "Only someone who writes here can take it."}`,
            ...(taken.has(idx) || !writer
              ? {}
              : {
                  after: html`<form method="post" action="${base}/week">
                    <input type="hidden" name="week_end" value="${retro.weekEnd}" />
                    <input type="hidden" name="idx" value="${String(idx)}" />
                    ${btn("Take it", { size: "sm" })}
                  </form>`,
                }),
          }),
        )}</ul>`}`;
}
export function weekPage(ctx: Ctx): Response {
  notePhase(ctx.request, "session", takeSessionTime(ctx.request));
  const repo = loadRepo(ctx);
  if (!repo) return notFoundPage(ctx);
  const base = repoBase(repo);
  const writer = ctx.auth.user !== undefined && ctx.auth.user.kind !== "agent" && canWrite(ctx.app.db, repo, ctx.auth.user);
  const retro = latestRetro(ctx.app.db, repo.id);
  const rendering = performance.now();
  const body = html`${repoHeader(ctx, repo, "issues")}
    <div class="page-head mt">
      <h1>The week</h1>
      <p class="muted">${retro === undefined
        ? "The forge writes this when the weekly window closes. None has closed yet."
        : `Written when the window ended ${retro.weekEnd.slice(0, 10)}, once, and never edited.`} <a href="${base}/next">Next up</a></p>
    </div>
    ${retro === undefined ? null : screen(base, retro, takenOf(ctx.app.db, repo.id, retro.weekEnd), writer)}`;
  const response = page({ ctx, title: `The week · ${repo.name}`, crumbs: crumbsFor(repo), palette: repoPalette(ctx, repo), body });
  notePhase(ctx.request, "render", performance.now() - rendering);
  return response;
}
/** POST /:owner/:name/week — `week_end` and `idx`: take one proposal. */
export async function weekSubmit(ctx: Ctx): Promise<Response> {
  const repo = loadRepo(ctx);
  if (!repo) return notFoundPage(ctx);
  if (!ctx.auth.user) return signInFirst(ctx);
  const form = await readForm(ctx, "rw");
  if (form instanceof Response) return form;
  const dest = backTo(form, `${repoBase(repo)}/week`);
  const weekEnd = field(form, "week_end");
  const idx = /^[0-9]$/.test(field(form, "idx")) ? Number(field(form, "idx")) : -1;
  if (!/^\d{4}-\d\d-\d\dT[\d:.]{8,12}Z$/.test(weekEnd) || idx < 0)
    return flashOrJson(ctx, dest, { tone: "danger", message: "Say which proposal." });
  const took = takeProposal(ctx.app, ctx.auth.user, repo, weekEnd, idx);
  if (!took.ok) {
    if (took.error.kind === "not_found") return notFoundPage(ctx);
    return flashOrJson(ctx, dest, { tone: "danger", message: took.error.message });
  }
  return flashOrJson(ctx, dest, { message: took.value });
}
@@ -862,6 +862,9 @@
textarea.editor:focus-visible { outline: none; }
.pipe-repo { font-size: 12.5px; fill: var(--muted-fg); }
.valve-form { display: flex; flex-wrap: wrap; align-items: center; gap: 8px; margin: 4px 0; }
.valve-range { flex: 1 1 12rem; min-width: 8rem; }
/* The week on Next up (#8704): the cut line and a row's cost range. */
.cut-line { list-style: none; padding: 6px 16px; font-size: 13px; color: var(--muted-fg); border-top: 2px dashed var(--series-1); border-bottom: 1px solid var(--border); background: var(--bg); }
.estimate { color: var(--fg); font-variant-numeric: tabular-nums; }
/* The config form (#7336): nested objects as quiet fieldsets, scalar
   arrays as a wrapping row of chips, object arrays as cards. */
.config-group { border-left: 2px solid var(--border); padding-left: 12px; }
@@ -124,7 +124,7 @@
describe("the one list of what asks first", () => {
    "assign", "attach_look", "bet", "board_pins", "board_write", "branches", "capacity", "valves", "cloud_accounts", "close", "confirm_wait",
    "crew", "decisions_by", "detach", "edit", "email_verify", "feed_chips", "feed_dismiss", "flag_set", "flag_winner",
    "follow_mode", "front_page", "hold", "issue_teams", "keep_plan", "labels", "lift", "limb", "make_it_yours", "map", "merge", "new_app",
    "next_up", "notify", "org_create", "origin_apps", "pins", "plan", "profile", "propose_to_parent_forge", "repo_labels", "reports",
    "next_up", "week", "notify", "org_create", "origin_apps", "pins", "plan", "profile", "propose_to_parent_forge", "repo_labels", "reports",
    "restore_drill", "review", "say", "signup", "snapshot_now", "spend", "steer", "sync", "take_back", "take_updates",
    "teams", "tell", "threads", "trail", "upstream", "variant", "wait_for", "watch", "whoami_can", "write_file",
  ]);
@@ -333,6 +333,7 @@
describe("the forge over MCP", () => {
      "repo_labels",
      "wait_for",
      "next_up",
      "week",
      "lift",
      "held",
      "confirm_wait",
@@ -54,6 +54,7 @@
test("a site-admin person is offered the whole roster", () => {
    ["pulls", "Pull requests in a repository", "owner/name"],
    ["milestones", "Milestones in a repository", "owner/name"],
    ["next-up", "Next up in a repository", "owner/name"],
    ["week", "The week in a repository", "owner/name"],
    ["repo-usage", "Usage of a repository", "owner/name"],
    ["new-issue", "New issue", "owner/name"],
    ["new-pull", "New pull request", "owner/name"],
@@ -141,6 +142,7 @@
test("a site-admin agent is offered the roster without the person-only entries",
    ["pulls", "Pull requests in a repository", "owner/name"],
    ["milestones", "Milestones in a repository", "owner/name"],
    ["next-up", "Next up in a repository", "owner/name"],
    ["week", "The week in a repository", "owner/name"],
    ["repo-usage", "Usage of a repository", "owner/name"],
    ["new-issue", "New issue", "owner/name"],
    ["new-pull", "New pull request", "owner/name"],
@@ -199,6 +201,7 @@
test("a member person is offered the signed-in roster without the admin entries"
    ["pulls", "Pull requests in a repository", "owner/name"],
    ["milestones", "Milestones in a repository", "owner/name"],
    ["next-up", "Next up in a repository", "owner/name"],
    ["week", "The week in a repository", "owner/name"],
    ["repo-usage", "Usage of a repository", "owner/name"],
    ["new-issue", "New issue", "owner/name"],
    ["new-pull", "New pull request", "owner/name"],
@@ -252,6 +255,7 @@
test("signed out, the palette offers sign-in and the public entries", () => {
    ["pulls", "Pull requests in a repository", "owner/name"],
    ["milestones", "Milestones in a repository", "owner/name"],
    ["next-up", "Next up in a repository", "owner/name"],
    ["week", "The week in a repository", "owner/name"],
    ["repo-usage", "Usage of a repository", "owner/name"],
    ["new-issue", "New issue", "owner/name"],
    ["new-pull", "New pull request", "owner/name"],
@@ -0,0 +1,266 @@
/**
 * The week's doors (#8704): the page, MCP and the terminal share one
 * `takeProposal`, so a proposal is taken by a person who writes and by no one
 * else, once; the cut line is drawn once capacity is read; and pricing a list
 * or writing a retrospective spends no agent run.
 */
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 { openIssue, setIssueState } from "../src/actions/issues.ts";
import { addToCrew, createAgent } from "../src/actions/crew.ts";
import { createRepo } from "../src/actions/repos.ts";
import { WEEK_FORBIDDEN, WEEK_PERSON, takeProposal } from "../src/actions/week.ts";
import { createApp, type App as Forge } from "../src/app.ts";
import { getIssue } from "../src/core/issues.ts";
import { nextUp } from "../src/core/next_up.ts";
import type { Repo } from "../src/core/repos.ts";
import { createRun } from "../src/core/runs.ts";
import { noteLimit } from "../src/core/standing.ts";
import { addSubscription } from "../src/core/subscriptions.ts";
import { createToken } from "../src/core/tokens.ts";
import { recordUsage } from "../src/core/usage.ts";
import { createUser, getUserByName, type User } from "../src/core/users.ts";
import { latestRetro, takenOf, tickWeeks, failureClass } from "../src/flow/retro.ts";
import { weekView } from "../src/flow/week.ts";
import { serve, type Servers } from "../src/http/server.ts";
import { createForgeApp } from "../src/tui/forge.ts";
import { headlessTerminal } from "../src/tui/term/terminal.ts";
import { quietLogs } from "./helpers/globals.ts";
import { settleApp } from "./helpers/tui.ts";
quietLogs();
describe("the week's doors", () => {
  let dataDir: string;
  let forge: Forge;
  let servers: Servers;
  let base: string;
  let alice: User;
  let bob: User;
  let bot: User;
  let repo: Repo;
  let aliceCookie = "";
  let bobCookie = "";
  let aliceTok = "";
  let botTok = "";
  const n: Record<string, number> = {};
  const day = 86_400_000;
  const open = (title: string): number => {
    const o = openIssue(forge, alice, repo, { title });
    if (!o.ok) throw new Error(String(o.error));
    return o.value.number;
  };
  const runRows = (): number => forge.db.query<{ n: number }, []>("SELECT COUNT(*) AS n FROM run").get()!.n;
  const spend = (number: number, usd: number, state: string, at: string, summary = "") =>
    forge.db
      .query(
        `INSERT INTO run (id, repo_id, kind, issue_id, state, cost_usd, started_at, summary)
         VALUES (lower(hex(randomblob(8))), ?1, 'agent', ?2, ?3, ?4, ?5, ?6)`,
      )
      .run(repo.id, getIssue(forge.db, repo.id, number)!.id, state, usd, at, summary);
  const signIn = async (username: string): Promise<string> => {
    const res = await fetch(`${base}/signin`, {
      method: "POST",
      body: new URLSearchParams({ username, password: "a-good-passphrase" }),
      redirect: "manual",
    });
    return (res.headers.get("set-cookie") ?? "").split(";")[0]!;
  };
  const mcp = async (token: string, args: unknown) => {
    const res = await fetch(`${servers.url}/mcp`, {
      method: "POST",
      headers: { "content-type": "application/json", accept: "application/json, text/event-stream", authorization: `Bearer ${token}` },
      body: JSON.stringify({ jsonrpc: "2.0", id: 1, method: "tools/call", params: { name: "week", arguments: args } }),
    });
    const body = (await res.json()) as any;
    const text: string = body.result.content[0].text;
    return body.result.isError === true ? { error: text } : { value: JSON.parse(text) };
  };
  const post = (headers: Record<string, string>, idx = 0) =>
    fetch(`${base}/alice/plan/week`, {
      method: "POST",
      headers: { accept: "application/json", ...headers },
      body: new URLSearchParams({ week_end: latestRetro(forge.db, repo.id)!.weekEnd, idx: String(idx) }),
      redirect: "manual",
    });
  beforeAll(async () => {
    dataDir = await mkdtemp(join(tmpdir(), "forge-week-doors-"));
    forge = createApp({ dataDir, port: 0 });
    servers = await serve(forge);
    base = `http://127.0.0.1:${servers.port}`;
    for (const [username, first] of [["alice", true], ["bob", false]] as const) {
      const made = await createUser(forge.db, {
        origin: "seed", trusted: true, username, email: `${username}@forge.local`,
        password: "a-good-passphrase", adminIfFirst: first,
      });
      if (!made.ok) throw new Error(made.error);
    }
    alice = getUserByName(forge.db, "alice")!;
    bob = getUserByName(forge.db, "bob")!;
    const made = await createRepo(forge, alice, { name: "plan", visibility: "public" });
    if (!made.ok) throw new Error(String(made.error));
    repo = made.value;
    const agent = await createAgent(forge, alice, { username: "bot" });
    if (!agent.ok) throw new Error(String(agent.error));
    bot = agent.value.user;
    if (!addToCrew(forge, alice, repo, "bot").ok) throw new Error("crew");
    botTok = createToken(forge.db, bot.id, "rw", "rw").token;
    aliceTok = createToken(forge.db, alice.id, "rw", "rw").token;
    n.gate = open("Later gate: not now");
    const past = new Date(Date.now() - 3 * day).toISOString();
    for (const usd of [1, 2, 3, 4, 5]) {
      const done = open(`Past ${usd}`);
      spend(done, usd, "ok", past);
      const r = setIssueState(forge, alice, repo, getIssue(forge.db, repo.id, done)!, "closed");
      if (!r.ok) throw new Error(String(r.error));
    }
    n.stuck = open("Stuck one");
    for (let i = 0; i < 6; i++) open(`Work ${i}`);
    for (let i = 0; i < 3; i++) spend(n.stuck, 3, "failed", new Date(Date.now() - 2 * day).toISOString(), "secret token sk-123 leaked in the check output");
    n.costly = open("Costly one");
    spend(n.costly, 4, "ok", new Date(Date.now() - 2 * day).toISOString());
    // Capacity: the provider refused at $20 a week ago; the next window is open and unspent.
    const sub = addSubscription(forge.db, dataDir, { name: "acct", token: "sk-ant-oat01-doors-test-1" });
    if (!sub.ok) throw new Error(sub.error);
    recordUsage(forge.db, {
      runId: createRun(forge.db, { repoId: repo.id, kind: "agent" }).id, repoId: repo.id, issueId: null, agentId: null,
      subscriptionId: sub.value.id, tokensIn: 1, tokensOut: 1, costUsd: 20, wallMs: 1000, outcome: "ok",
      at: new Date(Date.now() - 8.5 * day).toISOString(),
    });
    noteLimit(forge.db, sub.value.id, {
      window: "week", resetsAt: new Date(Date.now() - 2 * day).toISOString(),
      observedAt: new Date(Date.now() - 8 * day).toISOString(), said: "weekly limit",
    });
    aliceCookie = await signIn("alice");
    bobCookie = await signIn("bob");
  }, 30_000);
  afterAll(async () => {
    await servers.stop();
    forge.close();
    await rm(dataDir, { recursive: true, force: true });
  });
  test("once capacity is read, Next up draws the cut line and the rows below read as next week", async () => {
    const view = weekView(forge.db, repo.id, nextUp(forge.db, repo).rows, new Date());
    expect(view.cut.unsure).toBeNull();
    expect(view.cut.fits.length).toBeGreaterThan(0);
    expect(view.cut.fits.length).toBeLessThan(nextUp(forge.db, repo).rows.length);
    const page = await (await fetch(`${base}/alice/plan/next`, { headers: { cookie: aliceCookie } })).text();
    expect(page.match(/role="separator"/g)).toHaveLength(1);
    expect(page).toContain(`This week ends here (${view.cut.fits.length} fit)`);
    expect(page).toContain("should ship by");
    // The terminal draws the same line and the same ranges.
    const terminal = headlessTerminal(140, 40);
    const { app } = createForgeApp(forge, { sshUsername: "t", remoteAddress: "127.0.0.1", user: alice }, { terminal, exitHooks: false });
    app.start();
    const key = async (...keys: string[]) => {
      for (const k of keys) app.dispatch({ type: "key", key: k, ctrl: k === "ctrl+k" ? false : false, alt: false, shift: false });
      await settleApp(app);
    };
    app.dispatch({ type: "key", key: "k", ctrl: true, alt: false, shift: false });
    await settleApp(app);
    for (const ch of "Next up in a repository") app.dispatch({ type: "key", key: ch, ctrl: false, alt: false, shift: false });
    await key("enter");
    for (const ch of "alice/plan") app.dispatch({ type: "key", key: ch, ctrl: false, alt: false, shift: false });
    await key("enter");
    expect(terminal && app.screen.toText()).toContain("this week ends here");
    expect(app.screen.toText()).toContain("$");
    app.stop();
  });
  test("pricing, projecting and writing a retrospective spend no agent run", async () => {
    const before = runRows();
    weekView(forge.db, repo.id, nextUp(forge.db, repo).rows, new Date());
    await fetch(`${base}/alice/plan/next`, { headers: { cookie: aliceCookie } });
    // The window that ended two days ago had its projection stored; the tick closes it.
    const open = nextUp(forge.db, repo).rows;
    forge.db
      .query("INSERT INTO week_projection (repo_id, week_end, body, at) VALUES (?1, ?2, ?3, ?4)")
      .run(repo.id, new Date(Date.now() - day).toISOString(), JSON.stringify({ sentence: "s", fits: [], shipLow: 0, shipHigh: 1, confidence: "low", ranges: {} }), new Date(Date.now() - 8 * day).toISOString());
    expect(open.length).toBeGreaterThan(0);
    expect(tickWeeks(forge.db, [repo], new Date())).toHaveLength(1);
    expect(runRows()).toBe(before);
  });
  test("a stuck reason is a failure class, never the run's own words", () => {
    const retro = latestRetro(forge.db, repo.id)!;
    const stuck = retro.stuck.find((s) => s.number === n.stuck)!;
    expect(stuck.why).toContain("3 failed runs");
    expect(JSON.stringify(retro)).not.toContain("sk-123");
    expect(failureClass("the check failed")).toBe("its check failed");
    expect(failureClass("whatever else")).toBe("ended without finishing");
  });
  test("a sealed issue's cost does not shape visible ranges", () => {
    const before = weekView(forge.db, repo.id, nextUp(forge.db, repo).rows, new Date()).priced;
    const s = openIssue(forge, alice, repo, { title: "Sealed" });
    if (!s.ok) throw new Error(String(s.error));
    spend(s.value.number, 900, "ok", new Date().toISOString());
    forge.db.query("UPDATE issue SET state = 'closed', close_reason = 'done', closed_at = ?2 WHERE id = ?1").run(s.value.id, new Date().toISOString());
    forge.db.query("UPDATE issue SET sealed = 1 WHERE id = ?1").run(s.value.id);
    expect(weekView(forge.db, repo.id, nextUp(forge.db, repo).rows, new Date()).priced).toEqual(before);
  });
  test("takeProposal refuses a reader and an agent, with their own words, and takes nothing", () => {
    const retro = latestRetro(forge.db, repo.id)!;
    expect(retro.proposals.length).toBeGreaterThan(0);
    const reader = takeProposal(forge, bob, repo, retro.weekEnd, 0);
    expect(reader.ok).toBe(false);
    if (!reader.ok) expect(reader.error.message).toBe(WEEK_FORBIDDEN);
    const agent = takeProposal(forge, bot, repo, retro.weekEnd, 0);
    expect(agent.ok).toBe(false);
    if (!agent.ok) expect(agent.error.message).toBe(WEEK_PERSON);
    expect(takenOf(forge.db, repo.id, retro.weekEnd).size).toBe(0);
  });
  test("POST /week: no cookie, another origin, a reader and an agent are refused", async () => {
    const same = { origin: base };
    expect((await post({ ...same })).status).not.toBe(200);
    expect((await post({ cookie: aliceCookie, origin: "https://evil.example" })).status).toBe(403);
    expect((await post({ cookie: bobCookie, ...same })).status).toBe(422);
    expect((await post({ authorization: `Bearer ${botTok}`, ...same })).status).toBe(422);
    expect(takenOf(forge.db, repo.id, latestRetro(forge.db, repo.id)!.weekEnd).size).toBe(0);
  });
  test("MCP week: an agent is refused; a person takes a proposal once", async () => {
    const refused = await mcp(botTok, { app: "alice/plan", take: 0 });
    expect(refused.error).toContain("forbidden");
    const read = await mcp(botTok, { app: "alice/plan" });
    expect(read.value.proposals[0].taken).toBe(false);
    const took = await mcp(aliceTok, { app: "alice/plan", take: 0 });
    expect(took.value.proposals[0].taken).toBe(true);
    expect((await mcp(aliceTok, { app: "alice/plan", take: 0 })).error).toContain("already taken");
    expect(nextUp(forge.db, repo).rows.map((r) => r.issue.number)).not.toContain(latestRetro(forge.db, repo.id)!.proposals[0]!.number);
  });
  test("the terminal shows the retrospective and a reader's key takes nothing", async () => {
    const heard = latestRetro(forge.db, repo.id)!;
    expect(heard.proposals.length).toBeGreaterThan(1);
    const terminal = headlessTerminal(140, 40);
    const { app } = createForgeApp(forge, { sshUsername: "t", remoteAddress: "127.0.0.1", user: bob }, { terminal, exitHooks: false });
    app.start();
    const send = (key: string, ctrl = false) => app.dispatch({ type: "key", key, ctrl, alt: false, shift: false });
    await settleApp(app);
    send("k", true);
    await settleApp(app);
    for (const ch of "The week in a repository") send(ch);
    send("enter");
    await settleApp(app);
    for (const ch of "alice/plan") send(ch);
    send("enter");
    await settleApp(app);
    expect(app.screen.toText()).toContain("shipped");
    send("j");
    send("a");
    await settleApp(app);
    expect(takenOf(forge.db, repo.id, heard.weekEnd).has(1)).toBe(false);
    app.stop();
  });
});
@@ -0,0 +1,290 @@
/**
 * The week is the sprint (#8704): an estimate is a range from past issues of
 * its size and kind and says when it has too little history; the cut line
 * falls where the week's capacity ends and moves when the list is reranked;
 * the same state gives the same line; at the reset the forge writes one
 * frozen retrospective with at most three proposals, and nothing changes
 * until a person takes one.
 */
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 { createApp, type App } from "../src/app.ts";
import { openIssue, setIssueState } from "../src/actions/issues.ts";
import { createRepo } from "../src/actions/repos.ts";
import { takeProposal } from "../src/actions/week.ts";
import { getIssue } from "../src/core/issues.ts";
import { nextUp } from "../src/core/next_up.ts";
import type { Repo } from "../src/core/repos.ts";
import { createUser, type User } from "../src/core/users.ts";
import { estimate, issueHistory, sizeOf, type Sample } from "../src/flow/estimate.ts";
import { noteLimit } from "../src/core/standing.ts";
import { addSubscription } from "../src/core/subscriptions.ts";
import { createRun } from "../src/core/runs.ts";
import { recordUsage } from "../src/core/usage.ts";
import { weekCapacity } from "../src/flow/week.ts";
import { latestRetro, takenOf, tickWeeks, windowShipped, windowSpend, writeRetro } from "../src/flow/retro.ts";
import { cutLine, priceRows, projection } from "../src/flow/week.ts";
import { serve, type Servers } from "../src/http/server.ts";
const sample = (usd: number, size: Sample["size"] = "small", kind = ""): Sample => ({ size, kind, usd });
describe("estimates and the cut line, as data", () => {
  test("with too little history an estimate says so", () => {
    const e = estimate([sample(1), sample(2)], "small", "");
    expect(e.known).toBe(false);
    expect(e.basis).toContain("too little history");
  });
  test("a range comes from past issues of the same size and kind, else the same size", () => {
    const history = [1, 2, 3, 4, 5].map((n) => sample(n)).concat([sample(40, "small", "bug")]);
    expect(estimate(history, "small", "")).toMatchObject({ known: true, samples: 5 });
    // One "bug" sample is too few to speak for the kind: the size answers.
    expect(estimate(history, "small", "bug")).toMatchObject({ known: true, samples: 6 });
    const bugs = estimate([...history, sample(8, "small", "bug"), sample(9, "small", "bug")], "small", "bug");
    expect(bugs).toMatchObject({ known: true, samples: 3 });
    expect(estimate(history, "large", "").known).toBe(false);
  });
  test("the same history gives the same estimate", () => {
    const history = [5, 1, 4, 2, 3].map((n) => sample(n));
    expect(estimate(history, "small", "")).toEqual(estimate([...history].reverse(), "small", ""));
  });
  const priced = (mids: (number | null)[]) =>
    mids.map((m, i) => ({
      number: i + 1,
      estimate:
        m === null
          ? ({ known: false, samples: 0, basis: "x" } as const)
          : ({ known: true, low: m / 2, mid: m, high: m * 2, samples: 9, basis: "x" } as const),
    }));
  test("the line falls after the last issue that fits, strictly from the top", () => {
    const cut = cutLine(priced([2, 3, 1]), { usd: 5, resetsAt: null });
    expect(cut.fits).toEqual([1, 2]);
    // Issue 3 would fit the money left over, but the crew builds from the top and stops.
    expect(cutLine(priced([4, 3, 1]), { usd: 5, resetsAt: null }).fits).toEqual([1]);
  });
  test("reranking moves the line, and the same state gives the same line", () => {
    const cap = { usd: 5, resetsAt: null };
    expect(cutLine(priced([2, 3, 1]), cap)).toEqual(cutLine(priced([2, 3, 1]), cap));
    expect(cutLine(priced([2, 3, 1]), cap).fits).toEqual([1, 2]);
    const swapped = [priced([2, 3, 1])[2]!, priced([2, 3, 1])[0]!, priced([2, 3, 1])[1]!];
    expect(cutLine(swapped, cap).fits).toEqual([3, 1]);
  });
  test("no capacity or no history means no line, and the sentence says why", () => {
    expect(cutLine(priced([1]), null).unsure).toContain("capacity");
    expect(cutLine(priced([null]), { usd: 9, resetsAt: null }).unsure).toContain("history");
    expect(projection(cutLine(priced([null]), null), 1, null)).toStartWith("No projection yet");
  });
  test("the projection is one sentence with a range and a confidence", () => {
    const cap = { usd: 5, resetsAt: "2026-11-09T00:00:00.000Z" };
    const words = projection(cutLine(priced([2, 3, 1]), cap), 3, cap);
    expect(words).toContain("of the 3 issues");
    expect(words).toContain("2026-11-09");
    expect(words).toContain("high confidence");
  });
});
describe("the week, in a forge", () => {
  let dataDir: string;
  let app: App;
  let servers: Servers;
  let alice: User;
  let repo: Repo;
  let cookie: string;
  const n: Record<string, number> = {};
  const WEEK_END = "2026-11-09T00:00:00.000Z";
  const open = (title: string, body = ""): number => {
    const o = openIssue(app, alice, repo, { title, body });
    if (!o.ok) throw new Error(String(o.error));
    return o.value.number;
  };
  const close = (number: number) => {
    const r = setIssueState(app, alice, repo, getIssue(app.db, repo.id, number)!, "closed");
    if (!r.ok) throw new Error(String(r.error));
  };
  const spend = (number: number, usd: number, state = "ok", startedAt = "2026-11-04T10:00:00.000Z", summary = "") => {
    app.db
      .query(
        `INSERT INTO run (id, repo_id, kind, issue_id, state, cost_usd, started_at, summary)
         VALUES (lower(hex(randomblob(8))), ?1, 'agent', ?2, ?3, ?4, ?5, ?6)`,
      )
      .run(repo.id, getIssue(app.db, repo.id, number)!.id, state, usd, startedAt, summary);
  };
  beforeAll(async () => {
    dataDir = await mkdtemp(join(tmpdir(), "forge-week-"));
    app = createApp({ dataDir, port: 0 });
    servers = await serve(app);
    const made = await createUser(app.db, {
      origin: "seed", trusted: true, username: "alice", email: "[email protected]",
      password: "a-good-passphrase", adminIfFirst: true,
    });
    if (!made.ok) throw new Error(made.error);
    alice = made.value;
    const r = await createRepo(app, alice, { name: "plan", visibility: "public" });
    if (!r.ok) throw new Error(String(r.error));
    repo = r.value;
    n.gate = open("Later gate: not now");
    // Past work: five small issues done at $1..$5 are the history.
    for (const usd of [1, 2, 3, 4, 5]) {
      const done = open(`Past ${usd}`);
      spend(done, usd);
      close(done);
    }
    n.a = open("Alpha");
    n.b = open("Beta");
    n.stuck = open("Stuck one");
    const res = await fetch(`${servers.url}/signin`, {
      method: "POST",
      body: new URLSearchParams({ username: "alice", password: "a-good-passphrase" }),
      redirect: "manual",
    });
    cookie = (res.headers.get("set-cookie") ?? "").split(";")[0]!;
  });
  afterAll(async () => {
    await servers.stop();
    await rm(dataDir, { recursive: true, force: true });
  });
  test("history is the closed issues' real spend", () => {
    const h = issueHistory(app.db, repo.id);
    expect(h.map((s) => s.usd).sort()).toEqual([1, 2, 3, 4, 5]);
    expect(sizeOf({ title: "x", body: "" })).toBe("small");
  });
  test("each row of Next up has a range, and the same rows give the same prices", () => {
    const rows = nextUp(app.db, repo).rows;
    const one = priceRows(app.db, repo.id, rows);
    expect(one).toEqual(priceRows(app.db, repo.id, rows));
    expect(one.every((p) => p.estimate.known)).toBe(true);
  });
  test("the page shows ranges and the projection sentence; no capacity read means no line", async () => {
    const res = await fetch(`${servers.url}/alice/plan/next`, { headers: { cookie } });
    expect(res.status).toBe(200);
    const text = await res.text();
    expect(text).toContain("$2.00–$4.00");
    expect(text).toContain("No projection yet: the weekly capacity has not been read yet.");
    expect(text).not.toContain('role="separator"');
  });
  test("capacity is what the weekly window leaves, read from the ledger", () => {
    expect(weekCapacity(app.db, new Date("2026-11-06T00:00:00Z"))).toBeNull();
    const added = addSubscription(app.db, dataDir, { name: "week account", token: "sk-ant-oat01-week-test-1" });
    if (!added.ok) throw new Error(added.error);
    const sub = added.value.id;
    const ran = (at: string, usd: number) =>
      recordUsage(app.db, {
        runId: createRun(app.db, { repoId: repo.id, kind: "agent" }).id, repoId: repo.id, issueId: null, agentId: null,
        subscriptionId: sub, tokensIn: 1, tokensOut: 1, costUsd: usd, wallMs: 1000, outcome: "ok", at,
      });
    ran("2026-10-30T10:00:00.000Z", 20);
    noteLimit(app.db, sub, {
      window: "week", resetsAt: "2026-11-02T00:00:00.000Z", observedAt: "2026-10-31T00:00:00.000Z", said: "weekly limit",
    });
    ran("2026-11-05T10:00:00.000Z", 5);
    // The provider refused at $20 of spend and reset on the 2nd: that is the cap, the next window ends a week on, and $5 of it is used.
    const cap = weekCapacity(app.db, new Date("2026-11-06T00:00:00Z"))!;
    expect(cap.resetsAt).toBe(WEEK_END);
    expect(cap.usd).toBeGreaterThan(0);
    expect(cap.usd).toBeLessThanOrEqual(15);
  });
  test("with capacity, the page draws the cut line between what fits and next week", () => {
    const rows = nextUp(app.db, repo).rows;
    const priced = priceRows(app.db, repo.id, rows);
    const cut = cutLine(priced, { usd: 3, resetsAt: WEEK_END });
    expect(cut.unsure).toBeNull();
    expect(cut.fits.length).toBeGreaterThan(0);
    expect(cut.fits.length).toBeLessThan(rows.length);
    expect(projection(cut, rows.length, { usd: 3, resetsAt: WEEK_END })).toContain("of the");
  });
  test("the retrospective is written once, frozen, with proposals that change nothing until taken", () => {
    app.db
      .query("INSERT INTO week_projection (repo_id, week_end, body, at) VALUES (?1, ?2, ?3, ?4)")
      .run(
        repo.id,
        WEEK_END,
        JSON.stringify({ sentence: "s", fits: [n.a], shipLow: 1, shipHigh: 2, confidence: "medium", ranges: { [String(n.a!)]: { low: 1, high: 3 } } }),
        "2026-11-02T00:00:00.000Z",
      );
    // Alpha shipped at $2 (inside its range); Stuck one spent $9 over three failed runs and is still open.
    spend(n.a!, 2);
    close(n.a!);
    app.db.query("UPDATE issue SET closed_at = '2026-11-05T00:00:00.000Z' WHERE repo_id = ?1 AND number = ?2").run(repo.id, n.a!);
    for (let i = 0; i < 3; i++) spend(n.stuck!, 3, "failed", "2026-11-06T10:00:00.000Z", "the check failed");
    const now = new Date("2026-11-09T01:00:00.000Z");
    expect(tickWeeks(app.db, [repo], now)).toHaveLength(1);
    expect(tickWeeks(app.db, [repo], now)).toHaveLength(0);
    expect(writeRetro(app.db, repo, WEEK_END, now)).toBe(false);
    const retro = latestRetro(app.db, repo.id)!;
    expect(retro.shipped.map((s) => s.number)).toContain(n.a!);
    expect(retro.accuracy).toEqual({ compared: 1, inside: 1 });
    expect(retro.stuck.map((s) => s.number)).toEqual([n.stuck!]);
    expect(retro.stuck[0]!.why).toContain("its check failed");
    expect(retro.proposals.length).toBeLessThanOrEqual(3);
    expect(retro.proposals[0]).toMatchObject({ kind: "not_now", number: n.stuck! });
    // Writing it changed nothing: the issue is still on the list.
    expect(nextUp(app.db, repo).rows.map((r) => r.issue.number)).toContain(n.stuck!);
  });
  test("the screen is reachable and a tap takes a proposal once", async () => {
    const page = await (await fetch(`${servers.url}/alice/plan/week`, { headers: { cookie } })).text();
    expect(page).toContain("What shipped");
    expect(page).toContain("Take it");
    const retro = latestRetro(app.db, repo.id)!;
    const taken = takeProposal(app, alice, repo, retro.weekEnd, 0);
    expect(taken.ok).toBe(true);
    expect(takenOf(app.db, repo.id, retro.weekEnd).has(0)).toBe(true);
    expect(takeProposal(app, alice, repo, retro.weekEnd, 0).ok).toBe(false);
    expect(nextUp(app.db, repo).rows.map((r) => r.issue.number)).not.toContain(n.stuck!);
  });
  test("a proposal is refused for a reader and for one that does not exist", () => {
    const retro = latestRetro(app.db, repo.id)!;
    expect(takeProposal(app, alice, repo, retro.weekEnd, 7).ok).toBe(false);
    expect(takeProposal(app, alice, repo, "2020-01-01T00:00:00.000Z", 0).ok).toBe(false);
  });
});
describe("the reads walk an index", () => {
  test("history, labels and the window reads show no scan and no sort in their plans", async () => {
    const dir = await mkdtemp(join(tmpdir(), "forge-week-plan-"));
    const app = createApp({ dataDir: dir, port: 0 });
    try {
      const db = app.db;
      const original = db.query.bind(db);
      const sqls: string[] = [];
      (db as unknown as { query: unknown }).query = (sql: string) => (sqls.push(sql), original(sql));
      issueHistory(db, "x");
      windowSpend(db, "x", "a", "b");
      windowShipped(db, "x", "a", "b");
      (await import("../src/flow/estimate.ts")).labelsOf(db, ["x"]);
      (db as unknown as { query: unknown }).query = original;
      const lines = sqls
        .filter((q) => /^\s*SELECT/i.test(q))
        .flatMap((q) => {
          const n = Math.max(0, ...[...q.matchAll(/\?(\d+)/g)].map((m) => Number(m[1])));
          return original(`EXPLAIN QUERY PLAN ${q}`).all(...Array.from({ length: n }, () => "x")).map((r) => (r as { detail: string }).detail);
        });
      expect(lines.length).toBeGreaterThan(3);
      for (const line of lines) {
        expect(line).not.toMatch(/^SCAN (?!.*USING (COVERING )?INDEX)/);
        expect(line).not.toContain("TEMP B-TREE");
      }
    } finally {
      app.close();
      await rm(dir, { recursive: true, force: true });
    }
  });
});
		@@ -0,0 +1,3 @@
	1	# The week
	2
	3	On Next up (`src/web/pages/next.ts`) `.cut-line` is the separator row drawn between what this week's capacity can ship and what reads as next week: a dashed rule in `--series-1` with muted words under it. `.estimate` is a row's cost range, in `--fg` with tabular figures so ranges line up down the list. `/:owner/:name/week` uses only existing components (`card`, `row`, `btn`).
		@@ -11,3 +11,16 @@
11	11	- A rank is cleared when the issue closes. Dependencies order within the list and are shown, never edited here.
12	12
13	13	Terminal: the palette's "Next up in a repository" opens the same list; `t`, `u`, `d` and `n` are Top, Up, Down and Not now on the row under the cursor, through the same action as the page and MCP. A reader sees the order and the keys do nothing; a move made anywhere reorders an open screen live. At most 200 issues are ranked; a move past that is refused and says so.
	14
	15	## The week is the sprint (#8704)
	16
	17	The subscription's weekly reset is the sprint boundary; what the crew may still spend before it is the capacity (`flow/week.ts`, from `core/standing.ts`). No ceremony and no locked scope: rerank any time and the line moves on the next paint.
	18
	19	- Estimates: each row shows a cost range (the 25th to 75th percentile of what past closed issues of the same size and kind cost, every agent run on them summed, `flow/estimate.ts`). With fewer than three comparable issues it falls back to size alone, then says "too little history". Measured, never asked of an agent: no run is spent.
	20	- Cut line: walking from the top, the running median estimate is held against the capacity; the line falls before the first issue that does not fit and everything under it reads as next week. An issue with no estimate counts as the median of the others; with none estimated, or no capacity read, there is no line and the sentence says why. Same list and history, same line.
	21	- Projection: one sentence above the list: how many should ship by the reset, as a range from the high and low ends of the estimates, and a confidence (high at eight or more samples on every row).
	22	- Retrospective: once an hour the forge keeps the projection of the open window (`week_projection`) and, for a window that has ended, writes `week_retro` once (`flow/retro.ts`): what shipped against the projection, how many shipped issues cost inside their range, what open work cost most, what is stuck (two failed runs or more, and the class of the last failure, never the run's own output), and at most three proposals. `/:owner/:name/week` and the MCP `week` tool show it. A proposal is one tap (`POST /:owner/:name/week`, or `week { app, take }`) by a writer who is a person; it puts the issue behind the Later gate, the same move as `Not now`, and is taken at most once. Nothing changes without that tap. Only a person who writes can take one: `takeProposal` refuses an agent and a reader for every door.
	23	- Not done here: the line falls between issues, not whole scopes, because bets and scopes (#8713) are not in the forge yet; when they land the line moves to their edges. The health mark per group is left for the same reason.
	24	- Live: a drag posts the move and the page reloads itself from the server, which redraws the line; there is no manual reload, but it is a reload, not a client-side recompute.
	25	- Terminal: Next up shows each row's range and a muted "this week ends here" line under the last issue that fits, with the projection in the header. "The week in a repository" (palette) shows the retrospective; `j`/`k` choose a proposal and `enter` or `a` takes it, through the same `takeProposal`. A reader or an agent sees it and the key does nothing; a new retrospective (`week.retro`) or a proposal taken anywhere updates the open screen. MCP `next_up` rows carry `estimate` and `thisWeek`, with a `projection` sentence.
	26	- Sealed issues are left out of history and of the retrospective, so their cost never shapes a visible range.
		@@ -0,0 +1,41 @@
	1	/**
	2	* Taking a proposal from the week's retrospective (#8704): one tap by a person
	3	* who writes here, and it is the same move as the Next up page's `Not now`
	4	* (`actions/next.ts`). Each proposal is taken at most once; nothing else in
	5	* the retrospective ever changes anything.
	6	*/
	7	import type { App } from "../app.ts";
	8	import { getIssue } from "../core/issues.ts";
	9	import { canWrite, type Repo } from "../core/repos.ts";
	10	import type { User } from "../core/users.ts";
	11	import { err, ok, type Result } from "../kernel/result.ts";
	12	import { latestRetro, takenOf } from "../flow/retro.ts";
	13	import { rankIssue, type NextError } from "./next.ts";
	14
	15	export const WEEK_PERSON = "Only a person takes a proposal; an agent proposes and a person lands.";
	16	export const WEEK_FORBIDDEN = "Only someone with write access can take a proposal.";
	17
	18	export function takeProposal(
	19	app: App,
	20	actor: User,
	21	repo: Repo,
	22	weekEnd: string,
	23	idx: number,
	24	): Result<string, NextError> {
	25	// A person's tap, whatever the door: an agent proposes and never takes, a reader cannot.
	26	if (actor.kind === "agent") return err({ kind: "forbidden", message: WEEK_PERSON });
	27	if (!canWrite(app.db, repo, actor)) return err({ kind: "forbidden", message: WEEK_FORBIDDEN });
	28	const retro = latestRetro(app.db, repo.id);
	29	const proposal = retro?.weekEnd === weekEnd ? retro.proposals[idx] : undefined;
	30	if (proposal === undefined) return err({ kind: "not_found", message: "No such proposal." });
	31	if (takenOf(app.db, repo.id, weekEnd).has(idx))
	32	return err({ kind: "invalid", message: "That proposal was already taken." });
	33	const issue = getIssue(app.db, repo.id, proposal.number);
	34	if (issue === undefined) return err({ kind: "not_found", message: "No such issue." });
	35	const moved = rankIssue(app, actor, repo, proposal.number, { to: "not_now" });
	36	if (!moved.ok) return moved;
	37	app.db
	38	.query("INSERT OR IGNORE INTO week_retro_taken (repo_id, week_end, idx, actor_id, at) VALUES (?1, ?2, ?3, ?4, ?5)")
	39	.run(repo.id, weekEnd, idx, actor.id, new Date().toISOString());
	40	return ok(`#${proposal.number} is not now.`);
	41	}
		@@ -38,6 +38,7 @@ const READER_KINDS: ReadonlySet<string> = new Set([
38	38	"issue.labeled",
39	39	"issue.first",
40	40	"issue.ranked",
	41	"week.retro",
41	42	"issue.closed",
42	43	"issue.gate_reviewed",
43	44	"issue.commented",
		@@ -0,0 +1,1 @@
	1	8d5ade86821784d4cf4fc987b5e843b7df9f3855e8640fb54c34d73be83cc70f
		@@ -0,0 +1,28 @@
	1	// The week as the sprint (#8704): the projection the forge made when a weekly
	2	// window opened, and the retrospective it wrote when that window closed,
	3	// frozen once. A proposal in a retrospective is accepted at most once, by a
	4	// person: `week_retro_taken` holds who and when.
	5	export default `
	6	CREATE TABLE IF NOT EXISTS week_projection (
	7	repo_id TEXT NOT NULL REFERENCES repo(id) ON DELETE CASCADE,
	8	week_end TEXT NOT NULL,
	9	body TEXT NOT NULL,
	10	at TEXT NOT NULL,
	11	PRIMARY KEY (repo_id, week_end)
	12	);
	13	CREATE TABLE IF NOT EXISTS week_retro (
	14	repo_id TEXT NOT NULL REFERENCES repo(id) ON DELETE CASCADE,
	15	week_end TEXT NOT NULL,
	16	body TEXT NOT NULL,
	17	at TEXT NOT NULL,
	18	PRIMARY KEY (repo_id, week_end)
	19	);
	20	CREATE TABLE IF NOT EXISTS week_retro_taken (
	21	repo_id TEXT NOT NULL,
	22	week_end TEXT NOT NULL,
	23	idx INTEGER NOT NULL,
	24	actor_id TEXT NOT NULL,
	25	at TEXT NOT NULL,
	26	PRIMARY KEY (repo_id, week_end, idx)
	27	);
	28	`;
		@@ -0,0 +1,92 @@
	1	/**
	2	* What an issue will cost, as a range, from what past issues of its size and
	3	* kind cost (#8704). Measured, never guessed, and no agent run is spent: the
	4	* history is the ledger of finished work. Same history, same range. Plain data
	5	* in and out; `issueHistory` is the one read.
	6	*/
	7
	8	import type { Database } from "bun:sqlite";
	9	import type { Issue } from "../core/issues.ts";
	10
	11	/** Samples a group needs before it may speak; fewer and the estimate says so. */
	12	export const MIN_SAMPLES = 3;
	13	/** Samples at which a group is trusted. */
	14	export const SURE_SAMPLES = 8;
	15	/** The most past issues one estimate reads. */
	16	const HISTORY_MAX = 400;
	17
	18	export type Size = "small" \| "medium" \| "large";
	19
	20	export interface Sample {
	21	readonly size: Size;
	22	readonly kind: string;
	23	readonly usd: number;
	24	}
	25
	26	export type Estimate =
	27	\| { readonly known: true; readonly low: number; readonly mid: number; readonly high: number; readonly samples: number; readonly basis: string }
	28	\| { readonly known: false; readonly samples: number; readonly basis: string };
	29
	30	/** How big an issue reads, from the words written on it. */
	31	export function sizeOf(issue: Pick<Issue, "title" \| "body">): Size {
	32	const n = issue.title.length + issue.body.length;
	33	return n < 400 ? "small" : n < 1500 ? "medium" : "large";
	34	}
	35
	36	const quantile = (sorted: readonly number[], q: number): number => sorted[Math.round((sorted.length - 1) * q)]!;
	37	const cents = (n: number): number => Math.round(n * 100) / 100;
	38
	39	function rangeOf(group: readonly Sample[], basis: string): Estimate {
	40	const usd = group.map((s) => s.usd).sort((a, b) => a - b);
	41	return {
	42	known: true,
	43	low: cents(quantile(usd, 0.25)),
	44	mid: cents(quantile(usd, 0.5)),
	45	high: cents(quantile(usd, 0.75)),
	46	samples: usd.length,
	47	basis,
	48	};
	49	}
	50
	51	/** Past issues of the same size and kind; if too few, of the same size; if still too few, no estimate. */
	52	export function estimate(history: readonly Sample[], size: Size, kind: string): Estimate {
	53	const same = history.filter((s) => s.size === size && s.kind === kind);
	54	if (same.length >= MIN_SAMPLES) return rangeOf(same, `${same.length} past ${size} ${kind === "" ? "issues" : `“${kind}” issues`}`);
	55	const sized = history.filter((s) => s.size === size);
	56	if (sized.length >= MIN_SAMPLES) return rangeOf(sized, `${sized.length} past ${size} issues`);
	57	return { known: false, samples: sized.length, basis: `too little history: ${sized.length} past ${size} issues` };
	58	}
	59
	60	/** The kind of an issue: its first label by name, lowercase, or "". */
	61	export const kindOf = (labels: readonly string[]): string => [...labels].map((l) => l.toLowerCase()).sort()[0] ?? "";
	62
	63	/** Labels of the given issues, by issue id (the issue_label key leads with the issue). */
	64	export function labelsOf(db: Database, issueIds: readonly string[]): Map<string, string[]> {
	65	const out = new Map<string, string[]>();
	66	for (let at = 0; at < issueIds.length; at += 200) {
	67	const part = issueIds.slice(at, at + 200);
	68	const rows = db
	69	.query<{ issue_id: string; name: string }, string[]>(
	70	`SELECT il.issue_id, l.name FROM issue_label il JOIN label l ON l.id = il.label_id
	71	WHERE il.issue_id IN (${part.map((_, i) => `?${i + 1}`).join(",")})`,
	72	)
	73	.all(...part);
	74	for (const r of rows) out.set(r.issue_id, [...(out.get(r.issue_id) ?? []), r.name]);
	75	}
	76	return out;
	77	}
	78
	79	/** What closed issues cost: every agent run on each, summed; the latest {@link HISTORY_MAX} by number. */
	80	export function issueHistory(db: Database, repoId: string): Sample[] {
	81	const rows = db
	82	.query<{ id: string; title: string; body: string; usd: number }, [string, number]>(
	83	`SELECT i.id, i.title, i.body,
	84	(SELECT SUM(r.cost_usd) FROM run r WHERE r.issue_id = i.id AND r.kind = 'agent') AS usd
	85	FROM issue i
	86	WHERE i.repo_id = ?1 AND i.kind = 'issue' AND i.state = 'closed' AND i.sealed = 0 AND i.close_reason = 'done' AND usd > 0
	87	ORDER BY i.number DESC LIMIT ?2`,
	88	)
	89	.all(repoId, HISTORY_MAX);
	90	const labels = labelsOf(db, rows.map((r) => r.id));
	91	return rows.map((r) => ({ size: sizeOf(r), kind: kindOf(labels.get(r.id) ?? []), usd: r.usd }));
	92	}
		@@ -0,0 +1,263 @@
	1	/**
	2	* The week's retrospective (#8704): when a weekly window closes the forge
	3	* writes one frozen screen per repository, unasked — what shipped against the
	4	* projection it made when the window opened, how close the estimates ran,
	5	* what cost most for least, what got stuck and why — and ends it in at most
	6	* three proposals. A proposal changes nothing until a person takes it
	7	* (`actions/week.ts`). Plain code over the ledger, no model, no agent run.
	8	*/
	9
	10	import type { Database } from "bun:sqlite";
	11	import type { Repo } from "../core/repos.ts";
	12	import { nextUp } from "../core/next_up.ts";
	13	import type { Estimate } from "./estimate.ts";
	14	import { cutLine, priceRows, projection, weekCapacity, type Confidence } from "./week.ts";
	15
	16	export const WEEK_MS = 7 * 86_400_000;
	17	export const MAX_PROPOSALS = 3;
	18	/** A run that ended failed this many times in the window marks an issue stuck. */
	19	const STUCK_FAILS = 2;
	20
	21	export interface Projected {
	22	readonly sentence: string;
	23	readonly fits: readonly number[];
	24	readonly shipLow: number;
	25	readonly shipHigh: number;
	26	readonly confidence: Confidence;
	27	readonly ranges: Readonly<Record<string, { low: number; high: number }>>;
	28	}
	29
	30	export interface Line {
	31	readonly number: number;
	32	readonly title: string;
	33	readonly usd: number;
	34	readonly why: string;
	35	}
	36
	37	export interface Proposal {
	38	/** The one change a tap makes: put the issue behind the Later gate. */
	39	readonly kind: "not_now";
	40	readonly number: number;
	41	readonly words: string;
	42	}
	43
	44	export interface Retro {
	45	readonly weekEnd: string;
	46	readonly shipped: readonly Line[];
	47	readonly projected: Projected \| null;
	48	/** Shipped issues that had a range, and how many cost inside it. */
	49	readonly accuracy: { readonly compared: number; readonly inside: number };
	50	readonly costly: readonly Line[];
	51	readonly stuck: readonly Line[];
	52	readonly proposals: readonly Proposal[];
	53	}
	54
	55	const usd = (n: number): string => `$${n.toFixed(2)}`;
	56
	57	/** The projection made now for the open window; null while no weekly reset is known. */
	58	export function projectNow(db: Database, repo: Repo, now: Date): { weekEnd: string; projected: Projected } \| null {
	59	const capacity = weekCapacity(db, now);
	60	if (capacity?.resetsAt == null) return null;
	61	const rows = nextUp(db, repo).rows;
	62	const priced = priceRows(db, repo.id, rows);
	63	const cut = cutLine(priced, capacity);
	64	const ranges: Record<string, { low: number; high: number }> = {};
	65	for (const p of priced) if (p.estimate.known) ranges[String(p.number)] = rangeOf(p.estimate);
	66	return {
	67	weekEnd: capacity.resetsAt,
	68	projected: {
	69	sentence: projection(cut, rows.length, capacity),
	70	fits: cut.fits,
	71	shipLow: cut.shipLow,
	72	shipHigh: cut.shipHigh,
	73	confidence: cut.confidence,
	74	ranges,
	75	},
	76	};
	77	}
	78
	79	const rangeOf = (e: Estimate & { known: true }) => ({ low: e.low, high: e.high });
	80
	81	interface SpentRow {
	82	number: number;
	83	title: string;
	84	state: string;
	85	usd: number;
	86	failed: number;
	87	last: string;
	88	}
	89
	90	/** What each issue touched in the window cost, and how its runs ended; the dearest first. */
	91	export function windowSpend(db: Database, repoId: string, from: string, to: string): SpentRow[] {
	92	const runs = db
	93	.query<{ id: string; issue_id: string; cost_usd: number; state: string; summary: string }, [string, string, string]>(
	94	`SELECT r.id, r.issue_id, r.cost_usd, r.state, r.summary FROM run r
	95	WHERE r.kind = 'agent' AND r.started_at >= ?2 AND r.started_at < ?3 AND r.repo_id = ?1 AND r.issue_id IS NOT NULL`,
	96	)
	97	.all(repoId, from, to);
	98	const by = new Map<string, { usd: number; failed: number; last: string; lastId: string }>();
	99	for (const r of runs) {
	100	const was = by.get(r.issue_id) ?? { usd: 0, failed: 0, last: "", lastId: "" };
	101	was.usd += r.cost_usd;
	102	if (r.state === "failed") {
	103	was.failed++;
	104	if (r.id > was.lastId) {
	105	was.lastId = r.id;
	106	was.last = r.summary;
	107	}
	108	}
	109	by.set(r.issue_id, was);
	110	}
	111	const out: SpentRow[] = [];
	112	for (const [issueId, w] of by) {
	113	const i = db
	114	.query<{ number: number; title: string; state: string; sealed: number }, [string]>(
	115	"SELECT number, title, state, sealed FROM issue WHERE id = ?1 AND kind = 'issue'",
	116	)
	117	.get(issueId);
	118	if (i !== null && i.sealed === 0) out.push({ number: i.number, title: i.title, state: i.state, usd: w.usd, failed: w.failed, last: w.last });
	119	}
	120	return out.sort((a, b) => b.usd - a.usd \|\| a.number - b.number);
	121	}
	122
	123	/** Issues closed done in the window, with the spend of every run on each. */
	124	export function windowShipped(db: Database, repoId: string, from: string, to: string): Line[] {
	125	return db
	126	.query<{ number: number; title: string; usd: number }, [string, string, string]>(
	127	`SELECT i.number, i.title, COALESCE((SELECT SUM(cost_usd) FROM run WHERE issue_id = i.id AND kind = 'agent'), 0) AS usd
	128	FROM issue i
	129	WHERE i.repo_id = ?1 AND i.kind = 'issue' AND i.state = 'closed' AND i.sealed = 0 AND i.close_reason = 'done'
	130	AND i.closed_at >= ?2 AND i.closed_at < ?3
	131	ORDER BY i.number`,
	132	)
	133	.all(repoId, from, to)
	134	.map((r) => ({ number: r.number, title: r.title, usd: r.usd, why: `cost ${usd(r.usd)}` }));
	135	}
	136
	137	/** A failed run's words reduced to a class: its own output is never copied, since it may hold anything. */
	138	export function failureClass(summary: string): string {
	139	const t = summary.toLowerCase();
	140	if (/time ?out\|timed out/.test(t)) return "timed out";
	141	if (/limit\|quota\|rate/.test(t)) return "hit a usage limit";
	142	if (/check\|ci\b\|lint\|type/.test(t)) return "its check failed";
	143	if (/test/.test(t)) return "its tests failed";
	144	if (/conflict\|merge/.test(t)) return "hit a merge conflict";
	145	return "ended without finishing";
	146	}
	147
	148	/** Pure: the retrospective from what was read. */
	149	export function composeRetro(
	150	weekEnd: string,
	151	shipped: readonly Line[],
	152	spent: readonly SpentRow[],
	153	projected: Projected \| null,
	154	): Retro {
	155	let compared = 0;
	156	let inside = 0;
	157	for (const s of shipped) {
	158	const range = projected?.ranges[String(s.number)];
	159	if (range === undefined) continue;
	160	compared++;
	161	if (s.usd >= range.low && s.usd <= range.high) inside++;
	162	}
	163	const open = spent.filter((s) => s.state === "open" && s.usd > 0);
	164	const costly = open
	165	.slice(0, MAX_PROPOSALS)
	166	.map((s) => ({ number: s.number, title: s.title, usd: s.usd, why: `spent ${usd(s.usd)} and is still open` }));
	167	const stuck = open
	168	.filter((s) => s.failed >= STUCK_FAILS)
	169	.map((s) => ({
	170	number: s.number,
	171	title: s.title,
	172	usd: s.usd,
	173	why: `${s.failed} failed runs, the last ${failureClass(s.last)}`,
	174	}));
	175	const picked = new Map<number, Proposal>();
	176	for (const l of [...stuck, ...costly]) {
	177	if (picked.size >= MAX_PROPOSALS) break;
	178	if (!picked.has(l.number))
	179	picked.set(l.number, {
	180	kind: "not_now",
	181	number: l.number,
	182	words: `Put #${l.number} behind the Later gate: it ${l.why.startsWith("spent") ? l.why : `has ${l.why}`}.`,
	183	});
	184	}
	185	return { weekEnd, shipped, projected, accuracy: { compared, inside }, costly, stuck, proposals: [...picked.values()] };
	186	}
	187
	188	/** Write the retrospective of the window that ended at `weekEnd`, once. True when this call wrote it. */
	189	export function writeRetro(db: Database, repo: Repo, weekEnd: string, now: Date): boolean {
	190	const had = db
	191	.query<{ n: number }, [string, string]>("SELECT COUNT(*) AS n FROM week_retro WHERE repo_id = ?1 AND week_end = ?2")
	192	.get(repo.id, weekEnd);
	193	if (had !== null && had.n > 0) return false;
	194	const from = new Date(Date.parse(weekEnd) - WEEK_MS).toISOString();
	195	const stored = db
	196	.query<{ body: string }, [string, string]>("SELECT body FROM week_projection WHERE repo_id = ?1 AND week_end = ?2")
	197	.get(repo.id, weekEnd);
	198	const projected = stored === null ? null : (JSON.parse(stored.body) as Projected);
	199	const retro = composeRetro(weekEnd, windowShipped(db, repo.id, from, weekEnd), windowSpend(db, repo.id, from, weekEnd), projected);
	200	db.query("INSERT OR IGNORE INTO week_retro (repo_id, week_end, body, at) VALUES (?1, ?2, ?3, ?4)").run(
	201	repo.id,
	202	weekEnd,
	203	JSON.stringify(retro),
	204	now.toISOString(),
	205	);
	206	return true;
	207	}
	208
	209	/** The latest retrospective of a repository, or undefined. */
	210	export function latestRetro(db: Database, repoId: string): Retro \| undefined {
	211	const row = db
	212	.query<{ body: string }, [string]>("SELECT body FROM week_retro WHERE repo_id = ?1 ORDER BY week_end DESC LIMIT 1")
	213	.get(repoId);
	214	return row === null ? undefined : (JSON.parse(row.body) as Retro);
	215	}
	216
	217	/** Which proposals of a retrospective have been taken. */
	218	export function takenOf(db: Database, repoId: string, weekEnd: string): Set<number> {
	219	return new Set(
	220	db
	221	.query<{ idx: number }, [string, string]>("SELECT idx FROM week_retro_taken WHERE repo_id = ?1 AND week_end = ?2")
	222	.all(repoId, weekEnd)
	223	.map((r) => r.idx),
	224	);
	225	}
	226
	227	/**
	228	* Each hour: close the retrospective of every window that has ended, then keep
	229	* the projection of the window that is open. Only repositories with a ranked
	230	* list take part. Safe to call as often as you like.
	231	*/
	232	export function tickWeeks(db: Database, repos: readonly Repo[], now: Date): Repo[] {
	233	const wrote: Repo[] = [];
	234	for (const repo of repos) {
	235	const due = db
	236	.query<{ week_end: string }, [string, string]>(
	237	`SELECT p.week_end FROM week_projection p
	238	WHERE p.repo_id = ?1 AND p.week_end <= ?2
	239	AND NOT EXISTS (SELECT 1 FROM week_retro r WHERE r.repo_id = p.repo_id AND r.week_end = p.week_end)`,
	240	)
	241	.all(repo.id, now.toISOString());
	242	for (const d of due) if (writeRetro(db, repo, d.week_end, now)) wrote.push(repo);
	243	const open = projectNow(db, repo, now);
	244	if (open !== null)
	245	db.query("INSERT OR IGNORE INTO week_projection (repo_id, week_end, body, at) VALUES (?1, ?2, ?3, ?4)").run(
	246	repo.id,
	247	open.weekEnd,
	248	JSON.stringify(open.projected),
	249	now.toISOString(),
	250	);
	251	}
	252	return wrote;
	253	}
	254
	255	/** Repositories that have a ranked list: the ones whose week is planned. */
	256	export function plannedRepoIds(db: Database): string[] {
	257	return db
	258	.query<{ repo_id: string }, []>(
	259	`SELECT DISTINCT i.repo_id FROM issue_rank k JOIN issue i ON i.id = k.issue_id WHERE i.state = 'open'`,
	260	)
	261	.all()
	262	.map((r) => r.repo_id);
	263	}
		@@ -0,0 +1,127 @@
	1	/**
	2	* The week is the sprint (#8704): the subscription's weekly reset is the
	3	* boundary and what the crew may still spend before it is the capacity. The
	4	* cut line falls on the owner's ranked list after the last issue whose
	5	* running estimate still fits, building strictly from the top, so reranking
	6	* moves it. Same list, same history, same capacity: same line. No agent run
	7	* is spent. `cutLine` is plain data in and out; `weekCapacity` is the one read.
	8	*/
	9
	10	import type { Database } from "bun:sqlite";
	11	import type { NextRow } from "../core/next_up.ts";
	12	import { standings } from "../core/standing.ts";
	13	import { listCredentials } from "../core/subscriptions.ts";
	14	import { estimate, issueHistory, kindOf, labelsOf, MIN_SAMPLES, SURE_SAMPLES, sizeOf, type Estimate, type Sample } from "./estimate.ts";
	15
	16	export interface Capacity {
	17	/** What the crew may still spend before the reset, in US dollars. */
	18	readonly usd: number;
	19	/** The soonest weekly reset among the accounts that report one, ISO. */
	20	readonly resetsAt: string \| null;
	21	}
	22
	23	/** The crew's remaining weekly capacity over every account whose cap is known; null when none is. */
	24	export function weekCapacity(db: Database, now: Date): Capacity \| null {
	25	const ids = listCredentials(db).map((c) => c.id);
	26	let usd = 0;
	27	let resetsAt: string \| null = null;
	28	let any = false;
	29	for (const s of standings(db, ids, now).values()) {
	30	const week = s.windows.find((w) => w.window === "week");
	31	if (week?.crewRemaining == null) continue;
	32	any = true;
	33	usd += week.crewRemaining.value;
	34	const at = week.resetsAt?.value ?? null;
	35	if (at !== null && (resetsAt === null \|\| at < resetsAt)) resetsAt = at;
	36	}
	37	return any ? { usd: Math.round(usd * 100) / 100, resetsAt } : null;
	38	}
	39
	40	export interface Priced {
	41	readonly number: number;
	42	readonly estimate: Estimate;
	43	}
	44
	45	export type Confidence = "high" \| "medium" \| "low";
	46
	47	export interface Cut {
	48	/** Issue numbers that fit this week, in list order; the rest read as next week. */
	49	readonly fits: readonly number[];
	50	/** The least and most that should ship by the reset, from the range's two ends. */
	51	readonly shipLow: number;
	52	readonly shipHigh: number;
	53	readonly confidence: Confidence;
	54	/** Why there is no line: capacity or history missing. Null when drawn. */
	55	readonly unsure: string \| null;
	56	}
	57
	58	/** Walk the list from the top, adding each row's cost while it fits `usd`; stop at the first that does not. */
	59	function fitting(rows: readonly Priced[], cost: (e: Estimate & { known: true }) => number, fill: number, usd: number): number[] {
	60	const out: number[] = [];
	61	let used = 0;
	62	for (const r of rows) {
	63	used += r.estimate.known ? cost(r.estimate) : fill;
	64	if (used > usd) break;
	65	out.push(r.number);
	66	}
	67	return out;
	68	}
	69
	70	/**
	71	* Where the week's capacity ends on the ranked list. An issue with no
	72	* estimate counts as the median of those that have one; with none at all
	73	* there is no line, and it says so.
	74	*/
	75	export function cutLine(rows: readonly Priced[], capacity: Capacity \| null): Cut {
	76	const none = (unsure: string): Cut => ({ fits: [], shipLow: 0, shipHigh: 0, confidence: "low", unsure });
	77	if (capacity === null) return none("the weekly capacity has not been read yet");
	78	const known = rows.flatMap((r) => (r.estimate.known ? [r.estimate] : []));
	79	if (known.length === 0) return none("there is too little history to estimate any issue");
	80	const mids = known.map((e) => e.mid).sort((a, b) => a - b);
	81	const fill = mids[Math.floor((mids.length - 1) / 2)]!;
	82	const fits = fitting(rows, (e) => e.mid, fill, capacity.usd);
	83	const least = fitting(rows, (e) => e.high, fill, capacity.usd).length;
	84	const most = fitting(rows, (e) => e.low, fill, capacity.usd).length;
	85	const weakest = Math.min(...rows.map((r) => r.estimate.samples));
	86	const confidence: Confidence =
	87	known.length < rows.length ? "low" : weakest >= SURE_SAMPLES ? "high" : weakest >= MIN_SAMPLES ? "medium" : "low";
	88	return { fits, shipLow: least, shipHigh: most, confidence, unsure: null };
	89	}
	90
	91	/** The projection in one sentence. */
	92	export function projection(cut: Cut, total: number, capacity: Capacity \| null): string {
	93	if (cut.unsure !== null) return `No projection yet: ${cut.unsure}.`;
	94	const by = capacity?.resetsAt == null ? "the reset" : `the reset on ${capacity.resetsAt.slice(0, 10)}`;
	95	const count = cut.shipLow === cut.shipHigh ? `${cut.shipHigh}` : `${cut.shipLow} to ${cut.shipHigh}`;
	96	return `At the current rate ${count} of the ${total} issues on the list should ship by ${by}; ${cut.confidence} confidence.`;
	97	}
	98
	99	/** Price each row of the list from the repository's history. */
	100	export function priceRows(db: Database, repoId: string, rows: readonly NextRow[], history?: readonly Sample[]): Priced[] {
	101	const past = history ?? issueHistory(db, repoId);
	102	const labels = labelsOf(db, rows.map((r) => r.issue.id));
	103	return rows.map((r) => ({
	104	number: r.issue.number,
	105	estimate: estimate(past, sizeOf(r.issue), kindOf(labels.get(r.issue.id) ?? [])),
	106	}));
	107	}
	108
	109	/** "$1.20–$3.40" or why there is none. */
	110	export function rangeWords(e: Estimate): string {
	111	return e.known ? `$${e.low.toFixed(2)}–$${e.high.toFixed(2)} (${e.basis})` : e.basis;
	112	}
	113
	114	/** Everything the page, the terminal and MCP draw of the week on Next up, from one read. */
	115	export interface WeekView {
	116	readonly priced: readonly Priced[];
	117	readonly cut: Cut;
	118	readonly capacity: Capacity \| null;
	119	readonly sentence: string;
	120	}
	121
	122	export function weekView(db: Database, repoId: string, rows: readonly NextRow[], now: Date): WeekView {
	123	const capacity = weekCapacity(db, now);
	124	const priced = priceRows(db, repoId, rows);
	125	const cut = cutLine(priced, capacity);
	126	return { priced, cut, capacity, sentence: projection(cut, rows.length, capacity) };
	127	}
		@@ -174,5 +174,6 @@ export { tool as vision } from "./vision.ts";
174	174	export { tool as wait_for } from "./wait_for.ts";
175	175	export { tool as watch } from "./watch.ts";
176	176	export { tool as waves } from "./waves.ts";
	177	export { tool as week } from "./week.ts";
177	178	export { tool as whoami_can } from "./whoami_can.ts";
178	179	export { tool as write_file } from "./write_file.ts";