@skrr-ai/cli 0.1.37 → 0.1.38

package/dist/lib/search-query.js

@@ -0,0 +1,35 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveSearchQuery = resolveSearchQuery;
+/**
+ * The search term, from a positional or `--query`, resolved the same way by
+ * both spellings of the same search.
+ *
+ * `skills search` and `search skills` run the identical store search. Neither
+ * accepted the obvious invocation — `skrr skills search git` — so the single
+ * most natural way to call a search command failed on both, and `--query` was
+ * `required` on both, which is what made it fail rather than prompt.
+ *
+ * Shared rather than copied because the two spellings staying in step is the
+ * whole point: the reason a reader could not tell them apart was that they had
+ * drifted (different one-liners, short flags on one of them), and a second copy
+ * of this is how that starts again.
+ */
+function resolveSearchQuery(cmd, positional, flag, command) {
+    const fromPositional = positional?.trim();
+    const fromFlag = flag?.trim();
+    // Both given and DIFFERENT is a real ambiguity — refuse rather than pick.
+    // Both given and identical is a script that passes belt and braces; that is
+    // not an error and silently accepting it costs nobody anything.
+    if (fromPositional && fromFlag && fromPositional !== fromFlag) {
+        cmd.error(`Two different search terms: "${fromPositional}" and --query "${fromFlag}". Pass one.`, { exit: 2 });
+    }
+    const query = fromPositional || fromFlag;
+    if (!query) {
+        // `--query` used to be `required`, so oclif refused with its own generic
+        // sentence. Naming the shape people actually type is the point of the
+        // change, so the error names it too.
+        cmd.error(`What should I search for? Try \`skrr ${command} <term>\`.`, { exit: 2 });
+    }
+    return query;
+}

package/dist/lib/space-custom-actions.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Shared shape for `skrr spaces actions add|update`.
+ *
+ * Both commands describe the same stored object, and they had drifted from the
+ * server that validates it (`spaceCustomActionSchema` in api/server/routes/spaces.js).
+ */
+import type { SpaceCustomAction, SpaceMemberActionsResponse } from '@skrr-ai/data-provider';
+/**
+ * The server's limit on `icon`, which is `z.string().max(4)`.
+ *
+ * The flag used to be documented as "Lucide icon name". It is not one: the web
+ * settings page renders `action.icon` as literal text, and almost no Lucide name
+ * fits in four characters, so following the help produced a 400 with a raw Zod
+ * message and no hint that an emoji was wanted (OSK-9631).
+ *
+ * Zod's `max` counts UTF-16 code units, not visible characters, so the check
+ * below uses `String.prototype.length` to agree with it exactly. Counting
+ * graphemes instead would accept a family emoji the server then refuses.
+ */
+export declare const SPACE_CUSTOM_ACTION_ICON_MAX = 4;
+export declare const spaceCustomActionIconFlag: import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+export declare const spaceCustomActionLabelFlag: import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+/** Refuse an icon the server would refuse, with a message that says what fits. */
+export declare function spaceCustomActionIconProblem(icon: unknown): string | null;
+type SpaceWithActions = {
+    id: string;
+    title?: string;
+    leadAgentId?: string | null;
+    customActions?: SpaceCustomAction[] | null;
+};
+/**
+ * Why a space's OWN actions cannot run, or null when they can.
+ *
+ * A space custom action runs as a task assigned to the Space Leader, so on a
+ * space with no Leader every one of them is dead on arrival. That fact used to
+ * live only in a tooltip on a disabled web button: `spaces actions add` reported
+ * success, `spaces actions list` listed the action happily, and nothing on the
+ * CLI said it could never run (OSK-9641).
+ */
+export declare function spaceActionsNotRunnableReason(space: Pick<SpaceWithActions, 'id' | 'leadAgentId'>, bin: string): string | null;
+/**
+ * Find a space custom action by the id `spaces actions list` prints, or by the
+ * `space-custom:<id>` form the projected quick-action surfaces use.
+ */
+export declare function findSpaceCustomAction(space: SpaceWithActions, ref: string): {
+    customAction: SpaceCustomAction;
+    index: number;
+} | {
+    problem: string;
+};
+export type SpaceQuickActionRow = {
+    source: 'space' | 'agent';
+    title: string;
+    owner: string;
+    type: string;
+    ref: string;
+    run: string;
+};
+/**
+ * Everything a space's action panel offers, in the order the web shows it: the
+ * space's own actions first, then the actions of member agents the caller can
+ * view, filtered by scope with the same predicate the web and server use.
+ *
+ * `spaces actions list` showed only the first half and `spaces actions
+ * available` a wider second half (every member agent, including ones the caller
+ * cannot run), so "what can I run here?" had no answer on the CLI (OSK-9641).
+ * Every row's `run` is a command `spaces actions run` accepts.
+ */
+export declare function spaceQuickActionRows(space: SpaceWithActions & {
+    labelIds?: string[] | null;
+}, members: SpaceMemberActionsResponse['agents'], bin: string): SpaceQuickActionRow[];
+export {};

