@skrr-ai/cli 0.1.36 → 0.1.38

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

@@ -0,0 +1,33 @@
+import type { TaskClosureEvaluation } from '@skrr-ai/data-provider';
+/**
+ * Render "where does this Task actually stand" for every surface that should
+ * say it.
+ *
+ * ONE renderer, because the failure this exists to fix was several surfaces each
+ * asserting a closure state none of them had checked: `tasks result submit`
+ * printed a hard-coded "it is ready for review", the server wrote a
+ * `ready_for_review` Update to match, and the managed instructions told the
+ * agent to read a status the response did not carry. Three confident voices,
+ * one unchecked claim.
+ *
+ * So the rule here is narrow and absolute: this function says only what the
+ * evaluation says. If the evaluation is absent or could not run, it says THAT —
+ * it never falls back to an optimistic sentence, because the optimistic sentence
+ * is the bug.
+ */
+export type ClosureLike = TaskClosureEvaluation | {
+    unavailable: true;
+    reason?: string;
+} | undefined;
+/**
+ * The full account, for the moment a caller has just written something and is
+ * deciding what to do next.
+ *
+ * Every unmet Expectation is NAMED. The ids alone (`e1`, `e2`) are what the
+ * gate's own details carried for a while, and they are unusable on their own —
+ * the whole point is to be able to act without a second lookup.
+ */
+export declare function closureReport(closure: ClosureLike): 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

@@ -0,0 +1,104 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.closureSnapshotLines = exports.describeAssessor = void 0;
+exports.closureReport = closureReport;
+const data_provider_1 = require("@skrr-ai/data-provider");
+function isUnavailable(closure) {
+    return Boolean(closure && closure.unavailable);
+}
+// 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.
+ *
+ * Every unmet Expectation is NAMED. The ids alone (`e1`, `e2`) are what the
+ * gate's own details carried for a while, and they are unusable on their own —
+ * the whole point is to be able to act without a second lookup.
+ */
+function closureReport(closure) {
+    if (!closure)
+        return ['Closure state: not reported by this call.'];
+    if (isUnavailable(closure)) {
+        return [
+            'Closure state could not be evaluated. That is a statement about this read,',
+            'not about the work — run `skrr tasks expectations <task-id>` to ask directly.',
+        ];
+    }
+    const lines = [];
+    const exp = closure.expectations;
+    /*
+     * The degraded note comes FIRST, and before the closable shortcut.
+     *
+     * An unreadable assessment ledger makes the gate fail OPEN — deliberately, so
+     * a Mongo blip cannot create a Task nothing can close — which means `closable`
+     * can be true precisely because a check did not run. Reporting only "nothing
+     * is outstanding" there would launder an infrastructure failure into a clean
+     * bill of health, which is the same class of silence this whole file exists to
+     * remove.
+     */
+    if (exp?.degraded === 'assessments_unreadable' || closure.degraded === 'assessments_unreadable') {
+        lines.push('Expectation assessments could not be read; that check was skipped, not passed.');
+    }
+    if (closure.closable) {
+        lines.push('Nothing is outstanding — this Task can close.');
+        return lines;
+    }
+    if (exp && exp.total > 0) {
+        /*
+         * "Settled," not "met" — a waived Expectation was judged no longer owed,
+         * which is a different fact from done. The count names waivers when any
+         * exist so a scope change never reads as completed work.
+         */
+        const settled = exp.settledCount ?? exp.settled?.length ?? exp.met;
+        const waivedNote = exp.waived ? ` (${exp.waived} waived)` : '';
+        lines.push(`Expectations: ${settled} of ${exp.total} settled${waivedNote}.`);
+        for (const row of exp.unmet) {
+            lines.push(`  ${row.id}  ${truncate(row.sentence || row.text || '(no text)', 76)}`);
+        }
+    }
+    for (const blocker of closure.blockers) {
+        if (blocker.code === 'TASK_EXPECTATIONS_NOT_MET')
+            continue;
+        lines.push(SHORT_BLOCKER[blocker.code] ? capitalize(SHORT_BLOCKER[blocker.code]) + '.' : blocker.message);
+    }
+    if (exp && exp.unmet.length > 0) {
+        lines.push('');
+        lines.push('Settle each with `skrr tasks expectations assess <task-id> <expectation-id>');
+        lines.push('  --decision met|waived --reason "..."`, or review the whole space with');
+        lines.push('  `skrr tasks review-queue --space <space-id>`.');
+    }
+    /*
+     * Everything else is advisory — stamped onto `resolution.closure` if the
+     * Task closes over it. The one refusal left is an owner-declared required
+     * Review, and only for someone who is not the owner; when that blocker is
+     * present, say the narrower truth.
+     */
+    const reviewRequired = closure.blockers.some((b) => b.code === 'TASK_RESULT_REVIEW_REQUIRED');
+    lines.push('');
+    lines.push(reviewRequired
+        ? 'Only an accepted independent Review — or the Task owner closing directly — settles this. The rest is recorded on resolution.closure.'
+        : 'Closing anyway is allowed — all of this is recorded on resolution.closure.');
+    return lines;
+}
+/** `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;
+}
+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.d.ts

@@ -0,0 +1,14 @@
+import type { TaskLifecycleHistoryResponse, TaskLifecycleResponse, TaskLifecycleTransitionResponse } from '@skrr-ai/data-provider';
+/**
+ * Render the Task Lifecycle response — the projection, its stages in protocol
+ * order, and the transitions the waiting stage currently declares.
+ */
+export declare function renderTaskLifecycleSummary(response: TaskLifecycleResponse, log: (line: string) => void): void;
+/** Render the outcome of a lifecycle transition call. */
+export declare function renderLifecycleTransitionResult(response: TaskLifecycleTransitionResponse, log: (line: string) => void): void;
+/**
+ * Render the durable lifecycle event stream — every generation's transitions,
+ * gates and run events, newest first. `lifecycle show` answers where the Task
+ * IS; this answers how it got there.
+ */
+export declare function renderLifecycleHistory(response: TaskLifecycleHistoryResponse, log: (line: string) => void): void;

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

