This is the default execution transport for every consult the oracle skill
and its composing skills run. It replaces only the transport; every contract
in the owning SKILL.md — slug selection, packx bundling, Prior-State Ledger,
Forward Progress Gate, prompt quality, text-only output boundary, waiting
rules, summarization, and commit rules — still applies.
Consults run through the qualified four-slot, dual-account green service on tv. Each account has two isolated Chrome workers, allowing four concurrent consults without sharing a browser profile. Independent local CLIs join one crash-recoverable FIFO admission queue; only its oldest live waiter probes for capacity, and a fifth or later caller waits until a slot opens. The server remains authoritative for one run per worker, two per account family, and four total.
Do not call mcp__oracle__consult on this path — that process uses the
production ~/.oracle/config.json. Invoke the qualified runner below, which
opens a temporary SSH tunnel to green staging and runs the matching
protocol-v2 CLI with an isolated client home. The direct MCP browser consult
is the fallback only when this pool's preflight fails terminally.
Treat these values as a single immutable qualification set:
| Role | Value |
|---|---|
| SSH target | tv as the existing johnlindquist GUI account |
| Green service | 127.0.0.1:19474 on tv |
| LaunchAgent | com.steipete.oracle.staging.dual-profile.green |
| Green home | ~/.oracle-staging/dual-profile-green on tv |
| Chrome workers | account A: profile-a on 19222, profile-a-2 on 19224; account B: profile-b on 19223, profile-b-2 on 19225 |
| Qualified build | 4a5f05a1d46857396cda46dab5913f7d57c303d8467167404a5b3e9c0d227c7a |
| Matching local worktree | ~/dev/oracle-wt/dual-profile-isolation-scaffold |
| Temporary local forward | invocation-private dynamic loopback port -> tv:127.0.0.1:19474 |
| Isolated client home | ~/.oracle-round-robin via ORACLE_HOME_DIR |
| Production read-only guard | tv:7333; PID and start identity must not change |
The runner reads the green token over authenticated SSH into process memory only. It never prints or writes the token locally. It compares local CLI, protocol-v2 client, and browser-navigation hashes against the exact green release before use.
If any pinned value changes, stop. Requalify the new release and update this
skill, runner, and receipt together. Never silently follow latest, reuse
production config, or downgrade the build check.
~/.oracle/config.json for this workflow.--remote-profile. Omitting explicit profile selection is what
activates persistent server-side round robin.pkill, killall, wildcard cleanup, or recursive deletion.
The runner terminates only its verified SSH tunnel PID.commit.~/.agents/skills/oracle/scripts/run_round_robin.sh --check
Stop on any failure. A successful check proves:
0600;Use the owning SKILL.md preview and build contract:
mkdir -p ".notes/oracle/{slug}"
packx --preview [filters] -x "**/CLAUDE.md"
packx --limit 900k [filters] -x "**/CLAUDE.md" \
-f markdown --no-interactive --stdout \
> .notes/oracle/{slug}/bundle.txt
test -s .notes/oracle/{slug}/bundle.txt
Never include CLAUDE.md; prefer AGENTS.md. Add --strip-comments --minify
when preview exceeds 200 files. For broad planning/review, attempt richer context
when the bundle is below 250k.
Write the complete prompt to:
.notes/oracle/{slug}/prompt.md
Follow the full SKILL.md Prompt Contract. Include the slug header,
project briefing, goal, Prior-State Ledger, Forward Progress Gate, evidence,
bundle map, requested deliverable, the maximum-actionable-batch demand,
repository rules, and this output boundary:
Return your answer as text in this response only. Do not create, attach, export,
or offer any downloadable file. Do not create local project artifacts yourself.
The local agent will write any needed files, plans, notes, goals, commits, or
verification logs using local tools.
~/.agents/skills/oracle/scripts/run_round_robin.sh \
--slug "{slug}" \
--prompt-file "$PWD/.notes/oracle/{slug}/prompt.md" \
--bundle "$PWD/.notes/oracle/{slug}/bundle.txt"
Add each screenshot, PDF, compact evidence supplement, or other artifact with a
separate --file /absolute/path.
The runner always supplies:
engine: browser
model: gpt-5.6-pro
browser thinking: extended
browser attachments: always
remote profile: omitted (automatic round robin)
The service atomically persists allocation before upload or submission. Once a
run receives a slot, retries and reattachment remain sticky to that slot; there
is no post-assignment account failover. Fresh local invocations use a stable
service-level queue beneath ~/.oracle-round-robin/admission; the queue namespace
never contains the dynamic SSH port or slug. Its oldest live waiter retries only
the structured 409/no_capacity response with identical request and affinity
IDs, while younger CLIs make no allocation requests. Queue ownership records the
process birth identity so a dead or PID-reused waiter cannot block successors.
The queue ticket is released immediately after allocation, not after the entire
Oracle response, preserving four-way concurrency. Existing allocated sessions
bypass the queue and reattach directly.
The isolated authoritative artifacts are:
~/.oracle-round-robin/sessions/{slug}/output.log
~/.oracle-round-robin/sessions/{slug}/meta.json
Read the full output.log. Confirm meta.json contains protocol v2 routing and
assignedProfileId equal to profile-a, profile-b, profile-a-2, or
profile-b-2. The runner prints the assigned slot and receipt path after success.
Then copy both receipts into the pre-approved workspace notes directory:
cp ~/.oracle-round-robin/sessions/{slug}/output.log \
.notes/oracle/{slug}/oracle-output.log
cp ~/.oracle-round-robin/sessions/{slug}/meta.json \
.notes/oracle/{slug}/oracle-meta.json
The isolated client-home copies remain runtime-owned qualification artifacts;
.notes/oracle/{slug}/ is the durable user-facing record.
Do not infer routing from expectations alone. Compare durable
assignedProfileId and allocationId receipts. The persistent cursor advances
across available slots; busy slots are skipped and may be reused only after their
prior lease becomes terminal.
Follow the owning SKILL.md: lead with Oracle's recommendations, convert them into
implementation-ready work packages, preserve exact file/function/test targets,
and do not continue independently while Oracle is still processing.
A dry run validates the local public invocation without submitting a prompt:
run_round_robin.sh \
--slug "three-word-test" \
--prompt-file /path/to/prompt.md \
--bundle /path/to/bundle.txt \
--dry-run
Dry run is not live qualification and does not prove account state. Use --check
for topology health and the existing qualification receipt for live proof.
| Failure | Action |
|---|---|
| Build/hash mismatch | Stop; rebuild/redeploy/requalify as a new immutable release |
| Green unhealthy or worker unavailable | Stop for unhealthy/login/cooldown states; ordinary no_capacity waits automatically |
| Login required | Restore the affected isolated staging worker from its already-qualified account state or ask for login only when no approved state exists |
| Local tunnel allocation fails | Retry invocation-private dynamic ports; never kill by name or wildcard |
| Existing slug lock | Inspect ~/.oracle-round-robin/locks/{slug}.lock/pid; do not delete blindly |
| Transport loss after submit | Reattach using persisted protocol-v2 routing; never resubmit on another profile |
| Production identity changed | Stop and report a critical isolation violation |
| Oracle still processing | Keep waiting and read the isolated session output.log when complete |
The pinned release was qualified with:
profile-a, profile-b,
profile-a-2, and profile-b-2, subject to the persisted cursor;404 unsupported_protocol;challenge-platform bot-management script classified as not blocked;00000053 reused profile-b-2 only after
its earlier 00000051 lease completed, proving automatic capacity waiting;# Round-Robin Transport (default for all Oracle text consults)
This is the default execution transport for every consult the `oracle` skill
and its composing skills run. It replaces only the transport; every contract
in the owning `SKILL.md` — slug selection, packx bundling, Prior-State Ledger,
Forward Progress Gate, prompt quality, text-only output boundary, waiting
rules, summarization, and commit rules — still applies.
Consults run through the qualified four-slot, dual-account green service on
tv. Each account has two isolated Chrome workers, allowing four concurrent
consults without sharing a browser profile. Independent local CLIs join one
crash-recoverable FIFO admission queue; only its oldest live waiter probes for
capacity, and a fifth or later caller waits until a slot opens. The server
remains authoritative for one run per worker, two per account family, and
four total.
Do **not** call `mcp__oracle__consult` on this path — that process uses the
production `~/.oracle/config.json`. Invoke the qualified runner below, which
opens a temporary SSH tunnel to green staging and runs the matching
protocol-v2 CLI with an isolated client home. The direct MCP browser consult
is the fallback only when this pool's preflight fails terminally.
## Pinned Qualified Topology
Treat these values as a single immutable qualification set:
| Role | Value |
| --- | --- |
| SSH target | `tv` as the existing `johnlindquist` GUI account |
| Green service | `127.0.0.1:19474` on `tv` |
| LaunchAgent | `com.steipete.oracle.staging.dual-profile.green` |
| Green home | `~/.oracle-staging/dual-profile-green` on `tv` |
| Chrome workers | account A: `profile-a` on `19222`, `profile-a-2` on `19224`; account B: `profile-b` on `19223`, `profile-b-2` on `19225` |
| Qualified build | `4a5f05a1d46857396cda46dab5913f7d57c303d8467167404a5b3e9c0d227c7a` |
| Matching local worktree | `~/dev/oracle-wt/dual-profile-isolation-scaffold` |
| Temporary local forward | invocation-private dynamic loopback port -> `tv:127.0.0.1:19474` |
| Isolated client home | `~/.oracle-round-robin` via `ORACLE_HOME_DIR` |
| Production read-only guard | `tv:7333`; PID and start identity must not change |
The runner reads the green token over authenticated SSH into process memory only.
It never prints or writes the token locally. It compares local CLI, protocol-v2
client, and browser-navigation hashes against the exact green release before use.
If any pinned value changes, stop. Requalify the new release and update this
skill, runner, and receipt together. Never silently follow `latest`, reuse
production config, or downgrade the build check.
## Non-Negotiable Safety Rules
- Production Oracle is read-only and must not be restarted, edited, or routed.
- Never edit `~/.oracle/config.json` for this workflow.
- Never copy production cookies, Chrome state, tokens, sessions, or profile data.
- Never pass `--remote-profile`. Omitting explicit profile selection is what
activates persistent server-side round robin.
- Permit at most one active run per isolated worker, two per explicit account
family, and four total. Distinct slugs join the stable service-level local FIFO;
the oldest live waiter alone probes allocation capacity. A fifth or later caller
must keep waiting with the same allocation identity until a slot opens; do not
report ordinary capacity exhaustion as a blocker.
- Never bypass a red health, build-hash, local-client/navigation-hash, v1-disabled,
worker, lock, tunnel-owner, or production-identity check.
- Never use broad `pkill`, `killall`, wildcard cleanup, or recursive deletion.
The runner terminates only its verified SSH tunnel PID.
- Never use API mode. Use browser mode, ChatGPT Pro, and Extended thinking.
- Do not add ad hoc host, port, token, or profile overrides.
- Do not start another prompt-bearing qualification merely to test this skill.
All four workers, four-way concurrency, attachment handling, and queued fifth
caller behavior are already qualified.
- Do not commit unless the user explicitly says `commit`.
## Pipeline
### 1. Preflight the qualified pool
```bash
~/.agents/skills/oracle/scripts/run_round_robin.sh --check
```
Stop on any failure. A successful check proves:
- the exact green LaunchAgent is loaded;
- the token file is mode `0600`;
- green reports the pinned build, protocol v2, pooled mode, capacity four, and
four healthy workers; active workers may be busy while ordinary calls proceed;
- health polling has one bounded overall deadline (60 seconds by default) and
reports its last safe validation failure instead of silently retrying for hours;
- local protocol-v2 CLI/client files match the deployed release;
- a temporary loopback SSH tunnel can be established;
- production still has a stable listener identity.
### 2. Build the PackX bundle
Use the owning `SKILL.md` preview and build contract:
```bash
mkdir -p ".notes/oracle/{slug}"
packx --preview [filters] -x "**/CLAUDE.md"
packx --limit 900k [filters] -x "**/CLAUDE.md" \
-f markdown --no-interactive --stdout \
> .notes/oracle/{slug}/bundle.txt
test -s .notes/oracle/{slug}/bundle.txt
```
Never include `CLAUDE.md`; prefer `AGENTS.md`. Add `--strip-comments --minify`
when preview exceeds 200 files. For broad planning/review, attempt richer context
when the bundle is below 250k.
### 3. Write the prompt locally
Write the complete prompt to:
```text
.notes/oracle/{slug}/prompt.md
```
Follow the full `SKILL.md` Prompt Contract. Include the slug header,
project briefing, goal, Prior-State Ledger, Forward Progress Gate, evidence,
bundle map, requested deliverable, the maximum-actionable-batch demand,
repository rules, and this output boundary:
```text
Return your answer as text in this response only. Do not create, attach, export,
or offer any downloadable file. Do not create local project artifacts yourself.
The local agent will write any needed files, plans, notes, goals, commits, or
verification logs using local tools.
```
### 4. Run one automatic round-robin consult
```bash
~/.agents/skills/oracle/scripts/run_round_robin.sh \
--slug "{slug}" \
--prompt-file "$PWD/.notes/oracle/{slug}/prompt.md" \
--bundle "$PWD/.notes/oracle/{slug}/bundle.txt"
```
Add each screenshot, PDF, compact evidence supplement, or other artifact with a
separate `--file /absolute/path`.
The runner always supplies:
```text
engine: browser
model: gpt-5.6-pro
browser thinking: extended
browser attachments: always
remote profile: omitted (automatic round robin)
```
The service atomically persists allocation before upload or submission. Once a
run receives a slot, retries and reattachment remain sticky to that slot; there
is no post-assignment account failover. Fresh local invocations use a stable
service-level queue beneath `~/.oracle-round-robin/admission`; the queue namespace
never contains the dynamic SSH port or slug. Its oldest live waiter retries only
the structured `409/no_capacity` response with identical request and affinity
IDs, while younger CLIs make no allocation requests. Queue ownership records the
process birth identity so a dead or PID-reused waiter cannot block successors.
The queue ticket is released immediately after allocation, not after the entire
Oracle response, preserving four-way concurrency. Existing allocated sessions
bypass the queue and reattach directly.
### 5. Read and verify the receipt
The isolated authoritative artifacts are:
```text
~/.oracle-round-robin/sessions/{slug}/output.log
~/.oracle-round-robin/sessions/{slug}/meta.json
```
Read the full `output.log`. Confirm `meta.json` contains protocol v2 routing and
`assignedProfileId` equal to `profile-a`, `profile-b`, `profile-a-2`, or
`profile-b-2`. The runner prints the assigned slot and receipt path after success.
Then copy both receipts into the pre-approved workspace notes directory:
```bash
cp ~/.oracle-round-robin/sessions/{slug}/output.log \
.notes/oracle/{slug}/oracle-output.log
cp ~/.oracle-round-robin/sessions/{slug}/meta.json \
.notes/oracle/{slug}/oracle-meta.json
```
The isolated client-home copies remain runtime-owned qualification artifacts;
`.notes/oracle/{slug}/` is the durable user-facing record.
Do not infer routing from expectations alone. Compare durable
`assignedProfileId` and `allocationId` receipts. The persistent cursor advances
across available slots; busy slots are skipped and may be reused only after their
prior lease becomes terminal.
### 6. Summarize Oracle's answer
Follow the owning `SKILL.md`: lead with Oracle's recommendations, convert them into
implementation-ready work packages, preserve exact file/function/test targets,
and do not continue independently while Oracle is still processing.
## Dry-Run Boundary Test
A dry run validates the local public invocation without submitting a prompt:
```bash
run_round_robin.sh \
--slug "three-word-test" \
--prompt-file /path/to/prompt.md \
--bundle /path/to/bundle.txt \
--dry-run
```
Dry run is not live qualification and does not prove account state. Use `--check`
for topology health and the existing qualification receipt for live proof.
## Failure Recovery
| Failure | Action |
| --- | --- |
| Build/hash mismatch | Stop; rebuild/redeploy/requalify as a new immutable release |
| Green unhealthy or worker unavailable | Stop for unhealthy/login/cooldown states; ordinary `no_capacity` waits automatically |
| Login required | Restore the affected isolated staging worker from its already-qualified account state or ask for login only when no approved state exists |
| Local tunnel allocation fails | Retry invocation-private dynamic ports; never kill by name or wildcard |
| Existing slug lock | Inspect `~/.oracle-round-robin/locks/{slug}.lock/pid`; do not delete blindly |
| Transport loss after submit | Reattach using persisted protocol-v2 routing; never resubmit on another profile |
| Production identity changed | Stop and report a critical isolation violation |
| Oracle still processing | Keep waiting and read the isolated session `output.log` when complete |
## Qualification Summary
The pinned release was qualified with:
- healthy no-submit readiness on all four persistent workers;
- deterministic cyclic automatic allocation across `profile-a`, `profile-b`,
`profile-a-2`, and `profile-b-2`, subject to the persisted cursor;
- idempotent allocation replay with sticky identity;
- service restarts preserving profile-instance identities;
- protocol-v1 GET and POST returning `404 unsupported_protocol`;
- normal signed-in pages on both profiles with a ready app shell and the
`challenge-platform` bot-management script classified as **not blocked**;
- deterministic tests preserving true interstitial detection and a 12-second
hydration grace for script-only weak evidence;
- one attachment-bearing Pro Extended response from every worker;
- four simultaneous Pro Extended responses, one per worker;
- a five-caller run where allocation `00000053` reused `profile-b-2` only after
its earlier `00000051` lease completed, proving automatic capacity waiting;
- terminal sticky reattachment semantics preserved without resubmission;
- zero active runs after completion;
- no green process opening protected production paths;
- production listener PID/start identity unchanged throughout qualification.
See [round-robin-receipt.md](round-robin-receipt.md).