@songsid/agend 2.3.0-beta.9 → 2.3.0

package/launcher/install-admission.cjs

@@ -1,12 +1,7 @@
 "use strict";
-// #1450 C1: may this install of @songsid/agend proceed? Called by the postinstall, inside npm's transaction (a refusal
-// makes npm roll the install back). The lock is the updater's (src/install-lock.ts): `<prefix>/.agend-install.lock`,
-// next to the package it guards. The prefix comes from WHERE this package is — never from the environment.
-//   - no lock, no token            → a plain external install: proceed (the documented restriction covers the rest);
-//   - a live lock, its own token   → the updater's own npm child: proceed;
-//   - a live lock, other/no token  → a foreign install while AgEnD owns the prefix: refuse;
-//   - a token, but no live lock    → late or stale (it cannot authorise a successor): refuse;
-//   - a lock that cannot be read   → refuse, naming the file (unknown ownership blocks).
+// #1450 C1, reduced by #2264: the install lock's process readers (start time, start ticks, boot id), shared by the
+// updater's lock (src/install-lock.ts). Nothing here decides whether an install may run any more — a manual
+// `npm install -g` is never refused because of a lock (#2264: one that could not be read blocked every install).
 // Same syntax constraints as runtime-platform.cjs: this may run on an old Node.
 var fs = require("fs");
 var path = require("path");
@@ -124,37 +119,7 @@ function parse(text) {
       || (typeof r.startTicks === "string" && /^\d+$/.test(r.startTicks) && typeof r.bootId === "string" && /^[0-9a-f-]{36}$/.test(r.bootId))) ? r : null;
 }
 
-/** { ok: true, why } or { ok: false, reason }. deps (tests): env, processStart. */
-function admit(pkgDir, deps) {
-  var d = deps || {};
-  var env = d.env || process.env;
-  var token = env[TOKEN_ENV] || "";
-  var real;
-  try { real = fs.realpathSync(pkgDir); } catch (e) { real = pkgDir; }
-  var prefix = globalPrefix(real);
-  if (!prefix) return token ? { ok: false, reason: "an AgEnD install token was presented, but this is not a global install it could belong to" } : { ok: true, why: "not a global install" };
-  try { prefix = fs.realpathSync(prefix); } catch (e) { /* as derived */ }
-  var lockPath = path.join(prefix, LOCK);
-  var text = null;
-  try { text = fs.readFileSync(lockPath, "utf8"); } catch (e) {
-    if (e.code !== "ENOENT") return { ok: false, reason: "the install lock " + lockPath + " cannot be read (" + e.code + ")" };
-  }
-  if (text === null) {
-    return token ? { ok: false, reason: "an AgEnD install token was presented, but no update holds " + lockPath + " (a late or stale token)" } : { ok: true, why: "no lock: an external install" };
-  }
-  var lock = parse(text);
-  if (!lock) return { ok: false, reason: "the install lock " + lockPath + " cannot be read as a lock; if no `agend update` is running, remove it and retry" };
-  var state = holderState(lock, d);
-  if (state === "unknown") return { ok: false, reason: "whether the AgEnD update that holds " + lockPath + " (pid " + lock.pid + ") is still running cannot be told; retry" };
-  if (state === "stale") {
-    return token ? { ok: false, reason: "the AgEnD update that held " + lockPath + " is gone, so its token cannot authorise this install" } : { ok: true, why: "a stale lock and no token: an external install" };
-  }
-  if (lock.prefix !== prefix) return { ok: false, reason: "the install lock " + lockPath + " names another prefix (" + lock.prefix + ")" };
-  if (token && token === lock.token) return { ok: true, why: "the updater's own install" };
-  return { ok: false, reason: "an `agend update` (pid " + lock.pid + ") is installing into " + prefix + " right now; wait for it, then retry" };
-}
-
 module.exports = {
-  LOCK: LOCK, TOKEN_ENV: TOKEN_ENV, admit: admit, globalPrefix: globalPrefix, processStart: processStart, startTicks: startTicks, bootId: bootId,
+  LOCK: LOCK, TOKEN_ENV: TOKEN_ENV, globalPrefix: globalPrefix, processStart: processStart, startTicks: startTicks, bootId: bootId,
   sameStartText: sameStartText, START_TOLERANCE_MS: START_TOLERANCE_MS, exists: exists, holderState: holderState, parse: parse,
 };

