Any agent with only the URL starts building in one call: account, repo and live app, no person or crew needed #10916

An agent with only the forge's URL can now go from nothing to a live app in one call plus a git push, with no person and no crew involved. The pushed branch passes tsc, scripts/gate.ts, design-lint and the start, MCP and llms tests (267 pass). I did not run the full suite; the forge's check does that. I did not do the cold-agent run against a live forge, so the recorded proof the issue asks for is missing.

What changed

• Start call: POST /api/v1/start takes {name, description?, agent?} and needs no token. It makes an agent account, a repo from the app template and its app, and returns {user, token, repo, git, app, claim}. The token is scoped to that account and shown once. The logic is in src/actions/start.ts, the route in src/http/api/start.ts, and the account state in src/core/starts.ts plus the migration 20261110160000-start-accounts.
• MCP: start is open without a token, like report. I added it to src/http/mcp.ts and src/http/mcp_table.ts and noted it in docs/MCP.md. test/mcp-size.test.ts passes.
• Push builds it: an unclaimed account's repos have no crew assigned and spend no credits. Pushing to main deploys like any other app.
• Claim: claim.url is a one-time link (src/actions/claim.ts, page in src/web/pages/start_claim.ts). A person opens it, makes or signs into an account, and the agent account and its repos become theirs, with the agent kept as a member. Opening the link also wakes an account that was put to sleep.
• llms.txt: "Start here" now leads with the start call and a curl example. The "if /signup answers 403" dead end is gone.
• Defenses:

- Unclaimed apps run at the small size, reach no host but the package registries, and are public under the agent's name with the report link. - A few starts per IP per hour, plus a global per-day cap. - Unclaimed accounts sleep after 7 days (token dead) and are archived, not deleted, after 30 (src/actions/start_sweep.ts). - The setting Agents can start here: open / invite code / off is in /admin/limits, default open (src/settings/agent_start.ts).

• Tests: test/start.test.ts runs start, push, live, claim, the boundary and cross-origin refusals, the rate limit, the setting, the MCP tool and the sleep/archive sweep end to end against a scratch forge.

What to look at

• In my sandbox the tests logged git spawn errors (ENOENT … 'git') from the apps runtime. They passed regardless; the forge's check will confirm the deploy path.
• The hosted-forge offer on the claim page is not built. The claim only hands over the account and repos.

Try it

curl -sX POST $FORGE_URL/api/v1/start -d '{"name":"my-app"}'

Clone git.url, git push to main, open app.url, then open claim.url as a person.

🤖 Generated with Claude Code

Closes #10912

An agent with only the forge's URL can now go from nothing to a live app in one call plus a git push, with no person and no crew involved. The pushed branch passes tsc, scripts/gate.ts, design-lint and the start, MCP and llms tests (267 pass). I did not run the full suite; the forge's check does that. I did not do the cold-agent run against a live forge, so the recorded proof the issue asks for is missing.

What changed

• Start call: POST /api/v1/start takes {name, description?, agent?} and needs no token. It makes an agent account, a repo from the app template and its app, and returns {user, token, repo, git, app, claim}. The token is scoped to that account and shown once. The logic is in src/actions/start.ts, the route in src/http/api/start.ts, and the account state in src/core/starts.ts plus the migration 20261110160000-start-accounts.
• MCP: start is open without a token, like report. I added it to src/http/mcp.ts and src/http/mcp_table.ts and noted it in docs/MCP.md. test/mcp-size.test.ts passes.
• Push builds it: an unclaimed account's repos have no crew assigned and spend no credits. Pushing to main deploys like any other app.
• Claim: claim.url is a one-time link (src/actions/claim.ts, page in src/web/pages/start_claim.ts). A person opens it, makes or signs into an account, and the agent account and its repos become theirs, with the agent kept as a member. Opening the link also wakes an account that was put to sleep.
• llms.txt: "Start here" now leads with the start call and a curl example. The "if /signup answers 403" dead end is gone.
• Defenses:

