OrCa smoke run debugger
Overview
Get the first OrCa task to run successfully before spending effort on tuning or real specs.
Required references
Read ../references/campaign-state-and-autonomy.md and the dummy spec section of ../references/specs-and-counterexamples.md.
Sub-agent use
Use a sub-agent for long task logs, verbose local deployment output, or source-heavy setup failure diagnosis. The sub-agent should classify the failure, cite the key log lines or source references, and return the smallest viable fix or next diagnostic step. Keep run submission, permission checks, AuditHub version selection, and ledger updates in the main orchestrator unless explicitly delegated with the current ledger and gates.
Workflow
- Ensure a placeholder spec exists when no real [V] specs exist:
vars: uint a
spec: []!finished(*, False)
- Use default OrCa parameters for the first task; set timeout to 60-120 seconds unless the user specified otherwise.
- Before running, enforce the autonomy gates from
run_ledger.json.
- If an AuditHub OrCa task fails, fetch the task logs for that specific task before changing campaign parameters.
- If a local run fails, inspect local logs before changing campaign parameters.
- For local deployment failures, reproduce or inspect deployment under a local Anvil-style chain when practical.
- For live-state failures, validate chain, block, address, proxy ABI, and on-chain deployment JSON formatting.
- If the on-chain deployment JSON has a trimmed ABI, restore the full ABI for each fuzzed contract before retrying; never keep only the functions that seem immediately relevant.
- Record the run attempt and log-derived diagnosis in
orca_config/run_ledger.json.
- Before the first run, sanity-check campaign shape:
fuzz_targets must list contract names, not function selectors, and function-level narrowing belongs in fuzzing_blacklist.
- Before any new remote submission, run a submit-readiness gate over the
current deployment path, archive inputs, and spec set. Confirm that every
referenced file exists at the intended relative path and that OrCa can
recover deployed addresses from the chosen framework's artifacts.
- For local deployments, run or inspect the deployment script locally when
practical before submitting. A reproducible local setup failure is a local
blocker, not a reason to spend another remote run.
- For Foundry local deployments, a script that merely returns deployed
addresses is not submit-ready by itself; prefer a standard script/broadcast
flow or another machine-readable artifact shape that OrCa can parse instead
of relying on a human to copy values out of stdout or return data.
- If the submit-readiness gate fails for a locally diagnosable reason, record
the blocker and repair it before consuming another submitted run.
Task patience
The first OrCa task is often slow to finish. Treat it as potentially running for at least the configured timeout, plus extra minutes for task setup work such as source fetching, deployment, and ABI extraction. Do not declare it failed or stop checking too early just because the status has not changed yet. Use spaced-out status checks rather than frequent polling unless logs or task status clearly indicate failure.
Failure classification
deployment: constructor, initializer, mock, role, balance, approval, artifact, or local-chain issue.onchain_config: malformed JSON, wrong ABI, wrong chain/block, bad proxy handling, missing address.orca_config: invalid paths, missing spec, unsupported parameter, bad target name, or an empty transaction set caused by incorrect target/filter shape.environment: credentials, RPC, AuditHub task setup, dependency installation, or command availability.fuzzing: OrCa started and fuzzed but hit runtime behavior that should be analyzed through call metrics.
Do not proceed into tuning until at least one OrCa task reaches the fuzzing stage successfully.
1---2name: audithub-orca-smoke-run-debugger3description: Create dummy OrCa specs, perform or inspect short initial OrCa smoke runs, and debug setup failures. Use when a campaign needs the universal dummy spec, a first 1-2 minute run, diagnosis of failed local deployment scripts, diagnosis of malformed on-chain deployment JSON, or run-ledger updates for early OrCa attempts.4---56# OrCa smoke run debugger78## Overview910Get the first OrCa task to run successfully before spending effort on tuning or real specs.1112## Required references1314Read `../references/campaign-state-and-autonomy.md` and the dummy spec section of `../references/specs-and-counterexamples.md`.1516## Sub-agent use1718Use a sub-agent for long task logs, verbose local deployment output, or source-heavy setup failure diagnosis. The sub-agent should classify the failure, cite the key log lines or source references, and return the smallest viable fix or next diagnostic step. Keep run submission, permission checks, AuditHub version selection, and ledger updates in the main orchestrator unless explicitly delegated with the current ledger and gates.1920## Workflow21221. Ensure a placeholder spec exists when no real [V] specs exist:2324```text25vars: uint a26spec: []!finished(*, False)27```28292. Use default OrCa parameters for the first task; set timeout to 60-120 seconds unless the user specified otherwise.303. Before running, enforce the autonomy gates from `run_ledger.json`.314. If an AuditHub OrCa task fails, fetch the task logs for that specific task before changing campaign parameters.325. If a local run fails, inspect local logs before changing campaign parameters.336. For local deployment failures, reproduce or inspect deployment under a local Anvil-style chain when practical.347. For live-state failures, validate chain, block, address, proxy ABI, and on-chain deployment JSON formatting.358. If the on-chain deployment JSON has a trimmed ABI, restore the full ABI for each fuzzed contract before retrying; never keep only the functions that seem immediately relevant.369. Record the run attempt and log-derived diagnosis in `orca_config/run_ledger.json`.3710. Before the first run, sanity-check campaign shape: `fuzz_targets` must list contract names, not function selectors, and function-level narrowing belongs in `fuzzing_blacklist`.3811. Before any new remote submission, run a submit-readiness gate over the39 current deployment path, archive inputs, and spec set. Confirm that every40 referenced file exists at the intended relative path and that OrCa can41 recover deployed addresses from the chosen framework's artifacts.4212. For local deployments, run or inspect the deployment script locally when43 practical before submitting. A reproducible local setup failure is a local44 blocker, not a reason to spend another remote run.4513. For Foundry local deployments, a script that merely returns deployed46 addresses is not submit-ready by itself; prefer a standard script/broadcast47 flow or another machine-readable artifact shape that OrCa can parse instead48 of relying on a human to copy values out of stdout or return data.4914. If the submit-readiness gate fails for a locally diagnosable reason, record50 the blocker and repair it before consuming another submitted run.5152## Task patience5354The first OrCa task is often slow to finish. Treat it as potentially running for at least the configured timeout, plus extra minutes for task setup work such as source fetching, deployment, and ABI extraction. Do not declare it failed or stop checking too early just because the status has not changed yet. Use spaced-out status checks rather than frequent polling unless logs or task status clearly indicate failure.5556## Failure classification5758- `deployment`: constructor, initializer, mock, role, balance, approval, artifact, or local-chain issue.59- `onchain_config`: malformed JSON, wrong ABI, wrong chain/block, bad proxy handling, missing address.60- `orca_config`: invalid paths, missing spec, unsupported parameter, bad target name, or an empty transaction set caused by incorrect target/filter shape.61- `environment`: credentials, RPC, AuditHub task setup, dependency installation, or command availability.62- `fuzzing`: OrCa started and fuzzed but hit runtime behavior that should be analyzed through call metrics.6364Do not proceed into tuning until at least one OrCa task reaches the fuzzing stage successfully.
Veridise