@skrr-ai/cli 0.1.36 → 0.1.38

package/dist/lib/followups.d.ts

@@ -0,0 +1,115 @@
+import { withQuery } from './triggers';
+type Query = Parameters<typeof withQuery>[1];
+type Json = Record<string, unknown>;
+/**
+ * The `id` argument every follow-up command that addresses one takes.
+ *
+ * oclif treats an empty string as a PRESENT required argument, so a scripted
+ * `skrr followups show "$ID"` with an empty variable built `/api/followups/` —
+ * the LIST route — and answered with the list's requirement, "agentId is
+ * required unless allAgents is set", naming two flags `show` does not have
+ * (OSK-9676). Refused at parse time instead, so it renders where a missing
+ * argument does, with usage, before any request is sent.
+ */
+export declare const followUpIdArg: import("@oclif/core/lib/interfaces").Arg<string, Record<string, unknown>>;
+export { FOLLOWUP_KINDS, FOLLOWUP_STATES, FOLLOWUP_RESOLVE_OUTCOMES, type FollowUpKind, } from '@skrr-ai/data-provider';
+export declare const WATCH_WAIT_KINDS: readonly ["clock", "event", "poll_until"];
+export interface FollowUpRow {
+    id: string;
+    kind?: string;
+    form?: string | null;
+    producer?: string;
+    why?: string;
+    /** A reminder's own words. */
+    content?: string | null;
+    intentKey?: string;
+    subject?: {
+        type?: string;
+        externalKey?: string;
+        label?: string;
+        url?: string;
+    } | null;
+    agentId?: string | null;
+    state?: string;
+    terminal?: string | null;
+    terminalAt?: string | null;
+    terminalReason?: string | null;
+    escalatedInitiativeId?: string | null;
+    capsule?: unknown;
+    nextRunAt?: string | null;
+    deadlineAt?: string | null;
+    createdAt?: string;
+    label?: string;
+}
+export interface FollowUpCreateResponse {
+    followup: FollowUpRow | null;
+    reused?: boolean;
+    dropped?: false | 'budget';
+    proposal?: boolean;
+    budget?: Json;
+    fallbackTriggerId?: string | null;
+}
+export interface FollowUpObservability {
+    generatedAt?: string;
+    agents?: Array<{
+        agentId: string;
+        kinds: Array<{
+            kind: string;
+            created: number;
+            armed: number;
+            proposed: number;
+            settled: number;
+            terminal: Record<string, number>;
+            escalationRate: number | null;
+            fires: number;
+            budget: {
+                pool: string | null;
+                used: number;
+                limit: number | null;
+            } | null;
+            silenceRate: number | null;
+            silentFires: number | null;
+        }>;
+    }>;
+}
+export type ResolvedFollowUpAgent = {
+    id: string;
+    /**
+     * True when the identity came from the session binding rather than a flag —
+     * a follow-up declared inside an agent's own turn is `agent_in_turn`; one
+     * declared by a human at a shell is `user_explicit`. The producer field is
+     * provenance, not authority, and this is the only honest signal a CLI has.
+     */
+    boundToSession: boolean;
+};
+/**
+ * Which agent a follow-up belongs to.
+ *
+ * Deliberately NOT `resolveAgentIdentity`: that resolver's last step picks
+ * "the only visible agent", and a follow-up bound to the wrong agent wakes
+ * the wrong agent in the wrong main chat. The only honest sources are an
+ * explicit `--agent` and the session binding the runtime already proves
+ * (`OVERSKY_SESSION_AGENT_ID`, or the legacy `OVERSKY_AGENT_ID` a manual
+ * local runtime sets). Anything else throws AGENT_CONTEXT_AMBIGUOUS and
+ * names the fix rather than guessing.
+ */
+export declare function resolveFollowUpAgent(explicitAgentId?: string, env?: Record<string, string | undefined>): ResolvedFollowUpAgent;
+/** A `type:externalKey` subject ref → the subject block the API wants. */
+export declare function parseSubjectRef(ref: string): {
+    type: string;
+    externalKey: string;
+};
+export declare const followupsApi: {
+    create: (body: Json) => Promise<FollowUpCreateResponse>;
+    list: (query?: Query) => Promise<{
+        followups: FollowUpRow[];
+    }>;
+    observability: (query?: Query) => Promise<FollowUpObservability>;
+    show: (id: string) => Promise<{
+        followup: FollowUpRow;
+    }>;
+    resolve: (id: string, body: Json) => Promise<Json>;
+    cancel: (id: string, body?: Json) => Promise<Json>;
+    reschedule: (id: string, body: Json) => Promise<Json>;
+};
+export declare function followupSummaryLine(row: FollowUpRow): string;

