@skrr-ai/cli 0.1.45 → 0.1.46

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;

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

@@ -0,0 +1,23 @@
+import { BaseCommand } from '../../base-command';
+/**
+ * `skrr tasks promote` — settle a parallel group (B8).
+ *
+ * This is the destructive half of fork/race: fixing one branch as canonical
+ * CANCELS every live loser in the group. That is why it is its own verb with
+ * its own confirmation rather than a flag, and why the command prints what it
+ * cancelled rather than reporting only the winner.
+ */
+export default class TasksPromote 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>;
+        run: import("@oclif/core/lib/interfaces").OptionFlag<string, import("@oclif/core/lib/interfaces").CustomOptions>;
+        'group-member': import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+    };
+    run(): Promise<void>;
+}

package/dist/commands/tasks/promote.js

@@ -0,0 +1,82 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const core_1 = require("@oclif/core");
+const base_command_1 = require("../../base-command");
+const task_extras_1 = require("../../lib/task-extras");
+const task_resolver_1 = require("../../lib/task-resolver");
+/**
+ * `skrr tasks promote` — settle a parallel group (B8).
+ *
+ * This is the destructive half of fork/race: fixing one branch as canonical
+ * CANCELS every live loser in the group. That is why it is its own verb with
+ * its own confirmation rather than a flag, and why the command prints what it
+ * cancelled rather than reporting only the winner.
+ */
+class TasksPromote extends base_command_1.BaseCommand {
+    static description = 'Fix one branch of a parallel run group as canonical and cancel the live losers (B8)';
+    static examples = [
+        '<%= config.bin %> tasks promote <task-id> --run <run-id>',
+        '<%= config.bin %> tasks promote <task-id> --run <run-id> --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 resolution as JSON' }),
+        task: core_1.Flags.string({ description: 'Task ID; overrides daemon runtime context' }),
+        run: core_1.Flags.string({
+            description: 'The run to make canonical — must be a member of the parallel group',
+            required: true,
+        }),
+        'group-member': core_1.Flags.string({
+            description: 'Any run in the group to address it by (default: the canonical run itself, which is ' +
+                'always a member)',
+        }),
+    };
+    async run() {
+        this.requireAuth();
+        const { args, flags } = await this.parse(TasksPromote);
+        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 route resolves the GROUP from the addressed run, then requires the
+        // canonical run to be a member of it. Addressing by the canonical run
+        // itself is always valid and is the obvious default.
+        const addressedRunId = flags['group-member'] ?? flags.run;
+        let result;
+        try {
+            result = await (0, task_extras_1.taskRunPromote)(taskId, addressedRunId, { canonicalRunId: flags.run });
+        }
+        catch (err) {
+            this.handleApiError(err, { subject: `Task ${taskId}` });
+        }
+        if (flags.json) {
+            this.log(JSON.stringify(result, null, 2));
+            return;
+        }
+        const r = result;
+        const cancelled = Array.isArray(r.cancelledRunIds) ? r.cancelledRunIds.map(String) : [];
+        this.log(`Canonical run: ${r.canonicalRunId ?? flags.run}`);
+        this.log(`Parallel group: ${r.groupId ?? '?'}`);
+        this.log(cancelled.length
+            ? `Cancelled ${cancelled.length} losing run(s): ${cancelled.join(', ')}`
+            : 'Cancelled no runs — every other branch had already finished.');
+    }
+}
+exports.default = TasksPromote;

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

@@ -16,6 +16,22 @@ export declare function formatRunExecutor(run: Record<string, unknown>): string;
  * list, always once something failed.
  */
 export declare function runNeedsFailureReason(run: Record<string, unknown>): boolean;
