Skip to content

akiiwa-games/AgentCompass / skills/agent-compass

agent-compass

Flagged

Choose owner, model and effort, outbound authorization, advisor use, and continuation for delegated work. Reads local usage and effective account policy, profiles the task with the configured System-One scorer, then allocates a compatible worker. Use for independent worker or advisor work; ordinary local execution needs no routing.

FileKindSize
SKILL.mdskill md5.5 KB
agents/openai.yamlconfig427 B
calibration/README.mdmarkdown55.2 KB
calibration/arena_capture.pyscript14.0 KB
calibration/community.pyscript25.2 KB
calibration/five_axis.pyscript196.4 KB
calibration/measurements.pyscript68.4 KB
calibration/refresh.pyscript48.6 KB
calibration/series.pyscript10.2 KB
calibration/sources.pyscript24.1 KB
calibration/tiers.pyscript14.6 KB
grok-bot/.gitignoreother47 B
grok-bot/dependency_patch.pyscript4.5 KB
grok-bot/install_cli.pyscript3.6 KB
grok-bot/test-recovery.mjsscript8.6 KB
grok-bot/test_install_cli.pyscript4.1 KB
grok-bot/upstream.jsonconfig3.4 KB
references/accounts.jsonconfig155.9 KB
references/classifier-cases.jsonconfig21.5 KB
references/dispatch-lifecycle.mdmarkdown28.9 KB
references/dispatch-rules.mdmarkdown11.3 KB
references/effort-matching.mdmarkdown5.1 KB
references/fast-modes.mdmarkdown3.5 KB
references/five-axis-scores.jsonconfig3.1 MB
references/gemini-decisions-api.mdmarkdown2.9 KB
references/grok-bot.mdmarkdown13.0 KB
references/herdr.mdmarkdown5.1 KB
references/jev-api.mdmarkdown1.6 KB
references/level-3-conversion.jsonconfig2.4 KB
references/model-capabilities.jsonconfig3.6 KB
references/model-capabilities.mdmarkdown14.6 KB
references/parent-address-gate.mdmarkdown10.1 KB
references/plan-templates.jsonconfig13.2 KB
references/provider-discovery.mdmarkdown11.5 KB
references/provider-usage.mdmarkdown4.1 KB
references/public-data.jsonconfig816 B
references/public-measurements.jsonconfig1.3 MB
references/roll-reference.mdmarkdown26.7 KB
references/router-internals.mdmarkdown93.7 KB
references/task-classifier.mdmarkdown6.1 KB
references/user-scores.jsonconfig6.8 KB
references/work-kinds.mdmarkdown4.7 KB
references/worker-communication.mdmarkdown2.1 KB
scripts/account_fleet.pyscript32.9 KB
scripts/account_state.pyscript22.2 KB
scripts/accounts_override.pyscript14.8 KB
scripts/allocator.pyscript19.8 KB
scripts/antigravity_plan.pyscript18.7 KB
scripts/antigravity_telemetry.pyscript5.1 KB
scripts/auto_bundles.pyscript31.3 KB
scripts/axis_scores.pyscript40.3 KB
scripts/caller_input.pyscript3.0 KB
scripts/candidate_eval.pyscript54.0 KB
scripts/candidate_ranking.pyscript9.5 KB
scripts/capability_catalog.pyscript8.0 KB
scripts/check_router_contract.pyscript2.8 KB
scripts/conftest.pyscript2.5 KB
scripts/cwd_policy.pyscript1.5 KB
scripts/data_age.pyscript1.5 KB
scripts/decision_ledger.pyscript18.9 KB
scripts/demo_plan.pyscript6.3 KB
scripts/dispatch_fallback.pyscript40.3 KB
scripts/dispatch_flow.pyscript58.7 KB
scripts/dispatch_ground_truth.pyscript43.5 KB
scripts/dispatch_registry.pyscript113.7 KB
scripts/entry.pyscript1.7 KB
scripts/env_vars.pyscript580 B
scripts/fast_modes.pyscript2.5 KB
scripts/fixtures/grok-api-responses.jsonconfig907 B
scripts/fixtures/reference-accounts.jsonconfig26.9 KB
scripts/grok_bot_paths.pyscript1005 B
scripts/host_herdr.pyscript16.8 KB
scripts/host_placement.pyscript9.4 KB
scripts/host_policy.pyscript10.1 KB
scripts/launch_failures.pyscript5.9 KB
scripts/launch_values.pyscript12.3 KB
scripts/ledger_snapshot.pyscript11.1 KB
scripts/live_models.pyscript21.1 KB
scripts/model_latch.pyscript7.6 KB
scripts/model_resolution.pyscript18.0 KB
scripts/override_store.pyscript2.2 KB
scripts/plan_state_residue.pyscript5.0 KB
scripts/provider_inventory.pyscript128.2 KB
scripts/provider_retry.pyscript34.6 KB
scripts/public_data.pyscript59.2 KB
scripts/quota_economy.pyscript38.0 KB
scripts/quota_exhaustion.pyscript5.9 KB
scripts/quota_overrides.pyscript25.6 KB
scripts/quota_pools.pyscript29.8 KB
scripts/reference_provenance.pyscript32.3 KB
scripts/released_names.pyscript3.8 KB
scripts/roll.pyscript106.3 KB
scripts/route_judge.pyscript83.4 KB
scripts/route_simulation.pyscript26.3 KB
scripts/router_test_support.pyscript6.7 KB
scripts/run_grok_bot.pyscript18.8 KB
scripts/scorer_client.pyscript55.2 KB
scripts/stage_help.pyscript5.8 KB
scripts/state_upgrade.pyscript24.0 KB
scripts/subscription_cli.pyscript3.6 KB
scripts/task_intake.pyscript33.6 KB
scripts/test_account_identity.pyscript7.1 KB
scripts/test_account_state.pyscript63.3 KB
scripts/test_accounts_override.pyscript30.1 KB
scripts/test_allocator.pyscript94.2 KB
scripts/test_antigravity_plan.pyscript13.2 KB
scripts/test_applicable_quota.pyscript9.1 KB
scripts/test_auto_bundles.pyscript10.8 KB
scripts/test_billing_routing_policy.pyscript9.9 KB
scripts/test_cadence_count.pyscript32.2 KB
scripts/test_calibration_units.pyscript27.0 KB
scripts/test_capability_catalog.pyscript5.0 KB
scripts/test_decision_ledger.pyscript8.5 KB
scripts/test_demo_plan.pyscript3.4 KB
scripts/test_derived_state.pyscript21.6 KB
scripts/test_dispatch.pyscript322.3 KB
scripts/test_dispatch_answers.pyscript14.8 KB
scripts/test_dispatch_fallback.pyscript53.2 KB
scripts/test_entry.pyscript1.6 KB
scripts/test_fast_modes.pyscript9.9 KB
scripts/test_five_axis.pyscript290.1 KB
scripts/test_five_axis_economy.pyscript105.0 KB
scripts/test_fleet_parity.pyscript15.6 KB
scripts/test_grok_bot.pyscript47.7 KB
scripts/test_ground_truth_recording.pyscript68.8 KB
scripts/test_herdr.pyscript14.1 KB
scripts/test_host_policy.pyscript24.6 KB
scripts/test_launch_values.pyscript8.0 KB
scripts/test_metered_usd.pyscript60.4 KB
scripts/test_model_resolution.pyscript9.2 KB
scripts/test_named_route_facts.pyscript28.6 KB
scripts/test_native_hosts.pyscript6.0 KB
scripts/test_new_user_fleet.pyscript3.3 KB
scripts/test_no_hardcode_classification.pyscript75.1 KB
scripts/test_no_legacy_scoring.pyscript6.5 KB
scripts/test_override_store.pyscript2.3 KB
scripts/test_plan_says_why.pyscript44.9 KB
scripts/test_provider_inventory.pyscript83.2 KB
scripts/test_provider_names.pyscript126.0 KB
scripts/test_provider_pools.pyscript14.2 KB
scripts/test_public_data.pyscript93.5 KB
scripts/test_quota_exhaustion.pyscript5.6 KB
scripts/test_rate_limit_windows.pyscript6.3 KB
scripts/test_record_says_why.pyscript26.5 KB
scripts/test_reference_provenance.pyscript16.7 KB
scripts/test_refresh_entry.pyscript110.7 KB
scripts/test_released_names.pyscript4.1 KB
scripts/test_reset_priority.pyscript4.8 KB
scripts/test_roll_answers.pyscript44.7 KB
scripts/test_roll_notifications.pyscript10.4 KB
scripts/test_route_judge.pyscript99.8 KB
scripts/test_route_simulation.pyscript7.0 KB
scripts/test_routing_parity.pyscript32.3 KB
scripts/test_routing_review.pyscript25.1 KB
scripts/test_setup_discovery_parity.pyscript9.5 KB
scripts/test_stage_help.pyscript2.0 KB
scripts/test_state_upgrade.pyscript13.8 KB
scripts/test_turn_refusal.pyscript16.7 KB
scripts/test_usage_cache.pyscript4.9 KB
scripts/test_usage_collector.pyscript21.4 KB
scripts/test_usage_core_claude_accounts.pyscript1.8 KB
scripts/test_usage_core_grok_cli_billing.pyscript15.6 KB
scripts/test_usage_core_magpie.pyscript5.4 KB
scripts/test_usage_core_magpie_pool.pyscript10.8 KB
scripts/test_usage_core_safety.pyscript24.4 KB
scripts/test_user_scores.pyscript102.3 KB
scripts/test_venice_usage.pyscript1.3 KB
scripts/test_window_scope.pyscript5.5 KB
scripts/turn_refusal.pyscript10.7 KB
scripts/usage_cache.pyscript4.7 KB
scripts/usage_collector.pyscript7.4 KB
scripts/usage_core.pyscript142.0 KB
scripts/usage_magpie.pyscript10.6 KB
scripts/usage_reading.pyscript17.1 KB
scripts/user_scores.pyscript72.8 KB
scripts/venice_usage.pyscript2.6 KB
scripts/window_scope.pyscript3.2 KB
scripts/worker_context.pyscript8.9 KB
scripts/worker_sessions.pyscript10.9 KB

