tspl-cli 0.0.0-stage → 0.1.1

package/src/task/planning-context.js

@@ -0,0 +1,165 @@
+'use strict'
+
+const Fs = require('fs')
+const Os = require('os')
+const Path = require('path')
+const { spawnSync } = require('child_process')
+const { hashValue, approachBasis, TEST_FILE } = require('../shared')
+const { buildBrief } = require('./brief')
+
+const MAX_CONTEXT_CHARS = 6000
+const MAX_EXCERPT_CHARS = 3500
+const MAX_CHARS = MAX_CONTEXT_CHARS + MAX_EXCERPT_CHARS + 600
+const clip = (value, max = 160) => {
+  const text = String(value || '').replace(/\s+/g, ' ')
+  return text.length > max ? `${text.slice(0, max - 1)}…` : text
+}
+const compactBrief = brief => {
+  const reasons = (brief.confidence.reasons || []).join('; ')
+  const lines = [`CODE MAP: confidence ${brief.confidence.level}${reasons ? ` (${clip(reasons, 240)})` : ''}. Ranked by local search of indexed base commits; a starting point, not proof.`]
+  let omitted = false
+  const add = line => {
+    if (lines.join('\n').length + line.length + 1 > MAX_CONTEXT_CHARS - 100) { omitted = true; return }
+    lines.push(line)
+  }
+  for (const [repo, basis] of Object.entries(brief.basis || {})) add(`Commit: ${repo}@${basis.commit} (${basis.branch})`)
+  add('Relevant files (ranked):')
+  for (const file of brief.files.slice(0, 8)) {
+    const symbols = file.symbols.slice(0, 3).map(symbol => `${clip(symbol.name, 64)}${symbol.line ? `@${symbol.line}` : ''}`).join(', ')
+    add(`${file.repo}/${file.path}${symbols ? ` — ${symbols}` : ''}${file.why.length ? `; ${clip(file.why[0])}` : ''}`)
+  }
+  if (!brief.files.length) add('No matching files; use the targeted search hints below.')
+  for (const chain of brief.chains.slice(0, 4)) add(`Chain: ${clip(chain.map(step => `${step.repo}/${step.path}${step.detail ? ` (${step.detail})` : ''}`).join(' → '), 300)}`)
+  for (const step of (brief.searchSteps || []).slice(0, 4)) add(`Search hint: ${clip(step.pattern, 200)}`)
+  for (const place of brief.placement.slice(0, 3)) add(`New files: ${place.repo}/${place.pattern}`)
+  for (const rule of (brief.conventions || []).slice(0, 3)) add(`Convention: ${clip(rule, 200)}`)
+  if (brief.files.length > 8 || omitted) lines.push('More context omitted to keep the brief bounded; ask for targeted details when needed.')
+  return lines.join('\n')
+}
+
+const showFile = (dir, commit, file) => {
+  const result = spawnSync('git', ['-C', dir, 'show', `${commit}:${file}`], { encoding: 'utf8', maxBuffer: 4 * 1024 * 1024 })
+  return result.status === 0 ? result.stdout : null
+}
+const escape = text => text.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+const MAX_EXCERPT_LINES = 60
+/** Names worth showing: the search's own hits ("method: getBrowserInfo") first, then the file's listed symbols (definitions only). */
+const namesOf = file => {
+  const hits = file.why.flatMap(why => [...String(why).matchAll(/\b(?:method|function|class|mentions|calls|uses):\s*([A-Za-z_$][\w$]*)/g)].map(match => match[1]))
+  const seen = new Set()
+  return [...hits.map(name => ({ name, mention: true })), ...file.symbols.map(symbol => ({ name: symbol.name, mention: false }))]
+    .filter(item => /^[A-Za-z_$][\w$]{2,}$/.test(item.name) && !seen.has(item.name) && seen.add(item.name))
+}
+/** One definition (to its closing brace), else, when allowed, a few lines around the first mention. */
+const excerptOf = (lines, name, mention) => {
+  const definition = new RegExp(`^\\s*(?:export\\s+)?(?:default\\s+)?(?:(?:public|private|protected|static|async|readonly|override|function|const|let|var|def|class)\\s+)*${escape(name)}\\s*(?:[(<=:]|\\bextends\\b|\\{|$)`)
+  let start = lines.findIndex(line => definition.test(line))
+  let end
+  if (start !== -1) {
+    let depth = 0, opened = false
+    for (end = start; end < lines.length && end <= start + MAX_EXCERPT_LINES; end++) {
+      for (const char of lines[end]) {
+        if (char === '{') { depth++; opened = true } else if (char === '}') depth--
+      }
+      if (opened && depth <= 0) break
+      // No brace in the first lines (Python, one-line arrows): show a fixed window instead.
+      if (!opened && end >= start + 2) { end = Math.min(lines.length - 1, start + 11); break }
+    }
+  } else {
+    if (!mention) return null
+    const pattern = new RegExp(`\\b${escape(name)}\\b`)
+    const at = lines.findIndex(line => pattern.test(line))
+    if (at === -1) return null
+    start = Math.max(0, at - 2); end = Math.min(lines.length - 1, at + 3)
+  }
+  if (end - start >= MAX_EXCERPT_LINES) return null // a whole class is a file dump, not an excerpt
+  return { start, end: Math.min(end, lines.length - 1) }
+}
+/** Source of the matched symbols at the indexed commit, so the planner does not have to search for them. */
+const codeExcerpts = (loaded, brief, paths) => {
+  const repos = Object.values(loaded.index.repos)
+  const parts = []
+  const notes = []
+  let used = 0
+  for (const file of brief.files.slice(0, 3)) {
+    const repo = repos.find(item => item.name === file.repo)
+    const dir = paths.get(file.repo)
+    if (!repo || !dir || !repo.commitSha) continue
+    const indexed = showFile(dir, repo.commitSha, file.path)
+    let text = null
+    try { text = Fs.readFileSync(Path.join(dir, file.path), 'utf8') } catch (err) { text = null }
+    if (text === null) {
+      if (indexed !== null) notes.push(`${file.repo}/${file.path} is deleted in the working tree.`)
+      continue
+    }
+    if (indexed !== null && indexed !== text) notes.push(`${file.repo}/${file.path} has changed since the indexed commit; the code below is the current working tree.`)
+    const lines = text.split('\n')
+    const ranges = []
+    for (const { name, mention } of namesOf(file)) {
+      const range = excerptOf(lines, name, mention)
+      if (range && !ranges.some(other => range.start <= other.end && other.start <= range.end)) ranges.push(range)
+      if (ranges.length >= 2) break
+    }
+    for (const range of ranges.sort((a, b) => a.start - b.start)) {
+      const body = lines.slice(range.start, range.end + 1).map((line, i) => `${String(range.start + i + 1).padStart(4)}  ${line.replace(/\s+$/, '')}`).join('\n')
+      const part = `--- ${file.repo}/${file.path} lines ${range.start + 1}-${range.end + 1}\n${body}`
+      if (used + part.length > MAX_EXCERPT_CHARS) continue
+      parts.push(part)
+      used += part.length
+    }
+  }
+  return [...notes, ...(parts.length ? [`CODE (current working tree):\n${parts.join('\n')}`] : [])].join('\n')
+}
+/** Whether tests exist and how they run; without this the planner globs the repo for spec files. */
+const testSetup = (loaded, brief, paths) =>
+  Object.values(loaded.index.repos).filter(repo => brief.basis && brief.basis[repo.name]).map(repo => {
+    const tests = (repo.files || []).map(file => file.path).filter(path => TEST_FILE.test(path) && !/\.json$/.test(path))
+    let script = null
+    const dir = paths.get(repo.name)
+    if (dir && repo.commitSha) {
+      try { script = (JSON.parse(showFile(dir, repo.commitSha, 'package.json') || '{}').scripts || {}).test || null } catch (err) { script = null }
+    }
+    return `Tests in ${repo.name}: ${tests.length ? `${tests.length} test files, e.g. ${tests.slice(0, 3).join(', ')}` : 'none found (no spec/test files)'}${script ? `; npm test runs: ${clip(script, 120)}` : ''}`
+  }).join('\n')
+
+/** Uncommitted work changes the excerpts, so it is part of the cache key. */
+const worktreeState = paths =>
+  [...paths].sort(([a], [b]) => a.localeCompare(b)).map(([name, dir]) => {
+    const git = args => {
+      const result = spawnSync('git', ['-C', dir, ...args], { encoding: 'utf8', maxBuffer: 16 * 1024 * 1024 })
+      return result.status === 0 ? result.stdout : ''
+    }
+    return [name, hashValue([git(['rev-parse', 'HEAD']), git(['status', '--porcelain']), git(['diff', 'HEAD'])])]
+  })
+
+/**
+ * Local derived metadata only, keyed by requirements, keywords, feedback, indexed commits and the working tree.
+ * Returns the prompt text and the ranked files ("repo/path"), so a plan can be checked against what was found.
+ */
+const planningBrief = (loaded, task, { paths = null } = {}) => {
+  const identity = hashValue({ project: String(loaded.project._id), task: task.key || task.id })
+  const basis = hashValue({
+    format: 3, requirements: approachBasis(task.card), keywords: task.keywords || task.brief?.keywords || [],
+    commits: Object.entries(loaded.index.repos).map(([id, repo]) => [id, repo.name, repo.branch, repo.commitSha]).sort(),
+    feedback: (loaded.graph.files || []).filter(file => file.history?.length).map(file => [file.repo, file.path, file.history]),
+    code: paths ? worktreeState(paths) : null,
+  })
+  const dir = Path.join(process.env.TSPL_HOME || Path.join(Os.homedir(), '.tspl'), 'planning-context')
+  const file = Path.join(dir, `${identity}.json`)
+  try {
+    const cached = JSON.parse(Fs.readFileSync(file, 'utf8'))
+    if (cached.basis === basis && typeof cached.text === 'string' && cached.text.length <= MAX_CHARS && Array.isArray(cached.files)) return { text: cached.text, files: cached.files }
+  } catch (err) {
+    if (err.code !== 'ENOENT' && !(err instanceof SyntaxError)) throw err
+  }
+  const { brief } = buildBrief(loaded, { ...task, id: task.id || task.key }, { keywords: task.keywords || task.brief?.keywords || [] })
+  const files = brief.files.map(item => `${item.repo}/${item.path}`)
+  const text = [compactBrief(brief), ...(paths ? [testSetup(loaded, brief, paths), codeExcerpts(loaded, brief, paths)] : [])].filter(Boolean).join('\n')
+  Fs.mkdirSync(dir, { recursive: true, mode: 0o700 })
+  // A partial/interleaved cache write is disposable and rebuilt on the next read.
+  Fs.writeFileSync(file, JSON.stringify({ basis, text, files }), { mode: 0o600 })
+  Fs.chmodSync(file, 0o600)
+  return { text, files }
+}
+const planningContext = (loaded, task, options) => planningBrief(loaded, task, options).text
+module.exports = { planningContext, planningBrief, compactBrief, MAX_CONTEXT_CHARS }

