Autonomous development for real products. Governed agents build from specs you approve, follow the rules you set, and nothing merges until another agent proves it. Your decisions, judgement and taste are the bar that work must clear. Declare your vision and let agents build it.
JavaScript agentic-codingai-agentsai-governanceautonomous-agentsclaude-codeclicode-reviewcodexcoding-agentsdeveloper-toolsgit-hooksllmlocal-firstmulti-agentsoftware-factoryspec-driven-developmentverificationvibe-coding
feat(sentinel): schedule health refresh outside resume [N19,A6]
Corey Olson0b273fad1291
diff --git a/docs/api.md b/docs/api.mdindex 2b1c5018..10a9f386 100644--- a/docs/api.md+++ b/docs/api.md@@ -609,6 +609,8 @@ A project may declare a `staticChecks` command in `pullboard.json` (empty by def`resume` and the background view never execute approved watch commands. When watches are due, resume prints at most one line pointing to `pullboard sentinel run`. That explicit command prepares a clean checkout of the committed local trunk, runs due approved watches there in their approved relative directories, records their results on the original board, and removes the prepared checkout after the commands finish. It never chooses an agent's working tree as the execution directory or rewrites an approved command. Relative project inputs come from committed trunk; explicitly approved absolute paths retain their literal meaning.+`resume` also reads the last recorded work-health findings and their recording time from the board index; it does not run the Git-heavy health scan. `pullboard sentinel run` refreshes those findings and ordinary owner alerts even when no approved watch is due. A recorded empty finding list describes that recorded scan, not a new check of the current project.+Schedule `pullboard sentinel run` independently of work sessions. For example, an hourly server cron entry is `0 * * * * cd /path/to/project && pullboard sentinel run`. A scheduled CI job can run the same command after its ordinary checkout and board-access setup; its schedule calls this command, not `resume`. The checkout used by the timer must already have normal access to the board. `pullboard sentinel run --help` describes both scheduling options. These examples do not install a timer or change approval.The existing board and machine `health.sentinel: false` switches suppress execution. Ordered run leases prevent duplicate concurrent scheduled runs. External checks run outside the database write lock, with bounded final output and an owned-child timeout; recorded replay never executes a command. On POSIX hosts shutdown drains the owned process group; Windows uses direct-child termination. A failed check notifies its owner once with its name, final output and next step; staying red posts no duplicate, and recovery posts one cleared notice. Every red run remains a `sentinel:<name>` cause receipt for Rigor, without inventing a code change. Cancellation records its outcome without creating a failure or recovery notice. `pullboard sentinels --json` lists current rows, their owners, approval, latest result and current proposal’s run history. This is engine 56; earlier engines refuse the new moves before replay.diff --git a/src/commands/resume.js b/src/commands/resume.jsindex 77b6aa4d..07cc9dc4 100644--- a/src/commands/resume.js+++ b/src/commands/resume.js@@ -28,7 +28,7 @@ import {worktreeEntries,} from '../git.js';import {- scanHealthSentinel,+ recordedHealthFindings,} from '../health-sentinel.js';import {unwiredHookProblems,@@ -101,11 +101,12 @@ import {viewSetupComplete,whoAmI,withBoard,+ withBoardRead,worktreeLocation,} from '../cli.js';/**- * Resume's own moves (the approval baseline, health findings, due watches) are bookkeeping: a session that cannot+ * Resume's one compatibility move (the approval baseline) is bookkeeping: a session that cannot* reach the board key (SSH, a scheduled job, a locked keychain) still reads the whole card, and the moves wait for a* session that can. Every read works without the key [E9].*@@ -136,30 +137,24 @@ function keylessBookkeeping(send) {export async function resumeHere(io, view) {const ctx = context(io);const ordered = keylessBookkeeping(sendOrdered);- await withBoard(ctx, async board => {- const me = whoAmI(ctx, board);- // Bootstrap is an ordered move: observe health only after it, so the first legacy scan is not stale.- const initialBaseline = initialSpecApprovalBaseline(ctx, board, 'recordHealthFindings');- if (initialBaseline) {- const baselineIo = ctx.io.personRequest || ctx.io.personRequestMoveId- ? { ...ctx.io, personRequest: undefined, personRequestMoveId: undefined } : ctx.io;- await ordered({ ...ctx, io: baselineIo }, board, 'recordSpecApprovalBaseline', [{- agentId: COORDINATOR, baseline: initialBaseline,- }]);- }- const observation = scanHealthSentinel(ctx.file, { root: ctx.info.root, config: ctx.config, now: ctx.clock.now() });- if (observation) {- try { await ordered(ctx, board, 'recordHealthFindings', [{ agentId: me.id, ...observation }]); }- catch (error) { if (!(error instanceof Refused) || error.code !== 'HEALTH_SCAN_STALE') throw error; }- }+ const initialBaseline = withBoardRead(ctx, board => {+ whoAmI(ctx, board);+ return initialSpecApprovalBaseline(ctx, board, 'recordHealthFindings');});- resumeSentinels({ ctx, withBoard });+ if (initialBaseline) {+ const baselineIo = ctx.io.personRequest || ctx.io.personRequestMoveId+ ? { ...ctx.io, personRequest: undefined, personRequestMoveId: undefined } : ctx.io;+ await withBoard(ctx, board => ordered({ ...ctx, io: baselineIo }, board, 'recordSpecApprovalBaseline', [{+ agentId: COORDINATOR, baseline: initialBaseline,+ }]));+ }+ resumeSentinels({ ctx, withBoard: withBoardRead });const { root, isMain } = ctx.info;const mainRoot = primaryCheckoutRoot(ctx.info);const worktreeConfig = mainRoot ? (isMain ? ctx.config : loadConfig(mainRoot)) : null;let setupScope;let doctrine;- const card = withBoard(ctx, (board) => {+ const card = withBoardRead(ctx, (board) => {setupScope = setupIdentity(board);doctrine = agentDoctrine(ctx, board);const me = whoAmI(ctx, board);@@ -174,6 +169,7 @@ export async function resumeHere(io, view) {const needsState = personNeedsSummary(root, { board, config: ctx.config, includeFit: true, includeRigorUndrafted: me.id === COORDINATOR });return {me,+ health: recordedHealthFindings(board),all,needsYou: personNeeds(needsState),...(me.id === COORDINATOR ? { rigor: { undrafted: needsState.rigorUndrafted } } : {}),@@ -229,12 +225,16 @@ export async function resumeHere(io, view) {for (const problem of card.hookProblems) say(`${problem.message}; ${problem.next}`);const plural = (n, word) => `${n} ${word}${n === 1 ? '' : 's'}`;say(`resume: ${me.displayName}${me.family ? ` [family ${me.family}]` : ''}, ${me.lane} lane${isMain ? ', the main checkout' : ''}, at ${root}`);+ if (card.health.recordedAt) {+ say(`Health recorded ${card.health.recordedAt}: ${card.health.findings.length} finding${card.health.findings.length === 1 ? '' : 's'}; refresh with pullboard sentinel run.`);+ for (const finding of card.health.findings) say(` ${finding.subject}: ${finding.why}; next: ${finding.next}`);+ } else say('No health findings have been recorded; schedule pullboard sentinel run to refresh them.');card.view = view;// A view left running needs no line at every session start; a start, a busy port or a failure does.if (view.state !== 'running' && backgroundViewLine(view)) say(backgroundViewLine(view));if (card.inbox) for (const line of coordinatorInboxLines(card.inbox, name, (at) => span(ctx, at), firstLine)) say(line);say(`New agent worktrees: ${card.newWorktreeLocation}`);- card.setup = withBoard(ctx, board => withStarterWork(boardSetup(ctx, card, setupScope), { board, me, main: isMain, config: ctx.config, root, seat: ctx.io.callerRole() === 'seat' }));+ card.setup = withBoardRead(ctx, board => withStarterWork(boardSetup(ctx, card, setupScope), { board, me, main: isMain, config: ctx.config, root, seat: ctx.io.callerRole() === 'seat' }));if (!loadSpec(root, ctx.config).rows.length && card.all.length) say('Spec rows are optional; add a requirement later: pullboard spec draft "<text>".');if (card.setup) {say(`Setting up: step ${card.setup.step} of 5`);diff --git a/src/health-sentinel.js b/src/health-sentinel.jsindex 77983d6a..159a8dcc 100644--- a/src/health-sentinel.js+++ b/src/health-sentinel.js@@ -3,6 +3,7 @@ import { existsSync } from 'node:fs';import { openBoardReadOnly } from './board.js';import { healthReport } from './health.js';import { healthSentinelEnabled } from './settings.js';+import { Refused } from './refused.js';import {healthFindingIdentity,normalizedHealthFindings,@@ -24,3 +25,14 @@ export function scanHealthSentinel(file, { root, config, now }) {return { observedRevision, findings: report.stuck };} finally { db.close(); }}++/** Read the indexed last recorded findings and their recording time without running a health scan. */+export function recordedHealthFindings(board) {+ const last = board.db.prepare("SELECT event_at, event_detail FROM event WHERE event_kind = 'health-scan' ORDER BY event_id DESC LIMIT 1").get();+ if (!last) return { recordedAt: null, findings: [] };+ const detail = JSON.parse(last.event_detail);+ if (!Array.isArray(detail.active) || !Number.isFinite(Date.parse(last.event_at))) {+ throw new Refused('HEALTH_FINDINGS', 'the recorded health findings are invalid; run pullboard doctor before scheduling another sentinel run');+ }+ return { recordedAt: last.event_at, findings: detail.active };+}diff --git a/src/help.js b/src/help.jsindex b9b5a668..b6dfaee9 100644--- a/src/help.js+++ b/src/help.js@@ -367,6 +367,7 @@ const HELP_NOTES = {'Schedule this command with cron on a server or a scheduled CI job that already has ordinary board access.','For example: 0 * * * * cd /path/to/project && pullboard sentinel run','Each run prepares committed local trunk; resume and the background view never execute watch commands.',+ 'It also refreshes work-health findings; resume shows only the indexed findings and their recorded time.',],watch: ['Claude Code: run pullboard watch --to <your id> under the Monitor tool, and each event line wakes the seat.',diff --git a/src/sentinel-command.js b/src/sentinel-command.jsindex 98d2515f..195706de 100644--- a/src/sentinel-command.js+++ b/src/sentinel-command.js@@ -7,6 +7,9 @@ import { sentinels } from './sentinels.js';import { runDueSentinels } from './sentinel-runner.js';import { withSentinelTrunk } from './sentinel-runner.js';import { healthSentinelEnabled } from './settings.js';+import { recordedHealthFindings } from './health-sentinel.js';+import { scanHealthSentinel } from './health-sentinel.js';+import { initialSpecApprovalBaseline } from './spec-approval-bootstrap.js';/** The watch command's existing string options, shared with the CLI parser. */export const SENTINEL_OPTIONS = {@@ -30,14 +33,30 @@ export function resumeSentinels({ ctx, withBoard }) {async function runSentinels({ ctx, withBoard, whoAmI, ordered }) {return withBoard(ctx, async board => {const me = whoAmI(ctx, board);- if (!healthSentinelEnabled(ctx.config) || !dueSentinels(board).length) {- ctx.io.result?.({ sentinels: [] });+ const enabled = healthSentinelEnabled(ctx.config);+ if (enabled) {+ // Preserve bootstrap-before-observation ordering so the compatibility move cannot stale the scan.+ const baseline = initialSpecApprovalBaseline(ctx, board, 'recordHealthFindings');+ if (baseline) {+ const io = ctx.io.personRequest || ctx.io.personRequestMoveId+ ? { ...ctx.io, personRequest: undefined, personRequestMoveId: undefined } : ctx.io;+ await ordered({ ...ctx, io }, board, 'recordSpecApprovalBaseline', [{ agentId: 'coordinator', baseline }]);+ }+ const observation = scanHealthSentinel(ctx.file, { root: ctx.info.root, config: ctx.config, now: ctx.clock.now() });+ if (observation) {+ try { await ordered(ctx, board, 'recordHealthFindings', [{ agentId: me.id, ...observation }]); }+ catch (error) { if (!(error instanceof Refused) || error.code !== 'HEALTH_SCAN_STALE') throw error; }+ }+ }+ const health = recordedHealthFindings(board);+ if (!enabled || !dueSentinels(board).length) {+ ctx.io.result?.({ sentinels: [], health });ctx.io.say('No enabled sentinel is due.');return 0;}const { results, trunk } = await withSentinelTrunk(ctx.info.root, root => runDueSentinels({ root, board, agentId: me.id,ordered: (operation, args) => ordered(ctx, board, operation, args) }));- ctx.io.result?.({ sentinels: results, trunk });+ ctx.io.result?.({ sentinels: results, trunk, health });ctx.io.say(`Sentinels: ${results.length} run from trunk ${trunk.branch}@${trunk.commit.slice(0, 12)}.`);for (const row of results) ctx.io.say(`${row.name}: ${row.lastRun.green ? 'green' : 'red'}; owner ${row.owner}`);return 0;diff --git a/test/health-sentinel.test.js b/test/health-sentinel.test.jsindex 805f9ef9..b67a4c72 100644--- a/test/health-sentinel.test.js+++ b/test/health-sentinel.test.js@@ -180,16 +180,35 @@ test('a recurring health episode needs no changed code commit and legacy lookaliassert.deepEqual(eventCauses({ ...event, event_kind: 'shout' }), []);});-test('resume publishes health and the board and machine off switches suppress it [A6]', async t => {+test('resume reads recorded health and scheduled runs refresh it with both off switches intact [A6]', async t => {const box = fixture(t);- box.claimed(0); box.clock.offset += 2 * HOUR;+ const first = box.claimed(0); box.clock.offset += 2 * HOUR;+ box.scan();+ const last = store.events(box.board).filter(event => event.event_kind === 'health-scan').at(-1);+ assert.ok(last, 'the actual ordered scan records findings before resume');+ const notices = store.allShouts(box.board).filter(notice => notice.shout_from === 'sentinel').length;+ const second = box.claimed(1); box.clock.offset += 2 * HOUR;let stdout = ''; let stderr = '';const code = await main(['resume', '--json'], { cwd: box.root, clock: box.clock,stdout: { isTTY: false, write: value => { stdout += value; } }, stderr: { write: value => { stderr += value; } } });assert.equal(code, 0, stderr);- assert.doesNotThrow(() => JSON.parse(stdout));- assert.equal(store.allShouts(box.board).filter(notice => notice.shout_from === 'sentinel').length, 2);- box.claimed(1); box.clock.offset += 2 * HOUR;+ const resumed = JSON.parse(stdout);+ assert.equal(resumed.health.recordedAt, last.event_at);+ assert.ok(resumed.health.findings.some(finding => finding.item === first));+ assert.equal(resumed.health.findings.some(finding => finding.item === second), false, 'resume does not silently refresh stale recorded findings');+ assert.equal(store.events(box.board).filter(event => event.event_kind === 'health-scan').at(-1).event_id, last.event_id);+ assert.equal(store.allShouts(box.board).filter(notice => notice.shout_from === 'sentinel').length, notices);+ stdout = ''; stderr = '';+ const ran = await main(['sentinel', 'run', '--json'], { cwd: box.root, clock: box.clock,+ stdout: { isTTY: false, write: value => { stdout += value; } }, stderr: { write: value => { stderr += value; } } });+ assert.equal(ran, 0, stderr);+ const refreshed = JSON.parse(stdout);+ assert.deepEqual(refreshed.sentinels, [], 'health refresh still runs when no approved watch is due');+ assert.ok(refreshed.health.findings.some(finding => finding.item === second));+ const refreshedEvent = store.events(box.board).filter(event => event.event_kind === 'health-scan').at(-1);+ assert.equal(refreshed.health.recordedAt, refreshedEvent.event_at);+ assert.notEqual(refreshed.health.recordedAt, last.event_at);+ assert.ok(store.allShouts(box.board).filter(notice => notice.shout_from === 'sentinel').length > notices, 'scheduled refresh retains ordinary owner alerts');const config = JSON.parse(readFileSync(join(box.root, 'pullboard.json'), 'utf8'));writeFileSync(join(box.root, 'pullboard.json'), JSON.stringify({ ...config, health: { sentinel: false } }));assert.equal(scanHealthSentinel(box.file, { root: box.root, config: loadConfig(box.root), now: box.clock.now() }), null);diff --git a/test/relay-person-requests.test.js b/test/relay-person-requests.test.jsindex 62cf3e4b..d28ef053 100644--- a/test/relay-person-requests.test.js+++ b/test/relay-person-requests.test.js@@ -27,7 +27,7 @@ const APPROVAL_FLOW_CLI_CHILDREN = [{ command: ['relay', 'on'], snapshotUploads: 1 },{ command: ['status'], snapshotUploads: 4 },{ command: ['export'], snapshotUploads: 0 },- { command: ['resume'], snapshotUploads: 1 }, // The first health scan publishes the fixture's unserved work findings.+ { command: ['resume'], snapshotUploads: 0 }, // Resume reads indexed health; scheduled sentinel run publishes new findings (#1042).{ command: ['spec', 'apply'], snapshotUploads: 1 },{ command: ['answer'], snapshotUploads: 1 },{ command: ['status'], snapshotUploads: 3 },@@ -42,7 +42,7 @@ const DECLINE_FLOW_CLI_CHILDREN = [{ command: ['status'], snapshotUploads: 4 },{ command: ['answer'], snapshotUploads: 1 },{ command: ['answer'], snapshotUploads: 1 },- { command: ['resume'], snapshotUploads: 1 }, // The first health scan publishes the fixture's unserved work findings.+ { command: ['resume'], snapshotUploads: 0 }, // Resume reads indexed health; scheduled sentinel run publishes new findings (#1042).];/** Record the real phase and wait budget for a late-snapshot failure without changing either wait. */