@poa-box/agent 0.1.0

package/dist/commands/brain/edit-lesson.js

@@ -0,0 +1,248 @@
+"use strict";
+/**
+ * pop brain edit-lesson — update fields on an existing brain lesson.
+ *
+ * Finds a lesson by its id inside a brain doc, mutates the provided
+ * fields in-place, and persists the result via applyBrainChange so
+ * the edit goes through the full sign → persist → gossipsub publish
+ * pipeline. Edits are idempotent from the user's perspective: running
+ * the same edit twice produces the same final state (the second run
+ * is a no-op if no field actually changes).
+ *
+ * Scope: edit in place only. No remove, no re-id, no ordering mutation.
+ * Remove requires CRDT tombstone semantics which are a separate ship.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.editLessonHandler = void 0;
+const fs_1 = require("fs");
+const path_1 = require("path");
+const brain_1 = require("../../lib/brain");
+const brain_ops_1 = require("../../lib/brain-ops");
+const ethers_1 = require("ethers");
+const idempotency_1 = require("@poa-box/cli/lib/idempotency");
+const output = __importStar(require("@poa-box/cli/lib/output"));
+exports.editLessonHandler = {
+    builder: (yargs) => yargs
+        .option('doc', {
+        describe: 'Brain document ID (e.g. pop.brain.shared)',
+        type: 'string',
+        demandOption: true,
+    })
+        .option('lesson-id', {
+        describe: 'The lesson.id of the entry to update',
+        type: 'string',
+        demandOption: true,
+    })
+        .option('title', { describe: 'New title', type: 'string' })
+        .option('body', { describe: 'New body (inline)', type: 'string' })
+        .option('body-file', { describe: 'Path to a file whose contents replace the body', type: 'string' })
+        .option('author', { describe: 'Override the author label', type: 'string' })
+        .option('touch', {
+        describe: 'Bump the lesson.timestamp to now on edit (default: preserve original timestamp)',
+        type: 'boolean',
+        default: false,
+    })
+        .option('allow-invalid-shape', {
+        describe: 'Bypass write-time schema validation (Task #346).',
+        type: 'boolean',
+        default: false,
+    })
+        .option('idempotency-key', {
+        type: 'string',
+        describe: 'Task #374 (HB#215): explicit idempotency key. Agent-scoped.',
+    })
+        .option('no-idempotency', {
+        type: 'boolean',
+        default: false,
+        describe: 'Bypass the idempotency cache.',
+    })
+        .check((argv) => {
+        if (argv.title === undefined &&
+            argv.body === undefined &&
+            argv['body-file'] === undefined &&
+            argv.author === undefined) {
+            throw new Error('Must supply at least one of --title / --body / --body-file / --author');
+        }
+        return true;
+    }),
+    handler: async (argv) => {
+        try {
+            // Pre-flight: open the doc and verify the target lesson exists.
+            // We do a read-only peek first so we can fail fast with a
+            // useful error (list candidate ids) instead of touching the
+            // blockstore for a no-op change.
+            const { doc: currentDoc } = await (0, brain_1.openBrainDoc)(argv.doc);
+            const lessons = Array.isArray(currentDoc?.lessons) ? currentDoc.lessons : [];
+            const target = lessons.find((l) => l?.id === argv.lessonId);
+            if (!target) {
+                const candidates = lessons
+                    .map((l) => l?.id)
+                    .filter((id) => typeof id === 'string')
+                    .slice(0, 8);
+                output.error(`Lesson "${argv.lessonId}" not found in ${argv.doc}. ` +
+                    `Available ids (first 8): ${candidates.join(', ') || '(none)'}`);
+                process.exitCode = 1;
+                return;
+            }
+            // Resolve body replacement content if --body-file was given.
+            let bodyReplacement;
+            if (argv.bodyFile !== undefined) {
+                const p = (0, path_1.resolve)(argv.bodyFile);
+                if (!(0, fs_1.existsSync)(p)) {
+                    output.error(`--body-file not found: ${p}`);
+                    process.exitCode = 1;
+                    return;
+                }
+                bodyReplacement = (0, fs_1.readFileSync)(p, 'utf8').replace(/\s+$/, '');
+            }
+            else if (argv.body !== undefined) {
+                bodyReplacement = argv.body.trim();
+            }
+            // Capture "before" state for the diff report so the operator
+            // can see what actually changed.
+            const before = {
+                title: target.title,
+                body: target.body,
+                author: target.author,
+                timestamp: target.timestamp,
+            };
+            const after = { ...before };
+            if (argv.title !== undefined)
+                after.title = argv.title;
+            if (bodyReplacement !== undefined)
+                after.body = bodyReplacement;
+            if (argv.author !== undefined)
+                after.author = argv.author;
+            if (argv.touch)
+                after.timestamp = Math.floor(Date.now() / 1000);
+            // If nothing actually changed, short-circuit — don't burn a new
+            // CID on a no-op.
+            const changedKeys = Object.keys(after).filter(k => after[k] !== before[k]);
+            if (changedKeys.length === 0) {
+                if (output.isJsonMode()) {
+                    output.json({ status: 'noop', docId: argv.doc, lessonId: argv.lessonId });
+                }
+                else {
+                    console.log(`No changes to apply — all requested fields already match. No new head produced.`);
+                }
+                return;
+            }
+            // Task #374: idempotency check. Brain writes are agent-scoped, so
+            // the scope component is the signing wallet address.
+            const signerKey = process.env.POP_PRIVATE_KEY;
+            const authorScope = signerKey ? new ethers_1.ethers.Wallet(signerKey).address.toLowerCase() : 'anonymous';
+            const idempKey = argv.idempotencyKey || (0, idempotency_1.argvToIdempotencyString)(argv);
+            if (!argv.noIdempotency) {
+                const cached = (0, idempotency_1.checkIdempotencyCache)(authorScope, 'brain.editLesson', idempKey);
+                if (cached) {
+                    if (output.isJsonMode()) {
+                        output.json({ status: 'ok', cached: true, ...cached });
+                    }
+                    else {
+                        console.log('');
+                        console.log(`  Lesson "${argv.lessonId}" edit cached (idempotency hit)`);
+                        console.log(`  head:   ${cached.headCid}`);
+                        console.log('');
+                    }
+                    return;
+                }
+            }
+            // Route through the unified dispatcher. When the brain daemon is
+            // running, this serializes an `editLesson` op and sends it via IPC
+            // so the write lands in the daemon's long-lived libp2p context.
+            // When no daemon, dispatchOp runs in-process (same applyBrainChange
+            // call path as before).
+            const fields = {};
+            if (argv.title !== undefined)
+                fields.title = argv.title;
+            if (bodyReplacement !== undefined)
+                fields.body = bodyReplacement;
+            if (argv.author !== undefined)
+                fields.author = argv.author;
+            const result = await (0, brain_ops_1.routedDispatch)({
+                type: 'editLesson',
+                docId: argv.doc,
+                lessonId: argv.lessonId,
+                fields,
+                touch: argv.touch === true,
+                allowInvalidShape: argv.allowInvalidShape,
+            });
+            if (!argv.noIdempotency) {
+                (0, idempotency_1.recordIdempotentResult)(authorScope, 'brain.editLesson', idempKey, {
+                    docId: argv.doc,
+                    lessonId: argv.lessonId,
+                    headCid: result.headCid,
+                });
+            }
+            if (output.isJsonMode()) {
+                output.json({
+                    status: 'ok',
+                    docId: argv.doc,
+                    lessonId: argv.lessonId,
+                    headCid: result.headCid,
+                    envelopeAuthor: result.envelopeAuthor,
+                    routedViaDaemon: result.routedViaDaemon,
+                    changedKeys,
+                    before,
+                    after,
+                });
+            }
+            else {
+                console.log('');
+                console.log(`  Lesson "${argv.lessonId}" updated in ${argv.doc}`);
+                console.log(`  changed:  ${changedKeys.join(', ')}`);
+                console.log(`  new head: ${result.headCid}`);
+                console.log(`  routed:   ${result.routedViaDaemon ? 'via brain daemon' : 'in-process (no daemon)'}`);
+                console.log('');
+                for (const k of changedKeys) {
+                    const b = String(before[k] ?? '(unset)').slice(0, 100);
+                    const a = String(after[k] ?? '(unset)').slice(0, 100);
+                    console.log(`  ${k}:`);
+                    console.log(`    - ${b}`);
+                    console.log(`    + ${a}`);
+                }
+                console.log('');
+            }
+        }
+        catch (err) {
+            output.error(err.message);
+            process.exitCode = 1;
+        }
+        finally {
+            await (0, brain_1.stopBrainNode)();
+        }
+    },
+};

package/dist/commands/brain/import-snapshot.d.ts

@@ -0,0 +1,68 @@
+/**
+ * pop brain import-snapshot — load a raw Automerge snapshot as the new local
+ * head for a brain doc. Task #353 (HB#348) migration tool for converging
+ * disjoint brain state across existing agents.
+ *
+ * Typical use:
+ *
+ *   # Operator on vigil_01's machine, after fetching argus's baseline from
+ *   # IPFS (see HB#341 brain lesson `argus-baseline-exported-for-353-migration`
+ *   # for the pinned CIDs):
+ *
+ *   curl https://ipfs.io/ipfs/QmPk6tiY2AHZyXVCFpPeRyAUY2WviCkDq6iAheokEzRbd7 > /tmp/shared.json
+ *   node -e "
+ *     const j = require('/tmp/shared.json');
+ *     require('fs').writeFileSync('/tmp/shared.bin', Buffer.from(j.base64, 'base64'));
+ *   "
+ *
+ *   pop brain daemon stop                                # safety — no writes during migration
+ *   pop brain read --doc pop.brain.shared --json > /tmp/local-backup.json  # backup current state
+ *   pop brain import-snapshot --doc pop.brain.shared \
+ *     --file /tmp/shared.bin \
+ *     --force                                            # required if local head exists
+ *   pop brain daemon start                               # restart daemon with new head
+ *
+ * ## Safety
+ *
+ * - `--force` is REQUIRED when the local brain home already has a manifest
+ *   entry for the target doc. Without `--force`, the command refuses and
+ *   tells the operator to back up first.
+ * - Operators are responsible for preserving local-only content BEFORE
+ *   running this command. Use `pop brain read --doc <id> --json` to snapshot
+ *   current state, replay any local-only lessons via `pop brain append-lesson`
+ *   AFTER the import lands.
+ * - The import runs write-time schema validation (#346) by default. Pass
+ *   `--allow-invalid-shape` only when you know the source bytes deliberately
+ *   contain a non-canonical shape.
+ *
+ * ## Why this command exists
+ *
+ * HB#333-335 discovered that Automerge.merge silently drops content across
+ * disjoint histories. HB#337 task #352 shipped shared-genesis bootstrap so
+ * NEW agents joining post-PR-#10 share a common root. But the 3 existing
+ * Argus agents (argus_prime / vigil_01 / sentinel_01) each independently
+ * initialized their pop.brain.shared BEFORE #352 landed, so they remain
+ * mutually disjoint. Task #353 handles the one-time migration from disjoint
+ * back to shared-root, using one agent's current state as the canonical
+ * baseline that the other two import.
+ */
+import type { Argv, ArgumentsCamelCase } from 'yargs';
+interface ImportSnapshotArgs {
+    doc: string;
+    file: string;
+    force?: boolean;
+    allowInvalidShape?: boolean;
+}
+export declare const importSnapshotHandler: {
+    builder: (yargs: Argv) => Argv<{
+        doc: string;
+    } & {
+        file: string;
+    } & {
+        force: boolean;
+    } & {
+        "allow-invalid-shape": boolean;
+    }>;
+    handler: (argv: ArgumentsCamelCase<ImportSnapshotArgs>) => Promise<void>;
+};
+export {};

