Skip to content

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.

chore(core): compose lane lead routing with current trunk [B21,H16]

Corey Olsonfc3c59094868
diff --cc docs/formats.md
index 2fced428,60617ceb..f01ea0ca
--- a/docs/formats.md
+++ b/docs/formats.md
@@@ -452,7 -451,9 +452,9 @@@ The `event` table is a SQLite schema ob
| `guards` | board | `missing`, `changed`, `stale` |
| `rigor-notice` | rigor | `cause`, `items`, `occurrences`, `neverAgain`, `engine`, automatic-Rigor `drafts` |
| `rigor-draft` | rigor | `id`, `target`, `cause`, exact typed `source`, `unproved` (always true), `items`, `occurrences`, `engine` |
+ | `activity-delivered` | recipient | `interrupts`, `through`, `observedThrough`, `digestThrough` |
+ | `activity-acted` | recipient | `interrupts` |
-| `shout` | sender | `shout`, `to`, `decision`, `request`, `answers` |
+| `shout` | sender | `shout`, `to`, `decision`, `request`, `answers`, `messageKind` |
| `shout_news` | sender | `shout`, `to`, `decision`, `request`, `answers` |
| `flake-observation` | reporting agent | `engine`, `observation` |
| `flake-repair` | reporting agent | `engine`, `key`, `item` |
@@@ -678,4 -692,8 +693,10 @@@ replays activity. Reads freeze an even
and messages remain pending. News has a separate cursor so an ordinary poll cannot consume a
future session-start digest.
+The lane-lead engine, numbered at landing, adds coordinator-only `setLaneLead` with `{agentId, lane, seat, lanes}`. The seat is an existing agent in that lane, or `null` to remove the lead. Its `lane-lead` event records `lane` and `seat`. Typed shout routing records `messageKind` (`question`, `blocker` or `decision`); a status shout is refused. Older recorded engines retain their original routing and event details. Questions and blockers go to the named lead; lead decisions and explicit escalations go to the coordinator. Naming a lead grants no claim, lease or person authority.
++
+ ## 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.
+
+ The activity-delivery engine, numbered at landing, adds recipient-owned `recordActivityDelivery` and `actOnActivity` moves. Interrupt ids bind a native event (`event:<id>`) or an exact claim lease (`claim:<item>:<lease-until>`). A delivery event lists only interrupts actually included in that recipient's response; an acted event records a separate explicit acknowledgement. An inbox cursor or reading a response never means acted-on. Both moves use the joined recipient as their authenticated actor, preserve earlier event history, and refuse on an older replay engine before changing its prefix. Delivery state in indexed `board_meta` keys is part of the native board and its exports, not a checkout-only cursor. `through` is the safely covered interrupt prefix, `observedThrough` is the read snapshot's high-water mark, and optional `digestThrough` is the separately delivered digest prefix; an elided interrupt must remain available after a later small interrupt is delivered.
diff --cc src/board.js
index ebfe0e2d,3b68d872..cbb021ac
--- a/src/board.js
+++ b/src/board.js
@@@ -1,12 -1,4 +1,14 @@@
+import { applyLaneLead } from './lane-lead-policy.js';
+import { applyHealthFindings } from './board-health.js';
+import {
+ isLaneEscalation,
+ laneLeads,
+ leadOwnsDecision,
+ routeLaneMessage,
+} from './lane-lead.js';
+export { laneLeads };
++
+ import * as activityDeliveryStore from './activity-delivery-store.js';
import { requireFactKind } from './item-notes.js';
import { activityNewsFlag } from './activity-news.js';
import { migrateEventLogVersion } from './board-event-log-migrate.js';
@@@ -2311,9 -2334,20 +2305,24 @@@ export function intakeOutside(board, op
/** Record the person's exact-commit owner approval. */
export function approveOutside(board, id, options) { return applyOutsideApproval(board, id, options, atomic); }
+/** Name a lane lead only through coordinator-owned ordered policy [B21]. */
+export function setLaneLead(board, options) {
+ return applyLaneLead(board, options, { atomic, logEvent });
+}
/** Tailored inbox activity is the same canonical read projection as other board queries. */
export { agentActivity } from './board-query.js';
+
+ /** Read recipient delivery state without mutating any cursor or receipt. */
+ export function activityDeliveryState(board, agentId) {
+ return activityDeliveryStore.activityDeliveryState(board, agentId);
+ }
+
+ /** Record the exact interrupts included in an authenticated recipient response. */
+ export function recordActivityDelivery(board, options) {
+ return activityDeliveryStore.recordActivityDelivery(board, options, { atomic, logEvent });
+ }
+
+ /** Record an explicit recipient acknowledgement separately from delivery. */
+ export function actOnActivity(board, options) {
+ return activityDeliveryStore.actOnActivity(board, options, { atomic, logEvent });
+ }
diff --cc src/cli-main.js
index b6393b95,fcb9c7a3..eb5382c2
--- a/src/cli-main.js
+++ b/src/cli-main.js
@@@ -128,8 -130,8 +130,9 @@@ const OPTIONS =
verbose: { type: 'boolean' },
since: { type: 'string' },
window: { type: 'string' },
+ policy: { type: 'string' },
decision: { type: 'boolean' },
+ kind: { type: 'string' },
news: { type: 'boolean' },
evidence: { type: 'string' },
outcome: { type: 'string' },
diff --cc src/commands/shout.js
index 1bd3f335,06e34a83..d7aea35c
--- a/src/commands/shout.js
+++ b/src/commands/shout.js
@@@ -21,17 -23,22 +23,22 @@@ 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(' ');
requireReadableShout(text);
- 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 }]);
+ 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.kind === undefined ? {} : { kind: values.kind }), ...(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 --cc src/help.js
index 68ab163a,695a5c71..7a8a7ffa
--- a/src/help.js
+++ b/src/help.js
@@@ -153,20 -158,20 +158,22 @@@ Wor
a verdict takes --implies <ids>; a later verdict on the item supersedes it
any --note can be --note-file <file>, which keeps quotes, $ and backticks intact
pullboard shout <lane|agent|person|all> <text> pullboard inbox
+ pullboard inbox --acted-on <interrupt-ids> acknowledge comma-separated ids only after acting; reading is not acting
pullboard shout --item <id> <text> message the item builder, reviewer and coordinator
A seat shout to all reaches only coordinator and person; their broadcasts reach everyone.
+ pullboard shout coordinator <text> --kind question|blocker --decision route through a named lane lead
+ pullboard lanes lead <lane> <seat|off> coordinator names or removes the existing lane seat
pullboard shout all <text> --news coordinator/person release or focus news, digested at session start
Inbox combines direct coordination with item/dependency, file and cited-row activity; other lane activity is summarized.
pullboard shout [<to>] <text> --decision ask for a decision; defaults to your coordinator or the person
pullboard shout <to> <text> --evidence attempt|receipt --outcome <word> --item <id> --commit <rev>
- pullboard answer <shout-id> <text> [--as person] [--implies <ids>] [--supersedes <answer-id>]
- [--origin person-relayed|agent|inherited] [--rationale <why>]
+ pullboard answer <shout-id> <text> [--as person]
answer your decision; person mode is main-checkout only
+ Other options: [--implies <ids>] [--supersedes <answer-id>]
+ [--origin person-relayed|agent|inherited] [--rationale <why>]
--supersedes tells the items an earlier answer implied; only the person
supersedes the person's answer
- pullboard pass <shout-id> <note> coordinator passes a decision to the person
+ pullboard pass <shout-id> <note> lead escalates to coordinator; coordinator passes to person
pullboard decisions [--as person] shouts waiting for you; main checkout defaults to coordinator
pullboard watch [--to <agent|lane|all>] [--kinds <kinds>] [--item <id>] [--since <sequence>] [--json]
[--work <lane>] [--review-wait <minutes>]
diff --cc src/recorded-move.js
index 2fdf2d0f,27da8b43..ec66ee4f
--- a/src/recorded-move.js
+++ b/src/recorded-move.js
@@@ -28,9 -28,10 +28,10 @@@ export function requestedCommandMove(co
refreeze: ['refreeze'], reopen: ['reopen'], escalate: ['escalate', 'shout'],
next: ['claim', 'reserveReview', 'reserveNextReview'], run: ['claim', 'release', 'submit', 'reserveReview', 'reserveNextReview', 'verify', 'escalate', 'shout'],
init: ['register'], join: ['register'], worktree: ['register'], takeover: ['takeCoordinator'],
+ inbox: ['recordActivityDelivery', 'actOnActivity'],
shout: ['shout'], answer: ['answerDecision'], pass: ['passDecision'], fact: ['appendFact'],
hold: ['holdLane', 'releaseLane', 'holdItem', 'releaseItemHold'],
- bar: ['setBarReady', 'signBar'], settings: ['setLineSetting', 'setPersonSigning'], check: ['acceptCheck'],
+ lanes: ['setLaneLead'], bar: ['setBarReady', 'signBar'], settings: ['setLineSetting', 'setPersonSigning'], check: ['acceptCheck'],
spec: ['recordRowDecisions', 'decideSpecRevisions', 'applyRowDecisions', 'draftSpecRow', 'appendFact', 'editItem', 'withdraw'],
blueprint: ['draftSpecRow', 'addItem', 'appendFact'], rigor: ['draftSpecRow', 'proposeSentinel'], sweep: ['addItem'],
milestone: ['addMilestone', 'editMilestoneItems', 'orderMilestoneItems', 'moveMilestone', 'editMilestone', 'removeMilestone', 'shipMilestone'],
diff --cc src/templates.js
index 5c80b735,0b604a86..197a6637
--- a/src/templates.js
+++ b/src/templates.js
@@@ -144,10 -144,10 +144,12 @@@ When a reject names a structured cause
6. A reject reopens the item. Fix it, commit, claim, submit again; the same head is refused. If you cannot get an item green, do not force it: \`pullboard escalate <id> --note "what you tried and how it failed"\` hands it one tier up.
7. Your lane is done when its items are verified, not when they are submitted. After your last submit, keep running \`pullboard next --wait 9\`: a rejected item comes back to your lane.
- The coordinator merges verified items into the main line; builders never merge. When a release ships, the coordinator runs \`pullboard milestone ship <name>\`: it records main's commit and moves the items that have not landed into the next milestone. \`pullboard health\` lists every stuck item: a lapsed claim, a review nobody took, accepted work that never landed, an old hold, an unanswered decision. Each line says why, since when, the next step and who takes it; run it at the start of a session and take the steps that name you.
+ The coordinator merges verified items into the main line; builders never merge. When a release ships, the coordinator runs \`pullboard milestone ship <name>\`: it records main's commit and moves the items that have not landed into the next milestone. The queue orders itself by what each item unblocks and what it costs; the coordinator holds an item above that order with \`pullboard milestone pin <name> <ids> --reason "<why>"\`, below it with \`pullboard milestone sink <name> <ids> --reason "<why>"\`, and returns it with \`pullboard milestone lift <name> <ids>\`. \`pullboard health\` lists every stuck item: a lapsed claim, a review nobody took, accepted work that never landed, an old hold, an unanswered decision. Each line says why, since when, the next step and who takes it; run it at the start of a session and take the steps that name you.
+
+ **Replay flow.** Run \`pullboard flow replay --json\` to reproduce recorded landing order and stage quartiles from text-free lifecycle history. To compare a hypothetical order and board line settings, run \`pullboard flow replay --history history.json --policy policy.json --json\` with the exported version-1 history and a JSON policy containing \`order\` and \`settings\`. Recorded work durations stay fixed; alternate queue times are deterministic predictions, not measured speedups.
+Lane leads are off until the coordinator names an existing lane seat with \`pullboard lanes lead <lane> <seat|off>\`. Questions and blockers sent with \`pullboard shout coordinator "<text>" --kind question|blocker --decision\` reach that lead. The lead answers or uses \`pullboard pass <shout-id> "<why>"\` to escalate to the coordinator; only its decisions and escalations go upward. Status stays activity, not a coordination shout. A lead gains no claim, lease or person-approval authority.
+
For recurring checks, \`pullboard sentinels\` lists this board's watches, their approvals and their latest results. Propose one with \`pullboard sentinel propose <name> --check "<command>" --every hourly --owner coordinator\`; a proposal does not run until the person approves its exact command, directory and schedule. Only the person runs \`pullboard sentinel approve <name>\` or \`pullboard sentinel decline <name> --reason "<why>"\` from their own terminal or Pullboard View. Agents never approve their own proposals; send the decision to the coordinator.
For spare test capacity, use \`pullboard runner add <ssh-host> --slots <n> --browser <n>\`. It registers SSH capacity on this machine; \`pullboard runner list\` shows each runner's registered slots and browsers, and \`pullboard resources\` shows their usage. Only committed source goes to a runner, and board moves stay here. To see whether this board is linked to the relay, and for which GitHub account, run \`pullboard relay status\`.
diff --cc test/move-registry-baseline.json
index 51225c3d,dc7d7fa4..2f71861a
--- a/test/move-registry-baseline.json
+++ b/test/move-registry-baseline.json
@@@ -63,7 -63,8 +63,9 @@@
"takeCoordinator",
"landingLeaseMove",
"recordPublishFinding",
+ "actOnActivity",
- "recordActivityDelivery"
++ "recordActivityDelivery",
+ "setLaneLead"
],
"itemIdFirstArgument": [
"signBar",
@@@ -633,13 -634,21 +635,29 @@@
null,
null
],
+ "actOnActivity": [
+ null,
+ "first",
+ null,
+ null,
+ null,
+ null
+ ],
+ "recordActivityDelivery": [
+ null,
+ "first",
+ null,
+ null,
+ null,
+ null
++ ],
+ "setLaneLead": [
+ null,
+ "first",
+ null,
+ null,
+ null,
+ null
]
},
"floorCases": [
@@@ -6962,11 -6974,9 +6983,14 @@@
"WRONG_LANE": "create a worktree in the required lane with pullboard worktree <lane> --model \"<model name>\", or take an item in your lane with pullboard next",
"EXCLUDED_REPOSITORY": "restore the GitHub origin of each excluded project, then run pullboard relay on --all",
"EXCLUDED_INVENTORY": "restore at most 256 excluded boards and their active paired devices, then run pullboard relay on --all",
+ "BAD_ACTIVITY_RECEIPT": "read your own inbox again and use its exact interrupt ids",
+ "ACTIVITY_NOT_DELIVERED": "read your own inbox before marking its interrupt acted on",
- "STALE_ACTIVITY_RECEIPT": "read inbox again; the claim changed before delivery was recorded"
++ "STALE_ACTIVITY_RECEIPT": "read inbox again; the claim changed before delivery was recorded",
+ "BAD_LANE_LEAD": "name a configured lane and an existing seat in that lane, or off",
+ "BAD_MESSAGE_KIND": "use --kind question, blocker or decision",
+ "STATUS_IS_ACTIVITY": "keep working on the item; status is board activity, not a shout",
+ "LANE_MESSAGE_ITEM": "omit --kind for an item-specific message",
+ "NOT_LANE_LEAD": "ask your named lane lead to send the decision upward"
},
"replay": {
"initial": {
diff --cc test/relay-credential.test.js
index b4b4739e,e4b5957d..a8e63986
--- a/test/relay-credential.test.js
+++ b/test/relay-credential.test.js
@@@ -29,9 -29,10 +29,11 @@@ test('every current operation selects i
if (['claim', 'refreeze'].includes(operation)) args = [box.before.tables.item[0].item_id, options];
if (operation === 'reserveNextReview') args = [options];
if (operation === 'setLineSetting') args = [{ agentId: actor, key: 'reviewsFirst', value: true, reason: 'credential fixture', window: { windowMinutes: 60, activeReviewers: 1 } }];
+ if (operation === 'setLaneLead') args = [{ agentId: actor, lane: box.lane, seat: null, lanes: [box.lane] }];
if (operation === 'setBarReady') args = [{ agentId: actor, enabled: false }];
if (operation === 'recordHealthFindings') args = [{ agentId: actor, observedRevision: 0, findings: [] }];
+ if (operation === 'recordActivityDelivery') args = [{ agentId: actor, through: 0, interrupts: [] }];
+ if (operation === 'actOnActivity') args = [{ agentId: actor, ids: ['event:1'] }];
if (operation === 'recordSpecApprovalBaseline') args = [{ agentId: actor, baseline: { version: 1, file: 'SPEC.md', anchor: null, rows: [] } }];
if (operation === 'recordFlakeObservation') args = [{ agentId: actor, lane: box.lane, observation: syntheticFlakeObservation('credential-fixture') }];
if (operation === 'recordGateRun') args = [{ agentId: actor, lane: box.lane, receipt: { version: 1, id: '00000000-0000-4000-8000-00000000c0de', kind: 'gate', tree: 'b'.repeat(40), head: 'a'.repeat(40),