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/state_upgrade.py

View on GitHub
"""Read-only upgrade checks for local ~/.agent-compass state, hooks and global rule blocks.

Every diagnostic names the offending file and a fix that works when followed:
  - re-run "agentcompass setup"
  - edit the file (what to change is named)
  - delete "<file>", with what the deletion discards when the file holds something the user chose
Only what needs the user is listed: a cache or database the product rebuilds or skips itself is not.

Runtime loaders call the same validators so an unreadable or wrong-schema file
fails fast with the same message `agentcompass doctor` prints. A leftover meter
on one dollar account does not fail the file and is not read: that account stays
out of routing until setup, or one tray action on it, deletes the fields.
"""
from __future__ import annotations

import json
import os
import sqlite3
from pathlib import Path

FIX_SETUP = 're-run "agentcompass setup"'
# Shown on the account row, in doctor, and as the routing exclusion. The fields are not applied.
LEGACY_METER_REASON = (
    '旧的额度字段残留。运行 agentcompass setup 清掉旧字段。'
)
LEGACY_SETTINGS_REASON = (
    '旧设置残留。在设置里保存一次即可清掉,或运行 agentcompass setup。'
)

# Overlay words of an earlier release (v0.1.0 to v0.5.0) and the name they carry today: the release's own rewrite of the
# command placeholder, the variable names it renamed (AGENTCOMPASS_* is the one canonical name), and the skill rename.
# A token with no current name (a bare script path placeholder, a script file name, ROUTE_MANAGER_*) is not rewritten.
HOST_RULE_UPGRADES = {
    'python -X utf8 @@ROUTE_JUDGE@@': '@@AGENTCOMPASS@@',
    'ROUTER_WORKER': 'AGENTCOMPASS_WORKER',
    'ROUTER_ACCOUNTS_OVERRIDE': 'AGENTCOMPASS_ACCOUNTS_OVERRIDE',
    'ROUTER_LIVE_MODELS': 'AGENTCOMPASS_LIVE_MODELS',
    'route-agent-work': 'agent-compass',
}
# The files `host_rules.load` reads; the others in `host-rules/` (dispatch.md, personal-routing-policy.md) are the user's own
# documents, which no release or check reads as an overlay.
HOST_RULE_OVERLAYS = ('shared.md', 'codex.md', 'daemon-append.md')
# `judges` was read by the select and delegate stages (removed 2026-11-21); a file a released version wrote may still carry
# it, so it is accepted and kept as written, and nothing reads it.
HOST_POLICY_KEYS = frozenset({'allowed_accounts', 'judges', 'usage_providers', 'known_accounts'})
RETIRED_PLACEHOLDER = '@@ROUTE_JUDGE@@'     # no current meaning on its own; `python -X utf8 @@ROUTE_JUDGE@@` is renamed above
RULE_BEGIN = '<!-- agentcompass:begin -->'
RULE_END = '<!-- agentcompass:end -->'
# What an earlier release's rule block held and a current render never does (an overlay's words are carried through
# `upgrade_host_rule_text`, and the retired placeholder is refused); a name the user wrote in prose stays in the block.
STALE_RULE_TOKENS = (*HOST_RULE_UPGRADES, RETIRED_PLACEHOLDER)
LEGACY_HOOK_TOKENS = (
    'route-agent-work',
    'cli/_internal/agentcompass/data/setup/router_gate_hook.py',
    'ROUTER_WORKER',
    'ROUTER_PASEO_LEGACY_NO_LABELS',
    'ROUTER_ACCOUNTS_OVERRIDE',
)
OBSOLETE_USAGE_CONFIG_KEYS = (
    'llm_proxy_timezone',
    'llm_proxy_budget_duration',
    'llm_proxy_api_key',
    'llm_proxy_endpoint',
    'llm_proxy_provider_id',
    'litellm_proxies',
)
_RESET_METER_FIELDS = (
    'windows',
    'capacity_usd',
    'burn_pct_per_worker_hour',
    'burn_basis',
    'budget_duration',
    'timezone',
)
_OLD_PROXY_KINDS = frozenset({'litellm', 'proxy', 'api-proxy'})


