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/dispatch-lifecycle.md

View on GitHub
# Dispatch Lifecycle & Reservation Ledger

Every Paseo `roll` keeps a reservation row in `~/.agent-compass/dispatch.sqlite3` (non-Paseo writer rolls with `--workspace <dir>` also record a leased writer claim there; `plan` and `record` only register a decision, which reserves nothing) and appends an audit entry to `~/.agent-compass/router-ledger.jsonl`.

## 1. State Machine

```
prepared ──► launching ──► launched ──► started ──► completed
   │             │             │           │
   │             │             └───────────┴──────► failed | canceled
   │             ├──► create_failed
   │             └──► failed (never sent)
   └──► canceled
any open state ──lease lapses──► expired ──a later observation that the worker is still running──► that active state, with the evidence recorded
any open state ──host already ended, or the watcher exits──► completed | failed | canceled | create_failed
```

| State | Active Reservation? | Lease | Meaning |
| :--- | :---: | :---: | :--- |
| `prepared` | Yes | 5 min | Route bound, nothing sent. |
| `launching` | Yes | 10 min | Single-use claim taken, create sent or being sent; no agent observed yet. |
| `launched` / `started` | Yes | 10 min, renewed by each observation | The host shows the bound agent; `started` once it has run. |
| `completed` | No | Released | The host reports the worker finished. |
| `failed` | No | Released | The worker errored, or the host refused before sending (no parent, no notifier). |
| `create_failed` | No | Released | Paseo created no worker and none can appear later. Candidate-attributed refusals cool down and fall back; request-scoped or unclassified refusals stop immediately as a request error. |
| `canceled` | No | Released | Released before launch, or the host's worker was closed or removed unfinished. |
| `expired` | No | Released | The lease lapsed without a fresh observation. Not an outcome: a launched row stays open for a later observation. That observation restores an active state only when the snapshot shows the worker still running or waiting on permission, and the event records that evidence (`host_still_running`). An idle snapshot does not. |

`roll`, `launch` and `reconcile` observe and settle these; `release` only ever ends what is already over (section 3).

### How a create ends

The bridge's `create` call is cut off after 25 s, and the daemon carries on regardless: it owns the create across socket lifetimes and keeps the outcome in a durable record under the idempotency key (the dispatch ID). While no agent exists, every observation reads that record, so the answer the bridge never received is not lost.

| Daemon's record, no agent exists | Result | Why it is final |
| :--- | :--- | :--- |
| `accepted` ... `prompt_started` | Stays `launching` (`creating: true`), `next_action` says so | The worker can still appear. |
| same, past the create deadline | Stays open, `next_action` says it is overdue, and `release` refuses | The daemon has no cancel, so calling it failed could release a worker about to start. The only way out is restarting the daemon, which settles it (`failed`, outcome unknown). The real records hold no create stuck like this so far (967 agent creates read on 2026-11-07). |
| `failed`, no agent in its record | `create_failed` at once | The run is over and the daemon never reruns a key by itself; only a new request could, and `launching` never sends one. |
| none, before the deadline | Stays `launching` | The request may still be on its way. |
| none, at the deadline | `create_failed` | The bridge refuses to send after the send window (60 s after the claim), so nothing can arrive any more. |
| agent gone (the daemon answers `Previously created agent no longer exists`, not a phase), or `failed` with an agent in its record (its prompt failed), then removed | `canceled`, `next_action` says to check what the worker did before rolling again | Created, then removed before this dispatch observed it. |

The create deadline runs from the claim: 240 s by default, 480 s for `antigravity-resilient` (`CREATE_DEADLINES` in `dispatch_registry.py`), leaving room for the daemon's own provider timeouts. A host that cannot be read settles nothing (`observe_error`).

An outcome-unknown, request-scoped (`request_invalid`) or unclassified (`unknown` with no candidate error code) failure still settles `create_failed`, but cools nothing down in `launch_failures` and triggers no candidate walk, because there is no positive structured evidence against the candidate. Only the process that ended the row records a cooldown, so two settling one row count once.

Known residual risks: a request the daemon has not admitted by the deadline is settled as `create_failed` on the assumption that it can no longer arrive. Its send window closes at 60 s, so that would take a frame delayed by minutes on loopback, which could not be produced in review. If one did arrive, the settled row is not observed again: the worker would run unbound, seen only by the writer rule on a later `roll --workspace`. A tombstone create under the same key would close this and is not done. Separately, a restart in the milliseconds between the daemon admitting a create and starting its run leaves the record at `accepted` for good.

