@poa-box/agent 0.1.0

package/dist/commands/brain/retro-mark-change.js

@@ -0,0 +1,176 @@
+"use strict";
+/**
+ * pop brain retro mark-change — manually set a proposed change's status.
+ *
+ * The retro workflow separates VOTES (discussion-level signals) from
+ * CHANGE STATUS (decision). Other agents respond via `pop brain retro
+ * respond --vote change-1=agree`, which records a vote entry in the
+ * discussion array — NOT a status change on the proposed change.
+ *
+ * When the retro author (or a designated file-tasks runner) decides a
+ * change has enough agreement, they explicitly flip its status to
+ * 'agreed' with this command. Then `pop brain retro file-tasks` picks
+ * up the change and converts it into a real on-chain task.
+ *
+ * MVP design: quorum interpretation is human-judged per the task spec
+ * (#344 "out of scope: cross-agent voting quorum logic"). This command
+ * is the escape hatch that lets operators make the call explicitly.
+ *
+ * Usage:
+ *
+ *   pop brain retro mark-change retro-327-... change-1 --status agreed
+ *   pop brain retro mark-change retro-327-... change-2 --status rejected
+ *   pop brain retro mark-change retro-327-... change-3 --status modified
+ *
+ * Status values: proposed, agreed, modified, rejected, filed.
+ * Setting status to 'filed' manually is unusual — prefer `file-tasks`,
+ * which records the filedTaskId for you. Allowed here for emergency
+ * manual reconciliation.
+ */
+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.retroMarkChangeHandler = void 0;
+const ethers_1 = require("ethers");
+const brain_1 = require("../../lib/brain");
+const brain_ops_1 = require("../../lib/brain-ops");
+const idempotency_1 = require("@poa-box/cli/lib/idempotency");
+const output = __importStar(require("@poa-box/cli/lib/output"));
+const VALID_STATUSES = [
+    'proposed', 'agreed', 'modified', 'rejected', 'filed',
+];
+exports.retroMarkChangeHandler = {
+    builder: (yargs) => yargs
+        .positional('retro-id', {
+        describe: 'The retro.id containing the change',
+        type: 'string',
+    })
+        .positional('change-id', {
+        describe: 'The proposed-change id to update',
+        type: 'string',
+    })
+        .option('doc', {
+        describe: 'Brain document ID (default: pop.brain.retros)',
+        type: 'string',
+        default: 'pop.brain.retros',
+    })
+        .option('status', {
+        describe: 'New status for the proposed change',
+        type: 'string',
+        choices: VALID_STATUSES,
+        demandOption: true,
+    })
+        .option('filed-task-id', {
+        describe: 'When --status=filed, record the on-chain task id on the change (optional)',
+        type: 'string',
+    })
+        .option('idempotency-key', { type: 'string', describe: 'Task #375 (HB#217) idempotency cache.' })
+        .option('no-idempotency', { type: 'boolean', default: false, describe: 'Bypass the idempotency cache.' })
+        .demandOption(['retro-id', 'change-id']),
+    handler: async (argv) => {
+        try {
+            if (argv.filedTaskId && argv.status !== 'filed') {
+                output.error(`--filed-task-id only makes sense with --status=filed`);
+                process.exitCode = 1;
+                return;
+            }
+            // Task #375 idempotency check, agent-scoped
+            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.retroMarkChange', idempKey);
+                if (cached) {
+                    if (output.isJsonMode())
+                        output.json({ status: 'ok', cached: true, ...cached });
+                    else
+                        console.log(`  Change "${argv.changeId}" already marked (idempotency cache hit). head: ${cached.headCid}`);
+                    return;
+                }
+            }
+            const result = await (0, brain_ops_1.routedDispatch)({
+                type: 'updateChangeStatus',
+                docId: argv.doc,
+                retroId: argv.retroId,
+                changeId: argv.changeId,
+                newStatus: argv.status,
+                filedTaskId: argv.filedTaskId,
+            });
+            if (!argv.noIdempotency) {
+                (0, idempotency_1.recordIdempotentResult)(authorScope, 'brain.retroMarkChange', idempKey, {
+                    docId: argv.doc,
+                    retroId: argv.retroId,
+                    changeId: argv.changeId,
+                    newStatus: argv.status,
+                    headCid: result.headCid,
+                });
+            }
+            if (output.isJsonMode()) {
+                output.json({
+                    status: 'ok',
+                    docId: argv.doc,
+                    retroId: argv.retroId,
+                    changeId: argv.changeId,
+                    newStatus: argv.status,
+                    filedTaskId: argv.filedTaskId ?? null,
+                    headCid: result.headCid,
+                    envelopeAuthor: result.envelopeAuthor,
+                    routedViaDaemon: result.routedViaDaemon,
+                });
+            }
+            else {
+                console.log('');
+                console.log(`  Change "${argv.changeId}" in retro "${argv.retroId}" marked as ${argv.status}`);
+                if (argv.filedTaskId) {
+                    console.log(`  filed task: #${argv.filedTaskId}`);
+                }
+                console.log(`  new head:   ${result.headCid}`);
+                console.log(`  routed:     ${result.routedViaDaemon ? 'via brain daemon' : 'in-process (no daemon)'}`);
+                console.log('');
+                if (argv.status === 'agreed') {
+                    console.log(`  Next: run "pop brain retro file-tasks --retro ${argv.retroId}" to convert ` +
+                        `this change (and any other agreed changes) into real on-chain tasks.`);
+                    console.log('');
+                }
+            }
+        }
+        catch (err) {
+            output.error(err.message);
+            process.exitCode = 1;
+        }
+        finally {
+            await (0, brain_1.stopBrainNode)();
+        }
+    },
+};