def fix_delete(path: Path | str, discards: str | None = None) -> str:
    """The delete fix; `discards` says what the user loses by it when the file holds something they chose."""
    return f'delete "{path}"' + (f' ({discards})' if discards else '')


def format_issue(path: Path | str, detail: str, fix: str) -> str:
    return f'{path}: {detail}. Fix: {fix}.'


def _env(environ: dict | None) -> dict:
    return os.environ if environ is None else environ


def state_dir(home: Path | None = None, environ: dict | None = None) -> Path:
    env = _env(environ)
    configured = str(env.get('ROUTER_STATE_DIR') or '').strip()
    if configured:
        return Path(os.path.expandvars(configured)).expanduser()
    base = Path(home) if home is not None else Path.home()
    return base / '.agent-compass'


def legacy_meter_field_names(spec) -> list[str]:
    """Obsolete meter fields on a dollar account or an old proxy identity.

    Subscription windows are not these fields. The names are an error to clean,
    not values to read.
    """
    if not isinstance(spec, dict):
        return []
    found = [key for key in _RESET_METER_FIELDS if key in spec]
    if isinstance(spec.get('litellm'), dict):
        found.append('litellm')
    kind = str(spec.get('backend_kind') or '').strip().lower()
    if kind in _OLD_PROXY_KINDS:
        found.append(f'backend_kind={kind}')
    if not found:
        return []
    billing = str(spec.get('billing') or '').strip().lower()
    endpoint = str(spec.get('endpoint') or '').strip()
    api_key = spec.get('api_key')
    has_key = isinstance(api_key, str) and bool(api_key.strip())
    dollar = billing == 'metered' and bool(endpoint or has_key)
    old_identity = kind in _OLD_PROXY_KINDS or isinstance(spec.get('litellm'), dict)
    if not dollar and not old_identity:
        return []
    return found


def strip_legacy_meter_fields(spec) -> list[str]:
    """Delete leftover meter fields from one account. Returns the names removed."""
    names = legacy_meter_field_names(spec)
    if not isinstance(spec, dict):
        return []
    for name in names:
        if name == 'litellm' or name.startswith('backend_kind'):
            spec.pop('litellm' if name == 'litellm' else 'backend_kind', None)
        else:
            spec.pop(name, None)
    return names


def strip_legacy_meter_document(doc) -> list[str]:
    """Delete leftover meter fields and a top-level litellm_proxies section."""
    if not isinstance(doc, dict):
        return []
    removed = []
    accounts = doc.get('accounts')
    if isinstance(accounts, dict):
        for name, spec in accounts.items():
            fields = strip_legacy_meter_fields(spec)
            if fields:
                removed.append(f'{name}: {", ".join(fields)}')
    if 'litellm_proxies' in doc:
        doc.pop('litellm_proxies', None)
        removed.append('litellm_proxies')
    return removed


def legacy_meter_issues(doc) -> list[str]:
    """Doctor text for leftover meter fields. Empty when the document is clean."""
    if not isinstance(doc, dict):
        return []
    issues = []
    accounts = doc.get('accounts')
    if isinstance(accounts, dict):
        for name, spec in accounts.items():
            fields = legacy_meter_field_names(spec)
            if fields:
                issues.append(f"account {name!r} {LEGACY_METER_REASON} ({', '.join(fields)})")
    if 'litellm_proxies' in doc:
        issues.append(f'older accounts-override field litellm_proxies is not read. {LEGACY_METER_REASON}')
    return issues


def obsolete_usage_config_keys(doc) -> list[str]:
    if not isinstance(doc, dict):
        return []
    return [key for key in OBSOLETE_USAGE_CONFIG_KEYS if key in doc]


def usage_config_issue(path: Path | str, keys) -> str:
    listed = ', '.join(keys)
    return format_issue(
        path,
        f'usage config still has llm-proxy settings that no longer apply ({listed}). {LEGACY_SETTINGS_REASON}',
        FIX_SETUP,
    )


