@stravica-ai/digital-operator-pa 0.1.69 → 0.1.71

package/dist/engineering-pa-cli/src/pa/status-board-cli.mjs

@@ -1,31 +1,44 @@
-// status-board-cli.mjs - argv router for `pa status set | patch | show`.
+// status-board-cli.mjs - argv router for `pa status set | patch | show |
+// lane | notice | done`.
 //
 // Bare `pa status` (no subverb) stays the environment probe in cli.mjs;
-// only the three subverbs below route here. Every write goes through
+// only the subverbs below route here. `lane`, `notice` and `done` write the
+// schema v2 sections (lanes, forMe, done); `patch --lane <key>` merges one
+// item into a lane, the seam any outside writer uses to feed a lane. Every write goes through
 // `writeBoardAtomic` in status-board.mjs: validated first, then a temp
 // file renamed over the board, so a refused or half-written board never
-// lands. The PA keeps the board current through these verbs and never
-// hand-edits the JSON.
+// lands. Every writer verb runs its read, change and write inside the
+// board lock (`withBoardLock`), the one `pa dispatch` and the workspace
+// dismiss route take too, so concurrent writers lose no change. The PA
+// keeps the board current through these verbs and never hand-edits the
+// JSON.
 
 import { getRepoRoot } from './repo-root.mjs';
 import {
+  BOARD_SCHEMA_VERSION,
   BoardError,
+  DONE_WINDOW_HOURS,
+  FOR_ME_KINDS,
+  MAIN_LANE_KEY,
+  MAIN_LANE_TITLE,
   STATUS_VALUES,
-  boardPath,
   boardRelPath,
   isValidAgentName,
   parseBoard,
   readBoard,
-  resolveAgentName,
+  isValidLaneKey,
+  resolveAgentBoard,
+  toBoardV2,
+  withBoardLock,
   writeBoardAtomic,
 } from './status-board.mjs';
 
