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

package/dist/engineering-pa-cli/bin/pa

@@ -1,2 +1,19 @@
 #!/usr/bin/env node
-import('../src/pa/cli.mjs').then(async (m) => process.exit(await m.main(process.argv.slice(2))));
+// Each verb returns its exit code; the process ends only once stdout and
+// stderr have taken every byte. A write to a pipe is asynchronous on some
+// platforms, so a process.exit straight after main returned cut a long
+// output at the pipe's buffer (a board piped to `wc -c` gave 65536 bytes).
+// An empty write's callback runs after every write queued before it, and
+// process.exit then still ends a verb that left a handle open.
+import('../src/pa/cli.mjs').then(async (m) => {
+  const code = await m.main(process.argv.slice(2));
+  process.exitCode = code;
+  let open = 2;
+  const flushed = () => { open -= 1; if (open === 0) process.exit(code); };
+  for (const stream of [process.stdout, process.stderr]) {
+    // A reader that closes early (EPIPE) must not turn into a crash.
+    stream.on('error', () => {});
+    let called = false;
+    stream.write('', () => { if (!called) { called = true; flushed(); } });
+  }
+});

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

@@ -6,13 +6,16 @@
 // when the instance keeps initiatives records, with the open questions under
 // initiatives/<id>/questions/. It writes nothing anywhere: no cache, no lock.
 // It reads the spawn-log's lock file (agents/<agent>/spawn-log.json.lock) and
-// never writes, breaks or sweeps it.
+// the board's lock file (the board path plus .lock) and never writes, breaks
+// or sweeps either.
 //
 // One problem line each for:
 //   - the board's updatedAt 90 minutes old or more (the Status page's red
 //     threshold) while a dispatch is open, or no board at all while one is;
-//   - an open dispatch with no board item (an item in groups[].items[] whose
-//     ids holds the dispatch id; a mention in a title does not count);
+//   - an open dispatch with no board item (an item in groups[].items[], or
+//     on a schema v2 board a lane's running item or one of its queued items,
+//     any lane, paused or not, whose ids holds the dispatch id; a mention in
+//     a title does not count, nor an id held only by onMe, forMe or done);
 //   - an open dispatch that has been open 24 to 48 hours (close it or check it);
 //   - the spawn-log lock held for longer than the stale window
 //     (LOCK_STALE_AFTER_MS, one minute): the line leads with
@@ -31,6 +34,14 @@
 // `unrecognised status` warnings: the human output gives one line per word
 // with its count and at most five ids, `--json` lists every one. They never
 // change the exit code.
+// A board lock held by a live pid on this host whose lock file is more than
+// BOARD_LOCK_LONG_HELD_MS (10 minutes) old by the check's clock is one more
+// warning: one line naming the board, the pid, the age and the manual clear
+// (`rm <lock path>` once the pid is checked not to be a board writer), the
+// `boardLockWarning` object in `--json` (present only when it fires) and a
+// warning line in `--hook-envelope`. Such a lock is never broken, by the
+// check or by a writer. A foreign-host or ownerless board lock gives no
+// warning: the next writer breaks it as stale after BOARD_LOCK_STALE_MS.
 //
 // Exit codes: 0 clean | 1 usage error | 2 one or more problems |
 // 3 the check could not run (no repo root, the spawn-log or the board
