jishushell 0.6.5 → 0.7.3

package/dist/services/app-common/lifecycle-scripts.js

@@ -0,0 +1,935 @@
+import { existsSync, mkdtempSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, unlinkSync, writeFileSync, chmodSync, chownSync, lstatSync, } from "fs";
+import { homedir, tmpdir } from "os";
+import { join, dirname } from "path";
+import { spawn, spawnSync } from "child_process";
+import * as config from "../../config.js";
+import { emitTask } from "../tasks/registry.js";
+import { createInvalidSudoPasswordError, isSudoAuthenticationError, isSudoNoNewPrivilegesError, isSudoPasswordRequiredError, prepareSudoAskpassEnv, SUDO_PASSTHROUGH_ENV_KEYS, } from "../../utils/sudo-askpass.js";
+import { listBuiltinAppSpecs } from "./catalog-service.js";
+import { getInstanceInstallRecordRuntimeStatus } from "./execution-service.js";
+import { ANONYMOUS_DOWNLOAD_IMAGE_ALLOWLIST, ANONYMOUS_DOWNLOAD_IMAGE_REPOSITORY_ALLOWLIST, CURRENT_JISHUSHELL_VERSION, DEFAULT_LIFECYCLE_PATH, MACOS_LIFECYCLE_PATH_PROBES, expandPath, } from "./app-shared.js";
+function parseComparableVersion(version, label) {
+    const normalized = version
+        .trim()
+        .replace(/^>=\s*/, "")
+        .replace(/^v/i, "")
+        .replace(/[-+].*$/, "");
+    const match = normalized.match(/^(\d+)(?:\.(\d+))?(?:\.(\d+))?$/);
+    if (!match) {
+        throw new Error(`${label} '${version}' 格式无效，应为 x.y.z`);
+    }
+    return [
+        Number(match[1] ?? 0),
+        Number(match[2] ?? 0),
+        Number(match[3] ?? 0),
+    ];
+}
+function compareVersions(left, right) {
+    for (let index = 0; index < 3; index++) {
+        if (left[index] > right[index])
+            return 1;
+        if (left[index] < right[index])
+            return -1;
+    }
+    return 0;
+}
+function requiredJishuShellVersion(spec) {
+    const required = spec.jishushell?.min_version?.trim();
+    if (!required) {
+        throw new Error(`App '${spec.id}' 缺少 jishushell.min_version，请先在 YAML 中声明支持的最低 JishuShell 版本`);
+    }
+    return required;
+}
+function ensureCompatibleJishuShellVersion(spec) {
+    const required = requiredJishuShellVersion(spec);
+    const current = parseComparableVersion(CURRENT_JISHUSHELL_VERSION, "当前 JishuShell 版本");
+    const minimum = parseComparableVersion(required, "jishushell.min_version");
+    if (compareVersions(current, minimum) < 0) {
+        throw new Error(`当前 JishuShell 版本 ${CURRENT_JISHUSHELL_VERSION} 低于应用要求 ${required}，请先升级 JishuShell`);
+    }
+}
+function buildDeterministicPath(basePath, extraPaths = []) {
+    return [basePath ?? "", DEFAULT_LIFECYCLE_PATH, dirname(process.execPath), ...extraPaths]
+        .flatMap((entry) => entry.split(":"))
+        .map((entry) => entry.trim())
+        .filter(Boolean)
+        .filter((entry, index, entries) => entries.indexOf(entry) === index)
+        .join(":");
+}
+function buildLifecycleEnv() {
+    const extraPaths = process.platform === "darwin"
+        ? MACOS_LIFECYCLE_PATH_PROBES.filter((entry) => existsSync(entry))
+        : [];
+    const mergedPath = buildDeterministicPath(process.env.PATH, extraPaths);
+    // Surface core callback hooks to lifecycle scripts and internal shims.
+    // Managed instance helpers such as the OpenClaw drive shim use
+    // JISHUSHELL_CORE_URL + JISHUSHELL_INTERNAL_TOKEN together with
+    // X-Jishushell-Instance to call Core-owned internal routes without a user
+    // JWT. Best-effort: if the token file or port lookup fails we just omit
+    // the vars and the caller gets a clean "missing env" failure path.
+    const coreHooks = {};
+    try {
+        coreHooks.JISHUSHELL_CORE_URL = `http://127.0.0.1:${config.getCorePort()}`;
+        coreHooks.JISHUSHELL_INTERNAL_TOKEN = config.getInternalMcpToken();
+        // LAN host that *other* services (and the post_start script's curls into
+        // its own service) can reach. AnythingLLM binds eth0 via Nomad's
+        // `external` host_network, so the panel-host loopback (127.0.0.1) won't
+        // reach 18097 — post_start needs to hit the LAN IP to check its own
+        // health. getCoreLanHost() returns the same IP Nomad publishes ports on.
+        coreHooks.JISHUSHELL_LAN_HOST = config.getCoreLanHost();
+    }
+    catch {
+        // tolerate — only post_start cares
+    }
+    return {
+        ...process.env,
+        HOME: process.env.HOME ?? homedir(),
+        PATH: mergedPath,
+        ...coreHooks,
+    };
+}
+function buildSudoWrappedCommand(cmd, args, env, execOptions) {
+    const sudoArgs = execOptions?.sudoPassword ? ["-k", "-A"] : ["-n"];
+    const envArgs = SUDO_PASSTHROUGH_ENV_KEYS.flatMap((key) => {
+        const value = env[key];
+        return typeof value === "string" && value.length > 0 ? [`${key}=${value}`] : [];
+    });
+    return {
+        command: "sudo",
+        args: [...sudoArgs, "--", "env", ...envArgs, cmd, ...args],
+    };
+}
+function createLifecycleSudoError(stderr, fallbackDisplay, hasPassword) {
+    const message = sanitizeTaskLine(stderr).trim();
+    if (isSudoNoNewPrivilegesError(message)) {
+        return createNoNewPrivilegesSudoError();
+    }
+    if (isSudoAuthenticationError(message)) {
+        return createInvalidSudoPasswordError();
+    }
+    if (!hasPassword && isSudoPasswordRequiredError(message)) {
+        return new Error("该生命周期步骤需要 sudo 密码；请在页面弹窗中输入后重试。");
+    }
+    if (message) {
+        return new Error(message);
+    }
+    return new Error(`lifecycle sudo step failed: ${fallbackDisplay}`);
+}
+function materializeLifecycleInstanceTokens(value, instanceId) {
+    if (!instanceId)
+        return value;
+    if (typeof value === "string") {
+        return value.replace(/\$\{instance\.id\}/g, instanceId);
+    }
+    if (Array.isArray(value)) {
+        return value.map((entry) => materializeLifecycleInstanceTokens(entry, instanceId));
+    }
+    if (value && typeof value === "object") {
+        const rewritten = {};
+        for (const [key, entry] of Object.entries(value)) {
+            rewritten[key] = materializeLifecycleInstanceTokens(entry, instanceId);
+        }
+        return rewritten;
+    }
+    return value;
+}
+function coreSystemdServicePath() {
+    const override = process.env.JISHUSHELL_CORE_SYSTEMD_SERVICE_PATH?.trim();
+    return override || "/etc/systemd/system/jishushell.service";
+}
+function isLikelySystemdServiceProcess() {
+    return Boolean(process.env.INVOCATION_ID
+        || process.env.JOURNAL_STREAM
+        || process.env.NOTIFY_SOCKET
+        || process.env.JISHUSHELL_CORE_SYSTEMD_SERVICE_PATH?.trim());
+}
+function maybeRepairCoreAutostartNoNewPrivileges() {
+    if (!isLikelySystemdServiceProcess())
+        return null;
+    const servicePath = coreSystemdServicePath();
+    if (!existsSync(servicePath))
+        return null;
+    let unitText = "";
+    try {
+        unitText = readFileSync(servicePath, "utf-8");
+    }
+    catch {
+        return { servicePath, detected: true, updated: false };
+    }
+    if (!/^\s*NoNewPrivileges\s*=\s*true\s*$/mi.test(unitText)) {
+        return null;
+    }
+    const nextText = unitText.replace(/^\s*NoNewPrivileges\s*=\s*true\s*\n?/gim, "");
+    if (nextText === unitText) {
+        return { servicePath, detected: true, updated: false };
+    }
+    try {
+        writeFileSync(servicePath, nextText);
+        return { servicePath, detected: true, updated: true };
+    }
+    catch {
+        return { servicePath, detected: true, updated: false };
+    }
+}
+function manualInstallCommandForSpec(spec) {
+    if (spec.id === "ollama-binary") {
+        return "jishushell app install ollama";
+    }
+    const builtin = listBuiltinAppSpecs().find((entry) => entry.id === spec.id);
+    if (!builtin)
+        return null;
+    return `jishushell app install ${spec.id}`;
+}
+function createNoNewPrivilegesSudoError(manualInstallCommand) {
+    const repair = maybeRepairCoreAutostartNoNewPrivileges();
+    const restartCommand = "sudo systemctl daemon-reload && sudo systemctl restart jishushell";
+    const parts = ["当前运行环境禁止 sudo 提权（no new privileges），面板内无法继续后续安装。"];
+    if (repair?.updated) {
+        parts.push(`已从自启文件 ${repair.servicePath} 移除 NoNewPrivileges=true。请在系统终端执行以下命令后重试：\n${restartCommand}`);
+    }
+    else if (repair?.detected) {
+        parts.push(`检测到自启文件 ${repair.servicePath} 仍包含 NoNewPrivileges=true。请在系统终端删除该行后执行：\n${restartCommand}`);
+    }
+    if (manualInstallCommand) {
+        parts.push(`当前安装已停止。你也可以在系统终端手动执行 ${manualInstallCommand}。`);
+    }
+    return new Error(parts.join("\n"));
+}
+export function decorateInstallError(error, spec) {
+    const original = error instanceof Error ? error : new Error(String(error));
+    if (!isSudoNoNewPrivilegesError(original.message) && !/NoNewPrivileges=true/i.test(original.message)) {
+        return original;
+    }
+    return createNoNewPrivilegesSudoError(manualInstallCommandForSpec(spec) ?? undefined);
+}
+export async function validateSudoPassword(sudoPassword) {
+    if (!sudoPassword) {
+        throw new Error("请输入 sudo 密码");
+    }
+    if (typeof process.getuid === "function" && process.getuid() === 0) {
+        return;
+    }
+    const preparedEnv = prepareLifecycleExecEnv({ sudoPassword });
+    try {
+        await new Promise((resolve, reject) => {
+            const child = spawn("sudo", ["-k", "-A", "true"], {
+                stdio: ["ignore", "ignore", "pipe"],
+                env: preparedEnv.env,
+                timeout: 15_000,
+            });
+            let stderr = "";
+            child.stderr?.on("data", (chunk) => {
+                stderr += chunk.toString("utf-8");
+            });
+            child.on("close", (code) => {
+                if (code === 0) {
+                    resolve();
+                    return;
+                }
+                const message = sanitizeTaskLine(stderr).trim();
+                if (isSudoNoNewPrivilegesError(message)) {
+                    reject(createNoNewPrivilegesSudoError());
+                    return;
+                }
+                if (isSudoAuthenticationError(message)) {
+                    reject(createInvalidSudoPasswordError());
+                    return;
+                }
+                resolve();
+            });
+            child.on("error", (_error) => {
+                resolve();
+            });
+        });
+    }
+    finally {
+        preparedEnv.cleanup();
+    }
+}
+function prepareLifecycleExecEnv(execOptions, envOverrides) {
+    const env = {
+        ...buildLifecycleEnv(),
+        ...(envOverrides ?? {}),
+    };
+    const sudoPassword = execOptions?.sudoPassword;
+    if (!sudoPassword) {
+        return { env, cleanup: () => undefined };
+    }
+    return prepareSudoAskpassEnv(sudoPassword, env);
+}
+function shouldBypassDockerCredentialHelperForDownloadImage(image) {
+    const trimmedImage = image.trim();
+    return ANONYMOUS_DOWNLOAD_IMAGE_ALLOWLIST.has(trimmedImage)
+        || ANONYMOUS_DOWNLOAD_IMAGE_REPOSITORY_ALLOWLIST.has(normalizeDockerImageRepository(trimmedImage));
+}
+function normalizeDockerImageRepository(image) {
+    const digestIndex = image.indexOf("@");
+    const imageWithoutDigest = digestIndex >= 0 ? image.slice(0, digestIndex) : image;
+    const lastSlashIndex = imageWithoutDigest.lastIndexOf("/");
+    const lastColonIndex = imageWithoutDigest.lastIndexOf(":");
+    return lastColonIndex > lastSlashIndex
+        ? imageWithoutDigest.slice(0, lastColonIndex)
+        : imageWithoutDigest;
+}
+function createAnonymousDockerConfig() {
+    const dockerConfigDir = mkdtempSync(join(tmpdir(), "jishushell-docker-config-"));
+    writeFileSync(join(dockerConfigDir, "config.json"), `${JSON.stringify({ auths: {} }, null, 2)}\n`, { mode: 0o600 });
+    return {
+        envOverrides: {
+            DOCKER_CONFIG: dockerConfigDir,
+        },
+        cleanup: () => {
+            try {
+                rmSync(dockerConfigDir, { recursive: true, force: true });
+            }
+            catch {
+                // best effort cleanup for one-shot anonymous docker config files
+            }
+        },
+    };
+}
+const ANSI_ESCAPE_RE = /\u001B(?:[@-Z\\-_]|\[[0-?]*[ -/]*[@-~])/g;
+function sanitizeTaskLine(line) {
+    return line
+        .replace(ANSI_ESCAPE_RE, "")
+        .replace(/[\u0000-\u0008\u000B-\u001F\u007F]/g, "")
+        .trimEnd();
+}
+export function emitInstallTaskLog(task, message) {
+    if (!task)
+        return;
+    const line = sanitizeTaskLine(message).trim();
+    if (!line)
+        return;
+    emitTask(task, { type: "log", message: line });
+}
+export function selectRollbackUninstallSteps(steps, ownedArtifacts) {
+    if (!steps?.length)
+        return [];
+    const ownedImages = new Set(ownedArtifacts.filter((a) => a.type === "image").map((a) => a.path));
+    const ownedDirs = new Set(ownedArtifacts.filter((a) => a.type === "dir").map((a) => a.path));
+    const ownedBinaries = new Set(ownedArtifacts.filter((a) => a.type === "binary").map((a) => a.path));
+    return steps.filter((step) => {
+        if ("deleteImage" in step)
+            return ownedImages.has(step.deleteImage);
+        if ("deleteDir" in step)
+            return ownedDirs.has(expandPath(step.deleteDir));
+        if ("deleteBinary" in step)
+            return ownedBinaries.has(expandPath(step.deleteBinary));
+        if ("run" in step)
+            return true;
+        return false;
+    });
+}
+function spawnStep(label, display, cmd, args, task) {
+    return spawnStepWithTimeout(label, display, display, cmd, args, 300_000, task);
+}
+const DOCKER_PULL_RETRY_ATTEMPTS = 3;
+// spawnStep's 5-min default is fine for small CLI calls but starves real-world
+// image pulls on ARM + SD-card hardware. Hermes is ~2.4 GB compressed and may
+// not extract in 5 min on a Raspberry Pi. 30 min leaves headroom while still
+// capping runaway failures (total retry budget 90 min).
+const DOCKER_PULL_TIMEOUT_MS = 1_800_000;
+// Separate from the total timeout above: if docker pull stops producing any
+// stdout/stderr for long enough, treat it as stalled and retry rather than
+// waiting the full 30 minutes.
+//
+// Why 600s (not 180s): on slow links (especially Docker Hub from China to
+// edge devices), large single layers — AnythingLLM ~500MB, Hermes ~2.4GB —
+// can spend 5-8 minutes between progress lines without TTY. 180s
+// idle was killing pulls that were actually making progress, then rolling
+// back the partially-completed image. Layer cache is preserved across
+// retries (docker dedupes by layer sha), so a higher idle ceiling lets each
+// big layer finish without throwing away the layers already on disk.
+const DOCKER_PULL_IDLE_TIMEOUT_MS = 600_000;
+export async function pullDockerImageStep(label, image, display, task, timeoutMs = DOCKER_PULL_TIMEOUT_MS, idleTimeoutMs) {
+    if (await dockerImageExists(image)) {
+        const skipMessage = `[lifecycle:${label}] docker image '${image}' already exists locally; skipping pull`;
+        process.stdout.write(`  ${skipMessage}\n`);
+        emitInstallTaskLog(task, skipMessage);
+        return false;
+    }
+    const anonymousDockerConfig = shouldBypassDockerCredentialHelperForDownloadImage(image)
+        ? createAnonymousDockerConfig()
+        : null;
+    let lastError;
+    try {
+        for (let attempt = 1; attempt <= DOCKER_PULL_RETRY_ATTEMPTS; attempt++) {
+            try {
+                await spawnStepWithTimeout(label, display, display, "docker", ["pull", image], timeoutMs, task, undefined, undefined, {
+                    idleTimeoutMs: idleTimeoutMs ?? Math.min(DOCKER_PULL_IDLE_TIMEOUT_MS, timeoutMs),
+                    envOverrides: anonymousDockerConfig?.envOverrides,
+                    stallMessageHint: "Docker credential resolution (for example docker-credential-desktop) may be involved.",
+                });
+                return true;
+            }
+            catch (error) {
+                if (await dockerImageExists(image)) {
+                    const recoveredMessage = `[lifecycle:${label}] docker image '${image}' is present locally after pull failure/timeout; treating step as successful`;
+                    process.stdout.write(`  ${recoveredMessage}\n`);
+                    emitInstallTaskLog(task, recoveredMessage);
+                    return true;
+                }
+                lastError = error;
+                if (attempt === DOCKER_PULL_RETRY_ATTEMPTS) {
+                    break;
+                }
+                const reason = error instanceof Error ? error.message : String(error);
+                const retryMessage = `[lifecycle:${label}] docker pull failed for ${image} (attempt ${attempt}/${DOCKER_PULL_RETRY_ATTEMPTS}): ${reason}; retrying`;
+                process.stdout.write(`  ${retryMessage}\n`);
+                emitInstallTaskLog(task, retryMessage);
+            }
+        }
+    }
+    finally {
+        anonymousDockerConfig?.cleanup();
+    }
+    throw (lastError instanceof Error ? lastError : new Error(String(lastError)));
+}
+/**
+ * In-flight background pulls keyed by image tag. Used by
+ * `pullDockerImageInBackground` to dedup concurrent requests so repeated
+ * UI clicks for the same not-yet-local image don't queue duplicate pulls.
+ */
+const inFlightBackgroundPulls = new Map();
+/**
+ * Fire-and-forget background docker pull. Used by `*-manager.ts`
+ * (custom / hermes / ollama) when an instance is requested with an image
+ * that's not yet local: kicks off a pull in the background and the caller
+ * asks the user to retry later (HTTP 202).
+ *
+ * Wraps the same `pullDockerImageStep` used by full installs, so it
+ * inherits the same protections — total timeout (30 min), idle timeout
+ * (10 min of silence on the pull's stdout/stderr terminates it), 3
+ * retries, and a post-failure `dockerImageExists` recovery check — that
+ * a bare `exec("docker pull ...", { timeout: 0 })` lacks. Docker Desktop
+ * on macOS can hang the CLI for tens of minutes after the image has been
+ * fully downloaded (the final manifest/tag write step occasionally
+ * deadlocks); the idle timer kills the hung CLI and the recovery check
+ * picks up the image if the tag did make it through.
+ *
+ * Concurrent calls for the same image dedup onto a single in-flight pull
+ * so repeated UI clicks don't waste retries.
+ *
+ * Always resolves — errors are logged via console.warn so the
+ * fire-and-forget caller doesn't have to attach a `.catch` handler.
+ */
+export function pullDockerImageInBackground(label, image) {
+    const existing = inFlightBackgroundPulls.get(image);
+    if (existing)
+        return existing;
+    const promise = (async () => {
+        try {
+            await pullDockerImageStep(`${label}-background`, image, `docker pull ${image} (background)`);
+        }
+        catch (err) {
+            const reason = err instanceof Error ? err.message : String(err);
+            console.warn(`[${label}] Background pull of ${image} failed: ${reason}`);
+        }
+        finally {
+            inFlightBackgroundPulls.delete(image);
+        }
+    })();
+    inFlightBackgroundPulls.set(image, promise);
+    return promise;
+}
+async function dockerImageExists(image) {
+    return new Promise((resolve) => {
+        const child = spawn("docker", ["image", "inspect", image], {
+            stdio: "ignore",
+            env: buildLifecycleEnv(),
+        });
+        let settled = false;
+        const finish = (value) => {
+            if (settled)
+                return;
+            settled = true;
+            resolve(value);
+        };
+        // `docker image inspect` is a local-only daemon API call that should
+        // return in milliseconds. In practice, when dockerd itself wedges
+        // (the same failure mode that causes `docker pull` to hang), `docker
+        // image inspect` hangs too. Without this timeout the inspect call
+        // ties up the install lifecycle's post-failure recovery check, which
+        // in turn keeps the install lock held indefinitely. 10s is generous
+        // for a healthy daemon and short enough that a wedged daemon doesn't
+        // block install retry/recovery.
+        const watchdog = setTimeout(() => {
+            try {
+                child.kill("SIGKILL");
+            }
+            catch {
+                /* already exited */
+            }
+            finish(false);
+        }, 10_000);
+        watchdog.unref?.();
+        child.on("close", (code) => {
+            clearTimeout(watchdog);
+            finish(code === 0);
+        });
+        child.on("error", () => {
+            clearTimeout(watchdog);
+            finish(false);
+        });
+    });
+}
+/**
+ * Force-terminate a spawned child: send `SIGTERM`, then escalate to
+ * `SIGKILL` after a grace period if the process is still alive.
+ *
+ * Needed because some CLIs (notably `docker` on macOS when its daemon
+ * has wedged) block on a daemon round-trip and ignore `SIGTERM` until
+ * the daemon responds. Without `SIGKILL` escalation the parent
+ * `child.on("close")` handler never fires, the lifecycle promise never
+ * resolves, and the install task hangs forever holding its lock.
+ *
+ * The grace period must be long enough for well-behaved children to
+ * flush buffers and exit cleanly on SIGTERM (avoid corrupt artifacts in
+ * the common case) but short enough that a hung child doesn't waste a
+ * meaningful slice of the parent's overall budget. 30s is the sweet
+ * spot in practice for docker-class tooling.
+ */
+function forceTerminateChild(child, label) {
+    try {
+        child.kill("SIGTERM");
+    }
+    catch {
+        /* already exited */
+    }
+    // Unref'd so it doesn't keep the event loop alive. If the child
+    // exited cleanly under SIGTERM before this fires, `kill("SIGKILL")`
+    // on a dead process is a harmless no-op (and we try/catch around it
+    // anyway). We deliberately do NOT register an extra `on("close")`
+    // listener to cancel this timer — some lifecycle paths use bare
+    // mock children whose `on` is single-slot and a second listener
+    // would clobber the parent's reject handler.
+    const killTimer = setTimeout(() => {
+        if (child.exitCode !== null || child.signalCode !== null)
+            return;
+        process.stdout.write(`  [lifecycle:${label}] child ignored SIGTERM after 30s; escalating to SIGKILL\n`);
+        try {
+            child.kill("SIGKILL");
+        }
+        catch {
+            /* already exited */
+        }
+    }, 30_000);
+    killTimer.unref?.();
+}
+function spawnStepWithTimeout(label, display, taskDisplay, cmd, args, timeoutMs, task, execOptions, sudo, runOptions) {
+    process.stdout.write(`  [lifecycle:${label}] ${display}\n`);
+    emitInstallTaskLog(task, `[lifecycle:${label}] ${taskDisplay}`);
+    return new Promise((resolve, reject) => {
+        const preparedEnv = prepareLifecycleExecEnv(sudo ? execOptions : undefined, runOptions?.envOverrides);
+        let cleaned = false;
+        let heartbeatTimer = null;
+        let idleTimer = null;
+        let stdoutPending = "";
+        let stderrPending = "";
+        let capturedStderr = "";
+        let forcedError = null;
+        let totalTimeoutTimer = null;
+        const cleanupPreparedEnv = () => {
+            if (cleaned)
+                return;
+            cleaned = true;
+            if (heartbeatTimer) {
+                clearInterval(heartbeatTimer);
+                heartbeatTimer = null;
+            }
+            if (idleTimer) {
+                clearTimeout(idleTimer);
+                idleTimer = null;
+            }
+            if (totalTimeoutTimer) {
+                clearTimeout(totalTimeoutTimer);
+                totalTimeoutTimer = null;
+            }
+            preparedEnv.cleanup();
+        };
+        const spawnTarget = sudo
+            ? buildSudoWrappedCommand(cmd, args, preparedEnv.env, execOptions)
+            : { command: cmd, args };
+        const captureOutput = Boolean(task) || Boolean(sudo) || Boolean(runOptions?.idleTimeoutMs);
+        const child = spawn(spawnTarget.command, spawnTarget.args, {
+            stdio: captureOutput ? ["ignore", "pipe", "pipe"] : "inherit",
+            // Node's spawn `timeout` sends SIGTERM at the deadline but has no
+            // SIGKILL escalation, so a child that ignores SIGTERM (docker CLI
+            // on macOS when its daemon is wedged) still blocks the parent's
+            // `child.on("close")`. We keep this here so callers / tests can
+            // observe the configured budget on the spawn options, and add the
+            // `totalKillEscalationTimer` below to SIGKILL after a grace.
+            timeout: timeoutMs,
+            env: preparedEnv.env,
+        });
+        // SIGKILL escalation for the total-timeout case. Node's `timeout`
+        // option above will have sent SIGTERM at `timeoutMs`; if the child
+        // hasn't exited within `timeoutMs + 30s` we force it. Independent
+        // of the idle timer's escalation (which `forceTerminateChild`
+        // handles inline) — covers the path where output keeps flowing but
+        // the total budget is blown.
+        totalTimeoutTimer = setTimeout(() => {
+            if (child.exitCode !== null || child.signalCode !== null)
+                return;
+            const totalSeconds = Math.max(1, Math.round(timeoutMs / 1000));
+            const timeoutMessage = `[lifecycle:${label}] child ignored spawn-timeout SIGTERM ${totalSeconds}s+30s ago; escalating to SIGKILL`;
+            process.stdout.write(`  ${timeoutMessage}\n`);
+            emitInstallTaskLog(task, timeoutMessage);
+            if (!forcedError) {
+                forcedError = new Error(`lifecycle '${label}' step exceeded ${totalSeconds}s total budget: ${display}`);
+            }
+            try {
+                child.kill("SIGKILL");
+            }
+            catch {
+                /* already exited */
+            }
+        }, timeoutMs + 30_000);
+        totalTimeoutTimer.unref?.();
+        const resetIdleTimer = () => {
+            if (!runOptions?.idleTimeoutMs)
+                return;
+            if (idleTimer)
+                clearTimeout(idleTimer);
+            idleTimer = setTimeout(() => {
+                const idleSeconds = Math.max(1, Math.round(runOptions.idleTimeoutMs / 1000));
+                const stallMessageSuffix = runOptions.stallMessageHint ? ` ${runOptions.stallMessageHint}` : "";
+                const stallMessage = `[lifecycle:${label}] no output for ${idleSeconds}s; terminating stalled step: ${taskDisplay}${stallMessageSuffix}`;
+                process.stdout.write(`  ${stallMessage}\n`);
+                emitInstallTaskLog(task, stallMessage);
+                forcedError = new Error(`lifecycle '${label}' step stalled after ${idleSeconds}s with no output: ${display}${stallMessageSuffix}`);
+                forceTerminateChild(child, label);
+            }, runOptions.idleTimeoutMs);
+            idleTimer.unref?.();
+        };
+        resetIdleTimer();
+        if (captureOutput) {
+            const startedAt = Date.now();
+            const flushPendingLine = (line) => {
+                if (!task)
+                    return;
+                emitInstallTaskLog(task, line);
+            };
+            const handleChunk = (chunk, stream) => {
+                resetIdleTimer();
+                const text = typeof chunk === "string" ? chunk : chunk.toString("utf-8");
+                if (stream === "stderr") {
+                    capturedStderr += text;
+                }
+                if (!task) {
+                    if (stream === "stdout")
+                        process.stdout.write(text);
+                    else
+                        process.stderr.write(text);
+                    return;
+                }
+                const normalized = `${stream === "stdout" ? stdoutPending : stderrPending}${text}`
+                    .replace(/\r\n/g, "\n")
+                    .replace(/\r/g, "\n");
+                const lines = normalized.split("\n");
+                const pending = lines.pop() ?? "";
+                if (stream === "stdout")
+                    stdoutPending = pending;
+                else
+                    stderrPending = pending;
+                for (const line of lines) {
+                    flushPendingLine(line);
+                }
+            };
+            child.stdout?.on("data", (data) => handleChunk(data, "stdout"));
+            child.stderr?.on("data", (data) => handleChunk(data, "stderr"));
+            if (task) {
+                heartbeatTimer = setInterval(() => {
+                    const elapsedSeconds = Math.max(1, Math.round((Date.now() - startedAt) / 1000));
+                    emitInstallTaskLog(task, `[lifecycle:${label}] still running (${elapsedSeconds}s): ${taskDisplay}`);
+                }, 10_000);
+                child.on("close", () => {
+                    flushPendingLine(stdoutPending);
+                    flushPendingLine(stderrPending);
+                });
+            }
+        }
+        child.on("close", (code) => {
+            cleanupPreparedEnv();
+            if (forcedError)
+                reject(forcedError);
+            else if (code === 0)
+                resolve();
+            else if (sudo)
+                reject(createLifecycleSudoError(capturedStderr, display, Boolean(execOptions?.sudoPassword)));
+            else
+                reject(new Error(`lifecycle '${label}' step failed (exit ${code ?? 1}): ${display}`));
+        });
+        child.on("error", (err) => {
+            cleanupPreparedEnv();
+            if (forcedError) {
+                reject(forcedError);
+                return;
+            }
+            if (sudo && err.code === "ENOENT") {
+                reject(new Error("当前环境未检测到 sudo，无法执行需要 sudo 的生命周期步骤。请以 root 身份重试。"));
+                return;
+            }
+            reject(new Error(`lifecycle '${label}' step error: ${err.message}`));
+        });
+    });
+}
+function lifecycleRunStepDisplay(label, index) {
+    if (label === "pre_install") {
+        return `run step ${index + 1}`;
+    }
+    return "$";
+}
+async function commandExists(command) {
+    return new Promise((resolve) => {
+        const quoted = command.replace(/'/g, "'\\''");
+        const child = spawn("sh", ["-c", `command -v '${quoted}' > /dev/null 2>&1`], {
+            stdio: "ignore",
+            env: buildLifecycleEnv(),
+        });
+        child.on("close", (code) => resolve(code === 0));
+        child.on("error", () => resolve(false));
+    });
+}
+// Recursively chown a path. Owner format is "uid:gid" (numeric only, e.g.
+// "0:0" or "1000:1000"). Used by container apps whose images run as a
+// different uid than the service user — without this, bind-mounted data
+// dirs end up unwritable for the in-container process and fail with
+// SQLite "readonly database" or chroma init errors.
+function parseOwnerSpec(owner) {
+    const m = /^(\d+):(\d+)$/.exec(owner);
+    if (!m)
+        throw new Error(`chown owner must be "uid:gid" (numeric), got "${owner}"`);
+    return { uid: Number(m[1]), gid: Number(m[2]) };
+}
+function chownRecursive(path, uid, gid) {
+    chownSync(path, uid, gid);
+    let stat;
+    try {
+        stat = lstatSync(path);
+    }
+    catch {
+        return;
+    }
+    if (!stat.isDirectory())
+        return;
+    for (const entry of readdirSync(path)) {
+        chownRecursive(join(path, entry), uid, gid);
+    }
+}
+/**
+ * Try chowning via direct fs syscall first; on EPERM (core runs as a
+ * non-root user with no CAP_CHOWN) fall back to `sudo -n chown`. The
+ * fallback only succeeds where passwordless sudo is configured for the
+ * service user (the canonical Pi setup); on other hosts the original
+ * EPERM bubbles up as a clear error.
+ */
+function chownWithSudoFallback(path, uid, gid, recursive) {
+    try {
+        if (recursive)
+            chownRecursive(path, uid, gid);
+        else
+            chownSync(path, uid, gid);
+        return;
+    }
+    catch (e) {
+        if (e?.code !== "EPERM" && e?.code !== "EACCES")
+            throw e;
+    }
+    const args = [
+        "-n",
+        "chown",
+        ...(recursive ? ["-R"] : []),
+        `${uid}:${gid}`,
+        path,
+    ];
+    const r = spawnSync("sudo", args, { stdio: ["ignore", "ignore", "pipe"] });
+    if (r.status !== 0) {
+        const stderr = r.stderr ? r.stderr.toString().trim() : "";
+        throw new Error(`chown ${recursive ? "-R " : ""}${uid}:${gid} ${path} failed: service user lacks CAP_CHOWN and passwordless sudo also failed${stderr ? `: ${stderr}` : ""}`);
+    }
+}
+async function downloadBinaryStep(label, url, dest, chmod, task) {
+    const expanded = expandPath(dest);
+    process.stdout.write(`  [lifecycle:${label}] downloadBinary: ${url} → ${expanded}\n`);
+    emitInstallTaskLog(task, `[lifecycle:${label}] downloadBinary: ${url} -> ${expanded}`);
+    mkdirSync(dirname(expanded), { recursive: true });
+    const tmp = expanded + ".tmp";
+    const res = await fetch(url);
+    if (!res.ok)
+        throw new Error(`downloadBinary: HTTP ${res.status} ${url}`);
+    const buf = await res.arrayBuffer();
+    writeFileSync(tmp, Buffer.from(buf), { mode: 0o644 });
+    renameSync(tmp, expanded);
+    if (chmod)
+        chmodSync(expanded, parseInt(chmod, 8));
+}
+export async function runLifecycleSteps(steps, label, artifacts, task, execOptions, ownedArtifacts, instanceId) {
+    if (!steps || steps.length === 0)
+        return;
+    for (const [index, rawStep] of steps.entries()) {
+        const step = materializeLifecycleInstanceTokens(rawStep, instanceId);
+        if ("run" in step) {
+            if (step.ifFileExists && !existsSync(expandPath(step.ifFileExists))) {
+                continue;
+            }
+            const timeoutMs = step.timeout_ms ?? 300_000;
+            const display = label === "pre_install"
+                ? lifecycleRunStepDisplay(label, index)
+                : `${lifecycleRunStepDisplay(label, index)} ${step.run}`;
+            const taskDisplay = `run step ${index + 1}`;
+            try {
+                await spawnStepWithTimeout(label, display, taskDisplay, "sh", ["-c", step.run], timeoutMs, task, execOptions, step.sudo === true);
+            }
+            catch (error) {
+                if (step.successIfCommandExists && await commandExists(step.successIfCommandExists)) {
+                    process.stdout.write(`  [lifecycle:${label}] command '${step.successIfCommandExists}' detected after failure/timeout; treating step as successful\n`);
+                    emitInstallTaskLog(task, `[lifecycle:${label}] command '${step.successIfCommandExists}' detected after failure/timeout; treating step as successful`);
+                    continue;
+                }
+                throw error;
+            }
+        }
+        else if ("checkNotCommand" in step) {
+            const cmd = step.checkNotCommand;
+            const found = await commandExists(cmd);
+            if (found) {
+                throw new Error(step.message ??
+                    `系统中已检测到 '${cmd}'，建议直接使用系统版本，无需重复安装。如需由 Nomad 统一管理，请先卸载系统版本`);
+            }
+        }
+        else if ("downloadImage" in step) {
+            const pulled = await pullDockerImageStep(label, step.downloadImage, `downloadImage: ${step.downloadImage}`, task, step.timeout_ms, step.idle_timeout_ms);
+            artifacts?.push({ type: "image", path: step.downloadImage });
+            if (pulled)
+                ownedArtifacts?.push({ type: "image", path: step.downloadImage });
+        }
+        else if ("deleteImage" in step) {
+            await spawnStep(label, `deleteImage: ${step.deleteImage}`, "sh", [
+                "-c",
+                `docker rmi -f ${step.deleteImage} 2>/dev/null || true`,
+            ], task);
+        }
+        else if ("downloadBinary" in step) {
+            const { url, dest, chmod } = step.downloadBinary;
+            await downloadBinaryStep(label, url, dest, chmod, task);
+            artifacts?.push({ type: "binary", path: expandPath(dest) });
+        }
+        else if ("deleteBinary" in step) {
+            const p = expandPath(step.deleteBinary);
+            process.stdout.write(`  [lifecycle:${label}] deleteBinary: ${p}\n`);
+            emitInstallTaskLog(task, `[lifecycle:${label}] deleteBinary: ${p}`);
+            try {
+                unlinkSync(p);
+            }
+            catch (e) {
+                if (e.code !== "ENOENT")
+                    throw e;
+            }
+        }
+        else if ("mkdir" in step) {
+            const p = expandPath(step.mkdir);
+            process.stdout.write(`  [lifecycle:${label}] mkdir: ${p}\n`);
+            emitInstallTaskLog(task, `[lifecycle:${label}] mkdir: ${p}`);
+            // Ownership semantics for rollback (Step 3):
+            //   - If `p` did not exist before this step, this install attempt
+            //     created it → claim ownership (push into `ownedArtifacts`) so a
+            //     subsequent rollback may safely `rm -rf` it.
+            //   - If `p` already existed, treat it as a dependency only (push into
+            //     `artifacts`). User-pre-existing directories (e.g. a shared
+            //     `~/.config/<app>` the user already populated) must never be
+            //     deleted by our rollback path.
+            // `mkdir -p` is idempotent for the already-exists case, so the
+            // observable filesystem result is identical either way; only the
+            // rollback bookkeeping differs.
+            const preExisting = existsSync(p);
+            mkdirSync(p, { recursive: true });
+            artifacts?.push({ type: "dir", path: p });
+            if (!preExisting)
+                ownedArtifacts?.push({ type: "dir", path: p });
+        }
+        else if ("chown" in step) {
+            const p = expandPath(step.chown.path);
+            const { uid, gid } = parseOwnerSpec(step.chown.owner);
+            const recursive = step.chown.recursive !== false;
+            const tag = recursive ? "chown -R" : "chown";
+            process.stdout.write(`  [lifecycle:${label}] ${tag} ${uid}:${gid} ${p}\n`);
+            emitInstallTaskLog(task, `[lifecycle:${label}] ${tag} ${uid}:${gid} ${p}`);
+            if (!existsSync(p)) {
+                // chown only makes sense if the target exists; surface a clear
+                // error rather than letting fs throw an opaque ENOENT later.
+                throw new Error(`chown target does not exist: ${p}`);
+            }
+            try {
+                chownWithSudoFallback(p, uid, gid, recursive);
+            }
+            catch (chownErr) {
+                // In pre_start, chown failures are non-fatal: on macOS Docker/Colima
+                // the VM handles UID mapping for bind-mounts, so the container can
+                // write even without matching ownership. Failing fatally here blocks
+                // any non-root service user from starting the app.
+                if (label === "pre_start") {
+                    const msg = `[lifecycle:${label}] ${tag} ${uid}:${gid} ${p} failed (non-fatal): ${chownErr.message}`;
+                    process.stdout.write(`  ${msg}\n`);
+                    emitInstallTaskLog(task, msg);
+                }
+                else {
+                    throw chownErr;
+                }
+            }
+        }
+        else if ("deleteDir" in step) {
+            const p = expandPath(step.deleteDir);
+            process.stdout.write(`  [lifecycle:${label}] deleteDir: ${p}\n`);
+            emitInstallTaskLog(task, `[lifecycle:${label}] deleteDir: ${p}`);
+            rmSync(p, { recursive: true, force: true });
+        }
+    }
+}
+export function cleanupArtifacts(artifacts, task) {
+    for (let i = artifacts.length - 1; i >= 0; i--) {
+        const a = artifacts[i];
+        try {
+            switch (a.type) {
+                case "image":
+                    process.stdout.write(`  [cleanup] removing image: ${a.path}\n`);
+                    emitInstallTaskLog(task, `[cleanup] removing image: ${a.path}`);
+                    spawn("docker", ["rmi", "-f", a.path], { stdio: "ignore" }).unref();
+                    break;
+                case "binary":
+                    process.stdout.write(`  [cleanup] removing binary: ${a.path}\n`);
+                    emitInstallTaskLog(task, `[cleanup] removing binary: ${a.path}`);
+                    unlinkSync(a.path);
+                    break;
+                case "dir":
+                    process.stdout.write(`  [cleanup] removing dir: ${a.path}\n`);
+                    emitInstallTaskLog(task, `[cleanup] removing dir: ${a.path}`);
+                    rmSync(a.path, { recursive: true, force: true });
+                    break;
+            }
+        }
+        catch {
+            // best-effort
+        }
+    }
+}
+export async function runPostStartSteps(spec, instanceId) {
+    await runLifecycleSteps(spec.lifecycle?.post_start, "post_start", undefined, undefined, undefined, undefined, instanceId);
+}
+export async function runPreStartSteps(spec, instanceId) {
+    await runLifecycleSteps(spec.lifecycle?.pre_start, "pre_start", undefined, undefined, undefined, undefined, instanceId);
+}
+export async function waitForAppRuntimeRunning(instanceId, timeoutMs = 30_000, pollIntervalMs = 1_000) {
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+        const status = await getInstanceInstallRecordRuntimeStatus(instanceId);
+        if (status.status === "running")
+            return true;
+        if (status.status === "dead" || status.status === "failed")
+            return false;
+        await new Promise((resolve) => setTimeout(resolve, pollIntervalMs));
+    }
+    return false;
+}
+//# sourceMappingURL=lifecycle-scripts.js.map