@zq-silk/yui 2.10.0 → 2.12.0

package/dist/artifacts/artifactCapability.js

@@ -33,6 +33,15 @@ function requireTextContent(content) {
  * commit exactly that path, and return the resulting commit-pinned reference.
  */
 export async function saveArtifactCapability(home, taskId, input) {
+    const bytes = artifactInputBytes(input);
+    return saveArtifactFile(home, taskId, {
+        relativePath: input.relativePath, bytes,
+        ...(input.message === undefined ? {} : { message: input.message }),
+        ...(input.expectedHead === undefined ? {} : { expectedHead: input.expectedHead })
+    });
+}
+/** Shared bounded text/static-image input; never executes HTML or scripts. */
+export function artifactInputBytes(input) {
     if (input.encoding !== undefined && input.encoding !== "utf8" && input.encoding !== "base64") {
         throw new Error("Artifact encoding must be utf8 or base64.");
     }
@@ -50,12 +59,7 @@ export async function saveArtifactCapability(home, taskId, input) {
     else {
         bytes = requireTextContent(input.content);
     }
-    return saveArtifactFile(home, taskId, {
-        relativePath: input.relativePath,
-        bytes,
-        ...(input.message === undefined ? {} : { message: input.message }),
-        ...(input.expectedHead === undefined ? {} : { expectedHead: input.expectedHead })
-    });
+    return bytes;
 }
 /**
  * `artifact.read`: read `relativePath` at HEAD, or at a pinned `commit` for
@@ -68,7 +72,10 @@ 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;
+    return { taskId, ...presentArtifactContent(content) };
+}
+export function presentArtifactContent(content) {
+    const image = isRasterArtifact(content.relativePath) ? rasterMetadata(content.bytes) : null;
     let text;
     if (image)
         text = content.bytes.toString("base64");
@@ -83,7 +90,6 @@ export async function readArtifactCapability(home, taskId, input) {
             throw new Error("Binary artifact is not supported as text.");
     }
     return {
-        taskId,
         relativePath: content.relativePath,
         commit: content.commit,
         content: text,

package/dist/artifacts/artifactCommitLock.js

@@ -1,5 +1,7 @@
 import { mkdirSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
+import { setTimeout } from "node:timers/promises";
+import { safePathSegment } from "./artifactPaths.js";
 import { currentFileLockOwner, fileLockOwnerIsLive } from "../core/fileLockOwner.js";
 /**
  * Short per-Task commit fence for artifact repositories.
@@ -11,8 +13,8 @@ import { currentFileLockOwner, fileLockOwnerIsLive } from "../core/fileLockOwner
  * the commit critical section for one Task.
  *
  * The Project maintenance fence waits asynchronously for longer operations.
- * An artifact save is short, so this synchronous critical section briefly
- * retries a contended fence before giving up. It otherwise shares the same
+ * An artifact save is short, so acquisition asynchronously waits for a contended
+ * fence, allowing the live holder's Git subprocess to finish. It shares the same
  * crash-safe design: an exclusive directory under the Home's `locks/` area
  * (O_EXCL via mkdir), an owner file recording PID + process start time so a
  * recycled PID can never pass for the original holder, and reclaim of a stale
@@ -37,7 +39,7 @@ export class ArtifactCommitLockedError extends Error {
 }
 /** Directory of one Task's artifact commit fence, below the Home's locks area. */
 export function artifactCommitLockPath(home, taskId) {
-    return join(home, "locks", "task-artifacts", `${taskId}.lock`);
+    return join(home, "locks", "task-artifacts", `${safePathSegment(taskId)}.lock`);
 }
 /**
  * Acquire one Task's artifact commit fence. Returns the release function;
@@ -46,7 +48,7 @@ export function artifactCommitLockPath(home, taskId) {
  * a stale (dead) holder is reclaimed. There is no in-process reentrancy: every
  * acquisition contends.
  */
-export function acquireArtifactCommitLock(home, taskId) {
+export async function acquireArtifactCommitLock(home, taskId) {
     const lock = artifactCommitLockPath(home, taskId);
     const ownerIdentity = currentFileLockOwner();
     mkdirSync(join(home, "locks", "task-artifacts"), { recursive: true, mode: 0o700 });
@@ -69,7 +71,7 @@ export function acquireArtifactCommitLock(home, taskId) {
             reclaimStaleArtifactCommitLock(lock);
             if (Date.now() >= deadline)
                 throw new ArtifactCommitLockedError(taskId);
-            Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ARTIFACT_COMMIT_LOCK_RETRY_MS);
+            await setTimeout(ARTIFACT_COMMIT_LOCK_RETRY_MS);
         }
     }
 }

package/dist/artifacts/jobArtifact.js

@@ -0,0 +1,93 @@
+import { createHash } from "node:crypto";
+import { isDeepStrictEqual } from "node:util";
+import { join } from "node:path";
+import { requireKnownFields } from "../domain/validation.js";
+import { jobScopeKey } from "../job/jobDefinition.js";
+import { runReference } from "../job/jobBusinessResult.js";
+import { requireCommitId } from "./managedGit.js";
+import { safeRelativeArtifactPath } from "./artifactPaths.js";
+import { openTaskArtifactRepository, openVersionedArtifactRepository } from "./taskArtifactRepository.js";
+function identity(value) {
+    if (typeof value !== "string" || !/^[a-zA-Z0-9][a-zA-Z0-9._-]{0,127}$/u.test(value)) {
+        throw new Error("Invalid artifact owner/Run identity.");
+    }
+    return value;
+}
+function validateScope(scope) {
+    requireKnownFields(scope, scope?.kind === "task" ? ["kind", "taskId"] : ["kind"], "Artifact scope");
+    if (scope.kind !== "global" && scope.kind !== "task")
+        throw new Error("Invalid artifact scope.");
+    jobScopeKey(scope);
+}
+export function validateJobArtifactReference(ref, run) {
+    requireKnownFields(ref, ["kind", "owner", "sourceRun", "version", "relativePath", "digest"], "Artifact reference");
+    if (ref.kind !== "artifact")
+        throw new Error("Expected an explicit artifact reference.");
+    requireKnownFields(ref.sourceRun, ["scope", "runId"], "Artifact source Run");
+    validateScope(ref.sourceRun.scope);
+    identity(ref.sourceRun.runId);
+    if (ref.owner.kind === "job") {
+        requireKnownFields(ref.owner, ["kind", "scope", "jobId"], "Artifact Job owner");
+        validateScope(ref.owner.scope);
+        identity(ref.owner.jobId);
+        if (!isDeepStrictEqual(ref.owner.scope, ref.sourceRun.scope))
+            throw new Error("Artifact owner/source scope mismatch.");
+        if (run && ref.owner.jobId !== run.definitionId)
+            throw new Error("Artifact Job owner mismatch.");
+    }
+    else if (ref.owner.kind === "task") {
+        requireKnownFields(ref.owner, ["kind", "taskId"], "Artifact Task owner");
+        jobScopeKey({ kind: "task", taskId: ref.owner.taskId });
+    }
+    else
+        throw new Error("Invalid artifact owner.");
+    if (run && !isDeepStrictEqual(ref.sourceRun, runReference(run)))
+        throw new Error("Artifact source Run mismatch.");
+    if (requireCommitId(ref.version) !== ref.version)
+        throw new Error("Artifact version must be an exact commit.");
+    safeRelativeArtifactPath(ref.relativePath);
+    if (ref.relativePath.length > 512)
+        throw new Error("Artifact reference path exceeds 512 characters.");
+    if (typeof ref.digest !== "string" || !/^[a-f0-9]{64}$/u.test(ref.digest))
+        throw new Error("Invalid artifact digest.");
+    return ref;
+}
+export function jobArtifactOwner(run) {
+    return { kind: "job", scope: runReference(run).scope, jobId: run.definitionId };
+}
+/** Each Run has a distinct working tree and commit fence even for identical paths.
+ * The retained storage is unrelated to execution workspaces/logs/checkpoints. */
+export function openJobArtifactRepository(home, owner, sourceRun) {
+    validateScope(owner.scope);
+    validateScope(sourceRun.scope);
+    if (!isDeepStrictEqual(owner.scope, sourceRun.scope))
+        throw new Error("Artifact scope mismatch.");
+    const scopePath = owner.scope.kind === "global" ? ["global"] : ["task", owner.scope.taskId];
+    const path = join(home, "job-artifacts", ...scopePath, identity(owner.jobId), identity(sourceRun.runId));
+    const lockKey = `job-${createHash("sha256").update(JSON.stringify([jobScopeKey(owner.scope), owner.jobId, sourceRun.runId])).digest("hex")}`;
+    return openVersionedArtifactRepository(home, lockKey, path);
+}
+export async function readJobArtifactReference(home, ref) {
+    validateJobArtifactReference(ref);
+    const repo = ref.owner.kind === "task"
+        ? openTaskArtifactRepository(home, ref.owner.taskId)
+        : openJobArtifactRepository(home, ref.owner, ref.sourceRun);
+    const content = await repo.read(ref.relativePath, ref.version);
+    if (content.digest !== ref.digest)
+        throw new Error("Artifact digest mismatch; preserved evidence was not replaced.");
+    return content;
+}
+export function validateRunArtifacts(run) {
+    if (run.artifacts === undefined)
+        return;
+    if (!Array.isArray(run.artifacts) || run.artifacts.length > 256
+        || Buffer.byteLength(JSON.stringify(run.artifacts)) > 128 * 1024)
+        throw new Error("Run artifacts exceed the bounded reference limit.");
+    for (const ref of run.artifacts)
+        validateJobArtifactReference(ref, run);
+}
+export function artifactsAppendOnly(before, after) {
+    const old = before.artifacts ?? [];
+    const next = after.artifacts ?? [];
+    return next.length >= old.length && old.every((ref, i) => isDeepStrictEqual(ref, next[i]));
+}

package/dist/artifacts/jobArtifactTransport.js

@@ -0,0 +1,13 @@
+/** Conservative encoded payload bound inside the 1 MiB Controller envelope.
+ * JSON escaping/base64 and reference metadata count, not just raw file bytes.
+ * Repository limits stay independent; large retained text uses paged preview. */
+export const MAX_JOB_ARTIFACT_JSON_BYTES = 256 * 1024;
+// Leave room for the fixed reference and presentation metadata added on reads.
+export const MAX_JOB_ARTIFACT_RESPONSE_BYTES = 512 * 1024;
+export function boundedJobArtifactPayload(value, label, limit = MAX_JOB_ARTIFACT_JSON_BYTES) {
+    if (Buffer.byteLength(JSON.stringify(value), "utf8") > limit) {
+        throw new Error(`${label} exceeds the Job artifact ${limit / 1024} KiB encoded JSON transport limit. `
+            + "Use smaller material or paged artifact-preview for retained text; source Task material remains available through its owning surface.");
+    }
+    return value;
+}

package/dist/artifacts/taskArtifactRepository.js

@@ -1,7 +1,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 { lstat, mkdir, writeFile } from "node:fs/promises";
+import { dirname, join, relative } from "node:path";
 import { supportedGit } from "../repository/gitCompatibility.js";
 import { acquireArtifactCommitLock } from "./artifactCommitLock.js";
 import { resolveContainedArtifactPath, safeRelativeArtifactPath, taskArtifactRepoPath } from "./artifactPaths.js";
@@ -90,13 +90,35 @@ export class ArtifactHeadConflictError extends Error {
  */
 export function openTaskArtifactRepository(home, taskId) {
     const repoPath = taskArtifactRepoPath(home, taskId);
+    const repo = openVersionedArtifactRepository(home, taskId, repoPath);
+    return { ...repo, taskId, save: async (input) => ({ ...await repo.save(input), taskId }) };
+}
+/** Shared local-only storage. Callers derive paths from validated owning identities,
+ * never from a user-supplied filesystem location. Task layout/commits stay intact. */
+export function openVersionedArtifactRepository(home, key, repoPath) {
+    const taskId = key; // Existing error fields retain their public spelling.
+    const checkBoundary = async () => {
+        await resolveContainedArtifactPath(home, `${relative(home, repoPath).split("\\").join("/")}/boundary-check`);
+        try {
+            const metadata = await lstat(join(repoPath, ".git"));
+            if (!metadata.isDirectory() || metadata.isSymbolicLink()) {
+                throw new Error("Artifact Git metadata must be its owned local directory, not a link/worktree.");
+            }
+        }
+        catch (error) {
+            if (!(error instanceof Error && "code" in error && error.code === "ENOENT"))
+                throw error;
+        }
+    };
     const exists = () => existsSync(join(repoPath, ".git"));
     const head = async () => {
+        await checkBoundary();
         if (!exists())
             return null;
         return currentHead(repoPath);
     };
-    const ensure = async () => {
+    const ensureUnlocked = async () => {
+        await checkBoundary();
         supportedGit();
         if (exists()) {
             await assertNoRemote(taskId, repoPath);
@@ -109,6 +131,15 @@ export function openTaskArtifactRepository(home, taskId) {
         await managedGit(repoPath, ["commit", "--allow-empty", "-m", "init artifact repo"]);
         await assertNoRemote(taskId, repoPath);
     };
+    const ensure = async () => {
+        const release = await acquireArtifactCommitLock(home, key);
+        try {
+            await ensureUnlocked();
+        }
+        finally {
+            release();
+        }
+    };
     const save = async (input) => {
         if (input.files.length === 0) {
             throw new Error("An artifact save must include at least one file.");
@@ -135,9 +166,9 @@ export function openTaskArtifactRepository(home, taskId) {
             }
             seen.add(file.relativePath);
         }
-        await ensure();
-        const release = acquireArtifactCommitLock(home, taskId);
+        const release = await acquireArtifactCommitLock(home, key);
         try {
+            await ensureUnlocked();
             await assertNoRemote(taskId, repoPath);
             // Expected-HEAD check under the lock: a conflict stops without writing.
             if (input.expectedHead !== undefined) {
@@ -161,22 +192,23 @@ export function openTaskArtifactRepository(home, taskId) {
                 "diff", "--cached", "--quiet", "--", ...pathspecs
             ]);
             if (noChanges) {
-                return { taskId, commit: await currentHead(repoPath), savedPaths: pathspecs };
+                return { commit: await currentHead(repoPath), savedPaths: pathspecs };
             }
             // `--only <paths>` records exactly these paths; any other WIP stays WIP.
             await managedGit(repoPath, ["commit", "--only", "-m", message, "--", ...pathspecs]);
-            return { taskId, commit: await currentHead(repoPath), savedPaths: pathspecs };
+            return { commit: await currentHead(repoPath), savedPaths: pathspecs };
         }
         finally {
             release();
         }
     };
     const read = async (relativePath, commit) => {
+        await checkBoundary();
         const safeRelative = safeRelativeArtifactPath(relativePath);
         // A pinned commit reads frozen evidence; otherwise read the current HEAD.
         // Both resolve `<commit>:<path>`, an OBJECT spec (never the working tree, so
         // a read never follows a symlink or sees unrelated WIP).
-        const pinned = commit === undefined ? await currentHead(repoPath) : requireCommitId(commit);
+        const pinned = await artifactCommit(repoPath, commit);
         const objectSpec = `${pinned}:${safeRelative}`;
         // `<commit>:<path>` for a DIRECTORY resolves to a tree, and `git show` would
         // print a tree listing rather than fail — silently returning directory
@@ -211,9 +243,10 @@ export function openTaskArtifactRepository(home, taskId) {
         };
     };
     const list = async (commit) => {
+        await checkBoundary();
         if (!exists())
             return [];
-        const pinned = commit === undefined ? await currentHead(repoPath) : requireCommitId(commit);
+        const pinned = await artifactCommit(repoPath, commit);
         const output = await managedGit(repoPath, [
             "ls-tree", "-r", "-z", "--long", "--full-tree", pinned
         ]);
@@ -233,6 +266,7 @@ export function openTaskArtifactRepository(home, taskId) {
         return entries;
     };
     const workingChanges = async () => {
+        await checkBoundary();
         if (!exists())
             return [];
         const output = await managedGit(repoPath, [
@@ -247,11 +281,25 @@ export function openTaskArtifactRepository(home, taskId) {
         }
         return changes;
     };
-    return { taskId, repoPath, ensure, exists, head, save, read, list, workingChanges };
+    return { repoPath, ensure, exists, head, save, read, list, workingChanges };
 }
 async function currentHead(repoPath) {
     return requireCommitId(await managedGit(repoPath, ["rev-parse", "HEAD^{commit}"]));
 }
+async function artifactCommit(repoPath, value) {
+    if (value === undefined)
+        return currentHead(repoPath);
+    const commit = requireCommitId(value);
+    const type = await managedGit(repoPath, ["cat-file", "-t", commit]).catch(error => {
+        if (error instanceof ManagedGitError)
+            throw new Error(`Artifact commit ${commit} is unavailable.`, { cause: error });
+        throw error;
+    });
+    if (type.trim() !== "commit") {
+        throw new Error("Artifact version must name a commit, not another Git object.");
+    }
+    return commit;
+}
 /**
  * Verify the repository is within the managed boundary before a write: NO remote
  * (network or file sync) AND no repo-local config that can execute an external

package/dist/cli/callerDiscovery.js

@@ -0,0 +1,18 @@
+import { maintenanceCallerEnvironment } from "../storage/maintenanceCaller.js";
+import { discoveryAudience } from "./commandDiscovery.js";
+/** Complete role hints retain their offline template, not authentication.
+ * Native-ID-only callers need local lookup to select a template. Read only the
+ * selected Home's registry; failure yields unbound, never a public fallback.
+ * This observation is deliberately not written back to the process environment. */
+export function callerDiscoveryAudience(home, env) {
+    if ((env.YUI_SESSION_SCOPE !== undefined && env.YUI_ROLE !== undefined)
+        || (env.CODEX_THREAD_ID === undefined && env.YUI_NATIVE_SESSION_ID === undefined)) {
+        return discoveryAudience(env);
+    }
+    try {
+        return discoveryAudience(maintenanceCallerEnvironment(home, env, false));
+    }
+    catch {
+        return "unbound";
+    }
+}

package/dist/cli/commandCatalog.js

@@ -397,8 +397,8 @@ const taskChildren = [
     {
         name: "list", discovery: { surface: "public", audiences: ["public", "operator", "leader"] },
         summary: "Discover Tasks through a bounded, filterable catalog.",
-        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"]
+        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"] },
@@ -1653,18 +1653,47 @@ export const ROOT_COMMAND = buildNode({
             ]
         },
         {
-            name: "job", discovery: { surface: "managed", audiences: ["operator", "leader", "assignment"] },
+            name: "job", discovery: { surface: "public", audiences: ["public", "operator", "leader", "assignment", "global"] },
             summary: "Manage stable Job definitions and exact execution Runs (not scheduler wakes).",
-            sections: [{ id: "manage", title: "Commands", entries: ["define", "update", "list", "show", "run", "runs", "run-get", "logs", "run-cancel", "run-acknowledge", "start", "get", "cancel", "acknowledge"] }],
+            sections: [{ id: "manage", title: "Commands", entries: ["define", "update", "list", "show", "run", "runs", "run-get", "run-result", "run-evidence", "run-confirm", "run-delegation", "run-claim", "run-context", "run-report", "run-continue", "session-inspect", "session-create", "session-stop", "session-new", "logs", "run-cancel", "run-acknowledge", "artifact-save", "artifact-list", "artifact-read", "artifact-preview", "artifact-register", "start", "get", "cancel", "acknowledge"] }],
             children: [
-                ...["define", "update", "list", "show", "run", "runs", "run-get", "logs", "run-cancel", "run-acknowledge"].map(name => ({
-                    name, discovery: { surface: "managed", audiences: ["operator", "leader", "assignment"] },
-                    summary: `${name} a stable Job or exact Run.`,
+                ...["run-claim", "run-context", "run-report", "run-continue", "session-inspect", "session-create", "session-stop", "session-new"].map(name => ({
+                    name, discovery: { surface: "public", audiences: ["public", "operator", "leader", "assignment", "global"] },
+                    summary: name === "run-report" ? "Record the exact native attempt's explicit Job business result."
+                        : name === "run-continue" ? "Continue an unfinished Run only after its exact prior native terminal."
+                            : name === "session-new" ? "Replace a proven-ended Job-owned Session, retaining Job input and results."
+                                : `${name} for a bounded Agent Job execution.`,
+                    usage: `yui job ${name} (--task <id>|--global) --job <id>`
+                        + (name.startsWith("run-") ? " --run <run-id>" : " [--run <isolated-run-id>]")
+                        + (name === "run-report" ? " --result <business-result-json>" : "")
+                        + (name === "run-continue" ? " --expected-attempt <prior-native-attempt-id>" : "")
+                        + (name === "session-new" || name === "session-stop" ? " --expected-session <native-id>" : ""),
+                    options: ["--task", "--global", "--job", "--run", "--result", "--expected-session", "--expected-attempt"]
+                })),
+                ...["artifact-save", "artifact-list", "artifact-read", "artifact-preview", "artifact-register"].map(name => ({
+                    name, discovery: { surface: "public", audiences: ["public", "operator", "leader", "assignment", "global"] },
+                    summary: name === "artifact-save" ? "Save bounded formal material and publish an exact owned Run reference."
+                        : name === "artifact-register" ? "Register already-saved evidence without replaying execution."
+                            : name === "artifact-read" || name === "artifact-preview" ? "Read/preview one registered immutable artifact (never HEAD)."
+                                : "List published Run history and retained repository evidence.",
+                    usage: `yui job ${name} (--task <id>|--global) --job <id> --run <run-id>`
+                        + (name === "artifact-save" ? " --artifact <save-json>" : "")
+                        + (["artifact-read", "artifact-preview", "artifact-register"].includes(name) ? " --reference <reference-json>" : "")
+                        + (name === "artifact-preview" ? " [--offset <text-offset>]" : ""),
+                    options: ["--task", "--global", "--job", "--run", "--artifact", "--reference", "--offset"]
+                })),
+                ...["define", "update", "list", "show", "run", "runs", "run-get", "run-result", "run-evidence", "run-confirm", "run-delegation", "logs", "run-cancel", "run-acknowledge"].map(name => ({
+                    name, discovery: { surface: "public", audiences: ["public", "operator", "leader", "assignment", "global"] },
+                    summary: name === "run-result" ? "Read an exact Run's business outcome and admitted snapshot."
+                        : name === "run-evidence" ? "Read original process evidence separately from the business outcome."
+                            : name === "run-confirm" ? "Collect retained results for an exact Run without starting or replaying work."
+                                : name === "run-delegation" ? "Read the exact execution Task/WorkItem and attention projection; never a grant."
+                                    : `${name} a stable Job or exact Run.`,
                     usage: `yui job ${name} (--task <id>|--global)${name === "list" ? "" : " --job <id>"}`
                         + (name === "define" || name === "update" ? " --title <text> --input <configuration-json>" : "")
                         + (name === "update" ? " --revision <current>" : "")
                         + (name === "run" ? " --request-id <key> [--retry-of <run-id>]" : "")
-                        + (["run-get", "logs", "run-cancel", "run-acknowledge"].includes(name) ? " --run <run-id>" : "")
+                        + (["run-get", "run-result", "run-evidence", "run-confirm", "run-delegation", "logs", "run-cancel", "run-acknowledge"].includes(name) ? " --run <run-id>" : "")
                 })),
                 { name: "start", discovery: { surface: "managed", audiences: ["operator", "leader", "assignment"] }, summary: "Start a DurableJob under an explicit request identity.", usage: "yui job start --request-id <id> --task <id> --project <project> --head <sha> --workspace <dir> --step <name>=<command> [--step ...] [--owner task|work-item:<id>|integration-attempt:<id>] [--env <k=v>...]" },
                 { name: "get", discovery: { surface: "managed", audiences: ["operator", "leader", "assignment"] }, summary: "Show a DurableJob record and its terminal result.", usage: "yui job get --task <id> --job <job-id>" },
@@ -1673,16 +1702,18 @@ export const ROOT_COMMAND = buildNode({
             ]
         },
         {
-            name: "schedule", discovery: { surface: "managed", audiences: ["operator", "leader", "assignment"] },
+            name: "schedule", discovery: { surface: "public", audiences: ["public", "operator", "leader", "assignment"] },
             summary: "Manage persistent time plans referencing scoped Jobs.",
-            sections: [{ id: "manage", title: "Commands", entries: ["create", "list", "show", "update", "enable", "disable"] }],
-            children: ["create", "list", "show", "update", "enable", "disable"].map(name => ({
-                name, discovery: { surface: "managed", audiences: ["operator", "leader", "assignment"] },
-                summary: `${name} a Schedule; disabling never cancels an admitted Run.`,
+            sections: [{ id: "manage", title: "Commands", entries: ["create", "list", "show", "update", "enable", "disable", "revoke"] }],
+            children: ["create", "list", "show", "update", "enable", "disable", "revoke"].map(name => ({
+                name, discovery: { surface: "public", audiences: ["public", "operator", "leader", "assignment"] },
+                summary: `${name} a Schedule; disable stops future dispatch, revoke also denies queued service starts.`,
                 usage: `yui schedule ${name} (--global|--task <id>)${name === "list" ? "" : " --schedule <id>"}`
                     + (name === "create" ? " --job <id> --rule <json>" : "")
                     + (name === "update" ? " --rule <json> [--job <id>]" : "")
-                    + (["update", "enable", "disable"].includes(name) ? " --revision <observed>" : "")
+                    + (["create", "update"].includes(name) ? " [--target <json>]" : "")
+                    + (["create", "update", "enable"].includes(name) ? " [--authorization session|service]" : "")
+                    + (["update", "enable", "disable", "revoke"].includes(name) ? " --revision <observed>" : "")
             }))
         },
         {

package/dist/cli/commandDiscovery.js

@@ -16,8 +16,7 @@ export function discoveryAudience(env) {
         return env.YUI_ROLE === "leader" ? "leader" : "assignment";
     return "unbound";
 }
-export function discoveryCommandTree(env) {
-    const audience = discoveryAudience(env);
+export function discoveryCommandTree(env, audience = discoveryAudience(env)) {
     const project = (node) => {
         const children = node.children.map(project).filter((child) => child !== undefined);
         const eligible = node.discovery?.surface !== "runtime" && node.discovery?.audiences.includes(audience);
@@ -48,7 +47,7 @@ export function discoveryCommandTree(env) {
         const sections = [
             { id: "start", title: "Start work", entries: ["operator", "project"] },
             { id: "progress", title: "Inspect progress", entries: ["task", "jobs", "execution", "telemetry"] },
-            { id: "participate", title: "Participate and control", entries: ["role", "session"] },
+            { id: "participate", title: "Participate and control", entries: ["role", "session", "job"] },
             { id: "maintain", title: "Configure and maintain", entries: ["help", "version", "setup", "start", "doctor", "config", "web", "controller", "resources", "update", "upgrade", "release"] }
         ];
         return { ...tree, sections: sections.map(section => ({ ...section,

package/dist/commands/durableJobCommands.js

@@ -3,6 +3,7 @@ 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 { boundedJobArtifactPayload } from "../artifacts/jobArtifactTransport.js";
 /**
  * The textual `--owner` forms accepted by `job start`. The public help text in
  * the command catalog must document exactly these forms.
@@ -15,7 +16,7 @@ export const JOB_OWNER_USAGE = "task|work-item:<id>|integration-attempt:<id>";
  */
 export async function runDurableJobCommand(args, options) {
     const [command, ...rest] = args;
-    if (command !== undefined && ["define", "update", "list", "show", "run", "runs", "run-get", "run-cancel", "run-acknowledge", "logs"].includes(command)) {
+    if (command !== undefined && ["define", "update", "list", "show", "run", "runs", "run-get", "run-result", "run-evidence", "run-confirm", "run-delegation", "run-cancel", "run-acknowledge", "logs", "artifact-save", "artifact-list", "artifact-read", "artifact-preview", "artifact-register", "run-claim", "run-context", "run-report", "run-continue", "session-inspect", "session-create", "session-stop", "session-new"].includes(command)) {
         return definitionCommand(command, rest, options);
     }
     if (command === "start")
@@ -39,7 +40,7 @@ async function definitionCommand(command, args, options) {
     const flags = new Map();
     for (let i = 0; i < args.length; i++) {
         const flag = args[i];
-        if (!["--global", "--task", "--job", "--title", "--input", "--revision", "--request-id", "--retry-of", "--run"].includes(flag)
+        if (!["--global", "--task", "--job", "--title", "--input", "--revision", "--request-id", "--retry-of", "--run", "--artifact", "--reference", "--offset", "--result", "--expected-session", "--expected-attempt"].includes(flag)
             || flags.has(flag))
             throw usageError(`Unknown or repeated Job flag: ${flag}.`);
         if (flag === "--global") {
@@ -54,7 +55,10 @@ async function definitionCommand(command, args, options) {
     if (flags.has("--global") === flags.has("--task"))
         throw usageError("Choose exactly one of --task <id> or --global.");
     const taskId = flags.get("--task");
-    const caller = resolveJobCaller(options.environment, taskId ?? "");
+    const executionRead = ["show", "runs", "run-get", "run-result", "run-context", "run-claim", "run-report",
+        "run-evidence", "run-confirm", "artifact-save", "artifact-list", "artifact-read", "artifact-preview", "artifact-register"].includes(command);
+    const caller = resolveJobCaller(options.environment, taskId
+        ?? (executionRead ? options.environment?.YUI_TASK_ID : undefined) ?? "");
     const scope = taskId === undefined ? { kind: "global" } : { kind: "task", taskId };
     let configuration;
     if (flags.has("--input")) {
@@ -66,10 +70,31 @@ async function definitionCommand(command, args, options) {
         }
     }
     const requestId = flags.get("--request-id");
+    const parseObject = (flag) => {
+        if (!flags.has(flag))
+            return undefined;
+        try {
+            return JSON.parse(flags.get(flag));
+        }
+        catch {
+            throw usageError(`${flag} must be JSON.`);
+        }
+    };
+    const artifact = parseObject("--artifact");
+    if (artifact !== undefined)
+        boundedJobArtifactPayload(artifact, "Artifact save");
+    const reference = parseObject("--reference");
+    const resultInput = parseObject("--result");
     if (command === "run" && !requestId)
         throw usageError("job run requires --request-id.");
     const params = {
         op: command, scope, caller,
+        ...(artifact === undefined ? {} : { artifact }),
+        ...(reference === undefined ? {} : { reference }),
+        ...(resultInput === undefined ? {} : { result: resultInput }),
+        ...(flags.has("--expected-session") ? { expectedSessionId: flags.get("--expected-session") } : {}),
+        ...(flags.has("--expected-attempt") ? { expectedAttemptId: flags.get("--expected-attempt") } : {}),
+        ...(flags.has("--offset") ? { offset: Number(flags.get("--offset")) } : {}),
         ...(flags.has("--job") ? { id: flags.get("--job") } : {}),
         ...(flags.has("--title") ? { title: flags.get("--title") } : {}),
         ...(configuration === undefined ? {} : { configuration }),
@@ -114,8 +139,8 @@ async function getJob(args, options) {
         `Job ${job.id} (task ${job.taskId})`,
         `  status: ${job.status}`,
         `  owner: ${formatOwner(job.owner)}`,
-        `  head: ${job.head}`,
-        `  workspace: ${job.workspace}`,
+        ...(job.delegation ? [`  delegated task: ${job.delegation.taskId}`, `  goal: ${job.delegation.goal}`]
+            : [`  head: ${job.head}`, `  workspace: ${job.workspace}`]),
         `  created: ${job.createdAt}`
     ];
     if (job.startedAt !== undefined)
@@ -129,7 +154,7 @@ async function getJob(args, options) {
         if (job.result.unknownReason !== undefined)
             lines.push(`  reason: ${job.result.unknownReason}`);
     }
-    for (const step of job.steps) {
+    for (const step of job.steps ?? []) {
         lines.push(`  step ${step.name}: ${step.command}`);
     }
     return `${lines.join("\n")}\n`;

package/dist/commands/globalRoleCommands.js

@@ -194,6 +194,11 @@ function roleContext(args, store, options) {
             nativeTurnId: sessions.providerBinding.run.nativeTurnId,
             status: sessions.providerBinding.run.status
         },
+        ...(role.jobOwner === undefined ? {} : { job: {
+                owner: role.jobOwner,
+                read: `yui job show ${role.jobOwner.scope.kind === "global" ? "--global" : `--task ${role.jobOwner.scope.taskId}`} --job ${role.jobOwner.jobId} --json`,
+                boundary: "Job execution only. This Role is not Operator and owns no Task delivery authority. Read the exact Run from its original message."
+            } }),
         retry: providerRetrySummary(sessions?.providerBinding),
         // Historical interrupt receipts are available through Session inspection;
         // only this Turn's exact identity is required at entry.