@zq-silk/yui 2.8.0 → 2.8.1

package/dist/cli/updatePorts.js

@@ -776,6 +776,26 @@ function interpretPreflight(result) {
     // error is not a safe preflight — block rather than proceed to a switch.
     const data = parseSuccessEnvelopeData(result);
     if (data === null) {
+        // CLI bootstrap failures use an ok:false envelope on stderr. Preserve its
+        // already-sanitized diagnosis (including recovery guidance), never promote
+        // an error envelope to a successful storage preflight.
+        for (const stream of [result.stderr, result.stdout]) {
+            let failure;
+            try {
+                failure = JSON.parse(stream.toString("utf8").trim());
+            }
+            catch {
+                continue;
+            }
+            if (!isRecord(failure) || failure.ok !== false || typeof failure.message !== "string")
+                continue;
+            return {
+                status: "blocked",
+                stage: "preflight",
+                message: `Staged binary preflight failed (exit ${result.status ?? "null"}): ${failure.message}`,
+                action: "Resolve the reported staged-binary failure using the same Home and matching CLI; do not force the update."
+            };
+        }
         return {
             status: "blocked",
             stage: "preflight",

package/dist/controlPlaneCli.js

@@ -24,6 +24,7 @@ import { operatorOfflineCommand, taskDiagnosticTarget } from "./cli/managedDiagn
 import { assertConfigurationAuthority, assertTaskInvocationScope } from "./cli/invocationAuthority.js";
 import { requireManagedGlobalCaller, requireManagedGlobalReader, ManagedRuntimeDriftError } from "./runtime/managedCaller.js";
 import { sessionCallerEnvironment, requireManagedCaller } from "./runtime/sessionCaller.js";
+import { maintenanceCallerEnvironment } from "./storage/maintenanceCaller.js";
 import { checkCurrentSkills, SKILL_REUSE_RULE } from "./context/currentSkills.js";
 import { roleSkillIds } from "./context/roleSessionContext.js";
 import { hasManagedIdentity } from "./runtime/managedIdentity.js";
@@ -1999,6 +2000,23 @@ async function preflightManagedTaskControlPlane() {
     if (taskFinalReviewInvocation.error !== undefined) {
         throw new Error(taskFinalReviewInvocation.error);
     }
+    if (["doctor", "upgrade", "update"].includes(args[0] ?? "")) {
+        const home = resolveYuiHome(process.env);
+        Object.assign(process.env, maintenanceCallerEnvironment(home, process.env, args[0] !== "doctor"));
+        if (!hasManagedIdentity(process.env)
+            || (process.env.YUI_SESSION_SCOPE === "global" && process.env.YUI_ROLE === "operator")) {
+            if (process.env.YUI_SESSION_SCOPE === "global") {
+                const manifest = assertManagedSessionManifest(home, "global");
+                if (manifest !== undefined && manifest.roleKind !== "operator") {
+                    throw new ManagedRuntimeDriftError("Managed global invocation does not match its Session Manifest.");
+                }
+            }
+            if (taskFinalReviewInvocation.request !== undefined) {
+                throw new Error("Task final-review contract cannot be established by Home maintenance.");
+            }
+            return { contract: undefined, verifiedStore: undefined };
+        }
+    }
     // Desktop clients may carry only their provider-native identity. Resolve
     // command-local hints before any public/Task/Global routing. This reads this
     // Home only, and never creates a Session or mutates its registration.
@@ -2094,11 +2112,6 @@ async function preflightManagedGlobalControlPlane() {
         || manifest.roleKind !== expectedRoleKind)) {
         throw new ManagedRuntimeDriftError("Managed global invocation does not match its Session Manifest.");
     }
-    if (expectedRoleKind === "operator" && ["doctor", "upgrade", "update"].includes(args[0] ?? "")) {
-        // These commands inspect/adopt the storage contract themselves. Requiring
-        // current storage before reaching upgrade would make recovery impossible.
-        return { contract: undefined, verifiedStore: undefined };
-    }
     await assertRuntimeCoherence({ actualHome: home }, {
         checkController: !(expectedRoleKind === "operator" && operatorOfflineCommand(args))
     });

package/dist/storage/maintenanceCaller.js

@@ -0,0 +1,69 @@
+import { join } from "node:path";
+import Database from "../sqlite/driver.js";
+import { hasManagedIdentity } from "../runtime/managedIdentity.js";
+import { ManagedRuntimeDriftError, requireManagedGlobalCaller } from "../runtime/managedCaller.js";
+import { sessionCallerEnvironment } from "../runtime/sessionCaller.js";
+import { validateStoredRecord } from "./recordValidation.js";
+import { inspectSqliteSchema, storageMinorUpgradePlan, validateSqliteSchemaObjects } from "./sqliteSchema.js";
+import { CURRENT_DATABASE_FILENAME } from "./storageSchema.js";
+/**
+ * Maintenance must authenticate before migration, without opening a current-only
+ * business Store. The declared 1.x migrations preserve these Role/Session
+ * envelopes and physical tables. Read only those records in one SQLite snapshot;
+ * this grants no old-format business reads, writes or implicit migration.
+ */
+export function maintenanceCallerEnvironment(home, env, operatorOnly = true) {
+    if (!hasManagedIdentity(env))
+        return env;
+    const db = new Database(join(home, CURRENT_DATABASE_FILENAME), { readonly: true, fileMustExist: true });
+    try {
+        return db.transaction(() => {
+            const schema = inspectSqliteSchema(db);
+            if (storageMinorUpgradePlan(schema.currentVersion) === null) {
+                throw new ManagedRuntimeDriftError("Maintenance cannot authenticate an unsupported Home storage version.");
+            }
+            validateSqliteSchemaObjects(db);
+            const read = (table, where, params) => {
+                const row = db.prepare(`SELECT payload FROM ${table} WHERE ${where}`).get(...params);
+                if (!row)
+                    return null;
+                const value = JSON.parse(row.payload);
+                validateStoredRecord(table, value);
+                return value;
+            };
+            const registry = {
+                getGlobalRole: (name) => read("global_roles", "name=?", [name]),
+                getGlobalRoleSessionSet: (name) => read("global_role_session_sets", "name=?", [name]),
+                getTaskRoleSessionSet: (task, role) => read("role_session_sets", "task_id=? AND role_name=?", [task, role]),
+                listRuntimeSessionCandidates: () => {
+                    // Read canonical sets, not a derived index that could be stale. Only
+                    // active bindings participate, exactly as in normal caller discovery.
+                    const rows = db.prepare(`
+            SELECT 'global_role_session_sets' AS source, payload FROM global_role_session_sets
+            UNION ALL SELECT 'role_session_sets' AS source, payload FROM role_session_sets
+          `).all();
+                    return rows.flatMap(row => {
+                        const set = JSON.parse(row.payload);
+                        validateStoredRecord(row.source, set);
+                        const session = set.sessions[set.activeAgentId];
+                        if (!session || session.status !== "active")
+                            return [];
+                        return [{ owner: set.owner, agentId: session.agentId, adapterId: session.adapterId,
+                                nativeSessionId: session.nativeSessionId, sessionUpdatedAt: set.updatedAt }];
+                    });
+                }
+            };
+            const current = sessionCallerEnvironment(registry, env);
+            if (current.YUI_SESSION_SCOPE !== "global" || current.YUI_ROLE !== "operator") {
+                if (!operatorOnly)
+                    return current; // Doctor keeps normal scoped authorization below.
+                throw new ManagedRuntimeDriftError("Home maintenance requires the user or current Operator, not a Task or custom Role.");
+            }
+            requireManagedGlobalCaller(registry, current);
+            return current;
+        })();
+    }
+    finally {
+        db.close();
+    }
+}

package/dist/storage/sqliteSchema.js

@@ -119,7 +119,7 @@ function objects(db) {
     WHERE name NOT GLOB 'sqlite_*' ORDER BY type,name`).all();
 }
 let expectedObjects;
-function validateSchemaObjects(db) {
+export function validateSqliteSchemaObjects(db) {
     if (expectedObjects === undefined) {
         const reference = new Database(":memory:");
         try {
@@ -161,7 +161,7 @@ export function inspectSqliteSchema(db) {
         throw new SqliteSchemaError("baseline checksum does not match its version.");
     }
     if (version === CURRENT_STORAGE_VERSION)
-        validateSchemaObjects(db);
+        validateSqliteSchemaObjects(db);
     return {
         currentVersion: version, currentChecksum: row.checksum,
         targetVersion: CURRENT_STORAGE_VERSION, targetChecksum: CURRENT_SCHEMA_CHECKSUM,

package/docs/release-workflow.md

@@ -51,6 +51,28 @@ merely to avoid a version decision. Package versions remain distinct from protoc
 and persistent-storage contracts: their compatibility checks and required migrations
 are unchanged, and the storage rules below do not authorize a package release.
 
+### 2.8.1 compatibility and migration notes
+
+This patch fixes maintenance startup for an existing Operator conversation
+that supplies only its native identity, including Codex Desktop. `doctor`,
+`upgrade` and `update` authenticate against the supported Home before requiring
+current storage, so an older Home can reach the updater's read-only preflight.
+Structured preflight failures retain their original diagnosis and recovery
+guidance. Ordinary commands still require current storage and current authority.
+
+Storage remains **1.8**. The existing contiguous **1.0 through 1.8** migration
+chain, backup, maintenance lock and exact Controller handover are unchanged.
+Use `yui update --version 2.8.1`; no manual intermediate upgrade or replacement
+native Session is required for supported Homes. Pre-1.0 / 0.x Home formats are
+outside this release's supported migration contract; no historical authorization
+exception or legacy conversion is introduced.
+
+Verification includes an isolated published 2.7.1 CLI with storage 1.7 and a
+live Controller/Host: one native-only update preserves the original Host and
+native conversation, migrates storage and processes new input afterward.
+Only the external Provider is simulated. Publishing does not update a user's
+global CLI, Home or production Controller.
+
 ### 2.8.0 compatibility and migration notes
 
 This minor adds native metabridge model management: provider configuration,

package/docs/release-workflow.zh-CN.md

@@ -36,6 +36,22 @@ Agent 选择一个预先声明的计划，设施从持久状态驱动该计划
 不能将不兼容冒称为兼容，也不为回避版本选择新增历史兼容机制。包版本与协议、
 持久存储契约仍然独立：兼容性检查和必要迁移要求不变，下文存储规则不授予发版权限。
 
+### 2.8.1 兼容性及迁移说明
+
+本 patch 修复已有 Operator 会话仅携带 native 身份（包括 Codex Desktop）时的
+维护启动循环。`doctor`、`upgrade`、`update` 先在受支持的旧 Home 上验证调用者，
+不再要求存储已经升级才能进入只读预检。结构化预检失败保留原始诊断与恢复指引；
+普通业务命令仍要求当前存储格式和有效权限。
+
+存储仍为 **1.8**，已有 **1.0 至 1.8** 连续迁移链、备份、维护锁和精确 Controller
+交接保持不变。可使用 `yui update --version 2.8.1`；受支持的 Home 不需要手工先做
+中间升级或更换 native 会话。1.0 之前／0.x Home 格式不在本次迁移支持范围内，
+本版本不引入旧格式转换或历史授权例外。
+
+隔离验证使用真实已发布的 2.7.1 CLI、1.7 Home 和运行中的 Controller/Host：
+一次 native-only update 保留原 Host 与 native 会话，完成存储迁移并继续处理新输入。
+仅外部 Provider 使用确定性模拟。发布不会更新用户真实全局 CLI、Home 或生产 Controller。
+
 ### 2.8.0 兼容性及迁移说明
 
 本 minor 新增原生 metabridge 模型管理：提供商配置、模型目录缓存，以及经受支持

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zq-silk/yui",
-  "version": "2.8.0",
+  "version": "2.8.1",
   "description": "Local control plane for long-running native agent CLI sessions backed by tmux.",
   "license": "MIT",
   "private": false,