brl-subagent 2.3.9 → 2.5.0

package/src/recovery-engine.ts

@@ -0,0 +1,262 @@
+// Purpose: Pure recovery decision engine — identity, owner liveness classification, and the boot-scan plan over injected process deps.
+/**
+ * Option B U1 — recovery decision engine (pure over `RecoveryDeps`).
+ *
+ * The engine decides, for one persisted `running` record, whether its
+ * conductor is still live, whether to reject ownership, and whether to reap a
+ * marker-verified orphan child. It performs NO process work itself: every
+ * effect goes through the injected `RecoveryDeps`, so the full matrix is
+ * unit-testable without spawning processes. The boot orchestration lives in
+ * `src/recovery.ts`; the production `/proc` wiring in `src/proc.ts`.
+ *
+ * Decision order (`decideRecovery`):
+ *   - status not "running" → skip
+ *   - `interruptedAt` already set → never re-mark, but re-check for a leftover
+ *     live marker child and reap it again (B2 revisit)
+ *   - absent owner → skip (`no-owner`)
+ *   - owner present but unparsable → mark-only (`owner-unverifiable`), no kill
+ *   - owner alive (pid + start token match) → leave untouched
+ *   - owner alive but token unreadable → skip (`ownership-unverifiable`)
+ *   - owner dead → reap marker-verified orphan children, then mark
+ *
+ * Reaping is the ONE `escalateKill` sequence (src/kill-escalation.ts): SIGTERM
+ * every pid, wait one grace window, SIGKILL any survivor.
+ */
+
+import type { ProcessOwner, SubagentRun } from "./types";
+import { resolveTerminalRunEntry } from "./state";
+import { escalateKill, type EscalationTarget } from "./kill-escalation";
+
+// ---------------------------------------------------------------------------
+// Dependency injection surface
+// ---------------------------------------------------------------------------
+
+/** The process primitives the decision engine needs (injected for testability). */
+export interface RecoveryDeps {
+	/** True when the pid exists (SIGCONT/`kill -0` semantics; EPERM counts as alive). */
+	pidAlive(pid: number): boolean;
+	/** The process start-time token, or undefined when /proc is unavailable/unreadable. */
+	startTokenOf(pid: number): string | undefined;
+	/** Pids whose environment carries `CHILD_MARKER_ENV_KEY=<marker>`; [] when /proc is unavailable. */
+	findByMarker(marker: string): number[];
+	/** Send a signal to a pid (may throw when the pid is already gone). */
+	kill(pid: number, signal: NodeJS.Signals): void;
+	/** Sleep between SIGTERM and SIGKILL. */
+	sleep(ms: number): Promise<void>;
+	/** Grace period in ms between SIGTERM and SIGKILL. */
+	graceMs: number;
+}
+
+/** Which persisted store a candidate record came from. */
+export type RecoveryKind = "run" | "agent";
+
+/** A persisted `running` record projected into the shape the engine reasons over. */
+export interface RecoveryRecord {
+	id: string;
+	kind: RecoveryKind;
+	status: string;
+	interruptedAt?: string;
+	owner?: ProcessOwner;
+	childMarker?: string;
+	/** Original record for the caller's write-back; opaque to this module. */
+	source?: unknown;
+}
+
+export type RecoverySkipReason =
+	| "not-running"
+	| "already-interrupted"
+	| "no-owner"
+	| "owner-alive"
+	| "ownership-unverifiable";
+
+export type RecoveryMarkReason = "owner-dead" | "child-orphaned" | "owner-unverifiable";
+
+/** What the engine decided to do with one record (before any process work). */
+export type RecoveryPlan =
+	| { decision: "skip"; reason: RecoverySkipReason }
+	| { decision: "mark"; reason: RecoveryMarkReason; reap: number[] }
+	/** Already-marked record re-checked this boot: reap leftovers, never re-mark. */
+	| { decision: "reap"; reason: "revisit-interrupted"; reap: number[] };
+
+/** The engine's verdict on an owner identity. */
+export type OwnerState = "alive" | "dead" | "unknown";
+
+/** The result of applying a plan (kills performed, survivors logged). */
+export interface RecoveryOutcome {
+	id: string;
+	kind: RecoveryKind;
+	decision: "skip" | "mark" | "reap";
+	reason: string;
+	reaped: number[];
+	survived: number[];
+}
+
+// ---------------------------------------------------------------------------
+// Candidate projection
+// ---------------------------------------------------------------------------
+
+/**
+ * Durability identity for a newly dispatched run record. A retry inherits the
+ * original's dispatchId and records `resumeOf`/`attempt`; a fresh dispatch
+ * mints a new dispatchId with attempt 1. These are RECORD fields, not
+ * delegate_task params (D4).
+ */
+export function newDispatchIdentity(source: SubagentRun | undefined): {
+	dispatchId: string;
+	resumeOf?: string;
+	attempt: number;
+} {
+	return {
+		dispatchId: source?.dispatchId ?? crypto.randomUUID(),
+		resumeOf: source?.id,
+		attempt: source ? (source.attempt ?? 1) + 1 : 1,
+	};
+}
+
+/**
+ * Collapse run entries to ONE per id before the scan, using the ONE shared
+ * preference rule (`resolveTerminalRunEntry`, src/state.ts): terminal-first;
+ * among non-terminal entries the D3 `interruptedAt` mark wins over the
+ * original spawn entry; otherwise the first entry seen. Ids keep their
+ * first-seen order. Delegating keeps the recovery scan and U3's display/retry
+ * lookup from diverging (the historical duplicate rule picked the marked clone
+ * while the resolver picked the unmarked spawn).
+ */
+export function dedupeRunEntriesById(runs: SubagentRun[]): SubagentRun[] {
+	const ids: string[] = [];
+	const seen = new Set<string>();
+	for (const run of runs) {
+		if (seen.has(run.id)) continue;
+		seen.add(run.id);
+		ids.push(run.id);
+	}
+	const collapsed: SubagentRun[] = [];
+	for (const id of ids) {
+		const resolved = resolveTerminalRunEntry(runs, id);
+		if (resolved) collapsed.push(resolved);
+	}
+	return collapsed;
+}
+
+// ---------------------------------------------------------------------------
+// The decision engine (pure over RecoveryDeps)
+// ---------------------------------------------------------------------------
+
+/**
+ * Classify the recorded owner's liveness. `unknown` means the pid is alive but
+ * the start token could not be read, so pid reuse cannot be excluded — the
+ * caller must not act on it.
+ */
+export function classifyOwner(owner: ProcessOwner, deps: RecoveryDeps): OwnerState {
+	if (!deps.pidAlive(owner.pid)) return "dead";
+	// An empty recorded token means the WRITER could not read one (non-/proc
+	// platform). Even on a host that can read tokens now, the record's identity
+	// is unverifiable — never act on it.
+	if (!owner.start) return "unknown";
+	const token = deps.startTokenOf(owner.pid);
+	if (token === undefined) return "unknown";
+	return token === owner.start ? "alive" : "dead";
+}
+
+/**
+ * True when an owner carries a usable pid (positive integer). Anything else —
+ * a missing pid, a string, 0, a negative, NaN, a fraction — is UNPARSABLE
+ * ownership: the record is marked but the kill path is never touched.
+ */
+function hasParsableOwnerPid(owner: ProcessOwner): boolean {
+	return Number.isInteger(owner.pid) && owner.pid > 0;
+}
+
+/**
+ * Decide what to do with one persisted record. Pure — no process is touched.
+ * Reaping pids come ONLY from a marker scan: without a verified marker match
+ * the engine never proposes a kill. An unparsable owner is mark-only (see the
+ * module header's three-way owner policy): interrupt is certain, ownership is
+ * not, so `reap` is empty and the kill path stays untouched.
+ */
+export function decideRecovery(record: RecoveryRecord, deps: RecoveryDeps): RecoveryPlan {
+	if (record.status !== "running") return { decision: "skip", reason: "not-running" };
+	if (record.interruptedAt) {
+		// Already marked: NEVER re-mark (idempotent), but a SIGKILL survivor or a
+		// child whose marker was unreadable at mark time must stay revisitable.
+		// The registry entry is retained, so every later boot re-checks it.
+		const reap = record.childMarker ? deps.findByMarker(record.childMarker) : [];
+		return reap.length > 0
+			? { decision: "reap", reason: "revisit-interrupted", reap }
+			: { decision: "skip", reason: "already-interrupted" };
+	}
+	if (!record.owner) return { decision: "skip", reason: "no-owner" };
+	if (!hasParsableOwnerPid(record.owner)) {
+		return { decision: "mark", reason: "owner-unverifiable", reap: [] };
+	}
+
+	const ownerState = classifyOwner(record.owner, deps);
+	if (ownerState === "alive") return { decision: "skip", reason: "owner-alive" };
+	if (ownerState === "unknown") return { decision: "skip", reason: "ownership-unverifiable" };
+
+	const reap = record.childMarker ? deps.findByMarker(record.childMarker) : [];
+	return {
+		decision: "mark",
+		reason: reap.length > 0 ? "child-orphaned" : "owner-dead",
+		reap,
+	};
+}
+
+/**
+ * Escalate a set of pids together: SIGTERM every one, wait ONE grace window,
+ * then SIGKILL any survivor. Returns the pids still alive afterwards. Thin
+ * adapter over the shared `escalateKill` helper (src/kill-escalation.ts), which
+ * `recoverRecord` (one record) and `runBootScan` (the whole scan) both call, so
+ * a boot with N orphans waits one grace period total, never N.
+ */
+export async function reapPids(pids: number[], deps: RecoveryDeps): Promise<number[]> {
+	const unique = [...new Set(pids)];
+	const targets: EscalationTarget[] = unique.map((pid) => ({
+		terminate: () => {
+			deps.kill(pid, "SIGTERM");
+		},
+		forceKill: () => {
+			deps.kill(pid, "SIGKILL");
+		},
+		verifyDeath: () => !deps.pidAlive(pid),
+	}));
+	const survivors = await escalateKill(targets, {
+		graceMs: deps.graceMs,
+		sleep: deps.sleep,
+	});
+	const survivedSet = new Set(survivors);
+	return unique.filter((_, index) => survivedSet.has(targets[index]));
+}
+
+/**
+ * Apply a record's plan: SIGTERM every marker-verified orphan, wait the grace
+ * period, SIGKILL any survivor, then report. Never throws on a vanished pid.
+ */
+export async function recoverRecord(
+	record: RecoveryRecord,
+	deps: RecoveryDeps,
+): Promise<RecoveryOutcome> {
+	const plan = decideRecovery(record, deps);
+	if (plan.decision === "skip") {
+		return {
+			id: record.id,
+			kind: record.kind,
+			decision: "skip",
+			reason: plan.reason,
+			reaped: [],
+			survived: [],
+		};
+	}
+
+	const reaped = [...new Set(plan.reap)];
+	const survived = await reapPids(reaped, deps);
+
+	return {
+		id: record.id,
+		kind: record.kind,
+		decision: plan.decision,
+		reason: plan.reason,
+		reaped,
+		survived,
+	};
+}