package/launcher/postinstall.cjs

@@ -14,8 +14,6 @@ var crypto = require("crypto");
 var childProcess = require("child_process");
 var platform = require("./runtime-platform.cjs");
 var select = require("./runtime-select.cjs");
-var admission = require("./install-admission.cjs");
-var oldUpdater = require("./old-updater-note.cjs");
 
 /** Runs on the candidate Node with argv[1] = the package dir: version, N-API, and a real DB open in both threads. */
 var PROOF = [
@@ -33,13 +31,9 @@ var PROOF = [
 ].join("\n");
 
 function refuse(reason, recovery) {
-  // #1487: "the previous install stays" is true only when AgEnD 2.1's updater did not start this install.
-  var state = oldUpdater.oldUpdaterState(process.env);
-  var back = state === "removed" ? "npm is rolling this install back.\n"
-    : state === "kept" ? "npm is rolling this install back; the previous install stays.\n"
-    : "npm is rolling this install back; a previous install, if any, stays — unless AgEnD 2.1's updater started this.\n";
-  var note = oldUpdater.oldUpdaterNote(state);
-  process.stderr.write("\n  AgEnD cannot be installed here: " + reason + ".\n  " + back + "  " + recovery + "\n" + (note ? note : "") + "\n");
+  // #2264: one repair, whatever happened before: the installer (it puts back what an interrupted install moved aside).
+  process.stderr.write("\n  AgEnD cannot be installed here: " + reason + ".\n  npm is rolling this install back; a previous install, if any, stays.\n  " + recovery
+    + "\n  If `agend` is missing afterwards, run the installer again: curl -fsSL https://songsid.github.io/AgEnD/install.sh | bash\n\n");
   process.exit(1);
 }
 
@@ -62,9 +56,8 @@ function main(deps) {
     try { fs.unlinkSync(file); } catch (e) { /* checked below */ }
     if (!select.absent(file)) refuse("an old runtime receipt at " + file + " cannot be removed", "remove it, then: npm install -g @songsid/agend@" + pkg.manifest.version);
   });
-  // C1: an `agend update` owns this prefix right now → only its own npm child may install (install-admission.cjs).
-  var admitted = admission.admit(pkg.dir, { env: d.env, processStart: d.processStart });
-  if (!admitted.ok) refuse(admitted.reason, "Never run two installs of @songsid/agend into one prefix at once, or one while `agend update` runs.");
+  // #2264: no install lock is consulted here. A manual `npm install -g` is never refused because of one (a lock that
+  // could not be read used to block every install until removed by hand); only two installers exclude each other.
   var host = d.host || platform.hostPlatform();
   var running = d.versions || { node: process.versions.node, napi: Number(process.versions.napi) };
   var engines = (pkg.manifest.engines && pkg.manifest.engines.node) || ">=22.14.0";
