08c8ed8 · 6ea06b6 · ff0ba3c · 92420e2
@@ -672,8 +672,10 @@
purpose: a repository admin who is no site admin sees the list read-only on the
page, and nothing on the terminal screen (no rows, no `g`/`x`).
A release that turns egress on must not break an app whose writers have
not declared what it uses yet, so the operator can start it reported:
`FORGE_CELLS_EGRESS=report` lets an undeclared public host through (on 80
not declared what it uses yet, so an admin can set it reported:
`cells.egress` = `report` on /settings/capacity (or the API's
`PUT /api/v1/admin/capacity/cells.egress` with a `reason`; the change log
keeps who and why) lets an undeclared public host through (on 80
and 443 only) and
counts it per repository (`<data>/egress/<repo id>.json`, under the
forge's data where no cell sees it), and the app's page tells its writers
@@ -1655,7 +1657,7 @@
a link to the milestone (`docs/PLANNING.md`); its progress never does.
| `FORGE_CHECK_SHARDS`      | the machine's cores             | test shards per check (live: Settings → Capacity) |
| `FORGE_CHECK_CACHE_DAYS`  | `30`                            | days a package may go unlent before the check install cache drops it |
| `FORGE_CHECK_CACHE_MB`    | `2048`                          | size one repository's check install cache is swept down to |
| `FORGE_CELLS_EGRESS`      | `enforce`                       | `report` lets undeclared egress through on 80/443 (live: Settings → Capacity) |
| `FORGE_CELLS_EGRESS`      | ignored                         | logged once at boot; egress is enforced unless an admin sets `cells.egress` (Settings → Capacity), with a reason |
| `FORGE_CELL_CGROUP`       | `/sys/fs/cgroup` at a namespace root | the delegated cgroup v2 whose children cap each cell's memory; `off` watches only |
| `FORGE_CREW_CPUS`         | `4` | cores one crew run may use (`cpu.max` on its own cell cgroup, where the cpu controller is delegated) |
| `FORGE_CREW_BUDGET_USD`   | `5`                             | spend per run unless the agent says otherwise     |
@@ -70,7 +70,7 @@
bytes in `tools/list`. After changing a tool run `bun scripts/mcp-table.ts`;
| `boards` | — | The forge's boards for person admins: slug, title, range, refresh and panels | 425 |
| `branches` | `create`, `delete`, `branches`, `tags` | A repo's branches; `name`, `action` create (from `from`) or delete one, not the default | 407 |
| `builds` | — | A repo's build pins (`refs/builds/`): label, commit, pinned by, note | 231 |
| `capacity` | — | Forge capacity and guards, live | 363 |
| `capacity` | — | Forge capacity and guards, live | 390 |
| `claim_link` | — | A new claim link for an unclaimed child forge, only with `reveal: true`; the old stops | 289 |
| `close` | — | Close or reopen (`state` open) an issue or pull | 463 |
| `cloud_account` | — | Change a cloud account by `verb` (admin) | 549 |
@@ -79,7 +79,7 @@
bytes in `tools/list`. After changing a tool run `bun scripts/mcp-table.ts`;
| `confirm_wait` | — | Let an issue go ahead though its blocker closed dropped or split | 269 |
| `contribute` | — | For a new agent: what this forge is, its bottleneck, help-wanted issues, how to propose | 210 |
| `converge` | — | Have a fork's crew merge the parent's updates where both changed a file | 200 |
| `crew` | — | List a repository's crew, or add or remove an agent | 313 |
| `crew` | — | List a repository's crew, or add or remove an agent | 338 |
| `data` | — | Read SQLite files you may see: tables, rows, read-only SQL; secrets masked | 367 |
| `decisions_by` | — | Who decides parked hand-over cards: `me`, `decider`, `decider_tell` | 305 |
| `detach` | — | Detach a fork from its parent | 210 |
@@ -89,7 +89,7 @@
bytes in `tools/list`. After changing a tool run `bun scripts/mcp-table.ts`;
| `egress_grants` | — | Private destinations and grants: list, grant or revoke (site admin) | 289 |
| `email_verify` | — | Send yourself a new verification link | 126 |
| `events` | — | Repository events | 259 |
| `explore` | — | The apps, people (and, for an admin, forges) you can see, ranked | 414 |
| `explore` | — | The apps, people (and, for an admin, forges) you can see, ranked | 547 |
| `family` | — | The forge that sent this one and, for a site admin, those it sent, with state, version | 205 |
| `features` | — | Apps absorbed as forge features: list, read, absorb or un-absorb, change typed settings | 357 |
| `feed` | — | Your ranked home timeline; `cursor` pages; saved filter applies | 562 |
@@ -22,6 +22,8 @@
import {
  type CapacityKey,
  effectiveCapacity,
  followsSpeed,
  needsReason,
  REASON_MAX,
} from "../core/capacity.ts";
import type { EgressTotal } from "../apps/egress.ts";
import {
@@ -161,15 +163,23 @@
export function edgeOffDryRun(
  });
}
/** Set `key` to `value`; `null` or `""` goes back to the boot default. */
/** What a move to report, said without a reason, is told. */
export const REASON_WORDS = "Say why: setting cells.egress to report is kept with who made it and the reason.";
/**
 * Set `key` to `value`; `null` or `""` goes back to the boot default.
 * `reason` is kept beside who; a move of `cells.egress` to report is refused
 * without one (#10778). Tightening (enforce, or back to the default) never is.
 */
export function changeCapacity(
  app: App,
  actor: User | undefined,
  key: string,
  value: string | null,
  reason = "",
): Result<
  { key: CapacityKey; from: string; to: string },
  "not_found" | "no_such_setting" | "invalid_value" | "no_credential" | "derived"
  "not_found" | "no_such_setting" | "invalid_value" | "no_credential" | "derived" | "reason_required"
> {
  const who = admin(actor);
  if (!who.ok) return who;
@@ -180,16 +190,19 @@
export function changeCapacity(
    return err("invalid_value");
  if (key === "signin.edge" && next === "off" && !signsInWithoutEdge(app.db, who.value.id))
    return err("no_credential");
  const why = reason.replace(/[\u0000-\u001f\u007f]+/g, " ").trim().slice(0, REASON_MAX);
      
        sentinelcrew
        1d ago
        outdated
      
      Only a change to report should need a reason. As written, enforce and the reset to default are refused without one, which blocks the safe direction (and the page's Put back). Fix: needsReason(key) && next === "report", then test reset and enforce without a reason.
    
  if (needsReason(key) && next === "report" && why === "") return err("reason_required");
  const changed = setCapacity(
    app.db,
    key,
    next === "" ? null : next,
    who.value.id,
    why,
  );
  app.bus.append({
    kind: "capacity.changed",
    actorId: who.value.id,
    payload: { key, from: changed.from, to: changed.to },
    payload: { key, from: changed.from, to: changed.to, ...(why === "" ? {} : { reason: why }) },
  });
  return ok({ key, ...changed });
}
@@ -241,8 +241,8 @@
export interface CellSpec {
  readonly onRefused?: ((host: string, port: number, isPrivate: boolean) => void) | undefined;
  /**
   * Refuse undeclared egress, or only report it, for this cell — the
   * forge's setting when the cell starts (`core/capacity.ts`); the
   * environment's (`egressMode`) when the caller has none.
   * forge's setting when the cell starts (`core/capacity.ts`); enforce
   * when the caller has none. The environment never says (#10778).
   */
  readonly egressMode?: "enforce" | "report" | undefined;
  /**
@@ -274,16 +274,6 @@
export function watchedLimits(limits: Limits, cgroup: { readonly cpuCapped: bool
  return cgroup?.cpuCapped === true ? { ...limits, cpus: Number.POSITIVE_INFINITY } : limits;
}
/**
 * Whether undeclared egress is refused (`enforce`, the default) or let
 * through and reported (`FORGE_CELLS_EGRESS=report`), for a release that
 * must not break an app before its writers have declared what it uses.
 * Files, processes and private addresses are held the same in both.
 */
export function egressMode(): "enforce" | "report" {
  return process.env["FORGE_CELLS_EGRESS"] === "report" ? "report" : "enforce";
}
export interface Cell {
  /** The argv that runs `command` (through `sh -c`) inside the cell. */
  readonly argv: (command: string) => string[];
@@ -524,7 +514,8 @@
export function openCell(
        // the forge told its parent's door; a check that boots a forge is not.
        upstream: process.env["FORGE_PARENT_LOCAL"] === undefined ? undefined : upstreamProxy(),
        report:
          (spec.egressMode ?? egressMode()) === "report"
          // Enforce unless the caller carries an admin's report (`egressSetting`, #10778).
          spec.egressMode === "report"
            ? (host, port) => spec.onUndeclared?.(host, port)
            : undefined,
      },
@@ -33,7 +33,7 @@
export interface EgressPolicy {
   */
  readonly granted?: readonly string[] | undefined;
  /**
   * Set while egress is only reported (`FORGE_CELLS_EGRESS=report`): an
   * Set while egress is only reported (`cells.egress` = `report`, an admin's setting): an
   * undeclared public host is let through and handed here instead of
   * refused. Private addresses are refused either way.
   */
@@ -1,6 +1,6 @@
/**
 * What a repository's code reached without declaring it, while egress is
 * only reported (`FORGE_CELLS_EGRESS=report`, `apps/contain.ts`): one small
 * only reported (`cells.egress` = `report`, `core/capacity.ts`): one small
 * file per repository under `<data>/egress/`, read by the app's page so its
 * writers know what to add to `forge.json` before egress is enforced.
 */
@@ -33,7 +33,7 @@
export type CapacityKey =
interface Definition {
  /** What the settings page and the API call it. */
  readonly label: string;
  /** The environment variable that is its boot default. */
  /** The environment variable that is its boot default; "" for a setting only an admin moves. */
  readonly env: string;
  /** Whole numbers in a range, or one of a few words. */
  readonly kind:
@@ -100,10 +100,12 @@
export const CAPACITY: Record<CapacityKey, Definition> = {
  },
  "cells.egress": {
    label: "Egress from cells",
    env: "FORGE_CELLS_EGRESS",
    // No environment default: report is a decision an admin makes and the
    // change log keeps, never what a deployment's environment says (#10778).
    env: "",
    kind: { type: "choice", values: ["enforce", "report"] },
    fallback: "enforce",
    help: "enforce refuses a host an app or check did not declare; report lets it through on 80 and 443 and lists it on the app's page. Takes effect on the next cell started.",
    help: "enforce refuses a host an app or check did not declare; report lets it through on 80 and 443 and lists it on the app's page. Enforce unless an admin sets report here, with a reason. Takes effect on the next cell started.",
      
        sentinelcrew
        1d ago
        outdated
      
      Principles 1 and 8: this help already says what enforce and report do; the added clause and the page's "The default; only an admin moves it." repeat one another. Say it once: "Enforce unless an admin sets report here, with a reason."
    
  },
  "children.modelEgress": {
    label: "Model provider a child forge cell may reach",
@@ -178,7 +180,9 @@
export function capacityDefault(key: CapacityKey, cpus?: number): string {
/** The environment's value for `key`, when it holds a valid one. */
function explicitDefault(key: CapacityKey): string | undefined {
  const env = process.env[CAPACITY[key].env]?.trim() ?? "";
  const name = CAPACITY[key].env;
  if (name === "") return undefined;
  const env = process.env[name]?.trim() ?? "";
  return env !== "" && validCapacity(key, env) ? env : undefined;
}
@@ -391,11 +395,32 @@
export function maxChildren(db: Database): number {
  return Number(capacityValue(db, "children.max"));
}
/** The egress mode a cell starts with now. */
/** The egress mode a cell starts with now: enforce unless an admin set report. */
export function egressSetting(db: Database): "enforce" | "report" {
  return capacityValue(db, "cells.egress") === "report" ? "report" : "enforce";
}
/** The variable that once set the egress mode, and is now only noticed (#10778). */
export const EGRESS_ENV = "FORGE_CELLS_EGRESS";
/**
 * The one boot line for an environment that still asks for an egress mode:
 * it is ignored, and this says so once, plainly; null when it asks nothing.
 */
export function egressEnvIgnored(env: Record<string, string | undefined> = process.env): string | null {
  const asked = env[EGRESS_ENV]?.trim() ?? "";
  if (asked === "" || asked === "enforce") return null;
  return `${EGRESS_ENV}=${asked.slice(0, 32)} is ignored: egress is enforced unless an admin sets cells.egress on /settings/capacity, with a reason`;
}
/** Most characters a change's reason keeps. */
export const REASON_MAX = 500;
/** Keys whose loosening must say why: a move of these to report needs a reason. */
export function needsReason(key: CapacityKey): boolean {
  return key === "cells.egress";
}
/** The model provider hosts a child forge's cell may reach now: none unless an admin chose one. */
export function childModelHosts(db: Database): readonly string[] {
  return MODEL_HOSTS[capacityValue(db, "children.modelEgress")] ?? [];
@@ -466,6 +491,8 @@
export interface CapacityChange {
  readonly actorId: string;
  readonly actorName: string;
  readonly at: string;
  /** Why, as the admin said it; "" for a change made before reasons were kept. */
  readonly reason: string;
}
/**
@@ -479,6 +506,8 @@
export function setCapacity(
  key: CapacityKey,
  value: string | null,
  actorId: string,
  /** Why, in the admin's words, already cut to REASON_MAX by the action; kept beside who (#10778). */
  reason = "",
): { from: string; to: string } {
  const from = capacityValue(db, key);
  const at = new Date().toISOString();
@@ -494,9 +523,9 @@
export function setCapacity(
  })();
  const to = capacityValue(db, key);
  db.query(
    `INSERT INTO forge_setting_change (key, from_value, to_value, actor_id, at)
     VALUES (?1, ?2, ?3, ?4, ?5)`,
  ).run(key, from, to, actorId, at);
    `INSERT INTO forge_setting_change (key, from_value, to_value, actor_id, at, reason)
     VALUES (?1, ?2, ?3, ?4, ?5, ?6)`,
  ).run(key, from, to, actorId, at, reason);
  return { from, to };
}
@@ -511,10 +540,11 @@
export function capacityChanges(db: Database, limit = 20): CapacityChange[] {
        actor_id: string;
        username: string | null;
        at: string;
        reason: string;
      },
      [number]
    >(
      `SELECT c.key, c.from_value, c.to_value, c.actor_id, u.username, c.at
      `SELECT c.key, c.from_value, c.to_value, c.actor_id, u.username, c.at, c.reason
         FROM forge_setting_change c LEFT JOIN user u ON u.id = c.actor_id
        ORDER BY c.at DESC, c.rowid DESC LIMIT ?1`,
    )
@@ -527,5 +557,6 @@
export function capacityChanges(db: Database, limit = 20): CapacityChange[] {
      actorId: r.actor_id,
      actorName: r.username ?? "",
      at: r.at,
      reason: r.reason,
    }));
}
@@ -0,0 +1,1 @@
03b5a26202aad083af3b64356cc064faec8f1f275521c22beceef313f3f4612d
@@ -0,0 +1,5 @@
// A capacity change keeps why beside who (#10778): cells.egress moves to
// report only with a reason, and the change log shows it. Additive.
export default `
  ALTER TABLE forge_setting_change ADD COLUMN reason TEXT NOT NULL DEFAULT '';
  `;
@@ -13,7 +13,7 @@
import { kpiProbe } from "../../web/studio/kpi_probe.ts";
import { MAX_SECONDS, sampleStacks } from "../../perf/sample.ts";
import { listAccounts, removeAccount, retireAndRemoveAccount, retirementPlan, suspendAccount, unsuspendAccount, verifyAccount } from "../../actions/accounts.ts";
import { ADMIN_WORDS } from "../../actions/admin_words.ts";
import { DERIVED_WORDS, changeCapacity, edgeOffDryRun, listCapacity } from "../../actions/capacity.ts";
import { DERIVED_WORDS, REASON_WORDS, changeCapacity, edgeOffDryRun, listCapacity } from "../../actions/capacity.ts";
import { changeShield, lastShieldChange, shieldState } from "../../actions/shield.ts";
import { inviteLink, list as listInviteLinks, mint as mintInviteLink, revoke as revokeInviteLink } from "../../actions/invites.ts";
import { changeLimit, listLimits } from "../../actions/limits.ts";
@@ -188,7 +188,8 @@
export function adminRoutes(router: Router<Handler>): void {
      return dry.ok ? json({ dry_run: true, ...dry.value }) : notFound();
    }
    const value = input.value === null ? null : str(input.value);
    const changed = changeCapacity(ctx.app, ctx.auth.user, ctx.params.key!, value);
    const reason = typeof input.reason === "string" ? input.reason : "";
    const changed = changeCapacity(ctx.app, ctx.auth.user, ctx.params.key!, value, reason);
    if (changed.ok) return json(changed.value);
    if (changed.error === "not_found") return notFound();
    return apiError(
@@ -198,7 +199,9 @@
export function adminRoutes(router: Router<Handler>): void {
        ? "no such capacity setting"
        : changed.error === "derived"
          ? DERIVED_WORDS
          : SETTING_WORDS.outOfRange,
          : changed.error === "reason_required"
            ? REASON_WORDS
            : SETTING_WORDS.outOfRange,
    );
  });
@@ -1,11 +1,11 @@
import { DERIVED_WORDS, SETTABLE_CAPACITY, changeCapacity, listCapacity } from "../../../actions/capacity.ts";
import { DERIVED_WORDS, REASON_WORDS, SETTABLE_CAPACITY, changeCapacity, listCapacity } from "../../../actions/capacity.ts";
import { SETTING_WORDS } from "../../../actions/setting_words.ts";
import { scopeAllows } from "../../../core/tokens.ts";
import { good, bad, type Tool } from "../shared.ts";
export const tool: Tool = {
  name: "capacity",
  doc: "`{ key?, value?, dryRun? }` (forge admin): the forge's capacity and guards, live (crew and checks concurrency, check shards, cell egress, the new-account guard, the sign-in edge, queue depth, child forges, `egress.npmBytesLastHour` and `npmTopRepoLastHour`, and `selfSwap: { enabled, migrateReq, blocked }`: whether `FORGE_SELF_SWAP=1`, the kernel's `tcp_migrate_req` (`1`, `0`, `unreadable`), and why this forge cannot swap itself, null when it can; only the first six are settable by `key`); with `key` and `value` (`\"\"` restores the default), planned first (`dryRun` is true unless `false`); applying needs an admin-scope token",
  doc: "`{ key?, value?, reason?, dryRun? }` (forge admin): the forge's capacity and guards, live (crew and checks concurrency, check shards, cell egress, the new-account guard, the sign-in edge, queue depth, child forges, `egress.npmBytesLastHour` and `npmTopRepoLastHour`, and `selfSwap: { enabled, migrateReq, blocked }`: whether `FORGE_SELF_SWAP=1`, the kernel's `tcp_migrate_req` (`1`, `0`, `unreadable`), and why this forge cannot swap itself, null when it can; only the first six are settable by `key`); with `key` and `value` (`\"\"` restores the default) and `reason` (kept with who; required for `cells.egress`), planned first (`dryRun` is true unless `false`); applying needs an admin-scope token",
  description:
    "Forge capacity and guards, live. With `key` and `value` (\"\" restores default), plans.",
  inputSchema: {
@@ -16,6 +16,7 @@
export const tool: Tool = {
        enum: [...SETTABLE_CAPACITY],
      },
      value: { type: "string", maxLength: 16 },
      reason: { type: "string", maxLength: 500 },
      dryRun: { type: "boolean" },
    },
  },
@@ -35,8 +36,13 @@
export const tool: Tool = {
      });
    if (!scopeAllows(ctx.auth.scope ?? "ro", "admin"))
      return bad("forbidden", "changing the forge's capacity needs an admin-scope token");
    const changed = changeCapacity(ctx.app, user, key, value);
    if (!changed.ok) return bad(changed.error, changed.error === "derived" ? DERIVED_WORDS : SETTING_WORDS.outOfRange);
    const reason = typeof args["reason"] === "string" ? args["reason"] : "";
    const changed = changeCapacity(ctx.app, user, key, value, reason);
    if (!changed.ok)
      return bad(
        changed.error,
        changed.error === "derived" ? DERIVED_WORDS : changed.error === "reason_required" ? REASON_WORDS : SETTING_WORDS.outOfRange,
      );
    return good({
      says: `${key}: ${changed.value.from || "auto"} → ${changed.value.to || "auto"}, from the next pick on.`,
      ...changed.value,
@@ -93,7 +93,7 @@
import { ownTagsReader } from "./release/own_tags.ts";
import { rollProbe, tick as keeperTick } from "./keeper/keeper.ts";
import { keeperEnv, keeperPorts } from "./keeper/wire.ts";
import { snapshotPlace } from "./actions/health.ts";
import { capacityDefault } from "./core/capacity.ts";
import { capacityDefault, egressEnvIgnored } from "./core/capacity.ts";
import { bootCounts, recordBoot, recordCleanExit } from "./kernel/boots.ts";
import { census, censusWords, processRows } from "./kernel/census.ts";
import { reapLeftoverBridges } from "./crew/leftovers.ts";
@@ -397,6 +397,9 @@
const publicUrl = new URL(forgeUrl);
if (appDomain?.ok === false) app.log.error(appDomain.reason);
if (appDomain?.ok === true && appDomain.note !== undefined)
  app.log.warn(appDomain.note);
// An environment asking for egress report is ignored, and said so once (#10778).
const egressIgnored = egressEnvIgnored();
if (egressIgnored !== null) app.log.info(egressIgnored);
// One crew run's length: what a run takes, and how long past its idle
// window an app busy with one is left awake.
const crewRunMs = positive(process.env.FORGE_CREW_TIMEOUT_MIN, 45) * 60_000;
@@ -2,13 +2,14 @@
 * The forge's capacity and guards in the terminal, a forge admin's who is a
 * person: each guard's live value and bounds, and `e` on a settable one asks
 * for a value, shows the plan (from → to) and changes it after a confirm,
 * through the same actions as MCP `capacity`. The actions decide who may.
 * through the same actions as MCP `capacity`; a move of cells.egress to
 * report asks why first, as the page does. The actions decide who may.
 */
import type { SelfSwap } from "../../release/swap.ts";
import { DERIVED_WORDS, changeCapacity, listCapacity, type CapacityRow } from "../../actions/capacity.ts";
import { DERIVED_WORDS, REASON_WORDS, changeCapacity, listCapacity, type CapacityRow } from "../../actions/capacity.ts";
import { SETTING_WORDS } from "../../actions/setting_words.ts";
import { CAPACITY, belowCeiling, validCapacity, type CapacityKey } from "../../core/capacity.ts";
import { CAPACITY, belowCeiling, needsReason, validCapacity, type CapacityKey } from "../../core/capacity.ts";
import type { Ctx, Screen } from "../app/app.ts";
import { binding } from "../app/keys.ts";
import type { Session } from "../session.ts";
@@ -29,8 +30,10 @@
export function boundsOf(key: CapacityKey): string {
}
/** What a refused change says, in its own words. */
const refused = (error: "not_found" | "no_such_setting" | "invalid_value" | "no_credential" | "derived"): string =>
  error === "derived"
const refused = (error: "not_found" | "no_such_setting" | "invalid_value" | "no_credential" | "derived" | "reason_required"): string =>
  error === "reason_required"
      
        sentinelcrew
        1d ago
        outdated
      
      Both doors: the terminal refuses and sends the person to the page. The screen must collect the reason itself and call changeCapacity, so a person can do in the terminal what the page does. Add a test in test/tui-capacity.test.ts.
    
    ? REASON_WORDS
    : error === "derived"
    ? DERIVED_WORDS
    : error === "no_credential"
    ? "Set a password or a passkey first: turning the edge off would lock you out"
@@ -72,17 +75,17 @@
export function capacityScreen(f: Session, ctx: Ctx): Screen {
    return [...guards, selfSwapRow(listed.value.selfSwap), ...(egress === null ? [] : [{ title: egress, tone: "attn" as const }])];
  };
  const plan = (row: CapacityRow, typed: string): void => {
  const plan = (row: CapacityRow, typed: string, reason = ""): void => {
    const to = typed === "" ? row.default : typed;
    later(ctx, () =>
      confirmScreen(ctx, screen, {
        title: "Capacity",
        body: [`${row.key}: ${shown(row.value)} → ${shown(to)}`, "change it? y/n"],
        body: [`${row.key}: ${shown(row.value)} → ${shown(to)}`, ...(reason === "" ? [] : [`why: ${reason}`]), "change it? y/n"],
        actions: [{ label: "y" }, { label: "n" }],
        selected: 1,
        onChoose: (choice) => {
          if (choice !== 0) return;
          const done = changeCapacity(f.app, f.user, row.key, typed);
          const done = changeCapacity(f.app, f.user, row.key, typed, reason);
          if (!done.ok) return ctx.toast(refused(done.error), "danger");
          ctx.toast(`${done.value.key}: ${shown(done.value.from)} → ${shown(done.value.to)}, from the next pick on.`, "success");
          ctx.invalidate();
@@ -91,6 +94,16 @@
export function capacityScreen(f: Session, ctx: Ctx): Screen {
    );
  };
  const askWhy = (row: CapacityRow, value: string): void => {
    void later(ctx, () =>
      promptScreen(ctx, screen, {
        title: row.label,
        label: `Why set ${row.key} to ${value}? (kept with your name)`,
        onSubmit: (why) => (why === "" ? REASON_WORDS : (plan(row, value, why), undefined)),
      }),
    );
  };
  const screen: Screen = {
    title: "Capacity",
    keys: [binding(["e"], "change a setting"), binding(["j", "k"], "move cursor")],
@@ -113,6 +126,8 @@
export function capacityScreen(f: Session, ctx: Ctx): Screen {
          onSubmit: (typed) => {
            const value = typed.trim();
            if (value !== "" && !validCapacity(row.key, value)) return SETTING_WORDS.outOfRange;
            // A move to report says why, as the page asks (#10778); tightening never waits.
            if (needsReason(row.key) && value === "report") return askWhy(row, value), undefined;
            return plan(row, value), undefined;
          },
        }),
@@ -6,8 +6,8 @@
 * and each one is listed below the settings: who, when, from what to what.
 */
import { DERIVED_WORDS, changeCapacity, edgeOffDryRun, listCapacity, type CapacityRow } from "../../actions/capacity.ts";
import { CAPACITY, belowCeiling, type CapacityKey } from "../../core/capacity.ts";
import { DERIVED_WORDS, REASON_WORDS, changeCapacity, edgeOffDryRun, listCapacity, type CapacityRow } from "../../actions/capacity.ts";
import { CAPACITY, REASON_MAX, belowCeiling, needsReason, type CapacityKey } from "../../core/capacity.ts";
import { EGRESS_REPORTED } from "../../system/egress_line.ts";
import { bytes } from "../../system/format.ts";
import { egressRowsFor } from "../../spawn/process_counters.ts";
@@ -100,11 +100,14 @@
export function capacityPage(ctx: Ctx): Response {
      )}`,
      meta: html`${s.help} <br />Now <span class="mono">${s.value === "" ? "auto" : s.value}</span>. ${s.source === "setting"
          ? html`Set here; the boot default is
              <span class="mono">${s.default === "" ? "auto" : s.default}</span>
              (<span class="mono">${s.env}</span>).`
              <span class="mono">${s.default === "" ? "auto" : s.default}</span>${s.env === ""
                ? "."
                : html` (<span class="mono">${s.env}</span>).`}`
          : s.source === "derived"
            ? html`Derived from Speed (<span class="mono">crew.concurrency</span>); read-only here: change Speed and it moves.`
            : html`The boot default, from <span class="mono">${s.env}</span>.`}
            : s.env === ""
              ? html`The default.`
              : html`The boot default, from <span class="mono">${s.env}</span>.`}
        ${awayLine(s, now)}`,
      trail: s.source === "derived"
        ? html`<span class="mono" data-derived="${s.key}">${s.value}</span>`
@@ -115,6 +118,20 @@
export function capacityPage(ctx: Ctx): Response {
      >
        <input type="hidden" name="key" value="${s.key}" />
        ${input(s.key, s.value)}
        ${when(
      
        sentinelcrew
        1d ago
        
      
      The reason field is required on the Save form, but the Put back form carries none, so resetting cells.egress now fails with reason_required. Once the action only asks a reason for report this holds; add a page-level test that POSTs without a reason (refused) and a reset (accepted). Also principle 6/3: a bare placeholder="why" input beside the value is cramped; give it its own row.
    
          // Inside the row's own form, posted with Save: a move to report says why (#10778).
          needsReason(s.key),
          () => html`<input
            class="input"
            id="cap-${s.key}-reason"
            type="text"
            name="reason"
            maxlength="${String(REASON_MAX)}"
            autocomplete="off"
            placeholder="Why (needed to set report)"
            aria-label="Why (needed to set report)"
          />`,
        )}
        ${btn("Save", {
          size: "sm",
          variant: "primary",
@@ -142,7 +159,7 @@
export function capacityPage(ctx: Ctx): Response {
      title: html`<span class="mono">${c.key}</span>
        <span class="mono">${c.from === "" ? "auto" : c.from}</span> →
        <span class="mono">${c.to === "" ? "auto" : c.to}</span>`,
      meta: html`${c.actorName === "" ? "someone" : c.actorName} · ${time(c.at)}`,
      meta: html`${c.actorName === "" ? "someone" : c.actorName} · ${time(c.at)}${c.reason === "" ? "" : html` · ${c.reason}`}`,
    }),
  );
  const reported = settings.some(
@@ -239,6 +256,7 @@
const ERRORS: Record<string, string> = {
  no_such_setting: "There is no such setting.",
  derived: DERIVED_WORDS,
  invalid_value: "That value is outside what this setting takes.",
  reason_required: REASON_WORDS,
  no_credential:
    "Add a passkey (or a password) to your own account first: with the edge off, you would be signed out for good.",
};
@@ -268,6 +286,7 @@
export async function capacitySet(ctx: Ctx): Promise<Response> {
    ctx.auth.user,
    key,
    reset ? null : field(form, "value"),
    field(form, "reason"),
  );
  if (!changed.ok && changed.error === "not_found") return notFoundPage(ctx);
  return flashTo(
@@ -6,7 +6,6 @@
 */
import { egressModeSentence, undeclaredHosts } from "../../apps/egress_report.ts";
import { egressMode } from "../../apps/contain.ts";
import { html, type Html } from "../html.ts";
import { row } from "../ui.ts";
@@ -16,7 +15,7 @@
export function egressNote(
  /** What production declares now: a host declared since is not repeated. */
  declared: readonly string[],
  /** The forge's egress mode now (`core/capacity.ts`). */
  mode: "enforce" | "report" = egressMode(),
  mode: "enforce" | "report",
): Html | null {
  // Once egress is enforced the forge refuses these calls; the note is for the
  // window before that, when adding them to forge.json still saves the app.
@@ -716,7 +716,7 @@
describe("the board's forge strip", () => {
    claimRun(app.db, createRun(app.db, { repoId: made.value.id, kind: "agent" }).id);
    // Clear the stuck run the first test left behind.
    app.db.query("UPDATE run SET state = 'failed' WHERE heartbeat_at = ?1").run("2020-01-01T00:00:00.000Z");
    expect(changeCapacity(app, admin, "cells.egress", "report").ok).toBe(true);
    expect(changeCapacity(app, admin, "cells.egress", "report", "a test says why").ok).toBe(true);
    try {
      const text = await board("root");
      expect(text).toContain("All fine");
@@ -63,7 +63,7 @@
test("with egress enforced, System and Capacity say nothing about it, and neithe
});
test("egress in report mode is one line on Capacity and System, not on / or /board", async () => {
  const changed = await changeCapacity(app, admin.value, "cells.egress", "report");
  const changed = await changeCapacity(app, admin.value, "cells.egress", "report", "a test says why");
  expect(changed.ok).toBe(true);
  expect(await get("/settings/capacity")).toContain('id="egress-reported"');
  expect(await get("/system")).toContain('id="egress-reported"');
@@ -63,7 +63,7 @@
test("the egress row reads its true current state, and the reported note says so
  const before = await page();
  expect(before).not.toContain('id="egress-reported"');
  const now = /Now <span class="mono">([^<]+)<\/span>/.exec(egressRow(before))?.[1];
  expect(changeCapacity(app, alice, "cells.egress", "report").ok).toBe(true);
  expect(changeCapacity(app, alice, "cells.egress", "report", "a test says why").ok).toBe(true);
  const after = await page();
  expect(egressRow(after)).toContain('Now <span class="mono">report</span>');
  expect(now).not.toBe("report");
@@ -302,6 +302,7 @@
describe("capacity: only a forge admin reads or changes it", () => {
    const made = await mcp(aliceAdmin, {
      key: "cells.egress",
      value: "report",
      reason: "a test says why",
      dryRun: false,
    });
    expect(made.error).toBe(false);
@@ -457,7 +458,7 @@
describe("report mode is loud to admins, and to nobody else", () => {
  });
  test("reported: the Capacity page says it once, as a note; vitals do not", async () => {
    expect(changeCapacity(app, alice, "cells.egress", "report").ok).toBe(true);
    expect(changeCapacity(app, alice, "cells.egress", "report", "a test says why").ok).toBe(true);
    expect(needs(alice)).toEqual([]);
    const shown = await page();
    expect(shown).toContain('id="egress-reported"');
@@ -831,7 +832,7 @@
describe("the egress mode is the emergency lever: the next cell starts with what
      if (!record.ok) throw new Error(String(record.error));
      // A runtime that can hold cells is asked; one that cannot has none to start.
      (runtime as unknown as { cells: { ok: true } }).cells = { ok: true };
      expect(changeCapacity(app, alice, "cells.egress", "report").ok).toBe(
      expect(changeCapacity(app, alice, "cells.egress", "report", "a test says why").ok).toBe(
        true,
      );
      expect(runtime.cellFor(record.value, "production")?.egressMode).toBe(
@@ -906,10 +906,8 @@
describe.skipIf(noCells)(
        hostname: "127.0.0.1",
        fetch: () => new Response("inside"),
      });
      process.env["FORGE_CELLS_EGRESS"] = "report";
    });
    afterAll(async () => {
      delete process.env["FORGE_CELLS_EGRESS"];
      listener.stop(true);
      await rm(dir, { recursive: true, force: true });
    });
@@ -938,6 +936,7 @@
describe.skipIf(noCells)(
            egress: [],
            reach: [],
            limits: { memoryMiB: 1024, cpus: 2, diskMiB: 1024 },
            egressMode: "report",
            onUndeclared: (host, port) => seen.push(`${host}:${port}`),
          },
        },
@@ -0,0 +1,185 @@
// Egress is enforced unless an admin says otherwise, with a reason (#10778):
// an environment asking for report is ignored and said once, never obeyed.
import { afterAll, afterEach, 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 { serve, type Servers } from "../src/http/server.ts";
import { changeCapacity } from "../src/actions/capacity.ts";
import {
  capacityChanges,
  capacityDefault,
  egressEnvIgnored,
  egressSetting,
  REASON_MAX,
  setCapacity,
} from "../src/core/capacity.ts";
import type { User } from "../src/core/users.ts";
import { seedAdmin } from "./helpers/admin.ts";
let dataDir = "";
let app: App, servers: Servers, bearer = "", alice: User;
const before = process.env["FORGE_CELLS_EGRESS"];
beforeAll(async () => {
  dataDir = await mkdtemp(join(tmpdir(), "forge-egress-default-"));
  app = createApp({ dataDir, port: 0 });
  servers = await serve(app);
  const admin = await seedAdmin(app, { username: "alice", email: "[email protected]", password: "correct-horse-battery" });
  if (!admin.ok) throw new Error(admin.error);
  alice = admin.value;
  const minted = await fetch(`${servers.url}/api/v1/tokens`, {
    method: "POST",
    headers: { "content-type": "application/json" },
    body: JSON.stringify({ adminConfirm: true, username: "alice", password: "correct-horse-battery", name: "cli", scope: "admin" }),
  });
  bearer = ((await minted.json()) as { token: string }).token;
});
afterEach(() => {
  if (before === undefined) delete process.env["FORGE_CELLS_EGRESS"];
  else process.env["FORGE_CELLS_EGRESS"] = before;
  setCapacity(app.db, "cells.egress", null, alice.id);
});
afterAll(async () => {
  servers.stop();
  app.close();
  await rm(dataDir, { recursive: true, force: true });
});
test("the default is enforce", () => {
  delete process.env["FORGE_CELLS_EGRESS"];
  expect(capacityDefault("cells.egress")).toBe("enforce");
  expect(egressSetting(app.db)).toBe("enforce");
});
test("an environment asking for report is ignored, and said in one line", () => {
  process.env["FORGE_CELLS_EGRESS"] = "report";
  expect(capacityDefault("cells.egress")).toBe("enforce");
  expect(egressSetting(app.db)).toBe("enforce");
  const said = egressEnvIgnored();
  expect(said).toContain("FORGE_CELLS_EGRESS=report is ignored");
  expect(said).not.toContain("\n");
  expect(egressEnvIgnored({})).toBeNull();
  expect(egressEnvIgnored({ FORGE_CELLS_EGRESS: "enforce" })).toBeNull();
});
test("the capacity page shows no report line and no environment for it when only the environment asks", async () => {
  process.env["FORGE_CELLS_EGRESS"] = "report";
  const res = await fetch(`${servers.url}/settings/capacity`, { headers: { authorization: `Bearer ${bearer}` } });
  const body = await res.text();
  expect(body).not.toContain("Egress is reported, not enforced");
  expect(body).not.toContain("FORGE_CELLS_EGRESS");
});
test("an admin's report is honoured only with a reason, and kept with who and why", async () => {
  expect(changeCapacity(app, alice, "cells.egress", "report")).toEqual({ ok: false, error: "reason_required" });
  expect(changeCapacity(app, alice, "cells.egress", "report", "   ")).toEqual({ ok: false, error: "reason_required" });
  expect(egressSetting(app.db)).toBe("enforce");
  expect(changeCapacity(app, alice, "cells.egress", "report", "migrating the lab, one day").ok).toBe(true);
  expect(egressSetting(app.db)).toBe("report");
  const kept = capacityChanges(app.db)[0]!;
  expect([kept.key, kept.from, kept.to, kept.actorName, kept.reason]).toEqual([
    "cells.egress",
    "enforce",
    "report",
    "alice",
    "migrating the lab, one day",
  ]);
  // The API refuses without a reason and keeps the one it is given.
  const put = (body: object) =>
    fetch(`${servers.url}/api/v1/admin/capacity/cells.egress`, {
      method: "PUT",
      headers: { authorization: `Bearer ${bearer}`, "content-type": "application/json" },
      body: JSON.stringify(body),
    });
  expect((await put({ value: "report" })).status).toBe(422);
  expect((await put({ value: "enforce", reason: "lab done" })).status).toBe(200);
  expect(egressSetting(app.db)).toBe("enforce");
  expect(capacityChanges(app.db)[0]!.reason).toBe("lab done");
  expect((await put({ value: "report", reason: "lab again" })).status).toBe(200);
  expect(egressSetting(app.db)).toBe("report");
  // Tightening never waits on a reason.
  expect((await put({ value: "enforce" })).status).toBe(200);
  expect(egressSetting(app.db)).toBe("enforce");
  // The page lists the reason beside who.
  const page = await (await fetch(`${servers.url}/settings/capacity`, { headers: { authorization: `Bearer ${bearer}` } })).text();
  expect(page).toContain("lab done");
  expect(page).toContain('name="reason"');
});
test("a setting that needs no reason still takes none", () => {
  expect(changeCapacity(app, alice, "checks.shards", "2").ok).toBe(true);
  expect(capacityChanges(app.db)[0]!.reason).toBe("");
  changeCapacity(app, alice, "checks.shards", null);
});
test("tightening needs no reason: enforce and the reset to default both go through bare", () => {
  expect(changeCapacity(app, alice, "cells.egress", "report", "a window").ok).toBe(true);
  expect(changeCapacity(app, alice, "cells.egress", "enforce").ok).toBe(true);
  expect(egressSetting(app.db)).toBe("enforce");
  expect(changeCapacity(app, alice, "cells.egress", "report", "a window").ok).toBe(true);
  expect(changeCapacity(app, alice, "cells.egress", null).ok).toBe(true);
  expect(egressSetting(app.db)).toBe("enforce");
});
test("a reason is cut once, at the action, to REASON_MAX", () => {
  expect(changeCapacity(app, alice, "cells.egress", "report", "x".repeat(REASON_MAX + 50)).ok).toBe(true);
  expect(capacityChanges(app.db)[0]!.reason.length).toBe(REASON_MAX);
});
test("the page: report without a reason is refused, with one it holds, and Put back needs none", async () => {
  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: "correct-horse-battery" }),
  });
  const cookie = (signin.headers.get("set-cookie") ?? "").split(";")[0] ?? "";
  const post = (body: Record<string, string>) =>
    fetch(`${servers.url}/settings/capacity`, {
      method: "POST",
      redirect: "manual",
      headers: { cookie, "content-type": "application/x-www-form-urlencoded", origin: servers.url },
      body: new URLSearchParams(body),
    });
  await post({ key: "cells.egress", value: "report" });
  expect(egressSetting(app.db)).toBe("enforce");
  await post({ key: "cells.egress", value: "report", reason: "page says why" });
  expect(egressSetting(app.db)).toBe("report");
  expect(capacityChanges(app.db)[0]!.reason).toBe("page says why");
  await post({ key: "cells.egress", reset: "1" });
  expect(egressSetting(app.db)).toBe("enforce");
  // The reason is a labelled field inside the setting's own form, posted with Save.
  const page = await (await fetch(`${servers.url}/settings/capacity`, { headers: { cookie } })).text();
  const form = [...page.matchAll(/<form\b[\s\S]*?<\/form>/g)]
    .map((m) => m[0])
    .find((f) => f.includes('value="cells.egress"'));
  expect(form).toContain('name="reason"');
  expect(form).toContain('aria-label="Why (needed to set report)"');
});
test("MCP: report needs the reason argument, and keeps it", async () => {
  const call = async (args: Record<string, unknown>) => {
    const res = await fetch(`${servers.url}/mcp`, {
      method: "POST",
      headers: { authorization: `Bearer ${bearer}`, "content-type": "application/json", accept: "application/json, text/event-stream" },
      body: JSON.stringify({ jsonrpc: "2.0", id: 1, method: "tools/call", params: { name: "capacity", arguments: args } }),
    });
    const body = (await res.json()) as { result: { isError?: boolean; content: { text: string }[] } };
    return { error: body.result.isError === true, text: body.result.content[0]!.text };
  };
  const bare = await call({ key: "cells.egress", value: "report", dryRun: false });
  expect(bare.error).toBe(true);
  expect(bare.text).toContain("reason_required");
  expect(egressSetting(app.db)).toBe("enforce");
  expect((await call({ key: "cells.egress", value: "report", reason: "mcp says why", dryRun: false })).error).toBe(false);
  expect(capacityChanges(app.db)[0]!.reason).toBe("mcp says why");
  expect((await call({ key: "cells.egress", value: "enforce", dryRun: false })).error).toBe(false);
  expect(egressSetting(app.db)).toBe("enforce");
});
@@ -11,7 +11,7 @@
import { createAgent } from "../src/actions/crew.ts";
import { createApp, type App } from "../src/app.ts";
import { listEvents } from "../src/core/events.ts";
import { changeCapacity } from "../src/actions/capacity.ts";
import { CAPACITY_KEYS, capacityDefault, capacityValue } from "../src/core/capacity.ts";
import { CAPACITY_KEYS, capacityChanges, capacityDefault, capacityValue } from "../src/core/capacity.ts";
import { createUser, type User } from "../src/core/users.ts";
import { createForgeApp, forgeCommands } from "../src/tui/forge.ts";
import { capacityScreen } from "../src/tui/screens/capacity.ts";
@@ -98,7 +98,7 @@
describe("tui capacity", () => {
    };
    try {
      expect(await egressShown()).toBe(false);
      expect(changeCapacity(app, carol, "cells.egress", "report").ok).toBe(true);
      expect(changeCapacity(app, carol, "cells.egress", "report", "a test says why").ok).toBe(true);
      expect(await egressShown()).toBe(true);
      expect(changeCapacity(app, carol, "cells.egress", "enforce").ok).toBe(true);
      expect(await egressShown()).toBe(false);
@@ -107,6 +107,36 @@
describe("tui capacity", () => {
    }
  });
  test("cells.egress to report asks why in the terminal, keeps it with who; enforce asks nothing (#10778)", async () => {
    const egress = () => capacityValue(app.db, "cells.egress");
    const h = boot(carol, 60);
    try {
      for (let i = 0; i < CAPACITY_KEYS.indexOf("cells.egress"); i++) await h.press("j");
      await h.press("e");
      for (let i = 0; i < 10; i++) await h.press("backspace");
      await h.press(..."report", "enter");
      expect(h.text()).toContain("Why set cells.egress to report?");
      await h.press("enter");
      expect(h.text()).toContain("Say why");
      await h.press(..."lab move", "enter");
      expect(h.text()).toContain("why: lab move");
      await h.press("left", "enter");
      expect(egress()).toBe("report");
      const kept = capacityChanges(app.db)[0]!;
      expect([kept.actorName, kept.reason]).toEqual(["carol", "lab move"]);
      await h.press("e");
      for (let i = 0; i < 10; i++) await h.press("backspace");
      await h.press(..."enforce", "enter");
      expect(h.text()).not.toContain("Why set");
      await h.press("left", "enter");
      expect(egress()).toBe("enforce");
    } finally {
      h.stop();
      changeCapacity(app, carol, "cells.egress", null);
    }
  });
  test("a crew concurrency below its ceiling is marked, and not at it", async () => {
    const ceiling = capacityDefault("crew.concurrency");
    try {
@@ -285,7 +285,7 @@
describe("tui system: the forge's own state (#7296)", () => {
    await seed({});
    try {
      expect(await systemText(carol)).not.toContain(EGRESS_REPORTED.slice(0, 40));
      expect(changeCapacity(app, carol, "cells.egress", "report").ok).toBe(true);
      expect(changeCapacity(app, carol, "cells.egress", "report", "a test says why").ok).toBe(true);
      const text = await systemText(carol);
      expect(text).toContain("forge 9.8.7 · 0123456 · serving");
      // The dialog clips the sentence at its width; its opening words are one row.
@@ -455,7 +455,7 @@
describe("web pages end to end", () => {
    const { changeCapacity } = await import("../src/actions/capacity.ts");
    const { getUserByName } = await import("../src/core/users.ts");
    const ada = getUserByName(app.db, "ada")!;
    expect(changeCapacity(app, ada, "cells.egress", "report").ok).toBe(true);
    expect(changeCapacity(app, ada, "cells.egress", "report", "a test says why").ok).toBe(true);
    try {
      const text = await (await fetch(base, { headers: { cookie } })).text();
      expect(text).not.toMatch(/class="[^"]*\berror-note/);
		@@ -672,8 +672,10 @@ purpose: a repository admin who is no site admin sees the list read-only on the
672	672	page, and nothing on the terminal screen (no rows, no `g`/`x`).
673	673
674	674	A release that turns egress on must not break an app whose writers have
675		not declared what it uses yet, so the operator can start it reported:
676		`FORGE_CELLS_EGRESS=report` lets an undeclared public host through (on 80
	675	not declared what it uses yet, so an admin can set it reported:
	676	`cells.egress` = `report` on /settings/capacity (or the API's
	677	`PUT /api/v1/admin/capacity/cells.egress` with a `reason`; the change log
	678	keeps who and why) lets an undeclared public host through (on 80
677	679	and 443 only) and
678	680	counts it per repository (`<data>/egress/<repo id>.json`, under the
679	681	forge's data where no cell sees it), and the app's page tells its writers
		@@ -1655,7 +1657,7 @@ a link to the milestone (`docs/PLANNING.md`); its progress never does.
1655	1657	\| `FORGE_CHECK_SHARDS` \| the machine's cores \| test shards per check (live: Settings → Capacity) \|
1656	1658	\| `FORGE_CHECK_CACHE_DAYS` \| `30` \| days a package may go unlent before the check install cache drops it \|
1657	1659	\| `FORGE_CHECK_CACHE_MB` \| `2048` \| size one repository's check install cache is swept down to \|
1658		\| `FORGE_CELLS_EGRESS` \| `enforce` \| `report` lets undeclared egress through on 80/443 (live: Settings → Capacity) \|
	1660	\| `FORGE_CELLS_EGRESS` \| ignored \| logged once at boot; egress is enforced unless an admin sets `cells.egress` (Settings → Capacity), with a reason \|
1659	1661	\| `FORGE_CELL_CGROUP` \| `/sys/fs/cgroup` at a namespace root \| the delegated cgroup v2 whose children cap each cell's memory; `off` watches only \|
1660	1662	\| `FORGE_CREW_CPUS` \| `4` \| cores one crew run may use (`cpu.max` on its own cell cgroup, where the cpu controller is delegated) \|
1661	1663	\| `FORGE_CREW_BUDGET_USD` \| `5` \| spend per run unless the agent says otherwise \|
		@@ -70,7 +70,7 @@ bytes in `tools/list`. After changing a tool run `bun scripts/mcp-table.ts`;
70	70	\| `boards` \| — \| The forge's boards for person admins: slug, title, range, refresh and panels \| 425 \|
71	71	\| `branches` \| `create`, `delete`, `branches`, `tags` \| A repo's branches; `name`, `action` create (from `from`) or delete one, not the default \| 407 \|
72	72	\| `builds` \| — \| A repo's build pins (`refs/builds/`): label, commit, pinned by, note \| 231 \|
73		\| `capacity` \| — \| Forge capacity and guards, live \| 363 \|
	73	\| `capacity` \| — \| Forge capacity and guards, live \| 390 \|
74	74	\| `claim_link` \| — \| A new claim link for an unclaimed child forge, only with `reveal: true`; the old stops \| 289 \|
75	75	\| `close` \| — \| Close or reopen (`state` open) an issue or pull \| 463 \|
76	76	\| `cloud_account` \| — \| Change a cloud account by `verb` (admin) \| 549 \|
		@@ -79,7 +79,7 @@ bytes in `tools/list`. After changing a tool run `bun scripts/mcp-table.ts`;
79	79	\| `confirm_wait` \| — \| Let an issue go ahead though its blocker closed dropped or split \| 269 \|
80	80	\| `contribute` \| — \| For a new agent: what this forge is, its bottleneck, help-wanted issues, how to propose \| 210 \|
81	81	\| `converge` \| — \| Have a fork's crew merge the parent's updates where both changed a file \| 200 \|
82		\| `crew` \| — \| List a repository's crew, or add or remove an agent \| 313 \|
	82	\| `crew` \| — \| List a repository's crew, or add or remove an agent \| 338 \|
83	83	\| `data` \| — \| Read SQLite files you may see: tables, rows, read-only SQL; secrets masked \| 367 \|
84	84	\| `decisions_by` \| — \| Who decides parked hand-over cards: `me`, `decider`, `decider_tell` \| 305 \|
85	85	\| `detach` \| — \| Detach a fork from its parent \| 210 \|
		@@ -89,7 +89,7 @@ bytes in `tools/list`. After changing a tool run `bun scripts/mcp-table.ts`;
89	89	\| `egress_grants` \| — \| Private destinations and grants: list, grant or revoke (site admin) \| 289 \|
90	90	\| `email_verify` \| — \| Send yourself a new verification link \| 126 \|
91	91	\| `events` \| — \| Repository events \| 259 \|
92		\| `explore` \| — \| The apps, people (and, for an admin, forges) you can see, ranked \| 414 \|
	92	\| `explore` \| — \| The apps, people (and, for an admin, forges) you can see, ranked \| 547 \|
93	93	\| `family` \| — \| The forge that sent this one and, for a site admin, those it sent, with state, version \| 205 \|
94	94	\| `features` \| — \| Apps absorbed as forge features: list, read, absorb or un-absorb, change typed settings \| 357 \|
95	95	\| `feed` \| — \| Your ranked home timeline; `cursor` pages; saved filter applies \| 562 \|
		@@ -22,6 +22,8 @@ import {
22	22	type CapacityKey,
23	23	effectiveCapacity,
24	24	followsSpeed,
	25	needsReason,
	26	REASON_MAX,
25	27	} from "../core/capacity.ts";
26	28	import type { EgressTotal } from "../apps/egress.ts";
27	29	import {
		@@ -161,15 +163,23 @@ export function edgeOffDryRun(
161	163	});
162	164	}
163	165
164		/** Set `key` to `value`; `null` or `""` goes back to the boot default. */
	166	/** What a move to report, said without a reason, is told. */
	167	export const REASON_WORDS = "Say why: setting cells.egress to report is kept with who made it and the reason.";
	168
	169	/**
	170	* Set `key` to `value`; `null` or `""` goes back to the boot default.
	171	* `reason` is kept beside who; a move of `cells.egress` to report is refused
	172	* without one (#10778). Tightening (enforce, or back to the default) never is.
	173	*/
165	174	export function changeCapacity(
166	175	app: App,
167	176	actor: User \| undefined,
168	177	key: string,
169	178	value: string \| null,
	179	reason = "",
170	180	): Result<
171	181	{ key: CapacityKey; from: string; to: string },
172		"not_found" \| "no_such_setting" \| "invalid_value" \| "no_credential" \| "derived"
	182	"not_found" \| "no_such_setting" \| "invalid_value" \| "no_credential" \| "derived" \| "reason_required"
173	183	> {
174	184	const who = admin(actor);
175	185	if (!who.ok) return who;
		@@ -180,16 +190,19 @@ export function changeCapacity(
180	190	return err("invalid_value");
181	191	if (key === "signin.edge" && next === "off" && !signsInWithoutEdge(app.db, who.value.id))
182	192	return err("no_credential");
	193	const why = reason.replace(/[\u0000-\u001f\u007f]+/g, " ").trim().slice(0, REASON_MAX);
		sentinelcrew 1d ago outdated Only a change to report should need a reason. As written, enforce and the reset to default are refused without one, which blocks the safe direction (and the page's Put back). Fix: `needsReason(key) && next === "report"`, then test reset and enforce without a reason.
	194	if (needsReason(key) && next === "report" && why === "") return err("reason_required");
183	195	const changed = setCapacity(
184	196	app.db,
185	197	key,
186	198	next === "" ? null : next,
187	199	who.value.id,
	200	why,
188	201	);
189	202	app.bus.append({
190	203	kind: "capacity.changed",
191	204	actorId: who.value.id,
192		payload: { key, from: changed.from, to: changed.to },
	205	payload: { key, from: changed.from, to: changed.to, ...(why === "" ? {} : { reason: why }) },
193	206	});
194	207	return ok({ key, ...changed });
195	208	}
		@@ -241,8 +241,8 @@ export interface CellSpec {
241	241	readonly onRefused?: ((host: string, port: number, isPrivate: boolean) => void) \| undefined;
242	242	/**
243	243	* Refuse undeclared egress, or only report it, for this cell — the
244		* forge's setting when the cell starts (`core/capacity.ts`); the
245		* environment's (`egressMode`) when the caller has none.
	244	* forge's setting when the cell starts (`core/capacity.ts`); enforce
	245	* when the caller has none. The environment never says (#10778).
246	246	*/
247	247	readonly egressMode?: "enforce" \| "report" \| undefined;
248	248	/**
		@@ -274,16 +274,6 @@ export function watchedLimits(limits: Limits, cgroup: { readonly cpuCapped: bool
274	274	return cgroup?.cpuCapped === true ? { ...limits, cpus: Number.POSITIVE_INFINITY } : limits;
275	275	}
276	276
277		/**
278		* Whether undeclared egress is refused (`enforce`, the default) or let
279		* through and reported (`FORGE_CELLS_EGRESS=report`), for a release that
280		* must not break an app before its writers have declared what it uses.
281		* Files, processes and private addresses are held the same in both.
282		*/
283		export function egressMode(): "enforce" \| "report" {
284		return process.env["FORGE_CELLS_EGRESS"] === "report" ? "report" : "enforce";
285		}
286
287	277	export interface Cell {
288	278	/** The argv that runs `command` (through `sh -c`) inside the cell. */
289	279	readonly argv: (command: string) => string[];
		@@ -524,7 +514,8 @@ export function openCell(
524	514	// the forge told its parent's door; a check that boots a forge is not.
525	515	upstream: process.env["FORGE_PARENT_LOCAL"] === undefined ? undefined : upstreamProxy(),
526	516	report:
527		(spec.egressMode ?? egressMode()) === "report"
	517	// Enforce unless the caller carries an admin's report (`egressSetting`, #10778).
	518	spec.egressMode === "report"
528	519	? (host, port) => spec.onUndeclared?.(host, port)
529	520	: undefined,
530	521	},
		@@ -33,7 +33,7 @@ export interface EgressPolicy {
33	33	*/
34	34	readonly granted?: readonly string[] \| undefined;
35	35	/**
36		* Set while egress is only reported (`FORGE_CELLS_EGRESS=report`): an
	36	* Set while egress is only reported (`cells.egress` = `report`, an admin's setting): an
37	37	* undeclared public host is let through and handed here instead of
38	38	* refused. Private addresses are refused either way.
39	39	*/
		@@ -1,6 +1,6 @@
1	1	/**
2	2	* What a repository's code reached without declaring it, while egress is
3		* only reported (`FORGE_CELLS_EGRESS=report`, `apps/contain.ts`): one small
	3	* only reported (`cells.egress` = `report`, `core/capacity.ts`): one small
4	4	* file per repository under `<data>/egress/`, read by the app's page so its
5	5	* writers know what to add to `forge.json` before egress is enforced.
6	6	*/
		@@ -33,7 +33,7 @@ export type CapacityKey =
33	33	interface Definition {
34	34	/** What the settings page and the API call it. */
35	35	readonly label: string;
36		/** The environment variable that is its boot default. */
	36	/** The environment variable that is its boot default; "" for a setting only an admin moves. */
37	37	readonly env: string;
38	38	/** Whole numbers in a range, or one of a few words. */
39	39	readonly kind:
		@@ -100,10 +100,12 @@ export const CAPACITY: Record<CapacityKey, Definition> = {
100	100	},
101	101	"cells.egress": {
102	102	label: "Egress from cells",
103		env: "FORGE_CELLS_EGRESS",
	103	// No environment default: report is a decision an admin makes and the
	104	// change log keeps, never what a deployment's environment says (#10778).
	105	env: "",
104	106	kind: { type: "choice", values: ["enforce", "report"] },
105	107	fallback: "enforce",
106		help: "enforce refuses a host an app or check did not declare; report lets it through on 80 and 443 and lists it on the app's page. Takes effect on the next cell started.",
	108	help: "enforce refuses a host an app or check did not declare; report lets it through on 80 and 443 and lists it on the app's page. Enforce unless an admin sets report here, with a reason. Takes effect on the next cell started.",
		sentinelcrew 1d ago outdated Principles 1 and 8: this help already says what enforce and report do; the added clause and the page's "The default; only an admin moves it." repeat one another. Say it once: "Enforce unless an admin sets report here, with a reason."
107	109	},
108	110	"children.modelEgress": {
109	111	label: "Model provider a child forge cell may reach",
		@@ -178,7 +180,9 @@ export function capacityDefault(key: CapacityKey, cpus?: number): string {
178	180
179	181	/** The environment's value for `key`, when it holds a valid one. */
180	182	function explicitDefault(key: CapacityKey): string \| undefined {
181		const env = process.env[CAPACITY[key].env]?.trim() ?? "";
	183	const name = CAPACITY[key].env;
	184	if (name === "") return undefined;
	185	const env = process.env[name]?.trim() ?? "";
182	186	return env !== "" && validCapacity(key, env) ? env : undefined;
183	187	}
184	188
		@@ -391,11 +395,32 @@ export function maxChildren(db: Database): number {
391	395	return Number(capacityValue(db, "children.max"));
392	396	}
393	397
394		/** The egress mode a cell starts with now. */
	398	/** The egress mode a cell starts with now: enforce unless an admin set report. */
395	399	export function egressSetting(db: Database): "enforce" \| "report" {
396	400	return capacityValue(db, "cells.egress") === "report" ? "report" : "enforce";
397	401	}
398	402
	403	/** The variable that once set the egress mode, and is now only noticed (#10778). */
	404	export const EGRESS_ENV = "FORGE_CELLS_EGRESS";
	405
	406	/**
	407	* The one boot line for an environment that still asks for an egress mode:
	408	* it is ignored, and this says so once, plainly; null when it asks nothing.
	409	*/
	410	export function egressEnvIgnored(env: Record<string, string \| undefined> = process.env): string \| null {
	411	const asked = env[EGRESS_ENV]?.trim() ?? "";
	412	if (asked === "" \|\| asked === "enforce") return null;
	413	return `${EGRESS_ENV}=${asked.slice(0, 32)} is ignored: egress is enforced unless an admin sets cells.egress on /settings/capacity, with a reason`;
	414	}
	415
	416	/** Most characters a change's reason keeps. */
	417	export const REASON_MAX = 500;
	418
	419	/** Keys whose loosening must say why: a move of these to report needs a reason. */
	420	export function needsReason(key: CapacityKey): boolean {
	421	return key === "cells.egress";
	422	}
	423
399	424	/** The model provider hosts a child forge's cell may reach now: none unless an admin chose one. */
400	425	export function childModelHosts(db: Database): readonly string[] {
401	426	return MODEL_HOSTS[capacityValue(db, "children.modelEgress")] ?? [];
		@@ -466,6 +491,8 @@ export interface CapacityChange {
466	491	readonly actorId: string;
467	492	readonly actorName: string;
468	493	readonly at: string;
	494	/** Why, as the admin said it; "" for a change made before reasons were kept. */
	495	readonly reason: string;
469	496	}
470	497
471	498	/**
		@@ -479,6 +506,8 @@ export function setCapacity(
479	506	key: CapacityKey,
480	507	value: string \| null,
481	508	actorId: string,
	509	/** Why, in the admin's words, already cut to REASON_MAX by the action; kept beside who (#10778). */
	510	reason = "",
482	511	): { from: string; to: string } {
483	512	const from = capacityValue(db, key);
484	513	const at = new Date().toISOString();
		@@ -494,9 +523,9 @@ export function setCapacity(
494	523	})();
495	524	const to = capacityValue(db, key);
496	525	db.query(
497		`INSERT INTO forge_setting_change (key, from_value, to_value, actor_id, at)
498		VALUES (?1, ?2, ?3, ?4, ?5)`,
499		).run(key, from, to, actorId, at);
	526	`INSERT INTO forge_setting_change (key, from_value, to_value, actor_id, at, reason)
	527	VALUES (?1, ?2, ?3, ?4, ?5, ?6)`,
	528	).run(key, from, to, actorId, at, reason);
500	529	return { from, to };
501	530	}
502	531
		@@ -511,10 +540,11 @@ export function capacityChanges(db: Database, limit = 20): CapacityChange[] {
511	540	actor_id: string;
512	541	username: string \| null;
513	542	at: string;
	543	reason: string;
514	544	},
515	545	[number]
516	546	>(
517		`SELECT c.key, c.from_value, c.to_value, c.actor_id, u.username, c.at
	547	`SELECT c.key, c.from_value, c.to_value, c.actor_id, u.username, c.at, c.reason
518	548	FROM forge_setting_change c LEFT JOIN user u ON u.id = c.actor_id
519	549	ORDER BY c.at DESC, c.rowid DESC LIMIT ?1`,
520	550	)
		@@ -527,5 +557,6 @@ export function capacityChanges(db: Database, limit = 20): CapacityChange[] {
527	557	actorId: r.actor_id,
528	558	actorName: r.username ?? "",
529	559	at: r.at,
	560	reason: r.reason,
530	561	}));
531	562	}
		@@ -0,0 +1,1 @@
	1	03b5a26202aad083af3b64356cc064faec8f1f275521c22beceef313f3f4612d
		@@ -0,0 +1,5 @@
	1	// A capacity change keeps why beside who (#10778): cells.egress moves to
	2	// report only with a reason, and the change log shows it. Additive.
	3	export default `
	4	ALTER TABLE forge_setting_change ADD COLUMN reason TEXT NOT NULL DEFAULT '';
	5	`;
		@@ -13,7 +13,7 @@ import { kpiProbe } from "../../web/studio/kpi_probe.ts";
13	13	import { MAX_SECONDS, sampleStacks } from "../../perf/sample.ts";
14	14	import { listAccounts, removeAccount, retireAndRemoveAccount, retirementPlan, suspendAccount, unsuspendAccount, verifyAccount } from "../../actions/accounts.ts";
15	15	import { ADMIN_WORDS } from "../../actions/admin_words.ts";
16		import { DERIVED_WORDS, changeCapacity, edgeOffDryRun, listCapacity } from "../../actions/capacity.ts";
	16	import { DERIVED_WORDS, REASON_WORDS, changeCapacity, edgeOffDryRun, listCapacity } from "../../actions/capacity.ts";
17	17	import { changeShield, lastShieldChange, shieldState } from "../../actions/shield.ts";
18	18	import { inviteLink, list as listInviteLinks, mint as mintInviteLink, revoke as revokeInviteLink } from "../../actions/invites.ts";
19	19	import { changeLimit, listLimits } from "../../actions/limits.ts";
		@@ -188,7 +188,8 @@ export function adminRoutes(router: Router<Handler>): void {
188	188	return dry.ok ? json({ dry_run: true, ...dry.value }) : notFound();
189	189	}
190	190	const value = input.value === null ? null : str(input.value);
191		const changed = changeCapacity(ctx.app, ctx.auth.user, ctx.params.key!, value);
	191	const reason = typeof input.reason === "string" ? input.reason : "";
	192	const changed = changeCapacity(ctx.app, ctx.auth.user, ctx.params.key!, value, reason);
192	193	if (changed.ok) return json(changed.value);
193	194	if (changed.error === "not_found") return notFound();
194	195	return apiError(
		@@ -198,7 +199,9 @@ export function adminRoutes(router: Router<Handler>): void {
198	199	? "no such capacity setting"
199	200	: changed.error === "derived"
200	201	? DERIVED_WORDS
201		: SETTING_WORDS.outOfRange,
	202	: changed.error === "reason_required"
	203	? REASON_WORDS
	204	: SETTING_WORDS.outOfRange,
202	205	);
203	206	});
204	207