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
refactor(relay): keep local health outside transport plumbing [H5,H17]
Corey Olson930a4ff8f7ce
diff --git a/src/relay-canary-health.js b/src/relay-canary-health.jsindex d94e41ab..31e3ca20 100644--- a/src/relay-canary-health.js+++ b/src/relay-canary-health.js@@ -181,3 +181,14 @@ export function claimRelayCanaryTick(root, now = Date.now()) {.run(now + 60000, now).changes === 1;} finally { db.close(); }}++/** Best-effort telemetry never changes the outcome or credential authority of a native move. */+export function recordClientHealth(root, ok, error, roundTripMs, step = 'push') {+ const code = error?.code ?? 'OK';+ if (/VERSION/u.test(code)) step = 'version';+ else if (/AUTH|OAUTH|NOT_JOINED|RELAY_OFF/u.test(code)) step = 'sign-in';+ else if (/SEAL|DECRYPT|RELAY_KEY/u.test(code)) step = 'unseal';+ try { observeRelayHealth(root, { ok, step: ok ? 'complete' : step, code, roundTripMs,+ relayVersion: ok ? 1 : error?.relayVersion ?? null }, { alerts: false }); }+ catch { /* Losing optional local telemetry cannot undo a requested operation. */ }+}diff --git a/src/relay-status-fields.js b/src/relay-status-fields.jsindex dd30e407..4f2b62a7 100644--- a/src/relay-status-fields.js+++ b/src/relay-status-fields.js@@ -10,3 +10,22 @@ export function unlinkedRelayStatus(deleted = null) {return { linked: false, board: deleted?.board ?? '', url: deleted?.url ?? '', link: '', sequence: 0, behind: 0, recovery: recoverySummary(null),...(deleted ? { deleted: true, notice: 'The relay copy was deleted; your local board is complete. Keep working locally, or run pullboard relay on to link it again.' } : {}) };}++/** Confirm a recovered checkpoint contains the same durable refusal for the blocked transport slot. */+export function recoveryRefusalMatches(document, recovery) {+ const boardMeta = Array.isArray(document?.tables?.board_meta) ? document.tables.board_meta : [];+ const events = Array.isArray(document?.tables?.event) ? document.tables.event : [];+ const meta = boardMeta.find((row) => row?.meta_key === 'relay_refusal_' + recovery.skip);+ if (!meta || typeof meta.meta_value !== 'string') return false;+ let refusal;+ try { refusal = JSON.parse(meta.meta_value); } catch { return false; }+ if (typeof refusal?.outcome?.error?.code !== 'string' ||+ (recovery.blockerDigest && refusal.record !== recovery.blockerDigest)) return false;+ return events.some((event) => {+ if (event?.event_kind !== 'relay_refused' || typeof event.event_detail !== 'string') return false;+ try {+ const detail = JSON.parse(event.event_detail);+ return detail.sequence === recovery.skip && detail.code === refusal.outcome.error.code;+ } catch { return false; }+ });+}diff --git a/src/relay.js b/src/relay.jsindex a4309bde..6c0b95d8 100644--- a/src/relay.js+++ b/src/relay.js@@ -10,7 +10,7 @@ import {export { formatSnapshotLimit, originRepository };import { beginCommandPhase } from './command-phase.js';import {- observeRelayHealth,+ recordClientHealth,readRelayHealth,} from './relay-canary-health.js';import { deliverPersonEnrollments } from './relay-person-enrollment.js';@@ -21,6 +21,7 @@ import {} from './relay-excluded.js';import {recoverySummary,+ recoveryRefusalMatches,unlinkedRelayStatus,} from './relay-status-fields.js';import { originRepository } from './github-origin.js';@@ -434,41 +435,11 @@ function nativeBoardDigest(board) {return semanticBoardDigest(exportBoard(board));}-/** Confirm a recovered checkpoint contains the same durable refusal for the blocked transport slot. */-function recoveryRefusalMatches(document, recovery) {- const boardMeta = Array.isArray(document?.tables?.board_meta) ? document.tables.board_meta : [];- const events = Array.isArray(document?.tables?.event) ? document.tables.event : [];- const meta = boardMeta.find((row) => row?.meta_key === 'relay_refusal_' + recovery.skip);- if (!meta || typeof meta.meta_value !== 'string') return false;- let refusal;- try { refusal = JSON.parse(meta.meta_value); } catch { return false; }- if (typeof refusal?.outcome?.error?.code !== 'string' ||- (recovery.blockerDigest && refusal.record !== recovery.blockerDigest)) return false;- return events.some((event) => {- if (event?.event_kind !== 'relay_refused' || typeof event.event_detail !== 'string') return false;- try {- const detail = JSON.parse(event.event_detail);- return detail.sequence === recovery.skip && detail.code === refusal.outcome.error.code;- } catch { return false; }- });-}-/** Count unapplied uploads using durable event ids, without counting relay transport metadata. */function behind(root, state) {return localRecords(root, (board) => board.db.prepare('SELECT COUNT(*) AS count FROM event WHERE event_id > ?').get(state.cursor).count);}-/** Best-effort telemetry never changes the outcome or credential authority of a native move. */-function recordClientHealth(root, ok, error, roundTripMs, step = 'push') {- const code = error?.code ?? 'OK';- if (/VERSION/u.test(code)) step = 'version';- else if (/AUTH|OAUTH|NOT_JOINED|RELAY_OFF/u.test(code)) step = 'sign-in';- else if (/SEAL|DECRYPT|RELAY_KEY/u.test(code)) step = 'unseal';- try { observeRelayHealth(root, { ok, step: ok ? 'complete' : step, code, roundTripMs,- relayVersion: ok ? 1 : error?.relayVersion ?? null }, { alerts: false }); }- catch { /* Losing optional local telemetry cannot undo a requested operation. */ }-}-/** Expose key-free link status; only an explicit link operation includes its pairing carrier. */function summary(root, state, { pairing = false } = {}) {if (!state) {diff --git a/test/relay-canary-api.test.js b/test/relay-canary-api.test.jsnew file mode 100644index 00000000..4e13ae36--- /dev/null+++ b/test/relay-canary-api.test.js@@ -0,0 +1,126 @@+/** Local API projection for private relay-canary alerts; never part of the sealed relay view. */+import assert from 'node:assert/strict';+import { randomBytes } from 'node:crypto';+import { DatabaseSync } from 'node:sqlite';+import { createServer } from 'node:http';+import { join } from 'node:path';+import test from 'node:test';+import { createLocalApiHandler } from '../src/api.js';+import { relaySnapshot } from '../src/relay-presentation.js';+import { observeRelayHealth } from '../src/relay-canary-health.js';+import { main } from '../src/cli.js';+import { apiFetch } from './api-fixture.js';+import { createE2eHelpers } from './e2e-helpers.js';++const helpers = createE2eHelpers();+test.after(() => helpers.cleanup());++/** Keep process-global repository discovery inside one private fixture and restore it after the test. */+async function withFixtureEnvironment(env, action) {+ const names = ['PATH', 'HOME', 'PULLBOARD_HOME', 'PULLBOARD_MACHINE_HOME', 'GIT_CONFIG_GLOBAL', 'GIT_CONFIG_NOSYSTEM'];+ const saved = Object.fromEntries(names.map((name) => [name, process.env[name]]));+ for (const name of names) {+ if (Object.hasOwn(env, name)) process.env[name] = env[name];+ else delete process.env[name];+ }+ try { return await action(); }+ finally {+ for (const name of names) {+ if (saved[name] === undefined) delete process.env[name];+ else process.env[name] = saved[name];+ }+ }+}++/** Count native board events without opening a write-capable board connection. */+function eventCount(file) {+ const db = new DatabaseSync(file, { readOnly: true });+ try { return db.prepare('SELECT COUNT(*) AS count FROM event').get().count; }+ finally { db.close(); }+}++test('local API refreshes private relay health without adding it to a sealed presentation [A2,H5,H17]', async (t) => {+ const box = helpers.project('true');+ await withFixtureEnvironment(box.env, async () => {+ const secret = randomBytes(24).toString('base64url');+ let port = 0;+ const handler = createLocalApiHandler({+ secret,+ getPort: () => port,+ runCommand: main,+ projects: () => [{ root: box.repo, name: 'Canary API fixture', project: '', added: '2026-10-25T00:00:00.000Z' }],+ });+ const server = createServer(handler);+ await new Promise((resolve, reject) => {+ server.once('error', reject);+ server.listen(0, '127.0.0.1', () => { port = server.address().port; resolve(); });+ });+ t.after(async () => {+ handler.close();+ const closed = new Promise((resolve) => server.close(resolve));+ server.closeAllConnections();+ await closed;+ });++ const api = { origin: `http://127.0.0.1:${port}`, secret };+ const listingResponse = await apiFetch(api, '/api/v1/boards');+ assert.equal(listingResponse.status, 200);+ const listing = await listingResponse.json();+ const board = listing.boards.find((entry) => entry.root === box.repo);+ assert.ok(board?.id, 'the real local API lists the initialized Git board');+ const statePath = `/api/v1/boards/${encodeURIComponent(board.id)}/state`;+ const boardFile = join(box.repo, '.git', 'pullboard', 'board.sqlite');+ const beforeEvents = eventCount(boardFile);++ const initialResponse = await apiFetch(api, statePath);+ assert.equal(initialResponse.status, 200);+ const initial = await initialResponse.json();+ assert.deepEqual(initial.state.relayHealthAlerts, [], 'the private local API starts without a canary alert');++ const firstAt = Date.now();+ const failedPull = { ok: false, step: 'pull', code: 'RELAY_READ', roundTripMs: 73, relayVersion: 1 };+ observeRelayHealth(box.repo, failedPull, { now: firstAt });+ const secondAt = Date.now();+ assert.ok(secondAt >= firstAt, 'sample timestamps come from the actual clock, never a future fixture date');+ const alert = observeRelayHealth(box.repo, failedPull, { now: secondAt });+ assert.equal(alert.transition, 'alert', 'the second real persisted failure creates the local alert');++ const degradedResponse = await apiFetch(api, statePath);+ assert.equal(degradedResponse.status, 200);+ const degraded = await degradedResponse.json();+ assert.notEqual(degradedResponse.headers.get('etag'), initialResponse.headers.get('etag'),+ 'the private health database revision invalidates the already-primed API state cache');+ assert.equal(degraded.state.relayHealthAlerts.length, 1);+ assert.equal(degraded.state.relayHealthAlerts[0].step, 'pull');+ assert.match(degraded.state.relayHealthAlerts[0].text, /relay degraded since .*your moves are queued locally/u);+ assert.ok(degraded.state.needs.some((entry) => entry.kind === 'relay-health' && entry.id === 'relay-canary'),+ 'the local Needs-you projection includes the current canary alert');++ const sealedDuringAlert = relaySnapshot(box.repo);+ assert.equal(Object.hasOwn(sealedDuringAlert.presentation.state, 'relayHealthAlerts'), false,+ 'host-local health is not serialized into the device-sealed presentation');+ assert.equal(sealedDuringAlert.presentation.state.needs.some((entry) => entry.kind === 'relay-health'), false,+ 'a relay snapshot does not disclose this publishing host’s private health alert');++ const recoveryAt = Date.now();+ const recovered = observeRelayHealth(box.repo, {+ ok: true, step: 'complete', code: 'OK', roundTripMs: 21, relayVersion: 1,+ }, { now: recoveryAt });+ assert.equal(recovered.transition, 'recovery');+ const recoveredResponse = await apiFetch(api, statePath);+ assert.equal(recoveredResponse.status, 200);+ const recoveredState = await recoveredResponse.json();+ assert.notEqual(recoveredResponse.headers.get('etag'), degradedResponse.headers.get('etag'),+ 'recovery also invalidates the cached local API state');+ assert.deepEqual(recoveredState.state.relayHealthAlerts, []);+ assert.equal(recoveredState.state.needs.some((entry) => entry.kind === 'relay-health'), false,+ 'the local Needs-you alert disappears after a successful complete round trip');++ assert.equal(eventCount(boardFile), beforeEvents,+ 'health changes and API refreshes do not write a native board event');+ const sealedAfterRecovery = relaySnapshot(box.repo);+ assert.equal(Object.hasOwn(sealedAfterRecovery.presentation.state, 'relayHealthAlerts'), false);+ assert.equal(JSON.stringify(sealedAfterRecovery.presentation).includes('relay-canary'), false,+ 'private canary status remains outside the sealed snapshot after recovery too');+ });+});