tspl-cli 0.0.0-stage → 0.1.1

package/src/workflow/client.js

@@ -0,0 +1,82 @@
+'use strict'
+
+const { request } = require('../api-client')
+
+class LeaseLostError extends Error {
+  constructor(message) {
+    super(message)
+    this.name = 'LeaseLostError'
+  }
+}
+
+const conflict = err => err && err.statusCode === 409
+
+/**
+ * The server side of one task's workflow for one run. Calls are sent one at a time because every event carries the
+ * revision the previous one produced.
+ */
+const workflowClient = (projectId, taskKey, deps = {}) => {
+  const call = deps.request || request
+  const base = `/api/v1/projects/${projectId}/tasks/${encodeURIComponent(taskKey)}/workflow`
+  let revision = 0
+  let runId = null
+  let queue = Promise.resolve()
+
+  const serial = work => {
+    const next = queue.then(work, work)
+    queue = next.catch(() => {})
+    return next
+  }
+
+  const adopt = result => {
+    revision = result.workflow ? result.workflow.revision : 0
+    return result
+  }
+
+  const client = {
+    get revision() {
+      return revision
+    },
+
+    async get() {
+      return adopt(await call('GET', base))
+    },
+
+    /** Takes the task for this run. A held lease (another run) is reported as an error with the server's words. */
+    async claim(id) {
+      runId = id
+      return serial(async () => {
+        const current = await call('GET', base)
+        return adopt(await call('POST', `${base}/claim`, { runId: id, expectedRevision: current.workflow ? current.workflow.revision : 0 }))
+      })
+    },
+
+    send(event) {
+      return serial(async () => {
+        try {
+          return adopt(await call('PUT', base, { runId, expectedRevision: revision, event }))
+        } catch (err) {
+          if (!conflict(err)) throw err
+          const current = await call('GET', base)
+          const owned = current.workflow && current.workflow.runId === runId && current.workflow.revision !== revision
+          if (!owned) {
+            if (/lease|own|no longer/i.test(err.message)) throw new LeaseLostError(err.message)
+            throw err
+          }
+          adopt(current)
+          return adopt(await call('PUT', base, { runId, expectedRevision: revision, event }))
+        }
+      })
+    },
+
+    stop: () => serial(async () => adopt(await call('POST', `${base}/stop`))),
+
+    verify: (criterion, note) => call('POST', `${base}/verify`, { criterion, actor: 'human', note: note || '' }).then(adopt),
+  }
+  return client
+}
+
+module.exports = {
+  LeaseLostError,
+  workflowClient,
+}

package/src/workflow/controller.js

