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

scripts/dispatch_fallback.py

View on GitHub
"""Retry or relaunch a Paseo dispatch whose chosen model failed, so the parent hears only the final outcome.

Owner requirement (2026-11-10): "roll首选模型失败时,重试和自动选第二个模型都自己做好,不要让主会话自己重试。"

Contract:
- Covered failures of one attempt (`failure_of`): a create Paseo confirms failed (a provider INVALID_MODEL included;
  model_latch then holds that model) or a bundle refused at prepare/claim (registry.CapacityChanged: an exclusion that
  appeared since the plan, such as a live model list that dropped it, a launch floor or a disabled account); a worker that
  ended in error; a provider that kept retrying (`provider_retry_stuck`, only when the bridge's stop took); a turn the
  provider failed (`provider_turn_failed`, e.g. 429 or an exhausted quota). What a provider failure blocks is the
  System-One classifier's scope that provider_retry recorded for that dispatch (model, account, transient, unknown):
  this module reads the scope and nothing else, no message text, no model or provider names.
- Not covered, reported to the parent as before: scope `task_input` (the brief's own input) and `none` (the worker's own
  error), a stop that did not take (the worker may still be running), a removed or finished worker, a launch the host
  refused before creating anything for reasons of its own (parent, notifier), and every non-Paseo surface.
- Transient: the same bundle once more after its provider_retry backoff, when that wait fits the task's `can_wait_hours`
  (none given: nothing waits and the next candidate starts now). Nothing sleeps through the wait: the step records the
  retry time (`scheduled`) and returns; the failed attempt's watcher, or any later launch/observe of the brief
  (`resume_due`), runs `handle` again once it is due. The failed attempt's claim and the first dispatch's guard both
  last until then, so no other observer relaunches it meanwhile. The guard lasts as long as the task can wait
  (can_wait_hours); a retry nobody started by then is retired (`retry_expired`), never run beside a new dispatch of
  the brief. The parent's release of the dispatch cancels a scheduled retry (registry.retire_scheduled), and a parent
  follow-up that resumes a failed attempt's worker retires any pending retry or switch (`resumed`) and restores that
  attempt as `current`. A model the owner named (`roll --model`, a
  `user_override` decision) follows the same can_wait_hours rule and is never switched: when its backoff does not fit,
  the parent is told (`owner_named`). A worker the caller named (`roll --resume`, constraint `explicit_resume`) is
  never retried on a new worker nor replaced: its failure is reported as it is (`worker_named`).
- Otherwise: allocation runs again on the original decision's allocation task (its classifier profile, needs such as
  local_only, fast) with every bundle that failed in this dispatch marked unavailable; the classifier is not asked
  again. The winner is launched with the first dispatch's title, workspace, cwd, access, parent and the original prompt,
  prefixed by a note naming the failed attempts and asking the worker to check the workspace before continuing.
- One worker per brief: a relaunch is prepared only after the failed attempt is terminal and confirmed dead (create
  failed, or the worker ended in error, or the bridge's stop was confirmed), and `Chain.run` rechecks the failed
  attempt's host status via `dispatch_flow.reconcile` before launching so a worker the parent resumed never gets a
  sibling. Between attempts the first dispatch carries a guard (registry.fallback_guard) so the parent or another
  observer cannot start the brief a second time. A failed attempt is claimed once (`handled`), so two observers never
  relaunch it twice.
- Bound: every failure puts its bundle in the dispatch's excluded set (a transient one after its single same-bundle
  retry), and allocation never returns an excluded bundle, so one dispatch makes at most (startable candidates +
  transient retries) attempts, and ends `blocked` with every attempt's cause once allocation has nothing left.
- Bookkeeping: each attempt is its own registry row with its own decision, lease, labels and holds, linked by
  `attempt_of` (the first dispatch, the id the parent holds) and `previous_attempt`; the first dispatch keeps
  `fallback` = {state, current, attempts, handled, outcome}. Each step writes a `stage: fallback` ledger line and each
  re-plan its own plan line. A failed row is terminal, so its lease is released before the next attempt takes one.
"""
import argparse
import json
import os
from pathlib import Path
from datetime import timedelta

import dispatch_registry as registry

PROVIDER_FAILURES = ('provider_retry_stuck', 'provider_turn_failed')
TRANSIENT = 'transient'
NOT_COVERED_SCOPES = ('none', 'task_input')


# The sentence beside `disabled` and `unsettled`, for a person who runs the action: the watcher branches on `action`
# alone and the bridge keeps no other key of these two.
DISABLED_MEANING = ('Automatic retry and relaunch of a failed attempt is off on this machine (AGENTCOMPASS_ROLL_FALLBACK=off), '
                    'so nothing was retried or relaunched; the parent is told of the failure as it is.')