While `launching`, Paseo's `get_agent_status` answers "not found": the agent does not exist yet, and that is not a failure. Do not roll again; run `next_argv`. The worker notification goes out only at an end, and on a watched dispatch that notice already contains the final reply ([worker communication](worker-communication.md)): `finished`, `error`, `creation failed`, which says the brief can be rolled again, or `worker removed before it was observed`. A slow create sends nothing. A record that cannot be read keeps the watcher polling, and its watch limit still ends with a notice.

A resume is judged the same way, with no clock. The notification is `worker unavailable` only when Paseo answers that the worker no longer exists or is archived. Until the worker carries this dispatch's labels its state is the previous turn's, so nothing is sent, and if it cannot be read the watcher keeps polling. A resume that never binds therefore stays silent until `release` stops its watcher or the 7-day watch limit ends it with a notice.

A resume that binds but whose turn never lands holds its lease only until it lapses: only a seen run or a user message after the launch renews it, or recovers it once expired. When the lease lapses the watcher sends one `turn not delivered` notice and keeps watching, so a turn that lands later still reports its finish. A worker this dispatch saw under its own labels and later carrying another dispatch's ends the watch with `superseded by a later dispatch`.

### One writer per workspace directory

`roll --workspace <dir>` validates `<dir>` as an existing directory, canonicalizes it once (`resolve` + `normcase`), and refuses a second writer across any host (`paseo`, `herdr`, `cli`, `orca`, `t3`, `native`): `status: blocked`, `cause: workspace_has_active_writer`, nothing launched. `<dir>` is held by any unsettled writer dispatch recorded against that canonical directory (`prepared`, `launching`, `launched`, `started`, `expired` after Paseo launch, or an active host-claim lease on non-Paseo hosts) and by any router-launched Paseo agent running in `<dir>`, even after its dispatch completed (a worker can be sent a follow-up). A caller session never blocks itself, so a coordinator can roll into its own directory. On Paseo the check is repeated in the transaction that inserts the row, so of two concurrent rolls one wins. On hosts where `roll` does not own worker lifecycle (`orca`, `t3`, `native`), `roll` records a leased writer claim (`PREPARE_LEASE`, 5 min) in `dispatch.sqlite3`; Herdr and CLI record `RUN_LEASE` (10 min, released early on spawn failure or Herdr completion/cleanup). If running Paseo agents cannot be read, the recorded dispatches decide and `assumptions` says so.

Without `--workspace`, parallel dispatches only warn (`same_cwd_warning` in `assumptions` and `warnings`): parallel workers commonly start in one checkout and create their own worktrees. Each host adapter translates `<dir>` in one placement step (`host_placement.py`): Paseo sends `cwd` and attaches `workspaceId` only when Paseo has a verified workspace for that exact `cwd` (refusing before create if Paseo only has an enclosing workspace or cannot place `<dir>`); Herdr passes `--cwd`; CLI passes `cwd`; native hosts express `<dir>` in `next` and `workspace`; remote surfaces (`dot`, `chatgpt-web`, `grok-bot`) refuse directory placement before launch.

A resume stays in its directory too: with `--workspace <dir>`, a compatible Paseo worker living in another directory is not resumed (`worker_workspace_mismatch`) and the dispatch creates a new worker in `<dir>` instead.

Read-only work coexists with a writer. The System-One classifier decides `access` (`read-only` or `write`; `code_audit` is always `read-only`), and `--access read-only|write` overrides it if needed. Titles and task text are never matched in code.

`blocked_by` lists each holder (`dispatch_id`, `state`, `agent_id`, `task_id`, `title`). `next_action` gives the ways out: wait for the current writer to finish and roll again, create a separate worktree for parallel work, or pass `--access read-only` if the brief only reads.

### Repeating a brief

A repeated `roll` of an open brief hands back that dispatch (`pending`, `next_argv`) and starts nothing. `--new-worker` always creates a new dispatch and a new worker, leaving the old one running, subject to the writer rule above.

### Watching

A cooldown is best effort. If its store cannot be written, the dispatch still settles and the failure goes uncounted.