package/dist/lib/followups.js

@@ -0,0 +1,127 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.followupsApi = exports.WATCH_WAIT_KINDS = exports.FOLLOWUP_RESOLVE_OUTCOMES = exports.FOLLOWUP_STATES = exports.FOLLOWUP_KINDS = exports.followUpIdArg = void 0;
+exports.resolveFollowUpAgent = resolveFollowUpAgent;
+exports.parseSubjectRef = parseSubjectRef;
+exports.followupSummaryLine = followupSummaryLine;
+/**
+ * followups.ts — the `skrr followups` domain lib.
+ *
+ * A follow-up is ONE resource with four kinds (`reminder`, `watch`, `checkin`,
+ * `act`), declared by intent and derived into mechanism entirely server-side
+ * (`FollowUps/` + `docs/architecture/followup-service-2026-09-15.md`). The CLI
+ * is the universal substrate — a daemon-run local harness reaches the platform
+ * only through `skrr` — so every verb the API exposes lives here, and commands
+ * own flags only. The `followup_*` MCP tools wrap the same surface.
+ *
+ * What this file deliberately does NOT contain: executor modes, trigger kinds,
+ * destination logic, or budget policy. A caller names `kind` + `subject` +
+ * `why` and the server derives the rest; a second derivation here would be
+ * exactly the drift the service exists to kill.
+ */
+const core_1 = require("@oclif/core");
+const data_provider_1 = require("@skrr-ai/data-provider");
+const runtime_context_1 = require("./runtime-context");
+const triggers_1 = require("./triggers");
+const agent_resolver_1 = require("./agent-resolver");
+const MOUNT = '/api/followups';
+const base = (id) => `${MOUNT}/${encodeURIComponent(id)}`;
+/**
+ * The `id` argument every follow-up command that addresses one takes.
+ *
+ * oclif treats an empty string as a PRESENT required argument, so a scripted
+ * `skrr followups show "$ID"` with an empty variable built `/api/followups/` —
+ * the LIST route — and answered with the list's requirement, "agentId is
+ * required unless allAgents is set", naming two flags `show` does not have
+ * (OSK-9676). Refused at parse time instead, so it renders where a missing
+ * argument does, with usage, before any request is sent.
+ */
+exports.followUpIdArg = core_1.Args.string({
+    description: 'Follow-up (trigger) id',
+    required: true,
+    ignoreStdin: true,
+    parse: async (input) => {
+        const id = input.trim();
+        if (!id)
+            throw new Error('id is empty — pass the follow-up id (see `skrr followups list`)');
+        return id;
+    },
+});
+/* ------------------------------------------------------------------ *
+ * Vocabulary (client-side validation only — the server is the authority) *
+ * ------------------------------------------------------------------ */
+// Owned by `@skrr-ai/data-provider`, which the server validates against. These
+// were declared a second time here, and the state list is where the two copies
+// disagreed.
+var data_provider_2 = require("@skrr-ai/data-provider");
+Object.defineProperty(exports, "FOLLOWUP_KINDS", { enumerable: true, get: function () { return data_provider_2.FOLLOWUP_KINDS; } });
+Object.defineProperty(exports, "FOLLOWUP_STATES", { enumerable: true, get: function () { return data_provider_2.FOLLOWUP_STATES; } });
+Object.defineProperty(exports, "FOLLOWUP_RESOLVE_OUTCOMES", { enumerable: true, get: function () { return data_provider_2.FOLLOWUP_RESOLVE_OUTCOMES; } });
+exports.WATCH_WAIT_KINDS = ['clock', 'event', 'poll_until'];
+/**
+ * Which agent a follow-up belongs to.
+ *
+ * Deliberately NOT `resolveAgentIdentity`: that resolver's last step picks
+ * "the only visible agent", and a follow-up bound to the wrong agent wakes
+ * the wrong agent in the wrong main chat. The only honest sources are an
+ * explicit `--agent` and the session binding the runtime already proves
+ * (`OVERSKY_SESSION_AGENT_ID`, or the legacy `OVERSKY_AGENT_ID` a manual
+ * local runtime sets). Anything else throws AGENT_CONTEXT_AMBIGUOUS and
+ * names the fix rather than guessing.
+ */
+function resolveFollowUpAgent(explicitAgentId, env = process.env) {
+    const runtime = (0, runtime_context_1.readRuntimeContext)(env);
+    const sessionAgent = runtime.agent?.source === 'OVERSKY_SESSION_AGENT_ID' ||
+        runtime.agent?.source === 'OVERSKY_AGENT_ID'
+        ? runtime.agent
+        : undefined;
+    if (sessionAgent) {
+        if (explicitAgentId && explicitAgentId !== sessionAgent.id) {
+            throw new agent_resolver_1.AgentResolutionError({
+                code: 'AGENT_CONTEXT_CONFLICT',
+                message: 'This local runtime is bound to a session agent. Do not override it with another agent ID.',
+                suggestion: 'Use the bound session agent, or start a new daemon session for a different agent.',
+                details: { explicitAgentId, sessionAgentId: sessionAgent.id, source: sessionAgent.source },
+            });
+        }
+        return { id: sessionAgent.id, boundToSession: true };
+    }
+    if (explicitAgentId)
+        return { id: explicitAgentId, boundToSession: false };
+    throw new agent_resolver_1.AgentResolutionError({
+        code: 'AGENT_CONTEXT_AMBIGUOUS',
+        message: 'No agent: this session is not bound to one, so name the agent these follow-ups are for.',
+        suggestion: 'Pass `--agent <agent-id>`, run inside a daemon session that sets OVERSKY_SESSION_AGENT_ID, or use `--all-agents` where listing is the intent.',
+        details: { runtimeKind: runtime.kind },
+    });
+}
+/** A `type:externalKey` subject ref → the subject block the API wants. */
+function parseSubjectRef(ref) {
+    const idx = ref.indexOf(':');
+    if (idx <= 0 || idx === ref.length - 1) {
+        throw new Error(`--subject must be "type:externalKey" (e.g. task:OSK-42, conversation:conv_123), got "${ref}"`);
+    }
+    return { type: ref.slice(0, idx), externalKey: ref.slice(idx + 1) };
+}
+/* ------------------------------------------------------------------ *
+ * API                                                                  *
+ * ------------------------------------------------------------------ */
+exports.followupsApi = {
+    create: (body) => data_provider_1.request.post(MOUNT, body),
+    list: (query = {}) => data_provider_1.request.get((0, triggers_1.withQuery)(MOUNT, query)),
+    observability: (query = {}) => data_provider_1.request.get((0, triggers_1.withQuery)(`${MOUNT}/observability`, query)),
+    show: (id) => data_provider_1.request.get(base(id)),
+    resolve: (id, body) => data_provider_1.request.post(`${base(id)}/resolve`, body),
+    cancel: (id, body = {}) => data_provider_1.request.post(`${base(id)}/cancel`, body),
+    reschedule: (id, body) => data_provider_1.request.post(`${base(id)}/reschedule`, body),
+};
+/* ------------------------------------------------------------------ *
+ * Rendering                                                            *
+ * ------------------------------------------------------------------ */
+const fmtWhen = (iso) => (iso ? iso.slice(0, 16).replace('T', ' ') + 'Z' : '—');
+function followupSummaryLine(row) {
+    const subject = row.subject ? `${row.subject.type}:${row.subject.externalKey}` : '—';
+    const kindForm = row.form ? `${row.kind}/${row.form}` : (row.kind ?? '—');
+    const when = row.state === 'settled' ? `settled:${row.terminal ?? '?'}` : `next:${fmtWhen(row.nextRunAt)}`;
+    return `${row.id}  [${row.state ?? '?'}] ${kindForm}  ${subject}  ${when}`;
+}

