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(seats): route stable addresses with existing grants [H2,H16,N26]
Corey Olsonb46942e5d583
diff --git a/docs/api.md b/docs/api.mdindex 34edf335..6011e4be 100644--- a/docs/api.md+++ b/docs/api.md@@ -86,7 +86,7 @@ For example: `flow: review wait average 61 min (1 measured; > 60 min); bottlenec| `takeover` | `version:number`, `agent:string`, `path:string` || `worktree` | `version:number`, `agent:string`, `lane:string`, `route:string`, `path:string`, `branch:string`, `prompt:string`, `model:string`, `displayName:string` || `resume` | `version:number`, `me:object`, `all:array`, `requests:array`, `holding:array`, `sentBack:array`, `awaiting:array`, `toVerify:array`, `toMerge:array`, `open:array`, `stale:array`, `doctrineNotes:array`, `holds:array`, `unread:number`, `newest:array`, `root:string`, `newWorktreeLocation:string`, `dirty:number`, `next:string` |-| `whoami` | `version:number`, `id:string`, `lane:string`, `path:string`, `model:string`, `displayName:string` |+| `whoami` | `address:string`, `version:number`, `id:string`, `lane:string`, `path:string`, `model:string`, `displayName:string` || `agents` | `version:number`, `agents:array` || `lanes` | `version:number`, `lanes:object`, `shared:array`, `coordinator:string` || `lane add` | `version:number`, `lane:string`, `owns:array` |@@ -673,3 +673,7 @@ When `publish.pullRequest` is enabled, `pullboard publish` reconciles the GitHubA board-recorded item merge covers its introduced commits only when its exact submitted commit has that receipt and is an ancestor of the recorded merge. `Pullboard-Companion: #N` is covered only on a board-recorded trunk containing item N's landing. Unreceipted commits, including release bumps and synthetic publication commits, remain unverified. An outside PR is allowed and initially reads `not verified`; the JSON result's `verification[].intake` names the existing `pullboard intake` command that files it for review. Outside intake can cover only its exact accepted head, never its earlier commits by inference.The JSON result includes `verification` entries with PR number, exact head, state, assurance, receipt identities, and any unverified commit IDs. GitHub statuses are shared by PRs with the same head: if an outside or unproven PR shares a commit with a proven proposal, the shared status stays red rather than lending the proposal's green status to it. Publishing observes and posts statuses; it never merges a PR or requires outside authors to use Pullboard.++### Seat addresses++`whoami.address` and each `agents` entry expose `pullboard:<board-id>:<percent-encoded-seat-id>`. The address uses the persistent board identity and registered seat id, not its checkout path. Send with `pullboard shout <address> "<text>"` from a checkout linked to that board with the sender’s own grant; the existing sealed relay authenticates the sender and orders the ordinary shout. Another board’s address is refused with `SEAT_ADDRESS_BOARD`. An address grants no access, and revoked credentials cannot deliver a message.diff --git a/docs/formats.md b/docs/formats.mdindex aa186f46..4b24fad1 100644--- a/docs/formats.md+++ b/docs/formats.md@@ -672,3 +672,7 @@ not a native move, parent identity, configuration or authority record. Missing/dreplays activity. Reads freeze an event high-water mark before observing Git; subsequent eventsand messages remain pending. News has a separate cursor so an ordinary poll cannot consume afuture session-start digest.++## Seat addresses++A seat address is `pullboard:<board-id>:<percent-encoded-seat-id>`, where `board-id` is the board’s existing 32-character hexadecimal `board_id` and the seat component is the canonical JavaScript `encodeURIComponent` encoding of its registered agent id. It is independent of machine and checkout path. `whoami` and `agents` expose it; `shout` resolves it only within the current board and records the existing shout event with the exact recipient agent id. It is a destination, never a grant. Existing relay board credentials and authenticated sender attribution remain required on linked boards. No new stored event or file format is introduced.diff --git a/src/agent-tree.js b/src/agent-tree.jsindex f5adcd8b..bf42b2fe 100644--- a/src/agent-tree.js+++ b/src/agent-tree.js@@ -1,3 +1,4 @@+import { seatAddress } from './seat-address.js';/** The agents view: each agent with its seats, helpers and holds, from the board and this machine's parent notes [N2,B13]. */import { dirname } from 'node:path';import { COORDINATOR } from './config.js';@@ -16,6 +17,7 @@ import * as store from './board.js';*/export function agentTree(info, config, board) {const agents = store.listAgents(board);+ const boardId = store.boardId(board);const { parents, digests } = seatLinks(info, agents);// The coordinator is the main checkout; a board that never declared its seat still shows it once it has opened a helper.if (!agents.some((agent) => agent.agent_id === COORDINATOR) && [...parents.values()].includes(COORDINATOR)) {@@ -28,9 +30,9 @@ export function agentTree(info, config, board) {}const known = new Set(agents.map((agent) => agent.agent_id));const row = (agent, seen) => ({- id: agent.agent_id, parentSession: agent.agent_parent_session ?? null, displayName: displayAgentName(agent, config.agents.names), lane: agent.agent_lane, path: agent.agent_path,+ id: agent.agent_id, address: seatAddress(boardId, agent.agent_id), parentSession: agent.agent_parent_session ?? null, displayName: displayAgentName(agent, config.agents.names), lane: agent.agent_lane, path: agent.agent_path,seats: agents.filter((seat) => seat.agent_id === agent.agent_id || (digests.has(agent.agent_id) && digests.get(seat.agent_id) === digests.get(agent.agent_id)))- .map((seat) => ({ id: seat.agent_id, path: seat.agent_path })),+ .map((seat) => ({ id: seat.agent_id, address: seatAddress(boardId, seat.agent_id), path: seat.agent_path })),holds: held.get(agent.agent_id) ?? [],helpers: agents.filter((helper) => parents.get(helper.agent_id) === agent.agent_id && !seen.has(helper.agent_id)).map((helper) => row(helper, new Set([...seen, helper.agent_id]))),@@ -49,7 +51,7 @@ export function agentTreeLines(tree, indent = '') {if (!indent && !tree.length) return ['no agents have joined'];return tree.flatMap((agent) => {const held = agent.holds.map((hold) => `#${hold.item} (${hold.status})`).join(', ');- return [`${indent}${agent.displayName} (${agent.lane} lane) parent ${agent.parentSession ?? 'unknown'} at ${agent.path}${held ? `: ${held}` : ''}`, ...agentTreeLines(agent.helpers, indent + ' ')];+ return [`${indent}${agent.displayName} (${agent.lane} lane) parent ${agent.parentSession ?? 'unknown'} at ${agent.path} address ${agent.address}${held ? `: ${held}` : ''}`, ...agentTreeLines(agent.helpers, indent + ' ')];});}diff --git a/src/commands/shout.js b/src/commands/shout.jsindex 4df95125..a30f238e 100644--- a/src/commands/shout.js+++ b/src/commands/shout.js@@ -1,3 +1,5 @@+import { Refused } from '../refused.js';+import { addressedSeat } from '../seat-address.js';/** The pullboard shout command, in its own module so an item adding another command never edits these lines. */import * as store from '../board.js';import {@@ -20,16 +22,21 @@ import {export async function run(io, { first, second, rest, values }) {const act = (work) => actOn(io, work);return act(async (ctx, board, me) => {+ const recipient = addressedSeat(first, store.boardId(board));+ const addressed = typeof first === 'string' && first.startsWith('pullboard:');+ if (addressed && values.item !== undefined) throw new Refused('USAGE', 'use either a seat address or --item, not both');const evidence = values.evidence === undefined ? null : evidenceFrom(ctx, values);- const recipients = ['all', 'person', ...laneNames(ctx.config), ...board.db.prepare('SELECT agent_id FROM agent').all().map((agent) => agent.agent_id)];- const hasRecipient = first && recipients.includes(first) && (values.item === undefined || second !== undefined);- const to = values.item !== undefined ? `item:${values.item}` : hasRecipient ? first : values.decision ? (me.id === COORDINATOR ? 'person' : COORDINATOR) : first ?? '';+ const seatIds = board.db.prepare('SELECT agent_id FROM agent').all().map((agent) => agent.agent_id);+ if (addressed && recipient !== COORDINATOR && !seatIds.includes(recipient)) throw new Refused('NO_READER', 'copy the address of a joined seat from pullboard agents');+ const recipients = ['all', 'person', ...laneNames(ctx.config), ...seatIds];+ const hasRecipient = first && (addressed || recipients.includes(first)) && (values.item === undefined || second !== undefined);+ const to = values.item !== undefined ? `item:${values.item}` : hasRecipient ? recipient : values.decision ? (me.id === COORDINATOR ? 'person' : COORDINATOR) : first ?? '';const text = [hasRecipient ? second : first, ...(hasRecipient ? rest : [second, ...rest])].filter(Boolean).join(' ');const id = await ordered(ctx, board, 'shout', [{ from: personShout(io, me) ? store.PERSON : me.id, to, text, ...(values.item !== undefined ? { item: Number(values.item) } : {}), lanes: laneNames(ctx.config), decision: Boolean(values.decision), ...(values.news ? { news: true } : {}), evidence }]);io.result?.({ id, decision: Boolean(values.decision) });const agents = store.listAgents(board);- const recipient = agents.some((agent) => agent.agent_id === to) ? agentDisplayName(agents, ctx.config, to) : to;- io.say(values.decision ? `asked ${recipient} for a decision as #${id}; it stays open until someone runs: pullboard answer ${id} "<the decision>"` : `shouted to ${recipient}`);+ const recipientName = agents.some((agent) => agent.agent_id === to) ? agentDisplayName(agents, ctx.config, to) : to;+ io.say(values.decision ? `asked ${recipientName} for a decision as #${id}; it stays open until someone runs: pullboard answer ${id} "<the decision>"` : `shouted to ${recipientName}`);return 0;});}diff --git a/src/commands/whoami.js b/src/commands/whoami.jsindex 5acced54..b934f23c 100644--- a/src/commands/whoami.js+++ b/src/commands/whoami.js@@ -1,3 +1,5 @@+import { boardId } from '../board.js';+import { seatAddress } from '../seat-address.js';/** The pullboard whoami command, in its own module so an item adding another command never edits these lines. */import {context,@@ -8,8 +10,11 @@ import {/** Run `pullboard whoami` and return its exit code. */export function run(io) {const ctx = context(io);- const me = withBoard(ctx, (board) => whoAmI(ctx, board));+ const me = withBoard(ctx, (board) => {+ const agent = whoAmI(ctx, board);+ return { ...agent, address: seatAddress(boardId(board), agent.id) };+ });io.result?.({ ...me, path: ctx.info.root });- io.say(`${me.displayName} (${me.lane} lane${me.route === 'light' ? ', light route' : ''}) at ${ctx.info.root}`);+ io.say(`${me.displayName} (${me.lane} lane${me.route === 'light' ? ', light route' : ''}) at ${ctx.info.root}\naddress ${me.address}`);return 0;}diff --git a/src/json.js b/src/json.jsindex 046272e0..8c78ec55 100644--- a/src/json.js+++ b/src/json.js@@ -22,7 +22,7 @@ export const JSON_SHAPES = {takeover: shape({ agent: 'string', path: 'string' }),worktree: shape({ agent: 'string', lane: 'string', route: 'string', path: 'string', branch: 'string', prompt: 'string', model: 'string', displayName: 'string' }),resume: shape({ me: 'object', all: 'array', requests: 'array', holding: 'array', sentBack: 'array', awaiting: 'array', toVerify: 'array', toMerge: 'array', open: 'array', stale: 'array', doctrineNotes: 'array', holds: 'array', unread: 'number', newest: 'array', root: 'string', newWorktreeLocation: 'string', dirty: 'number', next: 'string' }),- whoami: shape({ id: 'string', lane: 'string', path: 'string', model: 'string', displayName: 'string' }),+ whoami: shape({ address: 'string', id: 'string', lane: 'string', path: 'string', model: 'string', displayName: 'string' }),agents: shape({ agents: 'array' }),lanes: shape({ lanes: 'object', shared: 'array', coordinator: 'string' }),'lane add': shape({ lane: 'string', owns: 'array' }),diff --git a/src/next-step-defaults.js b/src/next-step-defaults.jsindex e75f3dca..c9959188 100644--- a/src/next-step-defaults.js+++ b/src/next-step-defaults.js@@ -1,5 +1,6 @@/** General CLI recovery text; operation-owned codes live in src/moves/ [P4,C7]. */export const DEFAULT_NEXT_STEPS = Object.freeze({+ "SEAT_ADDRESS_BOARD": "open a linked checkout of the addressed board with your own grant, then run pullboard shout <address> <text>","GIT_SYNC_LOG": "restore the append-only refs/pullboard/board history on origin before running pullboard sync","GIT_SYNC_REMOTE": "restore read/write access to origin, then retry the original command or run pullboard sync; keep its pending sealed move","GIT_SYNC_LOCAL_CHANGED": "run pullboard export to preserve local moves, then ask the coordinator to reconcile the local and remote prefixes before syncing",diff --git a/src/seat-address.js b/src/seat-address.jsnew file mode 100644index 00000000..ac140bb7--- /dev/null+++ b/src/seat-address.js@@ -0,0 +1,22 @@+/** A stable seat address identifies a board and recipient; it never grants permission to that board [H2,H16]. */+import { Refused } from './refused.js';++/** Encode the persistent board identity and seat id, independently of a checkout path or machine. */+export function seatAddress(boardId, agentId) {+ return `pullboard:${boardId}:${encodeURIComponent(agentId)}`;+}++/** Resolve only addresses for this board; ordinary lane and seat names keep their existing meaning. */+export function addressedSeat(value, boardId) {+ if (typeof value !== 'string' || !value.startsWith('pullboard:')) return value;+ const match = /^pullboard:([0-9a-f]{32}):(.+)$/u.exec(value);+ let agent;+ try { agent = match && decodeURIComponent(match[2]); } catch { agent = null; /* Malformed address bytes never select a recipient. */ }+ if (!agent || seatAddress(match[1], agent) !== value) {+ throw new Refused('NO_READER', 'copy the exact seat address from pullboard whoami or pullboard agents');+ }+ if (match[1] !== boardId) {+ throw new Refused('SEAT_ADDRESS_BOARD', 'this address belongs to another board; open a linked checkout of that board with your own grant before sending');+ }+ return agent;+}diff --git a/test/move-registry-baseline.json b/test/move-registry-baseline.jsonindex 64427929..26e8bba7 100644--- a/test/move-registry-baseline.json+++ b/test/move-registry-baseline.json@@ -6881,6 +6881,7 @@"SEAL_FORMAT": "fetch the board again: pullboard relay","SEAL_KEY": "pair this device again: pullboard relay on --all","SEAL_VERSION": "upgrade Pullboard on this device: npm install -g pullboard@latest",+ "SEAT_ADDRESS_BOARD": "open a linked checkout of the addressed board with your own grant, then run pullboard shout <address> <text>","SELF_SHOUT": "name another agent, a lane or all: pullboard shout all \"<text>\"","SELF_VERIFY": "ask a different agent to verify it; from main create its worktree with pullboard worktree <lane> --model \"<model name>\"","SESSION_LEDGER": "make the agent-session ledger named in the message writable by this user, then run the command again",@@ -8106,6 +8107,7 @@"SEAL_FORMAT": "fetch the board again: pullboard relay","SEAL_KEY": "pair this device again: pullboard relay on --all","SEAL_VERSION": "upgrade Pullboard on this device: npm install -g pullboard@latest",+ "SEAT_ADDRESS_BOARD": "open a linked checkout of the addressed board with your own grant, then run pullboard shout <address> <text>","SELF_SHOUT": "name another agent, a lane or all: pullboard shout all \"<text>\"","SELF_VERIFY": "ask a different agent to verify it; from main create its worktree with pullboard worktree <lane> --model \"<model name>\"","SESSION_LEDGER": "make the agent-session ledger named in the message writable by this user, then run the command again",