`launch --watch-seconds N` returns the current state (`pending` or `started`) within N seconds: each bridge call is cut at what is left, and it starts no further observation with under 5 s left, so it can return up to 5 s early. Only the first observation can exceed that limit: under 1 s of watch, such as 0, it gets up to 5 s so it still reads the host. `roll` (which passes `watch_seconds=0`) and `launch` on a `prepared` row are the same watch, except that sending a create may take its full 25 s, and the first observation can follow it, so up to about 30 s. `poll-seconds` only spaces the observations.

## 2. In-Flight Quota Deduction

When `allocator.plan()` evaluates an account window from the effective account fleet:
1. Active dispatches (`prepared`, `launching`, `launched` or `started` with `lease_until > now`) whose `at` timestamp is newer than `usage[account].fetched_at` (or where `used_pct` has not yet moved past the dispatch baseline) reserve their `expected_usd` (or `expected_pct`) against remaining window capacity. One worker counts once: the newest open row for its `agent_id`. A row with no `agent_id` still counts on its own.
2. Once the dispatch ends (`completed`, `failed`, `create_failed`, `canceled`) or `usage-cache.json` reflects the spent quota, the reservation is released so quota is never double-counted.
3. The notification watcher runs `dispatch --dispatch-action settle` before every exit (the command `bridge_env` passes as `AGENTCOMPASS_SETTLE_ARGV`). Settle reads that dispatch's receipt under `paseo-notifications/` and writes the terminal state with no further host call. The receipt's reason is the ending: a `superseded by a later dispatch` receipt closes the old row even when its `status` is the next round's `running`. A receipt that is not an ending changes nothing. One finalization applies that receipt first and the local agent JSON only when the receipt has no ending. The first real terminal already stored is kept. Provider-hold, failure-record, and launch-latch effects are flagged separately from that state, and a later settle or reservation read still runs the ones the first writer skipped. If the watcher crashes or is killed before that, the next reservation read — including the gate's read-only read — uses the same rules. The agent JSON counts only when it is this round's: a timestamp older than `launched_at` is ignored, a resume the host has not bound yet still wears the previous round's label and is not canceled by it, and `superseded` is recorded only when this round was already bound and the label names a later dispatch. Permission, and a resume whose turn has not landed, are not endings. A still-running worker is not expired by a read-only read; only the write path lapses a lease. An idle question releases the reservation; when the host then shows that same round `running` or `initializing` with a user message newer than the release, the same row is counted again. The parent does not roll a new dispatch for that reply. That same moment is the parent's one end notice. The watcher message includes the final reply (a long reply is the path of the full text plus a summary) and the continuation verdict. If the watcher exits without a delivery, including when the send window ends at `delivery_failed`, the pending text and its stable message id stay on the receipt. The next settle or reservation read sends that one notice. The row records `sent` only after a delivery, or when the watcher intentionally did not send (the parent continued the worker, the parent can no longer be reached, or the attempt was resumed, canceled, or relaunched). A timeline read that fails is not an empty reply: that read sends nothing and does not record `sent`, and a later read tries again. A parent continuation uses Paseo's `notifyOnFinish`. The registry records that continuation as an event with `kind` `host_followup`; that field, not the reason text, is what counts the parent's notice as the one end notice. A terminal notice already composed but not yet sent is dropped once that continuation is known, so it is not a second AgentCompass notice. The send is the next reservation read, gate read, or settle, not a separate retry process. Which channel applies is [worker communication](worker-communication.md).
4. The hold drops when the row becomes terminal, from the watcher settle or the same disk rules. A `[Worker final report]` in a tool payload does not change the hold. `ROUTER_GATE_BYPASS=1` does not account for one.

## 3. CLI Commands

`roll` prepares, launches and observes the dispatch itself; nothing needs to be marked by hand. These commands exist for inspection and recovery:

```bash
# Where is this dispatch?
agentcompass dispatch --dispatch-action status --dispatch-id <dispatch_id>

# Re-observe the host and update every open dispatch (or one, with --dispatch-id)
agentcompass dispatch --dispatch-action reconcile

# Cancel a dispatch you will not use; its reservation is released
agentcompass dispatch --dispatch-action release --dispatch-id <dispatch_id> --parent-id <your_session_id> --basis "<why>"
```

What an action answers when it did nothing names why, so "nothing to do", "nothing found" and "could not look" differ:

