@1aboveio/skills 0.0.0-stage → 1.0.0

package/skills/engineering/resolve-issues/scripts/plan-sync.mjs

@@ -0,0 +1,269 @@
+#!/usr/bin/env node
+// Keep a run's task plan in step with its spec's GitHub issue tree, the only record of
+// scope. Every open issue under the spec with no open sub-issue is a unit; an issue with an
+// open sub-issue is a container; a closed issue is done. Order comes from native
+// `blockedBy` links.
+//
+//   plan-sync.mjs --run <run dir> [--live] [--json] [--exit-actions]
+//   plan-sync.mjs --find-run --runs <runs dir> --issue <owner/name#123> [--json] [--exit-actions]
+//
+// --live fetches the tree (issue-tree.mjs, one GraphQL query plus follow-ups) and, when the
+// fetch is complete, saves it as <run>/issue-tree.json. Without --live it diffs the plan
+// against that saved snapshot and makes no GitHub call. Actions:
+//
+//   add-unit         an open leaf issue under the spec that the plan does not know
+//   set-deps         a unit lacks a dependency its own issue's blockedBy names
+//   move-link        an issue with open sub-issues is blocked by an open issue: GitHub shows
+//                    it holding every sub-issue, but the run never inherits it, so move it
+//                    onto the sub-issues that use what the blocker builds
+//   drop-unit        a unit's issue was closed, gained open sub-issues, or left the tree
+//   blocked-outside  a unit waits on an open issue outside the spec's tree
+//
+// The plan knows an issue when a unit (any status), an `excluded` entry, or `merged` (merged
+// by an earlier run) names it. set-deps only adds: dependencies the explorer recorded
+// stay. A partial or failed fetch never drops a unit or changes dependencies; a failed one
+// falls back to the snapshot. A plan whose spec is not a GitHub issue has nothing to sync.
+//
+// --find-run prints the newest run directory whose spec or saved tree contains the issue, so
+// a new invocation resumes the spec's run instead of starting a second one.
+//
+// Exit 0 whenever it ran and answered: actions due or not, no tree available (`missingTree`),
+// a run found or not; the outcome is in the output (--json: `actions`, `missingTree`, and for
+// --find-run `found` and `dir`). Exit 2 only when it could not run (bad arguments, unreadable plan).
+// With --find-run and no run found, plain output is empty on stdout (a note goes to stderr).
+// --exit-actions restores the old exit codes for one release (deprecated): 1 when actions are due
+// or no run was found, 2 when no tree is available.
+
+import { existsSync, readdirSync, readFileSync, statSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+import { isMainModule } from '../../engineering-runtime/scripts/main-module.mjs'
+import { fetchTree, keyOf } from './issue-tree.mjs'
+import { parseIssueRef } from './ready-check.mjs'
+
+export const SNAPSHOT = 'issue-tree.json'
+const DONE = new Set(['succeeded', 'cancelled'])
+
+export class PlanSyncError extends Error {}
+
+const unitsOf = (plan) => (Array.isArray(plan?.units) ? plan.units : plan?.issues) ?? []
+
+// The spec's root issue, or null for a local or pasted spec.
+export function specRef(plan) {
+  for (const value of [plan?.specLocator, plan?.spec, plan?.specUrl]) {
+    if (typeof value !== 'string') continue
+    try { return parseIssueRef(value) } catch { /* not an issue reference */ }
+  }
+  return null
+}
+
+// The issue a unit or excluded entry names, as "owner/name#n", or null.
+function issueKey(entry, repo) {
+  for (const value of [entry?.issue, entry?.ref, entry?.id]) {
+    if (value === undefined || value === null) continue
+    try {
+      const ref = parseIssueRef(String(value), repo)
+      return keyOf(ref.repo, ref.number)
+    } catch { /* not an issue reference */ }
+  }
+  return null
+}
+
+const idFor = (key, repo) => (key.startsWith(`${repo}#`) ? key.slice(repo.length + 1) : key)
+
+// The unit ids of the plan's `excluded` issues (release gates, human-only environment work,
+// empty rollups): a unit that depends on one waits for a human, never for the run.
+export function excludedIds(plan) {
+  const repo = specRef(plan)?.repo ?? null
+  const ids = new Set()
+  for (const e of plan?.excluded ?? []) {
+    const key = issueKey(e, repo)
+    const raw = e?.issue ?? e?.id
+    if (key) ids.add(repo ? idFor(key, repo) : key)
+    else if (raw !== undefined && raw !== null) ids.add(String(raw).replace(/^#/, ''))
+  }
+  return ids
+}
+
+export function classify(tree) {
+  const kind = {}
+  for (const node of Object.values(tree.nodes)) {
+    if (node.state !== 'open') { kind[node.key] = 'closed'; continue }
+    const open = (node.children ?? []).filter((k) => tree.nodes[k]?.state === 'open')
+    kind[node.key] = open.length ? 'container' : 'unit'
+  }
+  return kind
+}
+
+// Diff the plan against the tree. `partial` suppresses every removal and dependency change.
+export function planSync(plan, tree) {
+  const root = specRef(plan)
+  if (!root) return { synced: false, actions: [] }
+  const repo = root.repo
+  const partial = !tree.complete
+  const kind = classify(tree)
+  const nodes = tree.nodes
+  const units = unitsOf(plan)
+  const byKey = new Map()
+  for (const u of units) { const key = issueKey(u, repo); if (key) byKey.set(key, u) }
+  const known = new Set(byKey.keys())
+  for (const e of plan.excluded ?? []) { const key = issueKey(e, repo); if (key) known.add(key) }
+  for (const id of plan.merged ?? []) { const key = issueKey({ id }, repo); if (key) known.add(key) }
+
+  const leavesUnder = (key, seen = new Set()) => {
+    if (seen.has(key)) return []
+    seen.add(key)
+    if (kind[key] === 'unit') return [key]
+    if (kind[key] !== 'container') return []
+    return (nodes[key].children ?? []).flatMap((k) => leavesUnder(k, seen))
+  }
+  // A unit waits on its own issue's blockers only. A container's link is never inherited:
+  // move-link asks for it on the sub-issues that actually wait.
+  const blockers = (key) => nodes[key]?.blockedBy ?? []
+  const wants = (key) => {
+    const deps = new Set()
+    const outside = []
+    for (const b of blockers(key)) {
+      if (b.state !== 'open') continue
+      if (nodes[b.key]) for (const leaf of leavesUnder(b.key)) { if (leaf !== key) deps.add(idFor(leaf, repo)) }
+      else outside.push(b.key)
+    }
+    return { deps: [...deps].sort(), outside }
+  }
+
+  const actions = []
+  const add = (action, unit, detail, extra = {}) => actions.push({ action, unit, detail, ...extra })
+  for (const [key, k] of Object.entries(kind)) {
+    if (k !== 'unit' || known.has(key)) continue
+    const node = nodes[key]
+    const { deps } = wants(key)
+    const id = idFor(key, repo)
+    const rollup = (node.children ?? []).length > 0
+    add('add-unit', id, `add unit ${id} for ${key} "${node.title}"${deps.length ? ` with dependsOn [${deps.join(', ')}]` : ''}: fetch its issue into the run, continue the explorer for it, rerun the size check${rollup ? '; every sub-issue is closed, so the explorer records what is left or that nothing is (then hand back "close it")' : ''}`, { issue: key, dependsOn: deps })
+  }
+  for (const [key, u] of byKey) {
+    if (DONE.has(u.status)) continue
+    const id = String(u.id)
+    const k = kind[key]
+    if (k === undefined) {
+      if (!partial) add('drop-unit', id, `unit ${id}'s issue ${key} is no longer under ${tree.root}: cancel the unit, or put the issue back in the tree`, { issue: key })
+      continue
+    }
+    if (k === 'closed') { add('drop-unit', id, `unit ${id}'s issue ${key} was closed on GitHub: set succeeded if its PR merged, else cancelled`, { issue: key }); continue }
+    if (k === 'container') {
+      const open = (nodes[key].children ?? []).filter((c) => nodes[c]?.state === 'open').map((c) => idFor(c, repo))
+      if (!partial) add('drop-unit', id, `unit ${id}'s issue ${key} now has open sub-issues (${open.join(', ')}): they are the units; cancel ${id} and keep its workspace`, { issue: key })
+      continue
+    }
+    const { deps, outside } = wants(key)
+    if (!partial) {
+      const have = new Set((u.dependsOn ?? []).map(String))
+      const missing = deps.filter((d) => !have.has(d))
+      if (missing.length) add('set-deps', id, `unit ${id} waits on ${missing.join(', ')} (blockedBy on GitHub): add ${missing.length === 1 ? 'it' : 'them'} to its dependsOn`, { issue: key, dependsOn: [...have, ...missing] })
+    }
+    for (const o of outside) add('blocked-outside', id, `unit ${id} is blocked by open ${o}, outside ${tree.root}: make it a sub-issue of an issue in the tree, or remove the link`, { issue: key, blocker: o })
+  }
+  for (const [key, k] of Object.entries(kind)) {
+    if (k !== 'container' || key === tree.root) continue
+    const open = (nodes[key].blockedBy ?? []).filter((b) => b.state === 'open').map((b) => b.key)
+    if (!open.length) continue
+    const children = (nodes[key].children ?? []).filter((c) => nodes[c]?.state === 'open').map((c) => idFor(c, repo))
+    add('move-link', idFor(key, repo), `${key} has ${children.length} open sub-issues (${children.join(', ')}) and is blocked by ${open.join(', ')}; the run does not inherit a link on it: add blocked_by on each sub-issue that uses what the blocker builds, remove the link from ${key}, drop the blocker from the dependsOn of sub-issues that do not use it, and rerun next-actions.mjs with --sync so the saved tree sees the move`, { issue: key, blockers: open })
+  }
+  const order = ['drop-unit', 'add-unit', 'set-deps', 'move-link', 'blocked-outside']
+  actions.sort((a, b) => order.indexOf(a.action) - order.indexOf(b.action) || String(a.unit).localeCompare(String(b.unit)))
+  return { synced: true, partial, actions }
+}
+
+const readJson = (path) => { try { return JSON.parse(readFileSync(path, 'utf8')) } catch { return null } }
+
+// Sync a run directory: fetch when `live`, else (or when the fetch fails) use the snapshot.
+export function syncRun(runDir, { live = false, fetch = fetchTree, now = () => new Date() } = {}) {
+  const plan = readJson(join(runDir, 'task-plan.json'))
+  if (!plan) throw new PlanSyncError(`cannot read ${join(runDir, 'task-plan.json')}`)
+  const root = specRef(plan)
+  if (!root) return { source: 'none', synced: false, actions: [] }
+  const snapshotPath = join(runDir, SNAPSHOT)
+  let tree = null
+  let source = 'snapshot'
+  let fetchError = null
+  if (live) {
+    const fetched = fetch(root)
+    if (fetched.complete) {
+      tree = { ...fetched, fetchedAt: now().toISOString() }
+      writeFileSync(snapshotPath, `${JSON.stringify(tree, null, 2)}\n`)
+      source = 'live'
+    } else if (Object.keys(fetched.nodes).length && fetched.nodes[fetched.root]?.children) {
+      tree = fetched
+      source = 'live-partial'
+      fetchError = fetched.errors
+    } else {
+      fetchError = fetched.errors
+    }
+  }
+  if (!tree) tree = readJson(snapshotPath)
+  if (!tree) return { source: 'none', synced: false, fetchError, actions: [], missingTree: true }
+  const result = planSync(plan, tree)
+  return { source, fetchedAt: tree.fetchedAt ?? null, fetchError, ...result }
+}
+
+// The newest run whose spec is the issue, or whose saved tree contains it.
+export function findRun(runsDir, ref) {
+  const key = keyOf(ref.repo, ref.number)
+  let best = null
+  let names = []
+  try { names = readdirSync(runsDir) } catch { return null }
+  for (const name of names) {
+    const dir = join(runsDir, name)
+    const planPath = join(dir, 'task-plan.json')
+    if (!existsSync(planPath)) continue
+    const plan = readJson(planPath)
+    const spec = specRef(plan)
+    const tree = readJson(join(dir, SNAPSHOT))
+    const match = (spec && keyOf(spec.repo, spec.number) === key) || Boolean(tree?.nodes?.[key])
+    if (!match) continue
+    const mtime = statSync(planPath).mtimeMs
+    if (!best || mtime > best.mtime) best = { dir, mtime }
+  }
+  return best?.dir ?? null
+}
+
+export function parseCliArgs(argv) {
+  const opts = { live: false, json: false, findRun: false }
+  for (let i = 0; i < argv.length; i++) {
+    const flag = argv[i]
+    if (flag === '--live') opts.live = true
+    else if (flag === '--json') opts.json = true
+    else if (flag === '--find-run') opts.findRun = true
+    else if (flag === '--exit-actions') opts.exitActions = true
+    else if (['--run', '--runs', '--issue'].includes(flag) && argv[i + 1] !== undefined) opts[flag.slice(2)] = argv[++i]
+    else throw new PlanSyncError('usage: plan-sync.mjs --run <run dir> [--live] [--json] [--exit-actions] | --find-run --runs <runs dir> --issue <owner/name#123> [--json] [--exit-actions]; exit 0 when it ran (the outcome is in the output), 2 on error')
+  }
+  if (opts.findRun ? !(opts.runs && opts.issue) : !opts.run) throw new PlanSyncError('usage: plan-sync.mjs --run <run dir> [--live] [--json] [--exit-actions] | --find-run --runs <runs dir> --issue <owner/name#123> [--json] [--exit-actions]; exit 0 when it ran (the outcome is in the output), 2 on error')
+  return opts
+}
+
+if (isMainModule(import.meta.url)) {
+  try {
+    const opts = parseCliArgs(process.argv.slice(2))
+    if (opts.findRun) {
+      const dir = findRun(opts.runs, parseIssueRef(opts.issue))
+      if (opts.json) console.log(JSON.stringify({ found: Boolean(dir), dir }, null, 2))
+      else if (dir) console.log(dir)
+      else process.stderr.write(`plan-sync: no run under ${opts.runs} for ${opts.issue}\n`)
+      process.exitCode = opts.exitActions && !dir ? 1 : 0
+    } else {
+      const result = syncRun(opts.run, { live: opts.live })
+      if (opts.json) console.log(JSON.stringify(result, null, 2))
+      else {
+        for (const a of result.actions) process.stdout.write(`${a.action.padEnd(17)}${a.detail}\n`)
+        if (result.fetchError) process.stdout.write(`fetch failed, ${result.source === 'live-partial' ? 'partial tree used' : 'saved snapshot used'}: ${result.fetchError.map((e) => `${e.key}: ${e.error}`).join('; ')}\n`)
+        process.stdout.write(result.synced ? `tree ${result.source}${result.fetchedAt ? ` ${result.fetchedAt}` : ''}; ${result.actions.length} due\n` : result.missingTree ? 'no issue tree available (no saved snapshot and no successful fetch): rerun with --live\n' : 'no issue tree to sync\n')
+      }
+      process.exitCode = opts.exitActions ? (result.missingTree ? 2 : result.actions.length ? 1 : 0) : 0
+    }
+  } catch (error) {
+    process.stderr.write(`plan-sync: ${error.message}\n`)
+    process.exitCode = 2
+  }
+}

package/skills/engineering/resolve-issues/scripts/plan-sync.test.mjs

@@ -0,0 +1,156 @@
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+import { spawnSync } from 'node:child_process'
+import { mkdirSync, mkdtempSync, readFileSync, utimesSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+import { SNAPSHOT, classify, findRun, parseCliArgs, PlanSyncError, planSync, syncRun } from './plan-sync.mjs'
+
+const script = join(dirname(fileURLToPath(import.meta.url)), 'plan-sync.mjs')
+
+// A tree in issue-tree.mjs's shape from { "n": { state, children: [n], blockedBy: [n] } } in o/r.
+function tree(spec, issues, { complete = true } = {}) {
+  const nodes = {}
+  const key = (n) => (String(n).includes('#') ? String(n) : `o/r#${n}`)
+  for (const [n, i] of Object.entries(issues)) {
+    nodes[key(n)] = { key: key(n), repo: 'o/r', number: Number(n), title: `t${n}`, state: i.state ?? 'open', labels: [], blockedBy: (i.blockedBy ?? []).map((b) => ({ key: key(b), state: issues[b]?.state ?? i.blockerState ?? 'open' })), children: (i.children ?? []).map(key), parent: null }
+  }
+  for (const node of Object.values(nodes)) for (const c of node.children) if (nodes[c]) nodes[c].parent = node.key
+  return { root: key(spec), complete, errors: complete ? [] : [{ key: key(spec), error: 'HTTP 502' }], nodes }
+}
+const plan = (units, extra = {}) => ({ spec: 'o/r#1', units, ...extra })
+const actionsOf = (result) => result.actions.map((a) => `${a.action} ${a.unit}`)
+
+test('a held issue whose filed prerequisite closed stays a unit, and a new open issue is added', () => {
+  // fmm #1343: its prerequisite #1659 was filed under it and closed; the old check dropped #1343.
+  const t = tree(1, { 1: { children: [1343, 1142, 1700] }, 1343: { children: [1659] }, 1659: { state: 'closed' }, 1142: { blockedBy: [1343] }, 1700: {} })
+  assert.equal(classify(t)['o/r#1343'], 'unit')
+  const result = planSync(plan([{ id: '1343', status: 'blocked' }, { id: '1142', status: 'pending', dependsOn: ['1343'] }]), t)
+  assert.deepEqual(actionsOf(result), ['add-unit 1700'])
+})
+
+test('add-unit carries blockedBy, expanding a blocking container into its open leaves', () => {
+  const t = tree(1, { 1: { children: [2, 5] }, 2: { children: [3, 4] }, 3: {}, 4: { state: 'closed' }, 5: { blockedBy: [2] } })
+  const result = planSync(plan([{ id: '3', status: 'pending' }]), t)
+  assert.deepEqual(result.actions.map((a) => [a.action, a.unit, a.dependsOn]), [['add-unit', '5', ['3']]])
+})
+
+test('a container\'s link is never inherited: move-link asks for it on the sub-issues that wait', () => {
+  // A link on a split issue fanned out to all five of its slices, though two used the blocker.
+  const t = tree(1, { 1: { children: [2, 9] }, 2: { children: [3, 4], blockedBy: [9] }, 3: {}, 4: {}, 9: {} })
+  const result = planSync(plan([{ id: '3', status: 'pending', dependsOn: ['7'] }, { id: '4', status: 'pending' }, { id: '9', status: 'pending' }]), t)
+  assert.deepEqual(result.actions.map((a) => [a.action, a.unit]), [['move-link', '2']])
+  assert.match(result.actions[0].detail, /o\/r#2 has 2 open sub-issues \(3, 4\) and is blocked by o\/r#9/)
+  const moved = tree(1, { 1: { children: [2, 9] }, 2: { children: [3, 4] }, 3: { blockedBy: [9] }, 4: {}, 9: {} })
+  const after = planSync(plan([{ id: '3', status: 'pending', dependsOn: ['7'] }, { id: '4', status: 'pending' }, { id: '9', status: 'pending' }]), moved)
+  assert.deepEqual(after.actions.map((a) => [a.action, a.unit, a.dependsOn]), [['set-deps', '3', ['7', '9']]], 'only the linked sub-issue waits; set-deps keeps the explorer-recorded 7')
+  const done = tree(1, { 1: { children: [2, 9] }, 2: { children: [3], blockedBy: [9] }, 3: {}, 9: { state: 'closed' } })
+  assert.deepEqual(planSync(plan([{ id: '3', status: 'pending' }]), done).actions, [], 'a closed blocker needs no move')
+})
+
+test('closed, split, and moved-out issues drop their units; done units are left alone', () => {
+  const t = tree(1, { 1: { children: [2, 3, 5] }, 2: { state: 'closed' }, 3: { children: [4] }, 4: {}, 5: { state: 'closed' } })
+  const result = planSync(plan([
+    { id: '2', status: 'in-flight' }, { id: '3', status: 'pending' }, { id: '4', status: 'pending' },
+    { id: '5', status: 'succeeded' }, { id: '8', status: 'pending' },
+  ]), t)
+  assert.deepEqual(actionsOf(result), ['drop-unit 2', 'drop-unit 3', 'drop-unit 8'])
+})
+
+test('a partial tree never drops a unit or changes dependencies', () => {
+  const t = tree(1, { 1: { children: [3, 5] }, 3: { blockedBy: [5] }, 5: {} }, { complete: false })
+  const result = planSync(plan([{ id: '3', status: 'pending' }, { id: '8', status: 'pending' }]), t)
+  assert.equal(result.partial, true)
+  assert.deepEqual(actionsOf(result), ['add-unit 5'])
+})
+
+test('an open blocker outside the tree is reported; a closed one is satisfied', () => {
+  const t = tree(1, { 1: { children: [3, 4] }, 3: { blockedBy: ['x/y#9'] }, 4: { blockedBy: ['x/y#10'], blockerState: 'closed' } })
+  const result = planSync(plan([{ id: '3', status: 'pending' }, { id: '4', status: 'pending' }]), t)
+  assert.deepEqual(result.actions.map((a) => [a.action, a.unit, a.blocker]), [['blocked-outside', '3', 'x/y#9']])
+})
+
+test('excluded issues and earlier merges are known; every other open leaf joins the run; a local spec has nothing to sync', () => {
+  const t = tree(1, { 1: { children: [2, 3, 4, 5] }, 2: {}, 3: {}, 4: {}, 5: {} })
+  const result = planSync(plan([{ id: '2', status: 'pending' }], { excluded: [{ issue: 'o/r#3', reason: 'release gate' }], merged: ['4'] }), t)
+  assert.deepEqual(result.actions.map((a) => `${a.action} ${a.unit}`), ['add-unit 5'], 'no wave keeps an open issue out of the run')
+  assert.equal(planSync({ spec: 'docs/spec.md', units: [{ id: 'one' }] }, t).synced, false)
+})
+
+function runDir(planBody, snapshot) {
+  const dir = mkdtempSync(join(tmpdir(), 'plan-sync-'))
+  writeFileSync(join(dir, 'task-plan.json'), JSON.stringify(planBody))
+  if (snapshot) writeFileSync(join(dir, SNAPSHOT), JSON.stringify(snapshot))
+  return dir
+}
+
+test('a live sync saves a complete tree; a failed fetch falls back to the snapshot and saves nothing', () => {
+  const saved = tree(1, { 1: { children: [2] }, 2: {} })
+  const dir = runDir(plan([{ id: '2', status: 'pending' }]), saved)
+  const fresh = tree(1, { 1: { children: [2, 3] }, 2: {}, 3: {} })
+  const live = syncRun(dir, { live: true, fetch: () => fresh, now: () => new Date('2026-10-12T00:00:00Z') })
+  assert.equal(live.source, 'live')
+  assert.deepEqual(actionsOf(live), ['add-unit 3'])
+  assert.equal(JSON.parse(readFileSync(join(dir, SNAPSHOT), 'utf8')).fetchedAt, '2026-10-12T00:00:00.000Z')
+  const down = syncRun(dir, { live: true, fetch: () => ({ root: 'o/r#1', complete: false, errors: [{ key: 'o/r#1', error: 'HTTP 502' }], nodes: {} }) })
+  assert.equal(down.source, 'snapshot')
+  assert.match(down.fetchError[0].error, /502/)
+  assert.deepEqual(actionsOf(down), ['add-unit 3'])
+  const offline = syncRun(dir, { fetch: () => { throw new Error('no call without --live') } })
+  assert.equal(offline.source, 'snapshot')
+})
+
+test('find-run picks the newest run whose spec or saved tree holds the issue', () => {
+  const runs = mkdtempSync(join(tmpdir(), 'plan-sync-runs-'))
+  const make = (name, body, snap, mtime) => {
+    mkdirSync(join(runs, name))
+    writeFileSync(join(runs, name, 'task-plan.json'), JSON.stringify(body))
+    if (snap) writeFileSync(join(runs, name, SNAPSHOT), JSON.stringify(snap))
+    utimesSync(join(runs, name, 'task-plan.json'), mtime, mtime)
+  }
+  make('old', plan([]), null, 1000)
+  make('followup', { spec: 'o/r#1512', units: [] }, tree(1512, { 1512: { children: [1343] }, 1343: {} }), 2000)
+  make('other', { spec: 'o/r#9', units: [] }, null, 3000)
+  assert.equal(findRun(runs, { repo: 'o/r', number: 1 }), join(runs, 'old'))
+  assert.equal(findRun(runs, { repo: 'o/r', number: 1343 }), join(runs, 'followup'))
+  assert.equal(findRun(runs, { repo: 'o/r', number: 77 }), null)
+})
+
+test('CLI exits 0 with or without actions and without a tree, 2 on bad input; --exit-actions restores the old codes', () => {
+  const dir = runDir(plan([{ id: '2', status: 'pending' }]), tree(1, { 1: { children: [2, 3] }, 2: {}, 3: {} }))
+  const due = spawnSync(process.execPath, [script, '--run', dir], { encoding: 'utf8' })
+  assert.equal(due.status, 0, due.stderr)
+  assert.match(due.stdout, /^add-unit +add unit 3/m)
+  assert.equal(JSON.parse(spawnSync(process.execPath, [script, '--run', dir, '--json'], { encoding: 'utf8' }).stdout).actions[0].action, 'add-unit')
+  assert.equal(spawnSync(process.execPath, [script, '--run', dir, '--exit-actions'], { encoding: 'utf8' }).status, 1)
+  const inSync = runDir(plan([{ id: '2', status: 'pending' }]), tree(1, { 1: { children: [2] }, 2: {} }))
+  assert.equal(spawnSync(process.execPath, [script, '--run', inSync], { encoding: 'utf8' }).status, 0)
+  assert.equal(spawnSync(process.execPath, [script, '--run', inSync, '--exit-actions'], { encoding: 'utf8' }).status, 0)
+  const noTree = runDir(plan([]))
+  const missing = spawnSync(process.execPath, [script, '--run', noTree], { encoding: 'utf8' })
+  assert.equal(missing.status, 0, missing.stderr)
+  assert.match(missing.stdout, /no issue tree available/)
+  assert.equal(JSON.parse(spawnSync(process.execPath, [script, '--run', noTree, '--json'], { encoding: 'utf8' }).stdout).missingTree, true)
+  assert.equal(spawnSync(process.execPath, [script, '--run', noTree, '--exit-actions'], { encoding: 'utf8' }).status, 2)
+  assert.equal(spawnSync(process.execPath, [script, '--run', join(noTree, 'nope')], { encoding: 'utf8' }).status, 2)
+  assert.equal(spawnSync(process.execPath, [script], { encoding: 'utf8' }).status, 2)
+  assert.throws(() => parseCliArgs(['--find-run', '--runs', 'x']), PlanSyncError)
+})
+
+test('--find-run exits 0 whether or not a run is found; --json and --exit-actions say which', () => {
+  const runs = mkdtempSync(join(tmpdir(), 'plan-sync-find-'))
+  const empty = (...extra) => spawnSync(process.execPath, [script, '--find-run', '--runs', runs, '--issue', 'o/r#77', ...extra], { encoding: 'utf8' })
+  const none = empty()
+  assert.equal(none.status, 0, none.stderr)
+  assert.equal(none.stdout, '', 'nothing on stdout when no run is found')
+  assert.deepEqual(JSON.parse(empty('--json').stdout), { found: false, dir: null })
+  assert.equal(empty('--exit-actions').status, 1)
+  mkdirSync(join(runs, 'one'))
+  writeFileSync(join(runs, 'one', 'task-plan.json'), JSON.stringify(plan([], { spec: 'o/r#77' })))
+  const found = empty('--json')
+  assert.equal(found.status, 0, found.stderr)
+  assert.deepEqual(JSON.parse(found.stdout), { found: true, dir: join(runs, 'one') })
+  assert.equal(empty('--exit-actions').status, 0)
+})