@poa-box/agent 0.1.0

package/dist/commands/brain/search.js

@@ -0,0 +1,190 @@
+"use strict";
+/**
+ * pop brain search — keyword / tag / author / HB filters over brain lesson docs.
+ *
+ * Task #347 (Retro #1 fallback #6). The pop.brain.shared / pop.brain.lessons
+ * doc has grown past the "cold read is cheap" threshold. Agents reaching for
+ * "is there a lesson about X" were grepping heartbeat-log.md as a faster
+ * proxy, which defeated the purpose of the canonical lesson substrate.
+ * This command makes lesson search cheaper than log grep.
+ *
+ * Filters compose as AND:
+ *   --query    case-insensitive substring match over title + body
+ *   --tag      exact tag match (one tag per invocation; run twice to AND)
+ *   --author   exact author match (0x lowercase)
+ *   --since    HB number: only lessons with timestamp >= the HB's wall-clock.
+ *              Heuristic — the HB number is not stored on the lesson; we
+ *              approximate by comparing the lesson timestamp against a
+ *              provided unix-seconds lower bound passed as --since-ts.
+ *
+ * Output is ranked by timestamp descending (most recent first) since that's
+ * the useful default for "what happened lately about X". JSON mode for
+ * programmatic consumption.
+ */
+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.searchHandler = void 0;
+const brain_1 = require("../../lib/brain");
+const output = __importStar(require("@poa-box/cli/lib/output"));
+function firstSentence(body) {
+    if (!body)
+        return '';
+    const trimmed = body.trim();
+    const match = trimmed.match(/^(.{1,160}?[.!?])(\s|$)/);
+    if (match)
+        return match[1];
+    // No sentence terminator in first 160 chars — take first line or 160 chars.
+    const firstLine = trimmed.split('\n')[0];
+    return firstLine.length > 160 ? firstLine.slice(0, 157) + '…' : firstLine;
+}
+exports.searchHandler = {
+    builder: (yargs) => yargs
+        .option('doc', {
+        describe: 'Brain document ID (e.g. pop.brain.shared)',
+        type: 'string',
+        demandOption: true,
+    })
+        .option('query', {
+        describe: 'Case-insensitive substring match over title + body',
+        type: 'string',
+    })
+        .option('tag', {
+        describe: 'Filter to lessons whose tags include this exact string',
+        type: 'string',
+    })
+        .option('author', {
+        describe: 'Filter to lessons by this author address (0x lowercase)',
+        type: 'string',
+    })
+        .option('since-ts', {
+        describe: 'Only lessons with timestamp >= this unix-seconds value',
+        type: 'number',
+    })
+        .option('limit', {
+        describe: 'Max number of lessons to return (default 10)',
+        type: 'number',
+        default: 10,
+    }),
+    handler: async (argv) => {
+        try {
+            const { doc: currentDoc } = await (0, brain_1.openBrainDoc)(argv.doc);
+            const lessons = Array.isArray(currentDoc?.lessons) ? currentDoc.lessons : [];
+            const queryLower = argv.query ? argv.query.toLowerCase() : null;
+            const wantTag = argv.tag ?? null;
+            const wantAuthor = argv.author ? argv.author.toLowerCase() : null;
+            const sinceTs = typeof argv.sinceTs === 'number' ? argv.sinceTs : null;
+            const matched = lessons.filter((lesson) => {
+                if (!lesson || lesson.removed === true)
+                    return false;
+                if (queryLower) {
+                    const haystack = `${lesson.title ?? ''}\n${lesson.body ?? lesson.text ?? ''}`.toLowerCase();
+                    if (!haystack.includes(queryLower))
+                        return false;
+                }
+                if (wantTag) {
+                    const tags = Array.isArray(lesson.tags) ? lesson.tags : [];
+                    if (!tags.some((t) => t === wantTag))
+                        return false;
+                }
+                if (wantAuthor) {
+                    const author = typeof lesson.author === 'string' ? lesson.author.toLowerCase() : '';
+                    if (author !== wantAuthor)
+                        return false;
+                }
+                if (sinceTs !== null) {
+                    const ts = typeof lesson.timestamp === 'number' ? lesson.timestamp : 0;
+                    if (ts < sinceTs)
+                        return false;
+                }
+                return true;
+            });
+            // Sort by timestamp descending. Non-numeric timestamps sort last.
+            matched.sort((a, b) => {
+                const ta = typeof a.timestamp === 'number' ? a.timestamp : 0;
+                const tb = typeof b.timestamp === 'number' ? b.timestamp : 0;
+                return tb - ta;
+            });
+            const limited = matched.slice(0, argv.limit ?? 10);
+            if (output.isJsonMode()) {
+                output.json({
+                    docId: argv.doc,
+                    filters: {
+                        query: argv.query ?? null,
+                        tag: argv.tag ?? null,
+                        author: argv.author ?? null,
+                        sinceTs: sinceTs,
+                    },
+                    totalMatched: matched.length,
+                    returned: limited.length,
+                    lessons: limited.map((l) => ({
+                        id: l.id ?? null,
+                        title: l.title ?? null,
+                        author: l.author ?? null,
+                        timestamp: l.timestamp ?? null,
+                        tags: Array.isArray(l.tags) ? l.tags : [],
+                        summary: firstSentence(l.body ?? l.text ?? ''),
+                    })),
+                });
+            }
+            else {
+                console.log('');
+                console.log(`  ${matched.length} matching lesson${matched.length === 1 ? '' : 's'} in ${argv.doc}` +
+                    (matched.length > limited.length ? ` (showing most recent ${limited.length})` : ''));
+                console.log('');
+                if (limited.length === 0) {
+                    console.log('  (no matches)');
+                    console.log('');
+                }
+                for (const l of limited) {
+                    const iso = typeof l.timestamp === 'number' ? new Date(l.timestamp * 1000).toISOString() : '?';
+                    const tags = Array.isArray(l.tags) && l.tags.length > 0 ? ` [${l.tags.join(', ')}]` : '';
+                    console.log(`  • ${l.title ?? l.id ?? '(no title)'}${tags}`);
+                    console.log(`    ${l.author ?? '?'} · ${iso}`);
+                    const summary = firstSentence(l.body ?? l.text ?? '');
+                    if (summary)
+                        console.log(`    ${summary}`);
+                    console.log('');
+                }
+            }
+        }
+        catch (err) {
+            output.error(err.message);
+            process.exitCode = 1;
+        }
+        finally {
+            await (0, brain_1.stopBrainNode)();
+        }
+    },
+};

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

