4e24dff · 974ebff · 7615678 · 0cf97e7 · ba38efc · b17e261
@@ -233,6 +233,7 @@
bytes in `tools/list`. After changing a tool run `bun scripts/mcp-table.ts`;
| `whoami_can` | `role`, `passkeys` | What you can do: your role and its roles-table row, yes or no each | 231 |
| `write_file` | — | Commit one file to a branch | 302 |
| `report` | — | Report a problem in a public repository, no account needed | 468 |
| `start` | — | Start building with no account: an account, a repo, a live app and a token in one call | 358 |
<!-- mcp-tools:end -->
The complete list, with schemas, is MCP `tools/list` called with a token.
@@ -0,0 +1,25 @@
# Start: an agent builds with only the forge's URL
      
        sentinelcrew
        1d ago
        
      
      Both doors: no src/tui/ screen for claiming or for the agent_start setting. The terminal must offer what the page does, gated the same way, with its entry where AGENTS.md says. This doc then covers the terminal path too.
    
This page is for agents and the people who run them. No account, token or crew is needed to begin.
## Start
```
curl -sX POST https://forge.open-platform.sh/api/v1/start -d '{"name":"my-app"}'
```
`name` is required; `description` and `agent` are optional. The answer holds `user`, `token` (shown once), `repo`, `git`, `app` and `claim`. The MCP `start` tool does the same and needs no token.
## Build
Clone `git.url` (it carries the token) and `git push` to main. `app.url` is live after the deploy. Issues and pulls work as on any repo. An unclaimed account has no crew, spends no credits, runs a small app and reaches no host but the package registries.
## Claim
Give `claim.url` to a person. They open it and sign in (or, where the forge's sign-up is open, make an account there), and the agent account and its repos become theirs, with the agent as a member. The link works once; if no repository can be moved it is given back, and one that cannot move stays with the agent and is named. Where sign-up is closed or by invite, the claim page makes no account: the person signs in.
In the terminal, **Take an agent's work** in the palette (any person) asks for the link, names the repositories and moves them after a confirm: the same claim, the same gate.
## Limits
Per source: 3 starts an hour and 10 a day. For the forge: 200 a day. Counts and the insert are one transaction, so concurrent calls cannot overshoot. One source can use at most 5% of the day's share; against abuse from many addresses an admin sets **Agents can start here** to invite code or off. Unclaimed accounts sleep after 7 days and are archived (never deleted) after 30; claiming wakes them. A site admin sets **Agents can start here** (open, invite code, off) in `/admin/limits`, or with `a` on the **Invite links** screen in the terminal (admins who are people).
@@ -0,0 +1,90 @@
/**
 * Taking an agent's account (#10912): the person who opens the one-time
 * claim link the start call returned, signed in, takes it. The agent's
 * repositories move to a new organisation the person owns, and the agent
 * stays in it as a member with write; the account wakes if it slept and
 * its archived repositories are woken. The link is burnt in the one
 * statement that checks it, so of two people racing on it one wins. A
 * repository that will not move stays with the agent and is reported; when
 * none moves the link is given back.
 */
import type { App } from "../app.ts";
import { setSuspended } from "../core/accounts.ts";
import { addTeamMember, createOrg, createTeam } from "../core/orgs.ts";
import { listReposOwnedBy, moveArchived, type Repo } from "../core/repos.ts";
import { markClaimed, startByClaim } from "../core/starts.ts";
import { transferRepo } from "../core/transfer.ts";
import { getUserById, type User } from "../core/users.ts";
import { err, ok, type Result } from "../kernel/result.ts";
export type ClaimError = "not_found" | "claimed" | "not_a_person" | "failed";
export const CLAIM_WORDS: Readonly<Record<ClaimError, string>> = {
  not_found: "This claim link is not one this forge made.",
  claimed: "This link was already used: someone has taken the account.",
  not_a_person: "Only a person's account can take this.",
  failed: "The account could not be moved; nothing was kept. Try the link again.",
};
export interface ClaimView {
  readonly agent: string;
  readonly repos: readonly string[];
  readonly claimed: boolean;
}
/** What a link holds, for the page that offers it: nothing secret. */
export function viewClaim(app: App, claimToken: string): ClaimView | undefined {
  const row = startByClaim(app.db, claimToken);
  const agent = row === undefined ? undefined : getUserById(app.db, row.userId);
  if (row === undefined || agent === undefined) return undefined;
  return {
    agent: agent.username,
    repos: listReposOwnedBy(app.db, agent.id).map((r) => `${r.ownerName}/${r.name}`),
    claimed: row.claimedAt !== null,
  };
}
export async function claimStart(
  app: App,
  claimer: User | undefined,
  claimToken: string,
  now: Date = new Date(),
): Promise<Result<{ org: string; repos: string[]; stayed: string[] }, ClaimError>> {
  const row = startByClaim(app.db, claimToken);
  const agent = row === undefined ? undefined : getUserById(app.db, row.userId);
  if (row === undefined || agent === undefined) return err("not_found");
  if (row.claimedAt !== null) return err("claimed");
  if (claimer === undefined || claimer.kind !== "user" || claimer.id === agent.id) return err("not_a_person");
  if (!markClaimed(app.db, agent.id, claimer.id, now)) return err("claimed");
  let org = createOrg(app.db, `${agent.username}-team`, claimer.id);
  if (!org.ok && org.error === "name_taken")
    org = createOrg(app.db, `${agent.username}-team-${Date.now().toString(36)}`, claimer.id);
  const team = org.ok ? createTeam(app.db, org.value.id, "agents", "write") : undefined;
  if (!org.ok || team === undefined || !team.ok || !addTeamMember(app.db, team.value, agent.id)) {
    // Nothing moved yet: give the link back.
    app.db.query("UPDATE start_account SET claimed_at = NULL, claimed_by = NULL WHERE user_id = ?1").run(agent.id);
    return err("failed");
  }
  const moved: Repo[] = [];
      
        sentinelcrew
        1d ago
        outdated
      
      A failed transferRepo is swallowed: the claim stays burnt and the repo stays with the agent. moveArchived(..., false) runs on the old repo regardless. The person is told "Taken" with fewer repos, and the link is spent. Fix: on any failed transfer, give the link back (as the org failure does) or report the repos that did not move. Wake only the repos that moved. Add a test.
    
  const stayed: string[] = [];
  for (const repo of listReposOwnedBy(app.db, agent.id)) {
    const done = await transferRepo(app.db, app.reposRoot, repo, org.value, claimer.id);
    if (done.ok) {
      moved.push(done.value);
      moveArchived(app.db, done.value.id, false);
    } else stayed.push(`${repo.ownerName}/${repo.name}`);
  }
  if (moved.length === 0 && stayed.length > 0) {
    // Nothing moved: give the link back.
    app.db.query("UPDATE start_account SET claimed_at = NULL, claimed_by = NULL WHERE user_id = ?1").run(agent.id);
    return err("failed");
  }
  setSuspended(app.db, agent.id, null);
  app.bus.append({
    kind: "start.claimed",
    actorId: claimer.id,
    payload: { agent: agent.username, org: org.value.username, repos: moved.length },
  });
  return ok({ org: org.value.username, repos: moved.map((r) => `${r.ownerName}/${r.name}`), stayed });
}
@@ -16,6 +16,7 @@
import { audienceFor } from "../core/audience.ts";
import { lacks } from "../core/roles.ts";
import { activeEdgeToken } from "../http/edge.ts";
import { sshTellCommand } from "../ssh/command.ts";
import { getAgentStart } from "../settings/agent_start.ts";
import { mcpPointers, TOKEN_FREE_TOOLS } from "../core/mcp_card.ts";
import type { App } from "../app.ts";
import { appsRuntime } from "../apps/runtime.ts";
@@ -331,6 +332,16 @@
function forgeActions(
      http: "GET /api/v1/changelog",
      mcp: "releases",
    },
    ...(getAgentStart(app.db) === "off"
      ? []
      : [
          {
            do: "start building with no account",
            http: "POST /api/v1/start",
            mcp: "start",
            ...tokenFree("start"),
          },
        ]),
    {
      do: "read the HTTP contract",
      http: "GET /contract/openapi.json",
@@ -12,6 +12,7 @@
import {
  type SignupChange,
  type SignupMode,
} from "../settings/signup.ts";
import { getAgentStart, parseAgentStart, setAgentStart, type AgentStartMode } from "../settings/agent_start.ts";
import { forgeSource, parseForgeSource, setForgeSource, storedForgeSource } from "../settings/forge_source.ts";
import type { User } from "../core/users.ts";
import { err, ok, type Result } from "../kernel/result.ts";
@@ -69,3 +70,22 @@
export function changeForgeSource(
  setForgeSource(app.db, name.value, who.value.id);
  return ok(name.value);
}
/** The agent-start setting (`settings/agent_start.ts`), for a forge admin who is a person. */
export function readAgentStart(app: App, actor: User | undefined): Result<AgentStartMode, "not_found"> {
  const who = admin(actor);
  return who.ok ? ok(getAgentStart(app.db)) : who;
}
export function changeAgentStart(
  app: App,
  actor: User | undefined,
  raw: unknown,
): Result<AgentStartMode, "not_found" | "invalid_agent_start"> {
  const who = admin(actor);
  if (!who.ok) return who;
  const mode = parseAgentStart(raw);
  if (!mode.ok) return mode;
  setAgentStart(app.db, mode.value, who.value.id);
  return ok(mode.value);
}
@@ -0,0 +1,201 @@
/**
 * The start call (#10912): an agent holding only the forge's URL gets an
 * account, a public repository from the app template and its app, and a
 * token for that account, in one call. No person and no crew are in it.
 *
 * The door is open to strangers, so its limits are mechanical:
 *
 * - **The setting.** `agent_start` (`settings/agent_start.ts`): open, a
 *   code (an open invite link's token, spent with the account), or off.
 * - **Capped.** A few starts per source per hour, ten per source per day, and
 *   a few hundred a day for the whole forge, counted from the rows the starts
 *   left, so a restart forgets nothing. The counts and the insert are one
 *   transaction, so concurrent calls cannot overshoot. One source cannot take
 *   more than `PER_SOURCE_PER_DAY / PER_DAY` of the day; a forge that sees
 *   abuse from many addresses sets `agent_start` to a code or off.
 * - **Held small.** The account stays a guest (no crew, no credits), its
 *   app runs small with no host but the package registries, and it sleeps
 *   after a week unclaimed and is archived, never deleted, after a month
 *   (`core/starts.ts`, `sweepStarts`).
 * - **Shown.** The app is public under the agent's name.
 *
 * The token is returned once; the claim link is returned once and kept as a
 * hash (`actions/claim.ts` is what opens it).
 */
import type { App } from "../app.ts";
import { appsRuntime } from "../apps/runtime.ts";
import { createToken } from "../core/tokens.ts";
import { createUser, discardFreshUser } from "../core/users.ts";
import { inviteOpen, redeemInvite } from "../core/invites.ts";
import { ARCHIVE_DAYS, SLEEP_DAYS, recordStart, startsSince } from "../core/starts.ts";
import { secret } from "../kernel/id.ts";
import { err, ok, type Result } from "../kernel/result.ts";
import { getAgentStart } from "../settings/agent_start.ts";
import { noEmail } from "./users.ts";
      
        sentinelcrew
        1d ago
        outdated
      
      MEDIUM (denial of service): PER_DAY=200 is a global cap that one source can exhaust at 3 per hour per address, or many addresses. That closes the door for every honest agent, and each start also deploys a public app that runs stranger-supplied code. Also, the check-then-insert for the caps is not atomic, so concurrent calls overshoot them. Fix: count and insert in one transaction, and give the daily cap a bounded share per source or an admin setting. Document the abuse bound in the pull.
    
import { newApp } from "./apps.ts";
export const PER_SOURCE_PER_HOUR = 3;
export const PER_SOURCE_PER_DAY = 10;
export const PER_DAY = 200;
export const NAME_MAX = 40;
export const DESCRIPTION_MAX = 2000;
export const AGENT_MAX = 64;
const HOUR_MS = 3_600_000;
const DAY_MS = 86_400_000;
export interface StartInput {
  readonly name?: unknown;
  readonly description?: unknown;
  readonly agent?: unknown;
  /** The token of an open invite link, when the forge asks for one. */
  readonly code?: unknown;
}
export type StartError =
  | "off"
  | "code_needed"
  | "invalid_name"
  | "invalid_description"
  | "invalid_agent"
  | "rate_limited"
  | "full"
  | "failed";
export type StartRefusal = { readonly error: StartError; readonly retryAfter?: number };
/** What each refusal says; the shape of the call is in `START_HINT`. */
export const START_WORDS: Readonly<Record<StartError, string>> = {
  off: "Agents cannot start here: the owner turned the start call off. A person can sign in or ask for an invitation.",
  code_needed: "This forge asks for an invite code: send it as `code`.",
  invalid_name: `name is 1-${NAME_MAX} characters with a letter or digit in it`,
  invalid_description: `description is plain text of at most ${DESCRIPTION_MAX} characters`,
  invalid_agent: `agent is a name of at most ${AGENT_MAX} letters, digits, . _ -`,
  rate_limited: "Too many starts from here; wait and send again.",
  full: "This forge has started its share of agents for today; try again tomorrow.",
  failed: "The start could not be finished; nothing was kept. Try again.",
};
export const START_HINT =
  `send JSON {name, description?, agent?}: name 1-${NAME_MAX} characters, description at most ` +
  `${DESCRIPTION_MAX}, agent your name (letters, digits, . _ -)`;
export interface Started {
  readonly user: { readonly username: string };
  /** Scoped to that account (read and write); shown once. */
  readonly token: string;
  readonly repo: string;
  readonly git: { readonly url: string; readonly push: string };
  readonly app: { readonly url: string | null };
  /** One-time link a person opens to take the account and its repositories. */
  readonly claim: { readonly url: string; readonly sleepsAfterDays: number; readonly archivedAfterDays: number };
}
/** The name as a repository and account name: lowercase letters, digits, dashes. */
export function nameSlug(raw: string): string {
  return raw
    .toLowerCase()
    .replace(/[^a-z0-9]+/g, "-")
    .replace(/^-+|-+$/g, "")
    .slice(0, 28)
    .replace(/-+$/g, "");
}
const hex = (n: number): string =>
  Array.from(crypto.getRandomValues(new Uint8Array(n)), (b) => b.toString(16).padStart(2, "0")).join("");
export async function startBuilding(
  app: App,
  input: StartInput,
  source: string,
  origin: string,
  now: Date = new Date(),
): Promise<Result<Started, StartRefusal>> {
  const refuse = (error: StartError, retryAfter?: number): Result<never, StartRefusal> =>
    err(retryAfter === undefined ? { error } : { error, retryAfter });
  const mode = getAgentStart(app.db);
  if (mode === "off") return refuse("off");
  const code = typeof input.code === "string" ? input.code : "";
  if (mode === "code" && !inviteOpen(app.db, code)) return refuse("code_needed");
  const given = typeof input.name === "string" ? input.name.trim() : "";
  const base = nameSlug(given);
  if (given === "" || given.length > NAME_MAX || base === "") return refuse("invalid_name");
  const description = input.description === undefined ? "" : input.description;
  if (typeof description !== "string" || description.length > DESCRIPTION_MAX || /[\0]/.test(description))
    return refuse("invalid_description");
  const agent = input.agent === undefined ? "" : input.agent;
  if (typeof agent !== "string" || agent.length > AGENT_MAX || !/^[A-Za-z0-9._-]*$/.test(agent))
    return refuse("invalid_agent");
  const capped = (): StartRefusal | undefined => {
    if (startsSince(app.db, new Date(now.getTime() - HOUR_MS), source) >= PER_SOURCE_PER_HOUR)
      return { error: "rate_limited", retryAfter: 3600 };
    if (startsSince(app.db, new Date(now.getTime() - DAY_MS), source) >= PER_SOURCE_PER_DAY)
      return { error: "rate_limited", retryAfter: 3600 };
    if (startsSince(app.db, new Date(now.getTime() - DAY_MS)) >= PER_DAY) return { error: "full" };
    return undefined;
  };
  // Cheap early refusal; the binding count is the one inside the transaction below.
  const early = capped();
  if (early !== undefined) return err(early);
  // The account: a person-shaped one with no password, which only its token signs in.
  let username = `${base}-${hex(2)}`;
  let made = await createUser(app.db, {
    origin: "start",
    username,
    email: noEmail(username),
    displayName: agent === "" ? base : agent,
    trusted: true,
  });
  if (!made.ok && made.error === "username_taken") {
    username = `${base}-${hex(3)}`;
    made = await createUser(app.db, {
      origin: "start",
      username,
      email: noEmail(username),
      displayName: agent === "" ? base : agent,
      trusted: true,
    });
  }
  if (!made.ok) return refuse("failed");
  const user = made.value;
  const undo = (): void => discardFreshUser(app.db, user.id);
  const claimToken = `claim_${secret()}`;
  let refusal: StartRefusal | undefined;
  try {
    app.db.transaction(() => {
      refusal = capped();
      if (refusal !== undefined) throw new Error("capped");
      if (mode === "code" && !redeemInvite(app.db, code, user.id)) throw new Error("code spent");
      recordStart(app.db, user.id, claimToken, source, now);
    })();
  } catch {
    undo();
    if (refusal !== undefined) return err(refusal);
    return refuse(mode === "code" ? "code_needed" : "failed");
  }
  // The repository and its app; a taken app name gets a suffix once.
  let made2 = await newApp(app, user, { name: base, description, visibility: "public" });
  if (!made2.ok && made2.error === "slug_taken")
    made2 = await newApp(app, user, { name: `${base}-${hex(2)}`, description, visibility: "public" });
  if (!made2.ok) {
    undo();
    return refuse("failed");
  }
  const { repo, app: record } = made2.value;
  const token = createToken(app.db, user.id, "start", "rw");
  app.bus.append({ kind: "start.made", repoId: repo.id, actorId: user.id, payload: {} });
  const url = `${origin}/${user.username}/${repo.name}.git`;
  return ok({
    user: { username: user.username },
    token: token.token,
    repo: `${user.username}/${repo.name}`,
    git: { url, push: `git push ${url.replace("://", `://${user.username}:${token.token}@`)} HEAD:main` },
    app: { url: appsRuntime(app)?.urlFor(record, "production") ?? null },
    claim: { url: `${origin}/claim/start/${claimToken}`, sleepsAfterDays: SLEEP_DAYS, archivedAfterDays: ARCHIVE_DAYS },
  });
}
@@ -0,0 +1,29 @@
/**
 * The life of an unclaimed account (#10912): asleep after `SLEEP_DAYS`
 * (suspended, so its token and its app stop answering), archived after
 * `ARCHIVE_DAYS` (its repositories archived), never deleted. A claim wakes
 * all of it (`actions/claim.ts`). Run from the daily maintenance tick.
 */
import type { App } from "../app.ts";
import { setSuspended } from "../core/accounts.ts";
import { listReposOwnedBy, moveArchived } from "../core/repos.ts";
import { dueToArchive, dueToSleep, markArchived, markSlept } from "../core/starts.ts";
export function sweepStarts(app: App, now: Date = new Date()): { slept: number; archived: number } {
  const stamp = now.toISOString();
  let slept = 0;
  let archived = 0;
  for (const userId of dueToSleep(app.db, now)) {
    setSuspended(app.db, userId, stamp);
    app.db.query("DELETE FROM token WHERE user_id = ?1").run(userId);
    markSlept(app.db, userId, now);
    slept++;
  }
  for (const userId of dueToArchive(app.db, now)) {
    for (const repo of listReposOwnedBy(app.db, userId)) moveArchived(app.db, repo.id, true, stamp);
    markArchived(app.db, userId, now);
    archived++;
  }
  if (slept + archived > 0) app.bus.append({ kind: "start.swept", payload: { slept, archived } });
  return { slept, archived };
}
@@ -104,6 +104,7 @@
import {
  type EnvName,
} from "./data.ts";
import { parseManifest, type AppManifest } from "./manifest.ts";
import { heldManifest } from "../core/starts.ts";
import { identityKey } from "./proxy.ts";
import { noteReached } from "./egress_report.ts";
import { cellHooks } from "./egress_refused.ts";
@@ -1509,7 +1510,9 @@
export class AppsRuntime {
      readFileAt(bare, run.commitOid, "forge.json"),
      readFileAt(bare, run.commitOid, "package.json"),
    ]);
    const manifest = parseManifest(forgeJson, packageJson);
    const parsed = parseManifest(forgeJson, packageJson);
    // An agent's unclaimed account runs small, with no host but the registries (#10912).
    const manifest = parsed.ok ? { ...parsed, value: heldManifest(this.app.db, repo.ownerId, parsed.value) } : parsed;
    clock.lap("manifest");
    if (!manifest.ok) {
      return {
@@ -2026,6 +2029,7 @@
export class AppsRuntime {
    };
    const manifest = parseManifest(read("forge.json"), read("package.json"));
    if (!manifest.ok) return false;
    const owner = getRepoById(this.app.db, record.repoId)?.ownerId;
    const state = this.envFor(record, env);
    if (state.live !== undefined || state.deploying !== undefined) return true;
    // The deploy that built this checkout, in an earlier life: its log is
@@ -2039,7 +2043,7 @@
export class AppsRuntime {
    state.asleep = {
      commitOid,
      dir,
      manifest: manifest.value,
      manifest: owner === undefined ? manifest.value : heldManifest(this.app.db, owner, manifest.value),
      runId: built?.id ?? "",
      since: new Date().toISOString(),
    };
@@ -349,6 +349,7 @@
export { route as postApiV1ReposOwnerNameTransfer } from "./postApiV1ReposOwnerN
export { route as postApiV1ReposOwnerNameUpstreamCheck } from "./postApiV1ReposOwnerNameUpstreamCheck.ts";
export { route as postApiV1Sessions } from "./postApiV1Sessions.ts";
export { route as postApiV1Share } from "./postApiV1Share.ts";
export { route as postApiV1Start } from "./postApiV1Start.ts";
export { route as postApiV1Thoughts } from "./postApiV1Thoughts.ts";
export { route as postApiV1Tokens } from "./postApiV1Tokens.ts";
export { route as postApiV1UserEmailVerify } from "./postApiV1UserEmailVerify.ts";
@@ -0,0 +1,23 @@
import type { Route } from "../shared.ts";
export const route: Route = {
  method: "post",
  path: "/api/v1/start",
  summary:
    "Start building with no account (an agent holding only the forge's URL): answers 201 { user: { username }, token, repo: \"owner/name\", git: { url, push }, app: { url }, claim: { url, sleepsAfterDays, archivedAfterDays } }. It makes an agent account, a public repository from the app template and its app; the token (read and write, that account only) and the claim link are shown once; `git push` to main deploys; a person opens `claim.url` to take the account and its repositories. Unclaimed it has no crew and no credits, runs small with no outbound host but the package registries, sleeps after 7 days and is archived after 30. A few starts per source an hour and a cap per day; refused from another origin with 403 forbidden; the owner's setting can turn it off or ask for an invite `code`",
  auth: false,
  role: "anonymous",
  status: 201,
  body: { name: "string", description: "string", agent: "string", code: "string" },
  refusals: {
    off: "403, the owner turned the start call off",
    code_needed: "403, this forge asks for an open invite link's token as `code`",
    rate_limited: "429, too many starts from this source; retry-after says when",
    full: "429, the forge has started its share for today",
    too_large: "413, the body is over the limit for a stranger's",
    invalid_name: "422, name is 1-40 characters with a letter or digit",
    invalid_description: "422, description is plain text of at most 2000 characters",
    invalid_agent: "422, agent is at most 64 letters, digits, . _ -",
    failed: "500, nothing was kept; try again",
  },
};
@@ -179,6 +179,10 @@
const READER_KINDS: ReadonlySet<string> = new Set([
  "traffic.capture_started",
  "traffic.networks_imported",
  "crew.governed",
  // Starts by an agent with only the URL (#10912): the forge owner hears them.
  "start.made",
  "start.claimed",
  "start.swept",
]);
/**
@@ -55,7 +55,7 @@
export function apiCatalog(origin: string) {
 * `http/mcp.ts` answers these and refuses the rest with 401. The card and
 * `/api/v1/here` both read this list, so they cannot drift.
 */
export const TOKEN_FREE_TOOLS: readonly string[] = ["report"];
export const TOKEN_FREE_TOOLS: readonly string[] = ["report", "start"];
/** A thin plugin the forge ships for a harness: where its source is and its one install line. */
export interface HarnessPlugin {
@@ -0,0 +1,1 @@
a74cde1d88d8302958aba970b12f8e86d912f720fc1bd4007a177722e40e33a8
@@ -0,0 +1,19 @@
// An agent that came with only the forge's URL (#10912): one row per account the
// start call made, holding the hash of its one-time claim link, where it came
// from (a hashed source, for the per-hour cap) and where it is in its life:
// asleep after 7 days unclaimed, archived after 30, claimed by a person.
// Additive.
export default `
  CREATE TABLE start_account (
    user_id    TEXT PRIMARY KEY REFERENCES user(id) ON DELETE CASCADE,
    claim_hash TEXT NOT NULL UNIQUE,
    source     TEXT NOT NULL,
    created_at TEXT NOT NULL,
    slept_at   TEXT,
    archived_at TEXT,
    claimed_at TEXT,
    claimed_by TEXT
  ) WITHOUT ROWID;
  CREATE INDEX start_account_created ON start_account (created_at);
  CREATE INDEX start_account_source ON start_account (source, created_at);
  `;
@@ -9,6 +9,7 @@
 */
import type { Database } from "bun:sqlite";
import { isUnclaimed } from "./starts.ts";
export const ROLES = ["guest", "member", "admin"] as const;
export type Role = (typeof ROLES)[number];
@@ -86,7 +87,10 @@
export function lacks(
  ability: Ability,
): boolean {
  if (user.kind !== "user") return false;
  return !can(roleOf(db, user), ability);
  // An account an agent started may make its first app and nothing a member
  // may spend on: it stays a guest, so no crew runs for it (#10912).
  if (can(roleOf(db, user), ability)) return false;
  return !(ability === "make_it_yours" && isUnclaimed(db, user.id));
}
/**
@@ -0,0 +1,162 @@
/**
 * Accounts an agent made by itself with the start call (`actions/start.ts`,
 * #10912), and where each is in its life. Pure data: no authz, no events.
 *
 * Unclaimed they are held small: no outbound host but the package registries,
 * a small app, no crew, and — after `SLEEP_DAYS` — asleep (suspended), then —
 * after `ARCHIVE_DAYS` — archived, never deleted. A person's claim ends all
 * of it. The claim link is kept as a sha256, like a token.
 */
import type { Database } from "bun:sqlite";
import { sha256 } from "../kernel/hash.ts";
export const SLEEP_DAYS = 7;
export const ARCHIVE_DAYS = 30;
const DAY_MS = 86_400_000;
/** What an unclaimed account's app may use: small, whatever forge.json says. */
export const SMALL_APP = { memoryMiB: 128, cpus: 0.25, diskMiB: 256 } as const;
export interface StartRow {
  readonly userId: string;
  readonly createdAt: string;
  readonly sleptAt: string | null;
  readonly archivedAt: string | null;
  readonly claimedAt: string | null;
  readonly claimedBy: string | null;
}
interface Raw {
  user_id: string;
  created_at: string;
  slept_at: string | null;
  archived_at: string | null;
  claimed_at: string | null;
  claimed_by: string | null;
}
const toRow = (r: Raw): StartRow => ({
  userId: r.user_id,
  createdAt: r.created_at,
  sleptAt: r.slept_at,
  archivedAt: r.archived_at,
  claimedAt: r.claimed_at,
  claimedBy: r.claimed_by,
});
/** A source (an address) is kept only as a hash: enough to count, never to read. */
export const sourceKey = (source: string): string => sha256(`start-source:${source}`).slice(0, 24);
export function recordStart(
  db: Database,
  userId: string,
  claimToken: string,
  source: string,
  at: Date = new Date(),
): void {
  db.query(
    "INSERT INTO start_account (user_id, claim_hash, source, created_at) VALUES (?1, ?2, ?3, ?4)",
  ).run(userId, sha256(claimToken), sourceKey(source), at.toISOString());
}
/** Starts made since `since`: from one source, or by everyone. */
export function startsSince(db: Database, since: Date, source?: string): number {
  const at = since.toISOString();
  const row =
    source === undefined
      ? db.query<{ n: number }, [string]>("SELECT COUNT(*) AS n FROM start_account WHERE created_at >= ?1").get(at)
      : db
          .query<{ n: number }, [string, string]>(
            "SELECT COUNT(*) AS n FROM start_account WHERE source = ?2 AND created_at >= ?1",
          )
          .get(at, sourceKey(source));
  return row?.n ?? 0;
}
export function startOfAccount(db: Database, userId: string): StartRow | undefined {
  const row = db.query<Raw, [string]>("SELECT * FROM start_account WHERE user_id = ?1").get(userId);
  return row === null ? undefined : toRow(row);
}
/** The row a claim link names, claimed or not. */
export function startByClaim(db: Database, claimToken: string): StartRow | undefined {
  const row = db
    .query<Raw, [string]>("SELECT * FROM start_account WHERE claim_hash = ?1")
    .get(sha256(claimToken));
  return row === null ? undefined : toRow(row);
}
/**
 * Burn the link for `claimedBy`, in the one statement that checks it: of two
 * people racing on one link, one wins.
 */
export function markClaimed(db: Database, userId: string, claimedBy: string, at: Date = new Date()): boolean {
  return (
    db
      .query(
        "UPDATE start_account SET claimed_at = ?1, claimed_by = ?2 WHERE user_id = ?3 AND claimed_at IS NULL",
      )
      .run(at.toISOString(), claimedBy, userId).changes === 1
  );
}
/** Whether the account is one an agent started that nobody has claimed. */
export function isUnclaimed(db: Database, userId: string): boolean {
  return (
    db
      .query<{ n: number }, [string]>("SELECT 1 AS n FROM start_account WHERE user_id = ?1 AND claimed_at IS NULL")
      .get(userId) !== null
  );
}
/**
 * A manifest as an unclaimed owner may run it: no host but the package
 * registries (the install steps add those themselves), and the small size
 * whatever `forge.json` asked for. A claimed or ordinary owner's passes whole.
 */
export function heldManifest<M extends { egress?: readonly string[] | undefined; limits?: object | undefined }>(
  db: Database,
  ownerId: string,
  manifest: M,
): M {
  if (!isUnclaimed(db, ownerId)) return manifest;
  const asked = (manifest.limits ?? {}) as Record<string, number | undefined>;
  const least = (key: keyof typeof SMALL_APP): number => Math.min(asked[key] ?? SMALL_APP[key], SMALL_APP[key]);
  return {
    ...manifest,
    egress: [],
    limits: { ...asked, memoryMiB: least("memoryMiB"), cpus: least("cpus"), diskMiB: least("diskMiB") },
  };
}
/** Unclaimed accounts made before `cutoff` that have not reached the stage yet. */
export function dueToSleep(db: Database, now: Date): string[] {
  const cutoff = new Date(now.getTime() - SLEEP_DAYS * DAY_MS).toISOString();
  return db
    .query<{ user_id: string }, [string]>(
      "SELECT user_id FROM start_account WHERE claimed_at IS NULL AND slept_at IS NULL AND created_at <= ?1",
    )
    .all(cutoff)
    .map((r) => r.user_id);
}
export function dueToArchive(db: Database, now: Date): string[] {
  const cutoff = new Date(now.getTime() - ARCHIVE_DAYS * DAY_MS).toISOString();
  return db
    .query<{ user_id: string }, [string]>(
      "SELECT user_id FROM start_account WHERE claimed_at IS NULL AND archived_at IS NULL AND created_at <= ?1",
    )
    .all(cutoff)
    .map((r) => r.user_id);
}
export function markSlept(db: Database, userId: string, at: Date): void {
  db.query("UPDATE start_account SET slept_at = ?1 WHERE user_id = ?2").run(at.toISOString(), userId);
}
export function markArchived(db: Database, userId: string, at: Date): void {
  db.query("UPDATE start_account SET archived_at = ?1, slept_at = COALESCE(slept_at, ?1) WHERE user_id = ?2").run(
    at.toISOString(),
    userId,
  );
}
@@ -126,7 +126,9 @@
export type CreateUserError =
 *
 * Every other origin is a named exemption, made by someone the forge already
 * trusts: a claim link the owner handed out, an admin's everyday account, a
 * crew member the admin adds, a spawned forge's seed accounts, the
 * crew member the admin adds, a spawned forge's seed accounts, the account an
 * agent's start call makes (`start`, held by the agent-start setting) and
 * the person who opens that account's claim link (`claimer`), the
 * operator's first admin (`first-admin`, from the one-time code only the
 * operator is shown), and `seed` for code that sets a forge up directly (the
 * chaos world, test fixtures).
@@ -139,7 +141,7 @@
export type CreateUserError =
 */
export type StrangerOrigin = "signup" | "passkey";
export type AdminOrigin = "claim" | "first-admin" | "seed";
export type ExemptOrigin = AdminOrigin | "everyday" | "agent" | "spawn";
export type ExemptOrigin = AdminOrigin | "everyday" | "agent" | "spawn" | "start" | "claimer";
export type AccountOrigin =
  /**
   * `invite` is the token of an invite link (`core/invites.ts`): while
@@ -277,6 +279,8 @@
function admission(db: Database, input: AccountOrigin): Admission {
    case "everyday":
    case "agent":
    case "spawn":
    case "start":
    case "claimer":
    case "first-admin":
    case "seed":
      return ADMITTED;
@@ -381,6 +381,7 @@
import { buildCartRoutes } from "./api/build_cart.ts";
import { iterationRoutes } from "./api/iterations.ts";
import { appNoteRoutes } from "./api/app_notes.ts";
import { reportRoutes } from "./api/reports.ts";
import { startRoutes } from "./api/start.ts";
import { rollbackRoutes } from "./api/rollback.ts";
import { takeBackRoutes } from "./api/take_back.ts";
import { conversationConfirmRoutes } from "./api/conversation_confirms.ts";
@@ -2136,6 +2137,7 @@
export function apiRoutes(router: Router<Handler>): void {
  issueRoutes(router);
  reportRoutes(router);
  startRoutes(router);
  appNoteRoutes(router);
  rollbackRoutes(router);
  takeBackRoutes(router);
@@ -0,0 +1,35 @@
/**
 * `POST /api/v1/start` (#10912): an agent with only the forge's URL gets an
 * account, a repository from the app template, its app and a token in one
 * call. No token, no session; the rules and limits are `actions/start.ts`.
 * A browser page from another site is refused: an agent is not one.
 */
import { START_HINT, START_WORDS, startBuilding } from "../../actions/start.ts";
import { REQUEST_MAX } from "../../core/reports.ts";
import { crossOrigin, type Handler } from "../context.ts";
import { clientBucket } from "../peer.ts";
import { apiError, boundedBody, json, tryAgain } from "../respond.ts";
import type { Router } from "../router.ts";
export function startRoutes(router: Router<Handler>): void {
  router.add("POST", "/api/v1/start", async (ctx) => {
    if (crossOrigin(ctx.request, ctx.url, ctx.app.log))
      return apiError("forbidden", 403, "send this call from your agent, not from a page on another site");
    const input = await boundedBody(ctx.request, REQUEST_MAX);
    if (input === "too_large") return apiError("too_large", 413, START_HINT);
    const started = await startBuilding(ctx.app, input, clientBucket(ctx.request), ctx.url.origin);
    if (started.ok)
      return json(started.value, 201, {
        // The token and the claim link are shown once: nothing may keep them.
        "cache-control": "no-store",
      });
    const refusal = started.error;
    const said = START_WORDS[refusal.error];
    if (refusal.error === "rate_limited" || refusal.error === "full")
      return tryAgain(refusal.error, 429, said, refusal.retryAfter ?? 3600);
    if (refusal.error === "off") return apiError("off", 403, said);
    if (refusal.error === "code_needed") return apiError("code_needed", 403, said);
    if (refusal.error === "failed") return apiError("failed", 500, said);
    return apiError(refusal.error, 422, `${said}; ${START_HINT}`);
  });
}
@@ -32,6 +32,7 @@
import { clientBucket } from "./peer.ts";
import { TOKEN_FREE_TOOLS } from "../core/mcp_card.ts";
import { proofOf } from "./report_filer.ts";
import { fileReport } from "../actions/reports.ts";
import { START_HINT, START_WORDS, startBuilding } from "../actions/start.ts";
import { REPORT_RECEIVED } from "../actions/report_words.ts";
import { BODY_MAX, REQUEST_MAX, TITLE_MAX } from "../core/reports.ts";
import { everydayOf } from "../core/everyday.ts";
@@ -55,7 +56,7 @@
export function toolEntries(tools: readonly (typeof TOOLS)[number][]) {
        ? {}
        : { _meta: { ui: { resourceUri: CARD_URI(CARD_OF_TOOL[t.name]!) } } }),
    })),
    { name: REPORT_TOOL.name, description: REPORT_TOOL.description, inputSchema: REPORT_TOOL.inputSchema },
    ...[REPORT_TOOL, START_TOOL].map((t) => ({ name: t.name, description: t.description, inputSchema: t.inputSchema })),
  ];
}
@@ -277,11 +278,34 @@
export const REPORT_TOOL = {
  },
} as const;
/**
 * `start`, the other tool open without a token (#10912): an agent with only
 * the forge's URL gets an account, a repository, its app and a token; the
 * same call as `POST /api/v1/start` (`actions/start.ts`).
 */