@@ -0,0 +1,585 @@
+'use strict'
+
+const Crypto = require('crypto')
+const { spawnSync } = require('child_process')
+const { TEST_FILE, completionProblems, RETRY_STAGES, workflowProgress } = require('../shared')
+
+const { LeaseLostError } = require('./client')
+const { AgentError } = require('./agents')
+const { renderPrBody } = require('./pr-body')
+const { resolveRequirements, pollCi } = require('../providers')
+
+const HEARTBEAT_MS = 15 * 1000
+const CI_POLL_MS = 30 * 1000
+const MAX_STEPS = 60
+const RESUME_AS_IS = ['repairs-exhausted', 'out-of-plan']
+
+const git = (dir, args) => {
+  const result = spawnSync('git', ['-C', dir, ...args], { encoding: 'utf8', env: { ...process.env, GIT_TERMINAL_PROMPT: '0' } })
+  return { ok: result.status === 0, out: (result.stdout || '').trim(), err: (result.stderr || '').trim() }
+}
+
+/** Local Git operations the controller needs. Kept narrow: it commits named files and pushes one branch, nothing else. */
+const gitOps = {
+  commit(dir, files, message) {
+    const added = git(dir, ['add', '--all', '--', ...files])
+    if (!added.ok) throw new Error(`git add failed: ${added.err}`)
+    const committed = git(dir, ['commit', '-q', '-m', message])
+    if (!committed.ok) throw new Error(`git commit failed: ${committed.err}`)
+  },
+  push(dir, branch) {
+    const pushed = git(dir, ['push', '-u', 'origin', branch])
+    if (!pushed.ok) throw new Error(`git push failed: ${pushed.err.split('\n')[0]}`)
+  },
+  remoteTip(dir, branch) {
+    const listed = git(dir, ['ls-remote', 'origin', `refs/heads/${branch}`])
+    return listed.ok && listed.out ? listed.out.split(/\s+/)[0] : null
+  },
+}
+
+const dirtyHint = names => `${names.join(', ')} has uncommitted changes (after tspl init, commit the new .tspl/ folder first)`
+
+const commitMessage = task => `${task.card && task.card.ticket ? `${task.card.ticket}: ` : ''}${(task.card && task.card.what) || task.key}\n\ntspl task ${task.key || task.id}`
+
+const sameDestinations = (authorization, destinations, planVersion) =>
+  Boolean(authorization) &&
+  authorization.planVersion === planVersion &&
+  destinations.length === (authorization.destinations || []).length &&
+  destinations.every(item => authorization.destinations.some(known => ['repo', 'repository', 'base', 'branch'].every(field => known[field] === item[field])))
+
+const failureFindings = workflow => [
+  ...(workflow.evidence || [])
+    .filter(item => ['failed', 'timed-out'].includes(item.status))
+    .map(item => `Check ${item.checkId} ${item.status}:\n${String(item.output || '').split('\n').slice(-25).join('\n')}`),
+  ...((workflow.review && workflow.review.verdict === 'changes-requested' && workflow.review.findings) || []),
+]
+
+/**
+ * Advances one task from wherever the server says it is. Every external step is preceded and followed by a server
+ * checkpoint, and on resume the actual repository and provider state is read again instead of repeating commands.
+ * Returns { stage, blockers, next, prs }.
+ */
+const runTask = async ({ cwd, taskId, signal, options = {} }, deps) => {
+  if (options.stage && !RETRY_STAGES.includes(options.stage)) throw new Error(`Unknown retry stage: ${options.stage}. Use ${RETRY_STAGES.join(', ')}`)
+  const ctx = await deps.load({ cwd, taskId })
+  const taskKey = ctx.task.key || taskId
+  const warnings = []
+  const outcome = (stage, blockers = [], next = []) => ({ stage, blockers, next, warnings, prs: (state.workflow && state.workflow.prs) || [] })
+  const state = { task: ctx.task, workflow: ctx.task.workflow || null }
+  const again = `tspl task run ${taskKey}`
+
+  const status = ctx.task.status
+  if (ctx.task.scope && ctx.task.scope.confirmed === false) {
+    return outcome('planning', [`The PM sent the scope back: ${ctx.task.scope.note || 'no note'}`], [`Change the task in the console, then: ${again}`])
+  }
+  const flow = ctx.task.flow || null
+  if (flow && flow.scope !== false && !(ctx.task.scope && ctx.task.scope.confirmed) && ['draft', 'plan-review', 'changes-requested'].includes(status)) {
+    return outcome('planning', ['The PM has not confirmed the scope yet.'], ['The PM confirms it in the console (or: tspl task scope ' + ctx.task.key + ')', `Then: ${again}`])
+  }
+  if (!ctx.task.plan || !ctx.task.plan.workflow) {
+    if (!ctx.task.plan && deps.plan) return planStage()
+    return outcome('planning', [ctx.task.plan ? 'This is a legacy task: its plan has no workflow snapshot, so it cannot use the tested-PR workflow.' : 'There is no plan yet.'], [
+      ctx.task.plan ? `Plan it again inside an initialized project (tspl init), then: ${again}` : `Plan it first: /tspl ${taskKey} in your AI tool, or ${again} once a plan exists`,
+    ])
+  }
+  if (['plan-review', 'pm-review', 'changes-requested'].includes(status)) {
+    return outcome('awaiting-approval', [`The plan is waiting: ${status}.`], [status === 'changes-requested' ? 'Change the plan as asked and submit it again.' : `A person approves: tspl plan approve ${taskKey}`, `Then: ${again}`])
+  }
+  if (!['approved', 'building', 'done'].includes(status)) {
+    return outcome('planning', [`The task is ${status}.`], [`Prepare it with: tspl task show ${taskKey}`])
+  }
+  if (status === 'done' && state.workflow && state.workflow.stage === 'ready') return outcome('ready', [], ['Nothing left to do.'])
+
+  async function planStage() {
+    signal?.throwIfAborted()
+    const planned = await deps.plan({ ...ctx, signal })
+    signal?.throwIfAborted()
+    if (planned && planned.waitingForSelection) return outcome('planning', ['Choose an implementation approach before planning.'], [planned.note, again])
+    return outcome('awaiting-approval', [], [`A person approves the plan: tspl plan approve ${taskKey}`, `Then: ${again}`].concat(planned && planned.note ? [planned.note] : []))
+  }
+
+  if (state.workflow && state.workflow.stage === 'blocked' && state.workflow.blocker && RESUME_AS_IS.includes(state.workflow.blocker.reason) && (state.workflow.blocker.reason === 'out-of-plan' || !options.stage)) {
+    return outcome('blocked', [state.workflow.blocker.message || state.workflow.blocker.reason], [
+      state.workflow.blocker.reason === 'out-of-plan' ? `Amend the plan: tspl plan amend ${taskKey}` : `Fix and commit it yourself, then: ${again} --stage testing (or amend the plan: tspl plan amend ${taskKey})`,
+    ])
+  }
+
+  const run = deps.runs.read(taskKey)
+  const runId = run.runId || Crypto.randomUUID()
+  deps.runs.write(taskKey, { ...run, runId })
+
+  let lock
+  try {
+    lock = deps.claimCheckouts(ctx.paths, { runId, taskId: taskKey })
+  } catch (err) {
+    return outcome('blocked', [err.message], [`Stop the other task, then: ${again}`])
+  }
+
+  const client = deps.client(ctx.projectId, taskKey)
+  const abort = new AbortController()
+  if (signal) {
+    if (signal.aborted) abort.abort()
+    else signal.addEventListener('abort', () => abort.abort(), { once: true })
+  }
+  let leaseLost = false
+  let timer = null
+  let ciDeadline = null
+  const aborted = () => abort.signal.aborted
+
+  try {
+    try {
+      const claimed = await client.claim(runId)
+      state.task = claimed.task
+      state.workflow = claimed.workflow
+    } catch (err) {
+      return outcome('blocked', [err.message], [`Try again later: ${again}`])
+    }
+    timer = setInterval(() => {
+      client.send({ type: 'heartbeat' }).then(() => lock.renew()).catch(() => {
+        leaseLost = true
+        abort.abort()
+      })
+    }, deps.heartbeatMs || HEARTBEAT_MS)
+    if (timer.unref) timer.unref()
+
+    const emit = async event => {
+      if (leaseLost) throw new LeaseLostError('The task lease was lost')
+      const result = await client.send(event)
+      state.task = result.task
+      state.workflow = result.workflow
+      return result
+    }
+    const block = async (reason, message, next = [again]) => {
+      try {
+        await emit({ type: 'stage', stage: 'blocked', blocker: { reason, message } })
+      } catch (err) {
+        throw err
+      }
+      const stage = state.workflow.resumeStage || state.workflow.stage
+      const retry = stage === 'repairing' ? 'testing' : stage
+      return outcome('blocked', [message], [...next, ...(RETRY_STAGES.includes(retry) ? [`Retry this stage: ${again} --stage ${retry}`] : [])])
+    }
+
+    const plan = ctx.task.plan
+    const snapshot = plan.workflow
+    const configRepo = name => ctx.config.repos.find(repo => repo.name === name)
+    const buildOf = () => state.task.build
+    const heads = () => deps.captureHeads(ctx.paths, buildOf())
+    const changedHeads = list => list.filter(head => head.baseSha && head.headSha !== head.baseSha)
+    const sameHeads = (local, server) => local.length === server.length && local.every(head => server.some(item => item.name === head.name && item.headSha === head.headSha))
+    const dirtyOf = list => list.filter(head => !head.clean).map(head => head.name)
+    // The work happens only on the build branch chosen before coding; a person or the coding engine moving off it stops the run.
+    const offBranch = list => list.filter(head => head.branch && head.branch !== buildOf().branch)
+    const branchBlock = (list, who) => {
+      const off = offBranch(list)
+      if (!off.length) return null
+      const where = off.map(head => `${head.name} is on "${head.branch}"`).join(', ')
+      const fix = off.map(head => `git -C ${ctx.paths.get(head.name)} switch ${buildOf().branch}`)
+      return block('other', `${who}: ${where}, but this task works only on "${buildOf().branch}". Nothing was committed.`, [...fix.map(cmd => `Switch back: ${cmd}`), `Then: ${again}`])
+    }
+
+    // The branch each repo starts from and the new branch name are decided before any code is written:
+    // from --base/--branch, else asked in the terminal; scripts without either keep the project defaults.
+    const startBuild = async () => {
+      const prepare = choice => deps.prepareBuild({ taskKey, task: state.task, project: ctx.project, paths: ctx.paths, ...choice })
+      let proposal = prepare({ branch: options.branch, base: options.base })
+      if (!options.branch && !options.base && deps.chooseBranch) {
+        const choice = await deps.chooseBranch(proposal)
+        if (!choice) return { blocked: await block('stopped', 'No branch was chosen, so coding did not start.', [again]) }
+        proposal = prepare(choice)
+      }
+      const problems = deps.buildBlockers(proposal)
+      if (problems.length) return { blocked: await block('other', problems.join('; '), [`Fix that, then: ${again}`]) }
+      const result = await deps.startBuild({ projectId: ctx.projectId, taskKey, task: state.task, proposal })
+      if (!result.started) return { blocked: await block('other', result.problems.join('; '), [`Fix that, then: ${again}`]) }
+      state.task = await deps.refreshTask(ctx.projectId, taskKey)
+      return {}
+    }
+
+    const commitWork = async (result, label) => {
+      if (result.outOfPlan.length) {
+        return block('out-of-plan', `${label} changed files that are not in the approved plan: ${result.outOfPlan.join(', ')}`, [`Amend the plan: tspl plan amend ${taskKey}`])
+      }
+      if (!result.changes.length) return block('other', `${label} made no changes.`, [`Look at the branch yourself, then: ${again}`])
+      for (const change of result.changes) deps.git.commit(ctx.paths.get(change.repo), change.files, commitMessage(state.task))
+      const after = heads()
+      const dirty = dirtyOf(after)
+      if (dirty.length) return block('out-of-plan', `${dirty.join(', ')} still has uncommitted files outside the approved plan.`, [`Clean them up yourself, then: ${again}`])
+      await emit({ type: 'heads', heads: after })
+      return null
+    }
+
+    const resilientAgent = async work => {
+      try { return await work() } catch (err) {
+        const transient = err instanceof AgentError && (err.code === 'timeout' || err.code === 'failed' && /temporar|connection|ECONN|502|503/i.test(err.message))
+        if (!transient || aborted()) throw err
+        // One retry only; quota/auth failures and cancelled work require explicit recovery.
+        await new Promise(resolve => setTimeout(resolve, deps.retryDelayMs ?? 1000))
+        if (aborted()) throw err
+        return work()
+      }
+    }
+
+    const implement = async (label, findings) => {
+      const engine = deps.engineFor('build')
+      const before = heads()
+      const wrongStart = branchBlock(before, 'Before coding')
+      if (wrongStart) return wrongStart
+      let result
+      try {
+        result = await resilientAgent(() => deps.agents.implementTask({
+          engine: engine.name, model: engine.model, task: state.task, paths: ctx.paths, heads: before, instructions: ctx.instructions,
+          findings, branch: buildOf().branch, signal: abort.signal, timeoutMs: ctx.config.workflow.engineTimeoutMs,
+        }, deps.agentDeps))
+      } catch (err) {
+        if (err instanceof AgentError) return agentBlock(err)
+        throw err
+      }
+      deps.runs.write(taskKey, { ...deps.runs.read(taskKey), buildSessionId: result.sessionId })
+      const moved = branchBlock(heads(), `${label} left the task branch`)
+      if (moved) return moved
+      return commitWork(result, label)
+    }
+
+    const agentBlock = async err => {
+      if (err.code === 'cancelled') {
+        if (leaseLost) return outcome('blocked', ['The task lease was lost; the new owner was left running.'], [again])
+        return block('stopped', 'Cancelled. The stage was interrupted; resume when ready.', [again])
+      }
+      const reason = ['limit', 'auth', 'timeout', 'failed', 'invalid-output', 'unsupported'].includes(err.code) ? 'provider' : 'other'
+      return block(reason, err.message, [err.code === 'limit' ? `Resume later: ${again}` : `Fix that, then: ${again}`])
+    }
+
+    if (options.stage) {
+      if (!buildOf() && options.stage !== 'implementing') return block('other', 'Implementation has not started; set up the build first.', [`${again} --stage implementing`])
+      if (buildOf()) {
+        const local = heads()
+        if (dirtyOf(local).length) return block('other', `${dirtyHint(dirtyOf(local))}; commit the manual fix before retrying.`, [`Commit the fix, then: ${again} --stage ${options.stage}`])
+        if (local.length && !sameHeads(local, state.workflow.heads)) await emit({ type: 'heads', heads: local })
+      }
+      await emit({ type: 'retry', stage: options.stage })
+    }
+
+    for (let step = 0; step < MAX_STEPS; step++) {
+      if (leaseLost) return outcome('blocked', ['The task lease was lost; another run may own it now. Nothing more was changed.'], [`Check with: tspl task status ${taskKey}`])
+      if (aborted()) {
+        return block('stopped', 'Cancelled. The run was stopped and its lease released.', [again])
+      }
+      const workflow = state.workflow
+
+      switch (workflow.stage) {
+        case 'implementing': {
+          if (!buildOf()) {
+            const started = await startBuild()
+            if (started.blocked) return started.blocked
+          } else if (deps.refreshChecklist) {
+            deps.refreshChecklist(taskKey, state.task.plan)
+          }
+          const current = heads()
+          const wrongBranch = branchBlock(current, 'Before coding')
+          if (wrongBranch) return wrongBranch
+          const ahead = changedHeads(current)
+          if (ahead.length && !dirtyOf(current).length) {
+            await emit({ type: 'heads', heads: current })
+            await emit({ type: 'stage', stage: 'testing' })
+            break
+          }
+          if (dirtyOf(current).length && ahead.length === 0 && !options.external) {
+            // uncommitted work from a person: never stash or reset it
+            return block('other', `${dirtyHint(dirtyOf(current))}. Commit or stash them, then run again.`, [`Commit or stash, then: ${again}`])
+          }
+          if (options.external) {
+            return outcome('implementing', ['Commit your work on the build branch first; tspl checks committed work only.'], [`git commit, then: ${again}`])
+          }
+          const blocked = await implement('The coding engine', [])
+          if (blocked) return blocked
+          await emit({ type: 'stage', stage: 'testing' })
+          break
+        }
+
+        case 'repairing': {
+          const blocked = await implement('The repair', failureFindings(workflow))
+          if (blocked) return blocked
+          await emit({ type: 'stage', stage: 'testing' })
+          break
+        }
+
+        case 'testing': {
+          const local = heads()
+          if (dirtyOf(local).length) return block('other', `${dirtyHint(dirtyOf(local))}, so the tested commit would not be what ships.`, [`Commit them, then: ${again}`])
+          if (!sameHeads(local, workflow.heads)) {
+            await emit({ type: 'heads', heads: local })
+            break
+          }
+          const evidence = await deps.runChecks({ snapshot, heads: local, paths: ctx.paths, signal: abort.signal, build: buildOf() }, deps.evidenceDeps)
+          if (aborted()) break
+          const files = evidence.flatMap(item => (item.attachments || []).map(file => ({ ...file, checkId: item.checkId, headSha: item.headSha })))
+          const results = evidence.map(({ attachments, ...item }) => item)
+          if (files.length && deps.uploadArtifact) {
+            for (const file of files) {
+              try {
+                await deps.uploadArtifact(ctx.projectId, taskKey, file)
+              } catch (err) {
+                warnings.push(`Evidence upload failed for ${file.name || file.path}: ${err.message}. Screenshot remains on this computer: ${file.path}`)
+              }
+            }
+          }
+          evidence.splice(0, evidence.length, ...results)
+          if (evidence.length) await emit({ type: 'evidence', evidence })
+          const failed = evidence.filter(item => ['failed', 'timed-out'].includes(item.status))
+          const unusable = evidence.filter(item => ['missing', 'stale', 'cancelled', 'skipped'].includes(item.status))
+          if (unusable.length) {
+            return block('other', `These checks could not run: ${unusable.map(item => `${item.checkId} (${item.status}: ${String(item.output).split('\n')[0]})`).join('; ')}`, [`Fix the cause (see .tspl/project.json), then: ${again}`])
+          }
+          if (failed.length) {
+            try {
+              await emit({ type: 'stage', stage: 'repairing' })
+            } catch (err) {
+              if (err instanceof LeaseLostError || !/repair rounds/.test(err.message)) throw err
+              return block('repairs-exhausted', `${err.message}. Still failing: ${failed.map(item => item.checkId).join(', ')}`, [`Fix it on the branch yourself, then: ${again}`])
+            }
+            break
+          }
+          await emit({ type: 'stage', stage: 'reviewing' })
+          break
+        }
+
+        case 'reviewing': {
+          const local = heads()
+          if (dirtyOf(local).length) return block('other', `${dirtyHint(dirtyOf(local))}.`, [`Commit them, then: ${again}`])
+          if (!sameHeads(local, workflow.heads)) {
+            await emit({ type: 'heads', heads: local })
+            break
+          }
+          const options = snapshot.options || {}
+          const verifier = deps.engineFor('verify')
+          let review = workflow.review
+          if (options.review === false) review = { verdict: 'passed', findings: [] }
+          else if (!review) {
+            try {
+              review = await resilientAgent(() => deps.agents.reviewTask({
+                engine: verifier.name, model: verifier.model, task: state.task, paths: ctx.paths, heads: local, instructions: ctx.instructions,
+                evidence: workflow.evidence, buildSessionId: deps.runs.read(taskKey).buildSessionId, signal: abort.signal, timeoutMs: ctx.config.workflow.engineTimeoutMs,
+              }, deps.agentDeps))
+            } catch (err) {
+              if (err instanceof AgentError) return agentBlock(err)
+              throw err
+            }
+            await emit({ type: 'review', review })
+          }
+          if (review.verdict === 'changes-requested') {
+            try {
+              await emit({ type: 'stage', stage: 'repairing' })
+            } catch (err) {
+              if (err instanceof LeaseLostError || !/repair rounds/.test(err.message)) throw err
+              return block('repairs-exhausted', `${err.message}. The review still asks for changes: ${review.findings.map(item => item.message).join('; ')}`, [`Fix it on the branch yourself, then: ${again}`])
+            }
+            break
+          }
+          const problems = completionProblems({ plan: state.task.plan, workflow: state.workflow, upTo: 'review' })
+          if (problems.length) {
+            const manual = problems.filter(text => /Acceptance criterion/.test(text))
+            if (manual.length === problems.length) {
+              return outcome('reviewing', manual, snapshot.manualCriteria.map(n => `tspl task verify ${taskKey} --check ${n}`).concat([`Then: ${again}`]))
+            }
+            return block('other', problems.join(' '), [`Fix it, then: ${again}`])
+          }
+          if (options.pullRequest === false) {
+            try {
+              await emit({ type: 'stage', stage: 'ready' })
+            } catch (err) {
+              if (err instanceof LeaseLostError) throw err
+              return block('other', err.message, [`Fix what it says, then: ${again}`])
+            }
+            break
+          }
+          await emit({ type: 'stage', stage: 'awaiting-delivery' })
+          break
+        }
+
+        case 'awaiting-delivery': {
+          const changed = changedHeads(workflow.heads)
+          const build = buildOf()
+          const destinations = changed.map(head => ({
+            repo: head.name,
+            repository: configRepo(head.name).delivery.repository,
+            base: build.repos.find(repo => repo.name === head.name).base,
+            branch: build.branch,
+          }))
+          for (const destination of destinations) {
+            const repoConfig = configRepo(destination.repo)
+            const provider = deps.providerFor(repoConfig)
+            if (!provider.supported) return block('provider', provider.reason, [`Open the pull request yourself from ${build.branch}.`])
+            try {
+              await provider.authenticate()
+              const resolved = resolveRequirements(repoConfig, await provider.requiredChecks(destination.base))
+              if (!resolved.determined) return block('provider', resolved.problems.join(' '), [`Fix .tspl/project.json, then: ${again}`])
+            } catch (err) {
+              if (err.code) return block('provider', err.message, [`Fix that, then: ${again}`])
+              throw err
+            }
+          }
+          if (!sameDestinations(workflow.deliveryAuthorization, destinations, workflow.planVersion)) {
+            const summary = [
+              'About to push and open draft pull requests:',
+              ...destinations.map(item => `  ${item.repo}: branch ${item.branch} → ${item.repository} (${item.base})`),
+              `  title: ${state.task.card.what}`,
+            ].join('\n')
+            const accepted = options.confirmDelivery || (deps.confirm ? await deps.confirm(summary) : false)
+            if (!accepted) return outcome('awaiting-delivery', [summary], [`Confirm and continue: ${again} --confirm-delivery`])
+            await emit({ type: 'delivery', authorization: { planVersion: workflow.planVersion, destinations } })
+          }
+          await emit({ type: 'stage', stage: 'creating-pr' })
+          break
+        }
+
+        case 'creating-pr': {
+          const build = buildOf()
+          const local = heads()
+          if (!sameHeads(local, workflow.heads)) {
+            await emit({ type: 'heads', heads: local })
+            break
+          }
+          for (const head of changedHeads(workflow.heads)) {
+            const existing = (workflow.prs || []).find(item => item.repo === head.name)
+            if (existing && existing.headSha === head.headSha) continue
+            const repoConfig = configRepo(head.name)
+            const provider = deps.providerFor(repoConfig)
+            const base = build.repos.find(repo => repo.name === head.name).base
+            const dir = ctx.paths.get(head.name)
+            try {
+              await provider.authenticate()
+              const resolved = resolveRequirements(repoConfig, await provider.requiredChecks(base))
+              if (!resolved.determined) return block('provider', resolved.problems.join(' '), [`Fix .tspl/project.json, then: ${again}`])
+              deps.git.push(dir, build.branch)
+              if (deps.git.remoteTip(dir, build.branch) !== head.headSha) {
+                return block('provider', `The remote branch ${build.branch} of ${head.name} is not at the tested commit ${head.headSha} after pushing. Someone else may have pushed to it.`, [`Look at the remote branch, then: ${again}`])
+              }
+              const body = renderPrBody({
+                task: state.task, summary: '', repo: head.name, head,
+                evidence: workflow.evidence.filter(item => item.repo === head.name),
+                criteria: ((state.task.card && state.task.card.doneWhen) || []).map((text, i) => ({ text, how: snapshot.checks.some(check => (check.criteria || []).includes(i + 1)) ? 'executed check' : 'human verification' })),
+                review: workflow.review,
+                limitations: ['Checks above were executed by the tspl CLI on the developer machine; required CI is reported separately by GitHub.'],
+                ci: resolved.confirmedNone ? 'This project confirmed that no CI is required; the PR relies on the local checks and the review above.' : null,
+              })
+              const pr = await provider.upsertDraft({ base, head: build.branch, title: commitMessage(state.task).split('\n')[0], body })
+              await emit({
+                type: 'pr',
+                pr: { repo: head.name, provider: provider.name, repository: repoConfig.delivery.repository, number: pr.number, url: pr.url, headSha: pr.headSha, base, draft: pr.draft, state: pr.state, requiredChecks: resolved.requirements, checks: [], observedAt: new Date().toISOString() },
+              })
+            } catch (err) {
+              if (err instanceof LeaseLostError) throw err
+              return block('provider', err.message, [`Resume without duplicates: ${again}`])
+            }
+          }
+          await emit({ type: 'stage', stage: 'awaiting-ci' })
+          break
+        }
+
+        case 'awaiting-ci': {
+          if (ciDeadline === null) ciDeadline = Date.now() + (deps.ciWaitMs || 0)
+          const local = heads()
+          if (!sameHeads(local, workflow.heads)) {
+            await emit({ type: 'heads', heads: local })
+            break
+          }
+          let pending = false
+          const prs = [...workflow.prs]
+          for (const pr of prs) {
+            const provider = deps.providerFor(configRepo(pr.repo))
+            let polled
+            try {
+              polled = await pollCi({ provider, number: pr.number, requirements: pr.requiredChecks, headSha: pr.headSha, maxMs: deps.ciPollMs ?? CI_POLL_MS }, deps.pollDeps)
+            } catch (err) {
+              return block('provider', err.message, [`Fix that, then: ${again}`])
+            }
+            await emit({ type: 'ci', repo: pr.repo, checks: polled.pr.checks, draft: polled.pr.draft, state: polled.pr.state, observedAt: polled.pr.observedAt })
+            if (polled.state === 'stale') return block('provider', `The pull request for ${pr.repo} is on ${polled.pr.headSha}, not the tested commit ${pr.headSha}. Someone pushed to the branch.`, [`Look at the branch, then: ${again}`])
+            if (polled.state === 'failed') {
+              const bad = polled.states.filter(item => item.state === 'failed').map(item => `${item.requirement.name}: ${item.reason}`)
+              return block('ci-failed', `Required CI failed for ${pr.repo}: ${bad.join('; ')}`, [`Fix the failure on the branch, then: ${again}`])
+            }
+            if (polled.state === 'pending') pending = true
+          }
+          if (pending) {
+            if (Date.now() < ciDeadline) {
+              await require('timers/promises').setTimeout(Math.min(deps.ciRetryDelayMs ?? 1000, Math.max(0, ciDeadline - Date.now())), undefined, { signal: abort.signal })
+              break
+            }
+            return outcome('awaiting-ci', [`Required CI has not finished: ${state.workflow.prs.map(item => item.url).join(', ')}`], [`Check again in a few minutes: ${again}`])
+          }
+          for (const pr of state.workflow.prs) {
+            const provider = deps.providerFor(configRepo(pr.repo))
+            let ready
+            try {
+              ready = await provider.markReady(pr.number, { headSha: pr.headSha })
+            } catch (err) {
+              return block('provider', err.message, [`Fix that, then: ${again}`])
+            }
+            await emit({ type: 'ci', repo: pr.repo, checks: pr.checks, draft: ready.draft, state: ready.state })
+          }
+          try {
+            await emit({ type: 'stage', stage: 'ready' })
+          } catch (err) {
+            if (err instanceof LeaseLostError) throw err
+            return outcome('awaiting-ci', [err.message], [`Fix what it says, then: ${again}`])
+          }
+          break
+        }
+
+        case 'ready': {
+          deps.finishLocal(taskKey)
+          if (!state.workflow.prs.length) {
+            const build = buildOf()
+            return outcome('ready', [], [`Done: tested${(snapshot.options || {}).review === false ? '' : ' and reviewed'} on branch ${build ? build.branch : 'the task branch'}. This task opens no pull request; push and merge it yourself.`])
+          }
+          return outcome('ready', [], state.workflow.prs.map(item => `Review the pull request: ${item.url}`))
+        }
+
+        default:
+          return outcome(workflow.stage, [`Unexpected stage ${workflow.stage}`], [`tspl task status ${taskKey}`])
+      }
+    }
+    return block('other', 'The workflow reached its step limit without finishing. Resume from the recorded checkpoint.', [again])
+  } catch (err) {
+    if (err instanceof LeaseLostError || leaseLost) {
+      return outcome('blocked', [`${err.message}. Another run may own the task now; nothing more was changed.`], [`Check with: tspl task status ${taskKey}`])
+    }
+    const message = aborted() ? 'Cancelled. The stage was interrupted; resume when ready.' : String(err.message || err).slice(0, 3500)
+    const stage = state.workflow?.resumeStage || state.workflow?.stage || 'implementing'
+    let persistence = ''
+    try {
+      const saved = await client.send({ type: 'stage', stage: 'blocked', blocker: { reason: aborted() ? 'stopped' : 'other', message } })
+      state.workflow = saved.workflow
+    } catch (saveError) { persistence = ` Could not save the failure: ${saveError.message}; an expired heartbeat will show the interruption.` }
+    return outcome('blocked', [message + persistence], [`Fix the cause, then: ${again} --stage ${stage === 'repairing' ? 'testing' : stage}`])
+  } finally {
+    clearInterval(timer)
+    if (lock) lock.release()
+  }
+}
+
+/** Plain-language state of a task's workflow, for `tspl task status`. */
+const describeWorkflow = task => {
+  const workflow = task.workflow
+  if (!task.plan && task.approaches) return { lines: [`${task.key}: ${task.approaches.selection ? 'approach selected; ready to plan' : 'waiting for approach selection'} (v${task.approaches.version})`], next: [task.approaches.selection ? `tspl task run ${task.key}` : `tspl task choose ${task.key} <option-id> --version ${task.approaches.version}`] }
+  if (!task.plan || !task.plan.workflow) return { lines: [`${task.key}: legacy task (status ${task.status}). Its history is a build report, not a tested pull request.`], next: [] }
+  if (!workflow) return { lines: [`${task.key}: status ${task.status}; the workflow has not started.`], next: [task.status === 'approved' ? `tspl task run ${task.key}` : `tspl plan show ${task.key}`] }
+  const lines = [`${task.key}: stage ${workflow.stage} (revision ${workflow.revision}, repair rounds used ${workflow.attempts})`]
+  const progress = workflowProgress(task)
+  if (progress) lines.push(...progress.steps.map(step => `  ${step.label}: ${step.status} — ${step.reason}${['failed', 'interrupted', 'waiting'].includes(step.status) ? `\n    ${step.command}` : ''}`))
+  if (workflow.blocker) lines.push(`  blocked: ${workflow.blocker.reason}${workflow.blocker.message ? ` - ${workflow.blocker.message}` : ''}`)
+  lines.push(...(workflow.heads || []).map(head => `  ${head.name}: ${String(head.headSha).slice(0, 7)} on ${head.branch}${head.clean ? '' : ' (uncommitted changes)'}`))
+  lines.push(...(workflow.evidence || []).map(item => `  check ${item.checkId}: ${item.status}${item.testCount ? `, ${item.testCount} tests` : ''} on ${String(item.headSha).slice(0, 7)} [run by the CLI on a developer machine]`))
+  if (workflow.review) lines.push(`  review: ${workflow.review.verdict} by ${workflow.review.engine || 'AI'} [separate session]`)
+  lines.push(...(workflow.prs || []).map(pr => `  PR ${pr.repo}: ${pr.url} ${pr.draft ? 'draft' : pr.state}, CI ${(pr.checks || []).length} observation(s) [reported by ${pr.provider}]`))
+  const next = workflow.stage === 'ready' ? [] : [`tspl task run ${task.key}`]
+  return { lines, next }
+}
+
+module.exports = {
+  gitOps,
+  runTask,
+  describeWorkflow,
+}