@@ -0,0 +1,32 @@
+/**
+ * pop brain snapshot — project a brain doc to markdown and write it to
+ * agent/brain/Knowledge/<docId>.generated.md.
+ *
+ * This is the read-side counterpart to applyBrainChange. The heartbeat
+ * skill calls this at end-of-heartbeat so the projection is kept in
+ * sync on disk for human review and git archival. Step 8 of the plan
+ * is when the hand-written files are retired and this becomes the
+ * source of truth; until then, the output lives at a `.generated.md`
+ * suffix so reviewers can diff it against the hand-written original.
+ *
+ * Graceful bootstrap: if the doc has no head CID yet (manifest empty),
+ * the command exits 0 with a log line so that the heartbeat skill can
+ * call it unconditionally without blowing up on fresh agents.
+ */
+import type { Argv, ArgumentsCamelCase } from 'yargs';
+interface SnapshotArgs {
+    doc: string;
+    outputPath?: string;
+    force?: boolean;
+}
+export declare const snapshotHandler: {
+    builder: (yargs: Argv) => Argv<{
+        doc: string;
+    } & {
+        "output-path": string | undefined;
+    } & {
+        force: boolean;
+    }>;
+    handler: (argv: ArgumentsCamelCase<SnapshotArgs>) => Promise<void>;
+};
+export {};

package/dist/commands/brain/snapshot.js

