sub-agents: a spawn cannot take the last of a window

The failure this prevents is specific — a sub-agent burns the end of a limit window and the session the
owner is actually sitting in dies mid-turn, because the credits went somewhere nobody was watching. So
it is a condition on spawning rather than a refinement: an endpoint that can start unattended work
without checking is wrong from its first call, and the symptom lands on someone else's conversation.

Wired into POST /command-hq/commanders/new, which — this is the finding — already IS the spawn
mechanism the sub-agents item was asking for. It starts a turn with ws: null, waits only for
session:claude, and returns the transcript id, with command_hq_sessions naming, listing and costing it.
So "commander or something lighter" answers itself: a commander costs nothing extra and a lighter thing
would need its own registry to be visible at all. What is still missing is only the agent-callable
surface.

Refuses rather than queues or downgrades. Queueing means holding work against a window Officer does not
control, and the reset it would wait for is a claim about a shared pool — every claude on the machine
spends these, including terminals and pipelines. A refusal naming the window, the percentage and the
reset is something a caller can act on now.

The floor is 15% and the reasoning is in the file: the interactive failure is not "cannot start a chat",
it is "a turn already in flight is cut off", and a turn costs a fraction of a window.

Fails OPEN, deliberately. The numbers come from an external endpoint with a credential Officer does not
own, so a blip or a signed-out CLI must not stop every spawn on the machine with an error about usage
that has nothing to do with usage. The problem is reported so a caller can say "started, but unchecked".

Seven tests on the pure rule — tightest window decides rather than the average, no limits allowed rather
than blocked, exactly-at-the-ceiling refuses. Verified against the live account, where it correctly
refuses right now at Session 90%.

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

src/servers/api/command-hq/router.ts

@@ -1,6 +1,7 @@
 import type { Context } from 'hono';
 import { randomUUID } from 'node:crypto';
 import { createRouter } from '../../create-router';
+import { checkBudget } from '../sub-agents/budget';
 import * as errors from '@@/custom-errors';
 import { resolveHomeDir } from '@@/user-home';
 import { getCommandersDir, toShellUsername } from '@@/data-path';
@@ -269,6 +270,17 @@ commandHqRouter.post('/commanders/new', async (ctx) => {
   const prompt = body.prompt?.trim();
   if (!prompt) throw errors.BAD_REQUEST('prompt is required');
 
+  // ── Room to run, before starting work nobody is watching ──
+  //
+  // A commander created here runs unattended. If it burns the last of a window, the session the owner is
+  // actually sitting in dies mid-turn — the credits went somewhere nobody was looking. So the floor is
+  // checked at the one door that starts unattended work, rather than left to whoever calls it.
+  //
+  // It fails OPEN by design (see budget.ts): the numbers come from an external endpoint with a credential
+  // Officer does not own, and a network blip must not stop every spawn on the machine.
+  const budget = await checkBudget();
+  if (!budget.ok) throw errors.TOO_MANY_REQUESTS(budget.reason ?? 'not enough usage headroom to start an agent');
+
   const sessionId = randomUUID();
   const model = (await getUserDefaultModel(user.id)) || DEFAULT_MODEL;