@skrr-ai/cli 0.1.44 → 0.1.46

package/dist/base-command.d.ts

@@ -311,14 +311,26 @@ export declare abstract class BaseCommand extends Command {
         body: unknown;
         idempotencyKey: string;
     }): never;
-    protected failWithCliError({ message, code, status, exit, retryable, details, }: {
+    protected failWithCliError({ message, code, status, exit, retryable, details, requestId, }: {
         message: string;
         code: string;
         status?: number;
         exit: number;
         retryable: boolean;
         details?: unknown;
+        /** The server's `X-Request-ID` for the refused call, when there was one. */
+        requestId?: string;
     }): never;
+    /**
+     * The server's `X-Request-ID` for the most recent refused API call.
+     *
+     * The CLI prints its own refusals but not the id the server logged them
+     * against, so matching one to a log line meant guessing from timestamps. On
+     * an account with several clients that misattributes: a 409 raised by
+     * another session's concurrent image update was nearly filed as a CLI retry
+     * bug (2026-09-18).
+     */
+    private lastApiRequestId?;
     private writeJsonCliError;
     protected wantsJsonOutput(): boolean;
 }

package/dist/base-command.js

@@ -853,9 +853,26 @@ class BaseCommand extends core_1.Command {
      * envelope carry the same identifying text.
      */
     handleApiError(err, { subject } = {}) {
+        // An error this command already raised for the user is not an API failure
+        // to translate. `this.error()` throws a CLIError carrying `oclif.exit`, and
+        // under --json it is the ExitError thrown AFTER `writeJsonCliError` already
+        // printed the envelope. When the raise sits inside the try whose catch is
+        // this call, re-wrapping it printed a SECOND envelope (`--json` saw the
+        // real message followed by `EEXIT: 1`) and rewrote the caller's exit code
+        // to 1 — `agents actions create --prompt ""` did exactly that. Pass it
+        // through so `catch()` renders it once, with its code and exit intact.
+        if (err instanceof Error) {
+            const raised = err;
+            if (isOclifExitError(raised) || typeof raised.oclif?.exit === 'number') {
+                throw err;
+            }
+        }
         const say = (message) => withSubject(subject, message);
         if (err instanceof Error) {
             const e = err;
+            // Remembered once here rather than threaded through every branch below:
+            // each one ends in `failWithCliError`, and the id belongs on all of them.
+            this.lastApiRequestId = e.requestId;
             const body = parseErrorBody(e.body);
             const bodyCode = stringProp(body, 'code') || stringProp(body, 'errorType');
             const bodyMessage = stringProp(body, 'message') || stringProp(body, 'error');
@@ -1242,9 +1259,9 @@ class BaseCommand extends core_1.Command {
             details: { outboxId: queuedId, idempotencyKey: write.idempotencyKey },
         });
     }
-    failWithCliError({ message, code, status, exit, retryable, details, }) {
+    failWithCliError({ message, code, status, exit, retryable, details, requestId, }) {
         if (this.wantsJsonOutput()) {
-            this.writeJsonCliError({ message, code, status, exit, retryable, details });
+            this.writeJsonCliError({ message, code, status, exit, retryable, details, requestId });
         }
         // Human path. Deliberately stderr-only: stdout is the SUCCESS channel, so
         // `id=$(skrr tasks start "$x")` and `sky ... | jq` are never fed error
@@ -1277,7 +1294,17 @@ class BaseCommand extends core_1.Command {
             ...(suggestion ? { suggestions: [suggestion] } : {}),
         });
     }
-    writeJsonCliError({ message, code, status, exit, retryable, details, }) {
+    /**
+     * The server's `X-Request-ID` for the most recent refused API call.
+     *
+     * The CLI prints its own refusals but not the id the server logged them
+     * against, so matching one to a log line meant guessing from timestamps. On
+     * an account with several clients that misattributes: a 409 raised by
+     * another session's concurrent image update was nearly filed as a CLI retry
+     * bug (2026-09-18).
+     */
+    lastApiRequestId;
+    writeJsonCliError({ message, code, status, exit, retryable, details, requestId, }) {
         this.log(JSON.stringify({
             ok: false,
             error: {
@@ -1287,6 +1314,13 @@ class BaseCommand extends core_1.Command {
                 retryable,
                 command: this.id ?? null,
                 server: this.cliConfig?.baseURL ?? null,
+                // The id the server logged this refusal against. Without it, a
+                // refused call can only be matched to a log line by guessing from
+                // timestamps — which, with several clients on one account,
+                // attributes another session's request to yours.
+                ...(requestId || this.lastApiRequestId
+                    ? { requestId: requestId ?? this.lastApiRequestId }
+                    : {}),
                 ...(details ? { details } : {}),
             },
         }, null, 2));

package/dist/commands/agents/actions/create.js

@@ -81,8 +81,11 @@ class AgentsActionsCreate extends base_command_1.BaseCommand {
         let replayed = false;
         try {
             const title = typeof body.title === 'string' ? body.title.trim() : '';
-            if (!title)
-                this.error('Action title is required. Pass --title or include title.', { exit: 1 });
+            if (!title) {
+                this.error(typeof body.title === 'string'
+                    ? 'The action title was provided but is empty. Pass non-empty text to --title or title in --from-json.'
+                    : 'Action title is required. Pass --title or include title.', { exit: 1 });
+            }
             const kind = body.kind === 'builtin' ? 'builtin' : 'prompt';
             // No read of the library: position is assigned by the server at the
             // moment of the append, so it cannot be computed from a stale copy. An
@@ -97,7 +100,9 @@ class AgentsActionsCreate extends base_command_1.BaseCommand {
             if (kind === 'builtin') {
                 const builtinType = body.builtinType;
                 if (!agent_actions_1.BUILTIN_ACTION_TYPES.includes(builtinType)) {
-                    this.error(`--builtin-type is required for built-in actions.`, { exit: 1 });
+                    this.error(builtinType === undefined
+                        ? '--builtin-type is required for built-in actions.'
+                        : `Invalid --builtin-type "${String(builtinType)}" — expected one of ${agent_actions_1.BUILTIN_ACTION_TYPES.join(', ')}.`, { exit: 1 });
                 }
                 created = (0, agent_actions_1.makeBuiltinAction)({
                     scope,
@@ -118,7 +123,9 @@ class AgentsActionsCreate extends base_command_1.BaseCommand {
             else {
                 const prompt = typeof body.prompt === 'string' ? body.prompt : '';
                 if (!prompt.trim()) {
-                    this.error('Prompt actions require --prompt or prompt in --from-json.', { exit: 1 });
+                    this.error(typeof body.prompt === 'string'
+                        ? 'The prompt was provided but is empty. Pass non-empty text to --prompt or prompt in --from-json.'
+                        : 'Prompt actions require --prompt or prompt in --from-json.', { exit: 1 });
                 }
                 // Embedded built-in actions (chip source of truth). The prompt keeps the
                 // inline `[[action:refId]]` tokens (positional); the server expands each

package/dist/commands/agents/chat.js

@@ -235,7 +235,9 @@ class AgentsChat extends base_command_1.BaseCommand {
             description: 'Emit the final one-shot response as JSON (use with --no-stream)',
         }),
         'approve-tools': core_1.Flags.boolean({
-            description: 'Prompt interactively before approving tool calls',
+            description: 'Allow this turn to use permission-gated tools. In a terminal it asks per call; ' +
+                'with no terminal the flag itself is the approval for this turn, and each one is ' +
+                'reported on the stream. Without it every such call is denied.',
         }),
         'local-skill': core_1.Flags.string({
             description: 'Invoke a skill on your machine on this turn, as `skrr skills local` lists it: its ' +
@@ -333,9 +335,6 @@ class AgentsChat extends base_command_1.BaseCommand {
             this.error('--local-skill has no meaning with --quick: the persona-only summarizer runs no ' +
                 'runtime, so no skill on your machine can load. Drop --quick for a real turn.', { exit: 2 });
         }
-        if (flags['approve-tools'] && !process.stdin.isTTY) {
-            this.error('--approve-tools requires an interactive terminal.', { exit: 2 });
-        }
         if (flags.conversation && flags['thread-root']) {
             this.error('--conversation and --thread-root are mutually exclusive.', { exit: 2 });
         }

package/dist/commands/browser/cloud-agents.d.ts

@@ -0,0 +1,20 @@
+import { Command } from '@oclif/core';
+/**
+ * Whether a cloud agent may drive the browser on THIS computer (OSK-10285).
+ *
+ * The setting lives in the daemon's own config on this computer, so it is
+ * forwarded to the daemon rather than sent to the API: consent to a cloud agent
+ * using a signed-in browser belongs to the person at the machine, and a request
+ * from the cloud must not be able to grant it.
+ */
+export default class BrowserCloudAgents extends Command {
+    static description: string;
+    static examples: string[];
+    static args: {
+        action: import("@oclif/core/lib/interfaces").Arg<string, Record<string, unknown>>;
+    };
+    static flags: {
+        json: import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
+    };
+    run(): Promise<void>;
+}

package/dist/commands/browser/cloud-agents.js

@@ -0,0 +1,43 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const core_1 = require("@oclif/core");
+const browser_1 = require("../browser");
+/**
+ * Whether a cloud agent may drive the browser on THIS computer (OSK-10285).
+ *
+ * The setting lives in the daemon's own config on this computer, so it is
+ * forwarded to the daemon rather than sent to the API: consent to a cloud agent
+ * using a signed-in browser belongs to the person at the machine, and a request
+ * from the cloud must not be able to grant it.
+ */
+class BrowserCloudAgents extends core_1.Command {
+    static description = 'Allow, deny, or show whether cloud agents may drive the browser on this computer (off by default)';
+    static examples = [
+        '<%= config.bin %> browser cloud-agents status',
+        '<%= config.bin %> browser cloud-agents allow',
+        '<%= config.bin %> browser cloud-agents deny',
+    ];
+    static args = {
+        action: core_1.Args.string({
+            description: 'allow, deny, or status',
+            required: true,
+            options: ['allow', 'deny', 'status'],
+            // Without this oclif reads stdin for a missing positional, so the command
+            // hangs when run from a pipe or a non-tty instead of refusing. Enforced
+            // by ARG_IMPLICIT_STDIN_ENABLED in the command-hygiene audit.
+            ignoreStdin: true,
+        }),
+    };
+    static flags = {
+        json: core_1.Flags.boolean({ description: 'Output JSON' }),
+    };
+    async run() {
+        const { args, flags } = await this.parse(BrowserCloudAgents);
+        await (0, browser_1.forwardBrowserCommand)(this, [
+            'cloud-agents',
+            args.action,
+            ...(flags.json ? ['--json'] : []),
+        ]);
+    }
+}
+exports.default = BrowserCloudAgents;

package/dist/commands/code/handover.d.ts

@@ -21,6 +21,15 @@ import { BaseCommand } from '../../base-command';
  * code in the cloud (`skrr machines hosted start --repo` is the second, and stays the
  * right choice when you want a persistent machine instead of a one-shot job).
  *
+ * ── `--carry-session` ──────────────────────────────────────────────────────
+ *
+ * The transcript CAN travel once the engine implements the session-export
+ * contract (docs/architecture/sky-code-session-export-contract-2026-08-21.md):
+ * `sky-code session export <id> --format json` writes a versioned envelope to
+ * stdout. This flag runs exactly that contract and folds the export into the
+ * prompt — the endpoint's only carrier. An engine that predates the contract
+ * is a clean refusal, never a silent fallback to brief-only.
+ *
  * ── The safety gate is the point ───────────────────────────────────────────
  *
  * The runtime CLONES FROM GITHUB at `--base`. Uncommitted or unpushed work is
@@ -38,6 +47,8 @@ export default class CodeHandover extends BaseCommand {
         base: import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
         'allow-dirty': import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
         browser: import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
+        'carry-session': import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
+        session: import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
         json: import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
     };
     /** Run git, returning null rather than throwing — every caller has a fallback. */

package/dist/commands/code/handover.js

@@ -6,6 +6,7 @@ const node_crypto_1 = require("node:crypto");
 const data_provider_1 = require("@skrr-ai/data-provider");
 const base_command_1 = require("../../base-command");
 const code_handover_1 = require("../../lib/code-handover");
+const first_party_harness_1 = require("../../lib/first-party-harness");
 /**
  * `skrr code handover` — hand the work in this directory to an agent running on
  * a cloud runtime.
@@ -28,6 +29,15 @@ const code_handover_1 = require("../../lib/code-handover");
  * code in the cloud (`skrr machines hosted start --repo` is the second, and stays the
  * right choice when you want a persistent machine instead of a one-shot job).
  *
+ * ── `--carry-session` ──────────────────────────────────────────────────────
+ *
+ * The transcript CAN travel once the engine implements the session-export
+ * contract (docs/architecture/sky-code-session-export-contract-2026-08-21.md):
+ * `sky-code session export <id> --format json` writes a versioned envelope to
+ * stdout. This flag runs exactly that contract and folds the export into the
+ * prompt — the endpoint's only carrier. An engine that predates the contract
+ * is a clean refusal, never a silent fallback to brief-only.
+ *
  * ── The safety gate is the point ───────────────────────────────────────────
  *
  * The runtime CLONES FROM GITHUB at `--base`. Uncommitted or unpushed work is
@@ -36,11 +46,13 @@ const code_handover_1 = require("../../lib/code-handover");
  * the pull request. This refuses by default and says what to do.
  */
 class CodeHandover extends base_command_1.BaseCommand {
-    static description = 'Hand the work in this directory to an agent on a cloud runtime';
+    static description = 'Hand the work in this directory to an agent on a cloud runtime ' +
+        '(--carry-session also carries the engine session transcript, when the engine supports export)';
     static examples = [
         '<%= config.bin %> code handover --to "Frontend Agent" --brief "finish the bundle-size fix"',
         '<%= config.bin %> code handover --to agent_abc --brief "continue the parser refactor" --base main',
         '<%= config.bin %> code handover --to "Engineer" --brief "..." --allow-dirty --json',
+        '<%= config.bin %> code handover --to "Engineer" --brief "..." --carry-session --session <engine-session-id>',
     ];
     static flags = {
         to: core_1.Flags.string({
@@ -64,6 +76,17 @@ class CodeHandover extends base_command_1.BaseCommand {
         browser: core_1.Flags.boolean({
             description: 'Give the receiving agent a browser. Refused where the deployment has no browser runtime, never run without one.',
         }),
+        'carry-session': core_1.Flags.boolean({
+            description: 'Export the engine session transcript (`sky-code session export`) and carry it into the ' +
+                'handover. Opt-in because carrying a whole session is a cost the user should choose. ' +
+                'Refused outright when the engine predates the export contract — there is no silent ' +
+                'fallback to brief-only.',
+            default: false,
+        }),
+        session: core_1.Flags.string({
+            description: 'Engine session id to export with --carry-session (default: the session id the engine ' +
+                'exports to its environment — SKRR_CODE_SESSION_ID or SKY_CODE_SESSION_ID)',
+        }),
         json: core_1.Flags.boolean({ description: 'Output the created task as JSON' }),
     };
     /** Run git, returning null rather than throwing — every caller has a fallback. */
@@ -105,6 +128,78 @@ class CodeHandover extends base_command_1.BaseCommand {
         if (!safety.safe && !flags['allow-dirty']) {
             this.error((0, code_handover_1.formatUnsafeHandover)(gitState, safety));
         }
+        if (flags.session && !flags['carry-session']) {
+            this.warn('--session has no effect without --carry-session.');
+        }
+        // ── Optional: carry the engine session. A refused export is terminal —
+        // the flag promised the transcript would travel, so dispatching without it
+        // would silently deliver a different product than the one asked for. ────
+        let sessionExport = null;
+        let carriedSessionId = null;
+        if (flags['carry-session']) {
+            const { path: engineBin } = (0, first_party_harness_1.resolveEngine)();
+            if (!engineBin)
+                this.error((0, first_party_harness_1.notInstalledMessage)());
+            // `--session` wins; otherwise the variable the engine stamps into
+            // processes it spawns (current namespace, then the legacy spelling).
+            const sessionId = flags.session ||
+                process.env.SKRR_CODE_SESSION_ID?.trim() ||
+                process.env.SKY_CODE_SESSION_ID?.trim();
+            if (!sessionId) {
+                this.error('--carry-session needs the engine session to carry. Pass --session <engine-session-id>, ' +
+                    'or run inside a session that exports SKRR_CODE_SESSION_ID.');
+            }
+            carriedSessionId = sessionId;
+            let stdout;
+            try {
+                stdout = (0, node_child_process_1.execFileSync)(engineBin, ['session', 'export', sessionId, '--format', 'json'], {
+                    encoding: 'utf8',
+                    stdio: ['ignore', 'pipe', 'pipe'],
+                    maxBuffer: 64 * 1024 * 1024,
+                });
+            }
+            catch (err) {
+                const e = err;
+                const failure = (0, code_handover_1.classifySessionExportError)(e);
+                if (failure.kind === 'unknown-session') {
+                    this.error(`No engine session "${sessionId}" — the engine found nothing to carry.\n` +
+                        `  ${failure.detail}`);
+                }
+                this.error('This engine does not support session export — --carry-session requires a sky-code ' +
+                    'engine implementing the session-export contract ' +
+                    '(docs/architecture/sky-code-session-export-contract-2026-08-21.md).\n' +
+                    `  ${failure.detail}\n` +
+                    '  Re-run without --carry-session to hand over the situation only, or upgrade the engine.');
+            }
+            const envelope = (0, code_handover_1.parseSessionExportEnvelope)(stdout);
+            if (!envelope) {
+                // Exit 0 but no contract envelope is a deviation, not a success: the
+                // one shape this side may depend on (C2) did not arrive, so attaching
+                // the output anyway would be guessing with someone else's session.
+                this.error('The engine ran `session export` but did not produce the contract envelope ' +
+                    '({version, sessionId, messages[], truncated}) — this build predates or deviates from ' +
+                    'the export contract, so nothing was attached.');
+            }
+            // The endpoint's prompt cap is 50000 chars; the transcript gets what the
+            // brief and the git context leave behind.
+            const budget = 50000 -
+                (0, code_handover_1.composeHandoverPrompt)({
+                    brief: flags.brief,
+                    repoFullName,
+                    branch,
+                    headSha: this.git(['rev-parse', '--short', 'HEAD']),
+                    recentCommits: this.git(['log', '--oneline', '-5']),
+                    localWorkNotCarried: safety.localWorkNotCarried,
+                }).length -
+                128;
+            sessionExport = (0, code_handover_1.renderSessionTranscript)(envelope, Math.max(0, budget));
+            if (sessionExport.totalCount > 0 && sessionExport.carriedCount === 0) {
+                // A "carried" block containing zero messages is a lie about what moved.
+                // The brief --brief plus git context already consumed the prompt budget.
+                this.error('The session transcript does not fit the 50000-character task prompt alongside this ' +
+                    'brief — nothing would be carried. Shorten --brief, or re-run without --carry-session.');
+            }
+        }
         // ── Target agent: id or name, from the agents this user can see. ────────
         let agents = [];
         try {
@@ -145,6 +240,7 @@ class CodeHandover extends base_command_1.BaseCommand {
             headSha: this.git(['rev-parse', '--short', 'HEAD']),
             recentCommits: this.git(['log', '--oneline', '-5']),
             localWorkNotCarried: safety.localWorkNotCarried,
+            sessionTranscript: sessionExport?.text,
         });
         let result;
         try {
@@ -173,6 +269,14 @@ class CodeHandover extends base_command_1.BaseCommand {
         const url = task.previewUrl ?? task.prUrl;
         if (url)
             this.log(`  ${String(url)}`);
+        if (sessionExport) {
+            const qualifiers = [
+                sessionExport.engineTruncated ? 'engine-truncated' : null,
+                sessionExport.clipped ? 'clipped to fit' : null,
+            ].filter(Boolean);
+            this.log(`  session ${carriedSessionId} — ${sessionExport.carriedCount}/${sessionExport.totalCount} ` +
+                `messages carried${qualifiers.length ? ` (${qualifiers.join(', ')})` : ''}`);
+        }
         if (safety.localWorkNotCarried) {
             this.log('  note   local uncommitted/unpushed work was not carried over.');
         }

package/dist/commands/commitments/handover.d.ts

@@ -0,0 +1,29 @@
+import { BaseCommand } from '../../base-command';
+/**
+ * `skrr commitments handover` — rebind a commitment's executor to a different
+ * agent.
+ *
+ * `commitment.agentId` is single-valued by design, so this is NOT a patch: the
+ * server records the move on the commitment's audit trail (`executorHandovers`)
+ * with who initiated it and why (impl contract B4, design doc P4). The
+ * canonical case is a commitment whose agent's execution targets are all
+ * quota-blocked — this is the "reassign" half of "executor cannot run until
+ * <date> — reassign or add a fallback target".
+ *
+ * Only the WHO moves: the contract, cadence, watched sources and audit trail
+ * are unchanged, and the new executor's own execution policy decides WHERE the
+ * next check runs.
+ */
+export default class CommitmentsHandover extends BaseCommand {
+    static description: string;
+    static examples: string[];
+    static args: {
+        id: import("@oclif/core/lib/interfaces").Arg<string, Record<string, unknown>>;
+    };
+    static flags: {
+        json: import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
+        to: import("@oclif/core/lib/interfaces").OptionFlag<string, import("@oclif/core/lib/interfaces").CustomOptions>;
+        reason: import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+    };
+    run(): Promise<void>;
+}

package/dist/commands/commitments/handover.js

@@ -0,0 +1,99 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const core_1 = require("@oclif/core");
+const data_provider_1 = require("@skrr-ai/data-provider");
+const base_command_1 = require("../../base-command");
+const commitments_1 = require("../../lib/commitments");
+const web_url_1 = require("../../lib/web-url");
+const code_handover_1 = require("../../lib/code-handover");
+/**
+ * `skrr commitments handover` — rebind a commitment's executor to a different
+ * agent.
+ *
+ * `commitment.agentId` is single-valued by design, so this is NOT a patch: the
+ * server records the move on the commitment's audit trail (`executorHandovers`)
+ * with who initiated it and why (impl contract B4, design doc P4). The
+ * canonical case is a commitment whose agent's execution targets are all
+ * quota-blocked — this is the "reassign" half of "executor cannot run until
+ * <date> — reassign or add a fallback target".
+ *
+ * Only the WHO moves: the contract, cadence, watched sources and audit trail
+ * are unchanged, and the new executor's own execution policy decides WHERE the
+ * next check runs.
+ */
+class CommitmentsHandover extends base_command_1.BaseCommand {
+    static description = 'Reassign a commitment to a different executor agent';
+    static examples = [
+        '<%= config.bin %> commitments handover <commitment-id> --to "Backup Agent"',
+        '<%= config.bin %> commitments handover <id> --to agent_abc --reason "claude quota exhausted until Sep 19"',
+        '<%= config.bin %> commitments handover <id> --to agent_abc --json',
+    ];
+    static args = {
+        id: core_1.Args.string({ description: 'Commitment ID', required: true, ignoreStdin: true }),
+    };
+    static flags = {
+        json: core_1.Flags.boolean({ description: 'Output as JSON' }),
+        to: core_1.Flags.string({
+            description: 'Agent that takes over the commitment — id or name',
+            required: true,
+        }),
+        reason: core_1.Flags.string({
+            description: 'Why the executor is changing — recorded on the audit trail',
+        }),
+    };
+    async run() {
+        this.requireAuth();
+        const { args, flags } = await this.parse(CommitmentsHandover);
+        // ── Target agent: id or name, resolved like `code handover --to`. ──────
+        let agents = [];
+        try {
+            const resp = await data_provider_1.dataService.listAgents({ requiredPermission: data_provider_1.PermissionBits.VIEW });
+            agents = (resp?.data ?? []).filter(Boolean);
+        }
+        catch (err) {
+            this.handleApiError(err);
+        }
+        const matched = (0, code_handover_1.matchAgent)(flags.to, agents);
+        if (matched.kind === 'none') {
+            this.error(`No agent matches "${flags.to}". Run \`${this.config.bin} agents list\` to see the agents you can use.`);
+        }
+        if (matched.kind === 'ambiguous') {
+            this.error(`"${flags.to}" matches ${matched.candidates.length} agents. Pass the agent id instead:\n` +
+                matched.candidates.map((a) => `  ${a.id}  ${a.name ?? ''}`).join('\n'));
+        }
+        const target = matched.agent;
+        let result;
+        try {
+            result = await commitments_1.commitmentApi.setExecutor(args.id, {
+                agentId: target.id,
+                ...(flags.reason ? { reason: flags.reason } : {}),
+            });
+        }
+        catch (err) {
+            this.handleApiError(err, { subject: `Commitment ${args.id}` });
+        }
+        if (flags.json) {
+            this.log(JSON.stringify(result, null, 2));
+            return;
+        }
+        const agentLabel = target.name ? `${target.name} (${target.id})` : target.id;
+        this.log(`Handed commitment ${args.id} over to ${agentLabel}`);
+        // The audit entry the server appended — echo it so "from whom" is answered
+        // without a second call. Absent on a server that predates the trail.
+        const commitment = result?.commitment ??
+            result;
+        const handovers = commitment?.executorHandovers;
+        if (Array.isArray(handovers) && handovers.length > 0) {
+            const last = handovers[handovers.length - 1];
+            if (typeof last?.fromAgentId === 'string' && typeof last?.toAgentId === 'string') {
+                this.log(`  executor ${last.fromAgentId} → ${last.toAgentId}`);
+            }
+        }
+        if (commitment) {
+            const withUrl = (0, web_url_1.withCommitmentUrl)(this.cliConfig.baseURL, commitment);
+            if (withUrl.url)
+                this.log(`  ${withUrl.url}`);
+        }
+    }
+}
+exports.default = CommitmentsHandover;

package/dist/commands/followups/list.js

@@ -14,7 +14,7 @@ const agent_resolver_1 = require("../../lib/agent-resolver");
  * obligations and start reasoning about them.
  */
 class FollowupsList extends base_command_1.BaseCommand {
-    static description = 'List follow-ups — armed, proposed, paused, or settled';
+    static description = 'List follow-ups — armed, proposed, paused, settling, or settled';
     static examples = [
         '<%= config.bin %> followups list',
         '<%= config.bin %> followups list --agent agent_1 --kind watch --state armed',

package/dist/commands/followups/watch.js

@@ -30,6 +30,7 @@ class FollowupsWatch extends base_command_1.BaseCommand {
         '<%= config.bin %> followups watch --subject task:OSK-42 --why "deploy still running" --url https://ci.example.com/api/build/9 --until \'{"path":"status","op":"equals","value":"done"}\' --deadline 6h',
         '<%= config.bin %> followups watch --subject task:OSK-42 --why "pr review" --check "gh pr view 42 --json state" --success "state == MERGED" --abort "state == CLOSED" --wait event --wait-entity github --wait-event pull_request_merged --wait-fallback 2h',
         '<%= config.bin %> followups watch --subject conversation:abc --why "vendor reply" --check "check inbox" --success "reply arrived" --abort "3 days" --wait clock --wait-at 2026-09-20T09:00:00Z',
+        '<%= config.bin %> followups watch --subject task:OSK-42 --why "deploy tail" --check "release-status says live" --success "live" --abort "6h" --wait clock --wait-at 45m',
     ];
     static flags = {
         subject: core_1.Flags.string({ description: 'Subject ref: type:externalKey', required: true }),
@@ -41,9 +42,15 @@ class FollowupsWatch extends base_command_1.BaseCommand {
             description: 'Predicate tree as JSON (predicate form — the server evaluates it; no agent turn per check): a leaf {"path","op","value"} or {"all"|"any": [...]}. op is equals, not_equals, contains, starts_with, in, gt, lt, exists, … — an unknown op is refused with the full list',
         }),
         grant: core_1.Flags.string({ description: 'Grant id supplying the watch credentials' }),
-        deadline: core_1.Flags.string({ description: 'When the watch must stop (predicate form, required)' }),
-        'check-every': core_1.Flags.string({ description: 'Observation interval (predicate form)' }),
-        'max-checks': core_1.Flags.integer({ description: 'Observation cap (predicate form)' }),
+        deadline: core_1.Flags.string({
+            description: 'When the watch must stop (predicate form, required — refused on a recipe watch, which ends through its --wait)',
+        }),
+        'check-every': core_1.Flags.string({
+            description: 'Observation interval (predicate form — refused on a recipe watch)',
+        }),
+        'max-checks': core_1.Flags.integer({
+            description: 'Observation cap (predicate form — refused on a recipe watch)',
+        }),
         'root-path': core_1.Flags.string({ description: 'JSON root path inside the response' }),
         'resume-prompt': core_1.Flags.string({ description: 'What to tell the settling turn' }),
         // recipe form
@@ -53,10 +60,15 @@ class FollowupsWatch extends base_command_1.BaseCommand {
         success: core_1.Flags.string({ description: 'What state means the wait resolved (recipe form)' }),
         abort: core_1.Flags.string({ description: 'When to stop and escalate (recipe form)' }),
         wait: core_1.Flags.string({
-            description: 'Wait kind (recipe form)',
+            description: 'Wait kind (recipe form, required)',
             options: [...followups_1.WATCH_WAIT_KINDS],
         }),
-        'wait-at': core_1.Flags.string({ description: 'Instant/duration for --wait clock' }),
+        'wait-at': core_1.Flags.string({
+            // Naming both shapes here and in the server's rejection, because the
+            // duration grammar is a shorthand and not ISO-8601: `PT45M` is refused
+            // (OSK-10392).
+            description: 'When --wait clock fires: an ISO-8601 instant, or a duration from now (45m, 2h, 3d, 1w)',
+        }),
         'wait-entity': core_1.Flags.string({ description: 'Entity type for --wait event' }),
         'wait-event': core_1.Flags.string({ description: 'Event type for --wait event' }),
         'wait-filter-field': core_1.Flags.string({ description: 'Payload field for an event filter' }),
@@ -161,6 +173,19 @@ class FollowupsWatch extends base_command_1.BaseCommand {
                     });
                 }
             }
+            const boundsRefusal = (0, followups_1.recipeWatchBoundsRefusal)(flags.wait, {
+                deadline: flags.deadline,
+                checkEvery: flags['check-every'],
+                maxChecks: flags['max-checks'],
+            });
+            if (boundsRefusal) {
+                this.failWithCliError({
+                    message: boundsRefusal,
+                    code: 'FOLLOWUP_INVALID_FIELD',
+                    exit: 2,
+                    retryable: false,
+                });
+            }
             const wait = { kind: flags.wait };
             if (flags.wait === 'clock') {
                 wait.at = flags['wait-at'];
@@ -188,6 +213,16 @@ class FollowupsWatch extends base_command_1.BaseCommand {
                 success: flags.success,
                 abort: flags.abort,
                 wait,
+                // Forwarded so the SERVER refuses them, rather than dropped here so
+                // nobody does (OSK-10407). These are predicate-only bounds; this branch
+                // used to assemble the five fields above and silently discard the rest,
+                // so `--deadline 7d` armed a watch and reported success having stored
+                // no deadline. The rule that answers now lives once, in
+                // `normalizeFollowUpInput`, so the CLI and the agent-facing paths
+                // cannot drift into disagreeing about which form owns a flag.
+                ...(flags.deadline !== undefined ? { deadline: flags.deadline } : {}),
+                ...(flags['check-every'] !== undefined ? { checkEvery: flags['check-every'] } : {}),
+                ...(flags['max-checks'] !== undefined ? { maxChecks: flags['max-checks'] } : {}),
             });
         }
         let response;

package/dist/commands/initiatives/list.d.ts

@@ -15,6 +15,7 @@ export default class InitiativesList extends BaseCommand {
         state: import("@oclif/core/lib/interfaces").OptionFlag<string[] | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
         pending: import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
         limit: import("@oclif/core/lib/interfaces").OptionFlag<number | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+        cursor: import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
     };
     run(): Promise<void>;
 }