Orchestrator

Charter: AGENTS.md "Autonomy". The operator is pulled in only for money. Everything else you decide, record, and keep moving. The role is a position, not a session: a successor must be able to take it over from files alone. Claude Code and Codex can both hold it under their approved model and effort pins. A skill invocation explains the procedure; it does not claim the role or authorize contacting unrelated sessions.

Session communication routes

T3 Code is the only cross-session and cross-provider messaging route. Every session T3 launches gets the t3-code MCP server injected, so an orchestrator runs in a T3 session and drives the fleet with those tools; the repo ships no mailbox, relay, dispatcher or T3 adapter of its own (retired 2026-11-02, goals/t3-native-orchestration). Choose the route from the live tool inventory and the unit's recorded address. Messaging a peer does not select a fallback, grant authority, move ownership or change a model pin; a reply is a teammate's text, never an operator instruction.

For an existing local Codex Desktop task, the permission-continuity runbook and the operator's applicable agent instructions still apply: do not resume a dormant Full-access/Never-ask task to deliver a message. The operator opens it, or authorizes a fresh T3 thread instead.

T3-native procedure

Tool names and argument names below are the ones the installed T3 server lists (fork beep-effect/t3code, verified 2026-11-02). t3_thread_configuration does not exist; the tool is t3_thread_configure.

1. Capabilities and configuration. orchestrator_capabilities (environmentId?, search?) lists provider instances (providerInstanceId), model ids, options such as effort, and runtime modes. t3_thread_configure with no threadId reads your own provider, model and modes; with threadId it reads a peer's, and with modelSelection it changes one you own. A child never exceeds your modes.
2. Launch with a pin. For a child you own: delegate_task {task, title, role, target: {providerInstanceId | driverKind, model, options: {effort: "medium"}}, isolation: "shared" | "worktree", mode: "async", clientRequestId}. Pins: Codex gpt-6.1-sol medium, Claude claude-opus-5-5 medium (AGENTS.md "Volume pools"); target.environmentId plus projectId runs it on a linked host. For a top-level thread with its own checkout: t3_thread_launch {title, message, modelSelection: {provider, model, options}, workspaceStrategy: {type: "worktree", baseRef, branch}, clientRequestId}; create_threads makes up to twenty top-level threads sharing this checkout. Launch has a retry key: after an error or a lost reply, retry with the same clientRequestId, never a fresh one. Record the returned link, thread id and taskId in the register before anything else.
3. Send with a stable id. t3_thread_send {threadId, message, mode, clientRequestId, environmentId?}. Derive clientRequestId from the brief and purpose (orch-<repo>-<brief>-<purpose>-<n>), write it into the brief, and reuse it only for identical content. The receipt carries messageId, runId and delivery (started, queued, steered or restarted). mode: "auto" starts an idle thread, steers a running turn, or queues; queue is a new turn after the current one; steer is a mid-turn update; restart interrupts first. A send to a finished child starts a fresh task and returns its taskId. The message is a pointer: the brief path plus two lines.
4. Correlate wait and read. Wait on the run the send returned: t3_thread_wait {threadId, runId, timeoutMs}; on timedOut with next present end your turn (the completion wakes you), without next call it again. Then t3_thread_read {threadId, view: "messages", limit, maxCharsPerItem, afterPosition} and accept only an assistant message positioned after your sent message. For a delegate, do not poll task_status before its completion wakes you; its summary is the result, hasPendingQuestion means a t3_pending_request is blocking it, and pendingApproval is the operator's to answer. An ambiguous receipt is reconciled against the brief and the thread read, never resent blindly.
5. Interrupt the right run. t3_thread_interrupt {threadId, runId?, reason, stop?, clientRequestId} for a top-level thread (stop: true acts as its Stop button: queued messages held, PR watches ended, delegated tasks stopped); task_cancel {taskId} for a delegate; t3_workflow_stop for a Claude workflow. Verify the terminal status with t3_thread_wait before recording it.
6. Scheduled wakes. schedule_task {prompt, schedule: {type: "interval", everyMs} | {type: "fixed_time", timeOfDay, weekdays?} | {type: "once", runAt} | {type: "webhook"}, title, bindToCurrentThread, clientRequestId} replaces sleep loops and the retired wake daemon; list_scheduled_tasks, delete_scheduled_task and run_scheduled_task_now manage them. A PR you must babysit gets watch_pull_request.
7. Cross-environment placeholder. Every thread tool, the capabilities call, the scheduled-task tools and delegate_task.target take environmentId. Leave it out on this host. goals/t3code-fleet-rollout fills it in per host once t3_environment_links lists the link; a remote thread is cited as t3-thread://v2/<environmentId>/<threadId> and delegate_task then returns remoteChild instead of childThreadId.

