solidity-argus 0.3.5 → 0.3.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "solidity-argus",
-  "version": "0.3.5",
+  "version": "0.3.7",
   "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

@@ -233,6 +233,9 @@ 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.
 
@@ -315,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.
@@ -481,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],

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,14 +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. **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. 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. **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:
+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.
-5. Confirm the report was generated in your response to Argus: "Report generated via argus_generate_report: {filePath}".
+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/create-hooks.ts

@@ -41,6 +41,31 @@ export type AgentTrackerRef = {
 
 let _agentTrackerRef: AgentTrackerRef | undefined
 
+const REPORT_METADATA_REGEX = /<!-- argus:report_metadata (.+?) -->/
+
+function extractRunIdFromReportToolOutput(result: string): string | undefined {
+  try {
+    const parsed = JSON.parse(result) as Record<string, unknown>
+    if (typeof parsed.run_id === "string" && parsed.run_id.length > 0) {
+      return parsed.run_id
+    }
+
+    if (typeof parsed.report === "string") {
+      const match = parsed.report.match(REPORT_METADATA_REGEX)
+      if (match?.[1]) {
+        const metadata = JSON.parse(match[1]) as Record<string, unknown>
+        if (typeof metadata.run_id === "string" && metadata.run_id.length > 0) {
+          return metadata.run_id
+        }
+      }
+    }
+  } catch {
+    return undefined
+  }
+
+  return undefined
+}
+
 export function getAgentForSession(sessionID: string): string | undefined {
   return _agentTrackerRef?.getAgentForSession(sessionID)
 }
@@ -310,12 +335,73 @@ 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"
+              },
+              getAgentNameForSession: (sessionId: string) => {
+                const agent = agentTracker.getAgentForSession(sessionId)
+                if (
+                  agent === "argus" ||
+                  agent === "sentinel" ||
+                  agent === "pythia" ||
+                  agent === "scribe" ||
+                  agent === "unknown"
+                ) {
+                  return agent
+                }
+
+                return "unknown"
+              },
             },
           ),
         "tool-tracking",
       )
     : undefined
 
