@sebastianandreasson/pi-autonomous-agents 0.1.0 → 0.3.0

package/README.md

@@ -59,6 +59,7 @@ packages/pi-harness/
 pi-harness once
 pi-harness run
 pi-harness report
+pi-harness clear-history
 pi-harness visual-once
 pi-harness adapter
 pi-harness visual-review-worker
@@ -82,12 +83,25 @@ Find SETUP.md in @sebastianandreasson/pi-autonomous-agents and set everything up
 
 The package ships a top-level [SETUP.md](./SETUP.md) specifically for that workflow.
 
+If you want to wipe all harness-generated state and start over cleanly in a repo, run:
+
+```bash
+PI_CONFIG_FILE=pi.config.json pi-harness clear-history
+```
+
+The command removes configured harness history/runtime files and verifies that no configured history paths remain afterward.
+
+For prompt debugging, the harness also writes the exact assembled prompt for the current role to `.pi-last-prompt.txt` by default.
+For flow debugging, it also writes a machine-readable `.pi-last-iteration.json` summary with the selected task, tester verdict, commit-plan state, and terminal reason.
+
 ## Generic Contracts
 
 - `taskFile`: usually `TODOS.md`
 - `developerInstructionsFile`: per-project developer instructions
 - `testerInstructionsFile`: per-project tester instructions
 - `roleModels`: optional per-role model overrides
+- `commitMode`: `agent` by default, `plan` only for legacy harness-managed commit parsing
+- `promptMode`: `compact` by default
 - `testCommand`: fast verification command
 - `visualCaptureCommand`: project-defined screenshot capture command
 - `visualFeedbackFile`: latest visual-review handoff
@@ -95,8 +109,14 @@ The package ships a top-level [SETUP.md](./SETUP.md) specifically for that workf
 
 For unattended loops, keep `testCommand` fast and bounded, such as a smoke suite. Long real-time Playwright happy-path specs belong in an explicit nightly or post-run lane, not the default developer/tester inner loop.
 
+Keep TODO items extremely small and implementation-shaped when using weaker local models. Broad tasks tend to produce much longer turns, more retries, and more tester drift than narrow one-step tasks.
+
 The adapter heartbeat is PI-RPC-event based. Streaming shell output does not count as progress on its own, so long-running tools should rely on the tool-aware watchdog thresholds rather than terminal streaming.
 
-`piModel` remains the default text model, but you can override specific roles with `roleModels` such as `developer`, `developerRetry`, `developerFix`, `tester`, `testerCommit`, and `visualReview`.
+`piModel` remains the default text model, but you can override specific roles with `roleModels` such as `developer`, `developerRetry`, `developerFix`, `tester`, and `visualReview`. `testerCommit` is only relevant if you opt back into `commitMode: "plan"`.
+
+By default, successful tester passes should stage and create the commit directly in the same PI turn. The old commit-plan parsing flow is still available as `commitMode: "plan"`, but it is now a compatibility mode rather than the default.
+
+Prompt/context handoff is compact by default. The harness now caps prior feedback excerpts, changed-file lists, verification excerpts, and prompt note handoff. If needed, tune `maxPromptChangedFiles`, `maxVisualFeedbackLines`, `maxTesterFeedbackLines`, `maxPromptNotesLines`, and `maxVerificationExcerptLines`.
 
 The harness expects screenshot capture to produce a `manifest.json` plus image files under the configured visual capture directory.

package/SETUP.md

@@ -46,10 +46,16 @@ If the repo uses another package manager already, use the repo-native equivalent
   - `taskFile`: usually `TODOS.md`
   - `developerInstructionsFile`: `pi/DEVELOPER.md`
   - `testerInstructionsFile`: `pi/TESTER.md`
+  - `commitMode`: normally `agent`
   - `testCommand`: a fast bounded verification command for this repo
   - `visualCaptureCommand`: only if this repo has a real screenshot capture flow
   - `models` / `piModel` / `visualReviewModel` / `roleModels`: configure the models actually available in this environment
 