package/dist/commands/brain/retro-remove.d.ts

@@ -0,0 +1,36 @@
+/**
+ * pop brain retro remove — soft-delete a retro from pop.brain.retros.
+ *
+ * Same tombstone pattern as remove-lesson / remove-project:
+ * {removed: true, removedAt, removedBy, removedReason?}. The retro
+ * stays in the Automerge doc (for CRDT-safe merge with concurrent
+ * edits) but is filtered out of the main projection and surfaced in
+ * a compact "## Removed retros" summary.
+ *
+ * Useful for: test retros, retros that were started in error, and
+ * retros where the entire window turned out to be a no-op and there's
+ * nothing worth shipping.
+ */
+import type { Argv, ArgumentsCamelCase } from 'yargs';
+interface RetroRemoveArgs {
+    doc: string;
+    retroId: string;
+    reason?: string;
+    'idempotency-key'?: string;
+    'no-idempotency'?: boolean;
+}
+export declare const retroRemoveHandler: {
+    builder: (yargs: Argv) => Argv<import("yargs").Defined<{
+        "retro-id": string | undefined;
+    } & {
+        doc: string;
+    } & {
+        reason: string | undefined;
+    } & {
+        "idempotency-key": string | undefined;
+    } & {
+        "no-idempotency": boolean;
+    }, "retro-id">>;
+    handler: (argv: ArgumentsCamelCase<RetroRemoveArgs>) => Promise<void>;
+};
+export {};

package/dist/commands/brain/retro-remove.js

