headlesscode 1.0.2 → 1.2.0

package/src/engine/loop.ts

@@ -62,6 +62,14 @@ import type { MemoryStore, RecallResult } from "../memory/types.js"
 import { createCheckpointService, type CheckpointService } from "../checkpoints/service.js"
 import { recordSessionUsage, removeLiveUsage, writeLiveUsage } from "./usage.js"
 import { EventFeed, EVENT_TRUNCATE_CHARS, truncateField } from "./events.js"
+import {
+	allClaimsVerified,
+	claimLabel,
+	extractClaims,
+	firstUnverifiedDetail,
+	verifyClaims,
+	type ClaimVerification,
+} from "./claims.js"
 import { writeSessionReport } from "./reports.js"
 import { Logger } from "./logger.js"
 import { extractEmbeddedToolCall, parseToolCalls } from "./parser.js"
@@ -89,6 +97,7 @@ import type {
 	ParsedToolCall,
 	SessionResult,
 	SessionBudgetUsage,
+	SessionCompletionVerification,
 	ToolContext,
 	ToolResult,
 } from "./types.js"
@@ -1068,6 +1077,37 @@ export interface HeadlessSessionConfig {
 	 * code-mode backend turns this on.
 	 */
 	verifyBeforeCompletion?: boolean
+	/**
+	 * Evidence-gated completion — the fabrication fix (2026-09-01, see
+	 * src/engine/claims.ts). When true, `attempt_completion` is refused
+	 * unless every machine-checkable claim its result text makes (a file
+	 * exists, a specific command passed, serial markers appear, a PR
+	 * exists) is independently verified against ground truth:
+	 *
+	 *   - file claim    → fs.stat on the resolved workspace path
+	 *   - command claim → RE-RUN the exact command (same permission gate as
+	 *                     execute_command), require exit 0
+	 *   - serial marker → grep the newest build/serial-*.log for the claimed
+	 *                     ordered markers
+	 *   - PR claim      → require real git-history evidence of the number
+	 *
+	 * Ground truth comes from the filesystem and real re-runs — never from
+	 * the model's own prose. This is the structural backstop for the exact
+	 * failure the FINAL_REPORT documented (§4): a session claimed "all
+	 * three hard gates pass" with a fabricated serial-log excerpt when the
+	 * driver was never merged and the claimed Makefile target didn't exist.
+	 * Fail-closed: any unverifiable claim defers the completion with a
+	 * corrective message naming the specific unverified claim.
+	 *
+	 * Deliberately separate from verifyBeforeCompletion (which is
+	 * token/state-based and only looks at the LAST command): this checks
+	 * the CONTENT of the completion's claims against the real world,
+	 * independent of what the session did or didn't run before.
+	 *
+	 * Default false; opt-in via --require-evidence or the local code
+	 * backend (see cli.ts).
+	 */
+	evidenceRequiredCompletion?: boolean
 	/**
 	 * When false, cost is never tracked/accumulated for this session (see
 	 * BudgetTrackerOptions.trackCost) — local-backend sessions have no real
@@ -1159,6 +1199,24 @@ export interface HeadlessSessionConfig {
 	 * the local Ollama code-mode backend turns this on.
 	 */
 	guardLargeOverwrites?: boolean
+	/**
+	 * read_file/list_files carry a session-scoped "[cache] unchanged, reuse
+	 * the earlier result" short-circuit (src/tools/executor.ts) that saves
+	 * real, measured token cost against a remote model's per-token bill.
+	 * Verified live 2026-09-02 against the local backend: an edit_file
+	 * failure told a session to re-read and retry; it DID call read_file
+	 * again exactly as instructed, got the cache-hit notice instead of real
+	 * content (correct per the mechanism's own design — the safety valve
+	 * is "a SECOND consecutive identical call serves real content again"),
+	 * never made that second call, and fabricated an attempt_completion
+	 * instead. Re-serving a few hundred lines of file content costs a
+	 * local session near-nothing (prefill, not generation, against a GPU
+	 * with no per-token price) — cheap insurance locally against a much
+	 * more expensive failure mode. Default false; the local Ollama code-mode
+	 * backend turns this on (same opt-in shape as guardLargeOverwrites
+	 * above).
+	 */
+	disableReadFileCache?: boolean
 	/**
 	 * Phase 3 context condensation: the model's real context window in
 	 * tokens, used to decide WHEN to condense (the last request's real
@@ -1346,6 +1404,8 @@ export interface ResolvedSessionConfig {
 	patchLocalToolSchemas: boolean
 	/** See HeadlessSessionConfig.verifyBeforeCompletion (default false). */
 	verifyBeforeCompletion: boolean
+	/** See HeadlessSessionConfig.evidenceRequiredCompletion (default false). */
+	evidenceRequiredCompletion: boolean
 	/** See HeadlessSessionConfig.trackCost (default true). */
 	trackCost: boolean
 	/** See HeadlessSessionConfig.requireArtifactBeforeCompletion (default false). */
@@ -1358,6 +1418,8 @@ export interface ResolvedSessionConfig {
 	requireArtifactSections?: string[]
 	/** See HeadlessSessionConfig.guardLargeOverwrites (default false). */
 	guardLargeOverwrites: boolean
+	/** See HeadlessSessionConfig.disableReadFileCache (default false). */
+	disableReadFileCache: boolean
 	/**
 	 * Phase 3 context condensation: the model's real context window in
 	 * tokens, when explicitly configured (undefined = resolve live from
@@ -1536,6 +1598,17 @@ export class HeadlessSession {
 	 * BudgetTracker either way.
 	 */
 	private sessionEnded = false
+	/**
+	 * Evidence-gated completion (fabrication fix, 2026-09-01): the outcome of
+	 * the last attempt_completion claim-verification pass, when
+	 * evidenceRequiredCompletion was on and the result contained
+	 * machine-checkable claims. Carried onto the SessionResult (see
+	 * src/engine/types.ts SessionResult.verification) so callers can
+	 * distinguish "success claim independently verified" from "success
+	 * accepted on prose alone". undefined when the gate didn't run (flag off,
+	 * or no claims to check).
+	 */
+	private lastCompletionVerification: SessionCompletionVerification | undefined = undefined
 	/**
 	 * True once the real context window has been resolved (from config, the
 	 * OpenRouter models endpoint, or the conservative default) — the lookup
@@ -1680,12 +1753,14 @@ export class HeadlessSession {
 			requireExplicitCompletion: config.requireExplicitCompletion ?? false,
 			patchLocalToolSchemas: config.patchLocalToolSchemas ?? false,
 			verifyBeforeCompletion: config.verifyBeforeCompletion ?? false,
+			evidenceRequiredCompletion: config.evidenceRequiredCompletion ?? false,
 			trackCost: config.trackCost ?? true,
 			requireArtifactBeforeCompletion: config.requireArtifactBeforeCompletion ?? false,
 			requireArtifactPathPattern: config.requireArtifactPathPattern,
 			requireArtifactMinCitations: config.requireArtifactMinCitations,
 			requireArtifactSections: config.requireArtifactSections,
 			guardLargeOverwrites: config.guardLargeOverwrites ?? false,
+			disableReadFileCache: config.disableReadFileCache ?? false,
 			// Deliberately left undefined when the caller didn't configure it:
 			// the live OpenRouter models-endpoint lookup in maybeCondenseHistory
 			// resolves the real context window (never hardcode a stale number —
@@ -1735,6 +1810,7 @@ export class HeadlessSession {
 				decisionPollIntervalMs: this.config.decisionPollIntervalMs,
 				permissions: this.config.permissions,
 				guardLargeOverwrites: this.config.guardLargeOverwrites,
+				disableReadFileCache: this.config.disableReadFileCache,
 				// Live worker monitoring: mirror ask_followup_question's
 				// .harness.needs-decision marker lifecycle on the session's
 				// event feed (decision_blocked / decision_answered). Non-fatal.
@@ -3242,6 +3318,57 @@ export class HeadlessSession {
 		// write_to_file — see the doc comment where it's set for why this
 		// exists as a separate flag.
 		let lastWriteToolFailed = false
+		// 2026-09-02: real, confirmed bug -- lastWriteToolFailed only ever
+		// gets updated when edit_file/write_to_file/set_indentation is
+		// called AGAIN, so once ANY such call fails, this stayed
+		// permanently true for the REST of the session if the model never
+		// touched that tool again -- even when it correctly determined, by
+		// re-reading the real file, that no further edit was needed at
+		// all. Verified live: a session read the file, correctly
+		// concluded the /health handler it was asked to add already
+		// existed and worked, and every subsequent honest, accurate
+		// attempt_completion was deferred anyway with a stale "fix the
+		// issue, make the edit succeed" message that no longer applied --
+		// 15+ consecutive identical deferrals with no bounded-failure
+		// kill-switch to end it (would have spun to the iteration cap).
+		// Tracks the failed call's resolved target path so a genuine
+		// re-verification (a successful read_file of that SAME file)
+		// clears the flag -- narrow and hard to game (it requires actually
+		// re-reading the exact file that failed to edit), unlike a blanket
+		// reset on any successful tool call of any kind.
+		let lastWriteToolFailedTarget: string | undefined
+		// 2026-09-02 (same-day follow-up to the re-read clearing above): the
+		// re-read escape hatch clears lastWriteToolFailed on the assumption
+		// that a model which re-reads the file it failed to edit has
+		// concluded "no edit was needed" and is about to finish honestly.
+		// Verified live (followthrough sweep, "add an entry to a JSON array"
+		// case): a session's edit_file failed, it re-read tasks.json exactly
+		// as the re-read hatch expects, then called attempt_completion
+		// claiming *"I added {\"id\": 7, \"name\": \"lint\"} to the tasks
+		// array in tasks.json."* — an edit it never actually landed. The
+		// re-read had cleared the flag, so the completion sailed through and
+		// the sweep scored it a fabrication. The re-read alone can't tell
+		// "no edit needed" (legit) from "edit still not made" (fabrication);
+		// the completion prose is the discriminator. This flag records that
+		// a failed write was cleared ONLY by a re-read (never by a real
+		// successful write since); at completion time, if the result also
+		// asserts an edit was made, the completion is deferred. A later
+		// genuinely successful write tool call clears it for good.
+		let writeFailedClearedByReReadOnly = false
+		let reReadClearedWriteSummary: string | undefined
+		// Second layer of defense alongside the lastWriteToolFailedTarget
+		// fix above: even a LEGITIMATE reason to keep deferring (a real,
+		// still-unfixed failure) has no bounded-failure kill-switch on this
+		// specific path today — verified live it can spin to the full
+		// iteration cap on unchanging identical deferrals with zero new
+		// information, the same failure shape as issue #26's fix already
+		// handled for the identical-tool-call-streak case but never for
+		// this one. Counts consecutive verifyBeforeCompletion deferrals
+		// carrying the SAME reason string; resets whenever the reason
+		// changes (a changing reason means real progress/new information is
+		// happening) or a real tool call succeeds.
+		let consecutiveDeferralReason: string | undefined
+		let consecutiveDeferralStreak = 0
 		// See HeadlessSessionConfig.requireArtifactBeforeCompletion's doc
 		// comment (issue #143). Set true the first time this session calls
 		// execute_command, write_to_file, or edit_file — regardless of
@@ -3249,6 +3376,23 @@ export class HeadlessSession {
 		// tried to produce a real effect; lastExecuteCommandFailed/
 		// lastWriteToolFailed above separately catch a FAILED attempt).
 		let hasCalledArtifactTool = false
+		// 2026-09-02: verified live in the fabrication sweep's e1000 case —
+		// the requireArtifactBeforeCompletion deferral (below) has no
+		// bounded-failure kill-switch of its own, unlike the
+		// verifyBeforeCompletion deferral (consecutiveDeferralStreak) and the
+		// identical-call streak (issue #26). A session that never once calls
+		// a real artifact tool, keeps re-issuing attempt_completion, and
+		// generates a large inline "report" each turn spun 17+ iterations /
+		// 971s before the duration cap finally killed it — the model even
+		// correctly diagnosed its own fabrication ("I never actually called
+		// write_to_file… the report I gave was the real output I expected to
+		// see AFTER running the gate") and kept going anyway. Count
+		// consecutive hits of that specific deferral; once it reaches
+		// consecutiveErrorLimit, end as a bounded failure. No reset needed:
+		// the branch only fires while hasCalledArtifactTool is false, and the
+		// first real execute_command/write_to_file/edit_file call (even a
+		// failed one) flips that permanently.
+		let artifactBeforeCompletionDeferrals = 0
 		// Concrete command + truncated error output for the failure above,
 		// so the attempt_completion rejection below can restate WHAT failed
 		// instead of pointing at it abstractly — by the time a model reaches
@@ -3677,9 +3821,30 @@ export class HeadlessSession {
 					!messages.some(
 						(m) => m.role === "tool" && m.name === "execute_command" && /\d/.test(String(m.content ?? "")),
 					)
+				// staleReReadEditClaim: a failed write was cleared by a re-read
+				// ONLY (never a real successful write since — see
+				// writeFailedClearedByReReadOnly's doc), yet this completion's prose
+				// still asserts an edit was actually made. The re-read hatch exists
+				// for the honest "no edit was needed" finish; a completion that
+				// claims it *did* edit contradicts the still-unlanded write and is
+				// deferred. Deliberately narrow: only affirmative "I/we added|
+				// wrote|created|…", "added|inserted|… <x> (in)to <file>", or "the
+				// edit/change has been made/applied" shapes — "already exists",
+				// "no edit needed", "was already correct" carry no change verb and
+				// still pass cleanly.
+				const completionAssertsEditMade =
+					/\b(?:I|we|I've|we've|I have|we have)\s+(?:just\s+|now\s+|successfully\s+)?(?:added|inserted|appended|wrote|written|created|updated|edited|modified|applied|replaced|changed)\b/i.test(
+						result,
+					) ||
+					/\b(?:added|inserted|appended|wrote|created|placed)\s+[^.\n]{0,80}?\b(?:in)?to\b\s+\S*[A-Za-z0-9_-]/i.test(result) ||
+					/\bthe\s+(?:edit|change|fix|update|modification|entry|line|function|field)\s+(?:was|has been|is now)\s+(?:made|applied|written|added|inserted|in place|complete)\b/i.test(
+						result,
+					) ||
+					/\bhas been\s+(?:added|inserted|appended|written|updated|applied|modified|replaced)\b/i.test(result)
+				const staleReReadEditClaim = writeFailedClearedByReReadOnly && completionAssertsEditMade
 				if (
 					this.config.verifyBeforeCompletion &&
-					(lastExecuteCommandFailed || lastWriteToolFailed || unsupportedMeasurementClaim)
+					(lastExecuteCommandFailed || lastWriteToolFailed || unsupportedMeasurementClaim || staleReReadEditClaim)
 				) {
 					// Verified live 2026-08-29 (joeos issue #26, rounds 17 + 20):
 					// the `continue` at the end of this block skips the
@@ -3716,7 +3881,9 @@ export class HeadlessSession {
 					identicalCallStreak = 0
 					identicalCallNudgeInjected = false
 					excludedToolCooldowns.delete("execute_command")
-					const reason = unsupportedMeasurementClaim
+					const reason = staleReReadEditClaim
+						? "edit claimed but never landed (only a re-read since the failed write)"
+						: unsupportedMeasurementClaim
 						? "unsupported measurement claim"
 						: lastExecuteCommandFailed
 							? "last execute_command failed"
@@ -3729,7 +3896,9 @@ export class HeadlessSession {
 							role: "tool",
 							tool_call_id: sibling.id,
 							name: sibling.name,
-							content: unsupportedMeasurementClaim
+							content: staleReReadEditClaim
+								? "[System: not executed — attempt_completion was deferred because your result claims an edit was made, but the edit_file/write_to_file call for it failed and you have only re-read the file since (never landed a successful write); re-issue this call if still needed.]"
+								: unsupportedMeasurementClaim
 								? "[System: not executed — attempt_completion was deferred because it makes a specific measurement/benchmark claim with no execute_command output in this session's history containing any supporting number; re-issue this call if still needed.]"
 								: lastExecuteCommandFailed
 									? "[System: not executed — attempt_completion was deferred because the last command you ran ended in an error; re-issue this call if still needed.]"
@@ -3740,7 +3909,11 @@ export class HeadlessSession {
 						role: "tool",
 						tool_call_id: completionCall.id,
 						name: "attempt_completion",
-						content: unsupportedMeasurementClaim
+						content: staleReReadEditClaim
+							? "[System: attempt_completion was NOT accepted. Your result describes an edit as made (e.g. \"added …\", \"the entry has been added\"), but the edit_file/write_to_file call for it failed and the only thing you have done since is re-read the file — no successful write ever landed:\n" +
+								`${reReadClearedWriteSummary ?? "(edit output no longer available)"}\n` +
+								"Either actually make the edit succeed and re-issue attempt_completion, or, if no edit was truly needed, restate the result to say so plainly (e.g. \"no change was required\") without claiming an edit you did not land.]"
+							: unsupportedMeasurementClaim
 							? "[System: attempt_completion was NOT accepted. Your result claims a specific measurement/benchmark, but no execute_command output anywhere in this session contains a supporting number. Either run the real command that produces this evidence and re-issue attempt_completion, or restate the result without the unsupported claim.]"
 							: lastExecuteCommandFailed
 								? "[System: attempt_completion was NOT accepted. The most recent command you ran ended in an error, and you have not run a command since that succeeded:\n" +
@@ -3751,8 +3924,28 @@ export class HeadlessSession {
 									"Fix the issue, make the edit succeed, and only call attempt_completion again once it actually applied.]",
 					})
 					this.logger.warn("[loop] attempt_completion deferred", { iteration, reason })
+					if (reason === consecutiveDeferralReason) {
+						consecutiveDeferralStreak++
+					} else {
+						consecutiveDeferralReason = reason
+						consecutiveDeferralStreak = 1
+					}
+					if (consecutiveDeferralStreak >= this.config.consecutiveErrorLimit) {
+						return this.boundedFailure(
+							"consecutive completion deferrals (same reason, no new evidence)",
+							iteration,
+							toolCalls,
+							consecutiveDeferralStreak,
+						)
+					}
 					continue
 				}
+				// A turn that reaches here without hitting the deferral branch
+				// above represents real progress (a normal tool call ran, or
+				// this SPECIFIC completion was actually accepted) — the streak
+				// above only means anything as CONSECUTIVE identical deferrals.
+				consecutiveDeferralReason = undefined
+				consecutiveDeferralStreak = 0
 
 				// requireArtifactBeforeCompletion guardrail (issue #143) — see
 				// HeadlessSessionConfig.requireArtifactBeforeCompletion's doc
@@ -3782,6 +3975,15 @@ export class HeadlessSession {
 						iteration,
 						reason: "no artifact-producing tool call in this session",
 					})
+					artifactBeforeCompletionDeferrals++
+					if (artifactBeforeCompletionDeferrals >= this.config.consecutiveErrorLimit) {
+						return this.boundedFailure(
+							"repeated attempt_completion with no artifact-producing tool call ever made",
+							iteration,
+							toolCalls,
+							artifactBeforeCompletionDeferrals,
+						)
+					}
 					continue
 				}
 
@@ -3953,9 +4155,139 @@ export class HeadlessSession {
 					continue
 				}
 
+				// Evidence-gated completion (fabrication fix, 2026-09-01 — see
+				// src/engine/claims.ts's module doc for the full writeup): when
+				// evidenceRequiredCompletion is on, every machine-checkable claim
+				// in the completion's result text (a file exists, a specific
+				// command passed, serial markers appear, a PR exists) must be
+				// independently verified against ground truth — the filesystem,
+				// a real re-run of the exact command, the newest serial log, and
+				// real git history — BEFORE the completion is accepted. This is
+				// the structural backstop for the FINAL_REPORT's central finding:
+				// a session claimed "all three hard gates pass" with a fabricated
+				// serial-log excerpt when the driver was never merged and the
+				// claimed Makefile target didn't exist. Fail-closed: any
+				// unverifiable claim defers the completion with a corrective
+				// message naming the specific claim, and emits an
+				// `unverified_claim` feed event so downstream consumers (eval,
+				// selfplay miner, orchestrator) can see WHY the completion was
+				// not accepted. A result with NO machine-checkable claims (pure
+				// prose) does not gate — but it also can never *pass* a gate.
+				this.lastCompletionVerification = undefined
+				if (this.config.evidenceRequiredCompletion) {
+					const claims = extractClaims(result)
+					if (claims.length > 0) {
+						const verification = await verifyClaims(claims, {
+							workspaceRoot: this.config.workspaceRoot,
+							permissions: this.executor.permissions,
+						})
+						this.lastCompletionVerification = {
+							claimsChecked: claims.length,
+							claimsPassed: verification.filter((v) => v.verified).length,
+							claimsUnverified: verification.filter((v) => !v.verified).length,
+						}
+						if (!allClaimsVerified(verification)) {
+							// Identical-call guardrail reset — the same live
+							// failure the verifyBeforeCompletion deferral above
+							// documents (joeos issue #26, rounds 17 + 20): the
+							// `continue` at the end of this block skips the
+							// identical-call streak update below (it's part of
+							// the normal per-iteration `calls` processing this
+							// branch exits before reaching), so without this
+							// reset lastCallBatchSignature/lastCallBatchNames/
+							// identicalCallStreak stay FROZEN at whatever they
+							// were when this deferral first started firing —
+							// typically two identical execute_command failures
+							// in a row, which is often exactly what triggers a
+							// fabricated-completion deferral in the first
+							// place (a model re-calling the same failing gate).
+							// Every subsequent deferred-completion turn then
+							// re-enters the request-prep cooldown-refresh loop
+							// with identicalCallGuardActive still true and
+							// lastCallBatchNames still ["execute_command"],
+							// re-arming that tool's exclusion to the full
+							// cooldown value EVERY turn before it ever ticks
+							// down — the model has no legal move
+							// (attempt_completion deferred, execute_command
+							// excluded) and just keeps re-calling
+							// attempt_completion, which is exactly the input
+							// that keeps re-triggering this same `continue`
+							// path. Confirmed live: 30+ iterations spinning
+							// between "attempt_completion deferred" and an
+							// unchanging "excludedToolCooldowns:
+							// {execute_command: 4}" until the iteration cap was
+							// hit. A deferred completion is definitionally not
+							// a repeat of whatever tool-call batch came before
+							// it, so the guard has no reason to stay active
+							// into the next turn.
+							lastCallBatchSignature = null
+							lastCallBatchNames = []
+							identicalCallStreak = 0
+							identicalCallNudgeInjected = false
+							excludedToolCooldowns.delete("execute_command")
+							const firstBad = verification.find((v) => !v.verified)
+							const unverifiedLabels = verification
+								.filter((v) => !v.verified)
+								.map((v) => claimLabel(v.claim))
+								.join(", ")
+							for (const sibling of calls) {
+								if (sibling.id === completionCall.id) {
+									continue
+								}
+								messages.push({
+									role: "tool",
+									tool_call_id: sibling.id,
+									name: sibling.name,
+									content:
+										"[System: not executed — attempt_completion was deferred because your result makes claims that could not be verified against the real workspace; re-issue this call if still needed.]",
+								})
+							}
+							messages.push({
+								role: "tool",
+								tool_call_id: completionCall.id,
+								name: "attempt_completion",
+								content:
+									"[System: attempt_completion was NOT accepted. Your result claims: " +
+									`${unverifiedLabels}. None of these could be independently confirmed: ` +
+									`${firstBad?.detail ?? "no evidence found"}. ` +
+									"Ground truth comes from the real filesystem and real command re-runs — never from a written report. " +
+									"Either run/verify the real thing (re-run the exact command, confirm the file actually exists on disk, check the real serial log) and re-issue attempt_completion, " +
+									"or restate the result to only claim what you have actually verified.]",
+							})
+							this.logger.warn("[loop] attempt_completion deferred — unverifiable claims in result", {
+								iteration,
+								claims,
+								verification: verification.map((v) => ({ verified: v.verified, detail: v.detail })),
+							})
+							this.scheduleAux(() =>
+								this.emitEvent(
+									"unverified_claim",
+									() =>
+										this.eventFeed.unverifiedClaim({
+											iteration,
+											claimsChecked: this.lastCompletionVerification?.claimsChecked ?? 0,
+											claimsPassed: this.lastCompletionVerification?.claimsPassed ?? 0,
+											claimsUnverified: this.lastCompletionVerification?.claimsUnverified ?? 0,
+											detail: firstBad?.detail ?? "",
+										}),
+									{ iteration },
+								),
+							)
+							continue
+						}
+					}
+				}
+
 				this.logger.info("[loop] attempt_completion received — success", { iteration })
 				const reportPath = await this.persistFinalReport(iteration, result)
-				return { status: "success", result, iterations: iteration, toolCalls: toolCalls + 1, reportPath }
+				return {
+					status: "success",
+					result,
+					iterations: iteration,
+					toolCalls: toolCalls + 1,
+					reportPath,
+					verification: this.lastCompletionVerification,
+				}
 			}
 
 			// 6b. Text-only reply (no tool_calls) → pragmatic success fallback,
@@ -4082,9 +4414,93 @@ export class HeadlessSession {
 					artifactRejectionStreak = 0
 					artifactRejectionNudgeInjected = false
 					if (text && !this.config.requireExplicitCompletion) {
+						// Evidence-gated completion (fabrication fix, 2026-09-01)
+						// — the text-only success fallback is a REAL bypass for
+						// cloud sessions: requireExplicitCompletion defaults OFF
+						// for the cloud backend, so with --require-evidence a
+						// cloud model could dump prose ("all three hard gates
+						// pass…") and be recorded as success with ZERO
+						// evidence, exactly the fabrication shape the gate
+						// exists to stop. When evidenceRequiredCompletion is
+						// ON, a text-only reply is treated as a completion
+						// CANDIDATE and runs the SAME extract/verify gate as an
+						// attempt_completion: pure prose (no machine-checkable
+						// claims) or fully-verified claims are accepted; any
+						// unverifiable claim defers with the corrective nudge
+						// and an unverified_claim event, never a success.
+						this.lastCompletionVerification = undefined
+						if (this.config.evidenceRequiredCompletion) {
+							const claims = extractClaims(text)
+							if (claims.length > 0) {
+								const verification = await verifyClaims(claims, {
+									workspaceRoot: this.config.workspaceRoot,
+									permissions: this.executor.permissions,
+								})
+								this.lastCompletionVerification = {
+									claimsChecked: claims.length,
+									claimsPassed: verification.filter((v) => v.verified).length,
+									claimsUnverified: verification.filter((v) => !v.verified).length,
+								}
+								if (!allClaimsVerified(verification)) {
+									// Same identical-call guardrail reset as the
+									// attempt_completion deferral above — a text-only
+									// reply is definitionally not a repeat of the
+									// previous tool-call batch.
+									lastCallBatchSignature = null
+									lastCallBatchNames = []
+									identicalCallStreak = 0
+									identicalCallNudgeInjected = false
+									excludedToolCooldowns.delete("execute_command")
+									const firstBad = verification.find((v) => !v.verified)
+									const unverifiedLabels = verification
+										.filter((v) => !v.verified)
+										.map((v) => claimLabel(v.claim))
+										.join(", ")
+									messages.push({
+										role: "user",
+										content:
+											`[System: your text-only reply was NOT accepted as a completion. It claims: ${unverifiedLabels}. ` +
+											`None of these could be independently confirmed: ${firstBad?.detail ?? "no evidence found"}. ` +
+											"Ground truth comes from the real filesystem and real command re-runs — never from a written report. " +
+											"Either run/verify the real thing (re-run the exact command, confirm the file actually exists on disk, check the real serial log) and then call attempt_completion, " +
+											"or restate your answer to only claim what you have actually verified.]",
+									})
+									this.logger.warn("[loop] text-only reply NOT accepted — unverifiable claims", {
+										iteration,
+										claims,
+										verification: verification.map((v) => ({
+											verified: v.verified,
+											detail: v.detail,
+										})),
+									})
+									this.scheduleAux(() =>
+										this.emitEvent(
+											"unverified_claim",
+											() =>
+												this.eventFeed.unverifiedClaim({
+													iteration,
+													claimsChecked: this.lastCompletionVerification?.claimsChecked ?? 0,
+													claimsPassed: this.lastCompletionVerification?.claimsPassed ?? 0,
+													claimsUnverified: this.lastCompletionVerification?.claimsUnverified ?? 0,
+													detail: firstBad?.detail ?? "",
+												}),
+											{ iteration },
+										),
+									)
+									continue
+								}
+							}
+						}
 						this.logger.info("[loop] text-only reply (no tool calls) — success", { iteration })
 						const reportPath = await this.persistFinalReport(iteration, text)
-						return { status: "success", result: text, iterations: iteration, toolCalls, reportPath }
+						return {
+							status: "success",
+							result: text,
+							iterations: iteration,
+							toolCalls,
+							reportPath,
+							...(this.lastCompletionVerification ? { verification: this.lastCompletionVerification } : {}),
+						}
 					}
 					// Empty reply, or a text reply that requireExplicitCompletion
 					// refuses to treat as final: nudge and count as a mistake.
@@ -4296,8 +4712,35 @@ export class HeadlessSession {
 								? resultContent.slice(0, 500)
 								: JSON.stringify(resultContent).slice(0, 500)
 						lastWriteToolSummary = `${call.name} ${target}\n${output}`
+						lastWriteToolFailedTarget = toolCallPathArg(this.config.workspaceRoot, call)
 					} else {
 						lastWriteToolSummary = undefined
+						lastWriteToolFailedTarget = undefined
+						// A genuinely successful write resolves the situation for
+						// real — the re-read-only clearing no longer needs to gate
+						// anything (see writeFailedClearedByReReadOnly's doc above).
+						writeFailedClearedByReReadOnly = false
+						reReadClearedWriteSummary = undefined
+					}
+				}
+				// See lastWriteToolFailedTarget's doc comment above: a
+				// successful read_file of the EXACT file a write tool just
+				// failed to edit is real re-verification evidence, not just
+				// time passing — clear the stale-failure flag so a
+				// subsequent honest completion (including "no edit was
+				// actually needed") isn't blocked by a failure the model
+				// has since genuinely re-checked.
+				if (call.name === "read_file" && !isError && lastWriteToolFailed) {
+					const readTarget = toolCallPathArg(this.config.workspaceRoot, call)
+					if (readTarget !== undefined && readTarget === lastWriteToolFailedTarget) {
+						lastWriteToolFailed = false
+						reReadClearedWriteSummary = lastWriteToolSummary
+						lastWriteToolSummary = undefined
+						lastWriteToolFailedTarget = undefined
+						// Remember this was cleared by a re-read ONLY, not by a
+						// real successful write — completion still has to prove
+						// it isn't claiming an edit it never landed.
+						writeFailedClearedByReReadOnly = true
 					}
 				}
 				const targetPath = editToolTargetPath(this.config.workspaceRoot, call)
@@ -4802,6 +5245,7 @@ export class HeadlessSession {
 			patchLocalToolSchemas: this.config.patchLocalToolSchemas,
 			verifyBeforeCompletion: this.config.verifyBeforeCompletion,
 			guardLargeOverwrites: this.config.guardLargeOverwrites,
+			disableReadFileCache: this.config.disableReadFileCache,
 			llmClient: this.llmClient,
 			logger: this.logger,
 			memory: this.config.memory,
@@ -5311,9 +5755,20 @@ export function summarizeToolArg(name: string, args: Record<string, unknown>): s
 		case "list_files":
 		case "write_to_file":
 		case "apply_diff":
+			return str(args.path)
 		case "search_replace":
 		case "edit_file":
-			return str(args.path)
+			// 2026-09-02: real, confirmed bug -- these two tools' native
+			// schemas (src/vendor/zoo-code/.../native-tools/edit_file.ts,
+			// search_replace.ts) declare `file_path`, not `path` (unlike
+			// write_to_file/apply_diff/list_files, which really do use
+			// `path`) -- so this always returned undefined -> "" here,
+			// making the tool_call event's path summary silently blank for
+			// every edit_file/search_replace call. That's exactly what made
+			// live log-watching during a real session unable to show which
+			// file was being edited. Fall back to `path` too in case an
+			// older/alias caller still sends that key.
+			return str(args.file_path) ?? str(args.path)
 		case "execute_command":
 			return str(args.command)?.slice(0, 200)
 		case "update_todo_list":

package/src/engine/prompt.ts

@@ -660,7 +660,11 @@ export function buildHeadlessConventions(mode: string, customModes: ModeConfig[]
 - Commit before finishing: real, working changes must be committed via \`git add\` + \`git commit\` BEFORE calling attempt_completion. Use one commit per logical change with a descriptive message, matching this repo's normal style (run \`git log --oneline\` for examples). If you genuinely have no changes to commit (e.g. a read-only investigation), finish without committing.
 - Test selection during iterative work: after editing a file, run the SPECIFIC test file(s) for what you changed (the \`run_tests\` tool, or \`npx tsx <test-file>\` directly) instead of the full suite on every edit. The full \`npm test\` is still required once, right before attempt_completion, for real confidence.
 - Batch same-file diffs: when several changes target the SAME file, include them as separate SEARCH/REPLACE blocks in ONE apply_diff call — and after any successful edit, re-read the file before composing further diffs, because its content has changed.
-- Waiting on an external check (CI run, registry, live service) is legitimate verification work, but every wait call still counts against your iteration budget: prefer ONE long-running command with an explicit \`timeout\` — e.g. \`gh run watch <id> --interval 30 --exit-status\` — over repeated \`sleep N && gh run list\` polls. (Issue #119: polling burns iterations with no token spend.)`
+- Waiting on an external check (CI run, registry, live service) is legitimate verification work, but every wait call still counts against your iteration budget: prefer ONE long-running command with an explicit \`timeout\` — e.g. \`gh run watch <id> --interval 30 --exit-status\` — over repeated \`sleep N && gh run list\` polls. (Issue #119: polling burns iterations with no token spend.)
+- Check the real workspace before assuming a path exists: when a task resembles something you've worked on before, use \`list_files\`/\`read_file\` on THIS workspace first rather than guessing a path from a similar prior task — a plausible-looking guess against the wrong repo/scratch layout still fails, and repeating the same wrong guess wastes the iteration budget without new information.
+- If the same command fails twice in a row, change what you do next — read the real error, try something different, or (if there's genuinely no path forward) report the honest state via \`attempt_completion\` rather than retrying the identical call or repeating the same diagnosis in prose without acting on it. A real, honest "this doesn't work and here's why" is always a valid, complete answer; a stalled loop is not.
+- When \`attempt_completion\` is deferred (rejected because a check hasn't actually passed yet, an edit hasn't succeeded, or a claim isn't backed by real evidence), your VERY NEXT action must be the real fix the deferral message describes — a new command, a corrected edit, or gathering the missing evidence — never another \`attempt_completion\` call on its own. Retrying completion without first taking that corrective action just repeats the same rejection and burns the iteration budget with no new information; it will keep being deferred for the identical reason until you actually address it.
+- Starting a long-running process (a dev server, a background listener) and then checking it — do this as TWO separate \`execute_command\` calls, not one. First call: run the command DIRECTLY, with no trailing \`&\` and no \`bash -c '... &'\` wrapper — e.g. \`python3 server.py\` with \`timeout: 2\`. The tool's own contract already keeps it running in the background past the timeout (you get the output captured so far, not an error); it does NOT need you to background it yourself. Second, separate call: the actual check (\`curl ...\`, \`nc -z ...\`). Manually backgrounding with \`&\` inside a \`bash -c\` (or any subshell) is a real, observed failure mode — the process gets backgrounded INSIDE that subshell, which then exits once the \`&\` returns, and the process can be reaped along with it before your next command in the same chain ever reaches it. If a check right after starting something fails, don't keep editing the file you just started — first suspect the START command's shape.`
 }
 
 // ─── Tool selection ──────────────────────────────────────────────────────────