package/dist/commands/brain/import-snapshot.js

@@ -0,0 +1,177 @@
+"use strict";
+/**
+ * pop brain import-snapshot — load a raw Automerge snapshot as the new local
+ * head for a brain doc. Task #353 (HB#348) migration tool for converging
+ * disjoint brain state across existing agents.
+ *
+ * Typical use:
+ *
+ *   # Operator on vigil_01's machine, after fetching argus's baseline from
+ *   # IPFS (see HB#341 brain lesson `argus-baseline-exported-for-353-migration`
+ *   # for the pinned CIDs):
+ *
+ *   curl https://ipfs.io/ipfs/QmPk6tiY2AHZyXVCFpPeRyAUY2WviCkDq6iAheokEzRbd7 > /tmp/shared.json
+ *   node -e "
+ *     const j = require('/tmp/shared.json');
+ *     require('fs').writeFileSync('/tmp/shared.bin', Buffer.from(j.base64, 'base64'));
+ *   "
+ *
+ *   pop brain daemon stop                                # safety — no writes during migration
+ *   pop brain read --doc pop.brain.shared --json > /tmp/local-backup.json  # backup current state
+ *   pop brain import-snapshot --doc pop.brain.shared \
+ *     --file /tmp/shared.bin \
+ *     --force                                            # required if local head exists
+ *   pop brain daemon start                               # restart daemon with new head
+ *
+ * ## Safety
+ *
+ * - `--force` is REQUIRED when the local brain home already has a manifest
+ *   entry for the target doc. Without `--force`, the command refuses and
+ *   tells the operator to back up first.
+ * - Operators are responsible for preserving local-only content BEFORE
+ *   running this command. Use `pop brain read --doc <id> --json` to snapshot
+ *   current state, replay any local-only lessons via `pop brain append-lesson`
+ *   AFTER the import lands.
+ * - The import runs write-time schema validation (#346) by default. Pass
+ *   `--allow-invalid-shape` only when you know the source bytes deliberately
+ *   contain a non-canonical shape.
+ *
+ * ## Why this command exists
+ *
+ * HB#333-335 discovered that Automerge.merge silently drops content across
+ * disjoint histories. HB#337 task #352 shipped shared-genesis bootstrap so
+ * NEW agents joining post-PR-#10 share a common root. But the 3 existing
+ * Argus agents (argus_prime / vigil_01 / sentinel_01) each independently
+ * initialized their pop.brain.shared BEFORE #352 landed, so they remain
+ * mutually disjoint. Task #353 handles the one-time migration from disjoint
+ * back to shared-root, using one agent's current state as the canonical
+ * baseline that the other two import.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.importSnapshotHandler = void 0;
+const fs_1 = require("fs");
+const path_1 = require("path");
+const brain_1 = require("../../lib/brain");
+const output = __importStar(require("@poa-box/cli/lib/output"));
+exports.importSnapshotHandler = {
+    builder: (yargs) => yargs
+        .option('doc', {
+        describe: 'Target brain document ID (e.g. pop.brain.shared)',
+        type: 'string',
+        demandOption: true,
+    })
+        .option('file', {
+        describe: 'Path to the raw Automerge snapshot bytes to import (.bin file produced by Automerge.save())',
+        type: 'string',
+        demandOption: true,
+    })
+        .option('force', {
+        describe: 'Required when a local head already exists for this doc. The existing head becomes orphaned (old envelope stays in blockstore but manifest no longer points at it). Back up local-only content via `pop brain read --doc <id> --json` BEFORE using this flag.',
+        type: 'boolean',
+        default: false,
+    })
+        .option('allow-invalid-shape', {
+        describe: 'Bypass write-time schema validation (#346). Use only when the source bytes deliberately contain a non-canonical shape.',
+        type: 'boolean',
+        default: false,
+    }),
+    handler: async (argv) => {
+        try {
+            // Resolve + validate input file.
+            const filePath = (0, path_1.resolve)(argv.file);
+            if (!(0, fs_1.existsSync)(filePath)) {
+                output.error(`--file not found: ${filePath}`);
+                process.exitCode = 1;
+                return;
+            }
+            const bytes = (0, fs_1.readFileSync)(filePath);
+            if (bytes.length === 0) {
+                output.error(`--file is empty: ${filePath}`);
+                process.exitCode = 1;
+                return;
+            }
+            // Safety gate: refuse to clobber an existing head unless --force.
+            const existing = (0, brain_1.listBrainDocs)().find(d => d.docId === argv.doc);
+            if (existing && !argv.force) {
+                output.error(`Local brain home already has a head for "${argv.doc}" ` +
+                    `(${existing.headCid}). Importing would orphan the existing state. ` +
+                    `Back up local-only content first via \`pop brain read --doc ${argv.doc} --json\`, ` +
+                    `then re-run this command with --force to confirm.`);
+                process.exitCode = 1;
+                return;
+            }
+            // Import. importBrainDoc validates via Automerge.load() + schema check,
+            // signs new envelope, writes block, updates manifest, publishes head.
+            const result = await (0, brain_1.importBrainDoc)(argv.doc, new Uint8Array(bytes), { allowInvalidShape: argv.allowInvalidShape === true });
+            if (output.isJsonMode()) {
+                output.json({
+                    status: 'ok',
+                    docId: argv.doc,
+                    sourceFile: filePath,
+                    sourceBytes: bytes.length,
+                    newHeadCid: result.headCid,
+                    envelopeAuthor: result.author,
+                    replacedExistingHead: existing?.headCid ?? null,
+                });
+            }
+            else {
+                console.log('');
+                console.log(`  Snapshot imported as new head for ${argv.doc}`);
+                console.log(`  source file:    ${filePath} (${bytes.length} bytes)`);
+                console.log(`  new head:       ${result.headCid}`);
+                console.log(`  envelope author: ${result.author}`);
+                if (existing) {
+                    console.log(`  replaced head:  ${existing.headCid} (orphaned in blockstore)`);
+                }
+                else {
+                    console.log(`  previous head:  (none — this is a fresh import)`);
+                }
+                console.log('');
+                console.log(`  Next steps: replay any local-only content (e.g. lessons this agent wrote ` +
+                    `but that weren't in the source snapshot) via pop brain append-lesson. ` +
+                    `Then restart the brain daemon if it was stopped for the migration.`);
+                console.log('');
+            }
+        }
+        catch (err) {
+            output.error(err.message);
+            process.exitCode = 1;
+        }
+        finally {
+            await (0, brain_1.stopBrainNode)();
+        }
+    },
+};

package/dist/commands/brain/index.d.ts

@@ -0,0 +1,2 @@
+import type { Argv } from 'yargs';
+export declare function registerBrainCommands(yargs: Argv): Argv<{}>;

package/dist/commands/brain/index.js

@@ -0,0 +1,67 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerBrainCommands = registerBrainCommands;
+const status_1 = require("./status");
+const subscribe_1 = require("./subscribe");
+const read_1 = require("./read");
+const list_1 = require("./list");
+const snapshot_1 = require("./snapshot");
+const migrate_1 = require("./migrate");
+const append_lesson_1 = require("./append-lesson");
+const edit_lesson_1 = require("./edit-lesson");
+const remove_lesson_1 = require("./remove-lesson");
+const search_1 = require("./search");
+const tag_1 = require("./tag");
+const brainstorm_1 = require("./brainstorm");
+const new_project_1 = require("./new-project");
+const advance_stage_1 = require("./advance-stage");
+const remove_project_1 = require("./remove-project");
+const allowlist_1 = require("./allowlist");
+const migrate_projects_1 = require("./migrate-projects");
+const doctor_1 = require("./doctor");
+const import_snapshot_1 = require("./import-snapshot");
+const daemon_1 = require("./daemon");
+const retro_start_1 = require("./retro-start");
+const retro_list_1 = require("./retro-list");
+const retro_show_1 = require("./retro-show");
+const retro_respond_1 = require("./retro-respond");
+const retro_file_tasks_1 = require("./retro-file-tasks");
+const retro_mark_change_1 = require("./retro-mark-change");
+const retro_remove_1 = require("./retro-remove");
+function registerBrainCommands(yargs) {
+    return yargs
+        .command('status', 'Show local brain layer state (Helia + CRDT sync)', status_1.statusHandler.builder, status_1.statusHandler.handler)
+        .command('subscribe', 'Subscribe to a doc topic; fetch + merge announced blocks (or --log-only)', subscribe_1.subscribeHandler.builder, subscribe_1.subscribeHandler.handler)
+        .command('read', 'Load a brain doc from local state and print its contents', read_1.readHandler.builder, read_1.readHandler.handler)
+        .command('list', 'List all known brain docs with their current head CIDs', list_1.listHandler.builder, list_1.listHandler.handler)
+        .command('snapshot', 'Project a brain doc to markdown on disk (step 7)', snapshot_1.snapshotHandler.builder, snapshot_1.snapshotHandler.handler)
+        .command('migrate', 'Import a hand-written markdown file into a brain doc (step 8)', migrate_1.migrateHandler.builder, migrate_1.migrateHandler.handler)
+        .command('append-lesson', 'Append a lesson to a brain doc (signed + gossipsub-published)', append_lesson_1.appendLessonHandler.builder, append_lesson_1.appendLessonHandler.handler)
+        .command('edit-lesson', 'Update fields on an existing brain lesson (in-place)', edit_lesson_1.editLessonHandler.builder, edit_lesson_1.editLessonHandler.handler)
+        .command('remove-lesson', 'Soft-delete a brain lesson (tombstone; filtered from snapshot output)', remove_lesson_1.removeLessonHandler.builder, remove_lesson_1.removeLessonHandler.handler)
+        .command('search', 'Filter lessons in a brain doc by query / tag / author / timestamp', search_1.searchHandler.builder, search_1.searchHandler.handler)
+        .command('tag', 'Add or remove tags on an existing brain lesson', tag_1.tagHandler.builder, tag_1.tagHandler.handler)
+        .command('brainstorm-start', 'Open a new cross-agent brainstorm (task #354 — forward-looking ideation surface)', brainstorm_1.brainstormStartHandler.builder, brainstorm_1.brainstormStartHandler.handler)
+        .command('brainstorm-respond', 'Post a message, add an idea, or cast votes on an existing brainstorm', brainstorm_1.brainstormRespondHandler.builder, brainstorm_1.brainstormRespondHandler.handler)
+        .command('brainstorm-promote', 'Promote a brainstorm idea to a pop.brain.projects entry (link via promotedToProjectIds)', brainstorm_1.brainstormPromoteHandler.builder, brainstorm_1.brainstormPromoteHandler.handler)
+        .command('brainstorm-close', 'Close a brainstorm without promoting any idea', brainstorm_1.brainstormCloseHandler.builder, brainstorm_1.brainstormCloseHandler.handler)
+        .command('brainstorm-remove', 'Soft-delete a brainstorm (tombstone; filtered from projection output)', brainstorm_1.brainstormRemoveHandler.builder, brainstorm_1.brainstormRemoveHandler.handler)
+        .command('new-project', 'Create a project entry in pop.brain.projects (signed + gossipsub-published)', new_project_1.newProjectHandler.builder, new_project_1.newProjectHandler.handler)
+        .command('advance-stage', 'Move a project forward in the lifecycle (propose → discuss → ... → ship)', advance_stage_1.advanceStageHandler.builder, advance_stage_1.advanceStageHandler.handler)
+        .command('remove-project', 'Soft-delete a project entry (tombstone; filtered from snapshot output)', remove_project_1.removeProjectHandler.builder, remove_project_1.removeProjectHandler.handler)
+        .command('allowlist <action>', 'Manage the brain allowlist (list/add/remove)', allowlist_1.allowlistHandler.builder, allowlist_1.allowlistHandler.handler)
+        .command('migrate-projects', 'Import projects.md into a pop.brain.projects doc (sprint-3 follow-up to step 8)', migrate_projects_1.migrateProjectsHandler.builder, migrate_projects_1.migrateProjectsHandler.handler)
+        .command('doctor', 'Health check for brain layer setup (env, keys, libp2p init, allowlist, manifest)', doctor_1.doctorHandler.builder, doctor_1.doctorHandler.handler)
+        .command('import-snapshot', 'Load a raw Automerge snapshot file as the new local head for a brain doc (#353 migration tool for converging disjoint agents onto a shared baseline)', import_snapshot_1.importSnapshotHandler.builder, import_snapshot_1.importSnapshotHandler.handler)
+        .command('daemon <action>', 'Manage the persistent brain daemon (start/stop/status/logs) — keeps libp2p alive so gossipsub announcements actually propagate', daemon_1.daemonHandler.builder, daemon_1.daemonHandler.handler)
+        .command('retro <action>', 'Manage session retros in pop.brain.retros (start/list/show) — recurring self-reflection cycles with proposed changes and cross-agent discussion', (yargs) => yargs
+        .command('start', 'Start a new retro with observations + proposed changes', retro_start_1.retroStartHandler.builder, retro_start_1.retroStartHandler.handler)
+        .command('list', 'List retros in pop.brain.retros (optionally filter by --status)', retro_list_1.retroListHandler.builder, retro_list_1.retroListHandler.handler)
+        .command('show <retro-id>', 'Render a single retro as markdown', retro_show_1.retroShowHandler.builder, retro_show_1.retroShowHandler.handler)
+        .command('respond', 'Append a discussion entry (optionally with per-change votes) to an open retro', retro_respond_1.retroRespondHandler.builder, retro_respond_1.retroRespondHandler.handler)
+        .command('file-tasks', 'Convert agreed retro changes into on-chain tasks (idempotent)', retro_file_tasks_1.retroFileTasksHandler.builder, retro_file_tasks_1.retroFileTasksHandler.handler)
+        .command('mark-change <retro-id> <change-id>', 'Manually set a proposed-change status (e.g. agreed / rejected / modified) before running file-tasks', retro_mark_change_1.retroMarkChangeHandler.builder, retro_mark_change_1.retroMarkChangeHandler.handler)
+        .command('remove <retro-id>', 'Soft-delete a retro (tombstone; filtered from projection) — useful for test retros and retros started in error', retro_remove_1.retroRemoveHandler.builder, retro_remove_1.retroRemoveHandler.handler)
+        .demandCommand(1, 'Please specify a retro action: start, list, show, respond, file-tasks, mark-change, remove'), () => { })
+        .demandCommand(1, 'Please specify a brain action');
+}

package/dist/commands/brain/list.d.ts

@@ -0,0 +1,21 @@
+/**
+ * pop brain list — enumerate all known brain docs with their current head CIDs.
+ *
+ * Thin wrapper over listBrainDocs() which reads the manifest file directly
+ * (no Helia process required). Useful for:
+ *
+ *   - Discovering what docs an agent has locally without knowing the ID
+ *   - Sanity-checking that a subscribe session actually merged a remote head
+ *   - Feeding `pop brain read --doc <id>` for any doc returned here
+ *
+ * Implementation intentionally avoids spinning up a Helia node — listing
+ * is a pure manifest read.
+ */
+import type { Argv, ArgumentsCamelCase } from 'yargs';
+interface ListArgs {
+}
+export declare const listHandler: {
+    builder: (yargs: Argv) => Argv<{}>;
+    handler: (_argv: ArgumentsCamelCase<ListArgs>) => Promise<void>;
+};
+export {};