def clear_obsolete_usage_file(path: Path) -> list[str]:
    """Drop leftover llm-proxy keys from one settings file. Every other key stays."""
    if not path.is_file():
        return []
    try:
        doc = json.loads(path.read_text(encoding='utf-8-sig'))
    except (OSError, UnicodeError, ValueError):
        return []
    if not isinstance(doc, dict):
        return []
    keys = obsolete_usage_config_keys(doc)
    if not keys:
        return []
    for key in keys:
        doc.pop(key, None)
    path.write_text(json.dumps(doc, indent=2, ensure_ascii=False) + '\n', encoding='utf-8', newline='\n')
    return keys


def check_usage_config(path: Path) -> str | None:
    if not path.exists():
        return None
    try:
        raw = path.read_text(encoding='utf-8-sig')
    except (OSError, UnicodeError):
        return None
    try:
        doc = json.loads(raw)
    except ValueError:
        return None
    keys = obsolete_usage_config_keys(doc)
    if not keys:
        return None
    return usage_config_issue(path, keys)


def check_accounts_override(path: Path) -> str | None:
    if not path.exists():
        return None
    import accounts_override
    try:
        doc = accounts_override.load_override(path)
    except ValueError as exc:
        return str(exc)
    flagged = [name for name, spec in (doc.get('accounts') or {}).items() if spec.get('verified') is False]
    leftover = legacy_meter_issues(doc)
    problems = [f'legacy disabled flag remains for {name}' for name in flagged] + leftover
    if not problems:
        return None
    # A tray toggle clears a leftover verified flag; only setup clears leftover meter fields (and both).
    fix = FIX_SETUP if leftover else f'toggle {", ".join(flagged)} in the tray or {FIX_SETUP}'
    return format_issue(path, '; '.join(problems), fix)


def host_policy_fix(path: Path | str) -> str:
    return ('edit the file to a JSON object with "allowed_accounts" (a list of account names) and, if wanted, '
            '"known_accounts", "usage_providers" (lists of names), or '
            + fix_delete(path, 'this discards which accounts take part in automatic routing on this machine; every '
                               'account does again until you set them in the tray'))


def validate_host_policy_doc(doc, path: Path | str) -> dict:
    if not isinstance(doc, dict) or 'allowed_accounts' not in doc:
        raise ValueError(format_issue(
            path, 'host-policy configuration requires allowed_accounts', host_policy_fix(path),
        ))
    unknown = sorted(set(doc) - HOST_POLICY_KEYS)
    if unknown:
        raise ValueError(format_issue(
            path, f'host-policy configuration has unsupported fields ({", ".join(unknown)})', host_policy_fix(path),
        ))
    for key, value in doc.items():
        if not isinstance(value, list) or any(not isinstance(v, str) or not v or v != v.strip() for v in value):
            raise ValueError(format_issue(
                path, f'host-policy configuration {key} must be a list of nonempty names', host_policy_fix(path),
            ))
    return doc


def check_host_policy(path: Path) -> str | None:
    if not path.exists():
        return None
    try:
        raw = path.read_text(encoding='utf-8-sig')
    except UnicodeError:
        return format_issue(path, 'host-policy configuration must be UTF-8', host_policy_fix(path))
    except OSError as exc:
        return format_issue(path, f'host-policy configuration unreadable ({exc})', host_policy_fix(path))
    try:
        doc = json.loads(raw)
    except ValueError:
        return format_issue(path, 'host-policy configuration invalid JSON', host_policy_fix(path))
    try:
        validate_host_policy_doc(doc, path)
    except ValueError as exc:
        return str(exc)
    return None


def check_user_scores(path: Path) -> str | None:
    """The file's shape, and the names in it that resolve to no row of the shipped catalog: those entries are kept and
    ignored for scoring (user_scores.apply_overlay), and named here once."""
    if not path.exists():
        return None
    import public_data
    import user_scores
    try:
        doc = user_scores.load_local(path)
    except ValueError as exc:
        return str(exc)
    try:
        accounts = public_data.document(user_scores.REFERENCES / 'accounts.json')
    except (OSError, ValueError):
        return None
    unknown = user_scores.unresolved_models(doc, accounts)
    if not unknown:
        return None
    return format_issue(path, 'scores kept but ignored: no model of this name in the catalog (' + ', '.join(unknown) + ')',
                        "move each score to the model's current name with `agentcompass score set` and clear the old one "
                        'with `agentcompass score clear`, or leave it until the model is in the catalog')


