@co0ontty/wand 2.11.1 → 2.12.0

package/dist/build-info.json

@@ -1,6 +1,6 @@
 {
-  "commit": "91ceeeaabff61dfaa09abd5bf1327dda55f51879",
-  "builtAt": "2026-07-12T01:48:23.296Z",
-  "version": "2.11.1",
+  "commit": "2ffe360ae10acb539bd5e5fe785073348e2b0482",
+  "builtAt": "2026-07-12T04:24:13.405Z",
+  "version": "2.12.0",
   "channel": "stable"
 }

package/dist/npm-update-utils.js

@@ -18,7 +18,6 @@ import path from "node:path";
 import process from "node:process";
 import { promisify } from "node:util";
 import { whichSync } from "./path-repair.js";
-import { compareSemver } from "./version-utils.js";
 import { getErrorMessage } from "./error-utils.js";
 const execFileAsync = promisify(execFile);
 export const PACKAGE_NAME = "@co0ontty/wand";
@@ -51,27 +50,13 @@ function computeUpdateAvailable(currentVersion, latestVersion, channel) {
     if (!latestVersion)
         return false;
     const current = cleanVersion(currentVersion);
-    const latest = cleanVersion(latestVersion);
-    const currentTag = getStableTagVersion(current);
-    const latestTag = getStableTagVersion(latest);
-    const tagCompare = compareSemver(latestTag, currentTag);
-    if (channel === "beta") {
-        if (tagCompare < 0)
-            return false;
-        if (tagCompare > 0)
-            return true;
-        // Beta follows the beta npm dist-tag exactly. The suffix contains the short
-        // git SHA, so recency comes from the dist-tag pointer instead of semver order.
-        return latest !== current;
-    }
-    if (tagCompare < 0)
-        return false;
-    if (tagCompare > 0)
-        return true;
-    // Stable intentionally tracks only the pure tag version. If the current build
-    // is a beta with the same base tag, switching back to stable should reinstall
-    // the clean npm @latest package.
-    return current !== latestTag;
+    const target = channel === "stable"
+        ? getStableTagVersion(latestVersion)
+        : cleanVersion(latestVersion);
+    // npm's selected dist-tag is authoritative. Manual/local builds can have a
+    // numerically higher, lower, invalid, or suffixed version; any mismatch must
+    // still allow switching to the exact package selected by @latest or @beta.
+    return current !== target;
 }
 export function buildPackageUpdateInfo(currentVersion, channel, latestVersion) {
     const latest = latestVersion?.trim() || null;

package/dist/process-manager.d.ts

@@ -1,6 +1,6 @@
 import { EventEmitter } from "node:events";
 import { WandStorage } from "./storage.js";
-import { ExecutionMode, ProcessEventHandler, SessionProvider, SessionSnapshot, WandConfig } from "./types.js";
+import { ExecutionMode, ProcessEventHandler, SessionProvider, SessionSnapshot, SessionSource, WandConfig } from "./types.js";
 export type { ProcessEvent, ProcessEventHandler } from "./types.js";
 /** Human-readable task information for the UI */
 export interface TaskInfo {
@@ -68,6 +68,8 @@ export declare class ProcessManager extends EventEmitter {
         cols?: number;
         rows?: number;
         thinkingEffort?: SessionSnapshot["thinkingEffort"];
+        sessionSource?: SessionSource;
+        automationId?: string;
     }): SessionSnapshot;
     list(): SessionSnapshot[];
     /** Return lightweight snapshots for the session list (no output/messages). */

package/dist/process-manager.js

@@ -701,6 +701,7 @@ export class ProcessManager extends EventEmitter {
                 const recoveredMessages = recoverMessagesFromSnapshot(snapshot);
                 const updated = {
                     ...snapshot,
+                    sessionSource: snapshot.sessionSource ?? "interactive",
                     status: "exited",
                     endedAt: orphanEndedAt,
                     claudeSessionId: restoredSessionId ?? null,
@@ -713,6 +714,7 @@ export class ProcessManager extends EventEmitter {
                 }
                 this.sessions.set(snapshot.id, {
                     ...updated,
+                    sessionSource: snapshot.sessionSource ?? "interactive",
                     provider,
                     processId: null,
                     ptyProcess: null,
@@ -871,15 +873,22 @@ export class ProcessManager extends EventEmitter {
         // re-prints its own banner and replayed history into the new PTY, and
         // mixing the two would surface every line twice in the terminal view.
         let priorMessages = [];
+        let inheritedSessionSource;
+        let inheritedAutomationId;
         if (opts?.reuseId) {
             const oldRecord = this.sessions.get(id);
             if (oldRecord) {
                 priorMessages = oldRecord.ptyBridge?.getMessages() ?? oldRecord.messages ?? [];
+                inheritedSessionSource = oldRecord.sessionSource;
+                inheritedAutomationId = oldRecord.automationId;
                 this.cleanupRecord(oldRecord);
                 this.sessions.delete(id);
             }
             else {
-                priorMessages = this.storage.getSession(id)?.messages ?? [];
+                const stored = this.storage.getSession(id);
+                priorMessages = stored?.messages ?? [];
+                inheritedSessionSource = stored?.sessionSource;
+                inheritedAutomationId = stored?.automationId;
             }
         }
         const worktreeSetup = opts?.worktreeEnabled
@@ -908,6 +917,8 @@ export class ProcessManager extends EventEmitter {
         const startedAt = new Date().toISOString();
         const record = {
             id,
+            sessionSource: opts?.sessionSource ?? inheritedSessionSource ?? "interactive",
+            automationId: opts?.automationId ?? inheritedAutomationId,
             provider,
             command,
             cwd: resolvedCwd,
@@ -1672,7 +1683,7 @@ export class ProcessManager extends EventEmitter {
         }
     }
     runStartupCommands() {
-        return this.config.startupCommands.map((command) => this.start(command, this.config.defaultCwd, this.config.defaultMode));
+        return this.config.startupCommands.map((command) => this.start(command, this.config.defaultCwd, this.config.defaultMode, undefined, { sessionSource: "startup" }));
     }
     snapshot(record) {
         // Get messages from bridge if available, otherwise use stored messages
@@ -1680,6 +1691,8 @@ export class ProcessManager extends EventEmitter {
         return {
             id: record.id,
             sessionKind: "pty",
+            sessionSource: record.sessionSource ?? "interactive",
+            automationId: record.automationId,
             provider: record.provider,
             runner: "pty",
             command: record.command,

package/dist/server-session-routes.d.ts

@@ -2,8 +2,15 @@ import { Express } from "express";
 import { ProcessManager } from "./process-manager.js";
 import { StructuredSessionManager } from "./structured-session-manager.js";
 import { WandStorage } from "./storage.js";
-import { ExecutionMode, WandConfig } from "./types.js";
+import { ExecutionMode, SessionSource, WandConfig } from "./types.js";
 import { getErrorMessage } from "./error-utils.js";
 export { getErrorMessage };
+export declare function parseSessionCreationOrigin(body: {
+    sessionSource?: unknown;
+    automationId?: unknown;
+} | null | undefined): {
+    sessionSource: SessionSource;
+    automationId?: string;
+};
 export declare function registerSessionRoutes(app: Express, processes: ProcessManager, structured: StructuredSessionManager, storage: WandStorage, defaultMode: ExecutionMode, config: WandConfig, onSessionCreated?: (cwd: string | undefined | null) => void): void;
 export declare function registerClaudeHistoryRoutes(app: Express, processes: ProcessManager, storage: WandStorage): void;

package/dist/server-session-routes.js

@@ -8,6 +8,24 @@ import { resolveCommitAiContext } from "./session-ai-context.js";
 import { getGitStatus, QuickCommitError, runQuickCommitWithFallback, runTagHead, runPush, generateCommitMessageOnly, } from "./git-quick-commit.js";
 import { getErrorMessage } from "./error-utils.js";
 export { getErrorMessage };
+export function parseSessionCreationOrigin(body) {
+    const rawSource = body?.sessionSource;
+    if (rawSource !== undefined && rawSource !== "interactive" && rawSource !== "automation" && rawSource !== "startup") {
+        throw new Error("sessionSource 必须是 interactive、automation 或 startup。");
+    }
+    const rawAutomationId = body?.automationId;
+    if (rawAutomationId !== undefined && typeof rawAutomationId !== "string") {
+        throw new Error("automationId 必须是非空字符串。");
+    }
+    const automationId = rawAutomationId?.trim();
+    if (rawAutomationId !== undefined && !automationId) {
+        throw new Error("automationId 必须是非空字符串。");
+    }
+    return {
+        sessionSource: rawSource ?? "interactive",
+        ...(automationId ? { automationId } : {}),
+    };
+}
 function getInputErrorResponse(error, sessionId) {
     if (error instanceof SessionInputError) {
         const statusCode = error.code === "SESSION_NOT_FOUND" ? 404 : 409;
@@ -235,6 +253,7 @@ export function registerSessionRoutes(app, processes, structured, storage, defau
             }
             const provider = body.provider === "codex" ? "codex" : "claude";
             const rawModel = typeof body.model === "string" ? body.model.trim() : "";
+            const origin = parseSessionCreationOrigin(body);
             const snapshot = structured.createSession({
                 cwd: resolveSessionCwd(body.cwd, config.defaultCwd),
                 mode: normalizeMode(body.mode, defaultMode),
@@ -245,6 +264,7 @@ export function registerSessionRoutes(app, processes, structured, storage, defau
                 thinkingEffort: typeof body.thinkingEffort === "string"
                     ? body.thinkingEffort
                     : config.defaultThinkingEffort,
+                ...origin,
             });
             onSessionCreated?.(snapshot.cwd);
             const prompt = body.prompt?.trim();
@@ -811,6 +831,9 @@ export function registerSessionRoutes(app, processes, structured, storage, defau
         const claudeSessionId = String(req.params.claudeSessionId || "").trim();
         const body = req.body;
         try {
+            const requestedOrigin = body.sessionSource !== undefined || body.automationId !== undefined
+                ? parseSessionCreationOrigin(body)
+                : null;
             if (!claudeSessionId) {
                 res.status(400).json({ error: "Claude 会话 ID 不能为空。" });
                 return;
@@ -838,7 +861,12 @@ export function registerSessionRoutes(app, processes, structured, storage, defau
                 const resumeCommand = `${command} --resume ${claudeSessionId}`;
                 const reqCols = typeof body.cols === "number" && Number.isFinite(body.cols) ? body.cols : undefined;
                 const reqRows = typeof body.rows === "number" && Number.isFinite(body.rows) ? body.rows : undefined;
-                const newSnapshot = processes.start(resumeCommand, existingSession.cwd, newMode, undefined, { reuseId: existingSession.id, cols: reqCols, rows: reqRows });
+                const newSnapshot = processes.start(resumeCommand, existingSession.cwd, newMode, undefined, {
+                    reuseId: existingSession.id,
+                    cols: reqCols,
+                    rows: reqRows,
+                    ...(requestedOrigin ?? {}),
+                });
                 res.status(201).json({ resumedClaudeSessionId: claudeSessionId, ...newSnapshot });
             }
             else {
@@ -851,7 +879,11 @@ export function registerSessionRoutes(app, processes, structured, storage, defau
                 const resumeCommand = `claude --resume ${claudeSessionId}`;
                 const reqCols = typeof body.cols === "number" && Number.isFinite(body.cols) ? body.cols : undefined;
                 const reqRows = typeof body.rows === "number" && Number.isFinite(body.rows) ? body.rows : undefined;
-                const newSnapshot = processes.start(resumeCommand, cwd, newMode, undefined, { cols: reqCols, rows: reqRows });
+                const newSnapshot = processes.start(resumeCommand, cwd, newMode, undefined, {
+                    cols: reqCols,
+                    rows: reqRows,
+                    ...(requestedOrigin ?? {}),
+                });
                 res.status(201).json({ resumedClaudeSessionId: claudeSessionId, ...newSnapshot });
             }
         }
@@ -910,6 +942,7 @@ export function registerSessionRoutes(app, processes, structured, storage, defau
                 return;
             }
             const newMode = normalizeMode(body.mode, defaultMode);
+            const origin = parseSessionCreationOrigin(body);
             const snapshot = structured.createSession({
                 cwd,
                 mode: newMode,
@@ -917,6 +950,7 @@ export function registerSessionRoutes(app, processes, structured, storage, defau
                 runner: "codex-cli-exec",
                 worktreeEnabled: body.worktreeEnabled === true,
                 claudeSessionId: threadId,
+                ...origin,
             });
             onSessionCreated?.(cwd);
             res.status(201).json({ resumedClaudeSessionId: threadId, ...snapshot });

package/dist/server.js

@@ -20,7 +20,7 @@ import { getCachedModels, refreshModels } from "./models.js";
 import { ProcessManager } from "./process-manager.js";
 import { SessionLogger } from "./session-logger.js";
 import { StructuredSessionManager } from "./structured-session-manager.js";
-import { getErrorMessage, registerClaudeHistoryRoutes, registerSessionRoutes } from "./server-session-routes.js";
+import { getErrorMessage, parseSessionCreationOrigin, registerClaudeHistoryRoutes, registerSessionRoutes } from "./server-session-routes.js";
 import { checkPackageUpdateAsync, installPackageGloballyAsync, normalizeUpdateChannel, resolveGlobalWandCli, } from "./npm-update-utils.js";
 import { repairServiceUnitAfterUpdate } from "./service-self-repair.js";
 import { computeRelaunch } from "./relaunch.js";
@@ -1851,11 +1851,8 @@ export async function startServer(config, configPath) {
                 res.status(502).json({ error: "无法连接到 npm registry。" });
                 return;
             }
-            if (!info.updateAvailable) {
-                res.json({ ok: true, message: channel === "beta" ? "已是最新 Beta 版本。" : "已经是最新版本。" });
-                return;
-            }
             const targetLabel = info.latest;
+            const reinstalling = !info.updateAvailable;
             if (!canUseDetachedUpdateHelper()) {
                 res.status(500).json({ error: "当前平台暂不支持 Web 异步更新，请在终端运行 install.sh 更新。" });
                 return;
@@ -1886,7 +1883,7 @@ export async function startServer(config, configPath) {
             });
             res.json({
                 ok: true,
-                message: `已开始更新到 ${targetLabel}`,
+                message: reinstalling ? `已开始重新安装 ${targetLabel}` : `已开始更新到 ${targetLabel}`,
                 restartRequired: false,
                 detachedUpdate: true,
                 version: targetLabel,
@@ -2355,6 +2352,7 @@ export async function startServer(config, configPath) {
         }
         const initialInput = body.initialInput?.trim();
         try {
+            const origin = parseSessionCreationOrigin(body);
             const rawModel = typeof body.model === "string" ? body.model.trim() : "";
             const provider = body.provider === "codex" || /^codex\b/.test(body.command.trim()) ? "codex" : "claude";
             const effectiveModel = rawModel || getDefaultModelForProvider(config, provider) || undefined;
@@ -2367,6 +2365,7 @@ export async function startServer(config, configPath) {
                 cols: reqCols,
                 rows: reqRows,
                 thinkingEffort: body.thinkingEffort ?? config.defaultThinkingEffort,
+                ...origin,
             });
             recordRecentPath(storage, snapshot.cwd);
             res.status(201).json(snapshot);

package/dist/storage.js

@@ -53,6 +53,9 @@ function normalizeWorktreeMergeStatus(raw) {
     }
     return undefined;
 }
+function normalizeSessionSource(raw) {
+    return raw === "automation" || raw === "startup" || raw === "interactive" ? raw : "interactive";
+}
 function mapWorktreeMergeFields(row) {
     return {
         worktreeMergeStatus: normalizeWorktreeMergeStatus(row.worktree_merge_status),
@@ -60,16 +63,18 @@ function mapWorktreeMergeFields(row) {
     };
 }
 function sessionSelectFields() {
-    return `id, provider, session_kind, runner, command, cwd, mode, status, exit_code, started_at, ended_at, output, archived, archived_at, claude_session_id, messages, queued_messages, structured_state
+    return `id, session_source, automation_id, provider, session_kind, runner, command, cwd, mode, status, exit_code, started_at, ended_at, output, archived, archived_at, claude_session_id, messages, queued_messages, structured_state
              , resumed_from_session_id, auto_recovered, worktree_enabled, worktree_info, worktree_merge_status, worktree_merge_info, title, description`;
 }
 function sessionPersistFields() {
-    return `id, command, cwd, mode, status, exit_code, started_at, ended_at, output
+    return `id, session_source, automation_id, command, cwd, mode, status, exit_code, started_at, ended_at, output
              , archived, archived_at, claude_session_id, provider, session_kind, runner, messages, queued_messages, structured_state
              , resumed_from_session_id, auto_recovered, worktree_enabled, worktree_info, worktree_merge_status, worktree_merge_info, title, description`;
 }
 function sessionPersistAssignments() {
-    return `command = excluded.command,
+    return `session_source = excluded.session_source,
+             automation_id = excluded.automation_id,
+             command = excluded.command,
              cwd = excluded.cwd,
              mode = excluded.mode,
              status = excluded.status,
@@ -96,7 +101,8 @@ function sessionPersistAssignments() {
              description = excluded.description`;
 }
 function sessionMetadataAssignments() {
-    return `command = ?, cwd = ?, mode = ?, status = ?, exit_code = ?,
+    return `session_source = ?, automation_id = ?,
+           command = ?, cwd = ?, mode = ?, status = ?, exit_code = ?,
            started_at = ?, ended_at = ?, output = ?,
            archived = ?, archived_at = ?, claude_session_id = ?,
            provider = ?, session_kind = ?, runner = ?, structured_state = ?,
@@ -107,6 +113,8 @@ function sessionMetadataAssignments() {
 function sessionPersistValues(snapshot) {
     return [
         snapshot.id,
+        normalizeSessionSource(snapshot.sessionSource),
+        snapshot.automationId ?? null,
         snapshot.command,
         snapshot.cwd,
         snapshot.mode,
@@ -136,6 +144,8 @@ function sessionPersistValues(snapshot) {
 }
 function sessionMetadataValues(snapshot) {
     return [
+        normalizeSessionSource(snapshot.sessionSource),
+        snapshot.automationId ?? null,
         snapshot.command,
         snapshot.cwd,
         snapshot.mode,
@@ -166,6 +176,8 @@ function mapSessionCore(row) {
     const provider = inferSessionProvider(row);
     return {
         id: row.id,
+        sessionSource: normalizeSessionSource(row.session_source),
+        automationId: row.automation_id ?? undefined,
         sessionKind: row.session_kind ?? "pty",
         provider,
         runner: row.runner ?? undefined,
@@ -207,6 +219,8 @@ const INIT_SQL = `
 
   CREATE TABLE IF NOT EXISTS command_sessions (
     id TEXT PRIMARY KEY,
+    session_source TEXT NOT NULL DEFAULT 'interactive',
+    automation_id TEXT,
     command TEXT NOT NULL,
     cwd TEXT NOT NULL,
     mode TEXT NOT NULL,
@@ -506,7 +520,7 @@ export class WandStorage {
             this.db
                 .prepare(`INSERT INTO command_sessions (
            ${sessionPersistFields()}
-           ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+           ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
            ON CONFLICT(id) DO UPDATE SET
              ${sessionPersistAssignments()}`)
                 .run(...sessionPersistValues(snapshot));
@@ -603,6 +617,8 @@ function mapPasswordItemRow(row) {
     };
 }
 const SCHEMA_MIGRATIONS = [
+    ["session_source", "ALTER TABLE command_sessions ADD COLUMN session_source TEXT NOT NULL DEFAULT 'interactive'"],
+    ["automation_id", "ALTER TABLE command_sessions ADD COLUMN automation_id TEXT"],
     ["archived", "ALTER TABLE command_sessions ADD COLUMN archived INTEGER NOT NULL DEFAULT 0"],
     ["archived_at", "ALTER TABLE command_sessions ADD COLUMN archived_at TEXT"],
     ["claude_session_id", "ALTER TABLE command_sessions ADD COLUMN claude_session_id TEXT"],

package/dist/structured-session-manager.d.ts

@@ -1,6 +1,6 @@
 import { SessionLogger } from "./session-logger.js";
 import { WandStorage } from "./storage.js";
-import { ContentBlock, ExecutionMode, ProcessEvent, SessionProvider, SessionRunner, SessionSnapshot, WandConfig } from "./types.js";
+import { ContentBlock, ExecutionMode, ProcessEvent, SessionProvider, SessionRunner, SessionSnapshot, SessionSource, WandConfig } from "./types.js";
 interface CreateStructuredSessionOptions {
     cwd: string;
     mode: ExecutionMode;
@@ -12,6 +12,8 @@ interface CreateStructuredSessionOptions {
     model?: string;
     /** 用户预设的思考深度。留空 / null 视为 off。 */
     thinkingEffort?: SessionSnapshot["thinkingEffort"];
+    sessionSource?: SessionSource;
+    automationId?: string;
     /**
      * 恢复用的初始会话 id：
      *   - Codex：历史 thread id，首条消息即 `codex exec ... resume <id>` 续接。

package/dist/structured-session-manager.js

@@ -805,6 +805,8 @@ export class StructuredSessionManager {
             const restored = {
                 ...snapshot,
                 sessionKind: "structured",
+                sessionSource: snapshot.sessionSource ?? "interactive",
+                automationId: snapshot.automationId,
                 provider: snapshot.provider ?? snapshot.structuredState?.provider ?? "claude",
                 runner: snapshot.runner ?? snapshot.structuredState?.runner ?? defaultStructuredRunner(snapshot.provider ?? snapshot.structuredState?.provider ?? "claude"),
                 status: restoredStatus,
@@ -923,6 +925,8 @@ export class StructuredSessionManager {
         const snapshot = {
             id,
             sessionKind: "structured",
+            sessionSource: options.sessionSource ?? "interactive",
+            automationId: options.automationId,
             provider,
             runner,
             command: provider === "codex"

package/dist/types.d.ts

@@ -1,6 +1,7 @@
 export type SessionKind = "pty" | "structured";
 export type SessionProvider = "claude" | "codex";
 export type SessionRunner = "claude-cli" | "claude-cli-print" | "claude-sdk" | "codex-cli-exec" | "pty";
+export type SessionSource = "interactive" | "automation" | "startup";
 export type ExecutionMode = "assist" | "agent" | "agent-max" | "default" | "auto-edit" | "full-access" | "native" | "managed";
 export type AutonomyPolicy = "assist" | "agent" | "agent-max";
 export type ApprovalPolicy = "ask-every-time" | "approve-once" | "remember-this-turn";
@@ -403,6 +404,10 @@ export interface StructuredSessionState {
 }
 export interface SessionSnapshot {
     id: string;
+    /** 会话创建来源。旧数据和缺省值按 interactive 处理。 */
+    sessionSource?: SessionSource;
+    /** 自动化创建会话时关联的自动化任务 ID。 */
+    automationId?: string;
     sessionKind?: SessionKind;
     provider?: SessionProvider;
     runner?: SessionRunner;

package/dist/update-helper.d.ts

@@ -4,6 +4,7 @@ export interface DetachedUpdateOptions {
     configPath: string;
     parentPid: number;
     cliArgs: string[];
+    nodeLoaderArgs?: string[];
     cwd: string;
     env: NodeJS.ProcessEnv;
     timeoutMs?: number;

package/dist/update-helper.js

@@ -143,7 +143,23 @@ export function checkManagedServiceUpdatePreflight() {
 export function shouldUseSystemdRunForDetachedUpdate(serviceScope) {
     return serviceScope !== null;
 }
-const DEFAULT_UPDATE_UTILS_PATH = path.join(path.dirname(fileURLToPath(import.meta.url)), "npm-update-utils.js");
+function resolveDefaultUpdateUtilsPath() {
+    const moduleDir = path.dirname(fileURLToPath(import.meta.url));
+    const compiledPath = path.join(moduleDir, "npm-update-utils.js");
+    if (existsSync(compiledPath))
+        return compiledPath;
+    const sourcePath = path.join(moduleDir, "npm-update-utils.ts");
+    return existsSync(sourcePath) ? sourcePath : compiledPath;
+}
+function resolveTypeScriptLoaderArgs() {
+    try {
+        return ["--import", import.meta.resolve("tsx")];
+    }
+    catch {
+        return [];
+    }
+}
+const DEFAULT_UPDATE_UTILS_PATH = resolveDefaultUpdateUtilsPath();
 /** Exported so the safety-critical update flow can be exercised without starting a detached process. */
 export function buildDetachedUpdateHelperScript(opts, logPath, serviceScope, updateUtilsPath = DEFAULT_UPDATE_UTILS_PATH) {
     if (!Number.isSafeInteger(opts.parentPid) || opts.parentPid <= 1) {
@@ -155,6 +171,12 @@ export function buildDetachedUpdateHelperScript(opts, logPath, serviceScope, upd
     const timeoutMs = Number.isFinite(requestedTimeout)
         ? Math.max(30_000, Math.trunc(requestedTimeout))
         : 300_000;
+    const nodeLoaderArgs = opts.nodeLoaderArgs
+        ?? (updateUtilsPath.endsWith(".ts") ? resolveTypeScriptLoaderArgs() : []);
+    if (updateUtilsPath.endsWith(".ts") && nodeLoaderArgs.length === 0) {
+        throw new Error("本地 TypeScript 更新 helper 无法解析 tsx loader，请先运行 npm install。");
+    }
+    const nodeLoaderCommand = nodeLoaderArgs.length > 0 ? `${shellArray(nodeLoaderArgs)} ` : "";
     return `#!/usr/bin/env bash
 set -euo pipefail
 LOG=${shellQuote(logPath)}
@@ -220,16 +242,18 @@ resolve_global_cli() {
 
 main() {
   echo "[wand-update] installing while parent service stays online"
-  if run "$NODE_BIN" --input-type=module - "$UPDATE_UTILS" "$INSTALL_SPEC" "$TIMEOUT_MS" <<'WAND_INSTALL_NODE'
+  if run "$NODE_BIN" ${nodeLoaderCommand}--input-type=module - "$UPDATE_UTILS" "$INSTALL_SPEC" "$TIMEOUT_MS" <<'WAND_INSTALL_NODE'
 import { pathToFileURL } from "node:url";
 
 const [modulePath, installSpec, timeoutValue] = process.argv.slice(2);
 const timeoutMs = Number(timeoutValue);
 const updateUtils = await import(pathToFileURL(modulePath).href);
-if (typeof updateUtils.installPackageGloballyAsync !== "function") {
+const installPackageGloballyAsync = updateUtils.installPackageGloballyAsync
+  ?? updateUtils.default?.installPackageGloballyAsync;
+if (typeof installPackageGloballyAsync !== "function") {
   throw new Error("installPackageGloballyAsync is unavailable in " + modulePath);
 }
-await updateUtils.installPackageGloballyAsync(installSpec, timeoutMs, (line) => {
+await installPackageGloballyAsync(installSpec, timeoutMs, (line) => {
   process.stdout.write(String(line) + "\\n");
 });
 WAND_INSTALL_NODE