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.

fix(grant): bind activation and replay to recorded history [E21,H16]

Corey Olson5bad4280e82d
diff --git a/docs/lifecycle.md b/docs/lifecycle.md
index 1868bdac..83b4c3b4 100644
--- a/docs/lifecycle.md
+++ b/docs/lifecycle.md
@@ -63,7 +63,7 @@ Each move checks its guards in this order and refuses with the first one that do
| reserve | submitted | submitted | agent, coordinator | coordinatorSaysAs (MAIN_IS_COORDINATOR), joined (NOT_JOINED or AGENT_REPLACED or SESSION_LEDGER), roadmapReadable (MILESTONES_CORRUPT or LINE_SETTING_RANGE), itemExists (NO_ITEM), inState (NOT_SUBMITTED), reviewCooldownElapsed (REVIEW_COOLDOWN), notBuilder (SELF_VERIFY or VERIFIER_STANDING or SELF_SESSION_VERIFY), routeAllows (ROUTE), policyAllows (COORDINATOR_VERIFIES), familyAllows (O2_FAMILY_MATCH), reviewFree (REVIEW_HELD) |
| accept | submitted, verified | verified | agent, coordinator | coordinatorSaysAs (MAIN_IS_COORDINATOR), joined (NOT_JOINED or AGENT_REPLACED or SESSION_LEDGER), itemExists (NO_ITEM), inState (NOT_SUBMITTED), atSubmittedCommit (NOT_AT_COMMIT or OUTSIDE_LANE or NO_POLICY or BAD_CONFIG or GIT_GRAFTS), notMerged (ALREADY_MERGED), verdictReviewRecorded (BAD_VERDICT_REVIEW), reviewTreeCurrent (STALE_VERDICT or DIRTY or UNTRACKED or VERDICT_TRUNK_MOVED), notBuilder (SELF_VERIFY or VERIFIER_STANDING or SELF_SESSION_VERIFY), routeAllows (ROUTE), policyAllows (COORDINATOR_VERIFIES), familyAllows (O2_FAMILY_MATCH), reviewFree (REVIEW_HELD), criterionUnchanged (CRITERIA_CHANGED), reasonIsMet (BAD_REASON), trunkMergeClean (MERGE_CONFLICT or MERGE_CHECK_FAILED or NO_POLICY or NO_TRUNK), noUnverifiedStack (STACKED_ON_UNVERIFIED), queuedItemLease (ITEM_LEASE_LOST or A5_GRAMMAR_VERSION or SPEC_BEHIND_MAIN or NOT_A_REPO or NO_CONFIG), itemCheckGreen (CHECK_RED or RUNNER_GUI_SESSION_REQUIRED or SANDBOX_PROVIDER_REQUIRED or SANDBOX_IMAGE_REQUIRED or SANDBOX_RUNTIME or SANDBOX_EXPORT or SANDBOX_EXECUTION or SANDBOX_CLEANUP_REQUIRED or SANDBOX_CHECK_REQUIRED or CHECK_NO_PROOF or OUTSIDE_SANDBOX_REQUIRED or SLOT_DB_LOCKED or TIMING_SLOT_REQUIRED or CHECK_UNVERIFIED or GUARD_CANNOT_FAIL or GUARD_NOT_FOUND), proofNoted (PROOF_REQUIRED), result (AGENT_GRANT_EXPIRED), result (AGENT_GRANT_ITEM), result (AGENT_GRANT_LANE), result (VERDICT_ENVIRONMENT), result (LAND_HEADER), result (ENGINE_VERSION) |
| reject | submitted, verified | open | agent, coordinator | coordinatorSaysAs (MAIN_IS_COORDINATOR), joined (NOT_JOINED or AGENT_REPLACED or SESSION_LEDGER), itemExists (NO_ITEM), inState (NOT_SUBMITTED), atSubmittedCommit (NOT_AT_COMMIT or OUTSIDE_LANE or NO_POLICY or BAD_CONFIG or GIT_GRAFTS), notMerged (ALREADY_MERGED), verdictReviewRecorded (BAD_VERDICT_REVIEW), reviewTreeCurrent (STALE_VERDICT or DIRTY or UNTRACKED or VERDICT_TRUNK_MOVED), notBuilder (SELF_VERIFY or VERIFIER_STANDING or SELF_SESSION_VERIFY), routeAllows (ROUTE), policyAllows (COORDINATOR_VERIFIES), familyAllows (O2_FAMILY_MATCH), reviewFree (REVIEW_HELD), criterionUnchanged (CRITERIA_CHANGED), reasonCoded (BAD_REASON), noteGiven (NOTE_REQUIRED), causeWellFormed (BAD_CAUSE), result (AGENT_GRANT_EXPIRED), result (AGENT_GRANT_ITEM), result (AGENT_GRANT_LANE), result (VERDICT_ENVIRONMENT), result (LAND_HEADER), result (ENGINE_VERSION), result (NOT_YOURS), result (CLOSED) |
-| reopen | submitted, verified | open | agent, coordinator | joined (NOT_JOINED or AGENT_REPLACED or SESSION_LEDGER), itemExists (NO_ITEM), inState (NOT_SUBMITTED), reopenAuthority (COORDINATOR_ONLY or VERDICT_WITHDRAW_FORBIDDEN or VERDICT_WITHDRAW_STATE), noteGiven (NOTE_REQUIRED), causeWellFormed (BAD_CAUSE), notMerged (ALREADY_MERGED), landingFailureRecorded (LANDING_FAILURE_REQUIRED), trunkConflicts (NOT_CONFLICTING or CONFLICT_FILES or NO_TRUNK or MERGE_CHECK_FAILED), conflictAccepted (NOT_ACCEPTED or BAD_CONFLICT or ENGINE_VERSION), result (BAD_VERDICT_WITHDRAW), result (ENGINE_VERSION), result (BAD_CONFIG) |
+| reopen | submitted, verified | open | agent, coordinator | joined (NOT_JOINED or AGENT_REPLACED or SESSION_LEDGER), itemExists (NO_ITEM), inState (NOT_SUBMITTED), reopenAuthority (COORDINATOR_ONLY or GIT_GRAFTS or GIT_REPLACE_REFS or VERDICT_WITHDRAW_FORBIDDEN or VERDICT_WITHDRAW_STATE), noteGiven (NOTE_REQUIRED), causeWellFormed (BAD_CAUSE), notMerged (ALREADY_MERGED), landingFailureRecorded (LANDING_FAILURE_REQUIRED), trunkConflicts (NOT_CONFLICTING or CONFLICT_FILES or NO_TRUNK or MERGE_CHECK_FAILED), conflictAccepted (NOT_ACCEPTED or BAD_CONFLICT or ENGINE_VERSION), result (BAD_VERDICT_WITHDRAW), result (ENGINE_VERSION), result (BAD_CONFIG) |
| escalate | open, claimed | open | agent, coordinator | joined (NOT_JOINED or AGENT_REPLACED or SESSION_LEDGER), noteGiven (NOTE_REQUIRED), itemExists (NO_ITEM), holderOrCoordinator (NOT_YOURS), inState (CLOSED) |
| refreeze | open, claimed, submitted | open | coordinator, when there is no live claim awaiting a coordinator correction | joined (NOT_JOINED or AGENT_REPLACED or SESSION_LEDGER), coordinatorOnly (COORDINATOR_ONLY), itemExists (NO_ITEM), inState (CLOSED), barReady (BAR_NOT_READY), rowsInForce (UNKNOWN_SPEC or A5_GRAMMAR_VERSION or NO_POLICY or BAD_CONFIG or SPEC_BEHIND_MAIN or AGENT_APPROVAL_REQUIRED or BAR_NOT_READY) |
| refreeze | claimed | claimed | agent, coordinator, when a live claim has a pending coordinator correction | joined (NOT_JOINED or AGENT_REPLACED or SESSION_LEDGER), itemExists (NO_ITEM), holderOrCoordinator (NOT_YOURS), inState (CLOSED), barReady (BAR_NOT_READY), rowsInForce (UNKNOWN_SPEC or A5_GRAMMAR_VERSION or NO_POLICY or BAD_CONFIG or SPEC_BEHIND_MAIN or AGENT_APPROVAL_REQUIRED or BAR_NOT_READY) |
@@ -98,6 +98,8 @@ Each move checks its guards in this order and refuses with the first one that do
| SESSION_LEDGER | the caller is the main checkout, or an unreplaced worktree seat that joined a lane; an agent session's claims, submits and verdicts can be checked against its local ledger | make the agent-session ledger named in the message readable and writable by this user, then run the command again |
| NO_ITEM | the item exists | pullboard list --all |
| COORDINATOR_ONLY | the coordinator reopens, the native board computes an automatic submitted-head conflict, or the exact accepting reviewer withdraws its verdict; older recorded submitted-conflict moves keep their joined-seat authority | ask the coordinator or the reviewer who recorded the accept |
+| GIT_GRAFTS | the coordinator reopens, the native board computes an automatic submitted-head conflict, or the exact accepting reviewer withdraws its verdict; older recorded submitted-conflict moves keep their joined-seat authority | ask the coordinator to remove the replica graft file, then resume the same move |
+| GIT_REPLACE_REFS | the coordinator reopens, the native board computes an automatic submitted-head conflict, or the exact accepting reviewer withdraws its verdict; older recorded submitted-conflict moves keep their joined-seat authority | ask the coordinator to remove the replica replacement refs, then resume the same move |
| VERDICT_WITHDRAW_FORBIDDEN | the coordinator reopens, the native board computes an automatic submitted-head conflict, or the exact accepting reviewer withdraws its verdict; older recorded submitted-conflict moves keep their joined-seat authority | ask the accepting reviewer or coordinator to withdraw the verdict |
| VERDICT_WITHDRAW_STATE | the coordinator reopens, the native board computes an automatic submitted-head conflict, or the exact accepting reviewer withdraws its verdict; older recorded submitted-conflict moves keep their joined-seat authority | refresh the item; only a current acceptance before landing can be withdrawn |
| COORDINATOR_ONLY | the caller is the coordinator | run it from the main checkout |
diff --git a/src/agent-grant.js b/src/agent-grant.js
index 9387273b..414299af 100644
--- a/src/agent-grant.js
+++ b/src/agent-grant.js
@@ -19,8 +19,20 @@ function existingItem(board, id) {
return board.db.prepare('SELECT * FROM item WHERE item_id=?').get(id) ?? null;
}
+/** A board activates only through a move recorded in its ordered prefix, never by opening a newer client. */
+function recordedGrantActivation(board) {
+ const cursor = board.db.prepare('SELECT meta_value FROM board_meta WHERE meta_key=?').get('relay_applied_sequence');
+ const sequence = cursor ? Number(cursor.meta_value) : 0;
+ if (!Number.isSafeInteger(sequence) || sequence < 1) return false;
+ return Boolean(board.db.prepare(`SELECT 1 FROM board_meta WHERE meta_key GLOB 'relay_receipt_*'
+ AND json_extract(meta_value, '$.sequence') <= ?
+ AND json_extract(json_extract(meta_value, '$.move'), '$.engine') >= ? LIMIT 1`)
+ .get(sequence, AGENT_GRANT_ENGINE));
+}
+
/** A version marker is not a grant: it only prevents an older engine bypassing a new seat or claim. */
export function agentGrantMinimum(board, move) {
+ if (recordedGrantActivation(board)) return AGENT_GRANT_ENGINE;
// Communication and review administration neither widen nor replace a claim. An old claim could erase its version marker.
if (move.operation !== 'claim' && (ADMINISTRATIVE.has(move.operation) || !target(move))) return 1;
const actor = MOVE_REGISTRY[move.operation]?.actor(move);
diff --git a/src/computed-conflict-receipt.js b/src/computed-conflict-receipt.js
index 6f550fee..999c6727 100644
--- a/src/computed-conflict-receipt.js
+++ b/src/computed-conflict-receipt.js
@@ -3,6 +3,7 @@ import { createHash } from 'node:crypto';
import { existsSync } from 'node:fs';
import { repoInfo } from './git.js';
import { recordedTrunkMerge } from './trunk-merge.js';
+import { refuseRecordedHistoryOverrides } from './trunk-merge.js';
import { dirname } from 'node:path';
import { join } from 'node:path';
import { Refused } from './refused.js';
@@ -40,10 +41,12 @@ function objectStore(board) {
export function requireComputedConflictObjects(board, receipt) {
const fields = computedConflictFields(receipt);
if (!fields) return null;
+ const gitDirectory = objectStore(board);
+ refuseRecordedHistoryOverrides(gitDirectory);
let cache = VERIFIED_OBJECTS.get(board);
if (!cache) { cache = new Map(); VERIFIED_OBJECTS.set(board, cache); }
const key = `${fields.head}:${fields.trunk}`;
- if (!cache.has(key)) cache.set(key, recordedTrunkMerge(objectStore(board), fields.head, fields.trunk));
+ if (!cache.has(key)) cache.set(key, recordedTrunkMerge(gitDirectory, fields.head, fields.trunk));
return cache.get(key);
}
diff --git a/src/machine.js b/src/machine.js
index c37f554f..b0ca09e8 100644
--- a/src/machine.js
+++ b/src/machine.js
@@ -99,7 +99,7 @@ export const GUARDS = [
{ id: IN_STATE, refuse: '', rule: "the move can start from the item's current state", next: 'pullboard show <id>', source: 'board' },
{ id: 'joined', refuse: 'NOT_JOINED', alsoRefuses: [{ code: 'AGENT_REPLACED', next: 'read the takeover and only shout on its exact hand-off item; continue work from the incoming agent worktree' }, { code: 'SESSION_LEDGER', next: 'make the agent-session ledger named in the message readable and writable by this user, then run the command again' }], rule: 'the caller is the main checkout, or an unreplaced worktree seat that joined a lane; an agent session\'s claims, submits and verdicts can be checked against its local ledger', next: 'pullboard join <lane> --model "<model name>" (see: pullboard lanes)', source: 'cli' },
{ id: 'itemExists', refuse: 'NO_ITEM', rule: 'the item exists', next: 'pullboard list --all', source: 'board' },
- { id: 'reopenAuthority', refuse: 'COORDINATOR_ONLY', rule: 'the coordinator reopens, the native board computes an automatic submitted-head conflict, or the exact accepting reviewer withdraws its verdict; older recorded submitted-conflict moves keep their joined-seat authority', next: 'ask the coordinator or the reviewer who recorded the accept', source: 'board', alsoRefuses: [{ code: 'VERDICT_WITHDRAW_FORBIDDEN', next: 'ask the accepting reviewer or coordinator to withdraw the verdict' }, { code: 'VERDICT_WITHDRAW_STATE', next: 'refresh the item; only a current acceptance before landing can be withdrawn' }] },
+ { id: 'reopenAuthority', refuse: 'COORDINATOR_ONLY', rule: 'the coordinator reopens, the native board computes an automatic submitted-head conflict, or the exact accepting reviewer withdraws its verdict; older recorded submitted-conflict moves keep their joined-seat authority', next: 'ask the coordinator or the reviewer who recorded the accept', source: 'board', alsoRefuses: [{ code: 'GIT_GRAFTS', next: 'ask the coordinator to remove the replica graft file, then resume the same move' }, { code: 'GIT_REPLACE_REFS', next: 'ask the coordinator to remove the replica replacement refs, then resume the same move' }, { code: 'VERDICT_WITHDRAW_FORBIDDEN', next: 'ask the accepting reviewer or coordinator to withdraw the verdict' }, { code: 'VERDICT_WITHDRAW_STATE', next: 'refresh the item; only a current acceptance before landing can be withdrawn' }] },
{ id: 'coordinatorOnly', refuse: 'COORDINATOR_ONLY', rule: 'the caller is the coordinator', next: 'run it from the main checkout', source: 'board' },
{ id: 'roadmapReadable', refuse: 'MILESTONES_CORRUPT', alsoRefuses: [{ code: 'LINE_SETTING_RANGE', rule: 'the recorded board line-order setting has a valid registry value', next: 'restore the recorded board line setting from its ordered event history, then retry next --verify' }], rule: 'the recorded queue policy and roadmap are readable when selecting the next review', next: 'restore board metadata from a known-good board export', source: 'board', when: 'only next --verify selection; a review reserved by id does not consult the roadmap' },
{ id: 'coordinatorSaysAs', refuse: 'MAIN_IS_COORDINATOR', rule: 'in the main checkout, the caller says it is the coordinator', next: 'verify from your own worktree; the coordinator adds --as coordinator', source: 'cli' },
diff --git a/src/next-step-defaults.js b/src/next-step-defaults.js
index c9903d6c..c95909d9 100644
--- a/src/next-step-defaults.js
+++ b/src/next-step-defaults.js
@@ -3,6 +3,7 @@ export const DEFAULT_NEXT_STEPS = Object.freeze({
"AGENT_GRANT_EXPIRED": "claim the intended item, or shout the coordinator if its claim is unavailable",
"AGENT_GRANT_ITEM": "finish or release the claim, then claim the intended item; use shout for coordination",
"AGENT_GRANT_LANE": "join a seat in the intended lane or ask its owner to make the item change",
+ "GIT_REPLACE_REFS": "ask the coordinator to remove this replica's refs/replace entries, then resume the same ordered move",
"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/trunk-merge.js b/src/trunk-merge.js
index 93d099cf..5ff2ff47 100644
--- a/src/trunk-merge.js
+++ b/src/trunk-merge.js
@@ -1,3 +1,5 @@
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
/** In-memory Git conflict computation without loading check execution or resource admission [V4,C7]. */
import { spawnSync } from 'node:child_process';
import { cleanGitEnvironment } from './git.js';
@@ -47,3 +49,16 @@ export function recordedTrunkMerge(gitDirectory, head, trunk) {
if (!files.length) throw new Refused('MERGE_CHECK_FAILED', 'Git did not provide conflict paths for the recorded commits; fetch their complete objects before resuming');
return files;
}
+
+
+/** Refuse local history overrides before trusting either a fresh or cached immutable conflict result. */
+export function refuseRecordedHistoryOverrides(gitDirectory) {
+ if (existsSync(join(gitDirectory, 'info', 'grafts'))) {
+ throw new Refused('GIT_GRAFTS', 'recorded conflict replay cannot trust a repository with info/grafts; ask the coordinator to remove its graft file, then resume the same move');
+ }
+ const refs = spawnSync('git', ['--no-replace-objects', `--git-dir=${gitDirectory}`, 'for-each-ref', '--format=%(refname)', 'refs/replace/'],
+ { env: cleanGitEnvironment(), encoding: 'utf8', maxBuffer: 1024 * 1024 });
+ if (refs.status !== 0) throw new Refused('MERGE_CHECK_FAILED', 'Git could not inspect this replica history; restore its object store, then resume the same move');
+ if (refs.stdout.trim()) throw new Refused('GIT_REPLACE_REFS',
+ 'recorded conflict replay cannot trust a repository with replacement refs; ask the coordinator to remove the refs/replace entries, then resume the same move');
+}