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: intake outside contributions only into a sandbox [V3,C7]

Corey Olsonedc246180beb
diff --git a/docs/lifecycle.md b/docs/lifecycle.md
index 9b2213fc..2114849d 100644
--- a/docs/lifecycle.md
+++ b/docs/lifecycle.md
@@ -13,6 +13,7 @@ Private commands drain their output through pipes, retaining a bounded 8 MiB cap
```mermaid
stateDiagram-v2
[*] --> open
+ open --> submitted: intake
open --> claimed: claim
claimed --> claimed: claim
open --> open: release
@@ -54,12 +55,13 @@ 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), itemNotHeld (ITEM_HELD), inLane (WRONG_LANE), routeAllows (ROUTE), dependenciesVerified (BLOCKED), notHeldByAnother (HELD), builderFirstRefusal (REOPEN_HELD_FOR_BUILDER), correctionRefrozen (PENDING_REFREEZE), laneOpen (LANE_HELD), oneLiveClaim (ONE_CLAIM), rowsInForce (UNKNOWN_SPEC or A5_GRAMMAR_VERSION or NO_POLICY or BAD_CONFIG or SPEC_BEHIND_MAIN or AGENT_APPROVAL_REQUIRED) |
| 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), correctionRefrozen (PENDING_REFREEZE), checkProvesSomething (CRITERION_PROVES_NOTHING), 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), 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 RUNNER_BROWSER_SLOT_REQUIRED or PIPEFAIL_UNAVAILABLE), treeStillDuringGate (MOVED_DURING_GATE), submissionProofValid (SUBMISSION_PROOF), childrenDone (CHILDREN_OPEN), headIsNew (HEAD_NOT_NEW) |
| reserve | submitted | submitted | agent, coordinator | coordinatorSaysAs (MAIN_IS_COORDINATOR), joined (NOT_JOINED or SESSION_LEDGER), roadmapReadable (MILESTONES_CORRUPT), 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 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 SLOT_DB_LOCKED or CHECK_UNVERIFIED or GUARD_CANNOT_FAIL or GUARD_NOT_FOUND), proofNoted (PROOF_REQUIRED), result (VERDICT_ENVIRONMENT), result (LAND_HEADER), result (ENGINE_VERSION) |
+| accept | submitted, verified | verified | agent, coordinator | coordinatorSaysAs (MAIN_IS_COORDINATOR), joined (NOT_JOINED 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 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 CHECK_UNVERIFIED or GUARD_CANNOT_FAIL or GUARD_NOT_FOUND), proofNoted (PROOF_REQUIRED), result (VERDICT_ENVIRONMENT), result (LAND_HEADER), result (ENGINE_VERSION) |
| reject | submitted, verified | open | agent, coordinator | coordinatorSaysAs (MAIN_IS_COORDINATOR), joined (NOT_JOINED 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 (VERDICT_ENVIRONMENT), result (LAND_HEADER), result (ENGINE_VERSION), result (NOT_YOURS), result (CLOSED) |
| reopen | submitted, verified | open | coordinator | joined (NOT_JOINED or SESSION_LEDGER), itemExists (NO_ITEM), inState (NOT_SUBMITTED), coordinatorOnly (COORDINATOR_ONLY), 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_CONFIG) |
| escalate | open, claimed | open | agent, coordinator | joined (NOT_JOINED or SESSION_LEDGER), noteGiven (NOTE_REQUIRED), itemExists (NO_ITEM), holderOrCoordinator (NOT_YOURS), inState (CLOSED) |
@@ -78,6 +80,7 @@ Each move checks its guards in this order and refuses with the first one that do
| Code | Raised when this does not hold | Next step |
| --- | --- | --- |
+| NOT_CLAIMABLE | intake: the item is in open | pullboard show <id> |
| NOT_CLAIMABLE | claim: the item is in open, claimed | pullboard show <id> |
| NOT_YOURS | release: the item is in open, claimed | pullboard show <id> |
| NOT_YOURS | submit: the item is in claimed | pullboard show <id> |
@@ -89,6 +92,7 @@ Each move checks its guards in this order and refuses with the first one that do
| CLOSED | refreeze: the item is in open, claimed, submitted | pullboard show <id> |
| CLOSED | refreeze: the item is in claimed | pullboard show <id> |
| CLOSED | withdraw: the item is in open, claimed, submitted | pullboard show <id> |
+| OUTSIDE_SOURCE | an outside author and exact fetched commit/tree are recorded with a trusted frozen criterion, without pretending a native builder gated it | fetch and intake the exact GitHub pull request again |
| NOT_JOINED | the caller is the main checkout, or a worktree that joined a lane; an agent session's claims, submits and verdicts can be checked against its local ledger | pullboard join <lane> --model "<model name>" (see: pullboard lanes) |
| SESSION_LEDGER | the caller is the main checkout, or a worktree 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 |
@@ -132,6 +136,15 @@ Each move checks its guards in this order and refuses with the first one that do
| RATCHET_ROSE | every touched doctrine check counts (exit 0 or 1), none rises above its committed count and no changed file gains a problem; watch-mode rules only count, only when accepted main has an approved doctrine rule with gate: check | fix the new problems, commit, submit again; only the person's signature raises count: |
| RATCHET_UNCOUNTED | every touched doctrine check counts (exit 0 or 1), none rises above its committed count and no changed file gains a problem; watch-mode rules only count, only when accepted main has an approved doctrine rule with gate: check | fix the check so it exits 0 or 1 within its timeout, then submit again |
| CHECK_RED | the frozen item check passes at the submitted commit, or its clean reviewed composition for a stale acceptance | reject the failing behavior; the builder fixes and resubmits |
+| SANDBOX_PROVIDER_REQUIRED | the frozen item check passes at the submitted commit, or its clean reviewed composition for a stale acceptance | configure the committed main Docker provider and pinned minimum/current images |
+| SANDBOX_IMAGE_REQUIRED | the frozen item check passes at the submitted commit, or its clean reviewed composition for a stale acceptance | preload the exact pinned official image into the configured daemon |
+| SANDBOX_RUNTIME | the frozen item check passes at the submitted commit, or its clean reviewed composition for a stale acceptance | correct the pinned image so its actual Node version matches its role |
+| SANDBOX_EXPORT | the frozen item check passes at the submitted commit, or its clean reviewed composition for a stale acceptance | restore access to the exact private Git export and recorded tree |
+| SANDBOX_EXECUTION | the frozen item check passes at the submitted commit, or its clean reviewed composition for a stale acceptance | restore the Docker runtime and inspect the owned container before another verification |
+| SANDBOX_CLEANUP_REQUIRED | the frozen item check passes at the submitted commit, or its clean reviewed composition for a stale acceptance | remove the exact named owned container after restoring Docker |
+| SANDBOX_CHECK_REQUIRED | the frozen item check passes at the submitted commit, or its clean reviewed composition for a stale acceptance | set a trusted full gate and frozen criterion before intake |
+| CHECK_NO_PROOF | the frozen item check passes at the submitted commit, or its clean reviewed composition for a stale acceptance | strengthen the criterion so it fails before the outside change |
+| OUTSIDE_SANDBOX_REQUIRED | the frozen item check passes at the submitted commit, or its clean reviewed composition for a stale acceptance | verify the outside item with --sandbox using the configured container provider |
| SLOT_DB_LOCKED | the frozen item check passes at the submitted commit, or its clean reviewed composition for a stale acceptance | the run never started, so it is not a red; rerun the same command once the named process releases the slot database |
| CHECK_UNVERIFIED | the frozen item check passes at the submitted commit, or its clean reviewed composition for a stale acceptance | restore the frozen install or check environment and retry |
| GUARD_CANNOT_FAIL | the frozen item check passes at the submitted commit, or its clean reviewed composition for a stale acceptance | reject: the check stays green with the named guard reverted |
diff --git a/src/board-query.js b/src/board-query.js
index e53f5b04..f21fc362 100644
--- a/src/board-query.js
+++ b/src/board-query.js
@@ -1,3 +1,4 @@
+import { outsideSource } from './outside-source.js';
import {
COORDINATION_SHOUT,
itemShoutReader,
@@ -105,7 +106,8 @@ export function itemById(board, id) {
export function getItem(board, id) {
const item = current(board, itemById(board, id));
const baseline = itemCheckBaseline(board, item);
- return baseline ? { ...item, item_check_baseline: baseline } : item;
+ const source = outsideSource(board, id);
+ return { ...item, ...(baseline ? { item_check_baseline: baseline } : {}), ...(source ? { outside: source } : {}) };
}
/**
diff --git a/src/board.js b/src/board.js
index a6ec9aee..c601a306 100644
--- a/src/board.js
+++ b/src/board.js
@@ -1,3 +1,13 @@
+import {
+ applyOutsideIntake,
+ approveOutside as applyOutsideApproval,
+} from './outside-store.js';
+import {
+ outsideSandboxProblem,
+ outsideSource,
+ requireOutsideOwner,
+ saveOutsideSource,
+} from './outside-source.js';
import {
closeBoard,
openBoardForRead,
@@ -1366,7 +1376,7 @@ function reserveWithin(board, id, { agentId, leaseMs, policy, familyPolicy = 'of
* @param {{ agentId: string, decision: string, reason?: string, note?: string, cause?: string, head: string, digest: string, policy: string, familyPolicy?: string, check?: 'none' | 'green', review?: {commit: string, head?: string, trunk: string, paths: string[]}, implies?: number[], impliesId?: string }} verdict - implies: items this verdict changes (B29)
* @returns {{ decision: string, reason: string, check?: 'none' | 'green' }}
*/
-export function verify(board, id, { agentId, decision, reason, note = '', cause, head, digest, policy, familyPolicy = 'off', check, review, implies, impliesId, reopenFirstRefusalMinutes, environment }) {
+export function verify(board, id, { agentId, decision, reason, note = '', cause, head, digest, policy, familyPolicy = 'off', check, review, implies, impliesId, reopenFirstRefusalMinutes, environment, sandbox }) {
const verb = { ACCEPT: 'accept', REJECT: 'reject' }[decision];
if (!verb) throw new Refused('BAD_DECISION', 'the decision is accept or reject');
const isAccept = verb === 'accept';
@@ -1398,7 +1408,7 @@ export function verify(board, id, { agentId, decision, reason, note = '', cause,
reasonIsMet: () => (reason && reason !== ACCEPT_REASON ? new Refused('BAD_REASON', `accept means ${ACCEPT_REASON}; a failed criterion is a reject`) : null),
trunkMergeClean: null,
noUnverifiedStack: null, queuedItemLease: null,
- itemCheckGreen: null,
+ itemCheckGreen: found => isAccept ? outsideSandboxProblem(board, found, sandbox) : null,
proofNoted: () =>
note.trim()
? null
@@ -1410,12 +1420,14 @@ export function verify(board, id, { agentId, decision, reason, note = '', cause,
before: (found) => recordVerdict(board, found, { agentId, decision, reason: code, note, digest, head }),
set: (found) => ({ item_verdict: decision, item_verified_by: isAccept ? agentId : null, item_owner: isAccept ? found.item_owner : null }),
});
+ if (isAccept && sandbox && outsideSource(board, id)) saveOutsideSource(board, id, { ...outsideSource(board, id), sandbox });
const returnedAt = !isAccept && engine >= REOPEN_FIRST_REFUSAL_ENGINE && reopenFirstRefusalMinutes > 0 && item.item_built_by ? board.clock.now() : undefined;
const reservation = !isAccept && engine >= REOPEN_FIRST_REFUSAL_ENGINE ? firstRefusalDetail(board, item, reopenFirstRefusalMinutes, returnedAt) : {};
const detail = { ...reservation, reason: code, commit: item.item_commit, ...(!isAccept && cause !== undefined && cause !== null ? { cause } : {}) };
if (isAccept && engine >= SPEC_APPROVAL_ENGINE) detail.note = note.trim();
if (isAccept && check !== undefined) detail.check = check;
if (environment !== undefined) detail.environment = environment;
+ if (sandbox !== undefined) detail.sandbox = sandbox;
if (newReview) detail.review = { commit: review.commit, ...(Object.hasOwn(review, 'head') ? { head: review.head } : {}), trunk: review.trunk, paths: [...review.paths] };
logEvent(board, agentId, verb, id, implies?.length ? { ...detail, implies } : detail, returnedAt);
const trigger = board.lastEvent;
@@ -1529,6 +1541,7 @@ export function merged(board, id, { agentId, commit, note = '' }) {
if (item.item_status !== 'verified') {
throw new Refused('NOT_VERIFIED', `item #${id} is ${item.item_status}; merge verified work only`);
}
+ requireOutsideOwner(board, item);
setItem(board, id, { item_merged_commit: commit });
logEvent(board, agentId, 'merged', id, { commit, ...(note.trim() ? { note: note.trim() } : {}) });
});
@@ -2451,3 +2464,9 @@ export function finishLandingBatch(board, { agentId, id, tip, landingFence }) {
return recordLandingBatch(board, { agentId, batch: { ...batch, state: 'landed' }, revision: batch.revision, landingFence });
});
}
+
+/** File or refresh an outside source through the ordinary ordered engine. */
+export function intakeOutside(board, options) { return applyOutsideIntake(board, options, { atomic, addItem, moveItem }); }
+
+/** Record the person's exact-commit owner approval. */
+export function approveOutside(board, id, options) { return applyOutsideApproval(board, id, options, atomic); }
diff --git a/src/cli-main.js b/src/cli-main.js
index d9a3edf9..45cc0139 100644
--- a/src/cli-main.js
+++ b/src/cli-main.js
@@ -32,6 +32,8 @@ export function traceServeStartup(phase) {
const OPTIONS = {
criterion: { type: 'string' },
+ sandbox: { type: 'boolean' },
+ lane: { type: 'string' },
specs: { type: 'string' },
parent: { type: 'string' },
reason: { type: 'string' },
diff --git a/src/commands/intake.js b/src/commands/intake.js
new file mode 100644
index 00000000..e53041c2
--- /dev/null
+++ b/src/commands/intake.js
@@ -0,0 +1,35 @@
+/** Intake records an outside source; fetching metadata never executes or checks out its code. */
+import * as store from '../board.js';
+import {
+ actOn,
+ freezer,
+ idArg,
+ ordered,
+} from '../cli.js';
+import { githubSource } from '../intake-github.js';
+import { requirePersonChannel } from '../person.js';
+import { Refused } from '../refused.js';
+
+/** Run intake or the explicit owner approval; there is deliberately no autonomous posting path. */
+export async function run(io, { first, second, values }) {
+ return actOn(io, async (ctx, board, me) => {
+ if (first === 'approve') {
+ requirePersonChannel(io.personChannel);
+ const id = idArg(second);
+ const approval = await ordered(ctx, board, 'approveOutside', [id, { agentId: 'person' }]);
+ io.result?.({ id, approval });
+ io.say(`owner approved outside commit for #${id}`);
+ return 0;
+ }
+ const source = githubSource(ctx.info.root, first);
+ const lane = values.lane ?? me.lane ?? Object.keys(ctx.config.lanes)[0];
+ if (!lane || !ctx.config.lanes[lane]) throw new Refused('NO_LANE', 'choose a configured lane with --lane before intake');
+ if (source.kind === 'pull-request' && (!values.criterion?.trim() || !values.check?.trim())) throw new Refused('CHECK_REQUIRED', 'intake a pull request with --criterion "behavior" --check "command" from the trusted coordinator checkout');
+ const item = { lane, title: source.title, criterion: values.criterion ?? '', check: values.check, specIds: [], route: 'strong' };
+ const frozen = source.kind === 'pull-request' ? freezer(ctx, { board, captureVerifyPolicy: true })({ item_title: item.title, item_criterion: item.criterion, item_check: item.check, item_spec_ids: '' }) : null;
+ const id = await ordered(ctx, board, 'intakeOutside', [{ agentId: me.id, source, item, frozen }]);
+ io.result?.({ item: store.getItem(board, id) });
+ io.say(`intaken ${source.kind} #${source.number} as #${id}; outside code is verified only with --sandbox`);
+ return 0;
+ });
+}
diff --git a/src/commands/verify.js b/src/commands/verify.js
index 199c1fe8..9cd59861 100644
--- a/src/commands/verify.js
+++ b/src/commands/verify.js
@@ -1,3 +1,4 @@
+import { outsideVerdict } from '../outside-verify.js';
/** The pullboard verify command, in its own module so an item adding another command never edits these lines. */
import * as store from '../board.js';
import {
@@ -123,6 +124,7 @@ export async function verifyHere(ctx, id, { second, values }) {
if (item.item_status !== 'submitted' && !stale) {
throw new Refused('NOT_SUBMITTED', `item #${id} is ${item.item_status}, not submitted`);
}
+ if (item.outside) return outsideVerdict(ctx, board, item, me, decision, values);
// Name an unknown implied item before the frozen check runs, not after it.
if (implies) checkImplies(board, implies);
const policy = itemPolicy(root, item);
diff --git a/src/engine.js b/src/engine.js
index 85a0c830..8df29895 100644
--- a/src/engine.js
+++ b/src/engine.js
@@ -1,3 +1,5 @@
+import { requireOutsideReceipt } from './outside-proof.js';
+import { OUTSIDE_INTAKE_ENGINE } from './outside-intake-engine.js';
import { ITEM_SHOUT_ENGINE } from './item-shout-engine.js';
/** Versioned, deterministic replay through the CLI's existing board engine [H3,H16]. */
import {
@@ -76,7 +78,7 @@ const ITEM_ID_FIRST_ARGUMENT = new Set(['acceptCheck', 'editItem', 'escalate', '
/** Only these public board operations may be requested by an encrypted move. */
export const ENGINE_OPERATIONS = Object.freeze([
- 'register', 'ensureCoordinator', 'addItem', 'editItem', 'completeCheckBaseline', 'escalate', 'recordAttempt',
+ 'intakeOutside', 'approveOutside', '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',
@@ -92,6 +94,12 @@ 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) {
+ const outside = ['intakeOutside', 'approveOutside'].includes(operation) || operation === 'verify' && args[1]?.sandbox !== undefined;
+ return Math.max(outside ? OUTSIDE_INTAKE_ENGINE : 1, minimumExistingOperationEngine(operation, args, board, at));
+}
+
+/** Preserve each pre-existing move's required feature level when composing outside metadata. */
+function minimumExistingOperationEngine(operation, args, board, at) {
if (operation === 'recordLandingTestDefect' || operation === 'verify' && args[1]?.environment !== undefined
|| operation === 'recordGateRun' && Object.hasOwn(args[0]?.receipt ?? {}, 'environment')
|| operation === 'recordLandingBatch' && carriesLandingEnvironment(args[0]?.batch)) return LANDING_ENVIRONMENT_ENGINE;
@@ -179,6 +187,7 @@ export function prepareEngineMove(board, operation, args, { id = randomUUID(), a
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.
if (operation === 'recordGateRun') requireBound(board, args[0]?.receipt);
+ if (operation === 'verify' && args[1]?.sandbox !== undefined) requireOutsideReceipt(board, args[1].sandbox);
const values = args.map((value) => value && typeof value === 'object' ? { ...value } : value);
if (operation === 'release') {
const problem = store.reviewReleaseNoteProblem(board, values[0], values[1], values[2]);
diff --git a/src/help.js b/src/help.js
index 5b099785..a4a40ee7 100644
--- a/src/help.js
+++ b/src/help.js
@@ -8,6 +8,12 @@ export const VERSION = packageData.version;
const ALL_HELP = `pullboard ${VERSION}: the local-first work board for teams of coding agents.
Nothing ships until a second agent verifies it.
+Outside contributions
+ pullboard intake <GitHub PR URL> --criterion "behavior" --check "command" [--lane <lane>] record exact outside author/commit, already submitted; never execute it here
+ pullboard intake <GitHub issue URL> record author, source state and maintainer reply; repeating intake refreshes metadata
+ pullboard verify <id> accept --sandbox --note "proof" configured Docker only, no network/credentials, Node22.13 and24; missing provider refuses
+ pullboard intake approve <id> owner/person approval for the exact sensitive outside commit; every PR result post still needs separate person OK
+
Set up
pullboard tour see it work: a reject and its rework, scripted, in thirty seconds
pullboard init [--model <name>] [--blueprint <name or file>]... [--no-permissions] [--yes] [--verbose] short setup summary; --verbose shows recipes; --yes commits only setup's own files with your Git identity
@@ -279,6 +285,7 @@ const HELP_EXAMPLES = {
'sentinel propose': 'pullboard sentinel propose "Run the checks" --check "npm test" --every hourly --owner web',
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"',
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/intake-github.js b/src/intake-github.js
new file mode 100644
index 00000000..1f4d2349
--- /dev/null
+++ b/src/intake-github.js
@@ -0,0 +1,45 @@
+/** Read GitHub public source metadata; never post, execute PR programs or use its executable settings. */
+import { spawnSync } from 'node:child_process';
+import { Refused } from './refused.js';
+import { git } from './git.js';
+
+/** Recognize one public GitHub issue or pull URL without allowing arbitrary API/fetch endpoints. */
+export function outsideURL(value) {
+ const match = /^https:\/\/github\.com\/([A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+)\/(pull|issues)\/([1-9][0-9]*)\/?$/u.exec(value ?? '');
+ if (!match || !Number.isSafeInteger(Number(match[3]))) throw new Refused('OUTSIDE_URL', 'use a GitHub pull request or issue URL: pullboard intake https://github.com/owner/repo/pull/123');
+ return { repository: match[1], kind: match[2] === 'pull' ? 'pull-request' : 'issue', number: Number(match[3]) };
+}
+
+/** A bounded read-only GitHub API request; authenticated gh never receives a posting verb. */
+function read(root, route) {
+ const result = spawnSync('gh', ['api', '--paginate', '--slurp', route], { cwd: root, encoding: 'utf8', timeout: 30_000, maxBuffer: 8 * 1024 * 1024 });
+ if (result.error || result.status !== 0) throw new Refused('OUTSIDE_FETCH', 'GitHub metadata could not be read; authenticate gh for this repository, then run intake again');
+ try { const value = JSON.parse(result.stdout); return Array.isArray(value) && value.every(Array.isArray) ? value.flat() : Array.isArray(value) && value.length === 1 && !Array.isArray(value[0]) ? value[0] : value; }
+ catch { throw new Refused('OUTSIDE_FETCH', 'GitHub returned unreadable metadata; restore gh API access before intake'); }
+}
+
+/** Fetch exact PR objects using Git only; preserve author and sign-off by never rewriting its commit. */
+export function githubSource(root, url) {
+ const source = outsideURL(url);
+ const prefix = `repos/${source.repository}`;
+ const data = read(root, `${prefix}/${source.kind === 'pull-request' ? 'pulls' : 'issues'}/${source.number}`);
+ const comments = read(root, `${prefix}/issues/${source.number}/comments?per_page=100`);
+ const replies = Array.isArray(comments) ? comments : [];
+ const common = { ...source, url, title: String(data.title ?? ''), author: data.user?.login, state: data.state,
+ maintainerReplied: replies.some(comment => ['OWNER', 'MEMBER', 'COLLABORATOR'].includes(comment.author_association)), updatedAt: data.updated_at };
+ if (source.kind === 'issue') return common;
+ if (!/^[a-f0-9]{40}$/u.test(data.head?.sha ?? '') || !/^[a-f0-9]{40}$/u.test(data.base?.sha ?? '')) throw new Refused('OUTSIDE_FETCH', 'GitHub did not return exact commit IDs; read the pull request again');
+ const files = read(root, `${prefix}/pulls/${source.number}/files?per_page=100`);
+ if (!Array.isArray(files) || files.length >= 100) throw new Refused('OUTSIDE_FETCH', 'this pull request needs a complete bounded changed-file list; split it below 100 files before intake');
+ // The server-owned pull ref, rather than the contributor-controlled clone URL, supplies objects.
+ git(root, ['fetch', '--no-tags', '--no-recurse-submodules', `https://github.com/${source.repository}.git`, `refs/pull/${source.number}/head`]);
+ const fetched = git(root, ['rev-parse', 'FETCH_HEAD^{commit}']).trim();
+ if (fetched !== data.head.sha) throw new Refused('OUTSIDE_HEAD_CHANGED', 'the pull request moved while intake fetched it; read and intake its new exact head');
+ const paths = files.map(file => file.filename);
+ if (paths.some(path => typeof path !== 'string' || path.includes('\n') || path.startsWith('/') || path.split('/').includes('..'))) throw new Refused('OUTSIDE_FETCH', 'GitHub returned an invalid changed path; restore its file metadata');
+ const changed = git(root, ['diff', '--name-only', '-z', `${data.base.sha}...${fetched}`]).split('\0').filter(Boolean);
+ if (changed.length !== paths.length || changed.some(path => !paths.includes(path))) throw new Refused('OUTSIDE_FETCH', 'the changed-file list differs from the fetched exact commit; refresh GitHub metadata');
+ // Fail closed for command-bearing files as well as explicit trust boundaries.
+ const sensitive = paths.some(path => /(^|\/)(relay|hooks?|\.github|person|sealing|signing)(\/|[.-]|$)/iu.test(path) || /(^|\/)(package\.json|Makefile|Dockerfile|.*\.(?:sh|bash|zsh|cmd|ps1))$/iu.test(path) || /(^|\/)(bin|scripts)\//u.test(path));
+ return { ...common, commit: fetched, tree: git(root, ['rev-parse', `${fetched}^{tree}`]).trim(), base: data.base.sha, files: paths, sensitive };
+}
diff --git a/src/land.js b/src/land.js
index b3d82308..2332c347 100644
--- a/src/land.js
+++ b/src/land.js
@@ -1,3 +1,4 @@
+import { requireOutsideOwner } from './outside-source.js';
/** Coordinator landing batches retain exact Git and gate receipts across interruptions [B3,R3]. */
import { assignEngineNumbers } from './engine-numbers.js';
import {
@@ -570,6 +571,7 @@ function withoutParallelBlocker(state, entries, removed) {
return entries.filter(entry => {
if (blocked.has(entry.id)) return false;
const item = store.getItem(state.board, entry.id);
+ requireOutsideOwner(state.board, item);
const dependency = (item.item_after ?? '').split(',').filter(Boolean).map(Number).find(id => blocked.has(id));
const stacked = tryGit(state.root, ['merge-base', '--is-ancestor', removed.reviewedCommit ?? removed.commit, entry.reviewedCommit ?? entry.commit]).status === 0;
if (dependency || stacked) {
@@ -940,6 +942,7 @@ function requirePushTarget(root, branch) {
function publicationInputs(state, batch) {
for (const entry of batch.items) {
const item = store.getItem(state.board, entry.id);
+ requireOutsideOwner(state.board, item);
if (item.item_status !== 'verified' || item.item_commit !== entry.commit
|| store.checkedLandingCommit(state.board, item) !== (entry.reviewedCommit ?? entry.commit)) {
throw new Refused('LAND_ITEM_MOVED', `item #${entry.id} changed its checked composition; rebuild the landing before publishing`);
@@ -1090,6 +1093,7 @@ async function landOnTrunk(state) {
}
for (const entry of state.batch.items) {
const item = store.getItem(state.board, entry.id);
+ requireOutsideOwner(state.board, item);
if (item.item_status !== 'verified' || item.item_commit !== entry.commit) throw new Refused('LAND_ITEM_MOVED', `item #${entry.id} changed after the batch merged; rebuild its landing`);
}
if (mainCheckout(state.root)?.commit !== state.batch.base) throw new Refused('LAND_TRUNK_MOVED', 'main moved during the landing; rebuild the batch from its new tip');
@@ -1214,6 +1218,7 @@ export async function runLandingBatch({ root, board, config, write, say, owner,
if (fence && trunk?.branch !== fence.branch) throw new Refused('LAND_LEASE_LOST', 'the trunk branch changed while landing waited; start a new land command for its current branch');
const unfinished = store.landingBatches(board).findLast((batch) => batch.state !== 'landed' && batch.state !== 'blocked');
if (fence && unfinished && unfinished.branch !== fence.branch) throw new Refused('LAND_LEASE_LOST', 'the interrupted batch belongs to another trunk branch; restore that branch and start a fresh land --adopt');
+ if (!dryRun && unfinished) for (const entry of unfinished.items ?? []) requireOutsideOwner(board, store.getItem(board, entry.id));
const recorded = store.landingBatches(board).findLast((batch) => batch.state === 'landed' && batch.base === trunk?.commit);
if (fence && recorded && recorded.branch !== fence.branch) throw new Refused('LAND_LEASE_LOST', 'the recorded Git repair belongs to another trunk branch; restore that branch before landing');
if (!dryRun && recorded && isClean(root) && !untracked(root).length) {
@@ -1234,6 +1239,7 @@ export async function runLandingBatch({ root, board, config, write, say, owner,
if (deferred) return deferred;
}
const selected = candidates(board, root, trunk.commit, maximum);
+ if (!dryRun) for (const item of selected.ready) requireOutsideOwner(board, item);
const stale = selected.blocked.find(item => item.code === 'STALE_VERDICT');
if (!selected.ready.length && stale) throw staleVerdictRefusal({ item_id: stale.id }, stale);
if (dryRun) {
diff --git a/src/machine.js b/src/machine.js
index 3bddb388..d259e64e 100644
--- a/src/machine.js
+++ b/src/machine.js
@@ -95,6 +95,7 @@ export const STATES = [
/** @type {Guard[]} */
export const GUARDS = [
+ { id: 'outsideSubmission', refuse: 'OUTSIDE_SOURCE', rule: 'an outside author and exact fetched commit/tree are recorded with a trusted frozen criterion, without pretending a native builder gated it', next: 'fetch and intake the exact GitHub pull request again', source: 'board' },
{ 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: '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 a worktree 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' },
@@ -124,7 +125,7 @@ export const GUARDS = [
{ id: 'noUnverifiedStack', refuse: 'STACKED_ON_UNVERIFIED', rule: "the candidate range contains no other item's unverified submitted commit", next: 'wait for that item to be accepted, or rebuild without its commits', source: 'cli' },
{ id: 'infraExplained', refuse: 'INFRA_NOTE_REQUIRED', rule: 'edits to tests or gate files that existed at claim carry an explanation', next: 'pullboard submit <id> --infra "<why>"', source: 'cli' },
{ id: 'doctrineHolds', refuse: 'RATCHET_ROSE', alsoRefuses: [{ code: 'RATCHET_UNCOUNTED', next: 'fix the check so it exits 0 or 1 within its timeout, then submit again' }], rule: "every touched doctrine check counts (exit 0 or 1), none rises above its committed count and no changed file gains a problem; watch-mode rules only count", next: "fix the new problems, commit, submit again; only the person's signature raises count:", source: 'cli', when: 'only when accepted main has an approved doctrine rule with gate: check' },
- { id: 'itemCheckGreen', refuse: 'CHECK_RED', alsoRefuses: [{ code: 'SLOT_DB_LOCKED', next: 'the run never started, so it is not a red; rerun the same command once the named process releases the slot database' }, { code: 'CHECK_UNVERIFIED', next: 'restore the frozen install or check environment and retry' }, { code: 'GUARD_CANNOT_FAIL', next: 'reject: the check stays green with the named guard reverted' }, { code: 'GUARD_NOT_FOUND', next: 'the named guard is not in the submitted commit; ask the coordinator to fix it' }], rule: 'the frozen item check passes at the submitted commit, or its clean reviewed composition for a stale acceptance', next: 'reject the failing behavior; the builder fixes and resubmits', source: 'cli' },
+ { id: 'itemCheckGreen', refuse: 'CHECK_RED', alsoRefuses: [{ code: 'SANDBOX_PROVIDER_REQUIRED', next: 'configure the committed main Docker provider and pinned minimum/current images' }, { code: 'SANDBOX_IMAGE_REQUIRED', next: 'preload the exact pinned official image into the configured daemon' }, { code: 'SANDBOX_RUNTIME', next: 'correct the pinned image so its actual Node version matches its role' }, { code: 'SANDBOX_EXPORT', next: 'restore access to the exact private Git export and recorded tree' }, { code: 'SANDBOX_EXECUTION', next: 'restore the Docker runtime and inspect the owned container before another verification' }, { code: 'SANDBOX_CLEANUP_REQUIRED', next: 'remove the exact named owned container after restoring Docker' }, { code: 'SANDBOX_CHECK_REQUIRED', next: 'set a trusted full gate and frozen criterion before intake' }, { code: 'CHECK_NO_PROOF', next: 'strengthen the criterion so it fails before the outside change' }, { code: 'OUTSIDE_SANDBOX_REQUIRED', next: 'verify the outside item with --sandbox using the configured container provider' }, { code: 'SLOT_DB_LOCKED', next: 'the run never started, so it is not a red; rerun the same command once the named process releases the slot database' }, { code: 'CHECK_UNVERIFIED', next: 'restore the frozen install or check environment and retry' }, { code: 'GUARD_CANNOT_FAIL', next: 'reject: the check stays green with the named guard reverted' }, { code: 'GUARD_NOT_FOUND', next: 'the named guard is not in the submitted commit; ask the coordinator to fix it' }], rule: 'the frozen item check passes at the submitted commit, or its clean reviewed composition for a stale acceptance', next: 'reject the failing behavior; the builder fixes and resubmits', source: 'cli' },
{ id: 'checkProvesSomething', refuse: 'CRITERION_PROVES_NOTHING', rule: "the item's check does not already pass on main, or the person accepted that exact check", next: 'set a check that fails before the work, or the person runs pullboard check accept <id>', source: 'cli', when: 'only when accepted main sets checks.provesNothing to "hold"' },
{ id: 'gateGreen', refuse: 'GATE_RED', alsoRefuses: [{ code: 'LAND_TIMEOUT_CUSTODY', next: 'inspect the saved timed gate cleanup state and stop only its proven owned processes before starting another landing' }, { code: 'LAND_GATE_OUTPUT', next: 'inspect the retained timed gate output directory and free disk space, then start another landing' }, { code: 'SLOT_DB_LOCKED', next: 'the run never started, so it is not a red; rerun the same command once the named process releases the slot database' }, { code: 'RUNNER_BROWSER_SLOT_REQUIRED', next: 'nothing to do: the run reruns on a local gate slot; if it repeats, set gate.browserByLaunch the same on this machine and that runner' }, { code: 'PIPEFAIL_UNAVAILABLE', next: 'rewrite the gate without a pipe' }], rule: 'the gate, which submit runs itself every time, is green at HEAD', next: 'fix what the digest names, commit, submit again', source: 'cli' },
@@ -155,6 +156,8 @@ export const GUARDS = [
/** @type {Move[]} */
export const MOVES = [
+ { verb: 'intake', from: ['open'], to: 'submitted', by: ['agent', 'coordinator'], refuse: 'NOT_CLAIMABLE',
+ guards: ['joined', 'itemExists', IN_STATE, 'outsideSubmission'], sets: ['item_built_by', 'item_commit', 'item_frozen_digest'], command: 'pullboard intake <PR> --criterion \"...\" --check \"...\"' },
{
verb: 'claim', from: ['open', 'claimed'], to: 'claimed', by: ['agent', 'coordinator'], refuse: 'NOT_CLAIMABLE',
guards: ['joined', 'itemExists', IN_STATE, 'checkProvesSomething', 'itemNotHeld', 'inLane', 'routeAllows', 'dependenciesVerified', 'notHeldByAnother', 'builderFirstRefusal', 'correctionRefrozen', 'laneOpen', 'oneLiveClaim', 'rowsInForce'],
diff --git a/src/outside-intake-engine.js b/src/outside-intake-engine.js
new file mode 100644
index 00000000..3d2aa474
--- /dev/null
+++ b/src/outside-intake-engine.js
@@ -0,0 +1,3 @@
+/** Outside-source intake and sandbox-only verification retain ordered semantics [C7,V3]. */
+import { unassignedEngine } from './engine-next.js';
+export const OUTSIDE_INTAKE_ENGINE = unassignedEngine();
diff --git a/src/outside-proof.js b/src/outside-proof.js
new file mode 100644
index 00000000..e02e0946
--- /dev/null
+++ b/src/outside-proof.js
@@ -0,0 +1,25 @@
+/** Native outside receipts bind the ordered accept to bytes written by its container executor. */
+import { createHash } from 'node:crypto';
+import { readFileSync } from 'node:fs';
+import {
+ dirname,
+ join,
+} from 'node:path';
+import { Refused } from './refused.js';
+
+/** Check the receipt beside this exact board, never a caller-selected host path. Replay retains its sealed facts. */
+export function requireOutsideReceipt(board, receipt) {
+ const refuse = () => new Refused('OUTSIDE_SANDBOX_REQUIRED', 'the sandbox accept needs its own locally stored executor receipt; run normal verify --sandbox');
+ if (!/^[a-f0-9-]{36}$/u.test(receipt?.id ?? '') || !Number.isSafeInteger(receipt?.item) || receipt.item < 1) throw refuse();
+ const file = board.db.prepare('PRAGMA database_list').all().find(row => row.name === 'main')?.file;
+ if (!file) throw refuse();
+ const directory = join(dirname(file), 'outside-check-output', String(receipt.item), receipt.id);
+ try {
+ if (readFileSync(join(directory, 'receipt.json'), 'utf8') !== JSON.stringify(receipt) + '\n') throw refuse();
+ for (const log of receipt.logs) {
+ if (!['minimum', 'current'].includes(log.role) || !['environment', 'baseline', 'gate', 'criterion'].includes(log.stage)) throw refuse();
+ const text = readFileSync(join(directory, `${log.role}-${log.stage}.log`));
+ if (createHash('sha256').update(text).digest('hex') !== log.sha256) throw refuse();
+ }
+ } catch { throw refuse(); }
+}
diff --git a/src/outside-source.js b/src/outside-source.js
new file mode 100644
index 00000000..276207a9
--- /dev/null
+++ b/src/outside-source.js
@@ -0,0 +1,33 @@
+/** Public outside-source facts; never credentials, native actors or executable provider settings. */
+import { Refused } from './refused.js';
+
+/** Read replayable metadata for one item without inferring native lineage for its outside author. */
+export function outsideSource(board, id) {
+ const row = board.db.prepare('SELECT meta_value FROM board_meta WHERE meta_key=?').get(`outside:${id}`);
+ return row ? JSON.parse(row.meta_value) : null;
+}
+
+/** Persist public facts inside the caller's ordered transaction. */
+export function saveOutsideSource(board, id, value) {
+ board.db.prepare('INSERT INTO board_meta(meta_key,meta_value) VALUES (?,?) ON CONFLICT(meta_key) DO UPDATE SET meta_value=excluded.meta_value')
+ .run(`outside:${id}`, JSON.stringify(value));
+}
+
+/** Require a person approval bound to the exact sensitive submission before any landing work. */
+export function requireOutsideOwner(board, item) {
+ const source = outsideSource(board, item.item_id);
+ if (source?.sensitive && (source.ownerApproval?.by !== 'person' || source.ownerApproval.commit !== item.item_commit)) {
+ throw new Refused('OUTSIDE_OWNER_APPROVAL', `outside item #${item.item_id} touches sensitive paths; the owner runs: pullboard intake approve ${item.item_id}`);
+ }
+}
+
+/** A board-level accept cannot bypass the container receipt by directly calling verify. */
+export function outsideSandboxProblem(board, item, receipt) {
+ if (!outsideSource(board, item.item_id)) return null;
+ if (!receipt || receipt.version !== 1 || receipt.provider !== 'docker' || receipt.commit !== item.item_commit || receipt.tree !== item.item_tree || receipt.digest !== item.item_frozen_digest ||
+ !Array.isArray(receipt.runs) || receipt.runs.length !== 2 || receipt.runs.some(run => run.exitCode !== 0 || run.network !== 'none' || run.credentials !== false || run.home !== 'empty') ||
+ !/^22\.13\./u.test(receipt.runs[0]?.environment?.node ?? '') || !/^24\./u.test(receipt.runs[1]?.environment?.node ?? '')) {
+ return new Refused('OUTSIDE_SANDBOX_REQUIRED', 'verify this outside item in the configured container: pullboard verify ' + item.item_id + ' accept --sandbox --note "what you checked"');
+ }
+ return null;
+}
diff --git a/src/outside-store.js b/src/outside-store.js
new file mode 100644
index 00000000..fae42cf8
--- /dev/null
+++ b/src/outside-store.js
@@ -0,0 +1,60 @@
+/** Ordered outside facts and the explicitly declared outside submission transition. */
+import { createHash } from 'node:crypto';
+import { logEvent } from './board-event-log.js';
+import { itemById } from './board-query.js';
+import { Refused } from './refused.js';
+import {
+ outsideSource,
+ saveOutsideSource,
+} from './outside-source.js';
+
+/** Validate exact immutable identifiers before recording an outside source. */
+function validate(source, frozen) {
+ if (!source || !['pull-request', 'issue'].includes(source.kind) || !/^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/u.test(source.repository ?? '') ||
+ !Number.isSafeInteger(source.number) || source.number < 1 || !/^[A-Za-z0-9-]{1,39}$/u.test(source.author ?? '') || !['open', 'closed'].includes(source.state) || typeof source.maintainerReplied !== 'boolean') {
+ throw new Refused('OUTSIDE_SOURCE', 'intake needs GitHub source metadata; fetch the exact issue or pull request again');
+ }
+ if (source.kind === 'pull-request' && (!/^[a-f0-9]{40}$/u.test(source.commit ?? '') || !/^[a-f0-9]{40}$/u.test(source.tree ?? '') || !frozen ||
+ createHash('sha256').update(frozen.text).digest('hex') !== frozen.digest)) throw new Refused('OUTSIDE_SOURCE', 'fetch the exact pull request commit and freeze its trusted criterion before intake');
+}
+
+/** Apply one replayable source refresh; refresh never silently replaces a submitted commit. */
+export function applyOutsideIntake(board, options, { atomic, addItem, moveItem }) {
+ return atomic(board, () => {
+ const { agentId, source, item, frozen } = options;
+ validate(source, frozen);
+ const existing = board.db.prepare("SELECT meta_key,meta_value FROM board_meta WHERE meta_key LIKE 'outside:%'").all()
+ .find(row => { const old = JSON.parse(row.meta_value); return old.repository === source.repository && old.kind === source.kind && old.number === source.number; });
+ if (existing) {
+ const id = Number(existing.meta_key.slice('outside:'.length));
+ const old = outsideSource(board, id);
+ if (source.kind === 'pull-request' && old.commit !== source.commit) throw new Refused('OUTSIDE_HEAD_CHANGED', 'the pull request head changed; ask the coordinator to reopen its recorded submission before intaking the new head');
+ saveOutsideSource(board, id, { ...old, state: source.state, maintainerReplied: source.maintainerReplied, updatedAt: source.updatedAt });
+ logEvent(board, agentId, 'outside-refresh', id, { source });
+ return id;
+ }
+ const id = addItem(board, { ...item, by: agentId });
+ saveOutsideSource(board, id, { ...source, ownerApproval: null, sandbox: null });
+ if (source.kind === 'pull-request') moveItem(board, id, 'intake', {
+ checks: { joined: null, itemExists: null, inState: () => new Refused('NOT_CLAIMABLE', 'intake files a new outside item'), outsideSubmission: null },
+ set: () => ({ item_built_by: `outside:github:${source.author}`, item_commit: source.commit, item_tree: source.tree,
+ item_claim_head: source.base, item_frozen: frozen.text, item_frozen_digest: frozen.digest, item_files: source.files.join('\n') }),
+ });
+ logEvent(board, agentId, 'outside-intake', id, { source, frozen });
+ return id;
+ });
+}
+
+/** Person authority is separate from native agent/parent identity and binds one exact commit. */
+export function approveOutside(board, id, { agentId }, atomic) {
+ return atomic(board, () => {
+ const item = itemById(board, id);
+ const source = outsideSource(board, id);
+ if (agentId !== 'person' || board.verifierStanding && !board.verifierStanding.person) throw new Refused('B26_PERSON_CHANNEL', 'only the owner approves outside sensitive changes through the person channel');
+ if (!source || source.kind !== 'pull-request') throw new Refused('OUTSIDE_SOURCE', 'choose an intaken pull request');
+ const ownerApproval = { by: 'person', commit: item.item_commit, at: board.clock.now().toISOString() };
+ saveOutsideSource(board, id, { ...source, ownerApproval });
+ logEvent(board, agentId, 'outside-owner-approval', id, { ownerApproval });
+ return ownerApproval;
+ });
+}
diff --git a/src/outside-verify.js b/src/outside-verify.js
new file mode 100644
index 00000000..16763b49
--- /dev/null
+++ b/src/outside-verify.js
@@ -0,0 +1,45 @@
+import { requireOutsideReceipt } from './outside-proof.js';
+/** Outside verification uses the ordinary native verdict authority but never checks out its executable tree. */
+import {
+ headCommit,
+ isClean,
+ untracked,
+} from './git.js';
+import {
+ freezer,
+ ordered,
+ resourceAgent,
+ textArg,
+} from './cli.js';
+import { withGateSlot } from './gate.js';
+import { Refused } from './refused.js';
+import { verifyOutsideSandbox } from './sandbox-verify.js';
+import {
+ itemPolicy,
+ requireTrunkMerge,
+} from './trusted-policy.js';
+
+/** Accept only a bound sandbox result; rejection does not execute contributed programs. */
+export async function outsideVerdict(ctx, board, item, me, decision, values) {
+ if (decision === 'ACCEPT' && !values.sandbox) throw new Refused('OUTSIDE_SANDBOX_REQUIRED', `outside code cannot be verified on the host; run pullboard verify ${item.item_id} accept --sandbox --note "what you checked"`);
+ const policy = itemPolicy(ctx.info.root, item);
+ const digest = freezer(ctx, { board })(item).digest;
+ if (digest !== item.item_frozen_digest) throw new Refused('CRITERIA_CHANGED', 'the trusted outside criterion changed; ask the coordinator to refreeze it');
+ let sandbox;
+ let review;
+ if (decision === 'ACCEPT') {
+ if (!isClean(ctx.info.root) || untracked(ctx.info.root).length) throw new Refused('DIRTY', 'commit the trusted reviewing checkout before sandbox verification');
+ const head = headCommit(ctx.info.root);
+ const trunk = requireTrunkMerge(ctx.info.root, item.item_commit);
+ sandbox = await withGateSlot(ctx.info.root, lease => verifyOutsideSandbox(ctx.info.root, item, policy, lease),
+ { remote: false, browser: false, agent: resourceAgent(ctx), item: String(item.item_id), kind: 'review', itemCheck: true });
+ requireOutsideReceipt(board, sandbox);
+ if (headCommit(ctx.info.root) !== head || !isClean(ctx.info.root) || untracked(ctx.info.root).length) throw new Refused('NOT_AT_COMMIT', 'the trusted reviewing checkout moved during sandbox verification; restore its clean head before reviewing again');
+ const after = requireTrunkMerge(ctx.info.root, item.item_commit);
+ if (after.commit !== trunk.commit) throw new Refused('VERDICT_TRUNK_MOVED', 'main moved during sandbox verification; review the outside change against current main');
+ review = { commit: item.item_commit, head: item.item_commit, trunk: trunk.commit, paths: [...new Set([...(item.outside.files ?? []), 'pullboard.json', 'SPEC.md', 'DOCTRINE.md'])] };
+ }
+ return ordered(ctx, board, 'verify', [item.item_id, { agentId: me.id, decision, reason: values.reason,
+ note: textArg(ctx.io, values, 'note') ?? '', head: item.item_commit, digest, policy: policy.config.verify.policy, familyPolicy: policy.config.verify.family,
+ ...(decision === 'ACCEPT' ? { sandbox, review, check: 'green', environment: sandbox.runs[1].environment } : { cause: values.cause }) }]);
+}
diff --git a/src/relay-sender.js b/src/relay-sender.js
index 867b2784..c4f9d674 100644
--- a/src/relay-sender.js
+++ b/src/relay-sender.js
@@ -7,6 +7,8 @@ export function relayMoveActor(move) {
const args = move?.args;
if (!Array.isArray(args)) return null;
if (move.operation === 'register' && move.engine >= VERIFIER_STANDING_ENGINE) return args[0]?.createdBy === 'machine' ? null : args[0]?.createdBy ?? null;
+ if (move.operation === 'intakeOutside') return args[0]?.agentId ?? null;
+ if (move.operation === 'approveOutside') return args[1]?.agentId ?? null;
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;
diff --git a/src/sandbox-verify.js b/src/sandbox-verify.js
new file mode 100644
index 00000000..127ca0a3
--- /dev/null
+++ b/src/sandbox-verify.js
@@ -0,0 +1,152 @@
+/** Docker-compatible, fail-closed execution of outside programs. No host-process isolation fallback. */
+import { execFile } from 'node:child_process';
+import {
+ createHash,
+ randomUUID,
+} from 'node:crypto';
+import {
+ existsSync,
+ mkdtempSync,
+ mkdirSync,
+ rmSync,
+ writeFileSync,
+} from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import {
+ git,
+ repoInfo,
+} from './git.js';
+import { Refused } from './refused.js';
+import { mainPolicy } from './trusted-policy.js';
+
+/** Await the owned client while native physical-admission heartbeats remain live. */
+function client(executable, args, options) {
+ return new Promise(resolve => {
+ execFile(executable, args, { encoding: 'utf8', ...options }, (error, stdout, stderr) => resolve({
+ error: error && typeof error.code !== 'number' ? error : null,
+ signal: error?.signal ?? null, status: error ? typeof error.code === 'number' ? error.code : null : 0,
+ stdout: stdout ?? '', stderr: stderr ?? '',
+ }));
+ });
+}
+
+/** Docker clients receive only deliberately constructed runtime discovery, never the host's credentials. */
+function clientEnvironment(directory, endpoint) {
+ const home = join(directory, 'client-home');
+ mkdirSync(home);
+ const config = join(home, '.docker');
+ mkdirSync(config);
+ writeFileSync(join(config, 'config.json'), '{}\n');
+ return { PATH: '/usr/bin:/bin:/usr/sbin:/sbin:/opt/homebrew/bin', HOME: home, DOCKER_CONFIG: config, DOCKER_HOST: endpoint };
+}
+
+/** Materialize only reachable Git objects into a private, independent source repository, never an operational mount. */
+function exportSource(root, commit, directory) {
+ const target = join(directory, 'source-' + randomUUID());
+ mkdirSync(target);
+ const home = join(directory, 'export-home-' + randomUUID());
+ mkdirSync(home);
+ const template = join(home, 'empty-template');
+ mkdirSync(template);
+ // New private export has no inherited Git config, templates, hooks, worktree pointer or alternates.
+ const env = { PATH: process.env.PATH, HOME: home, GIT_CONFIG_NOSYSTEM: '1', GIT_CONFIG_GLOBAL: '/dev/null', GIT_NO_REPLACE_OBJECTS: '1' };
+ git(target, ['init', '-q', '--template=' + template], { env });
+ git(target, ['fetch', '-q', '--no-tags', '--no-write-fetch-head', '--no-recurse-submodules', root, commit], { env });
+ git(target, ['checkout', '-q', '--detach', commit], { env });
+ const tree = git(target, ['rev-parse', 'HEAD^{tree}'], { env }).trim();
+ if (existsSync(join(target, '.git', 'objects', 'info', 'alternates')) || existsSync(join(target, '.git', 'commondir')) || existsSync(join(target, '.git', 'pullboard'))) {
+ throw new Refused('SANDBOX_EXPORT', 'the private export is not independent; restore Git object access before sandbox verification');
+ }
+ return { target, tree };
+}
+
+/** A supported provider must be explicitly configured by accepted main, with two immutable official runtime images. */
+function provider(root) {
+ const value = mainPolicy(root).config.sandbox;
+ if (!value || value.provider !== 'docker' || typeof value.executable !== 'string' || !value.executable.startsWith('/') ||
+ typeof value.endpoint !== 'string' || !/^unix:\/\/\/[^\r\n]+$/u.test(value.endpoint) ||
+ !['minimum', 'current'].every(role => /^node@sha256:[a-f0-9]{64}$/u.test(value.images?.[role] ?? ''))) {
+ throw new Refused('SANDBOX_PROVIDER_REQUIRED', 'configure sandbox.provider=docker with an absolute executable, explicit Unix endpoint and pinned node@sha256 images for minimum/current in committed main pullboard.json; no host fallback is permitted');
+ }
+ return value;
+}
+
+/** Run one owned container; bounded client output/timeout and unconditional owned-container cleanup are not a pass. */
+async function container(runtime, environment, directory, image, source, stage, command) {
+ const name = 'pullboard-outside-' + randomUUID();
+ const cid = join(directory, name + '.cid');
+ const args = ['run', '--pull', 'never', '--name', name, '--cidfile', cid, '--network', 'none', '--read-only',
+ '--cap-drop', 'ALL', '--security-opt', 'no-new-privileges', '--pids-limit', '256', '--memory', '2g', '--cpus', '2',
+ '--user', '1000:1000', '--tmpfs', '/work:rw,nosuid,nodev,size=1073741824,mode=1777',
+ '--tmpfs', '/home/sandbox:rw,nosuid,nodev,size=67108864,mode=1777', '--tmpfs', '/tmp:rw,nosuid,nodev,size=268435456,mode=1777',
+ '--env', 'HOME=/home/sandbox', '--env', 'PATH=/usr/local/bin:/usr/bin:/bin', '--label', `pullboard.sandbox.stage=${stage}`,
+ '--mount', `type=bind,source=${source},target=/source,readonly`, '--workdir', '/work', image,
+ '/bin/sh', '-eu', '-c', 'cp -R /source/. /work/; cd /work; ' + command];
+ let result;
+ try {
+ result = await client(runtime.executable, args, { env: environment, encoding: 'utf8', timeout: 300_000, maxBuffer: 8 * 1024 * 1024 });
+ } finally {
+ // Names are newly generated and never accepted from a caller or foreign receipt.
+ const cleanup = await client(runtime.executable, ['rm', '--force', name], { env: environment, encoding: 'utf8', timeout: 15_000, maxBuffer: 8192 });
+ if (cleanup.error || cleanup.status !== 0) throw new Refused('SANDBOX_CLEANUP_REQUIRED', `the owned container ${name} could not be removed; restore Docker and remove that exact container before another sandbox verification`);
+ }
+ if (result.error || result.signal || result.status === null) throw new Refused('SANDBOX_EXECUTION', 'the sandbox did not complete; restore the configured Docker runtime and inspect its owned container before retrying');
+ return { exitCode: result.status, output: result.stdout + result.stderr };
+}
+
+/** Verify both pinned image roles inside actual containers, then execute the trusted full gate and frozen criterion. */
+export async function verifyOutsideSandbox(root, item, policy, lease) {
+ const runtime = provider(root);
+ const directory = mkdtempSync(join(tmpdir(), 'pullboard-outside-'));
+ try {
+ const environment = clientEnvironment(directory, runtime.endpoint);
+ const command = JSON.parse(item.item_frozen).check;
+ if (!command || !policy.config.gate?.trim()) throw new Refused('SANDBOX_CHECK_REQUIRED', 'the trusted frozen criterion and full gate must both name commands; ask the coordinator to set them before intake');
+ const candidate = exportSource(root, item.item_commit, directory);
+ const baseline = exportSource(root, item.item_claim_head, directory);
+ if (candidate.tree !== item.item_tree) throw new Refused('SANDBOX_EXPORT', 'the exact PR tree differs from the recorded submission; fetch its recorded objects again');
+ const runs = [];
+ const id = randomUUID();
+ const outputDirectory = join(repoInfo(root).commonDir, 'pullboard', 'outside-check-output', String(item.item_id), id);
+ mkdirSync(outputDirectory, { recursive: true });
+ const logs = [];
+ /** Retain bounded output and its digest, independently of the temporary export. */
+ const record = (role, stage, result) => {
+ const name = `${role}-${stage}.log`;
+ writeFileSync(join(outputDirectory, name), result.output);
+ logs.push({ role, stage, exitCode: result.exitCode, sha256: createHash('sha256').update(result.output).digest('hex') });
+ return result;
+ };
+ for (const role of ['minimum', 'current']) {
+ lease?.renew?.();
+ const image = runtime.images[role];
+ const inspected = await client(runtime.executable, ['image', 'inspect', image], { env: environment, encoding: 'utf8', timeout: 15_000, maxBuffer: 65536 });
+ if (inspected.error || inspected.status !== 0) throw new Refused('SANDBOX_IMAGE_REQUIRED', `preload the explicitly pinned ${role} image ${image} into the configured Docker daemon; sandbox verification never pulls automatically`);
+ let imageFacts;
+ try { imageFacts = JSON.parse(inspected.stdout)[0]; }
+ catch { throw new Refused('SANDBOX_IMAGE_REQUIRED', 'the configured image has no readable digest receipt; restore the pinned official Node image'); }
+ if (!imageFacts?.RepoDigests?.includes(image)) throw new Refused('SANDBOX_IMAGE_REQUIRED', 'the local runtime image does not match the configured digest; preload that exact official Node image');
+ const measured = record(role, 'environment', await container(runtime, environment, directory, image, candidate.target, 'environment', 'node -p ' + "'JSON.stringify({node:process.versions.node,platform:process.platform,arch:process.arch})'"));
+ let actual;
+ try { actual = JSON.parse(measured.output.trim()); }
+ catch { throw new Refused('SANDBOX_RUNTIME', 'the container did not report its actual Node environment; restore the pinned Node runtime'); }
+ if (measured.exitCode !== 0 || actual.platform !== 'linux' || !['arm64', 'x64'].includes(actual.arch) || !(role === 'minimum' ? /^22\.13\./u : /^24\./u).test(actual.node ?? '')) throw new Refused('SANDBOX_RUNTIME', `the ${role} image must execute ${role === 'minimum' ? 'Node22.13.x' : 'Node24.x'} on Linux; correct its pinned digest`);
+ const before = record(role, 'baseline', await container(runtime, environment, directory, image, baseline.target, 'baseline', command));
+ lease?.renew?.();
+ if (before.exitCode === 0) throw new Refused('CHECK_NO_PROOF', 'the frozen check also passes before the outside change; strengthen its causal behavior assertion before intake');
+ const gate = record(role, 'gate', await container(runtime, environment, directory, image, candidate.target, 'gate', policy.config.gate));
+ lease?.renew?.();
+ const criterion = record(role, 'criterion', await container(runtime, environment, directory, image, candidate.target, 'criterion', command));
+ lease?.renew?.();
+ if (gate.exitCode !== 0 || criterion.exitCode !== 0) throw new Refused('CHECK_RED', `outside ${role} sandbox check is red; return the failing behavior to its author\n${(gate.output + criterion.output).slice(-12000)}`);
+ runs.push({ role, image, imageId: imageFacts.Id, environment: actual, exitCode: 0, network: 'none', credentials: false, home: 'empty', baselineExit: before.exitCode });
+ }
+ writeFileSync(join(outputDirectory, 'manifest.json'), JSON.stringify({ commit: item.item_commit, tree: item.item_tree, digest: item.item_frozen_digest, runs, logs }, null, 2) + '\n');
+ const receipt = { id, item: item.item_id, logs, version: 1, provider: 'docker', commit: item.item_commit, tree: item.item_tree, digest: item.item_frozen_digest, at: new Date().toISOString(), runs };
+ writeFileSync(join(outputDirectory, 'receipt.json'), JSON.stringify(receipt) + '\n');
+ return receipt;
+ } finally {
+ rmSync(directory, { recursive: true, force: true });
+ }
+}
diff --git a/test/intake-fixture.js b/test/intake-fixture.js
index 7663d5d7..f95eed1c 100644
--- a/test/intake-fixture.js
+++ b/test/intake-fixture.js
@@ -68,7 +68,7 @@ export function intakeFixture(t) {
user: { login: 'issue-author' }, html_url: 'https://github.com/fixture/project/issues/6', created_at: '2026-01-01T00:00:00Z', updated_at: '2026-01-02T00:00:00Z' } }));
executable(box, 'gh', `const fs=require('node:fs'); const args=process.argv.slice(2); fs.appendFileSync(${JSON.stringify(ghLog)},JSON.stringify(args)+'\\n');
const facts=JSON.parse(fs.readFileSync(${JSON.stringify(facts)},'utf8'));
-const route=(args.find(arg=>arg.startsWith('repos/')||arg.startsWith('/repos/'))||'').replace(/^\\//,'');
+const route=(args.find(arg=>arg.startsWith('repos/')||arg.startsWith('/repos/'))||'').replace(/^\\//,'').split('?')[0];
let value;
if(args[0]==='repo'&&args[1]==='view') value={nameWithOwner:'fixture/project',defaultBranchRef:{name:'main'}};
else if(args[0]!=='api'||args.includes('--method')||args.includes('-X')) { process.stderr.write('fixture refuses posting or unknown commands'); process.exit(2); }
@@ -80,7 +80,7 @@ else if(route==='repos/fixture/project/issues/6/comments') value=facts.issueComm
else if(route==='repos/fixture/project/issues/7/comments') value=[{user:{login:'maintainer'},author_association:'MEMBER',body:'Recorded for review.'}];
else if(route==='repos/fixture/project') value={full_name:'fixture/project',default_branch:'main',owner:{login:'fixture'}};
else { process.stderr.write('unrecognized fixture GitHub route '+route); process.exit(2); }
-process.stdout.write(JSON.stringify(value));\n`);
+process.stdout.write(JSON.stringify(args.includes('--slurp')?[value]:value));\n`);
return { ...made, ...box, base, commit, tree, fork, origin, facts, ghLog, pull };
}
@@ -98,7 +98,7 @@ else if(args[0]==='version') process.stdout.write('29.0.0');
else if(args[0]==='run') {
const cid=args.indexOf('--cidfile'); if(cid>=0) fs.writeFileSync(args[cid+1],'c'.repeat(64));
if(args.includes('--version')) process.stdout.write(minimum?'v22.13.1':'v24.21.0');
- else if(args.includes('-p')||args.includes('--eval')) process.stdout.write(JSON.stringify({node:minimum?'22.13.1':'24.21.0',platform:'linux',arch:'arm64'}));
+ else if(args.includes('-p')||args.includes('--eval')||args.some(arg=>arg.includes('node -p '))) process.stdout.write(JSON.stringify({node:minimum?'22.13.1':'24.21.0',platform:'linux',arch:'arm64'}));
else { const baseline=args.includes('pullboard.sandbox.stage=baseline'); process.stdout.write('TAP version 13\\n'+(baseline?'not ok':'ok')+' 1 - fixture sandbox stage\\n1..1\\n# tests 1\\n# pass '+(baseline?'0':'1')+'\\n# fail '+(baseline?'1':'0')+'\\n# skipped 0\\n'); if(baseline) process.exitCode=1; }
} else if(args[0]==='inspect') process.stdout.write('[]');
else if(!['rm','kill'].includes(args[0])) { process.stderr.write('unknown fixture Docker command'); process.exit(2); }\n`);
diff --git a/test/intake.test.js b/test/intake.test.js
index dcc57a0d..5218590c 100644
--- a/test/intake.test.js
+++ b/test/intake.test.js
@@ -49,7 +49,7 @@ test('an intaken pull request is verified only in the sandbox [V1,V2,V3,B26]', t
assert.equal(item.outside.sandbox.tree, box.tree);
assert.deepEqual(item.outside.sandbox.runs.map(run => run.environment.node), ['22.13.1', '24.21.0']);
assert.equal(item.outside.ownerApproval, null);
- refusal(box.run(box.repo, 'land', id, '--json'), 'OUTSIDE_OWNER_APPROVAL');
+ refusal(box.run(box.repo, 'land', '--json'), 'OUTSIDE_OWNER_APPROVAL');
assert.equal(box.git(box.repo, 'rev-parse', 'HEAD') === box.commit, false, 'sensitive PR never reaches the local trunk without its owner');
fixtureJSON(box, box.repo, 'intake', 'approve', id);
item = fixtureJSON(box, box.repo, 'show', id);