b35e100 · fa2ece1 · 7da6393 · 0399f05 · fa08e51 · df476e4
@@ -359,6 +359,7 @@
This page is the front door. Everything else is a file of its own under
- [`docs/WEBSPEC-PREVIEWS.md`](docs/WEBSPEC-PREVIEWS.md) — the website specification run over every preview, report-only.
- [`docs/CREW.md`](docs/CREW.md) — the crew: agents, how a run works, review, live triage, the merge queue, spend, roles and invites, the sandbox, passports, and the direction a vision pull will write.
- [`docs/SENTINEL.md`](docs/SENTINEL.md) — the forge hunting its own faults; [`docs/HUNT.md`](docs/HUNT.md) is the bug hunters' detectors against one running app (`bun scripts/hunt.ts <origin>`).
- Flow only: a repository's admin (a person, never an agent) sets one switch from Settings → On its own, `PATCH /api/v1/repos/:owner/:name` with `flowOnly`, MCP `repo_settings`, or `w` on the terminal's About card (`I`); turning it on makes the `flow` label. Nothing obeys it yet.
- [`docs/FLOW.md`](docs/FLOW.md) — where every issue stands: `GET /api/v1/repos/:owner/:name/flow` returns each open issue's stage, since, stalled and unblock, plus what went live in the last 24 h.
- Flow reads: `bun scripts/flow-report.ts [--db <path>] [--public] [--json]` prints one line per read; see [`docs/FLOW.md`](docs/FLOW.md).
- Under it, the panel says the crew's build yield over 24 h (runs finished, pushed, landed; `src/flow/build_yield.ts`) and the median hours to first review (`src/flow/review_latency.ts`); the terminal Flow dialog carries both in the same words (an agent reader there sees public repositories alone). `/boards` is for admins alone (anyone else gets not-found), so the page shows all repositories.
@@ -122,7 +122,7 @@
for a tunnel and a forge that sleeps.
| `releases` | `{}`: the forge's kept releases newest first: short sha, version, the pull that landed it, when, and for the live one `live: true` and `since`; for whoever may read /releases, others get its refusal; no rollback, a person does that on the page |  |
| `repo` | `{ repo }`: one repository's description, visibility, autonomy, `audience { level, sentence }` and `provenance` (where a migrated one came from, `null` when hidden), the same as `GET /api/v1/repos/:owner/:name` |  |
| `repo_labels` | `{ repo, action?, name?, color?, id? }`: list (`list`, the default; a read-only token may), create (`create`, `name`, `color` six hex digits) or remove (`remove`, `id`) the repository's labels, as `GET`/`POST …/labels` and `DELETE …/labels/:id`; create and remove need an admin token and a repository admin | yes |
| `repo_settings` | `{ repo, description?, visibility? }` (admin): change a repository's description and visibility as `PATCH /api/v1/repos/:owner/:name` does, for the same callers (a repository admin); answers `{ repo, description, visibility }`; a visibility other than public or private is `invalid` | yes |
| `repo_settings` | `{ repo, description?, visibility?, flowOnly? }` (admin): change a repository's description, visibility and FLOW ONLY switch as `PATCH /api/v1/repos/:owner/:name` does, for the same callers (a repository admin); answers `{ repo, description, visibility, flowOnly }` (with none to change it only reads); a visibility other than public or private is `invalid` | yes |
| `reports` | `{ repo, id?, action? }`: the waiting reports from outsiders, each `from: "outside"` (their words are unchecked); with `id` and `action` (`accept` opens it as an issue marked as from outside, `dismiss` closes it). A person who writes the repository only; needs an `rw` token | yes |
| `restore_drill` | no input: restore the newest snapshot as a drill and answer `{ verdict, failedStep?, says }`, worded as the Backups page's button; no store, a failure or a red drill is an answer, not an error; a forge admin's, with an admin token | yes |
| `returns` | `{ repo?, days? }`: what the crew's tokens bought over the last `days` (1–90, default 7): dollars, runs, changes landed, cost per change; `repo` narrows it to one app of yours |  |
@@ -123,6 +123,10 @@
- **The crew** — agents as accounts with nothing but a run-scoped token,
  working issues in the background with Claude Code and proposing through
  pulls a person merges.
- **Flow only** — a repository's admin (a person, never an agent) sets one
  switch from Settings, `PATCH /api/v1/repos/:owner/:name` or MCP
  `repo_settings`, or the terminal's About card (`w`); it makes the `flow`
  label. Nothing obeys it yet.
      
        sentinelcrew
        17d ago
        outdated
      
      Both doors: the terminal is a door like the page, and it already sets repository settings (src/tui/screens/about.ts, archive). Give Flow only a row and an admin-only toggle there, then drop this clause.
    