UNSETTLED_MEANING = ('This dispatch has not ended (state {state}), and only an attempt that ended in a failure is retried or '
                     'relaunched, so nothing was done. Observe it with --dispatch-action reconcile.')


def enabled():
    return os.environ.get('AGENTCOMPASS_ROLL_FALLBACK', '').strip().lower() != 'off'


def notification_dir():
    return Path(os.environ.get('ROUTER_STATE_DIR') or Path.home() / '.agent-compass') / 'paseo-notifications'


def failure_of(row):
    """What ended one attempt: {covered, kind ('switch' | 'transient' | None), label, scope}."""
    state, code = row.get('state'), row.get('failure_code')
    if state == 'create_failed':
        import launch_failures
        creation = row.get('creation') or {}
        cause = row.get('failure_class') or ('outcome_unknown' if creation.get('phase') == 'failed'
                                             else creation.get('phase') or 'unknown')
        covered = bool(launch_failures.candidate_failure_class(row.get('failure_class'), code))
        return {'covered': covered, 'kind': 'switch' if covered else None, 'scope': None,
                'label': ':'.join(str(p) for p in ('create_failed', cause, code) if p)}
    if state != 'failed' or not row.get('agent_id'):
        reason = next((e.get('reason') for e in reversed(row.get('events') or ()) if e.get('reason')), None)
        return {'covered': False, 'kind': None, 'scope': None, 'label': ':'.join(p for p in (state, reason) if p)}
    if code in PROVIDER_FAILURES:
        if (row.get('failure_detail') or {}).get('cancelled') is False:
            return {'covered': False, 'kind': None, 'scope': None, 'label': f'{code}:stop_failed'}
        import provider_retry
        scope = provider_retry.dispatch_scope(row['dispatch_id']) or 'unknown'
        if scope in NOT_COVERED_SCOPES:
            return {'covered': False, 'kind': None, 'scope': scope, 'label': f'{code} (classifier scope {scope})'}
        return {'covered': True, 'kind': TRANSIENT if scope == TRANSIENT else 'switch', 'scope': scope,
                'label': f'{code} (classifier scope {scope})'}
    if code == 'task_input_rejected':
        return {'covered': False, 'kind': None, 'scope': 'task_input', 'label': code}
    if code == 'worker_turn_failed':
        return {'covered': False, 'kind': None, 'scope': 'none', 'label': code}
    if code is None:
        return {'covered': True, 'kind': 'switch', 'scope': None, 'label': 'worker_error'}
    return {'covered': False, 'kind': None, 'scope': None, 'label': str(code)}


def refused(exc):
    return {'covered': True, 'kind': 'switch', 'scope': None, 'label': 'refused_before_launch',
            'detail': str(exc)[:300]}


def bundle_view(bundle):
    bundle = bundle or {}
    return {k: bundle.get(k) for k in ('bundle_id', 'provider', 'account', 'model', 'effort') if bundle.get(k)}


def hold_key(bundle):
    import provider_retry
    try:
        entry = provider_retry.entry_for(bundle, provider_retry.active())
    except OSError:
        return None
    return provider_retry.entry_key(entry) if entry else None


def line(attempt, following=None):
    head = f"attempt {attempt['attempt']}: {attempt.get('model')} on {attempt.get('account')}"
    if not attempt.get('failure'):
        return head + (' (current attempt)' if attempt.get('dispatch_id') else '')
    text = f"{head} failed: {attempt['failure']}" + (f" ({attempt['detail']})" if attempt.get('detail') else '')
    if following is None:
        return text
    if following.get('bundle_id') == attempt.get('bundle_id'):
        return text + '; retried the same model after its backoff'
    return text + f"; switched to {following.get('model')} on {following.get('account')}"


def lines(attempts):
    return [line(a, attempts[i + 1] if i + 1 < len(attempts) else None) for i, a in enumerate(attempts)]


def relaunch_prompt(base, attempts):
    failed = [f"- attempt {a['attempt']}: model {a.get('model')} on account {a.get('account')} failed with "
              f"{a.get('failure')}" for a in attempts if a.get('failure')]
    return ('AgentCompass note: earlier attempts at this brief stopped before finishing:\n' + '\n'.join(failed) +
            '\nThey may have left work in this workspace. Before you start, check its state (uncommitted changes, '
            'partial commits on the branch, files the brief names) and continue from it rather than starting over or '
            'discarding it.\n\n---\n\n' + base)


