headlesscode 1.0.3 → 1.2.1

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 ──────────────────────────────────────────────────────────

package/src/engine/types.ts

@@ -189,6 +189,15 @@ export interface ToolContext {
 	 * executors (tests, reviewer/QA).
 	 */
 	guardLargeOverwrites?: boolean
+	/**
+	 * See HeadlessSessionConfig.disableReadFileCache (loop.ts) for the full
+	 * writeup. When true, read_file/list_files always serve real content —
+	 * the session-scoped "[cache] unchanged, re-read the earlier result"
+	 * short-circuit (src/tools/executor.ts) never fires. Absent/false for
+	 * cloud sessions and bare executors (tests, reviewer/QA), where that
+	 * short-circuit's real token-cost savings still apply.
+	 */
+	disableReadFileCache?: boolean
 	/**
 	 * Decision escalation (ask_followup_question, see src/tools/executor.ts):
 	 * how long to block waiting for `.harness.decision-answer` before falling
@@ -269,6 +278,24 @@ export interface SessionBudgetUsage {
 	model: string
 }
 
+/**
+ * Evidence-gated completion (fabrication fix, 2026-09-01): the outcome of
+ * the claim-verification pass that ran against the final attempt_completion
+ * result when evidenceRequiredCompletion was on (see src/engine/claims.ts).
+ * Present on a successful SessionResult ONLY when the gate actually ran and
+ * found at least one machine-checkable claim — its presence is the caller's
+ * signal that "success" means "claims independently verified against ground
+ * truth", not "the model said so". Absent when the gate didn't run.
+ */
+export interface SessionCompletionVerification {
+	/** Number of machine-checkable claims extracted from the result text. */
+	claimsChecked: number
+	/** Number of claims independently confirmed against the real world. */
+	claimsPassed: number
+	/** Number of claims that could not be confirmed (0 on an accepted completion). */
+	claimsUnverified: number
+}
+
 export interface SessionResult {
 	status: SessionStatus
 	result?: string
@@ -277,6 +304,15 @@ export interface SessionResult {
 	reason?: string
 	iterations: number
 	toolCalls: number
+	/**
+	 * Evidence-gated completion (fabrication fix): present when the
+	 * completion's claims were independently verified against ground truth
+	 * (file existence, real command re-runs, serial logs, git history) — see
+	 * SessionCompletionVerification. Absent when the gate didn't run (flag
+	 * off, no claims in the result) — callers must NOT treat that as
+	 * "verified", only as "not checked".
+	 */
+	verification?: SessionCompletionVerification
 	/**
 	 * Issue #34: absolute path to the session's complete final report
 	 * (`<workspaceRoot>/.headlesscode/reports/<sessionId>.md`), present when

package/src/rsi/archive.ts

@@ -0,0 +1,129 @@
+import * as fs from "node:fs/promises"
+import * as path from "node:path"
+import type { CandidateRecord, RsiArchive, RsiRunRecord } from "./types.js"
+
+export function archivePath(archiveDir: string): string {
+	return path.join(archiveDir, "archive.json")
+}
+
+function emptyArchive(): RsiArchive {
+	return {
+		schemaVersion: 2,
+		updatedAt: new Date(0).toISOString(),
+		runs: [],
+		activeRuns: [],
+		candidates: [],
+		modelCandidates: [],
+		combinations: [],
+		jobs: [],
+		trajectoryRefs: [],
+		curriculumTasks: [],
+	}
+}
+
+function normalizeRun(run: RsiRunRecord): RsiRunRecord {
+	return {
+		...run,
+		candidates: Array.isArray(run.candidates) ? run.candidates : [],
+		reports: Array.isArray(run.reports) ? run.reports : [],
+		selectedCandidates: run.selectedCandidates ?? (run.selected ? [run.selected] : []),
+	}
+}
+
+function migrate(raw: Partial<RsiArchive> & { schemaVersion?: number }): RsiArchive {
+	const archive = emptyArchive()
+	archive.updatedAt = raw.updatedAt ?? archive.updatedAt
+	archive.runs = (Array.isArray(raw.runs) ? raw.runs : []).map((run) => normalizeRun(run))
+	archive.activeRuns = (Array.isArray(raw.activeRuns) ? raw.activeRuns : []).map((run) => normalizeRun(run))
+	archive.candidates = Array.isArray(raw.candidates) ? raw.candidates : archive.runs.flatMap((run) => run.candidates)
+	archive.modelCandidates = Array.isArray(raw.modelCandidates) ? raw.modelCandidates : []
+	archive.combinations = Array.isArray(raw.combinations) ? raw.combinations : []
+	archive.jobs = Array.isArray(raw.jobs) ? raw.jobs : []
+	archive.trajectoryRefs = Array.isArray(raw.trajectoryRefs) ? raw.trajectoryRefs : []
+	archive.curriculumTasks = Array.isArray(raw.curriculumTasks) ? raw.curriculumTasks : []
+	return archive
+}
+
+export async function readArchive(archiveDir: string): Promise<RsiArchive> {
+	try {
+		const raw = await fs.readFile(archivePath(archiveDir), "utf8")
+		const parsed = JSON.parse(raw) as Record<string, unknown> & { schemaVersion?: number }
+		if ((parsed.schemaVersion === 1 || parsed.schemaVersion === 2) && Array.isArray(parsed.runs)) {
+			return migrate(parsed as Partial<RsiArchive> & { schemaVersion?: number })
+		}
+	} catch {
+		// A missing or malformed archive starts a new durable history. The next
+		// write makes the state explicit and inspectable.
+	}
+	return emptyArchive()
+}
+
+export async function writeArchive(archiveDir: string, archive: RsiArchive): Promise<void> {
+	await fs.mkdir(archiveDir, { recursive: true })
+	const destination = archivePath(archiveDir)
+	const temporary = `${destination}.tmp-${process.pid}`
+	await fs.writeFile(temporary, `${JSON.stringify(archive, null, 2)}\n`, "utf8")
+	await fs.rename(temporary, destination)
+}
+
+export async function appendRun(archiveDir: string, run: RsiRunRecord): Promise<RsiArchive> {
+	const archive = await readArchive(archiveDir)
+	archive.activeRuns = archive.activeRuns.filter((entry) => entry.runId !== run.runId)
+	archive.runs = [...archive.runs.filter((entry) => entry.runId !== run.runId), normalizeRun(run)]
+	for (const candidate of run.candidates) {
+		const index = archive.candidates.findIndex((entry) => entry.id === candidate.id)
+		if (index >= 0) archive.candidates[index] = candidate
+		else archive.candidates.push(candidate)
+	}
+	for (const model of run.modelCandidates ?? []) {
+		if (!archive.modelCandidates.some((entry) => entry.id === model.id)) archive.modelCandidates.push(model)
+	}
+	for (const combination of run.combinations ?? []) {
+		const index = archive.combinations.findIndex((entry) => entry.id === combination.id)
+		if (index >= 0) archive.combinations[index] = combination
+		else archive.combinations.push(combination)
+	}
+	for (const job of run.jobs ?? []) {
+		const index = archive.jobs.findIndex((entry) => entry.id === job.id)
+		if (index >= 0) archive.jobs[index] = job
+		else archive.jobs.push(job)
+	}
+	for (const task of run.curriculumTasks ?? []) {
+		if (!archive.curriculumTasks.some((entry) => entry.id === task.id)) archive.curriculumTasks.push(task)
+	}
+	archive.trajectoryRefs = [...new Set([...archive.trajectoryRefs, ...(run.trajectoryRefs ?? [])])]
+	archive.updatedAt = new Date().toISOString()
+	await writeArchive(archiveDir, archive)
+	return archive
+}
+
+export async function checkpointRun(archiveDir: string, run: RsiRunRecord): Promise<RsiArchive> {
+	const archive = await readArchive(archiveDir)
+	const normalized = normalizeRun(run)
+	archive.activeRuns = [...archive.activeRuns.filter((entry) => entry.runId !== run.runId), normalized]
+	for (const candidate of run.candidates) {
+		const index = archive.candidates.findIndex((entry) => entry.id === candidate.id)
+		if (index >= 0) archive.candidates[index] = candidate
+		else archive.candidates.push(candidate)
+	}
+	for (const job of run.jobs ?? []) {
+		const index = archive.jobs.findIndex((entry) => entry.id === job.id)
+		if (index >= 0) archive.jobs[index] = job
+		else archive.jobs.push(job)
+	}
+	archive.updatedAt = new Date().toISOString()
+	await writeArchive(archiveDir, archive)
+	return archive
+}
+
+export async function findActiveRun(archiveDir: string, runId: string): Promise<RsiRunRecord | undefined> {
+	return (await readArchive(archiveDir)).activeRuns.find((run) => run.runId === runId)
+}
+
+export function archiveCandidate(archive: RsiArchive, candidate: CandidateRecord): RsiArchive {
+	const index = archive.candidates.findIndex((entry) => entry.id === candidate.id)
+	if (index >= 0) archive.candidates[index] = candidate
+	else archive.candidates.push(candidate)
+	archive.updatedAt = new Date().toISOString()
+	return archive
+}

package/src/rsi/config.ts

@@ -0,0 +1,312 @@
+import * as path from "node:path"
+import { DEFAULT_PROTECTED_FILES } from "../permissions/protected-files.js"
+import type { ComputePolicy, MutationHypothesis, MutationKind, ParentSelectionPolicy, RsiConfig } from "./types.js"
+
+export const DEFAULT_RSI_MODEL = "wxrq-qwen3.5-9b:latest"
+export const DEFAULT_VISIBLE_EVALS = ["npm test -- --filter rsi"]
+export const DEFAULT_PROTECTED_PATHS = [
+	...DEFAULT_PROTECTED_FILES,
+	"src/rsi/",
+	"scripts/",
+	"**/*.test.ts",
+	"package.json",
+	"package-lock.json",
+	".gitignore",
+	"scripts/eval-suite/",
+	".headlesscode/",
+	".worktrees/",
+]
+
+export interface ParsedRsiArgs {
+	config?: RsiConfig
+	help?: boolean
+	error?: string
+}
+
+function positiveInteger(value: string, name: string): number {
+	const parsed = Number(value)
+	if (!Number.isInteger(parsed) || parsed < 1) {
+		throw new Error(`${name} must be a positive integer`)
+	}
+	return parsed
+}
+
+function splitCommands(value: string): string[] {
+	return value
+		.split(";;")
+		.map((command) => command.trim())
+		.filter(Boolean)
+}
+
+export function rsiHelp(): string {
+	return `headlesscode improve — bounded recursive self-improvement
+
+Usage:
+  headlesscode improve --repo <path> [options]
+
+Options:
+  --model <id>                 worker model (default: ${DEFAULT_RSI_MODEL})
+  --population <n>             candidates per generation (default: 2)
+  --generations <n>            bounded generations (default: 1)
+  --parent-policy <name>      champion-specialist-novelty | pareto-front | all-eligible
+  --mutation-kind <name>      corrective | architectural | search-policy | curriculum | model-adaptation
+  --hypothesis <text>         recorded reason for the mutation
+  --expected-effect <text>    measurable benefit to test
+  --potential-downside <text> recorded cost or regression risk
+  --compute-policy <name>     single | independent | planner-executors | critic-retry
+  --eval <command>             visible command; repeat or separate with ;; 
+  --hidden-eval <command>      supervisor-only hidden command
+  --mutation-task <text>       improvement objective
+  --archive-dir <path>         durable archive directory
+  --worktree-dir <path>        candidate worktree directory
+  --trajectory-dir <path>      structured trajectory output directory
+  --curriculum-dir <path>      generated curriculum proposal directory
+  --resume <run-id>            resume a checkpointed active run
+  --model-candidate-id <id>    model identity used for combination tracking
+  --base-ref <ref>             git ref to branch from (default: HEAD)
+  --dry-run                    print the planned loop without changing files
+  --keep-worktrees              retain candidate worktrees after evaluation
+  --help                       show this help
+
+The evaluator and scoring code are protected from candidates. The first run
+uses the local Qwen worker unless --model overrides it.
+`
+}
+
+export function parseRsiArgs(argv: string[], cwd = process.cwd()): ParsedRsiArgs {
+	let repoRoot = cwd
+	let model = DEFAULT_RSI_MODEL
+	let population = 2
+	let generations = 1
+	let maxConcurrent = 1
+	let mutationTask = "Improve the headlesscode agent loop while preserving all existing behavior and tests."
+	let parentSelectionPolicy: ParentSelectionPolicy = "champion-specialist-novelty"
+	let mutationKind: MutationKind = "corrective"
+	let hypothesis: MutationHypothesis = {
+		statement: mutationTask,
+		expectedEffect: "higher verified task success without regressions",
+		potentialDownside: "additional complexity or inference cost",
+	}
+	let computePolicy: ComputePolicy = "single"
+	let evalCommands = [...DEFAULT_VISIBLE_EVALS]
+	let hiddenEvalCommands: string[] = []
+	let archiveDir: string | undefined
+	let worktreeDir: string | undefined
+	let baseRef = "HEAD"
+	let seed = "headlesscode-rsi"
+	let dryRun = false
+	let keepWorktrees = false
+	let maxIterations = 40
+	let commandTimeoutMs = 15 * 60_000
+	let trajectoryDir: string | undefined
+	let curriculumDir: string | undefined
+	let resumeRunId: string | undefined
+	let modelCandidateId: string | undefined
+
+	const take = (index: number, name: string): [string, number] => {
+		const value = argv[index + 1]
+		if (!value || value.startsWith("--")) {
+			throw new Error(`${name} requires a value`)
+		}
+		return [value, index + 1]
+	}
+
+	try {
+		for (let index = 0; index < argv.length; index++) {
+			const arg = argv[index]
+			switch (arg) {
+				case "--help":
+				case "-h":
+					return { help: true }
+				case "--repo": {
+					const [value, next] = take(index, arg)
+					repoRoot = path.resolve(value)
+					index = next
+					break
+				}
+				case "--model": {
+					const [value, next] = take(index, arg)
+					model = value
+					index = next
+					break
+				}
+				case "--population": {
+					const [value, next] = take(index, arg)
+					population = positiveInteger(value, arg)
+					index = next
+					break
+				}
+				case "--generations": {
+					const [value, next] = take(index, arg)
+					generations = positiveInteger(value, arg)
+					index = next
+					break
+				}
+				case "--parent-policy": {
+					const [value, next] = take(index, arg)
+					if (!["champion-specialist-novelty", "pareto-front", "all-eligible"].includes(value)) throw new Error(`${arg} has an invalid policy`)
+					parentSelectionPolicy = value as ParentSelectionPolicy
+					index = next
+					break
+				}
+				case "--mutation-kind": {
+					const [value, next] = take(index, arg)
+					if (!["corrective", "architectural", "search-policy", "curriculum", "model-adaptation"].includes(value)) throw new Error(`${arg} has an invalid mutation kind`)
+					mutationKind = value as MutationKind
+					hypothesis.statement = mutationTask
+					index = next
+					break
+				}
+				case "--hypothesis": {
+					const [value, next] = take(index, arg)
+					hypothesis.statement = value
+					index = next
+					break
+				}
+				case "--expected-effect": {
+					const [value, next] = take(index, arg)
+					hypothesis.expectedEffect = value
+					index = next
+					break
+				}
+				case "--potential-downside": {
+					const [value, next] = take(index, arg)
+					hypothesis.potentialDownside = value
+					index = next
+					break
+				}
+				case "--compute-policy": {
+					const [value, next] = take(index, arg)
+					if (!["single", "independent", "planner-executors", "critic-retry"].includes(value)) throw new Error(`${arg} has an invalid policy`)
+					computePolicy = value as ComputePolicy
+					index = next
+					break
+				}
+				case "--max-concurrent": {
+					const [value, next] = take(index, arg)
+					maxConcurrent = positiveInteger(value, arg)
+					index = next
+					break
+				}
+				case "--eval": {
+					const [value, next] = take(index, arg)
+					evalCommands = splitCommands(value)
+					index = next
+					break
+				}
+				case "--hidden-eval": {
+					const [value, next] = take(index, arg)
+					hiddenEvalCommands.push(...splitCommands(value))
+					index = next
+					break
+				}
+				case "--mutation-task": {
+					const [value, next] = take(index, arg)
+					mutationTask = value
+					index = next
+					break
+				}
+				case "--archive-dir": {
+					const [value, next] = take(index, arg)
+					archiveDir = path.resolve(repoRoot, value)
+					index = next
+					break
+				}
+				case "--worktree-dir": {
+					const [value, next] = take(index, arg)
+					worktreeDir = path.resolve(repoRoot, value)
+					index = next
+					break
+				}
+				case "--trajectory-dir": {
+					const [value, next] = take(index, arg)
+					trajectoryDir = path.resolve(repoRoot, value)
+					index = next
+					break
+				}
+				case "--curriculum-dir": {
+					const [value, next] = take(index, arg)
+					curriculumDir = path.resolve(repoRoot, value)
+					index = next
+					break
+				}
+				case "--resume": {
+					const [value, next] = take(index, arg)
+					resumeRunId = value
+					index = next
+					break
+				}
+				case "--model-candidate-id": {
+					const [value, next] = take(index, arg)
+					modelCandidateId = value
+					index = next
+					break
+				}
+				case "--base-ref": {
+					const [value, next] = take(index, arg)
+					baseRef = value
+					index = next
+					break
+				}
+				case "--seed": {
+					const [value, next] = take(index, arg)
+					seed = value
+					index = next
+					break
+				}
+				case "--max-iterations": {
+					const [value, next] = take(index, arg)
+					maxIterations = positiveInteger(value, arg)
+					index = next
+					break
+				}
+				case "--timeout-ms": {
+					const [value, next] = take(index, arg)
+					commandTimeoutMs = positiveInteger(value, arg)
+					index = next
+					break
+				}
+				case "--dry-run":
+					dryRun = true
+					break
+				case "--keep-worktrees":
+					keepWorktrees = true
+					break
+				default:
+					throw new Error(`unknown improve argument: ${arg}`)
+			}
+		}
+		const resolvedRepo = path.resolve(repoRoot)
+		return {
+			config: {
+				repoRoot: resolvedRepo,
+				model,
+				population,
+				generations,
+				maxConcurrent,
+				mutationTask,
+				parentSelectionPolicy,
+				mutationKind,
+				hypothesis: { ...hypothesis },
+				computePolicy,
+				evalCommands,
+				hiddenEvalCommands,
+				archiveDir: archiveDir ?? path.join(resolvedRepo, ".headlesscode", "rsi"),
+				worktreeDir: worktreeDir ?? path.join(resolvedRepo, ".worktrees", "rsi"),
+				trajectoryDir: trajectoryDir ?? path.join(archiveDir ?? path.join(resolvedRepo, ".headlesscode", "rsi"), "trajectories"),
+				curriculumDir: curriculumDir ?? path.join(archiveDir ?? path.join(resolvedRepo, ".headlesscode", "rsi"), "curriculum"),
+				baseRef,
+				seed,
+				dryRun,
+				keepWorktrees,
+				maxIterations,
+				protectedPaths: [...DEFAULT_PROTECTED_PATHS],
+				commandTimeoutMs,
+				resumeRunId,
+				modelCandidateId,
+			},
+		}
+	} catch (error) {
+		return { error: error instanceof Error ? error.message : String(error) }
+	}
+}