solidity-argus 0.3.6 → 0.5.6

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

@@ -1,15 +1,19 @@
-import { existsSync } from "node:fs"
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs"
 import path from "node:path"
 import { type ToolContext, tool } from "@opencode-ai/plugin"
 import { loadArgusConfig } from "../config/loader"
 import type { ArgusConfig } from "../config/types"
 import { readEvents } from "../features/persistent-state/event-sink"
-import type { DropDiagnostic, DropPolicy } from "../shared/drop-diagnostics"
+import { resolveRunIdFromOpencodeSession } from "../features/persistent-state/global-run-index"
+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 { createLogger } from "../shared/logger"
 import { resolveProjectDir } from "../shared/project-utils"
 import { resolveReportPath } from "../shared/report-path-resolver"
-import { normalizeToCanonicalFinding } from "../state/adapters"
+import { isNonEmptyString } from "../shared/type-guards"
+import { SEVERITY_RANK } from "../shared/validation-constants"
 import {
   compareIssueFingerprintSets,
   dedupeFindingsForFinalOutput,
@@ -21,6 +25,8 @@ import { checkReportPreflight } from "./report-preflight"
 
 type SeverityThreshold = "critical" | "high" | "medium" | "low" | "informational"
 
+type ToolCoveragePolicy = "enforce" | "warn" | "skip"
+
 type ReportGeneratorArgs = {
   project_name: string
   scope: string[]
@@ -28,8 +34,9 @@ type ReportGeneratorArgs = {
   severity_threshold?: SeverityThreshold
   quality_gate_policy?: QualityGatePolicy
   report_input?: string
-  audit_state?: string
   preflight_policy?: PreflightPolicy
+  tool_coverage_policy?: ToolCoveragePolicy
+  run_id?: string
 }
 
 type FindingsCount = {
@@ -44,6 +51,7 @@ export type ReportGenerationResult = {
   report: string
   findingsCount: FindingsCount
   filename: string
+  run_id: string
   contentHash: string
   qualityGates: ReportQualityValidation
   contractDiagnostics: DropDiagnostic[]
@@ -72,6 +80,7 @@ export type ReportGenerationDependencies = {
     runId: string,
     projectDir: string,
   ) => Promise<import("../state/schemas").AuditEvent[]>
+  resolveCanonicalRunId?: (sessionId: string, projectDir: string) => string | null | undefined
 }
 
 export const SINGLE_WRITER_POLICY_VERSION = "1.0.0"
@@ -147,13 +156,8 @@ const FINDING_WEIGHT: Record<FindingSeverity, number> = {
   Informational: 1,
 }
 
-const SEVERITY_RANK: Record<FindingSeverity, number> = {
-  Critical: 0,
-  High: 1,
-  Medium: 2,
-  Low: 3,
-  Informational: 4,
-}
+/** Sentinel for missing/unknown tool execution timestamps (schema requires startTime > 0). */
+const UNKNOWN_TIMESTAMP_SENTINEL = 1
 
 const MISSING_IMPACT_TEXT = "Impact details were not provided in the finding payload."
 const MISSING_RECOMMENDATION_TEXT =
@@ -175,19 +179,6 @@ function emptyCounts(): FindingsCount {
   }
 }
 
-function emptyAuditState(findings: Finding[] = []): AuditState {
-  return {
-    sessionId: "",
-    projectDir: "",
-    contractsReviewed: [],
-    findings,
-    toolsExecuted: [],
-    currentPhase: "complete",
-    scope: [],
-    startTime: 0,
-  }
-}
-
 /**
  * Parse a location string like "File.sol:18-22" or "File.sol:18" into { file, lines }.
  * Returns undefined if the string doesn't match a recognized format.
@@ -236,11 +227,15 @@ export function normalizeRawFinding(raw: Record<string, unknown>): Record<string
     }
   }
 
-  // file + lines: accept location string as alias
-  if (typeof result.file !== "string" && typeof result.location === "string") {
+  // file + lines: accept location string as alias.
+  // Always attempt to extract lines from location, even when file is already set.
+  // LLMs commonly provide both file and location (e.g. file="src/Vault.sol", location="Vault.sol:18-23").
+  if (typeof result.location === "string") {
     const parsed = parseLocationString(result.location as string)
     if (parsed) {
-      result.file = parsed.file
+      if (typeof result.file !== "string" || (result.file as string).length === 0) {
+        result.file = parsed.file
+      }
       if (!Array.isArray(result.lines) || (result.lines as unknown[]).length !== 2) {
         result.lines = parsed.lines
       }
@@ -297,79 +292,11 @@ export function normalizeRawFinding(raw: Record<string, unknown>): Record<string
     result.description = result.check
   }
 
-  return result
-}
-
-function hasMinimumFindingFields(
-  f: unknown,
-): f is { check: string; file: string; lines: [number, number] } {
-  if (typeof f !== "object" || f === null) return false
-  const obj = f as Record<string, unknown>
-  return (
-    typeof obj.check === "string" &&
-    obj.check.length > 0 &&
-    typeof obj.file === "string" &&
-    Array.isArray(obj.lines) &&
-    obj.lines.length === 2
-  )
-}
-
-const VALID_SEVERITIES: ReadonlySet<string> = new Set([
-  "Critical",
-  "High",
-  "Medium",
-  "Low",
-  "Informational",
-])
-const VALID_SOURCES: ReadonlySet<string> = new Set([
-  "slither",
-  "manual",
-  "pattern",
-  "scvd",
-  "solodit",
-  "fuzz",
-])
-
-function normalizeFinding(f: Record<string, unknown>): Finding {
-  const severity =
-    typeof f.severity === "string" && VALID_SEVERITIES.has(f.severity)
-      ? (f.severity as Finding["severity"])
-      : "Informational"
-  const confidence =
-    typeof f.confidence === "string" && ["High", "Medium", "Low"].includes(f.confidence)
-      ? (f.confidence as Finding["confidence"])
-      : "Low"
-  const source =
-    typeof f.source === "string" && VALID_SOURCES.has(f.source)
-      ? (f.source as Finding["source"])
-      : "manual"
-  const description = typeof f.description === "string" ? f.description : (f.check as string)
-  const id = typeof f.id === "string" ? f.id : `${f.check}:${f.file}:${(f.lines as number[])[0]}`
-  return {
-    id,
-    check: f.check as string,
-    severity,
-    confidence,
-    description,
-    file: f.file as string,
-    lines: f.lines as [number, number],
-    source,
-    remediation: typeof f.remediation === "string" ? f.remediation : undefined,
-    exploitReference: typeof f.exploitReference === "string" ? f.exploitReference : undefined,
-    ...(typeof f.impact === "string" ? { impact: f.impact } : {}),
-    ...(typeof f.recommendation === "string" ? { recommendation: f.recommendation } : {}),
-    ...(typeof f.proofOfConcept === "string" ? { proofOfConcept: f.proofOfConcept } : {}),
-    ...(typeof f.proof_of_concept === "string" ? { proofOfConcept: f.proof_of_concept } : {}),
-  } as Finding
-}
-
-export type ParseAuditStateOptions = {
-  dropPolicy?: DropPolicy
-}
+  if (!Array.isArray(result.lines) || (result.lines as unknown[]).length !== 2) {
+    result.lines = [0, 0]
+  }
 
-export type ParseAuditStateResult = {
-  state: AuditState
-  diagnostics: DropDiagnostic[]
+  return result
 }
 
 type ParseReportInputResult = {
@@ -406,80 +333,193 @@ function reportInputToAuditState(reportInput: ReportInput): AuditState {
     proxyContracts: reportInput.proxyContracts,
     patternVersion: reportInput.patternVersion,
     skillsLoaded: reportInput.skillsLoaded,
+    unavailableTools: reportInput.unavailableTools,
   }
 }
 
-function buildLegacyCompatibleReportInput(
-  state: AuditState,
-  context: ToolContext,
+function normalizeToolsExecutedDefaults(
+  parsed: unknown,
+  expectedRunId: string | undefined,
   diagnostics: ReturnType<typeof createDropDiagnosticsCollector>,
-): ReportInput {
-  diagnostics.warn(
-    "REPORT_INPUT_DEPRECATED_LEGACY_PAYLOAD",
-    "Legacy audit_state payload is deprecated; pass report_input with canonical ReportInput schema.",
-    "audit_state",
-  )
-
-  const runId = state.sessionId || context.sessionID || "legacy-run"
-  const sessionId = state.sessionId || context.sessionID || runId
+): void {
+  if (!parsed || typeof parsed !== "object") return
+  const obj = parsed as Record<string, unknown>
+  if (!Array.isArray(obj.toolsExecuted)) return
+
+  const runId = (typeof obj.run_id === "string" && obj.run_id) || expectedRunId || "unknown"
+  let patched = false
+
+  for (const entry of obj.toolsExecuted) {
+    if (!entry || typeof entry !== "object") continue
+    const rec = entry as Record<string, unknown>
+    if (typeof rec.startTime !== "number" || rec.startTime <= 0) {
+      rec.startTime = UNKNOWN_TIMESTAMP_SENTINEL
+      patched = true
+    }
+    if (typeof rec.success !== "boolean") {
+      rec.success = true
+      patched = true
+    }
+    if (typeof rec.findingsCount !== "number" || rec.findingsCount < 0) {
+      rec.findingsCount = 0
+      patched = true
+    }
+    if (!isNonEmptyString(rec.run_id)) {
+      rec.run_id = runId
+      patched = true
+    }
+    if (!isNonEmptyString(rec.schema_version)) {
+      rec.schema_version = SCHEMA_VERSION
+      patched = true
+    }
+  }
 
-  if (!state.sessionId) {
+  if (patched) {
     diagnostics.warn(
-      "REPORT_INPUT_SYNTHESIZED_SESSION",
-      "Legacy payload missing sessionId; synthesized session_id from tool context/run_id.",
-      "session_id",
+      "REPORT_INPUT_TOOLS_EXECUTED_NORMALIZED",
+      "toolsExecuted entries were missing canonical fields (startTime, success, findingsCount, run_id, schema_version); defaults applied.",
+      "toolsExecuted",
     )
   }
-  if (!state.projectDir) {
-    diagnostics.warn(
-      "REPORT_INPUT_SYNTHESIZED_PROJECT_DIR",
-      "Legacy payload missing projectDir; synthesized projectDir from tool context.",
-      "projectDir",
-    )
+}
+
+function resolveExpectedRunId(
+  args: ReportGeneratorArgs,
+  context: ToolContext,
+  deps: ReportGenerationDependencies,
+): string | undefined {
+  // 1. Explicit run_id from LLM args (highest priority)
+  if (isNonEmptyString(args.run_id)) {
+    return args.run_id.trim()
+  }
+
+  // 2. Global run index lookup by session ID
+  const sessionId = context.sessionID
+  const projectDir = resolveProjectDir(context)
+  if (isNonEmptyString(sessionId)) {
+    const resolveCanonicalRunId = deps.resolveCanonicalRunId ?? resolveRunIdFromOpencodeSession
+    const resolved = resolveCanonicalRunId(sessionId, projectDir)
+    if (isNonEmptyString(resolved)) {
+      return resolved
+    }
   }
 
-  const canonicalFindings = state.findings
-    .map((finding, index) => {
-      const normalized = normalizeToCanonicalFinding(finding, runId, index + 1)
-      for (const diag of normalized.diagnostics) {
-        diagnostics.warn(
-          "REPORT_INPUT_LEGACY_FINDING_NORMALIZED",
-          `[index:${index}] ${diag.message}`,
-          diag.field,
-        )
+  // When caller provides inline report_input, skip filesystem discovery —
+  // the caller already has their data and filesystem state may belong to a different run.
+  if (isNonEmptyString(args.report_input)) {
+    return undefined
+  }
+
+  // 3. Per-session state files (per-session managers write to sessions/state-{sessionId}.json)
+  const STALE_STATE_TTL_MS = 24 * 60 * 60 * 1000
+  const sessionsDir = path.join(projectDir, ".argus", "sessions")
+  try {
+    const entries = readdirSync(sessionsDir)
+    const stateFiles = entries.filter((e) => e.startsWith("state-") && e.endsWith(".json"))
+    const ranked = stateFiles
+      .map((name) => {
+        const filePath = path.join(sessionsDir, name)
+        try {
+          return { name, path: filePath, mtime: statSync(filePath).mtimeMs }
+        } catch {
+          return null
+        }
+      })
+      .filter((entry): entry is NonNullable<typeof entry> => entry !== null)
+      .sort((a, b) => b.mtime - a.mtime)
+
+    for (const entry of ranked) {
+      try {
+        const stateRaw = JSON.parse(readFileSync(entry.path, "utf-8")) as Record<string, unknown>
+        const stateSessionId = stateRaw.sessionId
+        const savedAt = typeof stateRaw.savedAt === "number" ? stateRaw.savedAt : 0
+        const isFresh = Date.now() - savedAt < STALE_STATE_TTL_MS
+        if (
+          typeof stateSessionId === "string" &&
+          stateSessionId.trim().length > 0 &&
+          !stateSessionId.startsWith("ses_") &&
+          isFresh
+        ) {
+          const resolver = createAuditArtifactResolver(stateSessionId, projectDir)
+          const hasArtifacts =
+            existsSync(resolver.paths().reportInputFile) || existsSync(resolver.paths().journalFile)
+          if (hasArtifacts) {
+            return stateSessionId
+          }
+        }
+      } catch {
+        /* skip unreadable session file */
       }
-      return normalized.data
-    })
-    .filter((finding) => finding.check.length > 0 && finding.file.length > 0)
+    }
+  } catch {
+    /* sessions dir doesn't exist */
+  }
 
