Issue #847: Orchestrator: scripts/orchestrate.nika runs architect and builders without the main session

Open and answer this issue on GitHub.

ready · opened 2026-10-25 · updated 2026-10-25 · 3 comments

Introduction

Today the main session runs the loop by hand. The architect writes a brief, the main session starts a builder with Read your brief at P, reads the one-line answer, runs scripts/cycle.nika -- DIR and then starts the next architect. cycle.nika (with status.nika, batch.nika and release.nika) already turns the state into lines (NEXT, CUT, RED, BUMP, OWNER). Only two steps are still manual: starting an agent and waiting for it. The owner wants a script that runs this loop and wakes the main session only when the loop can no longer go on.

Checked

• claude CLI headless mode: -p, --agent, --model, --max-turns, --max-budget-usd, --allowedTools, --output-format json (gives turns, usage, cost).
• std::process::run: blocks and captures output, but has no timeout, no background child and no kill.

Decisions (owner, 2026-10-25)

1. Permissions: --allowedTools per agent type; never --dangerously-skip-permissions.
   • builder: Bash, Read, Edit, Write, Grep, Glob.
   • architect: the tool list in .claude/agents/architect.md.
2. Limits, taken from the Runs table in docs/tokenspeed.md (recent builders used 38-185 turns and 1.2-14.4 M of context):
   • builder: 120 turns, 20 USD;
   • architect: 80 turns, 15 USD;
   • 200 USD per day;
   • at most 12 agent starts per script run.

   The limits are constants at the top of the script. Only the owner raises them, via the main session.

3. Operation: the main session starts the script with run_in_background. The script runs until it writes DIR/ESCALATE and exits with a non-zero code. The main session then talks to the owner and restarts it.
4. Version: the script may raise the version (cycle.nika --apply).
5. Owner questions: the first question is written to DIR/QUESTION, and the loop goes on with other topics. A second escalation or question while one is open stops the script.

No ADR and no specification text: this is tooling only, so no version raise.

Handover format

Each brief starts with frontmatter: agent, model, max_turns, budget_usd, issue, touches, parallel_with. The report keeps today’s fields and adds Owner: none|<question>. The architect hands back a file, DIR/architect.N.md, with Next: batch|owner|stop and Owner: lines.

Escalation (DIR/ESCALATE, exit code non-zero)

• a builder ends without a report, with an error, or at its turn or budget limit;
• the same brief is CUT twice in a row;
• RED survives one fix-forward cycle;
• the architect writes no new batch.txt;
• a second open question;
• less than 3 GB of disk free;
• the day cap or the start cap is reached;
• cycle.nika prints a line the script does not know.

To build

1. std::process::run: a timeout that kills the child after N seconds and reports it. Test in tests/compiler/.
2. batch.nika / cycle.nika: read brief frontmatter and print NEXT <brief> <agent> <model> <turns> <budget>; read the report field Owner:. Tests on fixture directories.
3. scripts/orchestrate.nika --dry-run: run the loop over cycle.nika and print the claude command lines without starting anything.
4. Start builders: write <brief>.run.json, record the figures with batch.nika --tokens, check the day cap, apply the escalation rules.
5. Start the architect and read its hand-back file; handle DIR/QUESTION and the stop rule; rewrite The loop and The main session’s cycle in docs/architect.md, and update .claude/agents/architect.md.
6. Pilot: one batch of two briefs, started with --max-starts 3.
7. Later: two builders in parallel when their touches lists do not overlap (needs a background child in std::process).

Comments

keywan-ghadami, 2026-10-25

Update (owner, 2026-10-25). This supersedes the points below in the issue text.

1. Probe done (step 0 is built). claude -p "Antworte nur mit: Hallo" --model sonnet --effort low --max-turns 1 --output-format json works in the container: stop_reason end_turn, terminal_reason completed, 1 turn, 6 output tokens. The JSON holds total_cost_usd, usage, modelUsage per model and session_id. Base load is about 26k cache-read plus 9k cache-creation tokens per start.
2. Dollar limits stay. The script uses total_cost_usd as a limit (per agent, per day), and also records turns and the tokens from usage for every run.
3. costBasis: "list" is the list price, not necessarily what is billed. The limits are therefore a guard, not an invoice.
4. To clear in step 4 (start builders): the session_id in the JSON of the probe was the one of the running main session. It is open whether the CLI inherits the session environment or continues that session. Step 4 starts with a test: run the same call (a) as is, (b) with --no-session-persistence, (c) with an explicit --session-id <fresh uuid>, and compare session_id and whether the main session’s transcript grew. claude --help lists --no-session-persistence, --fork-session (only with --resume) and --bare. Until the test shows separate sessions, the script passes --no-session-persistence and a fresh --session-id, and escalates if the returned id differs from the one it passed.

---

Generated by Claude Code

keywan-ghadami, 2026-10-25

Re-cut of the To build list (owner: every step must be in use at once, not only at the end). Steps 0 (probe) and 1 (within:, timed_out, ADR-243 D9, 0.0.1222) are built. This replaces steps 2-7 of the issue text.

1. scripts/agent.nika -- BRIEF [--dir DIR] [--dry-run] starts one agent headless from a brief (frontmatter optional, defaults builder/sonnet/120 turns/20 USD), with within:, a per-agent tool list, --no-session-persistence and a fresh --session-id. It writes BRIEF.run.json, appends turns/tokens/cost to tokens.txt and cost.txt, and writes DIR/ESCALATE (exit 2) on timeout, error, missing report, a changed session_id, low disk or the 200 USD day cap. It answers with one line, done <sha8> report <path> cost <usd> turns <n>. Use from now on: the main session starts builders with this command in the background instead of the Agent tool, and reads only its one line. This also settles the session_id question.
2. Frontmatter in batch.nika / cycle.nika and the report field Owner:: NEXT prints the full line (brief, agent, model, turns, budget), OWNER lines come from reports. Use: the main session runs agent.nika on the NEXT path without reading the brief; the architect’s frontmatter decides model and limits.
3. agent.nika --architect LINE: starts the architect with the cycle line, the token lines and the owner’s words (file DIR/owner-answers.txt), and reads its hand-back file DIR/architect.N.md (Next: batch|owner|stop, Owner:). Use: the main session no longer starts architects; it runs this on CUT/RED/BATCH DONE and reads one line.
4. scripts/orchestrate.nika --dry-run, then live with --max-starts: the loop cycle.nika -> agent.nika -> cycle.nika, sequential, with the escalation rules, DIR/QUESTION and the stop-on-second-question rule. Use: the main session starts one background command per batch and is woken only by exit/ESCALATE.
5. Release and CI inside the loop: cycle.nika --apply when CI is green, gh run watch on the pushed commit, one fix-forward cycle on RED. Use: no version raise or CI watch by hand any more. Rewrite The loop / The main session’s cycle in docs/architect.md and .claude/agents/architect.md.
6. Later: two builders in parallel when touches are disjoint (needs a background child in std::process).

Brief for step 2: briefs/847-agent-nika.md (builder, Sonnet).

---

Generated by Claude Code

keywan-ghadami, 2026-10-25

The local quality gate is #852: from its step 3 on, the orchestrator runs scripts/gate.nika after each builder report, and two REDs in a row from the gate count as ESCALATE (#852 step 5).

---

Generated by Claude Code

Back to Open Issues