@sebastianandreasson/pi-autonomous-agents 0.3.0 → 0.5.0

package/src/pi-rpc-adapter.mjs

@@ -10,6 +10,7 @@ import {
   getHeartbeatDecision,
   resolveHeartbeatConfig,
 } from './pi-heartbeat.mjs'
+import { signalProcessTree } from './pi-repo.mjs'
 
 function createJsonlReader(stream, onLine) {
   const rl = createInterface({ input: stream })
@@ -54,6 +55,44 @@ function extractToolTarget(toolName, args) {
   return ''
 }
 
+function extractShellCommand(args) {
+  if (!args || typeof args !== 'object') {
+    return ''
+  }
+
+  if (typeof args.command === 'string') {
+    return args.command
+  }
+
+  if (typeof args.cmd === 'string') {
+    return args.cmd
+  }
+
+  return ''
+}
+
+function isLargeShellRead(command) {
+  const text = String(command ?? '').trim()
+  if (text === '') {
+    return false
+  }
+
+  if (/^\s*cat\s+\S+/.test(text)) {
+    return true
+  }
+
+  const sedMatch = text.match(/sed\s+-n\s+['"]?(\d+)\s*,\s*(\d+)p['"]?/)
+  if (sedMatch) {
+    const start = Number.parseInt(sedMatch[1], 10)
+    const end = Number.parseInt(sedMatch[2], 10)
+    if (Number.isFinite(start) && Number.isFinite(end) && end >= start) {
+      return (end - start) >= 120
+    }
+  }
+
+  return false
+}
+
 function extractAssistantText(message) {
   if (!message || message.role !== 'assistant' || !Array.isArray(message.content)) {
     return ''
@@ -113,6 +152,7 @@ async function run() {
   const child = spawn(cli, args, {
     cwd: request.cwd,
     env: process.env,
+    detached: process.platform !== 'win32',
     stdio: ['pipe', 'pipe', 'pipe'],
   })
 
@@ -201,10 +241,10 @@ async function run() {
     closeAssistantLine()
     writeLive(`[PI guard] ${formatHeartbeatTimeoutMessage(decision)} Aborting current turn (pid=${child.pid ?? 'unknown'}).\n`)
     void send({ type: 'abort' }).catch(() => {})
-    child.kill('SIGTERM')
+    signalProcessTree(child.pid, 'SIGTERM')
     setTimeout(() => {
       if (child.exitCode === null) {
-        child.kill('SIGKILL')
+        signalProcessTree(child.pid, 'SIGKILL')
       }
     }, 1000)
   }
@@ -295,6 +335,7 @@ async function run() {
       activeToolName = String(data.toolName ?? '')
       activeToolStartedAt = Date.now()
       const target = extractToolTarget(data.toolName, data.args)
+      const shellCommand = data.toolName === 'bash' ? extractShellCommand(data.args) : ''
       if (signature === lastToolSignature) {
         repeatedToolCount += 1
       } else {
@@ -325,6 +366,9 @@ async function run() {
       }
 
       writeLive(`[PI tool:start] ${data.toolName}${suffix}\n`)
+      if (data.toolName === 'bash' && isLargeShellRead(shellCommand)) {
+        writeLive('[PI warning] large bash file read detected; prefer read or a smaller exact window to avoid truncated context.\n')
+      }
     }
 
     if (data.type === 'tool_execution_end') {
@@ -536,10 +580,10 @@ async function run() {
     }
     pending.clear()
 
-    child.kill('SIGTERM')
+    signalProcessTree(child.pid, 'SIGTERM')
     await new Promise((resolve) => {
       const timeout = setTimeout(() => {
-        child.kill('SIGKILL')
+        signalProcessTree(child.pid, 'SIGKILL')
         resolve()
       }, 1000)
 

package/src/pi-supervisor.mjs

@@ -12,8 +12,11 @@ import {
 } from './pi-prompts.mjs'
 import { appendTelemetry, ensureTelemetryFiles } from './pi-telemetry.mjs'
 import {
+  acquireRunLock,
   appendLog,
+  collectLargeFileWarnings,
   commitStagedFiles,
+  createRunId,
   didRepoChange,
   ensureFileExists,
   ensureRepo,
@@ -24,10 +27,12 @@ import {
   readOptionalTextFile,
   readSessionId,
   readState,
+  releaseRunLock,
   runVerification,
   runShellCommand,
   stageFiles,
   unstageFiles,
+  updateRunLock,
   runVisualCapture,
   timestamp,
   writeChangedFiles,
@@ -65,7 +70,7 @@ function printTerminalSummary(config, summary) {
   }
 
   const lines = [
-    `[PI supervisor] iteration=${summary.iteration} phase="${summary.phase}"`,
+    `[PI supervisor] run_id=${summary.runId || config.runId || ''} iteration=${summary.iteration} phase="${summary.phase}"`,
     `[PI supervisor] task=${summary.taskFile || toDisplayPath(config, config.taskFile)} developer_instructions=${summary.developerInstructionsFile || toDisplayPath(config, config.developerInstructionsFile)} tester_instructions=${summary.testerInstructionsFile || toDisplayPath(config, config.testerInstructionsFile)}`,
     `[PI supervisor] transport=${config.transport} developer_model=${summary.developerModel || resolveRoleModelName(config, 'developer') || '(PI default)'} tester_model=${summary.testerModel || resolveRoleModelName(config, 'tester') || '(PI default)'}`,
     `[PI supervisor] developer=${summary.developerStatus} tester=${summary.testerStatus} verification=${summary.verificationStatus}`,
@@ -79,6 +84,10 @@ function printTerminalSummary(config, summary) {
     lines.push(`[PI supervisor] notes=${summary.notes}`)
   }
 
+  if (Array.isArray(summary.largeFileWarnings) && summary.largeFileWarnings.length > 0) {
+    lines.push(`[PI supervisor] large_file_warnings=${formatLargeFileWarningsInline(summary.largeFileWarnings)}`)
+  }
+
   if (summary.terminalReason) {
     lines.push(`[PI supervisor] terminal_reason=${summary.terminalReason}`)
   }
@@ -147,9 +156,13 @@ function formatIterationSummary(summary) {
 
 async function writeIterationSummary(config, summary) {
   await writeTextFile(config.lastIterationSummaryFile, formatIterationSummary(summary))
+  if (config.runLastIterationSummaryFile && config.runLastIterationSummaryFile !== config.lastIterationSummaryFile) {
+    await writeTextFile(config.runLastIterationSummaryFile, formatIterationSummary(summary))
+  }
 }
 
 function createIterationSummary({
+  runId,
   iteration,
   phase,
   task,
@@ -162,12 +175,14 @@ function createIterationSummary({
   gitFinalizeStatus,
   visualStatus,
   terminalReason,
+  largeFileWarnings,
   sessionId,
   developerModel,
   testerModel,
   visualModel,
 }) {
   return {
+    runId,
     iteration,
     phase,
     task,
@@ -180,6 +195,7 @@ function createIterationSummary({
     gitFinalizeStatus,
     visualStatus,
     terminalReason,
+    largeFileWarnings,
     sessionId,
     developerModel,
     testerModel,
@@ -187,10 +203,63 @@ function createIterationSummary({
   }
 }
 
+async function persistStateSnapshot(config, state) {
+  await writeState(config.stateFile, state)
+  if (config.runStateFile && config.runStateFile !== config.stateFile) {
+    await writeState(config.runStateFile, state)
+  }
+}
+
+async function updateRunOwnership(config, fields = {}) {
+  if (!config.activeRunFile || !config.runId) {
+    return
+  }
+
+  await updateRunLock(config.activeRunFile, {
+    runId: config.runId,
+    pid: process.pid,
+    heartbeatAt: timestamp(),
+    ...fields,
+  })
+}
+
 function didInvocationCreateCommit(invocation) {
   return invocation?.beforeSnapshot?.head !== invocation?.afterSnapshot?.head
 }
 
+function mergeLargeFileWarnings(existing, incoming) {
+  const merged = new Map()
+  for (const warning of [...(existing || []), ...(incoming || [])]) {
+    if (!warning?.file) {
+      continue
+    }
+    const key = `${warning.kind}:${warning.file}`
+    const current = merged.get(key)
+    if (!current || Number(warning.lineCount) > Number(current.lineCount)) {
+      merged.set(key, warning)
+    }
+  }
+  return [...merged.values()].sort((left, right) => right.lineCount - left.lineCount)
+}
+
+function findLargeFileWarnings(config, files) {
+  return collectLargeFileWarnings(config.cwd, files, {
+    largeFileWarningLines: config.largeFileWarningLines,
+    largeSpecWarningLines: config.largeSpecWarningLines,
+  })
+}
+
+function formatLargeFileWarningsInline(warnings) {
+  const list = Array.isArray(warnings) ? warnings : []
+  if (list.length === 0) {
+    return ''
+  }
+  return list
+    .slice(0, 3)
+    .map((warning) => `${warning.file}(${warning.lineCount}${warning.kind === 'large_spec' ? ',spec' : ''})`)
+    .join(', ')
+}
+
 function clampPromptLines(text, maxLines) {
   const normalized = String(text ?? '').trim()
   if (normalized === '') {
@@ -232,6 +301,7 @@ function isInfrastructureVerificationFailure(output) {
 async function recordEvent(config, event) {
   await appendTelemetry(config, {
     timestamp: timestamp(),
+    runId: config.runId || '',
     ...event,
   })
 }
@@ -644,6 +714,7 @@ async function runMainTurnWithRetries({ config, iteration, phase, sessionId, ses
     prompt = buildSteeringPrompt(config, reason, {
       visualFeedback: await readLatestVisualFeedback(config),
       testerFeedback: await readLatestTesterFeedback(config),
+      largeFileWarnings: findLargeFileWarnings(config, listChangedFiles(config.cwd)),
     })
 
     if (shouldRetryForTimeout || shouldRetryForNoChange) {
@@ -656,12 +727,14 @@ async function runMainTurnWithRetries({ config, iteration, phase, sessionId, ses
 }
 
 async function runFixTurn({ config, iteration, phase, sessionId, sessionFile, testerOutput }) {
+  const largeFileWarnings = findLargeFileWarnings(config, listChangedFiles(config.cwd))
   const fixPrompt = buildFixPrompt(
     config,
     clampPromptLines(testerOutput, Number(config.maxVerificationExcerptLines) || 40),
     {
       visualFeedback: await readLatestVisualFeedback(config),
       testerFeedback: await readLatestTesterFeedback(config),
+      largeFileWarnings,
     }
   )
   return await runAgentInvocation({
@@ -762,6 +835,7 @@ async function runTesterTurn({
   developerNotes,
   reason,
 }) {
+  const largeFileWarnings = findLargeFileWarnings(config, changedFiles)
   const prompt = buildTesterPrompt(config, {
     phase,
     task,
@@ -770,6 +844,7 @@ async function runTesterTurn({
     reason,
     visualFeedback: await readLatestVisualFeedback(config),
     testerFeedback: await readLatestTesterFeedback(config),
+    largeFileWarnings,
   })
 
   const invocation = await runAgentInvocation({
@@ -835,6 +910,7 @@ async function runTesterCommitTurn({
   developerNotes,
   reason,
 }) {
+  const largeFileWarnings = findLargeFileWarnings(config, changedFiles)
   const prompt = buildCommitPrompt(config, {
     phase,
     task,
@@ -843,6 +919,7 @@ async function runTesterCommitTurn({
     reason,
     visualFeedback: await readLatestVisualFeedback(config),
     testerFeedback: await readLatestTesterFeedback(config),
+    largeFileWarnings,
   })
 
   const invocation = await runAgentInvocation({
@@ -1029,6 +1106,13 @@ async function runIteration({ config, state, iteration }) {
   const iterationStartSnapshot = getRepoSnapshot(config.cwd)
   const taskInfo = findFirstUncheckedTaskInfo(config.taskFile)
   if (!taskInfo.hasUncheckedTasks) {
+    await updateRunOwnership(config, {
+      status: 'idle',
+      iteration,
+      phase: taskInfo.phase || 'complete',
+      task: '',
+      lastCompletedIteration: iteration,
+    })
     await appendLog(config.logFile, 'No unchecked tasks remain in TODOS.md')
     return {
       stateUpdate: {
@@ -1039,9 +1123,12 @@ async function runIteration({ config, state, iteration }) {
         lastPhase: taskInfo.phase,
         lastStatus: 'complete',
         lastVerificationStatus: 'not_needed',
+        runId: config.runId || '',
+        inProgress: null,
         lastRunAt: timestamp(),
       },
       summary: {
+        runId: config.runId || '',
         iteration,
         phase: taskInfo.phase || 'complete',
         task: '',
@@ -1054,6 +1141,7 @@ async function runIteration({ config, state, iteration }) {
         gitFinalizeStatus: 'not_run',
         visualStatus: 'not_run',
         terminalReason: 'all_tasks_complete',
+        largeFileWarnings: [],
         notes: 'No unchecked tasks remain in TODOS.md.',
         sessionId: state.sessionId || '',
         outputPath: config.lastAgentOutputFile,
@@ -1070,6 +1158,26 @@ async function runIteration({ config, state, iteration }) {
 
   const phase = taskInfo.phase || 'unknown'
   const task = taskInfo.task || 'unknown'
+  const inProgressState = {
+    ...state,
+    runId: config.runId || '',
+    inProgress: {
+      runId: config.runId || '',
+      status: 'in_progress',
+      iteration,
+      phase,
+      task,
+      startedAt: timestamp(),
+      transport: config.transport,
+    },
+  }
+  await persistStateSnapshot(config, inProgressState)
+  await updateRunOwnership(config, {
+    status: 'iteration_in_progress',
+    iteration,
+    phase,
+    task,
+  })
   const canResumePriorSession = (
     state.lastTransport === config.transport
     && state.lastPiModel === developerModelName
@@ -1103,6 +1211,7 @@ async function runIteration({ config, state, iteration }) {
   let commitPlanFound = false
   let gitFinalizeStatus = 'not_run'
   let terminalReason = mainInvocation.result.terminalReason || ''
+  let largeFileWarnings = findLargeFileWarnings(config, mainInvocation.changedFiles)
   const noteParts = [`developer: ${mainInvocation.result.notes}`]
 
   if (mainInvocation.result.status === 'success' && config.transport === 'mock') {
@@ -1157,6 +1266,7 @@ async function runIteration({ config, state, iteration }) {
       testerVerdict = testerInvocation.testerVerdict
       commitPlanFound = testerInvocation.commitPlanFound === true
       terminalReason = testerInvocation.result.terminalReason || terminalReason
+      largeFileWarnings = mergeLargeFileWarnings(largeFileWarnings, findLargeFileWarnings(config, listChangedFiles(config.cwd)))
       noteParts.push(`tester: ${testerInvocation.result.notes}`)
       await writeTesterFeedback(config, {
         iteration,
@@ -1184,6 +1294,7 @@ async function runIteration({ config, state, iteration }) {
         testerVerdict = testerCommitInvocation.testerVerdict
         commitPlanFound = testerCommitInvocation.commitPlanFound === true
         terminalReason = testerCommitInvocation.result.terminalReason || terminalReason
+        largeFileWarnings = mergeLargeFileWarnings(largeFileWarnings, findLargeFileWarnings(config, listChangedFiles(config.cwd)))
         noteParts.push(`tester_commit: ${testerCommitInvocation.result.notes}`)
         await writeTesterFeedback(config, {
           iteration,
@@ -1241,6 +1352,7 @@ async function runIteration({ config, state, iteration }) {
       sessionFile = fixInvocation.result.sessionFile || sessionFile
       developerStatus = fixInvocation.result.status
       terminalReason = fixInvocation.result.terminalReason || 'developer_fix_incomplete'
+      largeFileWarnings = mergeLargeFileWarnings(largeFileWarnings, findLargeFileWarnings(config, listChangedFiles(config.cwd)))
       noteParts.push(`developer_fix: ${fixInvocation.result.notes}`)
 
       if (fixInvocation.result.status === 'success') {
@@ -1258,6 +1370,7 @@ async function runIteration({ config, state, iteration }) {
         testerVerdict = testerRecheck.testerVerdict
         commitPlanFound = testerRecheck.commitPlanFound === true
         terminalReason = testerRecheck.result.terminalReason || terminalReason
+        largeFileWarnings = mergeLargeFileWarnings(largeFileWarnings, findLargeFileWarnings(config, listChangedFiles(config.cwd)))
         noteParts.push(`tester_recheck: ${testerRecheck.result.notes}`)
         await writeTesterFeedback(config, {
           iteration,
@@ -1285,6 +1398,7 @@ async function runIteration({ config, state, iteration }) {
           testerVerdict = testerCommitInvocation.testerVerdict
           commitPlanFound = testerCommitInvocation.commitPlanFound === true
           terminalReason = testerCommitInvocation.result.terminalReason || terminalReason
+          largeFileWarnings = mergeLargeFileWarnings(largeFileWarnings, findLargeFileWarnings(config, listChangedFiles(config.cwd)))
           noteParts.push(`tester_commit: ${testerCommitInvocation.result.notes}`)
           await writeTesterFeedback(config, {
             iteration,
@@ -1432,15 +1546,27 @@ async function runIteration({ config, state, iteration }) {
     lastRunAt: timestamp(),
     successfulIterations,
     lastVisualStatus: visualStatus,
+    runId: config.runId || '',
+    inProgress: null,
   }
 
+  await updateRunOwnership(config, {
+    status: 'idle',
+    iteration,
+    phase,
+    task,
+    lastCompletedIteration: iteration,
+    lastStatus: finalStatus,
+  })
+
   await appendLog(
     config.logFile,
-    `Finished iteration ${iteration} with status=${finalStatus} verification=${finalVerificationStatus} tester_verdict=${testerVerdict} commit_plan_found=${commitPlanFound} terminal_reason=${terminalReason}`
+    `Finished iteration ${iteration} with status=${finalStatus} verification=${finalVerificationStatus} tester_verdict=${testerVerdict} commit_plan_found=${commitPlanFound} terminal_reason=${terminalReason}${largeFileWarnings.length > 0 ? ` large_file_warnings=${formatLargeFileWarningsInline(largeFileWarnings)}` : ''}`
   )
 
   const iterationEndSnapshot = getRepoSnapshot(config.cwd)
   const iterationSummary = createIterationSummary({
+    runId: config.runId || '',
     iteration,
     phase,
     task,
@@ -1453,6 +1579,7 @@ async function runIteration({ config, state, iteration }) {
     gitFinalizeStatus,
     visualStatus,
     terminalReason,
+    largeFileWarnings,
     sessionId,
     developerModel: developerModelName,
     testerModel: testerModelName,
@@ -1486,12 +1613,14 @@ async function runIteration({ config, state, iteration }) {
     testerVerdict,
     commitPlanFound,
     terminalReason,
+    riskWarnings: formatLargeFileWarningsInline(largeFileWarnings),
     notes: noteParts.join(' | '),
   })
 
   return {
     stateUpdate: nextState,
     summary: {
+      runId: config.runId || '',
       iteration,
       phase,
       task,
@@ -1504,6 +1633,7 @@ async function runIteration({ config, state, iteration }) {
       gitFinalizeStatus,
       visualStatus,
       terminalReason,
+      largeFileWarnings,
       notes: noteParts.join(' | '),
       sessionId,
       outputPath: config.lastAgentOutputFile,
@@ -1521,40 +1651,95 @@ async function runIteration({ config, state, iteration }) {
 
 async function main() {
   const config = loadConfig(process.argv[2] ?? 'once')
+  const runId = createRunId()
+  const runStartedAt = timestamp()
+  const runDir = path.join(config.piRuntimeDir, 'runs', runId)
+  config.runId = runId
+  config.runStartedAt = runStartedAt
+  config.runRuntimeDir = runDir
+  config.runLogFile = path.join(runDir, 'pi.log')
+  config.runTelemetryJsonl = path.join(runDir, 'pi_telemetry.jsonl')
+  config.runTelemetryCsv = path.join(runDir, 'pi_telemetry.csv')
+  config.runStateFile = path.join(runDir, 'state.json')
+  config.runLastIterationSummaryFile = path.join(runDir, 'last-iteration.json')
+
   ensureRepo(config.cwd)
   await ensureFileExists(config.taskFile, 'task file')
   await ensureFileExists(config.developerInstructionsFile, 'developer instructions file')
   await ensureFileExists(config.testerInstructionsFile, 'tester instructions file')
-  await ensureTelemetryFiles(config)
-  await runStartupPreflight(config)
-
-  let state = await readState(config.stateFile)
-  let completedIterations = 0
-
-  while (!stopRequested) {
-    const iteration = state.iteration + 1
-    const result = await runIteration({ config, state, iteration })
-    await writeIterationSummary(config, result.iterationSummary ?? result.summary)
-    state = result.stateUpdate
-    await writeState(config.stateFile, state)
-    printTerminalSummary(config, result.summary)
-    completedIterations += 1
-
-    if (result.shouldStop || config.mode !== 'run' || completedIterations >= config.maxIterations) {
-      break
+  const lockResult = await acquireRunLock(config.activeRunFile, {
+    runId,
+    pid: process.pid,
+    startedAt: runStartedAt,
+    heartbeatAt: runStartedAt,
+    status: 'starting',
+    iteration: 0,
+    phase: '',
+    task: '',
+    mode: config.mode,
+    configFile: config.configFile,
+    cwd: config.cwd,
+  })
+  try {
+    process.env.PI_RUN_ID = runId
+    process.env.PI_RUN_LOG_FILE = config.runLogFile
+    await ensureTelemetryFiles(config)
+    await appendLog(config.logFile, `Run started pid=${process.pid} mode=${config.mode}`)
+    if (lockResult.staleLock) {
+      await appendLog(
+        config.logFile,
+        `Recovered stale run lock from runId=${String(lockResult.staleLock.runId ?? '')} pid=${String(lockResult.staleLock.pid ?? '')} startedAt=${String(lockResult.staleLock.startedAt ?? '')}`
+      )
     }
+    await runStartupPreflight(config)
 
-    await sleep(config.sleepBetweenSeconds)
-  }
+    let state = await readState(config.stateFile)
+    if (state?.inProgress?.status === 'in_progress') {
+      await appendLog(
+        config.logFile,
+        `Recovering unfinished iteration=${state.inProgress.iteration} phase="${state.inProgress.phase || ''}" task="${state.inProgress.task || ''}" from runId=${String(state.inProgress.runId || state.runId || '')}`
+      )
+    }
+    let completedIterations = 0
+
+    while (!stopRequested) {
+      const iteration = state?.inProgress?.status === 'in_progress'
+        ? Number(state.inProgress.iteration) || (state.iteration + 1)
+        : state.iteration + 1
+      await updateRunOwnership(config, {
+        status: 'starting_iteration',
+        iteration,
+      })
+      const result = await runIteration({ config, state, iteration })
+      await writeIterationSummary(config, result.iterationSummary ?? result.summary)
+      state = result.stateUpdate
+      await persistStateSnapshot(config, state)
+      printTerminalSummary(config, result.summary)
+      completedIterations += 1
+
+      if (result.shouldStop || config.mode !== 'run' || completedIterations >= config.maxIterations) {
+        break
+      }
 
-  if (stopRequested) {
-    await appendLog(config.logFile, 'Stop requested by signal')
+      await sleep(config.sleepBetweenSeconds)
+    }
+
+    if (stopRequested) {
+      await appendLog(config.logFile, 'Stop requested by signal')
+    }
+  } finally {
+    await updateRunOwnership(config, {
+      status: stopRequested ? 'stopped' : 'finished',
+      heartbeatAt: timestamp(),
+    })
+    await releaseRunLock(config.activeRunFile, runId)
+    delete process.env.PI_RUN_ID
+    delete process.env.PI_RUN_LOG_FILE
   }
 }
 
 main().catch(async (error) => {
   const config = loadConfig(process.argv[2] ?? 'once')
-  await ensureTelemetryFiles(config)
   await appendLog(config.logFile, `Supervisor error: ${error instanceof Error ? error.stack ?? error.message : String(error)}`)
   console.error(error instanceof Error ? error.message : String(error))
   process.exitCode = 1

package/src/pi-telemetry.mjs

@@ -1,6 +1,7 @@
 import fs from 'node:fs/promises'
+import path from 'node:path'
 
-const CSV_HEADER = 'timestamp,iteration,phase,kind,status,transport,session_id,timed_out,exit_code,duration_seconds,commit_before,commit_after,repo_changed,changed_files_count,verification_status,retry_count,role,model,tool_calls,tool_errors,message_updates,stop_reason,loop_detected,loop_signature,tester_verdict,commit_plan_found,terminal_reason,notes\n'
+const CSV_HEADER = 'timestamp,run_id,iteration,phase,kind,status,transport,session_id,timed_out,exit_code,duration_seconds,commit_before,commit_after,repo_changed,changed_files_count,verification_status,retry_count,role,model,tool_calls,tool_errors,message_updates,stop_reason,loop_detected,loop_signature,tester_verdict,commit_plan_found,terminal_reason,risk_warnings,notes\n'
 
 function csvEscape(value) {
   const text = String(value ?? '')
@@ -14,22 +15,42 @@ export async function ensureTelemetryFiles(config) {
   await fs.writeFile(config.lastPromptFile, '', 'utf8')
   await fs.writeFile(config.lastIterationSummaryFile, '', 'utf8')
 
+  await fs.mkdir(path.dirname(config.logFile), { recursive: true })
+  await fs.mkdir(path.dirname(config.telemetryJsonl), { recursive: true })
+  await fs.mkdir(path.dirname(config.telemetryCsv), { recursive: true })
   await fs.appendFile(config.logFile, '', 'utf8')
   await fs.appendFile(config.telemetryJsonl, '', 'utf8')
+  if (config.runTelemetryJsonl && config.runTelemetryJsonl !== config.telemetryJsonl) {
+    await fs.mkdir(path.dirname(config.runTelemetryJsonl), { recursive: true })
+    await fs.appendFile(config.runTelemetryJsonl, '', 'utf8')
+  }
 
   try {
     await fs.access(config.telemetryCsv)
   } catch {
     await fs.writeFile(config.telemetryCsv, CSV_HEADER, 'utf8')
   }
+
+  if (config.runTelemetryCsv && config.runTelemetryCsv !== config.telemetryCsv) {
+    try {
+      await fs.access(config.runTelemetryCsv)
+    } catch {
+      await fs.mkdir(path.dirname(config.runTelemetryCsv), { recursive: true })
+      await fs.writeFile(config.runTelemetryCsv, CSV_HEADER, 'utf8')
+    }
+  }
 }
 
 export async function appendTelemetry(config, event) {
   const jsonLine = `${JSON.stringify(event)}\n`
   await fs.appendFile(config.telemetryJsonl, jsonLine, 'utf8')
+  if (config.runTelemetryJsonl && config.runTelemetryJsonl !== config.telemetryJsonl) {
+    await fs.appendFile(config.runTelemetryJsonl, jsonLine, 'utf8')
+  }
 
   const csvRow = [
     event.timestamp,
+    event.runId,
     event.iteration,
     event.phase,
     event.kind,
@@ -56,10 +77,14 @@ export async function appendTelemetry(config, event) {
     event.testerVerdict,
     event.commitPlanFound,
     event.terminalReason,
+    event.riskWarnings,
     event.notes,
   ].map(csvEscape).join(',')
 
   await fs.appendFile(config.telemetryCsv, `${csvRow}\n`, 'utf8')
+  if (config.runTelemetryCsv && config.runTelemetryCsv !== config.telemetryCsv) {
+    await fs.appendFile(config.runTelemetryCsv, `${csvRow}\n`, 'utf8')
+  }
 }
 
 export async function readTelemetry(config) {

package/templates/DEVELOPER.md

@@ -20,6 +20,9 @@ Rules:
 - Use the configured smoke verification path as the fast inner-loop gate. Do not replace it with a long full-flow Playwright spec unless the task explicitly requires it.
 - If a long Playwright happy-path spec changes, validate with smoke plus one narrow targeted spec or deterministic state hook, not the entire full-flow run.
 - Reserve long full-flow Playwright specs for an explicit nightly or post-run lane, not the developer turn.
+- Use `read` for source inspection. Use shell only for `git`, tests, and narrow diagnostics.
+- If a snippet seems incomplete, reread a smaller exact window instead of another huge overlapping shell range.
+- Do not build edits from large `sed`/`grep` output or from memory after partial shell reads.
 - Trust tool output over your own guesses.
 - Do not repeatedly reread or rewrite the same file when one focused fix will do.
 - After one failed edit attempt, reread the file before retrying.