- `reconcile` and `start` answer `observations` (what the host was asked and answered), `not_observed` and `active_reservations`. Each dispatch they were asked about and did not observe is in `not_observed` with its `state` and `why`: `prepared, never launched` (or `expired, never launched`), `already <state>` for one that has ended, `not a Paseo dispatch (<mode>)`, `observation not applied` with `error` the class the registry raised (the row keeps its state), or `could not be observed` with `error` the bridge's code. A `reconcile` with no open Paseo dispatch says so in `note` (it observes Paseo dispatches only), and names the open claims of other hosts (`herdr`, `cli`, a native host), which it does not observe. A host that is down for an open dispatch stays an `observations` entry with its `error`.
- An end notice that could not be sent stays due for the next read; the answer of `reconcile`, `start` or `settle` then carries `end_notices_error`, the error's class.
- `release` answers `released: true` when it ended the dispatch or canceled its scheduled retry; for one that was already over, `released: false` and a `note` with its state.
- `settle` with no ending receipt changes no state and says which in `note`: no receipt, a receipt that could not be read, a file that was read and is not a receipt, a receipt that records no ending, or one whose ending does not count for this dispatch (dated before this launch, or a reason AgentCompass does not read).
- `fallback` answers `unsettled` (the dispatch has not ended; only an attempt that ended in a failure is retried or relaunched) and `disabled` (`AGENTCOMPASS_ROLL_FALLBACK=off`) with one sentence in `meaning`. The watcher reads `action` only.

The exit code of `dispatch` is 1 exactly when the answer's `state` is `failed` or `create_failed`, also for an answer that did nothing (a `release` or a `settle` of a failed dispatch), and 0 otherwise. The watcher runs `settle` and `fallback` and reads their JSON, not the exit code.

`release` observes first, so a create that is over settles and releases. It refuses a live worker, and a create the daemon is still running, because it cancels neither. While Paseo cannot be read it refuses anything sent and not yet settled, since either could be alive; a dispatch never sent needs no host. A worker Paseo reads that does not carry this dispatch's labels is different: that answer will not change, so `release` waits only for the lease to lapse and its refusal gives the time. A release that ends a dispatch also stops its notification watcher, whose receipt then reads `creation_failed`.

## 4. Outcome, Reuse and Launch Failures