+/**
+ * The handover fields a run row may carry (execution-handover impl contracts):
+ *
+ *   `handover`      — the packet stamped on a run ADMITTED BY a handover; this
+ *                     run is the continuation, `packet.from.runId` is where it
+ *                     resumed from.
+ *   `handoverOffer` — the structured offer a retargetable terminal failure
+ *                     leaves behind (`{failureReason, resetAt?, actedRunId?}`).
+ *                     `actedRunId` means the offer was taken and names the
+ *                     continuation run.
+ *
+ * Both are absent on a server that predates them, so this returns null and the
+ * column below is rendered only when at least one row carries a marker — a
+ * healthy list against an older deployment pays and shows nothing.
+ */
+export declare function runHandoverMarker(run: Record<string, unknown>): string | null;
 /**
  * The run's OWN failure fields, when the server carries them.
  *

package/dist/commands/tasks/runs.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.formatRunExecutor = formatRunExecutor;
 exports.runNeedsFailureReason = runNeedsFailureReason;
+exports.runHandoverMarker = runHandoverMarker;
 exports.failureFromRun = failureFromRun;
 exports.renderRunFailures = renderRunFailures;
 const core_1 = require("@oclif/core");
@@ -46,6 +47,42 @@ function runNeedsFailureReason(run) {
         return true;
     return typeof run.errors === 'number' && run.errors > 0;
 }
+/**
+ * The handover fields a run row may carry (execution-handover impl contracts):
+ *
+ *   `handover`      — the packet stamped on a run ADMITTED BY a handover; this
+ *                     run is the continuation, `packet.from.runId` is where it
+ *                     resumed from.
+ *   `handoverOffer` — the structured offer a retargetable terminal failure
+ *                     leaves behind (`{failureReason, resetAt?, actedRunId?}`).
+ *                     `actedRunId` means the offer was taken and names the
+ *                     continuation run.
+ *
+ * Both are absent on a server that predates them, so this returns null and the
+ * column below is rendered only when at least one row carries a marker — a
+ * healthy list against an older deployment pays and shows nothing.
+ */
+function runHandoverMarker(run) {
+    const packet = run.handover;
+    if (packet && typeof packet === 'object') {
+        const from = packet.from;
+        const fromRun = from &&
+            typeof from === 'object' &&
+            typeof from.runId === 'string'
+            ? ` ← ${String(from.runId)}`
+            : '';
+        return `handover${fromRun}`;
+    }
+    const offer = run.handoverOffer;
+    if (offer && typeof offer === 'object') {
+        const o = offer;
+        if (o.actedRunId)
+            return `offer → ${String(o.actedRunId)}`;
+        const reason = typeof o.failureReason === 'string' ? o.failureReason : '';
+        return `offer${reason ? `:${reason}` : ''}`;
+    }
+    return null;
+}
 /**
  * The run's OWN failure fields, when the server carries them.
  *
@@ -151,13 +188,20 @@ class TasksRuns extends base_command_1.BaseCommand {
             this.log('No runs.');
             return;
         }
-        const rows = items.map((run) => ({
+        const markers = items.map(runHandoverMarker);
+        // The column exists only when a run carries a handover field — an older
+        // deployment sends neither, and an always-on column of '-' is noise.
+        const showHandover = markers.some(Boolean);
+        const rows = items.map((run, i) => ({
             runId: String(run.runId ?? run.id ?? run._id ?? '-'),
             status: String(run.status ?? '-'),
             executor: formatRunExecutor(run),
             started: run.startedAt ? (0, format_1.localTime)(run.startedAt) : '-',
             duration: run.durationMs != null ? `${run.durationMs}ms` : '-',
             tokens: String(run.totalTokens ?? run.tokens ?? '-'),
+            // Always present on the row so the record type stays uniform; the COLUMN
+            // is what is conditional.
+            handover: markers[i] ?? '-',
         }));
         (0, format_1.renderTable)(rows, [
             { key: 'runId', header: 'RUN ID' },
@@ -166,6 +210,7 @@ class TasksRuns extends base_command_1.BaseCommand {
             { key: 'started', header: 'STARTED' },
             { key: 'duration', header: 'DURATION' },
             { key: 'tokens', header: 'TOKENS' },
+            ...(showHandover ? [{ key: 'handover', header: 'HANDOVER' }] : []),
         ], (line) => this.log(line));
         // Only once something failed: a healthy list pays nothing for this.
         if (!unexplained)

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

@@ -20,6 +20,13 @@ export declare function taskPointerLines(t: Record<string, unknown>, ref: string
  * be read (or a label missing from it) degrades per entry rather than failing
  * the command or hiding the label.
  */
+/**
+ * The lines that say what a blocked Task is waiting on.
+ *
+ * Kept pure so the rule is testable without a network: the command fetches the
+ * newest `blocker` Update and hands its payload here.
+ */
+export declare function blockerDetailLines(detail: Record<string, unknown> | undefined): string[];
 export declare function labelsLine(labelIds?: string[], nameById?: Map<string, string>): string;
 /**
  * The `Executor:` value — who does this task, and whether anyone said so.
@@ -73,4 +80,20 @@ export default class TasksShow extends BaseCommand {
         'no-enrich': import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
     };
     run(): Promise<void>;
+    /**
+     * What a blocked Task is actually waiting on.
+     *
+     * The workflow tells an agent to record a typed `blocker` Update —
+     * `{cause, requiredAction, nextOwner}` — and only then move the Task to
+     * blocked. The move writes its own exceptional hold, whose summary is the
+     * `--reason` flag or the literal fallback `Task was marked blocked`, and that
+     * is what `Why:` prints. So the one line a reader looks at restated the
+     * status, while the thing the writer was told to record sat one command away
+     * in `tasks updates list` (OSK-10391).
+     *
+     * Read only for a blocked Task, and only the newest blocker Update. A failure
+     * here prints nothing: this decorates an answer the caller already has, and
+     * must never be the reason `tasks show` cannot answer at all.
+     */
+    private printBlockerDetail;
 }