glasspane-install 1.21.0 → 1.23.0

package/README.md

@@ -10,14 +10,15 @@ macOS 14+.
 ## Channels / 安装渠道
 
 ```bash
-# 1) Fetch, then run (recommended): install.sh clones the pinned release tag. Two steps on
+# 1) This package via npx (recommended) — also clones the pinned release tag when no local
+#    repo is found, then runs the same flow. It is also the only channel that leaves the
+#    `glasspane` command on PATH; `npm install -g glasspane-install` keeps it there permanently.
+npx glasspane-install
+
+# 2) Fetch, then run: install.sh clones the pinned release tag. Two steps on
 #    purpose — piped into `sh`, a curl that fails leaves stdin empty and the pipeline exits 0.
 curl -fsSL https://raw.githubusercontent.com/jingzhao-l/GlassPane/main/install.sh -o /tmp/gp-install.sh && sh /tmp/gp-install.sh
 
-# 2) This package via npx — also clones the pinned release tag when no local
-#    repo is found, then runs the same flow
-npx glasspane-install
-
 # 3) From an existing checkout
 node installer/cli.js
 ```
@@ -27,9 +28,39 @@ channels clone the **same pinned tag** — never a moving branch — so a fresh
 is reproducible. Override with `GLASSPANE_REF=<tag>` (`main` is available but is not
 a fixed artifact).
 
