synomem 0.1.0 → 0.2.0

package/src/cli.ts

@@ -34,7 +34,7 @@ import type {
   KudosSummary,
   ItemListInput,
   ItemSummary,
-  TodoDue,
+  TaskDue,
 } from './types.js';
 import { packageVersion } from './version.js';
 import type { SynomemService, SynomemServiceFactory } from './service.js';
@@ -109,11 +109,27 @@ function actor(kind: string, id: string, displayName?: string): ActorIdentity {
   };
 }
 
-function todoDue(options: {
+/**
+ * The acting identity for commands that do not take an explicit actor.
+ * Local storage accepts any actor, so these fall back to the historical CLI defaults; a remote
+ * backend binds the credential to one actor, so SYNOMEM_ACTOR_ID/KIND/NAME must be able to
+ * override them or those commands cannot authenticate.
+ */
+function defaultActor(
+  env: NodeJS.ProcessEnv,
+  fallbackKind: string,
+  fallbackId: string,
+): ActorIdentity {
+  const id = env.SYNOMEM_ACTOR_ID?.trim();
+  if (!id) return actor(fallbackKind, fallbackId);
+  return actor(env.SYNOMEM_ACTOR_KIND?.trim() || fallbackKind, id, env.SYNOMEM_ACTOR_NAME?.trim());
+}
+
+function taskDue(options: {
   dueDate?: string;
   dueAt?: string;
   timeZone?: string;
-}): TodoDue | undefined {
+}): TaskDue | undefined {
   if (options.dueDate && options.dueAt)
     throw new SynomemError('INVALID_INPUT', 'Use due-date or due-at, not both.');
   if (options.dueDate) return { kind: 'date', date: options.dueDate };
@@ -386,7 +402,7 @@ export function createCli(
       if (persisted?.backend.kind === 'remote') {
         throw new SynomemError('INVALID_INPUT', 'The init command requires a local backend.');
       }
-      await withClient(options.home, actor('system', 'cli'), async (client) => {
+      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.');
@@ -595,13 +611,16 @@ export function createCli(
         command: Command,
       ) => {
         const global = globals(command);
-        const profile = await withClient(global.home, actor('system', 'cli'), (client) =>
-          client.agents.create({
-            id,
-            displayName: options.name,
-            ...(options.alias.length ? { aliases: options.alias } : {}),
-            ...(options.description ? { description: options.description } : {}),
-          }),
+        const profile = await withClient(
+          global.home,
+          defaultActor(env, 'system', 'cli'),
+          (client) =>
+            client.agents.create({
+              id,
+              displayName: options.name,
+              ...(options.alias.length ? { aliases: options.alias } : {}),
+              ...(options.description ? { description: options.description } : {}),
+            }),
         );
         output(io, global.json, profile, `Created ${profile.displayName} (${profile.id})`);
       },
@@ -618,29 +637,73 @@ export function createCli(
     .option('--yes', 'apply the displayed plan', false)
     .option('--force', 'replace a conflicting synomem directory', false)
     .option('--link', 'symlink to the packaged skill instead of copying it', false)
-    .option('--actor-id <id>', 'print actor-bound MCP registration commands')
-    .option('--actor-name <name>', 'display name used in MCP registration commands')
+    .option('--agent <id-or-alias>', 'bind this installation to an agent')
     .action(
-      (
+      async (
         options: {
           runtime: string[];
           yes: boolean;
           force: boolean;
           link: boolean;
-          actorId?: string;
-          actorName?: string;
+          agent?: string;
         },
         command: Command,
       ) => {
         const global = globals(command);
+        const runtimes = skillRuntimes(options.runtime);
+
+        /*
+         * The agent is resolved BEFORE anything is written. An ambiguous or
+         * unknown name then stops the command with a name to fix, rather than
+         * leaving a skill installed and pointed at an agent that does not
+         * exist.
+         */
+        let agentId: string | undefined;
+        if (options.agent) {
+          agentId = await withClient(
+            global.home,
+            defaultActor(env, 'system', 'cli'),
+            async (client) => {
+              const resolution = await client.agents.resolve(options.agent!);
+              if (!resolution.match) {
+                throw new SynomemError(
+                  'AGENT_NOT_FOUND',
+                  resolution.candidates.length
+                    ? `"${options.agent}" matches ${resolution.candidates.length} agents: ${resolution.candidates
+                        .map((candidate) => candidate.id)
+                        .join(', ')}. Name one of them.`
+                    : `Unknown agent: ${options.agent}`,
+                );
+              }
+              return resolution.match.id;
+            },
+          );
+        }
+
         const result = installSkill({
-          runtimes: skillRuntimes(options.runtime),
+          ...(runtimes ? { runtimes } : {}),
           apply: options.yes,
           force: options.force,
           link: options.link,
-          actorId: options.actorId,
-          actorName: options.actorName,
+          ...(agentId ? { agentId } : {}),
         });
+
+        // Bindings follow what was actually installed, and only on a real run:
+        // a dry run must not claim a binding it did not make, and a runtime
+        // whose harness is not present here is not somewhere this agent runs.
+        if (agentId && options.yes) {
+          const installed = result.locations
+            .filter((location) => location.state !== 'unavailable')
+            .map((location) => location.runtime);
+          if (installed.length) {
+            await withClient(global.home, defaultActor(env, 'system', 'cli'), async (client) => {
+              for (const runtime of installed) {
+                await client.agents.bindRuntime({ agentId, runtime });
+              }
+            });
+          }
+        }
+
         output(io, global.json, result, formatSkillResult(result, 'install'));
       },
     );
@@ -649,19 +712,15 @@ export function createCli(
     .command('status')
     .description('Show installed, stale, missing, or conflicting skill copies')
     .option('--runtime <runtime>', `${skillRuntimeHelp} (repeatable)`, collect, [])
-    .option('--actor-id <id>', 'print actor-bound MCP registration commands')
-    .option('--actor-name <name>', 'display name used in MCP registration commands')
-    .action(
-      (options: { runtime: string[]; actorId?: string; actorName?: string }, command: Command) => {
-        const global = globals(command);
-        const result = skillStatus({
-          runtimes: skillRuntimes(options.runtime),
-          actorId: options.actorId,
-          actorName: options.actorName,
-        });
-        output(io, global.json, result, formatSkillResult(result, 'status'));
-      },
-    );
+    .option('--agent <id>', 'print the registration command for this agent')
+    .action((options: { runtime: string[]; agent?: string }, command: Command) => {
+      const global = globals(command);
+      const result = skillStatus({
+        runtimes: skillRuntimes(options.runtime),
+        ...(options.agent ? { agentId: options.agent } : {}),
+      });
+      output(io, global.json, result, formatSkillResult(result, 'status'));
+    });
 
   skillCommand
     .command('uninstall')
@@ -684,7 +743,7 @@ export function createCli(
     .description('List known agent identities')
     .action(async (_options, command: Command) => {
       const global = globals(command);
-      const agents = await withClient(global.home, actor('system', 'cli'), (client) =>
+      const agents = await withClient(global.home, defaultActor(env, 'system', 'cli'), (client) =>
         client.agents.list(),
       );
       const human = agents.length
@@ -703,7 +762,7 @@ 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, actor('system', 'cli'), (client) =>
+      const profile = await withClient(global.home, defaultActor(env, 'system', 'cli'), (client) =>
         client.agents.get(id),
       );
       output(
@@ -729,17 +788,141 @@ export function createCli(
       ) => {
         const global = globals(command);
         const hasAliases = options.clearAliases || options.alias.length > 0;
-        const profile = await withClient(global.home, actor('system', 'cli'), (client) =>
-          client.agents.update(id, {
-            ...(options.name ? { displayName: options.name } : {}),
-            ...(hasAliases ? { aliases: options.clearAliases ? [] : options.alias } : {}),
-            ...(options.description !== undefined ? { description: options.description } : {}),
-          }),
+        const profile = await withClient(
+          global.home,
+          defaultActor(env, 'system', 'cli'),
+          (client) =>
+            client.agents.update(id, {
+              ...(options.name ? { displayName: options.name } : {}),
+              ...(hasAliases ? { aliases: options.clearAliases ? [] : options.alias } : {}),
+              ...(options.description !== undefined ? { description: options.description } : {}),
+            }),
         );
         output(io, global.json, profile, `Updated ${profile.displayName} (${profile.id})`);
       },
     );
 
+  agentCommand
+    .command('resolve <name>')
+    .description('Resolve a name or alias to one agent, 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'),
+        (client) => client.agents.resolve(name),
+      );
+      // An ambiguous name is a question, not a failure: exit zero and show the
+      // candidates so the caller can pick one.
+      const human = resolution.match
+        ? `${resolution.match.displayName} (${resolution.match.id})`
+        : resolution.candidates.length
+          ? `"${resolution.query}" is ambiguous. Candidates:\n${resolution.candidates
+              .map((profile) => `  ${profile.id}  ${profile.displayName}`)
+              .join('\n')}`
+          : `No agent answers to "${resolution.query}".`;
+      output(io, global.json, resolution, human);
+    });
+
+  agentCommand
+    .command('directory')
+    .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 human = entries.length
+        ? entries
+            .map((entry) => {
+              const runtimes = entry.runtimeBindings.length
+                ? entry.runtimeBindings
+                    .map(
+                      (binding) =>
+                        `    ${binding.runtime}${binding.profile ? `/${binding.profile}` : ''}` +
+                        // Last-seen is advisory, so it is labelled as an
+                        // observation rather than a status.
+                        `${binding.lastSeenAt ? `  last seen ${binding.lastSeenAt}` : '  not yet seen'}`,
+                    )
+                    .join('\n')
+                : '    no runtime bindings';
+              return `${entry.profile.id}  ${entry.profile.displayName}\n${runtimes}`;
+            })
+            .join('\n')
+        : 'No agents configured.';
+      output(io, global.json, { entries }, human);
+    });
+
+  const runtimeCommand = agentCommand.command('runtime').description('Record where an agent runs');
+
+  runtimeCommand
+    .command('bind <agent>')
+    .description('Bind an agent to a runtime')
+    .requiredOption('--runtime <name>', 'runtime family, e.g. claude-code')
+    .option('--profile <name>', 'named configuration within the runtime')
+    .option('--installation <id>', 'hosted installation this binding belongs to')
+    .action(
+      async (
+        agent: string,
+        options: { runtime: string; profile?: string; installation?: string },
+        command: Command,
+      ) => {
+        const global = globals(command);
+        const binding = await withClient(
+          global.home,
+          defaultActor(env, 'system', 'cli'),
+          (client) =>
+            client.agents.bindRuntime({
+              agentId: agent,
+              runtime: options.runtime,
+              ...(options.profile ? { profile: options.profile } : {}),
+              ...(options.installation ? { installationId: options.installation } : {}),
+            }),
+        );
+        output(
+          io,
+          global.json,
+          binding,
+          `Bound ${binding.agentId} to ${binding.runtime}${binding.profile ? `/${binding.profile}` : ''} (${binding.id})`,
+        );
+      },
+    );
+
+  runtimeCommand
+    .command('list <agent>')
+    .description('List an agent runtime bindings')
+    .action(async (agent: string, _options, command: Command) => {
+      const global = globals(command);
+      const bindings = await withClient(global.home, defaultActor(env, 'system', 'cli'), (client) =>
+        client.agents.bindings(agent),
+      );
+      const human = bindings.length
+        ? bindings
+            .map(
+              (binding) =>
+                `${binding.id}  ${binding.runtime}${binding.profile ? `/${binding.profile}` : ''}  bound ${binding.boundAt}`,
+            )
+            .join('\n')
+        : 'No runtime bindings.';
+      output(io, global.json, { bindings }, human);
+    });
+
+  runtimeCommand
+    .command('unbind <binding-id>')
+    .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),
+      );
+      output(
+        io,
+        global.json,
+        { removed },
+        removed ? `Removed binding ${bindingId}.` : `No binding ${bindingId}.`,
+      );
+    });
+
   const kudosCommand = program.command('kudos').description('Give and manage agent recognition');
 
   kudosCommand
@@ -797,7 +980,7 @@ export function createCli(
 
   program
     .command('inbox [agent]')
-    .description('Show pending kudos, memos, and todos for an agent')
+    .description('Show pending kudos, memos, and tasks for an agent')
     .option('--as <agent-id>', 'defaults to the positional agent')
     .option('--limit <number>', 'maximum results (default 10, maximum 50)', '10')
     .option('--cursor <cursor>', 'opaque cursor returned by the previous page')
@@ -835,8 +1018,10 @@ export function createCli(
   addListOptions(kudosCommand.command('list').description('List and filter kudos')).action(
     async (options: Record<string, string>, command: Command) => {
       const global = globals(command);
-      const page = await withClient(global.home, actor('human', 'local-cli'), (client) =>
-        client.kudos.list(listInput(options)),
+      const page = await withClient(
+        global.home,
+        defaultActor(env, 'human', 'local-cli'),
+        (client) => client.kudos.list(listInput(options)),
       );
       output(
         io,
@@ -852,7 +1037,7 @@ export function createCli(
   program
     .command('list')
     .description('List compact summaries across all record types')
-    .option('--kind <kind>', 'kudos, memo, note, or todo (repeatable)', collect, [])
+    .option('--kind <kind>', 'kudos, memo, note, or task (repeatable)', collect, [])
     .option('--participant <agent>')
     .option('--actor <id>')
     .option('--tag <tag>')
@@ -863,8 +1048,10 @@ export function createCli(
     .option('--offset <number>', 'deprecated offset', '0')
     .action(async (options: Record<string, string | string[]>, command: Command) => {
       const global = globals(command);
-      const page = await withClient(global.home, actor('human', 'local-cli'), (client) =>
-        client.items.list(itemListInput(options)),
+      const page = await withClient(
+        global.home,
+        defaultActor(env, 'human', 'local-cli'),
+        (client) => client.items.list(itemListInput(options)),
       );
       output(
         io,
@@ -885,12 +1072,15 @@ export function createCli(
     .action(
       async (options: { after?: string; limit: string; kind: string[] }, command: Command) => {
         const global = globals(command);
-        const page = await withClient(global.home, actor('human', 'local-cli'), (client) =>
-          client.items.changes({
-            limit: Number(options.limit),
-            ...(options.kind.length ? { kinds: options.kind as ItemListInput['kinds'] } : {}),
-            ...(options.after ? { after: options.after } : {}),
-          }),
+        const page = await withClient(
+          global.home,
+          defaultActor(env, 'human', 'local-cli'),
+          (client) =>
+            client.items.changes({
+              limit: Number(options.limit),
+              ...(options.kind.length ? { kinds: options.kind as ItemListInput['kinds'] } : {}),
+              ...(options.after ? { after: options.after } : {}),
+            }),
         );
         const human = page.items.length
           ? `${page.items
@@ -964,21 +1154,26 @@ export function createCli(
         command: Command,
       ) => {
         const global = globals(command);
-        const page = await withClient(global.home, actor('human', 'local-cli'), (client) =>
-          client.memos.list({
-            ...(options.participant ? { participantAgentId: options.participant } : {}),
-            ...(options.status ? { status: options.status } : {}),
-            limit: Number(options.limit),
-            ...(options.cursor ? { cursor: options.cursor } : {}),
-          }),
+        const page = await withClient(
+          global.home,
+          defaultActor(env, 'human', 'local-cli'),
+          (client) =>
+            client.memos.list({
+              ...(options.participant ? { participantAgentId: options.participant } : {}),
+              ...(options.status ? { status: options.status } : {}),
+              limit: Number(options.limit),
+              ...(options.cursor ? { cursor: options.cursor } : {}),
+            }),
         );
         output(io, global.json, page, page.items.map(lineForItem).join('\n') || 'No memos found.');
       },
     );
   memoCommand.command('show <memo-id>').action(async (id: string, _options, command: Command) => {
     const global = globals(command);
-    const record = await withClient(global.home, actor('human', 'local-cli'), (client) =>
-      client.memos.get(id),
+    const record = await withClient(
+      global.home,
+      defaultActor(env, 'human', 'local-cli'),
+      (client) => client.memos.get(id),
     );
     output(
       io,
@@ -1068,20 +1263,25 @@ export function createCli(
     .action(
       async (options: { owner?: string; status?: string; limit: string }, command: Command) => {
         const global = globals(command);
-        const page = await withClient(global.home, actor('human', 'local-cli'), (client) =>
-          client.notes.list({
-            ...(options.owner ? { participantAgentId: options.owner } : {}),
-            ...(options.status ? { status: options.status } : {}),
-            limit: Number(options.limit),
-          }),
+        const page = await withClient(
+          global.home,
+          defaultActor(env, 'human', 'local-cli'),
+          (client) =>
+            client.notes.list({
+              ...(options.owner ? { participantAgentId: options.owner } : {}),
+              ...(options.status ? { status: options.status } : {}),
+              limit: Number(options.limit),
+            }),
         );
         output(io, global.json, page, page.items.map(lineForItem).join('\n') || 'No notes found.');
       },
     );
   noteCommand.command('show <note-id>').action(async (id: string, _options, command: Command) => {
     const global = globals(command);
-    const record = await withClient(global.home, actor('human', 'local-cli'), (client) =>
-      client.notes.get(id),
+    const record = await withClient(
+      global.home,
+      defaultActor(env, 'human', 'local-cli'),
+      (client) => client.notes.get(id),
     );
     output(
       io,
@@ -1155,8 +1355,163 @@ export function createCli(
       },
     );
 
-  const todoCommand = program.command('todo').description('Create and manage agent todos');
+  const todoCommand = program
+    .command('todo')
+    .description('Create and manage your own private reminders');
   todoCommand
+    .command('create')
+    .requiredOption('--as <actor-id>')
+    .option('--actor-kind <kind>', 'human, agent, or system', 'agent')
+    .requiredOption('--title <title>')
+    .option('--details <text>', 'private working detail')
+    .option('--priority <number>', '1 highest, 4 lowest', '3')
+    .option('--due-date <date>')
+    .option('--due-at <datetime>')
+    .option('--time-zone <iana-zone>')
+    .option('--tag <tag>', 'tag (repeatable)', collect, [])
+    .option('--idempotency-key <key>')
+    .action(
+      async (
+        options: {
+          as: string;
+          actorKind: string;
+          title: string;
+          details?: string;
+          priority: string;
+          dueDate?: string;
+          dueAt?: string;
+          timeZone?: string;
+          tag: string[];
+          idempotencyKey?: string;
+        },
+        command: Command,
+      ) => {
+        const global = globals(command);
+        const result = await withClient(
+          global.home,
+          actor(options.actorKind, options.as),
+          (client) =>
+            client.todos.create({
+              title: options.title,
+              ...(options.details ? { details: options.details } : {}),
+              priority: Number(options.priority) as 1 | 2 | 3 | 4,
+              ...((due) => (due ? { due } : {}))(taskDue(options)),
+              ...(options.tag.length ? { tags: options.tag } : {}),
+              ...(options.idempotencyKey ? { idempotencyKey: options.idempotencyKey } : {}),
+            }),
+        );
+        output(
+          io,
+          global.json,
+          result,
+          `${result.deduplicated ? 'Found existing' : 'Created'} private todo\nTitle: ${result.record.current.title}\nID: ${result.record.event.id}`,
+        );
+      },
+    );
+  todoCommand
+    .command('list')
+    .requiredOption('--as <actor-id>')
+    .option('--actor-kind <kind>', 'human, agent, or system', 'agent')
+    .option('--status <status>')
+    .option('--limit <number>', 'maximum results', '10')
+    .action(
+      async (
+        options: { as: string; actorKind: string; status?: string; limit: string },
+        command: Command,
+      ) => {
+        const global = globals(command);
+        const page = await withClient(global.home, actor(options.actorKind, options.as), (client) =>
+          client.todos.list({
+            ...(options.status ? { status: options.status } : {}),
+            limit: Number(options.limit),
+          }),
+        );
+        output(
+          io,
+          global.json,
+          page,
+          page.items.length
+            ? page.items
+                .map((item) => `${item.id}  ${item.status.padEnd(9)}  ${item.title}`)
+                .join('\n')
+            : 'No todos.',
+        );
+      },
+    );
+  todoCommand
+    .command('show <todo-id>')
+    .requiredOption('--as <actor-id>')
+    .option('--actor-kind <kind>', 'human, agent, or system', 'agent')
+    .action(async (id: string, options: { as: string; actorKind: string }, command: Command) => {
+      const global = globals(command);
+      const record = await withClient(global.home, actor(options.actorKind, options.as), (client) =>
+        client.todos.get(id),
+      );
+      output(
+        io,
+        global.json,
+        record,
+        `${record.current.title}\nStatus: ${record.status}\nPriority: ${record.current.priority}\nVersion: ${record.current.version}${record.current.details ? `\n\n${record.current.details}` : ''}`,
+      );
+    });
+  for (const operation of ['complete', 'reopen', 'cancel', 'archive'] as const) {
+    todoCommand
+      .command(`${operation} <todo-id>`)
+      .requiredOption('--as <actor-id>')
+      .option('--actor-kind <kind>', 'human, agent, or system', 'agent')
+      .option('--note <text>')
+      .option('--reason <text>')
+      .option('--idempotency-key <key>')
+      .action(
+        async (
+          id: string,
+          options: {
+            as: string;
+            actorKind: string;
+            note?: string;
+            reason?: string;
+            idempotencyKey?: string;
+          },
+          command: Command,
+        ) => {
+          const global = globals(command);
+          const record = await withClient(
+            global.home,
+            actor(options.actorKind, options.as),
+            (client) =>
+              operation === 'complete'
+                ? client.todos.complete({
+                    todoId: id,
+                    ...(options.note ? { note: options.note } : {}),
+                    ...(options.idempotencyKey ? { idempotencyKey: options.idempotencyKey } : {}),
+                  })
+                : operation === 'cancel'
+                  ? client.todos.cancel({
+                      todoId: id,
+                      ...(options.reason ? { reason: options.reason } : {}),
+                      ...(options.idempotencyKey ? { idempotencyKey: options.idempotencyKey } : {}),
+                    })
+                  : operation === 'archive'
+                    ? client.todos.archive({
+                        todoId: id,
+                        ...(options.idempotencyKey
+                          ? { idempotencyKey: options.idempotencyKey }
+                          : {}),
+                      })
+                    : client.todos.reopen({
+                        todoId: id,
+                        ...(options.idempotencyKey
+                          ? { idempotencyKey: options.idempotencyKey }
+                          : {}),
+                      }),
+          );
+          output(io, global.json, record, `Todo ${id} is now ${record.status}.`);
+        },
+      );
+  }
+
+  const taskCommand = program.command('task').description('Create and manage agent tasks');
+  taskCommand
     .command('create <assignee>')
     .requiredOption('--from <actor-id>')
     .option('--actor-kind <kind>', 'human, agent, or system', 'agent')
@@ -1192,12 +1547,12 @@ export function createCli(
           global.home,
           actor(options.actorKind, options.from),
           (client) =>
-            client.todos.create({
+            client.tasks.create({
               assigneeAgentId: assignee,
               title: options.title,
               ...(options.description ? { description: options.description } : {}),
               priority: Number(options.priority) as 1 | 2 | 3 | 4,
-              ...((due) => (due ? { due } : {}))(todoDue(options)),
+              ...((due) => (due ? { due } : {}))(taskDue(options)),
               ...(options.tag.length ? { tags: options.tag } : {}),
               visibility: options.visibility,
               ...(options.idempotencyKey ? { idempotencyKey: options.idempotencyKey } : {}),
@@ -1207,11 +1562,11 @@ export function createCli(
           io,
           global.json,
           result,
-          `${result.deduplicated ? 'Found existing' : 'Created'} todo for ${result.record.event.assigneeDisplayName}\nTitle: ${result.record.current.title}\nID: ${result.record.event.id}`,
+          `${result.deduplicated ? 'Found existing' : 'Created'} task for ${result.record.event.assigneeDisplayName}\nTitle: ${result.record.current.title}\nID: ${result.record.event.id}`,
         );
       },
     );
-  todoCommand
+  taskCommand
     .command('list')
     .option('--assignee <agent>')
     .option('--status <status>')
@@ -1219,20 +1574,25 @@ export function createCli(
     .action(
       async (options: { assignee?: string; status?: string; limit: string }, command: Command) => {
         const global = globals(command);
-        const page = await withClient(global.home, actor('human', 'local-cli'), (client) =>
-          client.todos.list({
-            ...(options.assignee ? { participantAgentId: options.assignee } : {}),
-            ...(options.status ? { status: options.status } : {}),
-            limit: Number(options.limit),
-          }),
+        const page = await withClient(
+          global.home,
+          defaultActor(env, 'human', 'local-cli'),
+          (client) =>
+            client.tasks.list({
+              ...(options.assignee ? { participantAgentId: options.assignee } : {}),
+              ...(options.status ? { status: options.status } : {}),
+              limit: Number(options.limit),
+            }),
         );
-        output(io, global.json, page, page.items.map(lineForItem).join('\n') || 'No todos found.');
+        output(io, global.json, page, page.items.map(lineForItem).join('\n') || 'No tasks found.');
       },
     );
-  todoCommand.command('show <todo-id>').action(async (id: string, _options, command: Command) => {
+  taskCommand.command('show <task-id>').action(async (id: string, _options, command: Command) => {
     const global = globals(command);
-    const record = await withClient(global.home, actor('human', 'local-cli'), (client) =>
-      client.todos.get(id),
+    const record = await withClient(
+      global.home,
+      defaultActor(env, 'human', 'local-cli'),
+      (client) => client.tasks.get(id),
     );
     output(
       io,
@@ -1241,8 +1601,8 @@ export function createCli(
       `${record.current.title}\nID: ${record.event.id}\nStatus: ${record.status}\nVersion: ${record.current.version}`,
     );
   });
-  todoCommand
-    .command('update <todo-id>')
+  taskCommand
+    .command('update <task-id>')
     .requiredOption('--as <actor-id>')
     .option('--actor-kind <kind>', 'agent or human', 'agent')
     .requiredOption('--expected-version <number>')
@@ -1275,13 +1635,13 @@ export function createCli(
         command: Command,
       ) => {
         const global = globals(command);
-        const parsedDue = todoDue(options);
+        const parsedDue = taskDue(options);
         const record = await withClient(
           global.home,
           actor(options.actorKind, options.as),
           (client) =>
-            client.todos.update({
-              todoId: id,
+            client.tasks.update({
+              taskId: id,
               expectedVersion: Number(options.expectedVersion),
               ...(options.title ? { title: options.title } : {}),
               ...(options.description !== undefined ? { description: options.description } : {}),
@@ -1291,71 +1651,78 @@ export function createCli(
               ...(options.idempotencyKey ? { idempotencyKey: options.idempotencyKey } : {}),
             }),
         );
-        output(io, global.json, record, `Updated todo ${id} to version ${record.current.version}.`);
+        output(io, global.json, record, `Updated task ${id} to version ${record.current.version}.`);
       },
     );
   for (const operation of ['accept', 'reject', 'complete', 'reopen', 'cancel'] as const) {
-    todoCommand
-      .command(`${operation} <todo-id>`)
+    const command_ = taskCommand
+      .command(`${operation} <task-id>`)
       .requiredOption('--as <actor-id>')
       .option('--actor-kind <kind>', 'agent or human', 'agent')
       .option('--note <text>')
       .option('--reason <text>')
-      .option('--idempotency-key <key>')
-      .action(
-        async (
-          id: string,
-          options: {
-            as: string;
-            actorKind: string;
-            note?: string;
-            reason?: string;
-            idempotencyKey?: string;
-          },
-          command: Command,
-        ) => {
-          const global = globals(command);
-          const record = await withClient(
-            global.home,
-            actor(options.actorKind, options.as),
-            (client) =>
-              operation === 'accept'
-                ? client.todos.accept({
-                    todoId: id,
+      .option('--idempotency-key <key>');
+    // Rejecting requires saying why; accepting may. Marked required at the
+    // parser so the CLI refuses before touching the store.
+    if (operation === 'reject') {
+      command_.requiredOption('--response <text>', 'why the task is being refused');
+    } else if (operation === 'accept') {
+      command_.option('--response <text>', 'conditions, timing, or partial capability');
+    }
+    command_.action(
+      async (
+        id: string,
+        options: {
+          as: string;
+          actorKind: string;
+          note?: string;
+          reason?: string;
+          response?: string;
+          idempotencyKey?: string;
+        },
+        command: Command,
+      ) => {
+        const global = globals(command);
+        const record = await withClient(
+          global.home,
+          actor(options.actorKind, options.as),
+          (client) =>
+            operation === 'accept'
+              ? client.tasks.accept({
+                  taskId: id,
+                  ...(options.response ? { response: options.response } : {}),
+                  ...(options.idempotencyKey ? { idempotencyKey: options.idempotencyKey } : {}),
+                })
+              : operation === 'reject'
+                ? client.tasks.reject({
+                    taskId: id,
+                    response: options.response ?? options.reason ?? '',
                     ...(options.idempotencyKey ? { idempotencyKey: options.idempotencyKey } : {}),
                   })
-                : operation === 'reject'
-                  ? client.todos.reject({
-                      todoId: id,
-                      ...(options.reason ? { reason: options.reason } : {}),
+                : operation === 'complete'
+                  ? client.tasks.complete({
+                      taskId: id,
+                      ...(options.note ? { note: options.note } : {}),
                       ...(options.idempotencyKey ? { idempotencyKey: options.idempotencyKey } : {}),
                     })
-                  : operation === 'complete'
-                    ? client.todos.complete({
-                        todoId: id,
-                        ...(options.note ? { note: options.note } : {}),
+                  : operation === 'cancel'
+                    ? client.tasks.cancel({
+                        taskId: id,
+                        ...(options.reason ? { reason: options.reason } : {}),
                         ...(options.idempotencyKey
                           ? { idempotencyKey: options.idempotencyKey }
                           : {}),
                       })
-                    : operation === 'cancel'
-                      ? client.todos.cancel({
-                          todoId: id,
-                          ...(options.reason ? { reason: options.reason } : {}),
-                          ...(options.idempotencyKey
-                            ? { idempotencyKey: options.idempotencyKey }
-                            : {}),
-                        })
-                      : client.todos.reopen({
-                          todoId: id,
-                          ...(options.idempotencyKey
-                            ? { idempotencyKey: options.idempotencyKey }
-                            : {}),
-                        }),
-          );
-          output(io, global.json, record, `Todo ${id} is ${record.status}.`);
-        },
-      );
+                    : client.tasks.reopen({
+                        taskId: id,
+                        ...(options.idempotencyKey
+                          ? { idempotencyKey: options.idempotencyKey }
+                          : {}),
+                      }),
+        );
+        output(io, global.json, record, `Task ${id} is ${record.status}.`);
+      },
+    );
   }
 
   kudosCommand
@@ -1363,7 +1730,7 @@ 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, actor('system', 'cli'), (client) =>
+      const record = await withClient(global.home, defaultActor(env, 'system', 'cli'), (client) =>
         client.kudos.get(id),
       );
       output(io, global.json, record, showRecord(record));
@@ -1437,28 +1804,32 @@ export function createCli(
       ) => {
         const global = globals(command);
         if (!agentId) throw new SynomemError('INVALID_INPUT', 'Specify an agent.');
-        const details = await withClient(global.home, actor('system', 'cli'), async (client) => {
-          const profile = await client.agents.get(agentId);
-          const info = await client.info();
-          if (info.backend !== 'local') {
-            throw new SynomemError(
-              'INVALID_INPUT',
-              'Generated WINS.md files are available only with the local backend.',
-            );
-          }
-          const capabilities = await client.capabilities();
-          const path = join(info.home, profile.id, 'WINS.md');
-          if (!existsSync(path)) {
-            const hint = capabilities.projections.writeWinsMarkdown
-              ? 'Run `synomem rebuild` to generate it.'
-              : 'Enable projection.writeWinsMarkdown and run `synomem rebuild`.';
-            throw new SynomemError(
-              'INVALID_INPUT',
-              `No generated WINS.md exists for ${profile.id}. ${hint}`,
-            );
-          }
-          return { profile, path, content: readFileSync(path, 'utf8') };
-        });
+        const details = await withClient(
+          global.home,
+          defaultActor(env, 'system', 'cli'),
+          async (client) => {
+            const profile = await client.agents.get(agentId);
+            const info = await client.info();
+            if (info.backend !== 'local') {
+              throw new SynomemError(
+                'INVALID_INPUT',
+                'Generated WINS.md files are available only with the local backend.',
+              );
+            }
+            const capabilities = await client.capabilities();
+            const path = join(info.home, profile.id, 'WINS.md');
+            if (!existsSync(path)) {
+              const hint = capabilities.projections.writeWinsMarkdown
+                ? 'Run `synomem rebuild` to generate it.'
+                : 'Enable projection.writeWinsMarkdown and run `synomem rebuild`.';
+              throw new SynomemError(
+                'INVALID_INPUT',
+                `No generated WINS.md exists for ${profile.id}. ${hint}`,
+              );
+            }
+            return { profile, path, content: readFileSync(path, 'utf8') };
+          },
+        );
         if (options.open) {
           const commandName =
             process.platform === 'darwin'
@@ -1478,7 +1849,7 @@ 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, actor('system', 'cli'), (client) =>
+    const stats = await withClient(global.home, defaultActor(env, 'system', 'cli'), (client) =>
       client.stats(listInput(options)),
     );
     output(
@@ -1494,7 +1865,7 @@ 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, actor('system', 'cli'), (client) =>
+      const result = await withClient(global.home, defaultActor(env, 'system', 'cli'), (client) =>
         client.rebuild(),
       );
       output(
@@ -1510,7 +1881,7 @@ 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, actor('system', 'cli'), (client) => {
+      const path = await withClient(global.home, defaultActor(env, 'system', 'cli'), (client) => {
         if (!client.backup) {
           throw new SynomemError(
             'INVALID_INPUT',
@@ -1535,8 +1906,10 @@ export function createCli(
         command: Command,
       ) => {
         const global = globals(command);
-        const content = await withClient(global.home, actor('system', 'cli'), (client) =>
-          client.export(options.format),
+        const content = await withClient(
+          global.home,
+          defaultActor(env, 'system', 'cli'),
+          (client) => client.export(options.format),
         );
         if (options.output) {
           const destination = resolve(options.output);
@@ -1558,7 +1931,7 @@ export function createCli(
     .description('Run safe diagnostics')
     .action(async (_options, command: Command) => {
       const global = globals(command);
-      const result = await withClient(global.home, actor('system', 'cli'), (client) =>
+      const result = await withClient(global.home, defaultActor(env, 'system', 'cli'), (client) =>
         client.doctor(),
       );
       const human = result.diagnostics
@@ -1571,18 +1944,44 @@ export function createCli(
   program
     .command('mcp')
     .description('Run the actor-bound MCP server over stdio')
-    .requiredOption('--actor-id <id>')
-    .requiredOption('--actor-kind <kind>', 'human, agent, or system')
-    .option('--actor-name <display-name>')
+    .option('--agent-id <id>', 'bound agent, whose identity is read from Synomem')
+    .option('--actor-id <id>', 'bound non-agent actor ID')
+    .option('--actor-kind <kind>', 'human or system')
+    .option('--actor-name <display-name>', 'display name for a non-agent actor')
     .action(
       async (
-        options: { actorId: string; actorKind: string; actorName?: string },
+        options: { agentId?: string; actorId?: string; actorKind?: string; actorName?: string },
         command: Command,
       ) => {
         const global = globals(command);
+        // An agent's name comes from its profile, never from the command line:
+        // 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);
+            })
+          : undefined;
+        if (!bound && !(options.actorId && options.actorKind)) {
+          throw new SynomemError(
+            'INVALID_INPUT',
+            'Specify --agent-id, or --actor-id with --actor-kind for a non-agent actor.',
+          );
+        }
         await startMcpServer({
           ...(global.home ? { home: global.home } : {}),
-          actor: actor(options.actorKind, options.actorId, options.actorName),
+          actor: bound ?? actor(options.actorKind!, options.actorId!, options.actorName),
         });
       },
     );