solidity-argus 0.3.6 → 0.5.6

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

@@ -1,9 +1,11 @@
-import { mkdir, rename } from "node:fs/promises"
+import { existsSync, mkdirSync, writeFileSync } from "node:fs"
+import { appendFile, mkdir } from "node:fs/promises"
 import { dirname, join } from "node:path"
+import { createLogger, type Logger } from "../../shared/logger"
 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"
+export type EventSinkErrorCode = "INVALID_EVENT" | "IO_ERROR"
 
 export class EventSinkError extends Error {
   readonly code: EventSinkErrorCode
@@ -16,8 +18,13 @@ export class EventSinkError extends Error {
 }
 
 export interface EventSink {
+  readonly runId: string
+  /** Whether this sink has been marked as finalized. Post-finalization appends are silently dropped. */
+  readonly isFinalized: boolean
   append(event: AuditEvent): Promise<void>
   readAll(): Promise<AuditEvent[]>
+  /** Mark this sink as finalized. Subsequent appends (except run.finalized) are silently dropped. */
+  markFinalized(): void
 }
 
 const VALID_EVENT_TYPES: ReadonlySet<string> = new Set<AuditEventType>([
@@ -31,7 +38,15 @@ const VALID_EVENT_TYPES: ReadonlySet<string> = new Set<AuditEventType>([
   "run.finalized",
 ])
 
-function createMutex() {
+export const MUTEX_TIMEOUT_MS = 30_000
+
+export interface MutexOptions {
+  timeoutMs?: number
+  logger?: Logger
+}
+
+export function createMutex(options: MutexOptions = {}) {
+  const { timeoutMs = MUTEX_TIMEOUT_MS, logger } = options
   let chain = Promise.resolve()
 
   return {
@@ -42,8 +57,14 @@ function createMutex() {
         release = r
       })
 
+      const timer = setTimeout(() => {
+        logger?.error("EventSink mutex held >30s — possible deadlock, still waiting")
+      }, timeoutMs)
+
       await prev
 
+      clearTimeout(timer)
+
       try {
         return await fn()
       } finally {
@@ -79,7 +100,22 @@ function parseJournalLines(content: string): AuditEvent[] {
     }
   }
 
-  events.sort((a, b) => a.seq - b.seq)
+  // Canonical ordering: sort by timestamp (primary), written seq hint (secondary tiebreaker).
+  // This produces a stable, deterministic order even when multiple writers assign
+  // overlapping seq values — the written seq is a best-effort hint, not authoritative.
+  events.sort((a, b) => {
+    const tsDiff = a.timestamp - b.timestamp
+    if (tsDiff !== 0) return tsDiff
+    return a.seq - b.seq
+  })
+
+  // Assign canonical sequential seq numbers starting from 1.
+  // All downstream consumers see clean, gap-free sequences regardless of
+  // how many independent writers appended to the journal.
+  for (let i = 0; i < events.length; i++) {
+    ;(events[i] as AuditEvent).seq = i + 1
+  }
+
   return events
 }
 
@@ -96,19 +132,39 @@ export async function readEvents(
   return parseJournalLines(content)
 }
 
-/**
- * Append-only event sink with monotonic seq allocation, in-process mutex,
- * and atomic temp-file-then-rename writes. Restart-safe via journal replay.
- */
+const sinkRegistry = new Map<string, EventSink>()
+export function releaseEventSink(runId: string): void {
+  sinkRegistry.delete(runId)
+}
+export function resetSinkRegistry(): void {
+  sinkRegistry.clear()
+}
+
 export function createEventSink(
   runId: string,
   projectDir: string,
   resolver: ArgusRootResolver = defaultRootResolver,
 ): EventSink {
+  const existing = sinkRegistry.get(runId)
+  if (existing) {
+    return existing
+  }
+
+  const logger = createLogger()
   const journalPath = buildJournalPath(runId, projectDir, resolver)
-  const mutex = createMutex()
+  const markerPath = `${journalPath}.finalized`
+  const mutex = createMutex({ logger })
   let lastSeq = 0
   let initialized = false
+  const sinkState = { finalized: false }
+
+  try {
+    if (existsSync(markerPath)) {
+      sinkState.finalized = true
+    }
+  } catch (err) {
+    logger.warn(`Failed to check finalization marker: ${String(err)}`)
+  }
 
   async function ensureInitialized(): Promise<void> {
     if (initialized) return
@@ -127,11 +183,32 @@ export function createEventSink(
     initialized = true
   }
 
-  return {
+  const sink: EventSink = {
+    runId,
+
+    get isFinalized() {
+      return sinkState.finalized
+    },
+
+    markFinalized() {
+      sinkState.finalized = true
+      try {
+        mkdirSync(dirname(markerPath), { recursive: true })
+        writeFileSync(markerPath, "")
+      } catch (err) {
+        logger.warn(`Failed to write finalization marker: ${String(err)}`)
+      }
+    },
+
     async append(event: AuditEvent): Promise<void> {
       return mutex.run(async () => {
         await ensureInitialized()
 
+        if (sinkState.finalized && event.type !== "run.finalized") {
+          logger.debug(`Dropping ${event.type} for finalized run ${runId}`)
+          return
+        }
+
         if (event.run_id !== runId) {
           throw new EventSinkError(
             "INVALID_EVENT",
@@ -143,27 +220,18 @@ export function createEventSink(
           throw new EventSinkError("INVALID_EVENT", `Invalid event type "${String(event.type)}"`)
         }
 
-        if (event.seq > 0 && event.seq <= lastSeq) {
-          throw new EventSinkError(
-            "SEQUENCE_CONFLICT",
-            `Event seq ${event.seq} conflicts with last assigned seq ${lastSeq}; must be > ${lastSeq}`,
-          )
-        }
-
+        // Best-effort seq hint — may have duplicates across isolated writer instances.
+        // Canonical seq is assigned at read time by parseJournalLines().
         const nextSeq = lastSeq + 1
         const eventToWrite: AuditEvent = { ...event, seq: nextSeq }
 
-        const currentContent = await readRawContent(journalPath)
-        const newContent = `${currentContent}${JSON.stringify(eventToWrite)}\n`
-
         await mkdir(dirname(journalPath), { recursive: true })
 
-        const suffix = `${Date.now()}.${Math.random().toString(36).slice(2)}`
-        const tempPath = `${journalPath}.${suffix}.tmp`
-
+        // O_APPEND atomic write — the OS guarantees that seek-to-end + write is atomic
+        // for regular files opened with O_APPEND, so concurrent appends from isolated
+        // writer instances won't interleave or overwrite each other.
         try {
-          await Bun.write(tempPath, newContent)
-          await rename(tempPath, journalPath)
+          await appendFile(journalPath, `${JSON.stringify(eventToWrite)}\n`)
         } catch (err) {
           throw new EventSinkError("IO_ERROR", `Failed to write event to journal: ${String(err)}`)
         }
@@ -177,4 +245,7 @@ export function createEventSink(
       return parseJournalLines(content)
     },
   }
+
+  sinkRegistry.set(runId, sink)
+  return sink
 }

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

@@ -2,8 +2,13 @@ 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 {
+  projectFindings,
+  projectReportInput,
+  projectToolExecutions,
+  stableHash,
+} from "../../state/projectors"
+import type { CanonicalFinding, CanonicalToolExecution, ReportInput } from "../../state/schemas"
 import { SCHEMA_VERSION } from "../../state/schemas"
 import { readEvents } from "./event-sink"
 
@@ -20,12 +25,34 @@ 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)
+  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))
@@ -33,7 +60,7 @@ export async function materializeFindings(
 
   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,
@@ -50,3 +77,30 @@ export async function materializeFindings(
 
   return artifact
 }
+
+export async function materializeReportInput(
+  runId: string,
+  projectDir: string,
+  _sessionId?: string,
+): Promise<ReportInput> {
+  const events = await readEvents(runId, projectDir)
+  if (events.length === 0) {
+    throw new Error(`No events found for run ${runId}`)
+  }
+
+  const reportInput = projectReportInput(events, runId, projectDir)
+
+  if (reportInput.scope.length === 0 && reportInput.findings.length > 0) {
+    reportInput.scope = [...new Set(reportInput.findings.map((f) => f.file).filter(Boolean))]
+  }
+
+  // Cross-run finding import removed: importing findings from sibling runs
+  // risks contaminating fresh audits with stale data and breaks per-run provenance.
+  // If the primary run has zero findings, the report reflects that accurately.
+
+  const reportInputFile = createAuditArtifactResolver(runId, projectDir).paths().reportInputFile
+  await mkdir(dirname(reportInputFile), { recursive: true })
+  await writeFile(reportInputFile, JSON.stringify(reportInput, null, 2))
+
+  return reportInput
+}

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

@@ -1,13 +1,11 @@
-import { appendFileSync } from "node:fs"
-import { mkdir } from "node:fs/promises"
-import { homedir } from "node:os"
-import { join } from "node:path"
+import { existsSync, readFileSync } from "node:fs"
+import { appendFile, mkdir } from "node:fs/promises"
+import { getGlobalRunIndexDir, getGlobalRunIndexFile } from "../../shared/cache-paths"
 import { createLogger } from "../../shared/logger"
 
 const logger = createLogger()
 
-const CACHE_DIR = join(homedir(), ".cache", "solidity-argus", "runs")
-const INDEX_FILE = join(CACHE_DIR, "index.jsonl")
+export type RunStatus = "active" | "finalized" | "failed"
 
 export type RunIndexEntry = {
   runId: string
@@ -18,21 +16,101 @@ export type RunIndexEntry = {
   startedAt: number
   phase: string
   findingsCount: number
+  status?: RunStatus
+  finalizedAt?: number
 }
 
 let dirEnsured = false
 
 async function ensureDir(): Promise<void> {
   if (dirEnsured) return
-  await mkdir(CACHE_DIR, { recursive: true })
+  await mkdir(getGlobalRunIndexDir(), { recursive: true })
   dirEnsured = true
 }
 
 export async function recordRun(entry: RunIndexEntry): Promise<void> {
   try {
     await ensureDir()
-    appendFileSync(INDEX_FILE, `${JSON.stringify(entry)}\n`)
+    await appendFile(getGlobalRunIndexFile(), `${JSON.stringify(entry)}\n`)
   } catch {
     logger.debug("Failed to write global run index entry")
   }
 }
+
+export async function updateRunStatus(runId: string, status: RunStatus): Promise<void> {
+  try {
+    await ensureDir()
+    const update = { runId, status, finalizedAt: status === "finalized" ? Date.now() : undefined }
+    await appendFile(getGlobalRunIndexFile(), `${JSON.stringify(update)}\n`)
+  } catch {
+    logger.debug("Failed to write run status update")
+  }
+}
+
+const STALE_RUN_TTL_MS = 24 * 60 * 60 * 1000
+
+export function resolveRunIdFromOpencodeSession(
+  opencodeSessionId: string,
+  projectDir?: string,
+): string | null {
+  if (typeof opencodeSessionId !== "string" || opencodeSessionId.length === 0) {
+    return null
+  }
+
+  const indexFile = getGlobalRunIndexFile()
+
+  if (!existsSync(indexFile)) {
+    return null
+  }
+
+  try {
+    const raw = readFileSync(indexFile, "utf-8")
+    const lines = raw.split("\n")
+    const now = Date.now()
+
+    const terminatedRunIds = new Set<string>()
+
+    for (let idx = lines.length - 1; idx >= 0; idx--) {
+      const line = lines[idx]
+      if (!line || line.trim().length === 0) continue
+
+      try {
+        const parsed = JSON.parse(line) as Partial<RunIndexEntry> & { status?: RunStatus }
+
+        if (parsed.status === "finalized" || parsed.status === "failed") {
+          if (typeof parsed.runId === "string") {
+            terminatedRunIds.add(parsed.runId)
+          }
+          continue
+        }
+
+        if (
+          parsed.opencodeSessionId === opencodeSessionId &&
+          typeof parsed.runId === "string" &&
+          parsed.runId.length > 0 &&
+          (!projectDir || parsed.projectDir === projectDir)
+        ) {
+          if (terminatedRunIds.has(parsed.runId)) {
+            logger.debug(`Skipping terminated run ${parsed.runId}`)
+            continue
+          }
+
+          if (typeof parsed.startedAt === "number" && now - parsed.startedAt > STALE_RUN_TTL_MS) {
+            logger.debug(
+              `Skipping stale run ${parsed.runId} (age: ${Math.round((now - parsed.startedAt) / 3600000)}h)`,
+            )
+            continue
+          }
+
+          return parsed.runId
+        }
+      } catch {
+        logger.debug("Skipping malformed run index line")
+      }
+    }
+  } catch {
+    logger.debug("Failed to read global run index")
+  }
+
+  return null
+}

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

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

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

@@ -9,10 +9,15 @@ export type FinalizationResult = {
   success: boolean
   invariantsPassed: boolean
   errors: string[]
+  warnings: string[]
   runId: string
   timestamp: number
 }
 
+type ExistingFinalizationResult = FinalizationResult & {
+  finalizedIndex: number
+}
+
 export function hasSessionCreated(events: AuditEvent[]): boolean {
   return events.some((event) => event.type === "session.created")
 }
@@ -132,8 +137,52 @@ function collectParentChildIntegrityErrors(events: AuditEvent[]): string[] {
   return errors
 }
 
-function collectInvariantErrors(events: AuditEvent[]): string[] {
+function collectMultiSessionErrors(events: AuditEvent[]): string[] {
+  const allSessionIds = new Set(events.map((e) => e.session_id).filter(Boolean))
+  if (allSessionIds.size <= 1) return []
+
+  const knownIds = new Set<string>()
+
+  for (const event of events) {
+    const payload = asRecord(event.payload)
+    if (!payload) continue
+    const childSessionId = payload.child_session_id
+    if (typeof childSessionId === "string" && childSessionId.length > 0) {
+      knownIds.add(childSessionId)
+      if (event.session_id) {
+        knownIds.add(event.session_id)
+      }
+    }
+  }
+
+  for (const event of events) {
+    if (event.type !== "session.created") {
+      continue
+    }
+    if (event.session_id && event.session_id.length > 0) {
+      knownIds.add(event.session_id)
+    }
+  }
+
+  const firstSessionId = events.find((e) => e.session_id)?.session_id ?? ""
+  const unexplained: string[] = []
+  for (const id of allSessionIds) {
+    if (id === firstSessionId) continue
+    if (knownIds.has(id)) continue
+    unexplained.push(id)
+  }
+
+  if (unexplained.length > 0) {
+    return [
+      `unexpected session writers detected (not in parent-child graph): ${unexplained.join(", ")}`,
+    ]
+  }
+  return []
+}
+
+function collectInvariantErrors(events: AuditEvent[]): { errors: string[]; warnings: string[] } {
   const errors: string[] = []
+  const warnings: string[] = []
 
   try {
     validateEventSequence(events)
@@ -145,13 +194,56 @@ function collectInvariantErrors(events: AuditEvent[]): string[] {
     errors.push("missing required lifecycle event: session.created")
   }
 
-  if (!hasSessionDeleted(events)) {
-    errors.push("missing required lifecycle event: session.deleted")
+  warnings.push(...collectOrphanedToolStarts(events))
+  errors.push(...collectParentChildIntegrityErrors(events))
+  errors.push(...collectMultiSessionErrors(events))
+  return { errors, warnings }
+}
+
+function parseExistingFinalizationResult(
+  events: AuditEvent[],
+  runId: string,
+): ExistingFinalizationResult | null {
+  const reversedIndex = [...events].reverse().findIndex((event) => event.type === "run.finalized")
+  if (reversedIndex < 0) {
+    return null
+  }
+
+  const finalizedIndex = events.length - 1 - reversedIndex
+  const finalized = events[finalizedIndex]
+  if (!finalized) {
+    return null
   }
 
-  errors.push(...collectOrphanedToolStarts(events))
-  errors.push(...collectParentChildIntegrityErrors(events))
-  return errors
+  const payload =
+    typeof finalized.payload === "object" &&
+    finalized.payload !== null &&
+    !Array.isArray(finalized.payload)
+      ? (finalized.payload as Record<string, unknown>)
+      : null
+
+  const errors = Array.isArray(payload?.errors)
+    ? payload.errors.filter((entry): entry is string => typeof entry === "string")
+    : []
+  const warnings = Array.isArray(payload?.warnings)
+    ? payload.warnings.filter((entry): entry is string => typeof entry === "string")
+    : []
+  const invariantsPassed =
+    typeof payload?.invariantsPassed === "boolean"
+      ? payload.invariantsPassed
+      : typeof payload?.finalized === "boolean"
+        ? payload.finalized
+        : errors.length === 0
+
+  return {
+    success: invariantsPassed,
+    invariantsPassed,
+    errors,
+    warnings,
+    runId,
+    timestamp: finalized.timestamp,
+    finalizedIndex,
+  }
 }
 
 export async function finalizeRun(
@@ -161,7 +253,21 @@ export async function finalizeRun(
 ): Promise<FinalizationResult> {
   const timestamp = Date.now()
   const events = sink ? await sink.readAll() : await readEvents(runId, projectDir)
-  const errors = collectInvariantErrors(events)
+  const existingResult = parseExistingFinalizationResult(events, runId)
+  const hasEventsAfterExistingFinalization =
+    existingResult !== null && existingResult.finalizedIndex < events.length - 1
+  if (existingResult?.invariantsPassed && !hasEventsAfterExistingFinalization) {
+    return {
+      success: existingResult.success,
+      invariantsPassed: existingResult.invariantsPassed,
+      errors: existingResult.errors,
+      warnings: existingResult.warnings,
+      runId: existingResult.runId,
+      timestamp: existingResult.timestamp,
+    }
+  }
+
+  const { errors, warnings } = collectInvariantErrors(events)
   const invariantsPassed = errors.length === 0
   const sessionId = events.at(-1)?.session_id ?? ""
 
@@ -178,16 +284,19 @@ export async function finalizeRun(
         finalized: invariantsPassed,
         invariantsPassed,
         errors,
+        warnings,
         status: invariantsPassed ? "finalized" : "failed-finalization",
         plugin_version: ARGUS_PLUGIN_VERSION,
       },
     })
+    sink.markFinalized()
   }
 
   return {
     success: invariantsPassed,
     invariantsPassed,
     errors,
+    warnings,
     runId,
     timestamp,
   }

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

@@ -0,0 +1,93 @@
+import { readdir, rm, stat } from "node:fs/promises"
+import { join } from "node:path"
+import { createLogger } from "../../shared/logger"
+import { type ArgusRootResolver, defaultRootResolver } from "../../shared/path-root-resolver"
+import { readEvents } from "./event-sink"
+
+const logger = createLogger()
+
+const DEFAULT_STALE_TTL_MS = 24 * 60 * 60 * 1000 // 24 hours
+const DEFAULT_FINALIZED_RETENTION_MS = 7 * 24 * 60 * 60 * 1000 // 7 days
+
+export type PruneResult = {
+  pruned: string[]
+  kept: string[]
+  errors: string[]
+}
+
+function isRunFinalized(events: Array<{ type: string }>): boolean {
+  return events.some((e) => e.type === "run.finalized")
+}
+
+export async function pruneStaleRuns(
+  projectDir: string,
+  options: {
+    staleTtlMs?: number
+    finalizedRetentionMs?: number
+    dryRun?: boolean
+    resolver?: ArgusRootResolver
+  } = {},
+): Promise<PruneResult> {
+  const {
+    staleTtlMs = DEFAULT_STALE_TTL_MS,
+    finalizedRetentionMs = DEFAULT_FINALIZED_RETENTION_MS,
+    dryRun = false,
+    resolver = defaultRootResolver,
+  } = options
+
+  const result: PruneResult = { pruned: [], kept: [], errors: [] }
+  const runsDir = join(resolver.writeRoot(projectDir), "runs")
+
+  let entries: string[]
+  try {
+    entries = await readdir(runsDir)
+  } catch {
+    return result
+  }
+
+  const now = Date.now()
+
+  for (const entry of entries) {
+    const runDir = join(runsDir, entry)
+    try {
+      const dirStat = await stat(runDir)
+      if (!dirStat.isDirectory()) continue
+
+      const journalPath = join(runDir, "events.jsonl")
+      let journalMtime: number
+      try {
+        const journalStat = await stat(journalPath)
+        journalMtime = journalStat.mtimeMs
+      } catch {
+        journalMtime = dirStat.mtimeMs
+      }
+
+      const age = now - journalMtime
+      const events = await readEvents(entry, projectDir, resolver)
+      const finalized = isRunFinalized(events)
+
+      const shouldPrune =
+        (finalized && age > finalizedRetentionMs) || (!finalized && age > staleTtlMs)
+
+      if (shouldPrune) {
+        if (!dryRun) {
+          await rm(runDir, { recursive: true, force: true })
+        }
+        result.pruned.push(entry)
+        logger.debug(
+          `Pruned ${finalized ? "finalized" : "stale"} run ${entry} (age: ${Math.round(age / 3600000)}h)`,
+        )
+      } else {
+        result.kept.push(entry)
+      }
+    } catch (err) {
+      result.errors.push(`${entry}: ${String(err)}`)
+    }
+  }
+
+  if (result.pruned.length > 0) {
+    logger.debug(`Pruned ${result.pruned.length} run(s), kept ${result.kept.length}`)
+  }
+
+  return result
+}