references/roll-reference.md

View on GitHub
# roll reference

Full mechanics behind `roll`; the SKILL.md default path needs none of this unless a result says otherwise.

Herdr core (`hc`) is a host, not a quota account. It detects the actual `HC_TERMINAL_ID` and launches an owned child terminal. See [Herdr setup, capabilities and return paths](herdr.md) before first use. Cindy's shell exposes no supported parent mailbox, so raw roll there is refused; its plugin lives in the separate `cindy-agentcompass-plugin` repository.

Never manually choose between Paseo `create_agent`, Claude `Agent`, Codex `spawn_agent`, Antigravity `invoke_subagent`, `run_dot_task.py`, or raw CLI. Pass the task inline, from stdin, or as a Markdown file; `--hours <n>` is optional (without it the classifier estimates hours in the same call; the source and confidence are reported under `assumptions`):

```bash
agentcompass roll --task "<text>"          # inline
agentcompass roll --task - < task.md       # stdin, any length
agentcompass roll --brief task.md          # a file
```

`--task` and `--brief` print the same short result: `status`, `next_action`, `worker`, `reason`, pointers (`next_argv`, `worker_output`, `worker_prompt_file`) and `details`, the path of the full result (also saved for every call). `--verbose` prints the full result instead. `agentcompass roll -h` lists only the options of this command; in a source checkout without an install the command is `python -X utf8 <checkout>/agentcompass roll ...` (same arguments).