- **Outcome is the finish, not the latest host state.** Paseo keeps changing a worker after it finishes: it closes an idle one when it collects the runtime (about an hour later), fails its session on a plugin reload, and archives it. The bridge's notification watcher records its first terminal sighting (`terminal` in `paseo-notifications/<dispatch_id>.json`); a later observation that sees `closed`, `error` or `archivedAt` after a recorded finish settles the dispatch `completed`. `closed` with `attentionReason: finished` is `completed` too; `closed` without a finish is `canceled`.
- **Which idle workers are resumed.** Only a worker whose last dispatch completed, that is not `closed` (its runtime was collected, so a resume would cold-restore it), whose last dispatch is no older than `REUSE_MAX_IDLE_HOURS` (24 h; a turn sent to it by message is not on its dispatch, so this age does not refuse a worker `--resume` names), that is under `rotate_after_carried_tokens` and passes `turn_refusal.gate_refusal`, and that matches by explicit `--resume`, `chain`, `task_id`/`brief_path`, or canonical `--workspace` (never a worker that wrote code for a read-only review). Matching the bundle alone is not continuity. When `--workspace` is blocked by an idle worker of the same parent, the `blocked` result names that worker and points to `--resume <id>`. A `--resume` the registry refuses (`resume_worker_unavailable`) says which of these facts refused it and the way out for that fact (`dispatch_registry.WORKER_STATES` for a worker's state, `Refusal` for the rest: a permission is answered, a running turn or an open dispatch is waited for, an error is read; a fresh worker is offered only where it helps). A host's refusal of a named worker carries the bridge's `condition` when it sent one (`worker_not_idle` with `running`, `initializing`, `error`, `provider_unavailable` or `permission_pending`; `worker_not_found` with `absent` or `archived`; `host_connection_failed` with `refused`, `timeout`, `authentication`, `credential_unreadable`, `rejected` or `unreachable`; `host_request_failed` and `host_resume_failed` with `timeout`, `connection_lost`, `daemon_error`, `invalid_response`, `authentication` or `bridge_error`: the table `dispatch_flow.HOST_CONDITIONS`), and the advice follows it. A resume the daemon may have received (`host_request_failed`, `sent: true`) stays `pending` with `cause` `host_request_failed:<condition>`: the turn may have landed, so only `next_argv` is safe.
- **Resume binds before it sends.** The bridge writes the new dispatch labels on the worker before sending the turn, so a send cut off by the caller's timeout is still observable; a send the host refused gives the worker its previous labels back and falls back to a fresh create. The bridge call for a resume may take up to 90 s.
- **Only candidate-attributed create refusals cool down.** A definitive Paseo create failure (`host_creation_failed`) is recorded in the event reason with a fixed class (`provider_refresh_timeout`, `provider_unavailable`, `subscription_inactive`, `quota`, `model_unavailable`, `request_invalid`, `unknown`; never remote error text). Only candidate-scoped classes (or structured candidate `failure_code`s such as `INVALID_MODEL`) are recorded in `launch-failures.json` and trigger automatic fallback; `request_invalid` and unclassified `unknown` refusals stop the dispatch without cooling down any model or account. Routing excludes the whole account for `provider_refresh_timeout` and `provider_unavailable` and only that model otherwise, for 15 min, doubling per consecutive failure up to 2 h; a worker that starts on the account clears it. Uncertain outcomes (timeouts, lost replies) never cool anything down. `ROUTER_LAUNCH_FAILURES=off` disables it; a path relocates the file.
- **Completed rows record calibration ground truth (`dispatch_ground_truth`).** When a dispatch reaches `completed`, its row in `dispatch.sqlite3` records `active_seconds` (event gaps `<= dispatch_registry.RUN_LEASE`, 600 s), `token_usage` (`input_tokens`, `output_tokens`, `cache_read_tokens`, `cache_write_tokens`) for `claude` and `codex`, git working-tree changes (`files_changed`, `lines_added`, `lines_deleted`, `lines_changed`) in `cwd` relative to `launch_commit`, and the follow-up-turn boundary (`initial_active_seconds`, `followup_active_seconds`, `first_followup_at`, `user_turns`, `followup_turns`). Telemetry that was not measured is `null` with an explicit `*_reason` (`antigravity`, `pi`, `grok-bot`, `dot`; a transcript not found, `session_transcript_not_found`, apart from one found or searched that could not be opened, `session_transcript_unreadable`; `not_a_git_checkout` only when git says the directory is in no repository, `git_no_work_tree` when it says the repository has no working tree (a bare repository, a directory inside `.git`), any other `rev-parse` failure `git_rev_parse_failed:<class>`; a git that did not finish in time `git_timeout`, one that could not be started `git_unavailable`). A measured zero is a zero of what was measured: `files_changed` and the line counts cover tracked files only (committed, staged and unstaged since `launch_commit`), and `untracked_files` counts the untracked, not ignored files of the whole working tree at the end, apart, because they cannot be attributed to the worker (`null` with `untracked_files_reason` when they could not be read). Measuring a completion is not the completion: on every path that records one (an observation, a watcher's receipt, an external runner) a collection that raised still completes the row, and the clears that follow a completion run. The row records every field `null` with `collection_failed:<class>` as its reason and in `ground_truth_reason`; an `OSError` (a file locked for a moment) is first retried once, by a read at least `dispatch_registry.GROUND_TRUTH_RETRY_SECONDS` (60 s) after it failed (`ground_truth_retry` holds the class and the time). Allocation (`allocator.plan` and the quota economy) never reads these fields.
- **A model the provider says does not exist is latched out.** When that create failure also carries the provider's own structured error code (`failure_code`, e.g. the Antigravity plugin's `INVALID_MODEL`, which the daemon records as the creation's `errorCode`) and the code is in `model_latch.MODEL_UNAVAILABLE_CODES`, `model-unavailable.json` latches that account's model. Only the code decides; no error text is read. Routing, a named model and prepare exclude it, `plan`/`roll` warn about it first and the tray model list marks it with its next retry. It lifts on the first of: a worker on that account and model starting after the latch, discovery (`model-catalog.json`) listing the model in a probe newer than the latch, `model_latch.RETRY_HOURS` (the same as an account latch, `account_state.LATCH_RETRY_HOURS`) passing so the next roll re-probes it, or `model_latch.py --clear <account>/<model>`. The user's model checkboxes are never changed. `ROUTER_MODEL_LATCH=off` disables it; a path relocates the file.
- **A provider that fails a worker is held out.** Two ways reach it, with the provider's own message verbatim. (1) Stuck retry: some providers retry a failing request forever (opencode 1.x `session.status` retry; Paseo renders it, and pi's `auto_retry_start`, as a timeline error `Provider retry (attempt N): <message>`; omp's as a structured status line). The bridge's per-dispatch watcher reads the running worker's timeline tail; when nothing but retry notices has happened for the whole `AGENTCOMPASS_RETRY_STUCK_SECONDS` window (default 300 s; `AGENTCOMPASS_RETRY_STUCK_ATTEMPTS` sets a minimum attempt count, default 1), it saves a terminal with `failure_code` `provider_retry_stuck`, the message, attempts, the provider's `next` when given, whether the turn had done work before retrying (`partial_work`), then cancels the turn (retried once; `cancelled: false` is told to the parent) and tells the parent. (2) Turn failed: a worker whose turn ends in error with the provider's error text (`agent.lastError`, only when it is this turn's: a resumed worker's error before its turn started is the previous turn's; opencode 2.x fails a free model at once: "Free usage limit reached. ...") gets `failure_code` `provider_turn_failed`. The registry marks the dispatch `failed` (cause `worker_failed:<code>`) and `provider_retry.py` records it once per dispatch in `provider-retry.json` (also from the watcher's receipt at the next plan or tray usage pass). The configured System-One classifier reads the message and decides the scope: `account` holds the quota pool of the failed model (the whole account when it has a single pool) with no retry time; `model`/`transient` hold only that model with the usage-reading backoff (2 min doubling, capped at 30 min; a later provider `next` wins); `none` (not the provider's doing, e.g. a tool error) and `task_input` (this task's own input refused, e.g. a prompt too long for the model) hold nothing, and a failed turn read that way becomes the worker's error (`worker_turn_failed` / `task_input_rejected`, with their own next_action and no provider wording); `unknown` (or no classifier answer) holds the model and widens to its pool only when another model of the same pool is held for an unknown reason too, and that widened hold backs off like a model hold: only the classifier's own `account` answer holds indefinitely. Pools (`provider_retry.pool_of`) come from structure, never names: models drawing a common quota window (window `models`/`models_except` scopes, the usage reading's own `models`, explicit `draws`) are one pool, so Antigravity's Gemini and third-party models are two; where one provider of the account launches under several provider prefixes of its own (`opencode/` Zen free models, `opencode-go/` Go), each prefix is a pool. A pool hold is keyed `ACCOUNT#POOL` and never blocks another pool; widening never crosses pools. An account hold taken while the account had one pool (e.g. a Zen free-usage hold before OpenCode Go was connected) becomes a hold of its failed models' pools once the account has several (`scope_account_holds`, when the accounts load). No code reads the message. Routing never picks a held bundle and plan/roll warn first; a model the user names (`roll --model`) is dispatched anyway as a probe, and a dispatch launched after the hold whose turn the watcher saw end on the model's reply (`replied` on the finished terminal: the last timeline item is an assistant message and nothing back to the prompt is an error; Paseo shows a cancelled turn as idle/finished too, so a completion without it lifts nothing) lifts the account's hold, its pool's and that model's. On an account with a usage reader, a good usage reading newer than the hold, or a credential other than the one it was taken under (re-login), lifts that account or pool hold and its model holds, as it lifts the plan-inactive latch (`provider_inventory`). Otherwise clear with the tray card's Clear link, `agentcompass hold --clear ACCOUNT` (every hold of it), `ACCOUNT#POOL` (that pool's hold and its models') or `agentcompass hold --clear ACCOUNT/MODEL` (that model's hold only). The tray account list and model list show the provider's message, the held pool and next retry; with pools held the card's Clear link names and clears one pool at a time. `ROUTER_PROVIDER_RETRY=off` disables it; a path relocates the file.
- **A worker that ends in error after Paseo created it** (the agent exists, so this is not a create failure) settles `failed` with `error: worker_failed` and a `next_action` to read its error and tell the user. Paseo keeps only text for such a failure (`lastError`; a turn's error code is not kept on the agent), so nothing is latched from it.
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