@@ -0,0 +1,142 @@
+"use strict";
+/**
+ * pop brain retro remove — soft-delete a retro from pop.brain.retros.
+ *
+ * Same tombstone pattern as remove-lesson / remove-project:
+ * {removed: true, removedAt, removedBy, removedReason?}. The retro
+ * stays in the Automerge doc (for CRDT-safe merge with concurrent
+ * edits) but is filtered out of the main projection and surfaced in
+ * a compact "## Removed retros" summary.
+ *
+ * Useful for: test retros, retros that were started in error, and
+ * retros where the entire window turned out to be a no-op and there's
+ * nothing worth shipping.
+ */
+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.retroRemoveHandler = void 0;
+const ethers_1 = require("ethers");
+const brain_1 = require("../../lib/brain");
+const brain_ops_1 = require("../../lib/brain-ops");
+const idempotency_1 = require("@poa-box/cli/lib/idempotency");
+const output = __importStar(require("@poa-box/cli/lib/output"));
+exports.retroRemoveHandler = {
+    builder: (yargs) => yargs
+        .positional('retro-id', {
+        describe: 'The retro.id to tombstone',
+        type: 'string',
+    })
+        .option('doc', {
+        describe: 'Brain document ID (default: pop.brain.retros)',
+        type: 'string',
+        default: 'pop.brain.retros',
+    })
+        .option('reason', {
+        describe: 'Optional human-readable reason recorded on the tombstone',
+        type: 'string',
+    })
+        .option('idempotency-key', { type: 'string', describe: 'Task #375 (HB#217) idempotency cache.' })
+        .option('no-idempotency', { type: 'boolean', default: false, describe: 'Bypass the idempotency cache.' })
+        .demandOption('retro-id'),
+    handler: async (argv) => {
+        try {
+            const key = process.env.POP_PRIVATE_KEY;
+            if (!key) {
+                output.error('POP_PRIVATE_KEY not set — cannot record removedBy. Set the env var and retry.');
+                process.exitCode = 1;
+                return;
+            }
+            const removerAddress = new ethers_1.ethers.Wallet(key).address.toLowerCase();
+            const now = Math.floor(Date.now() / 1000);
+            // Task #375 idempotency check
+            const idempKey = argv.idempotencyKey || (0, idempotency_1.argvToIdempotencyString)(argv);
+            if (!argv.noIdempotency) {
+                const cached = (0, idempotency_1.checkIdempotencyCache)(removerAddress, 'brain.retroRemove', idempKey);
+                if (cached) {
+                    if (output.isJsonMode())
+                        output.json({ status: 'ok', cached: true, ...cached });
+                    else
+                        console.log(`  Retro "${argv.retroId}" already removed (idempotency cache hit). head: ${cached.headCid}`);
+                    return;
+                }
+            }
+            const result = await (0, brain_ops_1.routedDispatch)({
+                type: 'removeRetro',
+                docId: argv.doc,
+                retroId: argv.retroId,
+                removedBy: removerAddress,
+                removedAt: now,
+                removedReason: argv.reason,
+            });
+            if (!argv.noIdempotency) {
+                (0, idempotency_1.recordIdempotentResult)(removerAddress, 'brain.retroRemove', idempKey, {
+                    docId: argv.doc,
+                    retroId: argv.retroId,
+                    headCid: result.headCid,
+                });
+            }
+            if (output.isJsonMode()) {
+                output.json({
+                    status: 'ok',
+                    docId: argv.doc,
+                    retroId: argv.retroId,
+                    removedAt: now,
+                    removedBy: removerAddress,
+                    removedReason: argv.reason ?? null,
+                    headCid: result.headCid,
+                    routedViaDaemon: result.routedViaDaemon,
+                });
+            }
+            else {
+                console.log('');
+                console.log(`  Retro "${argv.retroId}" tombstoned in ${argv.doc}`);
+                console.log(`  removedBy: ${removerAddress}`);
+                console.log(`  removedAt: ${new Date(now * 1000).toISOString()}`);
+                if (argv.reason)
+                    console.log(`  reason:    ${argv.reason}`);
+                console.log(`  new head:  ${result.headCid}`);
+                console.log(`  routed:    ${result.routedViaDaemon ? 'via brain daemon' : 'in-process (no daemon)'}`);
+                console.log('');
+            }
+        }
+        catch (err) {
+            output.error(err.message);
+            process.exitCode = 1;
+        }
+        finally {
+            await (0, brain_1.stopBrainNode)();
+        }
+    },
+};

package/dist/commands/brain/retro-respond.d.ts

@@ -0,0 +1,56 @@
+/**
+ * pop brain retro respond — append a discussion entry to an existing retro.
+ *
+ * Usage:
+ *
+ *   pop brain retro respond --to retro-327-1776... \
+ *     --message "Change 1 makes sense. Change 2 needs more research on Diamond ABI extraction."
+ *
+ *   # With per-change votes:
+ *   pop brain retro respond --to retro-327-1776... \
+ *     --message "..." \
+ *     --vote change-1=agree,change-2=modify
+ *
+ * The response lands in the retro's `discussion` array. The first
+ * response on an open retro auto-advances status from 'open' to
+ * 'discussed' (enforced by the respondToRetro op inside dispatchOp).
+ *
+ * Vote validation: vote change-ids must refer to real proposedChanges
+ * on the retro. Typos / unknown change-ids fail fast with a list of
+ * available change-ids in the error message.
+ */
+import type { Argv, ArgumentsCamelCase } from 'yargs';
+interface RetroRespondArgs {
+    doc: string;
+    to: string;
+    message?: string;
+    messageFile?: string;
+    vote?: string;
+    author?: string;
+    hb?: number;
+    'idempotency-key'?: string;
+    'no-idempotency'?: boolean;
+}
+export declare const retroRespondHandler: {
+    builder: (yargs: Argv) => Argv<{
+        doc: string;
+    } & {
+        to: string;
+    } & {
+        message: string | undefined;
+    } & {
+        "message-file": string | undefined;
+    } & {
+        vote: string | undefined;
+    } & {
+        author: string | undefined;
+    } & {
+        hb: number | undefined;
+    } & {
+        "idempotency-key": string | undefined;
+    } & {
+        "no-idempotency": boolean;
+    }>;
+    handler: (argv: ArgumentsCamelCase<RetroRespondArgs>) => Promise<void>;
+};
+export {};

package/dist/commands/brain/retro-respond.js

