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.
JavaScript agentic-codingai-agentsai-governanceautonomous-agentsclaude-codeclicode-reviewcodexcoding-agentsdeveloper-toolsgit-hooksllmlocal-firstmulti-agentsoftware-factoryspec-driven-developmentverificationvibe-coding
feat(init): a Codex agent is told how to make the board writable [I1,P4]
Corey Olsond326a98c0873
diff --git a/src/board-access.js b/src/board-access.jsindex f4235a31..156ad2c0 100644--- a/src/board-access.js+++ b/src/board-access.js@@ -1,7 +1,11 @@/** Name a board this process cannot write, such as one inside a read-only agent sandbox [I1,P4]. */import { dirname } from 'node:path';+import { AGENT_SHELL_MARKERS } from './person.js';import { Refused } from './refused.js';+/** The markers a Codex session sets; its sandbox needs the board folder named to Codex itself. */+const CODEX_MARKERS = AGENT_SHELL_MARKERS.filter((name) => name.startsWith('CODEX_'));+/*** Turn SQLite's bare readonly or cannot-open error, or a file-system access error, into a named* refusal that says which folder to open up; any other error comes back unchanged.@@ -12,9 +16,15 @@ import { Refused } from './refused.js';* @param {Error & { errcode?: number, code?: string }} error* @returns {Error}*/-export function boardNotWritable(file, error) {+export function boardNotWritable(file, error, environment = process.env) {const sqliteCode = Number.isInteger(error?.errcode) ? error.errcode & 0xff : null;if (sqliteCode !== 8 && sqliteCode !== 14 && !['EACCES', 'EPERM', 'EROFS'].includes(error?.code ?? '')) return error;+ const folder = dirname(file);+ // Codex's workspace-write sandbox keeps .git read-only; its own flag grants the one folder (#913).+ if (CODEX_MARKERS.some((name) => Boolean(environment[name]))) {+ return new Refused('BOARD_NOT_WRITABLE', `Cannot write the board in "${folder}": Codex's workspace-write sandbox keeps .git read-only.`,+ `restart Codex with that folder writable: codex --add-dir '${folder.replaceAll("'", "'\\''")}' (or add it to writable_roots under [sandbox_workspace_write] in ~/.codex/config.toml), then run the command again`);+ }return new Refused('BOARD_NOT_WRITABLE',- `Cannot write the board in "${dirname(file)}". Give the agent write access to that folder, the repo's .git/pullboard, or run the command outside the sandbox.`);+ `Cannot write the board in "${folder}". Give the agent write access to that folder, the repo's .git/pullboard, or run the command outside the sandbox.`);}diff --git a/src/init.js b/src/init.jsindex 4ab9606d..12f30c31 100644--- a/src/init.js+++ b/src/init.js@@ -42,6 +42,7 @@ import {settingCommand,} from './gate-config.js';export { detectGate } from './gate-config.js';+import { gitPath } from './git.js';import { machineHome } from './machine-home.js';import { Refused } from './refused.js';import { reviewerStartup } from './next-steps.js';@@ -542,9 +543,10 @@ function writeCodexLoopRules(root, gate, onWrite) {if (!machineHomeWriteScopeIsNarrow(machinePath)) {return `${rulesNote}; trust this project and restart the session to load rules. Machine-home write was not granted because the path is the OS home, an ancestor of it, or a filesystem root; choose a narrower PULLBOARD_MACHINE_HOME`;}- const workspaceWrite = `sandbox_mode = "workspace-write"\n\n[sandbox_workspace_write]\nwritable_roots = ${JSON.stringify([machinePath])}`;+ // The board folder sits under .git, which Codex keeps read-only, so it is granted beside the machine home (#913).+ const workspaceWrite = `sandbox_mode = "workspace-write"\n\n[sandbox_workspace_write]\nwritable_roots = ${JSON.stringify([machinePath, gitPath(root, 'pullboard')])}`;const profileWrite = `${JSON.stringify(machinePath)} = "write"`;- return `${rulesNote}; trust this project and restart the session to load rules. For machine-home access, merge these exact values into legacy Codex settings: put sandbox_mode at the TOML top level before any table, append this exact path to any existing writable_roots array while keeping its entries, and do not duplicate the table or replace unrelated settings:\n${workspaceWrite}\nPermission-profile users add ${profileWrite} under their existing [permissions.<active-profile>.filesystem] table instead; do not mix the two configuration formats. Official docs: https://learn.chatgpt.com/docs/config-file/config-reference and https://learn.chatgpt.com/docs/permissions`;+ return `${rulesNote}; trust this project and restart the session to load rules. For machine-home access, merge these exact values into legacy Codex settings: put sandbox_mode at the TOML top level before any table, append these exact paths to any existing writable_roots array while keeping its entries, and do not duplicate the table or replace unrelated settings:\n${workspaceWrite}\nPermission-profile users add ${profileWrite} under their existing [permissions.<active-profile>.filesystem] table instead; do not mix the two configuration formats. Official docs: https://learn.chatgpt.com/docs/config-file/config-reference and https://learn.chatgpt.com/docs/permissions`;}/**diff --git a/src/templates.js b/src/templates.jsindex 300e232c..62844b9f 100644--- a/src/templates.js+++ b/src/templates.js@@ -128,6 +128,8 @@ ${doctrineText(doctrine)}It prints the folder to work in and what to run there first. Every join needs the exact model label, either with \`--model\` or the \`PULLBOARD_MODEL\` environment variable; family is separate and never supplies the model. A smaller model joins with \`--route light\` or \`--route mid\` and takes items at its tier and below. Work only in that folder. Your shell may start every command in the main checkout, where pullboard takes you for the coordinator, so begin each command with \`cd <your worktree> &&\`. Verifiers take the \`review\` lane, which owns no folders. Only the coordinator adds a lane, from the main checkout, once the person agrees: \`pullboard lane add <name> --owns <path>[,<path>]\`. \`pullboard init\` proposes lanes from the folder layout and writes none until the person accepts. Keep your worktree and branch until your items are merged.+**Codex.** Codex's workspace-write sandbox keeps \`.git\` read-only, and the board lives in \`.git/pullboard\`, so start Codex with that folder writable before the first pullboard command: \`codex --add-dir "$(git rev-parse --path-format=absolute --git-common-dir)/pullboard"\` (or add the folder to \`writable_roots\` under \`[sandbox_workspace_write]\` in \`~/.codex/config.toml\`). A refused \`BOARD_NOT_WRITABLE\` names the same step.+**The loop.**1. \`pullboard resume\` at the start of every session and after your context is compacted: your claim, what came back, unread shouts and the next step. Then \`pullboard inbox\`.2. \`pullboard next\` claims the next free item your session can take across the lanes, by release and queue rank. It names the lane worktree to use and opens one when your session has none there; begin subsequent commands in that folder. Each worktree still owns only its lane’s files. Joining associates the seat with the invoking agent session automatically; no person setup is needed. When everything is waiting on other work, \`pullboard next --wait 9\` keeps looking for up to 9 minutes, which fits one tool call with a ten-minute timeout; run it again to keep waiting. A claim is a 2-hour lease; claim again to renew. The criterion freezes now: \`pullboard show <id>\` is the bar your work is judged against, and its brief says how to start. \`pullboard why <id>\` lists the decisions that changed it, newest first. When your own answer, verdict or fact changes other items, name them with \`--implies <ids>\` so each one carries it. A claim or submit refused as CRITERION_PROVES_NOTHING names a check that already passes on main, so it proves nothing: shout the coordinator for a check that fails before the work. Only the person accepts a check as it stands, with \`pullboard check accept <id>\` from the main checkout or the view.diff --git a/test/init-permissions.test.js b/test/init-permissions.test.jsindex ea4fa679..a1db6f00 100644--- a/test/init-permissions.test.js+++ b/test/init-permissions.test.js@@ -155,9 +155,10 @@ test('init grants the agent the permissions the Pullboard loop needs [I1,I2]', tassert.deepEqual(codexPrefixes(codexRules), [['pullboard'], ['git', 'status'], ['git', 'diff'], ['git', 'log'], ['git', 'add'], ['git', 'commit'], ['git', 'merge'], ['git', 'rebase'], ['git', 'switch'], ['git', 'checkout'], ['git', 'worktree'], ['npm', 'test']], 'Codex rules stay scoped to the exact loop commands');assert.ok(initialized.document.notes.some(note => /Claude Code.*Pullboard loop/u.test(note)), 'init says what Claude rules it added');assert.ok(initialized.document.notes.some(note => /trusted-project Codex rules.*trust this project and restart the session/u.test(note)), 'init explains trust and session restart for Codex rules');- const expectedLegacyCodex = `sandbox_mode = "workspace-write"\n\n[sandbox_workspace_write]\nwritable_roots = ${JSON.stringify([machineHomePath])}`;+ // The board folder under .git is granted beside the machine home, since Codex keeps .git read-only (#913).+ const expectedLegacyCodex = `sandbox_mode = "workspace-write"\n\n[sandbox_workspace_write]\nwritable_roots = ${JSON.stringify([machineHomePath, join(box.root, '.git', 'pullboard')])}`;assert.ok(initialized.document.notes.some(note => note.includes(expectedLegacyCodex)), 'Codex setup prints exact legacy workspace-write values scoped to the machine home');- assert.ok(initialized.document.notes.some(note => /sandbox_mode at the TOML top level before any table, append this exact path to any existing writable_roots array while keeping its entries, and do not duplicate the table or replace unrelated settings/u.test(note)), 'Codex setup explains the top-level key and exact append without replacing settings or duplicating the TOML table');+ assert.ok(initialized.document.notes.some(note => /sandbox_mode at the TOML top level before any table, append these exact paths to any existing writable_roots array while keeping its entries, and do not duplicate the table or replace unrelated settings/u.test(note)), 'Codex setup explains the top-level key and exact append without replacing settings or duplicating the TOML table');assert.ok(initialized.document.notes.some(note => /https:\/\/learn\.chatgpt\.com\/docs\/config-file\/config-reference.*https:\/\/learn\.chatgpt\.com\/docs\/permissions/u.test(note)), 'Codex setup cites the official sandbox and permission-profile references');assert.equal(readFileSync(codexConfigPath, 'utf8'), existingCodexConfig, 'init prints Codex configuration guidance without rewriting a project config');assert.ok(initialized.document.notes.some(note => /permission-profile users.*existing \[permissions\.<active-profile>\.filesystem\].*do not mix/iu.test(note)), 'Codex setup explains the permission-profile alternative without mixing config systems');diff --git a/test/machine-home.test.js b/test/machine-home.test.jsindex 6f9e43de..6ffea5b8 100644--- a/test/machine-home.test.js+++ b/test/machine-home.test.js@@ -122,3 +122,21 @@ test('a read-only board refuses resume by name [I1,L3,P4]', () => {} finally { unlockBoard(folder); }assert.equal(p.run(p.repo, 'resume').code, 0, 'restoring write access, the step it names, lets resume run');});++test('a Codex agent that cannot write the board is told the Codex step that grants it [I1,P4]', () => {+ const p = project();+ const folder = join(p.repo, '.git', 'pullboard');+ assert.equal(p.run(p.repo, 'resume').code, 0, 'the board opens before it is locked');+ // init's agent guidance names the step before the first refusal.+ assert.match(readFileSync(join(p.repo, 'AGENTS.md'), 'utf8'), /\*\*Codex\.\*\* .*codex --add-dir "\$\(git rev-parse --path-format=absolute --git-common-dir\)\/pullboard"/u);+ lockBoard(folder);+ try {+ const codex = runFixtureChild(process.execPath, [join(import.meta.dirname, '..', 'bin', 'pullboard.js'), 'resume', '--json'],+ { cwd: p.repo, env: { ...p.env, CODEX_THREAD_ID: 'codex-thread-913' }, encoding: 'utf8' });+ assert.notEqual(codex.status, 0);+ const { error } = JSON.parse(codex.stdout);+ assert.equal(error.code, 'BOARD_NOT_WRITABLE');+ assert.match(error.message, /Codex's workspace-write sandbox keeps \.git read-only/u);+ assert.equal(error.next, `restart Codex with that folder writable: codex --add-dir '${folder}' (or add it to writable_roots under [sandbox_workspace_write] in ~/.codex/config.toml), then run the command again`);+ } finally { unlockBoard(folder); }+});