package/src/task/refine.js

@@ -0,0 +1,73 @@
+'use strict'
+
+const { readEngines } = require('../config-store')
+const { ENGINES, detectAll, defaultAssignments, run } = require('../engines')
+const { renderFiles } = require('./brief')
+
+const list = value => (Array.isArray(value) ? value.map(item => String(item || '').trim()).filter(Boolean) : [])
+
+const engineFor = step => {
+  const saved = readEngines()
+  const assignments = saved.assignments || defaultAssignments(detectAll())
+  const name = assignments[step]
+  if (!name) throw new Error('No AI engine is set up on this computer. Run: tspl engines')
+  return { name, model: (saved.models || {})[step] || null }
+}
+
+const refinePrompt = (task, brief) =>
+  [
+    'You help prepare a software task before any code is planned. Answer from the text below only; do not open files or run tools.',
+    '',
+    'TASK',
+    task.summary,
+    '',
+    `FILES tspl FOUND without AI (confidence ${brief.confidence.level.toUpperCase()}: ${brief.confidence.reasons.join('; ')})`,
+    ...renderFiles(brief.files.slice(0, 8)),
+    brief.unknown && brief.unknown.length ? `Words of the task that never appear in the code: ${brief.unknown.join(', ')}` : null,
+    '',
+    'Reply with JSON only, no other text:',
+    '{"keywords": ["5-15 names or words the code probably uses for this task: functions, fields, labels, API paths, other words for the user\'s words"],',
+    ' "doneWhen": ["2-4 short testable checks, only if the task lists none"],',
+    ' "questions": ["up to 3 questions for the user, only if something important is unclear"],',
+    ' "note": "one sentence on where the change most likely lives and why"}',
+  ]
+    .filter(line => line !== null)
+    .join('\n')
+
+const parseRefinement = text => {
+  const match = String(text || '').match(/\{[\s\S]*\}/)
+  if (!match) return null
+  try {
+    const data = JSON.parse(match[0])
+    return {
+      keywords: list(data.keywords).slice(0, 20),
+      doneWhen: list(data.doneWhen).slice(0, 6),
+      questions: list(data.questions).slice(0, 3),
+      note: typeof data.note === 'string' ? data.note.trim() : '',
+    }
+  } catch (err) {
+    return null
+  }
+}
+
+const refineTask = async (task, brief, { cwd } = {}) => {
+  const { name, model } = engineFor('plan')
+  const result = await run(name, refinePrompt(task, brief), { model, cwd, noTools: true, timeoutMs: 180000 })
+  if (!result.ok) {
+    throw new Error(
+      result.limitHit
+        ? `${ENGINES[name].label} has reached its usage limit. Try later, or another engine: tspl engines set plan <engine>`
+        : `${ENGINES[name].label} failed: ${result.error}`,
+    )
+  }
+  const parsed = parseRefinement(result.text)
+  if (!parsed) throw new Error(`${ENGINES[name].label} did not answer with the expected JSON`)
+  return { ...parsed, engine: name, model, usage: result.usage || null, ms: result.ms, at: new Date().toISOString() }
+}
+
+module.exports = {
+  engineFor,
+  refinePrompt,
+  parseRefinement,
+  refineTask,
+}

