@zq-silk/yui 2.3.0 → 2.5.0

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
@@ -11,12 +12,18 @@ export function withSessionContextPointer(text, environment) {
     if (manifest === undefined)
         return text;
     return [
-        `Read the Yui Session Manifest at ${manifest}.`,
-        "Follow its referenced Role Skills and role profile. It gives the exact Context load command.",
+        sessionContextInstructions(manifest),
         "",
         text
     ].join("\n");
 }
+/** No remembered/sent flag can prove instructions survived context compaction. */
+export function sessionContextInstructions(manifestPath, digest) {
+    return `Yui Session Manifest: ${manifestPath}${digest === undefined ? "" : ` (digest ${digest})`}. `
+        + "Apply yui-runtime and its Role Skills/profile by exact manifest paths. "
+        + "Load on first entry, version change or missing context; reuse only same-version instructions "
+        + "fully available now, never infer availability from prior reads.";
+}
 /** Read back one immutable Session Manifest and verify its content digest. */
 export function readSessionBootstrapManifest(path) {
     const source = resolve(path);
@@ -69,6 +76,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 +120,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"

package/dist/context/skillCatalog.js

@@ -0,0 +1,108 @@
+import { createHash } from "node:crypto";
+import { lstatSync, readFileSync, readdirSync, realpathSync } from "node:fs";
+import { dirname, join, relative, resolve, sep } from "node:path";
+import { fileURLToPath } from "node:url";
+import { verifySkillPackage } from "./skillPackage.js";
+import { BUILTIN_YUI_SKILLS } from "./roleSessionContext.js";
+const SAFE_ID = /^[A-Za-z0-9][A-Za-z0-9_-]*$/u;
+const MAX_TEXT = 256 * 1024;
+const digest = (data) => createHash("sha256").update(data).digest("hex");
+/** Read-only source discovery; browsing never snapshots, installs or executes a package. */
+export function skillSource(home, id) {
+    if (!SAFE_ID.test(id))
+        throw new Error("Invalid Skill id.");
+    const builtin = BUILTIN_YUI_SKILLS.has(id);
+    return { kind: builtin ? "builtin" : "configured",
+        path: builtin ? fileURLToPath(new URL(`../../skills/${id}`, import.meta.url)) : resolve(home, "skills", id) };
+}
+function physical(path) {
+    if (realpathSync(path) !== resolve(path))
+        throw new Error("Skill paths must not contain symlinks.");
+}
+function textFile(path) {
+    physical(path);
+    const stat = lstatSync(path);
+    if (!stat.isFile() || stat.size > MAX_TEXT)
+        throw new Error("Only regular UTF-8 text files up to 256 KiB can be read.");
+    const bytes = readFileSync(path);
+    if (bytes.length > MAX_TEXT)
+        throw new Error("Skill content exceeds 256 KiB.");
+    const content = new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+    if (/[\u0000-\u0008\u000b\u000c\u000e-\u001f]/u.test(content))
+        throw new Error("Binary Skill resources cannot be displayed.");
+    return { content, byteSize: bytes.length, fileDigest: digest(bytes) };
+}
+export function listSkillSources(home, query = "", cursor = "0") {
+    if (query.length > 256 || !/^\d{1,8}$/u.test(cursor))
+        throw new Error("Invalid Skill search or cursor.");
+    let configured = [];
+    try {
+        const directory = resolve(home, "skills");
+        physical(directory);
+        configured = readdirSync(directory).filter(id => SAFE_ID.test(id));
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            throw error;
+    }
+    // Bounded discovery has an explicit limit, never silently presents a partial catalog.
+    if (configured.length > 2048)
+        throw new Error("Skill directory exceeds the 2048-entry browsing limit.");
+    const needle = query.trim().toLowerCase();
+    const items = [...new Set([...BUILTIN_YUI_SKILLS, ...configured])].sort().map(id => {
+        const source = skillSource(home, id);
+        try {
+            const file = textFile(join(source.path, "SKILL.md"));
+            const description = /^description:\s*(.+)$/mu.exec(file.content)?.[1]
+                ?? file.content.split("\n").find(line => line.trim() && !line.startsWith("#")) ?? "";
+            return { id, source, description: description.slice(0, 600), error: null };
+        }
+        catch (error) {
+            return { id, source, description: "", error: error instanceof Error ? error.message : String(error) };
+        }
+    }).filter(item => !needle || `${item.id} ${item.description}`.toLowerCase().includes(needle));
+    const offset = Number(cursor);
+    return { items: items.slice(offset, offset + 30), total: items.length,
+        nextCursor: offset + 30 < items.length ? String(offset + 30) : null };
+}
+export function readSkillSource(home, id, resource = "SKILL.md") {
+    const source = skillSource(home, id);
+    const files = [];
+    let entries = 0;
+    function walk(path, depth) {
+        if (depth > 32)
+            throw new Error("Skill resource depth exceeds 32.");
+        physical(path);
+        for (const name of readdirSync(path).sort()) {
+            if (++entries > 4096)
+                throw new Error("Skill exceeds the 4096-entry browsing limit.");
+            const child = join(path, name);
+            const stat = lstatSync(child);
+            if (stat.isSymbolicLink() || !stat.isDirectory() && !stat.isFile())
+                throw new Error("Skill contains a symlink or special file.");
+            if (stat.isDirectory())
+                walk(child, depth + 1);
+            else
+                files.push(relative(source.path, child).split(sep).join("/"));
+            if (files.length > 2048)
+                throw new Error("Skill contains more than 2048 resources.");
+        }
+    }
+    walk(source.path, 0);
+    if (!files.includes("SKILL.md"))
+        throw new Error("Skill entrypoint SKILL.md is missing.");
+    if (!files.includes(resource))
+        throw new Error("Resource is not in this Skill package.");
+    return { id, source, version: "current-source", resource, files, ...textFile(join(source.path, resource)) };
+}
+/** The reference must come from a stored Session/Run, never from client paths. */
+export function readFrozenSkill(ref, resource) {
+    const manifest = verifySkillPackage(ref);
+    const root = join(dirname(ref.manifestPath), "files");
+    const entrypoint = relative(root, join(ref.path, "SKILL.md")).split(sep).join("/");
+    const selected = resource ?? entrypoint;
+    if (!manifest.files.some(file => file.path === selected))
+        throw new Error("Resource is not in this frozen Skill package.");
+    return { id: ref.id, source: ref.source, version: ref.digest, resource: selected,
+        files: manifest.files.map(file => file.path), ...textFile(join(root, selected)) };
+}

package/dist/context/skillPackage.js

@@ -0,0 +1,161 @@
+import { createHash } from "node:crypto";
+import { existsSync, lstatSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, realpathSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+const MAX_FILES = 2048;
+const MAX_BYTES = 32 * 1024 * 1024;
+const MAX_FILE_BYTES = 8 * 1024 * 1024;
+const hash = (bytes) => createHash("sha256").update(bytes).digest("hex");
+/** A package is data: no script, hook or executable is invoked while loading it.
+ * Builtin Skills share one tree so their sibling-relative references stay valid. */
+export function snapshotSkillPackage(input) {
+    const root = resolve(input.root);
+    assertPhysical(root);
+    const files = [];
+    const contents = new Map();
+    let byteSize = 0;
+    function walk(directory, depth) {
+        if (depth > 32)
+            throw new Error("Skill package directory depth exceeds 32.");
+        for (const name of readdirSync(directory).sort()) {
+            if (name.includes("\\") || /[\x00-\x1f\x7f]/u.test(name)) {
+                throw new Error(`Invalid Skill resource name: ${JSON.stringify(name)}.`);
+            }
+            const path = join(directory, name);
+            const stat = lstatSync(path);
+            if (stat.isDirectory()) {
+                walk(path, depth + 1);
+                continue;
+            }
+            if (!stat.isFile())
+                throw new Error(`Skill package requires regular files, not symlinks or special files: ${path}.`);
+            if (files.length >= MAX_FILES || stat.size > MAX_FILE_BYTES || byteSize + stat.size > MAX_BYTES) {
+                throw new Error(`Skill package exceeds limits (${MAX_FILES} files, 8 MiB/file, 32 MiB total).`);
+            }
+            const bytes = readFileSync(path);
+            if (bytes.length !== stat.size)
+                throw new Error(`Skill resource changed while reading: ${path}.`);
+            byteSize += bytes.length;
+            const entry = { path: relative(root, path).split(sep).join("/"), digest: hash(bytes),
+                size: bytes.length, executable: (stat.mode & 0o111) !== 0 };
+            files.push(entry);
+            contents.set(entry.path, bytes);
+        }
+    }
+    walk(root, 0);
+    files.sort((a, b) => a.path < b.path ? -1 : a.path > b.path ? 1 : 0);
+    const subdirectory = input.subdirectory ?? "";
+    const entrypoint = subdirectory ? `${subdirectory}/SKILL.md` : "SKILL.md";
+    if (!contents.has(entrypoint))
+        throw new Error(`Configured Skill not found: ${input.id}.`);
+    // Names, raw bytes and executable intent all participate; mtimes and source
+    // locations do not. Identical bundles deduplicate across Roles and Sessions.
+    const digest = hash(JSON.stringify(files));
+    const parent = resolve(input.home, "runtime", "skill-packages");
+    mkdirSync(parent, { recursive: true, mode: 0o700 });
+    assertPhysical(parent);
+    const destination = join(parent, digest);
+    const manifest = { schemaVersion: 1, files, digest };
+    if (!existsSync(destination)) {
+        const staging = mkdtempSync(join(parent, ".staging-"));
+        try {
+            for (const file of files) {
+                const path = join(staging, "files", file.path);
+                mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+                writeFileSync(path, contents.get(file.path), { flag: "wx", mode: file.executable ? 0o500 : 0o400 });
+            }
+            writeFileSync(join(staging, "manifest.json"), JSON.stringify(manifest), { flag: "wx", mode: 0o400 });
+            try {
+                renameSync(staging, destination);
+            }
+            catch (error) {
+                if (!existsSync(destination))
+                    throw error;
+                // Another producer can have won the same content-addressed destination.
+            }
+        }
+        finally {
+            rmSync(staging, { recursive: true, force: true });
+        }
+    }
+    const ref = {
+        id: input.id, path: join(destination, "files", subdirectory), digest,
+        source: { kind: input.kind, path: join(root, subdirectory) },
+        manifestPath: join(destination, "manifest.json"), fileCount: files.length, byteSize
+    };
+    verifySkillPackage(ref);
+    return ref;
+}
+export function validateSkillPackageRef(ref) {
+    if (ref === null || typeof ref !== "object"
+        || !/^[A-Za-z0-9][A-Za-z0-9_-]*$/u.test(ref.id)
+        || !/^[a-f0-9]{64}$/u.test(ref.digest)
+        || typeof ref.path !== "string" || !isAbsolute(ref.path)
+        || typeof ref.manifestPath !== "string" || !isAbsolute(ref.manifestPath)
+        || basename(dirname(ref.manifestPath)) !== ref.digest || basename(ref.manifestPath) !== "manifest.json"
+        || !ref.source || !["builtin", "configured"].includes(ref.source.kind)
+        || typeof ref.source.path !== "string" || !isAbsolute(ref.source.path)
+        || !Number.isSafeInteger(ref.fileCount) || ref.fileCount < 1 || ref.fileCount > MAX_FILES
+        || !Number.isSafeInteger(ref.byteSize) || ref.byteSize < 0 || ref.byteSize > MAX_BYTES) {
+        throw new Error("Skill package reference is invalid.");
+    }
+}
+/** Fail closed on lost/corrupt snapshots. Never refill them from mutable sources. */
+export function verifySkillPackage(ref) {
+    validateSkillPackageRef(ref);
+    const root = join(dirname(ref.manifestPath), "files");
+    assertPhysical(dirname(ref.manifestPath));
+    assertPhysical(ref.manifestPath);
+    if (lstatSync(ref.manifestPath).size > 1024 * 1024)
+        throw new Error("Skill package manifest exceeds limits.");
+    const manifest = JSON.parse(readFileSync(ref.manifestPath, "utf8"));
+    if (manifest.schemaVersion !== 1 || !Array.isArray(manifest.files)
+        || manifest.digest !== ref.digest || hash(JSON.stringify(manifest.files)) !== ref.digest
+        || manifest.files.length !== ref.fileCount)
+        throw new Error("Skill package manifest digest mismatch.");
+    const entrypoint = relative(root, join(ref.path, "SKILL.md")).split(sep).join("/");
+    let byteSize = 0;
+    const paths = new Set();
+    for (const file of manifest.files) {
+        if (typeof file.path !== "string" || !file.path || file.path.split("/").some((part) => part === ".." || part === "." || part === "")
+            || file.path.includes("\\") || isAbsolute(file.path) || paths.has(file.path)) {
+            throw new Error("Skill package resource path is invalid.");
+        }
+        paths.add(file.path);
+        const path = join(root, file.path);
+        assertPhysical(path);
+        const stat = lstatSync(path);
+        if (!stat.isFile() || stat.size !== file.size || stat.size > MAX_FILE_BYTES
+            || ((stat.mode & 0o111) !== 0) !== file.executable
+            || hash(readFileSync(path)) !== file.digest)
+            throw new Error(`Skill package resource changed: ${file.path}.`);
+        byteSize += file.size;
+    }
+    if (!paths.has(entrypoint) || byteSize !== ref.byteSize)
+        throw new Error("Skill package entrypoint or size mismatch.");
+    let observed = 0;
+    function checkInventory(directory, depth) {
+        if (depth > 32)
+            throw new Error("Skill package directory depth exceeds 32.");
+        for (const name of readdirSync(directory)) {
+            const path = join(directory, name);
+            const stat = lstatSync(path);
+            if (stat.isDirectory()) {
+                checkInventory(path, depth + 1);
+                continue;
+            }
+            if (!stat.isFile() || !paths.has(relative(root, path).split(sep).join("/"))) {
+                throw new Error("Skill package contains an unrecorded resource.");
+            }
+            observed++;
+        }
+    }
+    checkInventory(root, 0);
+    if (observed !== paths.size)
+        throw new Error("Skill package inventory changed.");
+    return manifest;
+}
+function assertPhysical(path) {
+    if (realpathSync(path) !== resolve(path)) {
+        throw new Error(`Skill package paths must not contain symlinks: ${path}.`);
+    }
+}

package/dist/context/taskContext.js

@@ -580,7 +580,8 @@ function freeze(value) {
 }
 function summarize(value) {
     const record = value;
-    return ["title", "objective", "question", "summary", "body", "status", "type"]
-        .flatMap((key) => typeof record[key] === "string" ? [`${key}: ${record[key]}`] : [])
+    return ["title", "scope", "expiresWhen", "version", "objective", "question", "summary", "body", "status", "type"]
+        .flatMap((key) => typeof record[key] === "string" || (key === "version" && typeof record[key] === "number")
+        ? [`${key}: ${record[key]}`] : [])
         .join("; ").slice(0, 400);
 }

package/dist/context/taskSearch.js

@@ -0,0 +1,127 @@
+import { usageError } from "../errors/cliError.js";
+import { TASK_SEARCH_KINDS } from "../storage/taskSearch.js";
+import { contextContentDigest } from "./contextSnapshot.js";
+import { taskCatalogScope } from "./taskCatalog.js";
+import { readTaskContextResource } from "./taskContext.js";
+const PAGE_BYTES = 32 * 1024;
+/** Human-readable field pages, using the same source authorization and version
+ * checks as Context. Offsets are Unicode code points, like search snippets. */
+export function readTaskSearchSource(store, taskId, input, environment = {}) {
+    if (!input.digest || !Number.isSafeInteger(input.offset) || input.offset < 0) {
+        throw usageError("A pinned digest and non-negative source offset are required.");
+    }
+    const fields = {
+        "task-brief": /^\$\.(objective|technicalApproach|currentFocus|leaderSummary|boundaries\[\d+\])$/,
+        "task-message": /^\$\.body$/,
+        "task-decision": /^\$\.(title|rationale|supersededReason)$/,
+        "run": /^\$\.result\.output$/,
+        "task": /^\$\.completionSummary$/
+    };
+    if (!fields[input.store]?.test(input.field))
+        throw usageError("Unsupported search source field.");
+    const original = readTaskContextResource(store, taskId, input, environment);
+    let value = original.value;
+    for (const part of input.field.slice(2).replace(/\[(\d+)\]/g, ".$1").split(".")) {
+        value = value && typeof value === "object" ? value[part] : undefined;
+    }
+    if (typeof value !== "string")
+        throw usageError("Search source text is unavailable.");
+    const points = Array.from(value);
+    if (input.offset > points.length)
+        throw usageError("Source offset is outside the text.");
+    const end = Math.min(input.offset + 4000, points.length);
+    return { taskId, ref: original.ref, field: input.field, authority: "reference-only",
+        content: points.slice(input.offset, end).join(""), offset: input.offset,
+        nextOffset: end < points.length ? end : null, totalCharacters: points.length,
+        offsetUnit: "unicode-code-points" };
+}
+export function parseTaskSearchOptions(args) {
+    const query = args[0]?.trim();
+    if (!query || query.length > 256 || query.includes("\0"))
+        throw usageError("Task search requires a query of 1..256 characters.");
+    const values = new Map();
+    for (let i = 1; i < args.length; i += 2) {
+        const key = args[i];
+        const value = args[i + 1];
+        if (!["--task", "--kind", "--limit", "--cursor"].includes(key) || values.has(key)
+            || value === undefined || value.startsWith("--"))
+            throw usageError("Task search expects query [--task <id>] [--kind <kind>] [--limit <1..100>] [--cursor <cursor>].");
+        values.set(key, value);
+    }
+    const limit = values.has("--limit") ? Number(values.get("--limit")) : 20;
+    const kind = values.get("--kind");
+    const taskId = values.get("--task");
+    if (!Number.isSafeInteger(limit) || limit < 1 || limit > 100)
+        throw usageError("Task search limit must be between 1 and 100.");
+    if (kind !== undefined && !TASK_SEARCH_KINDS.includes(kind))
+        throw usageError("Unknown Task search kind.");
+    if (taskId !== undefined && !/^task-[1-9]\d*$/.test(taskId))
+        throw usageError("Invalid Task search target.");
+    return { query, limit, ...(kind ? { kind } : {}), ...(taskId ? { taskId } : {}),
+        ...(values.has("--cursor") ? { cursor: values.get("--cursor") } : {}) };
+}
+export function searchTaskBodies(store, options, environment = {}) {
+    // Validate typed callers as well as CLI/HTTP callers through one parser.
+    const valid = parseTaskSearchOptions([options.query, "--limit", String(options.limit),
+        ...(options.taskId === undefined ? [] : ["--task", options.taskId]),
+        ...(options.kind === undefined ? [] : ["--kind", options.kind]),
+        ...(options.cursor === undefined ? [] : ["--cursor", options.cursor])]);
+    return store.readTransaction(reader => {
+        const callerTask = taskCatalogScope(reader, environment);
+        if (callerTask !== undefined && valid.taskId !== undefined && callerTask !== valid.taskId) {
+            throw usageError("Search target is outside the caller's Task.");
+        }
+        const taskId = callerTask ?? valid.taskId;
+        const scope = contextContentDigest({ taskId: taskId ?? null, query: valid.query, kind: valid.kind ?? null });
+        const after = valid.cursor === undefined ? undefined : decodeCursor(valid.cursor, scope);
+        const rows = reader.queryTaskSearch({ ...valid, taskId, after, limit: valid.limit + 1 });
+        const items = [];
+        let nextCursor = null;
+        const response = () => ({
+            query: valid.query, scope: { taskId: taskId ?? null, archived: "included" },
+            items, nextCursor, consistency: "current-per-page; repeat search after source changes",
+            matching: "literal substring; ASCII case-insensitive; Unicode otherwise exact",
+            limits: { maxItems: valid.limit, pageBytes: PAGE_BYTES, snippetCodePoints: 320 },
+            reuse: "References are evidence, not execution authority. An authorized reader may supply selected source text and its reference to a new Task; that Task plans and obtains its own authority."
+        });
+        for (const row of rows.slice(0, valid.limit)) {
+            // Reuse the exact Context permission and digest contract for each hit.
+            const original = readTaskContextResource(reader, row.taskId, { store: row.store, refId: row.refId }, environment);
+            const item = { taskId: row.taskId, kind: row.kind, field: row.field, snippet: row.snippet,
+                offset: row.offset, ref: original.ref, authority: "reference-only" };
+            const previous = nextCursor;
+            nextCursor = encodeCursor(scope, row);
+            items.push(item);
+            if (Buffer.byteLength(JSON.stringify({ ok: true, data: response() })) > PAGE_BYTES) {
+                items.pop();
+                nextCursor = previous;
+                break;
+            }
+        }
+        if (rows.length === items.length)
+            nextCursor = null;
+        if (rows.length && !items.length)
+            throw usageError("Task search identity exceeds its page budget.");
+        return response();
+    });
+}
+function encodeCursor(scope, row) {
+    return Buffer.from(JSON.stringify({ version: 1, scope, after: {
+            taskId: row.taskId, kind: row.kind, refId: row.refId, field: row.field
+        } })).toString("base64url");
+}
+function decodeCursor(raw, scope) {
+    try {
+        if (raw.length > 4096 || !/^[A-Za-z0-9_-]+$/.test(raw))
+            throw new Error();
+        const value = JSON.parse(Buffer.from(raw, "base64url").toString("utf8"));
+        if (value.version !== 1 || value.scope !== scope || !value.after
+            || !["taskId", "kind", "refId", "field"].every(key => typeof value.after[key] === "string"
+                && value.after[key].length > 0 && value.after[key].length <= 256))
+            throw new Error();
+        return value.after;
+    }
+    catch {
+        throw usageError("Invalid Task search cursor or cursor belongs to another scope/query.");
+    }
+}

package/dist/controlPlaneCli.js

@@ -36,7 +36,7 @@ import { runConfigOverview } from "./commands/configOverview.js";
 import { parseControllerCleanupOptions, parseControllerRuntimeSnapshot, parseControllerStatusOptions, renderControllerResourceStatus, renderRuntimeIdentitySection, runInteractiveControllerCleanup, summarizeDurablePhysicalMismatch } from "./commands/controllerCommands.js";
 import { runDurableJobCommand } from "./commands/durableJobCommands.js";
 import { parseExecutionAuditOptions, runExecutionAuditCommand } from "./commands/executionAuditCommands.js";
-import { runGlobalRoleCommand } from "./commands/globalRoleCommands.js";
+import { runGlobalRoleCommand, previewGlobalRoleAgentConfigurationMutation } from "./commands/globalRoleCommands.js";
 import { runJobCommand } from "./commands/jobCommands.js";
 import { applyOperatorSessionControl, runOperatorCommand } from "./commands/operatorCommands.js";
 import { previewProfileAgentConfigurationMutation, runProfileCommand } from "./commands/profileCommands.js";
@@ -110,7 +110,7 @@ import { inspectStorageSchema } from "./storage/storageSchema.js";
 import { resolveYuiHome } from "./storage/taskStore.js";
 import { renderArchiveDiagnostics, taskArchiveDiagnostics } from "./task/archiveDiagnostics.js";
 import { inspectTaskArchive, renderTaskArchivePreflight } from "./task/archivePreflight.js";
-import { assertTaskRemoteDeliveryIntegrated, createTaskRemoteDeliveryProof } from "./task/remoteDeliveryService.js";
+import { archiveOrdinaryTask } from "./task/ordinaryArchive.js";
 import { resolveTaskRecordReference } from "./task/taskRecordReference.js";
 import { openSchedulerTelemetry } from "./telemetry/telemetryWiring.js";
 import { NodeCommandExecutor } from "./tmux/commandExecutor.js";
@@ -704,7 +704,8 @@ export async function main() {
             const domain = resolved[1];
             const roleOptions = {
                 yuiHome: home,
-                env: process.env
+                env: process.env,
+                ...(validateAgentConfiguration === undefined ? {} : { validateAgentConfiguration })
             };
             if (domain === "show") {
                 const result = runConfigOverview(resolved.slice(2), store, process.env, roleOptions);
@@ -1039,7 +1040,7 @@ export async function main() {
                 const action = resolved[2];
                 const taskId = resolved[3];
                 const usage = "Usage: yui task artifact list <task> | read <task> <relative-path> [<commit>] | "
-                    + "save <task> <relative-path> <content> [--message <text>] [--expected-head <commit>]";
+                    + "save <task> <relative-path> <content> [--encoding utf8|base64] [--message <text>] [--expected-head <commit>]";
                 if (taskId === undefined || action === undefined || !["list", "read", "save"].includes(action)) {
                     throw usageError(usage);
                 }
@@ -1073,6 +1074,7 @@ export async function main() {
                     const rest = resolved.slice(6);
                     let message;
                     let expectedHead;
+                    let encoding;
                     for (let index = 0; index < rest.length; index += 1) {
                         const value = rest[index + 1];
                         if (rest[index] === "--message" && value !== undefined) {
@@ -1085,10 +1087,15 @@ export async function main() {
                             index += 1;
                             continue;
                         }
+                        if (rest[index] === "--encoding" && (value === "utf8" || value === "base64")) {
+                            encoding = value;
+                            index += 1;
+                            continue;
+                        }
                         throw usageError(usage);
                     }
                     data = await saveArtifactCapability(home, taskId, {
-                        relativePath, content,
+                        relativePath, content, ...(encoding === undefined ? {} : { encoding }),
                         ...(message === undefined ? {} : { message }),
                         ...(expectedHead === undefined ? {} : { expectedHead })
                     });
@@ -1320,8 +1327,6 @@ export async function main() {
                 });
                 return;
             }
-            let archiveRemoteDeliveryProof;
-            let archiveTaskReviewCandidate;
             if (resolved[1] === "archive") {
                 const request = parseTaskArchiveArguments(resolved.slice(2));
                 if (request.sourceMessage !== undefined) {
@@ -1359,15 +1364,17 @@ export async function main() {
                     emit(`Archived task ${taskId}\n${renderArchiveDiagnostics(archive)}`, false, { task: current, ...archive });
                     return;
                 }
+                if (disposition === "integrated") {
+                    const result = await archiveOrdinaryTask(workspaceCoordinator, taskId, {
+                        runtime, environment: process.env, yuiHome: home
+                    });
+                    emit(`Archived task ${taskId}\n${renderArchiveDiagnostics(result)}`, false, result);
+                    return;
+                }
                 {
-                    if (disposition === "integrated") {
-                        archiveTaskReviewCandidate = task.status === "cancelled" ? await actualTaskReviewCandidateForTaskCommand(resolved, store, workspacePreparer, process.env) : undefined;
-                        archiveRemoteDeliveryProof = createTaskRemoteDeliveryProof(store, task, archiveTaskReviewCandidate ?? null);
-                        assertTaskRemoteDeliveryIntegrated(archiveRemoteDeliveryProof.delivery);
-                    }
                     await workspaceCoordinator.prepareTaskForArchive(task.id);
                     runTaskCommand(resolved.slice(1), store, {
-                        runtime, environment: process.env, yuiHome: home, archiveRemoteDeliveryProof
+                        runtime, environment: process.env, yuiHome: home
                     });
                     await workspaceCoordinator.cleanupArchivedTask(task.id, disposition);
                     const current = store.getTask(task.id);
@@ -1527,9 +1534,7 @@ export async function main() {
                     laneDispatchProjectPaths = preparedLanes.projectPaths;
                 }
                 const candidateSnapshots = await candidateSnapshotForTaskCommand(resolved, store, workspacePreparer, process.env, taskFinalReviewContract);
-                const actualTaskReviewCandidate = archiveRemoteDeliveryProof === undefined
-                    ? await actualTaskReviewCandidateForTaskCommand(resolved, store, workspacePreparer, process.env)
-                    : archiveTaskReviewCandidate;
+                const actualTaskReviewCandidate = await actualTaskReviewCandidateForTaskCommand(resolved, store, workspacePreparer, process.env);
                 const deltaRecheckPreflight = await deltaRecheckPreflightForTaskCommand(resolved.slice(1), store, actualTaskReviewCandidate);
                 // Read-only Host evidence for Session inspect and Role status/list. The command stays
                 // synchronous over persisted state; this is the live reading it prints
@@ -1569,9 +1574,6 @@ export async function main() {
                     ...(actualTaskReviewCandidate === undefined
                         ? {}
                         : { actualTaskReviewCandidate }),
-                    ...(archiveRemoteDeliveryProof === undefined
-                        ? {}
-                        : { archiveRemoteDeliveryProof }),
                     ...(deltaRecheckPreflight === undefined
                         ? {}
                         : { deltaRecheckPreflight }),
@@ -2721,7 +2723,10 @@ function selectionPorts(store, catalogs) {
 }
 async function preflightAgentConfigurationMutation(commandArgs, store, catalogs) {
     const mutation = profileAgentConfigurationMutation(commandArgs, store)
-        ?? taskRoleAgentConfigurationMutation(commandArgs, store);
+        ?? taskRoleAgentConfigurationMutation(commandArgs, store)
+        ?? (commandArgs[0] === "config" && commandArgs[1] === "role"
+            ? previewGlobalRoleAgentConfigurationMutation(commandArgs.slice(2), store, { yuiHome: store.rootDirectory() })
+            : undefined);
     if (mutation === undefined) {
         await warmConfigurationMutationCatalog(commandArgs, store, catalogs);
         return undefined;