Fix packaged Local Worker startup and add CLI lifecycle controls (#195)

* fix: start packaged local worker

* feat: add CLI local worker lifecycle controls

* docs: update changelog for local worker lifecycle

Author: DeadWaveWave

CHANGELOG.md

@@ -34,9 +34,10 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 - Task: prompt templates for task requirement prefix injection (Global + Project scopes). (#71)
 - Sync-first: multi-client snapshot + revision + SSE `/events` for the worker control surface (Desktop/Web/CLI). (#122)
 - Worker: PTY session streaming over the control surface (`WS /pty`) + ticket→cookie web auth for the Worker Web Shell. (#133)
+- CLI: Local Worker lifecycle controls with `worker status --all` and ownership-safe `worker stop`. (#195)
 
 ### 💅 Changed
-- Worker: packaged Desktop is now local-only for Home Worker, auto-repairs legacy standalone/remote configs on launch, recovers cleanly if local-worker startup fails, and boots the packaged local worker without Electron-only runtime imports. (#162)
+- Worker: packaged Desktop now uses Local Worker mode, auto-repairs legacy standalone/remote configs on launch, recovers cleanly if local-worker startup fails, and boots the packaged local worker without Electron-only runtime imports. (#162, #195)
 - Settings: allow auto-focus to center within the visible canvas (accounts for the primary sidebar). (#166)
 - Workspace canvas: context menus now stay near the pointer, only flip on real overflow, and reorder note/space actions for faster access. (#64)
 - What's New: switched update notes from runtime GitHub compare fetching to release-manifest delivery embedded in each build. (#67)

DEVELOPMENT.md

@@ -176,7 +176,7 @@
 ## 常见问题（FAQ）
 
 -   **为什么我用 `pnpm dev` 启动后，Worker/Web UI 相关功能表现很奇怪（恢复/同步/持久化不生效）？**
-    -   先检查是否启用了 Home Worker（userData 目录下的 `home-worker.json` 中 `mode=local`，或环境变量 `OPENCOVE_WORKER_CLIENT=1`）。
+    -   先检查是否启用了本机 Worker 模式（userData 目录下的 `home-worker.json` 中 `mode=local`，或环境变量 `OPENCOVE_WORKER_CLIENT=1`）。
     -   然后执行一次 `pnpm build` 并重启 App，确保 `out/main/worker.js` 与当前源码一致。
 
 ## 文档地图（按问题找入口）

README_ZH.md

@@ -104,7 +104,7 @@ pnpm dev
 
 OpenCove 提供一个**实验性的 Worker Web UI**，允许你用浏览器打开画布（包括在同一内网的其他设备，例如平板）。
 
-- 在 **Settings → Experimental → Worker Web UI** 中手动开启 **Enable Web UI**（可选：设置固定端口），再启动 Local Worker。
+- 在 **Settings → Experimental → Worker Web UI** 中手动开启 **Enable Web UI**（可选：设置固定端口），再启动本机 Worker。
 - 默认只监听本机回环地址（`127.0.0.1`）。如需内网访问，开启 **LAN Access** 并设置 Web UI 密码。
 - 开发提示：LAN 访问会使用 `out/renderer` 的 build 产物（无 HMR）。修改 UI 后需要先跑 `pnpm build` 再刷新。
 

docs/CLI.md

@@ -20,13 +20,33 @@ CLI 的默认运行模型应满足：
 
 > 具体 transport（IPC vs HTTP/WS）以实现为准，但必须满足上述约束与 `docs/ARCHITECTURE.md` 的边界规则。
 
-## 3. 命令设计规范
+## 3. Worker 生命周期命令
+
+Worker 生命周期属于运行时进程管理问题。参考 [Docker CLI `container stop`](https://docs.docker.com/reference/cli/docker/container/stop/) 的成熟心智：停止命令必须指向明确目标，优先 graceful stop，必要时才强制结束。
+
+OpenCove 的本地转译规则：
+
+- **拓扑名**：跑在本机的 worker 统一叫 **Local Worker / 本机 Worker**；不要在用户文案里引入 Home Worker。
+- **生命周期 owner**：connection file 可标记 `startedBy=cli | desktop`；旧 connection file 缺失时视为 `unknown`。
+- **默认 stop 规则**：`opencove worker stop` 只停止 `startedBy=cli` 的本机 Worker。
+- **保护 Desktop-owned worker**：若目标是 `startedBy=desktop` 或 `unknown`，CLI 默认拒绝；只有显式 `--force` 才允许停止。
+- **目标选择**：如果发现多个本机 Worker，CLI 必须要求 `--user-data <dir>` 或 `--pid <pid>`，禁止猜测。
+- **发现范围**：CLI lifecycle 命令只读取 worker connection file（`worker-control-surface.json`），不把 Desktop 自己的 control surface 当成 Worker。
+- **重复启动**：同一 `userData` 下重复执行 `opencove worker start` 不会创建第二个 Worker；Worker 会输出现有 connection 并退出。
+
+关键不变量：
+
+1. CLI 默认不得误停 Desktop 启动/拥有的 Local Worker。
+2. 同一 `userData` 下最多一个 Worker；跨 `userData` 的多个 Worker 必须显式选目标。
+3. Stop 先发送 `SIGTERM`，超时且用户显式 `--force` 时才允许升级为强制结束。
+
+## 4. 命令设计规范
 
 - 子命令必须按业务领域分组（例如 `space/*`、`session/*`、`worktree/*`、`fs/*`），避免“一把梭”命令集。
 - `query` 类命令默认 `--json` 或直接 JSON 输出；人类可读输出必须可选（例如 `--pretty`）。
 - `command` 类命令必须明确其副作用与 scope（例如空间/挂载/工作目录的解析必须由 usecase/Control Surface 返回，CLI 不得自行猜测 cwd 规则）。
 
-## 4. 对贡献者：扩展 CLI 的正确方式
+## 5. 对贡献者：扩展 CLI 的正确方式
 
 当你需要新增一个 CLI 能力：
 
@@ -35,4 +55,3 @@ CLI 的默认运行模型应满足：
 3. 最后在 CLI 层只做参数解析与输出格式化，不写业务规则。
 
 这样才能保证未来 Web/Remote 复用同一条链路，而不是每个 client 各自实现一套语义。
-

src/app/cli/constants.mjs

@@ -1,3 +1,4 @@
 export const CONTROL_SURFACE_CONNECTION_FILE = 'control-surface.json'
+export const WORKER_CONTROL_SURFACE_CONNECTION_FILE = 'worker-control-surface.json'
 export const DEFAULT_TIMEOUT_MS = 20_000
 export const CONTROL_SURFACE_PROTOCOL_VERSION = 1

src/app/cli/opencove.mjs

@@ -11,6 +11,12 @@ import { invokeAndPrint, invokeControlSurface } from './invoke.mjs'
 import { printUsage } from './usage.mjs'
 import { CONTROL_SURFACE_PROTOCOL_VERSION } from './constants.mjs'
 import { tryHandleMultiEndpointCommands } from './commands/multiEndpoint.mjs'
+import {
+  getWorkerLifecycleStatus,
+  printWorkerLifecycleResult,
+  stopWorkerLifecycle,
+  WorkerLifecycleError,
+} from './workerLifecycle.mjs'
 
 function toErrorMessage(error) {
   if (error instanceof Error) {
@@ -78,6 +84,8 @@ async function main() {
       workerArgs.push('--hostname', hostname)
     }
 
+    workerArgs.push('--started-by', 'cli')
+
     if (advertiseHostname) {
       workerArgs.push('--advertise-hostname', advertiseHostname)
     }
@@ -143,6 +151,41 @@ async function main() {
     return
   }
 
+  if (command === 'worker' && args[1] === 'status' && !endpoint) {
+    const status = await getWorkerLifecycleStatus({
+      all: args.includes('--all'),
+      userData: readFlagValue(args, '--user-data'),
+      timeoutMs,
+    })
+    printWorkerLifecycleResult(status, pretty)
+    return
+  }
+
+  if (command === 'worker' && args[1] === 'stop') {
+    if (endpoint) {
+      process.stderr.write('[opencove] worker stop only supports local workers.\n')
+      process.exit(2)
+    }
+
+    try {
+      const result = await stopWorkerLifecycle({
+        userData: readFlagValue(args, '--user-data'),
+        pid: readFlagValue(args, '--pid'),
+        force: args.includes('--force'),
+        timeoutMs,
+      })
+      printWorkerLifecycleResult(result, pretty)
+      return
+    } catch (error) {
+      if (error instanceof WorkerLifecycleError) {
+        process.stderr.write(`${error.message}\n`)
+        process.exit(2)
+      }
+
+      throw error
+    }
+  }
+
   const capabilitiesRequest = { kind: 'query', id: 'system.capabilities', payload: null }
 
   const connection = endpoint

src/app/cli/usage.mjs

@@ -50,7 +50,10 @@ export function printUsage() {
     `  opencove worker start [--hostname <bindHost>] [--advertise-hostname <host>] [--port <port>] [--user-data <dir>] [--token <token>] [--web-ui-password-hash <hash>] [--approve-root <path>]\n`,
   )
   process.stdout.write(
-    `  opencove worker status [--endpoint <url>] [--token <token>] [--pretty]\n\n`,
+    `  opencove worker status [--all] [--user-data <dir>] [--endpoint <url>] [--token <token>] [--pretty]\n`,
+  )
+  process.stdout.write(
+    `  opencove worker stop [--user-data <dir>] [--pid <pid>] [--force] [--pretty]\n\n`,
   )
   process.stdout.write(`Global Options:\n`)
   process.stdout.write(`  --pretty                 Pretty-print JSON output\n`)