@stravica-ai/digital-operator-pa 0.1.70 → 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,7 +6,8 @@
 // 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
@@ -33,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
@@ -62,7 +71,12 @@ import {
 
 import { getRepoRoot } from './repo-root.mjs';
 import {
+  BOARD_LOCK_LONG_HELD_MS,
+  BOARD_LOCK_WAIT_MS,
   boardRelPath,
+  formatLockAge,
+  inspectBoardLock,
+  isLongHeldBoardLock,
   isValidAgentName,
   readBoard,
   resolveAgentBoard,
@@ -89,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
@@ -96,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
@@ -198,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 = {}) {
@@ -310,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 + '`',
   };
 }
 
@@ -358,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;
@@ -402,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';
@@ -474,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).');
   }
@@ -554,6 +602,9 @@ async function gather(repoRoot, agent, boardFile) {
   // 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,
@@ -561,6 +612,8 @@ async function gather(repoRoot, agent, boardFile) {
     hasInitiatives: initiatives.hasRecords,
     lock,
     lockRelPath: spawnLogRelPath(agent) + '.lock',
+    boardLock,
+    boardRelPath: boardRelPath(agent),
   };
 }
 
@@ -627,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/status-board-cli.mjs

@@ -90,6 +90,9 @@ Notes:
   - 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.