@@ -0,0 +1,243 @@
+"use strict";
+/**
+ * pop brain snapshot — project a brain doc to markdown and write it to
+ * agent/brain/Knowledge/<docId>.generated.md.
+ *
+ * This is the read-side counterpart to applyBrainChange. The heartbeat
+ * skill calls this at end-of-heartbeat so the projection is kept in
+ * sync on disk for human review and git archival. Step 8 of the plan
+ * is when the hand-written files are retired and this becomes the
+ * source of truth; until then, the output lives at a `.generated.md`
+ * suffix so reviewers can diff it against the hand-written original.
+ *
+ * Graceful bootstrap: if the doc has no head CID yet (manifest empty),
+ * the command exits 0 with a log line so that the heartbeat skill can
+ * call it unconditionally without blowing up on fresh agents.
+ */
+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.snapshotHandler = void 0;
+const path_1 = require("path");
+const brain_paths_1 = require("../../lib/brain-paths");
+const fs_1 = require("fs");
+const brain_1 = require("../../lib/brain");
+const brain_projections_1 = require("../../lib/brain-projections");
+const brain_migrate_1 = require("../../lib/brain-migrate");
+const output = __importStar(require("@poa-box/cli/lib/output"));
+/**
+ * Count unique lesson ids in a rendered `.generated.md` projection.
+ *
+ * Task #359 (HB#361): this previously used `/^### /gm` which matched EVERY
+ * line starting with `### ` in the markdown, INCLUDING lines inside lesson
+ * bodies that contain `### ` as literal content. After HB#358 (#357) taught
+ * the parser to preserve H3 body content, body H3s started inflating the
+ * naive count and the regression guard reported false mismatches.
+ *
+ * The fix is in two parts:
+ *   1. For the **local projection** side of the comparison, count
+ *      `doc.lessons.filter(!removed).length` directly — the doc is in
+ *      scope, no parsing needed, no inflation possible. Done inline at
+ *      the call site.
+ *   2. For the **existing-file** side, we don't have the old doc, so we
+ *      parse the markdown structurally (via the HB#358 parser) and count
+ *      UNIQUE ids. Unique-id counting dedupes the ghost lessons produced
+ *      by one lesson's body containing `### ` at line-start: the parser
+ *      will start "new lessons" at each body H3, but those ghosts often
+ *      share slug-fallback ids with their neighbors (or with the enclosing
+ *      real lesson), so counting unique-ids compresses the inflation
+ *      back out. The count reflects the best estimate of how many
+ *      distinct-id lessons are structurally present in the file.
+ *
+ * For non-shared docs (projects, retros), the naive H3 count is still
+ * usable because their bodies don't typically contain `### ` lines —
+ * kept as a fallback.
+ */
+function countLessonsInProjectedMarkdown(md) {
+    const parsed = (0, brain_migrate_1.parseSharedMarkdown)(md, {
+        defaultAuthor: 'snapshot-regression-guard',
+        defaultTimestamp: 0,
+    });
+    const uniqueIds = new Set();
+    for (const l of parsed.lessons) {
+        if (l && typeof l.id === 'string' && l.id !== '') {
+            uniqueIds.add(l.id);
+        }
+    }
+    return uniqueIds.size;
+}
+/**
+ * Legacy H3 counter — kept as a fallback for non-shared docs (projects,
+ * retros) whose projections don't embed H3 content inside bodies. New
+ * shared-doc logic uses `countLessonsInProjectedMarkdown` instead.
+ */
+function countH3Items(md) {
+    const matches = md.match(/^### /gm);
+    return matches ? matches.length : 0;
+}
+/** Parse the "*Head CID: `...`*" line from a generated projection file. */
+function parseExistingHeadCid(md) {
+    const m = /^\*Head CID: `([^`]+)`\*/m.exec(md);
+    return m?.[1] ?? null;
+}
+exports.snapshotHandler = {
+    builder: (yargs) => yargs
+        .option('doc', {
+        describe: 'Brain document ID (e.g. pop.brain.shared)',
+        type: 'string',
+        demandOption: true,
+    })
+        .option('output-path', {
+        describe: 'Explicit output path (default: agent/brain/Knowledge/<doc>.generated.md)',
+        type: 'string',
+    })
+        .option('force', {
+        describe: 'Overwrite the existing generated.md even if it would regress (fewer lessons/projects than the file currently on disk). Use only when you know local state is authoritative.',
+        type: 'boolean',
+        default: false,
+    }),
+    handler: async (argv) => {
+        const docId = argv.doc;
+        try {
+            const { doc, headCid } = await (0, brain_1.readBrainDoc)(docId);
+            // Bootstrap case: no local head yet. Log + exit 0 so the
+            // heartbeat skill can call us unconditionally.
+            if (!headCid && (!doc || Object.keys(doc).length === 0)) {
+                if (output.isJsonMode()) {
+                    output.json({ status: 'no-op', reason: 'no local head for this doc', docId });
+                }
+                else {
+                    console.log(`pop brain snapshot: no local head for "${docId}" — nothing to project yet.`);
+                }
+                return;
+            }
+            // Dispatch to the right projector based on docId. Unknown docIds
+            // fall through to projectShared so older callers don't regress.
+            const markdown = (0, brain_projections_1.projectForDoc)(docId, doc, headCid);
+            // Default path: the repo-TRACKED brain (packages/agent/brain/Knowledge).
+            // Resolved via getRepoBrainRoot, not process.cwd() — a cwd-built path
+            // recreated the pre-split agent/ tree as untracked junk after the move.
+            const outPath = argv.outputPath ??
+                (0, path_1.join)((0, brain_paths_1.getRepoBrainRoot)(), 'Knowledge', `${docId}.generated.md`);
+            const outDir = outPath.substring(0, outPath.lastIndexOf('/'));
+            if (!(0, fs_1.existsSync)(outDir))
+                (0, fs_1.mkdirSync)(outDir, { recursive: true });
+            // Regression guard (task #328): if the existing generated.md has
+            // MORE content items (H3 headers) than our local projection, the
+            // local state is probably behind the peer-merged team state and
+            // writing would silently regress the committed file. Refuse with
+            // a clear error unless --force. The heartbeat skill calls
+            // `pop brain snapshot ... || true` so exit-1 here lets the HB
+            // continue without committing the regressed file.
+            if ((0, fs_1.existsSync)(outPath) && !argv.force) {
+                const existingContent = (0, fs_1.readFileSync)(outPath, 'utf8');
+                // Task #359 (HB#361): shared-doc regression guard uses
+                // doc-direct counting for the local side and structural unique-id
+                // parsing for the existing-file side. Naive /^### /gm counting
+                // was inflated by body-embedded `### ` lines after HB#358 taught
+                // the parser to preserve them. Other docs fall back to the naive
+                // H3 counter (their bodies don't embed H3s).
+                const isSharedDoc = docId === 'pop.brain.shared';
+                let existingCount;
+                let newCount;
+                if (isSharedDoc) {
+                    existingCount = countLessonsInProjectedMarkdown(existingContent);
+                    // Authoritative count from the in-memory doc — no parsing,
+                    // no ghost lessons from body-H3 inflation.
+                    const liveLessons = Array.isArray(doc?.lessons)
+                        ? doc.lessons.filter((l) => l?.removed !== true)
+                        : [];
+                    const liveIds = new Set();
+                    for (const l of liveLessons) {
+                        if (l && typeof l.id === 'string' && l.id !== '')
+                            liveIds.add(l.id);
+                    }
+                    newCount = liveIds.size;
+                }
+                else {
+                    existingCount = countH3Items(existingContent);
+                    newCount = countH3Items(markdown);
+                }
+                if (newCount < existingCount) {
+                    const existingCid = parseExistingHeadCid(existingContent);
+                    const msg = `pop brain snapshot would regress ${outPath}: ` +
+                        `existing file has ${existingCount} items (head ${existingCid ?? '?'}), ` +
+                        `local doc projects to ${newCount} items (head ${headCid ?? '?'}). ` +
+                        `This usually means the local state lacks peer-merged content. ` +
+                        `Run \`pop brain subscribe --doc ${docId}\` first to sync, ` +
+                        `or pass \`--force\` to overwrite anyway.`;
+                    if (output.isJsonMode()) {
+                        output.json({
+                            status: 'refused',
+                            reason: 'regression',
+                            docId,
+                            path: outPath,
+                            existingCount,
+                            newCount,
+                            existingHead: existingCid,
+                            localHead: headCid,
+                        });
+                    }
+                    else {
+                        console.error(msg);
+                    }
+                    process.exitCode = 1;
+                    return;
+                }
+            }
+            (0, fs_1.writeFileSync)(outPath, markdown);
+            if (output.isJsonMode()) {
+                output.json({
+                    status: 'ok',
+                    docId,
+                    headCid,
+                    bytes: markdown.length,
+                    path: outPath,
+                });
+            }
+            else {
+                console.log(`Wrote ${markdown.length} bytes to ${outPath}`);
+                if (headCid)
+                    console.log(`Head CID: ${headCid}`);
+            }
+        }
+        catch (err) {
+            output.error(err.message);
+            process.exitCode = 1;
+        }
+        finally {
+            await (0, brain_1.stopBrainNode)();
+        }
+    },
+};

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

