@zq-silk/yui 2.3.0 → 2.5.0

package/README.md

@@ -46,7 +46,7 @@ For the self-built coding Agent (without a Controller or Yui Home), see
 [`yui agent`](docs/native-agent.md). Its explicit configuration and product state
 are separate from the orchestration setup below.
 
-You need Linux x64 (glibc) or macOS (x64 or Apple Silicon), Git, tmux, and
+You need Linux x64 (glibc) or macOS (x64 or Apple Silicon), Git 2.29.0 or newer, tmux, and
 Node.js `^20.17.0`, `^22.9.0`, `^24.0.0` or `^26.0.0`. On macOS install tmux with
 `brew install tmux`. For the simplest setup, have Codex CLI or Claude Code CLI
 installed and ready to use with your own account. Yui coordinates those
@@ -162,6 +162,20 @@ The task list remains at the left, task details occupy the primary reading area,
 and recorded Task messages live in a secondary discussion pane. You can resize,
 swap or hide that pane; on narrow screens it opens over the detail. Native Sessions
 remain separate from recorded Task messages.
+For a current controlled Codex Operator or Task Leader, **Conversation** and
+**Terminal** are two views of the same Thread. Terminal opens the native Codex
+TUI through the existing Host; it does not start another Agent. Only one browser
+terminal holds the writer at a time. Returning to Conversation or closing the
+page detaches that browser, without stopping the Agent. Conversation drafts and
+the browser's default-view preference survive switching. Native questions and
+approvals answer the original Codex request; Leader Task questions remain on
+the separate InputRequest channel. The default-view preference is shared with
+Settings; saving it does not switch the current view or Session.
+MCP forms and URL confirmations can be completed in Terminal or declined in
+Conversation. Native additional input is saved as a user Message with its exact
+steer receipt before submission.
+Attachments and native configuration changes
+are not supported by this managed text-input surface.
 The detail has four tabs: Overview (user input, progress and key Decisions),
 Delivery (WorkItems, Reviews, Integration and remote delivery, read on demand),
 Runtime (Roles, native Session activity, open execution and usage) and Records

package/dist/artifacts/artifactCapability.js

@@ -2,6 +2,7 @@ import { openTaskArtifactRepository } from "./taskArtifactRepository.js";
 import { saveArtifactFile } from "./gitArtifactRef.js";
 import { requireCommitId } from "./managedGit.js";
 import { safeRelativeArtifactPath } from "./artifactPaths.js";
+import { isRasterArtifact, MAX_IMAGE_BYTES, rasterMetadata } from "./imageMetadata.js";
 /**
  * Capability-shaped adapter over the per-Task local Git artifact repository.
  *
@@ -13,11 +14,8 @@ import { safeRelativeArtifactPath } from "./artifactPaths.js";
  * self-certifying commit-pinned reference (`taskId + commit + relativePath`),
  * which is the identity used for frozen Candidate/Review/completion evidence.
  *
- * Content is handled as UTF-8 text with the same 8 MiB cap as the former
- * immutable text artifact. Binary artifacts, high-frequency runtime data and
- * very large files are out of scope for this first version by contract (§3.5)
- * and are rejected or referenced through their existing resource boundary, not
- * carried here.
+ * Text is UTF-8 (8 MiB). Static raster images use explicit base64 (4 MiB
+ * decoded), with the same immutable repository and image limits as Web.
  */
 /** Text cap for a single artifact file, mirroring the former immutable-artifact limit. */
 const MAX_ARTIFACT_TEXT_BYTES = 8 * 1024 * 1024;