+An existing clone at the install directory is **advanced**, not ignored and not
+clobbered: if `git status --porcelain` is empty the installer fetches the pinned tag
+and `checkout --detach`s onto it; if it is dirty it refuses, names the files in the
+way, and offers a different `GLASSPANE_INSTALL_DIR`. No `git stash`, no `checkout -f`,
+no `clean` — an installer has no business destroying somebody's uncommitted work
+(that refusal is what replaced the 2026-10-26 shape, where one channel printed "the
+existing clone will not be switched" and then built from a three-versions-old tree
+while the other channel died on git's "already exists and is not an empty directory").
+
 三条渠道最终都走同一份 `installer/cli.js`，且两条一键渠道 clone 的是同一个**钉住的发布 tag**（不是移动的分支），
 所以同一天两次安装拿到的是同一份源码。
 
+安装目录里已经有一棵 clone 时，这一趟**把它前进**到钉住的那个 tag，而不是照用旧树、也不是删掉重来：
+`git status --porcelain` 是空的就 fetch + `checkout --detach`；不空就**拒绝**，点名挡路的那些文件，
+并给出换一个 `GLASSPANE_INSTALL_DIR` 的走法。没有 `git stash`、没有 `checkout -f`、没有 `clean`——
+安装器不该有能把别人的未提交工作抹掉的那一格。
+
+## The `glasspane` command / `glasspane` 这条命令
+
+这个包同时交付 `glasspane`（`bin` 里两个名字，见 `package.json`），回答的是"面板按钮失败了，
+而我不知道自己装到了哪里"：
+
+| 命令 | 做什么 | 退出码 |
+|---|---|---|
+| `glasspane doctor` | 只读这台机器：状态根、安装指针、更新器状态、在册 daemon 作业、socket、两个全局 npm 包；每格答 available / absent / unverified | 0 全在位；3 有格子不在位或答不了 |
+| `glasspane update` | 先 `check`，再装通过校验的那一份；检查停住就不进安装 | 沿用更新器自己的那一档（0/3/4/5） |
+| `glasspane status` | 把更新器那一行结论原样打出来 | 同上 |
+
+它只按 `~/.glasspane/update-install.json` 找那份更新器（安装器写的、面板读的同一份），不从当前目录猜；
+不 sudo、不删东西，需要人做的那一步只点名工具与目录。npm 那一格的补法给的是
+`npm install -g glasspane-mcp@<版本> glasspane-install@<版本>`——那取的是 registry 的发布物，
+与更新器从已校验暂存树里现场打包的那一份是两种来源，这句话也一起说。
+
 ## Flags / 选项
 
 | 选项 | 作用 |

package/cli.js

@@ -70,7 +70,7 @@ export const INSTALL_SH_URL =
 /** 发布线锚点（版本真源 = 根 package.json，由 scripts/set-version.mjs 统一改写，
  *  勿手改）：npx 形态下本地没有仓库时，引导 clone 的就是这个 tag，与 install.sh
  *  的 `GLASSPANE_RELEASE` 同值——两条一键入口必须拿到同一份源码。 */
-export const RELEASE_VERSION = '1.21.0'
+export const RELEASE_VERSION = '1.23.0'
 /** 发布 ref（tag 名）。GLASSPANE_REF 环境变量可覆盖（追主干用 `main`）。 */
 export const REPO_REF = `v${RELEASE_VERSION}`
 
@@ -2304,6 +2304,8 @@ export function bootstrapPlan({
   repoUrl = REPO_URL,
   ref = REPO_REF,
   installDir = null,
+  // 只读探针：注入它，这条纯函数才能被"目录已经存在且是一棵 GlassPane 仓库"这一支单测覆盖。
+  readCloneState = null,
 } = {}) {
   if (!homeDir) {
     return { error: '无法确定用户主目录（HOME 为空），不知道把源码 clone 到哪里' }
@@ -2314,6 +2316,18 @@ export function bootstrapPlan({
       error: `目标目录已存在且不是 GlassPane 仓库：${targetDir}（用 --repo 指定仓库，或清理该目录后重试）`,
     }
   }
+  // 目录存在**且是一棵 GlassPane 仓库**：这一支从前直接往下走 `git clone`，于是产品自己的安装位置
+  // （`~/glasspane`）里那份旧 clone 换来的是 git 的 "destination path … already exists and is not an
+  // empty directory"——读者按提示"换个目录"重跑，下一次又落在同一个地方。现在它前进那棵树，或说清
+  // 为什么不动它（判据见 `existingCloneDecision`）。
+  if (fs.existsSync(targetDir) && typeof readCloneState === 'function') {
+    const state = readCloneState({ targetDir, ref })
+    const decision = existingCloneDecision({ targetDir, ref, ...state })
+    if (decision.action !== 'advance') {
+      return { use: decision.action === 'use', targetDir, refuse: decision.action === 'refuse' ? decision : null, decision }
+    }
+    return { advance: { targetDir, ref, decision } }
+  }
   // 三个值都会进 git argv：ref 来自 GLASSPANE_REF、目录来自 GLASSPANE_INSTALL_DIR，
   // 都是文档里写明的覆盖口子。判据与 install.sh 的 assert_ref/assert_repo_url 同源。
   const clone = safeGitCloneArgs({ repoUrl, ref, targetDir })
@@ -2325,6 +2339,174 @@ export function bootstrapPlan({
   }
 }
 
+/**
+ * 既有 clone 的结论（纯判定，可单测）。
+ *
+ * 为什么这一格不能像以前那样"提示一句就照用"：`~/glasspane` 是产品自己的安装位置，`install.sh` 与
+ * `npx glasspane-install` 都往那里 clone。上一版在这里只打印"既有 clone 不会被自动切到 v1.21.0"，
+ * 然后**照用那棵树**去构建——2026-10-26 这台机器上那是 v1.5.0 的 clone，于是"一键安装"把一个 1.5.0
+ * 的产物当成新装交出去，而 `npx` 那条路更糟：它直接对已存在目录跑 `git clone`，被 git 以
+ * "destination path … already exists and is not an empty directory" 拒掉，读者只剩"换目录"这一条死路。
+ *
+ * 判据按那个人 2026-10-26 选的形状：
+ *   · 干净（`git status --porcelain` 空）且 HEAD 已经是那个 tag ⇒ 就用；
+ *   · 干净但不是那个 tag ⇒ 前进（fetch + detached checkout —— 这是移动**产品自己的 clone**，
+ *     不是移动任何人的工作树）；
+ *   · 脏 ⇒ 拒绝，点名前 10 个挡路的路径，并给一条不销毁任何东西的出路（换一个空目录）；
+ *   · HEAD 读不出 ⇒ 拒绝。"判不出来"永远不许变成"那就照用/那就切过去"。
+ *
+ * **"该 tag 本地读不出"不是一条拒绝**，2026-10-27 在本机被实测推翻的正是这一格。旧写法把它和
+ * "HEAD 读不出"并成同一句"判不出来就拒"，于是 `~/glasspane`（v1.5.0 的 clone，本地 tag 只到
+ * v1.2.0）在 npm 那条入口上**永远**走到 refuse：`bootstrapPlan` 先问判据、判据先拒，而那一步
+ * 之后**会 fetch 这个 tag 的代码（`advanceExistingClone`）根本轮不到执行**。`install.sh` 那一支
+ * 是对的（先 fetch 再判），两条一键入口对同一棵树给出两种答案——finding 10 那族的老形状。
+ * 现在 tag 缺席归到"前进"里：fetch 不成仍由 `advanceExistingClone` 拒，并交出 git 的原话；
+ * HEAD 读不出照旧是拒。前者是能补的事实缺口，后者是判据本身没了。
+ */
+export function existingCloneDecision({ targetDir, ref, head = null, tagCommit = null, blocking = [] }) {
+  const dirty = blocking.map((line) => String(line).trim()).filter((line) => line !== '')
+  if (dirty.length > 0) {
+    const shown = dirty.slice(0, 10)
+    return {
+      action: 'refuse',
+      blocking: dirty,
+      text: `${targetDir} 有 ${dirty.length} 处未提交改动，安装器不会切走它（切走会把别人的工作当成构建源码）：\n`
+        + shown.map((line) => `    ${line}`).join('\n')
+        + (dirty.length > shown.length ? `\n    …另有 ${dirty.length - shown.length} 处` : '')
+        + `\n下一步（不销毁任何东西，两条都做得动）：`
+        + `\n  a) 换一处干净的家再跑一键安装：GLASSPANE_INSTALL_DIR=~/glasspane-${String(ref).replace(/[^A-Za-z0-9._+-]/g, '_')} `
+        + `sh install.sh（或 npx glasspane-install）；`
+        + `\n  b) 自己收着这些改动：在 ${targetDir} 里把它们提交或转移到别处，再重跑本命令——`
+        + '安装器不替你决定这些文件去哪。',
+    }
+  }
+  if (!head) {
+    return {
+      action: 'refuse',
+      blocking: [],
+      text: `${targetDir} 读不出 HEAD（不是 git 仓库、那目录没有一次提交，或 git 本身答不了）：`
+        + '连"这棵树在哪"都判不出来，就不动它，也不装它。'
+        + `\n下一步：确认 ${targetDir} 是一棵 git 仓库（git -C "${targetDir}" rev-parse HEAD 能不能答话）；`
+        + '要一份全新的 clone 就 GLASSPANE_INSTALL_DIR=<空目录> 重跑一键安装。',
+    }
+  }
+  if (tagCommit && head === tagCommit) {
+    return { action: 'use', blocking: [], head, text: `${targetDir} 已经在 ${ref}（${String(head).slice(0, 7)}），直接用它构建。` }
+  }
+  if (!tagCommit) {
+    return {
+      action: 'advance',
+      blocking: [],
+      head,
+      tagCommit: null,
+      needsFetch: true,
+      text: `${targetDir} 是干净的 clone（HEAD 在 ${String(head).slice(0, 7)}），但本地没有 ${ref} 这个 tag`
+        + '（旧 clone 的 tag 表停在更早的一版，浅历史也会这样）：前进那一步先 fetch 它再切。'
+        + `fetch 不成就是拒——${targetDir} 原地不动，本轮不构建。`,
+    }
+  }
+  return {
+    action: 'advance',
+    blocking: [],
+    head,
+    tagCommit,
+    text: `${targetDir} 是干净的 clone，HEAD 在 ${String(head).slice(0, 7)} 而要装的是 ${ref}（${String(tagCommit).slice(0, 7)}）——`
+      + '把它前进到那一个 tag 再构建。',
+  }
+}
+
+/**
+ * 一棵既有 clone 的四份事实（IO 读，不判定）：HEAD 指向的 commit、`ref^{commit}`、
+ * `git status --porcelain` 的行，以及这份 clone 是不是浅仓。判据一律在 `existingCloneDecision`，
+ * 两处调用（bootstrap 的纯计划、前进这一步的复判）共用同一份读数，避免出现第二个"什么算脏"的说法。
+ *
+ * `shallow` 是给 fetch 挑形状的：`--depth 1` 会把一棵**完整**的 clone 变成浅仓（`.git/shallow`
+ * 一旦落下，之后的遍历都撞上人为边界，要恢复得 `git fetch --unshallow`）。旧写法对任何树都带
+ * `--depth 1`，而注释写的是"只往 .git 里加对象"——那句话对完整 clone 不成立，它加的是一个边界。
+ * 只有 git 亲口答 `true` 才用 `--depth 1`；答不出来（老 git、不是仓库）按完整仓对待，宁可多取
+ * 一点也不给人家的历史加边界。
+ */
+export function readCloneFacts({ targetDir, ref, spawn = spawnSync } = {}) {
+  const read = (args) => spawn('git', ['-C', targetDir, ...args], { encoding: 'utf8' })
+  const sha = (what) => {
+    const res = read(['rev-parse', '--verify', what])
+    return res.status === 0 ? String(res.stdout ?? '').trim() : null
+  }
+  const status = read(['status', '--porcelain'])
+  const shallow = read(['rev-parse', '--is-shallow-repository'])
+  return {
+    head: sha('HEAD'),
+    tagCommit: sha(`${ref}^{commit}`),
+    // `git status` 答非零时这里得到空数组，读起来是"干净"——那棵树随后会因为 `head` 读不出而被拒，
+    // 所以"判不出来"走的是拒绝那一支，不是"那就切过去"。
+    blocking: status.status === 0 ? String(status.stdout ?? '').split('\n').filter((line) => line !== '') : [],
+    shallow: shallow.status === 0 ? String(shallow.stdout ?? '').trim() === 'true' : null,
+  }
+}
+
+/**
+ * 把既有 clone 前进到钉住的 ref（IO 步；判据全在 `existingCloneDecision` 里）。
+ *
+ * 只有这几种 git 动作：`status --porcelain`、两次 `rev-parse --verify`、`rev-parse
+ * --is-shallow-repository`（全是读），`fetch --tags [origin <ref>]`（只往 .git 里加对象；
+ * 带不带 `--depth 1` 由 git 自己答的那句"是不是浅仓"决定，见 `readCloneFacts`），以及
+ * `checkout --detach <ref>`（只在树干净时执行）。没有 `-f`、没有 `stash`、没有 `clean`、
+ * 没有 `reset --hard`：一个 installer 不该有能把别人的未提交工作抹掉的那一格。
+ */
+export function advanceExistingClone({ repoDir, ref, spawn = spawnSync } = {}) {
+  const read = (args) => spawn('git', ['-C', repoDir, ...args], { encoding: 'utf8' })
+  let facts = readCloneFacts({ targetDir: repoDir, ref, spawn })
+  if (facts.blocking.length === 0 && facts.head && !facts.tagCommit) {
+    // tag 不在这份历史里（旧 clone / 浅 clone 都会这样）：先把它取回来，再判。fetch 失败不改任何东西。
+    const fetchArgs = facts.shallow === true
+      ? ['fetch', '--tags', '--depth', '1', 'origin', ref]
+      : ['fetch', '--tags', 'origin', ref]
+    const fetched = read(fetchArgs)
+    if (fetched.status !== 0) {
+      return {
+        action: 'refuse',
+        blocking: [],
+        fetchArgs,
+        text: `${repoDir} 里没有 ${ref} 这个 tag，而 `
+          + `git -C "${repoDir}" ${fetchArgs.join(' ')} 退出 ${String(fetched.status ?? 'null')}：`
+          + `${String(fetched.stderr ?? '').trim().split('\n')[0] || '（git 没有留下 stderr）'}。\n`
+          + '没有 clone、没有切分支、没有写入任何东西。下一步：确认网络与该 tag 存在（'
+          + `git ls-remote --tags origin ${ref}），或 GLASSPANE_INSTALL_DIR=<空目录> 换一处全新的 clone。`,
+      }
+    }
+    facts = readCloneFacts({ targetDir: repoDir, ref, spawn })
+  }
+  let decision = existingCloneDecision({ targetDir: repoDir, ref, ...facts })
+  if (decision.action !== 'advance') return decision
+  const out = read(['checkout', '--detach', ref])
+  if (out.status !== 0) {
+    return {
+      action: 'refuse',
+      blocking: readCloneFacts({ targetDir: repoDir, ref, spawn }).blocking,
+      text: `切到 ${ref} 没成（git checkout --detach 退出 ${String(out.status ?? 'null')}）：`
+        + `${String(out.stderr ?? '').trim().split('\n')[0] || '（git 没有留下 stderr）'}。\n`
+        + `${repoDir} 仍在 ${String(facts.head ?? '读不出').slice(0, 7)}，本轮没有构建任何东西。`,
+    }
+  }
+  // 切完再读一次：判据要落在**切换之后**的事实上，不是落在命令的退出码上。
+  const after = readCloneFacts({ targetDir: repoDir, ref, spawn })
+  const recheck = existingCloneDecision({ targetDir: repoDir, ref, ...after })
+  if (recheck.action !== 'use') {
+    return {
+      action: 'refuse',
+      blocking: after.blocking,
+      text: `切完之后 ${repoDir} 还不是 ${ref}（HEAD=${String(after.head ?? '读不出').slice(0, 7)}，`
+        + `tag=${String(after.tagCommit ?? '读不出').slice(0, 7)}，另有 ${after.blocking.length} 处改动）：本轮不拿它构建。`,
+    }
+  }
+  return {
+    ...recheck,
+    advanced: true,
+    from: facts.head,
+    text: `${repoDir} 从 ${String(facts.head ?? '读不出').slice(0, 7)} 前进到 ${ref}（${String(after.head).slice(0, 7)}），用它构建。`,
+  }
+}
+
 /** 未定位到仓库时的指引文本（纯函数，可单测）。 */
 export function repoMissingText() {
   return [
@@ -2531,31 +2713,50 @@ export async function install({
       installDir: env.GLASSPANE_INSTALL_DIR ?? null,
       repoUrl: env.GLASSPANE_REPO_URL ?? REPO_URL,
       ref: pinRef,
+      readCloneState: ({ targetDir, ref }) => readCloneFacts({ targetDir, ref }),
     })
     if (plan.error) {
       throw new Error(`${plan.error}\n\n${repoMissingText()}`)
     }
-    printStep(`未定位到本地仓库，引导 clone：${plan.targetDir}（ref: ${plan.ref}）……`)
-    // stderr 要留着归因（finding 9）：任何非零都算"网络不可达或 tag 不存在"会把
-    // "目标目录已存在且非空"这类本地故障说成网络问题，读者据此一直重试同一条死路。
-    const clone = spawnSync('git', plan.gitArgs, {
-      stdio: ['inherit', 'inherit', 'pipe'],
-      encoding: 'utf8',
-    })
-    if (clone.status !== 0) {
-      throw new Error(
-        `${cloneFailureText({
-          ref: plan.ref,
-          status: clone.status,
-          stderr: clone.stderr ?? clone.error?.message ?? '',
-          targetDir: plan.targetDir,
-        })}\n\n${repoMissingText()}`,
-      )
-    }
-    if (resolveProjectRoot(plan.targetDir) === null) {
-      throw new Error(`clone 完成但目录结构不完整：${plan.targetDir}\n\n${repoMissingText()}`)
+    // 目录里已经有一棵 GlassPane 仓库：要么用它（已经在钉的那个 tag 上），要么前进它，要么说清为什么
+    // 不动它。三条都是**结论**，没有一条是"那就 clone 试试，让 git 去报错"。
+    if (plan.refuse) {
+      throw new Error(`${plan.refuse.text}\n\n${repoMissingText()}`)
+    }
+    if (plan.use) {
+      printStep(plan.decision.text)
+      rootDir = plan.targetDir
+    } else if (plan.advance) {
+      printStep(plan.advance.decision.text)
+      const advanced = advanceExistingClone({ repoDir: plan.advance.targetDir, ref: plan.advance.ref })
+      if (advanced.action !== 'use') {
+        throw new Error(`${advanced.text}\n\n${repoMissingText()}`)
+      }
+      printStep(advanced.text)
+      rootDir = advanced.targetDir ?? plan.advance.targetDir
+    } else {
+      printStep(`未定位到本地仓库，引导 clone：${plan.targetDir}（ref: ${plan.ref}）……`)
+      // stderr 要留着归因（finding 9）：任何非零都算"网络不可达或 tag 不存在"会把
+      // "目标目录已存在且非空"这类本地故障说成网络问题，读者据此一直重试同一条死路。
+      const clone = spawnSync('git', plan.gitArgs, {
+        stdio: ['inherit', 'inherit', 'pipe'],
+        encoding: 'utf8',
+      })
+      if (clone.status !== 0) {
+        throw new Error(
+          `${cloneFailureText({
+            ref: plan.ref,
+            status: clone.status,
+            stderr: clone.stderr ?? clone.error?.message ?? '',
+            targetDir: plan.targetDir,
+          })}\n\n${repoMissingText()}`,
+        )
+      }
+      if (resolveProjectRoot(plan.targetDir) === null) {
+        throw new Error(`clone 完成但目录结构不完整：${plan.targetDir}\n\n${repoMissingText()}`)
+      }
+      rootDir = plan.targetDir
     }
-    rootDir = plan.targetDir
   }
 
   // 发布 tag GPG 验签：先过"这次到底验不验"的门（形状/存在性），再判动作，两条判据都是纯函数。

package/glasspane.js

@@ -0,0 +1,370 @@
+#!/usr/bin/env node
+/**
+ * `glasspane` — the one command an installed machine should need.
+ *
+ * Why this file exists. Until 2026-10-26 the machine had two ways to update itself and neither was a
+ * command a person would remember: the settings panel's button (which runs the updater as the *GUI's*
+ * child, and whose failure this package could not distinguish from the daemon's refusal to be restarted),
+ * and `node <那个 checkout>/updater/cli.js apply` (which needs the install root, which is exactly the
+ * thing people lose track of). The other complaint measured the same day: `npx glasspane-install` re-ran
+ * `git clone` into `~/glasspane`, git said "destination path … already exists", and the reader was told
+ * to change directory — forever, because the next run would look in the same place.
+ *
+ * So this is a *thin* bin, added to the same package that already owns the one-command install (adding a
+ * third bare-name package would be a third thing to version, sign and keep in step):
+ *
+ *   glasspane update   ask for an update and run it, through the updater this machine is already
+ *                      installed with — never through a copy guessed from the current directory
+ *   glasspane doctor   read the machine: install pointer, updater state, the loaded daemon job, the
+ *                      socket, and the two global npm packages. Reads only; every line answers
+ *                      available / absent / unverified, because "I could not look" is not "there is
+ *                      nothing there" (`installer/cli.js`'s PROBE_STATES is the same rule)
+ *   glasspane status   the updater's own one-line summary, verbatim
+ *
+ * What it deliberately does not do: no `sudo`, no npm escalation, no deleting anything. Where a repair
+ * needs a person, it prints the tool and the two directories involved, the same way the updater's remedy
+ * sentences do (SECURITY.md §3: a remedy may name a tool, it may not hand out an executable escalation).
+ */
+import fs from 'node:fs'
+import path from 'node:path'
+import os from 'node:os'
+import process from 'node:process'
+import { spawnSync } from 'node:child_process'
+
+export const VERBS = Object.freeze(['update', 'doctor', 'status', 'help'])
+/** 用法里的同义写法：读不出"同一条命令的两种问法"就没有可比性，所以别名是一张明面上的表。 */
+export const VERB_ALIASES = Object.freeze({ '-h': 'help', '--help': 'help' })
+export const DAEMON_JOB_LABEL = 'com.glasspane.daemon'
+export const NPM_PACKAGES = Object.freeze(['glasspane-mcp', 'glasspane-install'])
+/** The three answers a read may give. `unverified` is the one that used to be missing everywhere. */
+export const READS = Object.freeze({ available: 'available', absent: 'absent', unverified: 'unverified' })
+
+const POINTER_NAME = 'update-install.json'
+const STATE_NAME = 'update-state.json'
+
+/** Where this machine keeps GlassPane's state, and who said so. */
+export function stateRootOf({ env = process.env, homeDir = null } = {}) {
+  const named = String(env.GLASSPANE_STATE_DIR ?? '').trim()
+  if (named !== '') return { stateRoot: path.resolve(named), source: 'GLASSPANE_STATE_DIR' }
+  const home = String(homeDir ?? (typeof env.HOME === 'string' && env.HOME !== '' ? env.HOME : safeHomedir()) ?? '').trim()
+  if (home === '') return { stateRoot: null, source: '读不到家目录（HOME 未设置，os.homedir() 也没答）' }
+  return { stateRoot: path.join(home, '.glasspane'), source: '默认（<HOME>/.glasspane）' }
+}
+
+function safeHomedir() {
+  try {
+    return os.homedir()
+  } catch {
+    return null
+  }
+}
+
+/**
+ * The install pointer: the one file that says which updater this machine is installed with. Three states,
+ * because the remedy differs: absent (never installed / a state root that isn't ours), unreadable (a file
+ * that exists and does not parse — a person's problem, not a re-install's), and a pointer whose
+ * `updaterCli` no longer exists on disk (a moved or deleted checkout — §11's whole reason the pointer
+ * exists, and the case where "run the installer again" is the honest answer).
+ */
+export function readInstallPointer({ stateRoot, readFile = (p) => fs.readFileSync(p, 'utf8'), exists = (p) => fs.existsSync(p) } = {}) {
+  if (!stateRoot) return { read: READS.unverified, reason: '没有状态根可读', pointerPath: null }
+  const pointerPath = path.join(stateRoot, POINTER_NAME)
+  let text = null
+  try {
+    text = readFile(pointerPath)
+  } catch (error) {
+    const missing = error?.code === 'ENOENT'
+    return {
+      read: missing ? READS.absent : READS.unverified,
+      reason: missing ? `${pointerPath} 不存在` : `${pointerPath} 读不出来（${error?.message ?? String(error)}）`,
+      pointerPath,
+    }
+  }
+  let pointer = null
+  try {
+    pointer = JSON.parse(text)
+  } catch (error) {
+    return { read: READS.unverified, reason: `${pointerPath} 不是合法 JSON（${error.message}）`, pointerPath }
+  }
+  const updaterCli = typeof pointer?.updaterCli === 'string' && pointer.updaterCli !== '' ? pointer.updaterCli : null
+  if (updaterCli === null) return { read: READS.unverified, reason: `${pointerPath} 里没有 updaterCli 这一项`, pointerPath, pointer }
+  if (!exists(updaterCli)) {
+    return {
+      read: READS.absent,
+      reason: `指针指向的更新脚本不在盘上：${updaterCli}（那份 checkout 被移动或删除了）`,
+      remedy: '重跑一次安装程序（node installer/cli.js 或 curl -fsSL <安装脚本> | sh），它会重写指针并把代理指回稳定入口。',
+      pointerPath,
+      pointer,
+      updaterCli,
+    }
+  }
+  return { read: READS.available, reason: null, pointerPath, pointer, updaterCli, installRoot: pointer?.installRoot ?? null }
+}
+
+/** One child process, answered as data: did it run, what did it print, what did it exit with. */
+export function spawnJson(bin, args, { spawn = spawnSync, timeoutMs = 120_000 } = {}) {
+  const res = spawn(bin, args, { encoding: 'utf8', timeout: timeoutMs })
+  const status = typeof res?.status === 'number' ? res.status : null
+  const stdout = String(res?.stdout ?? '')
+  const stderr = String(res?.stderr ?? '').trim()
+  // Two documents, two shapes, and getting this wrong reads a healthy machine as a silent one:
+  // the updater CLI answers **one line** of JSON (its contract with the panel and `gp_diagnose`), while
+  // `npm ls -g --json` answers **pretty-printed multi-line JSON** (measured here against npm 11). A
+  // reader that took the last line got `}` and reported "npm 答的不是那份 JSON" about a prefix that
+  // named every package on the machine. So: the whole document first, the last line only as a fallback
+  // for a stream that carried a log line before the answer.
+  const parse = (text) => {
+    const trimmed = String(text ?? '').trim()
+    if (trimmed === '') return null
+    try {
+      return JSON.parse(trimmed)
+    } catch {
+      /* not the whole document */
+    }
+    const last = trimmed.split('\n').filter((line) => line !== '').pop()
+    try {
+      return JSON.parse(last)
+    } catch {
+      return null
+    }
+  }
+  const json = parse(stdout)
+  return {
+    read: status === null ? READS.unverified : READS.available,
+    status,
+    json,
+    stdout,
+    stderr,
+    reason: status === null
+      ? `${bin} 没答话（${res?.error?.message ?? String(res?.error ?? '没有退出码')}）`
+      : json === null && stdout.trim() !== ''
+        ? `${bin} 答的不是那份 JSON（前 120 字：${stdout.trim().slice(0, 120)}）`
+        : null,
+  }
+}
+
+/**
+ * The doctor's six readings. Each returns `{ name, read, detail, remedy }`, and `remedy` is only ever the
+ * command this tool can already see working — never an invented path, never an escalation.
+ */
+export function doctorReadings({
+  env = process.env,
+  homeDir = null,
+  readFile = (p) => fs.readFileSync(p, 'utf8'),
+  exists = (p) => fs.existsSync(p),
+  spawn = spawnSync,
+  execPath = process.execPath,
+  uid = null,
+  runLaunchctl = null,
+} = {}) {
+  const { stateRoot, source } = stateRootOf({ env, homeDir })
+  const out = []
+
+  out.push(stateRoot === null
+    ? { name: '状态根', read: READS.unverified, detail: source, remedy: 'export HOME=/Users/<你> 后重跑（这个产品把状态放在家目录下是刻意的）。' }
+    : { name: '状态根', read: READS.available, detail: `${stateRoot}（${source}）`, remedy: null })
+
+  const pointer = readInstallPointer({ stateRoot, readFile, exists })
+  out.push({
+    name: '安装指针',
+    read: pointer.read,
+    detail: pointer.read === READS.available
+      ? `${pointer.updaterCli}（安装根 ${pointer.installRoot ?? '未记'}）`
+      : pointer.reason,
+    remedy: pointer.remedy ?? (pointer.read === READS.unverified ? '这一份是安装器写的 JSON，读不出来通常意味着它被手改过：重跑安装程序覆盖它。' : null),
+  })
+
+  if (pointer.read !== READS.available) {
+    out.push({ name: '更新器状态', read: READS.unverified, detail: '没有可跑的更新脚本，这一格没问', remedy: '先把上面那一格修好。' })
+    out.push({ name: '定时代理', read: READS.unverified, detail: '同上', remedy: null })
+  } else {
+    const status = spawnJson(execPath, [pointer.updaterCli, 'status', '--json', '--state-dir', stateRoot], { spawn })
+    // `status --json` 的那一份文档把状态**整体**放在 `state` 里（顶层只有 command/status/code/
+    // message/exitCode）。在本机量过一次：按顶层读 `current` 得到的是空,于是 doctor 对着一台装着
+    // 1.6.2、最新 1.21.0 的机器答"装着=?"——一个读错字段的读数比不读更容易骗人。
+    const doc = status.json?.state ?? status.json ?? {}
+    out.push(status.read === READS.available && status.json
+      ? {
+        name: '更新器状态',
+        read: READS.available,
+        detail: `status=${status.json.status ?? '?'} 装着=${doc.current ?? '?'} 最新=${doc.latest ?? '未查'} `
+          + `待装=${doc.staged?.version ?? '没有'} code=${status.json.code ?? '无'}`,
+        // 状态里挂着的代号是这台机器**现在**的降级原因（`npm-not-refreshed`、`runtime-stale` 这一类）。
+        // 只把 message 摘要抄过来是不够的：读 doctor 的人要先知道是哪一格,才有办法决定去不去读原话。
+        remedy: status.json.code
+          ? `这一格挂在状态里的代号是 ${status.json.code}：${String(status.json.message ?? status.json.lastError?.message ?? '（没给原话）').slice(0, 200)}`
+          : null,
+      }
+      : { name: '更新器状态', read: READS.unverified, detail: status.reason ?? `${pointer.updaterCli} status 退出 ${status.status}：${status.stderr.slice(0, 160)}`, remedy: null })
+
+    const launchctl = runLaunchctl ?? ((args) => {
+      const res = spawn('launchctl', args, { encoding: 'utf8', timeout: 15_000 })
+      return { status: typeof res?.status === 'number' ? res.status : null, stdout: res?.stdout ?? '', stderr: String(res?.stderr ?? '') + (res?.error ? ` ${res.error.message ?? res.error}` : '') }
+    })
+    const who = uid ?? (typeof process.getuid === 'function' ? String(process.getuid()) : null)
+    const job = who === null
+      ? { read: READS.unverified, detail: '读不到 uid（id -u 没答），所以没问 launchd' }
+      : (() => {
+        const res = launchctl(['print', `gui/${who}/${DAEMON_JOB_LABEL}`])
+        const text = String(res?.stdout ?? '')
+        if (res?.status === 0) {
+          const state = /(?:^|\n)\s*state\s*=\s*(\S+)/.exec(text)
+          return { read: READS.available, detail: `在册作业装载着，state=${state ? state[1] : '未给出'}` }
+        }
+        if (res?.status === 113 || /could not find service|does not exist/i.test(String(res?.stderr ?? ''))) {
+          return { read: READS.absent, detail: `launchd 说它没有 gui/${who}/${DAEMON_JOB_LABEL} 这个作业`, remedy: '重跑安装程序（node installer/cli.js）——它会重新注册 daemon 作业，并在动手前问一句。' }
+        }
+        // 答不了就是答不了：这一支从前把 launchd 的沉默写成"没这个作业"，于是 daemon 明明在册、
+        // doctor 却说它缺席——缺席与不知道是两件事，补救也不同（一个是重装，一个是先让这一问能问出去）。
+        return { read: READS.unverified, detail: `launchctl print 退出 ${String(res?.status ?? 'null')}：${String(res?.stderr ?? '').trim().slice(0, 160) || '没有 stderr'}` }
+      })()
+    out.push({ name: '定时代理', read: job.read, detail: job.detail, remedy: job.remedy ?? null })
+  }
+
+  const socketPath = stateRoot ? path.join(stateRoot, 'engine.sock') : null
+  const socket = socketPath === null
+    ? { read: READS.unverified, detail: '没有状态根，socket 路径无从得出' }
+    : exists(socketPath)
+      ? { read: READS.available, detail: socketPath }
+      : { read: READS.absent, detail: `${socketPath} 不在：daemon 没在跑（或这台机器上它注册在别的状态根）` }
+  out.push({ name: '引擎 socket', read: socket.read, detail: socket.detail, remedy: socket.read === READS.absent ? '启动 daemon：open "GlassPane Daemon.app"，或重跑安装程序最后那一支。' : null })
+
+  const npm = spawnJson('npm', ['ls', '-g', '--depth=0', '--json'], { spawn })
+  if (npm.read !== READS.available || npm.json === null) {
+    out.push({
+      name: '全局 npm 包',
+      read: READS.unverified,
+      detail: npm.reason ?? `npm ls -g 退出 ${npm.status}：${npm.stderr.slice(0, 120) || '没有 stderr'}`,
+      remedy: '够不着 npm 时，这一格只能答"不知道"；先确认这个账号能跑到 npm。',
+    })
+  } else {
+    const deps = npm.json.dependencies ?? {}
+    const seen = NPM_PACKAGES.map((name) => `${name}=${deps[name]?.version ?? '没装'}`)
+    const missing = NPM_PACKAGES.filter((name) => !deps[name])
+    out.push({
+      name: '全局 npm 包',
+      read: missing.length === 0 ? READS.available : READS.absent,
+      detail: seen.join(' '),
+      remedy: missing.length === 0 ? null
+        : `补法（不需要权限，取的是 registry 的发布物）：npm install -g ${NPM_PACKAGES.map((n) => `${n}@<版本>`).join(' ')}`,
+    })
+  }
+
+  return out
+}
+
+/** The shape of `glasspane doctor`'s answer: one line per reading, plus the exit-code rule. */
+export function doctorReport(readings) {
+  const lines = readings.map((one) => `· ${one.name}：${one.detail}${one.remedy ? `\n    下一步：${one.remedy}` : ''}`)
+  const unhealthy = readings.filter((one) => one.read !== READS.available)
+  const verdict = unhealthy.length === 0
+    ? '六格都答了话且都在位。'
+    : `${unhealthy.length}/${readings.length} 格不在位或答不了话：${unhealthy.map((one) => `${one.name}(${one.read})`).join('、')}`
+  return { text: `${lines.join('\n')}\n${verdict}`, ok: unhealthy.length === 0 }
+}
+
+export function usageText() {
+  return [
+    '用法：glasspane <命令>',
+    '',
+    '  update    问一次有没有新版本，有就装（走这台机器已经装着的那个更新器）',
+    '  status    把更新器自己的那一行结论原样打出来',
+    '  doctor    读这台机器的安装状态（安装指针、更新器、daemon 作业、socket、全局 npm 包）——只读，不写',
+    '  help      这一页（`-h`、`--help` 同义）',
+    '',
+    '退出码：0 = 成/都在位；2 = 用法错；3 = 被拒或有一格不在位（doctor 用它表示"有东西要看上面那几行"）；',
+    '4/5 来自 update（换版后回退 / 回退也没成），与更新器本身的口径一致。',
+    '本命令不 sudo、不删东西：需要人做的那一步只会把工具名与目录写出来，不会给成可照抄的升权命令。',
+  ].join('\n')
+}
+
+export function parseVerb(argv) {
+  const first = String(argv?.[0] ?? '')
+  if (argv.length === 0) return { verb: null, error: '没给命令' }
+  // `-h` / `--help` 与 `help` 同义：这条命令是本产品给 agent 的入口，而 agent 的第一反应就是
+  // `--help`。2026-10-27 用发布物实测：`/usr/local/bin/glasspane --help` 回"不认得命令「--help」"
+  // 且退出 2——同产品的 `installer/cli.js` 认 `--help`，两条入口对同一种问法给两种答案。
+  const verb = VERB_ALIASES[first] ?? first
+  if (!VERBS.includes(verb)) return { verb: null, error: `不认得命令「${first}」` }
+  return { verb, error: null, rest: argv.slice(1) }
+}
+
+/**
+ * `update` = the updater's own two steps, in its own words. It runs `check` first (an update has to be
+ * staged before `apply` will move anything), and hands the *updater's* exit code back: 3 from `check`
+ * means "nothing staged / unreachable", which is a refusal, not a failure — and this command has no
+ * business re-interpreting that as its own verdict.
+ */
+export async function runUpdate({ execPath = process.execPath, updaterCli, stateRoot, spawn = spawnSync, write = (line) => process.stdout.write(`${line}\n`) } = {}) {
+  const check = spawnJson(execPath, [updaterCli, 'check', '--json', '--state-dir', stateRoot], { spawn })
+  if (check.read !== READS.available || check.json === null) {
+    write(`检查没答话：${check.reason ?? `退出 ${check.status}：${check.stderr.slice(0, 200)}`}`)
+    return { exitCode: check.status ?? 3, stage: 'check' }
+  }
+  write(`检查：${check.json.message ?? check.json.status}`)
+  if (check.json.status === 'up-to-date') {
+    write('已经是最新，没有要装的东西。')
+    return { exitCode: 0, stage: 'check' }
+  }
+  // 检查这一格的非零退出就是"这一趟停在这里"：`deferred`/`needs-consent`/`check-failed` 都带着它自己的
+  // 原因与代号。从前这里读的是一个不存在的字段（`exitCode`，而子进程答的是 `status`），于是条件恒假,
+  // 一次"daemon 正忙"的拒绝被接着送去 apply，屏幕上就多出一条没做过的安装。
+  if (check.status !== 0) {
+    write(`检查停在 ${check.json.status}（code=${check.json.code ?? '未给出'}，退出码 ${check.status}），没有进入安装。`)
+    return { exitCode: check.status ?? 3, stage: 'check', json: check.json }
+  }
+  const apply = spawnJson(execPath, [updaterCli, 'apply', '--json', '--state-dir', stateRoot], { spawn })
+  if (apply.read !== READS.available || apply.json === null) {
+    write(`安装没答话：${apply.reason ?? `退出 ${apply.status}：${apply.stderr.slice(0, 200)}`}`)
+    return { exitCode: apply.status ?? 3, stage: 'apply' }
+  }
+  write(`安装：${apply.json.message ?? apply.json.status}`)
+  if (apply.json.code) write(`（这一格的代号：${apply.json.code}——它挂在状态里，面板与 gp_diagnose 也读得到。）`)
+  return { exitCode: apply.status ?? 0, stage: 'apply', json: apply.json }
+}
+
+export async function main({ argv = process.argv.slice(2), env = process.env, spawn = spawnSync, write = (line) => process.stdout.write(`${line}\n`), fail = (line) => process.stderr.write(`${line}\n`) } = {}) {
+  const parsed = parseVerb(argv)
+  if (parsed.error) {
+    fail(`${parsed.error}。\n\n${usageText()}`)
+    return 2
+  }
+  if (parsed.verb === 'help') {
+    write(usageText())
+    return 0
+  }
+  const { stateRoot } = stateRootOf({ env })
+  const pointer = readInstallPointer({ stateRoot, readFile: (p) => fs.readFileSync(p, 'utf8'), exists: (p) => fs.existsSync(p) })
+  if (parsed.verb === 'doctor') {
+    const report = doctorReport(doctorReadings({ env, spawn }))
+    write(report.text)
+    return report.ok ? 0 : 3
+  }
+  if (pointer.read !== READS.available) {
+    fail(`这台机器的安装指针读不出可用的一份更新器：${pointer.reason}\n${pointer.remedy ?? ''}`)
+    return 3
+  }
+  if (parsed.verb === 'status') {
+    const status = spawnJson(process.execPath, [pointer.updaterCli, 'status', '--json', '--state-dir', stateRoot], { spawn })
+    if (status.read !== READS.available || status.json === null) {
+      fail(`更新器没答话：${status.reason ?? status.stderr.slice(0, 200)}`)
+      return 3
+    }
+    const doc = status.json.state ?? status.json
+    write(`${status.json.status}｜装着 ${doc.current ?? '?'}｜最新 ${doc.latest ?? '未查'}｜待装 ${doc.staged?.version ?? '没有'}｜代号 ${status.json.code ?? '无'}`)
+    if (status.json.message) write(status.json.message)
+    return status.status ?? 0
+  }
+  const result = await runUpdate({ updaterCli: pointer.updaterCli, stateRoot, spawn, write })
+  return result.exitCode
+}
+
+const invokedDirectly = process.argv[1] !== undefined && fs.realpathSync(process.argv[1]) === fs.realpathSync(new URL(import.meta.url).pathname)
+if (invokedDirectly) {
+  main().then((code) => {
+    process.exitCode = code
+  }, (error) => {
+    process.stderr.write(`glasspane 自己出了错：${error?.message ?? String(error)}\n`)
+    process.exitCode = 3
+  })
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "glasspane-install",
-  "version": "1.21.0",
+  "version": "1.23.0",
   "description": "GlassPane one-command installer: terminal onboarding → install deps → build TS + Swift engine → start daemon → open settings GUI for permission guide",
   "type": "module",
   "license": "MIT",
@@ -15,10 +15,12 @@
   "keywords": ["macos", "installer", "glasspane", "cli"],
   "main": "./cli.js",
   "bin": {
-    "glasspane-install": "./cli.js"
+    "glasspane-install": "./cli.js",
+    "glasspane": "./glasspane.js"
   },
   "files": [
     "cli.js",
+    "glasspane.js",
     "LICENSE",
     "README.md"
   ],