@zq-silk/yui 2.19.0 → 2.21.0

package/dist/cli/commandCatalog.js

@@ -136,6 +136,7 @@ const agentChildren = [
     { name: "remove", discovery: { surface: "public", audiences: ["public", "operator"] }, summary: "Remove a configured Agent.", usage: "yui config agent remove <id>" }
 ];
 const roleProfileOptions = [
+    "--instance-code",
     "--description", "--responsibility", "--constraint",
     "--expected-output", "--system-prompt", "--skill"
 ];
@@ -144,6 +145,7 @@ const roleAgentOptions = [
     "--allowed-tool", "--disallowed-tool", "--search"
 ];
 const roleProfileClearOptions = [
+    "--clear-instance-code",
     "--clear-description", "--clear-responsibilities", "--clear-constraints",
     "--clear-expected-output", "--clear-system-prompt", "--clear-skills"
 ];
@@ -399,19 +401,19 @@ const taskChildren = [
         fileOptions: ["--summary-file"]
     },
     {
-        name: "list", discovery: { surface: "public", audiences: ["public", "operator", "leader"] },
+        name: "list", discovery: { surface: "public", audiences: ["public", "operator", "leader", "assignment"] },
         summary: "Discover Tasks through a bounded, filterable catalog.",
         usage: "yui task list [--all] [--source <ordinary|job>] [--status <status>] [--project <id>] [--search <text>] [--attention <category>] [--limit <1..100>] [--cursor <cursor>]",
         options: ["--all", "--source", "--status", "--project", "--search", "--attention", "--limit", "--cursor"]
     },
     {
-        name: "search", discovery: { surface: "public", audiences: ["public", "operator", "leader"] },
+        name: "search", discovery: { surface: "public", audiences: ["public", "operator", "leader", "assignment"] },
         summary: "Search authorized Task bodies and return exact, reference-only source citations.",
         usage: "yui task search <query> [--task <id>] [--kind <brief|message|decision|result|completion>] [--limit <1..100>] [--cursor <cursor>]",
         options: ["--task", "--kind", "--limit", "--cursor"]
     },
     { name: "show", discovery: { surface: "public", audiences: ["public", "operator", "leader", "assignment"] }, summary: "Show Task metadata and counts; long details use contentPage.", usage: "yui task show <id> [--cursor <cursor>]", options: ["--cursor"] },
