@skrr-ai/cli 0.1.44 → 0.1.46

package/dist/commands/initiatives/list.js

@@ -29,6 +29,7 @@ class InitiativesList extends base_command_1.BaseCommand {
             description: 'Only proposals still awaiting a decision (detected, proposed, waiting)',
         }),
         limit: core_1.Flags.integer({ description: 'Max results (1..100)', min: 1, max: 100 }),
+        cursor: core_1.Flags.string({ description: 'Pagination cursor from a previous page' }),
     };
     async run() {
         this.requireAuth();
@@ -40,6 +41,7 @@ class InitiativesList extends base_command_1.BaseCommand {
                 ...(flags.agent ? { agentId: flags.agent } : {}),
                 ...(states?.length ? { state: states.join(',') } : {}),
                 ...(flags.limit ? { limit: flags.limit } : {}),
+                ...(flags.cursor ? { cursor: flags.cursor } : {}),
             });
         }
         catch (err) {
@@ -49,7 +51,7 @@ class InitiativesList extends base_command_1.BaseCommand {
             this.log(JSON.stringify(response, null, 2));
             return;
         }
-        const rows = response.data ?? [];
+        const rows = response.initiatives ?? [];
         if (rows.length === 0) {
             this.log(flags.pending ? 'Nothing is waiting on you.' : 'No initiatives.');
             return;
@@ -63,7 +65,14 @@ class InitiativesList extends base_command_1.BaseCommand {
             }
         }
         this.log('');
-        this.log(`${rows.length} shown. Decide one with: skrr initiatives decide <id> --approve`);
+        const active = response.counts?.active;
+        const shown = typeof active === 'number' && flags.pending
+            ? `${rows.length} shown of ${active} awaiting a decision.`
+            : `${rows.length} shown.`;
+        this.log(`${shown} Decide one with: skrr initiatives decide <id> --approve`);
+        if (response.nextCursor) {
+            this.log(`Next page: --cursor ${response.nextCursor}`);
+        }
     }
 }
 exports.default = InitiativesList;

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

@@ -1,4 +1,6 @@
+import { type SpaceLabelUsageCounts } from '@skrr-ai/data-provider';
 import { BaseCommand } from '../../base-command';
+import { type LabelRow } from '../../lib/label-ref';
 /**
  * `labels list` — every label you can actually USE, by default.
  *
@@ -21,7 +23,32 @@ import { BaseCommand } from '../../base-command';
  * The merge itself is `lib/label-ref.collectLabelVocabulary` — the same
  * function `--label <name>` resolves through. A separate copy here is how the
  * name you can type and the name you can see start to disagree.
+ *
+ * `--space` answers the OTHER question people ask of a vocabulary: not "what
+ * may I use" but "what do we actually use HERE". It orders the list by how many
+ * of that Space's tasks carry each label and prints the count, which is the
+ * same ordering the web picker applies when it is opened inside a Space — one
+ * comparator (`orderLabelsBySpaceUsage`), so the two surfaces cannot disagree
+ * about which label leads.
+ */
+/** One printable row per label, in the order the reader should see them. */
+export interface LabelListRow extends Record<string, string> {
+    id: string;
+    name: string;
+    scope: string;
+    color: string;
+    appliesTo: string;
+    used: string;
+    inSpace: string;
+    state: string;
+}
+/**
+ * Order the vocabulary for display and flatten it into table rows.
+ *
+ * Exported so the ordering can be tested without a command harness, and so the
+ * JSON and table outputs cannot drift into two different orders.
  */