export const START_TOOL = {
  name: "start",
  /** Its line in /llms.txt's `## MCP tools`; never sent to a client. */
  doc: "`{ name, description? }`: an account, repo, live app and token; push to main to deploy; `claim` is for a person",
  writes: true,
  description: "Start building with no account: an account, a repo, a live app and a token in one call.",
  inputSchema: {
    type: "object",
    properties: {
      name: { type: "string", maxLength: 40 },
      description: { type: "string", maxLength: 2000 },
      agent: { type: "string", maxLength: 64 },
      code: { type: "string", maxLength: 100 },
    },
    required: ["name"],
  },
} as const;
/** What a token-free tool does with its call: the JSON-RPC answer. One entry per name in TOKEN_FREE_TOOLS. */
type FreeHandler = (ctx: Ctx, id: unknown, args: Args) => unknown;
/** The gate picks its handler here, so a name listed in TOKEN_FREE_TOOLS without one is caught by a test. */
export const TOKEN_FREE_HANDLERS: Readonly<Record<string, FreeHandler>> = { report: reportAnswer };
export const TOKEN_FREE_HANDLERS: Readonly<Record<string, FreeHandler>> = { report: reportAnswer, start: startAnswer };
/** The JSON-RPC answer to a token-free tool call, or undefined for any other message. */
function reportCall(ctx: Ctx, message: unknown): unknown | undefined {
@@ -357,11 +381,26 @@
function reportAnswer(ctx: Ctx, id: unknown, args: Args): unknown {
  );
}
async function startAnswer(ctx: Ctx, id: unknown, args: Args): Promise<unknown> {
  const text = (t: string, isError = false) => ({
    jsonrpc: "2.0",
    id,
    result: { content: [{ type: "text", text: t }], ...(isError ? { isError } : {}) },
  });
  const started = await startBuilding(ctx.app, args, clientBucket(ctx.request), ctx.url.origin);
  if (started.ok) return text(JSON.stringify(started.value));
  const e = started.error;
  return text(
    `${e.error}: ${START_WORDS[e.error]}${e.retryAfter === undefined ? "" : ` (try again in ${e.retryAfter} seconds)`} ${START_HINT}`,
    true,
  );
}
const NOT_HERE = (allow: string): Response =>
  new Response(null, { status: 405, headers: { allow } });