@@ -0,0 +1,209 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.renderTaskLifecycleSummary = renderTaskLifecycleSummary;
+exports.renderLifecycleTransitionResult = renderLifecycleTransitionResult;
+exports.renderLifecycleHistory = renderLifecycleHistory;
+/**
+ * Render the Task Lifecycle response — the projection, its stages in protocol
+ * order, and the transitions the waiting stage currently declares.
+ */
+function renderTaskLifecycleSummary(response, log) {
+    const lifecycle = response.lifecycle;
+    if (!lifecycle) {
+        log('No lifecycle is attached to this Task.');
+        log('Attach one: skrr tasks lifecycle attach <task-id> --pack finding');
+        return;
+    }
+    // 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 ? '>' : ' ';
+        // 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) {
+        log('');
+        log(`Closure gate: ${response.gate.message}`);
+    }
+    const transitions = response.allowedTransitions || [];
+    const waiting = response.stage?.waitingFor;
+    if (response.stage && transitions.length) {
+        log('');
+        log(`Stage "${response.stage.nodeKey}" is waiting${waiting?.nextActor ? ` on ${waiting.nextActor}` : ''}. Legal transitions:`);
+        for (const transition of transitions) {
+            const needs = [
+                ...(transition.requires?.fields || []).map((f) => `payload.${f}`),
+                transition.requires?.updateType ? `${transition.requires.updateType} update` : undefined,
+                transition.requires?.evidence
+                    ? `${transition.requires.evidence} evidence ref(s)`
+                    : undefined,
+                transition.requires?.deliverableRef ? 'deliverable ref' : undefined,
+            ].filter(Boolean);
+            // 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) {
+            // 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) {
+    // 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) {
+        log(`Lifecycle: ${response.lifecycle.status}, stage ${response.lifecycle.currentStageKey ?? '—'}, revision ${response.lifecycle.revision}.`);
+    }
+}
+/**
+ * Render the durable lifecycle event stream — every generation's transitions,
+ * gates and run events, newest first. `lifecycle show` answers where the Task
+ * IS; this answers how it got there.
+ */
+function renderLifecycleHistory(response, log) {
+    if (!response.events.length) {
+        log('No lifecycle events recorded for this Task.');
+        return;
+    }
+    for (const event of response.events) {
+        const parts = [
+            event.at,
+            event.type,
+            // 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,
+            event.code,
+        ].filter(Boolean);
+        log(parts.join('  '));
+        if (event.message)
+            log(`    ${event.message}`);
+    }
+    if (response.truncated) {
+        log(`— truncated at the event limit; re-query with a higher --limit or --before.`);
+    }
+}

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

package/dist/lib/tasks.d.ts

@@ -66,6 +66,9 @@ export type TaskCreateFlagValues = {
     tag?: string[];
     'label-id'?: string[];
     worktree?: boolean;
+    'lifecycle-definition'?: string;
+    'lifecycle-version'?: string;
+    'lifecycle-pack'?: string;
 };
 /**
  * Map the tri-state `--worktree` flag to the `executionIsolation` value.