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(agents): helper seats record a parent; agents lists them [N2,B13]
Corey Olson92aa10924564
diff --git a/docs/api.md b/docs/api.mdindex 0bc8d6f4..75e01306 100644--- a/docs/api.md+++ b/docs/api.md@@ -83,6 +83,7 @@ For example: `flow: review wait average 61 min (1 measured; > 60 min); bottlenec| `worktree` | `version:number`, `agent:string`, `lane:string`, `route:string`, `path:string`, `branch:string`, `prompt:string`, `model:string`, `displayName:string` || `resume` | `version:number`, `me:object`, `all:array`, `requests:array`, `holding:array`, `sentBack:array`, `awaiting:array`, `toVerify:array`, `toMerge:array`, `open:array`, `stale:array`, `doctrineNotes:array`, `holds:array`, `unread:number`, `newest:array`, `root:string`, `newWorktreeLocation:string`, `dirty:number`, `next:string` || `whoami` | `version:number`, `id:string`, `lane:string`, `path:string`, `model:string`, `displayName:string` |+| `agents` | `version:number`, `agents:array` || `lanes` | `version:number`, `lanes:object`, `shared:array`, `coordinator:string` || `lane add` | `version:number`, `lane:string`, `owns:array` || `resources` | `version:number`, `resources:array` |diff --git a/src/agent-session.js b/src/agent-session.jsindex 1c3a46d3..9ee118a3 100644--- a/src/agent-session.js+++ b/src/agent-session.js@@ -131,3 +131,53 @@ export function localSessionSeats(info, { agents, digest }) {}return seats;}++/** Keep a helper seat's parent record in its own Git directory, beside its session binding. */+export function parentSessionFile(info) {+ return join(info.gitDir, 'pullboard-parent-session.json');+}++/**+ * Record which agent opened a helper seat, from inside that agent's session [N2,B13]. The record is local to the machine+ * and holds only the parent's id and session digest, so it can never lend the parent's claims to the helper: the helper+ * still claims and submits as itself.+ */+export function recordParentSession(info, { parent, digest }) {+ const file = parentSessionFile(info);+ const pending = file + '.' + process.pid + '.tmp';+ writeFileSync(pending, JSON.stringify({ version: 1, parent, digest, at: new Date().toISOString() }) + '\n', { mode: 0o600 });+ renameSync(pending, file);+}++/** Walk the board's linked checkouts and hand each registered agent's Git directory to visit. */+function eachSeatGitDir(info, agents, visit) {+ const directory = join(info.commonDir, 'worktrees');+ if (!existsSync(directory)) return;+ const registered = new Map(agents.filter((agent) => agent.agent_lane !== 'coordinator').map((agent) => [agent.agent_path, agent]));+ for (const entry of readdirSync(directory, { withFileTypes: true })) {+ if (!entry.isDirectory()) continue;+ const gitDir = join(directory, entry.name);+ try {+ const agent = registered.get(realpathSync(dirname(readFileSync(join(gitDir, 'gitdir'), 'utf8').trim())));+ if (agent) visit(agent, gitDir);+ } catch { /* A gone or half-removed checkout is not a seat to list. */ }+ }+}++/**+ * Map each helper agent's id to the id of the agent that opened it, and each agent's id to its session digest. Unreadable+ * or damaged records are skipped: they only mean the board lists that agent without a parent.+ */+export function seatLinks(info, agents) {+ const parents = new Map();+ const digests = new Map();+ eachSeatGitDir(info, agents, (agent, gitDir) => {+ for (const [name, field, into] of [['pullboard-parent-session.json', 'parent', parents], ['pullboard-checkout-session.json', 'digest', digests]]) {+ try {+ const value = JSON.parse(readFileSync(join(gitDir, name), 'utf8'));+ if (value.version === 1 && typeof value[field] === 'string') into.set(agent.agent_id, value[field]);+ } catch { /* No record, or a damaged one: no link. */ }+ }+ });+ return { parents, digests };+}diff --git a/src/cli.js b/src/cli.jsindex 6eac9c86..66a32d50 100644--- a/src/cli.js+++ b/src/cli.js@@ -88,6 +88,8 @@ import {HOOK_CHECKOUT_WAIT_MS,localSessionMatches,localSessionSeats,+ recordParentSession,+ seatLinks,} from './agent-session.js';import {decisionAnswer,@@ -2183,9 +2185,10 @@ function setupCommands(io, { first, second, rest = [], values }) {* @param {string} route* @param {string | null} family* @param {string | undefined} model+ * @param {boolean} helper - true when the seat is for another agent, so it records the session that opened it as its parent [N2,B13]; `next` opens the caller's own seat and passes false* @returns {Promise<number>}*/-async function worktreeFor(io, lane, route, family = null, model) {+async function worktreeFor(io, lane, route, family = null, model, helper = true) {const ctx = context(io);if (!lane || lane === COORDINATOR || !isLane(ctx.config, lane)) {throw new Refused('NO_LANE', `no lane "${lane ?? ''}"; lanes: ${laneNames(ctx.config).slice(1).join(', ') || 'none yet, declare them in pullboard.json'}`);@@ -2221,6 +2224,14 @@ async function worktreeFor(io, lane, route, family = null, model) {else io.err(`pullboard: registration failed; the changed worktree was preserved at ${root}`);throw error;}+ const digest = helper ? agentSessionDigest() : null;+ if (digest) {+ // A local note beside the new checkout; a failure to write it never undoes the seat that was made.+ const parent = ctx.info.isMain ? COORDINATOR : withBoard(ctx, (board) => store.agentAt(board, ctx.info.root)?.agent_id);+ if (parent) {+ try { recordParentSession(repoInfo(root), { parent, digest }); } catch { /* The seat still works without its parent note. */ }+ }+ }const displayName = displayAgentName({ agent_id: id, agent_model: model }, ctx.config.agents.names);const modelWord = shellWord(model);const prompt = `You are ${displayName}, in the ${lane} lane. Work only in ${shellWord(root)}, and start every command with ${cdTo(root)}\nModel: ${modelWord}. This worktree joined with --model ${modelWord}. For another worktree using the same model, pass --model ${modelWord} or set PULLBOARD_MODEL=${modelWord}; for a different agent, use that agent's actual model label.\nRead ${shellWord(join(root, 'AGENTS.md'))} first. Its rules govern this work, over any other repo's instructions you were given.`;@@ -2239,6 +2250,35 @@ async function worktreeFor(io, lane, route, family = null, model) {return 0;}+/**+ * Every joined agent with its seats, its helpers and what each holds, helpers nested under the agent that opened them+ * [N2,B13]. The parent links are read from this machine's checkouts; a helper whose parent is gone is listed on its own.+ *+ * @param {any} ctx+ * @param {any} board+ * @returns {any[]}+ */+function agentTree(ctx, board) {+ const agents = store.listAgents(board).filter((agent) => agent.agent_lane !== COORDINATOR);+ const { parents, digests } = seatLinks(ctx.info, agents);+ const held = new Map();+ for (const item of store.listItems(board)) {+ if (!item.item_owner || !['claimed', 'submitted'].includes(item.item_status)) continue;+ held.set(item.item_owner, [...(held.get(item.item_owner) ?? []), { item: item.item_id, status: item.item_status }]);+ }+ const known = new Set(agents.map((agent) => agent.agent_id));+ const row = (agent, seen) => ({+ id: agent.agent_id, displayName: displayAgentName(agent, ctx.config.agents.names), lane: agent.agent_lane, path: agent.agent_path,+ seats: agents.filter((seat) => seat.agent_id === agent.agent_id || (digests.has(agent.agent_id) && digests.get(seat.agent_id) === digests.get(agent.agent_id)))+ .map((seat) => ({ id: seat.agent_id, path: seat.agent_path })),+ holds: held.get(agent.agent_id) ?? [],+ helpers: agents.filter((helper) => parents.get(helper.agent_id) === agent.agent_id && !seen.has(helper.agent_id))+ .map((helper) => row(helper, new Set([...seen, helper.agent_id]))),+ });+ const parentId = (agent) => parents.get(agent.agent_id);+ return agents.filter((agent) => !known.has(parentId(agent))).map((agent) => row(agent, new Set([agent.agent_id])));+}+/** Describe the active configured location for new agent worktrees. */function worktreeLocation(mainRoot, config) {return config.worktrees === 'inside'@@ -2417,6 +2457,19 @@ function readCommands(io, { first, second, rest, values }) {io.say(`${me.displayName} (${me.lane} lane${me.route === 'light' ? ', light route' : ''}) at ${ctx.info.root}`);return 0;},+ agents: () => {+ const ctx = context(io);+ const listed = withBoard(ctx, (board) => agentTree(ctx, board));+ io.result?.({ agents: listed });+ if (!listed.length) io.say('no agents have joined');+ const show = (agent, indent) => {+ const held = agent.holds.map((hold) => `#${hold.item} (${hold.status})`).join(', ');+ io.say(`${indent}${agent.displayName} (${agent.lane} lane) at ${agent.path}${held ? `: ${held}` : ''}`);+ for (const helper of agent.helpers) show(helper, indent + ' ');+ };+ for (const agent of listed) show(agent, '');+ return 0;+ },lanes: () => {const { config } = context(io);io.result?.({ lanes: config.lanes, shared: config.shared, coordinator: COORDINATOR });@@ -3179,7 +3232,7 @@ async function nextSeatContext(ctx, board, me, item, seats) {let created = false;if (!agent) {let opened;- await worktreeFor({ ...ctx.io, say: () => {}, result: (value) => { opened = value; } }, item.item_lane, me.route, me.family, me.model);+ await worktreeFor({ ...ctx.io, say: () => {}, result: (value) => { opened = value; } }, item.item_lane, me.route, me.family, me.model, false);agent = store.agentAt(board, opened.path);created = true;}diff --git a/src/help.js b/src/help.jsindex 33979cc4..792353d3 100644--- a/src/help.js+++ b/src/help.js@@ -18,6 +18,7 @@ Set uppullboard join coordinator --model <name> declare the main checkout's coordinator modelpullboard.json agents.names: suffix (default) or prefixpullboard whoami | lanes | status who you are, the lanes, the board at a glance+ pullboard agents each agent with its seats and helpers, and what each holdspullboard lane add <name> --owns <path>[,<path>] add a lane that owns those folders to pullboard.jsonrefuses a lane name or a path that is already owned, naming the ownerpullboard takeover rebind this checkout when the same agent starts a new session@@ -296,6 +297,7 @@ const HELP_ALIASES = {version: { usage: 'pullboard version', source: null },whoami: { usage: 'pullboard whoami', source: 'whoami' },lanes: { usage: 'pullboard lanes', source: 'whoami' },+ agents: { usage: 'pullboard agents', source: 'whoami' },lane: { usage: 'pullboard lane add <name> --owns <path>[,<path>]', source: 'lane add' },status: { usage: 'pullboard status', source: 'whoami' },done: { usage: 'pullboard done <id>', source: 'submit <id>' },diff --git a/src/json.js b/src/json.jsindex d07c566c..a27742a7 100644--- a/src/json.js+++ b/src/json.js@@ -22,6 +22,7 @@ export const JSON_SHAPES = {worktree: shape({ agent: 'string', lane: 'string', route: 'string', path: 'string', branch: 'string', prompt: 'string', model: 'string', displayName: 'string' }),resume: shape({ me: 'object', all: 'array', requests: 'array', holding: 'array', sentBack: 'array', awaiting: 'array', toVerify: 'array', toMerge: 'array', open: 'array', stale: 'array', doctrineNotes: 'array', holds: 'array', unread: 'number', newest: 'array', root: 'string', newWorktreeLocation: 'string', dirty: 'number', next: 'string' }),whoami: shape({ id: 'string', lane: 'string', path: 'string', model: 'string', displayName: 'string' }),+ agents: shape({ agents: 'array' }),lanes: shape({ lanes: 'object', shared: 'array', coordinator: 'string' }),'lane add': shape({ lane: 'string', owns: 'array' }),resources: shape({ resources: 'array' }),diff --git a/test/agent-session.test.js b/test/agent-session.test.jsindex 354d6e62..0a78900f 100644--- a/test/agent-session.test.js+++ b/test/agent-session.test.js@@ -396,3 +396,49 @@ test('a session whose claims cannot be recorded is refused before it moves, neveassert.equal(box.run(box.web, ['claim', '1', '--json'], { session: 'codex-thread-secret-unrecorded-921', sessionKey: 'CODEX_THREAD_ID' }).status, 0, 'a writable ledger lets it through');assert.match(readFileSync(ledger, 'utf8'), /"move":"claim"/u);});++/** Open a helper seat from the web seat inside an agent session, returning the CLI result and the helper's Git directory. */+function openHelper(box, session, { agent = true } = {}) {+ const made = box.run(box.web, ['worktree', 'web', '--model', 'Helper Model', '--json'], { session, sessionKey: 'CODEX_THREAD_ID', agent });+ assert.equal(made.status, 0, `${made.stdout}${made.stderr}`);+ const result = JSON.parse(made.stdout);+ const gitDir = resolve(result.path, box.git(result.path, 'rev-parse', '--git-dir'));+ return { result, gitDir, file: join(gitDir, 'pullboard-parent-session.json') };+}++test('a helper seat records the agent that opened it [N2,B13]', () => {+ const box = project();+ const parent = JSON.parse(box.run(box.web, ['whoami', '--json'], { agent: false }).stdout).id;+ const session = 'codex-thread-secret-parent-800';+ const helper = openHelper(box, session);+ assert.equal(existsSync(helper.file), true, 'opening the seat inside an agent session records its parent with no flag');+ const record = JSON.parse(readFileSync(helper.file, 'utf8'));+ assert.equal(record.parent, parent, 'the record names the agent that opened the seat');+ assert.equal(record.digest, createHash('sha256').update(JSON.stringify(['CODEX_THREAD_ID', session])).digest('hex'));+ assert.equal(readFileSync(helper.file, 'utf8').includes(session), false, 'the record keeps only the session digest');+ const lone = openHelper(box, undefined, { agent: false });+ assert.equal(existsSync(lone.file), false, 'a seat a person opens has no parent');+ // The link never borrows a claim: the helper claims as itself, and the parent holds nothing.+ const claimed = box.run(helper.result.path, ['claim', '1', '--json'], { session: 'codex-thread-secret-helper-800', sessionKey: 'CODEX_THREAD_ID' });+ assert.equal(claimed.status, 0, `${claimed.stdout}${claimed.stderr}`);+ assert.equal(JSON.parse(box.run(box.web, ['show', '1', '--json'], { agent: false }).stdout).item_owner, helper.result.agent);+});++test('agents lists each agent with its helpers [N2,B13]', () => {+ const box = project();+ const parent = JSON.parse(box.run(box.web, ['whoami', '--json'], { agent: false }).stdout).id;+ const helper = openHelper(box, 'codex-thread-secret-parent-800');+ assert.equal(box.run(helper.result.path, ['claim', '1', '--json'], { session: 'codex-thread-secret-helper-800', sessionKey: 'CODEX_THREAD_ID' }).status, 0);+ const listed = box.run(box.web, ['agents', '--json'], { agent: false });+ assert.equal(listed.status, 0, `${listed.stdout}${listed.stderr}`);+ const agents = JSON.parse(listed.stdout).agents;+ const top = agents.find((agent) => agent.id === parent);+ assert.ok(top, 'the opening agent is listed');+ assert.deepEqual(top.helpers.map((agent) => agent.id), [helper.result.agent], 'its helper is listed under it');+ assert.deepEqual(top.helpers[0].holds.map((hold) => hold.item), [1], 'the helper shows what it holds');+ assert.deepEqual(top.holds, [], 'the parent holds nothing the helper claimed');+ assert.equal(agents.some((agent) => agent.id === helper.result.agent), false, 'a helper is listed only under its parent');+ const text = box.run(box.web, ['agents'], { agent: false });+ assert.equal(text.status, 0);+ assert.match(text.stdout, new RegExp(`${helper.result.agent}[^\\n]*#1`, 'u'), 'the text view shows the helper and its item');+});diff --git a/test/api-catalog.test.js b/test/api-catalog.test.jsindex 939a9ec3..0a049e73 100644--- a/test/api-catalog.test.js+++ b/test/api-catalog.test.js@@ -266,6 +266,7 @@ catalogCase('[A1] command results match the catalog across roots and subcommandsawait json(box, repo, 'hooks');await json(box, repo, 'whoami');await json(box, repo, 'lanes');+ assert.ok(Array.isArray((await json(box, repo, 'agents')).agents));await json(box, repo, 'resources');assert.equal((await json(box, repo, 'settings')).settings.gateSlots, 2);assert.equal((await json(box, repo, 'settings', ['gateSlots', '1'])).settings.gateSlots, 1);