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.

feat(companion): deduplicate cross-lane child requests [B2,B12,H16]

Corey Olsonafd503b769f1
diff --git a/docs/api.md b/docs/api.md
index 34edf335..ffb162d4 100644
--- a/docs/api.md
+++ b/docs/api.md
@@ -105,6 +105,7 @@ For example: `flow: review wait average 61 min (1 measured; > 60 min); bottlenec
| `milestone edit` | `version:number`, `milestone:object` |
| `milestone remove` | `version:number`, `milestone:object` |
| `milestone ship` | `version:number`, `milestone:object`, `into:string|null`, `moved:array`, `notMoved:array` |
+| `companion` | `version:number`, `item:object`, `created:boolean` |
| `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` |
@@ -673,3 +674,10 @@ When `publish.pullRequest` is enabled, `pullboard publish` reconciles the GitHub
A 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.
+
+
+## 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.
diff --git a/src/board.js b/src/board.js
index 38e71024..b94b452f 100644
--- a/src/board.js
+++ b/src/board.js
@@ -1,3 +1,4 @@
+import { companionPlan, applyCompanionRequest } from './companion.js';
import { activityNewsFlag } from './activity-news.js';
import { migrateEventLogVersion } from './board-event-log-migrate.js';
import {
@@ -654,24 +655,38 @@ function checkRouted({ brief, route, criterion, check }) {
*/
export function addItem(board, { by, lane, title, criterion = '', specIds = [], parentId = null, after = [], brief = '', route = 'strong', check, checkBaseline, barActor }) {
return atomic(board, () => {
- const { command, cleanTitle } = validateItemAddition(board, { by, lane, title, criterion, parentId, after, brief, route, check });
- const baseline = normalizeCheckBaseline(by, command, checkBaseline);
- const at = now(board);
- const result = board.db
- .prepare(
- `INSERT INTO item (item_parent_id, item_lane, item_title, item_criterion, item_spec_ids,
- item_after, item_brief, item_route, item_check, item_created_by, item_created_at, item_updated_at)
- VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
- )
- .run(parentId, lane, cleanTitle, criterion.trim(), specIds.join(','), after.join(','), brief.trim(), route, command, by, at, at);
- const id = Number(result.lastInsertRowid);
- saveCheckBaseline(board, id, baseline);
- logEvent(board, by, 'add', id, { lane, specIds, after, route, ...(baseline ? { checkBaseline: baseline } : {}) });
- recordBarRevision(board, itemById(board, id), by, null, barActor);
- return id;
+ const item = { by, lane, title, criterion, specIds, parentId, after, brief, route, check, checkBaseline, barActor };
+ return insertItem(board, item, validateItemAddition(board, item));
});
}
+/** Insert an already validated ordinary or companion child without bypassing check or bar recording. */
+function insertItem(board, item, { command, cleanTitle }) {
+ const { by, lane, criterion, specIds, parentId, after, brief, route, checkBaseline, barActor } = item;
+ const baseline = normalizeCheckBaseline(by, command, checkBaseline);
+ const at = now(board);
+ const result = board.db
+ .prepare(
+ `INSERT INTO item (item_parent_id, item_lane, item_title, item_criterion, item_spec_ids,
+ item_after, item_brief, item_route, item_check, item_created_by, item_created_at, item_updated_at)
+ VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+ )
+ .run(parentId, lane, cleanTitle, criterion.trim(), specIds.join(','), after.join(','), brief.trim(), route, command, by, at, at);
+ const id = Number(result.lastInsertRowid);
+ saveCheckBaseline(board, id, baseline);
+ logEvent(board, by, 'add', id, { lane, specIds, after, route, ...(baseline ? { checkBaseline: baseline } : {}) });
+ recordBarRevision(board, itemById(board, id), by, null, barActor);
+ return id;
+}
+
+/** Read the canonical request plan before a CLI performs any authorized baseline work. */
+export function planCompanion(board, options) { return companionPlan(board, options, validateItemAddition); }
+
+/** The single ordered operation permitted to create a child in a different lane. */
+export function requestCompanion(board, options) {
+ return applyCompanionRequest(board, options, { validateAddition: validateItemAddition, insertItem });
+}
+
/** Validate that dependencies exist, remain usable, and cannot lead back to the edited item. */
function validateItemDependencies(board, itemId, after) {
const direct = after.map((dependency) => itemById(board, dependency));
diff --git a/src/cli-main.js b/src/cli-main.js
index bc2553dc..ad62778b 100644
--- a/src/cli-main.js
+++ b/src/cli-main.js
@@ -238,7 +238,7 @@ async function bindCheckoutSession(io, positionals, values) {
if (command === 'takeover' && (positionals.length !== 1 || Object.keys(values).some((key) => key !== 'json'))) {
throw new Refused('USAGE', 'pullboard takeover takes no arguments; run pullboard takeover [--json]');
}
- const writes = ['handoff', 'bar', 'init', 'join', 'worktree', 'hooks', 'hook', 'skills', 'add', 'edit', 'fact', 'escalate', 'run', 'sweep',
+ const writes = ['handoff', 'bar', 'init', 'join', 'worktree', 'hooks', 'hook', 'skills', 'add', 'companion', 'edit', 'fact', 'escalate', 'run', 'sweep',
'next', 'claim', 'hold', 'release', 'submit', 'done', 'verify', 'check', 'merged', 'land', 'withdraw', 'refreeze', 'reopen', 'shout', 'answer', 'pass', 'import', 'milestone', 'takeover', 'forget'];
if (!writes.includes(command) && !(command === 'lane' && first === 'add') && !(command === 'settings' && first) && !(command === 'spec' && first === 'apply') && !(command === 'relay' && ['on', 'off'].includes(first))) return;
if (command === 'answer' && values.as === 'person') return;
diff --git a/src/cli.js b/src/cli.js
index d83617d7..7039914b 100644
--- a/src/cli.js
+++ b/src/cli.js
@@ -580,7 +580,7 @@ export async function ordered(ctx, board, operation, args) {
const joined = store.agentAt(board, ctx.info.root)?.agent_id;
args = [{ ...args[0], createdBy: ctx.info.isMain ? COORDINATOR : joined ?? 'machine' }, ...args.slice(1)];
}
- const command = ['add', 'edit', 'merged'].includes(ctx.io.relayCommand?.cliOperation) ? ctx.io.relayCommand : undefined;
+ const command = ['add', 'companion', 'edit', 'merged'].includes(ctx.io.relayCommand?.cliOperation) ? ctx.io.relayCommand : undefined;
/** Dispatch while this session holds the checkout, including long-running next/run loops. */
const execute = async () => {
/** Keep bootstrap in the same authenticated seat, without borrowing a person's action receipt. */
diff --git a/src/commands/companion.js b/src/commands/companion.js
new file mode 100644
index 00000000..b98966b7
--- /dev/null
+++ b/src/commands/companion.js
@@ -0,0 +1,45 @@
+/** Ask another lane for one durable child rather than starting duplicate companion work [B2,B12]. */
+import * as store from '../board.js';
+import { isLane } from '../lanes.js';
+import { Refused } from '../refused.js';
+import { idProblems, loadSpec } from '../spec.js';
+import { checkBaseline, prepareCheckBaseline, refuseCheckSyntax, sayCheckBaseline } from '../check-baseline.js';
+import { relayCommandReceipt, relayCommandReceiptReported } from '../relay.js';
+import { actOn, barActorForCommand, briefArg, briefInLane, idArg, idList, launchBaseline, ordered, buildInFilelessLane } from '../cli.js';
+
+/** Execute the normal authenticated request; only the coordinator may supply a check command. */
+export async function run(io, { first, second, rest, values }) {
+ return actOn(io, async (ctx, board, me) => {
+ const recovered = await relayCommandReceipt(ctx.info.root, io.relayCommand);
+ let result;
+ if (recovered) {
+ io.recordedMove = true;
+ for (const event of recovered.events) io.onEvent?.(event);
+ result = recovered.result;
+ } else {
+ if (!isLane(ctx.config, second)) throw new Refused('NO_LANE', `no lane "${second ?? ''}"; see pullboard lanes`);
+ const specIds = idList(values.specs);
+ const problems = idProblems(loadSpec(ctx.info.root, ctx.config), specIds, ctx.doctrine);
+ if (problems.length) throw new Refused('UNKNOWN_SPEC', problems.join('; '));
+ buildInFilelessLane(ctx.config, second, []);
+ const request = { agentId: me.id, parentId: idArg(first), lane: second, key: values.key,
+ title: rest.join(' '), criterion: values.criterion ?? '', specIds,
+ brief: briefInLane(ctx, second, briefArg(io, values) ?? ''), route: values.route ?? 'strong', check: values.check,
+ barActor: barActorForCommand(ctx, board, { asPerson: false }) };
+ const plan = store.planCompanion(board, request);
+ if (!plan.existing && plan.validated.command) {
+ refuseCheckSyntax(plan.validated.command);
+ request.checkBaseline = values.wait ? checkBaseline(ctx.info.root, plan.validated.command)
+ : prepareCheckBaseline(ctx.info.root, plan.validated.command);
+ }
+ result = await ordered(ctx, board, 'requestCompanion', [request]);
+ if (result.created && request.checkBaseline?.result === 'pending') await launchBaseline(ctx, board, result.item, request.checkBaseline);
+ }
+ const item = store.getItem(board, result.item);
+ io.result?.({ item, created: result.created });
+ io.say(`${result.created ? 'created' : 'existing'} companion #${item.item_id} in ${item.item_lane}; claim that item before building it`);
+ sayCheckBaseline(io, item);
+ if (recovered) await relayCommandReceiptReported(ctx.info.root, recovered.move.id);
+ return 0;
+ });
+}
diff --git a/src/companion-engine.js b/src/companion-engine.js
new file mode 100644
index 00000000..b3e4703f
--- /dev/null
+++ b/src/companion-engine.js
@@ -0,0 +1,3 @@
+/** Atomic cross-lane companion requests receive their replay number at landing [B2,B12,H16]. */
+import { unassignedEngine } from './engine-next.js';
+export const COMPANION_ENGINE = unassignedEngine();
diff --git a/src/companion.js b/src/companion.js
new file mode 100644
index 00000000..77aba192
--- /dev/null
+++ b/src/companion.js
@@ -0,0 +1,51 @@
+/** One durable request identity creates one normally claimable cross-lane child [B2,B5,B12]. */
+import { createHash } from 'node:crypto';
+import { itemById, listAgents } from './board-query.js';
+import { atomic, logEvent } from './board-event-log.js';
+import { ENGINE_VERSION } from './machine.js';
+import { COMPANION_ENGINE } from './companion-engine.js';
+import { Refused } from './refused.js';
+
+/** Plan a request without writes; the same validation runs again inside its creation transaction. */
+export function companionPlan(board, options, validateAddition) {
+ const { agentId, parentId, lane, key, title = '', criterion = '', specIds = [], brief = '', route = 'strong', check, checkBaseline, barActor } = options;
+ if ((board.executionEngineVersion ?? ENGINE_VERSION) < COMPANION_ENGINE) throw new Refused('ENGINE_VERSION', `companion requests require engine ${COMPANION_ENGINE}; upgrade Pullboard`);
+ if (!listAgents(board).some(agent => agent.agent_id === agentId)) throw new Refused('NOT_JOINED', 'join this board before requesting companion work');
+ if (!Number.isSafeInteger(parentId) || parentId < 1) throw new Refused('COMPANION_PARENT', 'name the parent item: pullboard companion <parent> <lane> "<title>" --key <key>');
+ if (typeof key !== 'string' || !/^[A-Za-z0-9][A-Za-z0-9._-]{0,79}$/u.test(key)) throw new Refused('COMPANION_KEY', 'supply a stable --key of 1 to 80 letters, digits, dots, underscores or hyphens; reuse it for this same companion');
+ if (typeof lane !== 'string' || !/^[a-z][a-z0-9-]*$/u.test(lane)) throw new Refused('NO_LANE', 'name the companion lane; see pullboard lanes');
+ const parent = itemById(board, parentId);
+ if (parent.item_lane === lane) throw new Refused('COMPANION_LANE', `the parent already belongs to ${lane}; request its companion in another lane`);
+ const index = 'companion:' + createHash('sha256').update(JSON.stringify([parentId, lane, key])).digest('hex');
+ const saved = board.db.prepare('SELECT meta_value FROM board_meta WHERE meta_key=?').get(index);
+ if (saved) {
+ const record = JSON.parse(saved.meta_value);
+ const child = itemById(board, record.item);
+ if (record.parentId !== parentId || record.lane !== lane || record.key !== key || child.item_parent_id !== parentId || child.item_lane !== lane) {
+ throw new Refused('COMPANION_RECORD', 'the companion index does not match its child; restore a consistent board export before requesting it again');
+ }
+ return { existing: child.item_id };
+ }
+ if (!['open', 'claimed'].includes(parent.item_status)) throw new Refused('PARENT_CLOSED', `parent #${parentId} is ${parent.item_status}; reopen it before adding companion work`);
+ if ([title, criterion, brief].some(value => typeof value !== 'string') || !Array.isArray(specIds) || specIds.some(id => typeof id !== 'string')) {
+ throw new Refused('COMPANION_CONTENT', 'supply title, criterion and brief text, and a list of existing spec ids');
+ }
+ const item = { by: agentId, parentId, lane, title, criterion, specIds, brief, route, check, checkBaseline, barActor, after: [] };
+ // Reuse every ordinary content/check guard; only this typed operation supplies a cross-lane parent.
+ const validated = validateAddition(board, { ...item, parentId: null });
+ return { item, validated, index, key };
+}
+
+/** Serialize the lookup, ordinary item insertion and durable request binding as one immediate move. */
+export function applyCompanionRequest(board, options, { validateAddition, insertItem }) {
+ return atomic(board, () => {
+ const plan = companionPlan(board, options, validateAddition);
+ if (plan.existing) return { item: plan.existing, created: false };
+ const id = insertItem(board, plan.item, plan.validated);
+ const { parentId, lane } = plan.item;
+ board.db.prepare('INSERT INTO board_meta(meta_key,meta_value) VALUES (?,?)')
+ .run(plan.index, JSON.stringify({ parentId, lane, key: plan.key, item: id }));
+ logEvent(board, options.agentId, 'companion', parentId, { item: id, lane, key: plan.key });
+ return { item: id, created: true };
+ });
+}
diff --git a/src/help.js b/src/help.js
index d627754c..6c1ccfec 100644
--- a/src/help.js
+++ b/src/help.js
@@ -116,6 +116,9 @@ Work
reads the board and changes nothing; exits 1 when something is stuck
pullboard.json health.stuck (default 1h), health.holds (1d), health.release (1d)
pullboard skills --update refresh unchanged Claude Code skills from shipped versions
+ pullboard companion <parent> <lane> "<title>" --key <key> [--criterion "<criterion>"] [--specs <ids>]
+ create one child in another lane; repeat the same parent, lane and key to find it
+ --brief "<brief>"; --route strong|mid|light; only the coordinator sets --check "<command>"
pullboard show <id> [--history] an item, the criterion frozen at claim, its verdicts: the latest in full,
earlier ones as one line; --history prints every note in full
pullboard fact <id> <kind> <text> [--answers <bar-check-fact-id>] [--supersedes <fact-id>] [--ref path:lines@full-sha] [--implies <ids>]
@@ -305,6 +308,7 @@ const HELP_EXAMPLES = {
tour: 'pullboard tour', init: 'pullboard init --blueprint web-app', worktree: 'pullboard worktree web --model "my-model"',
join: 'pullboard join web --model "my-model"', resume: 'pullboard resume',
intake: 'pullboard intake https://github.com/owner/repo/pull/7 --criterion "behavior" --check "npm test"',
+ companion: 'pullboard companion 12 api "Provide the API" --key api-part',
add: ADD_EXAMPLE, list: 'pullboard list web', show: 'pullboard show 12',
claim: 'pullboard claim 12', submit: 'pullboard submit 12', 'next --verify': 'pullboard next --verify',
fact: 'pullboard fact 12 measurement "The check passes in 8 seconds"',
diff --git a/src/json.js b/src/json.js
index 046272e0..59f2b29f 100644
--- a/src/json.js
+++ b/src/json.js
@@ -41,6 +41,7 @@ export const JSON_SHAPES = {
'milestone edit': shape({ milestone: 'object' }),
'milestone remove': shape({ milestone: 'object' }),
'milestone ship': shape({ milestone: 'object', into: 'string|null', moved: 'array', notMoved: 'array' }),
+ companion: shape({ item: 'object', created: 'boolean' }),
show: shape({ item_id: 'number', item_title: 'string', item_lane: 'string', item_status: 'string', verdicts: 'array', thread: 'array' }),
stats: shape({ stats: 'object', gateWaits: 'array' }),
badge: shape({ items: 'number', checked: 'number', percent: 'number|null', changed: 'array' }),
diff --git a/src/moves/requestCompanion.js b/src/moves/requestCompanion.js
new file mode 100644
index 00000000..5234d918
--- /dev/null
+++ b/src/moves/requestCompanion.js
@@ -0,0 +1,11 @@
+/** Cross-lane requests have one authenticated actor and their own replay boundary [B2,B12,H16]. */
+import { COMPANION_ENGINE } from '../companion-engine.js';
+
+/** Earlier moves cannot create companion children. */
+function minimumEngine() { return COMPANION_ENGINE; }
+
+/** Bind the request to the joined seat that asks for it. */
+function actor(move) { return move.args[0]?.agentId ?? null; }
+
+export default Object.freeze({ operation: 'requestCompanion', engine: COMPANION_ENGINE,
+ itemIdFirstArgument: false, minimumEngine, actor, nextSteps: Object.freeze({}) });
diff --git a/src/next-step-defaults.js b/src/next-step-defaults.js
index e75f3dca..a2cac9fe 100644
--- a/src/next-step-defaults.js
+++ b/src/next-step-defaults.js
@@ -1,5 +1,11 @@
/** General CLI recovery text; operation-owned codes live in src/moves/ [P4,C7]. */
export const DEFAULT_NEXT_STEPS = Object.freeze({
+ "COMPANION_PARENT": "name the parent item: pullboard companion <parent> <lane> \"<title>\" --key <key>",
+ "COMPANION_KEY": "supply a stable --key and reuse it for this same parent and target lane",
+ "COMPANION_LANE": "choose a different target lane; ordinary same-lane children use pullboard add --parent",
+ "COMPANION_CONTENT": "supply title, criterion and brief text and existing spec ids for the companion",
+ "COMPANION_RECORD": "restore a consistent board export so the companion request index matches its child",
+
"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/recorded-move.js b/src/recorded-move.js
index 187175dd..2dfdfd86 100644
--- a/src/recorded-move.js
+++ b/src/recorded-move.js
@@ -23,7 +23,7 @@ export function recordedMoveRefusal(io, error) {
export function requestedCommandMove(command, operation) {
if (!command) return false;
const forms = {
- add: ['addItem'], edit: ['editItem'], merged: ['merged'], submit: ['submit'],
+ add: ['addItem'], companion: ['requestCompanion'], edit: ['editItem'], merged: ['merged'], submit: ['submit'],
claim: ['claim'], release: ['release'], verify: ['verify'], withdraw: ['withdraw', 'editMilestoneItems'],
refreeze: ['refreeze'], reopen: ['reopen'], escalate: ['escalate', 'shout'],
next: ['claim', 'reserveReview', 'reserveNextReview'], run: ['claim', 'release', 'submit', 'reserveReview', 'reserveNextReview', 'verify', 'escalate', 'shout'],
diff --git a/src/relay-created-items.js b/src/relay-created-items.js
index ac854256..4e05b772 100644
--- a/src/relay-created-items.js
+++ b/src/relay-created-items.js
@@ -1,5 +1,5 @@
/** Explicit result bindings for item-creating moves; input item fields never become created-item identities [B26,H16]. */
-const SINGLE = Object.freeze({ addItem: [], intakeOutside: [], openHandoff: ['item'],
+const SINGLE = Object.freeze({ addItem: [], requestCompanion: ['item'], intakeOutside: [], openHandoff: ['item'],
recordLandingFlake: ['item'], recordLandingTestDefect: ['item'], recordFlakeObservation: ['item'],
recordPublishFinding: ['repair'] });
diff --git a/src/relay-outbox.js b/src/relay-outbox.js
index c1c65150..b10f8efe 100644
--- a/src/relay-outbox.js
+++ b/src/relay-outbox.js
@@ -169,6 +169,7 @@ const FIRST_ITEM = ['approveOutside', 'signBar', 'editItem', 'completeCheckBasel
*/
export const ITEM_SLOTS = Object.freeze({
setBarReady: [], setLineSetting: [],
+ requestCompanion: [[0, 'parentId']],
recordPublishFinding: [[0, 'item']],
register: [], ensureCoordinator: [], shout: [], passDecision: [], holdLane: [], releaseLane: [],
moveMilestone: [], editMilestone: [], removeMilestone: [], shipMilestone: [],
diff --git a/src/relay.js b/src/relay.js
index 23b1e2c1..548f3173 100644
--- a/src/relay.js
+++ b/src/relay.js
@@ -1348,7 +1348,7 @@ export async function relayCommandReceipt(root, command) {
if (!state) {
const recovered = deletedRecovery(root);
if (!recovered || recovered.marker.recovered.commandIntent !== intentDigest(operationIntent('cli:' + command.cliOperation, command))) return null;
- const expected = { add: 'addItem', edit: 'editItem', merged: 'merged' }[command.cliOperation];
+ const expected = { add: 'addItem', companion: 'requestCompanion', edit: 'editItem', merged: 'merged' }[command.cliOperation];
if (recovered.move.operation !== expected) throw new Refused('RELAY_STORAGE', 'restore the interrupted command receipt before retrying');
if (recovered.receipt.outcome.error) {
clearDeletedRecovery(root, recovered.marker);
@@ -1362,7 +1362,7 @@ export async function relayCommandReceipt(root, command) {
if (recovered.commandIntent !== operationIntent('cli:' + recovered.command?.cliOperation, recovered.command)) {
throw new Refused('RELAY_STORAGE', 'restore the interrupted command metadata before retrying');
}
- const expected = { add: 'addItem', edit: 'editItem', merged: 'merged' }[command.cliOperation];
+ const expected = { add: 'addItem', companion: 'requestCompanion', edit: 'editItem', merged: 'merged' }[command.cliOperation];
if (!recovered.move || recovered.move.operation !== expected) throw new Refused('RELAY_STORAGE', 'restore the interrupted command metadata before retrying');
const move = recoveredMove(root, state, recovered.move.operation, recovered.move.args, command);
const receipt = localRecords(root, board => engineReceipt(board, move.id));
diff --git a/src/templates.js b/src/templates.js
index 1e26fbe9..d5f398b2 100644
--- a/src/templates.js
+++ b/src/templates.js
@@ -146,7 +146,7 @@ For recurring checks, \`pullboard sentinels\` lists this board's watches, their
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.
**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.
diff --git a/test/companion.test.js b/test/companion.test.js
index 6f4d5b31..cf39361e 100644
--- a/test/companion.test.js
+++ b/test/companion.test.js
@@ -3,6 +3,9 @@ import assert from 'node:assert/strict';
import { join } from 'node:path';
import { after, test } from 'node:test';
import * as store from '../src/board.js';
+import { prepareEngineMove, applyRelayMove } from '../src/engine.js';
+import { COMPANION_ENGINE } from '../src/companion-engine.js';
+import { createdItems } from '../src/relay-created-items.js';
import { createE2eHelpers } from './e2e-helpers.js';
const helpers = createE2eHelpers();
@@ -58,3 +61,36 @@ test('a companion request becomes one claimable child item and a second request
assert.equal(box.run(box.web, 'companion', String(parent), 'web', 'Wrong lane', '--key', 'wrong').code, 1);
assert.equal(box.run(box.web, 'companion', String(parent), 'api', 'Missing key').code, 1);
});
+
+
+test('companion delivery preserves authenticated actors, engine fences and durable child identities [B2,B12,H16]', () => {
+ const box = helpers.project('true');
+ const parent = run(box, box.repo, 'add', 'web', 'Transport parent', '--specs', 'G1', '--json').item.item_id;
+ const board = store.openBoard(join(box.repo, '.git', 'pullboard', 'board.sqlite'));
+ try {
+ const agentId = store.agentAt(board, box.web).agent_id;
+ const request = { agentId, parentId: parent, lane: 'api', key: 'wire-part', title: 'API transport work', criterion: 'one child', specIds: ['G2'] };
+ const move = prepareEngineMove(board, 'requestCompanion', [request], { id: 'companion-wire-one', actor: agentId });
+ const options = { sequence: 1, at: new Date().toISOString(), kind: 'move', sender: { kind: 'agent', agent: agentId, userId: 'fixture-person' } };
+ assert.throws(() => applyRelayMove(board, { ...move, engine: COMPANION_ENGINE - 1 }, options), /RELAY_MOVE/u);
+ assert.equal(store.listItems(board, { all: true }).length, 1, 'an old engine creates no child');
+ const forged = applyRelayMove(board, { ...move, id: 'companion-forged-actor' }, { ...options, sender: { ...options.sender, agent: 'another-seat' } });
+ assert.equal(forged.error.code, 'RELAY_SENDER_MISMATCH');
+ const receipt = applyRelayMove(board, move, { ...options, sequence: 2 });
+ assert.equal(receipt.result.created, true);
+ assert.equal(store.getItem(board, receipt.result.item).item_created_by, agentId);
+ assert.deepEqual(applyRelayMove(board, move, { ...options, sequence: 2 }), receipt, 'duplicate delivery retains its original receipt');
+ assert.deepEqual(createdItems('requestCompanion', receipt.result), [{ resultPath: ['item'], item: receipt.result.item }], 'queued transport binds the child result rather than the parent argument');
+ const retry = store.requestCompanion(board, { ...request, title: 'Do not overwrite the original child' });
+ assert.equal(retry.created, false);
+ assert.equal(retry.item, receipt.result.item);
+ assert.equal(store.getItem(board, retry.item).item_title, request.title);
+ assert.throws(() => store.requestCompanion(board, { ...request, key: 'forged-check', check: 'true' }), /COORDINATOR_CHECK/u);
+ assert.throws(() => store.requestCompanion(board, { ...request, key: 'unjoined', agentId: 'unjoined-seat' }), /NOT_JOINED/u);
+ const extra = store.requestCompanion(board, { ...request, key: 'different-work' });
+ assert.notEqual(extra.item, retry.item, 'explicitly distinct requests remain separate children');
+ store.withdraw(board, parent, { agentId: 'coordinator', reason: 'No further companion requests' });
+ assert.equal(store.requestCompanion(board, request).item, retry.item, 'closed parents retain existing request identities');
+ assert.throws(() => store.requestCompanion(board, { ...request, key: 'new-after-close' }), /PARENT_CLOSED/u);
+ } finally { store.closeBoard(board); }
+});