@zq-silk/yui 2.3.0 → 2.4.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,6 +10,7 @@ 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 { completeProcessing, releaseProcessing } from "../coordination/workMailbox.js";
@@ -80,6 +81,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 +343,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 +374,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 +1727,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 +1759,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 +1809,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 +1937,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 +3536,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 +3593,7 @@ function dispatchWork(args, store, options) {
             }
             const laneWorkspace = managedWorkspace ?? workspace;
             const effective = resolveEffectiveLaunch({
+                store: tx,
                 role,
                 purpose: "execution",
                 workspace: laneWorkspace,
@@ -5101,6 +5120,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 +5656,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 +6150,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 +6213,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,

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

package/dist/context/roleSessionContext.js

@@ -2,8 +2,9 @@ import { createHash } from "node:crypto";
 import { readFileSync } from "node:fs";
 import { join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
+import { snapshotSkillPackage, verifySkillPackage } from "./skillPackage.js";
 import { SYSTEM_LEADER_ROLE, SYSTEM_OPERATOR_ROLE } from "../role/systemRoles.js";
-const BUILTIN_YUI_SKILLS = new Set([
+export const BUILTIN_YUI_SKILLS = new Set([
     "yui-runtime",
     "yui-operator",
     "yui-leader",
@@ -22,7 +23,9 @@ export function compileRoleSessionContext(yuiHome, role, owner, options = {}) {
         ...(builtInSkillId === undefined ? [] : [builtInSkillId]),
         ...(role.skills ?? [])
     ]);
-    const skills = loadYuiSkillContexts(yuiHome, skillIds);
+    const skills = options.skillPackages === undefined
+        ? loadYuiSkillContexts(yuiHome, skillIds)
+        : options.skillPackages.map(loadSkillPackageContext);
     return {
         developerInstructions: renderDeveloperInstructions(kind, role, owner),
         skills,
@@ -100,6 +103,14 @@ function loadSkill(yuiHome, id, builtIn) {
         ? resolve(fileURLToPath(new URL(`../../skills/${id}/`, import.meta.url)))
         : resolve(join(yuiHome, "skills", id));
     try {
+        if (yuiHome !== undefined) {
+            return loadSkillPackageContext(snapshotSkillPackage({
+                home: yuiHome,
+                root: builtIn ? resolve(path, "..") : path,
+                id, kind: builtIn ? "builtin" : "configured",
+                ...(builtIn ? { subdirectory: id } : {})
+            }));
+        }
         return { id, path, content: readFileSync(join(path, "SKILL.md"), "utf8").trim() };
     }
     catch (error) {
@@ -109,6 +120,11 @@ function loadSkill(yuiHome, id, builtIn) {
         throw error;
     }
 }
+export function loadSkillPackageContext(ref) {
+    verifySkillPackage(ref);
+    return { id: ref.id, path: ref.path, content: readFileSync(join(ref.path, "SKILL.md"), "utf8").trim(),
+        package: ref };
+}
 function unique(values) {
     return [...new Set(values)];
 }

package/dist/context/runContextPack.js

@@ -329,6 +329,7 @@ export function buildRunContextPack(store, taskId, runId) {
             workspace: run.effective.workspace.root
         }),
         snapshot: contextSnapshotRef(snapshot),
+        skillPackages: run.effective.skillPackages ?? null,
         input: run.inputs[0].input,
         authority: Object.freeze({ view, writableProjectIds }),
         pointers,
@@ -698,7 +699,10 @@ function materialize(layer, store, refId, value) {
             refId,
             revision,
             digest,
-            summary: title.slice(0, 400)
+            summary: (store === "project-knowledge"
+                ? [title, `version: ${record.version}`, ...(record.scope === undefined ? [] : [`scope: ${record.scope}`]),
+                    ...(record.expiresWhen === undefined ? [] : [`expiresWhen: ${record.expiresWhen}`])].join("; ")
+                : title).slice(0, 400)
         }),
         value
     });

package/dist/context/sessionBootstrapManifest.js

@@ -2,6 +2,7 @@ import { createHash } from "node:crypto";
 import { chmodSync, readFileSync } from "node:fs";
 import { join, resolve } from "node:path";
 import { writeTextFileAtomically } from "../storage/durableFile.js";
+import { validateSkillPackageRef } from "./skillPackage.js";
 import { SESSION_BOOTSTRAP_MANIFEST_SCHEMA_VERSION, SESSION_CONTEXT_PROTOCOL, sessionManifestCompatibilityDigest } from "./sessionProtocolIdentity.js";
 export { SESSION_BOOTSTRAP_MANIFEST_SCHEMA_VERSION, SESSION_CONTEXT_PROTOCOL, sessionManifestCompatibilityDigest } from "./sessionProtocolIdentity.js";
 /** Portable read pointers accompany every managed input, including the first
@@ -69,6 +70,13 @@ export function readSessionBootstrapManifest(path) {
         requireText(entry.id, "Session Manifest Skill id");
         requireText(entry.path, "Session Manifest Skill path");
         requireDigest(entry.digest, "Session Manifest Skill digest");
+        if (entry.package !== undefined) {
+            const ref = entry.package;
+            validateSkillPackageRef(ref);
+            if (entry.id !== ref.id || entry.path !== ref.path || entry.digest !== ref.digest) {
+                throw new Error("Session Manifest Skill package identity mismatch.");
+            }
+        }
     }
     const profile = record.roleProfileRef;
     requireDigest(profile.digest, "Session Manifest Role Profile digest");
@@ -106,7 +114,8 @@ export function materializeSessionBootstrap(input) {
         skills: input.skills.map((skill) => Object.freeze({
             id: skill.id,
             path: skill.path,
-            digest: digest(skill.content)
+            digest: skill.package?.digest ?? digest(skill.content),
+            ...(skill.package === undefined ? {} : { package: skill.package })
         })),
         roleProfileRef: { digest: profileDigest, path: roleProfilePath },
         contextProtocol: input.owner.scope === "global"