package/dist/lib/harnesses.d.ts

@@ -42,6 +42,14 @@ export interface Harness {
     _id: string;
     provider: string;
     name?: string;
+    /**
+     * The name everyone else sees, when YOUR alias is covering it. `name` is the
+     * effective one. Present only while an alias is actually shadowing a
+     * different value, so a reader can tell "no alias" from "alias equals the
+     * shared name".
+     */
+    sharedName?: string;
+    aliased?: boolean;
     status?: string;
     harnessLocation?: 'local' | 'cloud';
     daemonId?: string;

package/dist/lib/instruction-input.d.ts

@@ -50,11 +50,29 @@ export declare function resolveBundleLabel(bundleId: string | undefined, names:
  * the daemon is genuinely gone. A remedy that 409s is worse than no remedy — it
  * spends the reader's attention and returns them to where they started.
  */
+/**
+ * A daemon id is `daemon_<hash>_<source>[_<profile>]`, where the hash covers
+ * the MACHINE and the cwd and `<source>` is the supervision mode
+ * (`cli`, `launchd`, `electron`, …). So two ids that differ only in that
+ * segment describe the SAME machine and directory, started a different way.
+ *
+ * That matters because switching how the daemon is started — the desktop app
+ * installs a launchd agent, `skrr daemon start` runs a cli one — mints a new
+ * id and orphans every managed-instruction target pinned to the old one.
+ */
+export declare function parseDaemonId(daemonId: string): {
+    place: string;
+    source: string;
+    profile: string;
+} | null;
+/** The live daemon that is this target's machine and directory, started differently. */
+export declare function sameMachineDaemon(targetDaemonId: string, liveDaemonIds: string[]): string | null;
 export declare function describeTargetSync(target: {
     status: string;
+    daemonId?: string;
     lastError?: string;
     lastSyncedAt?: string;
     lastAttemptedAt?: string;
     updatedAt?: string;
     driftCount?: number;
-}, now?: number): string;
+}, now?: number, liveDaemonIds?: string[]): string;

