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
test(core): exercise the heartbeat catalog contract [A1,B3]
Corey Olsone1f70b5d7630
diff --git a/docs/api.md b/docs/api.mdindex 65ec82d6..fb260524 100644--- a/docs/api.md+++ b/docs/api.md@@ -110,6 +110,7 @@ For example: `flow: review wait average 61 min (1 measured; > 60 min); bottlenec| `show` | `version:number`, `item_id:number`, `item_title:string`, `item_lane:string`, `item_status:string`, `verdicts:array`, `thread:array` || `stats` | `version:number`, `stats:object`, `gateWaits:array` || `status` | `version:number`, `me:object`, `mine:array`, `ruleCounts:object`, `stats:object`, `reviewQueue:object`, `unread:number`, `relay:object` |+| `heartbeat` | `version:number`, `seat:string|null`, `presence:string`, `heartbeatAt:string|null` || `doctor` | `version:number`, `problems:array` || `health` | `version:number`, `asOf:string`, `thresholds:object`, `stuck:array`, `waiting:array` || `skills` | `version:number`, `updated:array`, `current:array`, `customized:array` |@@ -201,6 +202,8 @@ For example: `flow: review wait average 61 min (1 measured; > 60 min); bottlenecEach checkout is bound to the first agent session that writes there. The local Git directory holds only its session digest, agent id and timestamp; bindings are absent from board exports and relay snapshots. Another agent session gets `NOT_YOUR_CHECKOUT` and the command to make its own worktree. The same agent starting a new session runs `pullboard takeover`; the existing ordered shout records the takeover, addressed to the person for the main checkout or the coordinator for a lane checkout. On a linked board one main checkout holds the coordinator at a time: another linked main checkout acting as coordinator gets `COORDINATOR_HELD`, naming the holder as `computer` and the end of its relay machine id, and `pullboard takeover` there, from an agent session or a person's terminal, takes the coordinator; its result adds `coordinator` (the new holder) and `previous`. Markerless terminals, reads, the view and person requests keep their existing behavior. A shout or decision addressed to its sender is refused with `SELF_SHOUT`.+`heartbeat` records the registered seat’s machine-local session activity without adding a shared board move. It returns `{seat, presence, heartbeatAt}`; an unknown seat returns `null` for its identity and timestamp. SessionStart, Stop and SessionEnd hooks call it. A seat is live for ten minutes after its last observation, idle until thirty minutes, then gone; its permanent identity remains. Ordinary reads do not refresh presence. `status` shows live and idle seats, while `status --all` also lists gone seats. Observations are private to the machine and board identity and do not travel through export or relay.+`status.reviewQueue` contains `pending`, `reviewing` (distinct agents with live review leases), `reserved`, `oldestSubmittedAt` and `ageMs`. Age starts at each outstanding item's latest submit event; reserving or renewing its review does not reset it. An empty queue has `oldestSubmittedAt: null` and `ageMs: 0`. Among unreserved submissions, `awaitingFirstReview` counts items with no release since their latest submission; `releasedWithoutVerdict` counts those released without a verdict. `releasedItems` lists `{item, releases, reason}` with the cumulative release count and latest reason for that submission. Historical releases without a reason show `reason not recorded`.With `submitGate: "landing"`, `status.submitInvariantProposals` lists files that failed outside a recorded submit selection. Each proposal carries `file`, `escapes` (distinct tested merge commits), `runtimeMs`, `budgetMs: 60000`, `withinBudget`, `commits` and the participating `submissions`. Repeated escapes below budget come first. Unmeasured whole-file runtime is `null`, not a sum of test-case durations. A later whole-file diagnostic or full gate passing at the identical commit suppresses that escape; another commit or merely an equal Git tree does not. Submission events record versioned `submissionProof: { version: 1, files, full, deferred, reason }`, including the actual full-fallback reason, plus `deferredFiles` when `submitDeferAbove` moved the affected selection to landing. A deferred full fallback records only invariants actually selected to run, rather than its possible full selection. Historical submissions without this receipt remain unknown. Landing batches append versioned `invariantEvidence` with actual tested commits, participants and whole-file diagnostics; earlier evidence cannot be replaced. Status reads those canonical events and changes no configuration. Edit `submitInvariants` on main to accept a proposal. Outside the landing submit policy the proposal list is empty.diff --git a/test/api-catalog.test.js b/test/api-catalog.test.jsindex fa7533a1..ea09e96a 100644--- a/test/api-catalog.test.js+++ b/test/api-catalog.test.js@@ -287,6 +287,10 @@ catalogCase('[A1] command results match the catalog across roots and subcommandsassert.equal(existsSync(join(box.env.PULLBOARD_HOME, 'config.json')), false, 'machine settings use the separate settings.json file');await json(box, repo, 'resume');await json(box, repo, 'status');+ const heartbeat = await json(box, repo, 'heartbeat');+ assert.equal(heartbeat.seat, 'coordinator');+ assert.equal(heartbeat.presence, 'live');+ assert.ok(Number.isFinite(Date.parse(heartbeat.heartbeatAt)), 'an explicit hook returns its real local observation');await json(box, repo, 'stats');await json(box, repo, 'badge');await json(box, repo, 'doctor');