package/dist/lib/space-custom-actions.js

@@ -0,0 +1,117 @@
+"use strict";
+/**
+ * Shared shape for `skrr spaces actions add|update`.
+ *
+ * Both commands describe the same stored object, and they had drifted from the
+ * server that validates it (`spaceCustomActionSchema` in api/server/routes/spaces.js).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.spaceCustomActionLabelFlag = exports.spaceCustomActionIconFlag = exports.SPACE_CUSTOM_ACTION_ICON_MAX = void 0;
+exports.spaceCustomActionIconProblem = spaceCustomActionIconProblem;
+exports.spaceActionsNotRunnableReason = spaceActionsNotRunnableReason;
+exports.findSpaceCustomAction = findSpaceCustomAction;
+exports.spaceQuickActionRows = spaceQuickActionRows;
+const core_1 = require("@oclif/core");
+const data_provider_1 = require("@skrr-ai/data-provider");
+/**
+ * The server's limit on `icon`, which is `z.string().max(4)`.
+ *
+ * The flag used to be documented as "Lucide icon name". It is not one: the web
+ * settings page renders `action.icon` as literal text, and almost no Lucide name
+ * fits in four characters, so following the help produced a 400 with a raw Zod
+ * message and no hint that an emoji was wanted (OSK-9631).
+ *
+ * Zod's `max` counts UTF-16 code units, not visible characters, so the check
+ * below uses `String.prototype.length` to agree with it exactly. Counting
+ * graphemes instead would accept a family emoji the server then refuses.
+ */
+exports.SPACE_CUSTOM_ACTION_ICON_MAX = 4;
+exports.spaceCustomActionIconFlag = core_1.Flags.string({
+    description: `Emoji shown on the button, e.g. ✨ (at most ${exports.SPACE_CUSTOM_ACTION_ICON_MAX} UTF-16 units). Not an icon name.`,
+});
+exports.spaceCustomActionLabelFlag = core_1.Flags.string({
+    description: 'Button text shown in the space. Not a Label entity — to offer an agent action in every space carrying a Label, use `agents actions create --label`.',
+});
+/** Refuse an icon the server would refuse, with a message that says what fits. */
+function spaceCustomActionIconProblem(icon) {
+    if (icon === undefined || icon === null)
+        return null;
+    if (typeof icon !== 'string')
+        return '--icon must be text.';
+    if (icon.length > exports.SPACE_CUSTOM_ACTION_ICON_MAX) {
+        return (`--icon "${icon}" is too long: it is shown as text on the button and must be an emoji ` +
+            `(at most ${exports.SPACE_CUSTOM_ACTION_ICON_MAX} UTF-16 units), e.g. --icon ✨. ` +
+            'Icon names such as "Sparkles" are not accepted here.');
+    }
+    return null;
+}
+/**
+ * Why a space's OWN actions cannot run, or null when they can.
+ *
+ * A space custom action runs as a task assigned to the Space Leader, so on a
+ * space with no Leader every one of them is dead on arrival. That fact used to
+ * live only in a tooltip on a disabled web button: `spaces actions add` reported
+ * success, `spaces actions list` listed the action happily, and nothing on the
+ * CLI said it could never run (OSK-9641).
+ */
+function spaceActionsNotRunnableReason(space, bin) {
+    if (space.leadAgentId)
+        return null;
+    return (`This space has no Space Leader, so its own actions cannot run: each runs as a task ` +
+        `assigned to the Leader. Set one with \`${bin} spaces update ${space.id} --lead-agent <agent-id>\`.`);
+}
+/**
+ * Find a space custom action by the id `spaces actions list` prints, or by the
+ * `space-custom:<id>` form the projected quick-action surfaces use.
+ */
+function findSpaceCustomAction(space, ref) {
+    const actions = space.customActions ?? [];
+    const id = (0, data_provider_1.spaceCustomActionSourceId)(ref) ?? ref;
+    const index = actions.findIndex((action) => action.id === id);
+    if (index >= 0)
+        return { customAction: actions[index], index };
+    if (actions.length === 0) {
+        return { problem: `Space ${space.id} has no custom actions.` };
+    }
+    return {
+        problem: `No custom action ${ref} in space ${space.id}. It has: ` +
+            actions.map((action) => `${action.id} (${action.label})`).join(', ') +
+            '.',
+    };
+}
+/**
+ * Everything a space's action panel offers, in the order the web shows it: the
+ * space's own actions first, then the actions of member agents the caller can
+ * view, filtered by scope with the same predicate the web and server use.
+ *
+ * `spaces actions list` showed only the first half and `spaces actions
+ * available` a wider second half (every member agent, including ones the caller
+ * cannot run), so "what can I run here?" had no answer on the CLI (OSK-9641).
+ * Every row's `run` is a command `spaces actions run` accepts.
+ */
+function spaceQuickActionRows(space, members, bin) {
+    const subject = { spaceId: space.id, labelIds: space.labelIds ?? [] };
+    const leaderMissing = !space.leadAgentId;
+    return [
+        ...(space.customActions ?? []).map((action) => ({
+            source: 'space',
+            title: action.label,
+            owner: 'Space Leader',
+            type: 'prompt',
+            ref: action.id,
+            run: leaderMissing
+                ? '(needs a Space Leader)'
+                : `${bin} spaces actions run ${space.id} ${action.id}`,
+        })),
+        ...members.flatMap(({ agent }) => (agent.agentActions ?? [])
+            .filter((action) => (0, data_provider_1.isAgentActionAvailableInSpace)(action, subject))
+            .map((action) => ({
+            source: 'agent',
+            title: action.title,
+            owner: agent.name ?? agent.id,
+            type: (0, data_provider_1.isBuiltinAgentAction)(action) ? `builtin:${action.builtinType}` : 'prompt',
+            ref: `${agent.id}:${action.id}`,
+            run: `${bin} spaces actions run ${space.id} ${agent.id}:${action.id}`,
+        }))),
+    ];
+}

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

