d05d753 · 5d9009f · 2623566 · 3a5111b · a7d4867 · 8d7973c
@@ -86,6 +86,11 @@
sees `Reduced protection: …` in one line, under the filter on the terminal's
first screen and in the web footer; nobody else does, and a fully protected
forge shows nothing.
The family across forges: `:` → Family in the terminal, `/family` on the web,
`GET /api/v1/family` and the MCP `family` tool all give the same view. The
forge that sent this one is shown to anyone; the forges it sent, only to a
site admin (docs/SPAWN.md, "The family across forges").
Passkeys: Settings → Passkeys lists, adds and removes them (several per
account; `src/auth/webauthn.ts` verifies, no dependency, `none` attestation).
The sign-in page's "Sign in with a passkey" gives the same HttpOnly session a
@@ -48,6 +48,12 @@
Spawn makes the child's `secret.key` and SSH host key in the child's own directo
A spawner may give the child one credential: `modelKey`, an API-billed key (`sk-ant-api…`), with `budgetUsd`, a whole-life budget in dollars from 1 to 1000. A subscription token (`sk-ant-oat…`) is refused, because it is a person's own plan. The key never enters the plan, the dry run, the answer, the ledger or the idempotency table. In the child it is sealed with the child's own key as the account `starter` and granted to its organisation's crew. The budget is locked on that account (`lockBudget`): it is enforced where every run picks its account, whoever started the run and on whichever repository, and the child's admin cannot raise it, only add their own key. A retry with a different key is refused; a key is given once. Said plainly in every answer that carries a key (`keyNote`): the budget holds while this forge hosts the child, whose admin has no shell or database access; on a machine the child's owner controls, only a spend limit set at the provider binds the key, so use a key from a workspace with its own spend limit. The MCP `spawn` tool refuses `modelKey`, so a secret never passes through an agent's conversation. With no key the child is in a clean state: its pages say the crew has no model key yet and where an admin adds one.
## The family across forges (#425)
`/family` draws the forge-level tree as nested lists: the parent (from `FORGE_PARENT_URL`, or the `upstream` in a spawned child's `parent.json`), this forge, and the forges it sent, each with last seen, version, releases behind this forge, and open proposals. Anyone may see the parent; only this forge's admins see children. Bounded: 100 children, four levels.
Children report in; the parent never reaches in. Every ten minutes a spawned child POSTs `/api/v1/heartbeat` (`src/spawn/heartbeat.ts`): `{name, at, version, openProposals, children}` and nothing else, signed HMAC-SHA256 over the body in `x-forge-signature` with a per-child `beatKey` that spawn put in the parent's ledger and the child's `parent.json`. A name the parent did not make, a bad signature, a time more than ten minutes off, a replay or any extra field gets the same 404 and changes nothing. The last beat per child is kept in `<data>/beats/<name>.json`. A child silent for thirty minutes reads "quiet", never an error; one never heard from reads "has not reported yet". Children made before this change have no key and stay unheard until respawned.
## A client's forge in one form (#1608)
`/forges/new` is the whole path: a name, the owner's apps to fork, optionally one fresh app from a one-line description (`fresh`, at most 200 characters, one line), a budget with a model key; it ends in one claim link, shown once. Each picked app is a fork: its full history is copied and `parent.json` lists `apps: [{repo, upstream}]` so the child knows what it follows. A fresh app is a private repository in the child with a README, a `forge.json` and a tiny `index.ts` that answers `/` with the sentence, escaped; its name is the sentence's slug, never one of the forked names. A custom domain is not part of this: the child is reached at `<name>--<host>` and nothing else is promised. The same field is on `POST /api/v1/forges` and the MCP `spawn` (`fresh`). It is absent from the plan when unsaid, so older plan hashes are unchanged.
@@ -59,6 +59,7 @@
export const GATE: readonly string[] = [
  "test/health.test.ts",
  "test/client-address.test.ts",
  "test/client-list.test.ts",
  "test/family-heartbeat.test.ts",
  "test/contents-api.test.ts",
  "test/crew-agents-only.test.ts",
  "test/crew-brief-audience.test.ts",
@@ -109,6 +109,11 @@
interface Ledger {
   * last happened); the child keeps only its hash. Never in an answer.
   */
  statusToken?: string;
  /**
   * The key a child signs its heartbeats with (`spawn/heartbeat.ts`); the
   * child holds the same one in its `parent.json`. Never in an answer.
   */
  beatKey?: string;
}
const SAFE_ID = /^[A-Za-z0-9_-]{1,80}$/;
@@ -220,8 +225,9 @@
async function make(
    }
    if (ledger.done)
      return ok({ name: plan.name, org: plan.org, url: liveChildUrl(app, plan.name), bodyId: ledger.bodyId, existed: true });
    if (ledger.statusToken === undefined) {
      ledger.statusToken = secret();
    if (ledger.statusToken === undefined || ledger.beatKey === undefined) {
      ledger.statusToken ??= secret();
      ledger.beatKey ??= secret();
      await writeLedger(app, ledger);
    }
  } else {
@@ -241,6 +247,7 @@
async function make(
      apps: plan.apps.map((a) => a.ref),
      createdAt: new Date().toISOString(),
      statusToken: secret(),
      beatKey: secret(),
    };
    await writeLedger(app, ledger);
  }
@@ -437,6 +444,8 @@
async function copyInto(
          : { forgeCode: { repo: `${plan.org}/forge`, upstream: forgeCode.value } }),
        // Only the hash: the parent alone holds what it answers to.
        ...(ledger.statusToken === undefined ? {} : { statusHash: sha256(ledger.statusToken) }),
        // The key the child signs its heartbeats with; the parent holds the same.
        ...(ledger.beatKey === undefined ? {} : { beatKey: ledger.beatKey }),
      }),
    );
    return ok(mintClaim(child.db, org.id));