- Unclaimed apps run at the small size, reach no host but the package registries, and are public under the agent's name with the report link. - A few starts per IP per hour, plus a global per-day cap. - Unclaimed accounts sleep after 7 days (token dead) and are archived, not deleted, after 30 (src/actions/start_sweep.ts). - The setting Agents can start here: open / invite code / off is in /admin/limits, default open (src/settings/agent_start.ts).

• Tests: test/start.test.ts runs start, push, live, claim, the boundary and cross-origin refusals, the rate limit, the setting, the MCP tool and the sleep/archive sweep end to end against a scratch forge.

What to look at

• In my sandbox the tests logged git spawn errors (ENOENT … 'git') from the apps runtime. They passed regardless; the forge's check will confirm the deploy path.
• The hosted-forge offer on the claim page is not built. The claim only hands over the account and repos.

Try it

curl -sX POST $FORGE_URL/api/v1/start -d '{"name":"my-app"}'

Clone git.url, git push to main, open app.url, then open claim.url as a person.

🤖 Generated with Claude Code

The check failed on the "both doors" rule: the pull adds src/web/pages/start_claim.ts but no terminal screen. I added docs/features/start.md and a commit with a "No door:" line saying why none is needed.

bun scripts/gate.ts now passes with no output after the second commit, and the push went through. I did not re-run tsc or the tests, because the new commits add only a doc and an empty commit.

The "No door" reason is that the claim page is opened once from a link by a person in a browser. The agent's own side is the API and MCP start call, which docs/features/start.md covers.

If you want a terminal screen for claiming rather than the exemption, say so and I'll add one in src/tui/.

I merged main into the branch and pushed it. The only conflict was in src/web/standards.ts, in the llms.txt "Start here" list.

How I resolved it:

• Mine: the "Build now, no account" start line.
• Main's: UPSTREAM_REPO in the "Get your own forge" and "Work from your own forge" lines, instead of the hard-coded URL. Main also deleted the "if /signup answers 403" line, which was already the issue's ask, so I did not bring it back.
• Connector line: main's version only said report works without an account. I kept mine, which says start and report need none.

bun x tsc --noEmit is clean. I ran the llms, MCP and start tests (test/llms-anonymous.test.ts, test/llms-tools.test.ts, test/mcp-size.test.ts, test/mcp.test.ts, test/mcp-card.test.ts, test/start.test.ts) and all passed. scripts/gate.ts printed nothing, which I take as clean. After a small fix to the connector line I re-ran only four of those files (not test/mcp-size.test.ts or test/mcp.test.ts); 19 pass, 0 fail. I did not run the rest of the suite; the forge's check will.

I fixed the seven failing tests and pushed. The seven test files that counted doors now pass (the six edited ones plus signup-gate-parent, which is the same suite as before); bun x tsc --noEmit and bun scripts/gate.ts are clean. I did not run the full suite, so the forge's check on this push is the real verdict.

Six failures were the suites that count every door, which didn't yet know about the start feature:

• Event audience: start.made, start.claimed and start.swept are now classified for admins in src/core/event_audience.ts.
• Cookie sites: src/web/pages/start_claim.ts is listed in test/cookie-flags.test.ts as an unwalked cookie site, with the reason.
• createUser callers: src/actions/start.ts and src/web/pages/start_claim.ts are added to test/signup-gate-parent.test.ts.
• MCP tool entries: test/mcp-table.test.ts now expects two extra entries (report and start) instead of one.
• Unseeded routes: /claim/start/:token is listed in test/security-floor-routes.test.ts, since the seed can't mint a claim token.
• Pages budget: MAX_UNFIXTURED goes from 144 to 145 in test/pages-budget.test.ts, because the claim page has no fixture either. The file's own comment says never to raise it silently; this is the raise and the reason for it.

The seventh, the system-stalls test, was fragile rather than broken by my change. It reads the requests of the last few seconds, so it picked up requests that other test files had just made in the same process. It now waits 300 ms and uses a 300 ms window. This edits the test, not the code. It passed alone and failed when run with signup-gate-parent; I couldn't reproduce the shard order the check used, so I haven't confirmed the fix there.

