ad5b9d0 · 5ee5b5b · 5f85fde · c7221e0
@@ -1240,6 +1240,31 @@
memory only: a process is not state, and a restart rebuilds every
environment from the default branch and the open pulls, exactly as
`core/reconcile.ts` rebuilds the index from git.
### A child forge's own filesystem
How to read the line and turn the guard on: [docs/features/child-filesystem.md](features/child-filesystem.md).
A child forge (`/forges`) keeps everything it writes under
`<data>/children/<body id>`. The forge reads `/proc/self/mountinfo` to tell
whether that directory is a filesystem of its own, a mount whose mount point
is exactly that path, and reads its size with `statfs`: blocks × block size
in bytes, and its inodes (`src/spawn/disk_mount.ts`). The forge mounts
nothing itself. Making the filesystem is the platform's job (#10851).
- **On its own filesystem**, writing past its size fails with ENOSPC inside
  the child, and the parent's free space does not change. Its cell binds that
  filesystem by its real path (`cellSpecFor`). On the shared disk, only the
  cell's disk watch stops a child, and only after it has written too much.
- **The child's line** on `/forges` and on the terminal's forges screen says
  `own filesystem, N GiB` (GiB = 2^30 bytes, to one place) or `shared disk`.
- **`children.ownFilesystem`** (Settings → Capacity, or the `capacity` MCP
  tool with `key: "children.ownFilesystem"`) is `off` by default. When it is
  `on`, the forge refuses to start a child with no filesystem of its own,
  whether that child runs in a cell or in this forge's process. The refusal is
  a 503 with one plain line naming the child and saying why. Its pages and its
  apps answer with that line, and the boot skips the child and logs the same
  line. A child that is already running is not stopped.
## Runs
A run row is created `queued`, claimed with a compare-and-swap into
@@ -77,7 +77,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 | 390 |
| `capacity` | — | Forge capacity and guards, live | 415 |
| `claim_link` | `revoke`, `undo` | A child's claim link: `reveal` a new one, or `action` revoke/undo | 304 |
| `close` | — | Close or reopen (`state` open) an issue or pull | 463 |
| `cloud_account` | — | Change a cloud account by `verb` (admin) | 549 |
@@ -0,0 +1,48 @@
# A child forge's own filesystem (#10856)
Everything a child forge writes is kept under `<data>/children/<body id>`. The
forge checks whether that directory is a **filesystem of its own**: a mount
whose mount point is exactly that path in `/proc/self/mountinfo`. The forge
mounts nothing itself. Making that filesystem is the platform's job (#10851).
## What the line means
Each child's line on **`/forges`** and on the terminal's **Forges you sent**
screen (ctrl-k) ends with one of:
- **`own filesystem, N GiB`**: the child's data has a filesystem of its own.
  N is `statfs` blocks × block size, in GiB (2^30 bytes), to one place.
  Writing past that size fails with ENOSPC inside the child, and the parent's
  free space stays the same. The child's cell binds that filesystem by its
  real path.
- **`shared disk`**: the child's data sits on the disk this forge and its
  other children share. Only the cell's disk watch stops it, and only after it
  has written too much.
## Requiring one: `children.ownFilesystem`
The setting is `off` by default. To turn it on, use one of:
- **Settings → Capacity**: set "Child forges need a filesystem of their own"
  to `on`.
- **The terminal's Capacity screen**: press `e` on `children.ownFilesystem`.
- **The `capacity` MCP tool**:
  `{ "key": "children.ownFilesystem", "value": "on", "reason": "…", "dryRun": false }`.
  The value `""` puts back the default.
