@zq-silk/yui 2.3.0 → 2.5.0

package/dist/commands/projectCommands.js

@@ -3,6 +3,7 @@ import { readdir, rename, rm } from "node:fs/promises";
 import { dirname, isAbsolute, join, relative, resolve } from "node:path";
 import { CliError, usageError } from "../errors/cliError.js";
 import { defaultTableWidth, renderTable } from "../output/table.js";
+import { boundedDocument, readOptions, recordPage } from "../output/boundedRead.js";
 import { healCheckoutSwap, restoreCheckoutSwap, swapManagedCheckout } from "../repository/checkoutSwap.js";
 import { GitWorkspaceRefreshError, NodeGitWorkspace } from "../repository/gitWorkspace.js";
 import { acquireProjectMaintenanceLock } from "../repository/projectMaintenanceLock.js";
@@ -74,17 +75,11 @@ export async function runProjectCommand(args, store, options = {}) {
     }
     if (command === "knowledge") {
         const result = projectKnowledge(rest, store, options);
-        const project = resolveProject(store.listProjects(), result.projectId);
-        if (project === null)
-            return { output: result.output };
-        if (result.knowledgeId !== undefined) {
-            const knowledge = project.knowledge.find(({ id }) => id === result.knowledgeId);
-            return { output: result.output, data: { project, knowledge } };
-        }
-        const knowledge = result.all
-            ? project.knowledge
-            : project.knowledge.filter(({ status }) => status === "active");
-        return { output: result.output, data: { project, knowledge } };
+        return { output: result.output, data: result.data ?? {
+                projectId: result.projectId,
+                ...(result.knowledgeId === undefined ? {} : { knowledgeId: result.knowledgeId }),
+                ...(result.proposalId === undefined ? {} : { proposalId: result.proposalId })
+            } };
     }
     throw usageError(command === undefined
         ? "Project command is required."
@@ -1198,19 +1193,22 @@ function projectKnowledge(args, store, options) {
     }
     if (command === "list") {
         const all = rest.includes("--all");
-        const positionals = rest.filter((value) => value !== "--all");
-        if (positionals.length !== 1 || rest.some((value) => value.startsWith("--") && value !== "--all")) {
-            throw usageError("Project knowledge list usage: yui project knowledge list <project> [--all].");
-        }
-        const project = requireProject(store, positionals[0]);
-        const entries = all
-            ? project.knowledge
-            : project.knowledge.filter(({ status }) => status === "active");
+        const parsed = readOptions(rest.filter((value) => value !== "--all"));
+        if (parsed.positionals.length !== 1) {
+            throw usageError("Project knowledge list usage: yui project knowledge list <project> [--all] [--limit <1..100>] [--cursor <cursor>].");
+        }
+        const project = requireProject(store, parsed.positionals[0]);
+        const page = recordPage(project.knowledge.filter(({ status }) => all || status === "active").map(entry => ({
+            id: entry.id, title: entry.title.slice(0, 200), version: entry.version, status: entry.status,
+            scope: entry.scope?.slice(0, 200), expiresWhen: entry.expiresWhen?.slice(0, 200),
+            updatedAt: entry.updatedAt
+        })), `project:${project.id}/knowledge/${all ? "all" : "active"}`, parsed);
+        const entries = page.items;
         if (entries.length === 0) {
             return {
                 output: "No project knowledge found.\n",
                 projectId: project.id,
-                all
+                data: { projectId: project.id, ...page }
             };
         }
         return {
@@ -1218,25 +1216,32 @@ function projectKnowledge(args, store, options) {
                 { header: "Knowledge", minWidth: 9, maxWidth: 24 },
                 { header: "Title", minWidth: 8, maxWidth: 64 },
                 { header: "Status", minWidth: 6, maxWidth: 10 }
-            ], entries.map((entry) => [entry.id, entry.title, entry.status]), defaultTableWidth())}\n`,
+            ], entries.map((entry) => [entry.id, entry.title, entry.status]), defaultTableWidth())}\n${page.nextCursor === null ? "" : `Next cursor: ${page.nextCursor}\n`}`,
             projectId: project.id,
-            all
+            data: { projectId: project.id, ...page }
         };
     }
     if (command === "show") {
-        if (rest.length !== 2) {
-            throw usageError("Project knowledge show usage: yui project knowledge show <project> <knowledge>.");
+        const parsed = readOptions(rest, ["--cursor"]);
+        if (parsed.positionals.length !== 2) {
+            throw usageError("Project knowledge show usage: yui project knowledge show <project> <knowledge> [--cursor <cursor>].");
         }
-        const project = requireProject(store, rest[0]);
-        const entry = project.knowledge.find(({ id }) => id === rest[1]);
+        const project = requireProject(store, parsed.positionals[0]);
+        const entry = project.knowledge.find(({ id }) => id === parsed.positionals[1]);
         if (entry === undefined)
-            throw usageError(`Project knowledge not found: ${rest[1]}.`);
+            throw usageError(`Project knowledge not found: ${parsed.positionals[1]}.`);
+        const data = boundedDocument({ projectId: project.id, knowledge: entry }, `project:${project.id}/knowledge/${entry.id}`, parsed.cursor);
+        if ("contentPage" in data)
+            return { output: `${JSON.stringify(data)}\n`, projectId: project.id, data };
         return {
             output: [
                 `Knowledge: ${entry.id}`,
                 `Project: ${project.id}`,
                 `Title: ${entry.title}`,
                 `Status: ${entry.status}`,
+                `Version: ${entry.version}`,
+                ...(entry.scope === undefined ? [] : [`Scope: ${entry.scope}`]),
+                ...(entry.expiresWhen === undefined ? [] : [`Expires when: ${entry.expiresWhen}`]),
                 ...(entry.provenance === undefined ? [] : [
                     `Source: ${entry.provenance.taskId}`
                         + `${entry.provenance.decisionId === undefined ? "" : `/${entry.provenance.decisionId}`}`
@@ -1253,10 +1258,14 @@ function projectKnowledge(args, store, options) {
                         : [`Promoted by: ${entry.provenance.promotedBy} at ${entry.provenance.promotedAt ?? "?"}`])
                 ]),
                 "",
-                entry.body
+                entry.body,
+                ...(entry.history.length === 0 ? [] : [
+                    "", "Prior versions (exact records):", JSON.stringify(entry.history, null, 2)
+                ])
             ].join("\n").concat("\n"),
             projectId: project.id,
-            knowledgeId: entry.id
+            knowledgeId: entry.id,
+            data
         };
     }
     if (command === "update") {
@@ -1401,7 +1410,7 @@ function parseKnowledgeProposalOptions(args, usage) {
  * Leader-proposed promotion candidate. The proposal is workflow state, not
  * Knowledge: it never appears in `project knowledge list/show` until an
  * Operator accepts it. A managed Task Session may propose only for its own
- * Task. The same candidate (source identity + title + body) is deduplicated to
+ * Task. The same candidate (source, content, applicability and replacement intent) is deduplicated to
  * the existing pending proposal instead of creating a second copy.
  */
 function proposeKnowledge(args, store, options) {
@@ -1430,7 +1439,10 @@ function proposeKnowledge(args, store, options) {
             projectId: project.id,
             source,
             title: parsed.title,
-            body: parsed.body
+            body: parsed.body,
+            ...(parsed.scope === undefined ? {} : { scope: parsed.scope }),
+            ...(parsed.expiresWhen === undefined ? {} : { expiresWhen: parsed.expiresWhen }),
+            ...(parsed.supersedes === undefined ? {} : { supersedesKnowledgeId: parsed.supersedes })
         });
         const pending = findKnowledgeProposalByFingerprint(project, fingerprint, "pending");
         if (pending !== null) {
@@ -1452,7 +1464,7 @@ function proposeKnowledge(args, store, options) {
             };
         }
         const proposal = {
-            schemaVersion: 1,
+            schemaVersion: 2,
             id: nextProposalId(project),
             projectId: project.id,
             title: parsed.title,
@@ -1528,50 +1540,29 @@ function requireProposalEvidence(store, parsed) {
 }
 function listKnowledgeProposals(args, store) {
     const usage = "Project knowledge proposals list usage: yui project knowledge proposals list <project>"
-        + " [--status pending|accepted|rejected] [--all].";
-    const positionals = [];
-    let status = "pending";
-    let sawAll = false;
-    let sawStatus = false;
-    for (let index = 0; index < args.length; index += 1) {
-        const value = args[index];
-        if (value === "--all") {
-            if (sawStatus)
-                throw usageError(`--all and --status are mutually exclusive. ${usage}`);
-            sawAll = true;
-            status = undefined;
-        }
-        else if (value === "--status") {
-            if (sawAll)
-                throw usageError(`--all and --status are mutually exclusive. ${usage}`);
-            sawStatus = true;
-            const next = args[index + 1];
-            if (next === undefined || next.startsWith("--"))
-                throw usageError(usage);
-            if (next !== "pending" && next !== "accepted" && next !== "rejected")
-                throw usageError(usage);
-            status = next;
-            index += 1;
-        }
-        else if (value.startsWith("--")) {
-            throw usageError(`Unknown option: ${value}. ${usage}`);
-        }
-        else {
-            positionals.push(value);
-        }
-    }
-    if (positionals.length !== 1)
+        + " [--status pending|accepted|rejected] [--all] [--limit <1..100>] [--cursor <cursor>].";
+    const parsed = readOptions(args.filter(value => value !== "--all"), ["--cursor", "--limit", "--status"]);
+    const all = args.includes("--all");
+    if (all && parsed.values.has("--status"))
+        throw usageError(`--all and --status are mutually exclusive. ${usage}`);
+    const status = all ? undefined : parsed.values.get("--status") ?? "pending";
+    if (parsed.positionals.length !== 1
+        || (status !== undefined && !["pending", "accepted", "rejected"].includes(status)))
         throw usageError(usage);
-    const project = requireProject(store, positionals[0]);
-    const entries = project.knowledgeProposals
+    const project = requireProject(store, parsed.positionals[0]);
+    const page = recordPage(project.knowledgeProposals
         .filter((entry) => status === undefined || entry.status === status)
         .slice()
-        .sort((a, b) => a.id.localeCompare(b.id));
+        .sort((a, b) => a.id.localeCompare(b.id))
+        .map(entry => ({ id: entry.id, title: entry.title.slice(0, 200), status: entry.status,
+        source: entry.source, knowledgeId: entry.knowledgeId,
+        scope: entry.scope?.slice(0, 200), expiresWhen: entry.expiresWhen?.slice(0, 200) })), `project:${project.id}/knowledge-proposals/${status ?? "all"}`, parsed);
+    const entries = page.items;
     if (entries.length === 0) {
         return {
             output: "No knowledge proposals found.\n",
             projectId: project.id,
-            proposals: []
+            data: { projectId: project.id, ...page }
         };
     }
     return {
@@ -1589,20 +1580,24 @@ function listKnowledgeProposals(args, store) {
                 + `${entry.source.decisionId === undefined ? "" : `/${entry.source.decisionId}`}`
                 + `${entry.source.milestoneId === undefined ? "" : `/${entry.source.milestoneId}`}`,
             entry.knowledgeId ?? "-"
-        ]), defaultTableWidth())}\n`,
+        ]), defaultTableWidth())}\n${page.nextCursor === null ? "" : `Next cursor: ${page.nextCursor}\n`}`,
         projectId: project.id,
-        proposals: entries
+        data: { projectId: project.id, ...page }
     };
 }
 function showKnowledgeProposal(args, store) {
-    const usage = "Project knowledge proposals show usage: yui project knowledge proposals show <project> <proposal>.";
-    if (args.length !== 2)
+    const usage = "Project knowledge proposals show usage: yui project knowledge proposals show <project> <proposal> [--cursor <cursor>].";
+    const parsed = readOptions(args, ["--cursor"]);
+    if (parsed.positionals.length !== 2)
         throw usageError(usage);
-    const project = requireProject(store, args[0]);
-    const proposal = findKnowledgeProposal(project, args[1]);
+    const project = requireProject(store, parsed.positionals[0]);
+    const proposal = findKnowledgeProposal(project, parsed.positionals[1]);
     if (proposal === null) {
-        throw usageError(`Knowledge proposal not found: ${args[1]}.`);
+        throw usageError(`Knowledge proposal not found: ${parsed.positionals[1]}.`);
     }
+    const data = boundedDocument({ projectId: project.id, proposal }, `project:${project.id}/knowledge-proposals/${proposal.id}`, parsed.cursor);
+    if ("contentPage" in data)
+        return { output: `${JSON.stringify(data)}\n`, projectId: project.id, data };
     const lines = [
         `Proposal: ${proposal.id}`,
         `Project: ${project.id}`,
@@ -1629,7 +1624,7 @@ function showKnowledgeProposal(args, store) {
         output: `${lines.join("\n")}\n`,
         projectId: project.id,
         proposalId: proposal.id,
-        proposals: [proposal]
+        data
     };
 }
 /**
@@ -1654,6 +1649,10 @@ function acceptKnowledgeProposal(args, store, options) {
         if (proposal === null) {
             throw usageError(`Knowledge proposal not found: ${parsed.proposal}.`);
         }
+        if (proposal.status === "accepted"
+            && (parsed.update === undefined || parsed.update === proposal.knowledgeId)) {
+            return { projectId: project.id, proposalId: proposal.id, knowledgeId: proposal.knowledgeId, duplicate: true };
+        }
         if (proposal.status !== "pending") {
             throw usageError(`Knowledge proposal is already ${proposal.status}: ${proposal.id}.`);
         }
@@ -1675,20 +1674,24 @@ function acceptKnowledgeProposal(args, store, options) {
                 || previousProposal.status !== "accepted"
                 || previousProposal.knowledgeId !== target.id
                 || previousProposal.title !== target.title
-                || previousProposal.body !== target.body) {
+                || previousProposal.body !== target.body
+                || previousProposal.scope !== target.scope
+                || previousProposal.expiresWhen !== target.expiresWhen) {
                 throw usageError(`Knowledge ${target.id} has no complete proposal-backed version history. `
                     + "Create the replacement proposal with --supersedes instead of --update.");
             }
             knowledgeId = target.id;
             next = updateProjectKnowledge(next, knowledgeId, {
                 title: proposal.title,
-                body: proposal.body
-            }, now);
-            next = withKnowledgeProvenance(next, knowledgeId, {
-                ...provenanceFromProposal(proposal),
-                proposalId: proposal.id,
-                promotedBy: decidedBy,
-                promotedAt: now.toISOString()
+                body: proposal.body,
+                scope: proposal.scope ?? null,
+                expiresWhen: proposal.expiresWhen ?? null,
+                provenance: {
+                    ...provenanceFromProposal(proposal),
+                    proposalId: proposal.id,
+                    promotedBy: decidedBy,
+                    promotedAt: now.toISOString()
+                }
             }, now);
         }
         else {
@@ -1707,7 +1710,7 @@ function acceptKnowledgeProposal(args, store, options) {
                     proposalId: proposal.id,
                     promotedBy: decidedBy,
                     promotedAt: now.toISOString()
-                });
+                }, proposal);
             }
         }
         next = decideKnowledgeProposal(next, proposal.id, {
@@ -1768,14 +1771,6 @@ function provenanceFromProposal(proposal) {
         fingerprint: proposal.fingerprint
     };
 }
-/** Replace a Knowledge entry's provenance (used by accept --update). */
-function withKnowledgeProvenance(project, knowledgeId, provenance, now) {
-    const timestamp = now.toISOString();
-    const knowledge = project.knowledge.map((entry) => (entry.id === knowledgeId
-        ? { ...entry, provenance, updatedAt: timestamp }
-        : entry));
-    return validateProject({ ...project, knowledge, updatedAt: timestamp });
-}
 function parseAcceptArguments(args, usage) {
     const positionals = [];
     let update;

package/dist/commands/roleSkillValidation.js

@@ -1,6 +1,5 @@
-import { accessSync, constants, statSync } from "node:fs";
-import { resolve } from "node:path";
 import { usageError } from "../errors/cliError.js";
+import { loadYuiSkillContexts } from "../context/roleSessionContext.js";
 const ROLE_LAUNCH_CONTEXT_OPTIONS = new Set([
     "--workspace",
     "--description",
@@ -34,14 +33,11 @@ export function validateConfiguredRoleSkills(yuiHome, skillIds) {
         if (!SAFE_SKILL_ID.test(id)) {
             throw usageError(`Configured Skill id is invalid: ${id}.`);
         }
-        const path = resolve(yuiHome, "skills", id, "SKILL.md");
         try {
-            if (!statSync(path).isFile())
-                throw new Error("not a file");
-            accessSync(path, constants.R_OK);
+            loadYuiSkillContexts(yuiHome, [id]);
         }
-        catch {
-            throw usageError(`Configured Skill not found or unreadable: ${id}.`);
+        catch (error) {
+            throw usageError(`Configured Skill not found, unreadable or invalid: ${id}. ${error instanceof Error ? error.message : ""}`);
         }
     }
 }

package/dist/commands/taskCommands.js

@@ -10,8 +10,10 @@ import { buildRunContextDelta, buildRunContextPack, contextSnapshotDeltaRefIds,
 import { createRunInput } from "../context/runInputContract.js";
 import { parseTaskCatalogOptions, readTaskCatalog, renderTaskCatalog } from "../context/taskCatalog.js";
 import { assertContextRecordReadable, readTaskContextResource } from "../context/taskContext.js";
+import { parseTaskSearchOptions, searchTaskBodies } from "../context/taskSearch.js";
 import { boundedDocument, readOptions, messageReceipt, recordPage } from "../output/boundedRead.js";
 import { referencedWakeRunIds } from "../context/wakeRunReferences.js";
+import { taskMessagePresentation, wakeChangeLabels, wakeMessages } from "../interaction/notificationPresentation.js";
 import { completeProcessing, releaseProcessing } from "../coordination/workMailbox.js";
 import { enqueueRoleRunDispatch, enqueueWork, settleExactWorkExecution } from "../coordination/workMailboxQueue.js";
 import { CliError, dataError, roleNotFound, runtimeError, taskNotFound, usageError } from "../errors/cliError.js";
@@ -50,7 +52,7 @@ import { runtimeObservationFromTaskEvent } from "../runtime/runtimeObservation.j
 import { failureCapabilitiesCommand } from "../runtime/agentFailureContext.js";
 import { enqueueOperatorEvent } from "../scheduler/operatorEvent.js";
 import { isRoleRunStalled, RUN_PROGRESS_EVENT, RUN_RECOVERED_EVENT } from "../scheduler/roleRunStall.js";
-import { renderWakeReason, wakeReason } from "../scheduler/wakeReason.js";
+import { parseWakeReason, renderWakeReason, wakeReason } from "../scheduler/wakeReason.js";
 import { queueLeaderWakeup } from "../scheduler/wakeupQueue.js";
 import { planningRuntimeCwd } from "../storage/homeLayout.js";
 import { StorageConflictError } from "../storage/taskStore.js";
@@ -80,6 +82,7 @@ import { assertTaskOpen, clock, exactPositionals, leaderActionEventPayload, lead
 import { assertTaskCompletionPublishedTreeProof } from "./taskCompletionGate.js";
 import { runTaskContextCommand, taskRecordList } from "./taskContextCommand.js";
 import { taskBriefCommand, taskDecisionCommand, taskEventCommand, taskMilestoneCommand } from "./taskFactCommands.js";
+import { taskUsageCommand } from "./taskUsageCommand.js";
 import { openInputRequestCount, runTaskInputCommand } from "./taskInputCommands.js";
 import { runTaskNextActionCommand } from "./taskNextActionCommand.js";
 import { runPublicationCommand } from "./taskPublicationCommands.js";
@@ -341,6 +344,10 @@ function executeTaskCommand(args, store, options = {}) {
         case "create": return createTaskCommand(rest, store, options);
         case "update": return output(updateTaskCommand(rest, store, options));
         case "list": return listTaskCommand(rest, store, options.environment);
+        case "search": {
+            const result = searchTaskBodies(store, parseTaskSearchOptions(rest), options.environment);
+            return output(`${JSON.stringify(result, null, 2)}\n`, result);
+        }
         case "show": return showTaskCommand(rest, store, options.actualTaskReviewCandidate ?? null);
         case "context": return runTaskContextCommand(rest, store, options.environment);
         case "next-action": return runTaskNextActionCommand(rest, store, options.actualTaskReviewCandidate ?? null);
@@ -368,6 +375,7 @@ function executeTaskCommand(args, store, options = {}) {
         case "review": return taskReviewCommand(rest, store, options);
         case "run": return taskRunCommand(rest, store, options);
         case "brief": return taskBriefCommand(rest, store, options);
+        case "usage": return taskUsageCommand(rest, store, options);
         case "decision": return taskDecisionCommand(rest, store, options);
         case "milestone": return taskMilestoneCommand(rest, store, options);
         case "event": return taskEventCommand(rest, store, options);
@@ -1720,6 +1728,13 @@ function taskMessageCommand(args, store, options) {
  * input (decision-3 §5/§6).
  */
 export function applyTaskInputControl(taskId, input, store, options) {
+    if (input.expectedSessionId !== undefined) {
+        const roleName = input.action === "interrupt" ? input.role : input.to ?? "leader";
+        const set = store.getTaskRoleSessionSet(taskId, roleName);
+        if (set?.sessions[set.activeAgentId]?.nativeSessionId !== input.expectedSessionId) {
+            throw usageError("Selected native Session changed; refresh before sending.");
+        }
+    }
     if (input.action === "queue")
         return queueTaskInput(taskId, input, store, options);
     if (input.action === "steer")
@@ -1745,7 +1760,8 @@ function queueTaskInput(taskId, input, store, options) {
     if (recipientRole === undefined && (workItemId !== undefined || reviewRoundId !== undefined)) {
         throw usageError("--to is required for scoped Message delivery.");
     }
-    const result = sendTaskMessageCommand(store, taskId, body, options, recipientRole === undefined ? undefined : { roleName: recipientRole, workItemId, reviewRoundId }, undefined, undefined, { action: "queue", requestId });
+    const result = sendTaskMessageCommand(store, taskId, body, options, recipientRole === undefined ? undefined : { roleName: recipientRole, workItemId, reviewRoundId }, undefined, undefined, { action: "queue", requestId,
+        ...(input.expectedSessionId === undefined ? {} : { expectedSessionId: input.expectedSessionId }) });
     const reason = result.message.continuation?.notDeliveredReason;
     const delivery = result.idempotentReplay ? { state: "idempotent-replay" }
         : reason !== undefined ? { state: "not-delivered", reason }
@@ -1794,7 +1810,8 @@ function steerTaskInput(taskId, input, store, options) {
         throw usageError("Steering the Leader targets its current turn directly; it takes no --work-item/--review-round Assignment.");
     }
     const result = leaderTarget
-        ? sendTaskMessageCommand(store, taskId, body, options, undefined, undefined, undefined, { action: "steer", requestId, expectedTarget })
+        ? sendTaskMessageCommand(store, taskId, body, options, undefined, undefined, undefined, { action: "steer", requestId, expectedTarget,
+            ...(input.expectedSessionId === undefined ? {} : { expectedSessionId: input.expectedSessionId }) })
         : sendTaskMessageCommand(store, taskId, body, options, { roleName: recipientRole, workItemId, reviewRoundId }, undefined, undefined, { action: "steer", requestId, expectedTarget });
     const roleName = result.message.recipient?.roleName ?? recipientRole;
     if (result.idempotentReplay) {
@@ -1921,6 +1938,7 @@ export function sendTaskMessageCommand(store, taskId, body, options = {}, recipi
                     : { roleName: recipient.roleName, workItemId: recipient.workItemId, reviewRoundId: recipient.reviewRoundId };
                 if (prior?.action !== inputControl.action || existing.body !== body
                     || prior.expectedTarget !== inputControl.expectedTarget
+                    || prior.expectedSessionId !== inputControl.expectedSessionId
                     || !isDeepStrictEqual(priorRecipient, nextRecipient)) {
                     throw usageError(`Input requestId ${inputControl.requestId} was already used with different content or target; use a new requestId for a new input.`);
                 }
@@ -3519,6 +3537,7 @@ function dispatchWork(args, store, options) {
                 throw usageError(`${task.id}/${role.name} already has an active run.`);
             }
             const effective = resolveEffectiveLaunch({
+                store: tx,
                 role,
                 purpose: "execution",
                 workspace,
@@ -3575,6 +3594,7 @@ function dispatchWork(args, store, options) {
             }
             const laneWorkspace = managedWorkspace ?? workspace;
             const effective = resolveEffectiveLaunch({
+                store: tx,
                 role,
                 purpose: "execution",
                 workspace: laneWorkspace,
@@ -5101,6 +5121,7 @@ function retryRunOperation(args, store, options) {
             ?? (directSession === undefined ? undefined
                 : effectiveLaunchWithTaskMainWorkspace(directSession.effective, retryManagedWorkspace))
             ?? resolveEffectiveLaunch({
+                store: tx,
                 role,
                 purpose: previous.purpose,
                 ...(retryManagedWorkspace === undefined ? {} : { workspace: retryManagedWorkspace }),
@@ -5636,6 +5657,7 @@ function retryFailedReviewRun(previous, store, options, now) {
             }
             selectedReviewSynthesisProducers(tx, round, group, synthesisSourceRunIds(tx, run));
             const effective = resolveEffectiveLaunch({
+                store: tx,
                 role: reviewer,
                 purpose: "review",
                 workspace: run.workspace,
@@ -6129,6 +6151,7 @@ export function dispatchPreparedReviewRound(taskId, reviewRoundId, store, option
             }
             const runId = tx.nextRunId(taskId);
             const effective = resolveEffectiveLaunch({
+                store: tx,
                 role: reviewer,
                 purpose: "review",
                 workspace: round.workspace,
@@ -6191,6 +6214,7 @@ export function dispatchPreparedReviewRound(taskId, reviewRoundId, store, option
             }
             const laneManagedWorkspace = preparedLaneWorkspaces.get(lane.id);
             const effective = lane.effective ?? resolveEffectiveLaunch({
+                store: tx,
                 role: laneReviewer,
                 purpose: "review",
                 workspace: laneManagedWorkspace,
@@ -6909,12 +6933,16 @@ function taskWakeInspectionCommand(args, store) {
         return output(`${JSON.stringify(data)}\n`, data);
     }
     if (command === "show") {
-        const usage = "Task wake show usage: yui task wake show <task> <wake>.";
-        exactPositionals(rest, 2, usage);
-        const task = requireTask(store, rest[0]);
-        const wake = store.getTaskWake(task.id, rest[1]);
+        const usage = "Task wake show usage: yui task wake show <task> <wake> [--history].";
+        const history = rest.includes("--history");
+        const positional = history ? rest.filter(arg => arg !== "--history") : rest;
+        exactPositionals(positional, 2, usage);
+        if (rest.filter(arg => arg === "--history").length > 1)
+            throw usageError(usage);
+        const task = requireTask(store, positional[0]);
+        const wake = store.getTaskWake(task.id, positional[1]);
         if (wake === null)
-            throw dataError(`Wake not found: ${rest[1]}.`);
+            throw dataError(`Wake not found: ${positional[1]}.`);
         const timeZone = store.getConfig().timeZone;
         const fromMs = Date.parse(wake.fromCursor);
         const toMs = Date.parse(wake.toCursor);
@@ -6930,8 +6958,20 @@ function taskWakeInspectionCommand(args, store) {
         const currentClaim = store.getWorkMailbox(leaderMailbox(task.id))?.processing;
         const referenced = (type, id) => wake.refs?.some(ref => ref.type === type && ref.id === id
             && (!("taskId" in ref) || ref.taskId === task.id)) === true;
-        const events = allEvents.filter((e) => inWindow(e.createdAt) || referenced("event", e.id));
-        const messages = store.listMessages(task.id).filter((m) => inWindow(m.createdAt) || referenced("message", m.id));
+        // Some existing producers carry the exact source only in a reason tag
+        // (e.g. input-timeout:<request>). Do not hide its decision behind --history.
+        const reasonRefs = new Set(wake.reasons.flatMap(tag => {
+            const reason = parseWakeReason(tag);
+            return reason.kind !== "force-wake" && reason.ref !== undefined ? [reason.ref] : [];
+        }));
+        const reasonEvent = (event) => Date.parse(event.createdAt) <= toMs && [
+            event.id, event.payload.runId, event.payload.requestId, event.payload.jobId,
+            event.payload.workItemId, event.payload.reviewRoundId
+        ].some(id => id !== undefined && reasonRefs.has(id));
+        const windowEvents = allEvents.filter((e) => inWindow(e.createdAt) || referenced("event", e.id) || reasonEvent(e));
+        const events = history ? windowEvents : windowEvents.filter(e => referenced("event", e.id)
+            || reasonEvent(e) || ["run.completed", "run.failed", "run.cancelled"].includes(e.type));
+        const messages = wakeMessages(wake, store.listMessages(task.id));
         const allRuns = store.listRuns(task.id);
         const referencedRunIds = new Set(referencedWakeRunIds(allRuns, allEvents, events));
         for (const run of allRuns)
@@ -6940,7 +6980,7 @@ function taskWakeInspectionCommand(args, store) {
         for (const message of messages)
             if (message.resultRef?.type === "agent-run-result")
                 referencedRunIds.add(message.resultRef.runId);
-        const runs = operationalTaskRecords(allRuns, allEvents, "run").filter((run) => (inWindow(run.createdAt) || referencedRunIds.has(run.id)));
+        const runs = operationalTaskRecords(allRuns, allEvents, "run").filter((run) => (history && inWindow(run.createdAt) || referencedRunIds.has(run.id)));
         const lines = [
             `Wake: ${wake.id}`,
             `Task: ${task.id}`,
@@ -6956,29 +6996,40 @@ function taskWakeInspectionCommand(args, store) {
                 `Recovery: correct the cause, then yui task wake retry ${task.id} ${wake.id} --reason <correction>.`
             ]),
             `Reasons: ${wake.reasons.map(renderWakeReason).join(", ")}`,
+            `Changes: ${wakeChangeLabels(wake.reasons).join("; ")}`,
             `Delta window: ${wake.fromCursor} → ${wake.toCursor}`,
             `Dispatched: ${presentTime(wake.createdAt, timeZone)}`,
             ...(wake.consumedAt === undefined
                 ? []
                 : [`Consumed: ${presentTime(wake.consumedAt, timeZone)}`]),
             `Events (${events.length}):`,
-            ...events.map((e) => `  ${e.id} ${e.type} ${presentTime(e.createdAt, timeZone)}`),
+            ...events.map((e) => `  ${e.id} ${e.type} ${presentTime(e.createdAt, timeZone)} → yui task event show ${task.id} ${e.id}`),
             `Messages (${messages.length}):`,
-            ...messages.map((m) => `  ${m.id} [${taskMessageAuthorLabel(m.author)}] ${presentTime(m.createdAt, timeZone)}`),
+            ...messages.map((m) => {
+                const item = taskMessagePresentation(m, (taskId, runId) => store.getRun(taskId, runId));
+                return `  ${m.id} [${taskMessageAuthorLabel(m.author)}] ${item.fact}`
+                    + (item.summary === undefined ? "" : `; author summary (${item.summarySource}): ${JSON.stringify(item.summary)}`)
+                    + ` → yui task message show ${task.id}/${m.id}`;
+            }),
             `AgentRuns (${runs.length}):`,
             ...runs.map((run) => (`  ${run.id} [${run.status}/${run.purpose}] ${run.roleName} `
                 + `${presentTime(run.createdAt, timeZone)}`
                 + `${referencedRunIds.has(run.id)
                     ? ` → yui task run show ${task.id}/${run.id}`
-                    : ""}`))
+                    : ""}`)),
+            ...(!history ? [`History/diagnostics: yui task wake show ${task.id} ${wake.id} --history`,
+                "Read relevant originals in full; follow contentPage.nextCursor when present."] : [])
         ];
         return output(lines.join("\n").concat("\n"), {
             taskId: task.id,
             deliveryEvents,
             wake,
+            view: history ? "history" : "focus",
+            historyRead: `task wake show ${task.id} ${wake.id} --history`,
             events: events.map(event => ({ id: event.id, type: event.type, createdAt: event.createdAt,
                 read: `task event show ${task.id} ${event.id}` })),
             messages: messages.map(message => ({ id: message.id, kind: message.kind, author: message.author,
+                ...taskMessagePresentation(message, (taskId, runId) => store.getRun(taskId, runId)),
                 resultRef: message.resultRef, read: `task message show ${task.id}/${message.id}` })),
             runs: runs.map(run => ({ id: run.id, status: run.status, purpose: run.purpose, roleName: run.roleName,
                 read: `task run show ${task.id}/${run.id}` }))

package/dist/commands/taskUsageCommand.js

@@ -0,0 +1,38 @@
+import { assertContextRecordReadable } from "../context/taskContext.js";
+import { readTaskUsage } from "../runtime/taskUsageQuery.js";
+import { formatUsageMetric } from "../runtime/taskUsageMetrics.js";
+import { exactPositionals, output, parseTail, requireTask } from "./taskCommandSupport.js";
+import { usageError } from "../errors/cliError.js";
+import { taskActor } from "../task/taskAuthority.js";
+export function taskUsageCommand(args, store, options) {
+    const usage = "yui task usage <task> [--limit <0..50>] [--offset <n>]";
+    const parsed = parseTail(args, new Set(["--limit", "--offset"]), usage);
+    exactPositionals(parsed.positionals, 1, usage);
+    const task = requireTask(store, parsed.positionals[0]);
+    // Task-lifetime aggregation spans every Role, beyond a Worker/Reviewer
+    // Assignment. Reading the Task record alone does not authorize these facts.
+    taskActor(options.environment, task.id);
+    assertContextRecordReadable(store, task.id, "task", task.id, options.environment);
+    const limit = Number(parsed.options.get("--limit") ?? 0), offset = Number(parsed.options.get("--offset") ?? 0);
+    if (!Number.isSafeInteger(limit) || limit < 0 || limit > 50 || !Number.isSafeInteger(offset) || offset < 0) {
+        throw usageError(usage);
+    }
+    const result = readTaskUsage(store, task.id, { limit, offset, now: options.now?.() });
+    const money = (kind) => {
+        const metric = result.costs[kind];
+        return metric.amounts.length === 0 ? `unknown (${metric.reasons.join(", ")})`
+            : metric.amounts.map(amount => `${formatUsageMetric(amount)} ${amount.currency}`).join("; ");
+    };
+    return output([
+        `Task: ${task.id} — task lifetime, observed sources only; not a bill`,
+        `Tokens: ${formatUsageMetric(result.tokens)}`,
+        `Tool calls: ${formatUsageMetric(result.toolCalls)}`,
+        `Elapsed: ${formatUsageMetric(result.elapsedSeconds, "s")}`,
+        `Native execution: ${formatUsageMetric(result.executionSeconds, "s")} (not billable duration)`,
+        `Upstream actual: ${money("actual")}`,
+        `Estimated: ${money("estimated")}`,
+        `History: ${result.history.complete ? "all retained facts" : "bounded partial facts"}`,
+        `Details: --limit 20 --offset ${result.details.nextOffset ?? 0}`,
+        ...(limit === 0 ? [] : [JSON.stringify({ sessions: result.sessions, costs: result.costs }, null, 2)])
+    ].join("\n") + "\n", result);
+}