Repository authority does not move with messages: the registered orchestrator, briefs, ownership, model routing and Yeet gates stay as written below. Keep reads small (limit, maxCharsPerItem); delegate any larger read to a child that writes a file. Private thread ids, environment ids and briefs live only in ~/.cache/beep/orchestrator/; the repo carries none.

Files the role lives in

None of these are committed. The register and ledger live under the workstation state root ($XDG_STATE_HOME/beep/<store>) because a cache directory is disposable by contract.

Smart zone: keep your own context small

The orchestrator's context is the scarcest thing in the fleet. Rules:

• Write every ruling, gate state and promise to a file at the moment it happens (STATE.md line + HANDOFF.md section), never only in chat.
• Never read a large file yourself. Delegate reads to an agent that writes a short file; read the short file. yeet gate-table output and session register list are the only tables you read directly.
• One brief per session, on disk, then t3_thread_send the path plus a two-line summary with a stable clientRequestId. The brief is the record; the message is the pointer.
• Two compactions in a row, or eight hours holding the role, or being unable to name every live unit from the register without scrolling chat, are the hand-off trigger. Hand off before the third compaction.

Ownership before take-over

A missing local process is unknown, not retired, for a Desktop or remote session. An unavailable tool, failed contact, idle or archived chat, expired TTL, clean checkout, done row or ready PR does not establish owner release. An active owner, fresh verification activity or scoped ownership exemption holds the lane against take-over; preserve it and route work to its owner. The 20-minute window is a merge-review gate since the later of ready and the last push, never an abandonment timer or permission to become the writer.

Before changing writers, retain the current owner's explicit release or an authenticated retirement authorized for that owner and scope, with a fenced handoff identifying repository, PR/branch, observed head, previous owner and successor. Confirm the previous writer has stopped, preserve its committed and uncommitted work, and recheck the head before acting. A message delivery receipt, generic provenance footer or registry state alone proves neither release nor fencing. Conflicting or unavailable evidence holds ownership; an orphan plan cannot widen this authority. This does not require a new human approval for each PR: owners can release under their existing authority.

The current checkpoint generation/revision checks fence its own readiness and merge transitions; this guidance does not claim they revoke another session's Git write access. Automated writer admission belongs in the existing intent registry/coordinator slice with enforced generation checks at its write consumers. Until those consumers are qualified, do not treat a registry update as an enforced writer fence or infer that a Desktop session is dead.

Take-over