`next_argv` and `continuation_argv` are ready-to-run commands (an argv list, so a path with spaces needs no quoting) that go through the same public entry: `agentcompass launch ...` for a Paseo dispatch, `agentcompass dot status ...`, `agentcompass grok-bot status ...`, `agentcompass chatgpt-web --prompt ... --out ...`. Run them as given; never swap in a script path.

`roll` automatically detects the caller's host session (`PASEO_AGENT_ID`, Orca's `ORCA_AGENT_SESSION_ID` / `ORCA_TERMINAL_HANDLE`, `ANTIGRAVITY_CONVERSATION_ID`, `CLAUDE_SESSION_ID` / `CLAUDECODE`, `CODEX_THREAD_ID`, `PI_SESSION_ID`, `OPENCODE_SESSION_ID`), classifies the brief, allocates and records the worker, and chooses the best dispatch surface (`paseo`, `dot`, `cli`, `chatgpt-web`, `native`, or `self`). Every dispatch requires a real addressable parent session ID, host, and message address; missing information stops dispatch before classification or launch (`--dry-run` diagnostics remain available).

A Paseo single-use launch claim or a notifier marked `watching` does not confirm that a worker was created. Until a validated host observation binds the worker identity to the dispatch, roll returns `pending` with explicit `next_argv`. Run that command to observe the same dispatch; do not roll again or repeat create. Until then Paseo's `get_agent_status` answers "not found", which is not a failure. After observation confirms the worker, the existing launch/completion notification behavior applies. If Paseo confirms no worker was created, the dispatch ends `create_failed` and `cause` names the fixed failure class and any structured error code (`host_creation_failed:<class>[:<code>]`). Automatic cooldown (`launch_failures`) and fallback (`dispatch_fallback.py`) require positive structured evidence that a create refusal belongs to the candidate (provider, account, or model); a request-scoped (`request_invalid`) or unclassified (`unknown`) create refusal stops the dispatch immediately (`caller_action: "check_error"`) with no cooldown and no candidate walk. Candidate-attributed create refusals, bundles refused at prepare, workers that ended in error, stuck provider retries the bridge stopped, or turns whose provider failed are retried on the same bundle after its backoff when the classifier scoped it `transient` and `--can-wait-hours` allows the wait (nothing blocks meanwhile: the retry is scheduled, `status: pending` with `retry_at`, and the failed attempt's watcher or the next observation of the dispatch starts it once due; the brief counts as dispatched until the retry runs or, if nothing started it within `--can-wait-hours` of the failure, is retired as `retry_expired`; `dispatch --dispatch-action release` on the dispatch cancels a scheduled retry), and otherwise relaunched on the next candidate of a fresh allocation with every failed bundle of the dispatch unavailable. Each attempt is its own registry row linked by `attempt_of` to the dispatch the parent holds; observing that dispatch follows the current attempt; the parent gets one notification when the dispatch reaches a final state, listing the attempts, and `status: blocked`, `cause: no_candidate_left` when nothing is left. A model the owner named (`--model`) is never switched: it is retried only on a transient failure whose backoff fits `--can-wait-hours`, and otherwise the parent is told (`owner_named_model_failed`). `task_input` and worker-own errors (`none`) are not relaunched and are reported as before. `AGENTCOMPASS_ROLL_FALLBACK=off` restores the old behaviour, where `next_action` says rolling again is safe. See [the dispatch lifecycle](dispatch-lifecycle.md) for the states, the one-writer-per-`--workspace` rule (`status: blocked`, `blocked_by`, `--access`), the `warnings` a roll without `--workspace` gets about other writers in its directory, and `--new-worker`.

