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(core): record and enforce agent handoffs [B3,N19,H16]

Corey Olsonab824e2e9cb1
diff --git a/docs/api.md b/docs/api.md
index 8ae17676..923e3d83 100644
--- a/docs/api.md
+++ b/docs/api.md
@@ -622,3 +622,9 @@ A row approved after the board’s compatibility baseline is reported as `agent-
Board state and status expose `specApprovalBaseline: {pending: boolean, invalid: boolean}`. Read-only status/API calls do not establish a pending baseline. A present but unreadable baseline is invalid, never pending: current approved rows require their own confirmation evidence, flag-mode work remains available, and no command automatically resets the marker. Restore a known-good board export to recover it. Board state adds `spec[].agentApproval` (or `null`), item `agentApproved` and `approvalQualification`, and `agent-approved` Needs-you calls carrying the available author and commit. Invalid receipt evidence remains unconfirmed and appears in `specApprovalEvidenceErrors`; it is never treated as an approval. The state cache and live watcher include receipt and signer-trust file bytes. Status JSON exposes the same calls and diagnostics.
Verification output, current item detail and the ledger qualify affected accepted work as “verified against agent-approved <ids>”. A later confirmation clears the current qualification; it does not rewrite earlier acceptance receipts.
+
+## Agent hand-offs
+
+Run `pullboard handoff` from the outgoing agent worktree. It creates or finds one hand-off item and prints its claims, recent moves, asks and answers, worktree state and existing facts. Record unfinished ownership, principles and taste, open threads, outside files and context only that chat knows with `pullboard fact <id> note "..."`. Pullboard carries board records, not a chat transcript.
+
+The incoming agent joins a new worktree and runs `pullboard handoff --take <id>`. It reads the same hand-off and outgoing work card, and records a timed takeover fact. The first incoming seat wins; its repeat is idempotent. Claims are reported rather than silently reassigned. After takeover, the outgoing seat cannot make board moves except `pullboard shout --item <id> "..."` on that exact hand-off. Both seats read and answer that item channel. The command ends with that same sign-off command. The main checkout retains its separate coordinator takeover flow.
diff --git a/src/board-event-log.js b/src/board-event-log.js
index e656536c..be24eeb8 100644
--- a/src/board-event-log.js
+++ b/src/board-event-log.js
@@ -1,3 +1,4 @@
+import { requireHandoffActive } from './handoff-state.js';
/** Append native events and their rebuildable proof projection in the same transaction [R2]. */
import { ENGINE_VERSION } from './machine.js';
import { agentModel } from './seats.js';
@@ -16,6 +17,7 @@ import { ensureProofCounters } from './proof-counters.js';
* @param {Date} [at] An enabled move may share one instant with its deadline.
*/
export function logEvent(board, by, kind, itemId, detail = {}, at) {
+ requireHandoffActive(board, by, kind, [{ item: kind === 'shout' ? detail.item : undefined }]);
board.db.exec('SAVEPOINT proof_event_append');
try {
ensureProofCounters(board);
diff --git a/src/board.js b/src/board.js
index 892fd6c7..28a338a4 100644
--- a/src/board.js
+++ b/src/board.js
@@ -1,3 +1,4 @@
+export { openHandoff, takeHandoff } from './handoff.js';
import {
recordBarRevision,
barReadyProblem,
@@ -209,7 +210,6 @@ export { proposeSentinel, decideSentinel, beginSentinelRun, finishSentinelRun }
export { flakeLedger, recordFlakeObservation } from './flakes.js';
export { flakeQuarantines, gateRuns, recordGateRun } from './quarantine.js';
export { recordPublishFinding } from './pr-findings.js';
-
/** The seat readers live in seats.js; the board re-exports them so `store.*` callers keep one import. */
export { agentAt, agentById, agentCreator, coordinatorHolder, listAgents, nextSeatId, seatEnrolled, seatLineage, takeCoordinator, withVerifierStanding } from './seats.js';
@@ -240,7 +240,6 @@ export { systemClock } from './board-read-open.js';
export { openBoardForRead } from './board-read-open.js';
export { openBoardReadOnly } from './board-read-open.js';
-
/**
* Open, or create, the board at `file`. Tests pass `:memory:`.
*
diff --git a/src/cli-main.js b/src/cli-main.js
index c3dfe5d5..52d2949d 100644
--- a/src/cli-main.js
+++ b/src/cli-main.js
@@ -87,6 +87,7 @@ const OPTIONS = {
adopt: { type: 'boolean' },
waive: { type: 'string' },
until: { type: 'string' },
+ take: { type: 'string' },
agent: { type: 'string' },
'agent-light': { type: 'string' },
'agent-mid': { type: 'string' },
@@ -225,7 +226,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 = ['bar', 'init', 'join', 'worktree', 'hooks', 'hook', 'skills', 'add', 'edit', 'fact', 'escalate', 'run', 'sweep',
+ const writes = ['handoff', 'bar', 'init', 'join', 'worktree', 'hooks', 'hook', 'skills', 'add', '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 3f22b624..159f730e 100644
--- a/src/cli.js
+++ b/src/cli.js
@@ -1,3 +1,4 @@
+import { requireHandoffActive } from './handoff-state.js';
export { barActorForCommand } from './bar-actor.js';
import {
barReadinessRequired,
@@ -427,7 +428,6 @@ export async function launchBaseline(ctx, board, id, baseline) {
baseline: { command: baseline.command, main: baseline.main, result: 'unavailable', reason: 'background worker could not start; set --check again from the coordinator' } }]);
}
}
-
/** Parse an edit's dependency replacement, with the explicit word `none` meaning clear all. */
export function editAfter(text) {
if (text === undefined) return undefined;
@@ -438,7 +438,6 @@ export function editAfter(text) {
}
return parts.map((part) => idArg(part, 'an item id after --after'));
}
-
/**
* Text a command was given as --<name> "..." or as --<name>-file <file>, or undefined when neither.
* A file carries text past the shell exactly: backticks, dollar signs and quotes included.
@@ -458,7 +457,6 @@ export function textArg(io, values, name) {
if (!existsSync(file)) throw new Refused('NO_FILE', `no file ${path}`);
return readFileSync(file, 'utf8');
}
-
/**
* The brief a command was given, from --brief or --brief-file.
*
@@ -467,7 +465,6 @@ export function textArg(io, values, name) {
* @returns {string | undefined}
*/
export const briefArg = (io, values) => textArg(io, values, 'brief');
-
/**
* Verifying from the main checkout files the verdict as the coordinator's (V9). An agent whose
* shell started there would be taken for the coordinator, so the coordinator says so explicitly
@@ -492,7 +489,6 @@ export function checkMainVerifier(ctx, board, values) {
reviewerStartup(ctx.info.root, ctx.config, values.verifyId),
);
}
-
/**
* Select the person actor only through the main checkout's explicit person mode (B26).
*
@@ -591,11 +587,13 @@ export async function ordered(ctx, board, operation, args) {
() => store.recordSpecApprovalBaseline(board, ...values))
: store.recordSpecApprovalBaseline(board, ...values);
};
- ensureSpecApprovalCoordinator(ctx, board, initialBaseline);
const actor = ctx.info.isMain ? COORDINATOR : store.agentAt(board, ctx.info.root)?.agent_id;
+ requireHandoffActive(board, actor, operation, args);
+ ensureSpecApprovalCoordinator(ctx, board, initialBaseline);
+ const write = () => store.atomic(board, () => { requireHandoffActive(board, actor, operation, args); return store[operation](board, ...args); });
if (initialBaseline && actor) await recordBaseline(actor);
const result = await withItemSession(ctx.info, operation, args, () => relayLinked(ctx.info.root) || relayRecovered(ctx.info.root)
- ? relayOperation(ctx.info.root, operation, args, ctx.io, command, () => store[operation](board, ...args)) : store[operation](board, ...args));
+ ? relayOperation(ctx.info.root, operation, args, ctx.io, command, write) : write());
return result;
};
const digest = agentSessionDigest();
diff --git a/src/commands/handoff.js b/src/commands/handoff.js
new file mode 100644
index 00000000..5288b622
--- /dev/null
+++ b/src/commands/handoff.js
@@ -0,0 +1,66 @@
+/** Record a replacement on the board without pretending to transfer a chat's private context [B3,N19]. */
+import * as store from '../board.js';
+import { context, idArg, ordered, whoAmI, withBoard } from '../cli.js';
+import { tryGit } from '../git.js';
+import { itemHandoff } from '../handoff-state.js';
+import { Refused } from '../refused.js';
+
+const STILL_TO_WRITE = ['what you own and what is unfinished', 'principles and taste behind decisions',
+ 'open threads, questions and next steps', 'files outside this repository and where they are',
+ 'anything only this chat knows; Pullboard cannot transfer private chat context'];
+
+/** Build the outgoing seat's current board card without executing its session or its work. */
+function card(board, outgoing) {
+ const agent = store.agentById(board, outgoing);
+ const items = store.listItems(board, { all: true });
+ const claims = items.filter(item => item.item_owner === outgoing && item.item_status === 'claimed');
+ const moves = board.db.prepare('SELECT * FROM event WHERE event_by=? ORDER BY event_id DESC LIMIT 20').all(outgoing).reverse();
+ const shouts = store.allShouts(board);
+ const asks = shouts.filter(row => row.shout_decision && (row.shout_from === outgoing || row.shout_to === outgoing || row.shout_to === agent.agent_lane))
+ .map(ask => ({ ask, answers: shouts.filter(row => row.shout_answers === ask.shout_id) }));
+ const branch = tryGit(agent.agent_path, ['rev-parse', '--abbrev-ref', 'HEAD']);
+ const state = tryGit(agent.agent_path, ['status', '--porcelain']);
+ return { agent: outgoing, lane: agent.agent_lane, claims, moves, asks,
+ worktree: { path: agent.agent_path, branch: branch.status === 0 ? branch.stdout : null,
+ changes: state.status === 0 ? state.stdout : null, unavailable: branch.status !== 0 || state.status !== 0 } };
+}
+
+/** Print existing facts and the remaining checklist, ending with a post-takeover-safe sign-off. */
+function print(io, handoff, resume, facts) {
+ const signoff = `pullboard shout --item ${handoff.item} "Hand-off complete; ask any remaining questions here."`;
+ io.result?.({ handoff, resume, facts, stillToWrite: STILL_TO_WRITE, signoff });
+ io.say(`Hand-off #${handoff.item}: ${handoff.outgoing}${handoff.incoming ? ` → ${handoff.incoming} at ${handoff.takenAt}` : ' is preparing a replacement'}`);
+ io.say(`Worktree: ${resume.worktree.path}; branch ${resume.worktree.branch ?? 'unavailable'}`);
+ io.say(resume.worktree.unavailable ? 'Worktree state could not be read; record its last known state.' : `Uncommitted paths:\n${resume.worktree.changes || '(none)'}`);
+ io.say(`Claims: ${resume.claims.map(item => `#${item.item_id} ${item.item_title}`).join('; ') || '(none)'}`);
+ io.say('Recent moves:');
+ for (const move of resume.moves) io.say(` ${move.event_at} ${move.event_kind}${move.item_id ? ` #${move.item_id}` : ''}`);
+ io.say('Asks and answers:');
+ for (const { ask, answers } of resume.asks) {
+ io.say(` #${ask.shout_id}: ${ask.shout_text}`);
+ for (const answer of answers) io.say(` ${answer.shout_from}: ${answer.shout_text}`);
+ if (!answers.length) io.say(' (open)');
+ }
+ io.say('Recorded hand-off facts:');
+ for (const fact of facts) io.say(` ${fact.by} ${fact.kind}: ${fact.text}`);
+ io.say('Facts still to write before you leave:');
+ for (const subject of STILL_TO_WRITE) io.say(` pullboard fact ${handoff.item} note "${subject}"`);
+ io.say('After takeover, only shouts on this item remain available to the outgoing agent. Sign off with:');
+ io.say(signoff);
+}
+
+/** Create/find a hand-off, or atomically record an incoming agent's timed takeover. */
+export async function run(io, { first, second, rest, values }) {
+ if (first || second || rest.length) throw new Refused('USAGE', 'use pullboard handoff, or pullboard handoff --take <id> from the incoming agent worktree');
+ const ctx = context(io);
+ return withBoard(ctx, async board => {
+ const me = whoAmI(ctx, board);
+ if (ctx.info.isMain) throw new Refused('HANDOFF_WORKTREE', 'run pullboard handoff from an agent worktree; the main checkout has its separate coordinator takeover flow');
+ const handoff = values.take === undefined
+ ? await ordered(ctx, board, 'openHandoff', [{ agentId: me.id }])
+ : await ordered(ctx, board, 'takeHandoff', [{ agentId: me.id, item: idArg(values.take) }]);
+ const current = itemHandoff(board, handoff.item);
+ print(io, current, card(board, current.outgoing), store.itemThread(board, handoff.item).filter(row => row.type === 'fact'));
+ return 0;
+ });
+}
diff --git a/src/engine.js b/src/engine.js
index 73181d83..039d014f 100644
--- a/src/engine.js
+++ b/src/engine.js
@@ -1,3 +1,5 @@
+import { HANDOFF_ENGINE } from './handoff-engine.js';
+import { requireHandoffActive } from './handoff-state.js';
import { BAR_READY_ENGINE } from './bar-ready-engine.js';
import { barReadySetting } from './bar-readiness.js';
import { ITEM_SHOUT_ENGINE } from './item-shout-engine.js';
@@ -79,7 +81,7 @@ const ITEM_ID_FIRST_ARGUMENT = new Set(['signBar', 'acceptCheck', 'editItem', 'e
/** Only these public board operations may be requested by an encrypted move. */
export const ENGINE_OPERATIONS = Object.freeze([
- 'setBarReady', 'signBar', 'register', 'ensureCoordinator', 'addItem', 'editItem', 'completeCheckBaseline', 'escalate', 'recordAttempt',
+ 'openHandoff', 'takeHandoff', 'setBarReady', 'signBar', 'register', 'ensureCoordinator', 'addItem', 'editItem', 'completeCheckBaseline', 'escalate', 'recordAttempt',
'claim', 'release', 'submit', 'reserveReview', 'reserveNextReview', 'verify', 'merged',
'withdraw', 'refreeze', 'reopen', 'shout', 'passDecision', 'answerDecision', 'holdLane', 'releaseLane', 'holdItem', 'releaseItemHold',
'addMilestone', 'editMilestoneItems', 'orderMilestoneItems', 'moveMilestone', 'editMilestone', 'removeMilestone', 'shipMilestone',
@@ -96,6 +98,7 @@ const OPERATION_ENGINE = Object.freeze({ draftSpecRow: ROW_DRAFT_ENGINE, orderMi
/** Dependency edits, causes, sealed reviews, submission proofs, trunk conflicts, health observations and milestone targets retain distinct recorded engine meanings. */
function minimumOperationEngine(operation, args, board, at) {
+ if (['openHandoff', 'takeHandoff'].includes(operation)) return HANDOFF_ENGINE;
if (['setBarReady', 'signBar'].includes(operation) || board && ['claim', 'submit', 'editItem', 'addItem', 'refreeze'].includes(operation) && barReadySetting(board).enabled) return BAR_READY_ENGINE;
if (operation === 'recordPublishFinding') return PR_BRIDGE_ENGINE;
if (operation === 'recordLandingTestDefect' || operation === 'verify' && args[1]?.environment !== undefined
@@ -387,6 +390,7 @@ export function applyEngineMove(board, move, { sequence, at, standing = null, en
if (problem) throw problem;
// One main checkout coordinates a linked board at a time; another is refused by name (#347).
requireCoordinatorHold(board, move, standing?.lineage, at);
+ requireHandoffActive(board, relayMoveActor(move), move.operation, move.args);
return store[move.operation](board, ...executableArgs(move, board));
});
const result = standing ? store.withVerifierStanding(board, standing, execute) : execute();
diff --git a/src/handoff-engine.js b/src/handoff-engine.js
new file mode 100644
index 00000000..5a5947b3
--- /dev/null
+++ b/src/handoff-engine.js
@@ -0,0 +1,3 @@
+/** Durable agent replacement and its sole post-takeover channel [B3,N19,H16]. */
+import { unassignedEngine } from './engine-next.js';
+export const HANDOFF_ENGINE = unassignedEngine();
diff --git a/src/handoff-state.js b/src/handoff-state.js
new file mode 100644
index 00000000..58e17c2a
--- /dev/null
+++ b/src/handoff-state.js
@@ -0,0 +1,26 @@
+/** Read replacement authority only from typed engine events, never from a person's prose [B3,H16]. */
+import { Refused } from './refused.js';
+
+/** Find this outgoing seat's one durable hand-off, retaining its first takeover. */
+export function agentHandoff(board, outgoing) {
+ const open = board.db.prepare("SELECT * FROM event WHERE event_kind='handoff-open' AND event_by=? ORDER BY event_id DESC LIMIT 1").get(outgoing);
+ return open ? itemHandoff(board, open.item_id) : null;
+}
+
+/** Read one hand-off and its timed takeover from the indexed event prefix. */
+export function itemHandoff(board, item) {
+ const open = board.db.prepare("SELECT * FROM event WHERE item_id=? AND event_kind='handoff-open' ORDER BY event_id LIMIT 1").get(item);
+ if (!open) return null;
+ const taken = board.db.prepare("SELECT * FROM event WHERE item_id=? AND event_kind='handoff-take' ORDER BY event_id LIMIT 1").get(item);
+ return { item, outgoing: open.event_by, openedAt: open.event_at,
+ incoming: taken?.event_by ?? null, takenAt: taken?.event_at ?? null };
+}
+
+/** Refuse a replaced seat before any move, except a message on its exact hand-off item. */
+export function requireHandoffActive(board, actor, operation, args) {
+ if (typeof actor !== 'string' || actor === 'person' || actor === 'coordinator') return;
+ const handoff = agentHandoff(board, actor);
+ if (!handoff?.takenAt) return;
+ if (operation === 'shout' && args?.[0]?.item === handoff.item) return;
+ throw new Refused('AGENT_REPLACED', `${actor} was taken over by ${handoff.incoming} at ${handoff.takenAt}; only pullboard shout --item ${handoff.item} "<answer for the incoming agent>" remains available`);
+}
diff --git a/src/handoff.js b/src/handoff.js
new file mode 100644
index 00000000..31b73731
--- /dev/null
+++ b/src/handoff.js
@@ -0,0 +1,55 @@
+/** Atomic replacement receipts on the ordinary board, independent of chat tools [B3,N19,H16]. */
+import { addItem, agentById, appendFact, atomic, logEvent } from './board.js';
+import { HANDOFF_ENGINE } from './handoff-engine.js';
+import { ENGINE_VERSION } from './machine.js';
+import { agentHandoff, itemHandoff, requireHandoffActive } from './handoff-state.js';
+import { Refused } from './refused.js';
+
+/** Only a registered worktree seat can give up or take an agent's role. */
+function worktreeAgent(board, id) {
+ const agent = agentById(board, id);
+ if (!agent || ['coordinator', 'person'].includes(id)) throw new Refused('HANDOFF_WORKTREE', 'run pullboard handoff from a joined agent worktree; the main checkout uses its separate coordinator takeover flow');
+ return agent;
+}
+
+/** Refuse a leaf operation that the sender's replay engine cannot interpret. */
+function requireHandoffEngine(board) {
+ if ((board.executionEngineVersion ?? ENGINE_VERSION) < HANDOFF_ENGINE) throw new Refused('ENGINE_VERSION', 'upgrade Pullboard on every linked device before using pullboard handoff');
+}
+
+/** Find or create exactly one channel per outgoing seat under the same write lock. */
+export function openHandoff(board, { agentId }) {
+ return atomic(board, () => {
+ requireHandoffEngine(board);
+ requireHandoffActive(board, agentId, 'openHandoff', []);
+ const agent = worktreeAgent(board, agentId);
+ const existing = agentHandoff(board, agentId);
+ if (existing && !['verified', 'withdrawn'].includes(board.db.prepare('SELECT item_status FROM item WHERE item_id=?').get(existing.item).item_status)) return existing;
+ const item = addItem(board, { by: agentId, lane: agent.agent_lane, route: 'strong', title: `Hand-off from ${agentId}`,
+ criterion: 'The incoming agent reads the recorded hand-off and takes over.',
+ brief: 'Record ownership, principles and taste, open threads, outside files and context only this agent knows. The incoming agent runs pullboard handoff --take <id>.' });
+ logEvent(board, agentId, 'handoff-open', item, { engine: HANDOFF_ENGINE });
+ return itemHandoff(board, item);
+ });
+}
+
+/** First incoming seat wins atomically; repeating its own acknowledged takeover adds no fact. */
+export function takeHandoff(board, { agentId, item }) {
+ return atomic(board, () => {
+ requireHandoffEngine(board);
+ requireHandoffActive(board, agentId, 'takeHandoff', []);
+ worktreeAgent(board, agentId);
+ const handoff = itemHandoff(board, item);
+ if (!handoff || ['verified', 'withdrawn'].includes(board.db.prepare('SELECT item_status FROM item WHERE item_id=?').get(item)?.item_status)) throw new Refused('NO_HANDOFF', `#${item} is not an agent hand-off; ask the outgoing agent to run pullboard handoff`);
+ if (handoff.outgoing === agentId) throw new Refused('HANDOFF_SELF', 'the incoming agent takes the hand-off from its own new worktree: pullboard handoff --take <id>');
+ if (handoff.incoming && handoff.incoming !== agentId) throw new Refused('HANDOFF_TAKEN', `#${item} was taken by ${handoff.incoming} at ${handoff.takenAt}; ask them on that item before replacing another role`);
+ if (handoff.incoming) return handoff;
+ const active = agentHandoff(board, handoff.outgoing);
+ if (!active || active.item !== item || active.takenAt) throw new Refused('NO_HANDOFF', 'this is not the outgoing agent’s active hand-off; read its current hand-off before taking it');
+ logEvent(board, agentId, 'handoff-take', item, { outgoing: handoff.outgoing, engine: HANDOFF_ENGINE });
+ const taken = itemHandoff(board, item);
+ appendFact(board, item, { agentId, kind: 'takeover', factId: `handoff-take-${item}`,
+ text: `${agentId} took over from ${handoff.outgoing} at ${taken.takenAt}. The outgoing agent now only answers shouts on this hand-off item.` });
+ return taken;
+ });
+}
diff --git a/src/help.js b/src/help.js
index fe6a3743..64b17367 100644
--- a/src/help.js
+++ b/src/help.js
@@ -56,6 +56,7 @@ Set up
pullboard relay tokens list this board's agent token ids, agents and expiry, never credentials
pullboard relay revoke <token-id> revoke one token from that list; other agents keep working
pullboard relay recover --skip <sequence> person-only recovery of one blocked next relay position
+ pullboard handoff [--take <id>] write or take an agent hand-off; keep questions on its item
pullboard resume where you are: your claim, branch, uncommitted work, what came back,
unread shouts, what to do next; run it to start any session
pullboard badge write board-derived Shields endpoint JSON to docs/badges/
@@ -300,6 +301,7 @@ const HELP_EXAMPLES = {
edit: 'pullboard edit 12 --brief "Add the upload page"', release: 'pullboard release 12',
land: 'pullboard land --max 4',
publish: 'pullboard publish',
+ handoff: 'pullboard handoff --take 12',
health: 'pullboard health',
reopen: 'pullboard reopen 12 --note "correct the frozen criterion"',
escalate: 'pullboard escalate 12 --note "needs a manual step"', next: 'pullboard next',
@@ -353,6 +355,7 @@ const HELP_ALIASES = {
};
const HELP_FLAG_EXPLANATIONS = {
+ '--take': 'take the existing hand-off from a newly joined agent worktree',
'--after': 'claiming waits until those items are verified',
'--blueprint': 'start from a bundled blueprint or a JSON file; repeat it for one product, one architecture and any practice blueprints',
'--brief': 'what a cold agent needs',
diff --git a/src/next-step-words.js b/src/next-step-words.js
index 5cef37dd..d287b9fa 100644
--- a/src/next-step-words.js
+++ b/src/next-step-words.js
@@ -453,6 +453,11 @@ export const NEXT_STEPS = Object.freeze({
RELAY_ORIGIN: 'set a GitHub origin: git remote add origin https://github.com/<owner>/<repo>.git, then pullboard relay on',
RELAY_PERSON_ONLY: 'do it as the person from the paired phone or the person\'s own session',
RELAY_PRESENTATION_PENDING: 'run pullboard status again',
+ AGENT_REPLACED: 'read the takeover named in the refusal; only shout on that exact hand-off item, then continue work from the incoming agent worktree',
+ HANDOFF_WORKTREE: 'join an agent worktree and run pullboard handoff there; the main checkout uses pullboard takeover',
+ HANDOFF_SELF: 'join a different worktree as the incoming agent, then run pullboard handoff --take <id>',
+ HANDOFF_TAKEN: 'read the recorded takeover and ask the incoming agent on the hand-off item before replacing another role',
+ NO_HANDOFF: 'ask the outgoing agent to run pullboard handoff, then read and take the active item it prints',
RELAY_RECOVERY_HEALTHY: 'replay it normally: pullboard relay',
RELAY_RECOVERY_PENDING: 'finish the saved recovery: pullboard relay recover --skip <sequence>',
RELAY_REGISTRATION: 'create the seat again from its creating seat\'s checkout, or from the main checkout: pullboard worktree <lane> --model "<model name>"',
diff --git a/src/relay-sender.js b/src/relay-sender.js
index 96537158..ccb392bc 100644
--- a/src/relay-sender.js
+++ b/src/relay-sender.js
@@ -10,7 +10,7 @@ export function relayMoveActor(move) {
if (move.operation === 'addItem') return args[0]?.by ?? null;
if (move.operation === 'shout') return args[0]?.from ?? null;
if (['proposeSentinel', 'decideSentinel', 'beginSentinelRun', 'finishSentinelRun'].includes(move.operation)) return args[0]?.agentId ?? null;
- if (['setBarReady', 'recordHealthFindings', 'recordFlakeObservation', 'recordGateRun', 'declareJob', 'recordJobRun', 'takeCoordinator', 'landingLeaseMove', 'recordPublishFinding'].includes(move.operation)) return args[0]?.agentId ?? null;
+ if (['openHandoff', 'takeHandoff', 'setBarReady', 'recordHealthFindings', 'recordFlakeObservation', 'recordGateRun', 'declareJob', 'recordJobRun', 'takeCoordinator', 'landingLeaseMove', 'recordPublishFinding'].includes(move.operation)) return args[0]?.agentId ?? null;
if (['holdLane', 'releaseLane'].includes(move.operation) && args[1]?.asPerson) return 'person';
if (move.operation === 'release') return args[1] ?? null;
if (['reserveNextReview', 'addMilestone', 'recordRowDecisions', 'applyRowDecisions', 'draftSpecRow', 'recordSpecApprovalBaseline', 'recordLandingBatch', 'recordLandingWaiver', 'recordLandingFlake', 'recordLandingTestDefect', 'finishLandingBatch'].includes(move.operation)) return args[0]?.agentId ?? null;
diff --git a/src/shout-audience.js b/src/shout-audience.js
index fbffa9ac..cb59a452 100644
--- a/src/shout-audience.js
+++ b/src/shout-audience.js
@@ -22,7 +22,8 @@ export function shoutItemId(to) {
export function itemShoutReader(db, id, agent) {
const item = db.prepare('SELECT item_owner, item_built_by, item_review_by, item_verified_by FROM item WHERE item_id = ?').get(id);
return Boolean(item && (agent === 'coordinator' || (item.item_owner ?? item.item_built_by) === agent
- || (item.item_review_by ?? item.item_verified_by) === agent));
+ || (item.item_review_by ?? item.item_verified_by) === agent
+ || db.prepare("SELECT 1 FROM event WHERE item_id=? AND event_kind IN ('handoff-open','handoff-take') AND event_by=? LIMIT 1").get(id, agent)));
}
/** Match one live shout against an explicit seat or lane audience, including its item roles. */
@@ -37,9 +38,10 @@ export function shoutMatchesAudience(db, to, audience) {
/** Positional bindings work on the supported minimum Node SQLite API as well as newer releases. */
export const UNREAD_SHOUT_SQL = `FROM shout WHERE shout_id > ? AND shout_from != ? AND
(shout_to IN ('all', ?, ?) OR (shout_to = '${COORDINATION_SHOUT}' AND ? IN ('coordinator', 'person')) OR EXISTS (SELECT 1 FROM item WHERE shout_to = 'item:' || item_id AND
- (? = 'coordinator' OR COALESCE(item_owner, item_built_by) = ? OR COALESCE(item_review_by, item_verified_by) = ?)))`;
+ (? = 'coordinator' OR COALESCE(item_owner, item_built_by) = ? OR COALESCE(item_review_by, item_verified_by) = ? OR EXISTS
+ (SELECT 1 FROM event WHERE event.item_id=item.item_id AND event_kind IN ('handoff-open','handoff-take') AND event_by=?))))`;
/** Bind every positional identity occurrence explicitly, including item-role checks. */
export function unreadShoutBindings(cursor, seat, lane) {
- return [cursor, seat, lane, seat, seat, seat, seat, seat];
+ return [cursor, seat, lane, seat, seat, seat, seat, seat, seat];
}