@@ -0,0 +1,15 @@
+/**
+ * pop brain status — show the local brain layer state.
+ *
+ * MVP step 1: initialize a local Helia node, print the peer ID and
+ * listening addresses, report connected peer count. No CRDT ops yet;
+ * this is the "environment works" smoke test.
+ *
+ * Future steps will add doc sync status, known brain documents, and
+ * per-document sync state.
+ */
+import type { Argv, ArgumentsCamelCase } from 'yargs';
+export declare const statusHandler: {
+    builder: (yargs: Argv) => Argv<{}>;
+    handler: (_argv: ArgumentsCamelCase<{}>) => Promise<void>;
+};

package/dist/commands/brain/status.js

@@ -0,0 +1,166 @@
+"use strict";
+/**
+ * pop brain status — show the local brain layer state.
+ *
+ * MVP step 1: initialize a local Helia node, print the peer ID and
+ * listening addresses, report connected peer count. No CRDT ops yet;
+ * this is the "environment works" smoke test.
+ *
+ * Future steps will add doc sync status, known brain documents, and
+ * per-document sync state.
+ */
+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.statusHandler = void 0;
+const brain_1 = require("../../lib/brain");
+const brain_daemon_1 = require("../../lib/brain-daemon");
+const output = __importStar(require("@poa-box/cli/lib/output"));
+exports.statusHandler = {
+    builder: (yargs) => yargs,
+    handler: async (_argv) => {
+        // HB#364: when a daemon is running, query it via IPC instead of
+        // spinning up a second libp2p instance in the CLI process. The
+        // ephemeral-instance path produced misleading state (random listen
+        // port each call, 0 peers because the daemon owns the connections)
+        // and made cross-device onboarding debugging impossible. Fall back
+        // to the in-process libp2p path only when no daemon is running.
+        const daemonPid = (0, brain_daemon_1.getRunningDaemonPid)();
+        if (daemonPid !== null) {
+            try {
+                const daemonInfo = await (0, brain_daemon_1.sendIpcRequest)('status', {}, 5_000);
+                const info = {
+                    peerId: daemonInfo.peerId,
+                    peerIdSource: 'daemon',
+                    peerKeyPath: daemonInfo.brainHome + '/peer-key.json',
+                    listeningAddrs: daemonInfo.listenAddrs ?? [],
+                    connectedPeers: daemonInfo.connections ?? 0,
+                    bootstrapPeerCount: 0, // not exposed via IPC yet; pending #349 follow-up
+                    subscribedTopics: daemonInfo.topics ?? [],
+                    topicPeerCounts: {},
+                    heliaVersion: 'daemon-owned',
+                    blockstorePath: daemonInfo.brainHome + '/helia-blocks',
+                };
+                if (output.isJsonMode()) {
+                    output.json({ status: 'ok', source: 'daemon', daemonPid, ...info });
+                }
+                else {
+                    console.log('');
+                    console.log('  Brain layer — P2P CRDT substrate (daemon-owned)');
+                    console.log('  ' + '─'.repeat(60));
+                    console.log(`  Daemon PID:       ${daemonPid}`);
+                    console.log(`  Peer ID:          ${info.peerId}`);
+                    console.log(`  Connected peers:  ${info.connectedPeers}`);
+                    console.log(`  Blockstore path:  ${info.blockstorePath}`);
+                    console.log('');
+                    if (info.listeningAddrs.length > 0) {
+                        console.log('  Listening on (use for POP_BRAIN_PEERS):');
+                        for (const addr of info.listeningAddrs) {
+                            console.log(`    ${addr}`);
+                        }
+                        console.log('');
+                    }
+                    if (info.subscribedTopics.length > 0) {
+                        console.log('  Subscribed topics:');
+                        for (const t of info.subscribedTopics) {
+                            console.log(`    ${t}`);
+                        }
+                    }
+                    console.log('');
+                }
+                return;
+            }
+            catch (err) {
+                // IPC failed — fall through to in-process path and surface the
+                // daemon issue as a warning so operators see it.
+                if (!output.isJsonMode()) {
+                    console.error(`  [warn] daemon IPC at PID ${daemonPid} failed: ${err.message}`);
+                    console.error(`  [warn] falling back to in-process libp2p probe (may show stale state)`);
+                }
+            }
+        }
+        const spin = output.spinner('Initializing brain node...');
+        spin.start();
+        try {
+            const info = await (0, brain_1.getBrainNodeInfo)();
+            spin.stop();
+            if (output.isJsonMode()) {
+                output.json({
+                    status: 'ok',
+                    ...info,
+                });
+            }
+            else {
+                console.log('');
+                console.log('  Brain layer — P2P CRDT substrate');
+                console.log('  ' + '─'.repeat(60));
+                console.log(`  Helia version:    ${info.heliaVersion}`);
+                console.log(`  Peer ID:          ${info.peerId}`);
+                console.log(`  PeerId source:    ${info.peerIdSource}`);
+                console.log(`  Peer key file:    ${info.peerKeyPath}`);
+                console.log(`  Connected peers:  ${info.connectedPeers}`);
+                console.log(`  Bootstrap known:  ${info.bootstrapPeerCount}`);
+                console.log(`  Blockstore path:  ${info.blockstorePath}`);
+                console.log('');
+                if (info.listeningAddrs.length > 0) {
+                    console.log('  Listening on:');
+                    for (const addr of info.listeningAddrs) {
+                        console.log(`    ${addr}`);
+                    }
+                    console.log('');
+                }
+                if (info.subscribedTopics.length > 0) {
+                    console.log('  Subscribed topics:');
+                    for (const t of info.subscribedTopics) {
+                        const n = info.topicPeerCounts[t] ?? 0;
+                        console.log(`    ${t}  (${n} peer${n === 1 ? '' : 's'})`);
+                    }
+                }
+                else {
+                    console.log('  (no subscribed topics yet — run `pop brain subscribe --doc <id>` to listen)');
+                }
+                console.log('');
+            }
+        }
+        catch (err) {
+            spin.stop();
+            output.error(err.message);
+            process.exit(1);
+        }
+        finally {
+            // Short-lived CLI invocation — clean shutdown so the process exits.
+            await (0, brain_1.stopBrainNode)();
+        }
+    },
+};

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

@@ -0,0 +1,28 @@
+/**
+ * pop brain subscribe — keep the process alive and log incoming head-CID
+ * announcements on a doc's gossipsub topic. The manual test surface for
+ * MVP step 5.
+ *
+ * Typical 2-terminal smoke test:
+ *   Terminal A:  pop brain subscribe --doc pop.brain.shared
+ *   Terminal B:  (any write that calls applyBrainChange — step 7 ships
+ *                the write CLI; until then, a direct script or test)
+ *
+ * Terminal A logs each announcement it sees: docId, CID, claimed author
+ * (not trusted — see brain.ts#BrainHeadAnnouncement), the peer it came
+ * from. Block fetch + load is step 6.
+ */
+import type { Argv, ArgumentsCamelCase } from 'yargs';
+interface SubscribeArgs {
+    doc: string;
+    logOnly?: boolean;
+}
+export declare const subscribeHandler: {
+    builder: (yargs: Argv) => Argv<{
+        doc: string;
+    } & {
+        "log-only": boolean;
+    }>;
+    handler: (argv: ArgumentsCamelCase<SubscribeArgs>) => Promise<void>;
+};
+export {};