1ec2e9d · d452a82 · 055d0f8
@@ -664,6 +664,18 @@
is full: no pull has merged in 48 h while one was closed unmerged, or more than
words. A comment on the direction issue from someone who may write there lifts
the hold; an issue handed to the planner is still owed its pass.
Every tick says why each ready issue a builder cannot start is held, counted
under the first filter that holds it (`crew/held.ts`): `held: running=1
open_pull=10 stalled=12 run_cap=11` — a run on it, an open pull proposing it,
the planner's, stalled, at its run cap, parked twice, covered by a red-main
fix, or a setting's finding. `/flow` draws the same per autonomous app as one
bar, and the terminal's Flow command prints it as a line per app
(`flow/held.ts`, kept 5 s). When nothing is startable while builder slots are free and some of the
held are stalled, capped or parked twice, the planner is owed one pass with
that breakdown in its brief, to re-plan them into smaller, fresh issues; a
full plate and its own unanswered decline do not hold that pass, and the
same breakdown does not ask it twice.
The forge asks the host for one more binary: `claude`, on `PATH` or at
`FORGE_CLAUDE`, authenticated as the operator (an `ANTHROPIC_API_KEY` in the
forge's environment is handed to runs; the machine's own Claude Code login
@@ -55,3 +55,11 @@
Flow command, a forge admin's like the page, opens a dialog with the
bottleneck sentence, the headline and one line per stage of its last-hour
and 24-hour counts. A sealed issue is counted, its title is
not shown.
Under the pipeline, `/flow` shows each autonomous repository's ready list as
one bar (#2244): what a builder could start beside the count per filter that
holds the rest — `crew/held.ts`'s `heldBy`, the same counts the autonomy
tick logs as `held=`, read through `flow/held.ts`, which keeps the rows 5 s.
The terminal's Flow command prints the same rows, one line per repository
(`alice/engine startable=0 stalled=4 run_cap=1`). A granted agent sees
public repositories only, on both.
@@ -35,8 +35,6 @@
import {
  crewRole,
} from "../core/agents.ts";
import { pickBuilder, routeIssue } from "./route.ts";
import { coveredByRedFix } from "./red_fix.ts";
import { isSettingFinding } from "./setting_finding.ts";
import { readyNow, repoGraph, type Ranked } from "../core/dependencies.ts";
import {
  latestDecision,
@@ -91,13 +89,8 @@
import { reviewSummary } from "../core/reviews.ts";
import { standing } from "../core/standing.ts";
import { pace, type Pace } from "./pacing.ts";
import { BREAKER_NOTE, breakerTripped } from "./breaker.ts";
import {
  capReached,
  handedOverPulls,
  runCapOf,
  SKIP_SUMMARY,
  skipsReplan,
} from "./guard.ts";
import { handedOverPulls, SKIP_SUMMARY, skipsReplan } from "./guard.ts";
import { atRunCap, type Held, heldBy, heldWords, replannable } from "./held.ts";
import { BY_CREW, DONE_LIKE } from "../core/done_on_main.ts";
import { ALREADY_NOTE, alreadyDoneOids } from "./already.ts";
import { interruptionOf } from "./interrupted.ts";
@@ -115,8 +108,6 @@
import {
  directorsAmong,
  landsOnItsOwn,
  markReaders,
  proposedWork,
  speaksForCrew,
} from "./direct.ts";
import { crewOffInPreview } from "./preview.ts";
import { moveRequested } from "./requested.ts";
@@ -364,7 +355,8 @@
export async function driveRepo(
  // operator's; at a wall nothing new starts until the reset.
  const paced = repoPace(app, repo, now);
  if (paced.slots === 0 && slotted.length === 0) return "waiting";
  const ready = startable(app, repo, readyNow(repoGraph(app.db, repo.id, { sealed: true })), crew, active);
  const held = heldBy(app, repo, readyNow(repoGraph(app.db, repo.id, { sealed: true })), crew, active);
  const ready = held.startable;
  if (slotted.length >= paced.slots) {
    // The builders are busy; the planner can still refill the map, when
    // it is thin — counted, never assumed: a full crew with a full map is
@@ -412,17 +404,20 @@
export async function driveRepo(
    return "picked";
  }
  // Nothing is ready: the planner is asked, thin or dry, at most every
  // REPLAN_AFTER_MS.
  if (await planIfThin(app, repo, by, crew, active, 0, now)) return "planned";
  // Nothing is startable with slots free: the planner is asked, thin or
  // dry, at most every REPLAN_AFTER_MS. When ready issues are held by what
  // re-planning lifts — stalled, capped, parked twice — it is asked with
  // that breakdown, and neither a full plate nor its own unanswered
  // decline holds it: nothing else will move them (#2244).
  const stuck = replannable(held).length > 0 ? held : null;
  if (await planIfThin(app, repo, by, crew, active, 0, now, stuck)) return "planned";
  return "idle";
}
/**
 * The ready issues a builder may start now: not the direction, not in
 * flight, not already proposed in an open pull, not held by the planner or
 * a reviewer, not stalled, capped, parked, covered by a red fix, or a
 * setting's finding. The tick log counts these beside the raw ready list.
 * The ready issues a builder may start now: not the direction, and held by
 * none of `held.ts`'s filters. The tick log counts these beside the raw
 * ready list, and the held ones per filter.
 */
export function startable(
  app: App,
@@ -431,24 +426,7 @@
export function startable(
  crew: readonly { agent: Agent; role: CrewRole }[],
  active: readonly Run[],
): Ranked[] {
  const busyIssues = new Set(active.map((r) => r.issueId));
  const proposed = proposedWork(app.db, repo);
  // An issue a planner or a reviewer holds is theirs, not a builder's.
  const planners = new Set(
    crew.filter((c) => c.role !== "builder").map((c) => c.agent.user.id),
  );
  return ready.filter(
    (r) =>
      r.issue.id !== repo.directionIssueId &&
      !busyIssues.has(r.issue.id) &&
      !proposed.has(r.issue.number) &&
      (r.issue.assigneeId === null || !planners.has(r.issue.assigneeId)) &&
      !stalled(app, repo, r.issue) &&
      !atRunCap(app, repo, r.issue) &&
      parkedCount(app, repo, r.issue.id) < PARK_STRIKES &&
      !coveredByRedFix(app.db, repo.id, r.issue) &&
      !isSettingFinding(app.db, r.issue.id),
  );
  return heldBy(app, repo, ready, crew, active).startable;
}
/** The map is thin below this many ready issues; the planner refills it. */
@@ -581,6 +559,7 @@
async function planIfThin(
  active: readonly Run[],
  ready: number,
  now: Date,
  stuck: Held | null = null,
): Promise<boolean> {
  const handed = [...parkedTwice(app.db, [repo]), ...handedOverPulls(app.db, repo)];
  if (ready >= THIN_MAP && handed.length === 0) return false;
@@ -604,19 +583,23 @@
async function planIfThin(
  const seen = lastPlan?.created_at ?? "";
  const owed = handed.filter((issue) => issue.at > seen);
  if (ready >= THIN_MAP && owed.length === 0) return false;
  // Nothing startable for issues held since its last pass that re-planning
  // lifts: owed one pass like a hand-over, once (#2244).
  const unstuck = stuck === null ? [] : replannable(stuck).filter((issue) => heldSince(app, issue, seen));
  const news = owed.length + unstuck.length;
  // The direction is the planner's standing issue, not one issue retried:
  // it is held to its own day's share, never the builders' cap (#2143).
  if (atRunCap(app, repo, direction))
    return notPlanned(repo, "parked: the direction is at its day's planning cap");
  // An issue the crew handed over is owed its pass whatever the hold: the
  // planner splitting it is how work starts landing again.
  const hold = owed.length === 0 ? plannerHold(app, repo, now) : null;
  const hold = news === 0 ? plannerHold(app, repo, now) : null;
  if (hold !== null) return held(repo, holdWhy(hold));
  if (lastPlan !== null && lastPlan !== undefined) {
    // A planner that declined the direction is not asked again until a
    // person has said something on it, or the crew hands it an issue.
    if (
      owed.length === 0 &&
      news === 0 &&
      lastPlan.state === "failed" &&
      declinedUnanswered(app, repo, direction)
    )
@@ -631,7 +614,7 @@
async function planIfThin(
    // Nobody spoke and the map has not moved since the last pass: another
    // would read its own summary and change nothing (#1097).
    if (
      owed.length === 0 &&
      news === 0 &&
      skipsReplan(app.db, repo, direction, planner, lastPlan.created_at)
    )
      return notPlanned(repo, SKIP_SUMMARY);
@@ -650,9 +633,11 @@
async function planIfThin(
  log.info(
    owed.length > 0
      ? "parked twice; planner asked"
      : ready === 0
        ? "map ran dry; planner asked"
        : "map is thin; planner asked",
      : unstuck.length > 0
        ? "nothing startable; planner asked"
        : ready === 0
          ? "map ran dry; planner asked"
          : "map is thin; planner asked",
    {
      repo: `${repo.ownerName}/${repo.name}`,
      planner: planner.user.username,
@@ -660,43 +645,25 @@
async function planIfThin(
      ...(owed.length > 0
        ? { parkedTwice: owed.map((issue) => `#${issue.number}`).join(" ") }
        : {}),
      ...(stuck === null ? {} : { held: heldWords(stuck) }),
    },
  );
  return true;
}
/**
 * An issue a builder already ran on and left without a pull — declined, or
 * cut short — is not picked again by the clock: running it again blind is
 * the loop autonomy refuses. It waits for a person's word, which is a
 * feedback run like any other.
 * Whether `issue` came to be held after `since` — its newest builder run
 * ended then, which is what stalls or caps it — so a planning pass that
 * started before has not seen it.
 */
function stalled(app: App, repo: Repo, issue: Issue): boolean {
function heldSince(app: App, issue: Issue, since: string): boolean {
  const last = app.db
    .query<{ state: string; summary: string; created_at: string }, [string]>(
      `SELECT state, summary, created_at FROM run WHERE issue_id = ?1 AND kind = 'agent'
       ORDER BY created_at DESC LIMIT 1`,
    .query<{ at: string | null }, [string]>(
      `SELECT MAX(COALESCE(finished_at, created_at)) AS at FROM run
        WHERE issue_id = ?1 AND kind = 'agent'`,
    )
    .get(issue.id);
  if (last === null || last === undefined) return false;
  if (last.state === "queued" || last.state === "running") return true;
  if (/opened pull #|updated pull #/.test(last.summary)) return false;
  // Cut short by the provider or a restart: nobody tried it, so the clock
  // tries again (`interrupted.ts`).
  if (last.state === "failed" && interruptionOf(last.summary) !== undefined)
    return false;
  // A word since then — from someone who may direct the crew, or the
  // planner's when it re-planned a parked issue — is what un-stalls it. A
  // reader's comment stays on the thread, and so does one imported from
  // an origin, whoever connected it (#619).
  return !app.db
    .query<{ id: string }, [string, string]>(
      `SELECT DISTINCT n.author_id AS id FROM comment n
        WHERE n.issue_id = ?1 AND n.created_at > ?2 AND n.origin_author IS NULL
          AND NOT (n.body LIKE '${DONE_LIKE}' AND ${BY_CREW})`,
    )
    .all(issue.id, last.created_at)
    .some((r) => speaksForCrew(app.db, repo, getUserById(app.db, r.id)));
    .get(issue.id)?.at;
  return typeof last === "string" && last > since;
}
/** Whether the newest run on the issue was a decline and no person has spoken since. */
@@ -799,11 +766,6 @@
export function parkForBreaker(
  return true;
}
/** Whether `issue` is at its run cap (`guard.ts`): the clock neither picks nor plans it. */
export function atRunCap(app: App, repo: Repo, issue: Issue): boolean {
  return capReached(app.db, repo, issue, runCapOf(repo, issue, app.config));
}
/** How many times the crew has parked this issue since a person who directs it last spoke (`parks.ts`). */
export function parkedCount(app: App, repo: Repo, issueId: string): number {
  return countParks(app.db, repo, issueId);
@@ -1147,19 +1109,21 @@
export async function autonomyTick(
      // never a mystery: the numbers behind "idle" are on the line.
      const status = autonomyStatus(app, current, now);
      const ready = readyNow(repoGraph(app.db, current.id, { sealed: true }));
      const held = heldBy(
        app,
        current,
        ready,
        listCrewRoles(app.db, current.id),
        activeRuns(app, current.id),
      );
      log.info("tick", {
        repo: `${repo.ownerName}/${repo.name}`,
        did,
        ready: ready.length,
        // What the builders could start after the filters: 47 ready with 0
        // startable is every one in a pull, stalled or capped (#2143).
        startable: startable(
          app,
          current,
          ready,
          listCrewRoles(app.db, current.id),
          activeRuns(app, current.id),
        ).length,
        // What the builders could start after the filters (#2143), and
        // what holds the rest, per filter (#2244).
        startable: held.startable.length,
        held: heldWords(held),
        active: status.active,
        slots: status.slots,
        ...(requested.length === 0
@@ -187,6 +187,20 @@
export interface TaskInput extends BriefInput {
  readonly parkedTwice?: readonly HandedOver[] | undefined;
  /** For a planner: the issue deferred work waits behind, if there is one. */
  readonly laterGate?: number | undefined;
  /** For a planner: nothing ready can start, and what holds it (`held.ts`). */
  readonly stuck?: Stuck | undefined;
}
/** Ready issues no builder can start, as the planner is told of them (#2244). */
export interface Stuck {
  /** The count per filter, as the tick line says it: `open_pull=10 stalled=3`. */
  readonly held: string;
  /** The held issues re-planning lifts: stalled or at their run cap. */
  readonly issues: readonly {
    readonly number: number;
    readonly title: string;
    readonly hold: "stalled" | "run_cap";
  }[];
}
/** An issue the crew parked twice, as the planner is told of it. */
@@ -219,7 +233,9 @@
function taskBody(input: TaskInput): string {
  const { issue } = input;
  const out: string[] = [];
  const isAgent = (name: string): boolean => name === input.agent.user.username;
  const handed = parkedTwiceLines(input);
  const handed = [parkedTwiceLines(input), stuckLines(input)]
    .filter((lines) => lines.length > 0)
    .flatMap((lines, n) => (n === 0 ? lines : ["", ...lines]));
  const readers = input.readers ?? new Set<string>();
  const said = (author: string): string =>
    readers.has(author) ? `@${author} ${READER}` : `@${author}`;
@@ -515,6 +531,26 @@
function parkedTwiceLines(input: TaskInput): string[] {
  ];
}
/**
 * What a planner is told when no ready issue can start while builders sit
 * free: the count per filter, and each stalled or capped issue, to re-plan
 * now rather than wait for a word nobody is going to write.
 */
function stuckLines(input: TaskInput): string[] {
  const stuck = input.role === "planner" ? input.stuck : undefined;
  if (stuck === undefined || stuck.issues.length === 0) return [];
  const issues = `$FORGE_URL/api/v1/repos/${input.repo.ownerName}/${input.repo.name}/issues`;
  return [
    `Builders are free and no ready issue can start. What holds them: ${stuck.held}.`,
    "Only re-planning moves these; do not wait for a person's comment on them:",
    ...stuck.issues.map(
      (issue) =>
        `- #${issue.number} ${issue.title} (${issue.hold === "stalled" ? "stalled: a builder left it without a pull" : "at its run cap for the day"})`,
    ),
    `Re-plan each into smaller, fresh issues a builder can finish in one run: open them, then close the old one as split into them — PATCH ${issues}/N with {"state":"closed","reason":"split","into":[A,B]} — or, for one fresh issue, with "into":[M]. Say on the old issue what the fresh ones do differently.`,
  ];
}
/**
 * The turn after the budget runs out, in the same session: nothing new,
 * what exists made to land well, and the description written anyway.
@@ -0,0 +1,184 @@
/**
 * Why a ready issue cannot start (#2244). The map's ready list is what no
 * open issue stands in front of; a builder may start only the ones no
 * filter holds. Each held issue is counted under the first filter that
 * holds it, so a tick that says `ready=33 startable=0` also says why:
 * `held: open_pull=10 stalled=12 run_cap=11`.
 *
 * The filters, in the order they are asked:
 * - `running`: a run is in flight on it.
 * - `open_pull`: an open pull already proposes it (`direct.ts`).
 * - `planner`: the planner or a reviewer holds it, not a builder.
 * - `stalled`: a builder ran on it and left without a pull, and nobody
 *   who directs the crew has spoken since.
 * - `run_cap`: it has used its runs for the day (`guard.ts`).
 * - `parked_twice`: the crew parked it twice; it is the planner's (`parks.ts`).
 * - `red_fix`: a fix for a red main already covers it (`red_fix.ts`).
 * - `setting`: a setting's finding, a person's to answer (`setting_finding.ts`).
 *
 * The direction issue is the planner's standing issue and never a
 * builder's; it is left out, not counted.
 */
import type { App } from "../app.ts";
import { listCrewRoles, type Agent, type CrewRole } from "../core/agents.ts";
import { readyNow, repoGraph, type Ranked } from "../core/dependencies.ts";
import { BY_CREW, DONE_LIKE } from "../core/done_on_main.ts";
import type { Issue } from "../core/issues.ts";
import type { Repo } from "../core/repos.ts";
import { listActive, type Run } from "../core/runs.ts";
import { getUserById } from "../core/users.ts";
import type { Stuck } from "./brief.ts";
import { proposedWork, speaksForCrew } from "./direct.ts";
import { capReached, runCapOf } from "./guard.ts";
import { interruptionOf } from "./interrupted.ts";
import { PARK_STRIKES, parkedCount } from "./parks.ts";
import { coveredByRedFix } from "./red_fix.ts";
import { isSettingFinding } from "./setting_finding.ts";
export const HOLDS = [
  "running",
  "open_pull",
  "planner",
  "stalled",
  "run_cap",
  "parked_twice",
  "red_fix",
  "setting",
] as const;
export type HoldName = (typeof HOLDS)[number];
/** The holds the planner can lift by re-planning: the rest wait on work in flight or a person. */
export const REPLANNABLE: readonly HoldName[] = ["stalled", "run_cap", "parked_twice"];
export interface Held {
  /** The ready issues a builder may start now, in the map's order. */
  readonly startable: Ranked[];
  /** Each held issue under the first filter that holds it. */
  readonly by: Readonly<Record<HoldName, readonly Issue[]>>;
}
/**
 * An issue a builder already ran on and left without a pull — declined, or
 * cut short — is not picked again by the clock: running it again blind is
 * the loop autonomy refuses. It waits for a person's word, which is a
 * feedback run like any other.
 */
export function stalled(app: App, repo: Repo, issue: Issue): boolean {
  const last = app.db
    .query<{ state: string; summary: string; created_at: string }, [string]>(
      `SELECT state, summary, created_at FROM run WHERE issue_id = ?1 AND kind = 'agent'
       ORDER BY created_at DESC LIMIT 1`,
    )
    .get(issue.id);
  if (last === null || last === undefined) return false;
  if (last.state === "queued" || last.state === "running") return true;
  if (/opened pull #|updated pull #/.test(last.summary)) return false;
  // Cut short by the provider or a restart: nobody tried it, so the clock
  // tries again (`interrupted.ts`).
  if (last.state === "failed" && interruptionOf(last.summary) !== undefined)
    return false;
  // A word since then — from someone who may direct the crew, or the
  // planner's when it re-planned a parked issue — is what un-stalls it. A
  // reader's comment stays on the thread, and so does one imported from
  // an origin, whoever connected it (#619).
  return !app.db
    .query<{ id: string }, [string, string]>(
      `SELECT DISTINCT n.author_id AS id FROM comment n
        WHERE n.issue_id = ?1 AND n.created_at > ?2 AND n.origin_author IS NULL
          AND NOT (n.body LIKE '${DONE_LIKE}' AND ${BY_CREW})`,
    )
    .all(issue.id, last.created_at)
    .some((r) => speaksForCrew(app.db, repo, getUserById(app.db, r.id)));
}
/** Whether `issue` is at its run cap (`guard.ts`): the clock neither picks nor plans it. */
export function atRunCap(app: App, repo: Repo, issue: Issue): boolean {
  return capReached(app.db, repo, issue, runCapOf(repo, issue, app.config));
}
/** Sort the ready list into what a builder may start and what holds the rest. */
export function heldBy(
  app: App,
  repo: Repo,
  ready: readonly Ranked[],
  crew: readonly { agent: Agent; role: CrewRole }[],
  active: readonly Run[],
): Held {
  const busyIssues = new Set(active.map((r) => r.issueId));
  const proposed = proposedWork(app.db, repo);
  // An issue a planner or a reviewer holds is theirs, not a builder's.
  const planners = new Set(
    crew.filter((c) => c.role !== "builder").map((c) => c.agent.user.id),
  );
  const holdOf = (issue: Issue): HoldName | null => {
    if (busyIssues.has(issue.id)) return "running";
    if (proposed.has(issue.number)) return "open_pull";
    if (issue.assigneeId !== null && planners.has(issue.assigneeId)) return "planner";
    if (stalled(app, repo, issue)) return "stalled";
    if (atRunCap(app, repo, issue)) return "run_cap";
    if (parkedCount(app.db, repo, issue.id) >= PARK_STRIKES) return "parked_twice";
    if (coveredByRedFix(app.db, repo.id, issue)) return "red_fix";
    if (isSettingFinding(app.db, issue.id)) return "setting";
    return null;
  };
  const by = Object.fromEntries(HOLDS.map((h) => [h, [] as Issue[]])) as Record<
    HoldName,
    Issue[]
  >;
  const startable: Ranked[] = [];
  for (const r of ready) {
    if (r.issue.id === repo.directionIssueId) continue;
    const hold = holdOf(r.issue);
    if (hold === null) startable.push(r);
    else by[hold].push(r.issue);
  }
  return { startable, by };
}
/** The count per filter, in `HOLDS` order. */
export function heldCounts(held: Held): Record<HoldName, number> {
  return Object.fromEntries(HOLDS.map((h) => [h, held.by[h].length])) as Record<
    HoldName,
    number
  >;
}
/** The counts as the tick line says them: `open_pull=10 stalled=3`, the empty ones left out. */
export function heldWords(held: Held): string {
  const said = HOLDS.filter((h) => held.by[h].length > 0).map(
    (h) => `${h}=${held.by[h].length}`,
  );
  return said.length === 0 ? "none" : said.join(" ");
}
/** The held issues the planner can lift by re-planning them. */
export function replannable(held: Held): Issue[] {
  return REPLANNABLE.flatMap((h) => held.by[h]);
}
/** The ready list sorted now, from the map, the crew and the runs in flight. */
export function heldNow(app: App, repo: Repo): Held {
  return heldBy(
    app,
    repo,
    readyNow(repoGraph(app.db, repo.id, { sealed: true })),
    listCrewRoles(app.db, repo.id),
    listActive(app.db, "agent").filter((r) => r.repoId === repo.id),
  );
}
/**
 * What a planning pass is told when nothing ready can start: the counts,
 * and the stalled and capped issues to re-plan. Parked-twice ones reach it
 * as hand-overs already (`parks.ts`). Undefined when something can start
 * or nothing re-planning lifts holds the rest.
 */
export function stuckOf(held: Held): Stuck | undefined {
  if (held.startable.length > 0) return undefined;
  const issues = (["stalled", "run_cap"] as const).flatMap((hold) =>
    held.by[hold].map((issue) => ({ number: issue.number, title: issue.title, hold })),
  );
  return issues.length === 0 ? undefined : { held: heldWords(held), issues };
}
@@ -108,6 +108,7 @@
import { clearStaleLocks, lockedOut } from "./locks.ts";
import { interruptedSummary } from "./interrupted.ts";
import { laterGate } from "./later.ts";
import { parkedTwice } from "./parks.ts";
import { heldNow, stuckOf } from "./held.ts";
import { noteLimit } from "../core/standing.ts";
import { pauseReason } from "./pacing.ts";
import {
@@ -913,11 +914,13 @@
async function work(
              .get(issue.id, run.id, run.createdAt)!.n > 0,
          }
        : {}),
      // A planning run is given what the crew handed over (`parks.ts`).
      // A planning run is given what the crew handed over (`parks.ts`),
      // and what holds the ready list when nothing on it can start (`held.ts`).
      ...(brief.role === "planner" && issue.id === repo.directionIssueId
        ? {
            parkedTwice: [...parkedTwice(app.db, [repo]), ...handedOverPulls(app.db, repo)],
            laterGate: laterGate(app.db, repo.id),
            stuck: stuckOf(heldNow(app, repo)),
          }
        : {}),
      checkKind:
@@ -0,0 +1,47 @@
/**
 * Why ready issues cannot start, per autonomous repository (#2244): the
 * rows /flow draws as bars and the terminal's Flow dialog prints as lines —
 * `crew/held.ts`'s counts, the same the autonomy tick logs as `held=`.
 *
 * Sorting a ready list asks a few queries per issue, so the rows are kept
 * for a few seconds: a page reloaded, or the dialog opened beside it, reads
 * them once. The tick never reads this cache; it sorts afresh every time.
 */
import type { App } from "../app.ts";
import { listAutonomousRepos } from "../core/repos.ts";
import { heldCounts, heldNow, type HoldName } from "../crew/held.ts";
export interface HeldRow {
  /** `owner/name`. */
  readonly repo: string;
  readonly public: boolean;
  readonly startable: number;
  readonly counts: Readonly<Record<HoldName, number>>;
}
/** How long the rows are kept. */
export const HELD_TTL_MS = 5_000;
const kept = new WeakMap<App, { at: number; rows: readonly HeldRow[] }>();
/** Each autonomous repository's ready list, sorted by what holds it; private ones for the owner only. */
export function readHeld(app: App, owner: boolean, now = Date.now()): HeldRow[] {
  let entry = kept.get(app);
  if (entry === undefined || now - entry.at >= HELD_TTL_MS || now < entry.at) {
    entry = {
      at: now,
      rows: listAutonomousRepos(app.db).map((repo) => {
        const held = heldNow(app, repo);
      
        junipercrew
        29d ago
        
      
      The first uncached read sorts every autonomous repository on the request path, about 19 ms measured. A page reload after the 5 s TTL pays it, and so does a stampede of readers. Fine for now. If the repository count grows, refresh the rows from the tick instead.
    
        return {
          repo: `${repo.ownerName}/${repo.name}`,
          public: repo.visibility === "public",
          startable: held.startable.length,
          counts: heldCounts(held),
        };
      }),
    };
    kept.set(app, entry);
  }
  return entry.rows.filter((r) => owner || r.public);
}
@@ -53,6 +53,7 @@
import { domainsScreen } from "./screens/domains.ts";
import { ownerScreen } from "./screens/owner.ts";
import { resilienceLines, resilienceScreen } from "./screens/resilience.ts";
import { flowLines, flowScreen } from "./screens/flow.ts";
import { readHeld } from "../flow/held.ts";
import { memoryScreen, systemLines, systemScreen } from "./screens/system.ts";
import { grantable, READS_KEPT, recentReads } from "../core/telemetry.ts";
import { noteRead, setTelemetryGrant, telemetryReader } from "../actions/telemetry.ts";
@@ -267,6 +268,7 @@
export function forgeCommands(session: Session): (ctx: Ctx) => Command[] {
              new Date(),
              systemFor(session.app, flowReader).duplicates,
              flowReader.kind === "agent" ? { queues: queuesFor(session.app, flowReader) } : undefined,
              readHeld(session.app, flowReader.kind === "owner"),
            )));
        },
      });
@@ -6,11 +6,15 @@
 * MCP `flow` tool read. Under them, each repository's merge queue (#2036):
 * queued, gating, landed in the last hour (`flow/queue.ts`); then the
 * conflicted pulls, and the pulls with changes requested waiting on a
 * builder and on a reviewer (`flow/requested.ts`, #2172). Read-only;
 * Enter, Esc or q closes it.
 * builder and on a reviewer (`flow/requested.ts`, #2172); then each
 * autonomous repository's ready list, startable beside the count per
 * filter that holds the rest (`flow/held.ts`, #2244), as /flow draws it.
 * Read-only; Enter, Esc or q closes it.
 */
import type { Database } from "bun:sqlite";
import { HOLDS } from "../../crew/held.ts";
import type { HeldRow } from "../../flow/held.ts";
import { conflictedPulls, conflictedSays } from "../../flow/conflicted.ts";
import { readPipeline, STAGE_LABEL, verdict } from "../../flow/pipeline.ts";
import { readQueues } from "../../flow/queue.ts";
@@ -31,7 +35,9 @@
export function flowLines(
  now = new Date(),
  dups = live().read().duplicates,
  /** What an agent reader may see: its queue lines, conflicted pulls and changes-requested waits come already cut to public. */
  agent?: { queues: ReturnType<typeof readQueues> },
  agent?: { queues: ReturnType<typeof readQueues> } | undefined,
  /** Why ready issues wait, per autonomous repository (`readHeld`, already cut to what the reader may see). */
  held?: readonly HeldRow[],
): string[] {
  const stages = readPipeline(db, now);
  const flow = readThroughput(db, stages.map((s) => s.key), now);
@@ -63,11 +69,30 @@
export function flowLines(
        )),
    ...(conflicted === null ? [] : ["", ...wrap(conflicted, inner)]),
    ...waits,
    ...(held === undefined ? [] : ["", ...heldLines(held, inner)]),
    "",
    ...duplicateLines(dups, inner),
  ];
}
/** One line per autonomous repository: its name, then `startable=N` and each filter holding any. */
export function heldLines(rows: readonly HeldRow[], inner: number): string[] {
  if (rows.length === 0) return ["Ready, and why it waits: no repository runs on its own."];
  return [
    "Ready, and why it waits:",
    ...rows.flatMap((r) =>
      wrap(
        [
          r.repo,
          `startable=${r.startable}`,
          ...HOLDS.filter((h) => r.counts[h] > 0).map((h) => `${h}=${r.counts[h]}`),
        ].join(" "),
        inner,
      ),
    ),
  ];
}
export function flowScreen(ctx: Ctx, lines: readonly string[]): Screen {
  return {
    title: "Flow",
@@ -21,6 +21,11 @@
 * Beside the conflicted pulls, the pulls with changes requested (#2172):
 * those waiting on a builder apart from those waiting on a reviewer, by
 * age — `flow/requested.ts`'s, the rows the tick moves.
 *
 * Under the pipeline, why ready issues cannot start (#2244): per autonomous
 * repository, its ready list as one bar, startable beside each filter that
 * holds the rest — `flow/held.ts`'s rows, the same the tick line says and
 * the terminal's Flow command prints.
 */
import { noteRead, telemetryReader } from "../../actions/telemetry.ts";
@@ -47,6 +52,8 @@
import {
  type StageThroughput,
} from "../../flow/throughput.ts";
import { readQueues, type QueueRow } from "../../flow/queue.ts";
import { HOLDS } from "../../crew/held.ts";
import { readHeld, type HeldRow } from "../../flow/held.ts";
import type { Ctx } from "../../http/context.ts";
import { live } from "../../system/live.ts";
import { notFoundPage, signInFirst } from "../chrome.ts";
@@ -59,6 +66,18 @@
const css = /* css */ `
.flow-out svg { width: 72px; height: 16px; }
.flow-bar { fill: var(--muted-fg); }
.flow-bar[data-empty] { fill: var(--muted); }
.held-bar { width: 100%; height: 12px; display: block; }
.held-key { display: inline-flex; align-items: center; gap: 4px; margin-right: 12px; font-variant-numeric: tabular-nums; }
.held-key svg { width: 10px; height: 10px; }
.held-startable { fill: var(--success); }
.held-running { fill: var(--accent); }
.held-open_pull { fill: var(--merged); }
.held-planner { fill: var(--primary); }
.held-stalled { fill: var(--attn); }
.held-run_cap { fill: var(--danger); }
.held-parked_twice { fill: var(--del-fg); }
.held-red_fix { fill: var(--muted-fg); }
.held-setting { fill: var(--border-strong); }
`;
/** What `?out=` and `?hour=` ask to list, checked: an unknown stage or hour lists nothing. */
@@ -193,11 +212,65 @@
export function flowPage(ctx: Ctx): Response {
      </div>`,
      { pad: false },
    )}
    ${heldCard(readHeld(ctx.app, reader.kind === "owner", now))}
    ${queueCard(queuesFor(ctx.app, reader, new Date(now)))}
    ${listed === null || shown === undefined ? null : outList(shown, listed.hour, now)}`;
  return page({ ctx, title: "Flow", body, styleCss: css });
}
/** One segment per kind, as wide as its share: a picture only; the counts beside it are the words. */
function heldBar(row: HeldRow): Html {
  const parts: [string, number][] = [
    ["startable", row.startable],
    ...HOLDS.map((h): [string, number] => [h, row.counts[h]]),
      
        junipercrew
        29d ago
        outdated
      
      heldNow is computed per request for every autonomous repo, with per-issue queries. Cache it briefly or measure it. The same rows must also reach the terminal Flow screen.
    
  ];
  const total = parts.reduce((n, [, c]) => n + c, 0);
  let x = 0;
  const rects = parts
    .filter(([, c]) => c > 0)
    .map(([kind, c]) => {
      const w = (c / total) * 100;
      const rect = html`<rect class="held-${kind}" x="${x.toFixed(2)}" y="0" width="${w.toFixed(2)}" height="12" />`;
      x += w;
      return rect;
    });
  return html`<svg class="held-bar" viewBox="0 0 100 12" preserveAspectRatio="none" aria-hidden="true" focusable="false">${rects}</svg>`;
}
function heldKey(kind: string, n: number): Html {
  return html`<span class="held-key small" data-held="${kind}">
    <svg viewBox="0 0 10 10" aria-hidden="true" focusable="false"><rect class="held-${kind}" width="10" height="10" /></svg>
    <span class="mono">${kind}=${String(n)}</span>
  </span>`;
}
/** Why ready issues cannot start, per autonomous repository (#2244). */
function heldCard(rows: readonly HeldRow[]): Html {
  return card(
    html`<h2>Ready, and why it waits</h2>
      <p class="muted small">
        Each ready issue a builder could start, or the first filter that holds
        it: a run on it, an open pull, the planner, stalled, its run cap,
        parked twice, a red-main fix, a setting's finding. When nothing can
        start and builders are free, the planner is asked to re-plan what is
        stalled or capped.
      </p>
      ${rows.length === 0
        ? html`<p class="muted">No repository runs on its own.</p>`
        : rows.map(
            (r) => html`<div data-held-repo="${r.repo}">
              <p><a href="/${r.repo}/map">${r.repo}</a></p>
              ${heldBar(r)}
              <p>
                ${heldKey("startable", r.startable)}
                ${HOLDS.filter((h) => r.counts[h] > 0).map((h) => heldKey(h, r.counts[h]))}
              </p>
            </div>`,
          )}`,
    { id: "held" },
  );
}
/** The merge queue, one row per repository with something in it or landed. */
function queueCard(rows: readonly QueueRow[]): Html {
  return card(
@@ -0,0 +1,317 @@
/**
 * Why each ready issue cannot start (#2244): an issue held by each filter
 * is counted under that filter's name, the tick's words say the counts,
 * and a crew with free slots and nothing startable asks the planner once,
 * with the breakdown — a full plate does not hold it. /flow and the
 * terminal's Flow dialog show the same counts, private repositories to the
 * owner only. Each test makes its own repository and crew.
 */
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 { addToCrew, createAgent } from "../src/actions/crew.ts";
import { addComment, assignIssue, openIssue } from "../src/actions/issues.ts";
import { openPull } from "../src/actions/pulls.ts";
import { commitToBranch, createRepo, updateRepoSettings } from "../src/actions/repos.ts";
import { getAgentByName, setCrewRole } from "../src/core/agents.ts";
import { getIssueById, type Issue } from "../src/core/issues.ts";
import { getRepoById, type Repo } from "../src/core/repos.ts";
import { claimRun, createRun, finishRun } from "../src/core/runs.ts";
import { createUser, getUserByName, type User } from "../src/core/users.ts";
import { driveRepo } from "../src/crew/autonomy.ts";
import { taskPrompt } from "../src/crew/brief.ts";
import { ISSUE_RUN_CAP } from "../src/crew/guard.ts";
import { heldCounts, heldNow, heldWords, stuckOf } from "../src/crew/held.ts";
import { PARK_NOTE } from "../src/crew/parks.ts";
import { keyPart } from "../src/crew/sentinel.ts";
import { HELD_TTL_MS, readHeld } from "../src/flow/held.ts";
import { serve, type Servers } from "../src/http/server.ts";
import { flowLines, heldLines } from "../src/tui/screens/flow.ts";
const minutes = (n: number) => new Date(Date.now() - n * 60_000).toISOString();
async function crewed(
  app: App,
  alice: User,
  name: string,
  visibility: "public" | "private" = "private",
): Promise<{ repo: Repo; atlas: User; mason: User }> {
  const made = await createRepo(app, alice, { name, visibility });
  if (!made.ok) throw new Error(String(made.error));
  for (const agent of ["atlas", "mason"]) {
    if (getUserByName(app.db, agent) === undefined) {
      const created = await createAgent(app, alice, { username: agent });
      if (!created.ok) throw new Error(String(created.error));
    }
    expect(addToCrew(app, alice, made.value, agent).ok).toBe(true);
  }
  setCrewRole(app.db, made.value.id, getUserByName(app.db, "atlas")!.id, "planner");
  const set = await updateRepoSettings(app, alice, made.value, {
    autonomy: "autonomous",
    autonomyDirection: "Keep the engine small.",
    autonomyCeilingUsd: 100,
    autonomySlots: 1,
    autonomyBy: alice.id,
  });
  if (!set.ok) throw new Error(JSON.stringify(set.error));
  return {
    repo: getRepoById(app.db, made.value.id)!,
    atlas: getUserByName(app.db, "atlas")!,
    mason: getUserByName(app.db, "mason")!,
  };
}
describe("the tick says why each ready issue cannot start", () => {
  let dataDir: string;
  let app: App;
  let alice: User;
  let servers: Servers;
  /** A finished agent run on `issue`, `ago` minutes back. */
  function ran(repo: Repo, issue: Issue, by: User, summary: string, ago = 0, state: "ok" | "failed" = "failed"): void {
    const run = createRun(app.db, {
      repoId: repo.id,
      kind: "agent",
      issueId: issue.id,
      actorId: by.id,
      reason: "assigned",
    });
    claimRun(app.db, run.id);
    finishRun(app.db, run.id, { state, summary, costUsd: 0.1 });
    const at = minutes(ago);
    app.db
      .query("UPDATE run SET created_at = ?2, started_at = ?2, finished_at = ?2 WHERE id = ?1")
      .run(run.id, at);
  }
  function issue(repo: Repo, title: string, body = ""): Issue {
    const opened = openIssue(app, alice, getRepoById(app.db, repo.id)!, { title, body });
    if (!opened.ok) throw new Error(String(opened.error));
    return opened.value;
  }
  beforeAll(async () => {
    dataDir = await mkdtemp(join(tmpdir(), "forge-held-"));
    app = createApp({ dataDir, port: 0 });
    const a = await createUser(app.db, {
      trusted: true,
      username: "alice",
      email: "[email protected]",
      password: "a-good-passphrase",
      adminIfFirst: true,
    });
    if (!a.ok) throw new Error(a.error);
    alice = a.value;
    servers = await serve(app);
  });
  afterAll(async () => {
    servers.stop();
    app.close();
    await rm(dataDir, { recursive: true, force: true });
  });
  test("an issue held by each filter is counted under its name", async () => {
    const { repo, atlas, mason } = await crewed(app, alice, "engine");
    const free = issue(repo, "Free to start");
    const running = issue(repo, "Running");
    createRun(app.db, { repoId: repo.id, kind: "agent", issueId: running.id, actorId: mason.id, reason: "assigned" });
    const proposed = issue(repo, "Proposed");
    const seeded = await commitToBranch(app, alice, repo, {
      message: "Start",
      files: [{ path: "README.md", content: "# engine\n" }],
    });
    if (!seeded.ok) throw new Error(JSON.stringify(seeded.error));
    const branch = await commitToBranch(app, alice, repo, {
      branch: "feature/proposed",
      base: "main",
      message: "Proposed",
      files: [{ path: "proposed.ts", content: "export const n = 1;\n" }],
    });
    if (!branch.ok) throw new Error(JSON.stringify(branch.error));
    const pull = await openPull(app, alice, repo, {
      title: "Proposed",
      body: `Closes #${proposed.number}`,
      baseBranch: "main",
      headBranch: "feature/proposed",
    });
    if (!pull.ok) throw new Error(String(pull.error));
    const planned = issue(repo, "The planner's");
    expect(assignIssue(app, alice, repo, planned, atlas).ok).toBe(true);
    const stuck = issue(repo, "Stalled");
    ran(repo, stuck, mason, "declined: the ask is unclear");
    const capped = issue(repo, "Capped");
    for (let n = 0; n < ISSUE_RUN_CAP; n++) ran(repo, capped, mason, `opened pull #${90 + n}`, 60 - n, "ok");
      
        junipercrew
        29d ago
        outdated
      
      mason and atlas are only assigned in the previous test, so this test depends on test order. Assign them here.
    
    const parked = issue(repo, "Parked twice");
    addComment(app, mason, repo, parked, `${PARK_NOTE}first`);
    addComment(app, mason, repo, getIssueById(app.db, parked.id)!, `${PARK_NOTE}second`);
    const quoting = issue(repo, "Quotes the red test", "fails: the widget renders");
    const fix = issue(repo, "Fix main");
    const check = createRun(app.db, {
      repoId: repo.id,
      kind: "check",
      env: repo.defaultBranch,
      commitOid: "a".repeat(40),
      reason: "push",
    });
    claimRun(app.db, check.id);
    finishRun(app.db, check.id, {
      state: "failed",
      summary: "check failed: 1 test failed",
      checkDetail: { passed: 1, failed: 1, names: ["the widget renders"] },
    });
    app.db
      .query("INSERT INTO sentinel_finding (key, issue_id, evidence, first_seen, last_seen) VALUES (?1, ?2, '', 'x', 'x')")
      .run(`degraded:${keyPart(`red:${repo.id}`)}`, fix.id);
    const finding = issue(repo, "A setting's finding");
    app.db
      .query("INSERT INTO sentinel_finding (key, issue_id, evidence, first_seen, last_seen) VALUES ('setting:x', ?1, '', 'x', 'x')")
      .run(finding.id);
    const held = heldNow(app, getRepoById(app.db, repo.id)!);
    const named = (h: keyof typeof held.by) => held.by[h].map((i) => i.number);
    expect(held.startable.map((r) => r.issue.number).sort()).toEqual([free.number, fix.number].sort());
    expect(named("running")).toEqual([running.number]);
    expect(named("open_pull")).toEqual([proposed.number]);
    expect(named("planner")).toEqual([planned.number]);
    expect(named("stalled")).toEqual([stuck.number]);
    expect(named("run_cap")).toEqual([capped.number]);
    expect(named("parked_twice")).toEqual([parked.number]);
    expect(named("red_fix")).toEqual([quoting.number]);
    expect(named("setting")).toEqual([finding.number]);
    expect(heldCounts(held).open_pull).toBe(1);
    expect(heldWords(held)).toBe(
      "running=1 open_pull=1 planner=1 stalled=1 run_cap=1 parked_twice=1 red_fix=1 setting=1",
    );
    // Something can start: the planner is not told the crew is stuck.
    expect(stuckOf(held)).toBeUndefined();
  });
  test("nothing startable with a slot free asks the planner once, with the breakdown, whatever the plate", async () => {
    const { repo, atlas, mason } = await crewed(app, alice, "stuck");
    const fresh = () => getRepoById(app.db, repo.id)!;
    // The map ran dry: the planner's first pass, an hour ago.
    expect(await driveRepo(app, fresh())).toBe("planned");
    const direction = getIssueById(app.db, fresh().directionIssueId!)!;
    ran(fresh(), direction, atlas, "opened #2", 60, "ok");
    expect(assignIssue(app, alice, fresh(), getIssueById(app.db, direction.id)!, null).ok).toBe(true);
    // Then five issues, each stalled by a builder since: more than the
    // plate holds (slots × 3), and nothing a builder may start.
    const stalled = ["One", "Two", "Three", "Four"].map((t) => issue(fresh(), t));
    for (const s of stalled) ran(fresh(), s, mason, "declined: too big", 40);
    const capped = issue(fresh(), "Five");
    for (let n = 0; n < ISSUE_RUN_CAP; n++) ran(fresh(), capped, mason, `opened pull #${90 + n}`, 45 - n, "ok");
    const held = heldNow(app, fresh());
    expect(held.startable).toHaveLength(0);
    expect(heldWords(held)).toBe("stalled=4 run_cap=1");
    expect(await driveRepo(app, fresh())).toBe("planned");
    expect(getIssueById(app.db, direction.id)!.assigneeId).toBe(atlas.id);
    // The pass the crew would start, given the breakdown in its brief.
    const told = stuckOf(heldNow(app, fresh()));
    expect(told?.held).toBe("stalled=4 run_cap=1");
    const brief = taskPrompt({
      agent: getAgentByName(app.db, "atlas")!,
      repo: fresh(),
      issue: getIssueById(app.db, direction.id)!,
      branch: "atlas/1-direction",
      forgeUrl: "http://forge.test",
      isApp: false,
      resuming: false,
      role: "planner",
      reason: "assigned",
      comments: [],
      reviews: [],
      reviewComments: [],
      since: direction.createdAt,
      stuck: told,
    });
    expect(brief).toContain("What holds them: stalled=4 run_cap=1.");
    expect(brief).toContain(`- #${stalled[0]!.number} One (stalled: a builder left it without a pull)`);
    expect(brief).toContain(`- #${capped.number} Five (at its run cap for the day)`);
    expect(brief).toContain("do not wait for a person's comment");
    // A builder is never told.
    expect(taskPrompt({ ...{
      agent: getAgentByName(app.db, "mason")!,
      repo: fresh(),
      issue: stalled[0]!,
      branch: "mason/1-one",
      forgeUrl: "http://forge.test",
      isApp: false,
      resuming: false,
      role: "builder",
      reason: "assigned",
      comments: [],
      reviews: [],
      reviewComments: [],
      since: direction.createdAt,
    }, stuck: told })).not.toContain("What holds them");
    // That pass ran and left them as they were: it is not asked again for
    // the same breakdown, and the full plate holds it as before.
    ran(fresh(), direction, atlas, "left them", 30, "ok");
    expect(assignIssue(app, alice, fresh(), getIssueById(app.db, direction.id)!, null).ok).toBe(true);
    expect(await driveRepo(app, fresh())).toBe("idle");
    expect(getIssueById(app.db, direction.id)!.assigneeId).toBeNull();
  });
  test("both doors: /flow and the terminal's Flow dialog show the counts, private ones to the owner only", async () => {
    const open = await crewed(app, alice, "open-door", "public");
    const shut = await crewed(app, alice, "shut-door");
    for (const { repo, mason } of [open, shut]) {
      ran(repo, issue(repo, "Stalled"), mason, "declined: too big", 10);
      const capped = issue(repo, "Capped");
      for (let n = 0; n < ISSUE_RUN_CAP; n++) ran(repo, capped, mason, `opened pull #${90 + n}`, 20 - n, "ok");
    }
    const signin = await fetch(`${servers.url}/signin`, {
      method: "POST",
      redirect: "manual",
      headers: { "content-type": "application/x-www-form-urlencoded", origin: servers.url },
      body: new URLSearchParams({ username: "alice", password: "a-good-passphrase" }),
    });
    const cookie = (signin.headers.get("set-cookie") ?? "").split(";")[0] ?? "";
    const res = await fetch(`${servers.url}/flow`, { headers: { cookie } });
    expect(res.status).toBe(200);
    const page = await res.text();
    expect(page).toContain('id="held"');
    const row = page.slice(page.indexOf('data-held-repo="alice/open-door"'));
    expect(row).toContain('class="held-bar"');
    expect(row).toContain('<span class="mono">startable=0</span>');
    expect(row).toContain('<span class="mono">stalled=1</span>');
    expect(row).toContain('<span class="mono">run_cap=1</span>');
    expect(page).toContain('data-held-repo="alice/shut-door"');
    // The terminal reads the same rows: the owner sees both, an agent
    // reader the public one alone.
    const owner = flowLines(app.db, new Date(), [], undefined, readHeld(app, true)).join("\n");
    expect(owner).toContain("Ready, and why it waits:");
    expect(owner).toContain("alice/open-door startable=0 stalled=1 run_cap=1");
    expect(owner).toContain("alice/shut-door startable=0 stalled=1 run_cap=1");
    const agent = flowLines(app.db, new Date(), [], { queues: [] }, readHeld(app, false)).join("\n");
    expect(agent).toContain("alice/open-door startable=0 stalled=1 run_cap=1");
    expect(agent).not.toContain("shut-door");
    expect(heldLines([], 58)).toEqual(["Ready, and why it waits: no repository runs on its own."]);
  });
  test("the rows are kept a few seconds, then read afresh", async () => {
    const { repo, mason } = await crewed(app, alice, "kept");
    const t0 = Date.now() + 60 * 60_000;
    const stalled = (now: number) =>
      readHeld(app, true, now).find((r) => r.repo === "alice/kept")!.counts.stalled;
    expect(stalled(t0)).toBe(0);
    ran(repo, issue(repo, "Stalled"), mason, "declined: too big", 5);
    expect(stalled(t0 + 1_000)).toBe(0);
    expect(stalled(t0 + HELD_TTL_MS)).toBe(1);
  });
});
		@@ -664,6 +664,18 @@ is full: no pull has merged in 48 h while one was closed unmerged, or more than
664	664	words. A comment on the direction issue from someone who may write there lifts
665	665	the hold; an issue handed to the planner is still owed its pass.
666	666
	667	Every tick says why each ready issue a builder cannot start is held, counted
	668	under the first filter that holds it (`crew/held.ts`): `held: running=1
	669	open_pull=10 stalled=12 run_cap=11` — a run on it, an open pull proposing it,
	670	the planner's, stalled, at its run cap, parked twice, covered by a red-main
	671	fix, or a setting's finding. `/flow` draws the same per autonomous app as one
	672	bar, and the terminal's Flow command prints it as a line per app
	673	(`flow/held.ts`, kept 5 s). When nothing is startable while builder slots are free and some of the
	674	held are stalled, capped or parked twice, the planner is owed one pass with
	675	that breakdown in its brief, to re-plan them into smaller, fresh issues; a
	676	full plate and its own unanswered decline do not hold that pass, and the
	677	same breakdown does not ask it twice.
	678
667	679	The forge asks the host for one more binary: `claude`, on `PATH` or at
668	680	`FORGE_CLAUDE`, authenticated as the operator (an `ANTHROPIC_API_KEY` in the
669	681	forge's environment is handed to runs; the machine's own Claude Code login
		@@ -55,3 +55,11 @@ Flow command, a forge admin's like the page, opens a dialog with the
55	55	bottleneck sentence, the headline and one line per stage of its last-hour
56	56	and 24-hour counts. A sealed issue is counted, its title is
57	57	not shown.
	58
	59	Under the pipeline, `/flow` shows each autonomous repository's ready list as
	60	one bar (#2244): what a builder could start beside the count per filter that
	61	holds the rest — `crew/held.ts`'s `heldBy`, the same counts the autonomy
	62	tick logs as `held=`, read through `flow/held.ts`, which keeps the rows 5 s.
	63	The terminal's Flow command prints the same rows, one line per repository
	64	(`alice/engine startable=0 stalled=4 run_cap=1`). A granted agent sees
	65	public repositories only, on both.
		@@ -35,8 +35,6 @@ import {
35	35	crewRole,
36	36	} from "../core/agents.ts";
37	37	import { pickBuilder, routeIssue } from "./route.ts";
38		import { coveredByRedFix } from "./red_fix.ts";
39		import { isSettingFinding } from "./setting_finding.ts";
40	38	import { readyNow, repoGraph, type Ranked } from "../core/dependencies.ts";
41	39	import {
42	40	latestDecision,
		@@ -91,13 +89,8 @@ import { reviewSummary } from "../core/reviews.ts";
91	89	import { standing } from "../core/standing.ts";
92	90	import { pace, type Pace } from "./pacing.ts";
93	91	import { BREAKER_NOTE, breakerTripped } from "./breaker.ts";
94		import {
95		capReached,
96		handedOverPulls,
97		runCapOf,
98		SKIP_SUMMARY,
99		skipsReplan,
100		} from "./guard.ts";
	92	import { handedOverPulls, SKIP_SUMMARY, skipsReplan } from "./guard.ts";
	93	import { atRunCap, type Held, heldBy, heldWords, replannable } from "./held.ts";
101	94	import { BY_CREW, DONE_LIKE } from "../core/done_on_main.ts";
102	95	import { ALREADY_NOTE, alreadyDoneOids } from "./already.ts";
103	96	import { interruptionOf } from "./interrupted.ts";
		@@ -115,8 +108,6 @@ import {
115	108	directorsAmong,
116	109	landsOnItsOwn,
117	110	markReaders,
118		proposedWork,
119		speaksForCrew,
120	111	} from "./direct.ts";
121	112	import { crewOffInPreview } from "./preview.ts";
122	113	import { moveRequested } from "./requested.ts";
		@@ -364,7 +355,8 @@ export async function driveRepo(
364	355	// operator's; at a wall nothing new starts until the reset.
365	356	const paced = repoPace(app, repo, now);
366	357	if (paced.slots === 0 && slotted.length === 0) return "waiting";
367		const ready = startable(app, repo, readyNow(repoGraph(app.db, repo.id, { sealed: true })), crew, active);
	358	const held = heldBy(app, repo, readyNow(repoGraph(app.db, repo.id, { sealed: true })), crew, active);
	359	const ready = held.startable;
368	360	if (slotted.length >= paced.slots) {
369	361	// The builders are busy; the planner can still refill the map, when
370	362	// it is thin — counted, never assumed: a full crew with a full map is
		@@ -412,17 +404,20 @@ export async function driveRepo(
412	404	return "picked";
413	405	}
414	406
415		// Nothing is ready: the planner is asked, thin or dry, at most every
416		// REPLAN_AFTER_MS.
417		if (await planIfThin(app, repo, by, crew, active, 0, now)) return "planned";
	407	// Nothing is startable with slots free: the planner is asked, thin or
	408	// dry, at most every REPLAN_AFTER_MS. When ready issues are held by what
	409	// re-planning lifts — stalled, capped, parked twice — it is asked with
	410	// that breakdown, and neither a full plate nor its own unanswered
	411	// decline holds it: nothing else will move them (#2244).
	412	const stuck = replannable(held).length > 0 ? held : null;
	413	if (await planIfThin(app, repo, by, crew, active, 0, now, stuck)) return "planned";
418	414	return "idle";
419	415	}
420	416
421	417	/**
422		* The ready issues a builder may start now: not the direction, not in
423		* flight, not already proposed in an open pull, not held by the planner or
424		* a reviewer, not stalled, capped, parked, covered by a red fix, or a
425		* setting's finding. The tick log counts these beside the raw ready list.
	418	* The ready issues a builder may start now: not the direction, and held by
	419	* none of `held.ts`'s filters. The tick log counts these beside the raw
	420	* ready list, and the held ones per filter.
426	421	*/
427	422	export function startable(
428	423	app: App,
		@@ -431,24 +426,7 @@ export function startable(
431	426	crew: readonly { agent: Agent; role: CrewRole }[],
432	427	active: readonly Run[],
433	428	): Ranked[] {
434		const busyIssues = new Set(active.map((r) => r.issueId));
435		const proposed = proposedWork(app.db, repo);
436		// An issue a planner or a reviewer holds is theirs, not a builder's.
437		const planners = new Set(
438		crew.filter((c) => c.role !== "builder").map((c) => c.agent.user.id),
439		);
440		return ready.filter(
441		(r) =>
442		r.issue.id !== repo.directionIssueId &&
443		!busyIssues.has(r.issue.id) &&
444		!proposed.has(r.issue.number) &&
445		(r.issue.assigneeId === null \|\| !planners.has(r.issue.assigneeId)) &&
446		!stalled(app, repo, r.issue) &&
447		!atRunCap(app, repo, r.issue) &&
448		parkedCount(app, repo, r.issue.id) < PARK_STRIKES &&
449		!coveredByRedFix(app.db, repo.id, r.issue) &&
450		!isSettingFinding(app.db, r.issue.id),
451		);
	429	return heldBy(app, repo, ready, crew, active).startable;
452	430	}
453	431
454	432	/** The map is thin below this many ready issues; the planner refills it. */
		@@ -581,6 +559,7 @@ async function planIfThin(
581	559	active: readonly Run[],
582	560	ready: number,
583	561	now: Date,
	562	stuck: Held \| null = null,
584	563	): Promise<boolean> {
585	564	const handed = [...parkedTwice(app.db, [repo]), ...handedOverPulls(app.db, repo)];
586	565	if (ready >= THIN_MAP && handed.length === 0) return false;
		@@ -604,19 +583,23 @@ async function planIfThin(
604	583	const seen = lastPlan?.created_at ?? "";
605	584	const owed = handed.filter((issue) => issue.at > seen);
606	585	if (ready >= THIN_MAP && owed.length === 0) return false;
	586	// Nothing startable for issues held since its last pass that re-planning
	587	// lifts: owed one pass like a hand-over, once (#2244).
	588	const unstuck = stuck === null ? [] : replannable(stuck).filter((issue) => heldSince(app, issue, seen));
	589	const news = owed.length + unstuck.length;
607	590	// The direction is the planner's standing issue, not one issue retried:
608	591	// it is held to its own day's share, never the builders' cap (#2143).
609	592	if (atRunCap(app, repo, direction))
610	593	return notPlanned(repo, "parked: the direction is at its day's planning cap");
611	594	// An issue the crew handed over is owed its pass whatever the hold: the
612	595	// planner splitting it is how work starts landing again.
613		const hold = owed.length === 0 ? plannerHold(app, repo, now) : null;
	596	const hold = news === 0 ? plannerHold(app, repo, now) : null;
614	597	if (hold !== null) return held(repo, holdWhy(hold));
615	598	if (lastPlan !== null && lastPlan !== undefined) {
616	599	// A planner that declined the direction is not asked again until a
617	600	// person has said something on it, or the crew hands it an issue.
618	601	if (
619		owed.length === 0 &&
	602	news === 0 &&
620	603	lastPlan.state === "failed" &&
621	604	declinedUnanswered(app, repo, direction)
622	605	)
		@@ -631,7 +614,7 @@ async function planIfThin(
631	614	// Nobody spoke and the map has not moved since the last pass: another
632	615	// would read its own summary and change nothing (#1097).
633	616	if (
634		owed.length === 0 &&
	617	news === 0 &&
635	618	skipsReplan(app.db, repo, direction, planner, lastPlan.created_at)
636	619	)
637	620	return notPlanned(repo, SKIP_SUMMARY);
		@@ -650,9 +633,11 @@ async function planIfThin(
650	633	log.info(
651	634	owed.length > 0
652	635	? "parked twice; planner asked"
653		: ready === 0
654		? "map ran dry; planner asked"
655		: "map is thin; planner asked",
	636	: unstuck.length > 0
	637	? "nothing startable; planner asked"
	638	: ready === 0
	639	? "map ran dry; planner asked"
	640	: "map is thin; planner asked",
656	641	{
657	642	repo: `${repo.ownerName}/${repo.name}`,
658	643	planner: planner.user.username,
		@@ -660,43 +645,25 @@ async function planIfThin(
660	645	...(owed.length > 0
661	646	? { parkedTwice: owed.map((issue) => `#${issue.number}`).join(" ") }
662	647	: {}),
	648	...(stuck === null ? {} : { held: heldWords(stuck) }),
663	649	},
664	650	);
665	651	return true;
666	652	}
667	653
668	654	/**
669		* An issue a builder already ran on and left without a pull — declined, or
670		* cut short — is not picked again by the clock: running it again blind is
671		* the loop autonomy refuses. It waits for a person's word, which is a
672		* feedback run like any other.
	655	* Whether `issue` came to be held after `since` — its newest builder run
	656	* ended then, which is what stalls or caps it — so a planning pass that
	657	* started before has not seen it.
673	658	*/
674		function stalled(app: App, repo: Repo, issue: Issue): boolean {
	659	function heldSince(app: App, issue: Issue, since: string): boolean {
675	660	const last = app.db
676		.query<{ state: string; summary: string; created_at: string }, [string]>(
677		`SELECT state, summary, created_at FROM run WHERE issue_id = ?1 AND kind = 'agent'
678		ORDER BY created_at DESC LIMIT 1`,
	661	.query<{ at: string \| null }, [string]>(
	662	`SELECT MAX(COALESCE(finished_at, created_at)) AS at FROM run
	663	WHERE issue_id = ?1 AND kind = 'agent'`,
679	664	)
680		.get(issue.id);
681		if (last === null \|\| last === undefined) return false;
682		if (last.state === "queued" \|\| last.state === "running") return true;
683		if (/opened pull #\|updated pull #/.test(last.summary)) return false;
684		// Cut short by the provider or a restart: nobody tried it, so the clock
685		// tries again (`interrupted.ts`).
686		if (last.state === "failed" && interruptionOf(last.summary) !== undefined)
687		return false;
688		// A word since then — from someone who may direct the crew, or the
689		// planner's when it re-planned a parked issue — is what un-stalls it. A
690		// reader's comment stays on the thread, and so does one imported from
691		// an origin, whoever connected it (#619).
692		return !app.db
693		.query<{ id: string }, [string, string]>(
694		`SELECT DISTINCT n.author_id AS id FROM comment n
695		WHERE n.issue_id = ?1 AND n.created_at > ?2 AND n.origin_author IS NULL
696		AND NOT (n.body LIKE '${DONE_LIKE}' AND ${BY_CREW})`,
697		)
698		.all(issue.id, last.created_at)
699		.some((r) => speaksForCrew(app.db, repo, getUserById(app.db, r.id)));
	665	.get(issue.id)?.at;
	666	return typeof last === "string" && last > since;
700	667	}
701	668
702	669	/** Whether the newest run on the issue was a decline and no person has spoken since. */
		@@ -799,11 +766,6 @@ export function parkForBreaker(
799	766	return true;
800	767	}
801	768
802		/** Whether `issue` is at its run cap (`guard.ts`): the clock neither picks nor plans it. */
803		export function atRunCap(app: App, repo: Repo, issue: Issue): boolean {
804		return capReached(app.db, repo, issue, runCapOf(repo, issue, app.config));
805		}
806
807	769	/** How many times the crew has parked this issue since a person who directs it last spoke (`parks.ts`). */
808	770	export function parkedCount(app: App, repo: Repo, issueId: string): number {
809	771	return countParks(app.db, repo, issueId);
		@@ -1147,19 +1109,21 @@ export async function autonomyTick(
1147	1109	// never a mystery: the numbers behind "idle" are on the line.
1148	1110	const status = autonomyStatus(app, current, now);
1149	1111	const ready = readyNow(repoGraph(app.db, current.id, { sealed: true }));
	1112	const held = heldBy(
	1113	app,
	1114	current,
	1115	ready,
	1116	listCrewRoles(app.db, current.id),
	1117	activeRuns(app, current.id),
	1118	);
1150	1119	log.info("tick", {
1151	1120	repo: `${repo.ownerName}/${repo.name}`,
1152	1121	did,
1153	1122	ready: ready.length,
1154		// What the builders could start after the filters: 47 ready with 0
1155		// startable is every one in a pull, stalled or capped (#2143).
1156		startable: startable(
1157		app,
1158		current,
1159		ready,
1160		listCrewRoles(app.db, current.id),
1161		activeRuns(app, current.id),
1162		).length,
	1123	// What the builders could start after the filters (#2143), and
	1124	// what holds the rest, per filter (#2244).
	1125	startable: held.startable.length,
	1126	held: heldWords(held),
1163	1127	active: status.active,
1164	1128	slots: status.slots,
1165	1129	...(requested.length === 0
		@@ -187,6 +187,20 @@ export interface TaskInput extends BriefInput {
187	187	readonly parkedTwice?: readonly HandedOver[] \| undefined;
188	188	/** For a planner: the issue deferred work waits behind, if there is one. */
189	189	readonly laterGate?: number \| undefined;
	190	/** For a planner: nothing ready can start, and what holds it (`held.ts`). */
	191	readonly stuck?: Stuck \| undefined;
	192	}
	193
	194	/** Ready issues no builder can start, as the planner is told of them (#2244). */
	195	export interface Stuck {
	196	/** The count per filter, as the tick line says it: `open_pull=10 stalled=3`. */
	197	readonly held: string;
	198	/** The held issues re-planning lifts: stalled or at their run cap. */
	199	readonly issues: readonly {
	200	readonly number: number;
	201	readonly title: string;
	202	readonly hold: "stalled" \| "run_cap";
	203	}[];
190	204	}
191	205
192	206	/** An issue the crew parked twice, as the planner is told of it. */
		@@ -219,7 +233,9 @@ function taskBody(input: TaskInput): string {
219	233	const { issue } = input;
220	234	const out: string[] = [];
221	235	const isAgent = (name: string): boolean => name === input.agent.user.username;
222		const handed = parkedTwiceLines(input);
	236	const handed = [parkedTwiceLines(input), stuckLines(input)]
	237	.filter((lines) => lines.length > 0)
	238	.flatMap((lines, n) => (n === 0 ? lines : ["", ...lines]));
223	239	const readers = input.readers ?? new Set<string>();
224	240	const said = (author: string): string =>
225	241	readers.has(author) ? `@${author} ${READER}` : `@${author}`;
		@@ -515,6 +531,26 @@ function parkedTwiceLines(input: TaskInput): string[] {
515	531	];
516	532	}
517	533
	534	/**
	535	* What a planner is told when no ready issue can start while builders sit
	536	* free: the count per filter, and each stalled or capped issue, to re-plan
	537	* now rather than wait for a word nobody is going to write.
	538	*/
	539	function stuckLines(input: TaskInput): string[] {
	540	const stuck = input.role === "planner" ? input.stuck : undefined;
	541	if (stuck === undefined \|\| stuck.issues.length === 0) return [];
	542	const issues = `$FORGE_URL/api/v1/repos/${input.repo.ownerName}/${input.repo.name}/issues`;
	543	return [
	544	`Builders are free and no ready issue can start. What holds them: ${stuck.held}.`,
	545	"Only re-planning moves these; do not wait for a person's comment on them:",
	546	...stuck.issues.map(
	547	(issue) =>
	548	`- #${issue.number} ${issue.title} (${issue.hold === "stalled" ? "stalled: a builder left it without a pull" : "at its run cap for the day"})`,
	549	),
	550	`Re-plan each into smaller, fresh issues a builder can finish in one run: open them, then close the old one as split into them — PATCH ${issues}/N with {"state":"closed","reason":"split","into":[A,B]} — or, for one fresh issue, with "into":[M]. Say on the old issue what the fresh ones do differently.`,
	551	];
	552	}
	553
518	554	/**
519	555	* The turn after the budget runs out, in the same session: nothing new,
520	556	* what exists made to land well, and the description written anyway.
		@@ -0,0 +1,184 @@
	1	/**
	2	* Why a ready issue cannot start (#2244). The map's ready list is what no
	3	* open issue stands in front of; a builder may start only the ones no
	4	* filter holds. Each held issue is counted under the first filter that
	5	* holds it, so a tick that says `ready=33 startable=0` also says why:
	6	* `held: open_pull=10 stalled=12 run_cap=11`.
	7	*
	8	* The filters, in the order they are asked:
	9	* - `running`: a run is in flight on it.
	10	* - `open_pull`: an open pull already proposes it (`direct.ts`).
	11	* - `planner`: the planner or a reviewer holds it, not a builder.
	12	* - `stalled`: a builder ran on it and left without a pull, and nobody
	13	* who directs the crew has spoken since.
	14	* - `run_cap`: it has used its runs for the day (`guard.ts`).
	15	* - `parked_twice`: the crew parked it twice; it is the planner's (`parks.ts`).
	16	* - `red_fix`: a fix for a red main already covers it (`red_fix.ts`).
	17	* - `setting`: a setting's finding, a person's to answer (`setting_finding.ts`).
	18	*
	19	* The direction issue is the planner's standing issue and never a
	20	* builder's; it is left out, not counted.
	21	*/
	22
	23	import type { App } from "../app.ts";
	24	import { listCrewRoles, type Agent, type CrewRole } from "../core/agents.ts";
	25	import { readyNow, repoGraph, type Ranked } from "../core/dependencies.ts";
	26	import { BY_CREW, DONE_LIKE } from "../core/done_on_main.ts";
	27	import type { Issue } from "../core/issues.ts";
	28	import type { Repo } from "../core/repos.ts";
	29	import { listActive, type Run } from "../core/runs.ts";
	30	import { getUserById } from "../core/users.ts";
	31	import type { Stuck } from "./brief.ts";
	32	import { proposedWork, speaksForCrew } from "./direct.ts";
	33	import { capReached, runCapOf } from "./guard.ts";
	34	import { interruptionOf } from "./interrupted.ts";
	35	import { PARK_STRIKES, parkedCount } from "./parks.ts";
	36	import { coveredByRedFix } from "./red_fix.ts";
	37	import { isSettingFinding } from "./setting_finding.ts";
	38
	39	export const HOLDS = [
	40	"running",
	41	"open_pull",
	42	"planner",
	43	"stalled",
	44	"run_cap",
	45	"parked_twice",
	46	"red_fix",
	47	"setting",
	48	] as const;
	49
	50	export type HoldName = (typeof HOLDS)[number];
	51
	52	/** The holds the planner can lift by re-planning: the rest wait on work in flight or a person. */
	53	export const REPLANNABLE: readonly HoldName[] = ["stalled", "run_cap", "parked_twice"];
	54
	55	export interface Held {
	56	/** The ready issues a builder may start now, in the map's order. */
	57	readonly startable: Ranked[];
	58	/** Each held issue under the first filter that holds it. */
	59	readonly by: Readonly<Record<HoldName, readonly Issue[]>>;
	60	}
	61
	62	/**
	63	* An issue a builder already ran on and left without a pull — declined, or
	64	* cut short — is not picked again by the clock: running it again blind is
	65	* the loop autonomy refuses. It waits for a person's word, which is a
	66	* feedback run like any other.
	67	*/
	68	export function stalled(app: App, repo: Repo, issue: Issue): boolean {
	69	const last = app.db
	70	.query<{ state: string; summary: string; created_at: string }, [string]>(
	71	`SELECT state, summary, created_at FROM run WHERE issue_id = ?1 AND kind = 'agent'
	72	ORDER BY created_at DESC LIMIT 1`,
	73	)
	74	.get(issue.id);
	75	if (last === null \|\| last === undefined) return false;
	76	if (last.state === "queued" \|\| last.state === "running") return true;
	77	if (/opened pull #\|updated pull #/.test(last.summary)) return false;
	78	// Cut short by the provider or a restart: nobody tried it, so the clock
	79	// tries again (`interrupted.ts`).
	80	if (last.state === "failed" && interruptionOf(last.summary) !== undefined)
	81	return false;
	82	// A word since then — from someone who may direct the crew, or the
	83	// planner's when it re-planned a parked issue — is what un-stalls it. A
	84	// reader's comment stays on the thread, and so does one imported from
	85	// an origin, whoever connected it (#619).
	86	return !app.db
	87	.query<{ id: string }, [string, string]>(
	88	`SELECT DISTINCT n.author_id AS id FROM comment n
	89	WHERE n.issue_id = ?1 AND n.created_at > ?2 AND n.origin_author IS NULL
	90	AND NOT (n.body LIKE '${DONE_LIKE}' AND ${BY_CREW})`,
	91	)
	92	.all(issue.id, last.created_at)
	93	.some((r) => speaksForCrew(app.db, repo, getUserById(app.db, r.id)));
	94	}
	95
	96	/** Whether `issue` is at its run cap (`guard.ts`): the clock neither picks nor plans it. */
	97	export function atRunCap(app: App, repo: Repo, issue: Issue): boolean {
	98	return capReached(app.db, repo, issue, runCapOf(repo, issue, app.config));
	99	}
	100
	101	/** Sort the ready list into what a builder may start and what holds the rest. */
	102	export function heldBy(
	103	app: App,
	104	repo: Repo,
	105	ready: readonly Ranked[],
	106	crew: readonly { agent: Agent; role: CrewRole }[],
	107	active: readonly Run[],
	108	): Held {
	109	const busyIssues = new Set(active.map((r) => r.issueId));
	110	const proposed = proposedWork(app.db, repo);
	111	// An issue a planner or a reviewer holds is theirs, not a builder's.
	112	const planners = new Set(
	113	crew.filter((c) => c.role !== "builder").map((c) => c.agent.user.id),
	114	);
	115	const holdOf = (issue: Issue): HoldName \| null => {
	116	if (busyIssues.has(issue.id)) return "running";
	117	if (proposed.has(issue.number)) return "open_pull";
	118	if (issue.assigneeId !== null && planners.has(issue.assigneeId)) return "planner";
	119	if (stalled(app, repo, issue)) return "stalled";
	120	if (atRunCap(app, repo, issue)) return "run_cap";
	121	if (parkedCount(app.db, repo, issue.id) >= PARK_STRIKES) return "parked_twice";
	122	if (coveredByRedFix(app.db, repo.id, issue)) return "red_fix";
	123	if (isSettingFinding(app.db, issue.id)) return "setting";
	124	return null;
	125	};
	126	const by = Object.fromEntries(HOLDS.map((h) => [h, [] as Issue[]])) as Record<
	127	HoldName,
	128	Issue[]
	129	>;
	130	const startable: Ranked[] = [];
	131	for (const r of ready) {
	132	if (r.issue.id === repo.directionIssueId) continue;
	133	const hold = holdOf(r.issue);
	134	if (hold === null) startable.push(r);
	135	else by[hold].push(r.issue);
	136	}
	137	return { startable, by };
	138	}
	139
	140	/** The count per filter, in `HOLDS` order. */
	141	export function heldCounts(held: Held): Record<HoldName, number> {
	142	return Object.fromEntries(HOLDS.map((h) => [h, held.by[h].length])) as Record<
	143	HoldName,
	144	number
	145	>;
	146	}
	147
	148	/** The counts as the tick line says them: `open_pull=10 stalled=3`, the empty ones left out. */
	149	export function heldWords(held: Held): string {
	150	const said = HOLDS.filter((h) => held.by[h].length > 0).map(
	151	(h) => `${h}=${held.by[h].length}`,
	152	);
	153	return said.length === 0 ? "none" : said.join(" ");
	154	}
	155
	156	/** The held issues the planner can lift by re-planning them. */
	157	export function replannable(held: Held): Issue[] {
	158	return REPLANNABLE.flatMap((h) => held.by[h]);
	159	}
	160
	161	/** The ready list sorted now, from the map, the crew and the runs in flight. */
	162	export function heldNow(app: App, repo: Repo): Held {
	163	return heldBy(
	164	app,
	165	repo,
	166	readyNow(repoGraph(app.db, repo.id, { sealed: true })),
	167	listCrewRoles(app.db, repo.id),
	168	listActive(app.db, "agent").filter((r) => r.repoId === repo.id),
	169	);
	170	}
	171
	172	/**
	173	* What a planning pass is told when nothing ready can start: the counts,
	174	* and the stalled and capped issues to re-plan. Parked-twice ones reach it
	175	* as hand-overs already (`parks.ts`). Undefined when something can start
	176	* or nothing re-planning lifts holds the rest.
	177	*/
	178	export function stuckOf(held: Held): Stuck \| undefined {
	179	if (held.startable.length > 0) return undefined;
	180	const issues = (["stalled", "run_cap"] as const).flatMap((hold) =>
	181	held.by[hold].map((issue) => ({ number: issue.number, title: issue.title, hold })),
	182	);
	183	return issues.length === 0 ? undefined : { held: heldWords(held), issues };
	184	}
		@@ -108,6 +108,7 @@ import { clearStaleLocks, lockedOut } from "./locks.ts";
108	108	import { interruptedSummary } from "./interrupted.ts";
109	109	import { laterGate } from "./later.ts";
110	110	import { parkedTwice } from "./parks.ts";
	111	import { heldNow, stuckOf } from "./held.ts";
111	112	import { noteLimit } from "../core/standing.ts";
112	113	import { pauseReason } from "./pacing.ts";
113	114	import {
		@@ -913,11 +914,13 @@ async function work(
913	914	.get(issue.id, run.id, run.createdAt)!.n > 0,
914	915	}
915	916	: {}),
916		// A planning run is given what the crew handed over (`parks.ts`).
	917	// A planning run is given what the crew handed over (`parks.ts`),
	918	// and what holds the ready list when nothing on it can start (`held.ts`).
917	919	...(brief.role === "planner" && issue.id === repo.directionIssueId
918	920	? {
919	921	parkedTwice: [...parkedTwice(app.db, [repo]), ...handedOverPulls(app.db, repo)],
920	922	laterGate: laterGate(app.db, repo.id),
	923	stuck: stuckOf(heldNow(app, repo)),
921	924	}
922	925	: {}),
923	926	checkKind:
		@@ -0,0 +1,47 @@
	1	/**
	2	* Why ready issues cannot start, per autonomous repository (#2244): the
	3	* rows /flow draws as bars and the terminal's Flow dialog prints as lines —
	4	* `crew/held.ts`'s counts, the same the autonomy tick logs as `held=`.
	5	*
	6	* Sorting a ready list asks a few queries per issue, so the rows are kept
	7	* for a few seconds: a page reloaded, or the dialog opened beside it, reads
	8	* them once. The tick never reads this cache; it sorts afresh every time.
	9	*/
	10
	11	import type { App } from "../app.ts";
	12	import { listAutonomousRepos } from "../core/repos.ts";
	13	import { heldCounts, heldNow, type HoldName } from "../crew/held.ts";
	14
	15	export interface HeldRow {
	16	/** `owner/name`. */
	17	readonly repo: string;
	18	readonly public: boolean;
	19	readonly startable: number;
	20	readonly counts: Readonly<Record<HoldName, number>>;
	21	}
	22
	23	/** How long the rows are kept. */
	24	export const HELD_TTL_MS = 5_000;
	25
	26	const kept = new WeakMap<App, { at: number; rows: readonly HeldRow[] }>();
	27
	28	/** Each autonomous repository's ready list, sorted by what holds it; private ones for the owner only. */
	29	export function readHeld(app: App, owner: boolean, now = Date.now()): HeldRow[] {
	30	let entry = kept.get(app);
	31	if (entry === undefined \|\| now - entry.at >= HELD_TTL_MS \|\| now < entry.at) {
	32	entry = {
	33	at: now,
	34	rows: listAutonomousRepos(app.db).map((repo) => {
	35	const held = heldNow(app, repo);
		junipercrew 29d ago The first uncached read sorts every autonomous repository on the request path, about 19 ms measured. A page reload after the 5 s TTL pays it, and so does a stampede of readers. Fine for now. If the repository count grows, refresh the rows from the tick instead.
	36	return {
	37	repo: `${repo.ownerName}/${repo.name}`,
	38	public: repo.visibility === "public",
	39	startable: held.startable.length,
	40	counts: heldCounts(held),
	41	};
	42	}),
	43	};
	44	kept.set(app, entry);
	45	}
	46	return entry.rows.filter((r) => owner \|\| r.public);
	47	}
		@@ -53,6 +53,7 @@ import { domainsScreen } from "./screens/domains.ts";
53	53	import { ownerScreen } from "./screens/owner.ts";
54	54	import { resilienceLines, resilienceScreen } from "./screens/resilience.ts";
55	55	import { flowLines, flowScreen } from "./screens/flow.ts";
	56	import { readHeld } from "../flow/held.ts";
56	57	import { memoryScreen, systemLines, systemScreen } from "./screens/system.ts";
57	58	import { grantable, READS_KEPT, recentReads } from "../core/telemetry.ts";
58	59	import { noteRead, setTelemetryGrant, telemetryReader } from "../actions/telemetry.ts";
		@@ -267,6 +268,7 @@ export function forgeCommands(session: Session): (ctx: Ctx) => Command[] {
267	268	new Date(),
268	269	systemFor(session.app, flowReader).duplicates,
269	270	flowReader.kind === "agent" ? { queues: queuesFor(session.app, flowReader) } : undefined,
	271	readHeld(session.app, flowReader.kind === "owner"),
270	272	)));
271	273	},
272	274	});
		@@ -6,11 +6,15 @@
6	6	* MCP `flow` tool read. Under them, each repository's merge queue (#2036):
7	7	* queued, gating, landed in the last hour (`flow/queue.ts`); then the
8	8	* conflicted pulls, and the pulls with changes requested waiting on a
9		* builder and on a reviewer (`flow/requested.ts`, #2172). Read-only;
10		* Enter, Esc or q closes it.
	9	* builder and on a reviewer (`flow/requested.ts`, #2172); then each
	10	* autonomous repository's ready list, startable beside the count per
	11	* filter that holds the rest (`flow/held.ts`, #2244), as /flow draws it.
	12	* Read-only; Enter, Esc or q closes it.
11	13	*/
12	14
13	15	import type { Database } from "bun:sqlite";
	16	import { HOLDS } from "../../crew/held.ts";
	17	import type { HeldRow } from "../../flow/held.ts";
14	18	import { conflictedPulls, conflictedSays } from "../../flow/conflicted.ts";
15	19	import { readPipeline, STAGE_LABEL, verdict } from "../../flow/pipeline.ts";
16	20	import { readQueues } from "../../flow/queue.ts";
		@@ -31,7 +35,9 @@ export function flowLines(
31	35	now = new Date(),
32	36	dups = live().read().duplicates,
33	37	/** What an agent reader may see: its queue lines, conflicted pulls and changes-requested waits come already cut to public. */
34		agent?: { queues: ReturnType<typeof readQueues> },
	38	agent?: { queues: ReturnType<typeof readQueues> } \| undefined,
	39	/** Why ready issues wait, per autonomous repository (`readHeld`, already cut to what the reader may see). */
	40	held?: readonly HeldRow[],
35	41	): string[] {
36	42	const stages = readPipeline(db, now);
37	43	const flow = readThroughput(db, stages.map((s) => s.key), now);
		@@ -63,11 +69,30 @@ export function flowLines(
63	69	)),
64	70	...(conflicted === null ? [] : ["", ...wrap(conflicted, inner)]),
65	71	...waits,
	72	...(held === undefined ? [] : ["", ...heldLines(held, inner)]),
66	73	"",
67	74	...duplicateLines(dups, inner),
68	75	];
69	76	}
70	77
	78	/** One line per autonomous repository: its name, then `startable=N` and each filter holding any. */
	79	export function heldLines(rows: readonly HeldRow[], inner: number): string[] {
	80	if (rows.length === 0) return ["Ready, and why it waits: no repository runs on its own."];
	81	return [
	82	"Ready, and why it waits:",
	83	...rows.flatMap((r) =>
	84	wrap(
	85	[
	86	r.repo,
	87	`startable=${r.startable}`,
	88	...HOLDS.filter((h) => r.counts[h] > 0).map((h) => `${h}=${r.counts[h]}`),
	89	].join(" "),
	90	inner,
	91	),
	92	),
	93	];
	94	}
	95
71	96	export function flowScreen(ctx: Ctx, lines: readonly string[]): Screen {
72	97	return {
73	98	title: "Flow",
		@@ -21,6 +21,11 @@
21	21	* Beside the conflicted pulls, the pulls with changes requested (#2172):
22	22	* those waiting on a builder apart from those waiting on a reviewer, by
23	23	* age — `flow/requested.ts`'s, the rows the tick moves.
	24	*
	25	* Under the pipeline, why ready issues cannot start (#2244): per autonomous
	26	* repository, its ready list as one bar, startable beside each filter that
	27	* holds the rest — `flow/held.ts`'s rows, the same the tick line says and
	28	* the terminal's Flow command prints.
24	29	*/
25	30
26	31	import { noteRead, telemetryReader } from "../../actions/telemetry.ts";
		@@ -47,6 +52,8 @@ import {
47	52	type StageThroughput,
48	53	} from "../../flow/throughput.ts";
49	54	import { readQueues, type QueueRow } from "../../flow/queue.ts";
	55	import { HOLDS } from "../../crew/held.ts";
	56	import { readHeld, type HeldRow } from "../../flow/held.ts";
50	57	import type { Ctx } from "../../http/context.ts";
51	58	import { live } from "../../system/live.ts";
52	59	import { notFoundPage, signInFirst } from "../chrome.ts";
		@@ -59,6 +66,18 @@ const css = /* css */ `
59	66	.flow-out svg { width: 72px; height: 16px; }
60	67	.flow-bar { fill: var(--muted-fg); }
61	68	.flow-bar[data-empty] { fill: var(--muted); }
	69	.held-bar { width: 100%; height: 12px; display: block; }
	70	.held-key { display: inline-flex; align-items: center; gap: 4px; margin-right: 12px; font-variant-numeric: tabular-nums; }
	71	.held-key svg { width: 10px; height: 10px; }
	72	.held-startable { fill: var(--success); }
	73	.held-running { fill: var(--accent); }
	74	.held-open_pull { fill: var(--merged); }
	75	.held-planner { fill: var(--primary); }
	76	.held-stalled { fill: var(--attn); }
	77	.held-run_cap { fill: var(--danger); }
	78	.held-parked_twice { fill: var(--del-fg); }
	79	.held-red_fix { fill: var(--muted-fg); }
	80	.held-setting { fill: var(--border-strong); }
62	81	`;
63	82
64	83	/** What `?out=` and `?hour=` ask to list, checked: an unknown stage or hour lists nothing. */
		@@ -193,11 +212,65 @@ export function flowPage(ctx: Ctx): Response {
193	212	</div>`,
194	213	{ pad: false },
195	214	)}
	215	${heldCard(readHeld(ctx.app, reader.kind === "owner", now))}
196	216	${queueCard(queuesFor(ctx.app, reader, new Date(now)))}
197	217	${listed === null \|\| shown === undefined ? null : outList(shown, listed.hour, now)}`;
198	218	return page({ ctx, title: "Flow", body, styleCss: css });
199	219	}
200	220
	221	/** One segment per kind, as wide as its share: a picture only; the counts beside it are the words. */
	222	function heldBar(row: HeldRow): Html {
	223	const parts: [string, number][] = [
	224	["startable", row.startable],
	225	...HOLDS.map((h): [string, number] => [h, row.counts[h]]),
		junipercrew 29d ago outdated heldNow is computed per request for every autonomous repo, with per-issue queries. Cache it briefly or measure it. The same rows must also reach the terminal Flow screen.
	226	];
	227	const total = parts.reduce((n, [, c]) => n + c, 0);
	228	let x = 0;
	229	const rects = parts
	230	.filter(([, c]) => c > 0)
	231	.map(([kind, c]) => {
	232	const w = (c / total) * 100;
	233	const rect = html`<rect class="held-${kind}" x="${x.toFixed(2)}" y="0" width="${w.toFixed(2)}" height="12" />`;
	234	x += w;
	235	return rect;
	236	});
	237	return html`<svg class="held-bar" viewBox="0 0 100 12" preserveAspectRatio="none" aria-hidden="true" focusable="false">${rects}</svg>`;
	238	}
	239
	240	function heldKey(kind: string, n: number): Html {
	241	return html`<span class="held-key small" data-held="${kind}">
	242	<svg viewBox="0 0 10 10" aria-hidden="true" focusable="false"><rect class="held-${kind}" width="10" height="10" /></svg>
	243	<span class="mono">${kind}=${String(n)}</span>
	244	</span>`;
	245	}
	246
	247	/** Why ready issues cannot start, per autonomous repository (#2244). */
	248	function heldCard(rows: readonly HeldRow[]): Html {
	249	return card(
	250	html`<h2>Ready, and why it waits</h2>
	251	<p class="muted small">
	252	Each ready issue a builder could start, or the first filter that holds
	253	it: a run on it, an open pull, the planner, stalled, its run cap,
	254	parked twice, a red-main fix, a setting's finding. When nothing can
	255	start and builders are free, the planner is asked to re-plan what is
	256	stalled or capped.
	257	</p>
	258	${rows.length === 0
	259	? html`<p class="muted">No repository runs on its own.</p>`
	260	: rows.map(
	261	(r) => html`<div data-held-repo="${r.repo}">
	262	<p><a href="/${r.repo}/map">${r.repo}</a></p>
	263	${heldBar(r)}
	264	<p>
	265	${heldKey("startable", r.startable)}
	266	${HOLDS.filter((h) => r.counts[h] > 0).map((h) => heldKey(h, r.counts[h]))}
	267	</p>
	268	</div>`,
	269	)}`,
	270	{ id: "held" },
	271	);
	272	}
	273
201	274	/** The merge queue, one row per repository with something in it or landed. */
202	275	function queueCard(rows: readonly QueueRow[]): Html {
203	276	return card(