-export const SUBVERBS = ['set', 'patch', 'show'];
+export const SUBVERBS = ['set', 'patch', 'show', 'lane', 'notice', 'done'];
 
 const USAGE = `pa status - environment probe, plus the daily status board subverbs
 
 Usage:
-  pa status <set|patch|show> --help   Show this help
+  pa status <set|patch|show|lane|notice|done> --help   Show this help
   pa status                       Probe operator content, installed package and workspace (unchanged)
   pa status set   [--file <path>] [--agent <name>]
                                   Replace the whole board from a JSON file, or stdin when --file is absent or "-"
@@ -36,21 +49,61 @@ Usage:
                   [--question "..."] [--options "a|b"] [--workstream "..."] [--remove]
                   [--add-done "<title>"]
                                   Merge one item or one on-me entry, set statuses, append to done
+  pa status patch --lane <key> (--id <id> | --match "<title>") [--lane-title "..."]
+                  [--title "..."] [--slot running|queued] [--after "<task>"] [--project "..."]
+                  [--status <status>] [--where "..."] [--stage "..."] [--note "..."]
+                  [--ids a,b] [--link <url>] [--started <iso>] [--estimate <iso>] [--remove]
+                                  Merge one item into a lane (the lanes seam); --status done moves it to done
   pa status show  [--agent <name>] [--json]
                                   Print the board
+  pa status lane  --key <key> [--agent <name>] [--title "..."] [--paused | --resume]
+                  [--file <path>] [--remove]
+                                  Add or change a lane; --file (or "-" for stdin) replaces its
+                                  running item and queue from { title?, state?, running?, queued? }
+  pa status notice [--agent <name>] [--id <id>] [--kind Risk|Money|Security] [--text "..."]
+                  [--link <url>] [--dismiss | --undismiss | --remove]
+                                  Add or change one For-me notice (risk, money or security only)
+  pa status done  [--agent <name>] (--id <id> | --title "...") [--ids a,b] [--project "..."]
+                  [--note "..."] [--ended <iso>] | --prune
+                                  Move the lane item or open group item holding the id to done
+                                  (--id), add a done entry (--title), or drop done entries older
+                                  than ${DONE_WINDOW_HOURS} hours (--prune)
 
 Notes:
   - The board is agents/<agent>/workspace/status-board.json. The agent comes
     from --agent, else preferences.json paName, else the single agents/*
-    folder holding next-session.md, else "dave".
+    folder holding next-session.md, else "dave". Whichever way it comes, it
+    must be an agent folder name and the board must lie inside its
+    workspace folder (no symlink out); otherwise the verb exits 1 and reads
+    and writes nothing.
   - Every write stamps the board's updatedAt from the clock, is validated
     against the schema and lands atomically (temp file, then rename).
-  - Status values: ${STATUS_VALUES.join(' | ')}. The legacy key and status
-    "onBaz" are read as "onMe" and written as "onMe".
+  - Writers take one lock beside the board (status-board.json.lock), the
+    same one pa dispatch and the workspace take; a write that cannot get it
+    within a few seconds exits 2 and writes nothing.
+  - An option's value never starts with "--": "--link --dismiss" and
+    "--link=--dismiss" are usage errors. --started, --estimate and --ended
+    take an ISO 8601 date-time with a zone on a real calendar date, like
+    2030-01-15T09:30:00Z or 2030-01-15T09:30:00+01:00.
+  - Status values: ${STATUS_VALUES.join(' | ')}. The legacy on-me key and
+    its status value are read as "onMe" and written as "onMe".
   - patch --id matches items (or with --on-me, on-me entries) whose ids hold
     the id; --match matches the exact title (or question). More than one
     match is refused. No match creates the entry (an item needs --group).
+  - On a lane item or a group item, --ids with --id X keeps X in the ids:
+    the list as given when it holds X, else X first and then the list, so
+    a later --id X still finds the item.
   - --status done also appends the item to the done list.
+  - Lanes: a lane key is a lowercase slug. The "${MAIN_LANE_KEY}" lane is always shown,
+    first; any other lane a writer adds is shown after it, in board order.
+    A lane with no running item and an empty queue reads as idle.
+  - patch --lane: no match adds the item (queued last, or as the running
+    item with --slot running); a lane that does not exist yet is added.
+    --slot running is refused while the lane already has a running item.
+  - Writing a lane or a notice, done and done --prune make the board schema
+    v${BOARD_SCHEMA_VERSION}; v1 groups stay.
+  - notice: with no --id a new notice gets one from the clock; a new notice
+    needs --kind and --text. Kinds: ${FOR_ME_KINDS.join(' | ')}.
 
 Exit codes:
   0 ok | 1 usage error or schema refusal | 2 operational failure | 3 IO failure
@@ -69,9 +122,13 @@ const FLAGS = {
   patch: [
     'agent', 'headline', 'id', 'match', 'on-me', 'title', 'status', 'where', 'stage', 'note',
     'ids', 'link', 'group', 'question', 'options', 'workstream', 'remove', 'add-done',
+    'lane', 'lane-title', 'slot', 'after', 'project', 'started', 'estimate',
   ],
+  lane: ['agent', 'key', 'title', 'paused', 'resume', 'file', 'remove'],
+  notice: ['agent', 'id', 'kind', 'text', 'link', 'dismiss', 'undismiss', 'remove'],
+  done: ['agent', 'id', 'title', 'ids', 'project', 'note', 'ended', 'prune'],
 };
-const BOOLEAN_FLAGS = new Set(['json', 'on-me', 'remove']);
+const BOOLEAN_FLAGS = new Set(['json', 'on-me', 'remove', 'paused', 'resume', 'dismiss', 'undismiss', 'prune']);
 
 /**
  * @param {string[]} argv  subverb and its flags (argv after `status`)
@@ -86,11 +143,13 @@ export async function run(argv, opts = {}) {
     if (!SUBVERBS.includes(verb)) throw new UsageError('unknown subverb: ' + verb);
     const flags = parseFlags(argv.slice(1), FLAGS[verb]);
     const repoRoot = opts.repoRoot ?? await getRepoRoot();
-    const agent = pickAgent(flags.agent, repoRoot);
-    const file = boardPath(repoRoot, agent);
+    const { agent, file } = pickBoard(flags.agent, repoRoot);
     const ctx = { repoRoot, agent, file, flags, out, err, now: opts.now ?? (() => new Date()), stdin: opts.stdin };
     if (verb === 'set') return await doSet(ctx);
     if (verb === 'patch') return await doPatch(ctx);
+    if (verb === 'lane') return await doLane(ctx);
+    if (verb === 'notice') return await doNotice(ctx);
+    if (verb === 'done') return await doDone(ctx);
     return await doShow(ctx);
   } catch (e) {
     if (e instanceof BoardError) {
@@ -104,7 +163,7 @@ export async function run(argv, opts = {}) {
   }
 }
 
-function parseFlags(args, allowed) {
+export function parseFlags(args, allowed) {
   const flags = {};
   for (let i = 0; i < args.length; i++) {
     const a = args[i];
@@ -117,25 +176,54 @@ function parseFlags(args, allowed) {
       flags[key] = true;
       continue;
     }
-    if (eq !== -1) { flags[key] = a.slice(eq + 1); continue; }
+    if (eq !== -1) {
+      const v = a.slice(eq + 1);
+      if (v.startsWith('--')) throw new UsageError('--' + key + ' needs a value, got the option ' + v + '; nothing written');
+      flags[key] = v;
+      continue;
+    }
     const v = args[i + 1];
     if (v === undefined) throw new UsageError('--' + key + ' needs a value');
+    if (v.startsWith('--')) throw new UsageError('--' + key + ' needs a value, got the option ' + v + '; nothing written');
     flags[key] = v;
     i += 1;
   }
   return flags;
 }
 
-function pickAgent(flag, repoRoot) {
-  if (flag === undefined) return resolveAgentName(repoRoot);
-  if (!isValidAgentName(flag)) throw new UsageError('--agent must be a lowercase agent folder name, got "' + flag + '"');
-  return flag;
+/**
+ * The agent and its board file, through the one resolver every board reader
+ * and writer uses (resolveAgentBoard): --agent when given, else the
+ * configured agent. A bad name or a board path that leads out of
+ * agents/<agent>/workspace/ is a usage error (exit 1) before anything is
+ * read or written.
+ */
+function pickBoard(flag, repoRoot) {
+  if (flag !== undefined && !isValidAgentName(flag)) throw new UsageError('--agent must be a lowercase agent folder name, got "' + flag + '"');
+  const r = resolveAgentBoard(repoRoot, flag);
+  if (!r.ok) {
+    const from = flag === undefined ? ' (the agent from preferences)' : '';
+    throw new UsageError(r.message + from + ', got "' + r.agent + '"; nothing was read or written');
+  }
+  return r;
 }
 
 function stamp(now) {
   return now().toISOString().replace(/\.\d{3}Z$/, 'Z');
 }
 
+/**
+ * Run a verb's read, change and write inside the board lock. The resolver's
+ * fence is checked again once the lock is held, so the path cannot have
+ * been swapped for a symlink in between.
+ */
+function locked(ctx, fn) {
+  return withBoardLock(ctx.file, () => {
+    pickBoard(ctx.flags.agent, ctx.repoRoot);
+    return fn();
+  });
+}
+
 async function readStdin(given) {
   if (typeof given === 'string') return given;
   const chunks = [];
@@ -163,8 +251,10 @@ async function doSet(ctx) {
   if (board === null || typeof board !== 'object' || Array.isArray(board)) {
     throw new BoardError(['board must be a JSON object']);
   }
-  board.updatedAt = stamp(ctx.now);
-  const written = await writeBoardAtomic(ctx.file, withDefaults(board));
+  const written = await locked(ctx, () => {
+    board.updatedAt = stamp(ctx.now);
+    return writeBoardAtomic(ctx.file, withDefaults(board));
+  });
   ctx.out.write('Board set for ' + ctx.agent + ' at ' + boardRelPath(ctx.agent) + ' (' + counts(written) + ').\n');
   return 0;
 }
@@ -174,7 +264,8 @@ async function doSet(ctx) {
 function withDefaults(board) {
   const { updatedAt, ...rest } = board;
   const out = { updatedAt, ...rest };
-  for (const k of ['onMe', 'groups', 'done']) {
+  const keys = out.schemaVersion === BOARD_SCHEMA_VERSION ? ['onMe', 'forMe', 'lanes', 'done'] : ['onMe', 'groups', 'done'];
+  for (const k of keys) {
     if (out[k] === undefined && !(k === 'onMe' && 'onBaz' in out)) out[k] = [];
   }
   return out;
@@ -201,6 +292,11 @@ async function doShow(ctx) {
   lines.push('On me (' + onMe.length + ')');
   if (!onMe.length) lines.push('  nothing');
   for (const a of onMe) lines.push('  - ' + a.question + idsSuffix(a.ids));
+  if (b.schemaVersion === BOARD_SCHEMA_VERSION) {
+    showV2(toBoardV2(b), lines);
+    ctx.out.write(lines.join('\n') + '\n');
+    return 0;
+  }
   for (const g of b.groups || []) {
     lines.push('');
     lines.push(g.label || 'Untitled workstream');
@@ -216,11 +312,37 @@ async function doShow(ctx) {
   return 0;
 }
 
+function showV2(v2, lines) {
+  const notices = v2.forMe.filter((n) => !n.dismissedAt);
+  lines.push('');
+  lines.push('For me (' + notices.length + ')');
+  if (!notices.length) lines.push('  nothing');
+  for (const n of notices) lines.push('  - [' + n.kind + '] ' + n.text + ' (' + n.id + ')');
+  for (const l of v2.lanes) {
+    lines.push('');
+    lines.push(l.title + ' [' + l.key + ']' + (l.state === 'paused' ? ' (paused)' : ''));
+    if (!l.running && !l.queued.length) lines.push('  ' + (l.state === 'paused' ? 'lane paused' : 'lane idle'));
+    if (l.running) lines.push('  [running] ' + l.running.title + idsSuffix(l.running.ids));
+    for (const it of l.queued) {
+      lines.push('  [' + (it.status || 'queued') + '] ' + it.title + idsSuffix(it.ids) + (it.after ? '  after ' + it.after : ''));
+    }
+  }
+  lines.push('');
+  lines.push('Done, last ' + DONE_WINDOW_HOURS + ' hours (' + v2.done.length + ')');
+  for (const it of v2.done) lines.push('  - ' + it.title + idsSuffix(it.ids));
+}
+
 function idsSuffix(ids) {
   return Array.isArray(ids) && ids.length ? ' (' + ids.join(', ') + ')' : '';
 }
 
 function counts(b) {
+  if (b.schemaVersion === BOARD_SCHEMA_VERSION) {
+    const lanes = b.lanes || [];
+    const items = lanes.reduce((n, l) => n + (l.running ? 1 : 0) + (l.queued || []).length, 0);
+    return lanes.length + ' lanes, ' + items + ' items, ' + (b.onMe || []).length + ' on me, '
+      + (b.forMe || []).length + ' for me, ' + (b.done || []).length + ' done';
+  }
   const items = (b.groups || []).reduce((n, g) => n + g.items.length, 0);
   return (b.groups || []).length + ' groups, ' + items + ' items, ' + (b.onMe || []).length + ' on me, ' + (b.done || []).length + ' done';
 }
@@ -242,8 +364,13 @@ async function loadExisting(ctx, opts) {
 const ITEM_FIELDS = ['title', 'status', 'where', 'stage', 'note', 'link'];
 const ASK_FIELDS = ['question', 'workstream', 'link'];
 
+const LANE_ITEM_FLAGS = ['lane-title', 'slot', 'after', 'project', 'started', 'estimate'];
+
 async function doPatch(ctx) {
   const f = ctx.flags;
+  if (f.lane !== undefined) return doPatchLane(ctx);
+  const strayLane = LANE_ITEM_FLAGS.find((k) => f[k] !== undefined);
+  if (strayLane) throw new UsageError('--' + strayLane + ' applies to lane items; give --lane <key>');
   const hasTarget = f.id !== undefined || f.match !== undefined;
   if (f.id !== undefined && f.match !== undefined) throw new UsageError('give --id or --match, not both');
   if (!hasTarget) {
@@ -264,26 +391,28 @@ async function doPatch(ctx) {
     if (bad) throw new UsageError('--' + bad + ' applies to --on-me entries');
   }
 
-  const parsed = await loadExisting(ctx, { strictStatus: true });
-  if (parsed.problems.length) throw new OpError('board on disk is invalid; fix it with `pa status set`:\n  - ' + parsed.problems.join('\n  - '));
-  const board = structuredClone(parsed.board);
-  board.onMe = board.onMe || [];
-  board.groups = board.groups || [];
-  board.done = board.done || [];
-  const now = stamp(ctx.now);
-  const notes = [];
-
-  if (f.headline !== undefined) { board.headline = f.headline; notes.push('headline set'); }
-  if (hasTarget) notes.push(f['on-me'] ? patchAsk(board, f, now) : patchItem(board, f, now));
-  if (f['add-done'] !== undefined) {
-    board.done.push(doneEntry({ title: f['add-done'], ids: splitList(f.ids, ',') || [] }, f.workstream, now));
-    notes.push('done entry added');
-  }
+  return locked(ctx, async () => {
+    const parsed = await loadExisting(ctx, { strictStatus: true });
+    if (parsed.problems.length) throw new OpError('board on disk is invalid; fix it with `pa status set`:\n  - ' + parsed.problems.join('\n  - '));
+    const board = structuredClone(parsed.board);
+    board.onMe = board.onMe || [];
+    board.groups = board.groups || [];
+    board.done = board.done || [];
+    const now = stamp(ctx.now);
+    const notes = [];
+
+    if (f.headline !== undefined) { board.headline = f.headline; notes.push('headline set'); }
+    if (hasTarget) notes.push(f['on-me'] ? patchAsk(board, f, now) : patchItem(board, f, now));
+    if (f['add-done'] !== undefined) {
+      board.done.push(doneEntry({ title: f['add-done'], ids: splitList(f.ids, ',') || [] }, f.workstream, now));
+      notes.push('done entry added');
+    }
 
-  board.updatedAt = now;
-  await writeBoardAtomic(ctx.file, board);
-  ctx.out.write('Board patched for ' + ctx.agent + ': ' + notes.join('; ') + '.\n');
-  return 0;
+    board.updatedAt = now;
+    await writeBoardAtomic(ctx.file, board);
+    ctx.out.write('Board patched for ' + ctx.agent + ': ' + notes.join('; ') + '.\n');
+    return 0;
+  });
 }
 
 function normaliseStatusValue(s) {
@@ -316,7 +445,7 @@ function patchItem(board, f, now) {
     if (f.group === undefined) throw new UsageError('no item matches; to add one, give --group');
     const title = f.title ?? f.match;
     if (title === undefined) throw new UsageError('no item matches --id ' + f.id + '; to add one, give --title and --group');
-    const ids = mergeIds(splitList(f.ids, ',') || [], f.id);
+    const ids = keepIdFirst(splitList(f.ids, ',') || [], f.id);
     const item = {
       title,
       status: normaliseStatusValue(f.status ?? 'queued'),
@@ -343,7 +472,7 @@ function patchItem(board, f, now) {
   for (const k of ITEM_FIELDS) {
     if (f[k] !== undefined) item[k] = k === 'status' ? normaliseStatusValue(f[k]) : f[k];
   }
-  if (f.ids !== undefined) item.ids = splitList(f.ids, ',');
+  if (f.ids !== undefined) item.ids = keepIdFirst(splitList(f.ids, ','), f.id);
   item.updatedAt = now;
   let label = fromGroup.label;
   if (f.group !== undefined && f.group !== fromGroup.label) {
@@ -397,6 +526,18 @@ function mergeIds(ids, id) {
   return ids;
 }
 
+/**
+ * The ids of a lane item or a group item written with --ids: the list as
+ * given when it holds the --id, or the --id first and then the list when it
+ * does not, so a later --id still finds the item. With no --id (a --match
+ * write), the list as given. On-me and done entries keep mergeIds.
+ */
+export function keepIdFirst(ids, id) {
+  const list = Array.isArray(ids) ? ids : [];
+  if (id === undefined || list.includes(id)) return list;
+  return [id, ...list];
+}
+
 function groupFor(board, label) {
   let g = board.groups.find((x) => x.label === label);
   if (!g) {
@@ -423,3 +564,350 @@ function addDoneOnce(board, item, workstream, now) {
   if (board.done.some((d) => d.title === item.title)) return;
   board.done.push(doneEntry(item, workstream, now));
 }
+
+// -- schema v2 writes -----------------------------------------------------
+
+/** Load the board for a v2 write: valid on disk, cloned, v2 sections present. */
+async function loadForV2Write(ctx) {
+  const parsed = await loadExisting(ctx, { strictStatus: true });
+  if (parsed.problems.length) throw new OpError('board on disk is invalid; fix it with `pa status set`:\n  - ' + parsed.problems.join('\n  - '));
+  return asV2(structuredClone(parsed.board));
+}
+
+/**
+ * The board on disk made schema v2 for a write: schemaVersion first, then
+ * the keys as they were, with onMe, forMe, lanes and done present. v1
+ * groups are kept as they are.
+ */
+export function asV2(board) {
+  const { schemaVersion: _v, ...rest } = board;
+  const out = { schemaVersion: BOARD_SCHEMA_VERSION, ...rest };
+  for (const k of ['onMe', 'forMe', 'lanes', 'done']) if (!Array.isArray(out[k])) out[k] = [];
+  return out;
+}
+
+async function writeV2(ctx, board, note) {
+  board.updatedAt = stamp(ctx.now);
+  await writeBoardAtomic(ctx.file, board);
+  ctx.out.write('Board patched for ' + ctx.agent + ': ' + note + '.\n');
+  return 0;
+}
+
+function needKey(key, flag) {
+  if (key === undefined) throw new UsageError(flag + ' is required');
+  if (!isValidLaneKey(key)) throw new UsageError(flag + ' must be a lowercase slug (letters, digits, hyphens), got "' + key + '"');
+  return key;
+}
+
+/** The lane with this key, added (last; main first) when the board has none. */
+function laneFor(board, key, title) {
+  let lane = board.lanes.find((l) => l.key === key);
+  if (!lane) {
+    lane = { key, title: title ?? (key === MAIN_LANE_KEY ? MAIN_LANE_TITLE : key), queued: [] };
+    if (key === MAIN_LANE_KEY) board.lanes.unshift(lane);
+    else board.lanes.push(lane);
+  }
+  if (!Array.isArray(lane.queued)) lane.queued = [];
+  return lane;
+}
+
+// An ISO 8601 date-time with a zone: date, T, hours and minutes (seconds
+// and a fraction optional), then Z or a +hh:mm or -hh:mm offset.
+const ISO_DATE_TIME_RE = /^(\d{4})-(0[1-9]|1[0-2])-(0[1-9]|[12]\d|3[01])T([01]\d|2[0-3]):([0-5]\d)(?::([0-5]\d)(\.\d+)?)?(Z|([+-])([01]\d|2[0-3]):([0-5]\d))$/;
+
+/**
+ * An ISO 8601 date-time with a zone on a real calendar date. Date.parse
+ * alone rolls 2030-02-31 over into March, so the parsed instant is moved
+ * back into the input's own offset and its year, month, day, hour, minute
+ * and second must read back as the input's.
+ */
+export function isIsoDateTime(v) {
+  if (typeof v !== 'string') return false;
+  const m = ISO_DATE_TIME_RE.exec(v);
+  if (!m) return false;
+  const ms = Date.parse(v);
+  if (Number.isNaN(ms)) return false;
+  const offsetMin = m[8] === 'Z' ? 0 : (m[9] === '-' ? -1 : 1) * (Number(m[10]) * 60 + Number(m[11]));
+  const local = new Date(ms + offsetMin * 60_000);
+  return local.getUTCFullYear() === Number(m[1])
+    && local.getUTCMonth() + 1 === Number(m[2])
+    && local.getUTCDate() === Number(m[3])
+    && local.getUTCHours() === Number(m[4])
+    && local.getUTCMinutes() === Number(m[5])
+    && local.getUTCSeconds() === Number(m[6] ?? 0);
+}
+
+function checkIsoFlag(v, flag) {
+  if (v !== undefined && !isIsoDateTime(v)) {
+    throw new UsageError(flag + ' must be an ISO timestamp: an ISO 8601 date-time with a zone on a real calendar date, like 2030-01-15T09:30:00Z; got "' + v + '"');
+  }
+}
+
+/** Every item held in a lane (running or queued) that the --id or --match picks. */
+function laneHits(board, f) {
+  const hits = [];
+  for (const lane of board.lanes) {
+    const test = (it) => (f.id !== undefined
+      ? Array.isArray(it.ids) && it.ids.includes(f.id)
+      : String(it.title).trim() === String(f.match).trim());
+    if (lane.running && test(lane.running)) hits.push({ lane, slot: 'running', item: lane.running });
+    (lane.queued || []).forEach((it, i) => { if (test(it)) hits.push({ lane, slot: 'queued', index: i, item: it }); });
+  }
+  return hits;
+}
+
+function takeOut(hit) {
+  if (hit.slot === 'running') delete hit.lane.running;
+  else hit.lane.queued.splice(hit.lane.queued.indexOf(hit.item), 1);
+}
+
+/**
+ * Every open group item (status anything but done) holding the id: the
+ * items the read side carries into Main when no lane holds them.
+ */
+function openGroupHits(board, id) {
+  const hits = [];
+  for (const group of Array.isArray(board.groups) ? board.groups : []) {
+    for (const item of Array.isArray(group.items) ? group.items : []) {
+      if (item.status !== 'done' && Array.isArray(item.ids) && item.ids.includes(id)) hits.push({ group, item });
+    }
+  }
+  return hits;
+}
+
+async function doPatchLane(ctx) {
+  const f = ctx.flags;
+  const key = needKey(f.lane, '--lane');
+  if (f.id !== undefined && f.match !== undefined) throw new UsageError('give --id or --match, not both');
+  if (f.id === undefined && f.match === undefined) throw new UsageError('patch --lane needs a target (--id or --match)');
+  const bad = ['on-me', 'group', 'question', 'options', 'add-done', 'headline', 'workstream'].find((k) => f[k] !== undefined);
+  if (bad) throw new UsageError('--' + bad + ' does not apply with --lane');
+  if (f.slot !== undefined && !['running', 'queued'].includes(f.slot)) throw new UsageError('--slot must be running or queued');
+  if (f.status !== undefined && !STATUS_VALUES.includes(normaliseStatusValue(f.status))) {
+    throw new UsageError('--status must be one of ' + STATUS_VALUES.join(', '));
+  }
+  checkIsoFlag(f.started, '--started');
+  checkIsoFlag(f.estimate, '--estimate');
+  return locked(ctx, () => patchLaneLocked(ctx, key));
+}
+
+async function patchLaneLocked(ctx, key) {
+  const f = ctx.flags;
+  const board = await loadForV2Write(ctx);
+  const now = stamp(ctx.now);
+  const hits = laneHits(board, f);
+  if (hits.length > 1) throw refusal(hits, (h) => '"' + h.item.title + '" in lane ' + h.lane.key + ' (' + h.slot + ')');
+  let hit = hits[0];
+  if (f.remove) {
+    if (!hit) throw new OpError('no lane item matches; nothing to remove');
+    takeOut(hit);
+    return writeV2(ctx, board, 'item "' + hit.item.title + '" removed from lane ' + hit.lane.key);
+  }
+  const lane = laneFor(board, key, f['lane-title']);
+  if (f['lane-title'] !== undefined) lane.title = f['lane-title'];
+
+  let note;
+  if (!hit) {
+    const title = f.title ?? f.match;
+    if (title === undefined) throw new UsageError('no item in lane ' + key + ' matches --id ' + f.id + '; to add one, give --title');
+    const item = { title, ids: keepIdFirst(splitList(f.ids, ',') || [], f.id) };
+    hit = { lane, slot: null, item };
+    note = 'item "' + title + '" added to lane ' + key;
+  } else if (hit.lane !== lane) {
+    note = 'item "' + hit.item.title + '" moved from lane ' + hit.lane.key + ' to lane ' + key;
+    takeOut(hit);
+    hit = { lane, slot: null, item: hit.item };
+  } else {
+    note = 'item "' + hit.item.title + '" updated in lane ' + key;
+  }
+
+  const item = hit.item;
+  for (const k of ['title', 'where', 'stage', 'note', 'link', 'after', 'project']) if (f[k] !== undefined) item[k] = f[k];
+  if (f.status !== undefined) item.status = normaliseStatusValue(f.status);
+  if (f.ids !== undefined && hits.length) item.ids = keepIdFirst(splitList(f.ids, ','), f.id);
+  if (f.started !== undefined) item.startedAt = f.started;
+  if (f.estimate !== undefined) item.estimatedFinishAt = f.estimate;
+  item.updatedAt = now;
+
+  if (item.status === 'done') {
+    if (hit.slot !== null) takeOut(hit);
+    const entry = { ...item, endedAt: item.endedAt ?? now };
+    delete entry.after;
+    if (!board.done.some((d) => d.title === entry.title && sameIds(d.ids, entry.ids))) board.done.push(entry);
+    return writeV2(ctx, board, note + '; moved to done');
+  }
+
+  const slot = f.slot ?? hit.slot ?? 'queued';
+  if (slot !== hit.slot) {
+    if (slot === 'running' && lane.running && lane.running !== item) {
+      throw new OpError('lane ' + key + ' already has a running item ("' + lane.running.title + '"); move it on first');
+    }
+    if (hit.slot !== null) takeOut(hit);
+    if (slot === 'running') {
+      delete item.after;
+      if (item.startedAt === undefined) item.startedAt = now;
+      lane.running = item;
+    } else {
+      lane.queued.push(item);
+    }
+  }
+  return writeV2(ctx, board, note);
+}
+
+function sameIds(a, b) {
+  return JSON.stringify(a || []) === JSON.stringify(b || []);
+}
+
+/** The JSON a `pa status lane --file` reads: { title?, state?, running?, queued? }. */
+export function parseLaneFile(text) {
+  let body;
+  try { body = JSON.parse(text); } catch (e) { throw new UsageError('lane file is not valid JSON: ' + e.message); }
+  if (body === null || typeof body !== 'object' || Array.isArray(body)) throw new UsageError('lane file must be a JSON object');
+  const extra = Object.keys(body).filter((k) => !['title', 'state', 'running', 'queued'].includes(k));
+  if (extra.length) throw new UsageError('lane file key "' + extra[0] + '" is not one of title, state, running, queued');
+  return body;
+}
+
+async function doLane(ctx) {
+  const f = ctx.flags;
+  const key = needKey(f.key, '--key');
+  if (f.paused && f.resume) throw new UsageError('give --paused or --resume, not both');
+  if (f.remove && Object.keys(f).some((k) => !['agent', 'key', 'remove'].includes(k))) {
+    throw new UsageError('--remove takes no other lane flag');
+  }
+  let fromFile;
+  if (f.file !== undefined) {
+    let text;
+    if (f.file === '-') text = await readStdin(ctx.stdin);
+    else {
+      const { readFile } = await import('node:fs/promises');
+      text = await readFile(f.file, 'utf8');
+    }
+    fromFile = parseLaneFile(text);
+  }
+  return locked(ctx, () => laneLocked(ctx, key, fromFile));
+}
+
+async function laneLocked(ctx, key, fromFile) {
+  const f = ctx.flags;
+  const board = await loadForV2Write(ctx);
+  if (f.remove) {
+    const i = board.lanes.findIndex((l) => l.key === key);
+    if (i === -1) throw new OpError('no lane ' + key + ' on the board; nothing to remove');
+    board.lanes.splice(i, 1);
+    return writeV2(ctx, board, 'lane ' + key + ' removed');
+  }
+  const existed = board.lanes.some((l) => l.key === key);
+  const lane = laneFor(board, key, f.title ?? (fromFile && fromFile.title));
+  if (fromFile) {
+    if (fromFile.title !== undefined) lane.title = fromFile.title;
+    if (fromFile.state === undefined || fromFile.state === null) delete lane.state;
+    else lane.state = fromFile.state;
+    if (fromFile.running === undefined || fromFile.running === null) delete lane.running;
+    else lane.running = fromFile.running;
+    lane.queued = fromFile.queued === undefined ? [] : fromFile.queued;
+  }
+  if (f.title !== undefined) lane.title = f.title;
+  if (f.paused) lane.state = 'paused';
+  if (f.resume) delete lane.state;
+  return writeV2(ctx, board, 'lane ' + key + (existed ? ' updated' : ' added'));
+}
+
+function noticeId(now) {
+  return 'n-' + now().toISOString().replace(/[-:]/g, '').replace(/\.\d{3}Z$/, 'Z').replace('T', '-').toLowerCase();
+}
+
+async function doNotice(ctx) {
+  const f = ctx.flags;
+  const actions = ['dismiss', 'undismiss', 'remove'].filter((k) => f[k]);
+  if (actions.length > 1) throw new UsageError('give one of --dismiss, --undismiss, --remove');
+  if (f.kind !== undefined && !FOR_ME_KINDS.includes(f.kind)) {
+    throw new UsageError('--kind must be one of ' + FOR_ME_KINDS.join(', ') + ' (For me is for risk, money or security only)');
+  }
+  if (actions.length && f.id === undefined) throw new UsageError('--' + actions[0] + ' needs --id');
+  return locked(ctx, () => noticeLocked(ctx, actions));
+}
+
+async function noticeLocked(ctx, actions) {
+  const f = ctx.flags;
+  const board = await loadForV2Write(ctx);
+  const now = stamp(ctx.now);
+  const notice = f.id === undefined ? undefined : board.forMe.find((n) => n.id === f.id);
+  if (!notice) {
+    if (actions.length) throw new OpError('no For-me notice with id ' + f.id);
+    if (f.kind === undefined || f.text === undefined) throw new UsageError('a new notice needs --kind and --text');
+    const id = f.id ?? noticeId(ctx.now);
+    const n = { id, kind: f.kind, text: f.text };
+    if (f.link !== undefined) n.link = f.link;
+    board.forMe.push(n);
+    return writeV2(ctx, board, 'notice ' + id + ' added');
+  }
+  if (f.remove) {
+    board.forMe.splice(board.forMe.indexOf(notice), 1);
+    return writeV2(ctx, board, 'notice ' + f.id + ' removed');
+  }
+  for (const k of ['kind', 'text', 'link']) if (f[k] !== undefined) notice[k] = f[k];
+  if (f.dismiss && !notice.dismissedAt) notice.dismissedAt = now;
+  if (f.undismiss) delete notice.dismissedAt;
+  return writeV2(ctx, board, 'notice ' + f.id + (f.dismiss ? ' dismissed' : f.undismiss ? ' shown again' : ' updated'));
+}
+
+async function doDone(ctx) {
+  const f = ctx.flags;
+  if (f.prune) {
+    const other = Object.keys(f).filter((k) => !['agent', 'prune'].includes(k));
+    if (other.length) throw new UsageError('--prune takes no other flag');
+  } else {
+    if (f.id === undefined && f.title === undefined) throw new UsageError('done needs --id, --title or --prune');
+  }
+  checkIsoFlag(f.ended, '--ended');
+  return locked(ctx, () => doneLocked(ctx));
+}
+
+/**
+ * done --id moves the item holding the id: the lane item, else the open
+ * group item a v1 board (or a group item no lane holds) puts in Main. Every
+ * open group item holding the id leaves its group too, so nothing holding
+ * it is carried back into Main; the item lands in done once.
+ */
+async function doneLocked(ctx) {
+  const f = ctx.flags;
+  const board = await loadForV2Write(ctx);
+  const now = stamp(ctx.now);
+  if (f.prune) {
+    const before = board.done.length;
+    board.done = toBoardV2({ ...board, updatedAt: now }).done;
+    return writeV2(ctx, board, (before - board.done.length) + ' done entries older than ' + DONE_WINDOW_HOURS + ' hours dropped');
+  }
+  const hits = f.id === undefined ? [] : laneHits(board, { id: f.id });
+  if (hits.length > 1) throw refusal(hits, (h) => '"' + h.item.title + '" in lane ' + h.lane.key);
+  const groupHits = f.id === undefined ? [] : openGroupHits(board, f.id);
+  if (!hits.length && groupHits.length > 1) {
+    throw refusal(groupHits, (h) => '"' + h.item.title + '" in group ' + (h.group.label || 'with no label'));
+  }
+  let entry;
+  let from;
+  if (hits.length || groupHits.length) {
+    if (hits.length) takeOut(hits[0]);
+    for (const h of groupHits) h.group.items.splice(h.group.items.indexOf(h.item), 1);
+    const base = hits.length ? hits[0].item : groupHits[0].item;
+    entry = { ...base };
+    delete entry.after;
+    entry.status = 'done';
+    if (!hits.length && typeof groupHits[0].group.label === 'string' && groupHits[0].group.label && entry.workstream === undefined) {
+      entry.workstream = groupHits[0].group.label;
+    }
+    from = hits.length ? 'lane ' + hits[0].lane.key : 'group ' + (groupHits[0].group.label || 'with no label');
+  } else {
+    if (f.title === undefined) throw new OpError('no lane item or open group item holds ' + f.id + '; to add a done entry, give --title');
+    entry = { title: f.title, status: 'done', ids: mergeIds(splitList(f.ids, ',') || [], f.id) };
+  }
+  if (f.title !== undefined) entry.title = f.title;
+  if (f.project !== undefined) entry.project = f.project;
+  if (f.note !== undefined) entry.note = f.note;
+  if (f.ids !== undefined && from) entry.ids = splitList(f.ids, ',');
+  entry.endedAt = f.ended ?? now;
+  entry.updatedAt = now;
+  board.done.push(entry);
+  return writeV2(ctx, board, '"' + entry.title + '" ' + (from ? 'moved from ' + from + ' to done' : 'added to done'));
+}