solidity-argus 0.5.10 → 0.6.1

package/src/tools/forge-coverage-tool.ts

@@ -40,6 +40,8 @@ type ForgeCoverageResult = {
   report: ForgeCoverageReport
   executionTime: number
   error?: string
+  hint?: string
+  suggested_command?: string
 }
 
 export type ForgeCommandRunner = (
@@ -73,6 +75,36 @@ function isStackTooDeep(stderr: string): boolean {
   return /stack too deep/i.test(stderr)
 }
 
+function classifyCoverageFailure(
+  stderr: string,
+  args: NormalizedForgeCoverageArgs,
+): Pick<ForgeCoverageResult, "hint" | "suggested_command"> | undefined {
+  if (
+    !/(optimizerSteps|unsupported optimizer|config parse|failed to parse|instrumentation)/i.test(
+      stderr,
+    )
+  ) {
+    return undefined
+  }
+
+  const command = buildCoverageCommand({ ...args, ir_minimum: true }).join(" ")
+  return {
+    hint:
+      `Forge coverage failed for ${args.target} while parsing or instrumenting project configuration. ` +
+      "If foundry.toml uses optimizerSteps or unsupported optimizer settings, run a scoped coverage command or temporarily adjust coverage-only config manually; Argus will not edit foundry.toml.",
+    suggested_command: command,
+  }
+}
+
+function shouldRetryWithIrMinimum(stderr: string): boolean {
+  return (
+    isStackTooDeep(stderr) ||
+    /(optimizerSteps|unsupported optimizer|config parse|failed to parse|instrumentation)/i.test(
+      stderr,
+    )
+  )
+}
+
 function parsePercent(input: string): number {
   const match = input.match(/(\d+(?:\.\d+)?)%/)
   if (!match?.[1]) {
@@ -165,11 +197,15 @@ export async function executeForgeCoverage(
   const normalizedArgs = normalizeArgs(args, context)
   context.metadata({ title: `Run forge coverage: ${normalizedArgs.target}` })
 
-  const fail = (error: string): ForgeCoverageResult => ({
+  const fail = (
+    error: string,
+    diagnostics?: Pick<ForgeCoverageResult, "hint" | "suggested_command">,
+  ): ForgeCoverageResult => ({
     success: false,
     report: { files: [], summary: { ...EMPTY_SUMMARY } },
     executionTime: Date.now() - startedAt,
     error,
+    ...diagnostics,
   })
 
   try {
@@ -181,7 +217,7 @@ export async function executeForgeCoverage(
     if (
       runResult.exitCode !== 0 &&
       !normalizedArgs.ir_minimum &&
-      isStackTooDeep(runResult.stderr)
+      shouldRetryWithIrMinimum(runResult.stderr)
     ) {
       runResult = await runCommand(buildCoverageCommand(normalizedArgs, true), {
         signal: context.abort,
@@ -190,9 +226,9 @@ export async function executeForgeCoverage(
     }
 
     if (runResult.exitCode !== 0) {
-      return fail(
-        runResult.stderr.trim() || `forge coverage exited with code ${runResult.exitCode}`,
-      )
+      const error =
+        runResult.stderr.trim() || `forge coverage exited with code ${runResult.exitCode}`
+      return fail(error, classifyCoverageFailure(error, normalizedArgs))
     }
 
     let report: ForgeCoverageReport

package/src/tools/persist-deduped-tool.ts

@@ -1,7 +1,8 @@
-import { mkdir, writeFile } from "node:fs/promises"
+import { mkdir, readFile, writeFile } from "node:fs/promises"
 import { dirname } from "node:path"
 import { type ToolContext, tool } from "@opencode-ai/plugin"
 import { createAuditArtifactResolver } from "../shared/audit-artifact-resolver"
+import { validateFindingLineage } from "../shared/lineage-validator"
 import { createLogger } from "../shared/logger"
 import { resolveProjectDir } from "../shared/project-utils"
 import { isNonEmptyString } from "../shared/type-guards"
@@ -22,6 +23,28 @@ export interface DedupedFindingsArtifact {
   findings: CanonicalFinding[]
 }
 
+async function loadRawFindings(
+  runId: string,
+  projectDir: string,
+): Promise<CanonicalFinding[] | null> {
+  const findingsFile = createAuditArtifactResolver(runId, projectDir).paths().findingsFile
+  try {
+    const parsed = JSON.parse(await readFile(findingsFile, "utf8"))
+    if (!parsed || !Array.isArray(parsed.findings)) return null
+    return parsed.findings
+  } catch {
+    return null
+  }
+}
+
+function missingRawFindings(runId: string): string {
+  return JSON.stringify({
+    success: false,
+    error: "MissingRawFindingsError",
+    message: `Cannot verify deduped lineage because .argus/runs/${runId}/findings.json is missing or invalid`,
+  })
+}
+
 export async function executePersistDeduped(
   args: PersistDedupedArgs,
   context: ToolContext,
@@ -55,6 +78,27 @@ export async function executePersistDeduped(
   const projectDir = resolveProjectDir(context)
   const resolver = createAuditArtifactResolver(args.run_id, projectDir)
   const dedupedPath = resolver.paths().dedupedFindingsFile
+  const rawFindings = await loadRawFindings(args.run_id, projectDir)
+
+  if (!rawFindings) {
+    return missingRawFindings(args.run_id)
+  }
+
+  const lineage = validateFindingLineage(rawFindings, findings)
+  if (!lineage.valid) {
+    return JSON.stringify({
+      success: false,
+      error: "LineageError",
+      lineage: {
+        raw_count: lineage.raw_count,
+        mapped_count: lineage.mapped_count,
+        duplicate_observation_ids: lineage.duplicate_observation_ids,
+        phantom_observation_ids: lineage.phantom_observation_ids,
+        missing_observation_ids: lineage.missing_observation_ids,
+        count_mismatches: lineage.count_mismatches,
+      },
+    })
+  }
 
   const artifact: DedupedFindingsArtifact = {
     run_id: args.run_id,

package/src/tools/read-findings-tool.ts

@@ -12,6 +12,8 @@ import type { AuditState } from "../state/types"
 
 type ReadFindingsArgs = {
   run_id: string
+  findings_offset?: number
+  findings_limit?: number
 }
 
 type ReportFinding = Omit<
@@ -42,6 +44,11 @@ type CompactReportInput = Omit<
   run_id: string
   findings: ReportFinding[]
   toolsExecuted: ReportToolExecution[]
+  findingsPage?: {
+    offset: number
+    limit: number
+    total: number
+  }
 }
 
 type ReadFindingsInlineResult = {
@@ -98,13 +105,31 @@ function stripInternalKeys(obj: object, keysToStrip: ReadonlySet<string>): Recor
   return result
 }
 
-function buildCompactInput(reportInput: ReportInput): CompactReportInput {
+function normalizePageArgs(args: ReadFindingsArgs): { offset: number; limit: number } | null {
+  if (args.findings_offset == null && args.findings_limit == null) return null
+
+  const offset = args.findings_offset ?? 0
+  const limit = args.findings_limit ?? 50
+  if (!Number.isInteger(offset) || offset < 0) {
+    throw new Error("findings_offset must be a non-negative integer")
+  }
+  if (!Number.isInteger(limit) || limit < 1 || limit > 500) {
+    throw new Error("findings_limit must be an integer between 1 and 500")
+  }
+  return { offset, limit }
+}
+
+function buildCompactInput(
+  reportInput: ReportInput,
+  page: { offset: number; limit: number } | null = null,
+): CompactReportInput {
+  const rawFindings = page
+    ? reportInput.findings.slice(page.offset, page.offset + page.limit)
+    : reportInput.findings
   return {
     run_id: reportInput.run_id,
     projectDir: reportInput.projectDir,
-    findings: reportInput.findings.map(
-      (f) => stripInternalKeys(f, FINDING_INTERNAL_KEYS) as ReportFinding,
-    ),
+    findings: rawFindings.map((f) => stripInternalKeys(f, FINDING_INTERNAL_KEYS) as ReportFinding),
     toolsExecuted: reportInput.toolsExecuted.map(
       (t) => stripInternalKeys(t, TOOL_EXECUTION_INTERNAL_KEYS) as ReportToolExecution,
     ),
@@ -118,6 +143,13 @@ function buildCompactInput(reportInput: ReportInput): CompactReportInput {
     ...(reportInput.proxyContracts && { proxyContracts: reportInput.proxyContracts }),
     ...(reportInput.patternVersion && { patternVersion: reportInput.patternVersion }),
     ...(reportInput.skillsLoaded && { skillsLoaded: reportInput.skillsLoaded }),
+    ...(page && {
+      findingsPage: {
+        offset: page.offset,
+        limit: page.limit,
+        total: reportInput.findings.length,
+      },
+    }),
   }
 }
 
@@ -339,7 +371,8 @@ export async function executeReadFindings(
 
   const projectDir = resolveProjectDir(context)
   const reportInput = readAuditStateAsReportInput(projectDir, runId)
-  const compactInput = buildCompactInput(reportInput)
+  const page = normalizePageArgs(args)
+  const compactInput = buildCompactInput(reportInput, page)
 
   const inlineJson = JSON.stringify({
     success: true,
@@ -383,6 +416,14 @@ export const readFindingsTool = tool({
     "Read the materialized ReportInput artifact from disk for a given run. Returns the canonical findings, tools executed, scope, and all enrichment data. Scribe should call this before generating the report.",
   args: {
     run_id: tool.schema.string().describe("The run ID to read findings for."),
+    findings_offset: tool.schema
+      .number()
+      .optional()
+      .describe("Optional zero-based finding offset for paged inline retrieval."),
+    findings_limit: tool.schema
+      .number()
+      .optional()
+      .describe("Optional finding page size for inline retrieval (1-500)."),
   },
   async execute(args, context) {
     return executeReadFindings(args, context)

package/src/tools/record-finding-tool.ts

@@ -1,7 +1,7 @@
 import { type ToolContext, tool } from "@opencode-ai/plugin"
 import { isNonEmptyString } from "../shared/type-guards"
 import { normalizeToCanonicalFinding } from "../state/adapters"
-import { SCHEMA_VERSION } from "../state/schemas"
+import { type CanonicalFinding, SCHEMA_VERSION } from "../state/schemas"
 import type { ArgusAgentName } from "../state/types"
 
 type RecordFindingArgs = {
@@ -12,20 +12,7 @@ type RecordFindingArgs = {
 type RecordFindingResponse = {
   success: boolean
   count: number
-  findings: Array<{
-    id: string
-    check: string
-    severity: string
-    confidence: string
-    file: string
-    description: string
-    lines: [number, number]
-    source: string
-    reported_by_agent: string
-    impact?: string
-    recommendation?: string
-    proofOfConcept?: string
-  }>
+  findings: CanonicalFinding[]
   schema_version: string
   note: string
   enrichment_warnings?: string[]
@@ -63,7 +50,13 @@ function parseFindingObject(raw: string, label: "finding" | "findings"): ParseRe
 }
 
 function normalizeAgent(value: string): ArgusAgentName {
-  if (value === "argus" || value === "sentinel" || value === "pythia" || value === "scribe") {
+  if (
+    value === "argus" ||
+    value === "sentinel" ||
+    value === "pythia" ||
+    value === "audit-specialist" ||
+    value === "scribe"
+  ) {
     return value
   }
 
@@ -196,20 +189,7 @@ export async function executeRecordFinding(
   const response: RecordFindingResponse = {
     success: true,
     count: findings.length,
-    findings: findings.map((f) => ({
-      id: f.id,
-      check: f.check,
-      severity: f.severity,
-      confidence: f.confidence,
-      file: f.file,
-      description: f.description,
-      lines: f.lines,
-      source: f.source,
-      reported_by_agent: f.reported_by_agent,
-      ...(f.impact !== undefined ? { impact: f.impact } : {}),
-      ...(f.recommendation !== undefined ? { recommendation: f.recommendation } : {}),
-      ...(f.proofOfConcept !== undefined ? { proofOfConcept: f.proofOfConcept } : {}),
-    })),
+    findings,
     schema_version: SCHEMA_VERSION,
     note: "Findings recorded to event journal. The system assigns the canonical run_id automatically — use the run_id from <argus-context> for Scribe dispatch.",
     ...(enrichmentWarnings.length > 0

package/src/tools/report-generator-tool.ts

@@ -9,6 +9,7 @@ import { createAuditArtifactResolver } from "../shared/audit-artifact-resolver"
 import type { DropDiagnostic } from "../shared/drop-diagnostics"
 import { createDropDiagnosticsCollector } from "../shared/drop-diagnostics"
 import { computeMissingKeyTools } from "../shared/key-tools"
+import { validateFindingLineage } from "../shared/lineage-validator"
 import { createLogger } from "../shared/logger"
 import { resolveProjectDir } from "../shared/project-utils"
 import { resolveReportPath } from "../shared/report-path-resolver"
@@ -38,6 +39,8 @@ type ReportGeneratorArgs = {
   preflight_policy?: PreflightPolicy
   tool_coverage_policy?: ToolCoveragePolicy
   run_id?: string
+  revision?: number
+  force?: boolean
 }
 
 type FindingsCount = {
@@ -131,6 +134,30 @@ async function checkDuplicateWrite(
   return null
 }
 
+async function checkSafeForceOverwrite(
+  filePath: string,
+  runId: string,
+): Promise<{ code: string; message: string } | null> {
+  if (!existsSync(filePath)) return null
+  try {
+    const existingContent = await Bun.file(filePath).text()
+    const existingRunId = extractReportRunId(existingContent)
+    if (existingRunId === runId) return null
+    return {
+      code: "INSECURE_OVERWRITE_REFUSED",
+      message:
+        existingRunId == null
+          ? `Refusing to force overwrite ${filePath}: existing file has no Argus report metadata.`
+          : `Refusing to force overwrite ${filePath}: existing report belongs to run_id "${existingRunId}", not "${runId}".`,
+    }
+  } catch (err) {
+    return {
+      code: "INSECURE_OVERWRITE_REFUSED",
+      message: `Refusing to force overwrite ${filePath}: existing file could not be read (${err instanceof Error ? err.message : String(err)}).`,
+    }
+  }
+}
+
 const SEVERITY_ORDER: FindingSeverity[] = ["Critical", "High", "Medium", "Low", "Informational"]
 
 const SEVERITY_PREFIX: Record<FindingSeverity, string> = {
@@ -309,6 +336,7 @@ const VALID_AGENT_VALUES = new Set<ArgusAgentName>([
   "argus",
   "sentinel",
   "pythia",
+  "audit-specialist",
   "scribe",
   "unknown",
 ])
@@ -766,6 +794,23 @@ function shouldIncludeFinding(finding: Finding, threshold: SeverityThreshold): b
   return FINDING_WEIGHT[finding.severity] >= THRESHOLD_WEIGHT[threshold]
 }
 
+function normalizeScopePath(value: string): string {
+  return value.replace(/^\.\//, "").replace(/\/+$|\\+$/g, "")
+}
+
+function isFindingInScope(finding: Finding, scope: string[]): boolean {
+  if (scope.length === 0) return true
+  const file = normalizeScopePath(finding.file)
+  return scope.some((entry) => {
+    const scoped = normalizeScopePath(entry)
+    return file === scoped || file.startsWith(`${scoped}/`)
+  })
+}
+
+function collectOutOfScopeFindings(findings: Finding[], scope: string[]): Finding[] {
+  return findings.filter((finding) => !isFindingInScope(finding, scope))
+}
+
 function calculateCounts(findings: Finding[]): FindingsCount {
   const counts = emptyCounts()
 
@@ -876,31 +921,6 @@ function hasDedupLineage(findings: Finding[]): boolean {
   })
 }
 
-function observationIdsForFinding(finding: Finding): string[] {
-  const observationIds = (finding as { observation_ids?: unknown }).observation_ids
-  if (Array.isArray(observationIds)) {
-    return observationIds.filter((id): id is string => typeof id === "string" && id.length > 0)
-  }
-  return typeof finding.observation_id === "string" && finding.observation_id.length > 0
-    ? [finding.observation_id]
-    : []
-}
-
-function compareObservationLineage(
-  eventFindings: Finding[],
-  reportFindings: Finding[],
-): { missing: string[]; extra: string[]; matches: boolean } {
-  const expected = new Set(eventFindings.flatMap(observationIdsForFinding))
-  const actual = new Set(reportFindings.flatMap(observationIdsForFinding))
-  const missing = Array.from(expected)
-    .filter((id) => !actual.has(id))
-    .sort((a, b) => a.localeCompare(b))
-  const extra = Array.from(actual)
-    .filter((id) => !expected.has(id))
-    .sort((a, b) => a.localeCompare(b))
-  return { missing, extra, matches: missing.length === 0 && extra.length === 0 }
-}
-
 export function validateReportQuality(
   findings: Finding[],
   policy: QualityGatePolicy,
@@ -1210,6 +1230,18 @@ export async function executeReportGeneration(
   const qualityGatePolicy = args.quality_gate_policy ?? "warn"
   const toolCoveragePolicy = args.tool_coverage_policy ?? "enforce"
   const expectedRunId = resolveExpectedRunId(args, context, deps)
+  const invalidRegenerationOptions =
+    args.force === true && args.revision != null
+      ? {
+          code: "INVALID_REGENERATION_OPTIONS",
+          message: "force and revision must not both be set.",
+        }
+      : args.revision != null && (!Number.isInteger(args.revision) || args.revision < 2)
+        ? {
+            code: "INVALID_REGENERATION_OPTIONS",
+            message: "revision must be an integer greater than or equal to 2.",
+          }
+        : null
 
   // Ensure report-input.json is materialized before attempting disk lookup.
   // Scribe may call generate_report without calling read_findings first,
@@ -1234,6 +1266,18 @@ export async function executeReportGeneration(
   const preflightPolicy = args.preflight_policy ?? "warn"
   let preflightWarningSection: string | null = null
   const warningBullets: string[] = []
+  const state = reportInputToAuditState(reportInput)
+  const scope = args.scope.length > 0 ? args.scope : reportInput.scope
+  const finalFindings = dedupeFindingsForFinalOutput(reportInput.findings)
+  const outOfScopeFindings = collectOutOfScopeFindings(finalFindings, scope)
+  if (outOfScopeFindings.length > 0) {
+    const locations = outOfScopeFindings.map(formatLocation).join(", ")
+    const message = `findings outside audited scope: ${locations}`
+    if (preflightPolicy === "strict-fail") {
+      throw new Error(`Preflight failed (strict-fail): ${message}`)
+    }
+    warningBullets.push(`- ${message}`)
+  }
 
   // Hard gate: refuse to generate a report if key audit tools have not been executed
   if (toolCoveragePolicy !== "skip") {
@@ -1284,11 +1328,24 @@ export async function executeReportGeneration(
     const inputFindings = dedupeFindingsForFinalOutput(reportInput.findings)
     const hasLineage = hasDedupLineage(reportInput.findings)
     const shouldCheckParity = eventFindings.length === inputFindings.length || hasLineage
+    const lineage = hasLineage
+      ? validateFindingLineage(projectFindings(events), reportInput.findings)
+      : null
     const parity = shouldCheckParity
-      ? hasLineage
-        ? compareObservationLineage(projectFindings(events), reportInput.findings)
-        : compareIssueFingerprintSets(eventFindings, inputFindings)
-      : { missing: [], extra: [], matches: true }
+      ? lineage
+        ? {
+            missing: lineage.missing_observation_ids,
+            extra: lineage.phantom_observation_ids,
+            duplicates: lineage.duplicate_observation_ids,
+            countMismatches: lineage.count_mismatches,
+            matches: lineage.valid,
+          }
+        : {
+            ...compareIssueFingerprintSets(eventFindings, inputFindings),
+            duplicates: [],
+            countMismatches: [],
+          }
+      : { missing: [], extra: [], duplicates: [], countMismatches: [], matches: true }
 
     if (!shouldCheckParity) {
       const unverifiableSummary = `event_findings=${eventFindings.length}, report_findings=${inputFindings.length}`
@@ -1319,6 +1376,14 @@ export async function executeReportGeneration(
       if (parity.extra.length > 0) {
         warningBullets.push(`- Extra ${parityLabel}: ${parity.extra.join(", ")}`)
       }
+      if (parity.duplicates.length > 0) {
+        warningBullets.push(`- Duplicate ${parityLabel}: ${parity.duplicates.join(", ")}`)
+      }
+      if (parity.countMismatches.length > 0) {
+        warningBullets.push(
+          `- Observation count mismatches: ${parity.countMismatches.map((item) => item.check).join(", ")}`,
+        )
+      }
     }
   } catch (err) {
     if (err instanceof Error && err.message.startsWith("Preflight failed (strict-fail)")) {
@@ -1340,9 +1405,6 @@ export async function executeReportGeneration(
     ].join("\n")
   }
 
-  const state = reportInputToAuditState(reportInput)
-  const scope = args.scope.length > 0 ? args.scope : reportInput.scope
-  const finalFindings = dedupeFindingsForFinalOutput(reportInput.findings)
   const findings = sortFindingsDeterministically(
     finalFindings.filter((finding) => shouldIncludeFinding(finding, threshold)),
   )
@@ -1441,6 +1503,7 @@ export async function executeReportGeneration(
     date: new Date(auditDate),
     outputDir: ".opencode/reports/",
     runId: runId || undefined,
+    revision: args.revision,
   })
 
   const result: ReportGenerationResult = {
@@ -1453,6 +1516,11 @@ export async function executeReportGeneration(
     contractDiagnostics: diagnostics,
   }
 
+  if (invalidRegenerationOptions) {
+    result.error = invalidRegenerationOptions
+    return result
+  }
+
   try {
     const loadConfig = deps.loadConfig ?? loadArgusConfig
     const projectDir = resolveProjectDir(context)
@@ -1467,14 +1535,28 @@ export async function executeReportGeneration(
       }
       return result
     }
-    const fullPath = path.join(resolvedOutput, canonicalFilename)
+    const { filePath: fullPath } = resolveReportPath({
+      contractName: args.project_name,
+      date: new Date(auditDate),
+      outputDir: resolvedOutput,
+      runId: runId || undefined,
+      revision: args.revision,
+    })
 
     // Single-writer policy: check for duplicate writes with same run_id
     if (runId) {
-      const duplicateError = await checkDuplicateWrite(fullPath, runId)
-      if (duplicateError) {
-        result.error = duplicateError
-        return result
+      if (args.force === true) {
+        const forceError = await checkSafeForceOverwrite(fullPath, runId)
+        if (forceError) {
+          result.error = forceError
+          return result
+        }
+      } else {
+        const duplicateError = await checkDuplicateWrite(fullPath, runId)
+        if (duplicateError) {
+          result.error = duplicateError
+          return result
+        }
       }
     }
 
@@ -1504,6 +1586,10 @@ export const reportGeneratorTool = tool({
       .enum(["critical", "high", "medium", "low", "informational"])
       .default("informational"),
     preflight_policy: tool.schema.enum(["warn", "strict-fail"]).optional(),
+    quality_gate_policy: tool.schema
+      .enum(["warn", "strict-fail"])
+      .optional()
+      .describe("Controls whether report quality gate violations warn or fail generation."),
     tool_coverage_policy: tool.schema
       .enum(["enforce", "warn", "skip"])
       .optional()
@@ -1517,6 +1603,18 @@ export const reportGeneratorTool = tool({
       .describe(
         "The canonical run ID from <argus-context>. The tool reads the materialized report-input.json from disk using this ID.",
       ),
+    revision: tool.schema
+      .number()
+      .optional()
+      .describe(
+        "Caller-supplied report revision. Must be an integer >= 2 and writes a -r{revision} file.",
+      ),
+    force: tool.schema
+      .boolean()
+      .optional()
+      .describe(
+        "Overwrite only the base canonical report path when existing Argus metadata matches the same run_id.",
+      ),
   },
   async execute(args, context) {
     const result = await executeReportGeneration(args, context)