@@ -0,0 +1,250 @@
+"use strict";
+/**
+ * pop brain retro respond — append a discussion entry to an existing retro.
+ *
+ * Usage:
+ *
+ *   pop brain retro respond --to retro-327-1776... \
+ *     --message "Change 1 makes sense. Change 2 needs more research on Diamond ABI extraction."
+ *
+ *   # With per-change votes:
+ *   pop brain retro respond --to retro-327-1776... \
+ *     --message "..." \
+ *     --vote change-1=agree,change-2=modify
+ *
+ * The response lands in the retro's `discussion` array. The first
+ * response on an open retro auto-advances status from 'open' to
+ * 'discussed' (enforced by the respondToRetro op inside dispatchOp).
+ *
+ * Vote validation: vote change-ids must refer to real proposedChanges
+ * on the retro. Typos / unknown change-ids fail fast with a list of
+ * available change-ids in the error message.
+ */
+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.retroRespondHandler = void 0;
+const fs_1 = require("fs");
+const path_1 = require("path");
+const ethers_1 = require("ethers");
+const brain_1 = require("../../lib/brain");
+const brain_ops_1 = require("../../lib/brain-ops");
+const idempotency_1 = require("@poa-box/cli/lib/idempotency");
+const output = __importStar(require("@poa-box/cli/lib/output"));
+const VALID_VOTES = ['agree', 'modify', 'reject'];
+/**
+ * Parse the --vote flag value. Expected shape is a comma-separated
+ * list of `change-id=vote` pairs, e.g. `change-1=agree,change-2=modify`.
+ * Returns a map of {changeId: vote}, or throws on a bad value.
+ */
+function parseVoteFlag(raw) {
+    const result = {};
+    const pairs = raw.split(',').map(s => s.trim()).filter(Boolean);
+    for (const pair of pairs) {
+        const eq = pair.indexOf('=');
+        if (eq < 0) {
+            throw new Error(`--vote pair "${pair}" must be in "change-id=vote" format`);
+        }
+        const changeId = pair.slice(0, eq).trim();
+        const voteRaw = pair.slice(eq + 1).trim().toLowerCase();
+        if (!changeId) {
+            throw new Error(`--vote pair "${pair}" has empty change-id`);
+        }
+        if (!VALID_VOTES.includes(voteRaw)) {
+            throw new Error(`--vote pair "${pair}" has invalid vote "${voteRaw}" — must be one of: ${VALID_VOTES.join(', ')}`);
+        }
+        result[changeId] = voteRaw;
+    }
+    return result;
+}
+exports.retroRespondHandler = {
+    builder: (yargs) => yargs
+        .option('doc', {
+        describe: 'Brain document ID (default: pop.brain.retros)',
+        type: 'string',
+        default: 'pop.brain.retros',
+    })
+        .option('to', {
+        describe: 'The retro.id to respond to',
+        type: 'string',
+        demandOption: true,
+    })
+        .option('message', {
+        describe: 'The response message (inline). Use --message-file for long content.',
+        type: 'string',
+    })
+        .option('message-file', {
+        describe: 'Path to a file whose contents are the response message',
+        type: 'string',
+    })
+        .option('vote', {
+        describe: 'Per-change votes as "change-id=vote,change-id=vote" (votes: agree, modify, reject). Example: change-1=agree,change-2=modify',
+        type: 'string',
+    })
+        .option('author', {
+        describe: 'Override the author label (default: signing wallet address)',
+        type: 'string',
+    })
+        .option('hb', {
+        describe: 'Heartbeat number at response time (optional metadata)',
+        type: 'number',
+    })
+        .option('idempotency-key', { type: 'string', describe: 'Task #375 (HB#217) idempotency cache.' })
+        .option('no-idempotency', { type: 'boolean', default: false, describe: 'Bypass the idempotency cache.' })
+        .check((argv) => {
+        if (!argv.message && !argv['message-file']) {
+            throw new Error('Must supply --message or --message-file');
+        }
+        return true;
+    }),
+    handler: async (argv) => {
+        try {
+            // Resolve message content.
+            let message;
+            if (argv.messageFile) {
+                const p = (0, path_1.resolve)(argv.messageFile);
+                if (!(0, fs_1.existsSync)(p)) {
+                    output.error(`--message-file not found: ${p}`);
+                    process.exitCode = 1;
+                    return;
+                }
+                message = (0, fs_1.readFileSync)(p, 'utf8').trim();
+            }
+            else {
+                message = (argv.message ?? '').trim();
+            }
+            if (!message) {
+                output.error('Response message is empty.');
+                process.exitCode = 1;
+                return;
+            }
+            // Resolve author.
+            let authorLabel;
+            if (argv.author) {
+                authorLabel = argv.author;
+            }
+            else {
+                const key = process.env.POP_PRIVATE_KEY;
+                if (!key) {
+                    output.error('POP_PRIVATE_KEY not set — cannot derive default author. Pass --author explicitly.');
+                    process.exitCode = 1;
+                    return;
+                }
+                authorLabel = new ethers_1.ethers.Wallet(key).address.toLowerCase();
+            }
+            // Parse votes if provided.
+            let votePerChange;
+            if (argv.vote) {
+                try {
+                    votePerChange = parseVoteFlag(argv.vote);
+                }
+                catch (err) {
+                    output.error(err.message);
+                    process.exitCode = 1;
+                    return;
+                }
+            }
+            const now = Math.floor(Date.now() / 1000);
+            // Task #375 idempotency check, agent-scoped
+            const idempKey = argv.idempotencyKey || (0, idempotency_1.argvToIdempotencyString)(argv);
+            if (!argv.noIdempotency) {
+                const cached = (0, idempotency_1.checkIdempotencyCache)(authorLabel, 'brain.retroRespond', idempKey);
+                if (cached) {
+                    if (output.isJsonMode())
+                        output.json({ status: 'ok', cached: true, ...cached });
+                    else
+                        console.log(`  Retro response already recorded (idempotency cache hit). head: ${cached.headCid}`);
+                    return;
+                }
+            }
+            const result = await (0, brain_ops_1.routedDispatch)({
+                type: 'respondToRetro',
+                docId: argv.doc,
+                retroId: argv.to,
+                author: authorLabel,
+                hb: argv.hb,
+                message,
+                votePerChange,
+                timestamp: now,
+            });
+            if (!argv.noIdempotency) {
+                (0, idempotency_1.recordIdempotentResult)(authorLabel, 'brain.retroRespond', idempKey, {
+                    docId: argv.doc,
+                    retroId: argv.to,
+                    headCid: result.headCid,
+                });
+            }
+            if (output.isJsonMode()) {
+                output.json({
+                    status: 'ok',
+                    docId: argv.doc,
+                    retroId: argv.to,
+                    author: authorLabel,
+                    hb: argv.hb ?? null,
+                    votes: votePerChange ?? null,
+                    headCid: result.headCid,
+                    envelopeAuthor: result.envelopeAuthor,
+                    routedViaDaemon: result.routedViaDaemon,
+                });
+            }
+            else {
+                console.log('');
+                console.log(`  Response appended to retro "${argv.to}"`);
+                console.log(`  author:    ${authorLabel}`);
+                if (argv.hb !== undefined)
+                    console.log(`  hb:        #${argv.hb}`);
+                if (votePerChange) {
+                    console.log(`  votes:`);
+                    for (const [changeId, vote] of Object.entries(votePerChange)) {
+                        console.log(`    - ${changeId}: ${vote}`);
+                    }
+                }
+                console.log(`  new head:  ${result.headCid}`);
+                console.log(`  routed:    ${result.routedViaDaemon ? 'via brain daemon' : 'in-process (no daemon)'}`);
+                console.log('');
+                console.log(`  The retro's status advances from 'open' to 'discussed' on the first ` +
+                    `response. When proposed changes are agreed, run "pop brain retro file-tasks ` +
+                    `--retro ${argv.to}" to convert them to on-chain tasks.`);
+                console.log('');
+            }
+        }
+        catch (err) {
+            output.error(err.message);
+            process.exitCode = 1;
+        }
+        finally {
+            await (0, brain_1.stopBrainNode)();
+        }
+    },
+};

package/dist/commands/brain/retro-show.d.ts

@@ -0,0 +1,23 @@
+/**
+ * pop brain retro show — render a single retro as markdown.
+ *
+ * Loads the retro doc, extracts the requested retro, and runs it
+ * through the projection layer. Same shape + schema as projectRetros
+ * produces for the full doc snapshot, but scoped to one entry.
+ *
+ * Pure read path — no daemon routing required.
+ */
+import type { Argv, ArgumentsCamelCase } from 'yargs';
+interface RetroShowArgs {
+    retroId: string;
+    doc: string;
+}
+export declare const retroShowHandler: {
+    builder: (yargs: Argv) => Argv<import("yargs").Defined<{
+        "retro-id": string | undefined;
+    } & {
+        doc: string;
+    }, "retro-id">>;
+    handler: (argv: ArgumentsCamelCase<RetroShowArgs>) => Promise<void>;
+};
+export {};