While it is on, the forge does not start a child that has no filesystem of its
own. This applies whether the child runs in a cell or in this forge's process.
The forge reads the setting on every start, and a child that is already
running is not stopped.
## What the refusal says
The child's pages and its apps answer **503**, `text/plain`, with one line:
> kid was not started: its data is on the shared disk, not a filesystem of its own, and this forge requires one (children.ownFilesystem is on).
The boot skips that child and logs the same line as `child forge not started`.
Code: `src/spawn/disk_mount.ts` (reading the mounts), `startRefused` in
`src/spawn/host.ts`, and `launchSpecFor` in `src/spawn/cell.ts`. Tests:
`test/disk-mount.test.ts`.
@@ -42,7 +42,7 @@
import { err, ok, type Result } from "../kernel/result.ts";
/** What a refused change to a dial that follows Speed says, on every door. */
export const DERIVED_WORDS = "The pace floor and the queue depth follow Speed: change Speed (crew.concurrency) and they move with it.";
/** The six guards a caller may set by `key`: the MCP tool's enum and the terminal's `e`. */
/** The guards a caller may set by `key`: the MCP tool's enum and the terminal's `e`. */
export const SETTABLE_CAPACITY = [
  "crew.concurrency",
  "checks.concurrency",
@@ -50,6 +50,7 @@
export const SETTABLE_CAPACITY = [
  "cells.egress",
  "guard_new_accounts",
  "signin.edge",
  "children.ownFilesystem",
] as const satisfies readonly CapacityKey[];
export interface CapacityRow {
@@ -26,6 +26,7 @@
export type CapacityKey =
  | "cells.egress"
  | "children.modelEgress"
  | "children.registryEgress"
  | "children.ownFilesystem"
  | "guard_new_accounts"
  | "signin.edge"
  | "pace.floor";
@@ -121,6 +122,14 @@
export const CAPACITY: Record<CapacityKey, Definition> = {
    fallback: "off",
    help: "off keeps a child forge's cell from the package registries, so its checks cannot fill their install cache; npm also lets it reach registry.npmjs.org on 443; build opens the hosts ordinary app builds fetch from, on 443 alone: npm and yarn, PyPI, GitHub (git dependencies and release tarballs), crates.io and the Go module proxy. Nothing else opens, and the cell enforces this even when cells.egress is report. Takes effect on the next child cell started.",
  },
  "children.ownFilesystem": {
    label: "Child forges need a filesystem of their own",
    // No environment default: refusing children is an admin's decision.
    env: "",
    kind: { type: "choice", values: ["off", "on"] },
    fallback: "off",
    help: "on refuses to start a child forge whose data directory (<data>/children/<id>) is not a filesystem of its own, so no child can fill the disk this forge and its other children share; the refusal names the child and says why. off starts it on the shared disk, held only by its cell's disk watch. Off by default, because a forge mounts nothing itself: turn it on once the platform mounts one per child. A child already running is not stopped. Read on every start.",
  },
  "guard_new_accounts": {
    label: "New-account repository guard",
    env: "FORGE_GUARD_NEW_ACCOUNTS",
@@ -434,6 +443,11 @@
const MODEL_HOSTS: Readonly<Record<string, readonly string[]>> = {
  both: ["openrouter.ai:443", "api.anthropic.com:443"],
};
/** Whether a child forge must have a filesystem of its own to start (`children.ownFilesystem`); off by default. */
export function childNeedsOwnFilesystem(db: Database): boolean {
  return capacityValue(db, "children.ownFilesystem") === "on";
}
/** The package registry a child forge cell may reach (`children.registryEgress`); none by default. */
export function childRegistryHosts(db: Database): readonly string[] {
  const value = capacityValue(db, "children.registryEgress");
@@ -5,7 +5,7 @@
import { good, bad, type Tool } from "../shared.ts";
export const tool: Tool = {
  name: "capacity",
  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",
  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, whether a child forge needs its own filesystem, 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 seven 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: {
@@ -578,6 +578,7 @@
import {
  hostedChildOpen,
  resolveHostedChild,
  resolveHostedChildApp,
  refusedResponse,
  socketToCell,
  wakeGate,
  watchHostedChildClose,
@@ -2571,6 +2572,7 @@
export async function serve(app: App): Promise<Servers> {
      if (hit === "unknown")
        return securityFloor(new Response("not found", { status: 404 }));
      if (hit !== undefined) {
        if ("refused" in hit) return securityFloor(refusedResponse(hit.refused));
        if ("cell" in hit) return fromCell(hit.cell);
        notePeer(request, server.requestIP(request)?.address, trust);
        return proxyApp(hit.runtime, request, hit.target, server);
@@ -23,6 +23,7 @@
import { hostedPlacement, parentOrigin, childPublicUrl, type BodyStore, type Pla
import { SIZE_IO, SIZES, type Size } from "./sizes.ts";
import { CGROUP_DIR_ENV, SIZE_ENV } from "./usage.ts";
import { childModelHosts, childRegistryHosts } from "../core/capacity.ts";
import { liveChildDisk, type ChildDisk } from "./disk_mount.ts";
export const CELL_PREFIX = "cell-";
export const ownsBody = (bodyId: string): boolean => bodyId.startsWith(CELL_PREFIX);
@@ -116,10 +117,18 @@
export function cellSpecFor(input: {
  modelHosts?: readonly string[];
  /** The package registry an admin let children reach (`children.registryEgress`); none by default. */
  registryHosts?: readonly string[];
  /**
   * The child's writable space as found (`spawn/disk_mount.ts`). A filesystem
   * of its own is named among the binds by its real path (bwrap binds
   * recursively, and `openCell` binds a path once), so a data directory
   * reached through a symlink still writes to it; with none, the cell is
   * what it always was.
   */
  disk?: ChildDisk;
}): CellSpec {
  return {
    dir: input.dir,
    writable: [],
    writable: input.disk?.own === true ? [input.disk.path] : [],
    home: join(input.dir, ".home"),
    // The parent's data and home are what a child must not see: the home holds
    // the parent crew's sessions and model login, and the child runs as the
@@ -224,6 +233,33 @@
async function answers(port: number, gone: Promise<unknown>): Promise<boolean> {
  return false;
}
/**
 * The cell a child forge is launched in, from what the parent holds now: its
 * egress settings and its data directory as found (`liveChildDisk`), so a
 * child with a filesystem of its own has it bound. `mountinfo` is this
 * process's unless a test passes its own.
 */
export function launchSpecFor(
  parent: App,
  input: { readonly bodyId: string; readonly name: string; readonly size: Size },
  at: { readonly port: number; readonly parentPort: number },
  mountinfo?: string,
): CellSpec {
  return cellSpecFor({
    dir: childDirOf(parent, input.bodyId),
    parentDataDir: parent.config.dataDir,
    parentUrl: parentOrigin(parent.config),
    url: childPublicUrl(input.name, parentOrigin(parent.config)),
    parentPort: at.parentPort,
    size: input.size,
    port: at.port,
    label: `forge:${input.name}`,
    modelHosts: childModelHosts(parent.db),
    registryHosts: childRegistryHosts(parent.db),
    disk: liveChildDisk(parent.config.dataDir, input.bodyId, mountinfo),
  });
}
function makeRegistry(parent: App): CellChildren {
  const held = new Map<string, Held>();
  const starting = new Map<string, Promise<CellChild | undefined>>();
@@ -248,18 +284,7 @@
function makeRegistry(parent: App): CellChildren {
    const url = childPublicUrl(input.name, parentOrigin(parent.config));
    const door = openBeatDoor(parent);
    const parentPort = door.port;
    const spec = cellSpecFor({
      dir,
      parentDataDir: parent.config.dataDir,
      parentUrl: parentOrigin(parent.config),
      url,
      parentPort,
      size: input.size,
      port,
      label: `forge:${input.name}`,
      modelHosts: childModelHosts(parent.db),
      registryHosts: childRegistryHosts(parent.db),
    });
    const spec = launchSpecFor(parent, input, { port, parentPort });
    const heard = childLog((line) => parent.log.info("child forge", { name: input.name, line }));
    const log = (raw: string): void => {
      const line = plainLine(raw);
@@ -9,6 +9,7 @@
 * list never waits on, or fails for, one forge that is down.
 */
import { liveChildDisk, readMountinfo, type ChildDisk } from "./disk_mount.ts";
import type { App } from "../app.ts";
import { childDirOf, listChildren, statusTokenOf, type Child } from "../actions/spawn.ts";
import { timingSafeEqual } from "node:crypto";
@@ -62,6 +63,8 @@
export interface ClientRow {
  readonly size: Size;
  /** What it uses against that size: its cell's reading, or "shared" when it is hosted here. */
  readonly use: ForgeUse;
  /** Whether its data is a filesystem of its own, and that filesystem's size (`spawn/disk_mount.ts`). */
  readonly disk: ChildDisk;
  /** When its last heartbeat reached this forge, ISO; null when none has. */
  readonly lastHeartbeatAt: string | null;
  /** The first step its person has not taken, read from the child's heartbeat. */
@@ -220,6 +223,8 @@
export async function clientRows(app: App): Promise<ClientRow[]> {
    }),
  );
  const beats = await Promise.all(children.map((c) => lastHeard(app, c.name)));
  // One read of the mount table for every row.
  const mountinfo = children.length === 0 ? "" : readMountinfo();
  return orderRows(
    children.map((c, i) => ({
      name: c.name,
@@ -238,6 +243,7 @@
export async function clientRows(app: App): Promise<ClientRow[]> {
      ...creditView(app, c.name),
      size: c.size,
      use: forgeUse(c, childDirOf(app, c.bodyId)),
      disk: liveChildDisk(app.config.dataDir, c.bodyId, mountinfo),
      lastHeartbeatAt: beats[i] === undefined ? null : new Date(beats[i]!.receivedAt).toISOString(),
      link: states[i]?.link ?? null,
      nextStep: nextStepOf(states[i]?.claimed ?? null, beats[i]?.beat),
@@ -0,0 +1,143 @@
/**
 * Whether a child forge's writable space, `<data>/children/<id>`, is a
 * filesystem of its own: a mount whose mount point is exactly that
 * directory, read from `/proc/self/mountinfo` (proc(5)). On one, writing
 * past its size is ENOSPC inside the child and the parent's free space does
 * not move; on the shared disk only the cell's disk watch stops it, after
 * the fact (#10851). This module reads what is mounted; it mounts nothing.
 *
 * Plain data in, plain data out: the mountinfo is passed in as text and the
 * size read through `stat`, so a test feeds both.
 */
import { readFileSync, realpathSync, statfsSync } from "node:fs";
import { join } from "node:path";
/** One line of mountinfo, the fields this module reads. */
export interface Mount {
  /** Field 5: where it is mounted, its octal escapes (`\040` is a space) undone. */
  readonly mountPoint: string;
  /** The first field after ` - `: ext4, xfs, overlay, tmpfs… */
  readonly fsType: string;
}
/** A child's writable space as the forge finds it. */
export type ChildDisk =
  | { readonly own: true; readonly path: string; readonly fsType: string; readonly bytes: number; readonly inodes: number }
  | { readonly own: false; readonly path: string };
/** What `statfs(2)` says of a filesystem, the fields read here. */
export interface FsSize {
  /** Block size in bytes (`f_bsize`). */
  readonly bsize: number;
  /** Total blocks (`f_blocks`). */
  readonly blocks: number;
  /** Total inodes (`f_files`). */
  readonly files: number;
}
/** A body id is one path segment: letters, digits, `.`, `_`, `-`; a first character other than `.` rules out `.` and `..`. */
const BODY_ID = /^[A-Za-z0-9_-][A-Za-z0-9._-]{0,127}$/;
export const validBodyId = (id: string): boolean => BODY_ID.test(id);
/** Undo mountinfo's octal escapes: space, tab, newline and backslash are written `\ooo`. */
const unescape = (field: string): string => field.replace(/\\([0-7]{3})/g, (_, o: string) => String.fromCharCode(parseInt(o, 8)));
/**
 * Every mount in a mountinfo text. A line reads
 * `36 35 98:0 /mnt1 /mnt/parent rw,noatime master:1 - ext3 /dev/root rw`:
 * mount point fifth, then optional fields up to a lone `-`, then the type. A line that does not have that shape is skipped.
 */
export function parseMountinfo(text: string): Mount[] {
  const mounts: Mount[] = [];
  for (const line of text.split("\n")) {
    const fields = line.split(" ");
    const dash = fields.indexOf("-", 6);
    if (fields.length < 7 || dash < 0) continue;
    const mountPoint = fields[4];
    const fsType = fields[dash + 1];
    if (mountPoint === undefined || fsType === undefined || !mountPoint.startsWith("/")) continue;
    mounts.push({ mountPoint: unescape(mountPoint), fsType });
  }
  return mounts;
}
/** The mount whose mount point is exactly `path` (the last one, as the kernel stacks them); undefined when none. */
export function mountAt(mounts: readonly Mount[], path: string): Mount | undefined {
  const want = path.length > 1 ? path.replace(/\/+$/, "") : path;
  let found: Mount | undefined;
  for (const m of mounts) if (m.mountPoint === want) found = m;
  return found;
}
/**
 * The child's writable space: its own filesystem with its size in bytes
 * (blocks × block size) and inodes, or the shared disk. `path` is where the
 * mount must sit, already resolved (`childDiskPath`). A filesystem whose size
 * cannot be read is not counted as the child's own.
 */
export function childDisk(input: { path: string; mountinfo: string; size: (path: string) => FsSize | undefined }): ChildDisk {
  const mount = mountAt(parseMountinfo(input.mountinfo), input.path);
  if (mount === undefined) return { own: false, path: input.path };
  const fs = input.size(input.path);
  if (fs === undefined || !(fs.bsize > 0) || !(fs.blocks > 0)) return { own: false, path: input.path };
  return { own: true, path: input.path, fsType: mount.fsType, bytes: fs.blocks * fs.bsize, inodes: fs.files };
}
/** `<data>/children/<id>`, symlinks resolved (mountinfo names real paths); the joined path when it does not exist yet. */
export function childDiskPath(dataDir: string, bodyId: string): string | undefined {
  if (!validBodyId(bodyId)) return undefined;
  const path = join(dataDir, "children", bodyId);
  try {
    return realpathSync(path);
  } catch {
    return path;
  }
}
/** This process's mountinfo; "" where there is none (not Linux), which reads as no mount at all. */
export function readMountinfo(): string {
  try {
    return readFileSync("/proc/self/mountinfo", "utf8");
  } catch {
    return "";
  }
}
/** `statfs` of `path`; undefined when it cannot be read. */
export function statSize(path: string): FsSize | undefined {
  try {
    const s = statfsSync(path);
    return { bsize: Number(s.bsize), blocks: Number(s.blocks), files: Number(s.files) };
  } catch {
    return undefined;
  }
}
/** The live answer for one child: this process's mounts, the real `statfs`. */
export function liveChildDisk(dataDir: string, bodyId: string, mountinfo: string = readMountinfo()): ChildDisk {
  const path = childDiskPath(dataDir, bodyId);
  return path === undefined ? { own: false, path: join(dataDir, "children") } : childDisk({ path, mountinfo, size: statSize });
}
const GIB = 1024 ** 3;
/** GiB to one place, the `.0` dropped: 10 GiB is 10 737 418 240 bytes. */
export function gib(bytes: number): string {
  const n = Math.round((bytes / GIB) * 10) / 10;
  return Number.isInteger(n) ? String(n) : n.toFixed(1);
}
/** The words a child's line carries: `own filesystem, N GiB` or `shared disk`. */
export function diskWords(disk: ChildDisk): string {
  return disk.own ? `own filesystem, ${gib(disk.bytes)} GiB` : "shared disk";
}
/**
 * Why a child may not start, in one plain line; undefined when it may. Only
 * when the forge requires a filesystem of its own (`children.ownFilesystem`).
 */
export function startRefusal(name: string, disk: ChildDisk, required: boolean): string | undefined {
  if (!required || disk.own) return undefined;
  return `${name} was not started: its data is on the shared disk, not a filesystem of its own, and this forge requires one (children.ownFilesystem is on).`;
}
@@ -25,6 +25,8 @@
import {
import { DEFAULT_SIZE, isSize, type Size } from "./sizes.ts";
import { cellChildren, forward, forwardSocket, type CellChild } from "./cell.ts";
import { cellsAvailable } from "../apps/contain.ts";
import { childNeedsOwnFilesystem } from "../core/capacity.ts";
import { liveChildDisk, startRefusal } from "./disk_mount.ts";
import { limitValue } from "../settings/limits.ts";
import { awakeRefusal, idleAfterMs, WakeRate } from "./sleep.ts";
import { wakingResponse } from "../web/pages/waking.ts";
@@ -252,6 +254,27 @@
function keepSweeping(parent: App): void {
const carriesCredentials = (parent: App, bodyId: string, request: Request): boolean =>
  vouched(childDirOf(parent, bodyId), request, caches.get(parent)?.get(bodyId)?.db);
/**
 * Why the child `ledger` names may not start now, in one plain line;
 * undefined when it may. Only `children.ownFilesystem` refuses: a child whose
 * data is not a filesystem of its own. The setting is read first, so with it
 * off a start costs no mountinfo read.
 */
export function startRefused(parent: App, ledger: { readonly name: string; readonly bodyId: string }): string | undefined {
  if (!childNeedsOwnFilesystem(parent.db)) return undefined;
  const why = startRefusal(ledger.name, liveChildDisk(parent.config.dataDir, ledger.bodyId), true);
  if (why !== undefined) parent.log.warn("child forge not started", { name: ledger.name, why });
  return why;
}
/** The answer to a request for a child that may not start: the line, as text, 503. */
export function refusedResponse(why: string): Response {
  return new Response(`${why}\n`, {
    status: 503,
    headers: { "content-type": "text/plain; charset=utf-8", "cache-control": "no-store" },
  });
}
/**
 * Before a child's Host is answered: a child already awake is marked busy (by a
 * request whose session or token the child verifies, so a stranger cannot keep it awake); one
@@ -274,6 +297,9 @@
export function wakeGate(parent: App, request: Request): Response | undefined {
    }
    return undefined;
  }
  // Asleep, so answering would start it: not where it has no filesystem of its own and one is required.
  const refused = startRefused(parent, ledger);
  if (refused !== undefined) return refusedResponse(refused);
  // A wake already granted (a cell takes a moment to answer) is one wake, not one per request.
  let reserved = waking.get(parent);
  if (!reserved) waking.set(parent, (reserved = new Map()));
@@ -444,6 +470,7 @@
function openOnce(parent: App, ledger: ChildLedger): Promise<App> | App {
export async function bootHostedChild(parent: App, name: string): Promise<void> {
  let ledger = readLedgerSync(parent, name);
  if (ledger === undefined || !ledger.done) return;
  if (!isAwakeBody(parent, ledger.bodyId) && startRefused(parent, ledger) !== undefined) return;
  if (ledger.placement === "cell") {
    if ((await settleCell(parent, ledger)) !== undefined) return;
    ledger = { ...ledger, placement: "hosted" };
@@ -484,6 +511,11 @@
export interface ChildAppHit {
  readonly target: AppTarget;
}
/** A child app whose forge may not start (`startRefused`): the line it is answered with. */
export interface RefusedHit {
  readonly refused: string;
}
/** A child app in a child's own cell: its runtime is in that process, so the request is carried there. */
export interface CellAppHit {
  readonly cell: string;
@@ -497,7 +529,7 @@
export interface CellAppHit {
export async function resolveHostedChildApp(
  parent: App,
  request: Request,
): Promise<ChildAppHit | CellAppHit | "unknown" | undefined> {
): Promise<ChildAppHit | CellAppHit | RefusedHit | "unknown" | undefined> {
  const host = request.headers.get("host");
  if (host === null) return undefined;
  const label = parseHostedChildAppLabel(host, childHost(parent));
@@ -513,6 +545,10 @@
export async function resolveHostedChildApp(
    if (!CHILD_NAME.test(name)) continue;
    const ledger = readLedgerSync(parent, name);
    if (ledger === undefined || !ledger.done) continue;
    if (!isAwakeBody(parent, ledger.bodyId)) {
      const refused = startRefused(parent, ledger);
      if (refused !== undefined) return { refused };
    }
    if (ledger.placement === "cell") return { cell: name };
    const child = await openOnce(parent, ledger);
    const runtime = appsRuntime(child);
@@ -13,6 +13,7 @@
import { card } from "../ui/widgets.ts";
import { drawFacts, runAsync } from "./common.ts";
import type { PaletteEntry } from "./entries.ts";
import { clientRows } from "../../spawn/clients.ts";
import { diskWords } from "../../spawn/disk_mount.ts";
import { changeLink, removeForge, stopForge } from "../../spawn/manage.ts";
import { undoable, type LinkInfo } from "../../spawn/claim.ts";
import { confirmScreen, pickerScreen } from "./common.ts";
@@ -23,7 +24,7 @@
export function forgeLines(rows: readonly ClientRow[]): [string, string][] {
  if (rows.length === 0) return [["", "You have not sent a forge yet"]];
  return rows.flatMap((r): [string, string][] => [[
    r.name,
    [r.made ? (r.awake === true ? "awake" : "asleep") : null, r.attention === null ? null : ATTENTION_WORDS[r.attention], r.for === null ? null : `for ${r.for}`, CLAIM_WORDS[claimState(r)], linkWords(r.link), runningWords(r), r.nextStep.words, spendWords(r)?.words ?? null, creditWords(r), useLine(r.size, r.use), r.lastHeartbeatAt === null ? "no heartbeat yet" : `heartbeat ${timeAgo(r.lastHeartbeatAt)}`]
    [r.made ? (r.awake === true ? "awake" : "asleep") : null, r.attention === null ? null : ATTENTION_WORDS[r.attention], r.for === null ? null : `for ${r.for}`, CLAIM_WORDS[claimState(r)], linkWords(r.link), runningWords(r), r.nextStep.words, spendWords(r)?.words ?? null, creditWords(r), useLine(r.size, r.use), r.made ? diskWords(r.disk) : null, r.lastHeartbeatAt === null ? "no heartbeat yet" : `heartbeat ${timeAgo(r.lastHeartbeatAt)}`]
      .filter((m): m is string => m !== null)
      .join(" · "),
  ], ...addressLines(r)]);
@@ -18,6 +18,7 @@
import { readForm } from "../form.ts";
import { badge, btn, row, time } from "../ui.ts";
import { noRoom } from "../../spawn/door.ts";
import { sizeWords, useWords } from "../../spawn/usage.ts";
import { diskWords } from "../../spawn/disk_mount.ts";
import { listChildren } from "../../actions/spawn.ts";
import { removeForge, stopForge, type Managed } from "../../spawn/manage.ts";
import { claimLinkBody } from "./new-forge.ts";
@@ -42,7 +43,7 @@
function spendNote(r: ClientRow): Html | null {
    : html`<span data-spend="ok">${s.words}</span>`;
}
function forgeRow(r: ClientRow, now: number): Html {
export function forgeRow(r: ClientRow, now: number): Html {
  const state = claimState(r);
  const meta = [
    r.for === null ? null : html`for ${r.for}`,
@@ -50,6 +51,7 @@
function forgeRow(r: ClientRow, now: number): Html {
    state === "unknown" ? html`it did not answer just now` : null,
    r.made ? badge(r.awake === true ? "awake" : "asleep", r.awake === true ? { tone: "success" } : { variant: "outline" }) : null,
    r.made ? html`${sizeWords(r.size)}` : null,
    r.made ? html`<span data-disk="${r.disk.own ? "own" : "shared"}">${diskWords(r.disk)}</span>` : null,
    runningNote(r),
    spendNote(r),
    creditWords(r) === null ? null : html`<span data-credit>${creditWords(r)}</span>`,
@@ -0,0 +1,252 @@
/**
 * #10856: the forge knows whether a child forge's writable space is a
 * filesystem of its own, binds it into the child's cell, says so on the
 * child's line, and refuses to start a child without one when an admin asks.
 */
import { afterAll, describe, expect, test } from "bun:test";
import { mkdirSync, mkdtempSync, realpathSync, rmSync, writeFileSync } from "node:fs";
import { tmpdir } from "node:os";
import { join } from "node:path";
import { createApp, type App } from "../src/app.ts";
import { createUser } from "../src/core/users.ts";
import { capacityValue, childNeedsOwnFilesystem, setCapacity } from "../src/core/capacity.ts";
import { childDisk, diskWords, gib, mountAt, parseMountinfo, startRefusal, validBodyId, type FsSize } from "../src/spawn/disk_mount.ts";
import { cellSpecFor, launchSpecFor } from "../src/spawn/cell.ts";
import { bootHostedChild, childAwake, resolveHostedChildApp, sleepChild, startRefused, wakeGate } from "../src/spawn/host.ts";
import { childDirOf, spawnForge } from "../src/actions/spawn.ts";
import { hostedPlacement } from "../src/spawn/placement.ts";
import { forgeRow } from "../src/web/pages/forges.ts";
import { forgeLines } from "../src/tui/screens/forges.ts";
import { tool as capacityTool } from "../src/http/mcp/tools/capacity.ts";
import type { ClientRow } from "../src/spawn/clients.ts";
import { quietLogs } from "./helpers/globals.ts";
quietLogs();
const tmp = mkdtempSync(join(tmpdir(), "disk-mount-"));
afterAll(() => rmSync(tmp, { recursive: true, force: true }));
// Two real lines in proc(5)'s shape: the root, and a child's own ext4 at /d/children/c1.
const ROOT = "22 1 259:2 / / rw,relatime shared:1 - ext4 /dev/nvme0n1p2 rw";
const OWN = "731 22 7:3 / /d/children/c1 rw,nosuid,nodev,relatime shared:401 - ext4 /dev/loop3 rw";
// 10 GiB of 4 KiB blocks: 2 621 440 × 4096 = 10 737 418 240 bytes; 655 360 inodes.
const TEN_GIB: FsSize = { bsize: 4096, blocks: 2_621_440, files: 655_360 };
const sized = (fs: FsSize | undefined) => () => fs;
describe("a child's writable space, read from mountinfo", () => {
  test("a mount exactly at <data>/children/<id> is its own filesystem, with its size in bytes and inodes", () => {
    const disk = childDisk({ path: "/d/children/c1", mountinfo: `${ROOT}\n${OWN}\n`, size: sized(TEN_GIB) });
    expect(disk).toEqual({ own: true, path: "/d/children/c1", fsType: "ext4", bytes: 10_737_418_240, inodes: 655_360 });
    expect(diskWords(disk)).toBe("own filesystem, 10 GiB");
  });
  test("without the mount it is the shared disk", () => {
    const disk = childDisk({ path: "/d/children/c1", mountinfo: `${ROOT}\n`, size: sized(TEN_GIB) });
    expect(disk).toEqual({ own: false, path: "/d/children/c1" });
    expect(diskWords(disk)).toBe("shared disk");
  });
  test("a mount above it, beside it or below it is not its own", () => {
    const near = [
      "40 22 7:4 / /d/children rw - ext4 /dev/loop4 rw",
      "41 22 7:5 / /d/children/c10 rw - ext4 /dev/loop5 rw",
      "42 22 7:6 / /d/children/c1/sub rw - ext4 /dev/loop6 rw",
    ].join("\n");
    expect(childDisk({ path: "/d/children/c1", mountinfo: `${ROOT}\n${near}`, size: sized(TEN_GIB) }).own).toBe(false);
  });
  test("a mount whose size cannot be read is not counted as its own", () => {
    expect(childDisk({ path: "/d/children/c1", mountinfo: OWN, size: sized(undefined) }).own).toBe(false);
    expect(childDisk({ path: "/d/children/c1", mountinfo: OWN, size: sized({ bsize: 4096, blocks: 0, files: 0 }) }).own).toBe(false);
  });
  test("octal escapes in a mount point are undone, optional fields skipped, junk lines ignored", () => {
    const text = "50 22 7:7 / /d/my\\040data/children/c1 rw shared:9 master:2 - xfs /dev/loop7 rw\nnot a mount line\n\n";
    const mounts = parseMountinfo(text);
    expect(mounts).toEqual([{ mountPoint: "/d/my data/children/c1", fsType: "xfs" }]);
    expect(mountAt(mounts, "/d/my data/children/c1/")?.fsType).toBe("xfs");
  });
  test("GiB to one place: 1.5 GiB is 1 610 612 736 bytes", () => {
    expect(gib(1_610_612_736)).toBe("1.5");
    expect(gib(10 * 1024 ** 3)).toBe("10");
  });
  test("a body id is one path segment", () => {
    expect(validBodyId("cell-01abc")).toBe(true);
    for (const bad of ["..", ".", "a/b", "", "../x", "a\nb"]) expect(validBodyId(bad)).toBe(false);
  });
});
describe("the child's cell", () => {
  const base = { dir: "/d/children/c1", parentDataDir: "/d", parentHome: "/home/f", parentUrl: "https://f.test", size: "small", port: 4100, label: "forge:kid" } as const;
  test("binds its own filesystem when it has one", () => {
    const spec = cellSpecFor({ ...base, disk: { own: true, path: "/mnt/kids/c1", fsType: "ext4", bytes: 1, inodes: 1 } });
    expect(spec.writable).toEqual(["/mnt/kids/c1"]);
  });
  test("with no mount is exactly what it was", () => {
    expect(cellSpecFor({ ...base, disk: { own: false, path: "/d/children/c1" } })).toEqual(cellSpecFor(base));
    expect(cellSpecFor(base).writable).toEqual([]);
  });
});
describe("children.ownFilesystem", () => {
  const made: App[] = [];
  afterAll(() => {
    for (const app of made) app.close();
  });
  const parentWith = (name: string): App => {
    const dataDir = join(tmp, name);
    const app = createApp({ dataDir, url: "https://forge.test" });
    made.push(app);
    mkdirSync(join(dataDir, "spawn"), { recursive: true });
    mkdirSync(join(dataDir, "children", "body-kid"), { recursive: true });
    writeFileSync(join(dataDir, "spawn", "kid.json"), JSON.stringify({ name: "kid", bodyId: "body-kid", done: true, placement: "hosted" }));
    return app;
  };
  test("the line names the child and says why, and is nothing when one is not required or there is one", () => {
    const own = { own: true, path: "/d/children/c1", fsType: "ext4", bytes: 1, inodes: 1 } as const;
    const shared = { own: false, path: "/d/children/c1" } as const;
    const line = startRefusal("kid", shared, true)!;
    expect(line).toContain("kid was not started");
    expect(line).toContain("not a filesystem of its own");
    expect(line.includes("\n")).toBe(false);
    expect(startRefusal("kid", shared, false)).toBeUndefined();
    expect(startRefusal("kid", own, true)).toBeUndefined();
  });
  test("off by default: a child on the shared disk starts", () => {
    const parent = parentWith("off");
    expect(capacityValue(parent.db, "children.ownFilesystem")).toBe("off");
    expect(startRefused(parent, { name: "kid", bodyId: "body-kid" })).toBeUndefined();
    expect(wakeGate(parent, new Request("https://forge.test/", { headers: { host: "kid--forge.test" } }))).toBeUndefined();
  });
  test("on: a child on the shared disk is refused, its page and its apps answer the line", async () => {
    const parent = parentWith("on");
    setCapacity(parent.db, "children.ownFilesystem", "on", "system");
    expect(childNeedsOwnFilesystem(parent.db)).toBe(true);
    const page = wakeGate(parent, new Request("https://forge.test/", { headers: { host: "kid--forge.test" } }));
    expect(page?.status).toBe(503);
    expect(page?.headers.get("content-type")).toContain("text/plain");
    const said = await page!.text();
    expect(said).toContain("kid was not started");
    expect(said.trim().split("\n")).toHaveLength(1);
    const app = await resolveHostedChildApp(parent, new Request("https://forge.test/", { headers: { host: "shop--kid--forge.test" } }));
    expect(app !== undefined && typeof app === "object" && "refused" in app ? app.refused : "").toContain("kid was not started");
  });
  test("the capacity MCP tool reads and writes it", async () => {
    const parent = parentWith("mcp");
    const made = await createUser(parent.db, { origin: "seed", trusted: true, username: "alice", email: "[email protected]", isAdmin: true });
    if (!made.ok) throw new Error("no admin");
    const admin = made.value;
    const ctx = { app: parent, auth: { user: admin, scope: "admin" }, request: new Request("https://forge.test/mcp") } as never;
    const listed = await capacityTool.run(ctx, admin, {});
    expect(JSON.stringify(listed)).toContain("children.ownFilesystem");
    // Read, never matched with an asymmetric matcher: bun's toMatchObject writes the matcher into the
    // object it is given, and this schema is the tool's own, shared with test/mcp-table.test.ts.
    const keys = (capacityTool.inputSchema as { properties: { key: { enum: readonly string[] } } }).properties.key.enum;
    expect([...keys]).toContain("children.ownFilesystem");
    const set = await capacityTool.run(ctx, admin, { key: "children.ownFilesystem", value: "on", dryRun: false });
    expect(set.ok).toBe(true);
    expect(childNeedsOwnFilesystem(parent.db)).toBe(true);
    await capacityTool.run(ctx, admin, { key: "children.ownFilesystem", value: "", dryRun: false });
    expect(childNeedsOwnFilesystem(parent.db)).toBe(false);
  });
});
describe("the child's line", () => {
  const row = (over: Partial<ClientRow>): ClientRow => ({
    name: "kid",
    url: "https://kid--forge.test",
    for: null,
    apps: [],
    sentAt: null,
    made: true,
    claimed: true,
    lastActivityAt: null,
    running: null,
    reach: null,
    link: null,
    attention: null,
    spendTodayUsd: null,
    ceilingUsd: null,
    size: "small",
    use: { kind: "shared" },
    disk: { own: false, path: "/d/children/c1" },
    lastHeartbeatAt: null,
    nextStep: { key: "unreported", words: "has not reported yet", lastTellAt: null },
    ...over,
  });
  test("reads own filesystem, N GiB or shared disk on /forges and in the terminal", () => {
    const own = row({ disk: { own: true, path: "/d/children/c1", fsType: "ext4", bytes: 10 * 1024 ** 3, inodes: 1 } });
    expect(String(forgeRow(own, Date.now()))).toContain(`<span data-disk="own">own filesystem, 10 GiB</span>`);
    expect(String(forgeRow(row({}), Date.now()))).toContain(`<span data-disk="shared">shared disk</span>`);
    expect(forgeLines([own])[0]![1]).toContain("own filesystem, 10 GiB");
    expect(forgeLines([row({})])[0]![1]).toContain("shared disk");
  });
  test("is escaped", () => {
    const html = String(forgeRow(row({ name: `<img src=x onerror=alert(1)>`, for: `"><script>` }), Date.now()));
    expect(html).not.toContain("<img src=x");
    expect(html).not.toContain("<script>");
    expect(html).toContain("shared disk");
  });
});
describe("what the forge launches and boots", () => {
  const made: App[] = [];
  afterAll(() => {
    for (const app of made) app.close();
  });
  const spawned = async (name: string): Promise<App> => {
    const parent = createApp({ dataDir: join(tmp, name), url: "https://forge.test", port: 0 });
    made.push(parent);
    const admin = await createUser(parent.db, { origin: "seed", trusted: true, username: "alice", email: "[email protected]", isAdmin: true });
    if (!admin.ok) throw new Error("user");
    const out = await spawnForge(
      parent,
      admin.value,
      { name: "kid", org: "kid", apps: [], carryBriefs: false, carrySubscriptions: false },
      { catalog: [], briefs: [], subscriptions: [] },
      {
        placement: hostedPlacement({ host: "forge.test" }),
        request: new Request("https://forge.test/spawn", { method: "POST", headers: { origin: "https://forge.test" } }),
        url: new URL("https://forge.test/spawn"),
      },
    );
    if (!out.ok) throw new Error(JSON.stringify(out.error));
    await sleepChild(parent, "kid");
    return parent;
  };
  test("the registry's cell spec binds the child's own filesystem, and binds nothing on the shared disk", async () => {
    const parent = createApp({ dataDir: join(tmp, "launch"), url: "https://forge.test", port: 0 });
    made.push(parent);
    mkdirSync(childDirOf(parent, "cell-kid1"), { recursive: true });
    const real = realpathSync(childDirOf(parent, "cell-kid1"));
    const input = { bodyId: "cell-kid1", name: "kid", size: "small" } as const;
    const at = { port: 4100, parentPort: 4101 };
    const own = launchSpecFor(parent, input, at, `${ROOT}\n731 22 7:3 / ${real} rw - ext4 /dev/loop3 rw\n`);
    expect(own.writable).toEqual([real]);
    expect(launchSpecFor(parent, input, at, `${ROOT}\n`).writable).toEqual([]);
  });
  test("the boot does not open a child on the shared disk when one of its own is required, and opens it when not", async () => {
    const parent = await spawned("boot");
    expect(childAwake(parent, "kid")).toBe(false);
    setCapacity(parent.db, "children.ownFilesystem", "on", "system");
    await bootHostedChild(parent, "kid");
    expect(childAwake(parent, "kid")).toBe(false);
    setCapacity(parent.db, "children.ownFilesystem", "off", "system");
    await bootHostedChild(parent, "kid");
    expect(childAwake(parent, "kid")).toBe(true);
  });
});
@@ -24,6 +24,7 @@
const row = (name: string, o: Partial<ClientRow> = {}): Omit<ClientRow, "attenti
  link: null,
  size: "small",
  use: { kind: "shared" },
  disk: { own: false, path: "/d/children/c" },
  lastHeartbeatAt: null,
  nextStep: { key: "unreported", words: "has not reported yet", lastTellAt: null },
  spendTodayUsd: null,
@@ -44,6 +44,7 @@
describe("a hosted child's apps run in the parent", () => {
    if (hit === undefined) return new Response("not an app host", { status: 418 });
    if (hit === "unknown") return new Response("not found", { status: 404 });
    if ("cell" in hit) throw new Error("this child is hosted");
    if ("refused" in hit) return new Response(hit.refused, { status: 503 });
    // The server is only for a websocket upgrade, which these requests are not.
    return (await proxyApp(hit.runtime, request, hit.target, {} as never))!;
  };
@@ -32,6 +32,7 @@
const row = (over: Partial<ClientRow>): ClientRow => ({
  ceilingUsd: null,
  size: "small",
  use: { kind: "shared" },
  disk: { own: false, path: "/d/children/c" },
  lastHeartbeatAt: null,
  nextStep: { key: "unreported", words: "has not reported yet", lastTellAt: null },
  ...over,
@@ -172,15 +173,15 @@
describe("forges you sent in the terminal", () => {
    const up = { total: 3, running: 3, notRunning: [] };
    const down = { total: 2, running: 1, notRunning: [{ slug: "notes", why: "build failed" }] };
    expect(forgeLines([row({ running: up })])).toEqual([
      ["maria", "asleep · for Maria's bakery · Not claimed yet · 3 apps running · has not reported yet · small · shared · no heartbeat yet"],
      ["maria", "asleep · for Maria's bakery · Not claimed yet · 3 apps running · has not reported yet · small · shared · shared disk · no heartbeat yet"],
    ]);
    expect(forgeLines([row({ claimed: true, running: down, for: null })])).toEqual([
      ["maria", "asleep · Claimed · 1 app running · notes: build failed · has not reported yet · small · shared · no heartbeat yet"],
      ["maria", "asleep · Claimed · 1 app running · notes: build failed · has not reported yet · small · shared · shared disk · no heartbeat yet"],
    ]);
    expect(forgeLines([row({ claimed: null })])[0]![1]).toContain("Unknown");
    expect(forgeLines([row({ made: false })])[0]![1]).toContain("Still being made");
    expect(forgeLines([row({ attention: "down", claimed: true, for: null })])).toEqual([
      ["maria", "asleep · App down · Claimed · has not reported yet · small · shared · no heartbeat yet"],
      ["maria", "asleep · App down · Claimed · has not reported yet · small · shared · shared disk · no heartbeat yet"],
    ]);
    expect(forgeLines([row({})])[0]![1]).not.toMatch(/Not reporting|App down|Unclaimed/);
    expect(forgeLines([row({ nextStep: { key: "tell", words: "no tell yet", lastTellAt: null } })])[0]![1]).toContain("no tell yet");
		@@ -1240,6 +1240,31 @@ memory only: a process is not state, and a restart rebuilds every
1240	1240	environment from the default branch and the open pulls, exactly as
1241	1241	`core/reconcile.ts` rebuilds the index from git.
1242	1242
	1243	### A child forge's own filesystem
	1244
	1245	How to read the line and turn the guard on: [docs/features/child-filesystem.md](features/child-filesystem.md).
	1246
	1247	A child forge (`/forges`) keeps everything it writes under
	1248	`<data>/children/<body id>`. The forge reads `/proc/self/mountinfo` to tell
	1249	whether that directory is a filesystem of its own, a mount whose mount point
	1250	is exactly that path, and reads its size with `statfs`: blocks × block size
	1251	in bytes, and its inodes (`src/spawn/disk_mount.ts`). The forge mounts
	1252	nothing itself. Making the filesystem is the platform's job (#10851).
	1253
	1254	- On its own filesystem, writing past its size fails with ENOSPC inside
	1255	the child, and the parent's free space does not change. Its cell binds that
	1256	filesystem by its real path (`cellSpecFor`). On the shared disk, only the
	1257	cell's disk watch stops a child, and only after it has written too much.
	1258	- The child's line on `/forges` and on the terminal's forges screen says
	1259	`own filesystem, N GiB` (GiB = 2^30 bytes, to one place) or `shared disk`.
	1260	- `children.ownFilesystem` (Settings → Capacity, or the `capacity` MCP
	1261	tool with `key: "children.ownFilesystem"`) is `off` by default. When it is
	1262	`on`, the forge refuses to start a child with no filesystem of its own,
	1263	whether that child runs in a cell or in this forge's process. The refusal is
	1264	a 503 with one plain line naming the child and saying why. Its pages and its
	1265	apps answer with that line, and the boot skips the child and logs the same
	1266	line. A child that is already running is not stopped.
	1267
1243	1268	## Runs
1244	1269
1245	1270	A run row is created `queued`, claimed with a compare-and-swap into
		@@ -77,7 +77,7 @@ bytes in `tools/list`. After changing a tool run `bun scripts/mcp-table.ts`;
77	77	\| `boards` \| — \| The forge's boards for person admins: slug, title, range, refresh and panels \| 425 \|
78	78	\| `branches` \| `create`, `delete`, `branches`, `tags` \| A repo's branches; `name`, `action` create (from `from`) or delete one, not the default \| 407 \|
79	79	\| `builds` \| — \| A repo's build pins (`refs/builds/`): label, commit, pinned by, note \| 231 \|
80		\| `capacity` \| — \| Forge capacity and guards, live \| 390 \|
	80	\| `capacity` \| — \| Forge capacity and guards, live \| 415 \|
81	81	\| `claim_link` \| `revoke`, `undo` \| A child's claim link: `reveal` a new one, or `action` revoke/undo \| 304 \|
82	82	\| `close` \| — \| Close or reopen (`state` open) an issue or pull \| 463 \|
83	83	\| `cloud_account` \| — \| Change a cloud account by `verb` (admin) \| 549 \|
		@@ -0,0 +1,48 @@
	1	# A child forge's own filesystem (#10856)
	2
	3	Everything a child forge writes is kept under `<data>/children/<body id>`. The
	4	forge checks whether that directory is a filesystem of its own: a mount
	5	whose mount point is exactly that path in `/proc/self/mountinfo`. The forge
	6	mounts nothing itself. Making that filesystem is the platform's job (#10851).
	7
	8	## What the line means
	9
	10	Each child's line on `/forges` and on the terminal's Forges you sent
	11	screen (ctrl-k) ends with one of:
	12
	13	- `own filesystem, N GiB`: the child's data has a filesystem of its own.
	14	N is `statfs` blocks × block size, in GiB (2^30 bytes), to one place.
	15	Writing past that size fails with ENOSPC inside the child, and the parent's
	16	free space stays the same. The child's cell binds that filesystem by its
	17	real path.
	18	- `shared disk`: the child's data sits on the disk this forge and its
	19	other children share. Only the cell's disk watch stops it, and only after it
	20	has written too much.
	21
	22	## Requiring one: `children.ownFilesystem`
	23
	24	The setting is `off` by default. To turn it on, use one of:
	25
	26	- Settings → Capacity: set "Child forges need a filesystem of their own"
	27	to `on`.
	28	- The terminal's Capacity screen: press `e` on `children.ownFilesystem`.
	29	- The `capacity` MCP tool:
	30	`{ "key": "children.ownFilesystem", "value": "on", "reason": "…", "dryRun": false }`.
	31	The value `""` puts back the default.
	32
	33	While it is on, the forge does not start a child that has no filesystem of its
	34	own. This applies whether the child runs in a cell or in this forge's process.
	35	The forge reads the setting on every start, and a child that is already
	36	running is not stopped.
	37
	38	## What the refusal says
	39
	40	The child's pages and its apps answer 503, `text/plain`, with one line:
	41
	42	> kid was not started: its data is on the shared disk, not a filesystem of its own, and this forge requires one (children.ownFilesystem is on).
	43
	44	The boot skips that child and logs the same line as `child forge not started`.
	45
	46	Code: `src/spawn/disk_mount.ts` (reading the mounts), `startRefused` in
	47	`src/spawn/host.ts`, and `launchSpecFor` in `src/spawn/cell.ts`. Tests:
	48	`test/disk-mount.test.ts`.
		@@ -42,7 +42,7 @@ import { err, ok, type Result } from "../kernel/result.ts";
42	42	/** What a refused change to a dial that follows Speed says, on every door. */
43	43	export const DERIVED_WORDS = "The pace floor and the queue depth follow Speed: change Speed (crew.concurrency) and they move with it.";
44	44
45		/** The six guards a caller may set by `key`: the MCP tool's enum and the terminal's `e`. */
	45	/** The guards a caller may set by `key`: the MCP tool's enum and the terminal's `e`. */
46	46	export const SETTABLE_CAPACITY = [
47	47	"crew.concurrency",
48	48	"checks.concurrency",
		@@ -50,6 +50,7 @@ export const SETTABLE_CAPACITY = [
50	50	"cells.egress",
51	51	"guard_new_accounts",
52	52	"signin.edge",
	53	"children.ownFilesystem",
53	54	] as const satisfies readonly CapacityKey[];
54	55
55	56	export interface CapacityRow {
		@@ -26,6 +26,7 @@ export type CapacityKey =
26	26	\| "cells.egress"
27	27	\| "children.modelEgress"
28	28	\| "children.registryEgress"
	29	\| "children.ownFilesystem"
29	30	\| "guard_new_accounts"
30	31	\| "signin.edge"
31	32	\| "pace.floor";
		@@ -121,6 +122,14 @@ export const CAPACITY: Record<CapacityKey, Definition> = {
121	122	fallback: "off",
122	123	help: "off keeps a child forge's cell from the package registries, so its checks cannot fill their install cache; npm also lets it reach registry.npmjs.org on 443; build opens the hosts ordinary app builds fetch from, on 443 alone: npm and yarn, PyPI, GitHub (git dependencies and release tarballs), crates.io and the Go module proxy. Nothing else opens, and the cell enforces this even when cells.egress is report. Takes effect on the next child cell started.",
123	124	},
	125	"children.ownFilesystem": {
	126	label: "Child forges need a filesystem of their own",
	127	// No environment default: refusing children is an admin's decision.
	128	env: "",
	129	kind: { type: "choice", values: ["off", "on"] },
	130	fallback: "off",
	131	help: "on refuses to start a child forge whose data directory (<data>/children/<id>) is not a filesystem of its own, so no child can fill the disk this forge and its other children share; the refusal names the child and says why. off starts it on the shared disk, held only by its cell's disk watch. Off by default, because a forge mounts nothing itself: turn it on once the platform mounts one per child. A child already running is not stopped. Read on every start.",
	132	},
124	133	"guard_new_accounts": {
125	134	label: "New-account repository guard",
126	135	env: "FORGE_GUARD_NEW_ACCOUNTS",
		@@ -434,6 +443,11 @@ const MODEL_HOSTS: Readonly<Record<string, readonly string[]>> = {
434	443	both: ["openrouter.ai:443", "api.anthropic.com:443"],
435	444	};
436	445
	446	/** Whether a child forge must have a filesystem of its own to start (`children.ownFilesystem`); off by default. */
	447	export function childNeedsOwnFilesystem(db: Database): boolean {
	448	return capacityValue(db, "children.ownFilesystem") === "on";
	449	}
	450
437	451	/** The package registry a child forge cell may reach (`children.registryEgress`); none by default. */
438	452	export function childRegistryHosts(db: Database): readonly string[] {
439	453	const value = capacityValue(db, "children.registryEgress");
		@@ -5,7 +5,7 @@ import { good, bad, type Tool } from "../shared.ts";
5	5
6	6	export const tool: Tool = {
7	7	name: "capacity",
8		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",
	8	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, whether a child forge needs its own filesystem, 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 seven 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",
9	9	description:
10	10	"Forge capacity and guards, live. With `key` and `value` (\"\" restores default), plans.",
11	11	inputSchema: {
		@@ -578,6 +578,7 @@ import {
578	578	hostedChildOpen,
579	579	resolveHostedChild,
580	580	resolveHostedChildApp,
	581	refusedResponse,
581	582	socketToCell,
582	583	wakeGate,
583	584	watchHostedChildClose,
		@@ -2571,6 +2572,7 @@ export async function serve(app: App): Promise<Servers> {
2571	2572	if (hit === "unknown")
2572	2573	return securityFloor(new Response("not found", { status: 404 }));
2573	2574	if (hit !== undefined) {
	2575	if ("refused" in hit) return securityFloor(refusedResponse(hit.refused));
2574	2576	if ("cell" in hit) return fromCell(hit.cell);
2575	2577	notePeer(request, server.requestIP(request)?.address, trust);
2576	2578	return proxyApp(hit.runtime, request, hit.target, server);
		@@ -23,6 +23,7 @@ import { hostedPlacement, parentOrigin, childPublicUrl, type BodyStore, type Pla
23	23	import { SIZE_IO, SIZES, type Size } from "./sizes.ts";
24	24	import { CGROUP_DIR_ENV, SIZE_ENV } from "./usage.ts";
25	25	import { childModelHosts, childRegistryHosts } from "../core/capacity.ts";
	26	import { liveChildDisk, type ChildDisk } from "./disk_mount.ts";
26	27
27	28	export const CELL_PREFIX = "cell-";
28	29	export const ownsBody = (bodyId: string): boolean => bodyId.startsWith(CELL_PREFIX);
		@@ -116,10 +117,18 @@ export function cellSpecFor(input: {
116	117	modelHosts?: readonly string[];
117	118	/** The package registry an admin let children reach (`children.registryEgress`); none by default. */
118	119	registryHosts?: readonly string[];
	120	/**
	121	* The child's writable space as found (`spawn/disk_mount.ts`). A filesystem
	122	* of its own is named among the binds by its real path (bwrap binds
	123	* recursively, and `openCell` binds a path once), so a data directory
	124	* reached through a symlink still writes to it; with none, the cell is
	125	* what it always was.
	126	*/
	127	disk?: ChildDisk;
119	128	}): CellSpec {
120	129	return {
121	130	dir: input.dir,
122		writable: [],
	131	writable: input.disk?.own === true ? [input.disk.path] : [],
123	132	home: join(input.dir, ".home"),
124	133	// The parent's data and home are what a child must not see: the home holds
125	134	// the parent crew's sessions and model login, and the child runs as the
		@@ -224,6 +233,33 @@ async function answers(port: number, gone: Promise<unknown>): Promise<boolean> {
224	233	return false;
225	234	}
226	235
	236	/**
	237	* The cell a child forge is launched in, from what the parent holds now: its
	238	* egress settings and its data directory as found (`liveChildDisk`), so a
	239	* child with a filesystem of its own has it bound. `mountinfo` is this
	240	* process's unless a test passes its own.
	241	*/
	242	export function launchSpecFor(
	243	parent: App,
	244	input: { readonly bodyId: string; readonly name: string; readonly size: Size },
	245	at: { readonly port: number; readonly parentPort: number },
	246	mountinfo?: string,
	247	): CellSpec {
	248	return cellSpecFor({
	249	dir: childDirOf(parent, input.bodyId),
	250	parentDataDir: parent.config.dataDir,
	251	parentUrl: parentOrigin(parent.config),
	252	url: childPublicUrl(input.name, parentOrigin(parent.config)),
	253	parentPort: at.parentPort,
	254	size: input.size,
	255	port: at.port,
	256	label: `forge:${input.name}`,
	257	modelHosts: childModelHosts(parent.db),
	258	registryHosts: childRegistryHosts(parent.db),
	259	disk: liveChildDisk(parent.config.dataDir, input.bodyId, mountinfo),
	260	});
	261	}
	262
227	263	function makeRegistry(parent: App): CellChildren {
228	264	const held = new Map<string, Held>();
229	265	const starting = new Map<string, Promise<CellChild \| undefined>>();
		@@ -248,18 +284,7 @@ function makeRegistry(parent: App): CellChildren {
248	284	const url = childPublicUrl(input.name, parentOrigin(parent.config));
249	285	const door = openBeatDoor(parent);
250	286	const parentPort = door.port;
251		const spec = cellSpecFor({
252		dir,
253		parentDataDir: parent.config.dataDir,
254		parentUrl: parentOrigin(parent.config),
255		url,
256		parentPort,
257		size: input.size,
258		port,
259		label: `forge:${input.name}`,
260		modelHosts: childModelHosts(parent.db),
261		registryHosts: childRegistryHosts(parent.db),
262		});
	287	const spec = launchSpecFor(parent, input, { port, parentPort });
263	288	const heard = childLog((line) => parent.log.info("child forge", { name: input.name, line }));
264	289	const log = (raw: string): void => {
265	290	const line = plainLine(raw);
		@@ -9,6 +9,7 @@
9	9	* list never waits on, or fails for, one forge that is down.
10	10	*/
11	11
	12	import { liveChildDisk, readMountinfo, type ChildDisk } from "./disk_mount.ts";
12	13	import type { App } from "../app.ts";
13	14	import { childDirOf, listChildren, statusTokenOf, type Child } from "../actions/spawn.ts";
14	15	import { timingSafeEqual } from "node:crypto";
		@@ -62,6 +63,8 @@ export interface ClientRow {
62	63	readonly size: Size;
63	64	/** What it uses against that size: its cell's reading, or "shared" when it is hosted here. */
64	65	readonly use: ForgeUse;
	66	/** Whether its data is a filesystem of its own, and that filesystem's size (`spawn/disk_mount.ts`). */
	67	readonly disk: ChildDisk;
65	68	/** When its last heartbeat reached this forge, ISO; null when none has. */
66	69	readonly lastHeartbeatAt: string \| null;
67	70	/** The first step its person has not taken, read from the child's heartbeat. */
		@@ -220,6 +223,8 @@ export async function clientRows(app: App): Promise<ClientRow[]> {
220	223	}),
221	224	);
222	225	const beats = await Promise.all(children.map((c) => lastHeard(app, c.name)));
	226	// One read of the mount table for every row.
	227	const mountinfo = children.length === 0 ? "" : readMountinfo();
223	228	return orderRows(
224	229	children.map((c, i) => ({
225	230	name: c.name,
		@@ -238,6 +243,7 @@ export async function clientRows(app: App): Promise<ClientRow[]> {
238	243	...creditView(app, c.name),
239	244	size: c.size,
240	245	use: forgeUse(c, childDirOf(app, c.bodyId)),
	246	disk: liveChildDisk(app.config.dataDir, c.bodyId, mountinfo),
241	247	lastHeartbeatAt: beats[i] === undefined ? null : new Date(beats[i]!.receivedAt).toISOString(),
242	248	link: states[i]?.link ?? null,
243	249	nextStep: nextStepOf(states[i]?.claimed ?? null, beats[i]?.beat),
		@@ -0,0 +1,143 @@
	1	/**
	2	* Whether a child forge's writable space, `<data>/children/<id>`, is a
	3	* filesystem of its own: a mount whose mount point is exactly that
	4	* directory, read from `/proc/self/mountinfo` (proc(5)). On one, writing
	5	* past its size is ENOSPC inside the child and the parent's free space does
	6	* not move; on the shared disk only the cell's disk watch stops it, after
	7	* the fact (#10851). This module reads what is mounted; it mounts nothing.
	8	*
	9	* Plain data in, plain data out: the mountinfo is passed in as text and the
	10	* size read through `stat`, so a test feeds both.
	11	*/
	12
	13	import { readFileSync, realpathSync, statfsSync } from "node:fs";
	14	import { join } from "node:path";
	15
	16	/** One line of mountinfo, the fields this module reads. */
	17	export interface Mount {
	18	/** Field 5: where it is mounted, its octal escapes (`\040` is a space) undone. */
	19	readonly mountPoint: string;
	20	/** The first field after ` - `: ext4, xfs, overlay, tmpfs… */
	21	readonly fsType: string;
	22	}
	23
	24	/** A child's writable space as the forge finds it. */
	25	export type ChildDisk =
	26	\| { readonly own: true; readonly path: string; readonly fsType: string; readonly bytes: number; readonly inodes: number }
	27	\| { readonly own: false; readonly path: string };
	28
	29	/** What `statfs(2)` says of a filesystem, the fields read here. */
	30	export interface FsSize {
	31	/** Block size in bytes (`f_bsize`). */
	32	readonly bsize: number;
	33	/** Total blocks (`f_blocks`). */
	34	readonly blocks: number;
	35	/** Total inodes (`f_files`). */
	36	readonly files: number;
	37	}
	38
	39	/** A body id is one path segment: letters, digits, `.`, `_`, `-`; a first character other than `.` rules out `.` and `..`. */
	40	const BODY_ID = /^[A-Za-z0-9_-][A-Za-z0-9._-]{0,127}$/;
	41	export const validBodyId = (id: string): boolean => BODY_ID.test(id);
	42
	43	/** Undo mountinfo's octal escapes: space, tab, newline and backslash are written `\ooo`. */
	44	const unescape = (field: string): string => field.replace(/\\([0-7]{3})/g, (_, o: string) => String.fromCharCode(parseInt(o, 8)));
	45
	46	/**
	47	* Every mount in a mountinfo text. A line reads
	48	* `36 35 98:0 /mnt1 /mnt/parent rw,noatime master:1 - ext3 /dev/root rw`:
	49	* mount point fifth, then optional fields up to a lone `-`, then the type. A line that does not have that shape is skipped.
	50	*/
	51	export function parseMountinfo(text: string): Mount[] {
	52	const mounts: Mount[] = [];
	53	for (const line of text.split("\n")) {
	54	const fields = line.split(" ");
	55	const dash = fields.indexOf("-", 6);
	56	if (fields.length < 7 \|\| dash < 0) continue;
	57	const mountPoint = fields[4];
	58	const fsType = fields[dash + 1];
	59	if (mountPoint === undefined \|\| fsType === undefined \|\| !mountPoint.startsWith("/")) continue;
	60	mounts.push({ mountPoint: unescape(mountPoint), fsType });
	61	}
	62	return mounts;
	63	}
	64
	65	/** The mount whose mount point is exactly `path` (the last one, as the kernel stacks them); undefined when none. */
	66	export function mountAt(mounts: readonly Mount[], path: string): Mount \| undefined {
	67	const want = path.length > 1 ? path.replace(/\/+$/, "") : path;
	68	let found: Mount \| undefined;
	69	for (const m of mounts) if (m.mountPoint === want) found = m;
	70	return found;
	71	}
	72
	73	/**
	74	* The child's writable space: its own filesystem with its size in bytes
	75	* (blocks × block size) and inodes, or the shared disk. `path` is where the
	76	* mount must sit, already resolved (`childDiskPath`). A filesystem whose size
	77	* cannot be read is not counted as the child's own.
	78	*/
	79	export function childDisk(input: { path: string; mountinfo: string; size: (path: string) => FsSize \| undefined }): ChildDisk {
	80	const mount = mountAt(parseMountinfo(input.mountinfo), input.path);
	81	if (mount === undefined) return { own: false, path: input.path };
	82	const fs = input.size(input.path);
	83	if (fs === undefined \|\| !(fs.bsize > 0) \|\| !(fs.blocks > 0)) return { own: false, path: input.path };
	84	return { own: true, path: input.path, fsType: mount.fsType, bytes: fs.blocks * fs.bsize, inodes: fs.files };
	85	}
	86
	87	/** `<data>/children/<id>`, symlinks resolved (mountinfo names real paths); the joined path when it does not exist yet. */
	88	export function childDiskPath(dataDir: string, bodyId: string): string \| undefined {
	89	if (!validBodyId(bodyId)) return undefined;
	90	const path = join(dataDir, "children", bodyId);
	91	try {
	92	return realpathSync(path);
	93	} catch {
	94	return path;
	95	}
	96	}
	97
	98	/** This process's mountinfo; "" where there is none (not Linux), which reads as no mount at all. */
	99	export function readMountinfo(): string {
	100	try {
	101	return readFileSync("/proc/self/mountinfo", "utf8");
	102	} catch {
	103	return "";
	104	}
	105	}
	106
	107	/** `statfs` of `path`; undefined when it cannot be read. */
	108	export function statSize(path: string): FsSize \| undefined {
	109	try {
	110	const s = statfsSync(path);
	111	return { bsize: Number(s.bsize), blocks: Number(s.blocks), files: Number(s.files) };
	112	} catch {
	113	return undefined;
	114	}
	115	}
	116
	117	/** The live answer for one child: this process's mounts, the real `statfs`. */
	118	export function liveChildDisk(dataDir: string, bodyId: string, mountinfo: string = readMountinfo()): ChildDisk {
	119	const path = childDiskPath(dataDir, bodyId);
	120	return path === undefined ? { own: false, path: join(dataDir, "children") } : childDisk({ path, mountinfo, size: statSize });
	121	}
	122
	123	const GIB = 1024 ** 3;
	124
	125	/** GiB to one place, the `.0` dropped: 10 GiB is 10 737 418 240 bytes. */
	126	export function gib(bytes: number): string {
	127	const n = Math.round((bytes / GIB) * 10) / 10;
	128	return Number.isInteger(n) ? String(n) : n.toFixed(1);
	129	}
	130
	131	/** The words a child's line carries: `own filesystem, N GiB` or `shared disk`. */
	132	export function diskWords(disk: ChildDisk): string {
	133	return disk.own ? `own filesystem, ${gib(disk.bytes)} GiB` : "shared disk";
	134	}
	135
	136	/**
	137	* Why a child may not start, in one plain line; undefined when it may. Only
	138	* when the forge requires a filesystem of its own (`children.ownFilesystem`).
	139	*/
	140	export function startRefusal(name: string, disk: ChildDisk, required: boolean): string \| undefined {
	141	if (!required \|\| disk.own) return undefined;
	142	return `${name} was not started: its data is on the shared disk, not a filesystem of its own, and this forge requires one (children.ownFilesystem is on).`;
	143	}