@@ -442,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'),
@@ -469,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) {
@@ -523,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) {
@@ -695,7 +710,7 @@ async function patchLaneLocked(ctx, key) {
   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: mergeIds(splitList(f.ids, ',') || [], f.id) };
+    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) {
@@ -709,7 +724,7 @@ async function patchLaneLocked(ctx, 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 = splitList(f.ids, ',');
+  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;

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

@@ -560,6 +560,12 @@ export async function writeBoardAtomic(file, board, opts = {}) {
 //     lock can avoid that. The rule is that the next writer finds the dead
 //     pid, recovers the lock within the bounded wait, and nothing is lost:
 //     the board is only ever replaced by a whole temp file's rename.
+//   - A same-host lock whose pid is alive is never broken, however old, so
+//     a pid reused after a kill keeps a dead writer's lock live. It is made
+//     visible instead: BoardLockError names the holder's pid and the lock's
+//     age, and `pa board check` warns once a live same-host holder's lock is
+//     older than BOARD_LOCK_LONG_HELD_MS (inspectBoardLock, read-only),
+//     naming the manual clear. Nothing removes it automatically.
 //   - A folder the lock call had to create (no board yet) is removed again
 //     when it is still empty, so a refused write leaves no trace.
 
@@ -568,14 +574,20 @@ export const BOARD_LOCK_BREAK_SUFFIX = '.break';
 export const BOARD_LOCK_WAIT_MS = 3000;
 export const BOARD_LOCK_RETRY_MS = 10;
 export const BOARD_LOCK_STALE_MS = 10000;
+/** Age past which `pa board check` warns on a lock held by a live pid on this host. */
+export const BOARD_LOCK_LONG_HELD_MS = 10 * 60 * 1000;
 
 const BOARD_LOCK_HOST = createHash('sha256').update(osHostname()).digest('hex').slice(0, 8);
 
 /** The lock stayed held for the whole wait: nothing was read or written. */
 export class BoardLockError extends Error {
-  constructor(path, holder, waitMs) {
+  constructor(path, holder, waitMs, nowMs = Date.now()) {
     const pid = holder && holder.owner && Number.isInteger(holder.owner.pid) ? holder.owner.pid : null;
-    super('the status board is locked by another writer' + (pid !== null ? ' (pid ' + pid + ')' : '')
+    const ageMs = holder && Number.isFinite(holder.mtimeMs) ? nowMs - holder.mtimeMs : null;
+    const about = [];
+    if (pid !== null) about.push('pid ' + pid);
+    if (ageMs !== null) about.push('lock ' + formatLockAge(ageMs) + ' old');
+    super('the status board is locked by another writer' + (about.length ? ' (' + about.join(', ') + ')' : '')
       + ' and stayed locked for ' + (waitMs / 1000) + ' s; nothing was written, try again');
     this.name = 'BoardLockError';
     this.path = path;
@@ -583,6 +595,20 @@ export class BoardLockError extends Error {
   }
 }
 
+/**
+ * A lock's age for a message: whole seconds under a minute, whole minutes
+ * under an hour, then hours and minutes. A negative age (a file time ahead
+ * of the clock) reads as 0 s.
+ */
+export function formatLockAge(ms) {
+  const secs = Math.max(0, Math.floor((Number.isFinite(ms) ? ms : 0) / 1000));
+  if (secs < 60) return secs + ' s';
+  const mins = Math.floor(secs / 60);
+  if (mins < 60) return mins + ' min';
+  const rest = mins % 60;
+  return Math.floor(mins / 60) + ' h' + (rest ? ' ' + rest + ' min' : '');
+}
+
 /** The lock file of a board file. */
 export function boardLockPath(file) {
   return file + BOARD_LOCK_SUFFIX;
@@ -691,6 +717,38 @@ export function isStaleBoardLock(holder, staleMs = BOARD_LOCK_STALE_MS, nowMs =
   return nowMs - holder.mtimeMs > staleMs;
 }
 
+/**
+ * A board's lock as found, read-only, for `pa board check`: null when there
+ * is none; else its holder's pid (null with no readable owner), whether the
+ * holder ran on this host, whether that pid is alive (the stale rule's own
+ * check; null for a foreign or ownerless lock) and the lock file's time. It
+ * never writes, breaks or removes the lock.
+ *
+ * @param {string} file  the board file
+ */
+export async function inspectBoardLock(file) {
+  const lock = await readBoardLock(boardLockPath(file));
+  if (!lock) return null;
+  const o = lock.owner;
+  const sameHost = Boolean(o && o.host === BOARD_LOCK_HOST);
+  return {
+    pid: o ? o.pid : null,
+    sameHost,
+    alive: sameHost ? processAlive(o.pid) : null,
+    mtimeMs: lock.mtimeMs,
+  };
+}
+
+/**
+ * The long-held rule on an inspected lock: a live holder on this host whose
+ * lock file is more than thresholdMs old at nowMs. Pure.
+ */
+export function isLongHeldBoardLock(lock, nowMs = Date.now(), thresholdMs = BOARD_LOCK_LONG_HELD_MS) {
+  if (!lock || lock.sameHost !== true || lock.alive !== true) return false;
+  if (!Number.isInteger(lock.pid) || !Number.isFinite(lock.mtimeMs)) return false;
+  return nowMs - lock.mtimeMs > thresholdMs;
+}
+
 /** Alive unless process.kill(pid, 0) says ESRCH; EPERM and any other answer read as alive. */
 function processAlive(pid) {
   try {

package/dist/engineering-pa-core/knowledge/work-management/status-board.md

@@ -31,7 +31,7 @@ The PA updates the board, through the CLI, at every one of these moments, in the
 
 ## The write path
 
-The PA never hand-edits the JSON. The CLI reads the clock, validates against the schema and writes atomically (temp file, then rename), so a bad write never lands and the page never reads a half-written file. Every writer (the `pa status` verbs, `pa dispatch` and the page's Dismiss) reads, changes and writes the board inside one lock, `status-board.json.lock` beside it, so two writers never lose each other's change; a write that cannot get the lock within a few seconds writes nothing and says so. A lock left by a writer on the same host counts as stale only when that writer's process is gone; a live writer is never broken, however long it holds. A lock from another host, or one with no readable owner, counts as stale after ten seconds. A stale lock is removed only under a short break mutex, `status-board.json.lock.break`, and only while it is still the lock judged stale, so recovering it never lets two writers in. A crash or a kill can leave the lock file behind: the next writer recovers it within its wait, and nothing is lost, because the board itself is only ever replaced whole. Neither file is ever committed. An option's value never starts with `--`, in the separate form or the `--flag=value` form, and `--started`, `--estimate` and `--ended` take an ISO 8601 date-time with a zone on a real calendar date, such as `2030-01-15T09:30:00Z` (`2030-02-31T09:30:00Z` is refused).
+The PA never hand-edits the JSON. The CLI reads the clock, validates against the schema and writes atomically (temp file, then rename), so a bad write never lands and the page never reads a half-written file. Every writer (the `pa status` verbs, `pa dispatch` and the page's Dismiss) reads, changes and writes the board inside one lock, `status-board.json.lock` beside it, so two writers never lose each other's change; a write that cannot get the lock within a few seconds writes nothing and says so. A lock left by a writer on the same host counts as stale only when that writer's process is gone; a live writer is never broken, however long it holds. A long hold is made visible instead: a writer refused by the lock names the holder's pid and the lock's age, and `pa board check` warns once a lock held by a live writer on this host is more than ten minutes old, naming the manual clear, `rm` of the lock file after checking that pid is not a board writer; nothing clears it automatically. A lock from another host, or one with no readable owner, counts as stale after ten seconds. A stale lock is removed only under a short break mutex, `status-board.json.lock.break`, and only while it is still the lock judged stale, so recovering it never lets two writers in. A crash or a kill can leave the lock file behind: the next writer recovers it within its wait, and nothing is lost, because the board itself is only ever replaced whole. Neither file is ever committed. An option's value never starts with `--`, in the separate form or the `--flag=value` form, and `--started`, `--estimate` and `--ended` take an ISO 8601 date-time with a zone on a real calendar date, such as `2030-01-15T09:30:00Z` (`2030-02-31T09:30:00Z` is refused).
 
 | Verb | Use |
 |---|---|

package/dist/engineering-pa-workspace/app/banner.js

@@ -321,16 +321,17 @@
     document.addEventListener('visibilitychange', onVisibility);
   }
 
-  // Fire after load rather than DOMContentLoaded. On busy pages (e.g.
-  // home.html fires ~9 API fetches) the HTTP/1.1 6-connection pool means
-  // DOMContentLoaded-initiated fetches queue behind the inline script's
-  // fetches. Waiting for load is cheap (sub-100ms on quiet pages, a
-  // second on busy ones) and gives the banner a clear slot. The banner
-  // is a background-info surface, not a critical-path element, so modest
-  // delay is the right trade.
-  if (document.readyState === 'complete') {
-    boot();
+  // Start on DOMContentLoaded, or at once when the document is already
+  // past it. The top window's `load` event waits for every subresource,
+  // the shell's iframe document included, so a slow iframe page held the
+  // banner back for as long as that page took (w-2026-10-31-dave-001).
+  // The banner needs only the shell's own DOM: its slot is in the shell's
+  // markup, or boot() makes one at the top of the body. The script loads
+  // with `defer`, so by the time it runs the DOM is parsed and the start
+  // is usually immediate.
+  if (document.readyState === 'loading') {
+    document.addEventListener('DOMContentLoaded', boot);
   } else {
-    window.addEventListener('load', boot);
+    boot();
   }
 })();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stravica-ai/digital-operator-pa",
-  "version": "0.1.70",
+  "version": "0.1.71",
   "description": "Digital Operator PA: single-bundled public package surface (bins + library) for the platform.",
   "type": "module",
   "main": "./index.mjs",