@@ -60,11 +71,15 @@ import {
 
 import { getRepoRoot } from './repo-root.mjs';
 import {
-  boardPath,
+  BOARD_LOCK_LONG_HELD_MS,
+  BOARD_LOCK_WAIT_MS,
   boardRelPath,
+  formatLockAge,
+  inspectBoardLock,
+  isLongHeldBoardLock,
   isValidAgentName,
   readBoard,
-  resolveAgentName,
+  resolveAgentBoard,
 } from './status-board.mjs';
 
 export const BOARD_STALE_MINUTES = 90;
@@ -79,7 +94,8 @@ Usage:
 
 Reports, one line each:
   - the board not updated for ${BOARD_STALE_MINUTES} minutes (or missing) while a dispatch is open
-  - an open dispatch with no board item (an item whose ids hold the dispatch id)
+  - an open dispatch with no board item (a group item, or a lane's running or
+    queued item, whose ids hold the dispatch id)
   - a dispatch open 24 to 48 hours (close it or check it)
   - the spawn-log lock held for more than ${LOCK_STALE_AFTER_MS / 60000} minute, naming its holder and
     pa dispatch unlock (writers wait on it and then fail)
@@ -87,6 +103,9 @@ Reports, one line each:
     dispatch with no stage, and an open question with no on-me entry
 Unrecognised status or outcome words are warnings (exit 0): one line per word,
 with its count and at most 5 ids; --json lists every one.
+A board lock held by a live process on this host for more than
+${BOARD_LOCK_LONG_HELD_MS / 60000} minutes is a warning (exit 0) naming its pid, its age and the
+manual clear; nothing breaks it.
 
 Flags:
   --json            One JSON object on stdout
@@ -94,7 +113,8 @@ Flags:
   --agent <name>    The agent folder (default: preferences paName, else the
                     single agents/* folder holding next-session.md)
 
-Read-only: never writes a file, and never breaks or removes the spawn-log lock.
+Read-only: never writes a file, and never breaks or removes the spawn-log lock
+or the board lock.
 
 Exit codes:
   0 clean | 1 usage error | 2 problems found | 3 the check could not run
@@ -173,6 +193,11 @@ function boardIdSet(board, key) {
   };
   if (key === 'groups') {
     for (const g of Array.isArray(board.groups) ? board.groups : []) if (isPlainObject(g)) add(g.items);
+    for (const l of Array.isArray(board.lanes) ? board.lanes : []) {
+      if (!isPlainObject(l)) continue;
+      add([l.running]);
+      add(l.queued);
+    }
   } else {
     add(board.onMe);
   }
@@ -191,6 +216,9 @@ function boardIdSet(board, key) {
  * @param {object|null} [input.lock]      the spawn-log lock as read (readSpawnLogLock),
  *                                        or null/absent when there is none or it was not read
  * @param {string} [input.lockRelPath]    the lock's path for the message
+ * @param {object|null} [input.boardLock] the board lock as inspected (inspectBoardLock),
+ *                                        or null/absent when there is none or it was not read
+ * @param {string} [input.boardRelPath]   the board's path for the board-lock warning
  * @param {Date|number|Function} [input.now]
  */
 export function checkBoard(input = {}) {
@@ -303,6 +331,31 @@ export function checkBoard(input = {}) {
     openNotOnBoard,
     problems,
     unrecognisedStatuses,
+    boardLockWarning: boardLockWarning(input.boardLock, input.boardRelPath, nowMs),
+  };
+}
+
+/**
+ * The board-lock warning, or null: a lock held by a live pid on this host
+ * whose file is more than BOARD_LOCK_LONG_HELD_MS old at nowMs. The message
+ * names the board, the pid, the age and the manual clear, and says nothing
+ * breaks it. A warning: it never changes the exit code.
+ */
+export function boardLockWarning(lock, boardRel, nowMs) {
+  if (!isPlainObject(lock) || !isLongHeldBoardLock(lock, nowMs)) return null;
+  const board = typeof boardRel === 'string' && boardRel ? boardRel : 'the status board';
+  const lockPath = board === 'the status board' ? 'the status board lock' : board + '.lock';
+  const ageMs = nowMs - lock.mtimeMs;
+  const age = formatLockAge(ageMs);
+  return {
+    kind: 'board-lock-held',
+    boardPath: board,
+    lockPath,
+    pid: lock.pid,
+    ageMinutes: Math.floor(ageMs / 60000),
+    message: 'board lock on ' + board + ' held by live pid ' + lock.pid + ' for ' + age
+      + '; writers wait ' + (BOARD_LOCK_WAIT_MS / 1000) + ' s, then fail, and nothing breaks it.'
+      + ' Once you have checked pid ' + lock.pid + ' is not a board writer, clear it with `rm ' + lockPath + '`',
   };
 }
 
@@ -351,7 +404,7 @@ function summaryLine(agent, result) {
   const live = result.open.live.length;
   const stale = result.open.stale.length;
   const nProblems = result.problems.length;
-  const nWarnings = result.unrecognisedStatuses.length;
+  const nWarnings = result.unrecognisedStatuses.length + (result.boardLockWarning ? 1 : 0);
   const head = nProblems === 0
     ? 'board check: clean for ' + agent
     : 'board check: ' + plural(nProblems, 'problem', 'problems') + ' for ' + agent;
@@ -395,6 +448,7 @@ export function warningLines(unrecognisedStatuses) {
 export function renderHuman(agent, result) {
   const lines = [];
   for (const p of result.problems) lines.push('problem: ' + p.message);
+  if (result.boardLockWarning) lines.push('warning: ' + result.boardLockWarning.message);
   lines.push(...warningLines(result.unrecognisedStatuses));
   lines.push(summaryLine(agent, result));
   return lines.join('\n') + '\n';
@@ -467,6 +521,7 @@ export function buildHookEnvelope(agent, result, hasInitiatives) {
     });
   const problemLines = result.problems.map((p) => '- ' + oneLine(p.message, p.kind === 'lock-held' ? 360 : 160));
   const footer = [];
+  if (result.boardLockWarning) footer.push('Warning: ' + oneLine(result.boardLockWarning.message, 360));
   if (result.unrecognisedStatuses.length) {
     footer.push('Unrecognised status words: ' + result.unrecognisedStatuses.length + ' (warnings; `pa board check` lists them).');
   }
@@ -522,7 +577,7 @@ function parseFlags(args) {
   return flags;
 }
 
-async function gather(repoRoot, agent) {
+async function gather(repoRoot, agent, boardFile) {
   const spawnLogFile = join(repoRoot, 'agents', agent, 'spawn-log.json');
   let log;
   try {
@@ -535,7 +590,7 @@ async function gather(repoRoot, agent) {
   }
   let parsed;
   try {
-    parsed = await readBoard(boardPath(repoRoot, agent), { strictStatus: false });
+    parsed = await readBoard(boardFile, { strictStatus: false });
   } catch (e) {
     if (e instanceof SyntaxError) throw new PreconditionError('board at ' + boardRelPath(agent) + ' is not valid JSON: ' + e.message);
     throw new PreconditionError('could not read the board at ' + boardRelPath(agent) + ': ' + (e.message || e));
@@ -547,6 +602,9 @@ async function gather(repoRoot, agent) {
   // Read-only: the lock file is read, never written, broken or swept.
   let lock = null;
   try { lock = await readSpawnLogLock(spawnLogFile); } catch { lock = null; }
+  // The board lock beside the board, read-only the same way.
+  let boardLock = null;
+  try { boardLock = await inspectBoardLock(boardFile); } catch { boardLock = null; }
   return {
     board: parsed ? parsed.board : null,
     dispatches: log.dispatches,
@@ -554,6 +612,8 @@ async function gather(repoRoot, agent) {
     hasInitiatives: initiatives.hasRecords,
     lock,
     lockRelPath: spawnLogRelPath(agent) + '.lock',
+    boardLock,
+    boardRelPath: boardRelPath(agent),
   };
 }
 
@@ -585,10 +645,18 @@ export async function run(argv, opts = {}) {
         throw new PreconditionError(e.message || String(e));
       }
     }
-    const agent = flags.agent ?? resolveAgentName(repoRoot);
+    // The one agent-board resolver every board reader and writer uses: a bad
+    // name or a board path that leads out of agents/<agent>/workspace/ is a
+    // usage error before anything is read.
+    const resolved = resolveAgentBoard(repoRoot, flags.agent);
+    if (!resolved.ok) {
+      throw new UsageError(resolved.message + (flags.agent === undefined ? ' (the agent from preferences)' : '')
+        + ', got "' + resolved.agent + '"; nothing was read');
+    }
+    const agent = resolved.agent;
     let input;
     try {
-      input = await gather(repoRoot, agent);
+      input = await gather(repoRoot, agent, resolved.file);
     } catch (e) {
       if (e instanceof PreconditionError && flags.json) {
         out.write(JSON.stringify({ ok: false, exitCode: 3, agent, error: e.message }, null, 2) + '\n');
@@ -612,6 +680,8 @@ export async function run(argv, opts = {}) {
         problems: result.problems,
         unrecognisedStatuses: result.unrecognisedStatuses,
       };
+      // Present only when the warning fires, so a clean report keeps its shape.
+      if (result.boardLockWarning) payload.boardLockWarning = result.boardLockWarning;
       out.write(JSON.stringify(payload, null, 2) + '\n');
       return result.exitCode;
     }

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

@@ -38,6 +38,9 @@ Usage:
   pa status set [--file <p>]  Replace this PA's daily status board from a JSON file or stdin
   pa status patch [flags]     Merge one board item or on-me entry, set statuses, append to done
   pa status show [--json]     Print the daily status board (never hand-edit its JSON)
+  pa status lane --key <k>    Add or change a board lane (title, paused, its running item and queue)
+  pa status notice [flags]    Add, change or dismiss a For-me notice (Risk, Money or Security)
+  pa status done [flags]      Move a lane item to done, add a done entry, or prune old ones
   pa board check [--json] [--hook-envelope] [--agent <n>]
                               Read-only: is the board current, and is every open dispatch on it?
                               Exit 0 clean | 1 usage error | 2 problems found | 3 could not run
@@ -121,8 +124,8 @@ export async function main(argv) {
       return await doSession(rest);
     case 'status':
       // Bare `pa status` (and any argv that is not a board subverb) stays
-      // the environment probe; set | patch | show write and read the daily
-      // status board.
+      // the environment probe; set | patch | show | lane | notice | done
+      // write and read the daily status board.
       if (STATUS_BOARD_SUBVERBS.includes(rest[0])) return await runStatusBoard(rest);
       return await doStatus();
     case 'board':

package/dist/engineering-pa-cli/src/pa/dispatch-cli.mjs

@@ -9,7 +9,8 @@
 //   stage  appends a checkpoint { at, line, stage } to the record, sets its
 //          stage, and refreshes the board item and the board's updatedAt;
 //   close  sets completedAt and the closing outcome (a known closed word,
-//          done by default) and moves the item from its group to done;
+//          done by default) and moves the item to done, out of its group or
+//          its lane (running or queued), once;
 //   list   prints the open dispatches by the shared rule and writes nothing;
 //   unlock prints the spawn-log lock's holder and removes the lock when its
 //          holder is provably dead (this host, pid gone), or with --force
@@ -23,7 +24,10 @@
 //
 // The spawn-log write and then the board patch run inside one hold of the
 // spawn-log's lock (core spawn-log/write.mjs), so concurrent calls get
-// distinct ids and lose no record and no board item. A failed board patch never undoes the
+// distinct ids and lose no record and no board item. The board patch also
+// runs inside the board lock (status-board.mjs withBoardLock), the one
+// `pa status` and the workspace dismiss route take, so no other board
+// writer loses a change to it either. A failed board patch never undoes the
 // spawn-log write: the record stays, stdout still prints what was written,
 // stderr names the board error, the exit code is 2, and `pa board check`
 // then names the dispatch as not on the board. A missing board is such a
@@ -64,13 +68,14 @@ import { dispatchLabel } from '../../../engineering-pa-core/src/dispatch/label.m
 import { getRepoRoot } from './repo-root.mjs';
 import {
   BoardError,
+  BoardLockError,
   STATUS_VALUES,
-  boardPath,
   boardRelPath,
   isValidAgentName,
   readBoard,
-  resolveAgentName,
+  resolveAgentBoard,
   validateBoard,
+  withBoardLock,
   writeBoardAtomic,
 } from './status-board.mjs';
 
@@ -155,9 +160,12 @@ class ClosedDispatchError extends Error {
  * A failed board patch. `state` is the board's: 'missing', 'unparsed' (not
  * valid JSON), 'unreadable', 'structural' (off the schema's structure),
  * 'status' (only a status value outside STATUS_VALUES), 'write' (the write
- * itself failed) or 'lost' (the spawn-log lock was lost before the board's
- * rename, so the fence skipped the write). `onBoard` says whether a group item holds the id, when
- * the board parsed.
+ * itself failed), 'lost' (the spawn-log lock was lost before the board's
+ * rename, so the fence skipped the write), 'locked' (another board writer
+ * held the board lock for the whole wait, so the board was not read or
+ * written) or 'refused' (the agent-board resolver's fence, checked again
+ * inside the lock, refused the path, so the board was not read or written). `onBoard` says whether a board item (a group item, or a lane's
+ * running or queued item) holds the id, when the board parsed.
  */
 class BoardPatchError extends OpError {
   constructor(msg, state, onBoard = false) {
@@ -203,12 +211,12 @@ export async function run(argv, opts = {}) {
       if (flags[k] === undefined || String(flags[k]).trim() === '') throw new UsageError('--' + k + ' is required');
     }
     const repoRoot = opts.repoRoot ?? await getRepoRoot();
-    const agent = pickAgent(flags.agent, repoRoot);
+    const { agent, file: board } = pickBoard(flags.agent, repoRoot);
     const ctx = {
       repoRoot,
       agent,
       spawnLog: join(repoRoot, 'agents', agent, 'spawn-log.json'),
-      board: boardPath(repoRoot, agent),
+      board,
       flags,
       out,
       err,
@@ -257,10 +265,21 @@ function parseFlags(args, allowed) {
   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 in status-board.mjs): --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 the
+ * spawn-log or the board 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) {
@@ -293,10 +312,25 @@ export function stageText(stage) {
 /**
  * Load the board for a patch, apply `change(board)`, stamp updatedAt and
  * write it atomically, with the spawn-log lock's `fence` run just before the
- * board's rename. Throws OpError when the board is missing, not JSON, off
- * the schema, the write is refused, or the lock was lost.
+ * board's rename, all inside the board lock. Throws OpError when the board
+ * is missing, not JSON, off the schema, the write is refused, the
+ * spawn-log lock was lost, or the board lock stayed held.
  */
 async function patchBoard(ctx, id, change, fence) {
+  try {
+    return await withBoardLock(ctx.board, () => {
+      // The resolver's fence again, now the lock is held.
+      const again = resolveAgentBoard(ctx.repoRoot, ctx.agent);
+      if (!again.ok) throw new BoardPatchError(again.message + '; nothing was written', 'refused');
+      return patchBoardLocked(ctx, id, change, fence);
+    });
+  } catch (e) {
+    if (e instanceof BoardLockError) throw new BoardPatchError(e.message, 'locked');
+    throw e;
+  }
+}
+
+async function patchBoardLocked(ctx, id, change, fence) {
   let parsed;
   try {
     parsed = await readBoard(ctx.board, { strictStatus: true });
@@ -332,7 +366,7 @@ async function patchBoard(ctx, id, change, fence) {
 }
 
 function holdsId(board, id) {
-  return Boolean(board && Array.isArray(board.groups)) && itemsWithId({ groups: board.groups.filter((g) => g && typeof g === 'object') }, id).length > 0;
+  return Boolean(board) && typeof board === 'object' && itemsWithId(board, id).length > 0;
 }
 
 /**
@@ -345,6 +379,8 @@ function boardPatchFailure(e, { id, agent, open }) {
   let check;
   if (e.state === 'unparsed' || e.state === 'unreadable' || e.state === 'structural') {
     check = '`pa board check` exits 3 naming ' + file + ' until the board is fixed';
+  } else if (e.state === 'locked' || e.state === 'refused') {
+    check = 'the board at ' + file + ' was left as it was, so `pa board check` reads it unchanged';
   } else if (!open) {
     check = '`pa board check` does not name a closed dispatch';
   } else if (e.onBoard) {
@@ -384,11 +420,23 @@ function refuseClosed(merged, id, verb, ctx) {
   throw new ClosedDispatchError(id + ' is closed (' + why.join(', ') + '); pa dispatch ' + verb + ' refuses a closed dispatch and wrote nothing');
 }
 
+/**
+ * Every board item holding the id: group items first ({ gi, ii, item }),
+ * then each lane's running item and queued items ({ lane, slot, item }).
+ * Safe on a board off the schema (anything not an object is passed over).
+ */
 function itemsWithId(board, id) {
   const hits = [];
-  board.groups.forEach((g, gi) => (Array.isArray(g.items) ? g.items : []).forEach((it, ii) => {
-    if (Array.isArray(it.ids) && it.ids.includes(id)) hits.push({ gi, ii, item: it });
+  const isObj = (v) => v !== null && typeof v === 'object' && !Array.isArray(v);
+  const holds = (it) => isObj(it) && Array.isArray(it.ids) && it.ids.includes(id);
+  (Array.isArray(board.groups) ? board.groups : []).forEach((g, gi) => (isObj(g) && Array.isArray(g.items) ? g.items : []).forEach((it, ii) => {
+    if (holds(it)) hits.push({ gi, ii, item: it });
   }));
+  for (const lane of Array.isArray(board.lanes) ? board.lanes : []) {
+    if (!isObj(lane)) continue;
+    if (holds(lane.running)) hits.push({ lane, slot: 'running', item: lane.running });
+    for (const it of Array.isArray(lane.queued) ? lane.queued : []) if (holds(it)) hits.push({ lane, slot: 'queued', item: it });
+  }
   return hits;
 }
 
@@ -521,12 +569,19 @@ async function doClose(ctx) {
   return result.after ? 0 : 2;
 }
 
-/** Take the dispatch's items out of their groups and add one done entry. */
+/**
+ * Take the dispatch's items out of their groups and their lanes (running or
+ * queued) and add one done entry.
+ */
 function moveToDone(board, id, record, f, outcome, now) {
   const hits = itemsWithId(board, id);
   const base = hits.length ? hits[0].item : null;
-  const group = hits.length ? board.groups[hits[0].gi].label : null;
-  for (const { gi, ii } of [...hits].reverse()) board.groups[gi].items.splice(ii, 1);
+  const group = hits.length && hits[0].lane === undefined ? board.groups[hits[0].gi].label : null;
+  for (const h of [...hits].reverse()) {
+    if (h.lane === undefined) board.groups[h.gi].items.splice(h.ii, 1);
+    else if (h.slot === 'running') delete h.lane.running;
+    else h.lane.queued.splice(h.lane.queued.indexOf(h.item), 1);
+  }
   if (board.done.some((d) => Array.isArray(d.ids) && d.ids.includes(id))) return;
   const entry = { title: base ? base.title : (str(record.label) || id), status: BOARD_DONE };
   if (str(group)) entry.workstream = group;