def write_attempts_file(dispatch_id, root_id, attempt_lines):
    """What the new attempt's watcher puts in the parent's notification (paseo_dispatch_bridge.mjs attemptsNote)."""
    folder = notification_dir()
    try:
        folder.mkdir(parents=True, exist_ok=True)
        (folder / f'{dispatch_id}.json.attempts').write_bytes(
            json.dumps({'root_dispatch_id': root_id, 'lines': attempt_lines}, ensure_ascii=False).encode('utf-8'))
    except OSError:
        pass  # the notification then names only this attempt; the registry still has the whole chain


def lease_end(stamp):
    try:
        return registry.stamp(registry.parse(stamp) + timedelta(seconds=registry.RUN_LEASE)) if stamp else None
    except ValueError:
        return None


class AlreadyHandled(Exception):
    def __init__(self, outcome):
        super().__init__('already handled')
        self.outcome = outcome


class Chain:
    """The attempts of one brief, from its first dispatch (`root`) or, before any row exists, from its decision."""

    def __init__(self, decision, launch, *, root=None, access='write', workspace=None, cwd=None,
                 judge=None, host=None):
        if judge is None:
            import route_judge as judge
        self.judge, self.host = judge, host
        self.decision = decision
        self.owner_named = decision.get('constraint') == 'user_override'
        # `roll --resume <id>` named a worker, not a route: no other worker, and no retry on a new one, replaces it.
        self.worker_named = decision.get('constraint') == 'explicit_resume'
        task = dict(decision.get('allocation_task') or decision['task'])
        task.pop('chain', None)   # a relaunch is a new worker, never a resume
        self.task = task
        self.parent = decision['parent_id']
        self.launch = launch
        self.access, self.workspace, self.cwd = access, workspace, cwd
        self.root = root
        fallback = (root or {}).get('fallback') or {}
        self.attempts = [dict(a) for a in fallback.get('attempts') or ()]
        if root is not None and not self.attempts:
            self.attempts = [self.entry(root['bundle'], root)]

    @classmethod
    def of(cls, root, **kwargs):
        request = root['request']
        base = root.get('fallback_prompt') or request['initialPrompt']
        launch = {'title': request['title'], 'initialPrompt': base,
                  **({'cwd': request['cwd']} if request.get('cwd') else {})}
        return cls(registry.decision_record(root['decision_id']), launch, root=root, access=root.get('access', 'write'),
                   workspace=root.get('workspace'), cwd=root.get('cwd') or request.get('cwd'), **kwargs)

    @property
    def root_id(self):
        return self.root['dispatch_id'] if self.root else None

    def entry(self, bundle, row=None):
        return {'attempt': len(self.attempts) + 1, **bundle_view(bundle),
                **({'dispatch_id': row['dispatch_id'], 'decision_id': row['decision_id']} if row else {})}

    def recorded_earlier(self):
        """True when this brief's decision was recorded by an earlier version (dispatch_registry.earlier_version): it is
        neither replanned nor read again (`dispatch_registry.prepare` refuses the same decision), so its relaunch ends
        here with a reason."""
        return registry.earlier_version(self.task) is not None

    def failed(self, attempt, failure, row=None):
        attempt.update(failure=failure['label'], kind=failure['kind'], covered=failure['covered'],
                       **({'scope': failure['scope']} if failure.get('scope') else {}),
                       **({'detail': failure['detail']} if failure.get('detail') else {}),
                       **({'state': row['state'], 'agent_id': row.get('agent_id')} if row else {}))
        if failure['covered']:
            held = hold_key({k: attempt.get(k) for k in ('account', 'provider', 'model')}) if failure['scope'] else None
            if held:
                attempt['hold'] = held

    def excluded(self):
        """Bundles this dispatch must not start again: each covered failure's, a transient one once retried."""
        out = set()
        for a in self.attempts:
            if not a.get('covered') or not a.get('bundle_id'):
                continue
            if a.get('kind') != TRANSIENT or self.transient_tries(a['bundle_id']) > 1 or not self.can_retry(a):
                out.add(a['bundle_id'])
        return out

    def transient_tries(self, bundle_id):
        return sum(1 for a in self.attempts if a.get('bundle_id') == bundle_id and a.get('kind') == TRANSIENT)

    def can_retry(self, attempt):
        """The same rule for every model, the owner's included: the backoff must fit the task's can_wait_hours."""
        return self.backoff(attempt) <= float(self.task.get('can_wait_hours') or 0) * 3600

    def backoff(self, attempt):
        """Seconds until provider_retry lets this model be tried again; its own first backoff when nothing is held."""
        import provider_retry
        try:
            entry = provider_retry.entry_for({k: attempt.get(k) for k in ('account', 'provider', 'model')},
                                             provider_retry.active())
        except OSError:
            entry = None
        if entry and isinstance(entry.get('retry_at'), str):
            return max(0.0, (registry.parse(entry['retry_at']) - registry.utcnow()).total_seconds())
        return float(provider_retry.retry_seconds(1))

    def ledger(self, action, attempt, **extra):
        import decision_ledger
        try:
            decision_ledger.append_ledger({'v': 1, 'at': registry.stamp(registry.utcnow()), 'stage': 'fallback',
                                      'action': action, 'parent_id': self.parent, 'task_id': self.task.get('task_id'),
                                      'root_dispatch_id': self.root_id, 'attempt': attempt.get('attempt'),
                                      'failed': {k: attempt.get(k) for k in (
                                          'dispatch_id', 'bundle_id', 'provider', 'account', 'model', 'effort',
                                          'failure', 'scope', 'hold', 'detail') if attempt.get(k)}, **extra})
        except Exception:   # noqa: BLE001 - auditing never stops a relaunch
            pass

    def save(self, state, **fields):
        if not self.root:
            return None
        attempts = [dict(a) for a in self.attempts]

        def change(fallback):
            fallback.update(state=state, attempts=attempts, lines=lines(attempts), **fields)
            if state not in ('retrying', 'relaunching'):
                fallback.pop('until', None)
            if state != 'retrying':
                fallback.pop('retry_at', None)
                fallback.pop('retry_of', None)
        self.root = registry.update_fallback(self.root['dispatch_id'], change)
        return self.root

    def claim(self, failed_id):
        """Only one observer handles a failed attempt; a second gets the first one's outcome. Returns True when the
        claim is the scheduled same-bundle retry falling due (run it with resume=True), False for a fresh failure.

        A claim stays valid until its own `until`: a step in progress holds it for RUN_LEASE, a scheduled retry until
        its retry time (no observer may take a failure over while its backoff is still being waited out). Only a claim
        whose holder died (a pending one past its `until`) or a scheduled retry that is due may be taken.

        A scheduled retry only runs while the first dispatch's guard holds (fallback `until`, see `schedule`): the
        guard is what keeps the brief from being dispatched again, so a retry found due after it lapsed is retired
        (`retry_expired`) in this same transaction instead, and a fresh dispatch of the brief and this retry never both
        run. Taking a due retry renews the guard, so it cannot lapse between the claim and the relaunch's own guard."""
        claimed = {}

        def change(fallback):
            now = registry.utcnow()
            handled = dict(fallback.get('handled') or {})
            before = claimed['before'] = handled.get(failed_id)
            action = (before or {}).get('action')
            due = action == 'scheduled' and not registry.later(before.get('retry_at'), now)
            stale = action == 'pending' and not registry.later(before.get('until') or lease_end(before.get('at')), now)
            resume = due or (stale and bool(before.get('resume')))
            if resume and fallback.get('retry_of') == failed_id and not registry.later(fallback.get('until'), now):
                registry.retire_scheduled(fallback, now, 'retry_expired', RETRY_EXPIRED_NEXT, self.root_id)
                claimed['before'] = fallback['handled'][failed_id]
                claimed['take'] = False
                return
            claimed['take'] = before is None or due or stale
            if claimed['take']:
                handled[failed_id] = {'action': 'pending', 'at': registry.stamp(now), 'until': registry.stamp(
                    now + timedelta(seconds=registry.RUN_LEASE)), **({'resume': True} if resume else {})}
                claimed['resume'] = resume
                fallback['handled'] = handled
                if resume:
                    lease = registry.stamp(now + timedelta(seconds=registry.RUN_LEASE))
                    fallback['until'] = max(fallback['until'], lease, key=registry.parse)
        self.root = registry.update_fallback(self.root['dispatch_id'], change)
        before = claimed['before']
        if claimed['take']:
            return claimed['resume']
        if before.get('action') == 'pending':
            raise AlreadyHandled({'action': 'pending', 'root_dispatch_id': self.root_id,
                                  'detail': 'another observer is relaunching this attempt'})
        raise AlreadyHandled(before)

    def outcome(self, failed_id, outcome):
        if not self.root or not failed_id:
            return outcome

        def change(fallback):
            fallback['handled'] = {**(fallback.get('handled') or {}), failed_id: outcome}
        self.root = registry.update_fallback(self.root['dispatch_id'], change)
        return outcome

    # The loop.

    def run(self, failure, row=None, bundle=None, resume=False):
        """From one failed attempt to the next live worker, a scheduled retry or a final state. `row` is the failed
        attempt's row (None when its bundle was refused before a row existed); `bundle` the refused bundle then.
        `resume`: the scheduled same-bundle retry of `row` is due (claim said so); it starts without deciding again."""
        import usage_reading
        failed_id = row['dispatch_id'] if row else None
        while True:
            attempt = next((a for a in self.attempts if row and a.get('dispatch_id') == row['dispatch_id']), None)
            if attempt is None:
                attempt = self.entry(bundle or row['bundle'], row)
                self.attempts.append(attempt)
            kept = len(self.attempts)
            if self.recorded_earlier():
                if not resume:
                    self.failed(attempt, failure, row)
                self.ledger('older_profile', attempt)
                return self.finish('older_profile', failure, failed_id)
            if self.worker_named and not resume:
                self.failed(attempt, failure, row)
                self.ledger('worker_named', attempt)
                return self.finish('worker_named', failure, failed_id)
            if resume:
                resume = False
                resumed_id = self.resumed_attempt(row)
                if resumed_id:
                    return self.settle_resumed(resumed_id, attempt, failed_id)
                choice = (self.same_bundle(attempt), 'retry_same', 0)
            else:
                self.failed(attempt, failure, row)
                if not failure['covered']:
                    self.ledger('declined', attempt)
                    return self.finish('declined', failure, failed_id)
                resumed_id = self.resumed_attempt(row)
                if resumed_id:
                    return self.settle_resumed(resumed_id, attempt, failed_id)
                choice = self.next_choice(attempt)
            if choice is None:
                kind = 'owner_named' if self.owner_named else 'blocked'
                self.ledger(kind, attempt, excluded=sorted(self.excluded()))
                return self.finish(kind, failure, failed_id)
            decision, how, wait = choice
            if how == 'scheduled':
                return self.schedule(attempt, wait, failed_id)
            if how == 'switch':
                resumed_id = self.resumed_attempt(row)
                if resumed_id:
                    self.attempts[kept:] = []
                    return self.settle_resumed(resumed_id, attempt, failed_id)
            new_bundle = decision['selected_bundle']
            self.ledger(how, attempt, next={'decision_id': decision['decision_id'], **bundle_view(new_bundle)})
            try:
                new = registry.prepare(decision['decision_id'], self.task, dict(
                    self.launch, initialPrompt=relaunch_prompt(self.launch['initialPrompt'], self.attempts)),
                    usage_reading.usage_snapshot(None), access=self.access,
                    workspace=self.workspace, cwd=self.cwd,
                    attempt={'attempt_of': self.root_id, 'attempt': len(self.attempts) + 1,
                             'previous_attempt': (row or {}).get('dispatch_id')} if self.root else None)
            except registry.CapacityChanged as exc:
                row, bundle, failure = None, new_bundle, refused(exc)
                continue
            except ValueError as exc:   # a writer appeared in the workspace, or the decision cannot dispatch
                live = self.live_attempt(failed_id)
                if live:
                    # Another attempt of this brief already runs (its own watcher reports): this failure is settled by
                    # it, and the chain's record must keep pointing at it.
                    return self.outcome(failed_id, {'action': 'relaunched', 'dispatch_id': live,
                                                    'root_dispatch_id': self.root_id, 'attempts': self.attempts,
                                                    'lines': lines(self.attempts),
                                                    'detail': 'another attempt of this brief is live'})
                attempt_next = self.entry(new_bundle)
                self.attempts.append(attempt_next)
                self.failed(attempt_next, {'covered': False, 'kind': None, 'scope': None,
                                           'label': 'not_prepared', 'detail': str(exc)[:300]})
                self.ledger('declined', attempt_next)
                return self.finish('declined', {'label': 'not_prepared'}, failed_id)
            if self.root is None:
                # Refused before the first row existed: this attempt becomes the dispatch the parent holds.
                self.root = new
                self.attempts.append(self.entry(new_bundle, new))
                self.save('relaunching', current=new['dispatch_id'])
            else:
                self.attempts.append(self.entry(new_bundle, new))
                self.save('relaunching', current=new['dispatch_id'],
                          until=registry.stamp(registry.utcnow() + timedelta(seconds=registry.RUN_LEASE)))
            write_attempts_file(new['dispatch_id'], self.root_id, lines(self.attempts))
            import dispatch_flow
            try:
                receipt = dispatch_flow.launch(new['dispatch_id'], self.parent, host=self.host, watch_seconds=0)
            except registry.CapacityChanged as exc:   # refused at claim: nothing was sent
                registry.release(new['dispatch_id'], self.parent, 'refused_at_claim', failed=True)
                row, bundle, failure = registry.inspect(new['dispatch_id']), new_bundle, refused(exc)
                continue
            current = registry.inspect(new['dispatch_id'])
            # A relaunched worker can finish before this read: completed is this attempt's success, not its failure.
            if current['state'] in registry.TERMINAL and current['state'] not in ('expired', 'completed'):
                row, bundle, failure = current, new_bundle, failure_of(current)
                continue
            self.save('relaunched', current=current['dispatch_id'])
            outcome = {'action': 'relaunched', 'dispatch_id': current['dispatch_id'], 'root_dispatch_id': self.root_id,
                       'agent_id': current.get('agent_id'), 'attempts': self.attempts, 'lines': lines(self.attempts),
                       'receipt': receipt}
            return self.outcome(failed_id, outcome)

    def next_choice(self, attempt):
        """(decision, 'retry_same' | 'switch', 0) for the next attempt now, (None, 'scheduled', seconds) for a same-bundle
        retry after its backoff, or None when nothing may start."""
        if attempt.get('kind') == TRANSIENT and self.transient_tries(attempt['bundle_id']) == 1 and self.can_retry(attempt):
            wait = self.backoff(attempt)
            if wait > 0:
                return None, 'scheduled', wait
            return self.same_bundle(attempt), 'retry_same', 0
        if self.owner_named:
            return None
        decision = self.replan()
        return (decision, 'switch', 0) if decision else None

    def schedule(self, attempt, wait, failed_id):
        """Nothing blocks for the backoff: the retry time is recorded and the step returns. The failed attempt's watcher
        (paseo_dispatch_bridge.mjs, outcome `scheduled`) or any later observation (`resume_due`, from dispatch launch or
        observe) runs `handle` again once it is due; the claim and the guard hold until then, so no one starts the brief
        in between and the observer that resumes is the only one.

        The guard (fallback `until`) lasts as long as the task said it can wait (can_wait_hours from the failure), and at
        least RUN_LEASE past the retry time: a retry nobody started by then is retired by the next claim (`claim`), so
        the guard never lapses while the retry may still run."""
        now = registry.utcnow()
        retry_at = registry.stamp(now + timedelta(seconds=wait))
        until = registry.stamp(now + timedelta(seconds=max(wait + registry.RUN_LEASE,
                                                            float(self.task.get('can_wait_hours') or 0) * 3600)))
        self.ledger('scheduled', attempt, wait_seconds=round(wait), retry_at=retry_at)
        self.save('retrying', current=attempt.get('dispatch_id'), retry_of=failed_id, retry_at=retry_at, until=until)
        return self.outcome(failed_id, {'action': 'scheduled', 'root_dispatch_id': self.root_id, 'retry_at': retry_at,
                                        'attempts': self.attempts, 'lines': lines(self.attempts)})

    def same_bundle(self, attempt):
        """The decision for a transient failure's retry on its own bundle. It is issued and written to the ledger like
        every routed start (a plan line, or a record line for the owner's model), so the audit sees a route for it."""
        import decision_ledger
        # A transient failure is a provider's, so it always has the row whose bundle it was.
        failed_row = registry.inspect(attempt['dispatch_id'])
        bundle = dict(failed_row['bundle'])
        # A named route keeps what its record decided: the rows a provider listed for a model the shipped data has no row
        # for (provider_inventory), and its route fields (an unclassified launch stays priced from its hours).
        failed_decision = registry.decision_record(failed_row['decision_id']) if self.owner_named else {}
        listed = failed_decision.get('listed_rows')
        result = {'stage': 'record' if self.owner_named else 'plan', 'source': 'fallback_retry',
                  'choice': bundle.get('bundle_id'), 'selected_bundle': bundle, 'decision': {'action': 'start'},
                  'parent_id': self.parent,
                  **({'constraint': 'user_override',
                      'basis': f'AgentCompass transient retry of dispatch {self.root_id} on the owner-named model'}
                     if self.owner_named else
                     {'basis': f'AgentCompass transient retry of dispatch {self.root_id} on its routed bundle'})}
        issued = registry.issue(result, self.task, allocation_task=failed_decision.get('allocation_task') or self.task,
                                listed_rows=listed, route=failed_decision.get('route'))
        decision = {**result, **issued}
        try:
            decision_ledger.append_ledger({
                'v': 1, 'at': registry.stamp(registry.utcnow()), 'stage': decision['stage'], 'source': 'fallback_retry',
                'choice': decision['choice'],
                **{k: decision[k] for k in ('decision_id', 'parent_id', 'task_hash', 'bound') if decision.get(k)},
                **({'task_id': self.task['task_id']} if self.task.get('task_id') else {}),
                'constraint': decision.get('constraint'), 'basis': decision['basis'][:400],
                'bundle': {k: bundle.get(k) for k in ('provider', 'account', 'model', 'effort', 'bundle_id', 'fast')
                           if bundle.get(k) is not None},
                'action': 'start', 'root_dispatch_id': self.root_id, 'attempt': len(self.attempts) + 1})
        except Exception:   # noqa: BLE001 - auditing never stops a relaunch
            pass
        return decision

    def live_attempt(self, failed_id):
        """Another attempt of this brief that is running or may still appear, if the chain's record names one."""
        current = ((self.root or {}).get('fallback') or {}).get('current')
        if not current or current in (failed_id, None):
            return None
        try:
            row = registry.inspect(current)
        except (KeyError, ValueError):
            return None
        return current if registry.unresolved(row, registry.utcnow()) else None

    def resumed_attempt(self, row=None):
        """A failed attempt of this brief whose worker the parent resumed, observed on the host via reconcile."""
        if not self.root:
            return None
        import dispatch_flow
        seen = []
        for candidate in ([row['dispatch_id']] if row else []) + [
                a['dispatch_id'] for a in reversed(self.attempts) if a.get('dispatch_id')]:
            if candidate not in seen:
                seen.append(candidate)
        for dispatch_id in seen:
            target = row if row and row['dispatch_id'] == dispatch_id else registry.inspect(dispatch_id)
            if target.get('state') == 'failed' and target.get('launched_at') and target.get('agent_id'):
                dispatch_flow.reconcile(dispatch_id, host=self.host)
                self.root = registry.inspect(self.root['dispatch_id'])
                fb = self.root.get('fallback') or {}
                if fb.get('state') == 'final' and (fb.get('outcome') or {}).get('result') == 'resumed':
                    return fb.get('current') or self.root['dispatch_id']
        self.root = registry.inspect(self.root['dispatch_id'])
        fb = self.root.get('fallback') or {}
        if fb.get('state') == 'final' and (fb.get('outcome') or {}).get('result') == 'resumed':
            return fb.get('current') or self.root['dispatch_id']
        return None

    def settle_resumed(self, resumed_id, attempt, failed_id):
        self.ledger('resumed', attempt, resumed_dispatch_id=resumed_id)
        attempts = [dict(a) for a in self.attempts]

        def change(fallback):
            fallback.update(attempts=attempts, lines=lines(attempts))
            registry.retire_scheduled(fallback, registry.utcnow(), 'resumed', registry.RESUMED_NEXT,
                                      self.root_id, current=resumed_id, extra_ids=(failed_id,))
        self.root = registry.update_fallback(self.root['dispatch_id'], change)
        return self.root['fallback']['handled'][failed_id or resumed_id]

    def replan(self):
        """Allocation again on the original inputs with this dispatch's failed bundles unavailable."""
        import roll
        import scorer_client
        excluded = self.excluded()
        profile = self.task.get('profile') if isinstance(self.task.get('profile'), dict) else {}
        args = argparse.Namespace(stage='plan', dry_run=False, no_score=True, score=False, demo=False, fast=False,
                                  score_timeout=scorer_client.SCORER_TIMEOUT_SECONDS, usage_cache=None,
                                  hours=None,
                                  keep_whole=(f'AgentCompass relaunch of dispatch {self.root_id}: the original roll '
                                              'kept this brief whole') if profile.get('multi_task') else None)
        for _ in range(len(excluded) + 64):
            decision, _ = self.judge.plan_stage({'task': self.task, 'unavailable': sorted(excluded)}, args)
            bundle = decision.get('selected_bundle') or {}
            if (decision.get('error') or decision.get('choice') in (None, 'none', 'self', 'split') or not bundle
                    or (decision.get('decision') or {}).get('needs_user_decision')
                    or not decision.get('decision_id')):
                return None
            bundle_id = bundle.get('bundle_id') or decision.get('choice')
            if bundle_id in excluded:
                return None
            if not roll.can_launch_via_paseo(bundle.get('provider')):
                # This relaunch runs on Paseo; a candidate only another surface starts is passed over, not launched.
                excluded.add(bundle_id)
                self.attempts.append({**self.entry(bundle), 'failure': 'not_launchable_on_paseo', 'kind': 'switch',
                                      'covered': True})
                continue
            return decision
        return None

    def finish(self, kind, failure, failed_id):
        text = final_text(kind, self.attempts, self.task)
        self.save('final', outcome={'result': kind, 'next_action': text}, current=(
            self.attempts[-1].get('dispatch_id') if self.attempts else None) or self.root_id)
        outcome = {'action': 'final', 'result': kind, 'covered': bool(failure.get('covered')),
                   'root_dispatch_id': self.root_id, 'attempts': self.attempts, 'lines': lines(self.attempts),
                   'text': text}
        return self.outcome(failed_id, outcome)


