@sebastianandreasson/pi-autonomous-agents 0.3.0 → 0.5.0

package/README.md

@@ -6,7 +6,7 @@
 - a fast verification step
 - a skeptical `tester` pass
 - optional periodic multimodal visual review
-- harness-owned git finalization
+- tester-owned final commit by default
 
 The package is intentionally generic. It does not know how to navigate or test a specific app on its own.
 
@@ -18,7 +18,7 @@ The package is intentionally generic. It does not know how to navigate or test a
 - telemetry
 - loop guards, timeout guards, and retries
 - tester feedback + visual feedback handoff
-- harness-owned git finalize step
+- optional legacy harness git finalize step for `commitMode: "plan"`
 - multimodal visual review client
 
 ## What Stays Per Project
@@ -93,6 +93,7 @@ The command removes configured harness history/runtime files and verifies that n
 
 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.
+For run isolation, the supervisor also maintains `.pi-runtime/active-run.json` and stores PI sessions plus per-run telemetry under `.pi-runtime/runs/<runId>/`.
 
 ## Generic Contracts
 
@@ -113,10 +114,16 @@ Keep TODO items extremely small and implementation-shaped when using weaker loca
 
 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.
 
+The supervisor now enforces single-run ownership per repo/config. If a stale run crashed mid-iteration, the next run recovers the unfinished iteration number from `.pi-state.json` instead of silently rolling forward.
+
 `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 default coding tool mix is now safer for local models: `read,edit,write,find,ls,bash`. Prompts explicitly steer source inspection toward `read` and reserve shell usage for `git`, tests, and narrow diagnostics.
+
+The harness also emits lightweight large-file warnings for touched source/spec files and carries them into `.pi-last-iteration.json`, `pi-harness report`, and relevant prompts. Tune `largeFileWarningLines` and `largeSpecWarningLines` if needed.
+
 The harness expects screenshot capture to produce a `manifest.json` plus image files under the configured visual capture directory.

package/SETUP.md

@@ -47,6 +47,7 @@ If the repo uses another package manager already, use the repo-native equivalent
   - `developerInstructionsFile`: `pi/DEVELOPER.md`
   - `testerInstructionsFile`: `pi/TESTER.md`
   - `commitMode`: normally `agent`
+  - `promptMode`: normally `compact`
   - `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
@@ -125,6 +126,7 @@ Recommended pattern:
 - 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
+- keep large-file thresholds sensible for local models (`largeFileWarningLines`, `largeSpecWarningLines`)
 
 Example shape:
 
@@ -192,6 +194,7 @@ For flow debugging, inspect `.pi-last-iteration.json` after a run. It summarizes
 - 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.
+- Prefer `read` for code inspection and keep shell usage focused on `git`, tests, and narrow diagnostics, especially for weaker local models.
 
 ## What To Report Back
 

package/docs/PI_SUPERVISOR.md

@@ -30,7 +30,7 @@ Main package files:
 - `src/pi-client.mjs`: transport layer
 - `src/pi-rpc-adapter.mjs`: built-in adapter from supervisor JSON to `pi --mode rpc`
 - `src/pi-config.mjs`: config loader
-- `src/pi-repo.mjs`: repo helpers, verification runner, git finalize step
+- `src/pi-repo.mjs`: repo helpers, verification runner, and optional legacy git finalize step
 - `src/pi-telemetry.mjs`: telemetry writer/reader
 - `src/pi-prompts.mjs`: default prompt builders
 - `src/pi-visual-review.mjs`: multimodal visual-review worker
@@ -126,7 +126,7 @@ Request shape:
   "runtimeDir": "/absolute/repo/path/.pi-runtime",
   "piCli": "pi",
   "model": "local/model-name",
-  "tools": "read,bash,edit,write,grep,find,ls",
+  "tools": "read,edit,write,find,ls,bash",
   "thinking": "",
   "noExtensions": false,
   "noSkills": false,
@@ -170,6 +170,8 @@ The default flow keeps commit ownership with the active agent:
 
 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.
 