package/src/recovery.ts

@@ -0,0 +1,325 @@
+// Purpose: Boot-time recovery scan — decides whether a persisted running record is live, reaps orphaned children, and marks interrupted records.
+/**
+ * Option B U1 — recovery boot orchestration.
+ *
+ * A run record is written BEFORE its effect (the spawn), so a crashed
+ * conductor leaves `running` records and — on the foreground path — an
+ * orphaned child process. This module runs the boot-time scan that decides, in
+ * a FRESH process, which of those records are genuinely live:
+ *
+ *   - `interruptedAt` already set  → never re-mark, but re-check for a leftover
+ *     live marker child and reap it again (B2 revisit)
+ *   - owner alive (pid + start token match) → leave untouched
+ *   - owner dead → reap a marker-verified orphan child (SIGTERM → grace →
+ *     SIGKILL), then mark `interruptedAt` on the record
+ *
+ * The decision logic itself is the pure engine in `src/recovery-engine.ts`
+ * (type/external surface unchanged); this module owns candidate sourcing and
+ * the scan loop. `recoverInflightRuns` sources candidates from the durable
+ * registry (`src/run-registry.ts`) — NOT from the current session's run
+ * entries, which a fresh process cannot see after a crash — and
+ * `recoverProduction` is the entry point that also enforces the platform guard.
+ *
+ * Reaping waits ONE grace window for the whole scan (`runBootScan` collects
+ * every orphan pid and escalates them together), so N orphans cost one grace
+ * period, not N.
+ *
+ * PLATFORM BOUNDARY (required): the `/proc` reads live in `src/proc.ts`.
+ * Where `/proc` is unavailable, `recoverProduction` SKIPS the whole scan with
+ * one log line — `process.kill(pid, 0)` liveness alone cannot rule out pid
+ * reuse, so we NEVER kill an unverified process and NEVER mark a record when
+ * ownership cannot be verified.
+ */
+
+import { listInflightRuns, type InflightRun } from "./run-registry";
+import { assertSafeAgentId } from "./sanitize";
+import { isProcAvailable, defaultRecoveryDeps } from "./proc";
+import { decideRecovery, reapPids, type RecoveryDeps, type RecoveryRecord } from "./recovery-engine";
+import type { Logger } from "./logging";
+
+// Re-export the pure engine and the production wiring so existing importers
+// (`index.ts`, the recovery/registry suites) keep their single entry point.
+export * from "./recovery-engine";
+export * from "./proc";
+
+// ---------------------------------------------------------------------------
+// Boot scan orchestration
+// ---------------------------------------------------------------------------
+
+/** Aggregate counts from one boot scan (also the shape the log line carries). */
+export interface BootScanSummary {
+	scanned: number;
+	skipped: number;
+	/** Records whose interruption mark was DURABLY written (issue #304). */
+	marked: number;
+	/** Records whose mark the engine decided but whose durable write failed (#304). */
+	markFailures: number;
+	reaped: number;
+	/** Already-marked records that had leftover children reaped again this boot. */
+	revisited: number;
+	skippedUnverifiable: number;
+	skippedNoOwner: number;
+	/** Registry entries skipped fail-closed because their id failed the write guard. */
+	skippedUnsafeIds: number;
+}
+
+/** The all-zero summary (a skipped scan / an empty registry). */
+export function emptyBootScanSummary(): BootScanSummary {
+	return {
+		scanned: 0,
+		skipped: 0,
+		marked: 0,
+		markFailures: 0,
+		reaped: 0,
+		revisited: 0,
+		skippedUnverifiable: 0,
+		skippedNoOwner: 0,
+		skippedUnsafeIds: 0,
+	};
+}
+
+export interface BootScanOptions {
+	records: RecoveryRecord[];
+	deps: RecoveryDeps;
+	/**
+	 * Persist the D3 mark for this record (registry entry; agent record for
+	 * background). Returns `false` when the durable write did NOT land — the scan
+	 * then counts a `markFailure` instead of claiming `marked` (issue #304). A
+	 * `void` return keeps the historical assume-success contract.
+	 */
+	mark(record: RecoveryRecord, interruptedAt: string): boolean | void;
+	now?: () => Date;
+	log?: Pick<Logger, "debug" | "info" | "warn">;
+}
+
+/**
+ * The warning context shared by the two mark outcomes (issue #306 nit 3): the
+ * record identity, why it was marked, which orphan pids were reaped, and which
+ * of those survived the escalation. One construction so the "marked" and
+ * "mark failed" warnings cannot drift apart.
+ */
+function markWarningPayload(
+	record: RecoveryRecord,
+	reason: string,
+	reaped: number[],
+	survived: ReadonlySet<number>,
+): { id: string; kind: RecoveryRecord["kind"]; reason: string; reaped: number[]; survived: number[] } {
+	return {
+		id: record.id,
+		kind: record.kind,
+		reason,
+		reaped,
+		survived: reaped.filter((pid) => survived.has(pid)),
+	};
+}
+
+/**
+ * Run the decision engine over every candidate, reap markers, and mark the
+ * records whose conductor is dead. Every decision is logged; the UI is
+ * deliberately silent (the notice/offer surface lands in U3).
+ *
+ * Idempotent: a marked record has `interruptedAt` set in memory before the
+ * next iteration, so a second scan over the same array is a no-op.
+ *
+ * Wait-once: every orphan pid across every record is reaped in ONE
+ * SIGTERM → grace → SIGKILL window (the `reapActiveChildren` shape), so a boot
+ * with N orphans is not an N × graceMs stall.
+ */
+export async function runBootScan(options: BootScanOptions): Promise<BootScanSummary> {
+	const { records, deps, mark } = options;
+	const nowIso = (options.now?.() ?? new Date()).toISOString();
+	const summary = emptyBootScanSummary();
+	summary.scanned = records.length;
+
+	// Plan every record first (pure), then reap ALL proposed pids together —
+	// including leftovers of already-marked records (never re-marked).
+	const planned = records.map((record) => ({ record, plan: decideRecovery(record, deps) }));
+	const allReaps = planned.flatMap(({ plan }) =>
+		plan.decision === "mark" || plan.decision === "reap" ? plan.reap : [],
+	);
+	const survived = new Set(await reapPids(allReaps, deps));
+
+	for (const { record, plan } of planned) {
+		if (plan.decision === "mark") {
+			const durable = mark(record, nowIso) !== false;
+			// In-memory mark first: guarantees the scan is idempotent even when
+			// the caller's write-back is append-only (run entries) or deferred.
+			record.interruptedAt = nowIso;
+			const reaped = [...new Set(plan.reap)];
+			summary.reaped += reaped.length;
+			const markWarning = markWarningPayload(record, plan.reason, reaped, survived);
+			if (durable) {
+				summary.marked++;
+				options.log?.warn("Recovery: marked interrupted record", markWarning);
+			} else {
+				// Issue #304: the mark did NOT land. Count the failure and warn with
+				// the id — this must be visible even when nothing was marked, so it
+				// does not hide behind the caller's `summary.marked > 0` gate.
+				summary.markFailures++;
+				options.log?.warn("Recovery: registry mark failed", markWarning);
+			}
+		} else if (plan.decision === "reap") {
+			// B2 revisit: the record was already marked (so it is never re-marked),
+			// but it still carried a live marker child — reap it again this boot.
+			const reaped = [...new Set(plan.reap)];
+			summary.revisited++;
+			summary.reaped += reaped.length;
+			options.log?.warn("Recovery: reaped a leftover child of an interrupted record", {
+				id: record.id,
+				kind: record.kind,
+				reaped,
+				survived: reaped.filter((pid) => survived.has(pid)),
+			});
+		} else {
+			summary.skipped++;
+			if (plan.reason === "ownership-unverifiable") summary.skippedUnverifiable++;
+			if (plan.reason === "no-owner") summary.skippedNoOwner++;
+			options.log?.debug("Recovery: left record untouched", {
+				id: record.id,
+				kind: record.kind,
+				reason: plan.reason,
+			});
+		}
+	}
+
+	return summary;
+}
+
+// ---------------------------------------------------------------------------
+// Registry-sourced scan (the production candidate source)
+// ---------------------------------------------------------------------------
+
+/** The subset of a persisted background agent record the scan reasons over. */
+export interface PersistedAgentLike {
+	status: string;
+	interruptedAt?: string;
+	owner?: RecoveryRecord["owner"];
+	childMarker?: string;
+}
+
+export interface RegistryScanOptions {
+	deps: RecoveryDeps;
+	/**
+	 * Persist the D3 mark for this record (registry entry; agent record for
+	 * background). Returns `false` when the durable write did not land.
+	 */
+	mark(record: RecoveryRecord, interruptedAt: string): boolean | void;
+	/**
+	 * Read ONE background run's agent record by id (never the whole store).
+	 * Returns null when the record is absent; absent defaults to an in-flight
+	 * entry so a registry without an agent file is still marked, not skipped.
+	 */
+	readAgentRecord?(id: string): PersistedAgentLike | null;
+	now?: () => Date;
+	log?: Pick<Logger, "debug" | "info" | "warn">;
+}
+
+/**
+ * The production boot scan: candidate runs come from the durable registry
+ * (`listInflightRuns`), NOT from the current session's entries and NOT from a
+ * full parse of `.pi/subagents/`. This is what makes detection work on pi's
+ * default fresh startup after a conductor crash.
+ *
+ * Foreground/unit entries become `kind: "run"` candidates straight from the
+ * registry; background entries become `kind: "agent"` candidates enriched by
+ * reading THAT ONE agent file (so a stale registry entry whose agent record is
+ * already terminal is dropped). Legacy records with no registry entry are
+ * invisible here — consistent with the maintained `no-owner` policy (don't act
+ * on what we cannot verify).
+ */
+export async function recoverInflightRuns(options: RegistryScanOptions): Promise<BootScanSummary> {
+	// Issue #304 read/write asymmetry, fail-closed: `listInflightRuns` accepts
+	// any string id, but every write (and `markInterrupted`) resolves through
+	// `assertSafeAgentId`. Acting on an entry the writer could never have
+	// produced is unsafe, so SKIP those here — counted and reported in ONE log
+	// line — instead of attempting a mark that would silently no-op.
+	const addressable: InflightRun[] = [];
+	const unsafeIds: string[] = [];
+	for (const entry of listInflightRuns()) {
+		try {
+			assertSafeAgentId(entry.id);
+			addressable.push(entry);
+		} catch {
+			unsafeIds.push(entry.id);
+		}
+	}
+	if (unsafeIds.length > 0) {
+		options.log?.warn("Recovery: skipped registry entries whose id fails the UUID guard", {
+			count: unsafeIds.length,
+			ids: unsafeIds,
+		});
+	}
+
+	const records: RecoveryRecord[] = [];
+	for (const entry of addressable) {
+		if (entry.kind === "background") {
+			const agent = options.readAgentRecord?.(entry.id) ?? null;
+			if (agent && agent.status !== "running") continue;
+			records.push({
+				id: entry.id,
+				kind: "agent",
+				status: "running",
+				interruptedAt: agent?.interruptedAt ?? entry.interruptedAt,
+				owner: agent?.owner ?? entry.owner,
+				childMarker: agent?.childMarker ?? entry.childMarker,
+				source: entry,
+			});
+		} else {
+			records.push({
+				id: entry.id,
+				kind: "run",
+				status: "running",
+				interruptedAt: entry.interruptedAt,
+				owner: entry.owner,
+				childMarker: entry.childMarker,
+				source: entry,
+			});
+		}
+	}
+	const summary = await runBootScan({
+		records,
+		deps: options.deps,
+		mark: options.mark,
+		now: options.now,
+		log: options.log,
+	});
+	summary.skippedUnsafeIds = unsafeIds.length;
+	return summary;
+}
+
+// ---------------------------------------------------------------------------
+// Production entry (owns the /proc platform guard)
+// ---------------------------------------------------------------------------
+
+export interface ProductionRecoveryOptions {
+	/** Process deps; defaults to the real /proc wiring (`defaultRecoveryDeps`). */
+	deps?: RecoveryDeps;
+	/** Persist the D3 mark for this record; `false` = the durable write failed. */
+	mark(record: RecoveryRecord, interruptedAt: string): boolean | void;
+	readAgentRecord?(id: string): PersistedAgentLike | null;
+	now?: () => Date;
+	log?: Pick<Logger, "debug" | "info" | "warn">;
+}
+
+/**
+ * The production boot-recovery entry. It owns the `/proc` platform guard so the
+ * guarantee "nothing is marked or killed without /proc ownership verification"
+ * is enforced — and testable — BELOW the extension entry point: on a platform
+ * without `/proc` it returns an empty summary without scanning, instead of
+ * relying on the caller's early return.
+ */
+export async function recoverProduction(options: ProductionRecoveryOptions): Promise<BootScanSummary> {
+	if (!isProcAvailable()) {
+		options.log?.info(
+			"Boot recovery skipped: /proc start-token verification unavailable on this platform",
+		);
+		return emptyBootScanSummary();
+	}
+	return recoverInflightRuns({
+		deps: options.deps ?? defaultRecoveryDeps(),
+		mark: options.mark,
+		readAgentRecord: options.readAgentRecord,
+		now: options.now,
+		log: options.log,
+	});
+}