+export declare function labelListRows(items: LabelRow[], spaceUsage?: SpaceLabelUsageCounts): LabelListRow[];
 export default class LabelsList extends BaseCommand {
     static description: string;
     static examples: string[];
@@ -29,6 +56,7 @@ export default class LabelsList extends BaseCommand {
         scope: import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
         'applicable-to': import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
         'include-archived': import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
+        space: import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
         'scope-id': import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
         json: import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
     };

package/dist/commands/labels/list.js

@@ -1,5 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.labelListRows = labelListRows;
 const core_1 = require("@oclif/core");
 const data_provider_1 = require("@skrr-ai/data-provider");
 const base_command_1 = require("../../base-command");
@@ -7,28 +8,29 @@ const format_1 = require("../../lib/format");
 const label_scope_1 = require("../../lib/label-scope");
 const label_ref_1 = require("../../lib/label-ref");
 /**
- * `labels list` — every label you can actually USE, by default.
+ * Order the vocabulary for display and flatten it into table rows.
  *
- * This used to default to `--scope user` and show one scope at a time, which
- * is a faithful rendering of `GET /api/labels` and a poor answer to the
- * question people ask. `scope` is an OWNERSHIP boundary, not a filter anyone
- * browses by: a workspace-scoped label is attachable by every member, so
- * leaving it out of the default view means the vocabulary you are told about
- * is smaller than the one you have.
- *
- * It had a measurable cost. Three workspace-scoped labels existed and were
- * invisible to the bare command, so nobody knew they were there — which is
- * part of why the label system shipped complete and went unused, and why a
- * second `dogfood` nearly got created beside one that already existed.
- *
- * `--scope` still narrows to exactly one scope, so every explicit invocation
- * behaves as it always did. Only the bare command changed, and it changed to
- * a superset.
- *
- * The merge itself is `lib/label-ref.collectLabelVocabulary` — the same
- * function `--label <name>` resolves through. A separate copy here is how the
- * name you can type and the name you can see start to disagree.
+ * Exported so the ordering can be tested without a command harness, and so the
+ * JSON and table outputs cannot drift into two different orders.
  */
+function labelListRows(items, spaceUsage) {
+    return (0, data_provider_1.orderLabelsBySpaceUsage)(items, spaceUsage).map((l) => ({
+        id: String(l.id ?? '-'),
+        name: String(l.name ?? '-'),
+        // Where it lives decides who else sees it, and it is the one column the
+        // old single-scope view never had to show.
+        scope: String(l.scope ?? '-'),
+        color: String(l.color ?? '-'),
+        appliesTo: Array.isArray(l.applicableTo) ? l.applicableTo.join(',') : '-',
+        used: String(l.usageCount ?? 0),
+        // `USED` is the global counter; `IN SPACE` is this Space's own tasks.
+        // Printed side by side because the gap between them is the finding: a
+        // label used 30 times across the workspace and 0 times here is not this
+        // Space's vocabulary, however alive it looks everywhere else.
+        inSpace: String(spaceUsage?.get(String(l.id)) ?? 0),
+        state: l.archivedAt ? 'archived' : 'active',
+    }));
+}
 class LabelsList extends base_command_1.BaseCommand {
     static description = 'List labels — every scope you can use, unless --scope narrows it';
     static examples = [
@@ -36,6 +38,7 @@ class LabelsList extends base_command_1.BaseCommand {
         '<%= config.bin %> labels list --applicable-to space',
         '<%= config.bin %> labels list --scope user',
         '<%= config.bin %> labels list --scope workspace --scope-id <workspace-id>',
+        '<%= config.bin %> labels list --space "Dogfood: Space navigation"',
         '<%= config.bin %> labels list --include-archived --json',
     ];
     static flags = {
@@ -52,6 +55,9 @@ class LabelsList extends base_command_1.BaseCommand {
             options: [...label_scope_1.LABEL_APPLICABLE],
         }),
         'include-archived': core_1.Flags.boolean({ description: 'Include archived labels' }),
+        space: core_1.Flags.string({
+            description: 'Order by how often this Space uses each label, and show the count',
+        }),
     };
     async run() {
         this.requireAuth();
@@ -83,8 +89,29 @@ class LabelsList extends base_command_1.BaseCommand {
                 this.error(err.message, { exit: 1 });
             this.handleApiError(err);
         }
+        /*
+         * Per-Space usage, when asked for. A failure here must not take the list
+         * with it: the unordered vocabulary is still the answer to the question,
+         * and refusing to print it because a secondary count could not be read
+         * would turn a degraded answer into no answer.
+         */
+        let spaceUsage;
+        if (flags.space) {
+            try {
+                spaceUsage = (0, data_provider_1.spaceLabelUsageCounts)(await data_provider_1.dataService.getSpaceLabelUsage(flags.space));
+            }
+            catch (err) {
+                this.warn(`Could not read label usage for this Space; showing the stored order. ${err instanceof Error ? err.message : String(err)}`);
+            }
+        }
         if (flags.json) {
-            this.log(JSON.stringify({ data: items }, null, 2));
+            const ordered = (0, data_provider_1.orderLabelsBySpaceUsage)(items, spaceUsage);
+            this.log(JSON.stringify({
+                data: spaceUsage
+                    ? ordered.map((l) => ({ ...l, spaceUsageCount: spaceUsage?.get(String(l.id)) ?? 0 }))
+                    : ordered,
+                ...(flags.space ? { spaceId: flags.space } : {}),
+            }, null, 2));
             return;
         }
         if (items.length === 0) {
@@ -93,17 +120,7 @@ class LabelsList extends base_command_1.BaseCommand {
                 : 'No labels you can use. Create one with `labels create --name <name> --applicable-to <entity>`.');
             return;
         }
-        const rows = items.map((l) => ({
-            id: String(l.id ?? '-'),
-            name: String(l.name ?? '-'),
-            // Where it lives decides who else sees it, and it is the one column the
-            // old single-scope view never had to show.
-            scope: String(l.scope ?? '-'),
-            color: String(l.color ?? '-'),
-            appliesTo: Array.isArray(l.applicableTo) ? l.applicableTo.join(',') : '-',
-            used: String(l.usageCount ?? 0),
-            state: l.archivedAt ? 'archived' : 'active',
-        }));
+        const rows = labelListRows(items, spaceUsage);
         (0, format_1.renderTable)(rows, [
             { key: 'id', header: 'ID' },
             { key: 'name', header: 'NAME', maxWidth: 32 },
@@ -111,6 +128,7 @@ class LabelsList extends base_command_1.BaseCommand {
             { key: 'color', header: 'COLOR' },
             { key: 'appliesTo', header: 'APPLIES TO' },
             { key: 'used', header: 'USED' },
+            ...(spaceUsage ? [{ key: 'inSpace', header: 'IN SPACE' }] : []),
             { key: 'state', header: 'STATE' },
         ], (line) => this.log(line));
     }

package/dist/commands/tasks/fork.d.ts

@@ -0,0 +1,32 @@
+import { BaseCommand } from '../../base-command';
+/**
+ * `skrr tasks fork` — race a second attempt at the same work (B8).
+ *
+ * The line against `tasks handover`: a handover CONTINUES the work once, from a
+ * finished run. A fork runs a SIBLING attempt from the same Resume Point while
+ * the original is still live — both in one `parallel.groupId`, neither
+ * canonical until `tasks promote` picks one.
+ *
+ * The shared-workspace hazard is the reason this is not a flag on handover. Two
+ * executors of the same target class can be writing one workspace, and the
+ * server refuses (`shared_workspace_ack_required`) until the caller says
+ * plainly that it knows. `--acknowledge-shared-workspace` is that sentence;
+ * it is deliberately long to type.
+ */
+export default class TasksFork extends BaseCommand {
+    static description: string;
+    static examples: string[];
+    static args: {
+        id: import("@oclif/core/lib/interfaces").Arg<string | undefined, Record<string, unknown>>;
+    };
+    static flags: {
+        json: import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
+        task: import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+        to: import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+        harness: import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+        'from-run': import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+        reason: import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+        'acknowledge-shared-workspace': import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
+    };
+    run(): Promise<void>;
+}

package/dist/commands/tasks/fork.js

@@ -0,0 +1,171 @@
+"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 code_handover_1 = require("../../lib/code-handover");
+const task_extras_1 = require("../../lib/task-extras");
+const task_resolver_1 = require("../../lib/task-resolver");
+/**
+ * `skrr tasks fork` — race a second attempt at the same work (B8).
+ *
+ * The line against `tasks handover`: a handover CONTINUES the work once, from a
+ * finished run. A fork runs a SIBLING attempt from the same Resume Point while
+ * the original is still live — both in one `parallel.groupId`, neither
+ * canonical until `tasks promote` picks one.
+ *
+ * The shared-workspace hazard is the reason this is not a flag on handover. Two
+ * executors of the same target class can be writing one workspace, and the
+ * server refuses (`shared_workspace_ack_required`) until the caller says
+ * plainly that it knows. `--acknowledge-shared-workspace` is that sentence;
+ * it is deliberately long to type.
+ */
+class TasksFork extends base_command_1.BaseCommand {
+    static description = 'Race a sibling run of a task from the same Resume Point (parallel attempt, B8)';
+    static examples = [
+        '<%= config.bin %> tasks fork <task-id> --to "Codex Agent"',
+        '<%= config.bin %> tasks fork <task-id> --to agent_abc --harness agent-worker',
+        '<%= config.bin %> tasks fork <task-id> --from-run <run-id> --acknowledge-shared-workspace',
+    ];
+    static args = {
+        id: core_1.Args.string({
+            description: 'Task ID; defaults to OVERSKY_SESSION_TASK_ID in task runtimes',
+            required: false,
+            ignoreStdin: true,
+        }),
+    };
+    static flags = {
+        json: core_1.Flags.boolean({ description: 'Output the {run, packet, groupId} response as JSON' }),
+        task: core_1.Flags.string({ description: 'Task ID; overrides daemon runtime context' }),
+        to: core_1.Flags.string({
+            description: 'Agent for the branch — id or name. Default: the source run’s own agent.',
+        }),
+        harness: core_1.Flags.string({
+            description: 'Execution target for the branch. Default: the target agent’s own policy chain.',
+        }),
+        'from-run': core_1.Flags.string({
+            description: 'Run to branch from (default: the task’s most recent run)',
+        }),
+        reason: core_1.Flags.string({ description: 'Why a second attempt — recorded in the packet' }),
+        'acknowledge-shared-workspace': core_1.Flags.boolean({
+            description: 'Proceed when the branch resolves to the same execution-target class as the source, ' +
+                'where two executors can write one workspace. Required by the server in that case.',
+            default: false,
+        }),
+    };
+    async run() {
+        this.requireAuth();
+        const { args, flags } = await this.parse(TasksFork);
+        let taskIdentity;
+        try {
+            taskIdentity = (0, task_resolver_1.resolveTaskIdentity)({ positionalId: args.id, flagTask: flags.task });
+        }
+        catch (err) {
+            const failure = (0, task_resolver_1.taskResolutionFailure)(err);
+            this.failWithCliError({
+                message: failure.message,
+                code: failure.code,
+                exit: 2,
+                retryable: false,
+                details: { suggestion: failure.suggestion, context: failure.details },
+            });
+        }
+        const taskId = taskIdentity.id;
+        // The branch agent is OPTIONAL — a fork onto the same agent on a different
+        // target is the "try it on Codex too" case, and the server derives the
+        // agent from the source run when none is named.
+        let targetAgentId;
+        if (flags.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'));
+            }
+            targetAgentId = matched.agent.id;
+        }
+        let sourceRunId = flags['from-run'] ?? '';
+        if (!sourceRunId) {
+            let runs = [];
+            try {
+                const resp = await data_provider_1.dataService.getTaskRuns(taskId);
+                runs = (resp?.data ?? []);
+            }
+            catch (err) {
+                this.handleApiError(err);
+            }
+            const latest = runs[0];
+            if (!latest) {
+                this.failWithCliError({
+                    message: `Task ${taskId} has no runs to fork from. Run \`${this.config.bin} tasks runs ${taskId}\` to see the ledger.`,
+                    code: 'FORK_NO_SOURCE_RUN',
+                    exit: 2,
+                    retryable: false,
+                });
+            }
+            sourceRunId = String(latest.runId ?? latest.id ?? '');
+        }
+        let result;
+        try {
+            result = await (0, task_extras_1.taskRunFork)(taskId, sourceRunId, {
+                ...(targetAgentId ? { targetAgentId } : {}),
+                ...(flags.harness ? { executionTargetRef: (0, task_extras_1.parseExecutionTargetRef)(flags.harness) } : {}),
+                ...(flags.reason ? { reason: flags.reason } : {}),
+                ...(flags['acknowledge-shared-workspace'] ? { acknowledgeSharedWorkspace: true } : {}),
+            });
+        }
+        catch (err) {
+            const refusal = (0, base_command_1.apiRefusal)(err);
+            if (refusal.code?.toLowerCase() === 'shared_workspace_ack_required') {
+                this.failWithCliError({
+                    message: (refusal.message ??
+                        'The branch resolves to the same execution-target class as the source.') +
+                        '\n  → two executors could write one workspace. Re-run with ' +
+                        '`--acknowledge-shared-workspace` if that is acceptable, or pass `--harness` ' +
+                        'to put the branch on a different target class.',
+                    code: refusal.code,
+                    exit: 3,
+                    retryable: false,
+                    details: refusal.body,
+                });
+            }
+            if (refusal.code?.toLowerCase() === 'target_not_assignee') {
+                this.failWithCliError({
+                    message: (refusal.message ?? `Agent ${flags.to} may not work this task.`) +
+                        `\n  → assign it first: \`${this.config.bin} tasks assign ${taskId} --agent "${flags.to}"\`, then re-run.`,
+                    code: refusal.code,
+                    exit: 3,
+                    retryable: false,
+                    details: refusal.body,
+                });
+            }
+            this.handleApiError(err, { subject: `Task ${taskId}` });
+        }
+        if (flags.json) {
+            this.log(JSON.stringify(result, null, 2));
+            return;
+        }
+        const r = result;
+        const branch = r.run ?? {};
+        const branchRunId = String(branch.runId ?? branch.id ?? '?');
+        this.log(`Forked run ${sourceRunId} → branch ${branchRunId}`);
+        this.log(`Parallel group: ${r.groupId ?? '?'}`);
+        const notCarried = Array.isArray(r.packet?.notCarried)
+            ? r.packet.notCarried.map(String).filter(Boolean)
+            : [];
+        this.log(`Not carried: ${notCarried.length ? notCarried.join(', ') : '(nothing declared)'}`);
+        this.log(`Both runs are live and neither is canonical. Pick one with ` +
+            `\`${this.config.bin} tasks promote ${taskId} --run <run-id>\` — the losers are cancelled.`);
+    }
+}
+exports.default = TasksFork;

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

@@ -0,0 +1,23 @@
+import { BaseCommand } from '../../base-command';
+/**
+ * Whether a run row is a legal handover source — exported for tests.
+ * `endedAt` is a defensive OR: a projection that stamps a terminal timestamp
+ * without a recognized status is still terminal.
+ */
+export declare function isHandoverSourceRun(run: Record<string, unknown>): boolean;
+export default class TasksHandover extends BaseCommand {
+    static description: string;
+    static examples: string[];
+    static args: {
+        id: import("@oclif/core/lib/interfaces").Arg<string | undefined, Record<string, unknown>>;
+    };
+    static flags: {
+        json: import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
+        task: import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+        to: import("@oclif/core/lib/interfaces").OptionFlag<string, import("@oclif/core/lib/interfaces").CustomOptions>;
+        harness: import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+        'from-run': import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, 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/tasks/handover.js

@@ -0,0 +1,205 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isHandoverSourceRun = isHandoverSourceRun;
+const core_1 = require("@oclif/core");
+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 task_extras_1 = require("../../lib/task-extras");
+const task_resolver_1 = require("../../lib/task-resolver");
+const format_1 = require("../../lib/format");
+/**
+ * `skrr tasks handover` — continue a task's work under a different agent or a
+ * different execution target, from where a finished run left off.
+ *
+ * Distinct from `tasks retry` (same executor, same authority, starts the task
+ * over) and `tasks assign` (a prerequisite consent change, not the act). A
+ * handover admits a NEW run resumed from the source run's Resume Point, so the
+ * ledger keeps both halves: the old run as immutable evidence, the new one as
+ * the visible continuation.
+ *
+ * The two axes are independent (docs/architecture/execution-handover-2026-09-17.md
+ * §1): `--to` changes WHO runs, `--harness` changes WHERE it runs. The server
+ * contract is B1 — `POST /api/tasks/:taskId/runs/:runId/handover`.
+ *
+ * What does not move is declared, not implied: the response's `packet.notCarried`
+ * names what stayed behind (provider session, agent-private memory, local
+ * machine state) and is printed verbatim rather than paraphrased.
+ */
+/** The run statuses from which a handover can source a Resume Point. */
+const HANDOVER_SOURCE_RUN_STATUSES = new Set([
+    'succeeded',
+    'failed',
+    'cancelled',
+    // Contract B1 admits "terminal or parked". `parked` is not a
+    // TASK_EXECUTION_RUN_STATUSES value today, but the contract names it — a run
+    // parked awaiting runtime is exactly the handover case, so accept the word
+    // when a newer server starts sending it.
+    'parked',
+]);
+/**
+ * Whether a run row is a legal handover source — exported for tests.
+ * `endedAt` is a defensive OR: a projection that stamps a terminal timestamp
+ * without a recognized status is still terminal.
+ */
+function isHandoverSourceRun(run) {
+    const status = typeof run.status === 'string' ? run.status : '';
+    if (HANDOVER_SOURCE_RUN_STATUSES.has(status))
+        return true;
+    return typeof run.endedAt === 'string' && run.endedAt !== '';
+}
+class TasksHandover extends base_command_1.BaseCommand {
+    static description = 'Hand a task run over to a different agent or execution target, resumed from its Resume Point';
+    static examples = [
+        '<%= config.bin %> tasks handover <task-id> --to "Codex Agent"',
+        '<%= config.bin %> tasks handover <task-id> --to agent_abc --harness <target-ref>',
+        '<%= config.bin %> tasks handover <task-id> --to agent_abc --from-run <run-id> --reason "claude quota exhausted until Sep 19"',
+        '<%= config.bin %> tasks handover <task-id> --to agent_abc --json',
+    ];
+    static args = {
+        id: core_1.Args.string({
+            description: 'Task ID; defaults to OVERSKY_SESSION_TASK_ID in task runtimes',
+            required: false,
+            ignoreStdin: true,
+        }),
+    };
+    static flags = {
+        json: core_1.Flags.boolean({ description: 'Output the {run, packet} response as JSON' }),
+        task: core_1.Flags.string({ description: 'Task ID; overrides daemon runtime context' }),
+        to: core_1.Flags.string({
+            description: 'Agent that takes over — id or name',
+            required: true,
+        }),
+        harness: core_1.Flags.string({
+            description: 'Execution target ref for the new run. Default: the TARGET agent\u2019s own execution ' +
+                'policy chain — a handover re-runs the chain, it does not inherit the failed run\u2019s ' +
+                'resolved target.',
+        }),
+        'from-run': core_1.Flags.string({
+            description: 'Source run to resume from (default: the task\u2019s latest terminal or parked run)',
+        }),
+        reason: core_1.Flags.string({
+            description: 'Why the work is moving — recorded in the handover packet provenance',
+        }),
+    };
+    async run() {
+        this.requireAuth();
+        const { args, flags } = await this.parse(TasksHandover);
+        let taskIdentity;
+        try {
+            taskIdentity = (0, task_resolver_1.resolveTaskIdentity)({ positionalId: args.id, flagTask: flags.task });
+        }
+        catch (err) {
+            const failure = (0, task_resolver_1.taskResolutionFailure)(err);
+            this.failWithCliError({
+                message: failure.message,
+                code: failure.code,
+                exit: 2,
+                retryable: false,
+                details: { suggestion: failure.suggestion, context: failure.details },
+            });
+        }
+        const taskId = taskIdentity.id;
+        // ── 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;
+        // ── Source run: --from-run, else the latest terminal/parked run. ───────
+        let sourceRun = null;
+        if (flags['from-run']) {
+            sourceRun = { runId: flags['from-run'] };
+        }
+        else {
+            let runs = [];
+            try {
+                const resp = await data_provider_1.dataService.getTaskRuns(taskId);
+                runs = (resp?.data ?? []);
+            }
+            catch (err) {
+                this.handleApiError(err);
+            }
+            // `listRuns` is newest-first (admittedAt desc), so the first match IS the
+            // latest terminal run.
+            sourceRun = runs.find(isHandoverSourceRun) ?? null;
+            if (!sourceRun) {
+                this.failWithCliError({
+                    message: `Task ${taskId} has no terminal or parked run to hand over from — a handover ` +
+                        `resumes from a finished run's Resume Point, and there is nothing to resume. ` +
+                        `Run \`${this.config.bin} tasks runs ${taskId}\` to see the ledger.`,
+                    code: 'HANDOVER_NO_SOURCE_RUN',
+                    exit: 2,
+                    retryable: false,
+                });
+            }
+        }
+        const sourceRunId = String(sourceRun.runId ?? sourceRun.id ?? '');
+        // ── B1. ────────────────────────────────────────────────────────────────
+        let result;
+        try {
+            result = await (0, task_extras_1.taskRunHandover)(taskId, sourceRunId, {
+                targetAgentId: target.id,
+                ...(flags.harness ? { executionTargetRef: (0, task_extras_1.parseExecutionTargetRef)(flags.harness) } : {}),
+                ...(flags.reason ? { reason: flags.reason } : {}),
+            });
+        }
+        catch (err) {
+            const refusal = (0, base_command_1.apiRefusal)(err);
+            // The consent gate, named: the target must already be an assignee —
+            // the API never bundles a silent assign (impl contract B1). Turn the
+            // refusal into the two-step the operator actually has to run.
+            if (refusal.code?.toLowerCase() === 'target_not_assignee') {
+                this.failWithCliError({
+                    message: (refusal.message ?? `Agent ${flags.to} may not work this task.`) +
+                        `\n  → assign it first: \`${this.config.bin} tasks assign ${taskId} --agent "${flags.to}"\` ` +
+                        `(or \`${this.config.bin} tasks update ${taskId} --add-assignee-agent <agent-id>\`), ` +
+                        'then re-run this handover.',
+                    code: refusal.code,
+                    exit: 3,
+                    retryable: false,
+                    details: refusal.body,
+                });
+            }
+            this.handleApiError(err, { subject: `Task ${taskId}` });
+        }
+        if (flags.json) {
+            // {run, packet} verbatim — the packet IS the audit record, so a scripted
+            // caller gets exactly what the server stamped.
+            this.log(JSON.stringify(result, null, 2));
+            return;
+        }
+        const r = result;
+        const newRun = r.run ?? {};
+        const newRunId = String(newRun.runId ?? newRun.id ?? '?');
+        const resumePointId = typeof newRun.resumedFromResumePointId === 'string'
+            ? newRun.resumedFromResumePointId
+            : undefined;
+        const agentLabel = target.name ? `${target.name} (${target.id})` : target.id;
+        this.log(`Handed run ${sourceRunId} over to ${agentLabel}`);
+        this.log(`New run: ${newRunId}` +
+            `${newRun.startedAt || newRun.admittedAt ? ` at ${(0, format_1.localTime)(newRun.startedAt ?? newRun.admittedAt)}` : ''}`);
+        this.log(`Source run: ${sourceRunId}`);
+        this.log(`Resume point: ${resumePointId ?? 'none recorded'}`);
+        // Required, not optional (design §4.1): a packet that says what it left
+        // behind is the difference between a contract and a guess. An absent or
+        // empty list is printed as undeclared rather than silently dropped.
+        const notCarried = Array.isArray(r.packet?.notCarried)
+            ? r.packet.notCarried.map(String).filter(Boolean)
+            : [];
+        this.log(`Not carried: ${notCarried.length ? notCarried.join(', ') : '(nothing declared)'}`);
+    }
+}
+exports.default = TasksHandover;