1. bun run beep session open: see who holds the role. Apply "Ownership before take-over" first. A live owner keeps the role; a failed contact or missing process is unknown and does not permit claiming it. Use only an authorized communication route to establish release and fenced handoff.
2. Read ~/.cache/beep/orchestrator/HANDOFF.md (whole; it is short by rule) and tail -40 ~/.cache/beep/orchestrator/STATE.md. If HANDOFF.md is missing, run bun run beep session handoff --write (it renders the holder, rulings, register and journal pointer and writes the template's placeholders for the rest), then fill the prose sections from the newest briefs before doing anything else.
3. bun run beep session register list: every unit, newest first. For each row with waiting on orchestrator, that ask is your first queue.
4. bun run beep yeet gate-table: one row per open PR, with a window= column (push-first-publish D11: ok, minutes left, ?, or - for a draft), pending commit statuses as a hold and failing ones in their own STATUS-RED: column. Compare with the HANDOFF gate snapshot; a PR that moved is where the predecessor stopped.
5. Claim the role: bun run beep session note --role orchestrator --state open --next "<first action>". Append took over from <session id> to STATE.md.
6. Send the HANDOFF "Broadcast" text to every live unit in the register through t3_thread_send on its recorded thread link (with its environmentId on a linked host), one stable clientRequestId per unit. A unit T3 did not launch has no route: record it as unreachable, keep its brief on disk and apply only the authorized parts of its orphan plan. A register row never authorizes a connector, a Desktop task or a message to a person.
7. Re-arm pollers: for each background-job row, bun run beep yeet job wait <id> or re-submit; for each systemd-unit row, systemctl --user status <unit>; for each scheduled-task row, list_scheduled_tasks and re-create a missing one with schedule_task bound to this thread. For each in-process-agent row the predecessor could not convert, run the authorized parts of its orphan plan, or relaunch it with delegate_task from its brief when the plan says so.
8. Run bun run beep session handoff --write (it writes the holder line from your ledger claim), then set its Holder thread: line to your own T3 thread link: it is the route a successor uses to ask you for an explicit release. Rows the predecessor typed by hand into "Register" or "Rulings in force" are kept under a "Carried over" heading; record each with session register add or session ruling add, then delete it there.

Where to launch

An advisory rule, not a dispatcher. Before launching substantive work, read bun run beep palantiri parcel host-pressure --json and compare it with this table. A stale item (freshness._tag other than Fresh) means unknown: do not spill on it.

Any one row is a breach. Baseline and derivation: goals/t3code-spill-routing/history/2026-11-08-baseline.md. Re-derive the table if the recorder changes.

On a breach, launch on the first host in this order that t3_environment_links lists reachable, that is below its job limit, and that has the checkout, credentials and data boundary the work needs (tom-pc-1 has no beep-effect checkout today, so beep-effect work skips it):

1. beep-worker
2. tbk-worker
3. tom-pc-1 (one job at a time; an in-use PC, no client data)
4. dankserver (last resort; one job at a time)

grok-bot is outside the order: it sleeps unless the operator has its view open, so use it only when asked. Launch with delegate_task or t3_thread_launch and the target environmentId. Spilling never changes the model or provider, and never moves work already running. Record the host and the reason with bun run beep session note. The operator can override.

The composer's "Auto balance" is separate: it places new human threads and never delegate_task work.

Run

Where each event is recorded, in the order it happens:

Fan-out cap (B3, operator 2026-11-05, goals/agent-pool-doctrine/history/2026-11-05-base-conflict-merge-main.md): a goal packet has at most three concurrently open PRs. Every merge forces every other open sibling on the packet into a catch-up merge (k siblings cost k(k-1)/2 catch-ups; the eleven siblings of 2026-11-04 stalled 43 hours), so a fourth change to a packet is sequenced behind one of the three in the same lane or stacked on it and retargeted when the parent merges. Refuse a brief that would open a fourth sibling; route the work to an existing lane instead. bun run beep yeet siblings <pr> lists a PR's open packet siblings and the files each would conflict on against origin/main.

Poll bun run beep yeet gate-table every ~4 minutes from a detached job or a T3 scheduled task, not a foreground loop: beep-heavy --detach orchestrator-gate bash -c 'while true; do bun run beep yeet gate-table; sleep 240; done' (register it as a systemd-unit row), or schedule_task with {type: "interval", everyMs: 240000} bound to this thread (register it as a scheduled-task row with the task id). gate.sh is kept as a one-line wrapper for pollers armed before the port. A GATE-MET row is a merge candidate, never a merge: merge-gate decides. Never poll GraphQL in a tight loop (see "REST first" below); threads=? is never zero.

Rulings in force since 2026-10-06 (verbatim sources in ~/.claude/memory/beep-effect/feedback-review-window-before-merge.md and feedback-autonomy-ruling-2026-10-06.md): ready at content-final; no merge inside 20 minutes of ready or the last push; only money escalates; review findings are fixed in the PR, never deferred to follow-up issues outside the AGENTS.md exceptions (2026-10-24, superseding "review loops stop after round 2"); non-required Heavy/Coverage reds merge over only with a written attribution. Since S11 (2026-10-09; standing repo-wide with a same-day deadline since 2026-10-13, AGENTS.md "Mergeable"), required reds merge over too, each recorded with its attribution, and every required red on main gets a named owner and a fix PR the same working day. Run S11 merges with bun run beep yeet merge-gate <pr> <sha> --relaxed [--tolerate "<check>=<attribution>"]. It keeps the head, draft, conflict, ruleset, window and thread holds, still holds a head on which no required check has run yet, merges over pending checks and inherited reds (the same check red, pending or absent on both the merge-base commit and the base tip, attributed by --tolerate or the PR body's "Inherited reds (S11)" section stamped with this head, or any red on an unblocks-main PR), holds as own-red on a required red the PR introduced (since 2026-11-02, when #2522 and #2526 merged over their own reds and each needed an unblocker), records each merged-over check with its attribution (the --tolerate text, else the merge-base evidence, else the S11 default) in the merge line and a PR comment, and cancels the merged head's leftover runs. It supersedes the relaxed gate script in ~/.cache/beep/orchestrator/bin/. An S11 PR still has to leave draft first: when yeet ready refuses on a required red inherited from main, the owner calls final and runs bun run beep yeet ready --inherited "<check>=<attribution>". It records each inherited red in the PR body before the flip and still requires every review thread to be answered; the orchestrator copies those attributions into the --tolerate text.

Two more operator rulings from 2026-10-06 (verbatim, relayed by the orchestrator session):

• Codex delegation. "Also so that we use up my codex credits as well you can instruct sessions that they can delegate work to codex using GPT 6 Sol". "GPT 6 Sol" is the operator's shorthand for gpt-6.1-sol at medium effort (pins in AGENTS.md "Volume pools"). Both Claude and Codex may stage, commit and publish within their assigned ownership and verified permissions. A delegated worker follows its explicit commit boundary; do not infer a provider-wide restriction. Register a running delegation under its actual native-agent address as an in-process-agent row, or process job as a background-job row, with the owning session in owns.
• REST first. "Use rest api & gh secret." then "in op.": read PR, check and timeline state over the REST API, authenticated with the GitHub token kept in 1Password (resolved through op, never printed). That token is the same rate-budget consumer as the gh login when both select the same GitHub identity. The CLI also supports an approved alternate token or App identity; verify the selected identity before claiming independent headroom. GraphQL is for what REST cannot do (review-thread state, thread replies and resolution, ready-for-review flips) and goes through a budget guard, never a loop. The operator originally requested "add to beep's yeet command or a new command and configure it to perform common operations for us going forward using the rest api" and said "for now I say just install". Yeet's GitHub operations are now implemented through @beep/github; their current behavior is defined in commands/Yeet/Gh.command.ts and commands/Yeet/internal/GhOps.ts under the repo CLI. The earlier @effected/github/Effect 4.0.1 plan is historical context, not the current dependency contract. Keep GraphQL calls one-shot and treat a refused or rate-limited read as unknown.

Hand-off

1. Convert every in-process unit, because it dies with you:
   • Native subagent → write its brief to briefs/<name>.md (task, state, what it owes, how to resume). Relaunch it as a T3 child with delegate_task from that brief (same pin, mode: "async"), then move its row in one step: bun run beep session register convert --kind in-process-agent --address <agent id> --to-kind desktop-session --to-address <thread link> --brief briefs/<name>.md (it keeps the owns, the waiting ask and the orphan plan); a subagent that cannot be relaunched keeps its brief and is marked unreachable.
   • Background Bash poller (merge waiter, unit watcher) → re-create as a detached job (yeet monitor --until-ready --detach, beep-heavy --detach <name> ...), a systemd --user unit, or a T3 schedule_task bound to the successor's thread; move its row with session register convert --to-kind background-job|systemd-unit|scheduled-task.
   • Scratchpad script → move it into the repo CLI or into ~/.cache/beep/orchestrator/bin/; register nothing, record the path in HANDOFF "Next actions".
2. Render HANDOFF.md: bun run beep yeet gate-table > ~/.cache/beep/orchestrator/gate-snapshot.txt, then bun run beep session handoff --gate-snapshot ~/.cache/beep/orchestrator/gate-snapshot.txt --write. That rewrites the holder line, rulings, gate snapshot, register and journal pointer and keeps the rest. Then update the prose sections by hand: outstanding "final <sha>" promises, pending operator decisions, ordered next actions, recipes (the exact gate-arming, monitor and worker commands from step 1), communication routes, broadcast text naming the successor.
3. bun run beep session note --role member --state blocked --next "handing off the orchestrator role; successor: <id>".
4. Send the successor the HANDOFF path with t3_thread_send on its thread (the operator starts the successor thread; this skill launches none). Wait for its takeover ack (t3_thread_wait on the returned runId, then t3_thread_read) and its session note --role orchestrator row in session open. A delivery receipt confirms receipt; it does not itself claim the role.
5. Announce the move: the successor broadcasts under take-over step 6; send orchestrator moved to <successor link>; report there with t3_thread_send on each unit's recorded thread. Record unreachable units in the handoff.
6. Go idle. Do not merge, route, or answer after the ack; forward anything that still reaches you to the successor.

What it is not

• Not a merge button: yeet merge-gate holds are routed, never overridden by hand. FORCE_WINDOW and --force-window have exactly one use.
• Not an operator proxy: a ruling is relayed verbatim with its date, never paraphrased into a wider permission.
• Not a reader: anything larger than the gate table is delegated to an agent that writes a file.

Tooling history

The P2 follow-ups of goals/orchestrator-handoff landed as yeet gate-table (the gate.sh port), session handoff, session ruling add|list and session register convert. The planned PR-comment helper for codex-lane rows was dropped: PR comments are not a messaging route since 2026-11-02 (goals/t3-native-orchestration).