todo: turn timer in chat, and a sub-agent spawn endpoint bounded by usage limits

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

todo/sub-agents/_index.md

@@ -0,0 +1,9 @@
+---
+theme: sub-agents
+heading: "Sub-agents — agents spawning agents"
+kind: theme
+---
+
+An agent asking Officer to run another agent, through a door the owner defines rather than whatever the
+harness happens to offer. Related: `todo/agent-delivery/` is the other direction — the backend speaking
+into a session that already exists.

todo/sub-agents/an-api-endpoint-for-spawning-an-agent-with-a.md

@@ -0,0 +1,29 @@
+---
+id: sub-agents/an-api-endpoint-for-spawning-an-agent-with-a
+title: "An API endpoint for spawning an agent with a prompt"
+theme: sub-agents
+status: open
+created: 2026-08-21
+date_source: stated
+order: 1
+---
+
+**An API endpoint for spawning an agent with a prompt.** Wanted 2026-08-21. An agent calls it, names a
+prompt, and gets another agent running. A sub-agent system — but **defined by the owner**, which is the
+whole point of building one rather than leaning on the harness's own: the shapes, the limits and the
+vocabulary are Officer's, so every harness gets the same door and the definition does not change when a
+CLI does.
+
+It has more of a starting point than it looks. `startClaudeTurn` already runs a turn with no browser
+attached (`nudger.ts:102`, `ws: null`), so the mechanism for "run an agent from the backend" is proven —
+what is missing is spawning a NEW one on request rather than feeding a known session, plus the surface
+an agent can actually call, which is MCP or an authenticated route.
+
+Open: whether a spawned agent is a Command HQ commander (named, listed, costed — `command_hq_sessions`
+already does all three) or something lighter that disappears when it finishes; how its output returns to
+the caller, streamed or awaited; and what the caller may set — model, effort, cwd, permission mode — versus
+what Officer fixes.
+
+**Bounded by the budget rule in `sub-agents/spawning-must-respect-the-account-s-own`, which is not
+optional.** An endpoint that spawns freely is exactly how a weekly limit gets spent by something nobody
+was watching.

todo/sub-agents/spawning-must-respect-the-account-s-own.md

@@ -0,0 +1,32 @@
+---
+id: sub-agents/spawning-must-respect-the-account-s-own
+title: "Spawning must respect the account's own session and weekly limits"
+theme: sub-agents
+status: open
+created: 2026-08-21
+date_source: stated
+order: 2
+---
+
+**Spawning must respect the account's own session and weekly limits.** Wanted 2026-08-21, as a
+condition on the spawn endpoint rather than a later refinement. The failure it exists to prevent is
+specific: a sub-agent burns the last of a window, and the chat or session the owner is actually in dies
+mid-turn because the credits went somewhere nobody was watching.
+
+**The numbers are already read.** `api/chat/claude-usage.ts` fetches the limit windows from Anthropic's
+OAuth usage endpoint using the token the CLI stored at login, and exposes them as `UsageLimit` — a label
+already fit to render (`Session`, `Weekly`, `Fable Weekly`) with its percentage. So the backend does not
+need new plumbing to know how much room is left; it needs to consult what it has before starting work.
+
+Two facts from that file that shape this, both stated in its own header:
+
+- **The windows belong to the ANTHROPIC ACCOUNT, not to Officer.** They are spent by every `claude` on
+  the machine — this chat, a terminal, a task runner, a pipeline step. So a budget check has to reason
+  about a shared pool it does not control, and a reservation Officer makes for itself is a guess.
+- **The module is owner-only and structurally so.** It takes no identity at all, deliberately, because
+  `getOwnerHomeDir` ignores the email it is passed. Any budget rule that has to answer "how much has
+  THIS user left" needs something that does not exist yet.
+
+Open: what the endpoint does when the room is thin — refuse, queue until the window resets (the reset
+time is in the same payload), or downgrade the model; and whether the reserve is a fixed floor or a
+share the owner sets.