+Important:
+
+- Do not assume a local provider’s served model id matches a GGUF filename or a guessed name.
+- If the repo uses custom OpenAI-compatible providers, verify the exact served ids from each provider’s `/v1/models` response before finalizing `piModel`, `visualReviewModel`, or `roleModels`.
+
 3. Create role instruction files.
 
 - Copy `node_modules/@sebastianandreasson/pi-autonomous-agents/templates/DEVELOPER.md` to `pi/DEVELOPER.md`.
@@ -118,6 +124,7 @@ Recommended pattern:
 - local model for `developerFix`
 - local or slightly stronger model for `tester`
 - stronger frontier model for `visualReview` only if available
+- keep `commitMode` as `agent` unless the repo explicitly needs legacy harness-managed commit-plan parsing
 
 Example shape:
 
@@ -136,6 +143,21 @@ Example shape:
 }
 ```
 
+If the repo uses a custom OpenAI-compatible local provider, validate it directly:
+
+1. Verify the endpoint is reachable.
+2. Query `<baseUrl>/models`.
+3. Use the exact returned model id.
+4. Do not assume the served id equals a GGUF filename on disk.
+
+If the repo overrides `PI_CODING_AGENT_DIR`:
+
+- do not point it at an empty directory
+- ensure that PI home is already bootstrapped
+- ensure `models.json` exists there before running the harness
+
+If `PI_CODING_AGENT_DIR` is set to a repo-local PI home and `models.json` is missing, setup is incomplete.
+
 9. Validate the setup.
 
 Run at least:
@@ -152,6 +174,16 @@ PI_CONFIG_FILE=pi.config.json PI_TRANSPORT=mock PI_TEST_CMD= pi-harness once
 
 If setup validation fails, fix the config rather than leaving a half-configured repo.
 
+The harness should fail fast if:
+
+- PI cannot list models
+- a configured PI role model does not exist
+- a configured provider endpoint is unreachable
+- a configured provider does not serve the configured model id
+
+For prompt debugging, inspect `.pi-last-prompt.txt` after a run. It contains the exact assembled prompt that was sent for the active role.
+For flow debugging, inspect `.pi-last-iteration.json` after a run. It summarizes the selected task, repo-change outcome, tester verdict, commit-plan state, and terminal reason.
+
 ## Agent Rules
 
 - Reuse existing repo conventions where possible.
@@ -159,6 +191,7 @@ If setup validation fails, fix the config rather than leaving a half-configured
 - Do not invent fake test commands or model endpoints.
 - Do not enable visual review unless the repo actually has a usable capture command and model config.
 - Keep changes minimal and local to harness setup.
+- Prefer very small, implementation-shaped TODO items for local models. Broad tasks tend to create long turns, retries, and weak tester behavior.
 
 ## What To Report Back
 
@@ -169,3 +202,13 @@ When setup is complete, report:
 - whether visual review was enabled
 - which roles were mapped to which models
 - whether validation was run successfully
+
+## Resetting Harness State
+
+If the user wants to start over from a clean slate later, use:
+
+```bash
+PI_CONFIG_FILE=pi.config.json pi-harness clear-history
+```
+
+This should remove harness-generated runtime/history state only, not project source files.

package/docs/PI_SUPERVISOR.md

@@ -18,7 +18,7 @@ Each real iteration follows this sequence:
 2. A fast local verification command runs immediately after the developer round.
 3. If verification passes, `tester` reviews the change independently from a skeptical user-facing perspective.
 4. If tester or verification finds a real issue, the supervisor gives the findings back to `developer` for one focused repair pass.
-5. If tester reaches `PASS`, tester provides a commit plan and the harness performs the actual git finalization.
+5. If tester reaches `PASS`, tester creates the commit directly in the same turn by default.
 6. Optionally, every `N` successful iterations, the harness runs a read-only visual review over screenshots and persists the feedback for later runs.
 7. If that visual review returns `FAIL`, `BLOCKED`, or times out, the iteration is not counted as a success and the feedback is carried into later prompts.
 
@@ -69,6 +69,7 @@ Projects typically provide their own `pi.config.json` with fields such as:
 - `models`
 - `piModel`
 - `visualReviewModel`
+- `commitMode`
 
 Model entries may carry their own OpenAI-compatible endpoint settings, so the PI text loop and the multimodal visual reviewer can point at different backends without changing code.
 
@@ -83,7 +84,6 @@ Model entries may carry their own OpenAI-compatible endpoint settings, so the PI
     "developerRetry": "local/dev-model",
     "developerFix": "local/dev-model",
     "tester": "local/tester-model",
-    "testerCommit": "local/tester-model",
     "visualReview": "cloud/vision-model"
   }
 }
@@ -162,15 +162,13 @@ Allowed response `status` values:
 
 ## Git Finalization
 
-The harness is designed to keep commit history structured:
+The default flow keeps commit ownership with the active agent:
 
 1. `developer` should leave a clean, reviewable diff and should not commit.
-2. `tester` should review functionality and, on `PASS`, provide a commit plan:
-   - `COMMIT_MESSAGE: ...`
-   - `COMMIT_FILES:`
-   - `- path/to/file`
-3. The harness stages only those requested files and performs the commit itself.
-4. If the requested plan cannot be isolated safely, the iteration is blocked or failed instead of committing unrelated work.
+2. `tester` should review functionality and, on `PASS`, stage only the task-related files and create the commit directly.
+3. If the working tree is too messy to isolate safely, tester should return `VERDICT: BLOCKED` instead of guessing.
+
+If a repo explicitly needs the older harness-managed commit-plan flow, set `commitMode` to `plan`. In that mode, `testerCommit` and parsed commit plans are used as a compatibility path rather than the default.
 
 ## Persistent Handoffs
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@sebastianandreasson/pi-autonomous-agents",
   "private": false,
-  "version": "0.1.0",
+  "version": "0.3.0",
   "type": "module",
   "description": "Portable unattended PI harness for developer/tester/visual-review loops.",
   "license": "MIT",
@@ -16,8 +16,8 @@
     "pi-harness": "./src/cli.mjs"
   },
   "scripts": {
-    "check": "node --check src/cli.mjs && node --check src/pi-client.mjs && node --check src/pi-config.mjs && node --check src/pi-flow.mjs && node --check src/pi-heartbeat.mjs && node --check src/pi-prompts.mjs && node --check src/pi-repo.mjs && node --check src/pi-report.mjs && node --check src/pi-rpc-adapter.mjs && node --check src/pi-supervisor.mjs && node --check src/pi-telemetry.mjs && node --check src/pi-visual-once.mjs && node --check src/pi-visual-review.mjs && node --check src/index.mjs && node --check test/pi-heartbeat.test.mjs && node --check test/pi-role-models.test.mjs && node --check test/pi-flow.test.mjs",
-    "test": "node --test test/pi-heartbeat.test.mjs test/pi-role-models.test.mjs test/pi-flow.test.mjs"
+    "check": "node --check src/cli.mjs && node --check src/pi-clear-history.mjs && node --check src/pi-client.mjs && node --check src/pi-config.mjs && node --check src/pi-flow.mjs && node --check src/pi-heartbeat.mjs && node --check src/pi-history.mjs && node --check src/pi-preflight.mjs && node --check src/pi-prompts.mjs && node --check src/pi-repo.mjs && node --check src/pi-report.mjs && node --check src/pi-rpc-adapter.mjs && node --check src/pi-supervisor.mjs && node --check src/pi-telemetry.mjs && node --check src/pi-visual-once.mjs && node --check src/pi-visual-review.mjs && node --check src/index.mjs && node --check test/pi-heartbeat.test.mjs && node --check test/pi-role-models.test.mjs && node --check test/pi-flow.test.mjs && node --check test/pi-history.test.mjs && node --check test/pi-prompts.test.mjs && node --check test/pi-preflight.test.mjs && node --check test/pi-repo.test.mjs && node --check test/pi-telemetry.test.mjs",
+    "test": "node --test test/pi-heartbeat.test.mjs test/pi-role-models.test.mjs test/pi-flow.test.mjs test/pi-history.test.mjs test/pi-prompts.test.mjs test/pi-preflight.test.mjs test/pi-repo.test.mjs test/pi-telemetry.test.mjs"
   },
   "files": [
     "src",

package/pi.config.json

@@ -3,6 +3,7 @@
   "adapterCommand": "pi-harness adapter",
   "instructionsFile": "",
   "taskFile": "TODOS.md",
+  "commitMode": "agent",
   "streamTerminal": false,
   "loopRepeatThreshold": 12,
   "samePathRepeatThreshold": 8,

package/src/cli.mjs

@@ -11,6 +11,7 @@ const COMMANDS = new Map([
   ['once', 'pi-supervisor.mjs'],
   ['run', 'pi-supervisor.mjs'],
   ['report', 'pi-report.mjs'],
+  ['clear-history', 'pi-clear-history.mjs'],
   ['visual-once', 'pi-visual-once.mjs'],
   ['adapter', 'pi-rpc-adapter.mjs'],
   ['visual-review-worker', 'pi-visual-review.mjs'],

package/src/index.mjs

@@ -4,4 +4,10 @@ export {
   deriveWorkflowStatus,
   shouldPersistLatestTesterFeedback,
 } from './pi-flow.mjs'
+export {
+  extractModelIdsFromProviderResponse,
+  parsePiListModelsOutput,
+  runStartupPreflight,
+} from './pi-preflight.mjs'
+export { clearHarnessHistory, collectHistoryTargets } from './pi-history.mjs'
 export { runAgentTurn } from './pi-client.mjs'

package/src/pi-clear-history.mjs

@@ -0,0 +1,26 @@
+#!/usr/bin/env node
+
+import { loadConfig } from './pi-config.mjs'
+import { ensureRepo } from './pi-repo.mjs'
+import { clearHarnessHistory } from './pi-history.mjs'
+
+async function main() {
+  const config = loadConfig('once')
+  ensureRepo(config.cwd)
+
+  const result = await clearHarnessHistory(config)
+
+  console.log(`Cleared harness history for ${result.clearedTargets.length} existing paths.`)
+  if (result.clearedTargets.length > 0) {
+    console.log('Cleared:')
+    for (const targetPath of result.clearedTargets) {
+      console.log(`- ${targetPath}`)
+    }
+  }
+  console.log('Verification passed: no configured harness history paths remain.')
+}
+
+main().catch((error) => {
+  console.error(error instanceof Error ? error.message : String(error))
+  process.exitCode = 1
+})

package/src/pi-client.mjs

@@ -18,6 +18,7 @@ function formatLastAgentOutput(response) {
     `status: ${String(response.status ?? '')}`,
     `sessionId: ${String(response.sessionId ?? '')}`,
     `sessionFile: ${String(response.sessionFile ?? '')}`,
+    `terminalReason: ${String(response.terminalReason ?? '')}`,
     `notes: ${String(response.notes ?? '').trim()}`,
   ]
 
@@ -58,6 +59,15 @@ async function runMockTurn({ config, sessionId, sessionFile, prompt, reason }) {
     durationSeconds: 0,
     output,
     notes: 'Mock transport completed without repo edits.',
+    role: '',
+    model: '',
+    toolCalls: 0,
+    toolErrors: 0,
+    messageUpdates: 0,
+    stopReason: '',
+    loopDetected: false,
+    loopSignature: '',
+    terminalReason: 'mock_completed',
   }
 }
 
@@ -142,6 +152,15 @@ async function runAdapterTurn({ config, model, sessionId, sessionFile, prompt, i
       durationSeconds: result.durationSeconds,
       output: result.combinedOutput,
       notes: 'Adapter process exceeded the configured timeout.',
+      role: '',
+      model: model ?? config.piModel,
+      toolCalls: 0,
+      toolErrors: 0,
+      messageUpdates: 0,
+      stopReason: '',
+      loopDetected: false,
+      loopSignature: '',
+      terminalReason: 'agent_timeout',
     }
   }
 
@@ -157,6 +176,15 @@ async function runAdapterTurn({ config, model, sessionId, sessionFile, prompt, i
       durationSeconds: result.durationSeconds,
       output: result.combinedOutput,
       notes: truncateForNotes(result.combinedOutput) || 'Adapter exited non-zero.',
+      role: '',
+      model: model ?? config.piModel,
+      toolCalls: 0,
+      toolErrors: 0,
+      messageUpdates: 0,
+      stopReason: '',
+      loopDetected: false,
+      loopSignature: '',
+      terminalReason: 'adapter_failed',
     }
   }
 
@@ -179,6 +207,15 @@ async function runAdapterTurn({ config, model, sessionId, sessionFile, prompt, i
     durationSeconds: result.durationSeconds,
     output,
     notes,
+    role: String(response.role ?? ''),
+    model: String(response.model ?? model ?? config.piModel ?? ''),
+    toolCalls: Number.isFinite(Number(response.toolCalls)) ? Number(response.toolCalls) : 0,
+    toolErrors: Number.isFinite(Number(response.toolErrors)) ? Number(response.toolErrors) : 0,
+    messageUpdates: Number.isFinite(Number(response.messageUpdates)) ? Number(response.messageUpdates) : 0,
+    stopReason: String(response.stopReason ?? ''),
+    loopDetected: response.loopDetected === true,
+    loopSignature: String(response.loopSignature ?? ''),
+    terminalReason: String(response.terminalReason ?? ''),
   }
 }
 

package/src/pi-config.mjs

@@ -130,6 +130,22 @@ function normalizeRoleModels(raw) {
   return normalized
 }
 
+function normalizeCommitMode(raw) {
+  const value = normalizeString(raw, 'agent').trim().toLowerCase()
+  if (value === 'agent' || value === 'plan') {
+    return value
+  }
+  throw new Error(`Expected commitMode to be "agent" or "plan", received "${raw}"`)
+}
+
+function normalizePromptMode(raw) {
+  const value = normalizeString(raw, 'compact').trim().toLowerCase()
+  if (value === 'compact' || value === 'full') {
+    return value
+  }
+  throw new Error(`Expected promptMode to be "compact" or "full", received "${raw}"`)
+}
+
 function resolveModelProfile(modelProfiles, modelName) {
   if (!modelName || typeof modelName !== 'string') {
     return null
@@ -181,12 +197,30 @@ export function loadConfig(mode = 'once') {
   const repoConfig = readRepoConfig(cwd)
   const file = repoConfig.values
   const bundledAdapterCommand = 'pi-harness adapter'
+  const bundledDeveloperInstructionsFile = path.join(packageRoot, 'templates', 'DEVELOPER.md')
+  const bundledTesterInstructionsFile = path.join(packageRoot, 'templates', 'TESTER.md')
   const modelProfiles = readObject('models', file.models, {})
   const roleModels = normalizeRoleModels(file.roleModels)
   const piModel = readString('PI_MODEL', file.piModel, '')
   const visualReviewModel = readString('PI_VISUAL_REVIEW_MODEL', file.visualReviewModel, '')
   const resolvedPiModel = resolveModelProfile(modelProfiles, piModel)
   const resolvedVisualReviewModel = resolveModelProfile(modelProfiles, visualReviewModel)
+  const developerInstructionsFile = resolveInstructionsFile(
+    cwd,
+    'PI_DEVELOPER_INSTRUCTIONS_FILE',
+    file.developerInstructionsFile,
+    hasValue(file.instructionsFile)
+      ? String(file.instructionsFile)
+      : bundledDeveloperInstructionsFile
+  )
+  const testerInstructionsFile = resolveInstructionsFile(
+    cwd,
+    'PI_TESTER_INSTRUCTIONS_FILE',
+    file.testerInstructionsFile,
+    hasValue(file.instructionsFile)
+      ? String(file.instructionsFile)
+      : bundledTesterInstructionsFile
+  )
 
   return {
     cwd,
@@ -196,23 +230,11 @@ export function loadConfig(mode = 'once') {
     agentName: readString('PI_AGENT_NAME', file.agentName, 'PI'),
     adapterCommand: readString('PI_ADAPTER_COMMAND', file.adapterCommand, bundledAdapterCommand),
     taskFile: resolveFromCwd(cwd, 'PI_TASK_FILE', file.taskFile, 'TODOS.md'),
-    instructionsFile: resolveInstructionsFile(cwd, 'PI_INSTRUCTIONS_FILE', file.instructionsFile, path.join(packageRoot, 'templates', 'DEVELOPER.md')),
-    developerInstructionsFile: resolveInstructionsFile(
-      cwd,
-      'PI_DEVELOPER_INSTRUCTIONS_FILE',
-      file.developerInstructionsFile,
-      hasValue(file.instructionsFile)
-        ? String(file.instructionsFile)
-        : path.join(packageRoot, 'templates', 'DEVELOPER.md')
-    ),
-    testerInstructionsFile: resolveInstructionsFile(
-      cwd,
-      'PI_TESTER_INSTRUCTIONS_FILE',
-      file.testerInstructionsFile,
-      hasValue(file.instructionsFile)
-        ? String(file.instructionsFile)
-        : path.join(packageRoot, 'templates', 'TESTER.md')
-    ),
+    instructionsFile: resolveInstructionsFile(cwd, 'PI_INSTRUCTIONS_FILE', file.instructionsFile, bundledDeveloperInstructionsFile),
+    developerInstructionsFile,
+    testerInstructionsFile,
+    usingBundledDeveloperInstructions: developerInstructionsFile === bundledDeveloperInstructionsFile,
+    usingBundledTesterInstructions: testerInstructionsFile === bundledTesterInstructionsFile,
     logFile: resolveFromCwd(cwd, 'PI_LOG_FILE', file.logFile, 'pi.log'),
     telemetryJsonl: resolveFromCwd(cwd, 'PI_TELEMETRY_JSONL', file.telemetryJsonl, 'pi_telemetry.jsonl'),
     telemetryCsv: resolveFromCwd(cwd, 'PI_TELEMETRY_CSV', file.telemetryCsv, 'pi_telemetry.csv'),
@@ -221,12 +243,21 @@ export function loadConfig(mode = 'once') {
     lastAgentOutputFile: resolveFromCwd(cwd, 'PI_LAST_AGENT_OUTPUT_FILE', file.lastAgentOutputFile, '.pi-last-output.txt'),
     lastVerificationOutputFile: resolveFromCwd(cwd, 'PI_LAST_VERIFICATION_OUTPUT_FILE', file.lastVerificationOutputFile, '.pi-last-verification.txt'),
     changedFilesFile: resolveFromCwd(cwd, 'PI_CHANGED_FILES_FILE', file.changedFilesFile, '.pi-changed-files.txt'),
+    lastPromptFile: resolveFromCwd(cwd, 'PI_LAST_PROMPT_FILE', file.lastPromptFile, '.pi-last-prompt.txt'),
+    lastIterationSummaryFile: resolveFromCwd(cwd, 'PI_LAST_ITERATION_SUMMARY_FILE', file.lastIterationSummaryFile, '.pi-last-iteration.json'),
     piRuntimeDir: resolveFromCwd(cwd, 'PI_RUNTIME_DIR', file.piRuntimeDir, '.pi-runtime'),
     piCli: readString('PI_CLI', file.piCli, 'pi'),
     piModel,
     piModelProfile: resolvedPiModel,
     modelProfiles,
     roleModels,
+    commitMode: normalizeCommitMode(readString('PI_COMMIT_MODE', file.commitMode, 'agent')),
+    promptMode: normalizePromptMode(readString('PI_PROMPT_MODE', file.promptMode, 'compact')),
+    maxPromptChangedFiles: readInt('PI_MAX_PROMPT_CHANGED_FILES', file.maxPromptChangedFiles, 10),
+    maxVisualFeedbackLines: readInt('PI_MAX_VISUAL_FEEDBACK_LINES', file.maxVisualFeedbackLines, 20),
+    maxTesterFeedbackLines: readInt('PI_MAX_TESTER_FEEDBACK_LINES', file.maxTesterFeedbackLines, 32),
+    maxPromptNotesLines: readInt('PI_MAX_PROMPT_NOTES_LINES', file.maxPromptNotesLines, 16),
+    maxVerificationExcerptLines: readInt('PI_MAX_VERIFICATION_EXCERPT_LINES', file.maxVerificationExcerptLines, 40),
     piTools: readString('PI_TOOLS', file.piTools, 'read,bash,edit,write,grep,find,ls'),
     piThinking: readString('PI_THINKING', file.piThinking, ''),
     piNoExtensions: readBool('PI_NO_EXTENSIONS', file.piNoExtensions, false),

package/src/pi-history.mjs

@@ -0,0 +1,92 @@
+import fs from 'node:fs/promises'
+import path from 'node:path'
+
+function unique(values) {
+  return [...new Set(values)]
+}
+
+function isWithinCwd(cwd, targetPath) {
+  const relativePath = path.relative(cwd, targetPath)
+  return relativePath !== '' && !relativePath.startsWith('..') && !path.isAbsolute(relativePath)
+}
+
+export function collectHistoryTargets(config) {
+  return unique([
+    config.logFile,
+    config.telemetryJsonl,
+    config.telemetryCsv,
+    config.stateFile,
+    config.sessionFile,
+    config.lastAgentOutputFile,
+    config.lastVerificationOutputFile,
+    config.changedFilesFile,
+    config.lastPromptFile,
+    config.lastIterationSummaryFile,
+    config.piRuntimeDir,
+    config.visualFeedbackFile,
+    config.testerFeedbackFile,
+    config.testerFeedbackHistoryDir,
+    config.visualReviewHistoryDir,
+    config.visualCaptureDir,
+  ].map((value) => String(value ?? '').trim()).filter(Boolean))
+}
+
+async function pathExists(targetPath) {
+  try {
+    await fs.access(targetPath)
+    return true
+  } catch {
+    return false
+  }
+}
+
+function validateHistoryTargets(config, targets) {
+  const invalidTargets = targets.filter((targetPath) => {
+    if (!path.isAbsolute(targetPath)) {
+      return true
+    }
+    if (targetPath === config.cwd || targetPath === path.parse(targetPath).root) {
+      return true
+    }
+    return !isWithinCwd(config.cwd, targetPath)
+  })
+
+  if (invalidTargets.length > 0) {
+    throw new Error(
+      `Refusing to clear history outside the repo root. Invalid targets: ${invalidTargets.join(', ')}`
+    )
+  }
+}
+
+export async function clearHarnessHistory(config) {
+  const targets = collectHistoryTargets(config)
+  validateHistoryTargets(config, targets)
+
+  const existingTargets = []
+  for (const targetPath of targets) {
+    if (await pathExists(targetPath)) {
+      existingTargets.push(targetPath)
+    }
+  }
+
+  for (const targetPath of [...existingTargets].sort((left, right) => right.length - left.length)) {
+    await fs.rm(targetPath, { recursive: true, force: true })
+  }
+
+  const remainingTargets = []
+  for (const targetPath of targets) {
+    if (await pathExists(targetPath)) {
+      remainingTargets.push(targetPath)
+    }
+  }
+
+  if (remainingTargets.length > 0) {
+    throw new Error(`Failed to clear harness history for: ${remainingTargets.join(', ')}`)
+  }
+
+  return {
+    targets,
+    clearedTargets: existingTargets,
+    remainingTargets,
+  }
+}