def upgrade_host_rule_text(text: str) -> str:
    """An overlay an earlier release accepted, in today's words; the file itself is the user's and is never rewritten."""
    for old, new in HOST_RULE_UPGRADES.items():
        text = text.replace(old, new)
    return text


def overlay_fix(path: Path) -> str:
    return (f'edit the overlay: replace {RETIRED_PLACEHOLDER} with `@@AGENTCOMPASS@@` (the command), or '
            + fix_delete(path, 'this discards your overlay: the shipped default rules are used instead'))


def read_host_rule_file(path: Path) -> str:
    """The text of one ``host-rules`` overlay carried into the current names (`upgrade_host_rule_text`). The overlay is
    the user's own text, so a name mentioned in it is left as written. Raises ``ValueError`` for a file that is
    unreadable or still uses the retired placeholder, which cannot be rendered."""
    try:
        text = path.read_bytes().decode('utf-8-sig')    # bytes, not text mode: the overlay keeps its line endings
    except (OSError, UnicodeError) as exc:
        raise ValueError(format_issue(path, f'host-rules file unreadable ({exc})', overlay_fix(path))) from exc
    text = upgrade_host_rule_text(text)
    if RETIRED_PLACEHOLDER in text:
        raise ValueError(format_issue(
            path, f'host-rules overlay uses the placeholder {RETIRED_PLACEHOLDER}, which has no current meaning',
            overlay_fix(path),
        ))
    return text


def check_host_rule_file(path: Path) -> str | None:
    if not path.exists():
        return None
    try:
        read_host_rule_file(path)
    except ValueError as exc:
        return str(exc)
    return None


def _validate_profile(profile) -> None:
    import task_intake
    task_intake.validate_profile(profile)


def row_has_old_profile(row: dict) -> bool:
    """True when a ledger row carries a task profile that fails the four-category schema."""
    if not isinstance(row, dict):
        return False
    snap = row.get('decision_snapshot')
    if isinstance(snap, dict):
        snap_task = snap.get('task')
        if isinstance(snap_task, dict) and 'profile' in snap_task and snap_task['profile'] is not None:
            try:
                _validate_profile(snap_task['profile'])
            except ValueError:
                return True
    if 'profile' in row and row['profile'] is not None:
        try:
            _validate_profile(row['profile'])
        except ValueError:
            return True
    return False


def check_dispatch_db(path: Path) -> str | None:
    """Only a database sqlite cannot read. One an older version made is not a fault: missing tables are created on use
    (`dispatch_registry.transaction`) and a decision recorded under an older task profile is refused on its own
    (`dispatch_registry.prepare`) without touching the rest."""
    if not path.exists():
        return None
    try:
        uri = path.resolve().as_uri() + '?mode=ro'
        conn = sqlite3.connect(uri, uri=True, timeout=1.0)
    except (OSError, sqlite3.Error) as exc:
        return format_issue(path, f'dispatch database unreadable ({exc})', _dispatch_db_fix(path))
    try:
        conn.execute("SELECT name FROM sqlite_master").fetchall()
    except sqlite3.Error as exc:
        return format_issue(path, f'dispatch database corrupt ({exc})', _dispatch_db_fix(path))
    finally:
        conn.close()
    return None


def _dispatch_db_fix(path: Path) -> str:
    return fix_delete(path, 'this discards the recorded decisions and the reservations of workers still running; '
                            'a new database is created on the next dispatch')


def _overrides_fix(path: Path) -> str:
    return fix_delete(path, 'this discards the temporary priorities it holds')


def check_provider_inventory(path: Path) -> str | None:
    if not path.exists():
        return None
    import provider_inventory
    try:
        provider_inventory.previous_inventory(path)
    except ValueError as exc:
        return str(exc)
    return None