-  return {
-    run_id: runId,
-    seq: state.toolsExecuted.length + canonicalFindings.length,
-    session_id: sessionId,
-    tool_call_id: "legacy-adapter",
-    source: "report-generator-legacy-adapter",
-    schema_version: SCHEMA_VERSION,
-    projectDir: state.projectDir || resolveProjectDir(context),
-    findings: canonicalFindings,
-    toolsExecuted: state.toolsExecuted.map((toolExec) => ({
-      ...toolExec,
-      run_id: runId,
-      schema_version: SCHEMA_VERSION,
-    })),
-    scope: state.scope,
-    soloditResults: state.soloditResults,
-    fuzzCounterexamples: state.fuzzCounterexamples,
-    coverageReport: state.coverageReport,
-    gasHotspots: state.gasHotspots,
-    proxyContracts: state.proxyContracts,
-    patternVersion: state.patternVersion,
-    skillsLoaded: state.skillsLoaded,
+  // 4. Shared audit state (legacy fallback)
+  try {
+    const sharedStatePath = path.join(projectDir, ".argus", "argus-state.json")
+    if (existsSync(sharedStatePath)) {
+      const stateRaw = JSON.parse(readFileSync(sharedStatePath, "utf-8")) as Record<string, unknown>
+      const stateSessionId = stateRaw.sessionId
+      const savedAt = typeof stateRaw.savedAt === "number" ? stateRaw.savedAt : 0
+      const isFresh = Date.now() - savedAt < STALE_STATE_TTL_MS
+      if (
+        typeof stateSessionId === "string" &&
+        stateSessionId.trim().length > 0 &&
+        !stateSessionId.startsWith("ses_") &&
+        isFresh
+      ) {
+        const resolver = createAuditArtifactResolver(stateSessionId, projectDir)
+        const hasArtifacts =
+          existsSync(resolver.paths().reportInputFile) || existsSync(resolver.paths().journalFile)
+        if (hasArtifacts) {
+          return stateSessionId
+        }
+      }
+    }
+  } catch {
+    /* fallback path */
   }
+
+  return undefined
+}
+
+function finalizeReportInputSelection(
+  reportInput: ReportInput,
+  diagnostics: ReturnType<typeof createDropDiagnosticsCollector>,
+  expectedRunId?: string,
+): ParseReportInputResult {
+  if (reportInput.run_id.startsWith("ses_")) {
+    diagnostics.error(
+      "REPORT_INPUT_RUN_ID_MISMATCH",
+      "ReportInput run_id must be a canonical run identifier, not an OpenCode session id (ses_*).",
+      "run_id",
+    )
+    throwContractMismatch(
+      "ReportInput contract mismatch: run_id/session_id conflation detected",
+      diagnostics.getDiagnostics(),
+    )
+  }
+
+  if (expectedRunId && reportInput.run_id !== expectedRunId) {
+    diagnostics.error(
+      "REPORT_INPUT_CANONICAL_RUN_MISMATCH",
+      `ReportInput run_id ${reportInput.run_id} does not match canonical run_id ${expectedRunId}.`,
+      "run_id",
+    )
+    throwContractMismatch(
+      "ReportInput contract mismatch: report_input run_id diverges from canonical run_id",
+      diagnostics.getDiagnostics(),
+    )
+  }
+
+  return { reportInput, diagnostics: diagnostics.getDiagnostics() }
 }
 
 function parseReportInputPayload(
   args: ReportGeneratorArgs,
   context: ToolContext,
+  expectedRunId: string | undefined,
 ): ParseReportInputResult {
   const diagnostics = createDropDiagnosticsCollector(
     "warn",
@@ -487,7 +527,7 @@ function parseReportInputPayload(
     "argus_generate_report",
   )
 
-  if (typeof args.report_input === "string" && args.report_input.trim().length > 0) {
+  if (isNonEmptyString(args.report_input)) {
     let parsed: unknown
     try {
       parsed = JSON.parse(args.report_input)
@@ -503,44 +543,109 @@ function parseReportInputPayload(
       )
     }
 
+    normalizeToolsExecutedDefaults(parsed, expectedRunId, diagnostics)
+
     const validation = validateReportInput(parsed)
     if (!validation.success) {
       for (const error of validation.errors) {
-        diagnostics.error(
-          "REPORT_INPUT_CONTRACT_MISMATCH",
+        diagnostics.warn(
+          "REPORT_INPUT_INLINE_VALIDATION_FAILED",
           `${error.field}: ${error.message}`,
           error.field,
         )
       }
-      throwContractMismatch(
-        "ReportInput contract mismatch: report_input failed schema validation",
-        diagnostics.getDiagnostics(),
-      )
-    }
-
-    if (typeof args.audit_state === "string" && args.audit_state.trim().length > 0) {
       diagnostics.warn(
-        "REPORT_INPUT_LEGACY_FIELD_IGNORED",
-        "Both report_input and audit_state were provided; audit_state is ignored.",
-        "audit_state",
+        "REPORT_INPUT_INLINE_FALLTHROUGH",
+        `Inline report_input failed validation (${validation.errors.length} errors). Falling back to disk artifact.`,
+        "report_input",
       )
+    } else {
+      return finalizeReportInputSelection(validation.data, diagnostics, expectedRunId)
     }
-
-    return { reportInput: validation.data, diagnostics: diagnostics.getDiagnostics() }
   }
 
-  if (typeof args.audit_state === "string" && args.audit_state.trim().length > 0) {
-    const legacy = parseAuditStateWithDiagnostics(args.audit_state, { dropPolicy: "warn" })
-    for (const diagnostic of legacy.diagnostics) {
-      diagnostics.warn(diagnostic.reason.code, diagnostic.reason.message, diagnostic.reason.field)
+  const effectiveRunId =
+    (isNonEmptyString(args.run_id) ? args.run_id.trim() : undefined) ?? expectedRunId
+
+  if (isNonEmptyString(effectiveRunId)) {
+    const projectDir = resolveProjectDir(context)
+    const resolver = createAuditArtifactResolver(effectiveRunId, projectDir)
+
+    const dedupedFile = resolver.paths().dedupedFindingsFile
+    if (existsSync(dedupedFile)) {
+      try {
+        const dedupedArtifact = JSON.parse(readFileSync(dedupedFile, "utf-8")) as {
+          findings?: unknown[]
+        }
+        if (Array.isArray(dedupedArtifact.findings) && dedupedArtifact.findings.length > 0) {
+          const reportInputFile = resolver.paths().reportInputFile
+          let baseInput: Record<string, unknown> = {}
+          if (existsSync(reportInputFile)) {
+            try {
+              baseInput = JSON.parse(readFileSync(reportInputFile, "utf-8")) as Record<
+                string,
+                unknown
+              >
+            } catch {
+              /* use empty base */
+            }
+          }
+          const merged = {
+            ...baseInput,
+            run_id: effectiveRunId,
+            findings: dedupedArtifact.findings,
+          }
+          const validation = validateReportInput(merged)
+          if (validation.success) {
+            return finalizeReportInputSelection(validation.data, diagnostics, expectedRunId)
+          }
+        }
+      } catch {
+        /* deduped file unreadable — fall through to report-input.json */
+      }
     }
-    const reportInput = buildLegacyCompatibleReportInput(legacy.state, context, diagnostics)
-    return { reportInput, diagnostics: diagnostics.getDiagnostics() }
-  }
 
+    const reportInputFile = resolver.paths().reportInputFile
+    if (existsSync(reportInputFile)) {
+      diagnostics.warn(
+        "REPORT_INPUT_DISK_FALLBACK",
+        `No report_input provided; reading materialized report-input.json from disk for run ${effectiveRunId}.`,
+        "report_input",
+      )
+      let parsed: unknown
+      try {
+        parsed = JSON.parse(readFileSync(reportInputFile, "utf-8"))
+      } catch {
+        diagnostics.error(
+          "REPORT_INPUT_DISK_CORRUPT",
+          `Materialized report-input.json for run ${effectiveRunId} is not valid JSON.`,
+          "report_input",
+        )
+        throwContractMismatch(
+          "ReportInput contract mismatch: corrupted disk artifact",
+          diagnostics.getDiagnostics(),
+        )
+      }
+      const validation = validateReportInput(parsed)
+      if (!validation.success) {
+        for (const error of validation.errors) {
+          diagnostics.error(
+            "REPORT_INPUT_DISK_VALIDATION_FAILED",
+            `${error.field}: ${error.message}`,
+            error.field,
+          )
+        }
+        throwContractMismatch(
+          "ReportInput contract mismatch: disk artifact failed schema validation",
+          diagnostics.getDiagnostics(),
+        )
+      }
+      return finalizeReportInputSelection(validation.data, diagnostics, expectedRunId)
+    }
+  }
   diagnostics.error(
     "REPORT_INPUT_MISSING",
-    "Missing report_input payload. Provide report_input (preferred) or legacy audit_state for transition.",
+    `Missing report_input payload. args.run_id=${args.run_id ?? "undefined"}, expectedRunId=${expectedRunId ?? "undefined"}. Provide report_input (preferred) or run_id for disk fallback.`,
     "report_input",
   )
   throwContractMismatch(
@@ -549,135 +654,6 @@ function parseReportInputPayload(
   )
 }
 
-function emitDropDiagnosticsForFindings(
-  rawItems: unknown[],
-  normalized: Record<string, unknown>[],
-  validFindings: Finding[],
-  diag: ReturnType<typeof createDropDiagnosticsCollector>,
-): void {
-  const droppedCount = rawItems.length - validFindings.length
-  if (droppedCount <= 0) return
-
-  for (const item of normalized) {
-    if (hasMinimumFindingFields(item)) continue
-    const missing: string[] = []
-    if (typeof item.check !== "string" || (item.check as string).length === 0) missing.push("check")
-    if (typeof item.file !== "string") missing.push("file")
-    if (!Array.isArray(item.lines) || (item.lines as unknown[]).length !== 2) missing.push("lines")
-    diag.error(
-      "MISSING_REQUIRED_FIELD",
-      `Finding dropped: missing ${missing.join(", ") || "unknown fields"} after normalization`,
-      missing[0],
-    )
-  }
-}
-
-export function parseAuditState(auditState: string, options?: ParseAuditStateOptions): AuditState {
-  const policy = options?.dropPolicy ?? "warn"
-  const diag = createDropDiagnosticsCollector(policy, "report-generator")
-
-  let parsed: unknown
-  try {
-    parsed = JSON.parse(auditState)
-  } catch {
-    diag.error("MALFORMED_JSON", "audit_state is not valid JSON")
-    diag.throwIfStrict()
-    throw new Error(
-      "audit_state is not valid JSON — expected an AuditState object or Finding[] array",
-    )
-  }
-
-  if (Array.isArray(parsed)) {
-    const rawItems = parsed as unknown[]
-    const normalized = rawItems
-      .filter((item): item is Record<string, unknown> => typeof item === "object" && item !== null)
-      .map((item) => normalizeRawFinding(item))
-    const validFindings = normalized
-      .filter(hasMinimumFindingFields)
-      .map((f) => normalizeFinding(f as Record<string, unknown>))
-    emitDropDiagnosticsForFindings(rawItems, normalized, validFindings, diag)
-    diag.throwIfStrict()
-    return emptyAuditState(validFindings)
-  }
-
-  if (
-    typeof parsed === "object" &&
-    parsed !== null &&
-    Array.isArray((parsed as AuditState).findings)
-  ) {
-    const state = parsed as AuditState
-    const rawFindings = state.findings as unknown[]
-    const normalized = rawFindings
-      .filter((item): item is Record<string, unknown> => typeof item === "object" && item !== null)
-      .map((item) => normalizeRawFinding(item))
-    const validFindings = normalized
-      .filter(hasMinimumFindingFields)
-      .map((f) => normalizeFinding(f as Record<string, unknown>))
-    emitDropDiagnosticsForFindings(rawFindings, normalized, validFindings, diag)
-    diag.throwIfStrict()
-    return {
-      ...emptyAuditState(),
-      ...state,
-      findings: validFindings,
-    }
-  }
-
-  return emptyAuditState()
-}
-
-export function parseAuditStateWithDiagnostics(
-  auditState: string,
-  options?: ParseAuditStateOptions,
-): ParseAuditStateResult {
-  const policy = options?.dropPolicy ?? "warn"
-  const diag = createDropDiagnosticsCollector(policy, "report-generator")
-
-  let parsed: unknown
-  try {
-    parsed = JSON.parse(auditState)
-  } catch {
-    diag.error("MALFORMED_JSON", "audit_state is not valid JSON")
-    diag.throwIfStrict()
-    return { state: emptyAuditState(), diagnostics: diag.getDiagnostics() }
-  }
-
-  if (Array.isArray(parsed)) {
-    const rawItems = parsed as unknown[]
-    const normalized = rawItems
-      .filter((item): item is Record<string, unknown> => typeof item === "object" && item !== null)
-      .map((item) => normalizeRawFinding(item))
-    const validFindings = normalized
-      .filter(hasMinimumFindingFields)
-      .map((f) => normalizeFinding(f as Record<string, unknown>))
-    emitDropDiagnosticsForFindings(rawItems, normalized, validFindings, diag)
-    diag.throwIfStrict()
-    return { state: emptyAuditState(validFindings), diagnostics: diag.getDiagnostics() }
-  }
-
-  if (
-    typeof parsed === "object" &&
-    parsed !== null &&
-    Array.isArray((parsed as AuditState).findings)
-  ) {
-    const auditStateObj = parsed as AuditState
-    const rawFindings = auditStateObj.findings as unknown[]
-    const normalized = rawFindings
-      .filter((item): item is Record<string, unknown> => typeof item === "object" && item !== null)
-      .map((item) => normalizeRawFinding(item))
-    const validFindings = normalized
-      .filter(hasMinimumFindingFields)
-      .map((f) => normalizeFinding(f as Record<string, unknown>))
-    emitDropDiagnosticsForFindings(rawFindings, normalized, validFindings, diag)
-    diag.throwIfStrict()
-    return {
-      state: { ...emptyAuditState(), ...auditStateObj, findings: validFindings },
-      diagnostics: diag.getDiagnostics(),
-    }
-  }
-
-  return { state: emptyAuditState(), diagnostics: diag.getDiagnostics() }
-}
-
 function normalizeTitle(check: string): string {
   if (!check || typeof check !== "string") return "Unknown Check"
   return check
@@ -755,7 +731,7 @@ function getExtendedFinding(finding: Finding): Finding & ReportFindingFields {
 
 function getFindingImpact(finding: Finding): string {
   const extended = getExtendedFinding(finding)
-  if (typeof extended.impact === "string" && extended.impact.trim().length > 0) {
+  if (isNonEmptyString(extended.impact)) {
     return extended.impact.trim()
   }
   return MISSING_IMPACT_TEXT
@@ -763,10 +739,10 @@ function getFindingImpact(finding: Finding): string {
 
 function getFindingRecommendation(finding: Finding): string {
   const extended = getExtendedFinding(finding)
-  if (typeof extended.recommendation === "string" && extended.recommendation.trim().length > 0) {
+  if (isNonEmptyString(extended.recommendation)) {
     return extended.recommendation.trim()
   }
-  if (typeof finding.remediation === "string" && finding.remediation.trim().length > 0) {
+  if (isNonEmptyString(finding.remediation)) {
     return finding.remediation.trim()
   }
   return MISSING_RECOMMENDATION_TEXT
@@ -774,10 +750,10 @@ function getFindingRecommendation(finding: Finding): string {
 
 function getPocEvidence(finding: Finding): string | undefined {
   const extended = getExtendedFinding(finding)
-  if (typeof extended.proofOfConcept === "string" && extended.proofOfConcept.trim().length > 0) {
+  if (isNonEmptyString(extended.proofOfConcept)) {
     return extended.proofOfConcept.trim()
   }
-  if (typeof finding.exploitReference === "string" && finding.exploitReference.trim().length > 0) {
+  if (isNonEmptyString(finding.exploitReference)) {
     return finding.exploitReference.trim()
   }
   return undefined
@@ -972,17 +948,17 @@ function formatDuration(ms: number): string {
 export function buildProvenanceAppendix(
   state: AuditState,
   threshold: SeverityThreshold,
-  includedCount: number,
+  reportFindings: Finding[],
 ): string {
   const lines: string[] = ["## Appendix: Data Provenance"]
 
-  lines.push("- Data source: `report_input` payload (legacy `audit_state` supported via adapter)")
+  lines.push("- Data source: `report_input` payload")
   lines.push(`- Severity threshold applied: ${threshold}`)
-  lines.push(`- Findings included in report: ${includedCount}`)
+  lines.push(`- Findings included in report: ${reportFindings.length}`)
 
-  if (state.findings.length > 0) {
+  if (reportFindings.length > 0) {
     const sourceCounts: Record<string, number> = {}
-    for (const f of state.findings) {
+    for (const f of reportFindings) {
       sourceCounts[f.source] = (sourceCounts[f.source] ?? 0) + 1
     }
     lines.push("")
@@ -1098,10 +1074,51 @@ export async function executeReportGeneration(
   const includeExecutiveSummary = args.include_executive_summary ?? true
   const threshold = args.severity_threshold ?? "low"
   const qualityGatePolicy = args.quality_gate_policy ?? "warn"
-  const { reportInput, diagnostics } = parseReportInputPayload(args, context)
+  const toolCoveragePolicy = args.tool_coverage_policy ?? "enforce"
+  const expectedRunId = resolveExpectedRunId(args, context, deps)
+
+  // Ensure report-input.json is materialized before attempting disk lookup.
+  // Scribe may call generate_report without calling read_findings first,
+  // or read_findings may have materialized under a different run_id.
+  if (typeof expectedRunId === "string" && expectedRunId.length > 0) {
+    const projectDir = resolveProjectDir(context)
+    const resolver = createAuditArtifactResolver(expectedRunId, projectDir)
+    if (!existsSync(resolver.paths().reportInputFile)) {
+      try {
+        const { materializeReportInput } = await import(
+          "../features/persistent-state/findings-materializer"
+        )
+        await materializeReportInput(expectedRunId, projectDir, context.sessionID)
+      } catch {
+        /* Best-effort: parseReportInputPayload will produce a clear error if the file is still missing */
+      }
+    }
+  }
+
+  const { reportInput, diagnostics } = parseReportInputPayload(args, context, expectedRunId)
+
   const preflightPolicy = args.preflight_policy ?? "warn"
   let preflightWarningSection: string | null = null
   const warningBullets: string[] = []
+
+  // Hard gate: refuse to generate a report if key audit tools have not been executed
+  if (toolCoveragePolicy !== "skip") {
+    const missingTools = computeMissingKeyTools(
+      reportInput.toolsExecuted,
+      reportInput.unavailableTools,
+    )
+    if (missingTools.length > 0) {
+      const toolList = missingTools.join(", ")
+      if (toolCoveragePolicy === "enforce") {
+        throw new Error(
+          `Tool coverage gate failed: the following key audit tools have not been executed: ${toolList}. ` +
+            'Run the missing tools before generating a report, or pass tool_coverage_policy: "warn" to override.',
+        )
+      }
+      warningBullets.push(`- Tool coverage incomplete: ${toolList} not executed`)
+    }
+  }
+
   try {
     const readEventsFn = deps.readEvents ?? readEvents
     const events = await readEventsFn(reportInput.run_id, reportInput.projectDir)
@@ -1182,7 +1199,22 @@ export async function executeReportGeneration(
     )
   }
   const counts = calculateCounts(findings)
-  const auditDate = new Date().toISOString().slice(0, 10)
+  // Derive audit date from the run's start time for deterministic output.
+  // Falls back to the earliest toolsExecuted timestamp, then current date as last resort.
+  // Exclude UNKNOWN_TIMESTAMP_SENTINEL (patched-in value for missing timestamps).
+  const runStartTime = reportInput.toolsExecuted.reduce(
+    (earliest, exec) =>
+      typeof exec.startTime === "number" &&
+      exec.startTime > UNKNOWN_TIMESTAMP_SENTINEL &&
+      exec.startTime < earliest
+        ? exec.startTime
+        : earliest,
+    Number.MAX_SAFE_INTEGER,
+  )
+  const auditDate =
+    runStartTime < Number.MAX_SAFE_INTEGER
+      ? new Date(runStartTime).toISOString().slice(0, 10)
+      : new Date().toISOString().slice(0, 10)
 
   context.metadata({ title: `Generate audit report: ${args.project_name}` })
 
@@ -1237,10 +1269,13 @@ export async function executeReportGeneration(
     sections.push(preflightWarningSection)
   }
 
-  sections.push(buildProvenanceAppendix(state, threshold, findings.length))
+  sections.push(buildProvenanceAppendix(state, threshold, findings))
 
   // Embed report metadata for single-writer policy enforcement
-  const runId = reportInput.run_id || state.sessionId || ""
+  const runId = expectedRunId ?? reportInput.run_id
+  if (runId.startsWith("ses_")) {
+    throw new Error("Report generation requires canonical run_id; received OpenCode session id")
+  }
   if (runId) {
     sections.push(buildReportMetadataComment(runId))
   }
@@ -1258,6 +1293,7 @@ export async function executeReportGeneration(
     report: reportMarkdown,
     findingsCount: counts,
     filename: canonicalFilename,
+    run_id: runId,
     contentHash,
     qualityGates,
     contractDiagnostics: diagnostics,
@@ -1267,8 +1303,17 @@ export async function executeReportGeneration(
     const loadConfig = deps.loadConfig ?? loadArgusConfig
     const projectDir = resolveProjectDir(context)
     const config = loadConfig(projectDir)
-    const outputDir = config.reporting?.output_dir ?? ".argus/reports/"
-    const fullPath = path.join(projectDir, outputDir, canonicalFilename)
+    const rawOutputDir = config.reporting?.output_dir ?? ".argus/reports/"
+    const resolvedOutput = path.resolve(projectDir, rawOutputDir)
+    const projectRoot = projectDir.endsWith(path.sep) ? projectDir : projectDir + path.sep
+    if (resolvedOutput !== projectDir && !resolvedOutput.startsWith(projectRoot)) {
+      result.error = {
+        code: "OUTPUT_DIR_TRAVERSAL",
+        message: `output_dir "${rawOutputDir}" resolves outside the project root. Report not written.`,
+      }
+      return result
+    }
+    const fullPath = path.join(resolvedOutput, canonicalFilename)
 
     // Single-writer policy: check for duplicate writes with same run_id
     if (runId) {
@@ -1285,6 +1330,10 @@ export async function executeReportGeneration(
     const logger = createLogger()
     const message = err instanceof Error ? err.message : String(err)
     logger.warn(`Failed to write report to disk: ${message}`)
+    result.error = {
+      code: "WRITE_FAILED",
+      message,
+    }
   }
 
   return result
@@ -1292,20 +1341,39 @@ export async function executeReportGeneration(
 
 export const reportGeneratorTool = tool({
   description:
-    "Generate a professional markdown security audit report from versioned ReportInput payloads with legacy audit_state compatibility.",
+    "Generate a professional markdown security audit report. Pass project_name, scope, and run_id — the tool reads the materialized ReportInput artifact from disk automatically.",
   args: {
     project_name: tool.schema.string(),
     scope: tool.schema.array(tool.schema.string()),
     include_executive_summary: tool.schema.boolean().default(true),
     severity_threshold: tool.schema
       .enum(["critical", "high", "medium", "low", "informational"])
-      .default("low"),
-    report_input: tool.schema.string().optional(),
-    audit_state: tool.schema.string().optional(),
+      .default("informational"),
     preflight_policy: tool.schema.enum(["warn", "strict-fail"]).optional(),
+    tool_coverage_policy: tool.schema
+      .enum(["enforce", "warn", "skip"])
+      .optional()
+      .describe(
+        "Controls whether report generation requires key audit tools to have been executed. " +
+          "Defaults to 'enforce'.",
+      ),
+    run_id: tool.schema
+      .string()
+      .optional()
+      .describe(
+        "The canonical run ID from <argus-context>. The tool reads the materialized report-input.json from disk using this ID.",
+      ),
   },
   async execute(args, context) {
     const result = await executeReportGeneration(args, context)
-    return JSON.stringify(result)
+    // Return a slim payload to avoid OpenCode truncating large tool results.
+    // The full markdown is already written to disk at result.filePath.
+    // Truncated JSON breaks tool-tracking-hook parsing, which prevents
+    // reportGenerated from being set and blocks run finalization.
+    const { report, ...slimResult } = result
+    return JSON.stringify({
+      ...slimResult,
+      reportSummary: `Report written to disk (${report.length} bytes, ${report.split("\n").length} lines). See filePath.`,
+    })
   },
 })