All of sentinel's findings are addressed except the direction question, which needs a person. Nothing here has run against the forge's full check yet. Locally the gate and tsc are clean, design-lint is clean, and the touched suites pass. The suites I ran were start, start-claim, tui-signup, tui-claim-start, palette-roster, pages-budget, mcp-system-stalls, signup-gate-parent, cookie-flags and tui-invites.

Security

• Claim page, signup gate: the account form is now offered and accepted only where /signup would admit a stranger with no invite. That means signup open and not passkey-only. Otherwise the page shows only "Sign in", and a direct POST to /account makes no account and spends no link. Tests cover signup closed and invite-only (test/start-claim.test.ts).
• Failed transfer in claim: each repository's move is checked, and only those that moved are woken.

- Partial move: a repository that will not move stays with the agent and is named in the "Taken" message. - Nothing moved: the link is given back and the claim answers failed. - Test: a pre-made directory at the destination forces the failure, and the same link works once it is cleared.

• Start caps: the caps are now counted and the row inserted in one transaction, so concurrent starts cannot overshoot. Each source also gets 10 starts a day, so one source can use at most 5% of the 200-a-day forge cap. A test fires 7 concurrent starts from one source and expects exactly 3 to succeed, with no stray accounts.
• Abuse bound (documented in docs/features/start.md): many addresses can still fill the 200-a-day cap. I chose not to add an admin setting for the number. The existing Agents can start here setting (invite code or off) is the answer to that.

Both doors

• Claim in the terminal: the Take an agent's work palette entry (src/tui/screens/claim_start.ts) is offered to any person. It asks for the link, names the repositories, and claims through claimStart after a confirm.
• Setting in the terminal: a on the Invite links screen sets Agents can start here, from → to with a confirm, for admins who are people.
• Tests: test/tui-claim-start.test.ts, and an added case in test/tui-signup.test.ts.
• Docs and roster: docs/features/start.md now covers the terminal path, and the two palette-roster expectations gained the new entry.

Design

• Repo list: it now uses the row component.
• Explanations: the muted lines under the forms and the long text beside the admin select are removed, so each is said once.

Tests

• Page budget: MAX_UNFIXTURED is back at 144. The claim page has a real fixture, a seeded start row at /claim/start/claim_fixture.
• Stall test: the 300 ms sleep is gone. The job now holds the loop for the whole 300 ms window and the stall is read straight after. No request can finish inside that window, so other files' requests cannot reach it.

Direction: I did not reorder anything. #10912 is the onboarding feature, and whether it goes ahead of the pipeline items (#6534, #6611, #5276, #3316, #6217, #6428, #1242, #1073) is a person's call. I have no reason to give for putting it first. If you hold it, this branch is ready to land when released.

To try:

1. Run curl -sX POST $FORGE_URL/api/v1/start -d '{"name":"my-app"}'.
2. Open the returned claim.url signed in, or signed out where signup is open.
3. In the terminal, use the palette entry "Take an agent's work".

Both failures are fixed and pushed as 926e90cbb. Locally, pages-budget and header-width now pass, and so do start, start-claim and the roles tests. tsc --noEmit is clean. I did not run the full suite.

• header-width: the header comment in src/actions/claim.ts had one line over 160 columns. I wrapped it.
• pages-budget: /:owner/:name/issues/:number came to 71 SQL statements against a budget of 70. The cause was the test fixture the branch added: a new agent-fix account for the claim page. That extra user added one statement to the issue page. The fixture now records the start on the existing bob user, so no extra account is created. The page is back to 70 and the budget is unchanged.
• src/core/roles.ts: lacks() now checks the role first and asks the unclaimed table only when the role lacks make_it_yours. This saves a query per check and behaves the same. It wasn't the cause of the 71.

The pages-budget failure reproduced locally, so it was not a flaky timing failure.

