solidity-argus 0.3.4 → 0.3.6

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

@@ -2,13 +2,28 @@ import { mkdir, rename } from "node:fs/promises"
 import { dirname, join } from "node:path"
 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_DIR = ".opencode"
 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,
@@ -95,14 +158,73 @@ export function createDebouncedSave(
   }
 }
 
-export function createAuditStateManager(projectDir: string): AuditStateManager {
+export function createAuditStateManager(
+  projectDir: string,
+  resolver: ArgusRootResolver = defaultRootResolver,
+): AuditStateManager {
   const logger = createLogger()
-  const stateFilePath = join(projectDir, STATE_FILE_DIR, STATE_FILE_NAME)
+
+  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 file = Bun.file(stateFilePath)
+      const resolvedPath = resolver.resolveReadPath(projectDir, STATE_FILE_NAME)
+      const readPath = resolvedPath ?? stateFilePath
+
+      const file = Bun.file(readPath)
       if (!(await file.exists())) {
         return null
       }
@@ -114,11 +236,19 @@ export function createAuditStateManager(projectDir: string): AuditStateManager {
 
       const parsed: unknown = JSON.parse(content)
       if (!isPersistentAuditState(parsed)) {
-        logger.warn("Persistent audit state is invalid, ignoring", stateFilePath)
+        logger.warn("Persistent audit state is invalid, ignoring", readPath)
         return null
       }
 
-      const { savedAt: _savedAt, version, filePath: _filePath, ...state } = parsed
+      const {
+        savedAt: _savedAt,
+        version,
+        filePath: _filePath,
+        source_of_truth: snapshotSourceOfTruth,
+        last_event_seq: snapshotSeq,
+        event_stream_hash: snapshotEventHash,
+        ...state
+      } = parsed
 
       if (version === "1") {
         if (!state.soloditResults) {
@@ -129,7 +259,32 @@ export function createAuditStateManager(projectDir: string): AuditStateManager {
         }
       }
 
-      currentState = state
+      if (snapshotSeq !== undefined) {
+        logger.debug(`Loaded snapshot with last_event_seq=${snapshotSeq} from ${readPath}`)
+      }
+
+      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)
@@ -148,12 +303,23 @@ export function createAuditStateManager(projectDir: string): AuditStateManager {
     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: consistent.sourceOfTruth,
+          last_event_seq: consistent.lastEventSeq,
+          event_stream_hash: consistent.eventStreamHash,
         }
 
         const tempFilePath = `${stateFilePath}.${Date.now()}.tmp`
@@ -161,7 +327,7 @@ export function createAuditStateManager(projectDir: string): AuditStateManager {
         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)
@@ -197,14 +363,18 @@ export function createAuditStateManager(projectDir: string): AuditStateManager {
 
     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: 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,5 +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 { AuditEvent, AuditEventType } from "../../state/schemas"
 
 export type EventSinkErrorCode = "SEQUENCE_CONFLICT" | "INVALID_EVENT" | "IO_ERROR"
@@ -52,8 +53,8 @@ function createMutex() {
   }
 }
 
-function buildJournalPath(runId: string, projectDir: string): string {
-  return join(projectDir, ".opencode", "runs", runId, "events.jsonl")
+function buildJournalPath(runId: string, projectDir: string, resolver: ArgusRootResolver): string {
+  return join(resolver.writeRoot(projectDir), "runs", runId, "events.jsonl")
 }
 
 async function readRawContent(path: string): Promise<string> {
@@ -85,8 +86,12 @@ 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): Promise<AuditEvent[]> {
-  const journalPath = buildJournalPath(runId, projectDir)
+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)
 }
@@ -95,8 +100,12 @@ export async function readEvents(runId: string, projectDir: string): Promise<Aud
  * 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): EventSink {
-  const journalPath = buildJournalPath(runId, projectDir)
+export function createEventSink(
+  runId: string,
+  projectDir: string,
+  resolver: ArgusRootResolver = defaultRootResolver,
+): EventSink {
+  const journalPath = buildJournalPath(runId, projectDir, resolver)
   const mutex = createMutex()
   let lastSeq = 0
   let initialized = false

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

@@ -0,0 +1,52 @@
+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"
+import { readEvents } from "./event-sink"
+
+export interface FindingsArtifact {
+  run_id: string
+  session_id: string
+  schema_version: string
+  seq_first: number
+  seq_last: number
+  event_count: number
+  content_hash: string
+  generated_at: number
+  findings: CanonicalFinding[]
+  toolsExecuted: CanonicalToolExecution[]
+}
+
+export async function materializeFindings(
+  runId: string,
+  projectDir: string,
+  sessionId?: string,
+): Promise<FindingsArtifact> {
+  const events = await readEvents(runId, projectDir)
+  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 ?? "",
+    schema_version: SCHEMA_VERSION,
+    seq_first: events[0]?.seq ?? 0,
+    seq_last: events.at(-1)?.seq ?? 0,
+    event_count: events.length,
+    content_hash: contentHash,
+    generated_at: generatedAt,
+    findings,
+    toolsExecuted,
+  }
+
+  const findingsFile = createAuditArtifactResolver(runId, projectDir).paths().findingsFile
+  await mkdir(dirname(findingsFile), { recursive: true })
+  await writeFile(findingsFile, JSON.stringify(artifact, null, 2))
+
+  return artifact
+}

package/src/features/persistent-state/index.ts

@@ -1,3 +1,3 @@
 export { createAuditStateManager } from "./audit-state-manager"
-export { createEventSink, readEvents, EventSinkError } from "./event-sink"
 export type { EventSink, EventSinkErrorCode } from "./event-sink"
+export { createEventSink, EventSinkError, readEvents } from "./event-sink"

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"
@@ -12,18 +13,23 @@ export type FinalizationResult = {
   timestamp: number
 }
 
-function hasSessionCreated(events: AuditEvent[]): boolean {
+export function hasSessionCreated(events: AuditEvent[]): boolean {
   return events.some((event) => event.type === "session.created")
 }
 
-function hasSessionDeleted(events: AuditEvent[]): boolean {
+export function hasSessionDeleted(events: AuditEvent[]): boolean {
   return events.some((event) => event.type === "session.deleted")
 }
 
-function collectOrphanedToolStarts(events: AuditEvent[]): string[] {
+export type ToolLifecycleCheckResult = {
+  orphanedToolCallIds: string[]
+  malformedEvents: string[]
+}
+
+export function collectToolLifecycleIssues(events: AuditEvent[]): ToolLifecycleCheckResult {
   const startedCallIds = new Set<string>()
   const completedCallIds = new Set<string>()
-  const errors: string[] = []
+  const malformedEvents: string[] = []
 
   for (const event of events) {
     if (event.type !== "tool.started" && event.type !== "tool.completed") {
@@ -31,7 +37,7 @@ function collectOrphanedToolStarts(events: AuditEvent[]): string[] {
     }
 
     if (typeof event.tool_call_id !== "string" || event.tool_call_id.length === 0) {
-      errors.push(`${event.type} at seq ${event.seq} missing tool_call_id`)
+      malformedEvents.push(`${event.type} at seq ${event.seq} missing tool_call_id`)
       continue
     }
 
@@ -44,13 +50,25 @@ function collectOrphanedToolStarts(events: AuditEvent[]): string[] {
     }
   }
 
+  const orphanedToolCallIds: string[] = []
   for (const toolCallId of startedCallIds) {
     if (!completedCallIds.has(toolCallId)) {
-      errors.push(`orphaned tool.started without matching tool.completed: ${toolCallId}`)
+      orphanedToolCallIds.push(toolCallId)
     }
   }
 
-  return errors
+  return {
+    orphanedToolCallIds,
+    malformedEvents,
+  }
+}
+
+function collectOrphanedToolStarts(events: AuditEvent[]): string[] {
+  const { orphanedToolCallIds, malformedEvents } = collectToolLifecycleIssues(events)
+  const orphanedErrors = orphanedToolCallIds.map(
+    (toolCallId) => `orphaned tool.started without matching tool.completed: ${toolCallId}`,
+  )
+  return [...malformedEvents, ...orphanedErrors]
 }
 
 function asRecord(value: unknown): Record<string, unknown> | null {
@@ -161,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,10 @@
 import { appendFile, mkdir } from "node:fs/promises"
 import { dirname, join } from "node:path"
 import { createLogger } from "../../shared/logger"
+import { type ArgusRootResolver, defaultRootResolver } from "../../shared/path-root-resolver"
 
 const logger = createLogger()
 
-const JOURNAL_DIR = ".opencode"
 const JOURNAL_FILE = "argus-journal.jsonl"
 
 export type JournalEvent =
@@ -15,7 +15,12 @@ export type JournalEvent =
       findingsCount: number
       toolsExecutedCount: number
     }
-  | { type: "session.deleted"; timestamp: number; archived: boolean; finalizationPassed: boolean | null }
+  | {
+      type: "session.deleted"
+      timestamp: number
+      archived: boolean
+      finalizationPassed: boolean | null
+    }
   | {
       type: "tool.executed"
       tool: string
@@ -30,12 +35,15 @@ export type JournalEvent =
       findingsCount: number
     }
 
-export function createRunJournal(projectDir: string): {
+export function createRunJournal(
+  projectDir: string,
+  resolver: ArgusRootResolver = defaultRootResolver,
+): {
   log(event: JournalEvent): void
   close(): Promise<void>
   getPath(): string
 } {
-  const journalPath = join(projectDir, JOURNAL_DIR, JOURNAL_FILE)
+  const journalPath = join(resolver.writeRoot(projectDir), JOURNAL_FILE)
   let ensureDirPromise: Promise<void> | null = null
   const pendingWrites = new Set<Promise<void>>()
 

package/src/hooks/event-hook.ts

@@ -1,7 +1,8 @@
 import type { EventSink } from "../features/persistent-state/event-sink"
-import { finalizeRun } from "../features/persistent-state/run-finalizer"
 import type { FinalizationResult } from "../features/persistent-state/run-finalizer"
+import { finalizeRun } from "../features/persistent-state/run-finalizer"
 import { createLogger } from "../shared/logger"
+import { ARGUS_PLUGIN_VERSION } from "../shared/plugin-metadata"
 import { createAuditState } from "../state/audit-state"
 import type { AuditEvent } from "../state/schemas"
 import { SCHEMA_VERSION } from "../state/schemas"
@@ -140,6 +141,7 @@ export function createEventHook(
           await emitToSink("session.created", currentAuditState.sessionId, sessionId, {
             projectDir: currentAuditState.projectDir,
             sessionId: currentAuditState.sessionId,
+            plugin_version: ARGUS_PLUGIN_VERSION,
           })
         }
         break
@@ -160,6 +162,7 @@ export function createEventHook(
         if (preDeleteState) {
           await emitToSink("session.deleted", preDeleteState.sessionId, sessionId, {
             archived: true,
+            plugin_version: ARGUS_PLUGIN_VERSION,
           })
 
           if (eventSink) {

package/src/hooks/system-prompt-hook.ts

@@ -12,6 +12,13 @@ const TOOL_SHORT_NAMES: Record<string, string> = {
 }
 const KEY_TOOLS = ["slither", "forge-test", "patterns", "solodit", "analyzer"]
 
+/** Maps unavailable-tool short names to their KEY_TOOLS counterpart */
+const UNAVAILABLE_TO_KEY_TOOL: Record<string, string> = {
+  slither: "slither",
+  forge: "forge-test",
+  solodit: "solodit",
+}
+
 export interface SystemPromptHookDeps {
   getAuditState: () => AuditState | null
   getAgentForSession: (sessionID: string) => string | undefined
@@ -69,8 +76,15 @@ export function buildDynamicContext(
     (t) => `${t}=${executedToolNames.has(t) ? "done" : "pending"}`,
   ).join(" ")
   const unavailable = auditState.unavailableTools ?? []
+  const excusedTools = new Set(unavailable.map((t) => UNAVAILABLE_TO_KEY_TOOL[t]).filter(Boolean))
+  const pendingKeyTools = KEY_TOOLS.filter((t) => !executedToolNames.has(t) && !excusedTools.has(t))
+  const gateStatus =
+    pendingKeyTools.length > 0
+      ? `REPORTING GATE: BLOCKED \u2014 key tools pending: ${pendingKeyTools.join(", ")}`
+      : "REPORTING GATE: ALLOWED"
   const lines: string[] = [
     `<argus-context agent="${agent}">`,
+    gateStatus,
     `Phase: ${auditState.currentPhase}`,
     `Contracts: ${auditState.contractsReviewed.length} reviewed`,
     `Findings: Critical=${severityCounts.Critical} High=${severityCounts.High} Medium=${severityCounts.Medium} Low=${severityCounts.Low} Info=${severityCounts.Informational}`,
@@ -91,6 +105,7 @@ export function buildDynamicContext(
     const doneCount = KEY_TOOLS.filter((t) => executedToolNames.has(t)).length
     summary = [
       `<argus-context agent="${agent}">`,
+      gateStatus,
       `Phase: ${auditState.currentPhase} | Findings: ${auditState.findings.length} | Contracts: ${auditState.contractsReviewed.length} | Tasks: ${doneCount}/${KEY_TOOLS.length} done`,
       "</argus-context>",
     ].join("\n")