@zq-silk/yui 0.15.11 → 0.16.0

package/dist/completion/completionInstaller.js

@@ -3,9 +3,9 @@ import { chmodSync, existsSync, lstatSync, mkdirSync, readFileSync, renameSync,
 import { dirname, isAbsolute, join, resolve } from "node:path";
 import { dataError } from "../errors/cliError.js";
 import { activationBlock, activationEnd, activationIsAutomatic, activationStart, completionMarker, managedCompletionScript } from "./completionState.js";
-export function installCompletion(store, shell, installation, env, identity, activate) {
+export function installCompletion(store, shell, installation, env, activate) {
     validateInstallation(installation);
-    writeManagedScript(shell, installation.scriptPath, identity);
+    writeManagedScript(shell, installation.scriptPath);
     store.transaction((tx) => {
         const config = tx.getConfig();
         tx.saveConfig({
@@ -16,20 +16,20 @@ export function installCompletion(store, shell, installation, env, identity, act
             }
         });
     });
-    if (!activationIsAutomatic(shell, installation, env, identity) && activate) {
-        writeActivationBlock(shell, installation, identity);
+    if (!activationIsAutomatic(shell, installation, env) && activate) {
+        writeActivationBlock(shell, installation);
     }
 }
-export function uninstallCompletion(store, shell, identity) {
+export function uninstallCompletion(store, shell) {
     store.transaction((tx) => {
         const config = tx.getConfig();
         const installation = config.completionInstallations?.[shell];
         if (installation === undefined)
             return;
-        assertManagedScriptRemovable(shell, installation.scriptPath, identity);
-        assertActivationRemovable(shell, installation, identity);
-        removeManagedScript(shell, installation.scriptPath, identity);
-        removeActivationBlock(shell, installation, identity);
+        assertManagedScriptRemovable(shell, installation.scriptPath);
+        assertActivationRemovable(shell, installation);
+        removeManagedScript(shell, installation.scriptPath);
+        removeActivationBlock(shell, installation);
         const installations = { ...config.completionInstallations };
         delete installations[shell];
         if (Object.keys(installations).length > 0) {
@@ -40,17 +40,17 @@ export function uninstallCompletion(store, shell, identity) {
         tx.saveConfig(withoutInstallations);
     });
 }
-function assertManagedScriptRemovable(shell, path, identity) {
+function assertManagedScriptRemovable(shell, path) {
     if (!existsSync(path))
         return;
     const stat = lstatSync(path);
     if (!stat.isFile()
         || stat.isSymbolicLink()
-        || !readFileSync(path, "utf8").startsWith(completionMarker(shell, identity))) {
+        || !readFileSync(path, "utf8").startsWith(completionMarker(shell))) {
         throw dataError(`Refusing to remove unmanaged completion script: ${path}`);
     }
 }
-function assertActivationRemovable(shell, installation, identity) {
+function assertActivationRemovable(shell, installation) {
     const path = installation.activationPath;
     if (!existsSync(path))
         return;
@@ -59,25 +59,25 @@ function assertActivationRemovable(shell, installation, identity) {
         throw dataError(`Refusing to modify unsafe activation file: ${path}`);
     }
     const contents = readFileSync(path, "utf8");
-    const starts = occurrences(contents, activationStart(shell, identity));
-    const ends = occurrences(contents, activationEnd(shell, identity));
+    const starts = occurrences(contents, activationStart(shell));
+    const ends = occurrences(contents, activationEnd(shell));
     if (starts !== ends || starts > 1) {
         throw dataError(`Refusing to remove ambiguous Yui activation block: ${path}`);
     }
 }
-function writeManagedScript(shell, path, identity) {
+function writeManagedScript(shell, path) {
     if (existsSync(path)) {
         const stat = lstatSync(path);
         if (!stat.isFile() || stat.isSymbolicLink()) {
             throw dataError(`Refusing to overwrite unsafe completion script: ${path}`);
         }
-        if (!readFileSync(path, "utf8").startsWith(completionMarker(shell, identity))) {
+        if (!readFileSync(path, "utf8").startsWith(completionMarker(shell))) {
             throw dataError(`Refusing to overwrite unmanaged completion script: ${path}`);
         }
     }
-    writeAtomic(path, managedCompletionScript(shell, identity), 0o644);
+    writeAtomic(path, managedCompletionScript(shell), 0o644);
 }
-function writeActivationBlock(shell, installation, identity) {
+function writeActivationBlock(shell, installation) {
     const path = installation.activationPath;
     let contents = "";
     let mode = 0o644;
@@ -89,31 +89,31 @@ function writeActivationBlock(shell, installation, identity) {
         contents = readFileSync(path, "utf8");
         mode = stat.mode & 0o777;
     }
-    const start = activationStart(shell, identity);
-    const end = activationEnd(shell, identity);
+    const start = activationStart(shell);
+    const end = activationEnd(shell);
     const starts = occurrences(contents, start);
     const ends = occurrences(contents, end);
     if (starts > 1 || ends > 1 || starts !== ends) {
         throw dataError(`Refusing to modify ambiguous Yui activation block: ${path}`);
     }
-    const block = activationBlock(shell, installation, identity);
+    const block = activationBlock(shell, installation);
     const next = starts === 1
         ? replaceManagedBlock(contents, start, end, block)
         : `${contents}${contents.length === 0 || contents.endsWith("\n") ? "" : "\n"}${block}\n`;
     writeAtomic(path, next, mode);
 }
-function removeManagedScript(shell, path, identity) {
+function removeManagedScript(shell, path) {
     if (!existsSync(path))
         return;
     const stat = lstatSync(path);
     if (!stat.isFile()
         || stat.isSymbolicLink()
-        || !readFileSync(path, "utf8").startsWith(completionMarker(shell, identity))) {
+        || !readFileSync(path, "utf8").startsWith(completionMarker(shell))) {
         throw dataError(`Refusing to remove unmanaged completion script: ${path}`);
     }
     rmSync(path);
 }
-function removeActivationBlock(shell, installation, identity) {
+function removeActivationBlock(shell, installation) {
     const path = installation.activationPath;
     if (!existsSync(path))
         return;
@@ -122,8 +122,8 @@ function removeActivationBlock(shell, installation, identity) {
         throw dataError(`Refusing to modify unsafe activation file: ${path}`);
     }
     const contents = readFileSync(path, "utf8");
-    const start = activationStart(shell, identity);
-    const end = activationEnd(shell, identity);
+    const start = activationStart(shell);
+    const end = activationEnd(shell);
     const starts = occurrences(contents, start);
     const ends = occurrences(contents, end);
     if (starts !== ends || starts > 1) {

package/dist/completion/completionState.js

@@ -10,14 +10,14 @@ export function currentCompletionShell(env) {
         ? value
         : undefined;
 }
-export function suggestedCompletionInstallation(shell, env, identity) {
+export function suggestedCompletionInstallation(shell, env) {
     const home = absoluteEnvRoot("HOME", env.HOME);
     if (shell === "bash") {
         const data = env.XDG_DATA_HOME === undefined
             ? join(home, ".local", "share")
             : absoluteEnvRoot("XDG_DATA_HOME", env.XDG_DATA_HOME);
         return {
-            scriptPath: join(data, "bash-completion", "completions", identity),
+            scriptPath: join(data, "bash-completion", "completions", "yui"),
             activationPath: join(home, ".bashrc")
         };
     }
@@ -26,7 +26,7 @@ export function suggestedCompletionInstallation(shell, env, identity) {
             ? home
             : absoluteEnvRoot("ZDOTDIR", env.ZDOTDIR);
         return {
-            scriptPath: join(zshRoot, ".zfunc", `_${identity}`),
+            scriptPath: join(zshRoot, ".zfunc", "_yui"),
             activationPath: join(zshRoot, ".zshrc")
         };
     }
@@ -34,11 +34,11 @@ export function suggestedCompletionInstallation(shell, env, identity) {
         ? join(home, ".config")
         : absoluteEnvRoot("XDG_CONFIG_HOME", env.XDG_CONFIG_HOME);
     return {
-        scriptPath: join(config, "fish", "completions", `${identity}.fish`),
+        scriptPath: join(config, "fish", "completions", "yui.fish"),
         activationPath: join(config, "fish", "config.fish")
     };
 }
-export function inspectCompletionStates(config, env, identity) {
+export function inspectCompletionStates(config, env) {
     const current = currentCompletionShell(env);
     return COMPLETION_SHELLS.map((shell) => {
         const installation = config.completionInstallations?.[shell];
@@ -50,8 +50,8 @@ export function inspectCompletionStates(config, env, identity) {
                 current: shell === current
             };
         }
-        const installed = completionScriptIsCurrent(shell, installation, identity)
-            && completionActivationIsCurrent(shell, installation, env, identity);
+        const installed = completionScriptIsCurrent(shell, installation)
+            && completionActivationIsCurrent(shell, installation, env);
         return {
             shell,
             status: installed ? "Installed" : "Needs repair",
@@ -78,46 +78,46 @@ export function renderCompletionStateTable(states, width = defaultTableWidth())
         state.installation?.scriptPath ?? ""
     ]), width);
 }
-export function managedCompletionScript(shell, identity) {
-    return `${completionMarker(shell, identity)}\n${renderCompletion(shell, identity)}`;
+export function managedCompletionScript(shell) {
+    return `${completionMarker(shell)}\n${renderCompletion(shell)}`;
 }
-export function completionMarker(shell, identity) {
-    return `# yui-completion: managed shell=${shell} identity=${identity} format=1`;
+export function completionMarker(shell) {
+    return `# yui-completion: managed shell=${shell} identity=yui format=1`;
 }
-export function activationBlock(shell, installation, identity) {
-    const start = activationStart(shell, identity);
-    const end = activationEnd(shell, identity);
+export function activationBlock(shell, installation) {
+    const start = activationStart(shell);
+    const end = activationEnd(shell);
     const source = `source ${shellQuote(installation.scriptPath)}`;
     const functionName = basename(installation.scriptPath);
     const body = shell === "zsh"
-        ? `fpath=(${shellQuote(dirname(installation.scriptPath))} $fpath)\nautoload -Uz compinit\n(( $+functions[compdef] )) || compinit\nautoload -Uz -- ${shellQuote(functionName)}\ncompdef ${shellQuote(functionName)} ${shellQuote(identity)}`
+        ? `fpath=(${shellQuote(dirname(installation.scriptPath))} $fpath)\nautoload -Uz compinit\n(( $+functions[compdef] )) || compinit\nautoload -Uz -- ${shellQuote(functionName)}\ncompdef ${shellQuote(functionName)} 'yui'`
         : source;
     return `${start}\n${body}\n${end}`;
 }
-export function activationStart(shell, identity) {
-    return `# >>> yui completion shell=${shell} identity=${identity} >>>`;
+export function activationStart(shell) {
+    return `# >>> yui completion shell=${shell} identity=yui >>>`;
 }
-export function activationEnd(shell, identity) {
-    return `# <<< yui completion shell=${shell} identity=${identity} <<<`;
+export function activationEnd(shell) {
+    return `# <<< yui completion shell=${shell} identity=yui <<<`;
 }
-export function activationIsAutomatic(shell, installation, env, identity) {
+export function activationIsAutomatic(shell, installation, env) {
     return shell === "fish"
-        && installation.scriptPath === suggestedCompletionInstallation(shell, env, identity).scriptPath;
+        && installation.scriptPath === suggestedCompletionInstallation(shell, env).scriptPath;
 }
 export function shellQuote(value) {
     return `'${value.replaceAll("'", "'\\''")}'`;
 }
-export function completionScriptIsCurrent(shell, installation, identity) {
+export function completionScriptIsCurrent(shell, installation) {
     return safeRegularFile(installation.scriptPath)
-        && readFileSync(installation.scriptPath, "utf8") === managedCompletionScript(shell, identity);
+        && readFileSync(installation.scriptPath, "utf8") === managedCompletionScript(shell);
 }
-export function completionActivationIsCurrent(shell, installation, env, identity) {
-    if (activationIsAutomatic(shell, installation, env, identity))
+export function completionActivationIsCurrent(shell, installation, env) {
+    if (activationIsAutomatic(shell, installation, env))
         return true;
     if (!safeRegularFile(installation.activationPath))
         return false;
     const contents = readFileSync(installation.activationPath, "utf8");
-    const block = activationBlock(shell, installation, identity);
+    const block = activationBlock(shell, installation);
     return contents.split(block).length === 2;
 }
 function safeRegularFile(path) {

package/dist/completion/fileCompletionManager.js

@@ -4,21 +4,19 @@ import { COMPLETION_SHELLS, completionActivationIsCurrent, completionScriptIsCur
 export class FileCompletionManager {
     #store;
     #env;
-    #identity;
-    constructor(store, env, identity) {
+    constructor(store, env) {
         this.#store = store;
         this.#env = { ...env };
-        this.#identity = identity;
     }
     inspect() {
         const config = this.#store.getConfig();
         const currentShell = currentCompletionShell(this.#env);
         const states = COMPLETION_SHELLS.map((shell) => {
-            const suggested = suggestedCompletionInstallation(shell, this.#env, this.#identity);
+            const suggested = suggestedCompletionInstallation(shell, this.#env);
             const stored = config.completionInstallations?.[shell];
             const installation = stored ?? suggested;
-            const scriptCurrent = completionScriptIsCurrent(shell, installation, this.#identity);
-            const activationCurrent = completionActivationIsCurrent(shell, installation, this.#env, this.#identity);
+            const scriptCurrent = completionScriptIsCurrent(shell, installation);
+            const activationCurrent = completionActivationIsCurrent(shell, installation, this.#env);
             const status = scriptCurrent && activationCurrent
                 ? "Installed"
                 : stored === undefined ? "Not installed" : "Needs repair";
@@ -37,15 +35,12 @@ export class FileCompletionManager {
             });
         });
         return Object.freeze({
-            identity: this.#identity,
+            identity: "yui",
             ...(currentShell === undefined ? {} : { currentShell }),
             states: Object.freeze(states)
         });
     }
     install(request) {
-        installCompletion(this.#store, request.shell, request.installation, this.#env, this.#identity, request.activate);
+        installCompletion(this.#store, request.shell, request.installation, this.#env, request.activate);
     }
 }
-export function resolveCliIdentity(env) {
-    return env.YUI_CLI_NAME === "yui-dev" ? "yui-dev" : "yui";
-}

package/dist/config/configCatalog.js

@@ -14,8 +14,6 @@ export const CONFIG_DEFINITIONS = Object.freeze([
     { key: "runtime-health", domain: "runtime", property: "runtimeHealth", label: "Runtime health thresholds", summary: "Quiet, checkpoint-overdue, and read-only diagnostic thresholds in seconds; values must be strictly increasing (defaults: 300/900/1800).", takesEffect: "CLI and Web projections immediately; scheduler diagnostics after the Controller restarts." },
     { key: "agent-launch-inactivity-timeout-seconds", domain: "runtime", property: "agentLaunchInactivityTimeoutSeconds", label: "Agent launch inactivity timeout", summary: "Maximum launch silence before startup fails, 15-3600 seconds (default: 300).", takesEffect: "After the Controller restarts." },
     { key: "delivery-timeout-seconds", domain: "runtime", property: "deliveryTimeoutSeconds", label: "Delivery timeout", summary: "Total control-plane delivery retry budget, 5-600 seconds (default: 120).", takesEffect: "After the Controller restarts; internal retry cadence remains automatic." },
-    { key: "leader-next-action", domain: "workflow", property: "leaderNextActionMode", label: "Leader next-action mode", summary: "Leader next-action mode: display, warn, or enforce (default: display).", takesEffect: "The next Leader next-action projection or gate." },
-    { key: "leader-semantic-budget-runs", domain: "workflow", property: "leaderSemanticBudgetRuns", label: "Leader semantic budget", summary: "Consecutive completed Leader AgentRuns without durable delivery progress before warning, 1-20 (default: 3).", takesEffect: "The next Leader delivery guard evaluation." },
     { key: "review", domain: "workflow", property: "review", label: "Review", summary: "Optional global WorkItem review rule: a configured Role plus always, leader, or final trigger. Setup leaves it disabled so the Leader may review directly or delegate selectively.", takesEffect: "The next Candidate snapshot; in-flight Candidates and ReviewRounds keep their policy." },
     { key: "resources-gc-mode", domain: "resources", property: "resourcesGcMode", label: "Resources GC mode", summary: "Resource GC mode: report or quarantine (default: report).", takesEffect: "The next resource GC operation." },
     { key: "resources-gc-auto-quarantine", domain: "resources", property: "resourcesGcAutoQuarantine", label: "Resources GC auto-quarantine", summary: "Automatically quarantine eligible terminal Task resources (default: false).", takesEffect: "The next eligible automatic resource GC operation." },

package/dist/config/timeZone.js

@@ -0,0 +1,14 @@
+export const DEFAULT_TIME_ZONE = "Asia/Shanghai";
+export function resolveTimeZone(value) {
+    const timeZone = value ?? DEFAULT_TIME_ZONE;
+    if (typeof timeZone !== "string" || timeZone.trim() !== timeZone || timeZone.length === 0) {
+        throw new TypeError("timeZone must be a valid IANA timezone.");
+    }
+    try {
+        new Intl.DateTimeFormat("en", { timeZone }).format(0);
+    }
+    catch {
+        throw new TypeError("timeZone must be a valid IANA timezone.");
+    }
+    return timeZone;
+}

package/dist/config/yuiConfig.js

@@ -49,31 +49,6 @@ export function reconciliationIntervalMilliseconds(value) {
     }
     return seconds * 1_000;
 }
-/**
- * Issue 07 (Leader convergence) feature mode. `display` only shows the
- * read-only next-action decision support; `warn` additionally reports
- * duplicate deliveries and semantic-budget warnings; `enforce` hard-blocks
- * only exact duplicates, while semantic-budget exhaustion remains a warning
- * because it must not override Leader judgment. The mode is additive and
- * optional — Homes without it keep the `display` default, so no config
- * migration is required.
- */
-export const LEADER_NEXT_ACTION_MODES = ["display", "warn", "enforce"];
-export const DEFAULT_LEADER_NEXT_ACTION_MODE = "display";
-export function resolveLeaderNextActionMode(value) {
-    if (value === undefined || value === null)
-        return DEFAULT_LEADER_NEXT_ACTION_MODE;
-    if (typeof value !== "string") {
-        throw new TypeError("leaderNextActionMode must be display, warn, or enforce.");
-    }
-    const normalized = value.trim().toLowerCase();
-    if (normalized.length === 0)
-        return DEFAULT_LEADER_NEXT_ACTION_MODE;
-    if (!LEADER_NEXT_ACTION_MODES.includes(normalized)) {
-        throw new TypeError("leaderNextActionMode must be display, warn, or enforce.");
-    }
-    return normalized;
-}
 // ── Executable paths ──────────────────────────────────────────────────────
 export function resolveTmuxBin(value) {
     if (value === undefined || value === null)
@@ -115,7 +90,6 @@ export const DEFAULT_CONTROLLER_TASK_CONCURRENCY = 4;
 export const MAX_CONTROLLER_TASK_CONCURRENCY = 32;
 export const DEFAULT_AGENT_LAUNCH_INACTIVITY_TIMEOUT_SECONDS = 300;
 export const DEFAULT_DELIVERY_TIMEOUT_SECONDS = 120;
-export const DEFAULT_LEADER_SEMANTIC_BUDGET_RUNS = 3;
 export const DEFAULT_TMUX_HISTORY_LIMIT = 100_000;
 export function resolveRuntimeHealth(configured) {
     if (configured === undefined || configured === null)
@@ -141,9 +115,6 @@ export function resolveAgentLaunchInactivityTimeoutSeconds(value) {
 export function resolveDeliveryTimeoutSeconds(value) {
     return resolveBoundedPositiveInteger(value, DEFAULT_DELIVERY_TIMEOUT_SECONDS, 5, 600, "deliveryTimeoutSeconds");
 }
-export function resolveLeaderSemanticBudgetRuns(value) {
-    return resolveBoundedPositiveInteger(value, DEFAULT_LEADER_SEMANTIC_BUDGET_RUNS, 1, 20, "leaderSemanticBudgetRuns");
-}
 export function resolveTmuxHistoryLimit(value) {
     return resolveBoundedPositiveInteger(value, DEFAULT_TMUX_HISTORY_LIMIT, 1_000, 1_000_000, "tmuxHistoryLimit");
 }

package/dist/context/runContextPack.js

@@ -1,3 +1,4 @@
+import { providerRetryProjection } from "../runtime/providerRetry.js";
 import { operationalTaskRecords } from "../task/taskRecordRetirement.js";
 import { TASK_COMPLETION_PUBLISHED_TREE_AUTHORIZED_EVENT } from "../task/publicationReference.js";
 import { RUN_INPUT_MAX_DELTAS } from "./runInputContract.js";
@@ -277,8 +278,7 @@ export function buildRunContextPack(store, taskId, runId) {
 }
 /** Reads the Task's current in-flight execution, outside the frozen contract. */
 function readLiveTaskState(store, taskId) {
-    const activeRuns = store.listRuns(taskId)
-        .filter((run) => run.status === "active")
+    const activeRuns = store.listActiveRuns(taskId)
         .map((run) => Object.freeze({
         runId: run.id,
         roleName: run.roleName,
@@ -287,7 +287,7 @@ function readLiveTaskState(store, taskId) {
         ...(run.reviewRoundId === undefined ? {} : { reviewRoundId: run.reviewRoundId })
     }));
     const activeTaskReviews = store.listReviewRounds(taskId)
-        .filter((round) => ((round.scope ?? "work-item") === "task"
+        .filter((round) => (round.scope === "task"
         && (round.status === "pending" || round.status === "running")))
         .map((round) => Object.freeze({
         reviewRoundId: round.id,
@@ -295,6 +295,8 @@ function readLiveTaskState(store, taskId) {
         status: round.status
     }));
     return Object.freeze({
+        providerRetries: Object.freeze(store.listRoleSessionSets(taskId).flatMap(set => set.providerBinding?.retry === undefined
+            ? [] : [{ roleName: set.owner.roleName, retry: providerRetryProjection(set.providerBinding) }])),
         activeRuns: Object.freeze(activeRuns),
         activeTaskReviews: Object.freeze(activeTaskReviews)
     });

package/dist/context/taskCatalog.js

@@ -0,0 +1,185 @@
+import { usageError } from "../errors/cliError.js";
+import { contextContentDigest } from "./contextSnapshot.js";
+import { materialize, resolveContextReader } from "./taskContext.js";
+import { CATALOG_ATTENTION } from "../storage/taskCatalog.js";
+const TASK_STATUSES = ["draft", "active", "completed", "cancelled", "archived"];
+const PAGE_BYTES = 32 * 1024;
+const SUMMARY_BYTES = 512;
+const MAX_LIMIT = 100;
+export function parseTaskCatalogOptions(args) {
+    const values = new Map();
+    let all = false;
+    for (let i = 0; i < args.length; i++) {
+        const key = args[i];
+        if (key === "--all" && !all) {
+            all = true;
+            continue;
+        }
+        if (!["--limit", "--cursor", "--status", "--project", "--search", "--attention"].includes(key)
+            || values.has(key) || args[i + 1] === undefined || args[i + 1].startsWith("--")) {
+            throw usageError("Task list expects [--all] [--status <status>] [--project <id>] [--search <text>] [--attention <category>] [--limit <1..100>] [--cursor <cursor>].");
+        }
+        values.set(key, args[++i]);
+    }
+    const status = values.get("--status");
+    if (status !== undefined && !TASK_STATUSES.includes(status)) {
+        throw usageError("Unknown Task catalog status.");
+    }
+    const attention = values.get("--attention");
+    if (attention !== undefined && !CATALOG_ATTENTION.includes(attention)) {
+        throw usageError(`Task catalog attention must be one of: ${CATALOG_ATTENTION.join(", ")}.`);
+    }
+    const limit = values.has("--limit") ? Number(values.get("--limit")) : 20;
+    if (!Number.isSafeInteger(limit) || limit < 1 || limit > MAX_LIMIT)
+        throw usageError("Task catalog limit must be between 1 and 100.");
+    const search = values.get("--search")?.trim();
+    const project = values.get("--project")?.trim();
+    if ((search?.length ?? 0) > 256 || (project?.length ?? 0) > 256 || project === "") {
+        throw usageError("Task catalog filters exceed their text limit.");
+    }
+    return {
+        all: all || status === "archived", limit,
+        ...(status === undefined ? {} : { status: status }),
+        ...(attention === undefined ? {} : { attention: attention }),
+        ...(search ? { search } : {}),
+        ...(project === undefined ? {} : { project }),
+        ...(values.has("--cursor") ? { cursor: values.get("--cursor") } : {})
+    };
+}
+/** Task-local Leaders discover only their Task. Assignment Roles use their
+ * existing Context pack: whole-Task counts would leak unrelated assignments. */
+export function taskCatalogScope(store, environment) {
+    const caller = resolveContextReader(store, environment);
+    if (caller !== undefined && caller.roleName !== "leader") {
+        throw usageError("Task discovery is unavailable to an Assignment-scoped Role; use its authorized Run Context.");
+    }
+    return caller?.taskId;
+}
+export function readTaskCatalog(store, options, environment = {}) {
+    return store.transaction(reader => {
+        const taskId = taskCatalogScope(reader, environment);
+        const { cursor: rawCursor, ...filters } = options;
+        if (!Number.isSafeInteger(filters.limit) || filters.limit < 1 || filters.limit > MAX_LIMIT) {
+            throw usageError("Task catalog limit must be between 1 and 100.");
+        }
+        const scope = contextContentDigest({ taskId: taskId ?? null, ...filters });
+        const cursor = rawCursor === undefined ? undefined : decodeCursor(rawCursor, scope);
+        const facts = reader.queryTaskCatalog({
+            ...filters, ...(taskId === undefined ? {} : { taskId }),
+            ...(cursor === undefined ? {} : { after: cursor.after, through: cursor.through }),
+            limit: options.limit + 1
+        });
+        const refs = new Map();
+        const getRef = (id) => {
+            let ref = refs.get(id);
+            if (ref === undefined) {
+                const task = reader.getTask(id);
+                if (task === null)
+                    throw usageError("Task catalog changed during the read; retry.");
+                ref = { taskId: id, ...materialize("task", id, task).ref };
+                refs.set(id, ref);
+            }
+            return ref;
+        };
+        const attention = Object.fromEntries(CATALOG_ATTENTION.map(kind => {
+            const source = facts.attention[kind];
+            const selected = [];
+            for (const id of source.taskIds) {
+                const ref = getRef(id);
+                if (bytes([...selected, ref]) <= 2048)
+                    selected.push(ref);
+            }
+            return [kind, {
+                    count: source.count,
+                    unit: kind === "executionSignals" ? "signals" : "records",
+                    refs: selected,
+                    // Samples identify affected Tasks, not individual records. Count and
+                    // sample size therefore must never be subtracted from one another.
+                    taskCount: source.taskCount,
+                    omittedTaskRefs: source.taskCount - selected.length,
+                    query: { all: options.all, attention: kind }
+                }];
+        }));
+        const response = {
+            view: "compact",
+            scope: { taskId: taskId ?? null, archived: options.all ? "included" : "excluded",
+                attention: "authorized-catalog-before-filters", executionSignals: "raw-inspection-candidates-not-execution-status" },
+            filters, total: facts.total, counts: facts.counts, attention,
+            tasks: [],
+            nextCursor: null,
+            consistency: "current-per-page; refresh for membership changes; new creation keys after the upper bound excluded",
+            limits: { pageBytes: PAGE_BYTES, summaryBytes: SUMMARY_BYTES, maxTasks: options.limit, attentionTaskRefsPerCategory: 4 }
+        };
+        const through = cursor?.through ?? facts.through;
+        const continuation = (after) => through === null ? null
+            : Buffer.from(JSON.stringify({ version: 1, scope, after, through })).toString("base64url");
+        for (const row of facts.rows.slice(0, options.limit)) {
+            const ref = getRef(row.id);
+            const summary = row.summary === null ? null : truncateUtf8(row.summary, SUMMARY_BYTES);
+            const title = truncateUtf8(row.title, 256);
+            // SQL already limits these fields. Compare against the selected original
+            // only when necessary; length-at-limit is conservatively marked omitted.
+            const item = {
+                id: row.id, title, status: row.status, createdAt: row.createdAt, updatedAt: row.updatedAt,
+                summary, summaryStatus: row.summaryPresent ? "available" : "missing",
+                omitted: { title: row.title.length >= 256 || title !== row.title,
+                    summary: row.summary !== null && (row.summary.length >= 512 || summary !== row.summary) },
+                counts: { workItems: row.workItems, activeRuns: row.activeRuns },
+                attention: Object.fromEntries(CATALOG_ATTENTION.map(kind => [kind, row[kind]])),
+                ref
+            };
+            const next = continuation({ id: row.id, createdAt: row.createdAt });
+            if (bytes({ ok: true, data: { ...response, tasks: [...response.tasks, item], nextCursor: next } }) + 1 > PAGE_BYTES)
+                break;
+            response.tasks.push(item);
+        }
+        if (response.tasks.length < facts.rows.length) {
+            const last = response.tasks.at(-1);
+            if (last === undefined)
+                throw usageError("Task catalog identity/attention metadata exceeds the page byte budget.");
+            response.nextCursor = continuation({ id: last.id, createdAt: last.createdAt });
+        }
+        if (bytes({ ok: true, data: response }) + 1 > PAGE_BYTES)
+            throw usageError("Task catalog metadata exceeds the page byte budget.");
+        return response;
+    });
+}
+export function renderTaskCatalog(result) {
+    return [
+        `Tasks (compact): ${result.tasks.length} shown; ${result.total} matching`,
+        ...result.tasks.map(task => `${task.id}\t${task.status}\t${task.title}\n  ${task.summary ?? "(summary missing)"}`),
+        `Attention across catalog: ${CATALOG_ATTENTION.map(kind => `${kind}=${result.attention[kind].count}`).join(", ")}`,
+        "Expand: yui task context <task-id>; inspect the Task ref for original requirements.",
+        ...(result.nextCursor === null ? [] : [`Next cursor: ${result.nextCursor}`])
+    ].join("\n") + "\n";
+}
+function bytes(value) { return Buffer.byteLength(JSON.stringify(value)); }
+function truncateUtf8(value, max) {
+    let result = "";
+    let size = 0;
+    for (const point of value) {
+        size += Buffer.byteLength(point);
+        if (size > max)
+            break;
+        result += point;
+    }
+    return result;
+}
+function decodeCursor(raw, scope) {
+    try {
+        if (raw.length > 4096 || !/^[A-Za-z0-9_-]+$/.test(raw))
+            throw new Error();
+        const parsed = JSON.parse(Buffer.from(raw, "base64url").toString("utf8"));
+        const validKey = (key) => key && typeof key.id === "string" && key.id.length > 0
+            && typeof key.createdAt === "string" && Number.isFinite(Date.parse(key.createdAt));
+        if (parsed.version !== 1 || parsed.scope !== scope || !validKey(parsed.after) || !validKey(parsed.through)
+            || parsed.after.createdAt > parsed.through.createdAt
+            || (parsed.after.createdAt === parsed.through.createdAt
+                && Buffer.compare(Buffer.from(parsed.after.id), Buffer.from(parsed.through.id)) > 0))
+            throw new Error();
+        return parsed;
+    }
+    catch {
+        throw usageError("Invalid Task catalog cursor or cursor belongs to another scope/filter.");
+    }
+}