+  const materializeFindingsForRun = async (
+    runId: string,
+    projectDirForRun: string,
+    sessionIdForRun: string | undefined,
+    trigger: "session.idle" | "tool.execute.after",
+    failFast = false,
+  ): Promise<void> => {
+    if (!runId || runId.length === 0) {
+      return
+    }
+
+    try {
+      await materializeFindings(runId, projectDirForRun, sessionIdForRun, {
+        validateSessionId: sessionIdForRun != null && sessionIdForRun.length > 0,
+        requireEvents: true,
+      })
+    } catch (error) {
+      if (failFast) {
+        throw new Error(
+          `Failed to materialize findings artifact on ${trigger} for run ${runId}: ${error instanceof Error ? error.message : String(error)}`,
+        )
+      }
+
+      logger.warn(
+        `Failed to materialize findings artifact on ${trigger} for run ${runId}: ${error instanceof Error ? error.message : String(error)}`,
+      )
+    }
+  }
+
   const safeEventHook = isHookEnabled("event")
     ? safeCreateHook(
         () => async (input: Parameters<typeof eventHook>[0]) => {
@@ -332,7 +418,13 @@ export function createHooks(args: {
 
               if (hasNewFinalization && finalizationResult.runId.length > 0) {
                 try {
-                  await materializeFindings(finalizationResult.runId, projectDir)
+                  await materializeFindingsForRun(
+                    finalizationResult.runId,
+                    projectDir,
+                    input.event.sessionId,
+                    "session.idle",
+                    true,
+                  )
                 } catch (error) {
                   logger.warn(
                     `Failed to materialize findings artifact for run ${finalizationResult.runId}: ${error instanceof Error ? error.message : String(error)}`,
@@ -391,8 +483,26 @@ export function createHooks(args: {
             tool: input.tool,
             args: input.args,
             result: output.output,
+            sessionID: input.sessionID,
+            callID: input.callID,
           })
 
+          if (input.tool === "argus_generate_report") {
+            const state = getAuditState()
+            if (!state || state.sessionId.length === 0) {
+              throw new Error("argus_generate_report completed without active audit state")
+            }
+
+            const runId = extractRunIdFromReportToolOutput(output.output) ?? state.sessionId
+            await materializeFindingsForRun(
+              runId,
+              state.projectDir,
+              input.sessionID,
+              "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

@@ -13,7 +13,6 @@ const PHASE_ORDER: AuditPhase[] = [
 
 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"] },

package/src/features/persistent-state/audit-state-manager.ts

@@ -4,11 +4,26 @@ import type { AuditStateManager } from "../../managers/types"
 import { createLogger } from "../../shared/logger"
 import { type ArgusRootResolver, defaultRootResolver } from "../../shared/path-root-resolver"
 import { createAuditState } from "../../state/audit-state"
+import { projectAuditState, stableHash } from "../../state/projectors"
 import type { AuditState, PersistentAuditState } from "../../state/types"
+import { readEvents } from "./event-sink"
 
 const STATE_FILE_NAME = "argus-state.json"
 const STATE_VERSION = "2"
 
+type ProjectedAuditCore = Pick<
+  AuditState,
+  "contractsReviewed" | "findings" | "toolsExecuted" | "currentPhase" | "scope"
+>
+
+interface ConsistentStateResult {
+  state: AuditState
+  sourceOfTruth: "events" | "snapshot"
+  lastEventSeq?: number
+  eventStreamHash?: string
+  repaired: boolean
+}
+
 function isObject(value: unknown): value is Record<string, unknown> {
   return typeof value === "object" && value !== null
 }
@@ -46,6 +61,54 @@ function isPersistentAuditState(value: unknown): value is PersistentAuditState {
   )
 }
 
+function projectCoreState(
+  state: AuditState,
+  events: Awaited<ReturnType<typeof readEvents>>,
+): ProjectedAuditCore {
+  const projected = projectAuditState(events, state.projectDir)
+
+  return {
+    contractsReviewed: projected.contractsReviewed,
+    findings: projected.findings,
+    toolsExecuted: projected.toolsExecuted,
+    currentPhase: projected.currentPhase,
+    scope: projected.scope,
+  }
+}
+
+function hasProjectedCoreMismatch(state: AuditState, projectedCore: ProjectedAuditCore): boolean {
+  const stateCore: ProjectedAuditCore = {
+    contractsReviewed: state.contractsReviewed,
+    findings: state.findings,
+    toolsExecuted: state.toolsExecuted,
+    currentPhase: state.currentPhase,
+    scope: state.scope,
+  }
+
+  return stableHash(stateCore) !== stableHash(projectedCore)
+}
+
+function hasSnapshotStampMismatch(
+  snapshotSeq: number | undefined,
+  snapshotHash: string | undefined,
+  derivedSeq: number | undefined,
+  derivedHash: string | undefined,
+): boolean {
+  if (snapshotSeq === undefined && snapshotHash === undefined) {
+    return false
+  }
+
+  if (snapshotSeq !== undefined && derivedSeq !== undefined && snapshotSeq !== derivedSeq) {
+    return true
+  }
+
+  if (snapshotHash !== undefined && derivedHash !== undefined && snapshotHash !== derivedHash) {
+    return true
+  }
+
+  return false
+}
+
 export function createDebouncedSave(
   saveState: (state: AuditState) => Promise<void>,
   delayMs = 5_000,
@@ -104,6 +167,58 @@ export function createAuditStateManager(
   const stateFilePath = join(resolver.writeRoot(projectDir), STATE_FILE_NAME)
   let currentState: AuditState = createAuditState(projectDir).state
 
+  async function deriveConsistentState(state: AuditState): Promise<ConsistentStateResult> {
+    if (!state.sessionId || !state.projectDir) {
+      return {
+        state,
+        sourceOfTruth: "snapshot",
+        repaired: false,
+      }
+    }
+
+    try {
+      const events = await readEvents(state.sessionId, state.projectDir, resolver)
+      const lastEventSeq = events.at(-1)?.seq ?? 0
+      const eventStreamHash = stableHash(events)
+
+      if (events.length === 0) {
+        return {
+          state,
+          sourceOfTruth: "events",
+          lastEventSeq,
+          eventStreamHash,
+          repaired: false,
+        }
+      }
+
+      const projectedCore = projectCoreState(state, events)
+      const repaired = hasProjectedCoreMismatch(state, projectedCore)
+
+      return {
+        state: repaired
+          ? {
+              ...state,
+              ...projectedCore,
+            }
+          : state,
+        sourceOfTruth: "events",
+        lastEventSeq,
+        eventStreamHash,
+        repaired,
+      }
+    } catch (error) {
+      logger.warn(
+        `Failed to derive state from events for run ${state.sessionId}; using snapshot fallback`,
+        error,
+      )
+      return {
+        state,
+        sourceOfTruth: "snapshot",
+        repaired: false,
+      }
+    }
+  }
+
   async function load(): Promise<AuditState | null> {
     try {
       const resolvedPath = resolver.resolveReadPath(projectDir, STATE_FILE_NAME)
@@ -129,9 +244,9 @@ export function createAuditStateManager(
         savedAt: _savedAt,
         version,
         filePath: _filePath,
-        source_of_truth: _sourceOfTruth,
+        source_of_truth: snapshotSourceOfTruth,
         last_event_seq: snapshotSeq,
-        event_stream_hash: _eventStreamHash,
+        event_stream_hash: snapshotEventHash,
         ...state
       } = parsed
 
@@ -144,12 +259,32 @@ export function createAuditStateManager(
         }
       }
 
-
       if (snapshotSeq !== undefined) {
         logger.debug(`Loaded snapshot with last_event_seq=${snapshotSeq} from ${readPath}`)
       }
 
-      currentState = state
+      const consistent = await deriveConsistentState(state)
+      const stampMismatch =
+        consistent.sourceOfTruth === "events" &&
+        hasSnapshotStampMismatch(
+          snapshotSeq,
+          snapshotEventHash,
+          consistent.lastEventSeq,
+          consistent.eventStreamHash,
+        )
+
+      if (consistent.repaired || stampMismatch) {
+        const mismatchReason = consistent.repaired ? "projected core mismatch" : "stamp mismatch"
+        logger.warn(
+          `Recovered audit state from event stream for run ${state.sessionId}: ${mismatchReason}`,
+        )
+      } else if (snapshotSourceOfTruth === "events" && consistent.sourceOfTruth !== "events") {
+        logger.warn(
+          `Snapshot for run ${state.sessionId} was marked event-derived but could not be validated against events`,
+        )
+      }
+
+      currentState = consistent.state
       return currentState
     } catch (err) {
       logger.warn("Failed to load persisted audit state", err)
@@ -168,13 +303,23 @@ export function createAuditStateManager(
     try {
       while (true) {
         const stateToSave = currentState
+        const consistent = await deriveConsistentState(stateToSave)
+
+        if (consistent.repaired) {
+          logger.warn(
+            `State/core divergence detected for run ${stateToSave.sessionId}; auto-repairing`,
+          )
+          currentState = consistent.state
+        }
 
         const persistentState: PersistentAuditState = {
-          ...stateToSave,
+          ...consistent.state,
           savedAt: Date.now(),
           version: STATE_VERSION,
           filePath: stateFilePath,
-          source_of_truth: "events",
+          source_of_truth: consistent.sourceOfTruth,
+          last_event_seq: consistent.lastEventSeq,
+          event_stream_hash: consistent.eventStreamHash,
         }
 
         const tempFilePath = `${stateFilePath}.${Date.now()}.tmp`
@@ -182,7 +327,7 @@ export function createAuditStateManager(
         await Bun.write(tempFilePath, `${JSON.stringify(persistentState, null, 2)}\n`)
         await rename(tempFilePath, stateFilePath)
 
-        if (currentState === stateToSave) break
+        if (currentState === consistent.state) break
       }
     } catch (err) {
       logger.warn("Failed to persist audit state", err)
@@ -218,15 +363,18 @@ export function createAuditStateManager(
 
     if (hasContent) {
       try {
+        const consistent = await deriveConsistentState(currentState)
         const archivesDir = join(dirname(stateFilePath), "archives")
         await mkdir(archivesDir, { recursive: true })
         const archivePath = join(archivesDir, `argus-state.${Date.now()}.json`)
         const persistentState: PersistentAuditState = {
-          ...currentState,
+          ...consistent.state,
           savedAt: Date.now(),
           version: STATE_VERSION,
           filePath: archivePath,
-          source_of_truth: "events",
+          source_of_truth: consistent.sourceOfTruth,
+          last_event_seq: consistent.lastEventSeq,
+          event_stream_hash: consistent.eventStreamHash,
         }
         await Bun.write(archivePath, `${JSON.stringify(persistentState, null, 2)}\n`)
       } catch {

package/src/features/persistent-state/event-sink.ts

@@ -1,9 +1,6 @@
 import { mkdir, rename } from "node:fs/promises"
 import { dirname, join } from "node:path"
-import {
-  type ArgusRootResolver,
-  defaultRootResolver,
-} from "../../shared/path-root-resolver"
+import { type ArgusRootResolver, defaultRootResolver } from "../../shared/path-root-resolver"
 import type { AuditEvent, AuditEventType } from "../../state/schemas"
 
 export type EventSinkErrorCode = "SEQUENCE_CONFLICT" | "INVALID_EVENT" | "IO_ERROR"
@@ -89,7 +86,11 @@ function parseJournalLines(content: string): AuditEvent[] {
 /**
  * Replay-safe stateless read — returns all events for a run sorted by seq.
  */
-export async function readEvents(runId: string, projectDir: string, resolver: ArgusRootResolver = defaultRootResolver): Promise<AuditEvent[]> {
+export async function readEvents(
+  runId: string,
+  projectDir: string,
+  resolver: ArgusRootResolver = defaultRootResolver,
+): Promise<AuditEvent[]> {
   const journalPath = buildJournalPath(runId, projectDir, resolver)
   const content = await readRawContent(journalPath)
   return parseJournalLines(content)
@@ -99,7 +100,11 @@ export async function readEvents(runId: string, projectDir: string, resolver: Ar
  * Append-only event sink with monotonic seq allocation, in-process mutex,
  * and atomic temp-file-then-rename writes. Restart-safe via journal replay.
  */
-export function createEventSink(runId: string, projectDir: string, resolver: ArgusRootResolver = defaultRootResolver): EventSink {
+export function createEventSink(
+  runId: string,
+  projectDir: string,
+  resolver: ArgusRootResolver = defaultRootResolver,
+): EventSink {
   const journalPath = buildJournalPath(runId, projectDir, resolver)
   const mutex = createMutex()
   let lastSeq = 0

package/src/features/persistent-state/findings-materializer.ts

@@ -1,6 +1,7 @@
 import { mkdir, writeFile } from "node:fs/promises"
 import { dirname } from "node:path"
 import { createAuditArtifactResolver } from "../../shared/audit-artifact-resolver"
+import { dedupeFindingsForFinalOutput } from "../../state/finding-aggregation"
 import { projectFindings, projectToolExecutions, stableHash } from "../../state/projectors"
 import type { CanonicalFinding, CanonicalToolExecution } from "../../state/schemas"
 import { SCHEMA_VERSION } from "../../state/schemas"
@@ -19,20 +20,42 @@ export interface FindingsArtifact {
   toolsExecuted: CanonicalToolExecution[]
 }
 
+export interface FindingsMaterializeOptions {
+  validateSessionId?: boolean
+  requireEvents?: boolean
+}
+
 export async function materializeFindings(
   runId: string,
   projectDir: string,
   sessionId?: string,
+  options: FindingsMaterializeOptions = {},
 ): Promise<FindingsArtifact> {
   const events = await readEvents(runId, projectDir)
-  const findings = projectFindings(events)
+  if (options.requireEvents && events.length === 0) {
+    throw new Error(`No events found for run ${runId}`)
+  }
+
+  const sessionIdFromEvents = events[0]?.session_id ?? ""
+  if (
+    options.validateSessionId &&
+    sessionId &&
+    sessionIdFromEvents.length > 0 &&
+    sessionId !== sessionIdFromEvents
+  ) {
+    throw new Error(
+      `Session mismatch for run ${runId}: provided ${sessionId}, event stream has ${sessionIdFromEvents}`,
+    )
+  }
+
+  const findings = dedupeFindingsForFinalOutput(projectFindings(events))
   const toolsExecuted = projectToolExecutions(events)
   const contentHash = stableHash(JSON.stringify(findings))
   const generatedAt = events.at(-1)?.timestamp ?? 0
 
   const artifact: FindingsArtifact = {
     run_id: runId,
-    session_id: sessionId ?? events[0]?.session_id ?? "",
+    session_id: sessionId ?? sessionIdFromEvents,
     schema_version: SCHEMA_VERSION,
     seq_first: events[0]?.seq ?? 0,
     seq_last: events.at(-1)?.seq ?? 0,

package/src/features/persistent-state/run-finalizer.ts

@@ -1,3 +1,4 @@
+import { ARGUS_PLUGIN_VERSION } from "../../shared/plugin-metadata"
 import { validateEventSequence } from "../../state/projectors"
 import type { AuditEvent } from "../../state/schemas"
 import { SCHEMA_VERSION } from "../../state/schemas"
@@ -178,6 +179,7 @@ export async function finalizeRun(
         invariantsPassed,
         errors,
         status: invariantsPassed ? "finalized" : "failed-finalization",
+        plugin_version: ARGUS_PLUGIN_VERSION,
       },
     })
   }

package/src/features/persistent-state/run-journal.ts

@@ -1,10 +1,7 @@
 import { appendFile, mkdir } from "node:fs/promises"
 import { dirname, join } from "node:path"
-import {
-  type ArgusRootResolver,
-  defaultRootResolver,
-} from "../../shared/path-root-resolver"
 import { createLogger } from "../../shared/logger"
+import { type ArgusRootResolver, defaultRootResolver } from "../../shared/path-root-resolver"
 
 const logger = createLogger()