The check failed because postApiV1Start.ts had no role. Main now requires a role on every route in src/contract/openapi/. I merged origin/main into the branch and set role: "anonymous" on POST /api/v1/start, since it takes no account. Nothing else changed.

bun x tsc --noEmit and bun scripts/gate.ts pass. I ran six suites (openapi-coverage, openapi-drift, openapi-routes, start, start-claim, contract) and all 438 tests pass. I didn't run the full suite; the forge's check does that on this push.

To try it, open the preview at https://lab--10916--forge-trevato-apps.open-platform.sh and fetch /api/v1/openapi.json, or whichever path the app serves the spec at. The start route should now carry x-role: anonymous.

Parked by the crew: the check stayed red through 2 automatic tries

Reopened: this is the owner's ask from today (friends and their agents getting in), so it should not stay parked. Rebase on main, run the failing check locally until it is green, then push. If the failure is not yours, name the test here.

I merged current main into the branch and pushed. The forge's check hasn't run on the new push yet, so I can't say it is green.

What changed this round

• One merge conflict, in test/mcp-system-stalls.test.ts. It isn't part of this pull, so I took main's version of the file whole. The commit that fixed the stall measurement there is now on this branch.
• There are no other code changes. The feature is the one described earlier: POST /api/v1/start creates the account, repo and live app in one call, with its migration, MCP tool, claim page and settings. The start route keeps the anonymous role that main now requires of every route.

Checks run locally

• bun scripts/gate.ts and bun x tsc --noEmit both pass.
• I ran the 15 test files for the areas this pull touches: start, claim, signup gate, MCP card/table/tools, cookie flags, security floor, pages budget, palette roster and the TUI screens. All 308 tests pass.
• I ran the role and route tests: crew-roles, here-roles, mcp-routes-described and the OpenAPI and anonymous-route suites. All 514 pass.
• scripts/fast.ts says this diff reaches 2,272 of 2,619 test files, so I did not run the full suite. The forge's check will.
• The tests I ran log git ENOENT errors because there is no git binary in the sandbox. They don't fail any test.

I could not find which test turned the earlier check red, because I didn't have its log. If the check fails again, the log will name the test, and I'll look at it then.

🤖 Generated with Claude Code

I merged main into the branch, resolved the five conflicts keeping both sides, and pushed. tsc --noEmit and scripts/gate.ts are clean. I ran about 20 related test files, not the whole suite, and the only failure was the llms.txt size test, fixed below. I did not re-run that wider set after the llms.txt fix, only the four llms/standards files.

• src/http/server.ts, src/tui/screens/entries.ts, test/palette-roster.test.ts: kept both sides. The three /claim/start routes and the claimStart palette entry stay, and main's /signup/requested route and requests ("Waiting") entry come in beside them. The roster test lists both entries.
• src/web/pages/admin-limits.ts: the imports are the union of both sides: changeAgentStart, readAgentStart and AGENT_START_MODES from this branch, SIGNUP_MEANS from main.
• src/web/standards.ts: the "Build now, no account" line for /api/v1/start stays as it was. main's account-by-request line is kept with the same content, but shortened: with both lines in, the anonymous /llms.txt went over its 6 KB budget (test/llms-anonymous.test.ts checks it). The shortened line is the one place I changed wording from either side.

I did not change any test to make it pass.

Both failing tests pass locally and the fixes are pushed. tsc --noEmit is clean, and I re-ran only test/no-polling.test.ts and test/security-floor-doors.test.ts, not the full suite.

• "patterns the walk skips" (test/no-polling.test.ts): the new /claim/start/:token page needs the one-time token an anonymous start returns, which the seeded walk cannot make. I added it to NOT_WALKED with that reason.
• "each return … is floored" (test/security-floor-doors.test.ts): this failure did not come from my change. main already composes the floor in answered as .then((r) => securityFloor(resourcePolicy(request, r))).then(privateWhenSignedIn…), and the test still expected .then(securityFloor). I changed the assertion to a regex that accepts the floor wrapped in a callback. The floor itself is untouched. This is the one place I edited a test because the test was stale, not the code.