solidity-argus 0.3.4 → 0.3.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "solidity-argus",
-  "version": "0.3.4",
+  "version": "0.3.6",
   "description": "Solidity smart contract security auditing plugin for OpenCode — 4 specialized agents, 12 tools (11 core + optional Solodit), and a curated vulnerability knowledge base",
   "keywords": [
     "solidity",
@@ -25,8 +25,8 @@
     "./package.json": "./package.json"
   },
   "bin": {
-    "solidity-argus": "./src/cli/index.ts",
-    "argus": "./src/cli/index.ts"
+    "solidity-argus": "src/cli/index.ts",
+    "argus": "src/cli/index.ts"
   },
   "files": [
     "src/",
@@ -66,7 +66,7 @@
   },
   "repository": {
     "type": "git",
-    "url": "https://github.com/Apegurus/solidity-argus"
+    "url": "git+https://github.com/Apegurus/solidity-argus.git"
   },
   "engines": {
     "bun": ">=1.0.0"

package/src/agents/argus-prompt.ts

@@ -225,6 +225,52 @@ Task(subagent_type="scribe", prompt="Generate the final audit report for Project
   \`\`\`
 - Wait for both to complete before synthesizing their results.
 
+### STATE-FIRST SYNTHESIS POLICY
+
+**Synthesize and report from durable evidence — not transcript tails.**
+
+When building the final report or synthesizing findings:
+1. **Primary source**: \`toolsExecuted\` records, \`findings\` from state, and event stream data persisted via argus_* tool outputs.
+2. **Secondary source**: Tool transcript text (use only when durable evidence is unavailable or incomplete).
+3. **Never** synthesize findings from ephemeral background transcript retrieval alone if durable state evidence exists.
+4. **Manual-finding durability**: If Argus, Sentinel, or Pythia identifies a finding outside analyzer tool payloads, they must call \
+   \`argus_record_finding\` before proceeding.
+5. **Report parity rule**: Scribe must not include findings in \`report_input\` unless they are event-backed (recorded via tools/events).
+
+**Bounded background fan-out**: For deep audits, limit concurrent high-context background delegations to max 2 at a time. Split larger workloads into sequential waves. This prevents retrieval blind spots from simultaneous long-running tasks.
+
+Example — correct fan-out:
+- Wave 1: [Sentinel: slither + pattern check] + [Pythia: solodit search] (2 background tasks)
+- Wait for both. Then Wave 2: [Sentinel: forge tests] (1 background task)
+
+## SYNTHESIS BARRIER: MUST NOT PROCEED WITHOUT DURABLE EVIDENCE
+
+You **must not proceed** to synthesis or report generation until required durable evidence is confirmed present:
+- \`toolsExecuted\` records exist for all planned tools
+- Expected findings coverage is populated in state
+- Lifecycle invariants are satisfied (no orphaned tool starts)
+
+### Adaptive Retrieval Budget
+
+When waiting for background tasks, use bounded retrieval budgets by workload class:
+
+| Class    | Budget  | Criteria                                    |
+|----------|---------|---------------------------------------------|
+| quick    | 60s     | Single-tool or single-contract checks       |
+| standard | 180s    | Multi-tool single-agent batches             |
+| deep     | 600s    | Multi-agent or synthesis-heavy runs         |
+
+Poll until the task reaches a terminal state: \`completed\`, \`error\`, \`cancelled\`, or \`interrupt\`.
+
+### Re-dispatch (LAST RESORT)
+
+Re-dispatch is only justified when ALL of these are true:
+1. The task has reached terminal state OR retrieval budget has expired
+2. Required durable evidence is STILL missing from state/events
+3. The gap is specific and bounded (not a general "redo everything")
+
+**When re-dispatching**: Target only missing evidence segments. Use \`run_in_background=false\` (foreground only) for re-dispatch pivots. Do NOT re-dispatch routinely after a single transcript retrieval miss if durable state evidence is already complete.
+
 ## TASK COMPLETION TRACKING
 
 You must track which audit phases are complete to avoid redundant work and tool re-execution.
@@ -272,7 +318,12 @@ Your subagents have access to these specialized tools. Know when to delegate eac
 - **\`argus_generate_report\`**:
   - **Use**: During Reporting.
   - **Purpose**: Generates the final artifact.
-  - **Note**: Requires a versioned report_input JSON string matching the ReportInput contract (schema_version 1.0.0). Do not send natural-language-only findings to Scribe for tool invocation.
+  - **Note**: Requires a versioned report_input JSON string matching the ReportInput contract (schema_version 2.0.0). Do not send natural-language-only findings to Scribe for tool invocation.
+
+- **\`argus_record_finding\`**:
+  - **Use**: Whenever a manual/non-tool finding is identified.
+  - **Purpose**: Persist manually identified findings as canonical event-backed observations before reporting.
+  - **Note**: Accepts a single finding or an array. Call it immediately when the finding is identified.
 
 - **\`argus_sync_knowledge\`**:
   - **Use**: Maintenance.
@@ -424,6 +475,8 @@ Tools may fail. You must be resilient.
 
 After you have synthesized your findings, build a canonical ReportInput payload and invoke Scribe:
 
+**State-first requirement**: Before invoking Scribe, verify that \`toolsExecuted\` in your ReportInput contains entries for each tool you ran. Do NOT proceed to report generation if required tool coverage is missing from durable state — re-run the missing tool instead. Use \`preflight_policy: "strict-fail"\` for the final report invocation.
+
 \`\`\`
 Task(subagent_type="scribe", prompt="Generate the final security audit report.
 
@@ -436,7 +489,7 @@ ReportInput JSON (pass EXACTLY, no prose substitution):
   "session_id": "{session-id}",
   "tool_call_id": "{tool-call-id}",
   "source": "argus",
-  "schema_version": "1.0.0",
+  "schema_version": "2.0.0",
   "projectDir": "{project-dir}",
   "findings": [canonical findings],
   "toolsExecuted": [canonical tool executions],
@@ -454,6 +507,7 @@ Scribe must call argus_generate_report with:
 - project_name: project name
 - scope: audited file list
 - report_input: serialized ReportInput JSON string
+- preflight_policy: "strict-fail" (non-negotiable for final report)
 
 Legacy audit_state is transitional-only and deprecated.
 

package/src/agents/pythia-prompt.ts

@@ -49,6 +49,7 @@ You must follow this structured research process:
 ### 4. Reporting
 - **Objective**: Deliver actionable intelligence to Argus.
 - **Actions**:
+  - If you identify a manual finding from precedent/pattern reasoning, call \`argus_record_finding\` before reporting back.
   - Format findings clearly, citing the precedent (e.g., "Similar to the Cream Finance hack").
   - Assess severity based on the *likelihood* of exploitation in this specific context.
 
@@ -84,6 +85,16 @@ You have two primary tools. Master them.
 - Returns a list of matches with line numbers.
 - **Crucial**: You must verify the context. A regex match for \`selfdestruct\` is not a bug if it's in a test file or a legitimate upgrade mechanism (though still risky).
 
+### 3. \`argus_record_finding\`
+**Purpose**: Persist research/manual findings into durable event-backed observations.
+**When to use**:
+- Whenever your finding is derived from precedent analysis or manual reasoning rather than a direct analyzer payload.
+**Arguments**:
+- \`finding\` (string): Serialized JSON object for one finding.
+- \`findings\` (string): Serialized JSON array for multiple findings.
+**Interpretation**:
+- A finding is not report-ready until it has been recorded through this tool.
+
 ## EMPTY RESULTS STRATEGY
 
 When \`argus_solodit_search\` returns zero results for a query:

package/src/agents/scribe-prompt.ts

@@ -44,10 +44,15 @@ You must adhere to these strict writing standards:
 Argus passes you structured report data. Use that payload directly and keep it schema-accurate.
 
 **Your workflow**:
-1. Validate Argus provided a serialized ReportInput JSON string (schema_version 1.0.0) with required fields: run_id, seq, session_id, tool_call_id, source, schema_version, projectDir, findings, toolsExecuted, scope.
-2. Write the complete report in Markdown following the Report Structure and Output Format sections.
-3. Call \`argus_generate_report\` with arguments { project_name, scope, report_input }. Use legacy \`audit_state\` only for transitional compatibility and treat it as deprecated.
-4. Confirm the report was generated in your response to Argus: "Report generated via argus_generate_report: {filePath}".
+1. Validate Argus provided a serialized ReportInput JSON string (schema_version 2.0.0) with required fields: run_id, seq, session_id, tool_call_id, source, schema_version, projectDir, findings, toolsExecuted, scope. **Execution integrity check**: \`toolsExecuted\` must be non-empty for the audit to be considered complete. If \`toolsExecuted\` is empty or missing key tool families (slither, forge, patterns), add a \`## Limitations\` section to the report noting which tool coverage is absent.
+2. Enforce parity: do not include findings unless they are event-backed observations (recorded through tool/event flow, including \`argus_record_finding\`).
+3. Write the complete report in Markdown following the Report Structure and Output Format sections.
+4. Call \`argus_generate_report\` with arguments { project_name, scope, report_input }. Use legacy \`audit_state\` only for transitional compatibility and treat it as deprecated.
+5. **Limitations disclosure** (MANDATORY when tools fail): If any tool was unavailable, timed out, or failed, add a \`## Limitations\` section to the report BEFORE \`## Findings\`. Use this format:
+   - \`**Tool name**: [reason \u2014 unavailable/failed/timed out]. [Impact on finding coverage if any.]\`
+   - Example: \`**argus_solodit_search**: External database was unavailable. Known-vulnerability cross-referencing was performed using local patterns only.\`
+   - Never silently omit limitations — incomplete coverage must be disclosed.
+6. Confirm the report was generated in your response to Argus: "Report generated via argus_generate_report: {filePath}".
 
 ## SINGLE-WRITER POLICY
 

package/src/agents/sentinel-prompt.ts

@@ -32,6 +32,7 @@ You operate in a loop of **Scan -> Analyze -> Verify**.
 
 4.  **Reporting**:
      - Format your findings strictly according to the Output Format section.
+     - If you identify a manual finding outside analyzer payloads, call \`argus_record_finding\` immediately.
      - Report back to Argus with confirmed findings.
 
 ## POC VERIFICATION
@@ -127,6 +128,15 @@ You have access to a specific set of tools. Use them effectively.
 - High gas consumption often correlates with complex logic, unbounded loops, or storage-heavy operations.
 - Gas hotspots are prime candidates for DoS vulnerabilities.
 
+### 9. \`argus_record_finding\`
+**Purpose**: Persist manual/non-tool findings as canonical event-backed observations.
+**When to use**: Any time you manually confirm a finding that did not come from \`argus_slither_analyze\` or \`argus_check_patterns\` payloads.
+**Arguments**:
+- \`finding\` (string): Serialized JSON object for a single finding.
+- \`findings\` (string): Serialized JSON array for multiple findings.
+**Interpretation**:
+- Recording is mandatory before handing findings to Argus for final synthesis.
+
 ## SKILL SYSTEM
 
 Use \`argus_skill_load\` only when specialized context is needed before deep verification work.

package/src/cli/commands/init.ts

@@ -20,7 +20,7 @@ export const initCommand: CliCommand = {
   description: "Initialize Argus configuration for this project",
   async execute(_args: string[]): Promise<number> {
     const cwd = process.cwd()
-    const configDir = join(cwd, ".opencode")
+    const configDir = join(cwd, ".argus")
     const configPath = join(configDir, "solidity-argus.json")
 
     if (existsSync(configPath)) {

package/src/config/schema.ts

@@ -31,7 +31,7 @@ const ReportingConfigSchema = z.object({
   format: z.enum(["markdown"]).default("markdown"),
   severityThreshold: z.enum(["critical", "high", "medium", "low", "informational"]).default("low"),
   gasAnalysis: z.boolean().default(false),
-  output_dir: z.string().default(".opencode/reports/"),
+  output_dir: z.string().default(".argus/reports/"),
 })
 
 const SoloditConfigSchema = z.object({
@@ -74,7 +74,7 @@ export const ArgusConfigSchema = z.object({
     format: "markdown",
     severityThreshold: "low",
     gasAnalysis: false,
-    output_dir: ".opencode/reports/",
+    output_dir: ".argus/reports/",
   }),
   solodit: SoloditConfigSchema.default({
     enabled: true,

package/src/create-hooks.ts

@@ -1,4 +1,3 @@
-import { join } from "node:path"
 import type { Hooks as PluginHooks } from "@opencode-ai/plugin"
 import type { ArgusConfig } from "./config/types"
 import { createAuditEnforcer } from "./features/audit-enforcer/audit-enforcer"
@@ -7,9 +6,12 @@ import {
   createSessionRecoveryHandler,
   createToolErrorRecoveryHandler,
 } from "./features/error-recovery"
-import { createDebouncedSave } from "./features/persistent-state/audit-state-manager"
 import { getMigrationMode } from "./features/migration"
+import { adaptLegacyFindings } from "./features/migration/migration-adapter"
+import { computeParityMetrics, formatParityReport } from "./features/migration/parity-telemetry"
+import { createDebouncedSave } from "./features/persistent-state/audit-state-manager"
 import { createEventSink, type EventSink } from "./features/persistent-state/event-sink"
+import { materializeFindings } from "./features/persistent-state/findings-materializer"
 import { recordRun } from "./features/persistent-state/global-run-index"
 import { createRunJournal } from "./features/persistent-state/run-journal"
 import { createAgentTracker } from "./hooks/agent-tracker"
@@ -24,8 +26,8 @@ import { createSystemPromptHook } from "./hooks/system-prompt-hook"
 import { createToolTrackingHook } from "./hooks/tool-tracking-hook"
 import type { HookName } from "./hooks/types"
 import type { Managers } from "./managers/types"
-import { createLogger } from "./shared/logger"
 import { createAuditArtifactResolver } from "./shared/audit-artifact-resolver"
+import { createLogger } from "./shared/logger"
 import type { AuditState } from "./state/types"
 import { detectAuditArtifacts } from "./utils/audit-artifact-detector"
 import { detectProject, type ProjectConfig } from "./utils/project-detector"
@@ -135,10 +137,8 @@ export function createHooks(args: {
 
         const effectiveState = recoveredState ?? auditStateManager.get()
         if (effectiveState) {
+          const resolver = createAuditArtifactResolver(effectiveState.sessionId, projectDir)
           try {
-            // createAuditArtifactResolver is the canonical source for all run artifact paths.
-            // The journal file path is: {projectDir}/.opencode/runs/{runId}/events.jsonl
-            const resolver = createAuditArtifactResolver(effectiveState.sessionId, projectDir)
             const journalFile = resolver.paths().journalFile
             // createEventSink builds the same path internally; the resolver makes it explicit.
             currentEventSink = createEventSink(effectiveState.sessionId, projectDir)
@@ -149,13 +149,12 @@ export function createHooks(args: {
               `Failed to create event sink: ${error instanceof Error ? error.message : String(error)}`,
             )
           }
-
           void recordRun({
             runId: effectiveState.sessionId,
             opencodeSessionId: sessionId,
             projectDir: effectiveState.projectDir,
-            statePath: join(effectiveState.projectDir, ".opencode", "argus-state.json"),
-            journalPath: join(effectiveState.projectDir, ".opencode", "argus-journal.jsonl"),
+            statePath: resolver.paths().stateFile,
+            journalPath: resolver.paths().journalFile,
             startedAt: effectiveState.startTime,
             phase: effectiveState.currentPhase,
             findingsCount: effectiveState.findings.length,
@@ -188,17 +187,36 @@ export function createHooks(args: {
           toolsExecutedCount: auditState.toolsExecuted.length,
         })
 
+        const idleResolver = createAuditArtifactResolver(
+          auditState.sessionId,
+          auditState.projectDir,
+        )
         void recordRun({
           runId: auditState.sessionId,
           opencodeSessionId: sessionId,
           projectDir: auditState.projectDir,
-          statePath: join(auditState.projectDir, ".opencode", "argus-state.json"),
-          journalPath: join(auditState.projectDir, ".opencode", "argus-journal.jsonl"),
+          statePath: idleResolver.paths().stateFile,
+          journalPath: idleResolver.paths().journalFile,
           startedAt: auditState.startTime,
           phase: auditState.currentPhase,
           findingsCount: auditState.findings.length,
         })
 
+        if (migrationMode !== "legacy") {
+          try {
+            const { legacyFindings, canonicalFindings } = adaptLegacyFindings(
+              auditState,
+              migrationMode,
+              auditState.sessionId,
+            )
+            const parityMetrics = computeParityMetrics(legacyFindings, canonicalFindings)
+            logger.debug(formatParityReport(parityMetrics))
+          } catch (error) {
+            logger.warn(
+              `Migration parity check failed: ${error instanceof Error ? error.message : String(error)}`,
+            )
+          }
+        }
         return
       }
 
@@ -292,21 +310,82 @@ export function createHooks(args: {
             {
               getEventSink: () => currentEventSink,
               getSessionId: () => currentOpencodeSessionId,
+              getAgentName: () => {
+                if (!currentOpencodeSessionId) {
+                  return undefined
+                }
+
+                const agent = agentTracker.getAgentForSession(currentOpencodeSessionId)
+                if (
+                  agent === "argus" ||
+                  agent === "sentinel" ||
+                  agent === "pythia" ||
+                  agent === "scribe" ||
+                  agent === "unknown"
+                ) {
+                  return agent
+                }
+
+                return "unknown"
+              },
             },
           ),
         "tool-tracking",
       )
     : undefined
 
+  const materializeCurrentFindings = async (
+    trigger: "session.idle" | "tool.execute.after",
+    failFast = false,
+  ): Promise<void> => {
+    const state = getAuditState()
+    if (!state || state.sessionId.length === 0) {
+      return
+    }
+
+    try {
+      await materializeFindings(
+        state.sessionId,
+        state.projectDir,
+        currentOpencodeSessionId.length > 0 ? currentOpencodeSessionId : undefined,
+      )
+    } catch (error) {
+      if (failFast) {
+        throw new Error(
+          `Failed to materialize findings artifact on ${trigger} for run ${state.sessionId}: ${error instanceof Error ? error.message : String(error)}`,
+        )
+      }
+
+      logger.warn(
+        `Failed to materialize findings artifact on ${trigger} for run ${state.sessionId}: ${error instanceof Error ? error.message : String(error)}`,
+      )
+    }
+  }
+
   const safeEventHook = isHookEnabled("event")
     ? safeCreateHook(
         () => async (input: Parameters<typeof eventHook>[0]) => {
           const isSessionDeleted = input.event.type === "session.deleted"
+          const finalizationBeforeDelete = isSessionDeleted ? getLastFinalizationResult() : null
 
           try {
             await eventHook(input)
           } finally {
             if (isSessionDeleted) {
+              const finalizationResult = getLastFinalizationResult()
+              const hasNewFinalization =
+                finalizationResult !== null && finalizationResult !== finalizationBeforeDelete
+
+              if (hasNewFinalization && finalizationResult.runId.length > 0) {
+                try {
+                  await materializeFindings(finalizationResult.runId, projectDir)
+                } catch (error) {
+                  logger.warn(
+                    `Failed to materialize findings artifact for run ${finalizationResult.runId}: ${error instanceof Error ? error.message : String(error)}`,
+                  )
+                }
+              }
+
               await auditStateManager.archive()
 
               const deletedSessionId = input.event.sessionId
@@ -318,7 +397,7 @@ export function createHooks(args: {
                 type: "session.deleted",
                 timestamp: Date.now(),
                 archived: true,
-                finalizationPassed: getLastFinalizationResult()?.invariantsPassed ?? null,
+                finalizationPassed: finalizationResult?.invariantsPassed ?? null,
               })
 
               currentEventSink = null
@@ -360,6 +439,10 @@ export function createHooks(args: {
             result: output.output,
           })
 
+          if (input.tool === "argus_generate_report") {
+            await materializeCurrentFindings("tool.execute.after", true)
+          }
+
           const outputWithHint = recoveryHint ? `${output.output}${recoveryHint}` : output.output
           output.output = outputTruncator(outputWithHint)
         }

package/src/create-tools.ts

@@ -8,6 +8,7 @@ import { forgeTestTool } from "./tools/forge-test-tool"
 import { gasAnalysisTool } from "./tools/gas-analysis-tool"
 import { patternCheckerTool } from "./tools/pattern-checker-tool"
 import { proxyDetectionTool } from "./tools/proxy-detection-tool"
+import { recordFindingTool } from "./tools/record-finding-tool"
 import { reportGeneratorTool } from "./tools/report-generator-tool"
 import { slitherTool } from "./tools/slither-tool"
 import { createSoloditSearchTool } from "./tools/solodit-search-tool"
@@ -24,6 +25,7 @@ export function createTools(config: ArgusConfig): Record<string, ToolDefinition>
     argus_check_patterns: patternCheckerTool,
     argus_proxy_detection: proxyDetectionTool,
     argus_skill_load: argusSkillLoadTool,
+    argus_record_finding: recordFindingTool,
     argus_generate_report: reportGeneratorTool,
     argus_sync_knowledge: syncKnowledgeTool,
   }

package/src/features/audit-enforcer/audit-enforcer.ts

@@ -11,6 +11,23 @@ const PHASE_ORDER: AuditPhase[] = [
   "complete",
 ]
 
+const REPORTING_PHASES: AuditPhase[] = ["reporting", "complete"]
+
+const KEY_TOOL_FAMILIES: Array<{ family: string; prefixes: string[] }> = [
+  { family: "slither", prefixes: ["argus_slither_analyze", "slither"] },
+  { family: "forge_test", prefixes: ["argus_forge_test", "forge_test"] },
+  { family: "forge_fuzz", prefixes: ["argus_forge_fuzz", "forge_fuzz"] },
+  { family: "forge_coverage", prefixes: ["argus_forge_coverage", "forge_coverage"] },
+]
+
+function getMissingToolFamilies(auditState: AuditState): string[] {
+  const executedTools = auditState.toolsExecuted.map((t) => t.tool)
+  return KEY_TOOL_FAMILIES.filter(
+    ({ prefixes }) =>
+      !executedTools.some((tool) => prefixes.some((prefix) => tool.startsWith(prefix))),
+  ).map(({ family }) => family)
+}
+
 function getNextPhase(current: AuditPhase): AuditPhase | null {
   const idx = PHASE_ORDER.indexOf(current)
   if (idx === -1 || idx >= PHASE_ORDER.length - 1) return null
@@ -25,10 +42,21 @@ export function createAuditEnforcer() {
     const nextPhase = getNextPhase(auditState.currentPhase)
     if (!nextPhase) return null
 
-    return [
+    const parts: string[] = [
       `[Argus Audit Enforcer] Audit in progress — current phase: ${auditState.currentPhase}.`,
       `Next phase: ${nextPhase}. Do not stop until audit is complete.`,
       `Progress: ${auditState.findings.length} findings, ${auditState.contractsReviewed.length} contracts reviewed.`,
-    ].join(" ")
+    ]
+
+    if (REPORTING_PHASES.includes(auditState.currentPhase)) {
+      const missing = getMissingToolFamilies(auditState)
+      if (missing.length > 0) {
+        parts.push(
+          `\u26a0\ufe0f Tool coverage incomplete: ${missing.join(", ")} have not been executed. Do not proceed to report generation until required tools are complete.`,
+        )
+      }
+    }
+
+    return parts.join(" ")
   }
 }