def check_router_overrides(path: Path) -> str | None:
    if not path.exists():
        return None
    try:
        doc = json.loads(path.read_text(encoding='utf-8-sig'))
    except (OSError, UnicodeError, ValueError) as exc:
        return format_issue(path, f'router overrides invalid JSON ({exc})', _overrides_fix(path))
    if not isinstance(doc, dict):
        return format_issue(path, 'router overrides must be a JSON object', _overrides_fix(path))
    rows = doc.get('overrides')
    if rows is not None and not isinstance(rows, list):
        return format_issue(path, 'router overrides.overrides must be a JSON array', _overrides_fix(path))
    for item in rows or ():
        if not isinstance(item, dict):
            return format_issue(path, 'router override entry must be a JSON object', _overrides_fix(path))
    return None


def _check_global_rule_text(path: Path | str, text: str) -> str | None:
    if RULE_BEGIN in text and RULE_END in text:
        start = text.index(RULE_BEGIN)
        end = text.index(RULE_END, start) + len(RULE_END)
        managed = text[start:end]
        found = [tok for tok in STALE_RULE_TOKENS if tok in managed]
        if found:
            return format_issue(
                path,
                f'managed global rule block contains older token(s): {", ".join(found)}',
                FIX_SETUP,
            )
        return None
    stripped = text.strip()
    if stripped.startswith('# Agent Routing (Global)') or RETIRED_PLACEHOLDER in text or 'route-agent-work' in text:
        return format_issue(
            path,
            'older un-markered global routing rule block',
            FIX_SETUP,
        )
    return None


def check_hooks_and_rules(home: Path, environ: dict | None = None) -> list[str]:
    issues: list[str] = []
    hook_files = [
        home / '.claude' / 'settings.json',
        home / '.codex' / 'hooks.json',
        home / '.gemini' / 'config' / 'hooks.json',
        home / '.pi' / 'agent' / 'extensions' / 'router-gate.ts',
        home / '.config' / 'opencode' / 'plugins' / 'router-gate.js',
    ]
    for pattern, filename in (('.claude-*', 'settings.json'), ('.codex-*', 'hooks.json')):
        try:
            dirs = sorted(p for p in home.glob(pattern) if p.is_dir())
        except OSError:
            dirs = []
        for d in dirs:
            hook_files.append(d / filename)

    bundled = None
    try:
        from agentcompass import install
        bundled = install.bundled_cli(environ)
    except Exception:
        bundled = None

    for hpath in hook_files:
        if not hpath.is_file():
            continue
        try:
            text = hpath.read_text(encoding='utf-8', errors='replace')
        except OSError as exc:
            issues.append(format_issue(hpath, f'hook configuration unreadable ({exc})', FIX_SETUP))
            continue
        norm = text.replace('\\\\', '/').replace('\\', '/')
        bad_tokens = [tok for tok in LEGACY_HOOK_TOKENS if tok in norm]
        if bad_tokens:
            issues.append(format_issue(
                hpath, f'installed hook references older path/variable ({", ".join(bad_tokens)})', FIX_SETUP,
            ))
            continue
        if ('router_gate_hook.py' in norm or 'gate-hook' in norm) and bundled is not None:
            if str(bundled).replace('\\', '/').lower() not in norm.lower():
                issues.append(format_issue(
                    hpath, 'installed hook does not use the bundled agentcompass.exe', FIX_SETUP,
                ))

    rule_files = [
        home / '.claude' / 'CLAUDE.md',
        home / '.codex' / 'AGENTS.md',
        home / '.gemini' / 'GEMINI.md',
        home / '.gemini' / 'config' / 'GEMINI.md',
        home / '.pi' / 'agent' / 'AGENTS.md',
        home / '.config' / 'opencode' / 'AGENTS.md',
    ]
    for pattern, filename in (('.claude-*', 'CLAUDE.md'), ('.codex-*', 'AGENTS.md')):
        try:
            dirs = sorted(p for p in home.glob(pattern) if p.is_dir())
        except OSError:
            dirs = []
        for d in dirs:
            rule_files.append(d / filename)

    for rpath in rule_files:
        if not rpath.is_file():
            continue
        try:
            text = rpath.read_text(encoding='utf-8', errors='replace')
        except OSError:
            continue
        issue = _check_global_rule_text(rpath, text)
        if issue:
            issues.append(issue)

    env = _env(environ)
    paseo_home = Path(env.get('PASEO_HOME') or (home / '.paseo'))
    paseo_cfg = paseo_home / 'config.json'
    if paseo_cfg.is_file():
        try:
            pdoc = json.loads(paseo_cfg.read_text(encoding='utf-8-sig'))
            prompt = ((pdoc.get('daemon') or {}).get('appendSystemPrompt')) if isinstance(pdoc, dict) else None
            if isinstance(prompt, str) and prompt:
                issue = _check_global_rule_text(paseo_cfg, prompt)
                if issue:
                    issues.append(issue)
        except (OSError, UnicodeError, ValueError):
            pass

    skill_roots = [
        home / '.claude' / 'skills',
        home / '.codex' / 'skills',
        home / '.agents' / 'skills',
        home / '.gemini' / 'skills',
    ]
    for pattern in ('.claude-*', '.codex-*'):
        try:
            dirs = sorted(p for p in home.glob(pattern) if p.is_dir())
        except OSError:
            dirs = []
        for d in dirs:
            skill_roots.append(d / 'skills')
    for sroot in skill_roots:
        old_skill = sroot / 'route-agent-work'
        if old_skill.exists() or old_skill.is_symlink():
            # Setup retires only the links its own manifest records; this one predates the manifest.
            issues.append(format_issue(
                old_skill, 'older skill link route-agent-work (renamed to agent-compass)', fix_delete(old_skill),
            ))
        cur_skill = sroot / 'agent-compass'
        try:
            if cur_skill.exists() or cur_skill.is_symlink():
                resolved = str(cur_skill.resolve()).replace('\\', '/')
                if 'cli/_internal/agentcompass/data/skills' in resolved or not (cur_skill / 'SKILL.md').is_file():
                    issues.append(format_issue(
                        cur_skill, 'skill link points to an older or missing install layout', FIX_SETUP,
                    ))
        except OSError:
            issues.append(format_issue(cur_skill, 'broken skill link', FIX_SETUP))

    return issues


