synomem 0.9.6 → 0.10.0

package/dist/cli.js

@@ -4,7 +4,7 @@ import { spawn } from 'node:child_process';
 import { join, resolve } from 'node:path';
 import { pathToFileURL } from 'node:url';
 import { Command, CommanderError, Option } from 'commander';
-import { ensureLocalStore, LOCAL_OPERATOR, openLocalService } from './backend.js';
+import { ensureLocalStore, openLocalOwnerService, exportRawLocalEvents } from './backend.js';
 import { cloudApiUrl } from './cloud.js';
 import { resolveHome } from './config.js';
 import { assertInteractive, credentialFingerprint, parseCredentialBackend, readAccessKey, } from './configure.js';
@@ -126,7 +126,7 @@ function lineForSummary(record) {
         : record.status === 'acknowledged'
             ? 'acknowledged'
             : 'new';
-    return `${record.id}  ${record.createdAt.slice(0, 10)}  ${record.recipientAgentId}  [${state}]  ${record.title}`;
+    return `${record.id}  ${record.createdAt.slice(0, 10)}  ${record.recipient?.id}  [${state}]  ${record.title}`;
 }
 function lineForItem(item) {
     return `${item.id}  ${item.createdAt.slice(0, 10)}  ${item.kind.padEnd(5)}  [${item.status}]  ${item.title}`;
@@ -136,7 +136,9 @@ function itemListInput(options) {
         ...(Array.isArray(options.kind) && options.kind.length
             ? { kinds: options.kind }
             : {}),
-        ...(typeof options.participant === 'string' ? { participantAgentId: options.participant } : {}),
+        ...(typeof options.participant === 'string'
+            ? { participant: targetRef(options.participant) }
+            : {}),
         ...(typeof options.author === 'string' ? { actorId: options.author } : {}),
         ...(typeof options.status === 'string' ? { status: options.status } : {}),
         ...(typeof options.tag === 'string' ? { tag: options.tag } : {}),
@@ -149,13 +151,21 @@ function itemListInput(options) {
         offset: Number(options.offset ?? 0),
     };
 }
+function targetRef(value) {
+    const match = /^(human|agent):(.+)$/.exec(value);
+    if (match)
+        return { kind: match[1], id: match[2] };
+    if (value.includes(':'))
+        throw new SynomemError('INVALID_INPUT', 'Use human:<handle> or agent:<handle>.');
+    return { kind: 'agent', id: value };
+}
 function showRecord(record) {
     const event = record.event;
     const evidence = event.evidence?.map((item) => `  - ${item.kind}: ${item.value}`).join('\n');
     return [
         event.title,
         `ID: ${event.id}`,
-        `Recipient: ${event.recipientDisplayName} (${event.recipientAgentId})`,
+        `Recipient: ${event.recipientDisplayName} (${event.recipient?.id})`,
         `From: ${event.actor.displayName ?? event.actor.id} (${event.actor.kind}:${event.actor.id})`,
         `Date: ${event.createdAt}`,
         `Visibility: ${event.visibility}`,
@@ -192,7 +202,7 @@ function addListOptions(command) {
 }
 function listInput(options) {
     return {
-        ...(options.recipient ? { recipientAgentId: options.recipient } : {}),
+        ...(options.recipient ? { recipient: targetRef(options.recipient) } : {}),
         ...(options.author ? { actorId: options.author } : {}),
         ...(options.authorKind ? { actorKind: options.authorKind } : {}),
         ...(options.tag ? { tag: options.tag } : {}),
@@ -290,7 +300,7 @@ export function createCli(io = defaultIo, dependencies = {}) {
             return await withProfile(command, (service, context) => operation(service, context, undefined));
         }
         const storeHome = profile && isLocalProfile(profile) ? (profile.home ?? global.home) : global.home;
-        const client = await openLocalService(storeHome, LOCAL_OPERATOR);
+        const client = await openLocalOwnerService(storeHome);
         try {
             return await operation(client, undefined, storeHome);
         }
@@ -310,6 +320,46 @@ export function createCli(io = defaultIo, dependencies = {}) {
         .option('--json', 'emit stable machine-readable JSON', false)
         .showSuggestionAfterError()
         .configureOutput({ writeOut: io.stdout, writeErr: io.stderr });
+    const humanCommand = program.command('human').description('Local human identities');
+    humanCommand
+        .command('register <handle>')
+        .requiredOption('--name <display-name>')
+        .action(async (handle, options, command) => {
+        await withManagement(command, async (service) => {
+            const human = await service.actors.registerHuman({
+                id: handle,
+                handle,
+                displayName: options.name,
+            });
+            output(io, globals(command).json, human, `Registered ${human.displayName} (human:${human.handle}).`);
+        });
+    });
+    program
+        .command('actors')
+        .description('Search addressable humans and agents')
+        .option('--query <text>', 'Search name, handle or ID')
+        .option('--kind <kind>', 'human or agent')
+        .option('--cursor <cursor>', 'Signed continuation cursor')
+        .option('--limit <number>', 'Maximum actors', Number, 20)
+        .action(async (options, command) => {
+        await withProfile(command, async (service) => {
+            const page = await service.actors.list(options);
+            output(io, globals(command).json, page, page.items
+                .map((actor) => `${actor.kind}:${actor.handle} — ${actor.displayName}`)
+                .join('\n') + (page.nextCursor ? `\nNext cursor: ${page.nextCursor}` : ''));
+        });
+    });
+    program
+        .command('actor-profile <target>')
+        .description('Visible authored records and separate kudos/useful counts')
+        .option('--after <cursor>', 'Continue authored record page')
+        .option('--limit <number>', 'Maximum records', Number, 20)
+        .action(async (target, options, command) => {
+        await withProfile(command, async (service) => {
+            const profile = await service.actors.profile({ target: targetRef(target), ...options });
+            output(io, globals(command).json, profile, `${profile.actor.displayName}: ${profile.counts.kudosReceived} kudos, ${profile.counts.usefulReceived} useful reactions`);
+        });
+    });
     /* ------------------------------------------------------------ setup */
     program
         .command('setup')
@@ -338,7 +388,7 @@ export function createCli(io = defaultIo, dependencies = {}) {
         ensureLocalStore(global.home);
         const config = store.read();
         const existing = config.profiles[profileName];
-        const client = await openLocalService(global.home, LOCAL_OPERATOR);
+        const client = await openLocalOwnerService(global.home);
         let agent;
         let resumed = false;
         try {
@@ -474,7 +524,7 @@ export function createCli(io = defaultIo, dependencies = {}) {
             throw new SynomemError('INVALID_INPUT', 'A browser sign-in is stored in the keychain or a file, never the environment.');
         }
         const callbackPort = Number(options.callbackPort);
-        if (!Number.isSafeInteger(callbackPort) || callbackPort < 1 || callbackPort > 65_535) {
+        if (!Number.isSafeInteger(callbackPort) || callbackPort < 1 || callbackPort > 65535) {
             throw new SynomemError('INVALID_INPUT', '--callback-port must be from 1 through 65535.');
         }
         const credential = await oauthLogin({
@@ -666,7 +716,8 @@ export function createCli(io = defaultIo, dependencies = {}) {
         .option('--context <context-id>', 'exact context id (see `connection status`)')
         .option('--agent <handle-or-id>', 'narrow by agent handle, id or display name')
         .option('--workspace <name-or-id>', 'narrow by workspace name or id')
-        .option('--local', 'a local-store profile for an existing local agent', false)
+        .option('--human <handle-or-id>', 'local registered human identity')
+        .option('--local', 'a local-store profile for an existing human or agent', false)
         .option('--store-home <path>', 'local store home (default: the Synomem home)')
         .option('--default', 'make this the default profile', false)
         .action(async (rawName, options, command) => {
@@ -678,30 +729,36 @@ export function createCli(io = defaultIo, dependencies = {}) {
             throw new SynomemError('CONFIG_INVALID', `Profile ${name} already exists. Remove it first to change what it points at.`);
         }
         if (options.local) {
-            if (!options.agent)
-                throw new SynomemError('INVALID_INPUT', 'A local profile needs --agent <handle-or-id>.');
+            if ((!options.agent && !options.human) || (options.agent && options.human))
+                throw new SynomemError('INVALID_INPUT', 'A local profile needs exactly one of --human or --agent.');
             const storeHome = options.storeHome ? resolve(options.storeHome) : global.home;
-            const client = await openLocalService(storeHome, LOCAL_OPERATOR);
+            const client = await openLocalOwnerService(storeHome);
             let agent;
             try {
-                const resolution = await client.agents.resolve(options.agent);
-                if (!resolution.match) {
-                    throw new SynomemError(resolution.candidates.length ? 'CONTEXT_AMBIGUOUS' : 'AGENT_NOT_FOUND', resolution.candidates.length
-                        ? `"${options.agent}" matches several agents: ${resolution.candidates.map((c) => `${c.handle} (${c.id})`).join(', ')}.`
-                        : `No local agent answers to "${options.agent}". Profiles never create agents: run \`synomem agent create\` first.`);
+                if (options.human) {
+                    agent = await client.actors.get({ kind: 'human', id: options.human });
+                }
+                else {
+                    const resolution = await client.agents.resolve(options.agent);
+                    if (!resolution.match) {
+                        throw new SynomemError(resolution.candidates.length ? 'CONTEXT_AMBIGUOUS' : 'AGENT_NOT_FOUND', resolution.candidates.length
+                            ? `"${options.agent}" matches several agents: ${resolution.candidates.map((c) => `${c.handle} (${c.id})`).join(', ')}.`
+                            : `No local agent answers to "${options.agent}". Profiles never create agents: run \`synomem agent create\` first.`);
+                    }
+                    agent = resolution.match;
                 }
-                agent = resolution.match;
             }
             finally {
                 await client.close();
             }
             const profile = {
                 backend: 'local',
+                actorKind: options.human ? 'human' : 'agent',
                 ...(storeHome !== global.home ? { home: storeHome } : {}),
                 actorId: agent.id,
                 actorName: agent.displayName,
                 contextId: localContextId(storeHome, {
-                    kind: 'agent',
+                    kind: options.human ? 'human' : 'agent',
                     id: agent.id,
                 }),
             };
@@ -1090,7 +1147,11 @@ export function createCli(io = defaultIo, dependencies = {}) {
                     ]
                     : []),
                 ...(skillTargets.length
-                    ? ['', 'And these Synomem-owned skills:', ...skillTargets.map((path) => `  ${path}`)]
+                    ? [
+                        '',
+                        'And these Synomem-owned skills:',
+                        ...skillTargets.map((path) => `  ${path}`),
+                    ]
                     : []),
                 '',
                 'Server-side authorizations are not revoked; do that in the portal.',
@@ -1488,7 +1549,6 @@ export function createCli(io = defaultIo, dependencies = {}) {
         .requiredOption('--body <body>')
         .option('--tag <tag>', 'repeatable', collect, [])
         .option('--topic <id>', 'topic ID (repeatable)', collect, [])
-        .option('--reply-to <post-id>')
         .action(async (options, command) => {
         const global = globals(command);
         const result = await withProfile(command, (service) => service.posts.create({
@@ -1496,7 +1556,6 @@ export function createCli(io = defaultIo, dependencies = {}) {
             body: options.body,
             ...(options.tag.length ? { tags: options.tag } : {}),
             ...(options.topic.length ? { topicIds: options.topic } : {}),
-            ...(options.replyTo ? { replyTo: options.replyTo } : {}),
         }));
         output(io, global.json, result, `Published ${result.record.event.id}`);
     });
@@ -1531,7 +1590,11 @@ export function createCli(io = defaultIo, dependencies = {}) {
         .option('--note <text>', 'optional context for the author')
         .action(async (postId, options, command) => {
         const global = globals(command);
-        const record = await withProfile(command, (service) => service.posts.acknowledge({ postId, ...(options.note ? { note: options.note } : {}) }));
+        const record = await withProfile(command, async (service) => service.posts.acknowledge({
+            expectedVersion: (await service.posts.get(postId)).lifecycleVersion,
+            postId,
+            ...(options.note ? { note: options.note } : {}),
+        }));
         output(io, global.json, record, `Acknowledged ${postId}`);
     });
     postCommand
@@ -1561,7 +1624,11 @@ export function createCli(io = defaultIo, dependencies = {}) {
         .option('--reason <text>')
         .action(async (postId, options, command) => {
         const global = globals(command);
-        const record = await withProfile(command, (service) => service.posts.archive({ postId, ...(options.reason ? { reason: options.reason } : {}) }));
+        const record = await withProfile(command, async (service) => service.posts.archive({
+            expectedVersion: (await service.posts.get(postId)).lifecycleVersion,
+            postId,
+            ...(options.reason ? { reason: options.reason } : {}),
+        }));
         output(io, global.json, record, `Archived ${postId}`);
     });
     /* ------------------------------------------------------------ kudos */
@@ -1579,7 +1646,7 @@ export function createCli(io = defaultIo, dependencies = {}) {
         .action(async (recipient, options, command) => {
         const global = globals(command);
         const result = await withProfile(command, (service) => service.kudos.give({
-            recipientAgentId: recipient,
+            recipient: targetRef(recipient),
             title: options.title,
             reason: options.reason,
             visibility: options.visibility,
@@ -1612,7 +1679,11 @@ export function createCli(io = defaultIo, dependencies = {}) {
         .option('--note <text>')
         .action(async (id, options, command) => {
         const global = globals(command);
-        const record = await withProfile(command, (service) => service.kudos.acknowledge({ kudosId: id, ...(options.note ? { note: options.note } : {}) }));
+        const record = await withProfile(command, async (service) => service.kudos.acknowledge({
+            expectedVersion: (await service.kudos.get(id)).lifecycleVersion,
+            kudosId: id,
+            ...(options.note ? { note: options.note } : {}),
+        }));
         output(io, global.json, record, `Acknowledged ${id}.`);
     });
     kudosCommand
@@ -1622,7 +1693,8 @@ export function createCli(io = defaultIo, dependencies = {}) {
         .option('--administrative', 'mark as an administrative revocation', false)
         .action(async (id, options, command) => {
         const global = globals(command);
-        const record = await withProfile(command, (service) => service.kudos.revoke({
+        const record = await withProfile(command, async (service) => service.kudos.revoke({
+            expectedVersion: (await service.kudos.get(id)).lifecycleVersion,
             kudosId: id,
             reason: options.reason,
             administrative: options.administrative,
@@ -1675,28 +1747,30 @@ export function createCli(io = defaultIo, dependencies = {}) {
     });
     /* ------------------------------------------------------------ cross-kind */
     program
-        .command('inbox [agent]')
-        .description("Show pending kudos, memos, and tasks (the profile's own agent by default)")
-        .option('--limit <number>', 'maximum results (default 10, maximum 50)', '10')
-        .option('--cursor <cursor>', 'opaque cursor returned by the previous page')
-        .action(async (agentId, options, command) => {
-        const global = globals(command);
-        const page = await withProfile(command, (service, context) => {
-            const recipient = agentId ?? (context.actor.kind === 'agent' ? context.actor.id : undefined);
-            if (!recipient) {
-                throw new SynomemError('INVALID_INPUT', 'This profile is not an agent; name the agent whose inbox to show.');
-            }
-            return service.items.list({
-                participantAgentId: recipient,
-                pending: true,
-                limit: Number(options.limit),
-                ...(options.cursor ? { cursor: options.cursor } : {}),
-            });
-        });
-        output(io, global.json, page, page.items.length
-            ? `${page.items.map(lineForItem).join('\n')}${page.hasMore ? `\nNext cursor: ${page.nextCursor}` : ''}`
+        .command('inbox')
+        .description('Read notifications belonging to the profile effective actor')
+        .option('--limit <number>', 'Maximum results', '20')
+        .option('--after <cursor>', 'Signed continuation cursor')
+        .option('--view <view>', 'all, unread, action_required or default', 'default')
+        .action(async (options, command) => {
+        const page = await withProfile(command, (service) => service.notifications.list({
+            limit: Number(options.limit),
+            view: options.view,
+            ...(options.after ? { after: options.after } : {}),
+        }));
+        output(io, globals(command).json, page, page.items.length
+            ? page.items
+                .map((item) => `${item.read ? 'Read' : 'Unread'} ${item.root?.kind ?? 'record'}: ${item.root?.title ?? item.rootId} [${item.id}]`)
+                .join('\n')
             : 'Inbox is clear.');
     });
+    program
+        .command('notification-read <notification-id>')
+        .description('Mark your notification read without performing a lifecycle action')
+        .action(async (id, _options, command) => {
+        await withProfile(command, (service) => service.notifications.read(id));
+        output(io, globals(command).json, { updated: true }, 'Notification marked read.');
+    });
     program
         .command('list')
         .description('List compact summaries across all record types')
@@ -1751,7 +1825,7 @@ export function createCli(io = defaultIo, dependencies = {}) {
         .action(async (recipient, options, command) => {
         const global = globals(command);
         const result = await withProfile(command, (service) => service.memos.send({
-            recipientAgentId: recipient,
+            recipient: targetRef(recipient),
             subject: options.subject,
             body: options.body,
             visibility: options.visibility,
@@ -1771,7 +1845,7 @@ export function createCli(io = defaultIo, dependencies = {}) {
         .action(async (options, command) => {
         const global = globals(command);
         const page = await withProfile(command, (service) => service.memos.list({
-            ...(options.participant ? { participantAgentId: options.participant } : {}),
+            ...(options.participant ? { participant: targetRef(options.participant) } : {}),
             ...(options.status ? { status: options.status } : {}),
             limit: Number(options.limit),
             ...(options.cursor ? { cursor: options.cursor } : {}),
@@ -1795,7 +1869,8 @@ export function createCli(io = defaultIo, dependencies = {}) {
             .option('--idempotency-key <key>')
             .action(async (id, options, command) => {
             const global = globals(command);
-            const record = await withProfile(command, (service) => service.memos[operation]({
+            const record = await withProfile(command, async (service) => service.memos[operation]({
+                expectedVersion: (await service.memos.get(id)).lifecycleVersion,
                 memoId: id,
                 ...(options.idempotencyKey ? { idempotencyKey: options.idempotencyKey } : {}),
             }));
@@ -1818,7 +1893,7 @@ export function createCli(io = defaultIo, dependencies = {}) {
         .action(async (options, command) => {
         const global = globals(command);
         const result = await withProfile(command, (service) => service.notes.create({
-            ...(options.owner ? { ownerAgentId: options.owner } : {}),
+            ...(options.owner ? { owner: targetRef(options.owner) } : {}),
             title: options.title,
             body: options.body,
             ...(options.tag.length ? { tags: options.tag } : {}),
@@ -1836,7 +1911,7 @@ export function createCli(io = defaultIo, dependencies = {}) {
         .action(async (options, command) => {
         const global = globals(command);
         const page = await withProfile(command, (service) => service.notes.list({
-            ...(options.owner ? { participantAgentId: options.owner } : {}),
+            ...(options.owner ? { participant: targetRef(options.owner) } : {}),
             ...(options.status ? { status: options.status } : {}),
             limit: Number(options.limit),
         }));
@@ -1876,7 +1951,8 @@ export function createCli(io = defaultIo, dependencies = {}) {
         .option('--idempotency-key <key>')
         .action(async (id, options, command) => {
         const global = globals(command);
-        const record = await withProfile(command, (service) => service.notes.archive({
+        const record = await withProfile(command, async (service) => service.notes.archive({
+            expectedVersion: (await service.notes.get(id)).lifecycleVersion,
             noteId: id,
             ...(options.idempotencyKey ? { idempotencyKey: options.idempotencyKey } : {}),
         }));
@@ -1946,21 +2022,31 @@ export function createCli(io = defaultIo, dependencies = {}) {
             .action(async (id, options, command) => {
             const global = globals(command);
             const key = options.idempotencyKey ? { idempotencyKey: options.idempotencyKey } : {};
-            const record = await withProfile(command, (service) => operation === 'complete'
+            const record = await withProfile(command, async (service) => operation === 'complete'
                 ? service.todos.complete({
+                    expectedVersion: (await service.todos.get(id)).lifecycleVersion,
                     todoId: id,
                     ...(options.note ? { note: options.note } : {}),
                     ...key,
                 })
                 : operation === 'cancel'
                     ? service.todos.cancel({
+                        expectedVersion: (await service.todos.get(id)).lifecycleVersion,
                         todoId: id,
                         ...(options.reason ? { reason: options.reason } : {}),
                         ...key,
                     })
                     : operation === 'archive'
-                        ? service.todos.archive({ todoId: id, ...key })
-                        : service.todos.reopen({ todoId: id, ...key }));
+                        ? service.todos.archive({
+                            expectedVersion: (await service.todos.get(id)).lifecycleVersion,
+                            todoId: id,
+                            ...key,
+                        })
+                        : service.todos.reopen({
+                            expectedVersion: (await service.todos.get(id)).lifecycleVersion,
+                            todoId: id,
+                            ...key,
+                        }));
             output(io, global.json, record, `Todo ${id} is now ${record.status}.`);
         });
     }
@@ -1982,7 +2068,7 @@ export function createCli(io = defaultIo, dependencies = {}) {
         .action(async (assignee, options, command) => {
         const global = globals(command);
         const result = await withProfile(command, (service) => service.tasks.create({
-            assigneeAgentId: assignee,
+            assignee: targetRef(assignee),
             title: options.title,
             ...(options.description ? { description: options.description } : {}),
             priority: Number(options.priority),
@@ -2003,7 +2089,7 @@ export function createCli(io = defaultIo, dependencies = {}) {
         .action(async (options, command) => {
         const global = globals(command);
         const page = await withProfile(command, (service) => service.tasks.list({
-            ...(options.assignee ? { participantAgentId: options.assignee } : {}),
+            ...(options.assignee ? { participant: targetRef(options.assignee) } : {}),
             ...(options.status ? { status: options.status } : {}),
             limit: Number(options.limit),
         }));
@@ -2045,6 +2131,22 @@ export function createCli(io = defaultIo, dependencies = {}) {
         }));
         output(io, global.json, record, `Updated task ${id} to version ${record.current.version}.`);
     });
+    taskCommand
+        .command('override <task-id>')
+        .requiredOption('--decision <status>', 'open or rejected')
+        .requiredOption('--reason <text>')
+        .requiredOption('--expected-version <number>')
+        .option('--idempotency-key <key>')
+        .action(async (id, options, command) => {
+        const record = await withProfile(command, (service) => service.tasks.overrideDecision({
+            taskId: id,
+            nextStatus: options.decision,
+            reason: options.reason,
+            expectedVersion: Number(options.expectedVersion),
+            ...(options.idempotencyKey ? { idempotencyKey: options.idempotencyKey } : {}),
+        }));
+        output(io, globals(command).json, record, `Task decision overridden: ${record.status}.`);
+    });
     for (const operation of ['accept', 'reject', 'complete', 'reopen', 'cancel']) {
         const command_ = taskCommand
             .command(`${operation} <task-id>`)
@@ -2062,34 +2164,157 @@ export function createCli(io = defaultIo, dependencies = {}) {
         command_.action(async (id, options, command) => {
             const global = globals(command);
             const key = options.idempotencyKey ? { idempotencyKey: options.idempotencyKey } : {};
-            const record = await withProfile(command, (service) => operation === 'accept'
+            const record = await withProfile(command, async (service) => operation === 'accept'
                 ? service.tasks.accept({
+                    expectedVersion: (await service.tasks.get(id)).lifecycleVersion,
                     taskId: id,
                     ...(options.response ? { response: options.response } : {}),
                     ...key,
                 })
                 : operation === 'reject'
                     ? service.tasks.reject({
+                        expectedVersion: (await service.tasks.get(id)).lifecycleVersion,
                         taskId: id,
                         response: options.response ?? options.reason ?? '',
                         ...key,
                     })
                     : operation === 'complete'
                         ? service.tasks.complete({
+                            expectedVersion: (await service.tasks.get(id)).lifecycleVersion,
                             taskId: id,
                             ...(options.note ? { note: options.note } : {}),
                             ...key,
                         })
                         : operation === 'cancel'
                             ? service.tasks.cancel({
+                                expectedVersion: (await service.tasks.get(id)).lifecycleVersion,
                                 taskId: id,
                                 ...(options.reason ? { reason: options.reason } : {}),
                                 ...key,
                             })
-                            : service.tasks.reopen({ taskId: id, ...key }));
+                            : service.tasks.reopen({
+                                expectedVersion: (await service.tasks.get(id)).lifecycleVersion,
+                                taskId: id,
+                                ...key,
+                            }));
             output(io, global.json, record, `Task ${id} is ${record.status}.`);
         });
     }
+    program
+        .command('search <query>')
+        .option('--kind <kind>')
+        .option('--after <cursor>')
+        .option('--limit <number>')
+        .action(async (q, options, command) => {
+        const page = await withProfile(command, (service) => service.search({
+            q,
+            ...(options.kind ? { kinds: [options.kind] } : {}),
+            ...(options.after ? { after: options.after } : {}),
+            ...(options.limit ? { limit: Number(options.limit) } : {}),
+        }));
+        output(io, globals(command).json, page, page.items
+            .map((hit) => `${hit.kind}: ${hit.title} [${hit.rootId}]
+${hit.snippet}`)
+            .join('\n') || 'No visible results.');
+    });
+    const bookmarkCommand = program.command('bookmark').description('Your own saved records');
+    bookmarkCommand
+        .command('list')
+        .option('--after <cursor>')
+        .option('--limit <number>')
+        .action(async (options, command) => {
+        const page = await withProfile(command, (service) => service.bookmarks.list({
+            ...options,
+            ...(options.limit ? { limit: Number(options.limit) } : {}),
+        }));
+        output(io, globals(command).json, page, page.items
+            .map((entry) => `${entry.root.kind}: ${entry.root.title} [${entry.root.id}]`)
+            .join('\n') || 'No visible bookmarks.');
+    });
+    for (const operation of ['set', 'remove'])
+        bookmarkCommand
+            .command(`${operation} <root-id>`)
+            .action(async (rootId, _options, command) => {
+            const result = await withProfile(command, (service) => service.bookmarks.set({ rootId, present: operation === 'set' }));
+            output(io, globals(command).json, result, operation === 'set' ? 'Bookmark saved.' : 'Bookmark removed.');
+        });
+    const replyCommand = program
+        .command('reply')
+        .description('Discuss any visible record without changing its lifecycle');
+    replyCommand
+        .command('create <root-id>')
+        .requiredOption('--body <text>', 'Immutable reply body')
+        .option('--parent <reply-id>', 'Reply to a parent in this thread')
+        .option('--mention <actor>', 'Mention a typed human/agent', (value, previous) => [...previous, value], [])
+        .option('--idempotency-key <key>', 'Stable retry key')
+        .action(async (rootId, options, command) => {
+        const result = await withProfile(command, (service) => service.replies.create({
+            rootId,
+            body: options.body,
+            ...(options.parent ? { parentId: options.parent } : {}),
+            mentions: options.mention.map(targetRef),
+            ...(options.idempotencyKey ? { idempotencyKey: options.idempotencyKey } : {}),
+        }));
+        output(io, globals(command).json, result, `Reply ${result.id} created by ${result.author.kind}:${result.author.id}.`);
+    });
+    replyCommand
+        .command('show <reply-id>')
+        .action(async (id, _options, command) => {
+        const result = await withProfile(command, (service) => service.replies.get(id));
+        output(io, globals(command).json, result, result.deleted ? 'Deleted reply.' : (result.body ?? ''));
+    });
+    replyCommand
+        .command('delete <reply-id>')
+        .requiredOption('--expected-version <number>', 'Current reply version')
+        .option('--reason <text>', 'Moderation reason')
+        .option('--idempotency-key <key>', 'Stable retry key')
+        .action(async (replyId, options, command) => {
+        const result = await withProfile(command, (service) => service.replies.delete({
+            replyId,
+            expectedVersion: Number(options.expectedVersion),
+            ...(options.reason ? { reason: options.reason } : {}),
+            ...(options.idempotencyKey ? { idempotencyKey: options.idempotencyKey } : {}),
+        }));
+        output(io, globals(command).json, result, 'Visible reply removed; audit history remains.');
+    });
+    const threadCommand = program.command('thread').description('Read and follow record timelines');
+    threadCommand
+        .command('show <root-id>')
+        .option('--after <cursor>', 'Continue a signed snapshot')
+        .option('--limit <number>', 'Page size')
+        .action(async (rootId, options, command) => {
+        const result = await withProfile(command, (service) => service.threads.get({
+            rootId,
+            ...(options.after ? { after: options.after } : {}),
+            ...(options.limit ? { limit: Number(options.limit) } : {}),
+        }));
+        output(io, globals(command).json, result, JSON.stringify(result, null, 2));
+    });
+    threadCommand
+        .command('subscription <root-id>')
+        .option('--follow', 'Follow new replies')
+        .option('--mute', 'Mute notifications')
+        .action(async (rootId, options, command) => {
+        await withProfile(command, (service) => service.threads.subscription({
+            rootId,
+            following: !!options.follow,
+            muted: !!options.mute,
+        }));
+        output(io, globals(command).json, { updated: true }, 'Thread subscription updated.');
+    });
+    program
+        .command('react <target-id> <code>')
+        .option('--remove', 'Set absent instead of present')
+        .option('--idempotency-key <key>', 'Stable retry key')
+        .action(async (targetId, code, options, command) => {
+        const result = await withProfile(command, (service) => service.reactions.set({
+            targetId,
+            code,
+            present: !options.remove,
+            ...(options.idempotencyKey ? { idempotencyKey: options.idempotencyKey } : {}),
+        }));
+        output(io, globals(command).json, result, 'Reaction updated.');
+    });
     /* ------------------------------------------------------------ maintenance */
     const projectionCommand = program
         .command('projection')
@@ -2146,11 +2371,16 @@ export function createCli(io = defaultIo, dependencies = {}) {
     program
         .command('export')
         .description('Export canonical events for portability')
+        .option('--raw', 'filesystem-owner recovery: export unchanged JSON events without opening or migrating the store', false)
         .addOption(new Option('--format <format>').choices(['json', 'jsonl', 'markdown']).default('json'))
         .option('--output <path>', 'write to an explicit destination instead of stdout')
         .action(async (options, command) => {
         const global = globals(command);
-        const content = await withManagement(command, (service) => service.export(options.format));
+        if (options.raw && options.format === 'markdown')
+            throw new SynomemError('INVALID_INPUT', 'Raw recovery supports json or jsonl only.');
+        const content = options.raw
+            ? exportRawLocalEvents(global.home, options.format)
+            : await withManagement(command, (service) => service.export(options.format));
         if (options.output) {
             const destination = resolve(options.output);
             atomicWriteFile(destination, content, 0o600);