@stravica-ai/digital-operator-pa 0.1.68 → 0.1.70

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

@@ -11,8 +11,10 @@
 // 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
@@ -60,11 +62,10 @@ import {
 
 import { getRepoRoot } from './repo-root.mjs';
 import {
-  boardPath,
   boardRelPath,
   isValidAgentName,
   readBoard,
-  resolveAgentName,
+  resolveAgentBoard,
 } from './status-board.mjs';
 
 export const BOARD_STALE_MINUTES = 90;
@@ -79,7 +80,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)
@@ -173,6 +175,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);
   }
@@ -522,7 +529,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 +542,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));
@@ -585,10 +592,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');

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;