solidity-argus 0.3.6 → 0.5.6

package/src/create-managers.ts

@@ -16,8 +16,10 @@ export function createManagers(args: {
   const backgroundManager = createBackgroundManager(
     backgroundDispatcher ??
       (async (agentName: string, prompt: string) => {
-        logger.warn(`Background dispatch not wired: ${agentName} (${prompt.slice(0, 50)}...)`)
-        return `noop-${Date.now()}`
+        logger.warn(
+          `Background dispatcher not configured — task will not be executed: ${agentName} (${prompt.slice(0, 50)}...)`,
+        )
+        return ""
       }),
     { maxConcurrent: config.background?.max_concurrent ?? 3 },
   )

package/src/create-tools.ts

@@ -7,7 +7,9 @@ import { forgeFuzzTool } from "./tools/forge-fuzz-tool"
 import { forgeTestTool } from "./tools/forge-test-tool"
 import { gasAnalysisTool } from "./tools/gas-analysis-tool"
 import { patternCheckerTool } from "./tools/pattern-checker-tool"
+import { persistDedupedTool } from "./tools/persist-deduped-tool"
 import { proxyDetectionTool } from "./tools/proxy-detection-tool"
+import { readFindingsTool } from "./tools/read-findings-tool"
 import { recordFindingTool } from "./tools/record-finding-tool"
 import { reportGeneratorTool } from "./tools/report-generator-tool"
 import { slitherTool } from "./tools/slither-tool"
@@ -26,12 +28,14 @@ export function createTools(config: ArgusConfig): Record<string, ToolDefinition>
     argus_proxy_detection: proxyDetectionTool,
     argus_skill_load: argusSkillLoadTool,
     argus_record_finding: recordFindingTool,
+    argus_read_findings: readFindingsTool,
+    argus_persist_deduped: persistDedupedTool,
     argus_generate_report: reportGeneratorTool,
     argus_sync_knowledge: syncKnowledgeTool,
   }
 
   if (config.solodit?.enabled !== false) {
-    tools.argus_solodit_search = createSoloditSearchTool(config.solodit?.port ?? 3000)
+    tools.argus_solodit_search = createSoloditSearchTool()
   }
 
   return tools

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

@@ -1,16 +1,6 @@
+import { PHASE_ORDER } from "../../shared/audit-phases"
 import type { AuditPhase, AuditState } from "../../state/types"
 
-const PHASE_ORDER: AuditPhase[] = [
-  "reconnaissance",
-  "scanning",
-  "manual-review",
-  "attack-surface",
-  "research",
-  "testing",
-  "reporting",
-  "complete",
-]
-
 const REPORTING_PHASES: AuditPhase[] = ["reporting", "complete"]
 
 const KEY_TOOL_FAMILIES: Array<{ family: string; prefixes: string[] }> = [

package/src/features/background-agent/background-manager.ts

@@ -44,6 +44,7 @@ export function createBackgroundManager(
   let runningCount = 0
   const maxConcurrent = options?.maxConcurrent ?? 3
   let taskCount = 0
+  let drainScheduled = false
 
   function safeInvokeCallback(callback: CompletionCallback, taskId: string, result: unknown): void {
     try {
@@ -70,7 +71,16 @@ export function createBackgroundManager(
     task.callbacks.clear()
   }
 
-  function processQueue(): void {
+  function scheduleDrain(): void {
+    if (drainScheduled) return
+    drainScheduled = true
+    queueMicrotask(() => {
+      drainScheduled = false
+      drainQueue()
+    })
+  }
+
+  function drainQueue(): void {
     while (runningCount < maxConcurrent && queue.length > 0) {
       const nextTaskId = queue.shift()
 
@@ -86,7 +96,16 @@ export function createBackgroundManager(
       task.status = "running"
       runningCount += 1
 
-      dispatcher(task.agentName, task.prompt, task.options)
+      const TASK_TIMEOUT_MS = 5 * 60 * 1000
+      let timeoutHandle: ReturnType<typeof setTimeout> | undefined
+      const timeoutPromise = new Promise<never>((_, reject) => {
+        timeoutHandle = setTimeout(
+          () => reject(new Error(`Background task timed out after 5 minutes: ${nextTaskId}`)),
+          TASK_TIMEOUT_MS,
+        )
+      })
+
+      Promise.race([dispatcher(task.agentName, task.prompt, task.options), timeoutPromise])
         .then((result) => {
           const currentTask = tasks.get(nextTaskId)
 
@@ -105,14 +124,22 @@ export function createBackgroundManager(
             return
           }
 
+          const isTimeout =
+            error instanceof Error && error.message.includes("timed out after 5 minutes")
+          if (isTimeout) {
+            logger.error(`Background task timed out: ${nextTaskId}`, error)
+          } else {
+            logger.error(`Background task failed: ${nextTaskId}`, error)
+          }
+
           currentTask.status = "failed"
           currentTask.error = error
-          logger.error(`Background task failed: ${nextTaskId}`, error)
           invokeCallbacks(nextTaskId, error)
         })
         .finally(() => {
+          if (timeoutHandle) clearTimeout(timeoutHandle)
           runningCount = Math.max(0, runningCount - 1)
-          processQueue()
+          scheduleDrain()
         })
     }
   }
@@ -130,7 +157,7 @@ export function createBackgroundManager(
     })
 
     queue.push(taskId)
-    processQueue()
+    scheduleDrain()
 
     return taskId
   }

package/src/features/error-recovery/tool-error-recovery.ts

@@ -60,6 +60,7 @@ export function createToolErrorRecoveryHandler(
 
   return (toolResult: { tool: string; result: string }): string | null => {
     const { tool, result } = toolResult
+    if (!result || typeof result !== "string") return null
     const lowerResult = result.toLowerCase()
 
     const isViaIr =

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

@@ -1,14 +1,18 @@
-import { mkdir, rename } from "node:fs/promises"
+import { createHash } from "node:crypto"
+import { mkdirSync } from "node:fs"
+import { mkdir, readdir, rename, rm, stat } 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 { normalizeText } from "../../state/finding-fingerprint"
 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 SESSIONS_DIR = "sessions"
 const STATE_VERSION = "2"
 
 type ProjectedAuditCore = Pick<
@@ -24,6 +28,73 @@ interface ConsistentStateResult {
   repaired: boolean
 }
 
+const SAVE_MUTEX_TIMEOUT_MS = 30_000
+const MAX_SAVE_CAS_RETRIES = 10
+const LEGACY_OBSERVATION_ID_PATTERN = /^obs-\d+$/
+
+function generateDeterministicFindingId(
+  check: string,
+  file: string,
+  lines: [number, number],
+): string {
+  return createHash("sha256")
+    .update(`${normalizeText(check)}:${normalizeText(file)}:${lines[0]}-${lines[1]}`)
+    .digest("hex")
+    .substring(0, 16)
+}
+
+export function migrateLegacyFindingIds(state: AuditState): number {
+  let migratedCount = 0
+
+  state.findings = state.findings.map((finding) => {
+    if (!LEGACY_OBSERVATION_ID_PATTERN.test(finding.id)) {
+      return finding
+    }
+
+    migratedCount += 1
+    return {
+      ...finding,
+      id: generateDeterministicFindingId(finding.check, finding.file, finding.lines),
+    }
+  })
+
+  return migratedCount
+}
+
+export function createAsyncMutex(timeoutMs = SAVE_MUTEX_TIMEOUT_MS) {
+  const logger = createLogger()
+  let chain = Promise.resolve()
+
+  return {
+    async acquire(): Promise<() => void> {
+      const previous = chain
+      let releaseCurrent!: () => void
+      chain = new Promise<void>((resolve) => {
+        releaseCurrent = resolve
+      })
+
+      await previous
+
+      let released = false
+      const timeout = setTimeout(() => {
+        // Log the timeout but do NOT release — the holder must finish
+        // its critical section and call release() explicitly.
+        logger.error(`audit-state-manager mutex held for >${timeoutMs}ms — possible deadlock`)
+      }, timeoutMs)
+
+      return () => {
+        if (released) {
+          return
+        }
+
+        released = true
+        clearTimeout(timeout)
+        releaseCurrent()
+      }
+    },
+  }
+}
+
 function isObject(value: unknown): value is Record<string, unknown> {
   return typeof value === "object" && value !== null
 }
@@ -115,28 +186,40 @@ export function createDebouncedSave(
 ): {
   save: (state: AuditState) => void
   flush: () => Promise<void>
+  dispose: () => void
 } {
   let timer: ReturnType<typeof setTimeout> | null = null
-  let pendingState: AuditState | null = null
+  const pendingStates: AuditState[] = []
+  let persistQueue = Promise.resolve()
 
-  async function persistPendingState(): Promise<void> {
-    if (!pendingState) {
+  async function persistPendingStateQueue(): Promise<void> {
+    if (pendingStates.length === 0) {
       return
     }
 
-    const stateToPersist = pendingState
-    pendingState = null
+    // Only the latest state matters — each write replaces the file
+    const latestState = pendingStates[pendingStates.length - 1]
+    if (!latestState) {
+      pendingStates.length = 0
+      return
+    }
+    pendingStates.length = 0
 
     try {
-      await saveState(stateToPersist)
+      await saveState(latestState)
     } catch {
       createLogger().debug("Debounced state persistence failed")
     }
   }
 
+  function enqueuePersist(): Promise<void> {
+    persistQueue = persistQueue.then(() => persistPendingStateQueue())
+    return persistQueue
+  }
+
   return {
     save(state: AuditState): void {
-      pendingState = state
+      pendingStates.push(state)
 
       if (timer) {
         clearTimeout(timer)
@@ -144,7 +227,7 @@ export function createDebouncedSave(
 
       timer = setTimeout(() => {
         timer = null
-        void persistPendingState()
+        void enqueuePersist()
       }, delayMs)
     },
     async flush(): Promise<void> {
@@ -153,7 +236,14 @@ export function createDebouncedSave(
         timer = null
       }
 
-      await persistPendingState()
+      await enqueuePersist()
+    },
+    dispose(): void {
+      if (timer) {
+        clearTimeout(timer)
+        timer = null
+      }
+      pendingStates.length = 0
     },
   }
 }
@@ -164,8 +254,39 @@ export function createAuditStateManager(
 ): AuditStateManager {
   const logger = createLogger()
 
-  const stateFilePath = join(resolver.writeRoot(projectDir), STATE_FILE_NAME)
+  const argusRoot = resolver.writeRoot(projectDir)
+  const sharedStateFilePath = join(argusRoot, STATE_FILE_NAME)
+  const sessionsDirPath = join(argusRoot, SESSIONS_DIR)
+  let stateFilePath = sharedStateFilePath
+  let boundSessionId: string | undefined
   let currentState: AuditState = createAuditState(projectDir).state
+  const saveMutex = createAsyncMutex()
+
+  async function cleanupStaleTempFiles(): Promise<void> {
+    for (const dirPath of [argusRoot, sessionsDirPath]) {
+      let entries: string[]
+
+      try {
+        entries = await readdir(dirPath)
+      } catch {
+        continue
+      }
+
+      for (const entry of entries) {
+        if (!entry.endsWith(".tmp")) {
+          continue
+        }
+
+        try {
+          await rm(join(dirPath, entry), { force: true })
+        } catch (error) {
+          logger.warn(`Failed to remove stale tmp state file ${entry}`, error)
+        }
+      }
+    }
+  }
+
+  const startupCleanup = cleanupStaleTempFiles()
 
   async function deriveConsistentState(state: AuditState): Promise<ConsistentStateResult> {
     if (!state.sessionId || !state.projectDir) {
@@ -219,16 +340,91 @@ export function createAuditStateManager(
     }
   }
 
+  function bindSession(sessionId: string): void {
+    if (boundSessionId) {
+      logger.debug(`Already bound to session ${boundSessionId}, ignoring bind for ${sessionId}`)
+      return
+    }
+    boundSessionId = sessionId
+    stateFilePath = join(sessionsDirPath, `state-${sessionId}.json`)
+    try {
+      mkdirSync(sessionsDirPath, { recursive: true })
+    } catch {
+      logger.warn(`Failed to create sessions directory: ${sessionsDirPath}`)
+    }
+    logger.debug(`Bound state manager to session ${sessionId}: ${stateFilePath}`)
+  }
+
   async function load(): Promise<AuditState | null> {
     try {
-      const resolvedPath = resolver.resolveReadPath(projectDir, STATE_FILE_NAME)
-      const readPath = resolvedPath ?? stateFilePath
+      // 1. If bound to a session, try the session-scoped file first
+      let readPath: string | null = null
 
-      const file = Bun.file(readPath)
-      if (!(await file.exists())) {
+      if (boundSessionId) {
+        const sessionFile = Bun.file(stateFilePath)
+        if (await sessionFile.exists()) {
+          readPath = stateFilePath
+        }
+      }
+
+      // 2. Bound sessions with no matching file start clean — no cross-session contamination
+      if (!readPath && boundSessionId) {
+        logger.info("Starting new audit session with clean state")
+        return null
+      }
+
+      // 3. Unbound: scan sessions dir for most recent (backward compat)
+      if (!readPath) {
+        try {
+          const entries = await readdir(sessionsDirPath)
+          const jsonFiles = entries.filter((e) => e.startsWith("state-") && e.endsWith(".json"))
+
+          if (jsonFiles.length > 0) {
+            let newest: { name: string; mtime: number } | null = null
+            for (const name of jsonFiles) {
+              const filePath = join(sessionsDirPath, name)
+              try {
+                const s = await stat(filePath)
+                const mtime = s.mtimeMs
+                if (
+                  !newest ||
+                  mtime > newest.mtime ||
+                  (mtime === newest.mtime && name > newest.name)
+                ) {
+                  newest = { name, mtime }
+                }
+              } catch {
+                // Skip unreadable files
+              }
+            }
+            if (newest) {
+              readPath = join(sessionsDirPath, newest.name)
+              logger.debug(
+                `No session-scoped file for (unbound), falling back to newest: ${newest.name}`,
+              )
+            }
+          }
+        } catch {
+          // sessions dir doesn't exist yet
+        }
+      }
+
+      // 4. Unbound: try legacy shared file
+      if (!readPath) {
+        const resolvedPath = resolver.resolveReadPath(projectDir, STATE_FILE_NAME)
+        const legacyPath = resolvedPath ?? sharedStateFilePath
+        const legacyFile = Bun.file(legacyPath)
+        if (await legacyFile.exists()) {
+          readPath = legacyPath
+          logger.debug(`Falling back to legacy shared state file: ${legacyPath}`)
+        }
+      }
+
+      if (!readPath) {
         return null
       }
 
+      const file = Bun.file(readPath)
       const content = await file.text()
       if (!content.trim()) {
         return null
@@ -259,6 +455,11 @@ export function createAuditStateManager(
         }
       }
 
+      const migratedFindingCount = migrateLegacyFindingIds(state)
+      if (migratedFindingCount > 0) {
+        logger.info(`Migrating ${migratedFindingCount} finding IDs to deterministic format`)
+      }
+
       if (snapshotSeq !== undefined) {
         logger.debug(`Loaded snapshot with last_event_seq=${snapshotSeq} from ${readPath}`)
       }
@@ -292,21 +493,18 @@ export function createAuditStateManager(
     }
   }
 
-  let saveInFlight = false
-
   async function save(state: AuditState): Promise<void> {
+    await startupCleanup
+    const releaseMutex = await saveMutex.acquire()
     currentState = state
 
-    if (saveInFlight) return
-    saveInFlight = true
-
     try {
-      while (true) {
+      for (let attempt = 0; attempt < MAX_SAVE_CAS_RETRIES; attempt += 1) {
         const stateToSave = currentState
         const consistent = await deriveConsistentState(stateToSave)
 
         if (consistent.repaired) {
-          logger.warn(
+          logger.debug(
             `State/core divergence detected for run ${stateToSave.sessionId}; auto-repairing`,
           )
           currentState = consistent.state
@@ -323,17 +521,40 @@ export function createAuditStateManager(
         }
 
         const tempFilePath = `${stateFilePath}.${Date.now()}.tmp`
-        await mkdir(dirname(stateFilePath), { recursive: true })
-        await Bun.write(tempFilePath, `${JSON.stringify(persistentState, null, 2)}\n`)
-        await rename(tempFilePath, stateFilePath)
+        const targetDir = dirname(stateFilePath)
+        await mkdir(targetDir, { recursive: true })
+
+        // Retry write+rename on ENOENT — mkdir may not have flushed to
+        // disk before Bun.write attempts to use the directory.
+        const ENOENT_RETRIES = 3
+        for (let fsRetry = 0; fsRetry < ENOENT_RETRIES; fsRetry += 1) {
+          try {
+            await Bun.write(tempFilePath, `${JSON.stringify(persistentState, null, 2)}\n`)
+            await rename(tempFilePath, stateFilePath)
+            break
+          } catch (fsErr) {
+            const isEnoent =
+              fsErr instanceof Error && (fsErr as NodeJS.ErrnoException).code === "ENOENT"
+            if (!isEnoent || fsRetry === ENOENT_RETRIES - 1) {
+              throw fsErr
+            }
+            // Re-create directory and retry after a brief delay
+            await mkdir(targetDir, { recursive: true })
+            await Bun.sleep(50)
+          }
+        }
 
-        if (currentState === consistent.state) break
+        if (currentState === consistent.state) {
+          return
+        }
       }
+
+      logger.warn("CAS retries exhausted after 10 attempts; using last read state")
     } catch (err) {
       logger.warn("Failed to persist audit state", err)
       throw err
     } finally {
-      saveInFlight = false
+      releaseMutex()
     }
   }
 
@@ -364,7 +585,7 @@ export function createAuditStateManager(
     if (hasContent) {
       try {
         const consistent = await deriveConsistentState(currentState)
-        const archivesDir = join(dirname(stateFilePath), "archives")
+        const archivesDir = join(argusRoot, "archives")
         await mkdir(archivesDir, { recursive: true })
         const archivePath = join(archivesDir, `argus-state.${Date.now()}.json`)
         const persistentState: PersistentAuditState = {
@@ -383,15 +604,37 @@ export function createAuditStateManager(
     }
 
     currentState = createAuditState(projectDir).state
-    await save(currentState)
+
+    try {
+      await rm(stateFilePath, { force: true })
+    } catch (error) {
+      logger.warn(`Failed to remove live state file after archive: ${stateFilePath}`, error)
+    }
+  }
+
+  let disposed = false
+
+  async function dispose(): Promise<void> {
+    if (disposed) {
+      return
+    }
+    disposed = true
+
+    try {
+      await save(currentState)
+    } catch (err) {
+      logger.warn("Failed to flush state during dispose", err)
+    }
   }
 
   return {
+    bindSession,
     load,
     save,
     get,
     update,
     reset,
     archive,
+    dispose,
   }
 }