@@ -72,6 +65,15 @@ function main(deps) {
   var support = platform.runtimeSupport(host);
   var log = d.log || function (line) { process.stdout.write(line + "\n"); };
   var installed = function () { log(NEXT_STEP); return 0; };
+  // #2264: `npm exec --package @songsid/agend@<v> -- agend-install` fetches a release only to run its installer. npm
+  // hoists the bundled Node out of <pkg>/node_modules there, and nothing runs `agend` from that copy: the installer's own
+  // `npm install -g` proves the bundled Node where AgEnD is installed. Refusing here (an old Node running npm, the
+  // runtime not at its exact path) would stop the update before the installer starts — the real Mac rehearsal.
+  var env = d.env || process.env;
+  if (env.npm_command === "exec" && !(pin && support.supported && select.runtimeCandidate(pkg.dir, pin).exists)) {
+    log("  ℹ Fetched to run its installer (npm exec); the bundled Node is checked by the install itself.");
+    return 0;
+  }
 
   if (pin && support.supported) {
     var candidate = select.runtimeCandidate(pkg.dir, pin);

package/launcher/private-home.cjs

@@ -0,0 +1,43 @@
+"use strict";
+// Shared by the compiled CLI and the target-version installer. Keep syntax usable by old npm's Node.
+var fs = require("fs");
+var path = require("path");
+
+function checkedPath(dir, io, missingAllowed, message) {
+  var absolute = path.resolve(dir), parent = path.parse(absolute).root;
+  var pieces = absolute.slice(parent.length).split(path.sep).filter(Boolean), info;
+  for (var i = 0; i < pieces.length; i++) {
+    parent = path.join(parent, pieces[i]);
+    try { info = io.lstatSync(parent); }
+    catch (error) { if (missingAllowed && error.code === "ENOENT") return null; throw error; }
+    if (info.isSymbolicLink() || !info.isDirectory()) throw new Error(message);
+  }
+  return info || io.lstatSync(absolute);
+}
+
+/** Create privately; repair only an owned real home, never chmod by pathname or through a symlink. */
+function ensurePrivateHome(dir, options) {
+  var opts = options || {}, io = opts.fs || fs;
+  var uid = opts.uid === undefined ? (typeof process.getuid === "function" ? process.getuid() : null) : opts.uid;
+  var label = opts.label || "AgEnD";
+  var message = label + " requires an owned real AGEND_HOME without group/other write permission.";
+  checkedPath(dir, io, opts.create !== false, message);
+  if (opts.create !== false) io.mkdirSync(dir, { recursive: true, mode: 448 }); // 0700; umask cannot add permissions
+  var before = checkedPath(dir, io, false, message);
+  // Native Windows has no Unix uid/mode contract. The Windows installer runs this policy inside WSL.
+  if (uid === null) return;
+  if (before.uid !== uid) throw new Error(message);
+  var fd = io.openSync(dir, io.constants.O_RDONLY | io.constants.O_DIRECTORY | io.constants.O_NOFOLLOW);
+  try {
+    if (opts.afterOpen) opts.afterOpen(); // test seam: replacement at the check/change boundary
+    var info = io.fstatSync(fd), current = checkedPath(dir, io, false, message);
+    if (!info.isDirectory() || info.uid !== uid || current.dev !== info.dev || current.ino !== info.ino) throw new Error(message);
+    if (info.mode & 18) { // 0022: repair affected 0775/0777 homes; existing non-writable roots keep their mode
+      io.fchmodSync(fd, 448);
+      if ((io.fstatSync(fd).mode & 511) !== 448) throw new Error(message);
+      (opts.log || function (line) { console.warn(line); })("AgEnD: tightened owned AGEND_HOME permissions to 0700.");
+    }
+  } finally { io.closeSync(fd); }
+}
+
+module.exports = { ensurePrivateHome: ensurePrivateHome };

package/package.json

@@ -1,11 +1,12 @@
 {
   "name": "@songsid/agend",
-  "version": "2.3.0-beta.9",
+  "version": "2.3.0",
   "description": "Multi-agent fleet daemon — run coding CLIs (Claude, Muse, Codex, OpenCode) from Discord or Telegram",
   "type": "module",
   "bin": {
     "agend": "./launcher/agend",
-    "agend-agent": "./launcher/agend-agent"
+    "agend-agent": "./launcher/agend-agent",
+    "agend-install": "./launcher/agend-install.cjs"
   },
   "exports": {
     ".": "./dist/cli.js",
@@ -59,34 +60,36 @@
     "scripts/preinstall-guard.cjs"
   ],
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.27.1",
+    "@modelcontextprotocol/sdk": "^1.32.1",
     "better-sqlite3": "^13.0.3",
     "commander": "^14.0.3",
     "croner": "^10.0.1",
-    "discord.js": "^14.25.1",
+    "discord.js": "^14.27.0",
     "ejs": "^5.0.1",
     "grammy": "^1.44.0",
-    "js-yaml": "^4.1.1",
+    "js-yaml": "^4.3.2",
+    "libavoid-js": "0.4.5",
     "pino": "^10.3.1",
     "pino-pretty": "^13.1.3",
     "smol-toml": "1.9.0",
-    "undici": "6.24.1",
+    "undici": "6.29.1",
     "yaml": "^2.9.0",
     "zod": "^4.3.6"
   },
   "optionalDependencies": {
-    "@songsid/agend-node-darwin-arm64": "22.23.3",
-    "@songsid/agend-node-darwin-x64": "22.23.3",
-    "@songsid/agend-node-linux-arm64": "22.23.3",
-    "@songsid/agend-node-linux-x64": "22.23.3"
+    "@songsid/agend-node-darwin-arm64": "22.23.4",
+    "@songsid/agend-node-darwin-x64": "22.23.4",
+    "@songsid/agend-node-linux-arm64": "22.23.4",
+    "@songsid/agend-node-linux-x64": "22.23.4"
   },
   "devDependencies": {
     "@types/better-sqlite3": "^7.6.13",
     "@types/ejs": "^3.1.5",
     "@types/js-yaml": "^4.0.9",
     "@types/node": "^25.5.0",
-    "tsx": "^4.21.0",
-    "typescript": "^5.9.3",
-    "vitest": "^4.1.0"
+    "@typescript/native": "npm:typescript@7.0.2",
+    "tsx": "^4.23.15",
+    "typescript": "npm:@typescript/typescript6@6.0.2",
+    "vitest": "^4.1.12"
   }
 }

package/scripts/preinstall-guard.cjs

@@ -15,8 +15,7 @@
 // pins none) AND a system Node older than ENGINES — AgEnD would install and then not start.
 // Old syntax only (var, no ?. ??, no trailing call commas): this runs under whatever Node runs npm.
 //
-// Exiting 1 aborts the install. A previous install stays — except when AgEnD 2.1's updater started this one: it
-// removes the previous AgEnD first (#1487), so the refusal says so and gives the restore commands (old-updater-note.cjs).
+// Exiting 1 aborts the install; a previous install stays (#2264: no 2.1-era restore note — the repair is the installer).
 // --ignore-scripts bypasses this check; see Upgrade Notes in the changelog.
 
 "use strict";
@@ -24,7 +23,6 @@
 var path = require("path");
 var fs = require("fs");
 var platform = require(path.join(__dirname, "..", "launcher", "runtime-platform.cjs"));
-var oldUpdater = require(path.join(__dirname, "..", "launcher", "old-updater-note.cjs"));
 
 var ENGINES = "^22.14.0 || ^23.6.0 || >=24";
 var running = process.versions.node;
@@ -52,7 +50,6 @@ process.stderr.write(
   "\n" +
   "  Update Node to a compatible version, then retry:\n" +
   "    npm install -g @songsid/agend\n" +
-  "\n" +
-  (function () { var note = oldUpdater.oldUpdaterNote(oldUpdater.oldUpdaterState(process.env)); return note ? note + "\n" : ""; })()
+  "\n"
 );
 process.exit(1);

package/templates/windows-shortcuts.ps1

@@ -0,0 +1,181 @@
+# AgEnD 桌面捷徑（#1853）：`agend shortcuts` 在 WSL 裡經由 powershell.exe 執行這份文字，建立或更新「AgEnD 儀表板」和
+# 「AgEnD 重新啟動」兩個桌面捷徑。第一個空白行以下和 website/public/install-agend.ps1 裡的同一段一字不差
+# （tests/windows-shortcuts-cli-1853.test.ts 檢查）：改的時候兩邊一起改。
+
+$WSL_COMMAND_FN = @'
+function Get-WslAgendCommand([string]$command) {
+    return ('export PATH=$HOME/.local/bin:$PATH; source $HOME/.nvm/nvm.sh 2>/dev/null; ' + $command)
+}
+# 放進 PowerShell 文字裡的值（Linux、使用者名稱）一律用這個轉成字面字串：名稱裡的單引號（例如 o'neil）不會讓產生的
+# 腳本或貼上的指令壞掉（#2260 審查）。印給人看的指令，名稱沒有特殊字元時維持原樣、不加引號。
+function ConvertTo-PsLiteral([string]$value) { return ("'" + ($value -replace "'", "''") + "'") }
+function ConvertTo-PsArgument([string]$value) { if ($value -match '^[\w.-]+$') { return $value } else { return (ConvertTo-PsLiteral $value) } }
+function Get-AgendStartHint([string]$distro, [string]$user) {
+    return ("wsl -d {0} -u {1} -- bash -lc '{2}'" -f (ConvertTo-PsArgument $distro), (ConvertTo-PsArgument $user), (Get-WslAgendCommand 'agend start'))
+}
+'@
+. ([scriptblock]::Create($WSL_COMMAND_FN))
+
+$DASHBOARD_OPENER_FN = @'
+function Get-DashboardSignIn([string]$text) {
+    $url = [regex]::Match($text, 'Sign-in page:\s*(https?://\S+)')
+    $code = [regex]::Match($text, 'Code:\s*([A-Z2-7]{4}-?[A-Z2-7]{4})\b')
+    if (-not $url.Success -or -not $code.Success) { return $null }
+    return @{ Url = $url.Groups[1].Value; Code = $code.Groups[1].Value }
+}
+function Invoke-OpenDashboard([string]$distro, [string]$user = 'root', [switch]$Wait) {
+    # agend web --code 失敗時（AgEnD 沒在跑、沒有 token、連不上）會寫到 stderr 並以 1 結束。Windows PowerShell 5.1 會把重導的
+    # stderr 變成錯誤紀錄，在 ErrorActionPreference=Stop 下直接中止（#2242 審查）：取得輸出的這段改用 Continue、每一筆都轉成文字，
+    # 結束碼不是 0、啟動不了 wsl，都走下面「打不開」的說明。原本的設定在 finally 還原。
+    $text = ''; $exit = 1
+    $prevEAP = $ErrorActionPreference
+    try {
+        $ErrorActionPreference = 'Continue'
+        $text = ((& wsl.exe -d $distro -u $user -- bash -lc (Get-WslAgendCommand 'agend web --code') 2>&1) | ForEach-Object { "$_" } | Out-String)
+        $exit = $LASTEXITCODE
+    } catch {
+        $text = "$_"; $exit = 1
+    } finally {
+        $ErrorActionPreference = $prevEAP
+    }
+    $signIn = if ($exit -eq 0) { Get-DashboardSignIn $text } else { $null }
+    if (-not $signIn) {
+        Write-Host "  [!!] 現在打不開 AgEnD 儀表板：AgEnD 可能還沒啟動。" -ForegroundColor Yellow
+        Write-Host ("  稍等一下再試一次；或在 PowerShell 執行：" + (Get-AgendStartHint $distro $user))
+        if ($Wait) { Read-Host "按 Enter 關閉" }
+        return $false
+    }
+    $copied = $false; try { Set-Clipboard -Value $signIn.Code; $copied = $true } catch { }
+    $opened = $false; try { Start-Process $signIn.Url; $opened = $true } catch { }
+    $spaced = ($signIn.Code.ToCharArray() | ForEach-Object { [string]$_ }) -join ' '
+    Write-Host ""
+    Write-Host ("  ┌──────────────────────────────────────┐") -ForegroundColor Green
+    Write-Host ("  │   儀表板登入碼：  " + $spaced + "    │") -ForegroundColor Green
+    Write-Host ("  └──────────────────────────────────────┘") -ForegroundColor Green
+    if ($opened) { Write-Host "  [OK] 登入頁已在瀏覽器打開。" -ForegroundColor Green } else { Write-Host ("  請自己在瀏覽器打開：" + $signIn.Url) }
+    if ($copied) { Write-Host "  [OK] 登入碼已複製：在登入頁的輸入框按 Ctrl+V。這組登入碼只能用一次，幾分鐘內有效。" -ForegroundColor Green }
+    else { Write-Host "  在登入頁輸入上面的登入碼。這組登入碼只能用一次，幾分鐘內有效。" }
+    if ($Wait) { Read-Host "按 Enter 關閉" }
+    return $true
+}
+'@
+. ([scriptblock]::Create($DASHBOARD_OPENER_FN))
+
+# 「AgEnD 重新啟動」捷徑（#1853，使用者 2026-10-20 核准）：先問，預設不重啟；確定才在安裝時記下的 Linux 和使用者裡執行
+# agend restart，接著顯示 agend status，等你按 Enter。WSL 或 AgEnD 不在時直接說明；絕不執行 wsl --shutdown。
+# 這段函式的文字同時是捷徑執行的腳本（和儀表板捷徑一樣，安裝程式與捷徑共用同一份）。
+$RESTART_FN = @'
+function Invoke-AgendInWsl([string]$distro, [string]$user, [string]$command) {
+    # 在 WSL 裡以登入 shell 執行一個 agend 指令，回傳 @{ Code; Text }。Linux 的輸出是 UTF-8；stderr 不讓 5.1 中止（#2242）。
+    $prevEAP = $ErrorActionPreference; $prevEnc = [Console]::OutputEncoding
+    try {
+        $ErrorActionPreference = 'Continue'
+        try { [Console]::OutputEncoding = [Text.Encoding]::UTF8 } catch { }
+        $text = ((& wsl.exe -d $distro -u $user -- bash -lc (Get-WslAgendCommand $command) 2>&1) | ForEach-Object { "$_" } | Out-String)
+        return @{ Code = $LASTEXITCODE; Text = $text }
+    } catch {
+        return @{ Code = -1; Text = "$_" }
+    } finally {
+        $ErrorActionPreference = $prevEAP
+        try { [Console]::OutputEncoding = $prevEnc } catch { }
+    }
+}
+function Invoke-RestartAgend([string]$distro, [string]$user, [switch]$Wait, [int]$SettleSeconds = 3) {
+    Write-Host ""
+    $answer = Read-Host "  確定要重啟 AgEnD 嗎？所有 agent 會重新啟動，正在進行的工作會中斷。(y/N)"
+    # 只有一個 y 才算同意（y/N、yes 都不算）；[string]：沒有輸入時 Read-Host 回傳 $null，而 $null -notmatch '…' 不是 $true。
+    if (([string]$answer) -notmatch '^\s*[yY]\s*$') {
+        Write-Host "  沒有重啟。"
+        if ($Wait) { $null = Read-Host "按 Enter 關閉" }
+        return 'cancelled'
+    }
+    $r = Invoke-AgendInWsl $distro $user 'agend restart'
+    $result = 'restarted'
+    if ($r.Code -eq 0) {
+        Write-Host "  [OK] AgEnD 正在重新啟動。" -ForegroundColor Green
+    } else {
+        $result = 'failed'
+        if ($r.Code -eq -1) { Write-Host "  [!!] 找不到 WSL（wsl.exe），所以沒有重啟。" -ForegroundColor Yellow }
+        elseif ($r.Text -match 'Fleet not running') { Write-Host ("  [!!] AgEnD 沒有在執行，所以沒有可以重啟的。要啟動它：" + (Get-AgendStartHint $distro $user)) -ForegroundColor Yellow }
+        elseif ($r.Text -match 'command not found|agend: not found|no such file') { Write-Host ("  [!!] 在 {0} 裡找不到 AgEnD（agend 指令），所以沒有重啟。" -f $distro) -ForegroundColor Yellow }
+        else { Write-Host ("  [!!] 沒有重啟成功：{0} 不存在、WSL 沒有啟動，或 AgEnD 回報了錯誤。" -f $distro) -ForegroundColor Yellow }
+        if ($r.Text.Trim()) { Write-Host ("  " + ($r.Text.Trim() -replace "`r?`n", "`n  ")) }
+    }
+    if ($result -eq 'restarted') {
+        Start-Sleep -Seconds $SettleSeconds
+        Write-Host ""
+        $s = Invoke-AgendInWsl $distro $user 'agend status'
+        if ($s.Text.Trim()) { Write-Host ("  " + ($s.Text.Trim() -replace "`r?`n", "`n  ")) }
+    }
+    if ($Wait) { $null = Read-Host "按 Enter 關閉" }
+    return $result
+}
+'@
+. ([scriptblock]::Create($RESTART_FN))
+
+# 捷徑執行的腳本：共用的函式加上一行呼叫（UTF-8 有 BOM：Windows PowerShell 5.1 才會正確顯示中文）。Linux 與使用者是安裝時記下的。
+# 捷徑腳本印出的第一行：它要打開的 Linux 和使用者，指錯了一眼就看得出來。
+function Get-ShortcutTargetLine([string]$distro, [string]$user) {
+    return ('Write-Host ("AgEnD（Linux：{0}，使用者：{1}）" -f ' + (ConvertTo-PsLiteral $distro) + ', ' + (ConvertTo-PsLiteral $user) + ')')
+}
+function Get-DashboardOpenerScript([string]$distro, [string]$user) {
+    return ("# AgEnD 儀表板（AgEnD 安裝程式建立）`n" + (Get-ShortcutTargetLine $distro $user) + "`n" + $WSL_COMMAND_FN + "`n" + $DASHBOARD_OPENER_FN + "`n" + ("Invoke-OpenDashboard {0} {1} -Wait | Out-Null" -f (ConvertTo-PsLiteral $distro), (ConvertTo-PsLiteral $user)) + "`n")
+}
+function Get-RestartScript([string]$distro, [string]$user) {
+    return ("# AgEnD 重新啟動（AgEnD 安裝程式建立）`n" + (Get-ShortcutTargetLine $distro $user) + "`n" + $WSL_COMMAND_FN + "`n" + $RESTART_FN + "`n" + ("Invoke-RestartAgend {0} {1} -Wait | Out-Null" -f (ConvertTo-PsLiteral $distro), (ConvertTo-PsLiteral $user)) + "`n")
+}
+# 安裝時記下的 Linux 與使用者（%LOCALAPPDATA%\AgEnD\install.json）：捷徑、重新執行安裝指令時的快速路徑都讀它。
+function Get-AgendShortcutDir { return (Join-Path $env:LOCALAPPDATA 'AgEnD') }
+function Read-InstallRecord {
+    try {
+        $r = Get-Content -Raw -LiteralPath (Join-Path (Get-AgendShortcutDir) 'install.json') -ErrorAction Stop | ConvertFrom-Json
+        if ($r.distro -and $r.user) { return @{ Distro = [string]$r.distro; User = [string]$r.user } }
+    } catch { }
+    return $null
+}
+# install.json 已經指向另一個 Linux 或使用者時回傳那筆紀錄（例如 AgEnD 專用的 Linux 和原本的 Ubuntu），否則 $null。
+# 捷徑絕不悄悄改指向：agend shortcuts 遇到這種情況會先問。
+function Get-InstallRecordConflict([string]$distro, [string]$user) {
+    $record = Read-InstallRecord
+    # WSL 的名稱不分大小寫；Linux 的使用者名稱分（Han 和 han 是兩個人，#2279 審查）。
+    if ($record -and ($record.Distro -ne $distro -or $record.User -cne $user)) { return $record }
+    return $null
+}
+# 真正寫入前再讀一次：詢問時看到的是 $seen（$null：當時沒有衝突）。現在沒有衝突，或衝突的還是同一個，才可以寫；
+# 在等回答的時候被別的安裝程式或終端機改掉了，就不寫（#2279 審查）。
+function Test-InstallRecordAsSeen($seen, [string]$distro, [string]$user) {
+    $now = Get-InstallRecordConflict $distro $user
+    if ($null -eq $now) { return $true }
+    return ($null -ne $seen -and $now.Distro -eq $seen.Distro -and $now.User -ceq $seen.User)
+}
+# 一個桌面捷徑：腳本寫在 %LOCALAPPDATA%\AgEnD，捷徑以 Windows PowerShell 執行它（-ExecutionPolicy Bypass 只對那個行程）。
+function New-AgendShortcut([string]$name, [string]$scriptName, [string]$scriptText, [string]$description) {
+    $dir = Get-AgendShortcutDir
+    New-Item -ItemType Directory -Path $dir -Force | Out-Null
+    $file = Join-Path $dir $scriptName
+    [IO.File]::WriteAllText($file, $scriptText, (New-Object System.Text.UTF8Encoding $true))
+    $lnk = Join-Path ([Environment]::GetFolderPath('Desktop')) ($name + '.lnk')
+    $shell = New-Object -ComObject WScript.Shell
+    $sc = $shell.CreateShortcut($lnk)
+    $sc.TargetPath = Join-Path $env:SystemRoot 'System32\WindowsPowerShell\v1.0\powershell.exe'
+    $sc.Arguments = ('-NoProfile -ExecutionPolicy Bypass -File "{0}"' -f $file)
+    $sc.Description = $description
+    $sc.Save()
+    return $lnk
+}
+# 建立（或更新）兩個桌面捷徑、記下 Linux 與使用者。兩個各自建立，一個失敗不會擋住另一個；回傳建立好的捷徑路徑，
+# 呼叫端用 Write-ShortcutResult 分清楚兩個都好、只好一個、都沒好（#2252 審查）。兩個都好才在 WSL 裡留記號（agend update
+# 之後的提示就不會再出現）。不是 Windows 時回傳空陣列。
+function Install-AgendShortcuts([string]$distro, [string]$user) {
+    if (-not $script:OnWindows) { return @() }
+    $made = @()
+    try { $made += New-AgendShortcut 'AgEnD 儀表板' 'open-dashboard.ps1' (Get-DashboardOpenerScript $distro $user) 'AgEnD 網頁儀表板（自動帶入登入碼）' } catch { }
+    try { $made += New-AgendShortcut 'AgEnD 重新啟動' 'restart-agend.ps1' (Get-RestartScript $distro $user) '重新啟動 AgEnD（會先詢問）' } catch { }
+    try {
+        New-Item -ItemType Directory -Path (Get-AgendShortcutDir) -Force | Out-Null
+        $record = @{ distro = $distro; user = $user } | ConvertTo-Json -Compress
+        [IO.File]::WriteAllText((Join-Path (Get-AgendShortcutDir) 'install.json'), $record, (New-Object System.Text.UTF8Encoding $false))
+        if ($made.Count -eq 2) { $null = Invoke-AgendInWsl $distro $user 'set -f; IFS=; d=${AGEND_HOME:-$HOME/.agend}; umask 077; mkdir -p -m 700 -- $d && date -u +%FT%TZ > $d/windows-shortcuts' }
+    } catch { }
+    return $made
+}

package/launcher/old-updater-note.cjs

@@ -1,48 +0,0 @@
-// old-updater-note.cjs — #1487: what a refused install must tell someone whose AgEnD 2.1.x updater started it.
-//
-// 2.1.x's `agend update` (and chat /update) runs `npm unlink -g @songsid/agend` BEFORE `npm install -g`, so when this
-// install is refused (preinstall-guard.cjs, launcher/postinstall.cjs) nothing stays installed: no `agend`, and the
-// service cannot start after its next restart or login (proven on the real-Mac test host, #1487). That updater writes
-// <AGEND_HOME>/update-in-progress.json before it unlinks; 2.2's own updater never unlinks and marks its npm child with
-// AGEND_UPDATE_KEEPS_PREVIOUS=1. So: a fresh marker without that mark → the previous AgEnD is certainly gone; no marker
-// (a plain npm install) → say it conditionally; 2.2's updater → nothing to add.
-// Reads one small file, writes nothing, no network. Old syntax only (var, no ?. ??): it runs under any Node npm runs on.
-"use strict";
-
-var fs = require("fs");
-var os = require("os");
-var path = require("path");
-
-/** A 2.1.x update older than this is not the one running now. */
-var FRESH_MS = 60 * 60 * 1000;
-
-/** "removed" (certain), "maybe" (cannot tell), or "kept" (2.2's own updater: the previous install stays). */
-function oldUpdaterState(env, now) {
-  env = env || process.env;
-  if (env.AGEND_UPDATE_KEEPS_PREVIOUS === "1") return "kept";
-  var home = env.AGEND_HOME || path.join(os.homedir(), ".agend");
-  var marker;
-  try { marker = JSON.parse(fs.readFileSync(path.join(home, "update-in-progress.json"), "utf8")); } catch (e) { return "maybe"; }
-  var started = marker && typeof marker.startedAt === "number" ? marker.startedAt : NaN;
-  var at = now === undefined ? Date.now() : now;
-  return started === started && at - started >= 0 && at - started < FRESH_MS ? "removed" : "maybe";
-}
-
-var RESTORE = "    npm install -g @songsid/agend@2.1.12\n    agend install\n";
-
-/** The lines to add to a refusal (each starts with two spaces and ends with a newline); "" when nothing applies. */
-function oldUpdaterNote(state) {
-  if (state === "removed") {
-    return "  This install was started by AgEnD 2.1's updater (`agend update` or /update). That updater had ALREADY\n" +
-      "  REMOVED the previous AgEnD before this install began, so nothing stays installed: there is no `agend`\n" +
-      "  command now, and the AgEnD service will not start after its next restart or login.\n" +
-      "  Put the previous version back:\n" + RESTORE;
-  }
-  if (state === "maybe") {
-    return "  If this install was started by AgEnD 2.1's updater (`agend update` or /update): that updater had already\n" +
-      "  removed the previous AgEnD before this install began, so nothing stays installed. Put it back with:\n" + RESTORE;
-  }
-  return "";
-}
-
-module.exports = { oldUpdaterState: oldUpdaterState, oldUpdaterNote: oldUpdaterNote, FRESH_MS: FRESH_MS };