@zq-silk/yui 2.9.0 → 2.10.0

package/dist/web/controllerWeb.js

@@ -1,59 +1,111 @@
 import { parseWebCommandOptions, startYuiWebServer } from "./webServer.js";
+import { parseDurableJobCaller } from "../controller/jobControl.js";
+import { requireManagedGlobalCaller } from "../runtime/managedCaller.js";
 /** HTTP listener ownership only, alongside the Controller's one Kernel Host.
  * The authenticated Controller control socket starts/stops the exact listener;
  * no capability identity is accepted through this lifecycle API. */
 export function createControllerWeb(store, dependencies) {
     let current;
-    let starting = false;
-    const close = async () => {
+    let shutdown = false;
+    let startup;
+    let closing;
+    const closeListener = async () => {
+        if (closing)
+            return closing;
         const owned = current;
         if (!owned)
             return;
-        current = undefined;
         owned.server.closeTerminals();
-        await new Promise((resolve, reject) => {
+        closing = new Promise((resolve, reject) => {
             owned.server.close((error) => error ? reject(error) : resolve());
             owned.server.closeAllConnections();
         });
+        try {
+            await closing;
+            current = undefined;
+        }
+        finally {
+            closing = undefined;
+        }
     };
     return {
-        close,
+        async close() {
+            shutdown = true;
+            // A Controller shutdown must also own a bind still in flight.
+            if (startup)
+                await startup.catch(() => undefined);
+            await closeListener();
+        },
         async dispatch(method, value) {
             if (!value || typeof value !== "object" || Array.isArray(value))
                 throw new Error("Invalid Web listener request.");
             const params = value;
+            // The control socket proves the local Home/user boundary. Managed
+            // callers additionally retain their current native identity; no Web
+            // token or browser-user credential is issued by this API.
+            const caller = parseDurableJobCaller(params.caller);
+            if (caller.scope === "user") {
+                if (Object.keys(caller).length !== 1)
+                    throw new Error("Invalid local Web caller.");
+            }
+            else {
+                if (caller.scope !== "global" || caller.role !== "operator" || caller.taskId !== undefined || caller.runId !== undefined) {
+                    throw new Error("Only the current global Operator may manage Web listeners.");
+                }
+                requireManagedGlobalCaller(store, {
+                    YUI_SESSION_SCOPE: "global", YUI_ROLE: caller.role, YUI_AGENT_ID: caller.agentId,
+                    YUI_ADAPTER_ID: caller.adapterId, YUI_NATIVE_SESSION_ID: caller.nativeSessionId
+                });
+            }
             if (method === "web.status") {
-                if (Object.keys(params).length)
+                if (Object.keys(params).some(key => key !== "caller"))
                     throw new Error("Web status takes no arguments.");
-                return current ? { id: current.id, url: current.url } : null;
+                return current ? { ...current.status, state: closing ? "stopping" : "running" }
+                    : startup ? { state: "starting" } : null;
             }
             if (method === "web.stop") {
-                if (Object.keys(params).some((key) => key !== "id") || typeof params.id !== "string")
+                if (Object.keys(params).some((key) => !["id", "caller"].includes(key)) || typeof params.id !== "string")
                     throw new Error("Expected Web listener id.");
+                if (startup)
+                    throw new Error("Web listener is starting; query status before retrying.");
                 if (!current)
                     return { stopped: false };
-                if (current.id !== params.id)
+                if (current.status.id !== params.id)
                     throw new Error("Web listener identity changed.");
-                await close();
+                await closeListener();
                 return { stopped: true };
             }
-            if (method !== "web.start" || Object.keys(params).some((key) => !["id", "host", "port"].includes(key))
+            if (method !== "web.start" || Object.keys(params).some((key) => !["id", "host", "port", "authFile", "caller"].includes(key))
                 || typeof params.id !== "string" || !params.id.trim()
-                || typeof params.host !== "string" || typeof params.port !== "number") {
+                || typeof params.host !== "string" || typeof params.port !== "number"
+                || (params.authFile !== undefined && typeof params.authFile !== "string")) {
                 throw new Error("Expected id, host and port for Web start.");
             }
-            const options = parseWebCommandOptions(["--host", params.host, "--port", String(params.port)]);
-            if (starting || current)
-                throw new Error("A Web listener is already starting or running in this Controller.");
-            starting = true;
+            const options = parseWebCommandOptions(["--host", params.host, "--port", String(params.port),
+                ...(typeof params.authFile === "string" ? ["--auth-file", params.authFile] : [])]);
+            if (shutdown)
+                throw new Error("Controller Web lifecycle is shutting down.");
+            if (startup || closing)
+                throw new Error("Web listener lifecycle is busy; query status before retrying.");
+            if (current) {
+                if (current.status.host === options.host && current.status.port === options.port && current.authFile === options.authFile) {
+                    return { ...current.status, state: "running", alreadyRunning: true };
+                }
+                throw new Error("A different Web listener is already running. Inspect --status and explicitly --stop before changing its configuration.");
+            }
             try {
-                const server = await startYuiWebServer(store, options, dependencies);
-                const url = `http://${options.host === "::1" ? "[::1]" : options.host}:${options.port}`;
-                current = { id: params.id, server, url };
-                return { id: params.id, url };
+                startup = startYuiWebServer(store, options, dependencies);
+                const server = await startup;
+                const { urls, authentication, warnings } = server.access;
+                const status = { id: params.id, host: options.host, port: options.port,
+                    url: urls[0] ?? null, urls, authentication, warnings };
+                current = { status, server, authFile: options.authFile };
+                if (shutdown)
+                    throw new Error("Controller shut down before Web startup completed.");
+                return { ...status, state: "running", alreadyRunning: false };
             }
             finally {
-                starting = false;
+                startup = undefined;
             }
         }
     };

package/dist/web/taskPreviews.js

@@ -13,6 +13,16 @@ export function createTaskPreviews(store, home) {
     const secret = randomBytes(32);
     const key = (taskId, jobId) => createHmac("sha256", secret).update(JSON.stringify([taskId, jobId])).digest("base64url");
     const prefix = (job) => `/preview/${encodeURIComponent(job.taskId)}/${encodeURIComponent(job.id)}/${key(job.taskId, job.id)}/`;
+    const ticketTarget = (request) => {
+        const url = new URL(request.url ?? "/", "http://localhost");
+        const match = /^\/preview\/([A-Za-z0-9_-]+)\/([A-Za-z0-9_-]+)\/([A-Za-z0-9_-]+)\/(.*)$/.exec(url.pathname);
+        if (!match || (request.method !== "GET" && request.method !== "HEAD"))
+            return undefined;
+        const [, taskId, jobId, ticket, path] = match;
+        const expected = key(taskId, jobId);
+        return ticket.length === expected.length && timingSafeEqual(Buffer.from(ticket), Buffer.from(expected))
+            ? { taskId: taskId, jobId: jobId, path: path, search: url.search } : undefined;
+    };
     const registered = (taskId, jobId) => {
         const job = store.getDurableJob(taskId, jobId);
         if (!store.getTask(taskId) || !job || job.taskId !== taskId || !isHttpPreview(job.env)) {
@@ -52,6 +62,10 @@ export function createTaskPreviews(store, home) {
         return result;
     };
     return {
+        // Issued only by the authenticated list API. This credential authorizes
+        // one preview's reads, not the main page, APIs, writes or Terminal.
+        // Opaque sandbox fetch/module requests intentionally carry no user auth.
+        authenticated(request) { return ticketTarget(request) !== undefined; },
         async list(taskId) {
             if (!store.getTask(taskId))
                 throw new WebRequestRejected("Task not found.");
@@ -102,27 +116,21 @@ export function createTaskPreviews(store, home) {
             });
         },
         async serve(request, response) {
-            const url = new URL(request.url ?? "/", "http://localhost");
-            const match = /^\/preview\/([A-Za-z0-9_-]+)\/([A-Za-z0-9_-]+)\/([A-Za-z0-9_-]+)\/(.*)$/.exec(url.pathname);
             const fail = (status, detail) => {
                 response.statusCode = status;
                 response.setHeader("content-type", "text/plain; charset=utf-8");
                 response.end(detail);
             };
-            if (!match) {
-                fail(403, "Invalid preview ticket.");
+            if (request.method !== "GET" && request.method !== "HEAD") {
+                fail(405, "Preview supports GET and HEAD only.");
                 return;
             }
-            const [, taskId, jobId, ticket, path] = match;
-            const expected = key(taskId, jobId);
-            if (ticket.length !== expected.length || !timingSafeEqual(Buffer.from(ticket), Buffer.from(expected))) {
+            const target = ticketTarget(request);
+            if (!target) {
                 fail(403, "Invalid preview ticket.");
                 return;
             }
-            if (request.method !== "GET" && request.method !== "HEAD") {
-                fail(405, "Preview supports GET and HEAD only.");
-                return;
-            }
+            const { taskId, jobId, path, search } = target;
             let job;
             try {
                 job = registered(taskId, jobId);
@@ -134,7 +142,7 @@ export function createTaskPreviews(store, home) {
                 return;
             }
             try {
-                const result = await read(job, "/" + path + url.search, request.method);
+                const result = await read(job, "/" + path + search, request.method);
                 const base = prefix(job);
                 // No upstream CSP, cookies, auth, redirects, or CORS escape this boundary.
                 const source = `http://${request.headers.host}${base}`;
@@ -155,7 +163,7 @@ export function createTaskPreviews(store, home) {
                         fail(502, "External/absolute redirects are not supported in preview.");
                         return;
                     }
-                    const target = new URL(result.location, "http://preview.invalid/" + path + url.search);
+                    const target = new URL(result.location, "http://preview.invalid/" + path + search);
                     response.setHeader("location", base + target.pathname.slice(1) + target.search + target.hash);
                 }
                 response.statusCode = result.status;

package/dist/web/webAccess.js

@@ -0,0 +1,109 @@
+import { createHash, timingSafeEqual } from "node:crypto";
+import { closeSync, constants, fstatSync, openSync, readFileSync } from "node:fs";
+import { isIP } from "node:net";
+import { networkInterfaces } from "node:os";
+import { isAbsolute } from "node:path";
+export function isLoopbackAddress(host) {
+    return host === "localhost" || host === "::1" || /^127\./.test(host) && isIP(host) === 4;
+}
+/** Only numeric private addresses are advertised/accepted for LAN access.
+ * DNS aliases and proxy headers are deliberately not an authentication input. */
+export function isPrivateAddress(host) {
+    return isIP(host) === 4
+        ? /^(10\.|192\.168\.|172\.(1[6-9]|2[0-9]|3[01])\.)/.test(host)
+        : isIP(host) === 6 && /^f[cd]/i.test(host);
+}
+export function validateWebAccessOptions(options) {
+    if (!isLoopbackAddress(options.host) && !isPrivateAddress(options.host)
+        && options.host !== "0.0.0.0" && options.host !== "::") {
+        throw new Error("Web host must be localhost, a loopback/private IP address, 0.0.0.0 or ::.");
+    }
+    if (!Number.isInteger(options.port) || options.port < 1 || options.port > 65535) {
+        throw new Error("Web port must be an integer between 1 and 65535.");
+    }
+    if (!isLoopbackAddress(options.host) && !options.authFile) {
+        throw new Error("Non-loopback Web access requires --auth-file <absolute-path>.");
+    }
+    if (options.authFile !== undefined && !isAbsolute(options.authFile)) {
+        throw new Error("--auth-file must be an absolute path to an owner-only password file.");
+    }
+}
+function passwordDigest(path) {
+    let fd;
+    try {
+        fd = openSync(path, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+        const stat = fstatSync(fd);
+        if (!stat.isFile() || (stat.mode & 0o077) !== 0 || stat.uid !== process.getuid?.()
+            || stat.size < 32 || stat.size > 256)
+            throw new Error("invalid credential file");
+        const password = readFileSync(fd, "utf8").replace(/\r?\n$/, "");
+        if (!/^[\x21-\x7e]{32,128}$/.test(password))
+            throw new Error("invalid password");
+        return createHash("sha256").update(`Basic ${Buffer.from(`yui:${password}`).toString("base64")}`).digest();
+    }
+    catch {
+        // Never include file contents, OS error text or a submitted credential.
+        throw new Error("Cannot load Web credential: use a regular owner-only (0600) file containing a unique 32–128 character ASCII password. Then restart Web.");
+    }
+    finally {
+        if (fd !== undefined)
+            closeSync(fd);
+    }
+}
+export function createWebAccess(options, interfaces = networkInterfaces()) {
+    validateWebAccessOptions(options);
+    const lan = !isLoopbackAddress(options.host);
+    const digest = options.authFile === undefined ? undefined : passwordDigest(options.authFile);
+    const wildcard = options.host === "0.0.0.0" || options.host === "::";
+    const canonicalHost = (host) => isIP(host) === 6
+        ? new URL(`http://[${host}]`).hostname.slice(1, -1) : host;
+    const addresses = (wildcard
+        ? [...new Set(Object.values(interfaces).flatMap(entries => entries ?? [])
+                .filter(entry => isPrivateAddress(entry.address) && (options.host === "::" || entry.family === "IPv4"))
+                .map(entry => entry.address))]
+        : [options.host]).map(canonicalHost);
+    const allowed = new Set(!lan || wildcard ? [...addresses, "127.0.0.1", "::1", "localhost"] : addresses);
+    const urlHost = (host) => isIP(host) === 6 ? `[${host}]` : host;
+    const urls = addresses.map(host => `http://${urlHost(host)}:${options.port}`);
+    const warnings = lan ? [
+        "HTTP is not encrypted. Use only a trusted network; credentials and data are visible to network observers.",
+        ...(wildcard ? ["Wildcard binding listens on all matching interfaces, including public ones. Yui does not open firewall ports or tunnels."] : []),
+        ...(!urls.length ? ["No usable private interface address was found. Check interfaces or bind an explicit private address; reachability is not verified."] : [])
+    ] : [];
+    return {
+        lan,
+        authentication: digest ? "basic" : "local",
+        urls,
+        warnings,
+        acceptsHost(request) {
+            const host = request.headers.host;
+            if (!host)
+                return false;
+            try {
+                const url = new URL(`http://${host}`);
+                const hostname = url.hostname.replace(/^\[|\]$/g, "");
+                return allowed.has(hostname) && host === `${urlHost(hostname)}${request.socket.localPort === 80 ? "" : `:${request.socket.localPort}`}`
+                    && !url.username && !url.password && url.pathname === "/" && !url.search && !url.hash;
+            }
+            catch {
+                return false;
+            }
+        },
+        acceptsOrigin(request, requireOrigin = false, scopedPreview = false) {
+            const origin = request.headers.origin;
+            // Existing preview tickets authenticate only GET/HEAD of one sandboxed
+            // Job. Its opaque-origin modules/fetches must not inherit user credentials.
+            if (scopedPreview && (origin === undefined || origin === "null"))
+                return true;
+            return request.headers["sec-fetch-site"] !== "cross-site"
+                && (origin === undefined ? !requireOrigin : origin === `http://${request.headers.host}`);
+        },
+        authenticated(request) {
+            if (!digest)
+                return true;
+            const authorization = request.headers.authorization;
+            return typeof authorization === "string" && authorization.length <= 512
+                && timingSafeEqual(createHash("sha256").update(authorization).digest(), digest);
+        }
+    };
+}

package/dist/web/webServer.js

@@ -1,6 +1,7 @@
 import { randomBytes, timingSafeEqual } from "node:crypto";
 import { createServer } from "node:http";
 import WebSocket, { WebSocketServer } from "ws";
+import { createWebAccess, validateWebAccessOptions } from "./webAccess.js";
 import { CliError, usageError } from "../errors/cliError.js";
 import { parseTaskCatalogOptions } from "../context/taskCatalog.js";
 import { parseTaskSearchOptions, searchTaskBodies } from "../context/taskSearch.js";
@@ -17,6 +18,7 @@ const MAX_TERMINAL_BUFFERED_BYTES = 1024 * 1024;
 export function parseWebCommandOptions(args) {
     let host = "127.0.0.1";
     let port = 4173;
+    let authFile;
     for (let index = 0; index < args.length; index += 1) {
         const option = args[index];
         const value = args[index + 1];
@@ -28,19 +30,25 @@ export function parseWebCommandOptions(args) {
             port = Number(value);
             index += 1;
         }
+        else if (option === "--auth-file" && value !== undefined) {
+            authFile = value;
+            index += 1;
+        }
         else {
             throw webUsageError();
         }
     }
-    if (!new Set(["127.0.0.1", "::1", "localhost"]).has(host)) {
-        throw usageError("Web host must be a loopback address (127.0.0.1, ::1, or localhost).", webUsage());
+    const options = { host, port, ...(authFile === undefined ? {} : { authFile }) };
+    try {
+        validateWebAccessOptions(options);
     }
-    if (!Number.isInteger(port) || port < 1 || port > 65_535) {
-        throw usageError("Web port must be an integer between 1 and 65535.", webUsage());
+    catch (error) {
+        throw usageError(error.message, webUsage());
     }
-    return { host, port };
+    return options;
 }
-export function createYuiWebServer(store, dependencies = {}) {
+export function createYuiWebServer(store, dependencies = {}, options = { host: "127.0.0.1", port: 4173 }) {
+    const access = createWebAccess(options);
     const now = dependencies.now ?? (() => new Date());
     const token = dependencies.token ?? randomBytes(24).toString("base64url");
     const httpDependencies = { ...dependencies, previews: dependencies.previews?.() };
@@ -50,7 +58,7 @@ export function createYuiWebServer(store, dependencies = {}) {
         maxPayload: MAX_TERMINAL_MESSAGE_BYTES
     });
     const server = createServer((request, response) => {
-        void handleHttpRequest(request, response, store, httpDependencies, token, now).catch(() => {
+        void handleHttpRequest(request, response, store, httpDependencies, token, now, access).catch(() => {
             if (!response.headersSent)
                 setSecurityHeaders(response);
             if (!response.writableEnded) {
@@ -59,7 +67,7 @@ export function createYuiWebServer(store, dependencies = {}) {
         });
     });
     server.on("upgrade", (request, socket, head) => {
-        void handleTerminalUpgrade(request, socket, head, webSocketServer, dependencies.terminal, token);
+        void handleTerminalUpgrade(request, socket, head, webSocketServer, dependencies.terminal, token, access);
     });
     let terminalsClosed = false;
     const closeTerminals = () => {
@@ -71,24 +79,36 @@ export function createYuiWebServer(store, dependencies = {}) {
         webSocketServer.close();
     };
     server.on("close", closeTerminals);
-    return Object.assign(server, { closeTerminals });
+    return Object.assign(server, { closeTerminals, access });
 }
 export async function startYuiWebServer(store, options, dependencies = {}) {
-    const server = createYuiWebServer(store, dependencies);
-    await new Promise((resolve, reject) => {
-        server.once("error", reject);
-        server.listen(options.port, options.host, () => {
-            server.off("error", reject);
-            resolve();
+    const server = createYuiWebServer(store, dependencies, options);
+    try {
+        await new Promise((resolve, reject) => {
+            server.once("error", reject);
+            server.listen(options.port, options.host, () => {
+                server.off("error", reject);
+                resolve();
+            });
         });
-    });
+    }
+    catch (error) {
+        server.closeTerminals();
+        throw error;
+    }
     return server;
 }
-async function handleHttpRequest(request, response, store, dependencies, token, now) {
+async function handleHttpRequest(request, response, store, dependencies, token, now, access) {
     setSecurityHeaders(response);
     const method = request.method ?? "GET";
-    if (!isLoopbackHost(headerValue(request, "host"))) {
-        sendJson(response, 403, { error: "Invalid Host.", disposition: "not-submitted" }, method === "HEAD");
+    const previewAuthenticated = dependencies.previews?.authenticated(request) === true;
+    if (!access.acceptsHost(request) || !access.acceptsOrigin(request, access.lan && method !== "GET" && method !== "HEAD", previewAuthenticated)) {
+        sendJson(response, 403, { error: "Invalid Host or Origin.", disposition: "not-submitted" }, method === "HEAD");
+        return;
+    }
+    if (!previewAuthenticated && !access.authenticated(request)) {
+        response.setHeader("www-authenticate", 'Basic realm="Yui Web", charset="UTF-8"');
+        sendJson(response, 401, { error: "Web authentication required. Use username yui and the configured password. To revoke access, stop Web; to rotate the password, replace the credential file and restart Web.", disposition: "not-submitted" }, method === "HEAD");
         return;
     }
     let pathname;
@@ -99,7 +119,8 @@ async function handleHttpRequest(request, response, store, dependencies, token,
         sendJson(response, 400, { error: "Invalid URL.", disposition: "not-submitted" }, method === "HEAD");
         return;
     }
-    // The loopback page token is the actual user ingress. A request body cannot
+    // Authentication precedes every document/preview. The page token remains
+    // an independent CSRF boundary. A request body cannot
     // select Operator/Leader authority; all API reads use this boundary too.
     if (pathname.startsWith("/api/") && !tokenMatches(headerValue(request, "x-yui-web-token"), token)) {
         sendJson(response, 403, { error: "Invalid Yui web token.", disposition: "not-submitted" }, method === "HEAD");
@@ -714,10 +735,10 @@ async function handleHttpRequest(request, response, store, dependencies, token,
     response.setHeader("allow", "GET, HEAD");
     sendJson(response, 405, { error: "Method not allowed.", disposition: "not-submitted" }, method === "HEAD");
 }
-async function handleTerminalUpgrade(request, socket, head, webSocketServer, terminalPort, token) {
+async function handleTerminalUpgrade(request, socket, head, webSocketServer, terminalPort, token, access) {
     try {
         const url = new URL(request.url ?? "/", "http://localhost");
-        if (!isLoopbackHost(headerValue(request, "host"))) {
+        if (!access.acceptsHost(request) || !access.acceptsOrigin(request, true) || !access.authenticated(request)) {
             rejectUpgrade(socket, 403, "Forbidden");
             return;
         }
@@ -1079,26 +1100,6 @@ function headerValue(request, name) {
     const value = request.headers[name];
     return Array.isArray(value) ? value[0] : value;
 }
-function isLoopbackHost(value) {
-    if (value === undefined)
-        return false;
-    let url;
-    try {
-        url = new URL(`http://${value}`);
-    }
-    catch {
-        return false;
-    }
-    if (url.username.length > 0
-        || url.password.length > 0
-        || url.pathname !== "/"
-        || url.search.length > 0
-        || url.hash.length > 0) {
-        return false;
-    }
-    const hostname = url.hostname.toLowerCase();
-    return hostname === "localhost" || hostname === "127.0.0.1" || hostname === "[::1]";
-}
 function safeIdentity(value, label) {
     if (value === null || !/^[A-Za-z0-9][A-Za-z0-9._-]*$/u.test(value)) {
         throw new Error(`${label} is invalid.`);
@@ -1122,8 +1123,8 @@ function escapeHtmlAttribute(value) {
         .replaceAll(">", "&gt;");
 }
 function webUsageError() {
-    return usageError("Web usage: yui web [--host <loopback>] [--port <port>].", webUsage());
+    return usageError("Invalid Web options.", webUsage());
 }
 function webUsage() {
-    return "Usage: yui web [--host <127.0.0.1|::1|localhost>] [--port <1-65535>]";
+    return "Usage: yui web [--host <IP|localhost>] [--port <1-65535>] [--auth-file <absolute-path>]";
 }

package/docs/architecture/capabilities-and-resources.md

@@ -122,12 +122,14 @@ catalog; there is no second catalog or Host. A CLI contribution uses the
 capability's original name. A Web panel accepts only controlled text, an HTTP(S)
 link or a JSON query description — not author scripts or arbitrary HTML.
 
-The Web listener is started and stopped by the Controller and allows loopback
-only (`127.0.0.1`, `::1` or `localhost`; default port 4173). `yui web` opens this
-local surface, not a remote multi-user service or an OS sandbox.
+The Controller owns the single Web listener, defaulting to `127.0.0.1:4173`.
+Explicit trusted-LAN binding requires a private credential file; authentication
+precedes documents, APIs, previews and Terminal. See [controlled Web access](../web-access.md).
+Current Operator lifecycle calls are revalidated separately from browser access.
+This is still a single-user surface, not a multi-user service or an OS sandbox.
 
 The page supplies a token that authenticates all HTTP API reads and writes via
-`x-yui-web-token`; the server also checks the loopback Host. These controls act
+`x-yui-web-token`; the server also checks exact allowed Host/port and Origin. These controls act
 as the trusted local user, not a Role selected by the request body. They support
 Task metadata edits, messages, InputRequest answers, and explicit
 `queue / steer / interrupt` for Task or Global Roles. Managed Agent capability

package/docs/architecture/capabilities-and-resources.zh-CN.md

@@ -88,12 +88,13 @@ Surface contribution 由 Registry 当前获授权目录派生，没有第二份
 CLI contribution 使用能力原名称。Web panel 只接受受控 text、HTTP(S) link 或
 JSON query 描述，不接受作者脚本或任意 HTML。
 
-Web listener 由 Controller 启停，仅允许 loopback（`127.0.0.1`、`::1` 或
-`localhost`；默认端口 4173）。`yui web` 打开的是本地 Surface，不是远程多用户
-服务或 OS 沙箱。
+唯一 Web listener 由 Controller 启停，默认 `127.0.0.1:4173`。显式可信内网
+监听要求私有凭证文件，在页面、API、预览和 Terminal 之前认证。
+当前 Operator 的生命周期权限与浏览器访问分开复核。
+详见[受控 Web 访问](../web-access.md)；它仍是单用户 Surface，不是多用户服务或 OS 沙箱。
 
 页面提供 token，通过 `x-yui-web-token` 认证所有 HTTP API 读取与写入；服务端
-也检查 loopback Host。这些控制使用受信任本地用户身份，不由请求正文选择 Role。
+也检查精确允许的 Host/端口和 Origin。这些控制使用受信任本地用户身份，不由请求正文选择 Role。
 它们支持修改 Task 元数据、发送消息、回答 InputRequest，以及对 Task 或 Global
 Role 显式 `queue / steer / interrupt`。受管 Agent 的能力 RPC 仍使用自身 Session
 认证与范围；浏览器 token 不是 Agent 或插件绕过这些边界的途径。

package/docs/cli-information-contract.md

@@ -54,10 +54,22 @@ use family discovery when a broader requirement/history audit is needed.
   budget inside a 32 KiB response budget. Single inline values are at most
   2 KiB; large values and Message/Run/WorkItem/Knowledge bodies use references.
   Each collection contributes at most eight sampled records at entry.
-- Global entry samples up to eight unacknowledged inputs, including claimed or
-  uncertain ones. It does not repeat recent history, Profile bodies, frozen Skill
+- Global entry samples up to eight current-turn/available inputs, including
+  uncertain ones. Historical missing receipts are a separate count and explicit
+  `inbox list --view history` read; absence of ACK is not proof of unexecuted work.
+  Continue its pending page with `role message list <role> --current --cursor`.
+  It does not repeat recent history, Profile bodies, frozen Skill
   packages or accumulated retry details. The Manifest is the Profile pointer;
   explicit Message and Session retry reads retain history and original evidence.
+- `inbox list --view current|history|all` uses the current managed identity,
+  prioritizes exact current-turn input and shares originals with automatic
+  delivery. `claim` and `ack` accept 1–16 exact IDs with independent results.
+  ACK records semantic disposition (including legal routing or supersession),
+  not Task completion. Exact terminals emit one bounded handling check without
+  ACK or business replay; reminder-only input cannot self-wake indefinitely.
+  `inbox retire` disposes only obsolete proven-unsubmitted Global input with an
+  explicit reason, preserving its original target. Task retirement remains
+  the Leader's existing `task message retire` operation.
 - Run entry samples up to eight records per live category and 16 frozen refs.
   Pointer continuation uses `--view refs` and `pointerPage.nextCursor`; full pack
   document continuation uses `--view full`. Neither changes the frozen authority.

package/docs/cli-information-contract.zh-CN.md

@@ -44,8 +44,16 @@ Run 列表接受 Task 或 `task/work` 目标。
 - 当前 Task Context 至多 64 条，记录与 attention 共 24 KiB，响应预算 32 KiB。
   单个内联值至多 2 KiB；大值及 Message/Run/WorkItem/Knowledge 正文用引用。
   入口每个集合最多抽样八条。
-- Global 入口最多八条未确认处理的输入，保留已领取或效果未知项；不重复 recent、
+- Global 入口最多八条本轮/可用输入，保留效果未知项；历史缺回执单独计数，
+  通过 `inbox list --view history` 显式发现，不把缺 ACK 当作未执行。
+  pending 页用 `role message list <role> --current --cursor` 续读；不重复 recent、
   Profile 正文、历史 Skill 包和累计 retry 详情。Profile 由 Manifest 精确指向。
+- `inbox list --view current|history|all` 优先展示精确本轮输入，与自动投递共用原始记录。
+  `claim`、`ack` 接受 1–16 个精确 ID，分别返回结果。ACK 表示语义处置，
+  包括合法转交或被后续要求替代，不等于 Task 完成。
+  精确终态只生成一次有界检查通知，不自动 ACK 或重放业务；纯提醒不会无限自唤醒。
+  `inbox retire` 仅显式退役已过时且可证明未提交的 Global 输入，保留原始目标和理由；
+  Task 输入继续使用 Leader 的 `task message retire`。
 - Run 入口最多 16 个冻结引用和每类八条活跃观察，附总数。`--view refs` 配合
   `pointerPage.nextCursor` 发现更多引用；`--view full` 显式读取完整冻结包。
   若 `input.directiveOmitted` 为 true，行动前用 `--view input` 全文读取分配指令；

package/docs/project-delivery-scope.md

@@ -0,0 +1,59 @@
+# Task Project delivery scope
+
+Project bindings, delivery obligations, observed code changes and remote merge
+facts have different meanings. A Task may retain a temporary implementation in
+one Project while delivering its accepted result from another. Do not delete a
+binding or fabricate a Publication to express that decision.
+
+Read the original scope instruction and `yui task remote-delivery <task>`.
+An authorized user, Operator or current delivery Leader can record one bounded,
+append-only decision:
+
+```sh
+yui task project delivery task-1 project-2 \
+  --requirement excluded \
+  --reason "The accepted standalone implementation replaces the temporary one" \
+  --source-message message-3 \
+  --purpose "Only deliver the standalone implementation" \
+  --if-current none
+```
+
+The Message must be original user/Operator input in this Task and the purpose
+must be an exact quote. The Agent judges whether it authorizes this Project
+change, including an explicit delegation of scope judgment; the CLI verifies
+identity/provenance, not natural-language permission. A Role report, convenient
+reason or invented quote is not authorization to abandon unmet requirements.
+
+Use the latest `scopeDecision.id` from remote-delivery instead of `none` for
+subsequent decisions. To restore delivery, record `--requirement required` with
+its current guard and an appropriate original source. A stale guard fails
+without overwriting the current decision. After an uncertain write, inspect
+the decision before retrying; do not issue a new decision blindly.
+
+Active and completed, unarchived Tasks with enabled execution accept these
+management decisions. Completed Tasks stay completed; frozen heads, acceptance
+and Publication history remain intact. No new execution or cleanup permission
+is created. Archived, cancelled and stopped Tasks cannot use this operation to
+resume or replace lifecycle intent.
+
+The shared projection exposes `deliveryRequirement`, `scopeDecision` and
+`deliveryRequired` alongside unchanged `codeDelivery` and merge/verification
+facts. `codeProjectCount` still counts all changed or unknown Projects;
+`requiredCodeProjectCount` is the obligation denominator, and
+`excludedProjectCount` identifies explicit exclusions. Aggregate merged/verified
+counts and `allMerged`/`allVerified` cover required code Projects only. A zero
+denominator yields `status: none` (no delivery obligation), not evidence that
+excluded code was merged. Missing heads/bases are unknown, never no-change.
+
+CLI, current context, Web and ordinary archive use that projection. An unchanged
+Project needs no exclusion; a required changed Project needs exact verified
+remote coverage. Ordinary archive still requires settled WorkItems, inputs,
+reviews, integrations/jobs and stopped execution. Physical cleanup separately
+protects dirty files and excluded, unverified local commits. Logical archive can
+succeed with retained resources, which remain owned and inspectable through
+archive diagnostics and explicit cleanup. Exclusion never authorizes deletion
+or force archive, nor changes Project-global state.
+
+Storage 1.11 → 1.12 only admits the new event semantics through the centralized
+minor upgrade chain. It does not rewrite old records or invent scope decisions.
+No new table, workflow state, scan or background recovery service is added.