@@ -35,7 +33,23 @@ function requireTextContent(content) {
  * commit exactly that path, and return the resulting commit-pinned reference.
  */
 export async function saveArtifactCapability(home, taskId, input) {
-    const bytes = requireTextContent(input.content);
+    if (input.encoding !== undefined && input.encoding !== "utf8" && input.encoding !== "base64") {
+        throw new Error("Artifact encoding must be utf8 or base64.");
+    }
+    let bytes;
+    if (input.encoding === "base64") {
+        if (!isRasterArtifact(input.relativePath) || typeof input.content !== "string"
+            || input.content.length > Math.ceil(MAX_IMAGE_BYTES / 3) * 4) {
+            throw new Error("Base64 artifacts require a static PNG, JPEG or WebP path and at most 4 MiB.");
+        }
+        bytes = Buffer.from(input.content, "base64");
+        if (bytes.toString("base64") !== input.content)
+            throw new Error("Artifact image must use canonical base64.");
+        rasterMetadata(bytes);
+    }
+    else {
+        bytes = requireTextContent(input.content);
+    }
     return saveArtifactFile(home, taskId, {
         relativePath: input.relativePath,
         bytes,
@@ -45,8 +59,8 @@ export async function saveArtifactCapability(home, taskId, input) {
 }
 /**
  * `artifact.read`: read `relativePath` at HEAD, or at a pinned `commit` for
- * frozen evidence. Returns the bytes as UTF-8 text plus the resolved commit and
- * digest, so a caller can record or verify the exact reference.
+ * frozen evidence. Images return explicit base64 and bounded raster metadata;
+ * text returns UTF-8. Both carry the resolved commit and exact digest.
  */
 export async function readArtifactCapability(home, taskId, input) {
     const repo = openTaskArtifactRepository(home, taskId);
@@ -54,12 +68,27 @@ export async function readArtifactCapability(home, taskId, input) {
         throw new Error(`Artifact repository is unavailable for ${taskId}.`);
     const safeRelative = safeRelativeArtifactPath(input.relativePath);
     const content = await repo.read(safeRelative, input.commit === undefined ? undefined : requireCommitId(input.commit));
+    const image = isRasterArtifact(safeRelative) ? rasterMetadata(content.bytes) : null;
+    let text;
+    if (image)
+        text = content.bytes.toString("base64");
+    else {
+        try {
+            text = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(content.bytes);
+        }
+        catch {
+            throw new Error("Artifact is not readable UTF-8 text or a supported raster image.");
+        }
+        if (text.includes("\0"))
+            throw new Error("Binary artifact is not supported as text.");
+    }
     return {
         taskId,
         relativePath: content.relativePath,
         commit: content.commit,
-        content: content.bytes.toString("utf8"),
-        digest: content.digest
+        content: text,
+        digest: content.digest,
+        ...(image ? { encoding: "base64", ...image } : {})
     };
 }
 /**

package/dist/artifacts/imageMetadata.js

@@ -0,0 +1,120 @@
+import { extname } from "node:path";
+export const MAX_IMAGE_BYTES = 4 * 1024 * 1024;
+export function isRasterArtifact(path) {
+    return [".png", ".jpg", ".jpeg", ".webp"].includes(extname(path).toLowerCase());
+}
+/** Bounded raster metadata inspection, not a decoder. The viewer also reports
+ * browser decode errors. Never admit SVG/HTML or trust a caller's MIME type. */
+export function rasterMetadata(bytes) {
+    if (bytes.length > MAX_IMAGE_BYTES)
+        throw new Error("Image exceeds 4 MiB.");
+    let mime, width = 0, height = 0;
+    if (bytes.length >= 33 && bytes.subarray(0, 8).equals(Buffer.from([137, 80, 78, 71, 13, 10, 26, 10]))
+        && bytes.toString("ascii", 12, 16) === "IHDR" && bytes.readUInt32BE(8) === 13) {
+        mime = "image/png";
+        width = bytes.readUInt32BE(16);
+        height = bytes.readUInt32BE(20);
+        let end = false;
+        for (let offset = 8; offset + 12 <= bytes.length;) {
+            const length = bytes.readUInt32BE(offset);
+            const type = bytes.toString("ascii", offset + 4, offset + 8);
+            if (offset + length + 12 > bytes.length)
+                throw new Error("Truncated PNG image.");
+            if (type === "acTL")
+                throw new Error("Animated images are unsupported; save a static frame.");
+            offset += length + 12;
+            if (type === "IEND") {
+                end = length === 0 && offset === bytes.length;
+                break;
+            }
+        }
+        if (!end)
+            throw new Error("Incomplete PNG image.");
+    }
+    else if (bytes.length >= 4 && bytes[0] === 255 && bytes[1] === 216) {
+        mime = "image/jpeg";
+        let offset = 2;
+        while (offset + 4 <= bytes.length) {
+            if (bytes[offset++] !== 255)
+                throw new Error("Invalid JPEG image marker.");
+            while (bytes[offset] === 255)
+                offset++;
+            const marker = bytes[offset++];
+            if (marker === 0xda || marker === 0xd9)
+                break;
+            if (offset + 2 > bytes.length)
+                throw new Error("Truncated JPEG image.");
+            const length = bytes.readUInt16BE(offset);
+            if (length < 2 || offset + length > bytes.length)
+                throw new Error("Truncated JPEG image.");
+            if ([0xc0, 0xc1, 0xc2].includes(marker)) {
+                if (length < 8)
+                    throw new Error("Invalid JPEG image frame.");
+                if (width || height)
+                    throw new Error("Multiple JPEG image frames are unsupported.");
+                height = bytes.readUInt16BE(offset + 3);
+                width = bytes.readUInt16BE(offset + 5);
+            }
+            offset += length;
+        }
+        if (bytes[bytes.length - 2] !== 255 || bytes[bytes.length - 1] !== 217)
+            throw new Error("Incomplete JPEG image.");
+    }
+    else if (bytes.length >= 30 && bytes.toString("ascii", 0, 4) === "RIFF"
+        && bytes.toString("ascii", 8, 12) === "WEBP" && bytes.readUInt32LE(4) + 8 === bytes.length) {
+        mime = "image/webp";
+        const kind = bytes.toString("ascii", 12, 16);
+        if (kind === "VP8X") {
+            if (bytes[20] & 2)
+                throw new Error("Animated images are unsupported; save a static frame.");
+            width = 1 + bytes.readUIntLE(24, 3);
+            height = 1 + bytes.readUIntLE(27, 3);
+        }
+        else if (kind === "VP8 " && bytes.subarray(23, 26).equals(Buffer.from([157, 1, 42]))) {
+            width = bytes.readUInt16LE(26) & 0x3fff;
+            height = bytes.readUInt16LE(28) & 0x3fff;
+        }
+        else if (kind === "VP8L" && bytes[20] === 47) {
+            width = 1 + (bytes.readUInt32LE(21) & 0x3fff);
+            height = 1 + ((bytes.readUInt32LE(21) >>> 14) & 0x3fff);
+        }
+        let frames = 0;
+        for (let offset = 12; offset < bytes.length;) {
+            if (offset + 8 > bytes.length)
+                throw new Error("Truncated WebP image.");
+            const length = bytes.readUInt32LE(offset + 4);
+            const type = bytes.toString("ascii", offset, offset + 4);
+            if (type === "ANIM" || type === "ANMF")
+                throw new Error("Animated images are unsupported; save a static frame.");
+            if (offset + 8 + length > bytes.length)
+                throw new Error("Truncated WebP image.");
+            if (type === "VP8 " || type === "VP8L") {
+                let frameWidth = 0, frameHeight = 0;
+                if (type === "VP8 " && length >= 10
+                    && bytes.subarray(offset + 11, offset + 14).equals(Buffer.from([157, 1, 42]))) {
+                    frameWidth = bytes.readUInt16LE(offset + 14) & 0x3fff;
+                    frameHeight = bytes.readUInt16LE(offset + 16) & 0x3fff;
+                }
+                else if (type === "VP8L" && length >= 5 && bytes[offset + 8] === 47) {
+                    frameWidth = 1 + (bytes.readUInt32LE(offset + 9) & 0x3fff);
+                    frameHeight = 1 + ((bytes.readUInt32LE(offset + 9) >>> 14) & 0x3fff);
+                }
+                if (frameWidth !== width || frameHeight !== height || ++frames > 1) {
+                    throw new Error("Invalid WebP image frame dimensions.");
+                }
+            }
+            offset += 8 + length + (length % 2);
+            if (offset > bytes.length)
+                throw new Error("Truncated WebP image.");
+        }
+        if (frames !== 1)
+            throw new Error("WebP image has no readable frame.");
+    }
+    else {
+        throw new Error("Unsupported or damaged image. Use static PNG, JPEG or WebP (not SVG/GIF).");
+    }
+    if (!width || !height || width > 8192 || height > 8192 || width * height > 16_000_000) {
+        throw new Error("Unsupported image dimensions: maximum 8192 per side and 16 million pixels.");
+    }
+    return { mime, width, height };
+}

package/dist/artifacts/managedGit.js

@@ -1,5 +1,6 @@
 import { execFile } from "node:child_process";
 import { promisify } from "node:util";
+import { supportedGit } from "../repository/gitCompatibility.js";
 const executeFile = promisify(execFile);
 /**
  * Hardened, isolated Git runner for per-Task artifact repositories.
@@ -44,7 +45,7 @@ const HARDENING_FLAGS = Object.freeze([
     "-c", "protocol.file.allow=never",
     // Hooks / filters / external programs — no committed script may execute.
     "-c", `core.hooksPath=${NULL_DEVICE}`,
-    "-c", "core.fsmonitor=false",
+    "-c", "core.fsmonitor=",
     "-c", "core.pager=cat",
     "-c", "core.editor=false",
     // Signing — never shell out to a signing program.
@@ -77,8 +78,9 @@ function managedGitEnvironment() {
         PATH: process.env.PATH ?? "/usr/bin:/bin",
         LANG: "C.UTF-8",
         LC_ALL: "C.UTF-8",
-        // A neutral HOME keeps any accidental lookup inside a controlled area; config
-        // lookups are already redirected to the null device below.
+        // Older supported Git does not recognize GIT_CONFIG_GLOBAL/SYSTEM.
+        // A neutral HOME and absent XDG_CONFIG_HOME also block its global lookup;
+        // GIT_CONFIG_NOSYSTEM is understood by all supported versions.
         HOME: process.platform === "win32" ? (process.env.USERPROFILE ?? "") : "/nonexistent",
         GIT_CONFIG_NOSYSTEM: "1",
         GIT_CONFIG_GLOBAL: NULL_DEVICE,
@@ -122,8 +124,9 @@ function assertSafeArguments(args) {
  */
 async function spawnManagedGit(repoPath, args, options) {
     assertSafeArguments(args);
+    const program = supportedGit();
     try {
-        const result = await executeFile("git", [...HARDENING_FLAGS, "-C", repoPath, ...args], {
+        const result = await executeFile(program.path, [...HARDENING_FLAGS, "-C", repoPath, ...args], {
             encoding: "buffer",
             env: managedGitEnvironment(),
             maxBuffer: options?.maxBuffer ?? 16 * 1024 * 1024,

package/dist/artifacts/taskArtifactRepository.js

@@ -2,6 +2,7 @@ import { createHash } from "node:crypto";
 import { existsSync } from "node:fs";
 import { mkdir, writeFile } from "node:fs/promises";
 import { dirname, join } from "node:path";
+import { supportedGit } from "../repository/gitCompatibility.js";
 import { acquireArtifactCommitLock } from "./artifactCommitLock.js";
 import { resolveContainedArtifactPath, safeRelativeArtifactPath, taskArtifactRepoPath } from "./artifactPaths.js";
 import { ManagedGitError, externalProgramConfigViolations, managedGit, managedGitBuffer, managedGitSucceeds, requireCommitId } from "./managedGit.js";
@@ -96,6 +97,7 @@ export function openTaskArtifactRepository(home, taskId) {
         return currentHead(repoPath);
     };
     const ensure = async () => {
+        supportedGit();
         if (exists()) {
             await assertNoRemote(taskId, repoPath);
             return;
@@ -189,6 +191,10 @@ export function openTaskArtifactRepository(home, taskId) {
         if (objectType !== "blob") {
             throw new Error(`Artifact ${safeRelative} at ${pinned} is not a file (${objectType}).`);
         }
+        const size = Number((await managedGit(repoPath, ["cat-file", "-s", objectSpec])).trim());
+        if (!Number.isSafeInteger(size) || size > MAX_ARTIFACT_BYTES) {
+            throw new Error(`Artifact ${safeRelative} exceeds the ${MAX_ARTIFACT_BYTES}-byte limit.`);
+        }
         const bytes = await managedGitBuffer(repoPath, ["cat-file", "blob", objectSpec], {
             maxBuffer: MAX_ARTIFACT_BYTES + 4096
         }).catch((error) => {

package/dist/cli/commandCatalog.js

@@ -387,7 +387,14 @@ const taskChildren = [
         usage: "yui task list [--all] [--status <status>] [--project <id>] [--search <text>] [--attention <category>] [--limit <1..100>] [--cursor <cursor>]",
         options: ["--all", "--status", "--project", "--search", "--attention", "--limit", "--cursor"]
     },
+    {
+        name: "search", discovery: { surface: "public", audiences: ["public", "operator", "leader"] },
+        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: "artifact", discovery: { surface: "managed", audiences: ["operator", "leader"] },
         summary: "Save Task files in local Git and read current or commit-pinned content.",
@@ -395,7 +402,7 @@ const taskChildren = [
         children: [
             { name: "list", discovery: { surface: "public", audiences: ["public", "operator", "leader", "assignment"] }, summary: "List saved Task artifacts.", usage: "yui task artifact list <task>" },
             { name: "read", discovery: { surface: "public", audiences: ["public", "operator", "leader", "assignment"] }, summary: "Read a file at HEAD or an exact commit.", usage: "yui task artifact read <task> <relative-path> [<commit>]" },
-            { name: "save", discovery: { surface: "managed", audiences: ["operator", "leader"] }, summary: "Save and locally commit one file.", usage: "yui task artifact save <task> <relative-path> <content> [--message <text>] [--expected-head <commit>]", options: ["--message", "--expected-head"] }
+            { name: "save", discovery: { surface: "managed", audiences: ["operator", "leader"] }, summary: "Save UTF-8 text or a base64 static PNG/JPEG/WebP image and locally commit one file.", usage: "yui task artifact save <task> <relative-path> <content> [--encoding utf8|base64] [--message <text>] [--expected-head <commit>]", options: ["--encoding", "--message", "--expected-head"], optionValues: { "--encoding": ["utf8", "base64"] } }
         ]
     },
     {
@@ -1089,7 +1096,7 @@ const taskChildren = [
         sections: [{ id: "manage", title: "Commands", entries: ["list", "show", "retry", "resolve"] }],
         children: [
             { name: "list", discovery: { surface: "managed", audiences: ["operator", "leader"] }, summary: "List recorded Leader wakes.", usage: "yui task wake list <task> [--limit <1..100>] [--cursor <cursor>]", options: ["--limit", "--cursor"] },
-            { name: "show", discovery: { surface: "managed", audiences: ["operator", "leader"] }, summary: "Show a fixed wake window and exact detail reads.", usage: "yui task wake show <task> <wake> [--cursor <cursor>]", options: ["--cursor"] },
+            { name: "show", discovery: { surface: "managed", audiences: ["operator", "leader"] }, summary: "Show fixed wake inputs/results; expand diagnostics with --history.", usage: "yui task wake show <task> <wake> [--history] [--cursor <cursor>]", options: ["--history", "--cursor"] },
             { name: "retry", discovery: { surface: "managed", audiences: ["operator", "leader"] }, summary: "Retry a rejected notification after correcting its cause; preserve original input.",
                 usage: "yui task wake retry <task> <wake> --reason <correction>", options: ["--reason"] },
             { name: "resolve", discovery: { surface: "managed", audiences: ["operator", "leader"] }, summary: "Release an unknown notification claim after explicit quiescence evidence, without replay.",
@@ -1514,13 +1521,14 @@ export const ROOT_COMMAND = buildNode({
                         {
                             name: "list", discovery: { surface: "public", audiences: ["public", "operator", "leader"] },
                             summary: "List Project knowledge.",
-                            usage: "yui project knowledge list <project> [--all]",
-                            options: ["--all"]
+                            usage: "yui project knowledge list <project> [--all] [--limit <1..100>] [--cursor <cursor>]",
+                            options: ["--all", "--limit", "--cursor"]
                         },
                         {
                             name: "show", discovery: { surface: "public", audiences: ["public", "operator", "leader"] },
                             summary: "Read one Project knowledge entry.",
-                            usage: "yui project knowledge show <project> <knowledge>"
+                            usage: "yui project knowledge show <project> <knowledge> [--cursor <cursor>]",
+                            options: ["--cursor"]
                         },
                         {
                             name: "propose", discovery: { surface: "public", audiences: ["public", "operator", "leader"] },
@@ -1538,13 +1546,14 @@ export const ROOT_COMMAND = buildNode({
                                 {
                                     name: "list", discovery: { surface: "public", audiences: ["public", "operator", "leader"] },
                                     summary: "List Knowledge promotion proposals (pending by default).",
-                                    usage: "yui project knowledge proposals list <project> [--status pending|accepted|rejected] [--all]",
-                                    options: ["--status", "--all"]
+                                    usage: "yui project knowledge proposals list <project> [--status pending|accepted|rejected] [--all] [--limit <1..100>] [--cursor <cursor>]",
+                                    options: ["--status", "--all", "--limit", "--cursor"]
                                 },
                                 {
                                     name: "show", discovery: { surface: "public", audiences: ["public", "operator", "leader"] },
                                     summary: "Show one Knowledge promotion proposal.",
-                                    usage: "yui project knowledge proposals show <project> <proposal>"
+                                    usage: "yui project knowledge proposals show <project> <proposal> [--cursor <cursor>]",
+                                    options: ["--cursor"]
                                 }
                             ]
                         },
@@ -1586,7 +1595,7 @@ export const ROOT_COMMAND = buildNode({
             sections: [
                 { id: "lifecycle", title: "Lifecycle", entries: ["create", "project", "base", "update", "activate", "activation", "execution", "complete", "cancel", "reopen", "retire", "list", "show", "context", "next-action", "remote-delivery", "archive-preflight", "archive", "archive-cleanup", "replace", "reconcile", "upstream", "artifact"] },
                 { id: "collaboration", title: "Collaboration", entries: ["message", "input", "grant", "workflow", "publication", "work", "run", "review", "integration", "role", "overlap", "change-set"] },
-                { id: "knowledge", title: "Task Knowledge", entries: ["brief", "decision", "milestone", "event", "continuation", "wake"] }
+                { id: "knowledge", title: "Task Knowledge", entries: ["search", "brief", "decision", "milestone", "event", "continuation", "wake", "usage"] }
             ],
             children: taskChildren
         },

package/dist/cli/invocationAuthority.js

@@ -35,7 +35,7 @@ export function assertTaskInvocationScope(args, env) {
     if (args[0] === "jobs" || (args[0] === "task" && ["create", "overlap"].includes(args[1] ?? ""))) {
         throw usageError("This global operation is outside the caller's Task; use its scoped Context.");
     }
-    if (args[0] !== "task" || args[1] === "list")
+    if (args[0] !== "task" || ["list", "search"].includes(args[1] ?? ""))
         return;
     const diagnostic = taskDiagnosticTarget(args);
     if (diagnostic !== undefined) {

package/dist/commands/executionAuditCommands.js

@@ -251,6 +251,11 @@ export function renderExecutionAudit(report, width = defaultTableWidth()) {
         lines.push("", "Observed usage — Task lifetime, observed sources only (audit time window not applied):");
         for (const usage of report.usage.data) {
             lines.push(`  ${usage.taskId}: tokens=${formatUsageMetric(usage.tokens)}; tools=${formatUsageMetric(usage.toolCalls)}; elapsed=${formatUsageMetric(usage.elapsedSeconds, "s")}; native execution sum=${formatUsageMetric(usage.executionSeconds, "s")}`);
+            for (const kind of ["actual", "estimated"]) {
+                const costs = usage.costs[kind];
+                lines.push(`    ${kind} cost: ${costs.amounts.length === 0 ? `unknown (${costs.reasons.join(", ")})`
+                    : costs.amounts.map(amount => `${formatUsageMetric(amount)} ${amount.currency}`).join("; ")} (observed sources only, not a bill)`);
+            }
         }
     }
     else {

package/dist/commands/globalRoleCommands.js

@@ -16,8 +16,38 @@ import { isSystemRoleName, SYSTEM_ROLE_NAMES, systemRoleDescription } from "../r
 import { hasAgentConfigOptions, hasNoRoleMutation, parseRoleOptions, patchRoleAgentBinding, roleOptionSpecs, roleProfileFrom, roleProfilePatch } from "./roleConfiguration.js";
 import { hasRoleLaunchContextOptions, validateConfiguredRoleSkills } from "./roleSkillValidation.js";
 import { assertLiveRoleSessionAcknowledged, assertRoleRuntimeMutationAllowed, LIVE_SESSION_ACKNOWLEDGEMENT_OPTION } from "./roleRuntimeGuard.js";
+/** Preview the complete binding, not just the fields supplied by the caller. */
+export function previewGlobalRoleAgentConfigurationMutation(args, store, options = {}) {
+    const [command, rawName, ...tail] = args;
+    if (command !== "add" && command !== "update")
+        return undefined;
+    const name = roleName(rawName);
+    const parsed = parseRoleOptions(tail, roleOptionSpecs({
+        update: command === "update", includeAgent: true, includeWorkspace: true
+    }));
+    if (command === "update" && !hasAgentConfigOptions(parsed))
+        return undefined;
+    const role = command === "update" ? requireRole(name, store) : undefined;
+    const agentId = command === "add"
+        ? required(parsed.one("--agent"), "--agent")
+        : parsed.one("--agent")?.trim() || role.activeAgentId;
+    const agent = requireAgent(agentId, store);
+    const binding = patchRoleAgentBinding(role?.agentBindings[agentId] ?? createRoleAgentBinding(definition(agent)), parsed);
+    return {
+        agentId, config: binding.config,
+        cwd: trimmed(parsed.one("--workspace")) ?? role?.workspace
+            ?? (options.yuiHome !== undefined ? managedGlobalRoleWorkspace(options.yuiHome)
+                : store.getConfig().defaultWorkspace ?? process.cwd())
+    };
+}
 export function applyGlobalInputControl(name, input, store, options = {}) {
     assertGlobalInputAuthority(store, options, name);
+    if (input.expectedSessionId !== undefined) {
+        const set = store.getGlobalRoleSessionSet(name);
+        if (set?.sessions[set.activeAgentId]?.nativeSessionId !== input.expectedSessionId) {
+            throw usageError("Selected native Session changed; refresh before sending.");
+        }
+    }
     return input.action === "interrupt"
         ? interruptGlobalInput(name, input, store)
         : messageGlobalInput(name, input, store, options);
@@ -153,6 +183,7 @@ function roleContext(args, store, options) {
         // Historical interrupt receipts are available through Session inspection;
         // only this Turn's exact identity is required at entry.
         sessionManifestPath: environment.YUI_SESSION_MANIFEST,
+        skillPackages: session?.effective.skillPackages ?? null,
         cliCommand: "yui"
     });
     const data = boundedDocument(context, `global:${name}/context`, parsed.cursor);
@@ -206,6 +237,7 @@ function addRole(args, store, options) {
                 ? managedGlobalRoleWorkspace(options.yuiHome)
                 : tx.getConfig().defaultWorkspace ?? process.cwd());
         const binding = patchRoleAgentBinding(createRoleAgentBinding(definition(agent)), parsed);
+        options.validateAgentConfiguration?.({ agentId, config: binding.config, cwd: workspace });
         const profile = roleProfileFrom(parsed);
         validateConfiguredRoleSkills(options.yuiHome, profile.skills ?? []);
         const role = createGlobalRole(name, [binding], agent.id, workspace, now, profile);
@@ -295,7 +327,11 @@ function updateRole(args, store, options) {
             const agentId = parsed.one("--agent")?.trim() || role.activeAgentId;
             const agent = requireAgent(agentId, tx);
             const binding = role.agentBindings[agentId] ?? createRoleAgentBinding(definition(agent));
-            bindings = { ...role.agentBindings, [agentId]: patchRoleAgentBinding(binding, parsed) };
+            const patched = patchRoleAgentBinding(binding, parsed);
+            options.validateAgentConfiguration?.({
+                agentId, config: patched.config, cwd: workspace ?? role.workspace
+            });
+            bindings = { ...role.agentBindings, [agentId]: patched };
         }
         const updated = updateGlobalRole(role, {
             ...(workspace === undefined ? {} : { workspace }),
@@ -537,7 +573,8 @@ export function sendGlobalRoleMessageCommand(store, roleName, body, author, inpu
         const original = existing.inputControl ?? existing.interruptThen?.reusedInput;
         if (original?.action !== inputControl.action
             || existing.body !== body
-            || original.expectedTarget !== inputControl.expectedTarget) {
+            || original.expectedTarget !== inputControl.expectedTarget
+            || original.expectedSessionId !== inputControl.expectedSessionId) {
             throw usageError(`Input requestId ${inputControl.requestId} was already used with different content or target; use a new requestId for a new input.`);
         }
         return { message: existing, idempotentReplay: true };
@@ -630,7 +667,8 @@ function messageGlobalInput(name, input, store, options) {
             ? environment.YUI_ROLE === "operator" ? "operator" : "agent" : "user" };
     const persisted = store.transaction((tx) => {
         requireRole(name, tx);
-        return sendGlobalRoleMessageCommand(tx, name, body, author, { action, requestId, ...(expectedTarget === undefined ? {} : { expectedTarget }) }, now);
+        return sendGlobalRoleMessageCommand(tx, name, body, author, { action, requestId, ...(expectedTarget === undefined ? {} : { expectedTarget }),
+            ...(input.expectedSessionId === undefined ? {} : { expectedSessionId: input.expectedSessionId }) }, now);
     });
     if (action === "queue") {
         const state = persisted.idempotentReplay ? "idempotent-replay" : "queued";