Pages render without a line of JavaScript and are designed thumb-first. Six
premade themes (from warm paper to polar night) switch instantly and persist in
@@ -18,6 +18,7 @@
import { storageChanged, storageRefusal, storageSentence } from "../core/storage
import {
  createLabel as insertLabel,
  deleteLabel as removeLabel,
  getLabel,
  updateLabel as writeLabel,
  type Label,
} from "../core/issues.ts";
@@ -333,6 +334,9 @@
function moveArchive(app: App, repoId: string, archived: boolean): Promise<boole
  });
}
/** The label FLOW ONLY puts in a repository. */
const FLOW_LABEL = "flow";
/**
 * Change settings. A new default branch must exist; git HEAD is moved first
 * and the row follows (git is truth, the index is derived from it).
@@ -352,6 +356,7 @@
export async function updateRepoSettings(
    (settings.crewOutsiders !== undefined ||
      settings.decisionsBy !== undefined ||
      settings.plansNeedNod !== undefined ||
      settings.flowOnly !== undefined ||
      settings.archived !== undefined) &&
    admin.value.kind === "agent"
  )
@@ -370,10 +375,15 @@
export async function updateRepoSettings(
  }
  const { archived, ...rest } = settings;
  writeSettings(app.db, repo, rest);
  // FLOW ONLY names its label (the label it makes is not in `changed`, below): on, the repository has a `flow` to put on work.
  if (settings.flowOnly === true && getLabel(app.db, repo.id, FLOW_LABEL) === undefined)
      
        sentinelcrew
        17d ago
        
      
      This calls the core insertLabel directly, so the label is created with no event of its own on the bus. A labels list someone already has open will not show flow until they reload. If actions/repos.ts (or the labels module) has a label-create action that emits an event, use that here, or say in the comment that skipping the event is deliberate.
    
    insertLabel(app.db, repo.id, FLOW_LABEL, "d29922");
      
        sentinelcrew
        17d ago
        
      
      Fine: it's idempotent and the test pins a single label. The terminal toggle should reach this same function, so the label follows from every door.
    
  const moved =
    archived === undefined ? false : await moveArchive(app, repo.id, archived);
  const updated = getRepoById(app.db, repo.id);
  if (updated === undefined) return err("not_found");
  // `changed` is the audit line: it names settings, not the `flow` label
  // that turning flowOnly on may have made.
  const changed: string[] = (
    [
      "visibility",
@@ -385,6 +395,7 @@
export async function updateRepoSettings(
      "crewOutsiders",
      "decisionsBy",
      "plansNeedNod",
      "flowOnly",
    ] as const
  ).filter((k) => settings[k] !== undefined && settings[k] !== repo[k]);
  if (moved) changed.push("archived");
@@ -19,10 +19,12 @@
export const route: Route = {
    crewOutsiders: "boolean",
    decisionsBy: "string",
    plansNeedNod: "boolean",
    flowOnly: "boolean",
  },
  refusals: {
    bad_archived: "422: archived is true or false",
    bad_decisions_by: "422: decisionsBy is me, decider or decider_tell",
    bad_flow_only: "422: flowOnly is true or false",
    bad_plans_need_nod: "422: plansNeedNod is true or false",
    bad_show_provenance: "422: showProvenance is true or false",
    no_provenance: `422: ${FAMILY_WORDS.no_provenance}`,
@@ -0,0 +1,1 @@
76c51289fbefaf8b3f8325328548a34f6e6fab8e6a55a64fac1d4224178d11a5
@@ -0,0 +1,5 @@
// A repository can be FLOW ONLY (#6392): one switch its admin sets. Nothing
// obeys it yet; dispatch reads it in a later change.
export default `
  ALTER TABLE repo ADD COLUMN flow_only INTEGER NOT NULL DEFAULT 0;
  `;
@@ -121,6 +121,8 @@
export interface Repo {
  readonly decisionsBy: DecisionsBy;
  /** "Plans need a nod": a plan is stored as a proposal, not opened. */
  readonly plansNeedNod: boolean;
  /** FLOW ONLY: an admin's switch; nothing obeys it yet. */
  readonly flowOnly: boolean;
  /** The issue the planner is given, when the map has run dry. */
  readonly directionIssueId: string | null;
  /** The repo this was forked from, or null. */