RETRY_EXPIRED_NEXT = ('AgentCompass scheduled a retry of this brief on the same model after a transient provider failure, '
                      'but nothing started it before the wait the task allows (can_wait_hours) ran out, so the retry is '
                      'retired and nothing runs this brief. Tell the user; roll it again if it is still wanted.')


def final_text(kind, attempts, task):
    listed = '\n'.join(lines(attempts))
    if kind == 'blocked':
        return ('AgentCompass retried or relaunched this brief on every startable candidate and none is left:\n'
                f'{listed}\nNothing is running it. The holds and cooldowns behind these failures lift on their own '
                '(plan/roll warnings and the tray account list say when). Tell the user.')
    if kind == 'older_profile':
        return ('This brief was routed by an earlier version of AgentCompass, in a shape this version does not read, so '
                f'it was not relaunched after its failure:\n{listed}\nNothing is running it. Tell the user; roll the '
                'brief again to route it afresh.')
    if kind == 'worker_named':
        return ('The caller named this worker with --resume, so AgentCompass does not start another worker in its place '
                f'(a new one would not have its context):\n{listed}\nNothing is running this brief. Roll it without '
                '--resume to let the router choose, or name a route.')
    if kind == 'owner_named':
        return ('The model was named by the owner, so AgentCompass retried only a transient failure and does not '
                f'switch to another model:\n{listed}\nNothing is running this brief. Tell the user; to let the router '
                'choose, roll it without --model.')
    return listed