@@ -1,23 +1,3 @@
-/**
- * Space reference resolution — turn what a person typed into exactly one
- * space id, or an actionable failure.
- *
- * Every `--space` flag in the CLI (35 commands at last count) took a raw UUID
- * and nothing else. Passing a name did not error — it filtered on a UUID that
- * matches no space and returned an empty result:
- *
- *     skrr tasks list --space "Always on"     →     "No tasks."
- *
- * A person retries. An agent concludes the space is empty and proceeds on a
- * false premise, which is the failure mode this module exists to remove. The
- * contract is deliberately narrow: a value that already looks like an id is
- * forwarded untouched (no request, no behavior change for existing scripts);
- * anything else must resolve to exactly one space or the command fails.
- *
- * Modeled on `assignee-resolver.ts`, which already does this for people and
- * agents — `--assignee-user frank` has worked for a while. Spaces were the
- * outlier, not the exception.
- */
 export type SpaceRef = {
     /** The space UUID — what every `--space` flag ultimately wants. */
     id: string;
@@ -36,7 +16,7 @@ export type SpaceResolutionFailure = {
      *             hides. Distinct from NOT_FOUND because the fix is different:
      *             pass --include-archived (or the id), not a different name.
      */
-    code: 'NOT_FOUND' | 'AMBIGUOUS' | 'ARCHIVED';
+    code: 'NOT_FOUND' | 'AMBIGUOUS' | 'ARCHIVED' | 'NOT_A_REFERENCE';
     query: string;
     candidates: SpaceRef[];
 };

package/dist/lib/space-resolver.js

@@ -1,4 +1,15 @@
 "use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SPACE_CLI_ERROR_CODE = void 0;
+exports.looksLikeSpaceId = looksLikeSpaceId;
+exports.looksLikeCanonicalSpaceId = looksLikeCanonicalSpaceId;
+exports.normalizeSpaceRef = normalizeSpaceRef;
+exports.spaceRefFrom = spaceRefFrom;
+exports.resolveSpaceRef = resolveSpaceRef;
+exports.describeSpace = describeSpace;
+exports.describeSpaceCandidates = describeSpaceCandidates;
+exports.formatSpaceResolutionFailure = formatSpaceResolutionFailure;
+const failed_lookup_1 = require("./failed-lookup");
 /**
  * Space reference resolution — turn what a person typed into exactly one
  * space id, or an actionable failure.
@@ -19,16 +30,6 @@
  * agents — `--assignee-user frank` has worked for a while. Spaces were the
  * outlier, not the exception.
  */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.SPACE_CLI_ERROR_CODE = void 0;
-exports.looksLikeSpaceId = looksLikeSpaceId;
-exports.looksLikeCanonicalSpaceId = looksLikeCanonicalSpaceId;
-exports.normalizeSpaceRef = normalizeSpaceRef;
-exports.spaceRefFrom = spaceRefFrom;
-exports.resolveSpaceRef = resolveSpaceRef;
-exports.describeSpace = describeSpace;
-exports.describeSpaceCandidates = describeSpaceCandidates;
-exports.formatSpaceResolutionFailure = formatSpaceResolutionFailure;
 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}$/;
 const OBJECT_ID_RE = /^[0-9a-fA-F]{24}$/;
 /**
@@ -106,6 +107,11 @@ function resolveSpaceRef(query, spaces) {
     if (!q) {
         return { ok: false, code: 'NOT_FOUND', query: raw, candidates: spaces };
     }
+    // A failed lookup's output is refused before the name tiers can match it.
+    // See `failed-lookup.ts`.
+    if ((0, failed_lookup_1.isFailedLookupValue)(raw)) {
+        return { ok: false, code: 'NOT_A_REFERENCE', query: raw, candidates: [] };
+    }
     // An exact id or ref wins over everything, archived or not: both are
     // explicit and unambiguous, so there is nothing to protect the caller from.
     // Names are matched against live spaces only — see the ARCHIVED branch.
@@ -159,6 +165,8 @@ function describeSpaceCandidates(candidates, limit = 10) {
 /** One human-readable block per failure, suitable for a CLI error body. */
 function formatSpaceResolutionFailure(failure, bin = 'skrr') {
     switch (failure.code) {
+        case 'NOT_A_REFERENCE':
+            return (0, failed_lookup_1.describeFailedLookupValue)(failure.query, 'Space');
         case 'AMBIGUOUS':
             return (`"${failure.query}" matches ${failure.candidates.length} spaces:\n` +
                 `${describeSpaceCandidates(failure.candidates)}\n` +
@@ -178,4 +186,5 @@ exports.SPACE_CLI_ERROR_CODE = {
     AMBIGUOUS: 'SPACE_AMBIGUOUS',
     ARCHIVED: 'SPACE_ARCHIVED',
     NOT_FOUND: 'SPACE_NOT_FOUND',
+    NOT_A_REFERENCE: 'SPACE_NOT_A_REFERENCE',
 };

package/dist/lib/task-closure.d.ts

@@ -28,5 +28,6 @@ export type ClosureLike = TaskClosureEvaluation | {
  * the whole point is to be able to act without a second lookup.
  */
 export declare function closureReport(closure: ClosureLike): string[];
-/** `met (agent)` vs `met (you)` — whose judgement settled it, never hidden. */
-export declare function describeAssessor(kind: string | null | undefined): string;
+/** `met (agent)` vs `met (person)` — shared with the web through data-provider. */
+export { describeAssessorKind as describeAssessor } from '@skrr-ai/data-provider';
+export { describeClosure as closureSnapshotLines, type TaskClosureSnapshot as ClosureSnapshot, } from '@skrr-ai/data-provider';

package/dist/lib/task-closure.js

@@ -1,17 +1,14 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.closureSnapshotLines = exports.describeAssessor = void 0;
 exports.closureReport = closureReport;
-exports.describeAssessor = describeAssessor;
+const data_provider_1 = require("@skrr-ai/data-provider");
 function isUnavailable(closure) {
     return Boolean(closure && closure.unavailable);
 }
-const SHORT_BLOCKER = {
-    TASK_RESULT_REQUIRED: 'no Result submitted',
-    TASK_CURRENT_RESULT_MISSING: 'the current Result does not resolve',
-    TASK_RESULT_SPEC_VERSION_MISMATCH: 'the Result answers an older specification',
-    TASK_RESULT_CHANGES_REQUESTED: 'a reviewer requested changes',
-    TASK_RESULT_REVIEW_REQUIRED: 'an independent accepted Review is required',
-};
+// One phrase table, shared with the web through data-provider. Two copies is how
+// the same blocker came to read differently depending on which surface you asked.
+const SHORT_BLOCKER = data_provider_1.CLOSURE_BLOCKER_PHRASE;
 /**
  * The full account, for the moment a caller has just written something and is
  * deciding what to do next.
@@ -85,18 +82,9 @@ function closureReport(closure) {
         : 'Closing anyway is allowed — all of this is recorded on resolution.closure.');
     return lines;
 }
-/** `met (agent)` vs `met (you)` — whose judgement settled it, never hidden. */
-function describeAssessor(kind) {
-    if (kind === 'agent')
-        return 'agent';
-    if (kind === 'human')
-        return 'person';
-    if (kind === 'system')
-        return 'system';
-    if (kind === 'integration')
-        return 'integration';
-    return 'unattributed';
-}
+/** `met (agent)` vs `met (person)` — shared with the web through data-provider. */
+var data_provider_2 = require("@skrr-ai/data-provider");
+Object.defineProperty(exports, "describeAssessor", { enumerable: true, get: function () { return data_provider_2.describeAssessorKind; } });
 function truncate(value, max) {
     const flat = value.replace(/\s+/g, ' ').trim();
     return flat.length > max ? `${flat.slice(0, max - 1)}…` : flat;
@@ -104,3 +92,13 @@ function truncate(value, max) {
 function capitalize(value) {
     return value.charAt(0).toUpperCase() + value.slice(1);
 }
+/*
+ * The snapshot renderer moved to `@skrr-ai/data-provider`.
+ *
+ * It lived here, and "here" is `cli/` — so the web could not reach it, and the
+ * web is where most people read a finished Task. A single renderer that only one
+ * client can import is not a single renderer; it is the first copy. Re-exported
+ * under the old names so this module stays the CLI's one door to closure copy.
+ */
+var data_provider_3 = require("@skrr-ai/data-provider");
+Object.defineProperty(exports, "closureSnapshotLines", { enumerable: true, get: function () { return data_provider_3.describeClosure; } });

package/dist/lib/task-lifecycle-output.js

@@ -14,15 +14,25 @@ function renderTaskLifecycleSummary(response, log) {
         log('Attach one: skrr tasks lifecycle attach <task-id> --pack finding');
         return;
     }
-    log(`Lifecycle: ${lifecycle.status} (v${lifecycle.version}, generation ${lifecycle.generation}, revision ${lifecycle.revision})` +
-        (lifecycle.packId ? ` — pack ${lifecycle.packId}` : ''));
+    // Two different version numbers used to share one label. `v1` next to
+    // `pack finding` reads as "finding v1", and `finding` is pack v2 — `version`
+    // is the installed definition's WorkflowVersion. Name each one.
+    const protocol = lifecycle.packId
+        ? `pack ${lifecycle.packId}${lifecycle.packVersion ? ` v${lifecycle.packVersion}` : ''}`
+        : `definition ${lifecycle.definitionId}`;
+    log(`Lifecycle: ${lifecycle.status} — ${protocol}, protocol version ${lifecycle.version}, generation ${lifecycle.generation}, revision ${lifecycle.revision}`);
     if (response.run)
         log(`Run: ${response.run.id} — ${response.run.status}`);
     for (const stage of response.stages || []) {
         const marker = stage.key === lifecycle.currentStageKey ? '>' : ' ';
-        const state = stage.status
-            ? ` — ${stage.status}${stage.outcome ? `/${stage.outcome}` : ''}`
-            : '';
+        // A reopen marks everything behind its entry stage `skipped` in the NEW
+        // run. Saying so unqualified told the reader that work nobody skipped had
+        // never happened; say which generation did it instead.
+        const state = stage.completedInGeneration
+            ? ` — done in generation ${stage.completedInGeneration}${stage.priorOutcome ? `/${stage.priorOutcome}` : ''}`
+            : stage.status
+                ? ` — ${stage.status}${stage.outcome ? `/${stage.outcome}` : ''}`
+                : '';
         log(`${marker} ${stage.label || stage.key}${state}`);
     }
     if (response.gate) {
@@ -43,28 +53,122 @@ function renderTaskLifecycleSummary(response, log) {
                     : undefined,
                 transition.requires?.deliverableRef ? 'deliverable ref' : undefined,
             ].filter(Boolean);
-            log(`  ${transition.id} -> ${transition.outcome}${transition.label ? ` (${transition.label})` : ''}${needs.length ? ` — needs ${needs.join(', ')}` : ''}`);
+            // Lead with what it DOES and say where it goes. This printed
+            // `id -> outcome`, and `outcome` is an edge name: at triage that read
+            // `accept -> accept`, with nothing to separate the branch that continues
+            // to Diagnose from the one that ends the finding.
+            const destination = transition.endsLifecycle
+                ? 'ends the lifecycle'
+                : transition.toStageLabel || transition.toStageKey;
+            log(`  ${transition.id}${transition.label ? ` — ${transition.label}` : ''}${destination ? ` -> ${destination}` : ''}${needs.length ? ` — needs ${needs.join(', ')}` : ''}`);
+            // A copyable skeleton. Naming the update TYPE and a count of evidence
+            // told nobody which keys to put where, so every payload shape was
+            // guesswork against a contract only the server could see.
+            const skeleton = transitionPayloadSkeleton(transition);
+            if (skeleton)
+                log(`      --payload '${skeleton}'`);
         }
     }
     if (response.pendingEffects?.length) {
         log('');
+        const exhausted = response.pendingEffects.filter((effect) => effect.status === 'failed');
         log(`${response.pendingEffects.length} effect(s) pending repair:`);
         for (const effect of response.pendingEffects) {
-            log(`  ${effect.kind}${effect.lastError ? ` — ${effect.lastError}` : ''}`);
+            // Say whether it is still trying. A row that has given up and a row
+            // mid-retry need different things from the reader.
+            const state = effect.status === 'failed' ? ' [stopped retrying]' : '';
+            log(`  ${effect.kind}${state}${effect.attempts ? ` after ${effect.attempts} attempt(s)` : ''}${effect.lastError ? ` — ${effect.lastError}` : ''}`);
+        }
+        // Any row carrying an error is already actionable — waiting for it to
+        // exhaust its retries before naming the repair leaves the reader staring at
+        // a stage that cannot move and a transition list that offers nothing.
+        if (response.pendingEffects.some((effect) => effect.lastError)) {
+            log(exhausted.length
+                ? 'Fix what the error names, then re-arm them: skrr tasks lifecycle reconcile <task-id>'
+                : 'Still retrying. Fix what the error names, then: skrr tasks lifecycle reconcile <task-id>');
         }
     }
     if (lifecycle.statusDrift) {
         log(`Status drift: stage expects ${lifecycle.statusDrift.expected}, Task shows ${lifecycle.statusDrift.actual}.`);
     }
 }
+/**
+ * A copyable `--payload` skeleton for one transition, built from what the
+ * server says the transition requires.
+ *
+ * Deliberately built from the RESPONSE rather than from a table in the CLI: the
+ * field list per update type is the server's to own, and a second copy here
+ * would drift the moment a pack changed.
+ */
+function transitionPayloadSkeleton(transition) {
+    const requires = transition.requires;
+    if (!requires)
+        return undefined;
+    const payload = {};
+    for (const field of requires.fields || [])
+        payload[field] = `<${field}>`;
+    if (requires.deliverableRef)
+        payload.resourceLinkId = '<resource-link-id>';
+    if (requires.updateType) {
+        const data = {};
+        for (const field of requires.updateFields || []) {
+            data[field] = placeholderFor(field, requires.updateFieldShapes?.[field]);
+        }
+        if (requires.evidence) {
+            data.evidenceRefs = [{ kind: 'task', id: '<task-id>' }];
+        }
+        payload.update = { summary: '<one line about the work>', data };
+    }
+    return Object.keys(payload).length ? JSON.stringify(payload) : undefined;
+}
+/**
+ * A placeholder that has the field's SHAPE, taken from what the server declared.
+ * A list field shown as a string led people to write one comma-joined item
+ * where they meant several.
+ */
+function placeholderFor(field, shape) {
+    if (!shape)
+        return `<${field}>`;
+    if (shape === 'string[]')
+        return [`<${field} item>`];
+    if (shape === 'reference[]')
+        return [];
+    if (shape === 'principal')
+        return { kind: 'human', userId: '<user-id>' };
+    // An enum: show the legal values rather than a name to guess at.
+    if (shape.includes('|'))
+        return `<${shape}>`;
+    return `<${field}>`;
+}
 /** Render the outcome of a lifecycle transition call. */
 function renderLifecycleTransitionResult(response, log) {
-    log(`Transition ${response.status}${response.code ? ` (${response.code})` : ''}.`);
+    // A replay is not an apply. Retrying is the NORMAL path here — the default
+    // idempotency key is derived, so a re-run of the same command replays — and
+    // this printed "Transition applied / effect record_update: applied" either
+    // way, so the one question a retry asks (did I just do that, or had I
+    // already?) had no answer in the output.
+    const replayed = response.idempotent === true;
+    // A transition can be `applied` while one of its declared effects did not
+    // run. The headline said "Transition applied." and the reader had to notice a
+    // per-effect `pending` several lines down, so a capture whose source was
+    // never recorded read as a success.
+    const owed = (response.effects || []).filter((effect) => effect.status !== 'applied');
+    log(`Transition ${response.status}${replayed ? ' (replayed — the recorded outcome, no new work)' : ''}${response.code ? ` (${response.code})` : ''}${owed.length ? ` — ${owed.length} of ${response.effects?.length} effect(s) did NOT run` : ''}.`);
     if (response.message)
         log(response.message);
     for (const effect of response.effects || []) {
         log(`  effect ${effect.kind}: ${effect.status}${effect.ref ? ` -> ${effect.ref}` : ''}${effect.error ? ` — ${effect.error}` : ''}`);
     }
+    // The server names the legal transitions when it refuses an unknown id, and
+    // the human renderer dropped them — so a sequencing mistake ("not from this
+    // stage") and a typo read identically.
+    const allowed = response.details?.allowed;
+    if (Array.isArray(allowed) && allowed.length) {
+        log(`Legal from this stage: ${allowed.join(', ')}`);
+    }
+    const actualRevision = response.details?.actualRevision;
+    if (actualRevision !== undefined)
+        log(`Current revision is ${String(actualRevision)}.`);
     if (response.gate)
         log(`Gate: ${response.gate.message}`);
     if (response.lifecycle) {
@@ -85,7 +189,11 @@ function renderLifecycleHistory(response, log) {
         const parts = [
             event.at,
             event.type,
-            event.generation !== undefined ? `gen ${event.generation}` : undefined,
+            // Name the protocol beside the generation. A Task that wore two packs
+            // across a detach and re-attach rendered both passes identically.
+            event.generation !== undefined
+                ? `gen ${event.generation}${event.packId ? ` (${event.packId})` : ''}`
+                : undefined,
             event.transitionId,
             event.status,
             event.outcome,

package/dist/lib/task-ref-resolver.d.ts

@@ -1,19 +1,3 @@
-/**
- * Task reference resolution — turn what a person typed into exactly one task
- * id, or an actionable failure.
- *
- * Distinct from `task-resolver.ts`, which is about WHICH INPUT WINS among the
- * positional arg, `--task`, `--from-json` and the daemon runtime context. That
- * module does no lookup at all: it picks a string and hands it to the API. This
- * one runs after it and answers a different question — what does that string
- * refer to?
- *
- * Two shapes already work without a lookup. A UUID is the canonical id, and an
- * `OSK-2423` ref resolves server-side (`getTask` special-cases the pattern in
- * api/models/Task.js). A title did not work, which is the gap here: the ref is
- * printed in every listing but a person reading a task board out loud has the
- * title, not the number.
- */
 export type TaskRef = {
     id: string;
     /** The human-readable ref, e.g. `OSK-2423`. */
@@ -23,7 +7,7 @@ export type TaskRef = {
 };
 export type TaskResolutionRefFailure = {
     ok: false;
-    code: 'NOT_FOUND' | 'AMBIGUOUS';
+    code: 'NOT_FOUND' | 'AMBIGUOUS' | 'NOT_A_REFERENCE';
     query: string;
     candidates: TaskRef[];
 };

package/dist/lib/task-ref-resolver.js

@@ -1,4 +1,13 @@
 "use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TASK_REF_CLI_ERROR_CODE = void 0;
+exports.directTaskRef = directTaskRef;
+exports.taskRefFrom = taskRefFrom;
+exports.resolveTaskRef = resolveTaskRef;
+exports.describeTask = describeTask;
+exports.describeTaskCandidates = describeTaskCandidates;
+exports.formatTaskRefFailure = formatTaskRefFailure;
+const failed_lookup_1 = require("./failed-lookup");
 /**
  * Task reference resolution — turn what a person typed into exactly one task
  * id, or an actionable failure.
@@ -15,14 +24,6 @@
  * printed in every listing but a person reading a task board out loud has the
  * title, not the number.
  */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.TASK_REF_CLI_ERROR_CODE = void 0;
-exports.directTaskRef = directTaskRef;
-exports.taskRefFrom = taskRefFrom;
-exports.resolveTaskRef = resolveTaskRef;
-exports.describeTask = describeTask;
-exports.describeTaskCandidates = describeTaskCandidates;
-exports.formatTaskRefFailure = formatTaskRefFailure;
 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}$/;
 /** The server's identifier pattern, relaxed to accept a lowercase prefix. */
 const IDENTIFIER_RE = /^[A-Za-z]+-\d+$/;
@@ -78,6 +79,11 @@ function resolveTaskRef(query, tasks) {
     if (!q) {
         return { ok: false, code: 'NOT_FOUND', query: raw, candidates: tasks };
     }
+    // A failed lookup's output is refused before the title tiers can match it.
+    // See `failed-lookup.ts`.
+    if ((0, failed_lookup_1.isFailedLookupValue)(raw)) {
+        return { ok: false, code: 'NOT_A_REFERENCE', query: raw, candidates: [] };
+    }
     const tiers = [
         // 1. Exact id.
         (t) => t.id === raw,
@@ -118,6 +124,9 @@ function describeTaskCandidates(candidates, limit = 10) {
     return shown.join('\n');
 }
 function formatTaskRefFailure(failure, bin = 'skrr') {
+    if (failure.code === 'NOT_A_REFERENCE') {
+        return (0, failed_lookup_1.describeFailedLookupValue)(failure.query, 'task');
+    }
     if (failure.code === 'AMBIGUOUS') {
         return (`"${failure.query}" matches ${failure.candidates.length} tasks by title:\n` +
             `${describeTaskCandidates(failure.candidates)}\n` +
@@ -130,4 +139,5 @@ function formatTaskRefFailure(failure, bin = 'skrr') {
 exports.TASK_REF_CLI_ERROR_CODE = {
     AMBIGUOUS: 'TASK_REF_AMBIGUOUS',
     NOT_FOUND: 'TASK_REF_NOT_FOUND',
+    NOT_A_REFERENCE: 'TASK_REF_NOT_A_REFERENCE',
 };