synomem 0.5.3 → 0.6.1

package/dist/cli.js

@@ -8,8 +8,10 @@ import { configuredServiceFactory, readSynomemConfig, writeSynomemBackend } from
 import { cloudApiUrl } from './cloud.js';
 import { resolveHome } from './config.js';
 import { assertInteractive, confirmPlan, credentialFingerprint, credentialStoreChoices, environmentInstructions, readAccessToken, runConfigWizard, writeCredentialFile, } from './configure.js';
-import { discoverBoundWorkspace, discoverOrganizations, workspaceChoices } from './discover.js';
-import { defaultPromptIo } from './prompt.js';
+import { discoverAccessKeyWorkspaces, discoverOrganizations, workspaceChoices, } from './discover.js';
+import { DEFAULT_WORKSPACE, listLocalWorkspaces, localWorkspaceHome } from './workspaces.js';
+import { findProjectSelection, resolveWorkspaceSelection, writeProjectSelection, } from './project.js';
+import { defaultPromptIo, select } from './prompt.js';
 import { credentialReference, OsCredentialStore } from './credentials.js';
 import { asSynomemError, SynomemError } from './errors.js';
 import { atomicWriteFile } from './fs-utils.js';
@@ -61,11 +63,19 @@ function actor(kind, id, displayName) {
  * 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, fallbackKind, fallbackId) {
-    const id = env.SYNOMEM_ACTOR_ID?.trim();
+function defaultActor(env, fallbackKind, fallbackId, 
+/** `--actor`, which outranks the environment: it is said on this invocation. */
+override) {
+    const id = override?.trim() || 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());
+    const kind = override?.trim()
+        ? // An explicit --actor names an agent unless told otherwise; the historical
+            // fallbacks here are `system`/`cli`, which is not what somebody means when
+            // they name one.
+            env.SYNOMEM_ACTOR_KIND?.trim() || 'agent'
+        : env.SYNOMEM_ACTOR_KIND?.trim() || fallbackKind;
+    return actor(kind, id, env.SYNOMEM_ACTOR_NAME?.trim());
 }
 function taskDue(options) {
     if (options.dueDate && options.dueAt)
@@ -148,9 +158,28 @@ function showRecord(record) {
 function output(io, json, value, human) {
     io.stdout(json ? `${JSON.stringify(value, null, 2)}\n` : `${human}\n`);
 }
-function globals(command) {
-    return command.optsWithGlobals();
+/**
+ * The resolved global options for a command.
+ *
+ * `--workspace` is turned into a home HERE, before any service exists, which is
+ * the whole reason it costs nothing downstream: a local workspace is a separate
+ * database in its own home, and choosing one is choosing a home. Nothing in the
+ * domain, the commands, or the MCP tools learns that a workspace was selected.
+ *
+ * On a remote backend the name means a hosted workspace instead, which
+ * `backend use remote --workspace` already handles; passing both here would be
+ * two different answers to the same question, so it is refused.
+ */
+/** `parent child`, so a subcommand name cannot be confused with another's. */
+function commandPath(command) {
+    const parent = command.parent?.name();
+    return parent && parent !== 'synomem' ? `${parent} ${command.name()}` : command.name();
 }
+/**
+ * Commands where `--workspace` names a HOSTED workspace being configured,
+ * rather than a local one to act in.
+ */
+const CONFIGURES_BACKEND = new Set(['config init', 'backend use', 'remote import']);
 async function withService(serviceFactory, home, configuredActor, operation) {
     const client = serviceFactory({ ...(home ? { home } : {}), actor: configuredActor });
     await client.init();
@@ -195,11 +224,80 @@ function listInput(options) {
         offset: Number(options.offset),
     };
 }
-export function createCli(io = defaultIo, serviceFactory = configuredServiceFactory, dependencies = {}) {
+/**
+ * The value `--actor` should supply to commands that name an actor.
+ *
+ * Read from argv directly, before the commands are built, because Commander
+ * evaluates option defaults at DECLARATION time: a `--as` declared without one
+ * is required, and a `--as` declared with one is already satisfied. Supplying
+ * it here is a single change point instead of a fallback threaded through
+ * twenty action bodies, and `--as` still wins when both are given because an
+ * explicitly passed option overrides its default.
+ */
+function actorDefault(argv, env) {
+    for (let index = 0; index < argv.length; index += 1) {
+        const argument = argv[index];
+        if (argument === '--actor')
+            return argv[index + 1]?.trim() || undefined;
+        if (argument.startsWith('--actor='))
+            return argument.slice('--actor='.length).trim() || undefined;
+    }
+    if (env.SYNOMEM_ACTOR_ID?.trim())
+        return env.SYNOMEM_ACTOR_ID.trim();
+    /*
+     * Last, the project's own binding. `workspace use --as` exists so a
+     * repository can settle both questions once — which workspace, and as whom —
+     * and a command run there needs neither flag afterwards.
+     */
+    try {
+        return findProjectSelection()?.actor;
+    }
+    catch {
+        // A malformed project file is reported by the resolver when the command
+        // actually runs, with the path in the message. Failing here would turn it
+        // into an error before any command had been parsed.
+        return undefined;
+    }
+}
+export function createCli(io = defaultIo, serviceFactory = configuredServiceFactory, dependencies = {}, argv = process.argv) {
     const env = dependencies.env ?? process.env;
+    const actingDefault = actorDefault(argv, env);
+    const globals = (command) => {
+        const options = command.optsWithGlobals();
+        if (CONFIGURES_BACKEND.has(commandPath(command)))
+            return options;
+        /*
+         * Resolution runs even with no `--workspace`, because a project's
+         * `.synomem/config.json` selects one without anybody passing a flag — that is
+         * the whole point of it. `--home` still wins outright: it names a home
+         * directly rather than a workspace within one.
+         */
+        if (!options.home) {
+            const selection = resolveWorkspaceSelection({
+                ...(options.workspace ? { flag: options.workspace } : {}),
+                ...(options.actor ? { actorFlag: options.actor } : {}),
+                env,
+            });
+            return { ...options, home: selection.home, actor: selection.actor ?? options.actor };
+        }
+        if (!options.workspace)
+            return options;
+        /*
+         * One flag, one meaning — "which workspace" — resolved differently by the
+         * handful of commands that CONFIGURE a backend rather than act inside one.
+         * For those, the value is a hosted workspace ID to be written to the config,
+         * so it is passed through raw and they read `workspace`. Everywhere else it
+         * names a local workspace, which is a home.
+         *
+         * These commands used to declare their own `--workspace`, which does not
+         * work: Commander gives a duplicated long flag to the parent, so the
+         * subcommand never received it at all.
+         */
+        return { ...options, home: localWorkspaceHome(options.workspace, options.home) };
+    };
     const credentialStore = dependencies.credentialStore ?? new OsCredentialStore();
     const oauthLogin = dependencies.oauthLogin ?? loginWithOAuth;
-    const discoverWorkspace = dependencies.discoverBoundWorkspace ?? discoverBoundWorkspace;
+    const discoverWorkspaces = dependencies.discoverAccessKeyWorkspaces ?? discoverAccessKeyWorkspaces;
     const promptIo = dependencies.promptIo ?? defaultPromptIo();
     const verifyRemoteCredential = dependencies.verifyRemoteCredential ??
         (async (options) => {
@@ -224,9 +322,86 @@ export function createCli(io = defaultIo, serviceFactory = configuredServiceFact
         .description('Local-first communication, memory, recognition, and task infrastructure for agents')
         .version(packageVersion())
         .option('--home <path>', 'storage root (defaults to SYNOMEM_HOME or ~/.synomem)')
+        // A local workspace is its own database under the root, so this selects a
+        // home. On a remote backend the hosted workspace is chosen by
+        // `backend use remote --workspace` instead.
+        .option('--workspace <name>', 'local workspace to act in (see `synomem workspace list`)')
+        .option('--actor <id>', 'act as this agent (overrides SYNOMEM_ACTOR_ID)')
         .option('--json', 'emit stable machine-readable JSON', false)
         .showSuggestionAfterError()
         .configureOutput({ writeOut: io.stdout, writeErr: io.stderr });
+    /*
+     * Local workspaces.
+     *
+     * Each is a separate database in its own home, which is what makes the
+     * isolation real: SQLite has no row-level security, so a shared file would
+     * rest on every query remembering to filter, with nothing to catch a miss.
+     * Separate files mean cross-workspace leakage is not something anybody can
+     * write by accident.
+     */
+    const workspaceCommand = program
+        .command('workspace')
+        .description('Work in a separate local store, isolated from the others');
+    workspaceCommand
+        .command('list')
+        .description('List the local workspaces on this machine')
+        .action((_options, command) => {
+        const global = globals(command);
+        // Read from disk, so nothing is listed that does not exist.
+        const workspaces = listLocalWorkspaces(global.home);
+        // Which one is in effect here, and what decided it — a flag, the
+        // environment, a project file, or nothing.
+        const selection = resolveWorkspaceSelection({ env });
+        const human = workspaces
+            .map((workspace) => `${workspace.name === DEFAULT_WORKSPACE ? '*' : ' '} ${workspace.name.padEnd(24)} ${workspace.initialized ? workspace.home : `${workspace.home} (not initialized)`}`)
+            .join('\n');
+        output(io, global.json, { workspaces, active: selection.workspace ?? DEFAULT_WORKSPACE, source: selection.source }, [
+            human,
+            '',
+            `Acting in: ${selection.workspace ?? DEFAULT_WORKSPACE}  (from ${selection.source})`,
+            '',
+            'Bind a directory with `synomem workspace use <name>`, or pass --workspace once.',
+            'A local workspace is a separate store on this machine; a hosted workspace is shared,',
+            'and is selected with `backend use remote --workspace`.',
+        ].join('\n'));
+    });
+    workspaceCommand
+        .command('use <name>')
+        .description('Bind this directory to a workspace, for every session opened here')
+        .option('--as <actor-id>', 'also always write as this agent', actingDefault)
+        .action((name, options, command) => {
+        const global = globals(command);
+        // Validated by resolving it, so a name that could never work is refused
+        // before a file claiming it is written.
+        const home = localWorkspaceHome(name, undefined);
+        const path = writeProjectSelection(process.cwd(), {
+            workspace: name,
+            ...(options.as ? { actor: options.as } : {}),
+        });
+        output(io, global.json, { path, workspace: name, home, ...(options.as ? { actor: options.as } : {}) }, [
+            `Wrote ${path}`,
+            '',
+            `Every Synomem command and MCP server started in this directory now acts in ${name}${options.as ? ` as ${options.as}` : ''}, with no flag.`,
+            `Records live in ${home} — nothing is stored in this directory.`,
+            '',
+            'Commit it to share the choice with the repository, or ignore it to keep it yours.',
+        ].join('\n'));
+    });
+    workspaceCommand
+        .command('create <name>')
+        .description('Create a local workspace and initialize its store')
+        .action(async (name, _options, command) => {
+        const global = globals(command);
+        const home = localWorkspaceHome(name, global.home);
+        if (readSynomemConfig(home)) {
+            throw new SynomemError('INVALID_INPUT', `Workspace already exists: ${name}`);
+        }
+        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);
+        output(io, global.json, { name, home }, `Created workspace ${name} at ${home}.\nAct in it with --workspace ${name}.`);
+    });
     const remoteCommand = program.command('remote').description('Administer a remote workspace');
     /*
      * The browser counterpart to an access key naming its own workspace.
@@ -347,18 +522,43 @@ export function createCli(io = defaultIo, serviceFactory = configuredServiceFact
         const home = plan.home;
         const serviceUrl = plan.serviceUrl ?? cloudApiUrl(env);
         /*
-         * The workspace is discovered, not typed.
-         *
-         * An installation access key is bound to exactly one workspace, so the
-         * service can be asked which one rather than the person. An explicit
-         * --workspace still wins, because automation should not depend on a
-         * network round trip to configure a machine.
+         * A member-owned access key reaches every workspace in its organization,
+         * never just one, so the workspace is discovered and then chosen — not
+         * typed from memory, and not assumed. An explicit --workspace still wins
+         * regardless: automation should not depend on a network round trip, and a
+         * person who already knows which one they want should not be asked again.
          */
         let workspaceId = plan.workspaceId;
         if (plan.backend === 'remote' && !workspaceId && token) {
-            const bound = await discoverWorkspace({ baseUrl: serviceUrl, accessToken: token });
-            workspaceId = bound.workspaceId;
-            io.stdout(`Access key is bound to workspace ${workspaceId}.\n`);
+            const discovered = await discoverWorkspaces({ baseUrl: serviceUrl, accessToken: token });
+            if (discovered.workspaces.length === 0) {
+                throw new SynomemError('INVALID_INPUT', [
+                    "This access key's organization has no workspaces yet.",
+                    'Create one in the Synomem portal, then re-run this command — or pass',
+                    '--workspace <workspace-id> once one exists.',
+                ].join('\n'));
+            }
+            else if (discovered.workspaces.length === 1) {
+                workspaceId = discovered.workspaces[0].id;
+                io.stdout(`Using this key's only workspace: ${discovered.workspaces[0].displayName} (${workspaceId}).\n`);
+            }
+            else if (promptIo.interactive) {
+                workspaceId = await select(promptIo, 'Which workspace should this machine use?', discovered.workspaces.map((workspace) => ({
+                    value: workspace.id,
+                    label: workspace.displayName,
+                    detail: workspace.id,
+                })));
+            }
+            else {
+                throw new SynomemError('INVALID_INPUT', [
+                    'This access key can reach more than one workspace, so a non-interactive',
+                    'setup needs to be told which one:',
+                    '',
+                    ...discovered.workspaces.map((workspace) => `  ${workspace.id}  ${workspace.displayName}`),
+                    '',
+                    'Re-run with --workspace <workspace-id>.',
+                ].join('\n'));
+            }
         }
         if (plan.backend === 'remote' && !workspaceId) {
             /*
@@ -449,7 +649,6 @@ export function createCli(io = defaultIo, serviceFactory = configuredServiceFact
         .description('Configure Synomem without prompting')
         .option('--backend <kind>', 'local or remote')
         .option('--auth <method>', 'browser or access-key')
-        .option('--workspace <id>', 'remote workspace ID')
         .option('--credential-store <where>', 'auto, keychain, file, or environment', 'auto')
         // The token is read from stdin, never taken as an argument: an argument is
         // kept by the shell history and visible in the process list.
@@ -461,10 +660,10 @@ export function createCli(io = defaultIo, serviceFactory = configuredServiceFact
             throw new SynomemError('INVALID_INPUT', 'Pass --backend local or --backend remote.');
         }
         const backend = options.backend;
-        // An access key names its own workspace, so --workspace is only
-        // required when there is no key to ask.
-        if (backend === 'remote' && !options.workspace && !options.accessTokenStdin) {
-            throw new SynomemError('INVALID_INPUT', 'Remote setup requires --workspace, or --access-token-stdin so the key can name its own.');
+        // An access key can be asked which workspaces it reaches, so
+        // --workspace is only required when there is no key to ask.
+        if (backend === 'remote' && !global.workspace && !options.accessTokenStdin) {
+            throw new SynomemError('INVALID_INPUT', 'Remote setup requires --workspace, or --access-token-stdin so the key can be asked.');
         }
         const token = options.accessTokenStdin ? await readAccessToken(promptIo) : undefined;
         if (backend === 'remote' && options.auth === 'access-key' && !token) {
@@ -477,7 +676,7 @@ export function createCli(io = defaultIo, serviceFactory = configuredServiceFact
                 ? {
                     serviceUrl: cloudApiUrl(env),
                     auth: options.auth ?? 'access-key',
-                    workspaceId: options.workspace,
+                    workspaceId: global.workspace,
                     credentialStore: options.credentialStore,
                 }
                 : {}),
@@ -594,13 +793,12 @@ export function createCli(io = defaultIo, serviceFactory = configuredServiceFact
         // never ask for a service address, because a person has no way to tell a
         // real one from a phished one.
         .option('--url <url>', 'internal: alternate HTTPS origin')
-        .option('--workspace <id>', 'remote workspace ID')
         .action((kind, options, command) => {
         const global = globals(command);
         if (kind !== 'local' && kind !== 'remote') {
             throw new SynomemError('INVALID_INPUT', 'Backend kind must be local or remote.');
         }
-        if (kind === 'remote' && !options.workspace) {
+        if (kind === 'remote' && !global.workspace) {
             throw new SynomemError('INVALID_INPUT', 'Remote backend selection requires --workspace.');
         }
         const config = writeSynomemBackend(kind === 'local'
@@ -608,7 +806,7 @@ export function createCli(io = defaultIo, serviceFactory = configuredServiceFact
             : {
                 kind: 'remote',
                 baseUrl: options.url ?? cloudApiUrl(env),
-                workspaceId: options.workspace,
+                workspaceId: global.workspace,
             }, global.home);
         output(io, global.json, { backend: config.backend }, `Selected ${config.backend.kind} Synomem backend.`);
     });
@@ -1066,7 +1264,7 @@ export function createCli(io = defaultIo, serviceFactory = configuredServiceFact
     postCommand
         .command('create')
         .description('Publish a post the whole workspace can read')
-        .requiredOption('--as <actor-id>')
+        .requiredOption('--as <actor-id>', 'actor to act as (defaults to --actor)', actingDefault)
         .option('--actor-kind <kind>', 'human, agent, or system', 'agent')
         .requiredOption('--title <title>')
         .requiredOption('--body <body>')
@@ -1085,7 +1283,7 @@ export function createCli(io = defaultIo, serviceFactory = configuredServiceFact
     postCommand
         .command('list')
         .description('List posts in this workspace')
-        .requiredOption('--as <actor-id>')
+        .requiredOption('--as <actor-id>', 'actor to act as (defaults to --actor)', actingDefault)
         .option('--actor-kind <kind>', 'human, agent, or system', 'agent')
         .option('--limit <n>', 'default 10, maximum 50')
         .action(async (options, command) => {
@@ -1099,7 +1297,7 @@ export function createCli(io = defaultIo, serviceFactory = configuredServiceFact
     postCommand
         .command('show <post-id>')
         .description('Show one post with its acknowledgements')
-        .requiredOption('--as <actor-id>')
+        .requiredOption('--as <actor-id>', 'actor to act as (defaults to --actor)', actingDefault)
         .option('--actor-kind <kind>', 'human, agent, or system', 'agent')
         .action(async (postId, options, command) => {
         const global = globals(command);
@@ -1114,7 +1312,7 @@ export function createCli(io = defaultIo, serviceFactory = configuredServiceFact
     postCommand
         .command('acknowledge <post-id>')
         .description('Say you have seen a post')
-        .requiredOption('--as <actor-id>')
+        .requiredOption('--as <actor-id>', 'actor to act as (defaults to --actor)', actingDefault)
         .option('--actor-kind <kind>', 'human, agent, or system', 'agent')
         .option('--note <text>', 'optional context for the author')
         .action(async (postId, options, command) => {
@@ -1128,7 +1326,7 @@ export function createCli(io = defaultIo, serviceFactory = configuredServiceFact
     postCommand
         .command('roster <post-id>')
         .description('Who has acknowledged a post, and who has not')
-        .requiredOption('--as <actor-id>')
+        .requiredOption('--as <actor-id>', 'actor to act as (defaults to --actor)', actingDefault)
         .option('--actor-kind <kind>', 'human, agent, or system', 'agent')
         .action(async (postId, options, command) => {
         const global = globals(command);
@@ -1153,7 +1351,7 @@ export function createCli(io = defaultIo, serviceFactory = configuredServiceFact
     postCommand
         .command('archive <post-id>')
         .description('Archive a post you wrote')
-        .requiredOption('--as <actor-id>')
+        .requiredOption('--as <actor-id>', 'actor to act as (defaults to --actor)', actingDefault)
         .option('--actor-kind <kind>', 'human, agent, or system', 'agent')
         .option('--reason <text>')
         .action(async (postId, options, command) => {
@@ -1165,7 +1363,7 @@ export function createCli(io = defaultIo, serviceFactory = configuredServiceFact
     kudosCommand
         .command('give <recipient>')
         .description('Give specific, evidence-based kudos to an agent')
-        .requiredOption('--from <actor-id>', 'stable ID of the giver')
+        .requiredOption('--from <actor-id>', 'stable ID of the giver (defaults to --actor)', actingDefault)
         .requiredOption('--actor-kind <kind>', 'human, agent, or system')
         .option('--actor-name <display-name>')
         .requiredOption('--title <title>')
@@ -1258,7 +1456,7 @@ export function createCli(io = defaultIo, serviceFactory = configuredServiceFact
     const memoCommand = program.command('memo').description('Send and manage durable messages');
     memoCommand
         .command('send <recipient>')
-        .requiredOption('--from <actor-id>')
+        .requiredOption('--from <actor-id>', 'actor to act as (defaults to --actor)', actingDefault)
         .option('--actor-kind <kind>', 'human, agent, or system', 'agent')
         .option('--actor-name <name>')
         .requiredOption('--subject <subject>')
@@ -1319,7 +1517,7 @@ export function createCli(io = defaultIo, serviceFactory = configuredServiceFact
         .description('Retain and revise agent-owned knowledge');
     noteCommand
         .command('create')
-        .requiredOption('--as <actor-id>')
+        .requiredOption('--as <actor-id>', 'actor to act as (defaults to --actor)', actingDefault)
         .option('--actor-kind <kind>', 'agent or human', 'agent')
         .option('--owner <agent-id>')
         .requiredOption('--title <title>')
@@ -1358,7 +1556,7 @@ export function createCli(io = defaultIo, serviceFactory = configuredServiceFact
     });
     noteCommand
         .command('revise <note-id>')
-        .requiredOption('--as <actor-id>')
+        .requiredOption('--as <actor-id>', 'actor to act as (defaults to --actor)', actingDefault)
         .option('--actor-kind <kind>', 'agent or human', 'agent')
         .requiredOption('--expected-version <number>')
         .option('--title <title>')
@@ -1379,7 +1577,7 @@ export function createCli(io = defaultIo, serviceFactory = configuredServiceFact
     });
     noteCommand
         .command('archive <note-id>')
-        .requiredOption('--as <actor-id>')
+        .requiredOption('--as <actor-id>', 'actor to act as (defaults to --actor)', actingDefault)
         .option('--actor-kind <kind>', 'agent or human', 'agent')
         .option('--idempotency-key <key>')
         .action(async (id, options, command) => {
@@ -1395,7 +1593,7 @@ export function createCli(io = defaultIo, serviceFactory = configuredServiceFact
         .description('Create and manage your own private reminders');
     todoCommand
         .command('create')
-        .requiredOption('--as <actor-id>')
+        .requiredOption('--as <actor-id>', 'actor to act as (defaults to --actor)', actingDefault)
         .option('--actor-kind <kind>', 'human, agent, or system', 'agent')
         .requiredOption('--title <title>')
         .option('--details <text>', 'private working detail')
@@ -1419,7 +1617,7 @@ export function createCli(io = defaultIo, serviceFactory = configuredServiceFact
     });
     todoCommand
         .command('list')
-        .requiredOption('--as <actor-id>')
+        .requiredOption('--as <actor-id>', 'actor to act as (defaults to --actor)', actingDefault)
         .option('--actor-kind <kind>', 'human, agent, or system', 'agent')
         .option('--status <status>')
         .option('--limit <number>', 'maximum results', '10')
@@ -1437,7 +1635,7 @@ export function createCli(io = defaultIo, serviceFactory = configuredServiceFact
     });
     todoCommand
         .command('show <todo-id>')
-        .requiredOption('--as <actor-id>')
+        .requiredOption('--as <actor-id>', 'actor to act as (defaults to --actor)', actingDefault)
         .option('--actor-kind <kind>', 'human, agent, or system', 'agent')
         .action(async (id, options, command) => {
         const global = globals(command);
@@ -1447,7 +1645,7 @@ export function createCli(io = defaultIo, serviceFactory = configuredServiceFact
     for (const operation of ['complete', 'reopen', 'cancel', 'archive']) {
         todoCommand
             .command(`${operation} <todo-id>`)
-            .requiredOption('--as <actor-id>')
+            .requiredOption('--as <actor-id>', 'actor to act as (defaults to --actor)', actingDefault)
             .option('--actor-kind <kind>', 'human, agent, or system', 'agent')
             .option('--note <text>')
             .option('--reason <text>')
@@ -1485,7 +1683,7 @@ export function createCli(io = defaultIo, serviceFactory = configuredServiceFact
     const taskCommand = program.command('task').description('Create and manage agent tasks');
     taskCommand
         .command('create <assignee>')
-        .requiredOption('--from <actor-id>')
+        .requiredOption('--from <actor-id>', 'actor to act as (defaults to --actor)', actingDefault)
         .option('--actor-kind <kind>', 'human, agent, or system', 'agent')
         .requiredOption('--title <title>')
         .option('--description <text>')
@@ -1531,7 +1729,7 @@ export function createCli(io = defaultIo, serviceFactory = configuredServiceFact
     });
     taskCommand
         .command('update <task-id>')
-        .requiredOption('--as <actor-id>')
+        .requiredOption('--as <actor-id>', 'actor to act as (defaults to --actor)', actingDefault)
         .option('--actor-kind <kind>', 'agent or human', 'agent')
         .requiredOption('--expected-version <number>')
         .option('--title <title>')
@@ -1561,7 +1759,7 @@ export function createCli(io = defaultIo, serviceFactory = configuredServiceFact
     for (const operation of ['accept', 'reject', 'complete', 'reopen', 'cancel']) {
         const command_ = taskCommand
             .command(`${operation} <task-id>`)
-            .requiredOption('--as <actor-id>')
+            .requiredOption('--as <actor-id>', 'actor to act as (defaults to --actor)', actingDefault)
             .option('--actor-kind <kind>', 'agent or human', 'agent')
             .option('--note <text>')
             .option('--reason <text>')
@@ -1637,7 +1835,7 @@ export function createCli(io = defaultIo, serviceFactory = configuredServiceFact
     kudosCommand
         .command('revoke <kudos-id>')
         .description('Record a revocation while preserving history')
-        .requiredOption('--as <actor-id>')
+        .requiredOption('--as <actor-id>', 'actor to act as (defaults to --actor)', actingDefault)
         .option('--actor-kind <kind>', 'human, agent, or system', 'human')
         .requiredOption('--reason <reason>')
         .option('--administrative', 'mark as an administrative revocation', false)
@@ -1779,7 +1977,7 @@ export function createCli(io = defaultIo, serviceFactory = configuredServiceFact
     return program;
 }
 export async function runCli(argv = process.argv, io = defaultIo, serviceFactory = configuredServiceFactory, dependencies = {}) {
-    const program = createCli(io, serviceFactory, dependencies);
+    const program = createCli(io, serviceFactory, dependencies, argv);
     program.exitOverride();
     try {
         await program.parseAsync(argv);