synomem 0.6.10 → 0.7.0

package/src/cli.ts

@@ -228,6 +228,7 @@ function itemListInput(options: Record<string, string | string[]>): ItemListInpu
     ...(typeof options.actor === 'string' ? { actorId: options.actor } : {}),
     ...(typeof options.status === 'string' ? { status: options.status } : {}),
     ...(typeof options.tag === 'string' ? { tag: options.tag } : {}),
+    ...(typeof options.topic === 'string' ? { topicId: options.topic } : {}),
     ...(typeof options.visibility === 'string'
       ? { visibility: options.visibility as ItemListInput['visibility'] }
       : {}),
@@ -293,8 +294,13 @@ async function withService<T>(
   home: string | undefined,
   configuredActor: ActorIdentity,
   operation: (client: SynomemService) => Promise<T>,
+  assertActor?: boolean,
 ): Promise<T> {
-  const client = serviceFactory({ ...(home ? { home } : {}), actor: configuredActor });
+  const client = serviceFactory({
+    ...(home ? { home } : {}),
+    actor: configuredActor,
+    ...(assertActor !== undefined ? { assertActor } : {}),
+  });
   await client.init();
   try {
     return await operation(client);
@@ -309,6 +315,7 @@ function addListOptions(command: Command): Command {
     .option('--actor <id>')
     .option('--actor-kind <kind>', 'human, agent, or system')
     .option('--tag <tag>')
+    .option('--topic <id>', 'only records carrying this topic')
     .option('--status <status>', 'acknowledged or unacknowledged')
     .option('--visibility <visibility>', 'private, local, or public')
     .addOption(
@@ -327,6 +334,7 @@ function listInput(options: Record<string, string>): KudosListInput {
     ...(options.actor ? { actorId: options.actor } : {}),
     ...(options.actorKind ? { actorKind: options.actorKind as KudosListInput['actorKind'] } : {}),
     ...(options.tag ? { tag: options.tag } : {}),
+    ...(options.topic ? { topicId: options.topic } : {}),
     ...(options.status ? { status: options.status as KudosListInput['status'] } : {}),
     ...(options.visibility
       ? { visibility: options.visibility as KudosListInput['visibility'] }
@@ -452,7 +460,8 @@ export function createCli(
     home: string | undefined,
     configuredActor: ActorIdentity,
     operation: (client: SynomemService) => Promise<T>,
-  ) => withService(serviceFactory, home, configuredActor, operation);
+    assertActor?: boolean,
+  ) => withService(serviceFactory, home, configuredActor, operation, assertActor);
   cliExitCodes.set(program, 0);
   program
     .name('synomem')
@@ -559,7 +568,11 @@ export function createCli(
       writeSynomemBackend({ kind: 'local' }, home);
       // Opening it once creates the database, so `list` does not report a
       // workspace that exists in name only.
-      await withClient(home, defaultActor(env, 'system', 'cli'), async () => undefined);
+      await withClient(
+        home,
+        defaultActor(env, 'system', 'cli', global.actor),
+        async () => undefined,
+      );
       output(
         io,
         global.json,
@@ -698,18 +711,22 @@ export function createCli(
       if (persisted?.backend.kind === 'remote') {
         throw new SynomemError('INVALID_INPUT', 'The init command requires a local backend.');
       }
-      await withClient(options.home, defaultActor(env, 'system', 'cli'), async (client) => {
-        const info = await client.info();
-        if (info.backend !== 'local') {
-          throw new SynomemError('INVALID_INPUT', 'The init command requires a local backend.');
-        }
-        output(
-          io,
-          options.json,
-          { home: info.home, database: info.databasePath },
-          `Initialized Synomem at ${info.home}`,
-        );
-      });
+      await withClient(
+        options.home,
+        defaultActor(env, 'system', 'cli', options.actor),
+        async (client) => {
+          const info = await client.info();
+          if (info.backend !== 'local') {
+            throw new SynomemError('INVALID_INPUT', 'The init command requires a local backend.');
+          }
+          output(
+            io,
+            options.json,
+            { home: info.home, database: info.databasePath },
+            `Initialized Synomem at ${info.home}`,
+          );
+        },
+      );
     });
 
   /*
@@ -1160,7 +1177,7 @@ export function createCli(
       }
       const result = await withClient(
         global.home,
-        defaultActor(env, 'system', 'cli'),
+        defaultActor(env, 'system', 'cli', global.actor),
         async (client) => ({
           info: await client.info(),
           capabilities: await client.capabilities(),
@@ -1198,15 +1215,19 @@ export function createCli(
     .description('Report whether the generated files match the canonical events')
     .action(async (_options, command: Command) => {
       const global = globals(command);
-      const status = await withClient(global.home, defaultActor(env, 'system', 'cli'), (client) => {
-        if (!client.projectionStatus) {
-          throw new SynomemError(
-            'INVALID_INPUT',
-            'The remote backend keeps no filesystem projections, so there is nothing to report.',
-          );
-        }
-        return client.projectionStatus();
-      });
+      const status = await withClient(
+        global.home,
+        defaultActor(env, 'system', 'cli', global.actor),
+        (client) => {
+          if (!client.projectionStatus) {
+            throw new SynomemError(
+              'INVALID_INPUT',
+              'The remote backend keeps no filesystem projections, so there is nothing to report.',
+            );
+          }
+          return client.projectionStatus();
+        },
+      );
       const enabled = Object.entries(status.settings)
         .filter(([, on]) => on)
         .map(([name]) => name);
@@ -1373,7 +1394,7 @@ export function createCli(
         const global = globals(command);
         const profile = await withClient(
           global.home,
-          defaultActor(env, 'system', 'cli'),
+          defaultActor(env, 'system', 'cli', global.actor),
           (client) =>
             client.agents.create({
               handle,
@@ -1402,8 +1423,10 @@ export function createCli(
     .description('Add aliases, keeping the ones already there')
     .action(async (agent: string, aliases: string[], _options, command: Command) => {
       const global = globals(command);
-      const profile = await withClient(global.home, defaultActor(env, 'system', 'cli'), (client) =>
-        client.agents.addAliases(agent, aliases),
+      const profile = await withClient(
+        global.home,
+        defaultActor(env, 'system', 'cli', global.actor),
+        (client) => client.agents.addAliases(agent, aliases),
       );
       output(io, global.json, profile, `Aliases: ${(profile.aliases ?? []).join(', ') || 'none'}`);
     });
@@ -1413,8 +1436,10 @@ export function createCli(
     .description('Remove aliases, keeping the rest')
     .action(async (agent: string, aliases: string[], _options, command: Command) => {
       const global = globals(command);
-      const profile = await withClient(global.home, defaultActor(env, 'system', 'cli'), (client) =>
-        client.agents.removeAliases(agent, aliases),
+      const profile = await withClient(
+        global.home,
+        defaultActor(env, 'system', 'cli', global.actor),
+        (client) => client.agents.removeAliases(agent, aliases),
       );
       output(io, global.json, profile, `Aliases: ${(profile.aliases ?? []).join(', ') || 'none'}`);
     });
@@ -1424,8 +1449,10 @@ export function createCli(
     .description('Change an agent handle. Its canonical ID never changes.')
     .action(async (agent: string, handle: string, _options, command: Command) => {
       const global = globals(command);
-      const profile = await withClient(global.home, defaultActor(env, 'system', 'cli'), (client) =>
-        client.agents.update(agent, { handle }),
+      const profile = await withClient(
+        global.home,
+        defaultActor(env, 'system', 'cli', global.actor),
+        (client) => client.agents.update(agent, { handle }),
       );
       output(
         io,
@@ -1440,8 +1467,10 @@ export function createCli(
     .description('Stop an agent acting, keeping its records and history')
     .action(async (agent: string, _options, command: Command) => {
       const global = globals(command);
-      const profile = await withClient(global.home, defaultActor(env, 'system', 'cli'), (client) =>
-        client.agents.archive(agent),
+      const profile = await withClient(
+        global.home,
+        defaultActor(env, 'system', 'cli', global.actor),
+        (client) => client.agents.archive(agent),
       );
       output(io, global.json, profile, `Archived ${profile.handle} (${profile.id})`);
     });
@@ -1451,12 +1480,145 @@ export function createCli(
     .description('Let an archived agent act again')
     .action(async (agent: string, _options, command: Command) => {
       const global = globals(command);
-      const profile = await withClient(global.home, defaultActor(env, 'system', 'cli'), (client) =>
-        client.agents.restore(agent),
+      const profile = await withClient(
+        global.home,
+        defaultActor(env, 'system', 'cli', global.actor),
+        (client) => client.agents.restore(agent),
       );
       output(io, global.json, profile, `Restored ${profile.handle} (${profile.id})`);
     });
 
+  const topicCommand = program
+    .command('topic')
+    .description('Create and manage topics — a stable, reusable subject any record can carry');
+
+  topicCommand
+    .command('create <display-name>')
+    .description('Create a topic. Any actor may create one.')
+    .option('--alias <name>', 'alias (repeatable)', collect, [])
+    .action(async (displayName: string, options: { alias: string[] }, command: Command) => {
+      const global = globals(command);
+      const topic = await withClient(
+        global.home,
+        defaultActor(env, 'system', 'cli', global.actor),
+        (client) =>
+          client.topics.create({
+            displayName,
+            ...(options.alias.length ? { aliases: options.alias } : {}),
+          }),
+      );
+      output(io, global.json, topic, `Created ${topic.displayName}\n\nTopic ID: ${topic.id}`);
+    });
+
+  topicCommand
+    .command('list')
+    .description('List known topics')
+    .option('--status <status>', 'active or archived')
+    .action(async (options: { status?: string }, command: Command) => {
+      const global = globals(command);
+      const topics = await withClient(
+        global.home,
+        defaultActor(env, 'system', 'cli', global.actor),
+        (client) =>
+          client.topics.list(
+            options.status ? { status: options.status as 'active' | 'archived' } : {},
+          ),
+      );
+      const human = topics.length
+        ? topics
+            .map(
+              (topic) =>
+                `${topic.displayName}${topic.status === 'archived' ? '  [archived]' : ''}${
+                  topic.aliases?.length ? `  aliases: ${topic.aliases.join(', ')}` : ''
+                }\n  ${topic.id}`,
+            )
+            .join('\n')
+        : 'No topics yet.';
+      output(io, global.json, { topics }, human);
+    });
+
+  topicCommand
+    .command('show <id>')
+    .description('Show one topic, resolving aliases')
+    .action(async (id: string, _options, command: Command) => {
+      const global = globals(command);
+      const topic = await withClient(
+        global.home,
+        defaultActor(env, 'system', 'cli', global.actor),
+        (client) => client.topics.get(id),
+      );
+      output(
+        io,
+        global.json,
+        topic,
+        `${topic.displayName}\n\nTopic ID: ${topic.id}\nStatus:   ${topic.status}\nAliases:  ${topic.aliases?.join(', ') ?? 'none'}`,
+      );
+    });
+
+  topicCommand
+    .command('resolve <name>')
+    .description('Resolve a name or alias to one topic, or list the candidates')
+    .action(async (name: string, _options, command: Command) => {
+      const global = globals(command);
+      const resolution = await withClient(
+        global.home,
+        defaultActor(env, 'system', 'cli', global.actor),
+        (client) => client.topics.resolve(name),
+      );
+      const human = resolution.match
+        ? `${resolution.match.displayName} (${resolution.match.id})`
+        : resolution.candidates.length
+          ? `"${resolution.query}" is ambiguous. Candidates:\n${resolution.candidates
+              .map((topic) => `  ${topic.id}  ${topic.displayName}`)
+              .join('\n')}`
+          : `No topic answers to "${resolution.query}".`;
+      output(io, global.json, resolution, human);
+    });
+
+  topicCommand
+    .command('rename <id> <display-name>')
+    .description("Change a topic's display name. Its ID never changes.")
+    .action(async (id: string, displayName: string, _options, command: Command) => {
+      const global = globals(command);
+      const topic = await withClient(
+        global.home,
+        defaultActor(env, 'system', 'cli', global.actor),
+        (client) => client.topics.update(id, { displayName }),
+      );
+      output(
+        io,
+        global.json,
+        topic,
+        `Renamed to ${topic.displayName}\nTopic ID: ${topic.id} (unchanged)`,
+      );
+    });
+
+  topicCommand
+    .command('archive <id>')
+    .description('Stop a topic being attached to new records, keeping the ones it already has')
+    .action(async (id: string, _options, command: Command) => {
+      const global = globals(command);
+      const topic = await withClient(
+        global.home,
+        defaultActor(env, 'system', 'cli', global.actor),
+        (client) => client.topics.archive(id),
+      );
+      output(io, global.json, topic, `Archived ${topic.displayName} (${topic.id})`);
+    });
+
+  topicCommand
+    .command('restore <id>')
+    .description('Let an archived topic be attached to new records again')
+    .action(async (id: string, _options, command: Command) => {
+      const global = globals(command);
+      const topic = await withClient(
+        global.home,
+        defaultActor(env, 'system', 'cli', global.actor),
+        (client) => client.topics.restore(id),
+      );
+      output(io, global.json, topic, `Restored ${topic.displayName} (${topic.id})`);
+    });
+
   const skillCommand = program
     .command('skill')
     .description('Install and maintain the packaged agent skill');
@@ -1493,7 +1655,7 @@ export function createCli(
         if (options.agent) {
           agentId = await withClient(
             global.home,
-            defaultActor(env, 'system', 'cli'),
+            defaultActor(env, 'system', 'cli', global.actor),
             async (client) => {
               const resolution = await client.agents.resolve(options.agent!);
               if (!resolution.match) {
@@ -1582,8 +1744,10 @@ export function createCli(
     .description('List known agent identities')
     .action(async (_options, command: Command) => {
       const global = globals(command);
-      const agents = await withClient(global.home, defaultActor(env, 'system', 'cli'), (client) =>
-        client.agents.list(),
+      const agents = await withClient(
+        global.home,
+        defaultActor(env, 'system', 'cli', global.actor),
+        (client) => client.agents.list(),
       );
       const human = agents.length
         ? agents
@@ -1605,8 +1769,10 @@ export function createCli(
     .description('Show one agent profile, resolving aliases')
     .action(async (id: string, _options, command: Command) => {
       const global = globals(command);
-      const profile = await withClient(global.home, defaultActor(env, 'system', 'cli'), (client) =>
-        client.agents.get(id),
+      const profile = await withClient(
+        global.home,
+        defaultActor(env, 'system', 'cli', global.actor),
+        (client) => client.agents.get(id),
       );
       output(
         io,
@@ -1633,7 +1799,7 @@ export function createCli(
         const hasAliases = options.clearAliases || options.alias.length > 0;
         const profile = await withClient(
           global.home,
-          defaultActor(env, 'system', 'cli'),
+          defaultActor(env, 'system', 'cli', global.actor),
           (client) =>
             client.agents.update(id, {
               ...(options.name ? { displayName: options.name } : {}),
@@ -1652,7 +1818,7 @@ export function createCli(
       const global = globals(command);
       const resolution = await withClient(
         global.home,
-        defaultActor(env, 'system', 'cli'),
+        defaultActor(env, 'system', 'cli', global.actor),
         (client) => client.agents.resolve(name),
       );
       // An ambiguous name is a question, not a failure: exit zero and show the
@@ -1672,8 +1838,10 @@ export function createCli(
     .description('List agents with their runtime bindings')
     .action(async (_options, command: Command) => {
       const global = globals(command);
-      const entries = await withClient(global.home, defaultActor(env, 'system', 'cli'), (client) =>
-        client.agents.directory(),
+      const entries = await withClient(
+        global.home,
+        defaultActor(env, 'system', 'cli', global.actor),
+        (client) => client.agents.directory(),
       );
       const human = entries.length
         ? entries
@@ -1713,7 +1881,7 @@ export function createCli(
         const global = globals(command);
         const binding = await withClient(
           global.home,
-          defaultActor(env, 'system', 'cli'),
+          defaultActor(env, 'system', 'cli', global.actor),
           (client) =>
             client.agents.bindRuntime({
               agentId: agent,
@@ -1744,7 +1912,7 @@ export function createCli(
       const global = globals(command);
       const result = await withClient(
         global.home,
-        defaultActor(env, 'system', 'cli'),
+        defaultActor(env, 'system', 'cli', global.actor),
         async (client) => {
           if (agent) {
             const profile = await client.agents.get(agent);
@@ -1777,8 +1945,10 @@ export function createCli(
     .description('Remove a runtime binding')
     .action(async (bindingId: string, _options, command: Command) => {
       const global = globals(command);
-      const removed = await withClient(global.home, defaultActor(env, 'system', 'cli'), (client) =>
-        client.agents.unbindRuntime(bindingId),
+      const removed = await withClient(
+        global.home,
+        defaultActor(env, 'system', 'cli', global.actor),
+        (client) => client.agents.unbindRuntime(bindingId),
       );
       output(
         io,
@@ -1798,6 +1968,7 @@ export function createCli(
     .requiredOption('--title <title>')
     .requiredOption('--body <body>')
     .option('--tag <tag>', 'repeatable', collect, [])
+    .option('--topic <id>', 'topic ID (repeatable)', collect, [])
     .option('--reply-to <post-id>')
     .action(
       async (
@@ -1807,6 +1978,7 @@ export function createCli(
           title: string;
           body: string;
           tag: string[];
+          topic: string[];
           replyTo?: string;
         },
         command: Command,
@@ -1820,6 +1992,7 @@ export function createCli(
               title: options.title,
               body: options.body,
               ...(options.tag.length ? { tags: options.tag } : {}),
+              ...(options.topic.length ? { topicIds: options.topic } : {}),
               ...(options.replyTo ? { replyTo: options.replyTo } : {}),
             }),
         );
@@ -1969,6 +2142,7 @@ export function createCli(
     .requiredOption('--title <title>')
     .requiredOption('--reason <reason>')
     .option('--tag <tag>', 'tag (repeatable)', collect, [])
+    .option('--topic <id>', 'topic ID (repeatable)', collect, [])
     .option('--evidence <kind:value>', 'sanitized evidence (repeatable)', collect, [])
     .option('--visibility <visibility>', 'private, local, or public', 'workspace')
     .option('--idempotency-key <key>')
@@ -1982,6 +2156,7 @@ export function createCli(
           title: string;
           reason: string;
           tag: string[];
+          topic: string[];
           evidence: string[];
           visibility: 'private' | 'workspace' | 'public';
           idempotencyKey?: string;
@@ -1999,6 +2174,7 @@ export function createCli(
               reason: options.reason,
               visibility: options.visibility,
               ...(options.tag.length ? { tags: options.tag } : {}),
+              ...(options.topic.length ? { topicIds: options.topic } : {}),
               ...(options.evidence.length ? { evidence: options.evidence.map(parseEvidence) } : {}),
               ...(options.idempotencyKey ? { idempotencyKey: options.idempotencyKey } : {}),
             }),
@@ -2055,8 +2231,9 @@ export function createCli(
       const global = globals(command);
       const page = await withClient(
         global.home,
-        defaultActor(env, 'human', 'local-cli'),
+        defaultActor(env, 'human', 'local-cli', global.actor),
         (client) => client.kudos.list(listInput(options)),
+        Boolean(global.actor),
       );
       output(
         io,
@@ -2076,6 +2253,7 @@ export function createCli(
     .option('--participant <agent>')
     .option('--actor <id>')
     .option('--tag <tag>')
+    .option('--topic <id>', 'only records carrying this topic')
     .option('--status <status>')
     .option('--visibility <visibility>', 'private, workspace, or public')
     .option('--limit <number>', 'maximum results (default 10, maximum 50)', '10')
@@ -2085,8 +2263,9 @@ export function createCli(
       const global = globals(command);
       const page = await withClient(
         global.home,
-        defaultActor(env, 'human', 'local-cli'),
+        defaultActor(env, 'human', 'local-cli', global.actor),
         (client) => client.items.list(itemListInput(options)),
+        Boolean(global.actor),
       );
       output(
         io,
@@ -2109,13 +2288,14 @@ export function createCli(
         const global = globals(command);
         const page = await withClient(
           global.home,
-          defaultActor(env, 'human', 'local-cli'),
+          defaultActor(env, 'human', 'local-cli', global.actor),
           (client) =>
             client.items.changes({
               limit: Number(options.limit),
               ...(options.kind.length ? { kinds: options.kind as ItemListInput['kinds'] } : {}),
               ...(options.after ? { after: options.after } : {}),
             }),
+          Boolean(global.actor),
         );
         const human = page.items.length
           ? `${page.items
@@ -2138,6 +2318,7 @@ export function createCli(
     .requiredOption('--subject <subject>')
     .requiredOption('--body <body>')
     .option('--tag <tag>', 'tag (repeatable)', collect, [])
+    .option('--topic <id>', 'topic ID (repeatable)', collect, [])
     .option('--visibility <visibility>', 'private, workspace, or public', 'workspace')
     .option('--idempotency-key <key>')
     .action(
@@ -2150,6 +2331,7 @@ export function createCli(
           subject: string;
           body: string;
           tag: string[];
+          topic: string[];
           visibility: 'private' | 'workspace' | 'public';
           idempotencyKey?: string;
         },
@@ -2166,6 +2348,7 @@ export function createCli(
               body: options.body,
               visibility: options.visibility,
               ...(options.tag.length ? { tags: options.tag } : {}),
+              ...(options.topic.length ? { topicIds: options.topic } : {}),
               ...(options.idempotencyKey ? { idempotencyKey: options.idempotencyKey } : {}),
             }),
         );
@@ -2191,7 +2374,7 @@ export function createCli(
         const global = globals(command);
         const page = await withClient(
           global.home,
-          defaultActor(env, 'human', 'local-cli'),
+          defaultActor(env, 'human', 'local-cli', global.actor),
           (client) =>
             client.memos.list({
               ...(options.participant ? { participantAgentId: options.participant } : {}),
@@ -2199,6 +2382,7 @@ export function createCli(
               limit: Number(options.limit),
               ...(options.cursor ? { cursor: options.cursor } : {}),
             }),
+          Boolean(global.actor),
         );
         output(io, global.json, page, page.items.map(lineForItem).join('\n') || 'No memos found.');
       },
@@ -2207,8 +2391,9 @@ export function createCli(
     const global = globals(command);
     const record = await withClient(
       global.home,
-      defaultActor(env, 'human', 'local-cli'),
+      defaultActor(env, 'human', 'local-cli', global.actor),
       (client) => client.memos.get(id),
+      Boolean(global.actor),
     );
     output(
       io,
@@ -2255,6 +2440,7 @@ export function createCli(
     .requiredOption('--title <title>')
     .requiredOption('--body <body>')
     .option('--tag <tag>', 'tag (repeatable)', collect, [])
+    .option('--topic <id>', 'topic ID (repeatable)', collect, [])
     .option('--idempotency-key <key>')
     .action(
       async (
@@ -2265,6 +2451,7 @@ export function createCli(
           title: string;
           body: string;
           tag: string[];
+          topic: string[];
           idempotencyKey?: string;
         },
         command: Command,
@@ -2279,6 +2466,7 @@ export function createCli(
               title: options.title,
               body: options.body,
               ...(options.tag.length ? { tags: options.tag } : {}),
+              ...(options.topic.length ? { topicIds: options.topic } : {}),
               ...(options.idempotencyKey ? { idempotencyKey: options.idempotencyKey } : {}),
             }),
         );
@@ -2300,13 +2488,14 @@ export function createCli(
         const global = globals(command);
         const page = await withClient(
           global.home,
-          defaultActor(env, 'human', 'local-cli'),
+          defaultActor(env, 'human', 'local-cli', global.actor),
           (client) =>
             client.notes.list({
               ...(options.owner ? { participantAgentId: options.owner } : {}),
               ...(options.status ? { status: options.status } : {}),
               limit: Number(options.limit),
             }),
+          Boolean(global.actor),
         );
         output(io, global.json, page, page.items.map(lineForItem).join('\n') || 'No notes found.');
       },
@@ -2315,8 +2504,9 @@ export function createCli(
     const global = globals(command);
     const record = await withClient(
       global.home,
-      defaultActor(env, 'human', 'local-cli'),
+      defaultActor(env, 'human', 'local-cli', global.actor),
       (client) => client.notes.get(id),
+      Boolean(global.actor),
     );
     output(
       io,
@@ -2404,6 +2594,7 @@ export function createCli(
     .option('--due-at <datetime>')
     .option('--time-zone <iana-zone>')
     .option('--tag <tag>', 'tag (repeatable)', collect, [])
+    .option('--topic <id>', 'topic ID (repeatable)', collect, [])
     .option('--idempotency-key <key>')
     .action(
       async (
@@ -2417,6 +2608,7 @@ export function createCli(
           dueAt?: string;
           timeZone?: string;
           tag: string[];
+          topic: string[];
           idempotencyKey?: string;
         },
         command: Command,
@@ -2432,6 +2624,7 @@ export function createCli(
               priority: Number(options.priority) as 1 | 2 | 3 | 4,
               ...((due) => (due ? { due } : {}))(taskDue(options)),
               ...(options.tag.length ? { tags: options.tag } : {}),
+              ...(options.topic.length ? { topicIds: options.topic } : {}),
               ...(options.idempotencyKey ? { idempotencyKey: options.idempotencyKey } : {}),
             }),
         );
@@ -2557,6 +2750,7 @@ export function createCli(
     .option('--due-at <datetime>')
     .option('--time-zone <iana-zone>')
     .option('--tag <tag>', 'tag (repeatable)', collect, [])
+    .option('--topic <id>', 'topic ID (repeatable)', collect, [])
     .option('--visibility <visibility>', 'private, workspace, or public', 'workspace')
     .option('--idempotency-key <key>')
     .action(
@@ -2572,6 +2766,7 @@ export function createCli(
           dueAt?: string;
           timeZone?: string;
           tag: string[];
+          topic: string[];
           visibility: 'private' | 'workspace' | 'public';
           idempotencyKey?: string;
         },
@@ -2589,6 +2784,7 @@ export function createCli(
               priority: Number(options.priority) as 1 | 2 | 3 | 4,
               ...((due) => (due ? { due } : {}))(taskDue(options)),
               ...(options.tag.length ? { tags: options.tag } : {}),
+              ...(options.topic.length ? { topicIds: options.topic } : {}),
               visibility: options.visibility,
               ...(options.idempotencyKey ? { idempotencyKey: options.idempotencyKey } : {}),
             }),
@@ -2611,13 +2807,14 @@ export function createCli(
         const global = globals(command);
         const page = await withClient(
           global.home,
-          defaultActor(env, 'human', 'local-cli'),
+          defaultActor(env, 'human', 'local-cli', global.actor),
           (client) =>
             client.tasks.list({
               ...(options.assignee ? { participantAgentId: options.assignee } : {}),
               ...(options.status ? { status: options.status } : {}),
               limit: Number(options.limit),
             }),
+          Boolean(global.actor),
         );
         output(io, global.json, page, page.items.map(lineForItem).join('\n') || 'No tasks found.');
       },
@@ -2626,8 +2823,9 @@ export function createCli(
     const global = globals(command);
     const record = await withClient(
       global.home,
-      defaultActor(env, 'human', 'local-cli'),
+      defaultActor(env, 'human', 'local-cli', global.actor),
       (client) => client.tasks.get(id),
+      Boolean(global.actor),
     );
     output(
       io,
@@ -2765,8 +2963,10 @@ export function createCli(
     .description('Show one kudos item and its current state')
     .action(async (id: string, _options, command: Command) => {
       const global = globals(command);
-      const record = await withClient(global.home, defaultActor(env, 'system', 'cli'), (client) =>
-        client.kudos.get(id),
+      const record = await withClient(
+        global.home,
+        defaultActor(env, 'system', 'cli', global.actor),
+        (client) => client.kudos.get(id),
       );
       output(io, global.json, record, showRecord(record));
     });
@@ -2841,7 +3041,7 @@ export function createCli(
         if (!agentId) throw new SynomemError('INVALID_INPUT', 'Specify an agent.');
         const details = await withClient(
           global.home,
-          defaultActor(env, 'system', 'cli'),
+          defaultActor(env, 'system', 'cli', global.actor),
           async (client) => {
             const profile = await client.agents.get(agentId);
             const info = await client.info();
@@ -2885,8 +3085,10 @@ export function createCli(
     kudosCommand.command('stats').description('Show aggregate kudos statistics'),
   ).action(async (options: Record<string, string>, command: Command) => {
     const global = globals(command);
-    const stats = await withClient(global.home, defaultActor(env, 'system', 'cli'), (client) =>
-      client.stats(listInput(options)),
+    const stats = await withClient(
+      global.home,
+      defaultActor(env, 'system', 'cli', global.actor),
+      (client) => client.stats(listInput(options)),
     );
     output(
       io,
@@ -2901,8 +3103,10 @@ export function createCli(
     .description('Regenerate current-state and filesystem projections from canonical events')
     .action(async (_options, command: Command) => {
       const global = globals(command);
-      const result = await withClient(global.home, defaultActor(env, 'system', 'cli'), (client) =>
-        client.rebuild(),
+      const result = await withClient(
+        global.home,
+        defaultActor(env, 'system', 'cli', global.actor),
+        (client) => client.rebuild(),
       );
       output(
         io,
@@ -2917,15 +3121,19 @@ export function createCli(
     .description('Create a transactionally consistent SQLite backup')
     .action(async (destination: string, _options, command: Command) => {
       const global = globals(command);
-      const path = await withClient(global.home, defaultActor(env, 'system', 'cli'), (client) => {
-        if (!client.backup) {
-          throw new SynomemError(
-            'INVALID_INPUT',
-            'Filesystem backup is available only with the local backend.',
-          );
-        }
-        return client.backup(destination);
-      });
+      const path = await withClient(
+        global.home,
+        defaultActor(env, 'system', 'cli', global.actor),
+        (client) => {
+          if (!client.backup) {
+            throw new SynomemError(
+              'INVALID_INPUT',
+              'Filesystem backup is available only with the local backend.',
+            );
+          }
+          return client.backup(destination);
+        },
+      );
       output(io, global.json, { path }, `Created backup at ${path}`);
     });
 
@@ -2944,7 +3152,7 @@ export function createCli(
         const global = globals(command);
         const content = await withClient(
           global.home,
-          defaultActor(env, 'system', 'cli'),
+          defaultActor(env, 'system', 'cli', global.actor),
           (client) => client.export(options.format),
         );
         if (options.output) {
@@ -2967,8 +3175,10 @@ export function createCli(
     .description('Run safe diagnostics')
     .action(async (_options, command: Command) => {
       const global = globals(command);
-      const result = await withClient(global.home, defaultActor(env, 'system', 'cli'), (client) =>
-        client.doctor(),
+      const result = await withClient(
+        global.home,
+        defaultActor(env, 'system', 'cli', global.actor),
+        (client) => client.doctor(),
       );
       const human = result.diagnostics
         .map((item) => `${item.level.toUpperCase().padEnd(7)} ${item.code}: ${item.message}`)
@@ -2994,20 +3204,24 @@ export function createCli(
         // the name is written into every event the session appends, and a
         // harness must not be able to sign another agent's name to work.
         const bound = options.agentId
-          ? await withClient(global.home, defaultActor(env, 'system', 'cli'), async (client) => {
-              const resolution = await client.agents.resolve(options.agentId!);
-              if (!resolution.match) {
-                throw new SynomemError(
-                  'AGENT_NOT_FOUND',
-                  resolution.candidates.length
-                    ? `"${options.agentId}" matches ${resolution.candidates.length} agents: ${resolution.candidates
-                        .map((candidate) => candidate.id)
-                        .join(', ')}. Name one of them.`
-                    : `Unknown agent: ${options.agentId}`,
-                );
-              }
-              return actor('agent', resolution.match.id, resolution.match.displayName);
-            })
+          ? await withClient(
+              global.home,
+              defaultActor(env, 'system', 'cli', global.actor),
+              async (client) => {
+                const resolution = await client.agents.resolve(options.agentId!);
+                if (!resolution.match) {
+                  throw new SynomemError(
+                    'AGENT_NOT_FOUND',
+                    resolution.candidates.length
+                      ? `"${options.agentId}" matches ${resolution.candidates.length} agents: ${resolution.candidates
+                          .map((candidate) => candidate.id)
+                          .join(', ')}. Name one of them.`
+                      : `Unknown agent: ${options.agentId}`,
+                  );
+                }
+                return actor('agent', resolution.match.id, resolution.match.displayName);
+              },
+            )
           : undefined;
         if (!bound && !(options.actorId && options.actorKind)) {
           throw new SynomemError(