package/src/workflow/agents.js

@@ -0,0 +1,336 @@
+'use strict'
+
+const Crypto = require('crypto')
+const { spawnSync } = require('child_process')
+const { TEST_FILE, validateApproachProposal, bindApproach } = require('../shared')
+
+const { agentCapabilities, agentCommand, parseOutput, firstError, AUTH_PATTERN } = require('../engines')
+const { runProcess } = require('./process')
+
+const LIMIT_PATTERN = /usage limit|rate limit|limit reached|limit exceeded|quota|too many requests|\b429\b/i
+
+class AgentError extends Error {
+  /** code: unsupported, auth, limit, timeout, cancelled, invalid-output, stale, modified-worktree, failed */
+  constructor(code, message) {
+    super(message)
+    this.code = code
+  }
+}
+
+const newSessionId = () => Crypto.randomUUID()
+
+/** Runs one provider invocation with the shared process lifecycle (timeout, cancellation, bounded output). */
+const runAgent = async (engine, role, { prompt, model, dirs, sessionId, schema, timeoutMs, signal }) => {
+  const [command, args] = agentCommand(engine, role, { prompt, model, dirs, sessionId, schema })
+  const result = await runProcess(command, args, { cwd: dirs[0], timeoutMs, signal, maxOutputBytes: 1024 * 1024 })
+  const parsed = parseOutput(engine, result.stdout)
+  const message = `${parsed.text}\n${result.stderr}`
+  const problem = result.exitCode !== 0 || parsed.failed || result.error
+  return {
+    ok: !problem && !result.timedOut && !result.cancelled,
+    text: parsed.text,
+    usage: parsed.usage,
+    sessionId: parsed.sessionId || sessionId,
+    timedOut: result.timedOut,
+    cancelled: result.cancelled,
+    limitHit: Boolean(problem) && LIMIT_PATTERN.test(message),
+    authFailed: Boolean(problem) && AUTH_PATTERN.test(message),
+    error: problem ? result.error || firstError(result.stderr) || firstError(parsed.text) || `exited with code ${result.exitCode}` : null,
+  }
+}
+
+const checkCapability = (engine, role) => {
+  let capability
+  try {
+    capability = agentCapabilities(engine)
+  } catch (err) {
+    throw new AgentError('unsupported', err.message)
+  }
+  if (!capability[role]) throw new AgentError('unsupported', `${engine} cannot do the "${role}" step on its own; choose another engine with: tspl engines set`)
+  return capability
+}
+
+/** Calls the agent and turns provider failures into blockers; success is only returned for a clean, finished run. */
+const invoke = async (engine, role, options, deps) => {
+  const agent = (deps && deps.agent) || runAgent
+  const result = await agent(engine, role, options)
+  if (result.cancelled) throw new AgentError('cancelled', `The ${role} run was cancelled`)
+  if (result.timedOut) throw new AgentError('timeout', `The ${role} run ran out of time`)
+  if (!result.ok) {
+    if (result.limitHit) throw new AgentError('limit', `${engine}'s usage limit is reached; resume later`)
+    if (result.authFailed) throw new AgentError('auth', `${engine} is not logged in or has no access: ${result.error}`)
+    throw new AgentError('failed', `${engine} failed: ${result.error}`)
+  }
+  return result
+}
+
+/** Pulls the first balanced JSON object out of a reply, tolerating prose and code fences around it. */
+const extractJson = text => {
+  const source = String(text || '')
+  for (let start = source.indexOf('{'); start !== -1; start = source.indexOf('{', start + 1)) {
+    let depth = 0
+    let inString = false
+    for (let i = start; i < source.length; i++) {
+      const char = source[i]
+      if (inString) {
+        if (char === '\\') i++
+        else if (char === '"') inString = false
+      } else if (char === '"') inString = true
+      else if (char === '{') depth++
+      else if (char === '}' && --depth === 0) {
+        try {
+          return JSON.parse(source.slice(start, i + 1))
+        } catch (err) {
+          break
+        }
+      }
+    }
+  }
+  return null
+}
+
+const FILE_ITEM = { type: 'object', properties: { file: { type: 'string' }, why: { type: 'string' } }, required: ['file', 'why'] }
+
+const PLAN_SCHEMA = {
+  type: 'object',
+  properties: {
+    edit: { type: 'array', items: FILE_ITEM },
+    create: { type: 'array', items: FILE_ITEM },
+    remove: { type: 'array', items: FILE_ITEM },
+    screens: { type: 'array', items: { type: 'string' } },
+    tests: {
+      type: 'array',
+      items: {
+        type: 'object',
+        properties: { name: { type: 'string' }, file: { type: 'string' }, checks: { type: 'array', items: { type: 'number' } }, command: { type: 'string' } },
+        required: ['name'],
+      },
+    },
+    notes: { type: 'string' },
+    testCases: {
+      type: 'array',
+      items: {
+        type: 'object',
+        properties: { title: { type: 'string' }, steps: { type: 'array', items: { type: 'string' } }, expected: { type: 'string' } },
+        required: ['title'],
+      },
+    },
+  },
+  required: ['edit', 'create', 'remove', 'tests'],
+}
+
+const IMPLEMENT_SCHEMA = {
+  type: 'object',
+  properties: { summary: { type: 'string' }, notes: { type: 'string' } },
+  required: ['summary'],
+}
+
+const isList = value => Array.isArray(value)
+
+const validatePlan = value => {
+  if (!value || typeof value !== 'object') throw new AgentError('invalid-output', 'The plan was not a JSON object')
+  ;['edit', 'create', 'remove', 'tests'].forEach(field => {
+    if (!isList(value[field])) throw new AgentError('invalid-output', `The plan has no "${field}" list`)
+  })
+  ;['edit', 'create', 'remove'].forEach(field => {
+    value[field].forEach(item => {
+      if (!item || typeof item.file !== 'string' || !item.file.trim()) throw new AgentError('invalid-output', `A "${field}" entry has no file`)
+    })
+  })
+  value.tests.forEach(test => {
+    if (!test || typeof test.name !== 'string' || !test.name.trim()) throw new AgentError('invalid-output', 'A test entry has no name')
+  })
+  return value
+}
+
+const list = items => items.map(item => `  ${item}`).join('\n')
+
+/** The task's test cases as the AI should see them: TC<n> is done-when item n, with its steps and expected result. */
+const testCaseLines = card =>
+  ((card && card.doneWhen) || []).flatMap((text, i) => {
+    const testCase = ((card && card.testCases) || [])[i] || {}
+    return [
+      `  TC${i + 1}: ${text}`,
+      ...(testCase.steps || []).map((step, n) => `      step ${n + 1}: ${step}`),
+      ...(testCase.expected && testCase.expected !== text ? [`      expected: ${testCase.expected}`] : []),
+    ]
+  })
+
+const TEST_NAMING = [
+  'Name every test after the test case it proves, starting with its id, for example test(\'TC2: a blank email shows an error\'). tspl reports each test case from these names.',
+  'For a screen, write a browser test (Playwright) when the project has one, and save a screenshot after each step:',
+  '  await page.screenshot({ path: test.info().outputPath(\'step-1.png\') })',
+].join('\n')
+
+const CONTEXT_READING_RULES = 'The code map comes from a local search and can be wrong or incomplete. Start from it: first check that the listed code (the excerpts usually show it) really is where the task\'s behaviour lives. If it is, read only what you still need around it, without searching the whole repository. If it is not, if confidence is LOW, or if task words were not found, search for the task\'s key names and terms before planning, then read at most eight relevant files. Never plan an edit to code you have not seen. Avoid whole-file dumps where a symbol or line range answers the question.'
+/** Brief paths are "<repo>/<path>"; without this mapping the model guesses the folder and its first reads fail. */
+const repoFolders = paths =>
+  paths && paths.size ? `REPO FOLDERS: a file reference "<repo>/<path>" is <path> inside that repo's folder:\n${[...paths].map(([name, dir]) => `  ${name} = ${dir}`).join('\n')}` : ''
+const TOP_LEVEL_JSON = 'Put these fields at the top level of the reply object; do not wrap them in another key or a string.'
+const codeNoteLines = notes =>
+  notes && notes.length
+    ? ['CODE ALREADY READ IN THE APPROACH STEP (trust these; read code only for facts missing here)', ...notes.map(item => `  ${item.file}${item.lines ? `:${item.lines}` : ''} — ${item.note}`)].join('\n')
+    : ''
+const selectedApproachContext = task => {
+  const selected = bindApproach(task.approaches, task.card, { version: task.approaches.version, optionId: task.approaches.selection && task.approaches.selection.optionId })
+  return { version: selected.version, optionId: selected.optionId, title: selected.option.title, summary: selected.option.summary, benefits: selected.option.benefits, drawbacks: selected.option.drawbacks, files: selected.option.files }
+}
+
+const testCaseSection = card =>
+  (card && card.doneWhen && card.doneWhen.length)
+    ? ['TEST CASES (each must be proven by a test, or by a person when it cannot be automated)', ...testCaseLines(card)]
+    : ['TEST CASES: none yet. Propose 2-6 in "testCases" (title, steps, expected); they become TC1..TCn and each test\'s "checks" lists the numbers it proves.']
+const PLAN_REPLY = '{ "edit": [{"file": "repo/path", "why": "..."}], "create": [...], "remove": [...], "screens": [], "tests": [{"name": "TC1: ...", "file": "repo/path", "checks": [test case numbers], "command": "command that runs it from the repo folder"}], "testCases": [{"title": "...", "steps": ["..."], "expected": "..."}], "notes": "" }'
+const PLAN_FILES_RULE = 'List every file the change touches, including new test files under "create".'
+
+const planPrompt = ({ task, instructions, brief, paths }) =>
+  [
+    'You are planning a software change. Read the code with your read-only tools; do not change anything.',
+    repoFolders(paths),
+    '',
+    `TASK ${task.id || task.key}: ${JSON.stringify(task.card || {})}`,
+    ...testCaseSection(task.card),
+    brief ? `\nFILES FOUND BY tspl\n${brief}\n${CONTEXT_READING_RULES}` : '',
+    instructions ? `\nPROJECT RULES\n${instructions}` : '',
+    task.approaches ? `SELECTED APPROACH\n${JSON.stringify(selectedApproachContext(task))}\nCreate the plan using this selected approach; explain its application in notes.` : '',
+    task.approaches ? codeNoteLines(task.approaches.codeNotes) : '',
+    '',
+    `Reply with JSON only: ${PLAN_REPLY}. ${PLAN_FILES_RULE}`,
+    TOP_LEVEL_JSON,
+  ].join('\n')
+
+const planFiles = plan =>
+  new Set(['edit', 'create', 'remove'].flatMap(kind => ((plan && plan[kind]) || []).map(item => (typeof item === 'string' ? item : item.file))))
+
+const gitOut = (dir, args) => {
+  const result = spawnSync('git', ['-C', dir, ...args], { encoding: 'utf8' })
+  return result.status === 0 ? result.stdout : ''
+}
+
+/** Everything changed since `before` in the repo: new commits and uncommitted files. Independent of what the AI says. */
+const changedSince = (dir, before) => {
+  const files = new Set()
+  if (before) gitOut(dir, ['diff', '--name-only', `${before}..HEAD`]).split('\n').filter(Boolean).forEach(file => files.add(file))
+  gitOut(dir, ['status', '--porcelain', '--untracked-files=all'])
+    .split('\n')
+    .filter(Boolean)
+    .forEach(line => files.add(line.slice(3).replace(/^"|"$/g, '').split(' -> ').pop()))
+  return [...files].sort()
+}
+
+const implementPrompt = ({ task, instructions, findings, branch }) =>
+  [
+    `You are implementing task ${task.id || task.key} on branch ${branch || 'the current branch'}. Change only the files in the approved plan (and tests); anything else is refused.`,
+    `Stay on ${branch ? `branch ${branch}` : 'the current branch'} in every repo: do not create, switch, rename, delete or reset branches, and do not run git checkout, switch, reset, rebase, merge, stash, commit or push. Work that ends on another branch is refused.`,
+    '',
+    'APPROVED PLAN',
+    list(['edit', 'create', 'remove'].flatMap(kind => ((task.plan && task.plan[kind]) || []).map(item => `${kind}: ${item.file}${item.why ? ` - ${item.why}` : ''}`))),
+    '',
+    'TEST CASES',
+    ...testCaseLines(task.card),
+    TEST_NAMING,
+    instructions ? `\nPROJECT RULES\n${instructions}` : '',
+    findings && findings.length
+      ? `\nFIX THESE FINDINGS FIRST (from the last test run or review):\n${list(findings.map(finding => (typeof finding === 'string' ? finding : `${finding.file ? `${finding.file}${finding.line ? `:${finding.line}` : ''} ` : ''}${finding.message}`)))}`
+      : '',
+    '',
+    'Run the relevant tests yourself while you work. Do not commit; tspl commits and checks your work. When finished reply with JSON only: {"summary": "what you changed"}.',
+  ].join('\n')
+
+const APPROACH_SCHEMA = {
+  type: 'object', properties: {
+    options: { type: 'array', minItems: 2, maxItems: 3, items: { type: 'object', properties: {
+      id: { type: 'string' }, title: { type: 'string' }, summary: { type: 'string' },
+      benefits: { type: 'array', items: { type: 'string' } }, drawbacks: { type: 'array', items: { type: 'string' } }, files: { type: 'array', items: { type: 'string' } },
+    // files is optional (the validator defaults it): a schema miss makes the provider regenerate the whole reply.
+    }, required: ['id', 'title', 'summary', 'benefits', 'drawbacks'] } },
+    recommendedId: { type: 'string' }, reason: { type: 'string' },
+    codeNotes: { type: 'array', maxItems: 12, items: { type: 'object', properties: { file: { type: 'string' }, lines: { type: 'string' }, note: { type: 'string' } }, required: ['file', 'note'] } },
+  }, required: ['options', 'recommendedId', 'reason'],
+}
+const APPROACH_WITH_PLAN_SCHEMA = { ...APPROACH_SCHEMA, properties: { ...APPROACH_SCHEMA.properties, plan: PLAN_SCHEMA }, required: [...APPROACH_SCHEMA.required, 'plan'] }
+/**
+ * Offers approaches for the user to choose from. With withPlan, the same run also drafts the plan for its recommended
+ * option (returned as draftPlan, never shown before the choice), so choosing the recommendation needs no second run.
+ */
+const proposeTaskApproaches = async (context, deps = {}) => {
+  checkCapability(context.engine, 'plan')
+  const withPlan = Boolean(context.withPlan)
+  const prompt = [
+    'Read relevant code with read-only tools; do not edit. Compare two or three meaningful implementation approaches before planning.',
+    repoFolders(context.paths),
+    `TASK ${JSON.stringify(context.task.card)}`,
+    ...(withPlan ? testCaseSection(context.task.card) : []),
+    context.brief ? `FILES FOUND\n${context.brief}\n${CONTEXT_READING_RULES}` : '',
+    context.instructions ? `PROJECT RULES\n${context.instructions}` : '',
+    'Reply with JSON only: {"options":[{"id":"stable-id","title":"Name","summary":"What changes","benefits":["Benefit"],"drawbacks":["Trade-off"],"files":["repo/path"]}],"recommendedId":"one offered ID","reason":"Why it fits this task"}. Offer a third option only when it is genuinely distinct. Keep each summary at most 60 words, with at most two benefits and two drawbacks, each a short phrase. The user chooses the option; do not select one.',
+    'Also return "codeNotes": [{"file":"repo/path","lines":"120-140","note":"what is there"}]: at most 6, one short sentence each, recording only the facts a later planning step would need (functions to change, their current behaviour, test setup and test command or that none exists) so it does not search again.',
+    withPlan ? `Also return "plan": the implementation plan for your recommended option only, shaped ${PLAN_REPLY}. ${PLAN_FILES_RULE} Keep "notes" under 150 words. It stays hidden until the user chooses and is used only if they choose that option.` : '',
+    TOP_LEVEL_JSON,
+  ].join('\n')
+  const result = await invoke(context.engine, 'plan', { prompt, model: context.model, dirs: [...context.paths.values()], sessionId: newSessionId(), schema: withPlan ? APPROACH_WITH_PLAN_SCHEMA : APPROACH_SCHEMA, timeoutMs: context.timeoutMs, signal: context.signal }, deps)
+  const reply = extractJson(result.text)
+  let proposal
+  try { proposal = validateApproachProposal(reply) } catch (err) { throw new AgentError('invalid-output', err.message) }
+  if (!withPlan) return proposal
+  // A bad draft only costs the separate planning run it would have saved.
+  let draftPlan = null
+  try { draftPlan = validatePlan(reply.plan) } catch (err) { draftPlan = null }
+  return { ...proposal, draftPlan }
+}
+
+/** Plans a task headlessly with a read-only engine. Returns a schema-valid plan. */
+const planTask = async (context, deps = {}) => {
+  checkCapability(context.engine, 'plan')
+  let approach
+  try { approach = bindApproach(context.task.approaches, context.task.card, { version: context.task.approaches && context.task.approaches.version, optionId: context.task.approaches && context.task.approaches.selection && context.task.approaches.selection.optionId }) } catch (err) { throw new AgentError('stale', err.message) }
+  const binding = { version: approach.version, optionId: approach.optionId }
+  if (context.draft && context.draft.optionId === approach.optionId) {
+    try { return { ...validatePlan(structuredClone(context.draft.plan)), approach: binding } } catch (err) { /* plan it afresh below */ }
+  }
+  const dirs = [...context.paths.values()]
+  const result = await invoke(context.engine, 'plan', { prompt: planPrompt(context), model: context.model, dirs, sessionId: newSessionId(), schema: PLAN_SCHEMA, timeoutMs: context.timeoutMs, signal: context.signal }, deps)
+  const plan = extractJson(result.text)
+  if (!plan) throw new AgentError('invalid-output', 'The plan reply had no JSON')
+  return { ...validatePlan(plan), approach: binding }
+}
+
+/**
+ * Lets the coding engine edit the repos. What changed is read from Git afterwards, never from the engine's own report.
+ * Returns { summary, sessionId, usage, changes: [{ repo, files }], outOfPlan: [files] }.
+ */
+const implementTask = async (context, deps = {}) => {
+  checkCapability(context.engine, 'edit')
+  const before = new Map(context.heads.map(head => [head.name, head.headSha]))
+  const dirs = [...context.paths.values()]
+  const sessionId = newSessionId()
+  const result = await invoke(context.engine, 'edit', {
+    prompt: implementPrompt({ task: context.task, instructions: context.instructions, findings: context.findings, branch: context.branch }),
+    model: context.model, dirs, sessionId, schema: IMPLEMENT_SCHEMA, timeoutMs: context.timeoutMs, signal: context.signal,
+  }, deps)
+  const reply = extractJson(result.text) || {}
+  const planned = planFiles(context.task.plan)
+  const changes = [...context.paths.entries()].map(([repo, dir]) => ({ repo, files: changedSince(dir, before.get(repo)) })).filter(entry => entry.files.length)
+  const outOfPlan = changes.flatMap(entry =>
+    entry.files.filter(file => !planned.has(`${entry.repo}/${file}`) && !TEST_FILE.test(file)).map(file => `${entry.repo}/${file}`),
+  )
+  return { summary: String(reply.summary || '').slice(0, 2000), sessionId: result.sessionId || sessionId, usage: result.usage || null, changes, outOfPlan }
+}
+
+module.exports = {
+  testCaseLines,
+  TEST_NAMING,
+  AgentError,
+  PLAN_SCHEMA,
+  IMPLEMENT_SCHEMA,
+  newSessionId,
+  runAgent,
+  checkCapability,
+  invoke,
+  extractJson,
+  validatePlan,
+  changedSince,
+  planTask,
+  proposeTaskApproaches,
+  implementTask,
+}