@@ -613,6 +622,11 @@
export async function statusTokenOf(app: App, name: string): Promise<string | un
  return (await readLedger(app, name))?.statusToken;
}
/** The key a child of this forge signs heartbeats with; undefined for a name this forge did not make. */
export async function beatKeyOf(app: App, name: string): Promise<string | undefined> {
  return (await readLedger(app, name))?.beatKey;
}
/** One child, as the ledger keeps it. */
export interface Child {
  readonly name: string;
@@ -66,6 +66,7 @@
export const SYSTEM_NAMES: readonly string[] = [
  "boards",
  "events",
  "explore",
  "family",
  "fleet",
  "flow",
  "front",
@@ -47,6 +47,8 @@
import { emailVerified } from "../core/verify.ts";
import { readHealth } from "../actions/health.ts";
import { listChildren } from "../actions/spawn.ts";
import { forgeState, PARENT_HEADER } from "../spawn/clients.ts";
import { familyView } from "../spawn/family.ts";
import { receiveBeat, SIGNATURE_HEADER } from "../spawn/heartbeat.ts";
import { reissueDoor, spawnDoor } from "../spawn/door.ts";
import { listSecrets, putSecret, removeSecret } from "../actions/secrets.ts";
import { proposeUpstream } from "../actions/upstream.ts";
@@ -4134,6 +4136,23 @@
export function apiRoutes(router: Router<Handler>): void {
    return json(state);
  });
  // A child's signed heartbeat (docs/SPAWN.md): counts and version, never
  // data. Every refusal is the same 404, so nothing says who is a child.
  router.add("POST", "/api/v1/heartbeat", async (ctx) => {
      
        sentinelcrew
        29d ago
        outdated
      
      High: this trusts the declared Content-Length. A chunked request has none, so length is 0 and ctx.request.text() reads up to REQUEST_MAX on an endpoint that needs no sign-in. Use readBounded(ctx.request, 1024) from src/http/limits.ts and send too_large back as the same 404.
    
      
        sentinelcrew
        29d ago
        
      
      Good: capped by bytes read, signed, the same 404 for every refusal. Non-blocking: the paired test would pass without the cap (parseBeat already rejects >1 KiB). A multi-chunk stream that asserts an early cut-off would pin it.
    
    const bytes = await readBounded(ctx.request, 1024);
    if (bytes === "too_large") return apiError("not_found", 404, "no such door");
    const raw = new TextDecoder().decode(bytes);
    const kept = await receiveBeat(ctx.app, raw, ctx.request.headers.get(SIGNATURE_HEADER));
    return kept ? json({ ok: true }) : apiError("not_found", 404, "no such door");
  });
  // The family (#425): the parent for anyone, the children for an admin.
  router.add("GET", "/api/v1/family", async (ctx) => {
    const denied = ctx.auth.user === undefined ? undefined : requireScope(ctx, "ro");
    if (denied) return denied;
    return json(await familyView(ctx.app, ctx.auth.user?.isAdmin === true));
  });
  // A forge's children (docs/SPAWN.md): an admin's, planned before made.
  router.add("GET", "/api/v1/forges", async (ctx) => {
    const denied = requireScope(ctx, "ro");
@@ -40,6 +40,7 @@
import {
import { holdPull, releasePull } from "../actions/holds.ts";
import { openPlan, parsePlan, PLAN_MAX } from "../actions/plan.ts";
import { cancelRepoRun } from "../actions/runs.ts";
import { familyView } from "../spawn/family.ts";
import { clientRows } from "../spawn/clients.ts";
import { reissueDoor, spawnDoor } from "../spawn/door.ts";
import { contextNote, parseContext } from "../actions/tell_context.ts";
@@ -1157,6 +1158,16 @@
const TOOLS: readonly Tool[] = [
      });
    },
  },
  {
    name: "family",
    description:
      "The forge's family across forges: the forge that sent this one (anyone) and, for a site admin, the forges it sent, each as last heard — reporting, quiet (silent for thirty minutes) or unheard — with version, releases behind, open proposals. The same data as /family and /api/v1/family.",
    inputSchema: { type: "object", properties: {} },
    writes: false,
    async run(ctx, user) {
      return good(await familyView(ctx.app, user.isAdmin === true));
    },
  },
  {
    name: "next_steps",
    description:
@@ -203,6 +203,7 @@
import {
} from "../web/studio/actions.ts";
import { everydayCreate, everydayKeep, everydaySwitch } from "../web/pages/everyday.ts";
import { claimFragmentPage, claimSubmit } from "../web/pages/claim.ts";
import { familyPage } from "../web/pages/family.ts";
import { forgeLinkSubmit, forgesPage } from "../web/pages/forges.ts";
import { newForgePage, newForgeSubmit } from "../web/pages/new-forge.ts";
import { askedPage } from "../web/studio/asked_page.ts";
@@ -580,6 +581,7 @@
export function buildRouter(): Router<Handler> {
  router.add("POST", "/claim", claimSubmit);
  // "+ New forge": the spawn door as a page, any signed-in person (spawn/door.ts).
  router.add("GET", "/forges", forgesPage);
  router.add("GET", "/family", familyPage);
  router.add("POST", "/forges/:name/claim-link", forgeLinkSubmit);
  router.add("GET", "/forges/new", newForgePage);
  router.add("POST", "/forges/new", newForgeSubmit);
@@ -12,6 +12,7 @@
import { createApp } from "./app.ts";
import { reconcile } from "./core/reconcile.ts";
import { syncAllPillars } from "./actions/pillars.ts";
import { firstBoot } from "./spawn/first-boot.ts";
import { startHeartbeat } from "./spawn/heartbeat.ts";
import { pruneSessions } from "./core/sessions.ts";
import { runDelivery } from "./core/webhooks.ts";
import { isHookName, runHookClient } from "./git/hooks.ts";
@@ -320,6 +321,8 @@
const crew = appsOn && !crewHeldOff
// A spawned child's first boot: its direction, opened once for its planner
// (spawn/first-boot.ts). A forge that was not spawned is untouched.
await firstBoot(app);
// A spawned child reports its standing to its parent (spawn/heartbeat.ts).
const heartbeatTimer = startHeartbeat(app);
// Prompts from Instagram (docs/APPS.md): once a day, for each repository
// that connected an account, the top comment on its latest Reel is told to
// the crew. A minute's clock; nothing leaves the box until a source exists.
@@ -465,6 +468,7 @@
function shutdown(signal: NodeJS.Signals): void {
  // process that replaced this one, not to this one while it finishes.
  drainStreams();
  clearInterval(deliveryTimer);
  clearInterval(heartbeatTimer);
  clearInterval(syncTimer);
  clearInterval(staleTimer);
  clearInterval(leaseTimer);
@@ -0,0 +1,59 @@
/**
 * The family as plain data (#425): one answer for the page, the JSON read,
 * the MCP tool and the terminal. Anyone sees the parent; only a site admin
 * sees the children, so the gate lives here and nowhere else.
 */
import type { App } from "../app.ts";
import { parentForgeFor } from "../core/parent_releases.ts";
import { running } from "../kernel/version.ts";
import { childStandings, parentUpstream, type ChildStanding } from "./heartbeat.ts";
export interface FamilyView {
  readonly parent: { readonly url: string; readonly host: string; readonly behind: number | null } | null;
  readonly here: { readonly host: string | null; readonly version: string };
  readonly children: readonly ChildStanding[];
  readonly more: number;
}
export async function familyView(app: App, isAdmin: boolean): Promise<FamilyView> {
  const known = parentForgeFor(app.config);
  const url = app.config.parentUrl ?? (await parentUpstream(app));
  const kids = isAdmin ? await childStandings(app) : { items: [], more: 0 };
  return {
    parent:
      url === undefined
        ? null
        : { url, host: known?.host ?? new URL(url).host, behind: known?.behind ?? null },
    here: {
      host: app.config.url === undefined ? null : new URL(app.config.url).host,
      version: running().version,
    },
    children: kids.items,
    more: kids.more,
  };
}
/** The view as plain lines, for a terminal. */
export function familyLines(view: FamilyView): [string, string][] {
  const out: [string, string][] = [];
  if (view.parent !== null) {
    out.push(["parent", view.parent.url]);
    if (view.parent.behind !== null)
      out.push(["", view.parent.behind === 0 ? "this forge is up to date" : `this forge is ${view.parent.behind} behind`]);
  } else out.push(["parent", "none"]);
  out.push(["this forge", `${view.here.host ?? "here"} · version ${view.here.version}`]);
  for (const c of view.children) {
    const bits =
      c.state === "unheard"
        ? ["has not reported yet"]
        : [
            c.state,
            c.version === null ? "" : `version ${c.version}`,
            c.openProposals === null ? "" : `${c.openProposals} open`,
          ].filter((b) => b !== "");
    out.push([`child ${c.name}`, bits.join(" · ")]);
  }
  if (view.more > 0) out.push(["", `${view.more} more not shown`]);
  return out;
}
@@ -0,0 +1,265 @@
/**
 * The family across forges (#425): a child tells its parent how it stands,
 * and the parent never reaches in. A heartbeat is a small signed JSON
 * document carrying the child's name, a time, its version and two counts —
 * open proposals and children of its own — and nothing else: no titles, no
 * names, no data. The parent keeps the last one per child under
 * `<data>/beats/<name>.json`.
 *
 * Signed with the key spawn gave both sides (`beatKey` in the parent's
 * ledger and in the child's `parent.json`): HMAC-SHA256 over the exact body
 * bytes. A name the parent did not make, a bad signature, a stale or
 * replayed time, a malformed body all get the same answer and change
 * nothing: unknown children are ignored.
 */
import { createHmac, timingSafeEqual } from "node:crypto";
import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
import { join } from "node:path";
import type { App } from "../app.ts";
import { beatKeyOf, listChildren } from "../actions/spawn.ts";
import releases from "../core/releases.json" with { type: "json" };
import { running } from "../kernel/version.ts";
export const SIGNATURE_HEADER = "x-forge-signature";
/** A child reports this often; one silent for three beats reads as quiet. */
export const BEAT_MS = 10 * 60_000;
export const QUIET_MS = 3 * BEAT_MS;
/** A heartbeat's time may differ from the parent's clock by this much. */
const SKEW_MS = 10 * 60_000;
const MAX_BODY = 1024;
export const MAX_CHILDREN = 100;
export const MAX_DEPTH = 4;
const NAME = /^[a-z0-9](?:[a-z0-9-]{0,37}[a-z0-9])?$/;
const VERSION = /^[0-9A-Za-z][0-9A-Za-z.+_-]{0,63}$/;
const COUNT_MAX = 1_000_000;
export interface Beat {
  readonly name: string;
  /** The child's clock, ms since the epoch. */
  readonly at: number;
  readonly version: string;
  readonly openProposals: number;
  readonly children: number;
}
export function sign(key: string, body: string): string {
  return createHmac("sha256", key).update(body).digest("hex");
}
function verified(key: string, body: string, shown: string | null): boolean {
  if (shown === null || !/^[0-9a-f]{64}$/.test(shown)) return false;
  return timingSafeEqual(Buffer.from(sign(key, body)), Buffer.from(shown));
}
const count = (v: unknown): v is number =>
  typeof v === "number" && Number.isInteger(v) && v >= 0 && v <= COUNT_MAX;
/** The beat in `raw`, or undefined when it is not exactly one. */
export function parseBeat(raw: string): Beat | undefined {
  if (raw.length > MAX_BODY) return undefined;
  let doc: unknown;
  try {
    doc = JSON.parse(raw);
  } catch {
    return undefined;
  }
  if (typeof doc !== "object" || doc === null || Array.isArray(doc)) return undefined;
  const d = doc as Record<string, unknown>;
  const keys = Object.keys(d).sort().join(",");
  if (keys !== "at,children,name,openProposals,version") return undefined;
  const { name, at, version, openProposals, children } = d;
  if (typeof name !== "string" || !NAME.test(name)) return undefined;
  if (typeof at !== "number" || !Number.isSafeInteger(at) || at <= 0) return undefined;
  if (typeof version !== "string" || !VERSION.test(version)) return undefined;
  if (!count(openProposals) || !count(children)) return undefined;
  return { name, at, version, openProposals, children };
}
const beatPath = (app: App, name: string): string =>
  join(app.config.dataDir, "beats", `${name}.json`);
/** What this forge heard, and when (ms), for one child. */
export interface Heard {
  readonly beat: Beat;
  readonly receivedAt: number;
}
async function lastHeard(app: App, name: string): Promise<Heard | undefined> {
  try {
    const doc = JSON.parse(await readFile(beatPath(app, name), "utf8")) as {
      receivedAt?: unknown;
      beat?: unknown;
    };
    const beat = parseBeat(JSON.stringify(doc.beat));
    return beat !== undefined && typeof doc.receivedAt === "number"
      ? { beat, receivedAt: doc.receivedAt }
      : undefined;
  } catch {
    return undefined;
  }
}
/**
 * Take one heartbeat. True when it was kept; false for every refusal, which
 * the caller answers alike so nothing says whether a name is a child.
 */
export function receiveBeat(
  app: App,
  raw: string,
  signature: string | null,
  now = Date.now(),
): Promise<boolean> {
  // One at a time per name, so two identical beats cannot both be kept.
  const name = parseBeat(raw)?.name ?? "";
  const run = (turns.get(name) ?? Promise.resolve()).then(() =>
    takeBeat(app, raw, signature, now),
  );
  const tail = run.then(() => undefined, () => undefined);
  turns.set(name, tail);
  void tail.then(() => {
    if (turns.get(name) === tail) turns.delete(name);
  });
  return run;
}
const turns = new Map<string, Promise<void>>();
async function takeBeat(
  app: App,
  raw: string,
  signature: string | null,
  now: number,
): Promise<boolean> {
  const beat = parseBeat(raw);
  if (beat === undefined) return false;
  const key = await beatKeyOf(app, beat.name);
  if (key === undefined || !verified(key, raw, signature)) return false;
  if (Math.abs(now - beat.at) > SKEW_MS) return false;
  const before = await lastHeard(app, beat.name);
  if (before !== undefined && beat.at <= before.beat.at) return false;
  await mkdir(join(app.config.dataDir, "beats"), { recursive: true });
  const path = beatPath(app, beat.name);
  await writeFile(`${path}.tmp`, JSON.stringify({ receivedAt: now, beat }));
  await rename(`${path}.tmp`, path);
  return true;
}
/** What a child knows of its parent from `parent.json`, when it has all of it. */
async function parentLink(
  app: App,
): Promise<{ name: string; upstream: string; key: string } | undefined> {
  try {
    const doc = (await Bun.file(join(app.config.dataDir, "parent.json")).json()) as Record<string, unknown>;
    const { name, upstream, beatKey } = doc;
    if (typeof name !== "string" || !NAME.test(name)) return undefined;
    if (typeof upstream !== "string" || !/^https?:\/\/[^\s?#]+$/.test(upstream)) return undefined;
    if (typeof beatKey !== "string" || beatKey === "") return undefined;
    return { name, upstream: upstream.replace(/\/+$/, ""), key: beatKey };
  } catch {
    return undefined;
  }
}
/** This forge's standing, as the beat carries it. Counts only. */
export function standing(app: App, name: string, at = Date.now()): Beat {
  const proposals = app.db
    .query<{ n: number }, []>(
      `SELECT COUNT(*) AS n FROM pull JOIN issue ON issue.id = pull.issue_id WHERE issue.state = 'open'`,
    )
    .get();
  return {
    name,
    at,
    version: running().version,
    openProposals: Math.min(proposals?.n ?? 0, COUNT_MAX),
    children: 0,
  };
}
type FetchLike = (url: string, init?: RequestInit) => Promise<Response>;
let lastAt = 0;
/** A spawned child's one report to its parent; false when it has no parent or the try failed. Never throws. */
export async function sendBeat(
  app: App,
  fetcher: FetchLike = fetch,
  now = Date.now(),
): Promise<boolean> {
  const link = await parentLink(app);
  if (link === undefined) return false;
  const own = (await listChildren(app)).length;
  // Strictly later than the last one sent, so a quick restart is not a replay.
  lastAt = Math.max(now, lastAt + 1);
  const body = JSON.stringify({
    ...standing(app, link.name, lastAt),
    children: Math.min(own, COUNT_MAX),
  });
  try {
    const res = await fetcher(`${link.upstream}/api/v1/heartbeat`, {
      method: "POST",
      headers: { "content-type": "application/json", [SIGNATURE_HEADER]: sign(link.key, body) },
      body,
      signal: AbortSignal.timeout(5000),
      redirect: "error",
    });
    return res.ok;
  } catch {
    return false;
  }
}
/** Report now and then every BEAT_MS; returns the timer to clear. */
export function startHeartbeat(app: App): ReturnType<typeof setInterval> {
  void sendBeat(app);
  return setInterval(() => void sendBeat(app), BEAT_MS);
}
export type Standing = "reporting" | "quiet" | "unheard";
export interface ChildStanding {
  readonly name: string;
  readonly url: string;
  readonly state: Standing;
  /** ms since the epoch the parent last heard, or null. */
  readonly lastSeen: number | null;
  readonly version: string | null;
  /** Releases the child is behind this forge, or null when its version is not one of ours. */
  readonly behind: number | null;
  readonly openProposals: number | null;
  readonly ownChildren: number | null;
}
/** How many releases of this forge are newer than `version`; null when it is not one of them. */
export function releasesBehind(version: string): number | null {
  const i = releases.releases.findIndex((r) => r.version === version);
  return i < 0 ? null : i;
}
/** Each child this forge made, as last heard; bounded, and a silent one is quiet, not broken. */
export async function childStandings(
  app: App,
  now = Date.now(),
): Promise<{ items: ChildStanding[]; more: number }> {
  const all = await listChildren(app);
  const items: ChildStanding[] = [];
  for (const c of all.slice(0, MAX_CHILDREN)) {
    const heard = await lastHeard(app, c.name);
    items.push({
      name: c.name,
      url: c.url,
      state: heard === undefined ? "unheard" : now - heard.receivedAt > QUIET_MS ? "quiet" : "reporting",
      lastSeen: heard?.receivedAt ?? null,
      version: heard?.beat.version ?? null,
      behind: heard === undefined ? null : releasesBehind(heard.beat.version),
      openProposals: heard?.beat.openProposals ?? null,
      ownChildren: heard?.beat.children ?? null,
    });
  }
  return { items, more: Math.max(0, all.length - MAX_CHILDREN) };
}
/** The address of the forge that sent this one, when it was spawned and told. */
export async function parentUpstream(app: App): Promise<string | undefined> {
  return (await parentLink(app))?.upstream;
}
@@ -27,7 +27,10 @@
import {
  errorText,
  promptScreen,
  openOnWeb,
  runAsync,
} from "./screens/common.ts";
import { familyScreen } from "./screens/family.ts";
import { familyLines, familyView } from "../spawn/family.ts";
import { issueScreen } from "./screens/issue.ts";
import { pullScreen } from "./screens/pull.ts";
import { blobScreen } from "./screens/repo.ts";
@@ -192,6 +195,16 @@
export function forgeCommands(session: Session): (ctx: Ctx) => Command[] {
        hint: "the pipeline's bottleneck",
        run: () => ctx.toast(verdict(readPipeline(session.db)), "default"),
      });
    commands.push({
      id: "family",
      title: "Family",
      hint: "the forge that sent this one, and the forges it sent",
      run: () =>
        runAsync(ctx, async () => {
          const view = await familyView(session.app, session.user?.isAdmin === true);
          ctx.push(familyScreen(ctx, familyLines(view)));
        }),
    });
    commands.push({
      id: "quit",
      title: "Quit",
@@ -0,0 +1,29 @@
/**
 * The family across forges (#425) in a card: the same lines as /family, from
 * the same view, so the gate (guests see the parent, admins also the
 * children) is `spawn/family.ts`'s and not this screen's.
 */
import type { Ctx, Screen } from "../app/app.ts";
import { binding } from "../app/keys.ts";
import { card } from "../ui/widgets.ts";
import { drawFacts } from "./common.ts";
export function familyScreen(ctx: Ctx, rows: readonly (readonly [string, string])[]): Screen {
  return {
    title: "Family",
    keys: [binding(["esc"], "close")],
    render(area, s) {
      const c = ctx.theme.c;
      const w = Math.min(78, Math.max(30, area.w - 6));
      const h = Math.min(area.h, rows.length + 2);
      const r = { x: area.x + ((area.w - w) >> 1), y: area.y + ((area.h - h) >> 1), w, h };
      const inner = card(s, r, c, { title: "Family", focused: true });
      drawFacts(s, { x: inner.x + 1, y: inner.y, w: Math.max(0, inner.w - 1), h: inner.h }, c, rows, c.card);
    },
    key(e) {
      if (e.key === "esc" || e.key === "q") ctx.pop();
      return true;
    },
  };
}
@@ -324,6 +324,7 @@
function paletteIndex(ctx: Ctx, extra: PaletteItem[]): Html {
      ? [
          { t: "Flow", h: "/flow", c: "Go to" },
          { t: "Forges you sent", h: "/forges", c: "Go to" },
          { t: "Family of forges", h: "/family", c: "Go to" },
        ]
      : []),
  ];
@@ -0,0 +1,141 @@
/**
 * `/family`: the forge-level family (#425). The forge this one was spawned
 * from, this forge, and the forges it sent, each with how it stands as it
 * last reported (`spawn/heartbeat.ts`). Nested lists, like the repository
 * family tree, bounded in depth and count. Anyone may see the parent; only
 * this forge's admins see its children. A child that stopped reporting
 * reads "quiet": a fact about the clock, not a fault.
 */
import type { Ctx } from "../../http/context.ts";
import { familyView } from "../../spawn/family.ts";
import {
  MAX_DEPTH,
  type ChildStanding,
} from "../../spawn/heartbeat.ts";
import { pageHead } from "../chrome.ts";
import { html, type Html } from "../html.ts";
import { page } from "../layout.ts";
import { card, time } from "../ui.ts";
interface Node {
  readonly label: string;
  readonly href: string | null;
  readonly meta: readonly Html[];
  readonly badge: Html | null;
  readonly here?: boolean;
  readonly children: readonly Node[];
}
const plural = (n: number, one: string, many = `${one}s`) =>
  `${n} ${n === 1 ? one : many}`;
function standingNode(c: ChildStanding): Node {
  const meta: Html[] = [];
  if (c.state === "unheard") meta.push(html`has not reported yet`);
  else {
    if (c.lastSeen !== null)
      meta.push(html`last seen ${time(new Date(c.lastSeen).toISOString())}`);
    if (c.version !== null) meta.push(html`version ${c.version}`);
    if (c.behind !== null)
      meta.push(html`${c.behind === 0 ? "up to date" : `${plural(c.behind, "release")} behind`}`);
    if (c.openProposals !== null)
      meta.push(html`${plural(c.openProposals, "open proposal")}`);
    if (c.ownChildren !== null && c.ownChildren > 0)
      meta.push(html`${plural(c.ownChildren, "forge")} of its own`);
  }
  return {
    label: c.name,
    href: c.url,
    meta,
    badge:
      c.state === "reporting"
        ? html`<span class="pill" data-tone="accent">reporting</span>`
        : c.state === "quiet"
          ? html`<span class="pill">quiet</span>`
          : null,
    children: [],
      
        sentinelcrew
        29d ago
        outdated
      
      An unheard child falls through to the quiet pill. docs/SPAWN.md says a child never heard from reads 'has not reported yet', not quiet. Give unheard no badge, or a neutral one, and fix the test that expects 'quiet' here.
    
  };
}
function row(n: Node, depth: number): Html {
  const inner = html`<span class="row-main">
      <span class="row-title"
        >${n.label}${n.here ? html` <span class="lineage-here">you are here</span>` : null}</span
      >
      ${n.meta.length === 0
        ? null
        : html`<span class="row-meta"
            >${n.meta.map((m, i) => html`${i > 0 ? " · " : ""}${m}`)}</span
          >`}
    </span>
    ${n.badge === null ? null : html`<span class="row-trail">${n.badge}</span>`}`;
  return html`<li>
    ${n.href === null
      ? html`<div class="row">${inner}</div>`
      : html`<a class="row" href="${n.href}" rel="noopener noreferrer">${inner}</a>`}
    ${n.children.length === 0 || depth + 1 >= MAX_DEPTH
      ? null
      : html`<ul class="lineage-children">
          ${n.children.map((c) => row(c, depth + 1))}
        </ul>`}
  </li>`;
}
// GET /family
export async function familyPage(ctx: Ctx): Promise<Response> {
  const app = ctx.app;
  const owns = ctx.auth.user?.isAdmin === true;
  const view = await familyView(app, owns);
  const parent = view.parent;
  const kids = { items: view.children, more: view.more };
  const here: Node = {
    label: view.here.host ?? "this forge",
    href: null,
    meta: [html`version ${view.here.version}`],
    badge: null,
    here: true,
    children: kids.items.map(standingNode),
  };
  const root: Node =
    parent === null
      ? here
      : {
          label: parent.host,
          href: parent.url,
          meta:
            parent.behind === null
              ? []
              : [html`this forge is ${parent.behind === 0 ? "up to date" : plural(parent.behind, "release") + " behind"}`],
          badge: null,
          children: [here],
        };
  const alone = parent === null && kids.items.length === 0;
  return page({
    ctx,
    title: "Family",
    body: html`<div class="narrow-wide">
      ${pageHead("Family", {
        sub: "The forge this one came from, and the forges it sent. Children report in; nothing here reaches into one.",
      })}
      ${card(
        html`<ul class="list lineage" aria-label="Forges, by who sent whom">
            ${row(root, 0)}
          </ul>
          ${kids.more > 0
            ? html`<p class="muted small card-body">
                ${plural(kids.more, "more forge")} not shown.
              </p>`
            : null}
          ${alone
            ? html`<p class="muted small card-body">
                This forge has no parent and has sent none${owns ? "" : " that you can see"}.
              </p>`
            : null}`,
        { pad: false },
      )}
    </div>`,
  });
}
@@ -0,0 +1,247 @@
/**
 * The family across forges (#425): signed heartbeats carry counts and
 * version only, unknown children and bad signatures are ignored alike, a
 * silent child reads quiet, and only the parent's admins see children.
 */
import { afterAll, beforeAll, describe, expect, test } from "bun:test";
import { mkdtemp, readFile, rm } from "node:fs/promises";
import { tmpdir } from "node:os";
import { join } from "node:path";
import { createRepo } from "../src/actions/repos.ts";
import { beatKeyOf, childDirOf } from "../src/actions/spawn.ts";
import { createApp, type App } from "../src/app.ts";
import { createUser } from "../src/core/users.ts";
import { commitFiles } from "../src/git/write.ts";
import { repoDir } from "../src/git/repos.ts";
import { createToken } from "../src/core/tokens.ts";
import { serve, type Servers } from "../src/http/server.ts";
import {
  childStandings,
  parseBeat,
  QUIET_MS,
  sendBeat,
  sign,
  SIGNATURE_HEADER,
} from "../src/spawn/heartbeat.ts";
import { familyLines, familyView } from "../src/spawn/family.ts";
import { firstBoot } from "../src/spawn/first-boot.ts";
import { quietLogs } from "./helpers/globals.ts";
quietLogs();
const PASSWORD = "a-long-family-passphrase";
describe("family heartbeats", () => {
  let dir = "";
  let parent: App;
  let child: App;
  let servers: Servers;
  let key = "";
  let adminCookie = "";
  let bobCookie = "";
  const post = (body: string, sig: string | null) =>
    fetch(`${servers.url}/api/v1/heartbeat`, {
      method: "POST",
      headers: sig === null ? {} : { [SIGNATURE_HEADER]: sig },
      body,
    });
  const beat = (o: Record<string, unknown> = {}) =>
    JSON.stringify({
      name: "maria",
      at: Date.now(),
      version: "0.7.114",
      openProposals: 3,
      children: 0,
      ...o,
    });
  const signIn = async (username: string) => {
    const res = await fetch(`${servers.url}/signin`, {
      method: "POST",
      body: new URLSearchParams({ username, password: PASSWORD }),
      redirect: "manual",
    });
    return (res.headers.get("set-cookie") ?? "").split(";")[0]!;
  };
  const family = async (cookie?: string) =>
    (
      await fetch(`${servers.url}/family`, {
        headers: cookie === undefined ? {} : { cookie },
      })
    ).text();
  beforeAll(async () => {
    dir = await mkdtemp(join(tmpdir(), "forge-family-"));
    parent = createApp({ dataDir: dir, url: "https://forge.test", port: 0 });
    const alice = await createUser(parent.db, {
      trusted: true,
      username: "alice",
      email: "[email protected]",
      password: PASSWORD,
      isAdmin: true,
    });
    const bob = await createUser(parent.db, {
      trusted: true,
      username: "bob",
      email: "[email protected]",
      password: PASSWORD,
    });
    if (!alice.ok || !bob.ok) throw new Error("users");
    const token = createToken(parent.db, alice.value.id, "rw", "rw").token;
    const repo = await createRepo(parent, alice.value, { name: "bakery" });
    if (!repo.ok) throw new Error("repo");
    const c = await commitFiles(repoDir(parent.reposRoot, "alice", "bakery"), {
      branch: "main",
      message: "bakery",
      files: [{ path: "README.md", content: "# bakery\n" }],
      author: { name: "a", email: "[email protected]" },
    });
    if (!c.ok) throw new Error("commit");
    servers = await serve(parent);
    const made = await fetch(`${servers.url}/api/v1/forges`, {
      method: "POST",
      headers: { authorization: `Bearer ${token}`, "content-type": "application/json" },
      body: JSON.stringify({ name: "maria", apps: ["alice/bakery"], dryRun: false }),
    });
    if (made.status !== 201) throw new Error(`spawn ${made.status}`);
    const { bodyId } = (await made.json()) as { bodyId: string };
    child = createApp({ dataDir: childDirOf(parent, bodyId), port: 0 });
    await firstBoot(child);
    key = (await beatKeyOf(parent, "maria")) ?? "";
    adminCookie = await signIn("alice");
    bobCookie = await signIn("bob");
  }, 60_000);
  afterAll(async () => {
    servers.stop();
    child.close();
    parent.close();
    await rm(dir, { recursive: true, force: true });
  });
  test("before any report a child reads as not heard from, not as an error", async () => {
    const html = await family(adminCookie);
    expect(html).toContain("maria");
    expect(html).toContain("has not reported yet");
    expect(html).not.toContain("quiet");
  });
  test("a heartbeat holds only name, time, version and two counts", () => {
    expect(parseBeat(beat())).toBeDefined();
    expect(parseBeat(beat({ title: "secret plans" }))).toBeUndefined();
    expect(parseBeat(beat({ openProposals: -1 }))).toBeUndefined();
    expect(parseBeat(beat({ version: "<b>" }))).toBeUndefined();
    expect(parseBeat(beat({ name: "../x" }))).toBeUndefined();
    expect(parseBeat("x".repeat(5000))).toBeUndefined();
  });
  test("unknown children, bad signatures and stale times are ignored alike", async () => {
    const stranger = beat({ name: "nobody" });
    const a = await post(stranger, sign(key, stranger));
    const own = beat();
    const b = await post(own, sign("not-the-key", own));
    const c = await post(own, null);
    const old = beat({ at: Date.now() - 3_600_000 });
    const d = await post(old, sign(key, old));
    for (const r of [a, b, c, d]) expect(r.status).toBe(404);
    const state = await childStandings(parent);
    expect(state.items[0]?.state).toBe("unheard");
  });
  test("a signed heartbeat is kept, shown with its standing, and not replayable", async () => {
    const at = Date.now();
    const body = beat({ at });
    expect((await post(body, sign(key, body))).status).toBe(200);
    expect((await post(body, sign(key, body))).status).toBe(404);
    const html = await family(adminCookie);
    expect(html).toContain("reporting");
    expect(html).toContain("version 0.7.114");
    expect(html).toContain("3 open proposals");
    expect(html).toMatch(/\d+ releases? behind/);
    const stored = await readFile(join(dir, "beats", "maria.json"), "utf8");
    expect(Object.keys(JSON.parse(stored).beat).sort()).toEqual([
      "at",
      "children",
      "name",
      "openProposals",
      "version",
    ]);
  });
  test("a child that stops reporting reads quiet", async () => {
    const state = await childStandings(parent, Date.now() + QUIET_MS + 60_000);
    expect(state.items[0]?.state).toBe("quiet");
    expect(state.items[0]?.lastSeen).not.toBeNull();
  });
  test("only an admin of the parent sees children", async () => {
    expect(await family(bobCookie)).not.toContain("maria");
    expect(await family()).not.toContain("maria");
    expect(await family(adminCookie)).toContain("maria");
  });
  test("a chunked body over 1 KiB is refused unread and keeps nothing", async () => {
    const before = (await childStandings(parent)).items[0]?.lastSeen;
    const big = beat({ version: "1".repeat(4000) });
    const res = await fetch(`${servers.url}/api/v1/heartbeat`, {
      method: "POST",
      headers: { [SIGNATURE_HEADER]: sign(key, big) },
      body: new ReadableStream({
        start(c) {
          c.enqueue(new TextEncoder().encode(big));
          c.close();
        },
      }),
      duplex: "half",
    } as RequestInit);
    expect(res.status).toBe(404);
    expect((await childStandings(parent)).items[0]?.lastSeen).toBe(before);
  });
  test("two identical beats at once keep only one", async () => {
    const body = beat({ at: Date.now() + 1000 });
    const rs = await Promise.all([post(body, sign(key, body)), post(body, sign(key, body))]);
    expect(rs.map((r) => r.status).sort()).toEqual([200, 404]);
  });
  test("the family has a JSON door and a terminal view with the same gate", async () => {
    const read = async (cookie?: string) =>
      (await (
        await fetch(`${servers.url}/api/v1/family`, {
          headers: cookie === undefined ? {} : { cookie },
        })
      ).json()) as { children: { name: string }[]; here: unknown };
    expect((await read()).children).toEqual([]);
    expect((await read(bobCookie)).children).toEqual([]);
    expect((await read(adminCookie)).children.map((c) => c.name)).toEqual(["maria"]);
    const guest = familyLines(await familyView(parent, false));
    const admin = familyLines(await familyView(parent, true));
    expect(guest.some(([k]) => k === "child maria")).toBe(false);
    expect(admin.some(([k]) => k === "child maria")).toBe(true);
  });
  test("a child sends its own beat, signed with the key spawn gave it", async () => {
    const sent: { url: string; body: string; sig: string }[] = [];
    const ok = await sendBeat(child, async (url, init) => {
      sent.push({
        url,
        body: String(init?.body),
        sig: String((init?.headers as Record<string, string>)[SIGNATURE_HEADER]),
      });
      return new Response("{}");
    });
    expect(ok).toBe(true);
    expect(sent[0]?.url).toBe("https://forge.test/api/v1/heartbeat");
    expect(sent[0]?.sig).toBe(sign(key, sent[0]!.body));
    expect(Object.keys(JSON.parse(sent[0]!.body)).sort()).toEqual([
      "at",
      "children",
      "name",
      "openProposals",
      "version",
    ]);
    // A forge that was not spawned has no one to tell.
    expect(await sendBeat(parent, async () => new Response("{}"))).toBe(false);
  });
});
@@ -183,6 +183,7 @@
describe("the forge over MCP", () => {
      "claim_link",
      "take_updates",
      "converge",
      "family",
      "next_steps",
      "thought",
      "asked",
@@ -358,6 +358,7 @@
describe("a spawned child's own keys and domain", () => {
      ) as Record<string, unknown>;
      expect(Object.keys(record).sort()).toEqual([
        "apps",
        "beatKey",
        "keepAccess",
        "name",
        "org",
@@ -87,6 +87,8 @@
describe("spawnForge", () => {
      keepAccess: false,
      // A hash only: what the parent answers to stays in its own ledger.
      statusHash: expect.stringMatching(/^[0-9a-f]{64}$/),
      // The child signs heartbeats to its parent with it (#425).
      beatKey: expect.stringMatching(/^[A-Za-z0-9_-]{20,}$/),
    });
  });
		@@ -86,6 +86,11 @@ sees `Reduced protection: …` in one line, under the filter on the terminal's
86	86	first screen and in the web footer; nobody else does, and a fully protected
87	87	forge shows nothing.
88	88
	89	The family across forges: `:` → Family in the terminal, `/family` on the web,
	90	`GET /api/v1/family` and the MCP `family` tool all give the same view. The
	91	forge that sent this one is shown to anyone; the forges it sent, only to a
	92	site admin (docs/SPAWN.md, "The family across forges").
	93
89	94	Passkeys: Settings → Passkeys lists, adds and removes them (several per
90	95	account; `src/auth/webauthn.ts` verifies, no dependency, `none` attestation).
91	96	The sign-in page's "Sign in with a passkey" gives the same HttpOnly session a
		@@ -48,6 +48,12 @@ Spawn makes the child's `secret.key` and SSH host key in the child's own directo
48	48
49	49	A spawner may give the child one credential: `modelKey`, an API-billed key (`sk-ant-api…`), with `budgetUsd`, a whole-life budget in dollars from 1 to 1000. A subscription token (`sk-ant-oat…`) is refused, because it is a person's own plan. The key never enters the plan, the dry run, the answer, the ledger or the idempotency table. In the child it is sealed with the child's own key as the account `starter` and granted to its organisation's crew. The budget is locked on that account (`lockBudget`): it is enforced where every run picks its account, whoever started the run and on whichever repository, and the child's admin cannot raise it, only add their own key. A retry with a different key is refused; a key is given once. Said plainly in every answer that carries a key (`keyNote`): the budget holds while this forge hosts the child, whose admin has no shell or database access; on a machine the child's owner controls, only a spend limit set at the provider binds the key, so use a key from a workspace with its own spend limit. The MCP `spawn` tool refuses `modelKey`, so a secret never passes through an agent's conversation. With no key the child is in a clean state: its pages say the crew has no model key yet and where an admin adds one.
50	50
	51	## The family across forges (#425)
	52
	53	`/family` draws the forge-level tree as nested lists: the parent (from `FORGE_PARENT_URL`, or the `upstream` in a spawned child's `parent.json`), this forge, and the forges it sent, each with last seen, version, releases behind this forge, and open proposals. Anyone may see the parent; only this forge's admins see children. Bounded: 100 children, four levels.
	54
	55	Children report in; the parent never reaches in. Every ten minutes a spawned child POSTs `/api/v1/heartbeat` (`src/spawn/heartbeat.ts`): `{name, at, version, openProposals, children}` and nothing else, signed HMAC-SHA256 over the body in `x-forge-signature` with a per-child `beatKey` that spawn put in the parent's ledger and the child's `parent.json`. A name the parent did not make, a bad signature, a time more than ten minutes off, a replay or any extra field gets the same 404 and changes nothing. The last beat per child is kept in `<data>/beats/<name>.json`. A child silent for thirty minutes reads "quiet", never an error; one never heard from reads "has not reported yet". Children made before this change have no key and stay unheard until respawned.
	56
51	57	## A client's forge in one form (#1608)
52	58
53	59	`/forges/new` is the whole path: a name, the owner's apps to fork, optionally one fresh app from a one-line description (`fresh`, at most 200 characters, one line), a budget with a model key; it ends in one claim link, shown once. Each picked app is a fork: its full history is copied and `parent.json` lists `apps: [{repo, upstream}]` so the child knows what it follows. A fresh app is a private repository in the child with a README, a `forge.json` and a tiny `index.ts` that answers `/` with the sentence, escaped; its name is the sentence's slug, never one of the forked names. A custom domain is not part of this: the child is reached at `<name>--<host>` and nothing else is promised. The same field is on `POST /api/v1/forges` and the MCP `spawn` (`fresh`). It is absent from the plan when unsaid, so older plan hashes are unchanged.
		@@ -59,6 +59,7 @@ export const GATE: readonly string[] = [
59	59	"test/health.test.ts",
60	60	"test/client-address.test.ts",
61	61	"test/client-list.test.ts",
	62	"test/family-heartbeat.test.ts",
62	63	"test/contents-api.test.ts",
63	64	"test/crew-agents-only.test.ts",
64	65	"test/crew-brief-audience.test.ts",
		@@ -109,6 +109,11 @@ interface Ledger {
109	109	* last happened); the child keeps only its hash. Never in an answer.
110	110	*/
111	111	statusToken?: string;
	112	/**
	113	* The key a child signs its heartbeats with (`spawn/heartbeat.ts`); the
	114	* child holds the same one in its `parent.json`. Never in an answer.
	115	*/
	116	beatKey?: string;
112	117	}
113	118
114	119	const SAFE_ID = /^[A-Za-z0-9_-]{1,80}$/;
		@@ -220,8 +225,9 @@ async function make(
220	225	}
221	226	if (ledger.done)
222	227	return ok({ name: plan.name, org: plan.org, url: liveChildUrl(app, plan.name), bodyId: ledger.bodyId, existed: true });
223		if (ledger.statusToken === undefined) {
224		ledger.statusToken = secret();
	228	if (ledger.statusToken === undefined \|\| ledger.beatKey === undefined) {
	229	ledger.statusToken ??= secret();
	230	ledger.beatKey ??= secret();
225	231	await writeLedger(app, ledger);
226	232	}
227	233	} else {
		@@ -241,6 +247,7 @@ async function make(
241	247	apps: plan.apps.map((a) => a.ref),
242	248	createdAt: new Date().toISOString(),
243	249	statusToken: secret(),
	250	beatKey: secret(),
244	251	};
245	252	await writeLedger(app, ledger);
246	253	}
		@@ -437,6 +444,8 @@ async function copyInto(
437	444	: { forgeCode: { repo: `${plan.org}/forge`, upstream: forgeCode.value } }),
438	445	// Only the hash: the parent alone holds what it answers to.
439	446	...(ledger.statusToken === undefined ? {} : { statusHash: sha256(ledger.statusToken) }),
	447	// The key the child signs its heartbeats with; the parent holds the same.
	448	...(ledger.beatKey === undefined ? {} : { beatKey: ledger.beatKey }),
440	449	}),
441	450	);
442	451	return ok(mintClaim(child.db, org.id));
		@@ -613,6 +622,11 @@ export async function statusTokenOf(app: App, name: string): Promise<string \| un
613	622	return (await readLedger(app, name))?.statusToken;
614	623	}
615	624
	625	/** The key a child of this forge signs heartbeats with; undefined for a name this forge did not make. */
	626	export async function beatKeyOf(app: App, name: string): Promise<string \| undefined> {
	627	return (await readLedger(app, name))?.beatKey;
	628	}
	629
616	630	/** One child, as the ledger keeps it. */
617	631	export interface Child {
618	632	readonly name: string;
		@@ -66,6 +66,7 @@ export const SYSTEM_NAMES: readonly string[] = [
66	66	"boards",
67	67	"events",
68	68	"explore",
	69	"family",
69	70	"fleet",
70	71	"flow",
71	72	"front",
		@@ -47,6 +47,8 @@ import { emailVerified } from "../core/verify.ts";
47	47	import { readHealth } from "../actions/health.ts";
48	48	import { listChildren } from "../actions/spawn.ts";
49	49	import { forgeState, PARENT_HEADER } from "../spawn/clients.ts";
	50	import { familyView } from "../spawn/family.ts";
	51	import { receiveBeat, SIGNATURE_HEADER } from "../spawn/heartbeat.ts";
50	52	import { reissueDoor, spawnDoor } from "../spawn/door.ts";
51	53	import { listSecrets, putSecret, removeSecret } from "../actions/secrets.ts";
52	54	import { proposeUpstream } from "../actions/upstream.ts";
		@@ -4134,6 +4136,23 @@ export function apiRoutes(router: Router<Handler>): void {
4134	4136	return json(state);
4135	4137	});
4136	4138
	4139	// A child's signed heartbeat (docs/SPAWN.md): counts and version, never
	4140	// data. Every refusal is the same 404, so nothing says who is a child.
	4141	router.add("POST", "/api/v1/heartbeat", async (ctx) => {
		sentinelcrew 29d ago outdated High: this trusts the declared Content-Length. A chunked request has none, so `length` is 0 and `ctx.request.text()` reads up to REQUEST_MAX on an endpoint that needs no sign-in. Use `readBounded(ctx.request, 1024)` from `src/http/limits.ts` and send `too_large` back as the same 404. sentinelcrew 29d ago Good: capped by bytes read, signed, the same 404 for every refusal. Non-blocking: the paired test would pass without the cap (`parseBeat` already rejects >1 KiB). A multi-chunk stream that asserts an early cut-off would pin it.
	4142	const bytes = await readBounded(ctx.request, 1024);
	4143	if (bytes === "too_large") return apiError("not_found", 404, "no such door");
	4144	const raw = new TextDecoder().decode(bytes);
	4145	const kept = await receiveBeat(ctx.app, raw, ctx.request.headers.get(SIGNATURE_HEADER));
	4146	return kept ? json({ ok: true }) : apiError("not_found", 404, "no such door");
	4147	});
	4148
	4149	// The family (#425): the parent for anyone, the children for an admin.
	4150	router.add("GET", "/api/v1/family", async (ctx) => {
	4151	const denied = ctx.auth.user === undefined ? undefined : requireScope(ctx, "ro");
	4152	if (denied) return denied;
	4153	return json(await familyView(ctx.app, ctx.auth.user?.isAdmin === true));
	4154	});
	4155
4137	4156	// A forge's children (docs/SPAWN.md): an admin's, planned before made.
4138	4157	router.add("GET", "/api/v1/forges", async (ctx) => {
4139	4158	const denied = requireScope(ctx, "ro");
		@@ -40,6 +40,7 @@ import {
40	40	import { holdPull, releasePull } from "../actions/holds.ts";
41	41	import { openPlan, parsePlan, PLAN_MAX } from "../actions/plan.ts";
42	42	import { cancelRepoRun } from "../actions/runs.ts";
	43	import { familyView } from "../spawn/family.ts";
43	44	import { clientRows } from "../spawn/clients.ts";
44	45	import { reissueDoor, spawnDoor } from "../spawn/door.ts";
45	46	import { contextNote, parseContext } from "../actions/tell_context.ts";
		@@ -1157,6 +1158,16 @@ const TOOLS: readonly Tool[] = [
1157	1158	});
1158	1159	},
1159	1160	},
	1161	{
	1162	name: "family",
	1163	description:
	1164	"The forge's family across forges: the forge that sent this one (anyone) and, for a site admin, the forges it sent, each as last heard — reporting, quiet (silent for thirty minutes) or unheard — with version, releases behind, open proposals. The same data as /family and /api/v1/family.",
	1165	inputSchema: { type: "object", properties: {} },
	1166	writes: false,
	1167	async run(ctx, user) {
	1168	return good(await familyView(ctx.app, user.isAdmin === true));
	1169	},
	1170	},
1160	1171	{
1161	1172	name: "next_steps",
1162	1173	description:
		@@ -203,6 +203,7 @@ import {
203	203	} from "../web/studio/actions.ts";
204	204	import { everydayCreate, everydayKeep, everydaySwitch } from "../web/pages/everyday.ts";
205	205	import { claimFragmentPage, claimSubmit } from "../web/pages/claim.ts";
	206	import { familyPage } from "../web/pages/family.ts";
206	207	import { forgeLinkSubmit, forgesPage } from "../web/pages/forges.ts";
207	208	import { newForgePage, newForgeSubmit } from "../web/pages/new-forge.ts";
208	209	import { askedPage } from "../web/studio/asked_page.ts";
		@@ -580,6 +581,7 @@ export function buildRouter(): Router<Handler> {
580	581	router.add("POST", "/claim", claimSubmit);
581	582	// "+ New forge": the spawn door as a page, any signed-in person (spawn/door.ts).
582	583	router.add("GET", "/forges", forgesPage);
	584	router.add("GET", "/family", familyPage);
583	585	router.add("POST", "/forges/:name/claim-link", forgeLinkSubmit);
584	586	router.add("GET", "/forges/new", newForgePage);
585	587	router.add("POST", "/forges/new", newForgeSubmit);
		@@ -12,6 +12,7 @@ import { createApp } from "./app.ts";
12	12	import { reconcile } from "./core/reconcile.ts";
13	13	import { syncAllPillars } from "./actions/pillars.ts";
14	14	import { firstBoot } from "./spawn/first-boot.ts";
	15	import { startHeartbeat } from "./spawn/heartbeat.ts";
15	16	import { pruneSessions } from "./core/sessions.ts";
16	17	import { runDelivery } from "./core/webhooks.ts";
17	18	import { isHookName, runHookClient } from "./git/hooks.ts";
		@@ -320,6 +321,8 @@ const crew = appsOn && !crewHeldOff
320	321	// A spawned child's first boot: its direction, opened once for its planner
321	322	// (spawn/first-boot.ts). A forge that was not spawned is untouched.
322	323	await firstBoot(app);
	324	// A spawned child reports its standing to its parent (spawn/heartbeat.ts).
	325	const heartbeatTimer = startHeartbeat(app);
323	326	// Prompts from Instagram (docs/APPS.md): once a day, for each repository
324	327	// that connected an account, the top comment on its latest Reel is told to
325	328	// the crew. A minute's clock; nothing leaves the box until a source exists.
		@@ -465,6 +468,7 @@ function shutdown(signal: NodeJS.Signals): void {
465	468	// process that replaced this one, not to this one while it finishes.
466	469	drainStreams();
467	470	clearInterval(deliveryTimer);
	471	clearInterval(heartbeatTimer);
468	472	clearInterval(syncTimer);
469	473	clearInterval(staleTimer);
470	474	clearInterval(leaseTimer);
		@@ -0,0 +1,59 @@
	1	/**
	2	* The family as plain data (#425): one answer for the page, the JSON read,
	3	* the MCP tool and the terminal. Anyone sees the parent; only a site admin
	4	* sees the children, so the gate lives here and nowhere else.
	5	*/
	6
	7	import type { App } from "../app.ts";
	8	import { parentForgeFor } from "../core/parent_releases.ts";
	9	import { running } from "../kernel/version.ts";
	10	import { childStandings, parentUpstream, type ChildStanding } from "./heartbeat.ts";
	11
	12	export interface FamilyView {
	13	readonly parent: { readonly url: string; readonly host: string; readonly behind: number \| null } \| null;
	14	readonly here: { readonly host: string \| null; readonly version: string };
	15	readonly children: readonly ChildStanding[];
	16	readonly more: number;
	17	}
	18
	19	export async function familyView(app: App, isAdmin: boolean): Promise<FamilyView> {
	20	const known = parentForgeFor(app.config);
	21	const url = app.config.parentUrl ?? (await parentUpstream(app));
	22	const kids = isAdmin ? await childStandings(app) : { items: [], more: 0 };
	23	return {
	24	parent:
	25	url === undefined
	26	? null
	27	: { url, host: known?.host ?? new URL(url).host, behind: known?.behind ?? null },
	28	here: {
	29	host: app.config.url === undefined ? null : new URL(app.config.url).host,
	30	version: running().version,
	31	},
	32	children: kids.items,
	33	more: kids.more,
	34	};
	35	}
	36
	37	/** The view as plain lines, for a terminal. */
	38	export function familyLines(view: FamilyView): [string, string][] {
	39	const out: [string, string][] = [];
	40	if (view.parent !== null) {
	41	out.push(["parent", view.parent.url]);
	42	if (view.parent.behind !== null)
	43	out.push(["", view.parent.behind === 0 ? "this forge is up to date" : `this forge is ${view.parent.behind} behind`]);
	44	} else out.push(["parent", "none"]);
	45	out.push(["this forge", `${view.here.host ?? "here"} · version ${view.here.version}`]);
	46	for (const c of view.children) {
	47	const bits =
	48	c.state === "unheard"
	49	? ["has not reported yet"]
	50	: [
	51	c.state,
	52	c.version === null ? "" : `version ${c.version}`,
	53	c.openProposals === null ? "" : `${c.openProposals} open`,
	54	].filter((b) => b !== "");
	55	out.push([`child ${c.name}`, bits.join(" · ")]);
	56	}
	57	if (view.more > 0) out.push(["", `${view.more} more not shown`]);
	58	return out;
	59	}