def handle(dispatch_id, *, judge=None, host=None):
    """The bridge's watcher calls this (`agentcompass dispatch --dispatch-action fallback --dispatch-id ID`) when an
    attempt ends in a failure, and roll when a create fails at once. Returns {'action': 'relaunched' | 'scheduled' |
    'final' | 'unsettled' | 'disabled' | 'pending', ...}; the watcher stays silent on `relaunched`, calls again at
    `retry_at` on `scheduled`, looks again on `pending`, and sends one notification otherwise. Called again for a
    failure whose scheduled retry is due, it starts that retry."""
    if not enabled():
        return {'action': 'disabled', 'meaning': DISABLED_MEANING}
    import dispatch_flow
    row = registry.inspect(dispatch_id)
    if row['state'] not in registry.TERMINAL or row['state'] == 'expired':
        dispatch_flow.reconcile(dispatch_id, host=host)
        row = registry.inspect(dispatch_id)
    if row['state'] not in registry.TERMINAL or row['state'] == 'expired':
        return {'action': 'unsettled', 'state': row['state'], 'meaning': UNSETTLED_MEANING.format(state=row['state'])}
    root_id = registry.chain_root(row)
    root = row if root_id == dispatch_id else registry.inspect(root_id)
    if registry.fallback_guard(root, registry.utcnow()):
        dispatch_flow.reconcile(root_id, host=host)
        root = registry.inspect(root_id)
    chain = Chain.of(root, judge=judge, host=host)
    try:
        resume = chain.claim(dispatch_id)
    except AlreadyHandled as done:
        return done.outcome
    return chain.run(failure_of(row), row, resume=resume)


def resume_due(dispatch_id, *, host=None, now=None):
    """Any observation of a brief (dispatch launch/observe) starts its scheduled same-bundle retry once it is due, so
    the retry does not depend on the failed attempt's watcher alone. None when nothing is due."""
    if not enabled():
        return None
    try:
        row = registry.inspect(dispatch_id)
        root = row if registry.chain_root(row) == dispatch_id else registry.inspect(registry.chain_root(row))
    except (KeyError, ValueError):
        return None
    fallback = root.get('fallback') or {}
    if fallback.get('state') != 'retrying' or not fallback.get('retry_of') \
            or registry.later(fallback.get('retry_at'), now or registry.utcnow()):
        return None
    return handle(fallback['retry_of'], host=host)


def after_refusal(decision_id, launch, reason, *, access='write', workspace=None, cwd=None, judge=None, host=None):
    """roll's first prepare was refused (registry.CapacityChanged) before any row existed: go on to the next candidate."""
    decision = registry.decision_record(decision_id)
    chain = Chain(decision, launch, access=access, workspace=workspace, cwd=cwd, judge=judge, host=host)
    return chain.run(refused(reason), bundle=decision['bundle'])
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