+For source inspection, prompts prefer `read` and reserve shell usage for `git`, tests, and narrow diagnostics. Large shell file reads are more likely to truncate under context pressure than focused `read` calls.
+
 ## Persistent Handoffs
 
 The harness persists two cross-iteration handoff files:

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@sebastianandreasson/pi-autonomous-agents",
   "private": false,
-  "version": "0.3.0",
+  "version": "0.5.0",
   "type": "module",
   "description": "Portable unattended PI harness for developer/tester/visual-review loops.",
   "license": "MIT",

package/src/index.mjs

@@ -10,4 +10,5 @@ export {
   runStartupPreflight,
 } from './pi-preflight.mjs'
 export { clearHarnessHistory, collectHistoryTargets } from './pi-history.mjs'
+export { collectLargeFileWarnings } from './pi-repo.mjs'
 export { runAgentTurn } from './pi-client.mjs'

package/src/pi-client.mjs

@@ -103,7 +103,7 @@ async function runAdapterTurn({ config, model, sessionId, sessionFile, prompt, i
     instructionsFile: config.instructionsFile,
     developerInstructionsFile: config.developerInstructionsFile,
     testerInstructionsFile: config.testerInstructionsFile,
-    runtimeDir: config.piRuntimeDir,
+    runtimeDir: config.runRuntimeDir || config.piRuntimeDir,
     piCli: config.piCli,
     model: model ?? config.piModel,
     tools: config.piTools,

package/src/pi-config.mjs

@@ -246,6 +246,7 @@ export function loadConfig(mode = 'once') {
     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'),
+    activeRunFile: resolveFromCwd(cwd, 'PI_ACTIVE_RUN_FILE', file.activeRunFile, '.pi-runtime/active-run.json'),
     piCli: readString('PI_CLI', file.piCli, 'pi'),
     piModel,
     piModelProfile: resolvedPiModel,
@@ -258,7 +259,9 @@ export function loadConfig(mode = 'once') {
     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'),
+    largeFileWarningLines: readInt('PI_LARGE_FILE_WARNING_LINES', file.largeFileWarningLines, 500),
+    largeSpecWarningLines: readInt('PI_LARGE_SPEC_WARNING_LINES', file.largeSpecWarningLines, 300),
+    piTools: readString('PI_TOOLS', file.piTools, 'read,edit,write,find,ls,bash'),
     piThinking: readString('PI_THINKING', file.piThinking, ''),
     piNoExtensions: readBool('PI_NO_EXTENSIONS', file.piNoExtensions, false),
     piNoSkills: readBool('PI_NO_SKILLS', file.piNoSkills, false),

package/src/pi-prompts.mjs

@@ -40,6 +40,20 @@ function formatChangedFilesSection(files, maxFiles) {
   return lines.join('\n')
 }
 
+function formatLargeFileRiskHint(warnings) {
+  const list = Array.isArray(warnings) ? warnings.filter(Boolean) : []
+  if (list.length === 0) {
+    return ''
+  }
+
+  const lines = list
+    .slice(0, 3)
+    .map((warning) => `- ${warning.file} (${warning.lineCount} lines${warning.kind === 'large_spec' ? ', spec' : ''})`)
+    .join('\n')
+
+  return `\nLarge file risk in touched files:\n${lines}\nPrefer helper extraction, smaller scoped edits, or test splitting over broad in-place edits.\n`
+}
+
 function displayPath(config, filePath) {
   const relativePath = path.relative(config.cwd, filePath)
   if (
@@ -160,6 +174,9 @@ Harness rules:
 - Start by checking git status so you know whether unrelated changes already exist.
 - Update code, config, and docs only as needed for the selected task.
 - Tick only the checkbox items that are actually completed.
+- Use read for source inspection. Use bash only for git, tests, and narrow diagnostics.
+- Do not build edits from large sed/grep output or from memory after partial shell reads.
+- If a snippet seems incomplete, reread a smaller exact window with read instead of another large overlapping shell range.
 - If blocked, add a brief note directly under the relevant task in ${taskFile} explaining the blocker, then stop.
 - Do not create the final commit during the developer pass.
 ${staleEditRecoveryRules()}
@@ -180,6 +197,9 @@ Rules:
 - Start with git status.
 - Select the first unchecked actionable checkbox in phase order.
 - Keep changes minimal and scoped.
+- Use read for source inspection. Use bash only for git, tests, and narrow diagnostics.
+- If a snippet seems incomplete, reread a smaller exact window with read instead of another large overlapping shell range.
+- Do not edit from memory after partial shell output.
 - Tick only completed items.
 - If blocked, note it under the task in ${taskFile} and stop.
 - Do not touch lockfiles, generated files, or unrelated assets.
@@ -203,11 +223,13 @@ export function buildFixPrompt(config, recentVerificationOutput, options = {}) {
     config.usingBundledDeveloperInstructions,
   )
   const findings = clampLines(recentVerificationOutput, configMaxLines(config, 'maxVerificationExcerptLines', 40))
+  const largeFileRiskHint = formatLargeFileRiskHint(options.largeFileWarnings)
 
   if (!config.usingBundledDeveloperInstructions) {
     return `Read ${taskFile} and ${instructionsFile}.
 ${authorityLine}${visualFeedbackSection}
 ${testerFeedbackSection}
+${largeFileRiskHint}
 
 The tester step found a real problem in the current implementation. Fix only the product behavior related to the current phase and current task.
 
@@ -218,6 +240,9 @@ Harness rules:
 - Start by checking git status so you know which files are already dirty.
 - Do not paper over product bugs by weakening tests.
 - Keep changes minimal and focused on the failing behavior.
+- Use read for source inspection. Use bash only for git, tests, and narrow diagnostics.
+- If a snippet seems incomplete, reread a smaller exact window with read instead of another large overlapping shell range.
+- Do not edit from memory after partial shell output.
 - Do not perform speculative cleanup or unrelated refactors in this pass.
 - Do not create the final commit during the developer fix pass.
 ${staleEditRecoveryRules()}
@@ -230,6 +255,7 @@ Before stopping:
   return `Read ${taskFile} and ${instructionsFile}.
 ${authorityLine}${visualFeedbackSection}
 ${testerFeedbackSection}
+${largeFileRiskHint}
 
 The tester step found a real problem in the current implementation. Fix only the product behavior related to the current phase and current task.
 
@@ -240,6 +266,9 @@ Rules:
 - Start with git status.
 - Keep the fix narrow.
 - Do not weaken tests to hide product bugs.
+- Use read for source inspection. Use bash only for git, tests, and narrow diagnostics.
+- If a snippet seems incomplete, reread a smaller exact window with read instead of another large overlapping shell range.
+- Do not edit from memory after partial shell output.
 - Do not perform speculative cleanup or unrelated refactors.
 - Do not create the final commit.
 ${staleEditRecoveryRules()}
@@ -259,12 +288,14 @@ export function buildSteeringPrompt(config, reason, options = {}) {
     config.developerInstructionsFile,
     config.usingBundledDeveloperInstructions,
   )
+  const largeFileRiskHint = formatLargeFileRiskHint(options.largeFileWarnings)
 
   if (!config.usingBundledDeveloperInstructions) {
     return `Continue from the current repo state.
 Read ${taskFile} and ${instructionsFile}.
 ${authorityLine}${visualFeedbackSection}
 ${testerFeedbackSection}
+${largeFileRiskHint}
 
 Reason for this follow-up: ${reason}
 
@@ -272,9 +303,11 @@ Select the first unchecked actionable checkbox in the current phase, complete on
 
 Additional harness guardrails:
 - Start by checking git status.
+- Use read for source inspection. Use bash only for git, tests, and narrow diagnostics.
 - Do not repeat the same tool call over and over.
 - If you already read a file, use that context instead of rereading it unless something changed.
 - If an edit fails once, reread the file before retrying. Do not repeat the same exact edit attempt.
+- If a snippet seems incomplete, reread a smaller exact window with read instead of another large overlapping shell range.
 - If you are stuck, make the smallest decisive next action or stop and state the blocker.`
   }
 
@@ -282,15 +315,18 @@ Additional harness guardrails:
 Read ${taskFile} and ${instructionsFile}.
 ${authorityLine}${visualFeedbackSection}
 ${testerFeedbackSection}
+${largeFileRiskHint}
 
 Reason for this follow-up: ${reason}
 
 Select the first unchecked actionable checkbox in the current phase, complete one coherent task, tick completed items, run verification, and stop.
 
 Additional guardrails:
+- Use read for source inspection. Use bash only for git, tests, and narrow diagnostics.
 - Do not repeat the same tool call over and over.
 - If you already read a file, use that context instead of rereading it unless something changed.
 - If an edit fails once, reread the file before retrying. Do not repeat the same exact edit attempt.
+- If a snippet seems incomplete, reread a smaller exact window with read instead of another large overlapping shell range.
 - Prefer the configured smoke verification path and one narrow targeted check over long full-flow Playwright specs.
 - If you are stuck, make the smallest decisive next action or stop and state the blocker.`
 }
@@ -303,6 +339,7 @@ export function buildTesterPrompt(config, {
   reason = 'tester_review',
   visualFeedback = '',
   testerFeedback = '',
+  largeFileWarnings = [],
 }) {
   const taskFile = displayPath(config, config.taskFile)
   const instructionsFile = displayPath(config, config.testerInstructionsFile)
@@ -326,11 +363,13 @@ export function buildTesterPrompt(config, {
     config.usingBundledTesterInstructions,
   )
   const passOwnership = testerPassOwnershipRules(config)
+  const largeFileRiskHint = formatLargeFileRiskHint(largeFileWarnings)
 
   if (!config.usingBundledTesterInstructions) {
     return `Read ${taskFile} and ${instructionsFile}.
 ${authorityLine}${visualFeedbackSection}
 ${testerFeedbackSection}
+${largeFileRiskHint}
 
 You are the TESTER role. You are reviewing the most recent developer work from an independent quality and functionality perspective.
 
@@ -348,6 +387,8 @@ Rules:
 - Start with git status.
 - Follow repo-local tester instructions for what to verify and which commands to run.
 - Prefer one focused review pass.
+- Use read for source inspection. Use bash only for git, tests, and narrow diagnostics.
+- If a snippet seems incomplete, reread a smaller exact window with read instead of another large overlapping shell range.
 - If blocked or inconclusive, return VERDICT: BLOCKED.
 - Do not hide real bugs with brittle tests.
 - ${passOwnership.successRule.slice(2)}
@@ -370,6 +411,7 @@ Before stopping, end your final response with exactly one verdict line:
   return `Read ${taskFile} and ${instructionsFile}.
 ${authorityLine}${visualFeedbackSection}
 ${testerFeedbackSection}
+${largeFileRiskHint}
 
 You are the TESTER role. You are reviewing the most recent developer work from an independent quality and functionality perspective.
 
@@ -385,9 +427,11 @@ ${changedFilesSection}
 
 	Rules:
 	- Start with git status.
+	- Use read for source inspection. Use bash only for git, tests, and narrow diagnostics.
 	- Run the repo verification command yourself: ${verificationCommand}
 ${indentBlock(innerLoopValidationRules(verificationCommand), '\t')}
 	- Prefer one focused browser-driven review pass.
+	- If a snippet seems incomplete, reread a smaller exact window with read instead of another large overlapping shell range.
 	- Do not hide real bugs with brittle tests.
 	- If blocked or inconclusive, return VERDICT: BLOCKED.
 ${indentBlock(passOwnership.successRule, '\t')}
@@ -415,6 +459,7 @@ export function buildCommitPrompt(config, {
   reason = 'tester_passed_without_commit',
   visualFeedback = '',
   testerFeedback = '',
+  largeFileWarnings = [],
 }) {
   const taskFile = displayPath(config, config.taskFile)
   const instructionsFile = displayPath(config, config.testerInstructionsFile)
@@ -433,10 +478,12 @@ export function buildCommitPrompt(config, {
     developerNotes || '(none provided)',
     configMaxLines(config, 'maxPromptNotesLines', 16),
   )
+  const largeFileRiskHint = formatLargeFileRiskHint(largeFileWarnings)
 
   return `Read ${taskFile} and ${instructionsFile}.
 ${authorityLine}${visualFeedbackSection}
 ${testerFeedbackSection}
+${largeFileRiskHint}
 
 You are the TESTER role. The implementation already passed functional review, but the final commit was not created.
 

package/src/pi-repo.mjs

@@ -1,6 +1,7 @@
 import fs from 'node:fs/promises'
 import { readFileSync } from 'node:fs'
 import process from 'node:process'
+import { randomUUID } from 'node:crypto'
 import { execFileSync, spawn } from 'node:child_process'
 import path from 'node:path'
 
@@ -9,7 +10,17 @@ export function timestamp() {
 }
 
 export async function appendLog(logFile, message) {
-  await fs.appendFile(logFile, `[${timestamp()}] ${message}\n`, 'utf8')
+  const runId = String(process.env.PI_RUN_ID ?? '').trim()
+  const prefix = runId !== '' ? `[run:${runId}] ` : ''
+  const line = `[${timestamp()}] ${prefix}${message}\n`
+  await fs.mkdir(path.dirname(logFile), { recursive: true })
+  await fs.appendFile(logFile, line, 'utf8')
+
+  const runLogFile = String(process.env.PI_RUN_LOG_FILE ?? '').trim()
+  if (runLogFile !== '' && runLogFile !== logFile) {
+    await fs.mkdir(path.dirname(runLogFile), { recursive: true })
+    await fs.appendFile(runLogFile, line, 'utf8')
+  }
 }
 
 export function ensureRepo(cwd) {
@@ -30,7 +41,27 @@ export async function ensureFileExists(filePath, label) {
 export async function readState(stateFile) {
   try {
     const raw = await fs.readFile(stateFile, 'utf8')
-    return JSON.parse(raw)
+    const parsed = JSON.parse(raw)
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+      throw new Error('Invalid state file payload')
+    }
+    return {
+      iteration: 0,
+      lastTransport: '',
+      lastPiModel: '',
+      sessionId: '',
+      sessionFile: '',
+      consecutiveFailures: 0,
+      successfulIterations: 0,
+      lastPhase: '',
+      lastStatus: '',
+      lastVerificationStatus: '',
+      lastVisualStatus: '',
+      lastRunAt: '',
+      runId: '',
+      inProgress: null,
+      ...parsed,
+    }
   } catch {
     return {
       iteration: 0,
@@ -38,22 +69,165 @@ export async function readState(stateFile) {
       lastPiModel: '',
       sessionId: '',
       sessionFile: '',
-        consecutiveFailures: 0,
-        successfulIterations: 0,
-        lastPhase: '',
-        lastStatus: '',
-        lastVerificationStatus: '',
-        lastVisualStatus: '',
-        lastRunAt: '',
-      }
+      consecutiveFailures: 0,
+      successfulIterations: 0,
+      lastPhase: '',
+      lastStatus: '',
+      lastVerificationStatus: '',
+      lastVisualStatus: '',
+      lastRunAt: '',
+      runId: '',
+      inProgress: null,
+    }
   }
 }
 
 export async function writeState(stateFile, state) {
   const formatted = `${JSON.stringify(state, null, 2)}\n`
+  await fs.mkdir(path.dirname(stateFile), { recursive: true })
   await fs.writeFile(stateFile, formatted, 'utf8')
 }
 
+export function createRunId() {
+  return randomUUID()
+}
+
+function normalizePid(raw) {
+  const pid = Number.parseInt(String(raw ?? ''), 10)
+  return Number.isInteger(pid) && pid > 0 ? pid : 0
+}
+
+export function isProcessRunning(pid) {
+  const normalizedPid = normalizePid(pid)
+  if (normalizedPid <= 0) {
+    return false
+  }
+
+  try {
+    process.kill(normalizedPid, 0)
+    return true
+  } catch (error) {
+    if (error && typeof error === 'object' && 'code' in error) {
+      return error.code === 'EPERM'
+    }
+    return false
+  }
+}
+
+export async function readJsonFile(filePath, fallback = null) {
+  try {
+    const raw = await fs.readFile(filePath, 'utf8')
+    return JSON.parse(raw)
+  } catch {
+    return fallback
+  }
+}
+
+async function writeJsonFile(filePath, value, flags) {
+  const formatted = `${JSON.stringify(value, null, 2)}\n`
+  await fs.mkdir(path.dirname(filePath), { recursive: true })
+  await fs.writeFile(filePath, formatted, { encoding: 'utf8', flag: flags })
+}
+
+export async function acquireRunLock(lockFile, lockState) {
+  const desired = {
+    runId: String(lockState?.runId ?? ''),
+    pid: normalizePid(lockState?.pid),
+    startedAt: String(lockState?.startedAt ?? timestamp()),
+    heartbeatAt: String(lockState?.heartbeatAt ?? timestamp()),
+    status: String(lockState?.status ?? 'starting'),
+    iteration: Number.isFinite(Number(lockState?.iteration)) ? Number(lockState.iteration) : 0,
+    phase: String(lockState?.phase ?? ''),
+    task: String(lockState?.task ?? ''),
+    mode: String(lockState?.mode ?? ''),
+    configFile: String(lockState?.configFile ?? ''),
+    cwd: String(lockState?.cwd ?? ''),
+  }
+
+  await fs.mkdir(path.dirname(lockFile), { recursive: true })
+
+  try {
+    await writeJsonFile(lockFile, desired, 'wx')
+    return { acquired: true, staleLock: null }
+  } catch (error) {
+    if (!error || typeof error !== 'object' || !('code' in error) || error.code !== 'EEXIST') {
+      throw error
+    }
+  }
+
+  const existing = await readJsonFile(lockFile, null)
+  const existingPid = normalizePid(existing?.pid)
+  if (existing && existingPid > 0 && isProcessRunning(existingPid) && existingPid !== process.pid) {
+    throw new Error(
+      `Another pi-harness run is active (runId=${String(existing.runId ?? '')} pid=${existingPid} startedAt=${String(existing.startedAt ?? '')}).`
+    )
+  }
+
+  await fs.rm(lockFile, { force: true })
+
+  try {
+    await writeJsonFile(lockFile, desired, 'wx')
+  } catch (error) {
+    if (error && typeof error === 'object' && 'code' in error && error.code === 'EEXIST') {
+      const current = await readJsonFile(lockFile, null)
+      throw new Error(
+        `Another pi-harness run acquired the lock first (runId=${String(current?.runId ?? '')} pid=${String(current?.pid ?? '')}).`
+      )
+    }
+    throw error
+  }
+
+  return { acquired: true, staleLock: existing }
+}
+
+export async function updateRunLock(lockFile, lockState) {
+  const current = await readJsonFile(lockFile, null)
+  if (!current) {
+    return false
+  }
+
+  const next = {
+    ...current,
+    ...lockState,
+    pid: normalizePid(lockState?.pid ?? current.pid),
+    heartbeatAt: String(lockState?.heartbeatAt ?? timestamp()),
+  }
+  await writeJsonFile(lockFile, next)
+  return true
+}
+
+export async function releaseRunLock(lockFile, runId) {
+  const current = await readJsonFile(lockFile, null)
+  if (!current) {
+    return false
+  }
+
+  if (String(current.runId ?? '') !== String(runId ?? '')) {
+    return false
+  }
+
+  await fs.rm(lockFile, { force: true })
+  return true
+}
+
+export function signalProcessTree(pid, signal) {
+  const normalizedPid = normalizePid(pid)
+  if (normalizedPid <= 0) {
+    return false
+  }
+
+  try {
+    if (process.platform !== 'win32') {
+      process.kill(-normalizedPid, signal)
+    } else {
+      process.kill(normalizedPid, signal)
+    }
+    return true
+  } catch {
+    return false
+  }
+}
+
 export async function readSessionId(sessionFile) {
   try {
     return (await fs.readFile(sessionFile, 'utf8')).trim()
@@ -225,6 +399,65 @@ export function findFirstUncheckedTaskInfo(taskFile) {
   }
 }
 
+function countLines(text) {
+  const normalized = String(text ?? '')
+  if (normalized === '') {
+    return 0
+  }
+  return normalized.split('\n').length
+}
+
+function isSpecLikeFile(filePath) {
+  const normalized = String(filePath ?? '').replaceAll('\\', '/')
+  return /(^|\/)(e2e|test|tests|spec|specs)\//.test(normalized)
+    || /\.(spec|test)\.[cm]?[jt]sx?$/.test(normalized)
+}
+
+export function collectLargeFileWarnings(cwd, files, {
+  largeFileWarningLines = 500,
+  largeSpecWarningLines = 300,
+} = {}) {
+  const warnings = []
+  const seen = new Set()
+
+  for (const file of Array.isArray(files) ? files : []) {
+    const relativePath = String(file ?? '').trim()
+    if (relativePath === '' || seen.has(relativePath)) {
+      continue
+    }
+    seen.add(relativePath)
+
+    const absolutePath = path.resolve(cwd, relativePath)
+    let raw = ''
+    try {
+      raw = readFileSync(absolutePath, 'utf8')
+    } catch {
+      continue
+    }
+
+    const lineCount = countLines(raw)
+    const isSpec = isSpecLikeFile(relativePath)
+    if (isSpec && lineCount >= largeSpecWarningLines) {
+      warnings.push({
+        file: relativePath,
+        lineCount,
+        kind: 'large_spec',
+      })
+      continue
+    }
+
+    if (lineCount >= largeFileWarningLines) {
+      warnings.push({
+        file: relativePath,
+        lineCount,
+        kind: 'large_file',
+      })
+    }
+  }
+
+  return warnings.sort((left, right) => right.lineCount - left.lineCount)
+}
+
 export async function runShellCommand({
   cwd,
   command,
@@ -238,6 +471,7 @@ export async function runShellCommand({
     const child = spawn('/bin/zsh', ['-lc', command], {
       cwd,
       env: process.env,
+      detached: process.platform !== 'win32',
       stdio: ['pipe', 'pipe', 'pipe'],
     })
 
@@ -249,9 +483,9 @@ export async function runShellCommand({
 
     killTimer = setTimeout(() => {
       timedOut = true
-      child.kill('SIGTERM')
+      signalProcessTree(child.pid, 'SIGTERM')
       forceKillTimer = setTimeout(() => {
-        child.kill('SIGKILL')
+        signalProcessTree(child.pid, 'SIGKILL')
       }, 10000)
     }, timeoutSeconds * 1000)
 

package/src/pi-report.mjs

@@ -35,6 +35,17 @@ async function main() {
     console.log(`- ${kind}: ${count}`)
   }
 
+  const iterationSummaries = recent.filter((event) => event.kind === 'iteration_summary')
+  const warningsByIteration = iterationSummaries
+    .filter((event) => String(event.riskWarnings ?? '').trim() !== '')
+
+  if (warningsByIteration.length > 0) {
+    console.log('\nLarge file warnings:')
+    for (const event of warningsByIteration.slice(-5)) {
+      console.log(`- iteration ${event.iteration}: ${event.riskWarnings}`)
+    }
+  }
+
   const last = recent.at(-1)
   if (!last) {
     return