@zq-silk/yui 0.16.0 → 0.16.1

package/dist/cli/updatePorts.js

@@ -355,6 +355,7 @@ function stopReplacementControllerForUpdate(home, expectedPid, environment, spaw
 function runSchemaIndependentControllerStop(home, environment, spawn, expectedPid) {
     const helper = [
         "const values = process.argv.slice(1);",
+        "const handoverOwnerPid = Number(values.pop());",
         "const expectedPid = values.length === 3 ? Number(values.pop()) : undefined;",
         "const home = values.pop();",
         "const runtimeModule = values.pop();",
@@ -362,6 +363,7 @@ function runSchemaIndependentControllerStop(home, environment, spawn, expectedPi
         "  const { stopFileTaskController } = await import(runtimeModule);",
         "  const data = await stopFileTaskController(home, {",
         "    environment: process.env,",
+        "    handoverOwnerPid,",
         "    ...(expectedPid === undefined ? {} : { expectedPid })",
         "  });",
         "  process.stdout.write(JSON.stringify({ ok: true, data }));",
@@ -377,7 +379,10 @@ function runSchemaIndependentControllerStop(home, environment, spawn, expectedPi
         helper,
         UPDATE_CLIENT_RUNTIME_PATH,
         home,
-        ...(expectedPid === undefined ? [] : [String(expectedPid)])
+        ...(expectedPid === undefined ? [] : [String(expectedPid)]),
+        // The runtime validates the existing lock owner; the child must identify
+        // its owning updater instead of waiting on the parent's lock as foreign.
+        String(process.pid)
     ], { cwd: process.cwd(), env: { ...environment, YUI_HOME: home }, shell: false });
     if (result.error !== undefined || result.status !== 0) {
         const detail = result.stderr.toString("utf8").trim();
@@ -491,10 +496,11 @@ function restoreControllerIdentity(home, identity, environment, spawn) {
     // Spawn a detached child through a short-lived Node helper so the synchronous
     // update process can still use the authenticated, bounded readiness handshake
     // shared by Controller startup. No retry, sleep, or new identity inference is
-    // hidden here.
+    // hidden here. Restoration participates in the same parent-owned lock.
     const helper = [
         "const { spawn } = require('node:child_process');",
         "const values = process.argv.slice(1);",
+        "const handoverOwnerPid = Number(values.pop());",
         "const version = values.pop();",
         "const args = JSON.parse(values.pop());",
         "const executable = values.pop();",
@@ -504,6 +510,7 @@ function restoreControllerIdentity(home, identity, environment, spawn) {
         "  const { ensureFileTaskControllerIdentity } = await import(runtimeModule);",
         "  await ensureFileTaskControllerIdentity(home, { executablePath: executable, args, version }, {",
         "    environment: process.env,",
+        "    handoverOwnerPid,",
         "    spawnController: (_home, launchEnv) => {",
         "      const child = spawn(executable, args, { detached: true, stdio: 'ignore', env: launchEnv });",
         "      child.unref();",
@@ -518,7 +525,8 @@ function restoreControllerIdentity(home, identity, environment, spawn) {
         home,
         identity.executablePath,
         JSON.stringify(identity.args),
-        identity.version
+        identity.version,
+        String(process.pid)
     ], { cwd: process.cwd(), env: launchEnvironment, shell: false, stdio: "pipe" });
     assertSpawnOk(result, "restore the previously running Controller identity");
 }

package/docs/release-workflow.md

@@ -27,6 +27,21 @@ system sits behind `ReleaseWorkflowPorts`
 external ports exercise recovery without real GitHub, npm, git, Controller,
 or model effects.
 
+## Controller handover fix in 0.16.1
+
+The updater's stop and exact-identity restoration children now explicitly receive
+the parent updater's handover-lock owner identity. They no longer wait on their
+own parent's lock; unrelated callers remain fenced. Storage remains at version 37.
+
+An already-installed older updater, including 0.15.12 or 0.16.0, cannot gain this
+fix merely by staging the new package. If it reports `CONTROLLER_HANDOVER_TIMEOUT`
+before activation, inspect the original Controller and lock ownership. Once the
+failed updater has released its own lock and the original Controller is confirmed
+healthy, normally stop it with that installed release's `yui controller stop`,
+then retry `yui update`. This preserves managed Agent Sessions and retains the
+normal preflight, backup, migration and verification boundaries. Do not delete
+an active lock or force-kill a Controller to bypass the failure.
+
 ## Pre-1.0 contract cleanup
 
 Version 0.16.0 retires runtime compatibility before the final

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

@@ -20,6 +20,18 @@ Agent 选择一个预先声明的计划，设施从持久状态驱动该计划
 （`src/release/releaseWorkflowPorts.ts`）之后。可用临时 SQLite 和确定性的外部端口测试
 恢复逻辑，无需真实 GitHub、npm、git、Controller 或模型效果。
 
+## 0.16.1 的 Controller 交接修复
+
+升级器的停止与精确身份恢复子进程，现在显式接收父升级进程的交接锁归属身份，
+不再等待自己父进程持有的锁；无关调用仍被阻止。存储版本保持 37。
+
+已经安装的旧升级器（包括 0.15.12、0.16.0）不会因为暂存新包而提前获得此修复。
+若其在激活前报告 `CONTROLLER_HANDOVER_TIMEOUT`，先检查原 Controller 和锁的归属。
+确认失败的升级器已释放自己的锁、原 Controller 仍健康后，使用已安装版本的
+`yui controller stop` 正常停止 Controller，再重试 `yui update`。此操作保留受管
+Agent Session，仍完整执行预检、备份、迁移和验证；不要删除活动锁或强杀 Controller
+来绕过失败。
+
 ## 1.0 前的契约清理
 
 版本 `0.16.0` 先清退运行时兼容分支，尚未执行最终 1.0 基线切换，也不重置

package/docs/testing/verification-levels.md

@@ -245,7 +245,10 @@ artifact and provenance boundaries. This validates runtime integration, not
 real-model behavior. Pure contract and safety tests remain in `test/core`;
 production wiring is exercised here rather than only through mocked ports.
 The package smoke also checks unconditional status identity and update-owned
-resource/identity capture through the assembled package, without an installation
+resource/identity capture through the assembled package. Real lifecycle children
+stop the exact Controller and restore its captured launch identity while their
+parent holds the handover lock. Unrelated callers remain fenced, the lock stays
+owned by the parent, and durable input survives. These checks have no installation
 or publication effect.
 
 Configured Agents acting as developers or reviewers are ordinary execution

package/docs/testing/verification-levels.zh-CN.md

@@ -175,7 +175,9 @@ npm bin、依赖、受支持 Node 版本、产物和 provenance 边界。这证
 真实模型行为。纯契约与安全检查保留在 `test/core`，生产组件组装在这里验证，
 不只依赖模拟端口。
 组装包检查还验证固定身份输出，以及升级侧通过组装包采集资源和精确 Controller 身份，
-不执行安装或发布效果。
+并在父进程持有交接锁时，通过真实生命周期子进程停止精确 Controller、恢复其已捕获的
+启动身份。无关调用仍被锁阻止，锁保持由父进程持有，持久输入不变；
+这些检查不执行安装或发布效果。
 
 作为开发者或审查者的已配置 Agent 是普通执行资源。把一个真实 provider 或模型作为验证
 对象则不同：付费 API、共享 Home、生产系统、真实账号额度以及其他不可丢弃的外部效果，

package/package.json

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