package/dist/lib/instruction-input.js

@@ -4,6 +4,8 @@ exports.readInstructionBody = readInstructionBody;
 exports.formatSyncStatus = formatSyncStatus;
 exports.buildBundleNameIndex = buildBundleNameIndex;
 exports.resolveBundleLabel = resolveBundleLabel;
+exports.parseDaemonId = parseDaemonId;
+exports.sameMachineDaemon = sameMachineDaemon;
 exports.describeTargetSync = describeTargetSync;
 const promises_1 = require("node:fs/promises");
 async function readStdin() {
@@ -93,7 +95,39 @@ const PENDING_IS_SUSPECT_AFTER_MS = 24 * 60 * 60 * 1000;
  * the daemon is genuinely gone. A remedy that 409s is worse than no remedy — it
  * spends the reader's attention and returns them to where they started.
  */
-function describeTargetSync(target, now = Date.now()) {
+/**
+ * A daemon id is `daemon_<hash>_<source>[_<profile>]`, where the hash covers
+ * the MACHINE and the cwd and `<source>` is the supervision mode
+ * (`cli`, `launchd`, `electron`, …). So two ids that differ only in that
+ * segment describe the SAME machine and directory, started a different way.
+ *
+ * That matters because switching how the daemon is started — the desktop app
+ * installs a launchd agent, `skrr daemon start` runs a cli one — mints a new
+ * id and orphans every managed-instruction target pinned to the old one.
+ */
+function parseDaemonId(daemonId) {
+    const parts = String(daemonId || '').split('_');
+    if (parts.length < 3 || parts[0] !== 'daemon')
+        return null;
+    return { place: parts[1], source: parts[2], profile: parts.slice(3).join('_') };
+}
+/** The live daemon that is this target's machine and directory, started differently. */
+function sameMachineDaemon(targetDaemonId, liveDaemonIds) {
+    const target = parseDaemonId(targetDaemonId);
+    if (!target)
+        return null;
+    for (const live of liveDaemonIds) {
+        if (live === targetDaemonId)
+            continue;
+        const other = parseDaemonId(live);
+        if (!other)
+            continue;
+        if (other.place === target.place && other.profile === target.profile)
+            return live;
+    }
+    return null;
+}
+function describeTargetSync(target, now = Date.now(), liveDaemonIds = []) {
     const base = formatSyncStatus(target.status, target.lastError);
     // Say when skrr has overwritten something you typed.
     //
@@ -131,5 +165,22 @@ function describeTargetSync(target, now = Date.now()) {
     // remedy off the end — the same truncation e51abf3362 exists to prevent. A
     // stalled target is not reconciling, so its drift is historical and the
     // remedy is the actionable half; the count reappears once it is unstuck.
+    // CHECK BEFORE ASSERTING, and never ship `--force` with a guess.
+    //
+    // "daemon may be gone" was stated unconditionally. On this machine it was
+    // false — the daemon had answered a heartbeat 112 ms earlier — because the
+    // target is pinned to `daemon_<hash>_launchd_default` while the live daemon
+    // is `daemon_<hash>_cli_default`: same machine, same directory, started a
+    // different way. So the CLI confidently recommended
+    // `remove, then purge-target --force` against live, correctly-installed
+    // managed blocks. An error that is confidently wrong AND carries its own
+    // `--force` is worse than one that says it does not know.
+    const elsewhere = sameMachineDaemon(target.daemonId || '', liveDaemonIds);
+    if (elsewhere) {
+        const live = parseDaemonId(elsewhere);
+        const pinned = parseDaemonId(target.daemonId || '');
+        // Kept under the STATUS column's `maxWidth: 78`, same constraint as below.
+        return `${base} — stalled ${days}d; daemon here now runs as ${live?.source}, not ${pinned?.source}: re-install`;
+    }
     return `${base} — stalled ${days}d; daemon may be gone: remove, then purge-target --force`;
 }

package/dist/lib/label-ref.d.ts

@@ -0,0 +1,95 @@
+/**
+ * label-ref.ts — let a human type `--label dogfood` instead of a uuid.
+ *
+ * WHY
+ * ---
+ * Labels are addressed by id everywhere: `spaces labels add <space> --label
+ * <uuid>`. That is correct for the wire and hostile at a keyboard, and the cost
+ * was measurable — the fleet reached nine labels, every one of them
+ * `applicableTo: ['task']`, and not one space-applicable label had ever been
+ * created. Applying one meant `labels list`, eyeball the uuid, paste it. Three
+ * steps to do the thing the flag already existed for.
+ *
+ * THE RULE, AND WHY IT IS NOT "CREATE IT IF MISSING"
+ * -------------------------------------------------
+ * An unknown name is REFUSED, with the closest matches named. It is never
+ * created.
+ *
+ * Auto-create is the obvious convenience and it is the one thing that destroys
+ * the vocabulary: `--label dogfod` would mint a second label nobody meant, and
+ * a label is worth exactly as much as the completeness of a filter on it. The
+ * server draws the same line for every agent-supplied key — the operator
+ * declares the vocabulary, the caller chooses from it (`WakeIntentResolver`,
+ * the `agent_run` watched source, and `Labels/labelGuidance.js`). This is that
+ * rule at the keyboard instead of at the model.
+ *
+ * Refusing is also what makes the typo cheap: the caller sees
+ * `did you mean: dogfood?` and retries, instead of discovering six weeks later
+ * that half the program is under a name nobody can spell twice.
+ *
+ * An id passes through UNTOUCHED and costs no round trip — scripts and agents
+ * that already hold ids keep working exactly as before, and nothing here is on
+ * their path.
+ */
+import { dataService } from '@skrr-ai/data-provider';
+import type { LabelApplicable } from './label-scope';
+export declare function looksLikeLabelId(ref: string): boolean;
+/**
+ * A label row as the API returns it. Narrow on purpose at the fields this
+ * module reasons about; everything else rides along untouched so callers that
+ * RENDER labels (`labels list`) can use the same merge.
+ */
+export interface LabelRow {
+    id: string;
+    name: string;
+    scope?: string;
+    scopeId?: string;
+    color?: string;
+    applicableTo?: string[];
+    usageCount?: number;
+    archivedAt?: string | null;
+    [key: string]: unknown;
+}
+/**
+ * Names close enough to be worth printing. A suggestion list that includes
+ * everything is the same as no suggestion list — the caller still has to read
+ * all of it — so the threshold scales with the typed length and caps at three.
+ */
+export declare function closestNames(typed: string, names: string[], limit?: number): string[];
+export interface LabelVocabularyContext {
+    /** Narrow to labels attachable to this entity type. Omit for all of them. */
+    applicableTo?: LabelApplicable;
+    /** Narrows to the workspace scope; `--workspace` / OVERSKY_WORKSPACE_ID. */
+    workspaceId?: string;
+    /** Archived labels are excluded unless asked for. */
+    includeArchived?: boolean;
+    /** Injected in tests. */
+    getLabels?: typeof dataService.getLabels;
+}
+export interface LabelRefContext extends LabelVocabularyContext {
+    /** Which entity the resolved labels will be attached to. */
+    applicableTo: LabelApplicable;
+}
+/**
+ * Every scope this caller could legitimately attach from, merged.
+ *
+ * `GET /api/labels` takes ONE scope, and a label the caller may attach can live
+ * in either of two. Asking for one and calling it "the vocabulary" would refuse
+ * a name that exists — which is the failure mode that makes people stop using
+ * names at all. A scope that cannot be read contributes nothing and throws
+ * nothing: this runs to produce a better error message, and must never become
+ * the error.
+ */
+export declare function collectLabelVocabulary(context: LabelVocabularyContext): Promise<LabelRow[]>;
+export declare class LabelRefError extends Error {
+}
+/**
+ * Resolve `--label` / `--label-id` values, each either an id or a name.
+ *
+ * Throws `LabelRefError` with an actionable message when a name does not
+ * resolve, or resolves to more than one label. Ambiguity is a refusal rather
+ * than a pick: the same name may legitimately exist in a user scope and a
+ * workspace scope, and guessing which one the caller meant is how the wrong
+ * label ends up attached to a year of work.
+ */
+export declare function resolveLabelRefs(refs: string[] | undefined, context: LabelRefContext): Promise<string[]>;

package/dist/lib/label-ref.js

@@ -0,0 +1,163 @@
+"use strict";
+/**
+ * label-ref.ts — let a human type `--label dogfood` instead of a uuid.
+ *
+ * WHY
+ * ---
+ * Labels are addressed by id everywhere: `spaces labels add <space> --label
+ * <uuid>`. That is correct for the wire and hostile at a keyboard, and the cost
+ * was measurable — the fleet reached nine labels, every one of them
+ * `applicableTo: ['task']`, and not one space-applicable label had ever been
+ * created. Applying one meant `labels list`, eyeball the uuid, paste it. Three
+ * steps to do the thing the flag already existed for.
+ *
+ * THE RULE, AND WHY IT IS NOT "CREATE IT IF MISSING"
+ * -------------------------------------------------
+ * An unknown name is REFUSED, with the closest matches named. It is never
+ * created.
+ *
+ * Auto-create is the obvious convenience and it is the one thing that destroys
+ * the vocabulary: `--label dogfod` would mint a second label nobody meant, and
+ * a label is worth exactly as much as the completeness of a filter on it. The
+ * server draws the same line for every agent-supplied key — the operator
+ * declares the vocabulary, the caller chooses from it (`WakeIntentResolver`,
+ * the `agent_run` watched source, and `Labels/labelGuidance.js`). This is that
+ * rule at the keyboard instead of at the model.
+ *
+ * Refusing is also what makes the typo cheap: the caller sees
+ * `did you mean: dogfood?` and retries, instead of discovering six weeks later
+ * that half the program is under a name nobody can spell twice.
+ *
+ * An id passes through UNTOUCHED and costs no round trip — scripts and agents
+ * that already hold ids keep working exactly as before, and nothing here is on
+ * their path.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LabelRefError = void 0;
+exports.looksLikeLabelId = looksLikeLabelId;
+exports.closestNames = closestNames;
+exports.collectLabelVocabulary = collectLabelVocabulary;
+exports.resolveLabelRefs = resolveLabelRefs;
+const data_provider_1 = require("@skrr-ai/data-provider");
+/** A canonical v4 uuid, which is what every label id is. */
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+function looksLikeLabelId(ref) {
+    return UUID_RE.test(ref.trim());
+}
+/** Levenshtein, iterative, two rows. Only ever runs on a refusal path. */
+function distance(a, b) {
+    if (a === b)
+        return 0;
+    if (!a.length)
+        return b.length;
+    if (!b.length)
+        return a.length;
+    let prev = Array.from({ length: b.length + 1 }, (_, i) => i);
+    for (let i = 1; i <= a.length; i += 1) {
+        const row = [i];
+        for (let j = 1; j <= b.length; j += 1) {
+            row[j] = Math.min(prev[j] + 1, row[j - 1] + 1, prev[j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1));
+        }
+        prev = row;
+    }
+    return prev[b.length];
+}
+/**
+ * Names close enough to be worth printing. A suggestion list that includes
+ * everything is the same as no suggestion list — the caller still has to read
+ * all of it — so the threshold scales with the typed length and caps at three.
+ */
+function closestNames(typed, names, limit = 3) {
+    const needle = typed.trim().toLowerCase();
+    const budget = Math.max(2, Math.ceil(needle.length / 3));
+    return names
+        .map((name) => ({ name, d: distance(needle, name.toLowerCase()) }))
+        .filter((row) => row.d <= budget || row.name.toLowerCase().includes(needle))
+        .sort((a, b) => a.d - b.d)
+        .slice(0, limit)
+        .map((row) => row.name);
+}
+/**
+ * Every scope this caller could legitimately attach from, merged.
+ *
+ * `GET /api/labels` takes ONE scope, and a label the caller may attach can live
+ * in either of two. Asking for one and calling it "the vocabulary" would refuse
+ * a name that exists — which is the failure mode that makes people stop using
+ * names at all. A scope that cannot be read contributes nothing and throws
+ * nothing: this runs to produce a better error message, and must never become
+ * the error.
+ */
+async function collectLabelVocabulary(context) {
+    const getLabels = context.getLabels ?? data_provider_1.dataService.getLabels;
+    const requests = [{ scope: 'user' }];
+    if (context.workspaceId)
+        requests.push({ scope: 'workspace', scopeId: context.workspaceId });
+    const settled = await Promise.allSettled(requests.map((request) => getLabels({
+        ...request,
+        ...(context.applicableTo ? { applicableTo: context.applicableTo } : {}),
+        ...(context.includeArchived ? { includeArchived: true } : {}),
+    })));
+    const byId = new Map();
+    for (const outcome of settled) {
+        if (outcome.status !== 'fulfilled')
+            continue;
+        for (const row of outcome.value?.data ?? []) {
+            if (row?.id && !byId.has(row.id))
+                byId.set(row.id, row);
+        }
+    }
+    return [...byId.values()];
+}
+class LabelRefError extends Error {
+}
+exports.LabelRefError = LabelRefError;
+/**
+ * Resolve `--label` / `--label-id` values, each either an id or a name.
+ *
+ * Throws `LabelRefError` with an actionable message when a name does not
+ * resolve, or resolves to more than one label. Ambiguity is a refusal rather
+ * than a pick: the same name may legitimately exist in a user scope and a
+ * workspace scope, and guessing which one the caller meant is how the wrong
+ * label ends up attached to a year of work.
+ */
+async function resolveLabelRefs(refs, context) {
+    const input = (refs ?? []).map((ref) => ref.trim()).filter(Boolean);
+    if (input.length === 0)
+        return [];
+    // Ids are the wire form and the common case for scripts. Resolve nothing,
+    // fetch nothing, and let the server be the authority on whether they exist.
+    if (input.every(looksLikeLabelId))
+        return input;
+    const vocabulary = await collectLabelVocabulary(context);
+    const resolved = [];
+    for (const ref of input) {
+        if (looksLikeLabelId(ref)) {
+            resolved.push(ref);
+            continue;
+        }
+        const needle = ref.toLowerCase();
+        const matches = vocabulary.filter((row) => (row.name ?? '').toLowerCase() === needle);
+        if (matches.length === 1) {
+            resolved.push(matches[0].id);
+            continue;
+        }
+        if (matches.length > 1) {
+            const listed = matches
+                .map((row) => `  ${row.id}  ${row.name}${row.scope ? ` (${row.scope})` : ''}`)
+                .join('\n');
+            throw new LabelRefError(`"${ref}" names ${matches.length} labels. Pass the id you mean:\n${listed}`);
+        }
+        if (vocabulary.length === 0) {
+            throw new LabelRefError(`No label named "${ref}" — and no label applies to ${context.applicableTo}s yet. ` +
+                `Create one with \`labels create --name ${ref} --applicable-to ${context.applicableTo}\`.`);
+        }
+        const near = closestNames(ref, vocabulary.map((row) => row.name));
+        throw new LabelRefError(`No label named "${ref}" applies to ${context.applicableTo}s.` +
+            (near.length ? ` Did you mean: ${near.join(', ')}?` : '') +
+            ` Run \`labels list\` for the vocabulary, or create it deliberately with ` +
+            `\`labels create --name ${ref} --applicable-to ${context.applicableTo}\` — ` +
+            'a name is never created implicitly, because a second spelling of a label ' +
+            'is worse than no label.');
+    }
+    return resolved;
+}

package/dist/lib/label-scope.d.ts

@@ -1,7 +1,7 @@
 /**
  * Shared plumbing for the unified label commands (`skrr labels …`).
  *
- * Labels are anchored to exactly one scope — a user, a space, or a workspace —
+ * Labels are anchored to exactly one scope — a user or a workspace —
  * via the `(scope, scopeId)` pair. That pair is simultaneously the uniqueness
  * key and the permission boundary server-side (see
  * `api/server/services/Labels/LabelService.js`), so every label command has to
@@ -9,8 +9,23 @@
  * always explicit; `user` is the default because that is the only scope whose
  * id the server can infer (it falls back to the caller).
  */
-export declare const LABEL_SCOPES: readonly ["user", "space", "workspace"];
+export declare const LABEL_SCOPES: readonly ["user", "workspace"];
 export type LabelScope = (typeof LABEL_SCOPES)[number];
+/**
+ * Scopes whose id the server cannot infer, so `--scope-id` must name it.
+ *
+ * `resolveLabelScope` below and the `--scope-id` help text are BOTH derived
+ * from this, rather than each restating the list. They drifted once already:
+ * `0298b7e4fd` collapsed the vocabulary from three scopes to two, and the help
+ * kept advertising `--scope space` for months after the validator had stopped
+ * accepting it — so following `--help` produced `Expected --scope=space to be
+ * one of: user, workspace`, whose last line points back at the help that was
+ * wrong. Static prose describing a value set is how that happens; deriving it
+ * is what stops the next collapse doing the same.
+ */
+export declare const LABEL_SCOPES_REQUIRING_ID: readonly ["workspace"];
+/** Scopes the server resolves from the caller — passing an id is an error. */
+export declare const LABEL_SCOPES_INFERRED: "user"[];
 export declare const LABEL_APPLICABLE: readonly ["task", "space", "goal", "routine"];
 export type LabelApplicable = (typeof LABEL_APPLICABLE)[number];
 /**