package/src/workflow/checkout-lock.js

@@ -0,0 +1,92 @@
+'use strict'
+
+const Crypto = require('crypto')
+const Fs = require('fs')
+const Os = require('os')
+const Path = require('path')
+
+const TTL_MS = 60 * 1000
+
+const homeDir = () => process.env.TSPL_HOME || Path.join(Os.homedir(), '.tspl')
+
+const lockFile = dir => Path.join(homeDir(), 'locks', `${Crypto.createHash('sha1').update(Fs.realpathSync(dir)).digest('hex')}.json`)
+
+const alive = pid => {
+  try {
+    process.kill(pid, 0)
+    return true
+  } catch (err) {
+    return err.code === 'EPERM'
+  }
+}
+
+const readLock = file => {
+  try {
+    return JSON.parse(Fs.readFileSync(file, 'utf8'))
+  } catch (err) {
+    return null
+  }
+}
+
+const live = (lock, now) => Boolean(lock) && lock.expiresAt > now && alive(lock.pid)
+
+/**
+ * One task at a time per checkout on this machine, whatever the server lease says. A lock expires with its process or
+ * after a minute without renewal. Returns { renew(), release() } or throws naming the task that holds the checkout.
+ */
+const claimCheckouts = (paths, { runId, taskId }, deps = {}) => {
+  const now = deps.now || Date.now
+  const pid = deps.pid || process.pid
+  const dirs = [...new Set([...paths.values()])]
+  const held = []
+  const release = () => {
+    held.forEach(file => {
+      const lock = readLock(file)
+      if (lock && lock.runId === runId) Fs.rmSync(file, { force: true })
+    })
+  }
+  try {
+    dirs.forEach(dir => {
+      const file = lockFile(dir)
+      Fs.mkdirSync(Path.dirname(file), { recursive: true, mode: 0o700 })
+      const body = () => JSON.stringify({ runId, taskId, pid, dir, expiresAt: now() + TTL_MS })
+      for (let attempt = 0; attempt < 3; attempt++) {
+        try {
+          Fs.writeFileSync(file, body(), { flag: 'wx', mode: 0o600 })
+          held.push(file)
+          return
+        } catch (err) {
+          if (err.code !== 'EEXIST') throw err
+        }
+        const other = readLock(file)
+        if (other && other.runId === runId) {
+          Fs.writeFileSync(file, body(), { mode: 0o600 })
+          held.push(file)
+          return
+        }
+        if (live(other, now())) {
+          throw new Error(`${Path.basename(dir)} is in use by task ${other.taskId} on this computer (process ${other.pid}); wait for it or stop it first: tspl build stop ${other.taskId}`)
+        }
+        Fs.rmSync(file, { force: true })
+      }
+      throw new Error(`Could not lock ${dir}; try again`)
+    })
+  } catch (err) {
+    release()
+    throw err
+  }
+  return {
+    renew() {
+      held.forEach(file => {
+        const lock = readLock(file)
+        if (lock && lock.runId === runId) Fs.writeFileSync(file, JSON.stringify({ ...lock, expiresAt: now() + TTL_MS }), { mode: 0o600 })
+      })
+    },
+    release,
+  }
+}
+
+module.exports = {
+  TTL_MS,
+  claimCheckouts,
+}