def collect_issues(home: Path | None = None, environ: dict | None = None) -> list[str]:
    """Return per-file upgrade instructions for any old-shape local state. Never writes."""
    env = _env(environ)
    base_home = Path(home) if home is not None else Path.home()
    sdir = state_dir(base_home, env)
    issues: list[str] = []

    override_env = str(env.get('AGENTCOMPASS_ACCOUNTS_OVERRIDE') or '').strip()
    accounts_path = Path(os.path.expandvars(override_env)).expanduser() if override_env else sdir / 'accounts-override.json'
    policy_env = str(env.get('ROUTER_HOST_POLICY') or '').strip()
    policy_path = Path(os.path.expandvars(policy_env)).expanduser() if policy_env else sdir / 'host-policy.json'
    db_env = str(env.get('ROUTER_DISPATCH_DB') or '').strip()
    db_path = Path(os.path.expandvars(db_env)).expanduser() if db_env else sdir / 'dispatch.sqlite3'
    overrides_env = str(env.get('ROUTER_OVERRIDES') or '').strip()
    overrides_path = Path(os.path.expandvars(overrides_env)).expanduser() if overrides_env else sdir / 'router-overrides.json'

    for issue in (
        check_accounts_override(accounts_path),
        check_usage_config(sdir / 'usage-config.json'),
        check_host_policy(policy_path),
        check_user_scores(sdir / 'user-scores.json'),
        check_dispatch_db(db_path),
        check_router_overrides(overrides_path),
        check_provider_inventory(sdir / 'provider-inventory.json'),
    ):
        if issue:
            issues.append(issue)

    for name in HOST_RULE_OVERLAYS:
        issue = check_host_rule_file(sdir / 'host-rules' / name)
        if issue:
            issues.append(issue)

    issues.extend(check_hooks_and_rules(base_home, env))
    return issues
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