package/src/reports.ts

@@ -1,3 +1,4 @@
+// Purpose: Compliance reporting: file-access records and secrets-exposure detection.
 /**
  * brl-subagent — Compliance Reports (E5)
  *
@@ -128,6 +129,11 @@ function extractFilesFromOutputSummary(outputSummary: string): string[] {
 
 /**
  * Check if a file path matches any sensitive file pattern.
+ *
+ * This is the PATH-based detector for the secrets exposure report: it answers
+ * "did this run touch a sensitive FILE?" rather than "did the output text
+ * happen to mention one?". It was previously unreachable dead code; keep it in
+ * sync with SENSITIVE_FILE_PATTERNS / FILE_SEVERITY_MAP above.
  */
 function isSensitiveFile(filePath: string): { match: boolean; pattern?: string; severity?: "high" | "medium" | "low" } {
 	const normalizedPath = filePath.toLowerCase();
@@ -221,20 +227,40 @@ export function buildFileAccessReport(runs: SubagentRun[]): FileAccessReport {
  */
 export function buildSecretsExposureReport(runs: SubagentRun[]): SecretsExposureReport {
 	const exposures: SecretsExposureEntry[] = [];
+	// Dedupe key set: one exposure per (file, runId) regardless of whether the
+	// finding came from the text scan or the path scan.
+	const seen = new Set<string>();
 
 	for (const run of runs) {
 		// Check task description for sensitive keywords
 		const taskCheck = hasSensitiveTaskKeywords(run.task);
 		if (taskCheck.match && taskCheck.keyword) {
-			exposures.push({
-				file: `task:${taskCheck.keyword}`,
-				runId: run.id,
-				runLabel: run.label,
-				severity: "medium",
-			});
+			const file = `task:${taskCheck.keyword}`;
+			const key = `${file}\x00${run.id}`;
+			if (!seen.has(key)) {
+				seen.add(key);
+				exposures.push({
+					file,
+					runId: run.id,
+					runLabel: run.label,
+					severity: "medium",
+				});
+			}
+		}
+
+		// Files this run touched (mirrors buildFileAccessReport). Computed BEFORE
+		// the text scan so a text hit that is only a FRAGMENT of a touched path
+		// (e.g. ".env" inside "config/prod/.env") is not double-reported — the
+		// path scan below reports the real, full path instead.
+		const touched: string[] = [];
+		if (run.fullOutput && run.fullOutput.includes("diff --git")) {
+			touched.push(...extractFilesFromGitDiff(run.fullOutput));
+		}
+		if (touched.length === 0 && run.outputSummary) {
+			touched.push(...extractFilesFromOutputSummary(run.outputSummary));
 		}
 
-		// Check output for sensitive file access
+		// Check output text for sensitive file mentions.
 		const outputToCheck = [
 			run.outputSummary,
 			run.fullOutput,
@@ -254,8 +280,18 @@ export function buildSecretsExposureReport(runs: SubagentRun[]): SecretsExposure
 						}
 					}
 
+					// Report the text that actually matched, not the regex
+					// literal — the `file` field is what a reader acts on.
+					const matched = outputToCheck.match(pattern)?.[0] ?? patternStr;
+					// Fragment of a touched file? The path scan below reports the full
+					// path — skip this fragment so one file yields ONE entry.
+					if (touched.some((p) => p.toLowerCase().includes(matched.toLowerCase()))) continue;
+					const dedupeKey = `${matched}\x00${run.id}`;
+					if (seen.has(dedupeKey)) continue;
+					seen.add(dedupeKey);
+
 					exposures.push({
-						file: patternStr,
+						file: matched,
 						runId: run.id,
 						runLabel: run.label,
 						severity,
@@ -263,6 +299,26 @@ export function buildSecretsExposureReport(runs: SubagentRun[]): SecretsExposure
 				}
 			}
 		}
+
+		// Path-based detection: flag the sensitive FILES this run actually
+		// touched — the full path, even when the output text never names it (and
+		// even when it names it in a different case: the path is normalized
+		// before matching).
+		for (const file of touched) {
+			const check = isSensitiveFile(file);
+			if (!check.match) continue;
+
+			const dedupeKey = `${file}\x00${run.id}`;
+			if (seen.has(dedupeKey)) continue;
+			seen.add(dedupeKey);
+
+			exposures.push({
+				file,
+				runId: run.id,
+				runLabel: run.label,
+				severity: check.severity ?? "high",
+			});
+		}
 	}
 
 	return { exposures };