Selection and launch preflight both check the chosen model's applicable windows on its actual bound quota source. A fresh exhausted five-hour window prevents an immediate dispatch even when weekly capacity remains and the short window has no pricing specification. Explicit `draws` win; otherwise a window's scope is data only ([`window_scope.py`](../scripts/window_scope.py)): the account or plan spec's `windows.<id>.models` (tags matched as whole tokens of the model id) or `models_except`, and a `models` list the provider reports on the reading. A window no source scopes binds every model, so an unknown allowance can stop a launch but is never skipped; no window id or model name is special-cased in code. The Router Gate decides from the same rules (`quota_pools.launch_blockers` on `usage_reading.usage_snapshot`). No capacity or burn rate is invented for an observation-only limit. Fresh recovery or an available alternative account can permit dispatch; missing/stale data retains the existing uncertainty policy rather than becoming a blanket denial.

Do exactly what the short result's `next_action` says. A result that is not a launch names the fact that decided it and a way out that works for that fact, in `reason`, `cause`, `next_action`, `warnings` and `assumptions`:
- `blocked` with nothing startable names the candidate that only its own quota holds back, the window and the hours (`route.reason` starts with it; `next_action` says wait, or do the task yourself, or ask the user); with a chain owner that cannot continue it names what blocks the owner and for how long, and the two ways out (wait, or `--new-worker`); when the wait is longer than `--can-wait-hours` it names the window that sets it and a flag value that would allow it (the wait rounded up to a tenth of an hour, so rolling again with it is not asked again); a deferral names the account's window that sets the wait. When nothing but the user's own settings on this machine keeps the closest candidates out, `next_action` names each (the account outside `allowed_accounts` of host-policy.json, the account/model unchecked in model management, or the account's `cwd_regex` with the directory it was matched against), says they are the user's choice and not a fault, and gives the way out that works: a named route (`--provider --account --model --basis`) reaches past `allowed_accounts` and the checkbox, a `cwd_regex` holds for a named route too. It never says to change the user's settings. `route.reason` names them the same way. Every hour count in these answers is rounded up the same way, so waiting that long finds the window reset: the plan fields `decision.start_after_hours`, `decision.wait_hours`, `decision.wait_for.hours` and `decision.next_reset.hours` are rounded up to a tenth (`allocator.advised_hours`), not to the nearest tenth, and a chain owner that never resumes has `wait_hours: null`.
- A launch Paseo refused before any worker existed (`sdk_setup_failed`, `host_connection_failed`, `bridge_unavailable`, `create_send_window_elapsed`, `parent_agent_not_found`) is `status: error`, `cause` is the code, and `next_action` says what failed and what to do (the bridge's `setupHint` included). For `host_connection_failed` the advice follows the bridge's `condition` (`refused`, `timeout`, `unreachable`, `authentication`, `credential_unreadable`, `rejected`: a daemon that is running and refuses the credential or the handshake is not started again), from the one table `dispatch_flow.HOST_CONDITIONS`; a condition the table does not hold is printed as itself with advice that presumes no cause. No worker exists, so there is nothing to collect.
- `pending` names the error in `cause` when the create or the resume is not simply being carried out by the host (`host_timeout`, `invalid_host_response`, `create_outcome_uncertain_reconcile_by_label`, `resume_outcome_uncertain_reconcile_by_agent`, an observation error, and `host_request_failed`, which the bridge answers with `sent: true` because the request reached the daemon: `cause` is `host_request_failed:<condition>` and the text carries the condition's facts). It stays `pending`: a worker may exist, so only `next_argv` is safe, never another roll.
- A `--resume` that is refused says why and what to do about *that* reason: a permission is answered, a running turn is waited for, an error is read, a daemon that is down is started and the same `--resume` retried, a daemon that refuses the credential is not started again; a fresh worker is offered only where it helps. What to do about each state of a worker is written once (`dispatch_registry.WORKER_STATES`). A fault of the request or of the local data is said to be that, not the worker's.
- A CLI worker in place of a Paseo worker comes with a `warnings` entry naming the condition that decided it (the parent's host, no launcher for the provider, no Paseo parent, the daemon not reachable).
- A flag that did not take effect is said in `warnings`: `--fast` not applied (and why), `--file`/`--apply-to` on a route that is not Dot, `--basis` without a named route, `--trigger`/`--specialty`/`--reason-category`/`--accounts` on a roll that records no route (with `--trigger workflow`: no record authorizing a Workflow was written; that needs `record`), and any flag `roll` does not read at all (`agentcompass roll -h` lists what it reads).
- A Dot runner that launched nothing is `status: error` with `cause: dot_runner_exit_<code>`, the runner's exit code, what the runner means by it (its own documented outcomes), and the pointer to the `details` file where its output is kept. Nothing of the runner's stderr is printed in the answer: it can carry what the service answered, and no filter tells safe lines from unsafe ones. It exits 1, as does every launch that Paseo refused before any worker existed or that was sent and failed (`status: error`). A roll that ends `blocked` exits 2: refused before any launch (a gate or registry refusal), a `--resume` refused by the registry or the host, a dispatch that ended before it was sent, or no candidate left. A `pending` result exits 0.
- A failure outside the result path (a missing `--brief` file, a state error) prints `status: error`, `cause` (the path or the error the system gave, never a host's text) and `next_action`, and exits 1.

The cases below describe the full result (`details`, or `--verbose`), where `launched`, `dispatch_mode` and `caller_action` give the same answer in detail:
- **`launched: true` (`caller_action: "already_launched_do_not_respawn"`)**: `roll` has **already launched** the worker (`dispatch_mode: "paseo"`, `"cli"`, or `"dot"`). **Do NOT call `create_agent`, `Agent`, `spawn_agent`, or `invoke_subagent` again.** Follow `next`: Paseo registers a bounded local notification watcher (PID, deadline and durable state in `worker.completion_notification`) that sends the parent one finish/error/permission notice containing the worker's final reply. When `completion_notification.status` is `watching`, finish any independent work and end your turn to wait for that notification; do not sleep or poll (`paseo ls`, `get_agent_status`, or result files) in a shell command. A notice the watcher did not send is delivered once on the next reservation read, roll, or gate call. If no active watcher is confirmed, `worker.continuation_argv` observes the same dispatch. CLI has no automatic callback: the caller must watch `worker.output` / `worker.stderr` and own the process until exit or cancellation. For Dot use `continuation_argv`.
- **`launched: false` and `dispatch_mode: "self"` (`caller_action: "execute_self"`)**: Execute the task directly in your current session; do not spawn a subagent.
- **`status: "blocked"` and `caller_action: "wait_for_reset"` (`start_after_hours`)**: Returned only when the caller passed `--can-wait-hours <h>` and a stronger model whose short quota window resets within `h` hours beat all ready-now substitutes after waiting cost. Nothing was launched; `next_action` names the account's window that sets the wait. Wait `start_after_hours` (rounded up to a tenth of an hour) for the quota window reset, then run `roll` again (or re-run without `--can-wait-hours` to launch the best ready-now substitute immediately). Without `--can-wait-hours`, `roll` never defers and always launches the best model that can start now.
- **`status: "batch"`** (several `--brief`): `results` holds one result per brief, in order, each with its own `status` and `next_action`. Briefs are classified concurrently, then routed and launched one at a time so each allocation sees the reservations before it. Per-brief flags (`--hours`, `--can-wait-hours`, `--task-id`, `--title`, `--local-only`, `--keep-whole`, `--file`, model overrides) are refused; roll such a brief on its own. A brief that is refused or fails on its own (`OSError`, `ValueError`, `RuntimeError`) gets `status: error` with `error_type` and `cause` (as a failed run prints them: a `RuntimeError` names only its class) and the batch goes on. Any other error stops it: the briefs before keep their results, the one that raised is `status: error` the same way, and `not_started` lists the briefs after it; the batch still answers `status: batch`, exit 1. An interrupt (Ctrl+C) prints the same shape first (`results` so far, `interrupted`: the brief it stopped in, whose launch is not known, and `not_started`) and then goes on as an interrupt.
- **`launched: false` and `dispatch_mode: "split"` (`caller_action: "roll_each_line"`)**: The classifier read the whole brief and answered `multi_task: true` with a `task_count` (`2`, `3` or `>3`): the brief bundles separate tasks that different workers could do at the same time. Nothing was allocated or launched, and the ledger row (stage `split`) authorizes no launch. The parent stays the coordinator and splits the brief itself: it does the tasks coupled to its conversation, writes one brief per independent task and rolls them together (`--brief a.md --brief b.md`), and starts a task that needs another's result once that result returns. Never hand the tasks to one worker to coordinate. If the brief truly is one assignment, `--keep-whole "<reason>"` sends it to one worker anyway; the ledger keeps the reason and the daily audit lists it.
- **`launched: false` and `status: "scorer_unavailable"` (`caller_action: "parent_autonomous_choice"`)**: All System-One classifiers timed out or failed. Mechanical keyword fallback has been removed so no worker is launched on a keyword guess; the parent session chooses autonomously (`self` or an explicit `--provider <p> --account <a> --model <m> --effort <e> --basis "scorer_unavailable: parent autonomous choice"`).
- **`launched: false` and `dispatch_mode: "native"` (`caller_action: "launch_with_native_host_tool"`)**: Returned when `--parent-host native --parent-id <session-id> --parent-address <inbox-address>` is passed (or when neither Paseo nor a local CLI is available). Pass the **contents** of `worker_prompt_file` to the native host subagent tool using `route.bundle` and preserving the live preamble. Do not switch to Paseo or pass the filename as the prompt.
  - **Orca** (`parent_host: "orca"`, detected from `ORCA_AGENT_SESSION_ID` / `ORCA_TERMINAL_HANDLE`, or `--parent-host orca`): `next` is the `orca orchestration worker-start --spec ... --agent <provider> --model --effort` command for the routed bundle. The parent address is Orca's own mailbox spelling (`orca_session_id:<id>`, or the `structworker_...` handle of a dispatched worker); the worker reports with its injected preamble.
  - **T3 Code** (`parent_host: "t3"`, detected from `T3_MCP_URL` + `T3_MCP_BEARER_TOKEN`, which T3 sets for its Pi provider only, otherwise pass `--parent-host t3` or set `ROUTER_PARENT_HOST=t3`): `next` is the T3 MCP `delegate_task` call (`orchestrator_capabilities` first). T3 addresses the parent thread through the MCP credential and delivers the result itself, so the parent address is the session ID; do not poll `task_status`.

The source brief remains unchanged. The router appends the [worker communication contract](worker-communication.md) and actual parent address to `worker_prompt_file` on every route. `--hours` is optional and positive when given. Follow the returned continuation command for Paseo/Dot; CLI worker PIDs belong to the caller and must be waited for or stopped. The [parent-address gate contract](parent-address-gate.md) describes enforcement and host coverage.

Grok Bot uses the distinct provider/account/model selector `grok-bot` and joins
automatic routing when ready and enabled; no override flags are needed.
Follow [Grok Bot setup and usage](grok-bot.md) for the pinned upstream
CLI and `roll` command. It runs remotely and accepts text; no local file access
or Paseo-native support is implied. The service has independent conservative public
capability priors; its underlying model identity and dollar price remain unknown.
Quota ownership, capacity and local ratings come from effective account configuration.
The channel still excludes local-only, visual, GUI and file-transfer work: the Bot
cannot see images, transfer files, or run on this machine. Shared Grok observations retain their freshness; no separate Bot meter is read. Private material needs outbound authorization.
For uncertain delivery, `launched` is `null` and `caller_action` is
`check_delivery_do_not_resend`: run `continuation_argv`, never submit again.

Optional flags, only when they are facts (`agentcompass roll -h`; internal/diagnostic flags live in `--help-all`):
- `--workspace <dir>`: existing directory this worker writes in and claims exclusively (validated and canonicalized once by core; host IDs such as `wks_...` are not accepted). Automatically implies `local_only` (recording `local_only_reason: "inferred from --workspace <dir>"` in the ledger when `--local-only` is omitted): remote runners are not considered, the answer's `assumptions` says so, and their exclusion in the plan names `--workspace` (`needs.local_only_by`) rather than the parent. An account's `cwd_regex` is matched against `<dir>` (without `--workspace`, against the directory the worker starts in: a `--resume`d worker's own directory, else the parent's directory; a `--resume`d worker whose directory is not known on this machine is refused on an account with a `cwd_regex`, `resume_worker_directory_unknown`; see [router internals](router-internals.md)). When Paseo cannot be read for `<dir>`, `assumptions` says that too: for a writer, that only recorded dispatches were checked; for a reader, that the placement was not verified. One writer per canonical directory is enforced across all hosts (`paseo`, `herdr`, `cli`, `orca`, `t3`, `native`); each host adapter places the worker into `<dir>` (`cwd` + matching Paseo `workspaceId` when verified for that exact `cwd`, Herdr `--cwd`, CLI `cwd`, or native instructions + `workspace` output field) and refuses before launch when the surface cannot place `<dir>`. Read-only vs write access is judged by the System-One classifier (`access: "read-only" | "write"`).
- `--hours <n>`: expected active worker-hours (optional; when omitted, the classifier estimates it). A named route (`--provider/--account/--model`) with no classifier answer launches only with `--hours`, unclassified ([router internals](router-internals.md)).
- `--can-wait-hours <h>`: only when the task is not urgent — how many hours it may wait for a stronger model's quota window to reset. Without it, `roll` always launches the best model that can start now.
- `--local-only "<concrete local dependency>"`: keep the work on this machine when no `--workspace` is given (local git/daemon/pytest/hardware/intranet/credentials).
- `--keep-whole "<reason>"`: send a brief the classifier read as several separate tasks to one worker anyway (recorded as alert `kept_whole`).
- `--new-worker` / `--resume <agent_id>`: force a fresh worker, or resume a specific idle, non-worn, non-gated worker owned by the parent. `--resume` names the worker, and its route is the worker's own: it resumes that worker even if the router would otherwise pick a different bundle (adding a warning naming the router's pick); flags naming another route (`--provider`, `--account`, `--model`, `--effort`) are an error (exit 1), and flags naming its own route add nothing. Fast mode is part of the route: `--fast` on a worker that runs without it is the same error, and on a worker that runs fast it adds nothing. It never starts another worker in the named one's place: it returns a structured `blocked` result (`next_action`) when the worker is unavailable, worn, gated (`turn_refusal.gate_refusal`), lives in a directory other than `--workspace`, is refused by the host, or wrote code when the task is a read-only review ([router internals, Pins](router-internals.md)). `--resume` with `--dry-run` is an error (exit 1, `conflicting_flags`): a named worker's turn is decided by its state in the dispatch registry, which a dry run does not read. Without `--new-worker`, `roll` considers idle, non-worn, non-gated workers of the parent as continuation candidates (via `--resume`, `chain`, `task_id`/`brief_path`, or matching canonical `--workspace`) with the `continuity` term in allocation.
- `--file <path>` (repeatable): files Dot needs; Dot's returned files are applied to `--apply-to` (default: cwd). A local worker does not receive them, and the result's `warnings` says so.
- `--fast`: prefer Codex fast when quota is plentiful or during a pre-reset sprint (public subscription default: `2.5x`; explicit local calibration is retained). It is a preference: when the chosen route runs in its plain mode, `warnings` says `--fast was not applied` and why. An explicit Claude provider/model override plus `--fast` opts into paid usage credits on supported Opus models; automatic quota/reset routing never enables paid Claude fast. See [fast contracts and verification](fast-modes.md).
- The user named the model/effort in this request: add `--provider <p> --account <a> --model <m> --effort <e> --basis "<exact user quote>"`. `--effort` is optional, and `--model <m>:<e>` also works. A named route needs `--provider`, `--account`, `--model` and `--basis`; any of `--provider`, `--account`, `--model` or `--effort` given without the rest is refused in one answer that says what a named route needs, which flags this roll gave and which are missing, and that dropping the route flags lets the router choose. A named route stays on that account or is refused with the reason (an account this machine does not have, or a provider the account does not launch through, is named as such; a `--basis` over 400 characters is refused, not cut). Its `warnings` also say which quota windows binding the named model were not read (no usage snapshot, no fresh reading, or a reading without that window: not read is not exhausted, and the launch goes ahead) and when the model name was read as another row. `--basis` without a named route names nothing and `warnings` says it was ignored. A route named to `roll` is the user's own naming and nothing else: beside route flags, `--constraint user_override` adds nothing, and any other `--constraint` (a project rule such as `hard_constraint` or `dot_closed_loop`) is refused (exit 1) with the way to record it, `record --constraint <that constraint>`, which holds it to this machine's automatic-routing switches. `--constraint` on a roll with no route flags is a flag `roll` does not read: `warnings` says so. Pass any `warnings` in the result on to the user: the short result keeps the first four route warnings and, when there are more, ends `warnings` with how many more `route.warnings` of the details file holds; a `--dry-run` writes no details file, so its short result gives every warning.

Classifier input: the classifier reads the complete task text (never a head/tail view or summary) and the same call returns the hours estimate, the urgency the text itself states, and whether the brief bundles separate tasks (`multi_task`, true/false) with how many (`task_count`: `1`, `2`, `3`, `>3`). Every System-One scorer answers these from the whole text: LLM scorers (`claude_haiku_low`, `codex_terra_low`, `agy_flash_low`, `openai_compatible`) as schema fields and the question APIs (TypeSafe Jev, Google Gemini Decision 1) as a `noul` and a `choice` question. Default scorer priority cascades from lightest/fastest to slowest (`jev` when API key is configured -> `claude_haiku_low` -> `codex_terra_low` -> `agy_flash_low`); `gemini_decision` and `openai_compatible` run only when chosen as the scorer type, and then lead. `--hours` always wins; cost is then computed from hours and real rates/quota. Urgency is reported (compact `assumptions` when high, `details` always) and never changes owner, effort or fast mode; `--fast` or an explicit fast request in the text does. Transport: Claude/Codex scorers use stdin, Jev/Gemini Decision/OpenAI-compatible use HTTP, and the agy scorer sends a short task on its command line and a long one on stdin (stream-json). If all System-One scorers time out or fail, `roll` returns `status: "scorer_unavailable"` (`caller_action: "parent_autonomous_choice"`) rather than guessing from keywords. If no scorer can take the whole text (agy stdin failure with no fallback, HTTP 413), `roll` returns an `error` with the cause instead of cutting the text. The classification is cached 24 h per exact text + scorer identity + rubric/schema; the route (quota, policy, reservations) is always recomputed live.

Edit the brief freely before rolling. Rolling the same task again while its Paseo dispatch is still live returns that dispatch as `pending` with `next_argv` (no second classification, no second launch). When `launched` is false, `next` says why: a user decision, no fitting worker, or neither Paseo nor a CLI for the routed provider (then start it natively with exactly `route.bundle` and the contents of `worker_prompt_file` as its prompt).

reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 322kUpdated Claude CodeCodexVerifiedInstall