-    { name: "usage", discovery: { surface: "public", audiences: ["public", "operator", "leader"] }, summary: "Read bounded Task usage and sourced costs; request detail pages explicitly.", usage: "yui task usage <task> [--limit <0..50>] [--offset <n>]", options: ["--limit", "--offset"] },
+    { name: "usage", discovery: { surface: "public", audiences: ["public", "operator", "leader", "assignment"] }, summary: "Read bounded Task usage and sourced costs; request detail pages explicitly.", usage: "yui task usage <task> [--limit <0..50>] [--offset <n>]", options: ["--limit", "--offset"] },
     {
         name: "artifact", discovery: { surface: "managed", audiences: ["operator", "leader"] },
         summary: "Save Task files in local Git and read current or commit-pinned content.",

package/dist/cli/invocationAuthority.js

@@ -4,7 +4,7 @@ import { requireManagedGlobalCaller } from "../runtime/managedCaller.js";
 import { routeInvocation } from "./invocationRouter.js";
 import { findInteractionPolicy } from "./interactionPolicy.js";
 import { TASK_RECORD_ID_PREFIXES } from "../task/taskRecordReference.js";
-import { taskDiagnosticTarget } from "./managedDiagnostics.js";
+import { isTaskReadCommand } from "./managedDiagnostics.js";
 /** Configuration reads remain available; every Home configuration mutation
  * has one owner, irrespective of which config subcommand parses its flags. */
 export function assertConfigurationAuthority(args, store, env) {
@@ -37,12 +37,8 @@ export function assertTaskInvocationScope(args, env) {
     }
     if (args[0] !== "task" || ["list", "search"].includes(args[1] ?? ""))
         return;
-    const diagnostic = taskDiagnosticTarget(args);
-    if (diagnostic !== undefined) {
-        if (diagnostic !== env.YUI_TASK_ID)
-            throw usageError("Command target is outside the caller's Task.");
+    if (isTaskReadCommand(args))
         return;
-    }
     const invocation = routeInvocation([...args]);
     if (invocation.kind !== "execute")
         return;

package/dist/cli/managedDiagnostics.js

@@ -1,20 +1,28 @@
-/** Read/repair routing, not an alternative grant. Callers still prove their
- * Home and Role identity; writes still require current Session authority. */
-export function taskDiagnosticTarget(args) {
+/** Explicit effect classification, not a verb-name heuristic. Ordinary reads
+ * authenticate the caller but do not borrow the target Task's authority.
+ * Mixed commands (retry, base status) stay mutating unless this exact form is
+ * read-only. Domain parsers still reject unknown flags and malformed targets. */
+export function isTaskReadCommand(args) {
     if (args[0] !== "task")
-        return undefined;
-    if (["show", "context", "next-action", "archive-preflight"].includes(args[1] ?? "")) {
-        return args[1] === "context" && ["read", "list", "inspect", "delta"].includes(args[2] ?? "")
-            ? args[3] : args[2];
-    }
-    if (args[1] === "role" && ["list", "status", "show"].includes(args[2] ?? ""))
-        return args[3];
-    if (args[1] === "role" && args[2] === "session" && args[3] === "inspect")
-        return args[4];
-    if (["message", "run", "wake", "input"].includes(args[1] ?? "")
+        return false;
+    if (["list", "search", "show", "usage", "next-action", "remote-delivery", "archive-preflight"].includes(args[1] ?? ""))
+        return true;
+    if (args[1] === "context")
+        return true;
+    if (["brief", "decision", "milestone", "event", "message", "run", "wake", "input", "work", "publication"].includes(args[1] ?? "")
         && ["list", "show"].includes(args[2] ?? ""))
-        return args[3]?.split("/")[0];
-    return undefined;
+        return true;
+    if (args[1] === "artifact" && ["list", "read"].includes(args[2] ?? ""))
+        return true;
+    if (args[1] === "run" && args[2] === "context")
+        return true;
+    if (args[1] === "role" && ["list", "status", "show"].includes(args[2] ?? ""))
+        return true;
+    if (args[1] === "role" && args[2] === "session") {
+        return args[3] === "inspect"
+            || args[3] === "retry" && (args.length === 6 || args.length === 7 && args[6] === "show");
+    }
+    return false;
 }
 export function operatorOfflineCommand(args) {
     return (args[0] === "controller"
@@ -25,5 +33,5 @@ export function operatorOfflineCommand(args) {
         || (args[0] === "session" && ["context", "reconcile"].includes(args[1] ?? ""))
         || (args[0] === "role" && args[1] === "message" && ["list", "show"].includes(args[2] ?? ""))
         || (args[0] === "task" && args[1] === "list")
-        || taskDiagnosticTarget(args) !== undefined;
+        || isTaskReadCommand(args);
 }

package/dist/commands/durableJobCommands.js

@@ -2,7 +2,7 @@ import { usageError } from "../errors/cliError.js";
 import { ensureFileTaskController } from "../controller/clientRuntime.js";
 import { callFileTaskController } from "../controller/clientRuntime.js";
 import { acknowledgeDurableJob, cancelDurableJob, getDurableJob, startDurableJob } from "../controller/jobClient.js";
-import { resolveJobCaller, taskLocalActor } from "../task/taskAuthority.js";
+import { resolveJobCaller, resolveJobReadCaller, taskLocalActor } from "../task/taskAuthority.js";
 import { boundedJobArtifactPayload } from "../artifacts/jobArtifactTransport.js";
 import { readFileSync, statSync } from "node:fs";
 /**
@@ -177,8 +177,7 @@ async function startJob(args, options) {
 }
 async function getJob(args, options) {
     const ref = parseRefArgs(args, "get");
-    const caller = resolveJobCaller(options.environment, ref.taskId);
-    await ensureFileTaskController(options.home, { environment: options.environment });
+    const caller = resolveJobReadCaller(options.environment, ref.taskId);
     const job = await getDurableJob(options.home, ref.taskId, ref.jobId, caller);
     if (options.json === true)
         return `${JSON.stringify(job, null, 2)}\n`;

package/dist/commands/roleConfiguration.js

@@ -1,4 +1,5 @@
 import { usageError } from "../errors/cliError.js";
+import { validateInstanceCode } from "../role/instanceCode.js";
 import { parseEnabled } from "../role/availability.js";
 import { defaultRoleAgentConfig, resolveAgentAdapter } from "../executor/agentAdapter.js";
 const PROFILE_OPTIONS = [
@@ -66,6 +67,8 @@ export function roleOptionSpecs(input) {
         ...(input.includeWorkspace === true ? [["--workspace", "value"]] : []),
         ...(input.update ? [["--yes", "flag"]] : []),
         ...(input.update ? [["--enabled", "value"]] : []),
+        ["--instance-code", "value"],
+        ...(input.update ? [["--clear-instance-code", "flag"]] : []),
         ...PROFILE_OPTIONS,
         ...agentValueOptions,
         ...agentRepeatableOptions,
@@ -105,6 +108,7 @@ export function parseRoleOptions(args, specs, usage) {
 }
 export function roleProfileFrom(parsed) {
     return {
+        ...roleDisplayPatch(parsed),
         ...(parsed.has("--description") ? { description: requiredText(parsed.one("--description")) } : {}),
         responsibilities: parsed.many("--responsibility").map(requiredText),
         constraints: parsed.many("--constraint").map(requiredText),
@@ -125,6 +129,7 @@ export function roleProfilePatch(parsed) {
         ["--skill", "--clear-skills"]
     ]);
     return {
+        ...roleDisplayPatch(parsed),
         ...(parsed.has("--enabled") ? { enabled: parseEnabled(parsed.one("--enabled")) } : {}),
         ...(parsed.has("--description") ? { description: requiredText(parsed.one("--description")) } : {}),
         ...(parsed.has("--clear-description") ? { description: undefined } : {}),
@@ -144,6 +149,18 @@ export function roleProfilePatch(parsed) {
         ...(parsed.has("--clear-skills") ? { skills: [] } : {})
     };
 }
+function roleDisplayPatch(parsed) {
+    assertPairs(parsed, [["--instance-code", "--clear-instance-code"]]);
+    try {
+        return {
+            ...(parsed.has("--instance-code") ? { instanceCode: validateInstanceCode(parsed.one("--instance-code")) } : {}),
+            ...(parsed.has("--clear-instance-code") ? { instanceCode: undefined } : {})
+        };
+    }
+    catch (error) {
+        throw usageError(error instanceof Error ? error.message : String(error));
+    }
+}
 export function hasAgentConfigOptions(parsed) {
     return [...parsed.seen].some((option) => AGENT_CONFIG_OPTIONS.has(option));
 }

package/dist/commands/taskCommands.js

@@ -11,7 +11,7 @@ import { sourceRunContextValue } from "../context/sourceRunContext.js";
 import { buildRunContextDelta, buildRunContextPack, runContextEntry, runContextPointerPage, contextSnapshotDeltaRefIds, expandRunContextRef, freezeReviewStageContextSnapshot, freezeRunContextSnapshot, freezeWorkItemExecutionAssignmentContextSnapshot, freezeCandidateContextSnapshot, readRunContextSnapshot, synthesisSourceRunIds } from "../context/runContextPack.js";
 import { createRunInput } from "../context/runInputContract.js";
 import { parseTaskCatalogOptions, readTaskCatalog, renderTaskCatalog } from "../context/taskCatalog.js";
-import { assertContextRecordReadable, readTaskContextResource } from "../context/taskContext.js";
+import { assertTaskReadable, readTaskContextResource, resolveContextReader } 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";
@@ -46,7 +46,7 @@ import { resolveRecordedTaskFinalReviewContract } from "../review/taskFinalRevie
 import { copyGlobalRoleToTaskRole, activeRoleAgentBinding, createRole, createRoleAgentBinding, switchActiveRoleAgent, unbindRoleAgent, updateRole } from "../role/role.js";
 import { roleLaunchEventPayload, saveTaskRoleUpdate } from "../role/taskRoleUpdate.js";
 import { RUNTIME_SESSION_REPLACE_REQUIRED_REASON, runtimeLifecycleTarget } from "../runtime/lifecycleReservation.js";
-import { currentManagedRuntime, resolveManagedTaskReader } from "../runtime/managedCaller.js";
+import { currentManagedRuntime } from "../runtime/managedCaller.js";
 import { controlProviderRetry, providerRunRetry, providerRetryProjection, renderProviderRetry } from "../runtime/providerRetry.js";
 import { currentProviderConversation, transferProviderAuthority } from "../runtime/providerRuntimeIdentity.js";
 import { projectProviderContinuations } from "../runtime/runtimeContinuationProjection.js";
@@ -1684,7 +1684,7 @@ function taskMessageCommand(args, store, options) {
         const parsed = readOptions(rest, ["--cursor"]);
         exactPositionals(parsed.positionals, 1, usage);
         const ref = taskRecordReference(parsed.positionals[0], "message", "Message reference", options);
-        assertContextRecordReadable(store, ref.taskId, "task-message", ref.localId, options.environment);
+        assertTaskReadable(store, ref.taskId, options.environment);
         const message = store.queryContextRecords(ref.taskId, {
             family: "task-message", ids: [ref.localId], limit: 1
         }).records[0]?.value;
@@ -2512,14 +2512,8 @@ function taskRoleSessionCommand(args, store, options) {
             const role = requireRole(tx, task.id, roleName);
             if (action !== "show")
                 taskActor(tx, options, task.id);
-            else {
-                const reader = resolveManagedTaskReader(tx, options.environment);
-                if (reader === undefined)
-                    taskActor(tx, options, task.id);
-                else if (reader.taskId !== task.id || reader.roleName !== "leader" && reader.roleName !== role.name) {
-                    throw usageError("Provider retry read is outside the caller's Task/Role.");
-                }
-            }
+            else
+                resolveContextReader(tx, options.environment ?? {});
             const sessions = tx.getTaskRoleSessionSet(task.id, role.name);
             let binding = sessions?.providerBinding ?? null;
             if (action !== "show") {
@@ -2538,12 +2532,7 @@ function taskRoleSessionCommand(args, store, options) {
         exactPositionals(rest, 2, "Task Role Session inspect usage: yui task role session inspect <task> <role>.");
         const task = requireTask(store, rest[0]);
         const role = requireRole(store, task.id, rest[1]);
-        const reader = resolveManagedTaskReader(store, options.environment);
-        if (reader === undefined)
-            taskActor(store, options, task.id);
-        else if (reader.taskId !== task.id || (reader.roleName !== "leader" && reader.roleName !== role.name)) {
-            throw usageError("Session inspection is outside the caller's Task/Role.");
-        }
+        resolveContextReader(store, options.environment ?? {});
         const sessions = store.getTaskRoleSessionSet(task.id, role.name);
         const active = sessions?.sessions[sessions.activeAgentId] ?? null;
         const binding = sessions?.providerBinding ?? null;
@@ -4823,30 +4812,14 @@ function parseRunContextReference(value) {
     }
     return { taskId, runId };
 }
-/**
- * A AgentRun Context Pack is information the Role's own runtime reads in order to
- * work. Authorization is therefore scope-shaped, not schedule-shaped: the
- * caller must be the current runtime of the Task Role that owns the AgentRun,
- * proven by its per-Session caller key against durable state.
- *
- * It deliberately does not require the AgentRun to still be the active one. An
- * Agent whose AgentRun has advanced must still be able to read the context it was
- * given; losing read access to its own Role's history is what forces an
- * otherwise healthy Agent to stop and escalate to a human.
- */
+/** Frozen packs are readable evidence. Their execution authority still belongs
+ * exclusively to the dispatched Run; reading does not adopt that identity. */
 function authorizeRunContext(store, taskId, runId, environment) {
-    const managed = environment?.YUI_SESSION_SCOPE !== undefined
-        || environment?.YUI_TASK_ID !== undefined
-        || environment?.YUI_ROLE !== undefined;
-    if (!managed)
-        return;
+    resolveContextReader(store, environment ?? {});
     const run = store.getRun(taskId, runId);
     if (run === null) {
         throw usageError(`AgentRun Context access is not authorized: ${taskId}/${runId}.`);
     }
-    if (currentManagedRuntime(store, environment, taskId, run.roleName) === undefined) {
-        throw usageError(`AgentRun Context access requires the current runtime of ${taskId}/${run.roleName}.`);
-    }
 }
 function listRuns(args, store, options) {
     const reference = args[0];

package/dist/commands/taskFactCommands.js

@@ -1,5 +1,5 @@
 import { createTaskBrief, updateTaskBrief } from "../brief/taskBrief.js";
-import { assertContextRecordReadable, resolveContextReader } from "../context/taskContext.js";
+import { assertTaskReadable, resolveContextReader } from "../context/taskContext.js";
 import { taskRecordList } from "./taskContextCommand.js";
 import { materialize } from "../context/taskContext.js";
 import { enqueueWork } from "../coordination/workMailboxQueue.js";
@@ -15,7 +15,7 @@ export function taskBriefCommand(args, store, options) {
         exactPositionals(rest, 1, "Task brief show usage: yui task brief show <task>.");
         const { task, brief, writeGuard, phase } = store.readTransaction(reader => {
             const task = requireTask(reader, rest[0]);
-            assertContextRecordReadable(reader, task.id, "task-brief", task.id, options.environment);
+            assertTaskReadable(reader, task.id, options.environment);
             const caller = resolveContextReader(reader, options.environment ?? {});
             const shared = caller === undefined || caller.roleName === "leader";
             return { task, brief: reader.getTaskBrief(task.id),
@@ -144,7 +144,7 @@ export function taskDecisionCommand(args, store, options) {
     if (command === "show") {
         exactPositionals(rest, 2, "Task decision show usage: yui task decision show <task> <decision>.");
         const task = requireTask(store, rest[0]);
-        assertContextRecordReadable(store, task.id, "task-decision", rest[1], options.environment);
+        assertTaskReadable(store, task.id, options.environment);
         const decision = store.getDecision(task.id, rest[1]);
         if (decision === null)
             throw dataError(`Decision not found: ${rest[1]}.`);
@@ -228,7 +228,7 @@ export function taskMilestoneCommand(args, store, options) {
     if (command === "show") {
         exactPositionals(rest, 2, "Task milestone show usage: yui task milestone show <task> <milestone>.");
         const task = requireTask(store, rest[0]);
-        assertContextRecordReadable(store, task.id, "task-milestone", rest[1], options.environment);
+        assertTaskReadable(store, task.id, options.environment);
         const milestone = store.getMilestone(task.id, rest[1]);
         if (milestone === null)
             throw dataError(`Milestone not found: ${rest[1]}.`);
@@ -254,7 +254,7 @@ export function taskEventCommand(args, store, options = {}) {
     if (command === "show") {
         exactPositionals(rest, 2, "Task event show usage: yui task event show <task> <event>.");
         const task = requireTask(store, rest[0]);
-        assertContextRecordReadable(store, task.id, "task-event", rest[1], options.environment);
+        assertTaskReadable(store, task.id, options.environment);
         const event = store.queryContextRecords(task.id, {
             family: "task-event", ids: [rest[1]], limit: 1
         }).records[0]?.value;

package/dist/commands/taskUsageCommand.js

@@ -1,18 +1,14 @@
-import { assertContextRecordReadable } from "../context/taskContext.js";
+import { assertTaskReadable } 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);
+    assertTaskReadable(store, 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);

package/dist/context/taskCatalog.js

@@ -50,26 +50,17 @@ export function parseTaskCatalogOptions(args) {
         ...(values.has("--cursor") ? { cursor: values.get("--cursor") } : {})
     };
 }
-/** Task-local Leaders discover only their Task. Assignment Roles use their
- * existing Context pack: whole-Task counts would leak unrelated assignments. */
-export function taskCatalogScope(store, environment) {
-    const caller = resolveContextReader(store, environment);
-    if (caller !== undefined && caller.roleName !== "leader") {
-        throw usageError("Task discovery is unavailable to an Assignment-scoped Role; use its authorized Run Context.");
-    }
-    return caller?.taskId;
-}
 export function readTaskCatalog(store, options, environment = {}) {
     return store.transaction(reader => {
-        const taskId = taskCatalogScope(reader, environment);
+        resolveContextReader(reader, environment);
         const { cursor: rawCursor, ...filters } = options;
         if (!Number.isSafeInteger(filters.limit) || filters.limit < 1 || filters.limit > MAX_LIMIT) {
             throw usageError("Task catalog limit must be between 1 and 100.");
         }
-        const scope = contextContentDigest({ taskId: taskId ?? null, ...filters });
+        const scope = contextContentDigest({ taskId: null, ...filters });
         const cursor = rawCursor === undefined ? undefined : decodeCursor(rawCursor, scope);
         const facts = reader.queryTaskCatalog({
-            ...filters, ...(taskId === undefined ? {} : { taskId }),
+            ...filters,
             ...(cursor === undefined ? {} : { after: cursor.after, through: cursor.through }),
             limit: options.limit + 1
         });
@@ -106,7 +97,7 @@ export function readTaskCatalog(store, options, environment = {}) {
         }));
         const response = {
             view: "compact",
-            scope: { taskId: taskId ?? null, archived: options.all ? "included" : "excluded",
+            scope: { taskId: null, archived: options.all ? "included" : "excluded",
                 attention: "authorized-catalog-before-filters", executionSignals: "raw-inspection-candidates-not-execution-status" },
             filters, total: facts.total, counts: facts.counts, attention,
             tasks: [],