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 #1221 with landed main [B2,B12,H16]

Corey Olsonf65570e5ea35
diff --cc docs/api.md
index 1d1f7789,8d8a47b5..3e39c53b
--- a/docs/api.md
+++ b/docs/api.md
@@@ -715,10 -721,14 +722,21 @@@ query; it does not execute the decisio
Consumers supply the existing canonical resolver as `resolveBoardRef(id) -> {boardId}` without alias normalization here, their local `boardId`, and a synchronous authenticated `authorize({action,boardId,document})` port. Actions are `accepted`, `declined`, and `receive-result`. The port must verify the appropriate source/destination authority for the exact document; there is no permissive default. The destination's synchronous `createChild(content)` port must perform its native child move on this same board and return its item id. Invoke these contracts inside the consumer's ordered move: child creation and the destination retry record share one SQLite transaction. Source result delivery is a separately authorized, idempotent transaction. These contracts add no offer orchestration, two-board transaction or landing sequencer.
`minimalItemReceipt(fields,{sign})` accepts only `{version:1,sourceBoardId,item,commit,verifier,verdict}` and appends `integrity:{digest,signature}` over canonical permitted bytes. `verifyItemReceipt(receipt,{resolveBoardRef,verify},expected)` requires all expected references to match, checks the digest, and calls `verify(bytes,signature,sourceBoardId)` against the consumer's established source trust. Signatures are supplied through the existing authority adapter; a digest alone proves no authority. Titles, criteria, notes and unknown fields are refused even on verification. Private landing consumers still establish the real landing and verdict before issuing this reduced envelope.
+
+
+## Companion requests
+
+`pullboard companion <parent> <lane> "<title>" --key <stable-key>` creates a normally claimable child in another lane. Its durable identity is the parent item, target lane and explicit key (1–80 letters, digits, dots, underscores or hyphens). Concurrent requests with that identity return the same child and `created: false` after the first creation. A retry returns the original child without changing its title, criterion, brief or claim, including after the parent closes; different keys name different work. Only open or claimed parents accept a new companion. Ordinary `add --parent` retains its same-lane rule.
+
+The request accepts ordinary `--criterion`, `--brief`, `--specs` and `--route` content. Only the coordinator may supply `--check`; other builders use the existing coordinator check-setting workflow. The child is built and independently verified by its own lane, using normal exclusive leases. Requesting or finding it never claims it. Parent completion still waits for unfinished child items. The authenticated `requestCompanion` move binds the lookup and child insertion in one transaction; its feature engine is assigned at landing, and older engines refuse it. Relay outbox bindings preserve both the parent input identity and the created child result when final item numbers differ.
+ ## Agent lifecycle nudges
+
+ `init` merges project-local Claude Code `.claude/settings.json` and Codex `.codex/hooks.json` handlers for `SessionStart` and `Stop`, preserving other handlers and settings. Each installed line resolves the local, main-checkout or PATH executable and calls `pullboard hook <event>`; a missing executable exits successfully without output. `init --no-hooks` skips these agent nudges. Existing Git gate hooks are independent. `hooks uninstall` removes only Pullboard's exact agent-handler lines.
+
+ `SessionStart` returns the normal resume card as `hookSpecificOutput.additionalContext`. `Stop` returns a `systemMessage` when this seat has committed, unsubmitted work. A local error or two-second worker timeout returns a warning and exit zero, with no blocking decision. Unknown events are silent no-ops. These shapes follow the current [Codex hooks](https://learn.chatgpt.com/docs/hooks) and [Claude Code hooks](https://code.claude.com/docs/en/hooks) contracts.
+
+ `doctor --json` adds `agentHooks`, with each vendor's `configured` flag, installed `events`, and `trust`. Codex trust is `unverified`: file installation never grants vendor trust, and the Stop reminder may be off until the person reviews the exact definitions with `/hooks`. Text doctor output reports configured hooks; with no agent-hook files it retains its existing one-line clean-board result.
+
+ ### 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 --cc docs/formats.md
index b7062f1e,afdf587b..be0d4395
--- a/docs/formats.md
+++ b/docs/formats.md
@@@ -678,4 -700,8 +701,9 @@@ 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.
+Companion requests use the `requestCompanion` move and the unassigned `COMPANION_ENGINE` boundary allocated at landing. The authenticated first argument names `agentId`, `parentId`, target `lane` and stable `key`. A `board_meta` key `companion:` plus SHA-256 of JSON `[parentId,lane,key]` binds that identity to its child. The immediate transaction creates the ordinary item, records its check baseline and bar, appends the companion event, and stores the binding. A retry returns the existing child without changing its contents or claim. Ordinary `addItem` parent-lane validation remains unchanged.
+ ## 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 docs/formats.test.js
index a193960d,e7df3f5a..0d0467b5
--- a/docs/formats.test.js
+++ b/docs/formats.test.js
@@@ -24,9 -24,10 +24,11 @@@ import { readEngineLeaves } from '../sr
import { applyEngineMove, prepareEngineMove } from '../src/engine.js';
import {
ACCEPT_REASON,
+ actOnActivity,
+ recordActivityDelivery,
answerDecision,
addItem,
+ requestCompanion,
appendFact,
claim,
closeBoard,
diff --cc src/board.js
index a1a0555b,5bb79ec8..c78735c0
--- a/src/board.js
+++ b/src/board.js
@@@ -1,5 -1,4 +1,6 @@@
+import { companionPlan } from './companion.js';
+import { applyCompanionRequest } from './companion.js';
+ 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';
diff --cc src/templates.js
index fd1081db,0b604a86..1fbe201d
--- a/src/templates.js
+++ b/src/templates.js
@@@ -150,8 -152,10 +152,10 @@@ For recurring checks, \`pullboard senti
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\`.
-If your item needs code another lane owns and it is not there yet, shout that lane and take another item. Never copy their code into your lane, and never build another lane's item, even one that was rejected and blocks you: shout that lane and the coordinator. A claim refused as BLOCKED names the item it waits on.
+If your item needs code another lane owns, run \`pullboard companion <parent> <lane> "<title>" --key <stable-key>\` to create its claimable child; reuse that parent, lane and key to find the existing companion. The other lane claims the child before building; a duplicate request never assigns a second builder. Then shout that lane and take another item. Never copy their code into your lane, and never build another lane's item, even one that was rejected and blocks you: shout that lane and the coordinator. A claim refused as BLOCKED names the item it waits on.
+ The activity feed separates interrupts from digest summaries. Read \`pullboard inbox\` at your next check; rejected work, lapsing claims, answers and changed working files remain pending until you act. After acting, use \`pullboard inbox --acted-on <interrupt-ids>\` with its comma-separated ids. The board records delivery separately from acknowledgement; a local cursor never means acted-on. A short digest arrives on your first inbox check in a session and after a successful submit, without raw activity bodies. \`pullboard resume\` remains read-only.
+
**Talk.** \`pullboard shout <lane|agent|all> "<text>"\`. Only the coordinator or person marks release or focus news with \`pullboard shout all "<release or focus news>" --news\`; it arrives as a one-line digest at session start. Keep governing instructions as ordinary shouts so they stay direct. Read \`pullboard inbox\` before you start and after you submit. Only the coordinator (the agent in the main checkout) talks with the person. Every other agent sends anything that needs the person—a decision, an approval, a waiver, a preview or a phone check—to the coordinator with \`pullboard shout coordinator "<what is needed>" --decision\`, and never asks the person in its own session, even when the person is watching. An MCP client can do the same as your agent: add \`pullboard mcp\`, run from your worktree, as a stdio server; it reads the board, shows an item, shouts and captures ideas for the coordinator, and never makes a person's move.
**Listen.** Where your client can run a command in the background, run \`pullboard watch --to <your id>\` there: it prints one line per event as it happens, and Claude Code wakes on each line when it runs under the Monitor tool. \`pullboard watch --work <lane>\` also says when an item in your lane becomes claimable, a review has waited too long, or main moves. Where your client cannot, read \`pullboard inbox\` at session start, after submit and before ending a turn. Coordinator answers and sentinel findings arrive there either way.
diff --cc test/move-registry-baseline.json
index c5714c62,dc7d7fa4..3cb95e7e
--- a/test/move-registry-baseline.json
+++ b/test/move-registry-baseline.json
@@@ -63,7 -63,8 +63,9 @@@
"takeCoordinator",
"landingLeaseMove",
"recordPublishFinding",
- "requestCompanion"
++ "requestCompanion",
+ "actOnActivity",
+ "recordActivityDelivery"
],
"itemIdFirstArgument": [
"signBar",