@skrr-ai/cli 0.1.45 → 0.1.47

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;
 }

package/dist/commands/tasks/show.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.taskPointerLines = taskPointerLines;
+exports.blockerDetailLines = blockerDetailLines;
 exports.labelsLine = labelsLine;
 exports.taskExecutorLabel = taskExecutorLabel;
 exports.taskFailureLines = taskFailureLines;
@@ -52,6 +53,29 @@ function taskPointerLines(t, ref, bin = 'skrr') {
  * 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.
+ */
+function blockerDetailLines(detail) {
+    if (!detail)
+        return [];
+    const lines = [];
+    const cause = typeof detail.cause === 'string' ? detail.cause.trim() : '';
+    const required = typeof detail.requiredAction === 'string' ? detail.requiredAction.trim() : '';
+    const owner = detail.nextOwner;
+    if (cause)
+        lines.push(`Blocked on:  ${cause}`);
+    if (required)
+        lines.push(`Needs:       ${required}`);
+    if (owner && typeof owner.kind === 'string' && owner.kind) {
+        const who = typeof owner.userId === 'string' && owner.userId ? ` ${owner.userId}` : '';
+        lines.push(`Next owner:  ${owner.kind}${who}`);
+    }
+    return lines;
+}
 function labelsLine(labelIds, nameById) {
     const ids = (labelIds ?? []).filter((id) => typeof id === 'string' && id.length > 0);
     if (ids.length === 0)
@@ -370,6 +394,7 @@ class TasksShow extends base_command_1.BaseCommand {
         if (actionability) {
             this.log(`Next action: ${actionability.nextActor ?? '-'} · ${actionability.state ?? '-'} · ${actionability.reasonCode ?? '-'}`);
             this.log(`Why:         ${actionability.reason ?? '-'}`);
+            await this.printBlockerDetail(t, actionability);
         }
         const delivery = t.delivery;
         if (delivery?.prNumber || delivery?.prUrl || delivery?.branch) {
@@ -493,5 +518,39 @@ class TasksShow extends base_command_1.BaseCommand {
         for (const line of taskPointerLines(t, ref, this.config.bin))
             this.log(line);
     }
+    /**
+     * 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.
+     */
+    async printBlockerDetail(task, actionability) {
+        const looksBlocked = String(task.status ?? '') === 'blocked' || actionability.reasonCode === 'exceptional_hold';
+        if (!looksBlocked) {
+            return;
+        }
+        try {
+            const updates = await data_provider_1.dataService.listTaskUpdates(String(task.id), {
+                limit: 1,
+                type: 'blocker',
+            });
+            const detail = updates?.data?.[0]?.data;
+            for (const line of blockerDetailLines(detail)) {
+                this.log(line);
+            }
+        }
+        catch {
+            // The status line above already answered the question this decorates.
+        }
+    }
 }
 exports.default = TasksShow;

package/dist/lib/api-fetch.d.ts

@@ -30,7 +30,13 @@ export declare class ApiFetchError extends Error {
     readonly body?: string;
     readonly code?: string;
     readonly method?: string;
-    constructor(message: string, status: number, body?: string, code?: string, method?: string);
+    /**
+     * The server's `X-Request-ID` for the failing call, when it sent one. It is
+     * the id the server logs against, so a refusal can be looked up rather than
+     * attributed by guesswork — see `node-adapter.ts`.
+     */
+    readonly requestId?: string;
+    constructor(message: string, status: number, body?: string, code?: string, method?: string, requestId?: string);
 }
 /**
  * Call a skrr API endpoint with the current credential. Throws

package/dist/lib/api-fetch.js

@@ -54,13 +54,20 @@ class ApiFetchError extends Error {
     // (OSK-6765): `agents show` is a GET and had no body, and the advice was
     // impossible to follow.
     method;
-    constructor(message, status, body, code, method) {
+    /**
+     * The server's `X-Request-ID` for the failing call, when it sent one. It is
+     * the id the server logs against, so a refusal can be looked up rather than
+     * attributed by guesswork — see `node-adapter.ts`.
+     */
+    requestId;
+    constructor(message, status, body, code, method, requestId) {
         super(message);
         this.name = 'ApiFetchError';
         this.status = status;
         this.body = body;
         this.code = code;
         this.method = method;
+        this.requestId = requestId;
     }
 }
 exports.ApiFetchError = ApiFetchError;
@@ -209,7 +216,7 @@ async function apiFetch(pathOrUrl, opts = {}) {
         catch {
             /* ignore body read failures */
         }
-        throw new ApiFetchError(`HTTP ${res.status} ${res.statusText} — ${method} ${pathOrUrl}`, res.status, text, code, method);
+        throw new ApiFetchError(`HTTP ${res.status} ${res.statusText} — ${method} ${pathOrUrl}`, res.status, text, code, method, res.headers.get('x-request-id') || undefined);
     }
     // 204/205 carry no body by definition; an empty body has no content-type
     // worth judging. Neither is an error.

package/dist/lib/assignee-resolver.d.ts

@@ -25,6 +25,28 @@ export type SpaceMember = {
     name?: string;
     email?: string;
 };
+export type ExpertiseSuggestion = {
+    member: SpaceMember;
+    /** Expertise entries that exactly match a task tag (strong match). */
+    matchedTags: string[];
+    /** Expertise entries that appear in the task title/description (weak match). */
+    matchedText: string[];
+};
+/**
+ * Deterministic advisory lookup: which space members' declared `expertise`
+ * intersects this task's tags (strong) or appears in its title/description
+ * (weak). Not a routing decision — the caller still picks the assignee; this
+ * just surfaces the declared contract. Ranked: more tag matches first, then
+ * more text matches.
+ */
+export declare function suggestMembersByExpertise({ members, expertiseByMemberId, taskTags, taskText, }: {
+    members: SpaceMember[];
+    /** member.id → declared expertise labels */
+    expertiseByMemberId: Map<string, string[]>;
+    taskTags: string[];
+    /** Task title + description, any case — normalized internally. */
+    taskText: string;
+}): ExpertiseSuggestion[];
 export type ResolutionFailure = {
     ok: false;
     /**

package/dist/lib/assignee-resolver.js

@@ -1,5 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.suggestMembersByExpertise = suggestMembersByExpertise;
 exports.looksLikeRawId = looksLikeRawId;
 exports.membersFromPrincipals = membersFromPrincipals;
 exports.resolveMember = resolveMember;
@@ -9,6 +10,31 @@ exports.resolveAssigneeReferences = resolveAssigneeReferences;
 exports.formatResolutionFailure = formatResolutionFailure;
 const failed_lookup_1 = require("./failed-lookup");
 const data_provider_1 = require("@skrr-ai/data-provider");
+/**
+ * Deterministic advisory lookup: which space members' declared `expertise`
+ * intersects this task's tags (strong) or appears in its title/description
+ * (weak). Not a routing decision — the caller still picks the assignee; this
+ * just surfaces the declared contract. Ranked: more tag matches first, then
+ * more text matches.
+ */
+function suggestMembersByExpertise({ members, expertiseByMemberId, taskTags, taskText, }) {
+    const normTag = (v) => v.trim().toLowerCase();
+    const tags = new Set(taskTags.map(normTag));
+    const text = taskText.toLowerCase();
+    const out = [];
+    for (const member of members) {
+        const expertise = expertiseByMemberId.get(member.id);
+        if (!expertise || expertise.length === 0)
+            continue;
+        const matchedTags = expertise.filter((e) => tags.has(normTag(e)));
+        const matchedText = expertise.filter((e) => !matchedTags.includes(e) && normTag(e).length > 0 && text.includes(normTag(e)));
+        if (matchedTags.length > 0 || matchedText.length > 0) {
+            out.push({ member, matchedTags, matchedText });
+        }
+    }
+    out.sort((a, b) => b.matchedTags.length - a.matchedTags.length || b.matchedText.length - a.matchedText.length);
+    return out;
+}
 const OBJECT_ID_RE = /^[0-9a-fA-F]{24}$/;
 const UUID_RE = /^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$/;
 // Agent ids are transitioning from public UUIDs to opaque `agent_…` ids.