@@ -169,6 +171,7 @@
interface RepoRow {
  crew_outsiders: number;
  decisions_by: string;
  plans_need_nod: number;
  flow_only: number;
  direction_issue_id: string | null;
  fork_parent_id: string | null;
  sealed_for: string | null;
@@ -209,6 +212,7 @@
function toRepo(row: RepoRow): Repo {
    crewOutsiders: row.crew_outsiders === 1,
    decisionsBy: isDecisionsBy(row.decisions_by) ? row.decisions_by : "me",
    plansNeedNod: row.plans_need_nod === 1,
    flowOnly: row.flow_only === 1,
    directionIssueId: row.direction_issue_id,
    forkParentId: row.fork_parent_id,
    sealedFor: row.sealed_for,
@@ -1155,6 +1159,7 @@
export interface RepoSettings {
  /** Archive (true) or wake (false); the time is stamped here. */
  archived?: boolean;
  plansNeedNod?: boolean;
  flowOnly?: boolean;
}
/** The repositories still awake: what Yours lists before anyone types a filter. */
@@ -1178,7 +1183,7 @@
export function updateRepoSettings(
       default_branch = ?4, require_review = ?5, require_checks = ?7,
       autonomy = ?8, autonomy_direction = ?9, autonomy_ceiling_usd = ?10,
       autonomy_slots = ?11, autonomy_by = ?12, crew_outsiders = ?13, decisions_by = ?14,
       plans_need_nod = ?15
       plans_need_nod = ?15, flow_only = ?16
     WHERE id = ?6`,
  ).run(
    settings.visibility ?? repo.visibility,
@@ -1196,6 +1201,7 @@
export function updateRepoSettings(
    (settings.crewOutsiders ?? repo.crewOutsiders) ? 1 : 0,
    settings.decisionsBy ?? repo.decisionsBy,
    (settings.plansNeedNod ?? repo.plansNeedNod) ? 1 : 0,
    (settings.flowOnly ?? repo.flowOnly) ? 1 : 0,
  );
  forgetListings(db);
  return getRepoById(db, repo.id)!;
@@ -2509,6 +2509,8 @@
export function apiRoutes(router: Router<Handler>): void {
      );
    if (input.plansNeedNod !== undefined && typeof input.plansNeedNod !== "boolean")
      return apiError("bad_plans_need_nod", 422, "plansNeedNod is true or false");
    if (input.flowOnly !== undefined && typeof input.flowOnly !== "boolean")
      return apiError("bad_flow_only", 422, "flowOnly is true or false");
    if (input.showProvenance !== undefined) {
      if (typeof input.showProvenance !== "boolean")
        return apiError("bad_show_provenance", 422, "showProvenance is true or false");
@@ -2556,6 +2558,8 @@
export function apiRoutes(router: Router<Handler>): void {
      ...(typeof input.plansNeedNod === "boolean"
        ? { plansNeedNod: input.plansNeedNod }
        : {}),
      // FLOW ONLY: an admin's switch, never an agent's.
      ...(typeof input.flowOnly === "boolean" ? { flowOnly: input.flowOnly } : {}),
    });
    if (!updated.ok) return respondAccess(updated.error, 422);
    // "Show where this came from" (#3293): an admin's, never an agent's.
@@ -4,15 +4,16 @@
import { VISIBILITY_WORDS } from "../../../core/arg_words.ts";
export const tool: Tool = {
  name: "repo_settings",
  doc: "`{ repo, description?, visibility? }` (admin): change a repository's description and visibility as `PATCH /api/v1/repos/:owner/:name` does, for the same callers (a repository admin); answers `{ repo, description, visibility }`; a visibility other than public or private is `invalid`",
  doc: "`{ repo, description?, visibility?, flowOnly? }` (admin): change a repository's description, visibility and FLOW ONLY switch as `PATCH /api/v1/repos/:owner/:name` does, for the same callers (a repository admin); answers `{ repo, description, visibility, flowOnly }` (with none to change it only reads); a visibility other than public or private is `invalid`",
  description:
    "Change a repo's description or visibility: PATCH /api/v1/repos/:owner/:name (admin).",
    "Read or change a repo's description, visibility or flowOnly: PATCH /api/v1/repos/:owner/:name (admin).",
  inputSchema: {
    type: "object",
    properties: {
      repo: REPO_ARG,
      description: { type: "string", maxLength: 2000 },
      visibility: { type: "string", enum: ["public", "private"] },
      flowOnly: { type: "boolean" },
    },
    required: ["repo"],
  },
@@ -21,7 +22,9 @@
export const tool: Tool = {
  async run(ctx, user, args) {
    const repo = repoArg(ctx, user, args);
    if (isAnswer(repo)) return repo;
    const { description, visibility } = args;
    const { description, visibility, flowOnly } = args;
    if (flowOnly !== undefined && typeof flowOnly !== "boolean")
      return bad("invalid", "flowOnly is true or false");
    if (description !== undefined && typeof description !== "string")
      return bad("invalid", "description is text");
    if (visibility !== undefined && visibility !== "public" && visibility !== "private")
@@ -29,6 +32,7 @@
export const tool: Tool = {
    const updated = await updateRepoSettings(ctx.app, user, repo, {
      ...(visibility !== undefined ? { visibility } : {}),
      ...(description !== undefined ? { description } : {}),
      ...(flowOnly !== undefined ? { flowOnly } : {}),
    });
    if (!updated.ok)
      return bad(updated.error === "not_found" ? "not_found" : "forbidden", updated.error);
@@ -36,6 +40,7 @@
export const tool: Tool = {
      repo: `${updated.value.ownerName}/${updated.value.name}`,
      description: updated.value.description,
      visibility: updated.value.visibility,
      flowOnly: updated.value.flowOnly,
    });
  },
};
@@ -375,6 +375,7 @@
import {
  autonomySettingsUpdate,
  settingsPage,
  settingsUpdate,
  flowOnlyUpdate,
  waveCut,
  archiveSubmit,
  provenanceSubmit,
@@ -1444,6 +1445,7 @@
export function buildRouter(): Router<Handler> {
  );
  router.add("GET", "/:owner/:name/settings/autonomy", autonomySettingsPage);
  router.add("POST", "/:owner/:name/settings/autonomy", autonomySettingsUpdate);
  router.add("POST", "/:owner/:name/settings/flow-only", flowOnlyUpdate);
  router.add("POST", "/:owner/:name/settings/holds", fileHoldUpdate);
  router.add("POST", "/:owner/:name/settings/upstream", followUpstreamUpdate);
  router.add("POST", "/:owner/:name/settings/upstream/check", followUpstreamCheck);
@@ -89,6 +89,8 @@
export function aboutScreen(
    f.user?.kind !== "agent" &&
    repo !== undefined &&
    getProvenance(f.db, repo.id) !== undefined;
  // FLOW ONLY is a person's, an admin's: the settings page's gate.
  const mayFlow = (): boolean => may() && f.user?.kind !== "agent";
  // The following card's rule: an admin's, and only while it is on or to be turned on.
  const mayFollow = (): boolean =>
    may() && repo !== undefined && repo.origin === null;
@@ -96,6 +98,7 @@
export function aboutScreen(
    repo !== undefined && followShown(f.app, repo, f.user)?.enabled === true;
  const factRows = (): [string, string][] => [
    ...archivedRow(repo),
    ...flowRow(repo),
    ...aboutFacts(f, src, facts, ref),
    ...trailRows(f, repo),
    ...upstreamRows(f, repo),
@@ -154,6 +157,9 @@
export function aboutScreen(
              ),
            ]
          : []),
        ...(mayFlow()
          ? [binding(["w"], repo?.flowOnly === true ? "flow only off" : "flow only on")]
          : []),
        ...(mayTrail()
          ? [
              binding(
@@ -298,6 +304,18 @@
export function aboutScreen(
        });
        return true;
      }
      if (e.key === "w" && repo !== undefined && mayFlow()) {
        const on = !repo.flowOnly;
        void updateRepoSettings(f.app, f.user, repo, { flowOnly: on }).then((done) => {
          if (done.ok) {
            repo = getRepoById(f.db, done.value.id) ?? done.value;
            rows = factRows();
            ctx.toast(on ? "flow only is on" : "flow only is off", "success");
          } else ctx.toast("that could not be changed", "danger");
          ctx.invalidate();
        });
        return true;
      }
      if (e.key === "t" && repo !== undefined && mayTrail()) {
        const shown = getProvenance(f.db, repo.id)?.shown === true;
        const done = showProvenance(f.app, f.user, repo, !shown);
@@ -417,6 +435,12 @@
export function upstreamRows(
  ];
}
/** The FLOW ONLY switch, in the settings page's words; every reader sees it. */
export function flowRow(repo: Repo | undefined): [string, string][] {
  if (repo === undefined) return [];
  return [["Flow only", repo.flowOnly ? "on" : "off"]];
}
/** One line when an admin has put the repository away. */
function archivedRow(repo: Repo | undefined): [string, string][] {
  if (repo === undefined || repo.archivedAt === null) return [];
@@ -1446,6 +1446,28 @@
export function autonomySettingsPage(ctx: Ctx): Response {
  return redirect(`${repoBase(repo)}/settings#autonomy`);
}
// POST /:owner/:name/settings/flow-only — the one switch; the state asked
// for travels in the form, so a double submit is idempotent.
export async function flowOnlyUpdate(ctx: Ctx): Promise<Response> {
  const gate = await adminForm(ctx);
  if (gate instanceof Response) return gate;
  const { repo, form } = gate;
  const asked = field(form, "flowOnly");
  const back = `${repoBase(repo)}/settings#autonomy`;
  if (asked !== "0" && asked !== "1")
    return flashTo(ctx, back, { tone: "danger", message: NOT_CHANGED });
  const updated = await updateRepoSettings(ctx.app, ctx.auth.user, repo, {
    flowOnly: asked === "1",
  });
  return flashTo(
    ctx,
    back,
    updated.ok
      ? { message: asked === "1" ? "Flow only is on." : "Flow only is off." }
      : { tone: "danger", message: "Those settings could not be saved." },
  );
}
// POST /:owner/:name/settings/autonomy
export async function autonomySettingsUpdate(ctx: Ctx): Promise<Response> {
  const gate = await adminForm(ctx);
@@ -373,7 +373,17 @@
${repo.autonomyDirection}</textarea
          crew under Crew to have them reviewed and land on their own.
        </p>`
      : null;
  return card(html`${state}${noReviewer}${form}`, {
  const flowOnly = !admin
    ? null
    : html`<form method="post" action="${base}/settings/flow-only" id="flow-only">
      
        sentinelcrew
        17d ago
        
      
      The page door is right: it posts a <button> to a same-origin form, works with JavaScript off, and the wanted state rides a hidden field. Mirror it in the terminal: the same words (Flow only: on/off) and the same gate (admin and a person).
    
        <input type="hidden" name="flowOnly" value="${repo.flowOnly ? "0" : "1"}" />
      
        sentinelcrew
        17d ago
        
      
      Copy: "the direction is to finish what is open, not start features" reads as if the switch already enforces something, but nothing obeys it yet (the README and STATUS say so). Until dispatch reads it, consider adding "(nothing enforces it yet)". Separately, the terminal's About row shows the switch to every reader while this page shows it to admins only. Pick one rule when dispatch lands.
    
        <p class="small">
          <b>Flow only:</b> ${repo.flowOnly ? "on" : "off"} — the direction is
          to finish what is open, not start features.
          ${btn(repo.flowOnly ? "Turn off" : "Turn on", { size: "sm" })}
        </p>
      </form>`;
  return card(html`${state}${noReviewer}${form}${flowOnly}`, {
    id: "autonomy",
    head: html`${icon("play")}
      <h2>On its own</h2>`,
@@ -0,0 +1,200 @@
/**
 * A repository's FLOW ONLY switch (#6392): one setting its admin reads and
 * sets from Settings, the API and the MCP. A writer who is not admin is
 * refused at every door; turning it on makes the `flow` label. Nothing obeys
 * it yet.
 */
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 { listLabels } from "../src/core/issues.ts";
import { addToCrew, createAgent } from "../src/actions/crew.ts";
import type { Agent } from "../src/core/agents.ts";
import { addTeamMember, createOrg, createTeam, listTeams, OWNERS_TEAM } from "../src/core/orgs.ts";
import { createRepo, getRepoById, type Repo } from "../src/core/repos.ts";
import { createSession } from "../src/core/sessions.ts";
import { createToken } from "../src/core/tokens.ts";
import { createUser, type User } from "../src/core/users.ts";
import { serve, type Servers } from "../src/http/server.ts";
import { quietLogs } from "./helpers/globals.ts";
quietLogs();
let dataDir: string;
let app: App;
let servers: Servers;
let founder: User;
let dev: User;
let repo: Repo;
let bot: Agent;
const token: Record<string, string> = {};
const ok = <T>(r: { ok: true; value: T } | { ok: false; error: unknown }): T => {
  if (!r.ok) throw new Error(JSON.stringify(r.error));
  return r.value;
};
const flowOnly = (): boolean => getRepoById(app.db, repo.id)!.flowOnly;
const hasLabel = (): boolean =>
  listLabels(app.db, repo.id).some((l) => l.name === "flow");
const patch = (who: string, body: unknown) =>
  fetch(`${servers.url}/api/v1/repos/acme/svc`, {
    method: "PATCH",
    headers: { authorization: `Bearer ${token[who]}`, "content-type": "application/json" },
    body: JSON.stringify(body),
  });
async function mcp(who: string, args: unknown): Promise<{ error?: string; value?: any }> {
  const res = await fetch(`${servers.url}/mcp`, {
    method: "POST",
    headers: {
      "content-type": "application/json",
      accept: "application/json, text/event-stream",
      authorization: `Bearer ${token[who]}`,
    },
    body: JSON.stringify({
      jsonrpc: "2.0",
      id: 1,
      method: "tools/call",
      params: { name: "repo_settings", 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 web = (who: User, value: string, headers: Record<string, string> = {}) =>
  fetch(`${servers.url}/acme/svc/settings/flow-only`, {
    method: "POST",
    headers: {
      cookie: `forge_session=${createSession(app.db, who.id).token}`,
      "content-type": "application/x-www-form-urlencoded",
      ...headers,
    },
    body: new URLSearchParams({ flowOnly: value }),
    redirect: "manual",
  });
beforeAll(async () => {
  dataDir = await mkdtemp(join(tmpdir(), "forge-flow-only-"));
  app = createApp({ dataDir, port: 0 });
  servers = await serve(app);
  const make = async (username: string) =>
    ok(
      await createUser(app.db, {
        origin: "seed",
        trusted: true,
        username,
        email: `${username}@forge.local`,
        password: "a-good-passphrase",
        adminIfFirst: true,
      }),
    );
  founder = await make("founder");
  dev = await make("dev");
  const org = ok(createOrg(app.db, "acme", founder.id));
  const writers = ok(createTeam(app.db, org.id, "Writers", "write"));
  addTeamMember(app.db, writers, dev.id);
  repo = ok(
    await createRepo(app.db, app.reposRoot, { ownerId: org.id, name: "svc", visibility: "public" }),
  );
  bot = ok(await createAgent(app, founder, { username: "bot" }));
  expect(addToCrew(app, founder, repo, "bot").ok).toBe(true);
  // The hardest agent to refuse: on the team that administers the repository.
  const owners = listTeams(app.db, org.id).find((t) => t.name === OWNERS_TEAM)!;
  addTeamMember(app.db, owners, bot.user.id);
  for (const u of [founder, dev, bot.user]) token[u.username] = createToken(app.db, u.id, "admin", "admin").token;
}, 30_000);
afterAll(async () => {
  servers?.stop();
  app?.close();
  await rm(dataDir, { recursive: true, force: true });
});
describe("FLOW ONLY", () => {
  test("it starts off, and the API says so", async () => {
    expect(flowOnly()).toBe(false);
    const res = await fetch(`${servers.url}/api/v1/repos/acme/svc`);
    expect(((await res.json()) as { flowOnly: boolean }).flowOnly).toBe(false);
  });
  test("a writer who is not admin is refused at every door", async () => {
    expect((await patch("dev", { flowOnly: true })).status).toBe(404);
    expect((await mcp("dev", { repo: "acme/svc", flowOnly: true })).error).toBeDefined();
    const refused = await web(dev, "1");
    expect(refused.status).toBe(404);
    expect(flowOnly()).toBe(false);
    expect(hasLabel()).toBe(false);
  });
  test("an agent that administers the repository cannot switch it, on or off", async () => {
    expect((await patch("bot", { flowOnly: true })).status).toBe(404);
    expect((await mcp("bot", { repo: "acme/svc", flowOnly: true })).error).toBeDefined();
    expect(flowOnly()).toBe(false);
    await patch("founder", { flowOnly: true });
    expect((await patch("bot", { flowOnly: false })).status).toBe(404);
    expect((await mcp("bot", { repo: "acme/svc", flowOnly: false })).error).toBeDefined();
    expect(flowOnly()).toBe(true);
    await patch("founder", { flowOnly: false });
  });
  test("Settings draws the form for an admin only, not a writer or a guest", async () => {
    const seen = async (headers: Record<string, string>) =>
      (await fetch(`${servers.url}/acme/svc/settings`, { headers })).text();
    const asDev = `forge_session=${createSession(app.db, dev.id).token}`;
    expect(await seen({ cookie: asDev })).not.toContain('id="flow-only"');
    expect(await seen({})).not.toContain('id="flow-only"');
    const asFounder = `forge_session=${createSession(app.db, founder.id).token}`;
    expect(await seen({ cookie: asFounder })).toContain('id="flow-only"');
  });
  test("the API's admin turns it on, with its label, and off", async () => {
    const on = await patch("founder", { flowOnly: true });
    expect(on.status).toBe(200);
    expect(((await on.json()) as { flowOnly: boolean }).flowOnly).toBe(true);
    expect(flowOnly()).toBe(true);
    expect(hasLabel()).toBe(true);
    expect((await patch("founder", { flowOnly: false })).status).toBe(200);
    expect(flowOnly()).toBe(false);
    // Turning it on again does not make a second label.
    await patch("founder", { flowOnly: true });
    expect(listLabels(app.db, repo.id).filter((l) => l.name === "flow").length).toBe(1);
    await patch("founder", { flowOnly: false });
  });
  test("a non-boolean is a 422 and nothing changes", async () => {
    expect((await patch("founder", { flowOnly: "yes" })).status).toBe(422);
    expect(flowOnly()).toBe(false);
  });
  test("the MCP's admin reads, turns it on and off", async () => {
    expect((await mcp("founder", { repo: "acme/svc" })).value.flowOnly).toBe(false);
    expect((await mcp("founder", { repo: "acme/svc", flowOnly: true })).value.flowOnly).toBe(true);
    expect(flowOnly()).toBe(true);
    expect((await mcp("founder", { repo: "acme/svc", flowOnly: false })).value.flowOnly).toBe(false);
    expect(flowOnly()).toBe(false);
    expect((await mcp("founder", { repo: "acme/svc", flowOnly: "no" })).error).toBeDefined();
  });
  test("Settings shows it to the admin, and its form turns it on and off", async () => {
    const cookie = `forge_session=${createSession(app.db, founder.id).token}`;
    const page = await (await fetch(`${servers.url}/acme/svc/settings`, { headers: { cookie } })).text();
    expect(page).toContain("Flow only:");
    expect((await web(founder, "1")).status).toBe(303);
    expect(flowOnly()).toBe(true);
    expect((await web(founder, "0")).status).toBe(303);
    expect(flowOnly()).toBe(false);
    expect((await web(founder, "2")).status).toBe(303);
    expect(flowOnly()).toBe(false);
  });
  test("the form refuses a foreign Origin before it writes", async () => {
    const res = await web(founder, "1", { origin: "http://evil.example" });
    expect(res.status).toBe(403);
    expect(flowOnly()).toBe(false);
  });
});
@@ -0,0 +1,108 @@
/**
 * FLOW ONLY at the terminal's door (#6392): the About card shows the switch
 * to every reader; only a repository admin who is a person gets the `w` key.
 */
import { afterAll, beforeAll, 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 { listLabels } from "../src/core/issues.ts";
import { addTeamMember, createOrg, createTeam, listTeams, OWNERS_TEAM } from "../src/core/orgs.ts";
import { createRepo, getRepoById, type Repo } from "../src/core/repos.ts";
import { createUser, type User } from "../src/core/users.ts";
import type { Ctx, Screen } from "../src/tui/app/app.ts";
import { flowRow, aboutScreen } from "../src/tui/screens/about.ts";
import { localSource } from "../src/view/local.ts";
import type { Session } from "../src/tui/session.ts";
import { quietLogs } from "./helpers/globals.ts";
quietLogs();
let dataDir: string;
let app: App;
let founder: User;
let dev: User;
let bot: User;
let repo: Repo;
const ok = <T>(r: { ok: true; value: T } | { ok: false; error: unknown }): T => {
  if (!r.ok) throw new Error(JSON.stringify(r.error));
  return r.value;
};
const row = (): string => flowRow(getRepoById(app.db, repo.id)).map(([, v]) => v)[0]!;
function card(user: User) {
  const toasts: string[] = [];
  const ctx = {
    invalidate() {},
    toast: (t: string) => toasts.push(t),
    push() {},
    pop() {},
    copy() {},
  } as unknown as Ctx;
  const f = { app, db: app.db, user } as unknown as Session;
  const src = localSource(app, getRepoById(app.db, repo.id)!, user);
  const screen = aboutScreen(f, ctx, {} as Screen, src, undefined, "main");
  const offered = () => screen.keys.some((b) => b.keys.includes("w"));
  const press = async (key: string) => {
    screen.key!({ key } as never);
    await new Promise((r) => setTimeout(r, 20));
  };
  return { toasts, offered, press };
}
beforeAll(async () => {
  dataDir = await mkdtemp(join(tmpdir(), "forge-tui-flow-"));
  app = createApp({ dataDir, port: 0 });
  const make = async (username: string) =>
    ok(
      await createUser(app.db, {
        origin: "seed",
        trusted: true,
        username,
        email: `${username}@forge.local`,
        password: "a-good-passphrase",
        adminIfFirst: true,
      }),
    );
  founder = await make("founder");
  dev = await make("dev");
  const org = ok(createOrg(app.db, "acme", founder.id));
  const writers = ok(createTeam(app.db, org.id, "Writers", "write"));
  addTeamMember(app.db, writers, dev.id);
  repo = ok(await createRepo(app.db, app.reposRoot, { ownerId: org.id, name: "svc", visibility: "public" }));
  const agent = ok(await createAgent(app, founder, { username: "bot" }));
  expect(addToCrew(app, founder, repo, "bot").ok).toBe(true);
  const owners = listTeams(app.db, org.id).find((t) => t.name === OWNERS_TEAM)!;
  addTeamMember(app.db, owners, agent.user.id);
  bot = agent.user;
}, 30_000);
afterAll(async () => {
  app?.close();
  await rm(dataDir, { recursive: true, force: true });
});
test("an admin turns it on and off from About", async () => {
  const c = card(founder);
  expect(row()).toBe("off");
  expect(c.offered()).toBe(true);
  await c.press("w");
  expect(row()).toBe("on");
  expect(listLabels(app.db, repo.id).filter((l) => l.name === "flow")).toHaveLength(1);
  expect(c.toasts.at(-1)).toBe("flow only is on");
  await c.press("w");
  expect(row()).toBe("off");
  expect(c.toasts.at(-1)).toBe("flow only is off");
});
test("a writer and an agent see the line but cannot toggle it", async () => {
  for (const who of [dev, bot]) {
    const c = card(who);
    expect(c.offered()).toBe(false);
    await c.press("w");
    expect(row()).toBe("off");
  }
});
		@@ -359,6 +359,7 @@ This page is the front door. Everything else is a file of its own under
359	359	- [`docs/WEBSPEC-PREVIEWS.md`](docs/WEBSPEC-PREVIEWS.md) — the website specification run over every preview, report-only.
360	360	- [`docs/CREW.md`](docs/CREW.md) — the crew: agents, how a run works, review, live triage, the merge queue, spend, roles and invites, the sandbox, passports, and the direction a vision pull will write.
361	361	- [`docs/SENTINEL.md`](docs/SENTINEL.md) — the forge hunting its own faults; [`docs/HUNT.md`](docs/HUNT.md) is the bug hunters' detectors against one running app (`bun scripts/hunt.ts <origin>`).
	362	- Flow only: a repository's admin (a person, never an agent) sets one switch from Settings → On its own, `PATCH /api/v1/repos/:owner/:name` with `flowOnly`, MCP `repo_settings`, or `w` on the terminal's About card (`I`); turning it on makes the `flow` label. Nothing obeys it yet.
362	363	- [`docs/FLOW.md`](docs/FLOW.md) — where every issue stands: `GET /api/v1/repos/:owner/:name/flow` returns each open issue's stage, since, stalled and unblock, plus what went live in the last 24 h.
363	364	- Flow reads: `bun scripts/flow-report.ts [--db <path>] [--public] [--json]` prints one line per read; see [`docs/FLOW.md`](docs/FLOW.md).
364	365	- Under it, the panel says the crew's build yield over 24 h (runs finished, pushed, landed; `src/flow/build_yield.ts`) and the median hours to first review (`src/flow/review_latency.ts`); the terminal Flow dialog carries both in the same words (an agent reader there sees public repositories alone). `/boards` is for admins alone (anyone else gets not-found), so the page shows all repositories.
		@@ -122,7 +122,7 @@ for a tunnel and a forge that sleeps.
122	122	\| `releases` \| `{}`: the forge's kept releases newest first: short sha, version, the pull that landed it, when, and for the live one `live: true` and `since`; for whoever may read /releases, others get its refusal; no rollback, a person does that on the page \| \|
123	123	\| `repo` \| `{ repo }`: one repository's description, visibility, autonomy, `audience { level, sentence }` and `provenance` (where a migrated one came from, `null` when hidden), the same as `GET /api/v1/repos/:owner/:name` \| \|
124	124	\| `repo_labels` \| `{ repo, action?, name?, color?, id? }`: list (`list`, the default; a read-only token may), create (`create`, `name`, `color` six hex digits) or remove (`remove`, `id`) the repository's labels, as `GET`/`POST …/labels` and `DELETE …/labels/:id`; create and remove need an admin token and a repository admin \| yes \|
125		\| `repo_settings` \| `{ repo, description?, visibility? }` (admin): change a repository's description and visibility as `PATCH /api/v1/repos/:owner/:name` does, for the same callers (a repository admin); answers `{ repo, description, visibility }`; a visibility other than public or private is `invalid` \| yes \|
	125	\| `repo_settings` \| `{ repo, description?, visibility?, flowOnly? }` (admin): change a repository's description, visibility and FLOW ONLY switch as `PATCH /api/v1/repos/:owner/:name` does, for the same callers (a repository admin); answers `{ repo, description, visibility, flowOnly }` (with none to change it only reads); a visibility other than public or private is `invalid` \| yes \|
126	126	\| `reports` \| `{ repo, id?, action? }`: the waiting reports from outsiders, each `from: "outside"` (their words are unchecked); with `id` and `action` (`accept` opens it as an issue marked as from outside, `dismiss` closes it). A person who writes the repository only; needs an `rw` token \| yes \|
127	127	\| `restore_drill` \| no input: restore the newest snapshot as a drill and answer `{ verdict, failedStep?, says }`, worded as the Backups page's button; no store, a failure or a red drill is an answer, not an error; a forge admin's, with an admin token \| yes \|
128	128	\| `returns` \| `{ repo?, days? }`: what the crew's tokens bought over the last `days` (1–90, default 7): dollars, runs, changes landed, cost per change; `repo` narrows it to one app of yours \| \|
		@@ -123,6 +123,10 @@
123	123	- The crew — agents as accounts with nothing but a run-scoped token,
124	124	working issues in the background with Claude Code and proposing through
125	125	pulls a person merges.
	126	- Flow only — a repository's admin (a person, never an agent) sets one
	127	switch from Settings, `PATCH /api/v1/repos/:owner/:name` or MCP
	128	`repo_settings`, or the terminal's About card (`w`); it makes the `flow`
	129	label. Nothing obeys it yet.
		sentinelcrew 17d ago outdated Both doors: the terminal is a door like the page, and it already sets repository settings (src/tui/screens/about.ts, archive). Give Flow only a row and an admin-only toggle there, then drop this clause.
126	130
127	131	Pages render without a line of JavaScript and are designed thumb-first. Six
128	132	premade themes (from warm paper to polar night) switch instantly and persist in
		@@ -18,6 +18,7 @@ import { storageChanged, storageRefusal, storageSentence } from "../core/storage
18	18	import {
19	19	createLabel as insertLabel,
20	20	deleteLabel as removeLabel,
	21	getLabel,
21	22	updateLabel as writeLabel,
22	23	type Label,
23	24	} from "../core/issues.ts";
		@@ -333,6 +334,9 @@ function moveArchive(app: App, repoId: string, archived: boolean): Promise<boole
333	334	});
334	335	}
335	336
	337	/** The label FLOW ONLY puts in a repository. */
	338	const FLOW_LABEL = "flow";
	339
336	340	/**
337	341	* Change settings. A new default branch must exist; git HEAD is moved first
338	342	* and the row follows (git is truth, the index is derived from it).
		@@ -352,6 +356,7 @@ export async function updateRepoSettings(
352	356	(settings.crewOutsiders !== undefined \|\|
353	357	settings.decisionsBy !== undefined \|\|
354	358	settings.plansNeedNod !== undefined \|\|
	359	settings.flowOnly !== undefined \|\|
355	360	settings.archived !== undefined) &&
356	361	admin.value.kind === "agent"
357	362	)
		@@ -370,10 +375,15 @@ export async function updateRepoSettings(
370	375	}
371	376	const { archived, ...rest } = settings;
372	377	writeSettings(app.db, repo, rest);
	378	// FLOW ONLY names its label (the label it makes is not in `changed`, below): on, the repository has a `flow` to put on work.
	379	if (settings.flowOnly === true && getLabel(app.db, repo.id, FLOW_LABEL) === undefined)
		sentinelcrew 17d ago This calls the core `insertLabel` directly, so the label is created with no event of its own on the bus. A labels list someone already has open will not show `flow` until they reload. If `actions/repos.ts` (or the labels module) has a label-create action that emits an event, use that here, or say in the comment that skipping the event is deliberate.
	380	insertLabel(app.db, repo.id, FLOW_LABEL, "d29922");
		sentinelcrew 17d ago Fine: it's idempotent and the test pins a single label. The terminal toggle should reach this same function, so the label follows from every door.
373	381	const moved =
374	382	archived === undefined ? false : await moveArchive(app, repo.id, archived);
375	383	const updated = getRepoById(app.db, repo.id);
376	384	if (updated === undefined) return err("not_found");
	385	// `changed` is the audit line: it names settings, not the `flow` label
	386	// that turning flowOnly on may have made.
377	387	const changed: string[] = (
378	388	[
379	389	"visibility",
		@@ -385,6 +395,7 @@ export async function updateRepoSettings(
385	395	"crewOutsiders",
386	396	"decisionsBy",
387	397	"plansNeedNod",
	398	"flowOnly",
388	399	] as const
389	400	).filter((k) => settings[k] !== undefined && settings[k] !== repo[k]);
390	401	if (moved) changed.push("archived");
		@@ -19,10 +19,12 @@ export const route: Route = {
19	19	crewOutsiders: "boolean",
20	20	decisionsBy: "string",
21	21	plansNeedNod: "boolean",
	22	flowOnly: "boolean",
22	23	},
23	24	refusals: {
24	25	bad_archived: "422: archived is true or false",
25	26	bad_decisions_by: "422: decisionsBy is me, decider or decider_tell",
	27	bad_flow_only: "422: flowOnly is true or false",
26	28	bad_plans_need_nod: "422: plansNeedNod is true or false",
27	29	bad_show_provenance: "422: showProvenance is true or false",
28	30	no_provenance: `422: ${FAMILY_WORDS.no_provenance}`,
		@@ -0,0 +1,1 @@
	1	76c51289fbefaf8b3f8325328548a34f6e6fab8e6a55a64fac1d4224178d11a5
		@@ -0,0 +1,5 @@
	1	// A repository can be FLOW ONLY (#6392): one switch its admin sets. Nothing
	2	// obeys it yet; dispatch reads it in a later change.
	3	export default `
	4	ALTER TABLE repo ADD COLUMN flow_only INTEGER NOT NULL DEFAULT 0;
	5	`;
		@@ -121,6 +121,8 @@ export interface Repo {
121	121	readonly decisionsBy: DecisionsBy;
122	122	/** "Plans need a nod": a plan is stored as a proposal, not opened. */
123	123	readonly plansNeedNod: boolean;
	124	/** FLOW ONLY: an admin's switch; nothing obeys it yet. */
	125	readonly flowOnly: boolean;
124	126	/** The issue the planner is given, when the map has run dry. */
125	127	readonly directionIssueId: string \| null;
126	128	/** The repo this was forked from, or null. */
		@@ -169,6 +171,7 @@ interface RepoRow {
169	171	crew_outsiders: number;
170	172	decisions_by: string;
171	173	plans_need_nod: number;
	174	flow_only: number;
172	175	direction_issue_id: string \| null;
173	176	fork_parent_id: string \| null;
174	177	sealed_for: string \| null;
		@@ -209,6 +212,7 @@ function toRepo(row: RepoRow): Repo {
209	212	crewOutsiders: row.crew_outsiders === 1,
210	213	decisionsBy: isDecisionsBy(row.decisions_by) ? row.decisions_by : "me",
211	214	plansNeedNod: row.plans_need_nod === 1,
	215	flowOnly: row.flow_only === 1,
212	216	directionIssueId: row.direction_issue_id,
213	217	forkParentId: row.fork_parent_id,
214	218	sealedFor: row.sealed_for,
		@@ -1155,6 +1159,7 @@ export interface RepoSettings {
1155	1159	/** Archive (true) or wake (false); the time is stamped here. */
1156	1160	archived?: boolean;
1157	1161	plansNeedNod?: boolean;
	1162	flowOnly?: boolean;
1158	1163	}
1159	1164
1160	1165	/** The repositories still awake: what Yours lists before anyone types a filter. */
		@@ -1178,7 +1183,7 @@ export function updateRepoSettings(
1178	1183	default_branch = ?4, require_review = ?5, require_checks = ?7,
1179	1184	autonomy = ?8, autonomy_direction = ?9, autonomy_ceiling_usd = ?10,
1180	1185	autonomy_slots = ?11, autonomy_by = ?12, crew_outsiders = ?13, decisions_by = ?14,
1181		plans_need_nod = ?15
	1186	plans_need_nod = ?15, flow_only = ?16
1182	1187	WHERE id = ?6`,
1183	1188	).run(
1184	1189	settings.visibility ?? repo.visibility,
		@@ -1196,6 +1201,7 @@ export function updateRepoSettings(
1196	1201	(settings.crewOutsiders ?? repo.crewOutsiders) ? 1 : 0,
1197	1202	settings.decisionsBy ?? repo.decisionsBy,
1198	1203	(settings.plansNeedNod ?? repo.plansNeedNod) ? 1 : 0,
	1204	(settings.flowOnly ?? repo.flowOnly) ? 1 : 0,
1199	1205	);
1200	1206	forgetListings(db);
1201	1207	return getRepoById(db, repo.id)!;
		@@ -2509,6 +2509,8 @@ export function apiRoutes(router: Router<Handler>): void {
2509	2509	);
2510	2510	if (input.plansNeedNod !== undefined && typeof input.plansNeedNod !== "boolean")
2511	2511	return apiError("bad_plans_need_nod", 422, "plansNeedNod is true or false");
	2512	if (input.flowOnly !== undefined && typeof input.flowOnly !== "boolean")
	2513	return apiError("bad_flow_only", 422, "flowOnly is true or false");
2512	2514	if (input.showProvenance !== undefined) {
2513	2515	if (typeof input.showProvenance !== "boolean")
2514	2516	return apiError("bad_show_provenance", 422, "showProvenance is true or false");
		@@ -2556,6 +2558,8 @@ export function apiRoutes(router: Router<Handler>): void {
2556	2558	...(typeof input.plansNeedNod === "boolean"
2557	2559	? { plansNeedNod: input.plansNeedNod }
2558	2560	: {}),
	2561	// FLOW ONLY: an admin's switch, never an agent's.
	2562	...(typeof input.flowOnly === "boolean" ? { flowOnly: input.flowOnly } : {}),
2559	2563	});
2560	2564	if (!updated.ok) return respondAccess(updated.error, 422);
2561	2565	// "Show where this came from" (#3293): an admin's, never an agent's.
		@@ -4,15 +4,16 @@ import { VISIBILITY_WORDS } from "../../../core/arg_words.ts";
4	4
5	5	export const tool: Tool = {
6	6	name: "repo_settings",
7		doc: "`{ repo, description?, visibility? }` (admin): change a repository's description and visibility as `PATCH /api/v1/repos/:owner/:name` does, for the same callers (a repository admin); answers `{ repo, description, visibility }`; a visibility other than public or private is `invalid`",
	7	doc: "`{ repo, description?, visibility?, flowOnly? }` (admin): change a repository's description, visibility and FLOW ONLY switch as `PATCH /api/v1/repos/:owner/:name` does, for the same callers (a repository admin); answers `{ repo, description, visibility, flowOnly }` (with none to change it only reads); a visibility other than public or private is `invalid`",
8	8	description:
9		"Change a repo's description or visibility: PATCH /api/v1/repos/:owner/:name (admin).",
	9	"Read or change a repo's description, visibility or flowOnly: PATCH /api/v1/repos/:owner/:name (admin).",
10	10	inputSchema: {
11	11	type: "object",
12	12	properties: {
13	13	repo: REPO_ARG,
14	14	description: { type: "string", maxLength: 2000 },
15	15	visibility: { type: "string", enum: ["public", "private"] },
	16	flowOnly: { type: "boolean" },
16	17	},
17	18	required: ["repo"],
18	19	},
		@@ -21,7 +22,9 @@ export const tool: Tool = {
21	22	async run(ctx, user, args) {
22	23	const repo = repoArg(ctx, user, args);
23	24	if (isAnswer(repo)) return repo;
24		const { description, visibility } = args;
	25	const { description, visibility, flowOnly } = args;
	26	if (flowOnly !== undefined && typeof flowOnly !== "boolean")
	27	return bad("invalid", "flowOnly is true or false");
25	28	if (description !== undefined && typeof description !== "string")
26	29	return bad("invalid", "description is text");
27	30	if (visibility !== undefined && visibility !== "public" && visibility !== "private")
		@@ -29,6 +32,7 @@ export const tool: Tool = {
29	32	const updated = await updateRepoSettings(ctx.app, user, repo, {
30	33	...(visibility !== undefined ? { visibility } : {}),
31	34	...(description !== undefined ? { description } : {}),
	35	...(flowOnly !== undefined ? { flowOnly } : {}),
32	36	});
33	37	if (!updated.ok)
34	38	return bad(updated.error === "not_found" ? "not_found" : "forbidden", updated.error);
		@@ -36,6 +40,7 @@ export const tool: Tool = {
36	40	repo: `${updated.value.ownerName}/${updated.value.name}`,
37	41	description: updated.value.description,
38	42	visibility: updated.value.visibility,
	43	flowOnly: updated.value.flowOnly,
39	44	});
40	45	},
41	46	};