/** Every tool name the forge lists, admin-only ones included. */
export const toolNames = (): string[] => [...TOOLS.map((t) => t.name), REPORT_TOOL.name];
export const toolNames = (): string[] => [...TOOLS.map((t) => t.name), REPORT_TOOL.name, START_TOOL.name];
/** What each tool declares about itself, for the test that walks them all. */
export const toolRegistry = () =>
@@ -383,7 +422,7 @@
export function mcpRoutes(router: Router<Handler>): void {
    ) {
      const message: unknown = await body(ctx.request);
      const reported = reportCall(ctx, message);
      if (reported !== undefined) return json(reported);
      if (reported !== undefined) return json(await reported);
      const answer = await rpcOne(ctx, user, message);
      if (answer === undefined) return new Response(null, { status: 202 });
      return json(answer);
@@ -397,7 +436,7 @@
export function mcpRoutes(router: Router<Handler>): void {
        413,
      );
    const reported = reportCall(ctx, message);
    if (reported !== undefined) return json(reported);
    if (reported !== undefined) return json(await reported);
    // The refusal keeps the OAuth challenge a client starts from, and names
    // the one thing a stranger can do without signing in.
    return new Response(
@@ -405,7 +444,7 @@
export function mcpRoutes(router: Router<Handler>): void {
        error: "unauthorized",
        hint: "Send `Authorization: Bearer <token>` with a token you hold, then repeat the call; without one, only the `report` tool answers.",
        message:
          "send a forge token: Authorization: Bearer <token>. Without one, the tool `report` (tools/call, name \"report\", arguments {repo, title, body?, page?, agent?}) files a problem report on a public repository; see /llms.txt",
          "send a forge token: Authorization: Bearer <token>. Without one, the tool `start` (tools/call, name \"start\", arguments {name, description?, agent?}) makes you an account, a repo and a live app with a token; and the tool `report` (tools/call, name \"report\", arguments {repo, title, body?, page?, agent?}) files a problem report on a public repository; see /llms.txt",
        report: {
          method: "tools/call",
          name: "report",
@@ -4,7 +4,7 @@
 * description, and its bytes in `tools/list`. The doc holds it between two
 * markers; test/mcp-table.test.ts fails, naming the tool, when they differ.
 */
import { REPORT_TOOL, toolEntries } from "./mcp.ts";
import { REPORT_TOOL, START_TOOL, toolEntries } from "./mcp.ts";
import { TOOLS } from "./mcp/tools.ts";
export const TABLE_BEGIN = "<!-- mcp-tools:begin (generated by src/http/mcp_table.ts; edit the code, then run `bun scripts/mcp-table.ts`) -->";
@@ -70,7 +70,7 @@
export function firstSentence(text: string): string {
export function toolRows(): ToolRow[] {
  const entries = toolEntries(TOOLS);
  const schemas = new Map<string, unknown>([...TOOLS.map((t) => [t.name, t.inputSchema] as const), [REPORT_TOOL.name, REPORT_TOOL.inputSchema]]);
  const schemas = new Map<string, unknown>([...TOOLS.map((t) => [t.name, t.inputSchema] as const), [REPORT_TOOL.name, REPORT_TOOL.inputSchema], [START_TOOL.name, START_TOOL.inputSchema]]);
  return entries.map((entry) => ({
    name: entry.name,
    doors: doorsOf(schemas.get(entry.name)),
@@ -17,6 +17,7 @@
import {
import { secureFor } from "./cookie_secure.ts";
import { refusedByDatabase, shownRefusal } from "./refusal.ts";
import { NOT_A_MEMBER } from "../core/roles.ts";
import { startClaimAccountSubmit, startClaimPage, startClaimSubmit } from "../web/pages/start_claim.ts";
import { signupOptions, signupPasskey } from "../web/pages/signup-passkey.ts";
import { toolbarComment, toolbarPage } from "../web/studio/toolbar.ts";
import { TOOLBAR_NAME, toolbarResponse } from "../apps/toolbar.ts";
@@ -31,7 +32,7 @@
import { adminDataPage, appDataPage, dataPage } from "../web/pages/data.ts";
import { fleetAct, fleetReceipt, fleetUndo } from "../web/pages/fleet-ops.ts";
import { maintenancePage, maintenancePrepare, maintenanceResume } from "../web/pages/maintenance.ts";
import { nightlyOutputPage, resiliencePage } from "../web/pages/resilience.ts";
import { limitsPage, limitsSet, quotasSet, signupSet, inviteMint, inviteRevoke } from "../web/pages/admin-limits.ts";
import { agentStartSet, limitsPage, limitsSet, quotasSet, signupSet, inviteMint, inviteRevoke } from "../web/pages/admin-limits.ts";
import { allFlowsPage } from "../web/pages/flows-all.ts";
import { measureSubmit } from "./measure.ts";
import { cspReportSubmit } from "./csp_report.ts";
@@ -480,7 +481,7 @@
import { viaGate } from "./via_gate.ts";
import { checksRecheckRoutes } from "./checks_recheck.ts";
import { feedRoutes } from "./feed.ts";
import type { Database } from "bun:sqlite";
import { mcpRoutes, REPORT_TOOL } from "./mcp.ts";
import { mcpRoutes, REPORT_TOOL, START_TOOL } from "./mcp.ts";
import { TOOLS } from "./mcp/tools.ts";
import { setMcpTools } from "../web/llms_tools.ts";
import { resourcePolicy } from "./corp.ts";
@@ -866,6 +867,9 @@
export function buildRouter(): Router<Handler> {
  router.add("GET", "/signin/parent", parentStart);
  router.add("GET", "/signin/parent/callback", parentCallback);
  router.add("GET", "/signup", signupPage);
  router.add("GET", "/claim/start/:token", startClaimPage);
  router.add("POST", "/claim/start/:token", startClaimSubmit);
  router.add("POST", "/claim/start/:token/account", startClaimAccountSubmit);
  router.add("GET", "/signup/requested", requestedPage);
  router.add("GET", "/verify", verifyPage);
  router.add("POST", "/signup", signupSubmit);
@@ -1036,6 +1040,7 @@
export function buildRouter(): Router<Handler> {
  router.add("POST", "/admin/limits", limitsSet);
  router.add("POST", "/admin/quotas", quotasSet);
  router.add("POST", "/admin/signup", signupSet);
  router.add("POST", "/admin/agent-start", agentStartSet);
  router.add("POST", "/admin/invites", inviteMint);
  router.add("POST", "/admin/invites/:id/revoke", inviteRevoke);
@@ -1150,7 +1155,7 @@
export function buildRouter(): Router<Handler> {
  // reclaim a path under `/api/`.
  // The forge as an MCP server: the studio's verbs for an assistant.
  mcpRoutes(router);
  setMcpTools(TOOLS, [REPORT_TOOL]);
  setMcpTools(TOOLS, [REPORT_TOOL, START_TOOL]);
  // The public API as OpenAPI, for any client that reads it.
  openapiRoute(router);
  oauthRoutes(router);
@@ -4,6 +4,7 @@
 * environment-only — a handful of variables, all with sane defaults.
 */
import { sweepStarts } from "./actions/start_sweep.ts";
import { scanNightly } from "./checks/scan.ts";
import { nightlyDue } from "./checks/scan_store.ts";
import { runModelReview } from "./actions/model_review.ts";
@@ -671,6 +672,10 @@
const followTimer = setInterval(
  60_000,
);
const staleTimer = setInterval(() => void during("asks", tickAsks), 120_000);
// Accounts an agent started and nobody claimed sleep after a week and are
// archived after a month (`actions/start_sweep.ts`, #10912): hourly, and on boot.
const startsTimer = setInterval(() => during("starts", () => void sweepStarts(app)), 3_600_000);
during("starts", () => void sweepStarts(app));
void during("asks", tickAsks);
// Every start is counted, and one that follows a process that never said
@@ -898,6 +903,7 @@
function drain(signal: NodeJS.Signals): Promise<unknown> {
  clearInterval(reachTimer);
  clearInterval(syncTimer);
  clearInterval(staleTimer);
  clearInterval(startsTimer);
  clearInterval(followTimer);
  stopClogTick();
  stopKeeper();
@@ -0,0 +1,38 @@
/**
 * Whether an agent holding only the forge's URL may start here
 * (`POST /api/v1/start`, #10912): `open`, `code` (a start call must bring an
 * open invite link's token, spent with the account) or `off`. Stored in
 * `forge_setting` under `agent_start`; every change is kept with who and when.
 * Default `open` when nothing is stored.
 */
import type { Database } from "bun:sqlite";
import { err, ok, type Result } from "../kernel/result.ts";
import { writeSetting } from "./limits.ts";
export const AGENT_START_MODES = ["open", "code", "off"] as const;
export type AgentStartMode = (typeof AGENT_START_MODES)[number];
export const AGENT_START_DEFAULT: AgentStartMode = "open";
const STORE_KEY = "agent_start";
export function parseAgentStart(raw: unknown): Result<AgentStartMode, "invalid_agent_start"> {
  return typeof raw === "string" && (AGENT_START_MODES as readonly string[]).includes(raw)
    ? ok(raw as AgentStartMode)
    : err("invalid_agent_start");
}
export function getAgentStart(db: Database): AgentStartMode {
  const row = db
    .query<{ value: string }, [string]>("SELECT value FROM forge_setting WHERE key = ?1")
    .get(STORE_KEY);
  if (row === null) return AGENT_START_DEFAULT;
  const parsed = parseAgentStart(row.value);
  return parsed.ok ? parsed.value : AGENT_START_DEFAULT;
}
/** Set the mode and keep the change; the same mode again keeps nothing. */
export function setAgentStart(db: Database, value: AgentStartMode, actorId: string): void {
  const from = getAgentStart(db);
  if (from === value) return;
  writeSetting(db, STORE_KEY, value, from, value, actorId);
}
@@ -0,0 +1,75 @@
/**
 * Taking an agent's work, in the terminal (#10912): what the claim page does
 * for a person with the link the start call returned. `t` asks for the link,
 * the screen says whose repositories it holds, and they move only after a
 * confirm. It goes through `claimStart`, so the gate is the page's: a person's
 * account, a link that is open; an agent is never offered it.
 */
import { claimStart, CLAIM_WORDS, viewClaim } from "../../actions/claim.ts";
import type { Ctx, Screen } from "../app/app.ts";
import { binding } from "../app/keys.ts";
import type { Session } from "../session.ts";
import { style } from "../term/style.ts";
import { truncate } from "../term/width.ts";
import { confirmScreen, promptScreen } from "./common.ts";
import type { PaletteEntry } from "./entries.ts";
/** The token of a claim link, whether the whole link or only its last part was typed. */
export const tokenOfLink = (typed: string): string => (typed.trim().split(/[?#]/)[0]!.split("/").filter((p) => p !== "").pop() ?? "").slice(0, 200);
export function claimStartScreen(f: Session, ctx: Ctx): Screen {
  let note = "Paste the claim link an agent gave you. t asks for it.";
  const offer = (typed: string): string | undefined | Promise<void> => {
    const token = tokenOfLink(typed);
    const seen = viewClaim(f.app, token);
    if (seen === undefined) return CLAIM_WORDS.not_found;
    if (seen.claimed) return CLAIM_WORDS.claimed;
    // The prompt closes itself when this returns; the confirm goes on after it.
    return Promise.resolve().then(() => ctx.push(
      confirmScreen(ctx, screen, {
        title: `Take ${seen.agent}'s work?`,
        body: [
          `${seen.repos.length} ${seen.repos.length === 1 ? "repository moves" : "repositories move"} to an organisation you own;`,
          "the agent stays in it as a member who can still push.",
          ...seen.repos.map((r) => `  ${r}`),
        ],
        actions: [{ label: "Take it" }, { label: "Cancel" }],
        onChoose: (i) => {
          if (i !== 0) return;
          void claimStart(f.app, f.user, token).then((done) => {
            note = done.ok
              ? `Taken: ${done.value.repos.join(", ")} now belong to ${done.value.org}.${done.value.stayed.length === 0 ? "" : ` Not moved: ${done.value.stayed.join(", ")}.`}`
              : CLAIM_WORDS[done.error];
            ctx.invalidate();
          });
        },
      }),
    ));
  };
  const screen: Screen = {
    title: "Take an agent's work",
    keys: [binding(["t"], "enter the link")],
    render(area, s) {
      const c = ctx.theme.c;
      s.text(area.x, area.y, truncate(note, area.w), style(c.mutedFg, c.bg), area.x + area.w);
    },
    key(e) {
      if (e.ctrl || e.alt || e.key !== "t") return false;
      ctx.push(promptScreen(ctx, screen, { title: "Claim link", label: "the link the agent gave you", onSubmit: offer }));
      return true;
    },
  };
  return screen;
}
/** A person's, as the claim page is: the link is the proof, the account is theirs. */
export const entry: PaletteEntry = {
  id: "claim-start",
  title: "Take an agent's work",
  hint: "claim the repositories an agent started, from its one-time link",
  after: ["invites", "repos"],
  offered: (session) => session.user?.kind === "user",
  run: (session, ctx) => ctx.push(claimStartScreen(session, ctx)),
};
@@ -41,6 +41,7 @@
import { entry as flowsAll } from "./flowsall.ts";
import { entry as front } from "./front.ts";
import { entry as forges } from "./forges.ts";
import { entry as homePins } from "./home_pins.ts";
import { entry as claimStart } from "./claim_start.ts";
import { entry as invites } from "./invites.ts";
import { entry as limits } from "./limits.ts";
import { entry as economics } from "./economics.ts";
@@ -136,6 +137,7 @@
export const ENTRIES: readonly PaletteEntry[] = [
  agents,
  archived,
  invites,
  claimStart,
  requests,
  bulk,
  subscriptions,
@@ -6,12 +6,14 @@
 * selected open one after a confirm (`y` revokes, `n` or esc keeps it). Both go through the actions, so the gate is theirs: an
 * admin who is a person; anyone else sees nothing and mints nothing. The top
 * line says who may sign up now, as MCP `signup` does; `s` picks open, invite
 * or closed, shows from → to and changes it only after a confirm.
 * or closed, shows from → to and changes it only after a confirm; `a` does the
 * same for who may start an agent here (open, code or off, `Agents can start here`).
 */
import { inviteLink, list, mint, revoke } from "../../actions/invites.ts";
import { INVITE_NOT_OPEN } from "../../actions/sever_invite_words.ts";
import { changeSignup, readSignup } from "../../actions/signup.ts";
import { changeAgentStart, changeSignup, readAgentStart, readSignup } from "../../actions/signup.ts";
import { AGENT_START_MODES, type AgentStartMode } from "../../settings/agent_start.ts";
import { SIGNUP_MODES, type SignupMode } from "../../settings/signup.ts";
import { DEFAULT_DAYS, MAX_DAYS, type Invite } from "../../core/invites.ts";
import type { Ctx, Screen } from "../app/app.ts";
@@ -71,6 +73,27 @@
export function invitesScreen(f: Session, ctx: Ctx): Screen {
    );
  };
  const agentStart = () => readAgentStart(f.app, f.user);
  const planAgentStart = (to: AgentStartMode): void => {
    const now = agentStart();
    if (!now.ok || now.value === to) return;
    const from = now.value;
    ctx.push(
      confirmScreen(ctx, screen, {
        title: "Agents can start here",
        body: [`Would set agent start from ${from} to ${to}.`],
        actions: [{ label: "Change" }, { label: "Cancel" }],
        onChoose: (i) => {
          if (i !== 0) return;
          const changed = changeAgentStart(f.app, f.user, to);
          note = changed.ok ? `agent start: ${from} → ${changed.value}.` : "You cannot change agent start.";
          ctx.invalidate();
        },
      }),
    );
  };
  const rows = (): ListRow[] =>
    items().map((i) => ({
      title: i.id,
@@ -86,7 +109,7 @@
export function invitesScreen(f: Session, ctx: Ctx): Screen {
        binding(["j", "k"], "move cursor"),
        binding(["m"], "make a link"),
        binding(["x"], "revoke"),
        ...(signup().ok ? [binding(["s"], "who may sign up")] : []),
        ...(signup().ok ? [binding(["s"], "who may sign up"), binding(["a"], "agents can start here")] : []),
      ];
    },
    render(area, s) {
@@ -95,7 +118,7 @@
export function invitesScreen(f: Session, ctx: Ctx): Screen {
      const sg = signup();
      const [top, head, body] = split(area, "v", [len(sg.ok ? 1 : 0), len(1), fill(1)]);
      if (sg.ok)
        s.text(top!.x, top!.y, truncate(`signup: ${sg.value.signup}. s changes it.`, top!.w), style(c.fg, c.bg), top!.x + top!.w);
        s.text(top!.x, top!.y, truncate(`signup: ${sg.value.signup}. s changes it; a, who may start an agent (${agentStart().ok ? (agentStart() as { value: string }).value : ""}).`, top!.w), style(c.fg, c.bg), top!.x + top!.w);
      const text =
        note !== ""
          ? note
@@ -153,6 +176,20 @@
export function invitesScreen(f: Session, ctx: Ctx): Screen {
            onPick: ([m]) => plan(m as SignupMode),
          }),
        );
      } else if (e.key === "a") {
        const now = agentStart();
        if (!now.ok) return false;
        ctx.push(
          pickerScreen(ctx, screen, {
            title: "Agents can start here",
            items: AGENT_START_MODES.map((m) => ({
              id: m,
              label: m,
              ...(m === now.value ? { hint: "now" } : {}),
            })),
            onPick: ([m]) => planAgentStart(m as AgentStartMode),
          }),
        );
      } else return false;
      return true;
    },
@@ -11,7 +11,8 @@
import { changeQuotas, readQuotas } from "../../actions/quotas.ts";
import { inviteLink, list as listInviteLinks, mint as mintInviteLink, revoke as revokeInviteLink } from "../../actions/invites.ts";
import { INVITE_NOT_OPEN } from "../../actions/sever_invite_words.ts";
import { DEFAULT_DAYS, MAX_DAYS } from "../../core/invites.ts";
import { changeSignup, readSignup } from "../../actions/signup.ts";
import { changeAgentStart, changeSignup, readAgentStart, readSignup } from "../../actions/signup.ts";
import { AGENT_START_MODES } from "../../settings/agent_start.ts";
import { SIGNUP_MEANS, SIGNUP_MODES } from "../../settings/signup.ts";
import { QUOTA_KEYS } from "../../settings/quotas.ts";
import type { Ctx } from "../../http/context.ts";
@@ -30,6 +31,7 @@
export function limitsPage(ctx: Ctx): Response {
  if (!listed.ok) return notFoundPage(ctx);
  const quotas = timePhase(ctx.request, "quotas", () => readQuotas(ctx.app, ctx.auth.user));
  const signup = timePhase(ctx.request, "signup", () => readSignup(ctx.app, ctx.auth.user));
  const agentStart = readAgentStart(ctx.app, ctx.auth.user);
  const invites = timePhase(ctx.request, "invites", () => listInviteLinks(ctx.app, ctx.auth.user));
  const rendering = performance.now();
  const { limits, changes } = listed.value;
@@ -138,6 +140,20 @@
export function limitsPage(ctx: Ctx): Response {
    </dd>
    <dd class="status-act"></dd>
  </div>`;
  const agentStartRow = html`<div class="status-row">
    <dt>Agents can start here</dt>
    <dd>
      <form class="row-fields" method="post" action="/admin/agent-start">
        <select class="input mono" name="agent_start" aria-label="Agents can start here">
          ${AGENT_START_MODES.map(
            (m) => html`<option value="${m}" ${agentStart.ok && agentStart.value === m ? "selected" : ""}>${m === "code" ? "invite code" : m}</option>`,
          )}
        </select>
        ${btn("Save", { size: "sm", variant: "primary", label: "Save agent start" })}
      </form>
    </dd>
    <dd class="status-act"></dd>
  </div>`;
  const inviteRows = (invites.ok ? invites.value : []).map((i) =>
    row({
      lead: icon("activity"),
@@ -180,7 +196,7 @@
export function limitsPage(ctx: Ctx): Response {
  const body = html`<p class="small muted mb">
      Every limit you can hit, and why. A change applies to the next request that meets it; nothing needs a restart.
    </p>
    <dl class="status-rows">${signupRow}${inviteRow}${quotaRow}</dl>
    <dl class="status-rows">${signupRow}${agentStartRow}${inviteRow}${quotaRow}</dl>
    ${historyBlock("Invite links made", inviteRows)}
    <section class="settings-block mt">
      <h2>Limits</h2>
@@ -287,6 +303,22 @@
export async function signupSet(ctx: Ctx): Promise<Response> {
  );
}
// POST /admin/agent-start
export async function agentStartSet(ctx: Ctx): Promise<Response> {
  if (ctx.auth.user?.isAdmin !== true || ctx.auth.user.kind === "agent") return notFoundPage(ctx);
  const form = await readForm(ctx, "admin");
  if (form instanceof Response) return form;
  const changed = changeAgentStart(ctx.app, ctx.auth.user, field(form, "agent_start"));
  if (!changed.ok && changed.error === "not_found") return notFoundPage(ctx);
  return flashTo(
    ctx,
    "/admin/limits",
    changed.ok
      ? { message: "Agent start saved." }
      : { tone: "danger", message: "Agents can start here: open, invite code or off." },
  );
}
// POST /admin/invites
export async function inviteMint(ctx: Ctx): Promise<Response> {
  if (ctx.auth.user?.isAdmin !== true || ctx.auth.user.kind === "agent")
@@ -0,0 +1,113 @@
/**
 * `/claim/start/:token` (#10912): the one-time link the start call returned. A
 * person opens it, signs in or makes an account on the spot, and takes the
 * agent's account and repositories (`actions/claim.ts`). The link is the
 * proof of the claim, not of the right to join: the form that makes an
      
        sentinelcrew
        1d ago
        outdated
      
      HIGH (security): POST /claim/start/:token/account makes a person account with no invite, whatever the signup setting says. Anyone can mint a claim link from the open start call, so a forge with signup closed or invite-only can be joined by anyone through start then claim. Fix: make the account only when signupMode allows it (apply the same admission as /signup), or refuse the account form and require an already signed-in person. Add a test with signup closed.
    
 * account is offered, and works, only where `/signup` would let a stranger in
 * (`signupClosed`, and not a passkey-only forge); otherwise the person signs in.
 */
import { claimStart, CLAIM_WORDS, viewClaim } from "../../actions/claim.ts";
import { noEmail, plausibleEmail, signupClosed } from "../../actions/users.ts";
import { notePhase, takeSessionTime } from "../../core/route_timing.ts";
import { createSession } from "../../core/sessions.ts";
import { createUser } from "../../core/users.ts";
import type { Ctx } from "../../http/context.ts";
import { notFoundPage, pageHead } from "../chrome.ts";
import { field, readForm } from "../form.ts";
import { html } from "../html.ts";
import { flashTo, page, redirect } from "../layout.ts";
import { btn, field as formField, icon, row } from "../ui.ts";
import { sessionCookie } from "./site.ts";
/** Whether a stranger may make an account here: what `/signup` allows, with no invite. */
const mayMakeAccount = (ctx: Ctx): boolean => !signupClosed(ctx.app) && ctx.app.config.passkeyOnlySignup !== true;
const tokenOf = (ctx: Ctx): string => ctx.params["token"] ?? "";
function withNoStore(response: Response): Response {
  response.headers.set("cache-control", "no-store");
  return response;
}
// GET /claim/start/:token
export function startClaimPage(ctx: Ctx, errors: { username?: string; password?: string; email?: string } = {}, status = 200): Response {
  notePhase(ctx.request, "session", takeSessionTime(ctx.request));
  const token = tokenOf(ctx);
  const seen = viewClaim(ctx.app, token);
  if (seen === undefined) return notFoundPage(ctx);
  const person = ctx.auth.user?.kind === "user" ? ctx.auth.user : undefined;
  const here = `/claim/start/${encodeURIComponent(token)}`;
  const body = html`<div class="narrow stack">
    ${pageHead("Take this agent's work")}
    ${seen.claimed
      ? html`<p>${CLAIM_WORDS.claimed}</p>`
      : html`<p>
            An agent named <strong>${seen.agent}</strong> started building here without an account. Taking it moves
            ${seen.repos.length === 1 ? "its repository" : `its ${seen.repos.length} repositories`} to an organisation
            you own, with the agent as a member who can still push. Nothing else changes.
          </p>
          <ul class="list">${seen.repos.map((r) => row({ lead: icon("repo"), title: html`<span class="mono">${r}</span>` }))}</ul>
          ${person !== undefined
            ? html`<form method="post" action="${here}">
                                ${btn("Take it", { variant: "primary", label: "Take this agent's work" })}
              </form>`
            : html`<p><a href="/signin?next=${encodeURIComponent(here)}">Sign in</a> to take it${mayMakeAccount(ctx) ? ", or make an account:" : "."}</p>
              ${!mayMakeAccount(ctx) ? null : html`<form method="post" action="${here}/account" class="stack">
                ${formField({ label: "Username", name: "username", autocomplete: "username", required: true, pattern: "[A-Za-z0-9][A-Za-z0-9._-]*", ...(errors.username ? { error: errors.username } : {}) })}
                ${formField({ label: "Email", name: "email", type: "email", autocomplete: "email", hint: "Optional.", ...(errors.email ? { error: errors.email } : {}) })}
                ${formField({ label: "Password", name: "password", type: "password", autocomplete: "new-password", required: true, minlength: 12, hint: "At least 12 characters.", ...(errors.password ? { error: errors.password } : {}) })}
                ${btn("Make an account and take it", { variant: "primary", label: "Make an account and take it" })}
              </form>`}`}`}
  </div>`;
  return withNoStore(page({ ctx, title: "Claim", body }, status));
}
/** The words a refused claim says. */
const refused = (ctx: Ctx, error: keyof typeof CLAIM_WORDS): Response =>
  error === "not_found" ? notFoundPage(ctx) : flashTo(ctx, `/claim/start/${encodeURIComponent(tokenOf(ctx))}`, { tone: "danger", message: CLAIM_WORDS[error] });
// POST /claim/start/:token — a signed-in person takes it
export async function startClaimSubmit(ctx: Ctx): Promise<Response> {
  const form = await readForm(ctx);
  if (form instanceof Response) return form;
  const done = await claimStart(ctx.app, ctx.auth.user, tokenOf(ctx));
  if (!done.ok) return refused(ctx, done.error);
  return flashTo(ctx, `/${done.value.org}`, { message: `Taken: ${done.value.repos.join(", ")} now belong to ${done.value.org}.${done.value.stayed.length === 0 ? "" : ` Not moved, still the agent's: ${done.value.stayed.join(", ")}.`}` });
}
// POST /claim/start/:token/account — a stranger makes an account and takes it
export async function startClaimAccountSubmit(ctx: Ctx): Promise<Response> {
  const form = await readForm(ctx);
  if (form instanceof Response) return form;
  const token = tokenOf(ctx);
  const seen = viewClaim(ctx.app, token);
  if (seen === undefined) return notFoundPage(ctx);
  if (seen.claimed) return refused(ctx, "claimed");
  if (!mayMakeAccount(ctx)) return flashTo(ctx, `/claim/start/${encodeURIComponent(token)}`, { tone: "danger", message: "New accounts are not open here: sign in to take it." });
  const username = field(form, "username").trim();
  const given = field(form, "email").trim();
  if (given !== "" && !plausibleEmail(given)) return startClaimPage(ctx, { email: "That does not look like an email address." }, 422);
  const made = await createUser(ctx.app.db, {
    origin: "claimer",
    username,
    email: given === "" ? noEmail(username) : given,
    password: field(form, "password"),
    ...(given === "" ? { trusted: true } : {}),
  });
  if (!made.ok) {
    const said = {
      invalid_username: { username: "Usernames are letters, digits, dots, dashes." },
      username_taken: { username: "That username is taken." },
      username_reserved: { username: "That username is reserved." },
      email_taken: { email: "That email already has an account: sign in instead." },
      weak_password: { password: "Passwords need at least 12 characters." },
      password_too_long: { password: "That password is too long." },
      signup_closed: { username: "Accounts cannot be made here." },
    }[made.error];
    return startClaimPage(ctx, said, 422);
  }
  const done = await claimStart(ctx.app, made.value, token);
  if (!done.ok) return refused(ctx, done.error);
  const session = createSession(ctx.app.db, made.value.id);
  return redirect(`/${done.value.org}`, sessionCookie(session.token, session.expiresAt, ctx.url, ctx.app.config.url));
}
@@ -423,12 +423,13 @@
function renderLlmsTxt(ctx: Ctx, o: string, tell: string | undefined, running: s
      "",
      "## Start here",
      "",
      "If you are an assistant helping a person: say plainly what you can and cannot do from where you are. If you cannot reach this forge or hold an account on it, give the person these steps to do by hand.",
      "If you are an assistant helping a person: say plainly what you can and cannot do from here. If you cannot reach this forge, give the person these steps.",
      "",
      `- Help build a public app here: each one is a repository at ${o}/{owner}/{name}. A person makes an account at ${o}/signup, then follows "Offer a change" below. By request, POST ${o}/api/v1/users gives 202 {state:"waiting"}; sign in to see. If /signup says 403, use "Report a problem" below, or run your own forge.`,
      `- Build now, no account: \`curl -sX POST ${o}/api/v1/start -d '{"name":"my-app"}'\` -> {user, token, repo, git, app, claim}. Clone git.url (user:token@), \`git push\` to main: app.url is live. Give claim.url to the person who takes it over. Unclaimed: asleep in 7 days, archived in 30.`,
      `- Or with an account: sign up at ${o}/signup, then follow "Offer a change" below. By request, POST ${o}/api/v1/users gives 202 {state:"waiting"}. If /signup says 403, use "Report a problem".`,
      `- Get your own forge: \`git clone ${UPSTREAM_REPO}.git && cd forge && bun install && bun run src/main.ts\`, then in a second terminal \`bun src/main.ts --first-admin\`, which prints a one-time link that makes you the admin. It needs Bun; its crew needs the claude CLI and a model credential. Or a hosted one, free within limits while hosting is not sold: sign in and open ${o}/forges/new (or call the MCP \`spawn\` tool with the person's consent). It sleeps when idle and wakes on its next page load, push or API call; the person brings their own model credential, or its crew stays off.`,
      `- Work from your own forge: connect it to this one as an origin, bring an app in, and send your work back. How: ${UPSTREAM_REPO}/raw/main/docs/ORIGINS.md`,
      `- Connect an assistant that can use tools: add a custom connector with the URL ${mcp.url}. It signs in with OAuth; only the report tool works without an account.`,
      `- Connect an assistant that uses tools: custom connector URL ${mcp.url} (OAuth); start and report need no account.`,
      "",
      "## Report a problem (no account)",
      "",
@@ -46,6 +46,7 @@
const UNREACHED: Record<string, { sites: number; why: string }> = {
  "src/apps/feedback.ts": { sites: 2, why: "the visitor cookie is set on a deployed app's own host from its feedback widget; covered by the feedback tests" },
  "src/web/pages/claim.ts": { sites: 1, why: "claiming the first admin seat needs a fresh forge with a claim link; same sessionCookie() as the walked doors" },
  "src/web/pages/first-admin.ts": { sites: 1, why: "first-admin recovery needs a forge with no admin; same sessionCookie() as the walked doors" },
  "src/web/pages/start_claim.ts": { sites: 1, why: "the claim of an agent's start needs a one-time token; same sessionCookie() as the walked doors; covered by test/start.test.ts" },
  "src/web/pages/signup-passkey.ts": { sites: 2, why: "sign-up by passkey needs an invite; same sessionCookie() as the walked doors" },
  "src/web/pages/map.ts": { sites: 1, why: "the map's last-looked cookie holds two timestamps, HttpOnly and Lax, and grants nothing; covered by test/roadmap.test.ts (name, HttpOnly, SameSite, no Secure over http)" },
  "src/web/pages/everyday.ts": { sites: 2, why: "the admin/everyday switch needs a paired account; same sessionCookie() as the walked doors" },
@@ -43,25 +43,26 @@
const section = (body: string): string[] => {
  return lines.slice(start + 1, end).filter((l) => l.startsWith("- "));
};
test("the anonymous text is small, varies by reader, and lists report plus one line", async () => {
test("the anonymous text is small, varies by reader, and lists report and start plus one line", async () => {
  const res = await fetch(`${servers.url}/llms.txt`);
  const body = await res.text();
  expect(Buffer.byteLength(body)).toBeLessThan(6 * 1024);
  expect(res.headers.get("vary")).toContain("Cookie");
  expect(res.headers.get("vary")).toContain("Authorization");
  const listed = section(body);
  expect(listed).toHaveLength(2);
  expect(listed).toHaveLength(3);
  expect(listed[0]).toStartWith("- report: ");
  expect(listed[1]).toContain(`${TOOLS.length} more tools with an account`);
  expect(listed[1]).toContain("tools/list");
  expect(listed[1]).toContain("/contract/openapi.json");
  expect(listed[1]).toStartWith("- start: ");
  expect(listed[2]).toContain(`${TOOLS.length} more tools with an account`);
  expect(listed[2]).toContain("tools/list");
  expect(listed[2]).toContain("/contract/openapi.json");
});
test("every tool the anonymous text names is one tools/list returns", async () => {
  const names = section(await fetch(`${servers.url}/llms.txt`).then((r) => r.text()))
    .map((l) => /^- ([a-z_]+): /.exec(l)?.[1])
    .filter((n): n is string => n !== undefined);
  expect(names).toEqual(["report"]);
  expect(names).toEqual(["report", "start"]);
  const returned: string[] = [];
  let cursor: string | undefined;
  do {
@@ -80,5 +81,5 @@
test("a signed-in reader still gets every tool and report", async () => {
  const body = await fetch(`${servers.url}/llms.txt`, {
    headers: { authorization: `Bearer ${token}` },
  }).then((r) => r.text());
  expect(section(body)).toHaveLength(TOOLS.length + 1);
  expect(section(body)).toHaveLength(TOOLS.length + 2);
});
@@ -5,7 +5,7 @@
import { tmpdir } from "node:os";
import { join } from "node:path";
import { createApp } from "../src/app.ts";
import { serve, type Servers } from "../src/http/server.ts";
import { REPORT_TOOL } from "../src/http/mcp.ts";
import { REPORT_TOOL, START_TOOL } from "../src/http/mcp.ts";
import { TOOLS } from "../src/http/mcp/tools.ts";
import { createToken } from "../src/core/tokens.ts";
import { createUser } from "../src/core/users.ts";
@@ -45,9 +45,9 @@
describe("/llms.txt MCP tools", () => {
    expect(start).toBeGreaterThan(-1);
    const end = lines.findIndex((l, i) => i > start && l.startsWith("## "));
    const listed = lines.slice(start + 1, end).filter((l) => l.startsWith("- "));
    const expected = [...TOOLS, REPORT_TOOL].map((t: Listed) => {
    const expected = [...TOOLS, REPORT_TOOL, START_TOOL].map((t: Listed) => {
      const admin = t.adminOnly === true || t.needsAdminScope === true ? " (admin)" : "";
      return `- ${t.name}: ${(t.doc ?? t.description).replace(/\s+/g, " ").trim()}${admin}${t.writes ? " (writes)" : ""}${t.name === "report" ? " (no account)" : ""}`;
      return `- ${t.name}: ${(t.doc ?? t.description).replace(/\s+/g, " ").trim()}${admin}${t.writes ? " (writes)" : ""}${t.name === "report" || t.name === "start" ? " (no account)" : ""}`;
    });
    expect(listed).toEqual(expected);
    expect(TOOLS.some((t) => t.writes)).toBe(true);
@@ -35,7 +35,7 @@
describe("the MCP server card", () => {
    expect(card.version).toBe(running().version);
    expect(card.transport).toBe("streamable-http");
    expect(card.endpoint).toBe(`${base}/mcp`);
    expect(card.tokenFreeTools).toEqual(["report"]);
    expect(card.tokenFreeTools).toEqual(["report", "start"]);
    // Without a token the endpoint refuses everything but `report`.
    const report = await fetch(card.endpoint, {
@@ -89,5 +89,5 @@
test("the bytes are those of an admin's real tools/list response", async () => {
}, 30_000);
test("the entry builder is the one tools/list uses", () => {
  expect(toolEntries(TOOLS).length).toBe(TOOLS.length + 1);
  expect(toolEntries(TOOLS).length).toBe(TOOLS.length + 2);
});
@@ -10,7 +10,7 @@
import { mkdtemp, rm, writeFile } from "node:fs/promises";
import { tmpdir } from "node:os";
import { join } from "node:path";
import { indexText, toolFiles } from "../scripts/mcp-tools.ts";
import { REPORT_TOOL, toolNames } from "../src/http/mcp.ts";
import { REPORT_TOOL, START_TOOL, toolNames } from "../src/http/mcp.ts";
import { byName } from "../src/http/mcp/shared.ts";
import { TOOLS } from "../src/http/mcp/tools.ts";
import { toolsSection } from "../src/web/llms_tools.ts";
@@ -43,7 +43,7 @@
describe("the gathered tools", () => {
  test("are the files, sorted, one each, and `report` beside them", () => {
    expect(TOOLS.map((t) => t.name)).toEqual(files);
    expect(files).not.toContain("report");
    expect(toolNames()).toEqual([...files, "report"]);
    expect(toolNames()).toEqual([...files, "report", "start"]);
  });
  test("the index is current: run `bun scripts/mcp-tools.ts`", () => {
@@ -66,12 +66,12 @@
describe("the gathered tools", () => {
describe("the live tool list", () => {
  test("every tool's `doc` is its line in /llms.txt's tools section", () => {
    const section = toolsSection([...TOOLS, REPORT_TOOL]);
    for (const t of [...TOOLS, REPORT_TOOL]) {
    const section = toolsSection([...TOOLS, REPORT_TOOL, START_TOOL]);
    for (const t of [...TOOLS, REPORT_TOOL, START_TOOL]) {
      const line = section.find((l) => l.startsWith(`- ${t.name}: `));
      expect([t.name, line?.includes(t.doc ?? t.description) ?? false]).toEqual([t.name, true]);
    }
    expect(section.filter((l) => l.startsWith("- ")).length).toBe(TOOLS.length + 1);
    expect(section.filter((l) => l.startsWith("- ")).length).toBe(TOOLS.length + 2);
  });
  test("a pull adding a tool file and its index line needs no docs file", async () => {
@@ -37,8 +37,9 @@
import { listVia } from "./mcp-list.ts";
/** tools/list's order: the tools by name, then `report`. */
const sortedThenReport = (names: string[]): string[] => [
  ...names.filter((n) => n !== "report").sort((a, b) => a.localeCompare(b)),
  ...names.filter((n) => n !== "report" && n !== "start").sort((a, b) => a.localeCompare(b)),
  "report",
  "start",
];
describe("the forge over MCP", () => {
@@ -384,6 +385,7 @@
describe("the forge over MCP", () => {
      "pins",
      "board_delete",
      "report",
      "start",
    ]));
    const byName = new Map<string, any>(
      listed.body.result.tools.map((t: any) => [t.name, t]),
@@ -309,6 +309,7 @@
const NOT_WALKED: Record<string, string> = {
  "/boards/:slug": "needs a board",
  "/boards/:slug/live": "needs a board; a stream, not a page",
  "/bring/:id/:job": "needs a bring job",
  "/claim/start/:token": "needs the one-time token an anonymous start returned",
  "/fleet/ops/:id": "needs a fleet operation",
  "/go/:code": "needs a short code minted by a share",
  "/home/archived/:op": "needs an archived-home operation",
@@ -19,6 +19,7 @@
import { createApp, type App } from "../src/app.ts";
import { createIssue } from "../src/core/issues.ts";
import { pin } from "../src/core/pins.ts";
import { getRepo } from "../src/core/repos.ts";
import { recordStart } from "../src/core/starts.ts";
import { createUser, type User } from "../src/core/users.ts";
import { buildApiRouter, buildRouter, serve, type Servers } from "../src/http/server.ts";
import { quietLogs } from "./helpers/globals.ts";
@@ -54,6 +55,7 @@
const FIXTURE: Record<string, string> = {
  "/:owner/:name/pulls/:number": "/alice/forge/pulls/2",
  "/:owner/:name/display": "/alice/forge/display",
  "/api/v1/admin/machines/:machine/disks": "/api/v1/admin/machines/rack1/disks",
  "/claim/start/:token": "/claim/start/claim_fixture",
};
function registeredGets(): Set<string> {
@@ -130,6 +132,8 @@
beforeAll(async () => {
  const pull = createIssue(app.db, { repoId: forge.id, authorId: bob.id, title: "A pull", body: "body", kind: "pull" });
  if (!pull.ok) throw new Error(pull.error);
  app.db.run("INSERT INTO pull (issue_id, base_branch, head_branch, base_oid, head_oid) VALUES (?1, 'main', 'topic', '', 'h')", [pull.value.id]);
  // An agent's start the claim page can show (`/claim/start/:token`): bob's, so no extra account joins the walk.
  recordStart(app.db, bob.id, "claim_fixture", "127.0.0.1");
  servers = await serve(app);
  const signin = await fetch(`${servers.url}/signin`, {
    method: "POST",
@@ -145,6 +145,7 @@
test("a site-admin person is offered the whole roster", () => {
    ["teams", "Crew teams", "each team's charter, dial and members"],
    ["agents", "Crew agents", "each agent's model, budget and brief"],
    ["invites", "Invite links", "make a single-use link, see which are open, revoke one"],
    ["claim-start", "Take an agent's work", "claim the repositories an agent started, from its one-time link"],
    ["requests", "Waiting", "strangers who asked for an account: allow or decline"],
    ["bulk", "Bulk actions", "your last bulk actions; u undoes one inside its day"],
    ["subscriptions", "Crew subscriptions", "each account's budget and rest; wake one, set its budget, add or remove one"],
@@ -315,6 +316,7 @@
test("a member person is offered the signed-in roster without the admin entries"
    ["bugs", "Bugs", "open bugs and the bug clock"],
    ["audit", "Who can do what", "each app's doors from its contract.json: yes, own or no"],
    ["archived", "Archived repositories", "put away, not gone: open one or restore it"],
    ["claim-start", "Take an agent's work", "claim the repositories an agent started, from its one-time link"],
    ["bulk", "Bulk actions", "your last bulk actions; u undoes one inside its day"],
    ["bets", "Bets", "back, stop and finish a repository\'s bets"],
    ["origins", "Connected accounts", "the hosts your mirrors come from"],
@@ -92,7 +92,7 @@
test("each return of the public door and of `answered` is floored", () => {
  // `response` is only ever what `answered` gave back.
  for (const m of region.matchAll(/\bresponse\s*=\s*([^\n;]+)/g)) expect(m[1]!.trim()).toMatch(/^await answered\(/);
  // `answered` floors what the work returns, and its failure path floors too.
  expect(region).toContain("const done = await compress(request, response).then(securityFloor)");
  expect(region).toMatch(/const done = await compress\(request, response\)\.then\(\(r\) => securityFloor\(/);
  expect(server).toMatch(/function failure\([^]*?\n}\n/);
  const failure = server.match(/function failure\([^]*?\n}\n/)![0];
  for (const r of failure.matchAll(/\breturn\s+([^\n]+)/g)) expect(r[1]!.trim()).toMatch(/^securityFloor\(/);
@@ -60,6 +60,7 @@
const SHOT = "needs a pin with a picture kept by refs/shots; the seed pins nothi
const CART = "the seed pins no build with a cart (test/build-cart.test.ts covers its headers)";
const UNSEEDED: Record<string, string> = {
  "/:owner/-/teams/:team": ORG,
  "/claim/start/:token": "needs a one-time start claim token, which the seed does not mint (test/start.test.ts covers it)",
  "/talk/:id": TALK,
  "/bring/:id/:job": "needs a bring job of the signed-in person; the seed brings nothing",
  "/fleet/ops/:id": FLEET,
@@ -113,6 +113,7 @@
test("every caller of createUser says where its account comes from", async () =>
    "src/actions/crew.ts": ["agent"],
    "src/actions/first_admin.ts": ["first-admin"],
    "src/actions/spawn.ts": ["spawn", "spawn"],
    "src/actions/start.ts": ["start", "start"],
    "src/actions/users.ts": ["signup", "passkey"],
    "src/chaos/world.ts": ["seed"],
    "src/packs/mirror.ts": ["seed"],
@@ -120,5 +121,6 @@
test("every caller of createUser says where its account comes from", async () =>
    "src/spawn/preview-seed.ts": ["seed", "seed"],
    "src/web/pages/claim.ts": ["claim"],
    "src/web/pages/everyday.ts": ["everyday"],
    "src/web/pages/start_claim.ts": ["claimer"],
  });
});
@@ -0,0 +1,110 @@
/**
 * The start door's guards (#10912): the claim page's account form follows the
 * forge's signup gate, a repository that will not move gives the link back, and
 * concurrent starts cannot overshoot the per-source cap.
 */
import { afterAll, beforeAll, expect, test } from "bun:test";
import { mkdirSync, mkdtempSync, rmSync } from "node:fs";
import { tmpdir } from "node:os";
import { join } from "node:path";
import { claimStart } from "../src/actions/claim.ts";
import { PER_SOURCE_PER_HOUR, startBuilding } from "../src/actions/start.ts";
import { createApp, type App } from "../src/app.ts";
import { startByClaim } from "../src/core/starts.ts";
import { createUser, getUserByName, type User } from "../src/core/users.ts";
import { repoDir } from "../src/git/repos.ts";
import { serve, type Servers } from "../src/http/server.ts";
import { setSignup } from "../src/settings/signup.ts";
import { quietLogs } from "./helpers/globals.ts";
quietLogs();
let root = "";
let app: App;
let servers: Servers;
let alice: User;
beforeAll(async () => {
  root = mkdtempSync(join(tmpdir(), "forge-start-claim-"));
  app = createApp({ dataDir: root, port: 0 });
  const made = await createUser(app.db, { origin: "seed", trusted: true, username: "alice", email: "[email protected]", password: "a-good-passphrase", adminIfFirst: true });
  if (!made.ok) throw new Error(made.error);
  alice = made.value;
  servers = await serve(app);
}, 30_000);
afterAll(() => {
  servers.stop();
  app.close();
  rmSync(root, { recursive: true, force: true });
});
async function start(name: string, source: string) {
  const made = await startBuilding(app, { name }, source, servers.url);
  if (!made.ok) throw new Error(made.error.error);
  return { ...made.value, claimToken: made.value.claim.url.split("/").pop()! };
}
test("signup closed: the claim page offers no account form and the account form makes nothing", async () => {
  const s = await start("closed-door", "203.0.113.1");
  setSignup(app.db, "closed", alice.id);
  try {
    const page = await (await fetch(s.claim.url)).text();
    expect(page).not.toContain("/account");
    expect(page).toContain("/signin?next=");
    const posted = await fetch(`${s.claim.url}/account`, {
      method: "POST",
      redirect: "manual",
      headers: { origin: servers.url },
      body: new URLSearchParams({ username: "intruder", email: "", password: "a-friendly-passphrase" }),
    });
    expect(posted.status).toBe(303);
    expect(posted.headers.get("set-cookie") ?? "").not.toContain("forge_session");
    expect(getUserByName(app.db, "intruder")).toBeUndefined();
    expect(startByClaim(app.db, s.claimToken)!.claimedAt).toBeNull();
  } finally {
    setSignup(app.db, "open", alice.id);
  }
});
test("signup invite-only: the account form is closed too, without an invite", async () => {
  const s = await start("invite-door", "203.0.113.2");
  setSignup(app.db, "invite", alice.id);
  try {
    await fetch(`${s.claim.url}/account`, {
      method: "POST",
      redirect: "manual",
      headers: { origin: servers.url },
      body: new URLSearchParams({ username: "intruder2", email: "", password: "a-friendly-passphrase" }),
    });
    expect(getUserByName(app.db, "intruder2")).toBeUndefined();
  } finally {
    setSignup(app.db, "open", alice.id);
  }
});
test("a repository that will not move gives the link back, and nothing is woken or renamed", async () => {
  const s = await start("stuck", "203.0.113.3");
  const person = await createUser(app.db, { origin: "seed", trusted: true, username: "friend", email: "[email protected]", password: "a-friendly-passphrase" });
  if (!person.ok) throw new Error(person.error);
  // Where the repository would land is already taken.
  mkdirSync(repoDir(app.reposRoot, `${s.user.username}-team`, "stuck"), { recursive: true });
  const refused = await claimStart(app, person.value, s.claimToken);
  expect(refused).toEqual({ ok: false, error: "failed" });
  expect(startByClaim(app.db, s.claimToken)!.claimedAt).toBeNull();
  // Once the place is free the same link works.
  rmSync(repoDir(app.reposRoot, `${s.user.username}-team`, "stuck"), { recursive: true });
  const taken = await claimStart(app, person.value, s.claimToken);
  expect(taken.ok).toBe(true);
  if (taken.ok) expect(taken.value.stayed).toEqual([]);
});
test("concurrent starts from one source take no more than the hourly cap", async () => {
  const results = await Promise.all(
    Array.from({ length: PER_SOURCE_PER_HOUR + 4 }, (_, i) => startBuilding(app, { name: `race-${i}` }, "203.0.113.9", servers.url)),
  );
  expect(results.filter((r) => r.ok).length).toBe(PER_SOURCE_PER_HOUR);
  const refused = results.filter((r) => !r.ok);
  expect(refused.every((r) => !r.ok && r.error.error === "rate_limited")).toBe(true);
  // A refused start leaves no account behind.
  expect(app.db.query("SELECT COUNT(*) AS n FROM user WHERE username LIKE 'race-%'").get()).toEqual({ n: PER_SOURCE_PER_HOUR });
});
@@ -0,0 +1,222 @@
/**
 * An agent with only the forge's URL starts building in one call (#10912):
 * the start call, a push that deploys, the limits, the claim, and the
 * sleep/archive of what nobody claims. Against a scratch forge with its apps
 * runtime, so the app really comes up.
 */
import { afterAll, beforeAll, describe, expect, test } from "bun:test";
import { join } from "node:path";
import { claimStart } from "../src/actions/claim.ts";
import { startBuilding, PER_SOURCE_PER_HOUR } from "../src/actions/start.ts";
import { sweepStarts } from "../src/actions/start_sweep.ts";
import { getRepo, listReposOwnedBy } from "../src/core/repos.ts";
import { listRuns } from "../src/core/runs.ts";
import { getUserByName } from "../src/core/users.ts";
import { heldManifest, isUnclaimed, SMALL_APP } from "../src/core/starts.ts";
import { mintInvite } from "../src/core/invites.ts";
import { setAgentStart } from "../src/settings/agent_start.ts";
import { gitClientEnv } from "./helpers/git-client.ts";
import { deploySettled, fetchAsHost, startAppsForge, stopAppsForge, type AppsForge } from "./helpers/apps-forge.ts";
const gitEnv = gitClientEnv({
  GIT_AUTHOR_NAME: "Muse",
  GIT_AUTHOR_EMAIL: "[email protected]",
  GIT_COMMITTER_NAME: "Muse",
  GIT_COMMITTER_EMAIL: "[email protected]",
});
let forge: AppsForge;
beforeAll(async () => {
  forge = await startAppsForge();
}, 60_000);
afterAll(async () => {
  await forge.runtime.stop();
  await stopAppsForge(forge);
});
const post = (path: string, body: unknown, headers: Record<string, string> = {}, ip = "198.51.100.1") =>
  fetch(`${forge.servers.url}${path}`, {
    method: "POST",
    headers: { "content-type": "application/json", "x-forwarded-for": ip, ...headers },
    body: JSON.stringify(body),
  });
async function git(args: string[], cwd: string): Promise<{ code: number; err: string }> {
  const p = Bun.spawn(["git", ...args], { cwd, env: gitEnv, stdout: "ignore", stderr: "pipe" });
  const err = await new Response(p.stderr).text();
  return { code: await p.exited, err };
}
interface StartAnswer {
  user: { username: string };
  token: string;
  repo: string;
  git: { url: string; push: string };
  app: { url: string | null };
  claim: { url: string };
}
describe("start, push, live, claim", () => {
  let started: StartAnswer;
  test("one call with nothing but the URL makes the account, the repo, the app and a token", async () => {
    const res = await post("/api/v1/start", { name: "Glint Notes", description: "a notes app", agent: "glint" });
    expect(res.status).toBe(201);
    expect(res.headers.get("cache-control")).toBe("no-store");
    started = (await res.json()) as StartAnswer;
    expect(started.token).toStartWith("forge_");
    expect(started.repo).toMatch(/^glint-notes-[0-9a-f]+\/glint-notes$/);
    expect(started.claim.url).toContain("/claim/start/claim_");
    const repo = getRepo(forge.app.db, started.user.username, "glint-notes")!;
    expect(repo.visibility).toBe("public");
    // No crew, no password; held as a guest and unclaimed.
    expect(forge.app.db.query("SELECT COUNT(*) AS n FROM repo_crew WHERE repo_id = ?1").get(repo.id)).toEqual({ n: 0 });
    const user = getUserByName(forge.app.db, started.user.username)!;
    expect(user.kind).toBe("user");
    expect(isUnclaimed(forge.app.db, user.id)).toBe(true);
    expect(forge.app.db.query("SELECT password_hash FROM user WHERE id = ?1").get(user.id)).toEqual({ password_hash: "" });
  });
  test("the token is scoped to that account: it reads its own account and nobody else's private repo", async () => {
    const me = await fetch(`${forge.servers.url}/api/v1/user`, { headers: { authorization: `Bearer ${started.token}` } });
    expect(me.status).toBe(200);
    expect(((await me.json()) as { username: string }).username).toBe(started.user.username);
    const admin = await fetch(`${forge.servers.url}/api/v1/admin/limits`, { headers: { authorization: `Bearer ${started.token}` } });
    expect([403, 404]).toContain(admin.status);
  });
  test("the app is live, and a push to main deploys the new commit", async () => {
    const repo = getRepo(forge.app.db, started.user.username, "glint-notes")!;
    const first = await deploySettled(forge.app, repo.id, (r) => r.env === "production");
    expect(first.state).toBe("ok");
    const slug = forge.runtime.hostFor("glint-notes", "production");
    expect((await fetchAsHost(forge.servers, slug)).status).toBe(200);
    const remote = started.git.url.replace("://", `://${started.user.username}:${started.token}@`);
    const dir = join(forge.work, "clone");
    expect((await git(["clone", "-q", remote, dir], forge.work)).code).toBe(0);
    await Bun.write(join(dir, "NOTES.md"), "pushed by an agent\n");
    await git(["-C", dir, "add", "."], forge.work);
    await git(["-C", dir, "commit", "-q", "-m", "an agent's change"], forge.work);
    const pushed = await git(["-C", dir, "push", "-q", "origin", "HEAD:main"], forge.work);
    expect(pushed.err).toBe("");
    expect(pushed.code).toBe(0);
    const head = (await Bun.spawn(["git", "-C", dir, "rev-parse", "HEAD"], { env: gitEnv, stdout: "pipe" }).stdout.text()).trim();
    const deadline = Date.now() + 60_000;
    let second = listRuns(forge.app.db, repo.id, { kind: "deploy", limit: 20 }).find((r) => r.commitOid === head && r.env === "production");
    while (second === undefined && Date.now() < deadline) {
      await Bun.sleep(25);
      second = listRuns(forge.app.db, repo.id, { kind: "deploy", limit: 20 }).find((r) => r.commitOid === head && r.env === "production");
    }
    expect(second).toBeDefined();
  }, 120_000);
  test("a person opens the claim link, makes an account, and the repo and the agent are theirs", async () => {
    const page = await fetch(started.claim.url);
    expect(page.status).toBe(200);
    expect(page.headers.get("cache-control")).toBe("no-store");
    expect(await page.text()).toContain("glint");
    const made = await fetch(`${started.claim.url}/account`, {
      method: "POST",
      redirect: "manual",
      body: new URLSearchParams({ username: "friend", email: "", password: "a-friendly-passphrase" }),
    });
    expect(made.status).toBe(303);
    expect(made.headers.get("set-cookie")).toContain("HttpOnly");
    const org = `${started.user.username}-team`;
    expect(made.headers.get("location")).toBe(`/${org}`);
    const moved = getRepo(forge.app.db, org, "glint-notes")!;
    expect(moved).toBeDefined();
    expect(isUnclaimed(forge.app.db, getUserByName(forge.app.db, started.user.username)!.id)).toBe(false);
    // The agent is a member with write: its token still pushes.
    const remote = started.git.url.replace(`/${started.user.username}/`, `/${org}/`).replace("://", `://${started.user.username}:${started.token}@`);
    const dir = join(forge.work, "clone2");
    expect((await git(["clone", "-q", remote, dir], forge.work)).code).toBe(0);
    await Bun.write(join(dir, "MORE.md"), "still writing\n");
    await git(["-C", dir, "add", "."], forge.work);
    await git(["-C", dir, "commit", "-q", "-m", "again"], forge.work);
    expect((await git(["-C", dir, "push", "-q", "origin", "HEAD:main"], forge.work)).code).toBe(0);
    // The link is burnt.
    const again = await claimStart(forge.app, getUserByName(forge.app.db, "friend"), started.claim.url.split("/").pop()!);
    expect(again).toEqual({ ok: false, error: "claimed" });
  }, 120_000);
});
describe("the defenses", () => {
  test("a bad body is refused at the boundary, and a page on another site cannot call it", async () => {
    expect((await post("/api/v1/start", {}, {}, "198.51.100.20")).status).toBe(422);
    expect((await post("/api/v1/start", { name: "x".repeat(41) }, {}, "198.51.100.20")).status).toBe(422);
    expect((await post("/api/v1/start", { name: "ok", agent: "bad name!" }, {}, "198.51.100.20")).status).toBe(422);
    expect((await post("/api/v1/start", { name: "ok", description: 5 }, {}, "198.51.100.20")).status).toBe(422);
    const cross = await post("/api/v1/start", { name: "ok" }, { origin: "https://evil.example" }, "198.51.100.20");
    expect(cross.status).toBe(403);
  });
  test("a few starts an hour from one source, then a wait; another source is not held", async () => {
    for (let i = 0; i < PER_SOURCE_PER_HOUR; i++)
      expect((await post("/api/v1/start", { name: `lim-${i}` }, {}, "198.51.100.30")).status).toBe(201);
    const held = await post("/api/v1/start", { name: "lim-x" }, {}, "198.51.100.30");
    expect(held.status).toBe(429);
    expect(held.headers.get("retry-after")).toBe("3600");
    expect((await post("/api/v1/start", { name: "lim-y" }, {}, "198.51.100.31")).status).toBe(201);
  }, 60_000);
  test("the setting: off refuses, a code asks for an open invite and spends it", async () => {
    const admin = forge.alice;
    setAgentStart(forge.app.db, "off", admin.id);
    const off = await post("/api/v1/start", { name: "nope" }, {}, "198.51.100.40");
    expect(off.status).toBe(403);
    expect(((await off.json()) as { error: string }).error).toBe("off");
    setAgentStart(forge.app.db, "code", admin.id);
    expect((await post("/api/v1/start", { name: "nope" }, {}, "198.51.100.40")).status).toBe(403);
    expect((await post("/api/v1/start", { name: "nope", code: "wrong" }, {}, "198.51.100.40")).status).toBe(403);
    const invite = mintInvite(forge.app.db, admin.id, 7);
    const ok = await post("/api/v1/start", { name: "coded", code: invite.token }, {}, "198.51.100.40");
    expect(ok.status).toBe(201);
    expect((await post("/api/v1/start", { name: "coded2", code: invite.token }, {}, "198.51.100.41")).status).toBe(403);
    setAgentStart(forge.app.db, "open", admin.id);
  }, 60_000);
  test("the MCP `start` tool answers with no token, as the API does", async () => {
    const res = await fetch(`${forge.servers.url}/mcp`, {
      method: "POST",
      headers: { "content-type": "application/json", accept: "application/json", "x-forwarded-for": "198.51.100.50" },
      body: JSON.stringify({ jsonrpc: "2.0", id: 1, method: "tools/call", params: { name: "start", arguments: { name: "via-mcp" } } }),
    });
    const body = (await res.json()) as any;
    const out = JSON.parse(body.result.content[0].text) as StartAnswer;
    expect(out.token).toStartWith("forge_");
  });
  test("an unclaimed account's app runs small with no host but the registries; a claimed one is not touched", async () => {
    const made = await startBuilding(forge.app, { name: "held" }, "198.51.100.60", "http://x");
    if (!made.ok) throw new Error(made.error.error);
    const owner = getUserByName(forge.app.db, made.value.user.username)!;
    const declared: { egress: string[]; limits: { memoryMiB: number; cpus: number; diskMiB?: number } } = { egress: ["api.example.com"], limits: { memoryMiB: 4096, cpus: 8 } };
    const held = heldManifest(forge.app.db, owner.id, declared);
    expect(held.egress).toEqual([]);
    expect(held.limits).toEqual({ memoryMiB: SMALL_APP.memoryMiB, cpus: SMALL_APP.cpus, diskMiB: SMALL_APP.diskMiB });
    expect(heldManifest(forge.app.db, forge.alice.id, declared)).toBe(declared);
  });
  test("asleep after 7 days (token dead), archived after 30 (not deleted); a claim wakes it", async () => {
    const made = await startBuilding(forge.app, { name: "idle" }, "198.51.100.70", "http://x");
    if (!made.ok) throw new Error(made.error.error);
    const owner = getUserByName(forge.app.db, made.value.user.username)!;
    const day = 86_400_000;
    expect(sweepStarts(forge.app, new Date(Date.now() + 6 * day)).slept).toBe(0);
    const slept = sweepStarts(forge.app, new Date(Date.now() + 8 * day));
    expect(slept.slept).toBeGreaterThan(0);
    const gone = await fetch(`${forge.servers.url}/api/v1/user`, { headers: { authorization: `Bearer ${made.value.token}` } });
    expect(gone.status).toBe(401);
    sweepStarts(forge.app, new Date(Date.now() + 31 * day));
    const repos = listReposOwnedBy(forge.app.db, owner.id);
    expect(repos.length).toBe(1);
    expect(repos[0]!.archivedAt).not.toBeNull();
    const friend = getUserByName(forge.app.db, "friend")!;
    const taken = await claimStart(forge.app, friend, made.value.claim.url.split("/").pop()!);
    expect(taken.ok).toBe(true);
    const moved = getRepo(forge.app.db, `${owner.username}-team`, "idle")!;
    expect(moved.archivedAt).toBeNull();
  });
});
@@ -0,0 +1,64 @@
/** Taking an agent's work in the terminal (#10912): the claim page's gate and effect. */
import { afterAll, beforeAll, expect, test } from "bun:test";
import { mkdtemp, rm } from "node:fs/promises";
import { tmpdir } from "node:os";
import { join } from "node:path";
import { startBuilding } from "../src/actions/start.ts";
import { createApp, type App as Forge } from "../src/app.ts";
import { startByClaim } from "../src/core/starts.ts";
import { createUser, getUserByName } from "../src/core/users.ts";
import { createForgeApp } from "../src/tui/forge.ts";
import { tokenOfLink } from "../src/tui/screens/claim_start.ts";
import { entry } from "../src/tui/screens/claim_start.ts";
import { Session } from "../src/tui/session.ts";
import { headlessTerminal } from "../src/tui/term/terminal.ts";
import { quietLogs } from "./helpers/globals.ts";
import { settleApp } from "./helpers/tui.ts";
quietLogs();
let dir = "";
let forge: Forge;
beforeAll(async () => {
  dir = await mkdtemp(join(tmpdir(), "forge-tui-claim-"));
  forge = createApp({ dataDir: dir, port: 0 });
  const made = await createUser(forge.db, { origin: "seed", trusted: true, username: "bob", email: "[email protected]", password: "a-good-passphrase" });
  if (!made.ok) throw new Error(made.error);
});
afterAll(async () => {
  forge.close();
  await rm(dir, { recursive: true, force: true });
});
test("the token is the last part of a pasted link", () => {
  expect(tokenOfLink(" https://f.test/claim/start/claim_abc?x=1 ")).toBe("claim_abc");
  expect(tokenOfLink("claim_abc")).toBe("claim_abc");
});
test("a person pastes the link, confirms, and the repository is theirs; an agent is not offered it", async () => {
  const made = await startBuilding(forge, { name: "term" }, "203.0.113.5", "http://f.test");
  if (!made.ok) throw new Error(made.error.error);
  const link = made.value.claim.url;
  const bob = getUserByName(forge.db, "bob")!;
  const { app } = createForgeApp(forge, { sshUsername: "t", remoteAddress: "127.0.0.1", user: bob }, { terminal: headlessTerminal(140, 32), exitHooks: false });
  app.start();
  const k = (key: string) => app.dispatch({ type: "key", key, ctrl: false, alt: false, shift: false });
  app.dispatch({ type: "key", key: "k", ctrl: true, alt: false, shift: false });
  for (const ch of "Take an agent") k(ch);
  k("enter");
  await settleApp(app);
  k("t");
  for (const ch of link.split("/").pop()!) k(ch);
  k("enter");
  await settleApp(app);
  expect(app.screen.toText()).toContain("term");
  k("enter");
  await settleApp(app);
  await Bun.sleep(200);
  await settleApp(app);
  expect(app.screen.toText()).toContain("Taken");
  expect(startByClaim(forge.db, link.split("/").pop()!)!.claimedBy).toBe(bob.id);
  app.stop();
  const agent = { ...bob, kind: "agent" } as typeof bob;
  expect(entry.offered(new Session(forge, { sshUsername: "t", remoteAddress: "127.0.0.1", user: agent }))).toBe(false);
});
@@ -112,3 +112,23 @@
test("a non-admin and an admin agent are never offered s", async () => {
  const own = invitesScreen(admin, { push() {}, invalidate() {} } as never);
  expect(JSON.stringify(own.keys)).toContain('"s"');
});
test("an admin sets who may start an agent with a, after a confirm; others are not offered it", async () => {
  const { getAgentStart } = await import("../src/settings/agent_start.ts");
  const h = boot("alice");
  await h.open();
  expect(getAgentStart(forge.db)).toBe("open");
  await h.press("a", "j", "j", "enter");
  expect(h.text()).toContain("from open to off");
  await h.press("esc");
  expect(getAgentStart(forge.db)).toBe("open");
  await h.press("a", "j", "j", "enter", "enter");
  expect(getAgentStart(forge.db)).toBe("off");
  h.stop();
  const bob = boot("bob");
  await bob.open();
  await bob.press("a", "j", "enter", "enter");
  expect(getAgentStart(forge.db)).toBe("off");
  bob.stop();
  (await import("../src/settings/agent_start.ts")).setAgentStart(forge.db, "open", getUserByName(forge.db, "alice")!.id);
});
		@@ -233,6 +233,7 @@ bytes in `tools/list`. After changing a tool run `bun scripts/mcp-table.ts`;
233	233	\| `whoami_can` \| `role`, `passkeys` \| What you can do: your role and its roles-table row, yes or no each \| 231 \|
234	234	\| `write_file` \| — \| Commit one file to a branch \| 302 \|
235	235	\| `report` \| — \| Report a problem in a public repository, no account needed \| 468 \|
	236	\| `start` \| — \| Start building with no account: an account, a repo, a live app and a token in one call \| 358 \|
236	237	<!-- mcp-tools:end -->
237	238
238	239	The complete list, with schemas, is MCP `tools/list` called with a token.
		@@ -0,0 +1,25 @@
	1	# Start: an agent builds with only the forge's URL
		sentinelcrew 1d ago Both doors: no `src/tui/` screen for claiming or for the `agent_start` setting. The terminal must offer what the page does, gated the same way, with its entry where AGENTS.md says. This doc then covers the terminal path too.
	2
	3	This page is for agents and the people who run them. No account, token or crew is needed to begin.
	4
	5	## Start
	6
	7	```
	8	curl -sX POST https://forge.open-platform.sh/api/v1/start -d '{"name":"my-app"}'
	9	```
	10
	11	`name` is required; `description` and `agent` are optional. The answer holds `user`, `token` (shown once), `repo`, `git`, `app` and `claim`. The MCP `start` tool does the same and needs no token.
	12
	13	## Build
	14
	15	Clone `git.url` (it carries the token) and `git push` to main. `app.url` is live after the deploy. Issues and pulls work as on any repo. An unclaimed account has no crew, spends no credits, runs a small app and reaches no host but the package registries.
	16
	17	## Claim
	18
	19	Give `claim.url` to a person. They open it and sign in (or, where the forge's sign-up is open, make an account there), and the agent account and its repos become theirs, with the agent as a member. The link works once; if no repository can be moved it is given back, and one that cannot move stays with the agent and is named. Where sign-up is closed or by invite, the claim page makes no account: the person signs in.
	20
	21	In the terminal, Take an agent's work in the palette (any person) asks for the link, names the repositories and moves them after a confirm: the same claim, the same gate.
	22
	23	## Limits
	24
	25	Per source: 3 starts an hour and 10 a day. For the forge: 200 a day. Counts and the insert are one transaction, so concurrent calls cannot overshoot. One source can use at most 5% of the day's share; against abuse from many addresses an admin sets Agents can start here to invite code or off. Unclaimed accounts sleep after 7 days and are archived (never deleted) after 30; claiming wakes them. A site admin sets Agents can start here (open, invite code, off) in `/admin/limits`, or with `a` on the Invite links screen in the terminal (admins who are people).
		@@ -0,0 +1,90 @@
	1	/**
	2	* Taking an agent's account (#10912): the person who opens the one-time
	3	* claim link the start call returned, signed in, takes it. The agent's
	4	* repositories move to a new organisation the person owns, and the agent
	5	* stays in it as a member with write; the account wakes if it slept and
	6	* its archived repositories are woken. The link is burnt in the one
	7	* statement that checks it, so of two people racing on it one wins. A
	8	* repository that will not move stays with the agent and is reported; when
	9	* none moves the link is given back.
	10	*/
	11	import type { App } from "../app.ts";
	12	import { setSuspended } from "../core/accounts.ts";
	13	import { addTeamMember, createOrg, createTeam } from "../core/orgs.ts";
	14	import { listReposOwnedBy, moveArchived, type Repo } from "../core/repos.ts";
	15	import { markClaimed, startByClaim } from "../core/starts.ts";
	16	import { transferRepo } from "../core/transfer.ts";
	17	import { getUserById, type User } from "../core/users.ts";
	18	import { err, ok, type Result } from "../kernel/result.ts";
	19
	20	export type ClaimError = "not_found" \| "claimed" \| "not_a_person" \| "failed";
	21
	22	export const CLAIM_WORDS: Readonly<Record<ClaimError, string>> = {
	23	not_found: "This claim link is not one this forge made.",
	24	claimed: "This link was already used: someone has taken the account.",
	25	not_a_person: "Only a person's account can take this.",
	26	failed: "The account could not be moved; nothing was kept. Try the link again.",
	27	};
	28
	29	export interface ClaimView {
	30	readonly agent: string;
	31	readonly repos: readonly string[];
	32	readonly claimed: boolean;
	33	}
	34
	35	/** What a link holds, for the page that offers it: nothing secret. */
	36	export function viewClaim(app: App, claimToken: string): ClaimView \| undefined {
	37	const row = startByClaim(app.db, claimToken);
	38	const agent = row === undefined ? undefined : getUserById(app.db, row.userId);
	39	if (row === undefined \|\| agent === undefined) return undefined;
	40	return {
	41	agent: agent.username,
	42	repos: listReposOwnedBy(app.db, agent.id).map((r) => `${r.ownerName}/${r.name}`),
	43	claimed: row.claimedAt !== null,
	44	};
	45	}
	46
	47	export async function claimStart(
	48	app: App,
	49	claimer: User \| undefined,
	50	claimToken: string,
	51	now: Date = new Date(),
	52	): Promise<Result<{ org: string; repos: string[]; stayed: string[] }, ClaimError>> {
	53	const row = startByClaim(app.db, claimToken);
	54	const agent = row === undefined ? undefined : getUserById(app.db, row.userId);
	55	if (row === undefined \|\| agent === undefined) return err("not_found");
	56	if (row.claimedAt !== null) return err("claimed");
	57	if (claimer === undefined \|\| claimer.kind !== "user" \|\| claimer.id === agent.id) return err("not_a_person");
	58	if (!markClaimed(app.db, agent.id, claimer.id, now)) return err("claimed");
	59
	60	let org = createOrg(app.db, `${agent.username}-team`, claimer.id);
	61	if (!org.ok && org.error === "name_taken")
	62	org = createOrg(app.db, `${agent.username}-team-${Date.now().toString(36)}`, claimer.id);
	63	const team = org.ok ? createTeam(app.db, org.value.id, "agents", "write") : undefined;
	64	if (!org.ok \|\| team === undefined \|\| !team.ok \|\| !addTeamMember(app.db, team.value, agent.id)) {
	65	// Nothing moved yet: give the link back.
	66	app.db.query("UPDATE start_account SET claimed_at = NULL, claimed_by = NULL WHERE user_id = ?1").run(agent.id);
	67	return err("failed");
	68	}
	69	const moved: Repo[] = [];
		sentinelcrew 1d ago outdated A failed `transferRepo` is swallowed: the claim stays burnt and the repo stays with the agent. `moveArchived(..., false)` runs on the old repo regardless. The person is told "Taken" with fewer repos, and the link is spent. Fix: on any failed transfer, give the link back (as the org failure does) or report the repos that did not move. Wake only the repos that moved. Add a test.
	70	const stayed: string[] = [];
	71	for (const repo of listReposOwnedBy(app.db, agent.id)) {
	72	const done = await transferRepo(app.db, app.reposRoot, repo, org.value, claimer.id);
	73	if (done.ok) {
	74	moved.push(done.value);
	75	moveArchived(app.db, done.value.id, false);
	76	} else stayed.push(`${repo.ownerName}/${repo.name}`);
	77	}
	78	if (moved.length === 0 && stayed.length > 0) {
	79	// Nothing moved: give the link back.
	80	app.db.query("UPDATE start_account SET claimed_at = NULL, claimed_by = NULL WHERE user_id = ?1").run(agent.id);
	81	return err("failed");
	82	}
	83	setSuspended(app.db, agent.id, null);
	84	app.bus.append({
	85	kind: "start.claimed",
	86	actorId: claimer.id,
	87	payload: { agent: agent.username, org: org.value.username, repos: moved.length },
	88	});
	89	return ok({ org: org.value.username, repos: moved.map((r) => `${r.ownerName}/${r.name}`), stayed });
	90	}
		@@ -16,6 +16,7 @@ import { audienceFor } from "../core/audience.ts";
16	16	import { lacks } from "../core/roles.ts";
17	17	import { activeEdgeToken } from "../http/edge.ts";
18	18	import { sshTellCommand } from "../ssh/command.ts";
	19	import { getAgentStart } from "../settings/agent_start.ts";
19	20	import { mcpPointers, TOKEN_FREE_TOOLS } from "../core/mcp_card.ts";
20	21	import type { App } from "../app.ts";
21	22	import { appsRuntime } from "../apps/runtime.ts";
		@@ -331,6 +332,16 @@ function forgeActions(
331	332	http: "GET /api/v1/changelog",
332	333	mcp: "releases",
333	334	},
	335	...(getAgentStart(app.db) === "off"
	336	? []
	337	: [
	338	{
	339	do: "start building with no account",
	340	http: "POST /api/v1/start",
	341	mcp: "start",
	342	...tokenFree("start"),
	343	},
	344	]),
334	345	{
335	346	do: "read the HTTP contract",
336	347	http: "GET /contract/openapi.json",
		@@ -12,6 +12,7 @@ import {
12	12	type SignupChange,
13	13	type SignupMode,
14	14	} from "../settings/signup.ts";
	15	import { getAgentStart, parseAgentStart, setAgentStart, type AgentStartMode } from "../settings/agent_start.ts";
15	16	import { forgeSource, parseForgeSource, setForgeSource, storedForgeSource } from "../settings/forge_source.ts";
16	17	import type { User } from "../core/users.ts";
17	18	import { err, ok, type Result } from "../kernel/result.ts";
		@@ -69,3 +70,22 @@ export function changeForgeSource(
69	70	setForgeSource(app.db, name.value, who.value.id);
70	71	return ok(name.value);
71	72	}
	73
	74	/** The agent-start setting (`settings/agent_start.ts`), for a forge admin who is a person. */
	75	export function readAgentStart(app: App, actor: User \| undefined): Result<AgentStartMode, "not_found"> {
	76	const who = admin(actor);
	77	return who.ok ? ok(getAgentStart(app.db)) : who;
	78	}
	79
	80	export function changeAgentStart(
	81	app: App,
	82	actor: User \| undefined,
	83	raw: unknown,
	84	): Result<AgentStartMode, "not_found" \| "invalid_agent_start"> {
	85	const who = admin(actor);
	86	if (!who.ok) return who;
	87	const mode = parseAgentStart(raw);
	88	if (!mode.ok) return mode;
	89	setAgentStart(app.db, mode.value, who.value.id);
	90	return ok(mode.value);
	91	}
		@@ -0,0 +1,201 @@
	1	/**
	2	* The start call (#10912): an agent holding only the forge's URL gets an
	3	* account, a public repository from the app template and its app, and a
	4	* token for that account, in one call. No person and no crew are in it.
	5	*
	6	* The door is open to strangers, so its limits are mechanical:
	7	*
	8	* - The setting. `agent_start` (`settings/agent_start.ts`): open, a
	9	* code (an open invite link's token, spent with the account), or off.
	10	* - Capped. A few starts per source per hour, ten per source per day, and
	11	* a few hundred a day for the whole forge, counted from the rows the starts
	12	* left, so a restart forgets nothing. The counts and the insert are one
	13	* transaction, so concurrent calls cannot overshoot. One source cannot take
	14	* more than `PER_SOURCE_PER_DAY / PER_DAY` of the day; a forge that sees
	15	* abuse from many addresses sets `agent_start` to a code or off.
	16	* - Held small. The account stays a guest (no crew, no credits), its
	17	* app runs small with no host but the package registries, and it sleeps
	18	* after a week unclaimed and is archived, never deleted, after a month
	19	* (`core/starts.ts`, `sweepStarts`).
	20	* - Shown. The app is public under the agent's name.
	21	*
	22	* The token is returned once; the claim link is returned once and kept as a
	23	* hash (`actions/claim.ts` is what opens it).
	24	*/
	25	import type { App } from "../app.ts";
	26	import { appsRuntime } from "../apps/runtime.ts";
	27	import { createToken } from "../core/tokens.ts";
	28	import { createUser, discardFreshUser } from "../core/users.ts";
	29	import { inviteOpen, redeemInvite } from "../core/invites.ts";
	30	import { ARCHIVE_DAYS, SLEEP_DAYS, recordStart, startsSince } from "../core/starts.ts";
	31	import { secret } from "../kernel/id.ts";
	32	import { err, ok, type Result } from "../kernel/result.ts";
	33	import { getAgentStart } from "../settings/agent_start.ts";
	34	import { noEmail } from "./users.ts";
		sentinelcrew 1d ago outdated MEDIUM (denial of service): PER_DAY=200 is a global cap that one source can exhaust at 3 per hour per address, or many addresses. That closes the door for every honest agent, and each start also deploys a public app that runs stranger-supplied code. Also, the check-then-insert for the caps is not atomic, so concurrent calls overshoot them. Fix: count and insert in one transaction, and give the daily cap a bounded share per source or an admin setting. Document the abuse bound in the pull.
	35	import { newApp } from "./apps.ts";
	36
	37	export const PER_SOURCE_PER_HOUR = 3;
	38	export const PER_SOURCE_PER_DAY = 10;
	39	export const PER_DAY = 200;
	40	export const NAME_MAX = 40;
	41	export const DESCRIPTION_MAX = 2000;
	42	export const AGENT_MAX = 64;
	43	const HOUR_MS = 3_600_000;
	44	const DAY_MS = 86_400_000;
	45
	46	export interface StartInput {
	47	readonly name?: unknown;
	48	readonly description?: unknown;
	49	readonly agent?: unknown;
	50	/** The token of an open invite link, when the forge asks for one. */
	51	readonly code?: unknown;
	52	}
	53
	54	export type StartError =
	55	\| "off"
	56	\| "code_needed"
	57	\| "invalid_name"
	58	\| "invalid_description"
	59	\| "invalid_agent"
	60	\| "rate_limited"
	61	\| "full"
	62	\| "failed";
	63
	64	export type StartRefusal = { readonly error: StartError; readonly retryAfter?: number };
	65
	66	/** What each refusal says; the shape of the call is in `START_HINT`. */
	67	export const START_WORDS: Readonly<Record<StartError, string>> = {
	68	off: "Agents cannot start here: the owner turned the start call off. A person can sign in or ask for an invitation.",
	69	code_needed: "This forge asks for an invite code: send it as `code`.",
	70	invalid_name: `name is 1-${NAME_MAX} characters with a letter or digit in it`,
	71	invalid_description: `description is plain text of at most ${DESCRIPTION_MAX} characters`,
	72	invalid_agent: `agent is a name of at most ${AGENT_MAX} letters, digits, . _ -`,
	73	rate_limited: "Too many starts from here; wait and send again.",
	74	full: "This forge has started its share of agents for today; try again tomorrow.",
	75	failed: "The start could not be finished; nothing was kept. Try again.",
	76	};
	77
	78	export const START_HINT =
	79	`send JSON {name, description?, agent?}: name 1-${NAME_MAX} characters, description at most ` +
	80	`${DESCRIPTION_MAX}, agent your name (letters, digits, . _ -)`;
	81
	82	export interface Started {
	83	readonly user: { readonly username: string };
	84	/** Scoped to that account (read and write); shown once. */
	85	readonly token: string;
	86	readonly repo: string;
	87	readonly git: { readonly url: string; readonly push: string };
	88	readonly app: { readonly url: string \| null };
	89	/** One-time link a person opens to take the account and its repositories. */
	90	readonly claim: { readonly url: string; readonly sleepsAfterDays: number; readonly archivedAfterDays: number };
	91	}
	92
	93	/** The name as a repository and account name: lowercase letters, digits, dashes. */
	94	export function nameSlug(raw: string): string {
	95	return raw
	96	.toLowerCase()
	97	.replace(/[^a-z0-9]+/g, "-")
	98	.replace(/^-+\|-+$/g, "")
	99	.slice(0, 28)
	100	.replace(/-+$/g, "");
	101	}
	102
	103	const hex = (n: number): string =>
	104	Array.from(crypto.getRandomValues(new Uint8Array(n)), (b) => b.toString(16).padStart(2, "0")).join("");
	105
	106	export async function startBuilding(
	107	app: App,
	108	input: StartInput,
	109	source: string,
	110	origin: string,
	111	now: Date = new Date(),
	112	): Promise<Result<Started, StartRefusal>> {
	113	const refuse = (error: StartError, retryAfter?: number): Result<never, StartRefusal> =>
	114	err(retryAfter === undefined ? { error } : { error, retryAfter });
	115	const mode = getAgentStart(app.db);
	116	if (mode === "off") return refuse("off");
	117	const code = typeof input.code === "string" ? input.code : "";
	118	if (mode === "code" && !inviteOpen(app.db, code)) return refuse("code_needed");
	119
	120	const given = typeof input.name === "string" ? input.name.trim() : "";
	121	const base = nameSlug(given);
	122	if (given === "" \|\| given.length > NAME_MAX \|\| base === "") return refuse("invalid_name");
	123	const description = input.description === undefined ? "" : input.description;
	124	if (typeof description !== "string" \|\| description.length > DESCRIPTION_MAX \|\| /[\0]/.test(description))
	125	return refuse("invalid_description");
	126	const agent = input.agent === undefined ? "" : input.agent;
	127	if (typeof agent !== "string" \|\| agent.length > AGENT_MAX \|\| !/^[A-Za-z0-9._-]*$/.test(agent))
	128	return refuse("invalid_agent");
	129
	130	const capped = (): StartRefusal \| undefined => {
	131	if (startsSince(app.db, new Date(now.getTime() - HOUR_MS), source) >= PER_SOURCE_PER_HOUR)
	132	return { error: "rate_limited", retryAfter: 3600 };
	133	if (startsSince(app.db, new Date(now.getTime() - DAY_MS), source) >= PER_SOURCE_PER_DAY)
	134	return { error: "rate_limited", retryAfter: 3600 };
	135	if (startsSince(app.db, new Date(now.getTime() - DAY_MS)) >= PER_DAY) return { error: "full" };
	136	return undefined;
	137	};
	138	// Cheap early refusal; the binding count is the one inside the transaction below.
	139	const early = capped();
	140	if (early !== undefined) return err(early);
	141
	142	// The account: a person-shaped one with no password, which only its token signs in.
	143	let username = `${base}-${hex(2)}`;
	144	let made = await createUser(app.db, {
	145	origin: "start",
	146	username,
	147	email: noEmail(username),
	148	displayName: agent === "" ? base : agent,
	149	trusted: true,
	150	});
	151	if (!made.ok && made.error === "username_taken") {
	152	username = `${base}-${hex(3)}`;
	153	made = await createUser(app.db, {
	154	origin: "start",
	155	username,
	156	email: noEmail(username),
	157	displayName: agent === "" ? base : agent,
	158	trusted: true,
	159	});
	160	}
	161	if (!made.ok) return refuse("failed");
	162	const user = made.value;
	163	const undo = (): void => discardFreshUser(app.db, user.id);
	164
	165	const claimToken = `claim_${secret()}`;
	166	let refusal: StartRefusal \| undefined;
	167	try {
	168	app.db.transaction(() => {
	169	refusal = capped();
	170	if (refusal !== undefined) throw new Error("capped");
	171	if (mode === "code" && !redeemInvite(app.db, code, user.id)) throw new Error("code spent");
	172	recordStart(app.db, user.id, claimToken, source, now);
	173	})();
	174	} catch {
	175	undo();
	176	if (refusal !== undefined) return err(refusal);
	177	return refuse(mode === "code" ? "code_needed" : "failed");
	178	}
	179
	180	// The repository and its app; a taken app name gets a suffix once.
	181	let made2 = await newApp(app, user, { name: base, description, visibility: "public" });
	182	if (!made2.ok && made2.error === "slug_taken")
	183	made2 = await newApp(app, user, { name: `${base}-${hex(2)}`, description, visibility: "public" });
	184	if (!made2.ok) {
	185	undo();
	186	return refuse("failed");
	187	}
	188	const { repo, app: record } = made2.value;
	189	const token = createToken(app.db, user.id, "start", "rw");
	190	app.bus.append({ kind: "start.made", repoId: repo.id, actorId: user.id, payload: {} });
	191	const url = `${origin}/${user.username}/${repo.name}.git`;
	192	return ok({
	193	user: { username: user.username },
	194	token: token.token,
	195	repo: `${user.username}/${repo.name}`,
	196	git: { url, push: `git push ${url.replace("://", `://${user.username}:${token.token}@`)} HEAD:main` },
	197	app: { url: appsRuntime(app)?.urlFor(record, "production") ?? null },
	198	claim: { url: `${origin}/claim/start/${claimToken}`, sleepsAfterDays: SLEEP_DAYS, archivedAfterDays: ARCHIVE_DAYS },
	199	});
	200	}
	201
		@@ -0,0 +1,29 @@
	1	/**
	2	* The life of an unclaimed account (#10912): asleep after `SLEEP_DAYS`
	3	* (suspended, so its token and its app stop answering), archived after
	4	* `ARCHIVE_DAYS` (its repositories archived), never deleted. A claim wakes
	5	* all of it (`actions/claim.ts`). Run from the daily maintenance tick.
	6	*/
	7	import type { App } from "../app.ts";
	8	import { setSuspended } from "../core/accounts.ts";
	9	import { listReposOwnedBy, moveArchived } from "../core/repos.ts";
	10	import { dueToArchive, dueToSleep, markArchived, markSlept } from "../core/starts.ts";
	11
	12	export function sweepStarts(app: App, now: Date = new Date()): { slept: number; archived: number } {
	13	const stamp = now.toISOString();
	14	let slept = 0;
	15	let archived = 0;
	16	for (const userId of dueToSleep(app.db, now)) {
	17	setSuspended(app.db, userId, stamp);
	18	app.db.query("DELETE FROM token WHERE user_id = ?1").run(userId);
	19	markSlept(app.db, userId, now);
	20	slept++;
	21	}
	22	for (const userId of dueToArchive(app.db, now)) {
	23	for (const repo of listReposOwnedBy(app.db, userId)) moveArchived(app.db, repo.id, true, stamp);
	24	markArchived(app.db, userId, now);
	25	archived++;
	26	}
	27	if (slept + archived > 0) app.bus.append({ kind: "start.swept", payload: { slept, archived } });
	28	return { slept, archived };
	29	}
		@@ -104,6 +104,7 @@ import {
104	104	type EnvName,
105	105	} from "./data.ts";
106	106	import { parseManifest, type AppManifest } from "./manifest.ts";
	107	import { heldManifest } from "../core/starts.ts";
107	108	import { identityKey } from "./proxy.ts";
108	109	import { noteReached } from "./egress_report.ts";
109	110	import { cellHooks } from "./egress_refused.ts";
		@@ -1509,7 +1510,9 @@ export class AppsRuntime {
1509	1510	readFileAt(bare, run.commitOid, "forge.json"),
1510	1511	readFileAt(bare, run.commitOid, "package.json"),
1511	1512	]);
1512		const manifest = parseManifest(forgeJson, packageJson);
	1513	const parsed = parseManifest(forgeJson, packageJson);
	1514	// An agent's unclaimed account runs small, with no host but the registries (#10912).
	1515	const manifest = parsed.ok ? { ...parsed, value: heldManifest(this.app.db, repo.ownerId, parsed.value) } : parsed;
1513	1516	clock.lap("manifest");
1514	1517	if (!manifest.ok) {
1515	1518	return {
		@@ -2026,6 +2029,7 @@ export class AppsRuntime {
2026	2029	};
2027	2030	const manifest = parseManifest(read("forge.json"), read("package.json"));
2028	2031	if (!manifest.ok) return false;
	2032	const owner = getRepoById(this.app.db, record.repoId)?.ownerId;
2029	2033	const state = this.envFor(record, env);
2030	2034	if (state.live !== undefined \|\| state.deploying !== undefined) return true;
2031	2035	// The deploy that built this checkout, in an earlier life: its log is
		@@ -2039,7 +2043,7 @@ export class AppsRuntime {
2039	2043	state.asleep = {
2040	2044	commitOid,
2041	2045	dir,
2042		manifest: manifest.value,
	2046	manifest: owner === undefined ? manifest.value : heldManifest(this.app.db, owner, manifest.value),
2043	2047	runId: built?.id ?? "",
2044	2048	since: new Date().toISOString(),
2045	2049	};
		@@ -349,6 +349,7 @@ export { route as postApiV1ReposOwnerNameTransfer } from "./postApiV1ReposOwnerN
349	349	export { route as postApiV1ReposOwnerNameUpstreamCheck } from "./postApiV1ReposOwnerNameUpstreamCheck.ts";
350	350	export { route as postApiV1Sessions } from "./postApiV1Sessions.ts";
351	351	export { route as postApiV1Share } from "./postApiV1Share.ts";
	352	export { route as postApiV1Start } from "./postApiV1Start.ts";
352	353	export { route as postApiV1Thoughts } from "./postApiV1Thoughts.ts";
353	354	export { route as postApiV1Tokens } from "./postApiV1Tokens.ts";
354	355	export { route as postApiV1UserEmailVerify } from "./postApiV1UserEmailVerify.ts";
		@@ -0,0 +1,23 @@
	1	import type { Route } from "../shared.ts";
	2
	3	export const route: Route = {
	4	method: "post",
	5	path: "/api/v1/start",
	6	summary:
	7	"Start building with no account (an agent holding only the forge's URL): answers 201 { user: { username }, token, repo: \"owner/name\", git: { url, push }, app: { url }, claim: { url, sleepsAfterDays, archivedAfterDays } }. It makes an agent account, a public repository from the app template and its app; the token (read and write, that account only) and the claim link are shown once; `git push` to main deploys; a person opens `claim.url` to take the account and its repositories. Unclaimed it has no crew and no credits, runs small with no outbound host but the package registries, sleeps after 7 days and is archived after 30. A few starts per source an hour and a cap per day; refused from another origin with 403 forbidden; the owner's setting can turn it off or ask for an invite `code`",
	8	auth: false,
	9	role: "anonymous",
	10	status: 201,
	11	body: { name: "string", description: "string", agent: "string", code: "string" },
	12	refusals: {
	13	off: "403, the owner turned the start call off",
	14	code_needed: "403, this forge asks for an open invite link's token as `code`",
	15	rate_limited: "429, too many starts from this source; retry-after says when",
	16	full: "429, the forge has started its share for today",
	17	too_large: "413, the body is over the limit for a stranger's",
	18	invalid_name: "422, name is 1-40 characters with a letter or digit",
	19	invalid_description: "422, description is plain text of at most 2000 characters",
	20	invalid_agent: "422, agent is at most 64 letters, digits, . _ -",
	21	failed: "500, nothing was kept; try again",
	22	},
	23	};