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(line): bind capacity claims and preserve old replay [M1,H16]

Corey Olson963bc04c2f28
diff --git a/docs/formats.md b/docs/formats.md
index 7ad1b496..38dde806 100644
--- a/docs/formats.md
+++ b/docs/formats.md
@@ -629,4 +629,4 @@ its number at landing; no event-log or envelope format changes.
With `reviewsFirst` on, ordinary `next` offers an eligible review before a build when outstanding submissions exceed `wipPerReviewer` times the active-reviewer count (or ratio 3 while that numeric control is off). No permanent builder/reviewer seat type or role flag is required. Active reviewers are distinct registered seats with a reservation or verdict inside the flow window; its default is the last hour, and an empty window counts as one reviewer. The window uses the same validated boundaries as `stats --window`.
-With numeric `wipPerReviewer` on, a new claim that would exceed that limit is refused as `LINE_WIP_LIMIT`, naming the oldest eligible pending review when there is one. Live claimed items and outstanding submissions count; expired claims do not. Renewals remain possible. The native claim carries the configured verifier and family policies so its suggested review never relaxes those guards. With `takeoverMinutes` on, a sent-back item's idle interval can end its original builder's first-refusal window early; a live claim is never stolen, and normal claim appends preserve the old history. Disabled controls retain the previous behavior. New claims under these controls carry the line-capacity engine floor; older recorded claims keep their historical meaning during replay.
+With numeric `wipPerReviewer` on, a new claim that would exceed that limit is refused as `LINE_WIP_LIMIT`, naming the oldest eligible pending review when there is one. Live claimed items and outstanding submissions count; expired claims do not. Renewals remain possible. The native claim carries the configured verifier and family policies so its suggested review never relaxes those guards. With `takeoverMinutes` on, a sent-back item's idle interval can end its original builder's first-refusal window early; a live claim is never stolen, and normal claim appends preserve the old history. Disabled controls retain the previous behavior. New claims under these controls carry a true `lineCapacity` argument and the line-capacity engine floor; marker-absent older recorded claims keep their historical meaning during replay.
diff --git a/docs/lifecycle.md b/docs/lifecycle.md
index ddc15fdd..5c013735 100644
--- a/docs/lifecycle.md
+++ b/docs/lifecycle.md
@@ -56,7 +56,7 @@ Each move checks its guards in this order and refuses with the first one that do
| Move | From | To | Who | Guards, in order; result refusals |
| --- | --- | --- | --- | --- |
| intake | open | submitted | agent, coordinator | joined (NOT_JOINED or SESSION_LEDGER), itemExists (NO_ITEM), inState (NOT_CLAIMABLE), outsideSubmission (OUTSIDE_SOURCE) |
-| claim | open, claimed | claimed | agent, coordinator | joined (NOT_JOINED or SESSION_LEDGER), itemExists (NO_ITEM), inState (NOT_CLAIMABLE), checkProvesSomething (CRITERION_PROVES_NOTHING), barReady (BAR_NOT_READY), itemNotHeld (ITEM_HELD), inLane (WRONG_LANE or OUTSIDE_NATIVE_BUILD), routeAllows (ROUTE), dependenciesVerified (BLOCKED), notHeldByAnother (HELD), builderFirstRefusal (REOPEN_HELD_FOR_BUILDER), correctionRefrozen (PENDING_REFREEZE), laneOpen (LANE_HELD), lineCapacity (LINE_WIP_LIMIT), oneLiveClaim (ONE_CLAIM), 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) |
+| claim | open, claimed | claimed | agent, coordinator | joined (NOT_JOINED or SESSION_LEDGER), itemExists (NO_ITEM), inState (NOT_CLAIMABLE), checkProvesSomething (CRITERION_PROVES_NOTHING), barReady (BAR_NOT_READY), itemNotHeld (ITEM_HELD), inLane (WRONG_LANE or OUTSIDE_NATIVE_BUILD), routeAllows (ROUTE), dependenciesVerified (BLOCKED), notHeldByAnother (HELD), builderFirstRefusal (REOPEN_HELD_FOR_BUILDER), correctionRefrozen (PENDING_REFREEZE), laneOpen (LANE_HELD), lineCapacity (LINE_WIP_LIMIT or LINE_SETTING_RANGE), oneLiveClaim (ONE_CLAIM), 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) |
| release | open, claimed | open | agent, coordinator | joined (NOT_JOINED or SESSION_LEDGER), itemExists (NO_ITEM), inState (NOT_YOURS), releaseOwnsWork (NOT_YOURS), reviewReleaseExplained (NOTE_REQUIRED) |
| lapse | claimed | open | clock, when its lease runs out | none |
| submit | claimed | submitted | agent, coordinator | joined (NOT_JOINED or SESSION_LEDGER), itemExists (NO_ITEM), inState (NOT_YOURS), isHolder (NOT_YOURS or OUTSIDE_NATIVE_BUILD), correctionRefrozen (PENDING_REFREEZE), checkProvesSomething (CRITERION_PROVES_NOTHING), barReady (BAR_NOT_READY), criterionUnchanged (CRITERIA_CHANGED), treeClean (DIRTY), nothingUntracked (UNTRACKED), hasCommit (NO_COMMIT or HOST_NAME), withinLane (OUTSIDE_LANE or NO_POLICY or BAD_CONFIG or GIT_GRAFTS), trunkMergeClean (MERGE_CONFLICT or MERGE_CHECK_FAILED or NO_POLICY or NO_TRUNK), trunkInCandidate (MAIN_NOT_COMPOSED), noUnverifiedStack (STACKED_ON_UNVERIFIED), infraExplained (INFRA_NOTE_REQUIRED), doctrineHolds (RATCHET_ROSE or RATCHET_UNCOUNTED), gateConfigured (NO_GATE), queuedItemLease (ITEM_LEASE_LOST or A5_GRAMMAR_VERSION or SPEC_BEHIND_MAIN or NOT_A_REPO or NO_CONFIG), gateGreen (GATE_RED or LAND_TIMEOUT_CUSTODY or LAND_GATE_OUTPUT or SLOT_DB_LOCKED or TIMING_SLOT_REQUIRED or RUNNER_BROWSER_SLOT_REQUIRED or PIPEFAIL_UNAVAILABLE), treeStillDuringGate (MOVED_DURING_GATE), submissionProofValid (SUBMISSION_PROOF), childrenDone (CHILDREN_OPEN), headIsNew (HEAD_NOT_NEW) |
@@ -114,6 +114,7 @@ Each move checks its guards in this order and refuses with the first one that do
| ITEM_HELD | the coordinator has not put this item on hold, unless the caller is renewing its own live claim | the coordinator lifts it with pullboard hold <id> --off |
| PENDING_REFREEZE | no coordinator correction to a claimed criterion or check is waiting to be frozen | pullboard refreeze <id> |
| LINE_WIP_LIMIT | a new claim stays within recorded WIP per active reviewer, only for new claims while wipPerReviewer is on | review the oldest eligible waiting submission: pullboard next --verify |
+| LINE_SETTING_RANGE | a new claim stays within recorded WIP per active reviewer, only for new claims while wipPerReviewer is on | restore the malformed recorded line setting before claiming |
| ONE_CLAIM | the caller holds no other live top-level claim, reworks of its own rejected items aside | submit or release the other item first; child items are free |
| UNKNOWN_SPEC | every row the item cites exists and is in force, only where the criterion freezes: claiming an item with no frozen criterion, and refreeze | fix the spec, or the coordinator withdraws the item |
| A5_GRAMMAR_VERSION | every row the item cites exists and is in force, only where the criterion freezes: claiming an item with no frozen criterion, and refreeze | upgrade Pullboard or use a file written for grammar 1 |
diff --git a/src/board.js b/src/board.js
index a293caff..c26ea838 100644
--- a/src/board.js
+++ b/src/board.js
@@ -1275,9 +1275,14 @@ export function reviewOffer(board, { agentId, lane, policy = 'any', familyPolicy
/** Find the oldest eligible submission with exactly the reservation guards, including cooldown and ownership. */
function oldestCapacityReview(board, pending, who) {
- const checks = Object.values(reviewerChecks(board, who));
- return pending.find(item => !reviewHolder(board, item) && !reviewReleaseCooldown(board, item.item_id, who.agentId)
- && checks.every(check => !check(item))) ?? null;
+ try {
+ const checks = Object.values(reviewerChecks(board, who));
+ return pending.find(item => !reviewHolder(board, item) && !reviewReleaseCooldown(board, item.item_id, who.agentId)
+ && checks.every(check => !check(item))) ?? null;
+ } catch (error) {
+ if (error instanceof Refused) return null; // Eligibility failures are not a different claim refusal.
+ throw error;
+ }
}
/**
diff --git a/src/engine.js b/src/engine.js
index ada98e94..2c4f255a 100644
--- a/src/engine.js
+++ b/src/engine.js
@@ -105,7 +105,7 @@ const OPERATION_ENGINE = Object.freeze({ setLineSetting: LINE_SETTINGS_ENGINE, d
function minimumOperationEngine(operation, args, board, at) {
const outside = ['intakeOutside', 'approveOutside'].includes(operation) || operation === 'verify' && args[1]?.sandbox !== undefined
|| board && ['claim', 'submit', 'verify', 'merged'].includes(operation) && Boolean(outsideSource(board, args[0]));
- const capacity = board && operation === 'claim' && ['wipPerReviewer', 'takeoverMinutes'].some(key => typeof lineSettings(board)[key] === 'number');
+ const capacity = operation === 'claim' && args[1]?.lineCapacity === true;
return Math.max(outside ? OUTSIDE_INTAKE_ENGINE : 1, capacity ? LINE_CAPACITY_ENGINE : 1, minimumExistingOperationEngine(operation, args, board, at));
}
@@ -197,6 +197,9 @@ export function startRelayEpoch(board) {
export function prepareEngineMove(board, operation, args, { id = randomUUID(), actor } = {}) {
if (!ENGINE_OPERATIONS.includes(operation) || !Array.isArray(args)) throw new Refused('RELAY_MOVE', 'use a supported board-engine operation with its argument array');
if (operation === 'submit' && ENGINE_VERSION >= SUBMISSION_PROOF_ENGINE) submissionProof(args[1]?.submissionProof);
+ if (operation === 'claim' && ['wipPerReviewer', 'takeoverMinutes'].some(key => typeof lineSettings(board)[key] === 'number')) {
+ args = [args[0], { ...args[1], lineCapacity: true }, ...args.slice(2)];
+ }
const minimumEngine = minimumOperationEngine(operation, args, board);
if (ENGINE_VERSION < minimumEngine) throw new Refused('ENGINE_VERSION', `${operation} requires engine version ${minimumEngine}; this pullboard uses engine ${ENGINE_VERSION}; upgrade before sending it`);
// A gate run is sealed only as its gate's own receipt; a run made up by hand is refused before it reaches any replica.
diff --git a/src/machine.js b/src/machine.js
index 5d107539..d214f905 100644
--- a/src/machine.js
+++ b/src/machine.js
@@ -113,7 +113,7 @@ export const GUARDS = [
{ id: 'laneOpen', refuse: 'LANE_HELD', rule: 'nobody holds its lane', next: 'pullboard next --wait 9 (minutes)', source: 'board', when: 'unless the caller is renewing its own live claim' },
{ id: 'itemNotHeld', refuse: 'ITEM_HELD', rule: 'the coordinator has not put this item on hold', next: 'the coordinator lifts it with pullboard hold <id> --off', source: 'board', when: 'unless the caller is renewing its own live claim' },
{ id: 'correctionRefrozen', refuse: 'PENDING_REFREEZE', rule: 'no coordinator correction to a claimed criterion or check is waiting to be frozen', next: 'pullboard refreeze <id>', source: 'board' },
- { id: 'lineCapacity', refuse: 'LINE_WIP_LIMIT', rule: 'a new claim stays within recorded WIP per active reviewer', next: 'review the oldest eligible waiting submission: pullboard next --verify', source: 'board', when: 'only for new claims while wipPerReviewer is on' },
+ { id: 'lineCapacity', refuse: 'LINE_WIP_LIMIT', alsoRefuses: [{ code: 'LINE_SETTING_RANGE', next: 'restore the malformed recorded line setting before claiming' }], rule: 'a new claim stays within recorded WIP per active reviewer', next: 'review the oldest eligible waiting submission: pullboard next --verify', source: 'board', when: 'only for new claims while wipPerReviewer is on' },
{ id: 'oneLiveClaim', refuse: 'ONE_CLAIM', rule: 'the caller holds no other live top-level claim, reworks of its own rejected items aside', next: 'submit or release the other item first; child items are free', source: 'board' },
{ id: 'rowsInForce', refuse: 'UNKNOWN_SPEC', alsoRefuses: [{ code: 'A5_GRAMMAR_VERSION', next: 'upgrade Pullboard or use a file written for grammar 1' }, { code: 'NO_POLICY', next: 'restore the committed coordinator policy' }, { code: 'BAD_CONFIG', next: 'repair and commit the coordinator configuration' }, { code: 'SPEC_BEHIND_MAIN', next: 'merge main from this worktree, then retry the claim' }, { code: 'AGENT_APPROVAL_REQUIRED', next: 'ask the coordinator to arrange the person’s confirmation or decline, or change the explicit refuse setting' }, { code: 'BAR_NOT_READY', next: 'another parent session signs coverage for the current accepted test inventory and runner' }], rule: 'every row the item cites exists and is in force', next: 'fix the spec, or the coordinator withdraws the item', source: 'board', when: 'only where the criterion freezes: claiming an item with no frozen criterion, and refreeze' },
{ id: 'criterionUnchanged', refuse: 'CRITERIA_CHANGED', rule: 'the criterion and the rows it cites read as they did at claim', next: 'the coordinator runs pullboard refreeze <id>', source: 'cli' },
diff --git a/test/line-capacity.test.js b/test/line-capacity.test.js
index 66342f35..70c40c66 100644
--- a/test/line-capacity.test.js
+++ b/test/line-capacity.test.js
@@ -86,7 +86,11 @@ test('old recorded claims ignore new capacity while new claims retain the featur
const snapshot = exportBoard(f.board);
const options = { agentId: f.reviewer, lane: 'core', leaseMs: HOUR, freeze: FREEZE };
const move = prepareEngineMove(f.board, 'claim', [id, options]);
- const old = applyEngineMove(f.board, { ...move, engine: LINE_CAPACITY_ENGINE - 1 }, { sequence: 1, at: f.board.clock.now().toISOString() });
+ assert.equal(move.args[1].lineCapacity, true, 'newly prepared claims bind their new meaning explicitly');
+ const legacy = structuredClone(move);
+ delete legacy.args[1].lineCapacity;
+ assert.throws(() => applyEngineMove(f.board, { ...move, engine: LINE_CAPACITY_ENGINE - 1 }, { sequence: 1, at: f.board.clock.now().toISOString() }), { code: 'RELAY_MOVE' }, 'the true marker cannot be forged onto an older engine');
+ const old = applyEngineMove(f.board, { ...legacy, engine: LINE_CAPACITY_ENGINE - 1 }, { sequence: 1, at: f.board.clock.now().toISOString() });
assert.equal(old.error, undefined, JSON.stringify(old.error));
const replica = store.openBoard(join(f.root, 'replica.sqlite'), f.board.clock);
t.after(() => store.closeBoard(replica));
diff --git a/test/machine.test.js b/test/machine.test.js
index 11de8077..6b3d4fff 100644
--- a/test/machine.test.js
+++ b/test/machine.test.js
@@ -117,6 +117,8 @@ const CALLBACKS = { 'board.js': { freeze: 'cli.js#freezer' } };
* reads committed doctrine rules leniently: a doctrine it cannot parse carries no check [D1].
*/
const CAUGHT = {
+ // Review eligibility returns Refused values as data, and this helper also catches thrown eligibility refusals.
+ 'board.js#oldestCapacityReview': ['board.js#reviewerChecks'],
'commands/submit.js#submitHere': ['native-flakes.js#observeFailure', 'cli.js#freezer', 'main-red.js#compareMainFailures', 'main-red.js#matchingReworks', 'doctrine-checks.js#checkRulesAt'],
// observeNativeFailure catches its optional pair/recording errors; they cannot become lifecycle refusals.
'commands/verify.js#verifyHere': ['cli.js#freezer', 'native-flakes.js#observeFailure'],
@@ -984,11 +986,14 @@ test('claim refuses in the declared order, one failure peeled at a time, on a re
store.editItem(board, target, { agentId: 'coordinator', criterion: 'A new bar, so the next claim freezes it.' });
fired.push(claimAs(target, strong, 'web'));
store.releaseLane(board, 'web', { agentId: 'coordinator' });
+ store.setLineSetting(board, { agentId: 'coordinator', key: 'wipPerReviewer', value: 1.5, reason: 'peel the actual capacity guard', window: { activeReviewers: 1 } });
+ fired.push(claimAs(target, strong, 'web'));
+ store.setLineSetting(board, { agentId: 'coordinator', key: 'wipPerReviewer', value: false, reason: 'peel the remaining existing guards', window: { activeReviewers: 1 } });
fired.push(claimAs(target, strong, 'web'));
store.release(board, spare, strong);
fired.push(claimAs(target, strong, 'web'), claimAs(target, strong, 'web', freeze));
assert.deepEqual(fired, [...declaredBoardOrder('claim'), 'ok']);
- assert.deepEqual(fired, ['NO_ITEM', 'NOT_CLAIMABLE', 'BAR_NOT_READY', 'ITEM_HELD', 'WRONG_LANE', 'ROUTE', 'BLOCKED', 'HELD', 'REOPEN_HELD_FOR_BUILDER', 'PENDING_REFREEZE', 'LANE_HELD', 'ONE_CLAIM', 'UNKNOWN_SPEC', 'ok']);
+ assert.deepEqual(fired, ['NO_ITEM', 'NOT_CLAIMABLE', 'BAR_NOT_READY', 'ITEM_HELD', 'WRONG_LANE', 'ROUTE', 'BLOCKED', 'HELD', 'REOPEN_HELD_FOR_BUILDER', 'PENDING_REFREEZE', 'LANE_HELD', 'LINE_WIP_LIMIT', 'ONE_CLAIM', 'UNKNOWN_SPEC', 'ok']);
} finally {
lab.done();
}