jishushell 0.6.5 → 0.6.18

package/dist/services/instances/manager.js

@@ -0,0 +1,1348 @@
+import { execFileSync } from "child_process";
+import { chownSync, closeSync, existsSync, openSync, readFileSync, readdirSync, renameSync, statSync, } from "fs";
+import { rm as rmAsync } from "fs/promises";
+import { createServer as netCreateServer } from "net";
+import { networkInterfaces, userInfo } from "os";
+import { dirname, join, resolve } from "path";
+import * as config from "../../config.js";
+import { safeReadJson, safeWriteJson } from "../../utils/safe-json.js";
+import { ensureDirContainer, writeSecretFile } from "../../utils/fs.js";
+// integrations/index.ts gets imported only for framework-level integration lookups
+// (preferredHostPort allocator seed). Integrations statically import BACK into this
+// file for primitives; that static cycle is safe because no top-level code
+// in integrations references instance-manager exports.
+import { getIntegration } from "../integrations/index.js";
+import { isExecutionOwnerRequiredError, resolveExecutionOwnerFromMetadata, } from "../app-common/execution-owner.js";
+import { buildCanonicalAppInstance, readCanonicalInstance, readSpecSnapshotFromDir, } from "../app-common/instance-store.js";
+import { DEFINITION_FILENAME, INSTANCE_METADATA_FILENAME, MANIFEST_FILENAME, RESOLVED_SPEC_FILENAME, resolveAppDir, } from "../app-common/paths.js";
+function getConfigValue(name) {
+    return name in config ? config[name] : undefined;
+}
+function resolveConfigPath(value, fallback) {
+    return typeof value === "string" && value.trim() ? value : fallback;
+}
+const JISHUSHELL_HOME = resolveConfigPath(getConfigValue("JISHUSHELL_HOME"), resolve(process.env.HOME ?? userInfo().homedir, ".jishushell"));
+const APPS_DIR = resolveConfigPath(getConfigValue("APPS_DIR"), join(JISHUSHELL_HOME, "apps"));
+const BACKUPS_DIR = resolveConfigPath(getConfigValue("BACKUPS_DIR"), join(JISHUSHELL_HOME, "backups"));
+const getCoreConfigValue = getConfigValue("getCoreConfig");
+const _getCoreConfig = typeof getCoreConfigValue === "function"
+    ? getCoreConfigValue
+    : () => ({});
+const _configChangeListeners = [];
+export function onConfigChange(listener) {
+    _configChangeListeners.push(listener);
+    return () => {
+        const idx = _configChangeListeners.indexOf(listener);
+        if (idx >= 0)
+            _configChangeListeners.splice(idx, 1);
+    };
+}
+/**
+ * Fire the config-change listener fan-out. Integrations call this after
+ * `saveNativeConfig()` so LLM proxy / config editors pick up the change.
+ */
+export function notifyConfigChange(instanceId) {
+    for (const listener of _configChangeListeners) {
+        try {
+            listener(instanceId);
+        }
+        catch { /* ignore listener errors */ }
+    }
+}
+const ENV_KEY_RE = /^[A-Za-z_][A-Za-z0-9_]*$/;
+// ── Path helpers (framework-level) ──
+function hasIncompleteAppInstallShadow(dir) {
+    const markers = [
+        MANIFEST_FILENAME,
+        DEFINITION_FILENAME,
+        RESOLVED_SPEC_FILENAME,
+        INSTANCE_METADATA_FILENAME,
+    ].map((fileName) => existsSync(join(dir, fileName)));
+    return markers.some(Boolean) && !markers.every(Boolean);
+}
+function resolveInstanceRoot(instanceId) {
+    // Step 13: canonical `apps/<id>` only on the runtime path. Un-migrated
+    // `instances/<id>` directories must be handled by `jishushell migrate legacy`.
+    return resolveAppDir(instanceId);
+}
+export function instanceDir(instanceId) {
+    return resolveInstanceRoot(instanceId);
+}
+export function instanceMetaPath(instanceId) {
+    return join(instanceDir(instanceId), INSTANCE_METADATA_FILENAME);
+}
+// Default model env file path. Integration-specific resolvers live on the app
+// integration; this helper provides the framework-level fallback.
+export function defaultModelEnvFile(instanceId) {
+    return join(instanceDir(instanceId), "model.env");
+}
+export function normalizePath(p) {
+    return resolve(p.replace(/^~/, userInfo().homedir));
+}
+// ── Host port allocator ──
+//
+// Domain semantics (canonical port model, per Step 2 of the App Lifecycle
+// Runtime decision):
+//   - `hostPort` is the host-side port Core exposes for an instance. Core's
+//     allocator is the ONLY decider. Nomad/Docker may not reverse-decide it.
+//   - `containerPort` is the in-container listener owned by the workload and
+//     must remain stable across host-port reallocations.
+//   - The persisted source of truth is `runtime.ports[].hostPort` on each
+//     instance's `instance.json`.
+//
+// In-memory reservation table.
+//
+// `_pendingPorts` exists to close the race window between
+//   1. the allocator decided a host port is free, and
+//   2. that decision is durably persisted into `instance.json`.
+//
+// The canonical allocator lifecycle is:
+//   - `reserve` (internal): set by `allocateHostPort` before the async
+//     `isPortInUse` probe, so a concurrent caller cannot select the same port
+//     during the await gap.
+//   - `commit`: invoked by the caller AFTER `runtime.ports[].hostPort` is
+//     durably written. The reservation slot is freed because durable
+//     ownership has taken over.
+//   - `release`: invoked by the caller on any failure path before the
+//     durable write succeeds. The reservation slot is freed so concurrent /
+//     retried allocations can reuse the port.
+//
+// The shape is exposed via the `HostPortAllocation` object returned by
+// `allocateHostPort`. Callers must use that object's `commit()` /
+// `release()` and must NOT lean on the legacy "finally { releasePendingPort
+// } " pattern; that pattern conflates success and failure paths and was
+// explicitly called out as forbidden in Step 2.
+//
+// No cross-process reconcile is required for this table: it is a transient
+// in-memory Map; on Core restart it starts empty. Any port whose durable
+// `runtime.ports[].hostPort` got written before the crash is already owned
+// by the surviving `instance.json`; any port that was only reserved (no
+// durable write yet) is simply lost on restart, which is the correct
+// behaviour — the instance never existed.
+const _pendingPorts = new Map();
+export const INSTANCE_NEEDS_MIGRATION_CODE = "INSTANCE_NEEDS_MIGRATION";
+export class CanonicalRuntimePortRequiredError extends Error {
+    code = INSTANCE_NEEDS_MIGRATION_CODE;
+    statusCode = 409;
+    instanceId;
+    constructor(instanceId) {
+        super(`Instance '${instanceId}' has no canonical runtime.ports[] host-port allocation. ` +
+            "Legacy host-port fields are no longer read on lifecycle/status/proxy paths. " +
+            "Run `jishushell system repair-instances` or `jishushell migrate legacy --yes` before retrying.");
+        this.name = "CanonicalRuntimePortRequiredError";
+        this.instanceId = instanceId;
+    }
+}
+export function isCanonicalRuntimePortRequiredError(error) {
+    return error instanceof CanonicalRuntimePortRequiredError
+        || (!!error
+            && typeof error === "object"
+            && error.code === INSTANCE_NEEDS_MIGRATION_CODE);
+}
+function reservePendingPort(instanceId, port) {
+    _pendingPorts.set(port, instanceId);
+}
+function clearPendingPort(port, instanceId) {
+    const owner = _pendingPorts.get(port);
+    if (owner == null)
+        return;
+    if (instanceId && owner !== instanceId)
+        return;
+    _pendingPorts.delete(port);
+}
+/**
+ * Read the primary externally reachable host port out of a persisted runtime record.
+ *
+ * Runtime hot paths only trust canonical `runtime.ports[].hostPort`.
+ * Legacy env/args fallbacks are repair-only readers owned by the migrator or
+ * integration repair code and must not be consulted here.
+ */
+export function extractPrimaryHostPort(runtime, _integrationKind) {
+    if (!runtime)
+        return null;
+    // Primary: RuntimeSpec.ports[] declaration. Prefer the first externally
+    // visible port; fall back to any hostPort only for malformed/legacy records.
+    const ports = Array.isArray(runtime.ports) ? runtime.ports : [];
+    for (const port of ports) {
+        if ((port?.visibility ?? "external") !== "internal" && Number.isInteger(port.hostPort) && port.hostPort > 0) {
+            return port.hostPort;
+        }
+    }
+    for (const port of ports) {
+        if (Number.isInteger(port?.hostPort) && port.hostPort > 0) {
+            return port.hostPort;
+        }
+    }
+    return null;
+}
+function requireCanonicalPrimaryHostPort(instanceId, runtime) {
+    const port = extractPrimaryHostPort(runtime);
+    if (port)
+        return port;
+    throw new CanonicalRuntimePortRequiredError(instanceId);
+}
+function usedHostPorts(excludeId, excludeHostPort, options = {}) {
+    const ports = new Set();
+    for (const inst of listInstances()) {
+        const hasIntegration = Array.isArray(inst.integrations)
+            && inst.integrations.length > 0;
+        const runtimePorts = Array.isArray(inst.runtime?.ports) ? inst.runtime.ports : [];
+        const canonicalHostPorts = runtimePorts
+            .map((port) => port?.hostPort)
+            .filter((port) => Number.isInteger(port) && Number(port) > 0);
+        if (options.ignoreIncompleteCanonicalInstanceIds?.has(inst.id)
+            && hasIntegration
+            && canonicalHostPorts.length === 0) {
+            continue;
+        }
+        if (canonicalHostPorts.length === 0 && hasIntegration) {
+            throw new CanonicalRuntimePortRequiredError(inst.id);
+        }
+        for (const port of canonicalHostPorts) {
+            if (inst.id === excludeId && (excludeHostPort == null || port === excludeHostPort))
+                continue;
+            ports.add(port);
+        }
+    }
+    return ports;
+}
+function safePort(port) {
+    if (!Number.isInteger(port) || port < 1 || port > 65535)
+        throw new Error(`Invalid port: ${port}`);
+    return String(port);
+}
+/**
+ * Probes whether a port is currently held by any process on the host.
+ *
+ * Binds four addresses concurrently — `0.0.0.0`, `127.0.0.1`, `::` (v6-only),
+ * and `::1` — and treats the port as busy if any probe returns EADDRINUSE.
+ * The single-`0.0.0.0` probe used by the earlier revision was sufficient on
+ * Linux (where binding `0.0.0.0` conflicts with any pre-existing loopback
+ * listener on the same port) but silently passed on macOS, where BSD socket
+ * semantics let a wildcard v4 bind coexist with a `127.0.0.1` listener. A
+ * loopback-only service would then be invisible to JishuShell, so port
+ * allocation could assign the same host port to a new instance and the
+ * workload would silently fail to bind at start time. Probing the loopback
+ * addresses directly closes that gap.
+ */
+export function isPortInUse(port) {
+    if (!Number.isInteger(port) || port < 1 || port > 65535)
+        return Promise.resolve(false);
+    const probeAt = (host, opts = {}) => new Promise((resolve) => {
+        const server = netCreateServer();
+        server.once("error", (err) => {
+            if (err?.code === "EADDRINUSE")
+                return resolve(true);
+            // EACCES / EADDRNOTAVAIL / ENOTSUP / EINVAL mean we could not even
+            // attempt the bind (restricted port, address family unsupported on
+            // this host, etc). Report "not busy" from this probe so one bad
+            // locus doesn't falsely block the whole port — the other probes
+            // still cover their respective loci.
+            if (err?.code && err.code !== "EACCES" && err.code !== "EADDRNOTAVAIL"
+                && err.code !== "ENOTSUP" && err.code !== "EINVAL" && err.code !== "EAFNOSUPPORT") {
+                console.warn(`[port-probe] bind ${host}:${port} failed with ${err.code}: ${err.message}; treating locus as free`);
+            }
+            resolve(false);
+        });
+        server.once("listening", () => {
+            server.close(() => resolve(false));
+        });
+        server.listen({ port, host, ...opts });
+    });
+    // Run probes sequentially, not in parallel: two probes on the same port
+    // collide with each other (the first bind on 0.0.0.0 makes the second
+    // bind on 127.0.0.1 hit EADDRINUSE), which would make every port look
+    // busy. Short-circuit on the first busy locus to keep the common case
+    // (port free) close to single-probe latency.
+    return (async () => {
+        const loci = [
+            ["0.0.0.0", {}],
+            ["127.0.0.1", {}],
+            ["::", { ipv6Only: true }],
+            ["::1", {}],
+        ];
+        for (const [host, opts] of loci) {
+            if (await probeAt(host, opts))
+                return true;
+        }
+        return false;
+    })();
+}
+/**
+ * Kind-agnostic host-port allocator (canonical port model).
+ *
+ * Walks upward from `defaultPort` until a free host port is found that is
+ * neither held by any canonical runtime port on an existing instance, nor by
+ * a pending reservation, nor by any listener on the host. The historical
+ * Callers may use it for every external runtime port.
+ *
+ * Concurrent callers coordinate through `_pendingPorts`: each candidate port
+ * is reserved BEFORE the async `isPortInUse` probe so concurrent calls cannot
+ * select the same port during the await gap. The returned allocation owns
+ * the lifecycle from there: the caller
+ * MUST call `commit()` once the chosen port is durably persisted, or
+ * `release()` on any failure path. Calling neither leaks the reservation
+ * slot until process restart.
+ */
+export async function allocateHostPort(instanceId, defaultPort, replacingHostPort, options = {}) {
+    const used = usedHostPorts(instanceId, replacingHostPort, options);
+    const skipped = [];
+    let port = defaultPort;
+    while (true) {
+        if (port > 65535) {
+            throw new Error(`No available host port found (all ports ${defaultPort}-65535 in use)`);
+        }
+        if (used.has(port) || _pendingPorts.has(port)) {
+            skipped.push(port);
+            port++;
+            continue;
+        }
+        // Reserve BEFORE the async isPortInUse check to prevent concurrent callers
+        // from selecting the same port during the await gap.
+        reservePendingPort(instanceId, port);
+        const reservation = {
+            instanceId,
+            port,
+            skipped,
+            commit: () => {
+                clearPendingPort(port, instanceId);
+                return port;
+            },
+            release: () => {
+                clearPendingPort(port, instanceId);
+            },
+        };
+        try {
+            if (await isPortInUse(port)) {
+                reservation.release();
+                skipped.push(port);
+                port++;
+                continue;
+            }
+            return reservation;
+        }
+        catch {
+            reservation.release();
+            // Skip this port on a transient OS error rather than failing the entire
+            // allocation — a single bad port check should not prevent instance creation.
+            console.warn(`[instance] Port ${port} availability check failed, trying next port`);
+            skipped.push(port);
+            port++;
+            continue;
+        }
+    }
+}
+/**
+ * Legacy by-port release helper.
+ *
+ * Production code MUST use the `commit()` / `release()` methods on the
+ * {@link HostPortAllocation} returned from {@link allocateHostPort};
+ * those make the success-vs-failure split explicit, which is the Step 2
+ * canonical contract. This function is kept only as a test/facade compatibility
+ * export for older call sites that still talk to the allocator by port number.
+ * Normal production code should not need it.
+ */
+export function releasePendingPort(port) {
+    clearPendingPort(port);
+}
+// ── Runtime / config builders ──
+/**
+ * When jishushell runs as root (e.g. systemd service), returns the actual
+ * non-root user that should own instance files and run workload processes.
+ * Returns null when not running as root or when no suitable non-root user is found.
+ */
+export function resolveServiceUser() {
+    if (typeof process.getuid !== "function" || process.getuid() !== 0)
+        return null;
+    // SUDO_USER is set when launched via `sudo`
+    const sudoUser = process.env.SUDO_USER;
+    if (sudoUser && sudoUser !== "root") {
+        try {
+            const uid = parseInt(execFileSync("id", ["-u", sudoUser], { encoding: "utf-8" }).trim(), 10);
+            const gid = parseInt(execFileSync("id", ["-g", sudoUser], { encoding: "utf-8" }).trim(), 10);
+            if (!isNaN(uid) && !isNaN(gid))
+                return { username: sudoUser, uid, gid };
+        }
+        catch { /* fall through */ }
+    }
+    // Fall back to owner of APPS_DIR or JISHUSHELL_HOME
+    try {
+        const target = existsSync(APPS_DIR) ? APPS_DIR : JISHUSHELL_HOME;
+        const uid = statSync(target).uid;
+        if (uid !== 0) {
+            const username = execFileSync("id", ["-un", String(uid)], { encoding: "utf-8" }).trim();
+            const gid = parseInt(execFileSync("id", ["-g", username], { encoding: "utf-8" }).trim(), 10);
+            if (!isNaN(gid))
+                return { username, uid, gid };
+        }
+    }
+    catch { /* fall through */ }
+    return null;
+}
+/**
+ * When running as root, chown a file (and its .bak) to the service user so the
+ * workload process (running as that user) can read/write its own data files.
+ * No-op when not running as root.
+ */
+export function chownToServiceUser(...paths) {
+    const svc = resolveServiceUser();
+    if (!svc)
+        return;
+    for (const p of paths) {
+        for (const f of [p, p + ".bak", p + ".bak.1", p + ".bak.2"]) {
+            try {
+                if (existsSync(f))
+                    chownSync(f, svc.uid, svc.gid);
+            }
+            catch { /* best effort */ }
+        }
+    }
+}
+// ── Env file helpers ──
+export function parseEnvFile(path) {
+    const env = {};
+    if (!existsSync(path))
+        return env;
+    for (let line of readFileSync(path, "utf-8").split("\n")) {
+        line = line.trim();
+        if (!line || line.startsWith("#"))
+            continue;
+        if (line.startsWith("export "))
+            line = line.slice(7).trimStart();
+        if (!line.includes("="))
+            continue;
+        const eqIdx = line.indexOf("=");
+        const key = line.slice(0, eqIdx).trim();
+        let value = line.slice(eqIdx + 1).trim();
+        if (!ENV_KEY_RE.test(key))
+            continue;
+        if (value.length >= 2 && value[0] === value[value.length - 1] && (value[0] === "'" || value[0] === '"')) {
+            value = value.slice(1, -1);
+        }
+        env[key] = value;
+    }
+    return env;
+}
+function quoteEnvValue(value) {
+    if (/^[A-Za-z0-9_./:@%+=,-]+$/.test(value))
+        return value;
+    return JSON.stringify(value);
+}
+export function updateEnvFile(path, updates) {
+    ensureDirContainer(dirname(path));
+    const existing = existsSync(path) ? readFileSync(path, "utf-8").split("\n") : [];
+    const remaining = { ...updates };
+    const newLines = [];
+    for (const rawLine of existing) {
+        const stripped = rawLine.trim();
+        const candidate = stripped.startsWith("export ") ? stripped.slice(7).trimStart() : stripped;
+        if (!candidate || candidate.startsWith("#") || !candidate.includes("=")) {
+            newLines.push(rawLine);
+            continue;
+        }
+        const key = candidate.slice(0, candidate.indexOf("=")).trim();
+        if (!ENV_KEY_RE.test(key) || !(key in remaining)) {
+            newLines.push(rawLine);
+            continue;
+        }
+        const value = remaining[key];
+        delete remaining[key];
+        if (value === "")
+            continue;
+        const prefix = stripped.startsWith("export ") ? "export " : "";
+        newLines.push(`${prefix}${key}=${quoteEnvValue(value)}`);
+    }
+    for (const [key, value] of Object.entries(remaining)) {
+        if (!ENV_KEY_RE.test(key) || value === "")
+            continue;
+        newLines.push(`${key}=${quoteEnvValue(value)}`);
+    }
+    const output = newLines.join("\n").trimEnd();
+    const content = output ? output + "\n" : "";
+    // Atomic write: tmp then rename to protect against RPi power loss
+    const tmp = path + ".tmp";
+    writeSecretFile(tmp, content);
+    renameSync(tmp, path);
+    chownToServiceUser(path);
+}
+// ── Provider key helpers ──
+export function inferProviderApiKeyEnvName(providerId) {
+    let normalized = providerId.replace(/[^A-Za-z0-9]+/g, "_").replace(/^_|_$/g, "").toUpperCase();
+    if (!normalized)
+        normalized = "JISHUSHELL_PROVIDER";
+    return `${normalized}_API_KEY`;
+}
+// ── Public API ──
+/**
+ * Probe whether a file is readable by the current process. Used to
+ * distinguish "primary missing / corrupted" (recoverable via safeReadJson's
+ * .bak chain) from "primary exists but permission denied" (EACCES — the
+ * common sudo-script footgun that leaves root-owned files). safeReadJson
+ * swallows every read error internally and returns null, so without this
+ * probe an unreadable primary looks identical to a truly-gone instance.
+ */
+function probeReadable(path) {
+    if (!existsSync(path))
+        return null;
+    try {
+        const fd = openSync(path, "r");
+        closeSync(fd);
+        return null;
+    }
+    catch (e) {
+        return e;
+    }
+}
+export function listInstances() {
+    const deduped = new Map();
+    // Step 13: canonical `apps/<id>` only. Un-migrated `instances/<id>`
+    // directories are surfaced exclusively by `jishushell migrate legacy`.
+    const rootDir = APPS_DIR;
+    if (existsSync(rootDir)) {
+        const entries = readdirSync(rootDir).sort();
+        for (const name of entries) {
+            if (deduped.has(name))
+                continue;
+            const metaPath = join(rootDir, name, "instance.json");
+            const dirPath = join(rootDir, name);
+            try {
+                if (!statSync(dirPath).isDirectory())
+                    continue;
+                if (hasIncompleteAppInstallShadow(dirPath))
+                    continue;
+                if (!existsSync(metaPath))
+                    continue;
+                // Use safeReadJson so primary instance.json that was corrupted or
+                // deleted mid-rename falls back to the .bak chain maintained by
+                // safeWriteJson. Without this, an interrupted safeWriteJson call
+                // would silently drop the instance from every list/get hot path
+                // even though the backup chain still holds valid content on disk.
+                const meta = readCanonicalInstance(name);
+                if (meta) {
+                    deduped.set(name, meta);
+                    continue;
+                }
+                // safeReadJson → null can mean any of (a) primary missing + no
+                // backups, (b) all candidates unparseable, (c) permission denied.
+                // (a) and (b) are legitimate "drop from list" cases; (c) is the
+                // sudo-script footgun and must be logged loudly so the operator
+                // doesn't just see an empty instance list with no hint why.
+                const readErr = probeReadable(metaPath);
+                if (readErr && readErr.code === "EACCES") {
+                    console.error(`[instance-manager] cannot read instance '${name}': ${readErr.message}. ` +
+                        `Check file ownership with: ls -la ${metaPath}`);
+                }
+            }
+            catch (e) {
+                // Fallback for failures before the safeReadJson call (e.g. statSync
+                // on a directory we can't enter). Still log instead of silently
+                // dropping the entry.
+                console.error(`[instance-manager] cannot read instance '${name}': ${e.message}`);
+            }
+        }
+    }
+    return [...deduped.values()];
+}
+export function getInstance(instanceId) {
+    const metaPath = instanceMetaPath(instanceId);
+    // Go through safeReadJson so primary missing/corrupted instance.json
+    // is still served from the .bak chain. Returning null on "truly gone"
+    // (no primary, no backups) keeps the existing 404 behavior intact.
+    const meta = readCanonicalInstance(instanceId);
+    if (meta) {
+        return meta;
+    }
+    // safeReadJson swallows every read error internally, which is exactly
+    // wrong for the EACCES case — a root-owned primary would silently
+    // return null and callers would report "Instance not found" instead
+    // of the actionable "check file ownership" message. Re-probe to
+    // distinguish and throw on permission denial. Missing/corrupted with
+    // no backup still returns null (→ 404 upstream).
+    const readErr = probeReadable(metaPath);
+    if (readErr && readErr.code === "EACCES") {
+        throw new Error(`Cannot read instance '${instanceId}' metadata: ${readErr.message}. ` +
+            `Check file ownership with: ls -la ${metaPath}`);
+    }
+    return null;
+}
+export function updateInstance(instanceId, name, description) {
+    const meta = getInstance(instanceId);
+    if (!meta)
+        return null;
+    if (name != null)
+        meta.name = name;
+    if (description != null)
+        meta.description = description;
+    const snapshot = readSpecSnapshotFromDir(instanceDir(instanceId));
+    const next = buildCanonicalAppInstance({
+        raw: meta,
+        id: instanceId,
+        name: meta.name,
+        description: meta.description,
+        spec: snapshot?.spec ?? null,
+    });
+    safeWriteJson(instanceMetaPath(instanceId), next);
+    chownToServiceUser(instanceMetaPath(instanceId));
+    return next;
+}
+export function updateInstanceMeta(instanceId, patch) {
+    const metaPath = instanceMetaPath(instanceId);
+    const meta = getInstance(instanceId);
+    if (!meta)
+        throw new Error(`Cannot update unknown instance '${instanceId}'`);
+    Object.assign(meta, patch);
+    const snapshot = readSpecSnapshotFromDir(instanceDir(instanceId));
+    const next = buildCanonicalAppInstance({
+        raw: meta,
+        id: instanceId,
+        name: typeof meta.name === "string" ? meta.name : undefined,
+        description: typeof meta.description === "string" ? meta.description : undefined,
+        spec: snapshot?.spec ?? null,
+    });
+    safeWriteJson(metaPath, next);
+    chownToServiceUser(metaPath);
+}
+/**
+ * Toggle the opt-in "privileged" (native-install-like) profile on an
+ * OpenClaw instance's docker task. Default (false / absent) keeps the
+ * hardened container (cap_drop=ALL, no-new-privileges, read-only rootfs).
+ * When enabled, `OpenClawAdapter.buildNomadTask` relaxes those so the agent
+ * has native-install-like permissions. Persisted in `instance.json` runtime
+ * so it survives restarts and is reapplied on every Nomad job submit.
+ * Returns false when the instance does not exist. Caller must restart the
+ * instance for the change to take effect.
+ */
+export function setInstancePrivileged(instanceId, privileged) {
+    const metaPath = instanceMetaPath(instanceId);
+    const meta = safeReadJson(metaPath, "instance-meta");
+    if (!meta)
+        return false;
+    const runtime = (meta.runtime ?? {});
+    if (privileged)
+        runtime.privileged = true;
+    else
+        delete runtime.privileged;
+    meta.runtime = runtime;
+    safeWriteJson(metaPath, meta);
+    chownToServiceUser(metaPath);
+    return true;
+}
+export async function deleteInstance(instanceId, purgeBackups = false) {
+    const d = instanceDir(instanceId);
+    if (!existsSync(d))
+        return { ok: false, warnings: ["Instance directory not found"] };
+    const warnings = [];
+    // Cancel auto-backup timer and any queued jobs for this instance
+    import("../backup/backup-manager.js").then(({ cancelAutoBackup, getQueueStatus, cancelJob }) => {
+        cancelAutoBackup(instanceId);
+        // Cancel queued (not yet running) jobs for this instance
+        const q = getQueueStatus();
+        for (const job of q.queued) {
+            if (job.instanceId === instanceId)
+                cancelJob(job.id);
+        }
+    }).catch(() => { });
+    // Cache metadata BEFORE deletion so integrations can inspect it after rm.
+    const meta = getInstance(instanceId);
+    // Integration-owned pre-delete hook. Integrations use this to emit advisories
+    // for resources that live outside the instance dir (custom integration
+    // homes, named docker volumes, etc). Errors are collected
+    // into the response so one integration misbehaving can't block removal.
+    try {
+        const entry = getRuntimeIntegrationEntry(meta);
+        if (entry && meta) {
+            const integration = entry.integration;
+            if (integration.hooks?.onDelete) {
+                const hookResult = await integration.hooks.onDelete({ instanceId, meta });
+                if (hookResult && Array.isArray(hookResult.warnings)) {
+                    warnings.push(...hookResult.warnings);
+                }
+            }
+        }
+    }
+    catch (e) {
+        warnings.push(`integration onDelete hook failed: ${e.message}`);
+    }
+    // Clean up Nomad Variables (async, best-effort)
+    import("../runtime/drivers/nomad.js").then((nm) => {
+        nm.purgeInstanceVariables(instanceId).catch((e) => {
+            console.warn(`[instance] Failed to purge Nomad variables for ${instanceId}:`, e.message);
+        });
+    }).catch((e) => {
+        console.warn(`[instance] Could not load Nomad driver for cleanup:`, e.message);
+    });
+    // Async rm so the Node event loop stays responsive during large deletes:
+    // a fresh instance with a just-installed runtime package can be 1+ GB
+    // with hundreds of nested dirs, which takes 30-60s to unlink on SD storage.
+    // rmSync would block every other HTTP request for that whole window.
+    let dirDeleted = false;
+    try {
+        await rmAsync(d, { recursive: true, force: true });
+        dirDeleted = true;
+    }
+    catch {
+        try {
+            execFileSync("sudo", ["rm", "-rf", d], { timeout: 300000 });
+            dirDeleted = true;
+        }
+        catch (e) {
+            warnings.push(`Failed to delete instance directory: ${e.message}`);
+        }
+    }
+    // Integration-home orphan warnings are emitted by integration hooks.
+    // Handle backups (stored in separate directory, not affected by the
+    // instance rm above). Backups can be hundreds of MB each and accumulate
+    // across retention windows, so use the same async rm path to keep the
+    // event loop responsive.
+    const backupDir = join(BACKUPS_DIR, instanceId);
+    if (purgeBackups && existsSync(backupDir)) {
+        try {
+            await rmAsync(backupDir, { recursive: true, force: true });
+        }
+        catch (e) {
+            warnings.push(`Failed to delete backups: ${e.message}`);
+        }
+    }
+    else if (existsSync(backupDir)) {
+        warnings.push(`Backups preserved at ${backupDir}`);
+    }
+    return { ok: dirDeleted, warnings: warnings.length ? warnings : undefined };
+}
+// ── Native config dispatch wrappers ─────────────────────────────────
+// Integrations own the implementation (`getNativeConfig` / `getStoredNativeConfig`
+// / `saveNativeConfig`); these helpers preserve the synchronous public API
+// shape for existing call sites (llm-proxy, routes, backup-manager).
+function runtimeIntegrationKind(meta) {
+    if (!meta)
+        return null;
+    const instanceId = typeof meta.id === "string" && meta.id.trim()
+        ? meta.id.trim()
+        : typeof meta.instanceId === "string" && meta.instanceId.trim()
+            ? meta.instanceId.trim()
+            : "<unknown>";
+    const owner = resolveExecutionOwnerFromMetadata(instanceId, meta);
+    return owner.type === "integration" ? owner.integrationKind : null;
+}
+function getRuntimeIntegrationEntry(meta) {
+    const integrationKind = runtimeIntegrationKind(meta);
+    if (!integrationKind)
+        return null;
+    return { kind: integrationKind, integration: getIntegration(integrationKind) };
+}
+export function getConfig(instanceId) {
+    const meta = getInstance(instanceId);
+    const entry = getRuntimeIntegrationEntry(meta);
+    if (!entry)
+        return null;
+    const integration = entry.integration;
+    return typeof integration.getNativeConfig === "function"
+        ? integration.getNativeConfig(instanceId)
+        : null;
+}
+export function getStoredConfig(instanceId) {
+    const meta = getInstance(instanceId);
+    const entry = getRuntimeIntegrationEntry(meta);
+    if (!entry)
+        return null;
+    const integration = entry.integration;
+    return typeof integration.getStoredNativeConfig === "function"
+        ? integration.getStoredNativeConfig(instanceId)
+        : null;
+}
+export async function saveConfig(instanceId, config) {
+    const meta = getInstance(instanceId);
+    const entry = getRuntimeIntegrationEntry(meta);
+    if (!entry)
+        return false;
+    try {
+        const integration = entry.integration;
+        if (typeof integration.saveNativeConfig !== "function")
+            return false;
+        // Integrations may return boolean or Promise<boolean>. Awaiting a plain
+        // boolean is a no-op, so this handles both. Previously we stripped the
+        // Promise and always reported success for async integrations — that masked
+        // failures and left callers unable to detect dirty state.
+        const result = await integration.saveNativeConfig(instanceId, config);
+        return typeof result === "boolean" ? result : true;
+    }
+    catch (e) {
+        console.warn(`[instance-manager] saveConfig dispatch failed for ${instanceId}: ${e.message}`);
+        return false;
+    }
+}
+// ── Integration-native helper dispatch wrappers ──────────────────────
+// Each helper resolves the app integration for the instance and forwards
+// to the corresponding integration method. Kept here so existing callers
+// (routes, plugin-installer, app service re-exports, tests) stay
+// integration-agnostic.
+/** Dispatch wrapper for `AppIntegration.isChannelPluginInstalled`. */
+export function isChannelPluginInstalled(instanceId, channelId) {
+    try {
+        const meta = getInstance(instanceId);
+        const entry = getRuntimeIntegrationEntry(meta);
+        if (!entry)
+            return false;
+        const integration = entry.integration;
+        return typeof integration.isChannelPluginInstalled === "function"
+            ? integration.isChannelPluginInstalled(instanceId, channelId)
+            : false;
+    }
+    catch (error) {
+        if (isExecutionOwnerRequiredError(error))
+            throw error;
+        return false;
+    }
+}
+export function saveFeishuCredentials(instanceId, creds) {
+    const meta = getInstance(instanceId);
+    const entry = getRuntimeIntegrationEntry(meta);
+    if (!entry) {
+        throw new Error(`Instance '${instanceId}' is not backed by an app integration`);
+    }
+    const a = entry.integration;
+    if (typeof a.saveFeishuCredentials !== "function") {
+        throw new Error(`Integration "${entry.kind}" does not support Feishu credentials`);
+    }
+    a.saveFeishuCredentials(instanceId, creds);
+}
+export function saveWeixinCredentials(instanceId, creds) {
+    const meta = getInstance(instanceId);
+    const entry = getRuntimeIntegrationEntry(meta);
+    if (!entry) {
+        throw new Error(`Instance '${instanceId}' is not backed by an app integration`);
+    }
+    const a = entry.integration;
+    if (typeof a.saveWeixinCredentials !== "function") {
+        throw new Error(`Integration "${entry.kind}" does not support WeChat credentials`);
+    }
+    a.saveWeixinCredentials(instanceId, creds);
+}
+export function getWeixinAccounts(instanceId) {
+    const meta = getInstance(instanceId);
+    try {
+        const entry = getRuntimeIntegrationEntry(meta);
+        if (!entry)
+            return [];
+        const a = entry.integration;
+        return typeof a.getWeixinAccounts === "function"
+            ? a.getWeixinAccounts(instanceId)
+            : [];
+    }
+    catch (error) {
+        if (isExecutionOwnerRequiredError(error))
+            throw error;
+        return [];
+    }
+}
+export function getInstanceRuntime(instanceId) {
+    const meta = getInstance(instanceId);
+    if (!meta)
+        return {};
+    return structuredClone(meta.runtime || {});
+}
+export function getRuntimeEnvFiles(instanceId) {
+    const runtime = getInstanceRuntime(instanceId);
+    const rawEnvFiles = Array.isArray(runtime.env_files)
+        ? runtime.env_files
+        : Array.isArray(runtime.envFiles)
+            ? runtime.envFiles
+            : [];
+    const envFiles = rawEnvFiles.map((p) => normalizePath(p)).filter(Boolean);
+    return envFiles.length ? envFiles : [defaultModelEnvFile(instanceId)];
+}
+export function getPrimaryHostPort(instanceId) {
+    return requireCanonicalPrimaryHostPort(instanceId, getInstanceRuntime(instanceId));
+}
+/**
+ * Detect the host address where a published app port is actually listening.
+ *
+ * Strategy by driver:
+ *  - raw_exec (Linux/Pi): use `ss` to read the listening address directly.
+ *  - docker (macOS/bridge): Nomad publishes the port on the Nomad client's
+ *    interface IP (e.g. 10.x.x.x), NOT 127.0.0.1. Query the Nomad allocation
+ *    for `AllocatedResources.Shared.Ports[].HostIP`.
+ *
+ * Result is cached for 30 s to avoid an API call on every proxy request.
+ */
+const _gwHostCache = new Map();
+const GW_HOST_CACHE_TTL = 30000;
+export function getListeningHostForPort(port) {
+    // Linux: ss is universal and parses cleanly. macOS/BSD ships lsof but
+    // not ss, so without this fallback execFileSync throws ENOENT, the
+    // catch block silently returns 127.0.0.1, and any caller that fans
+    // out to the wrong host fails (the capability HTTP proxy in
+    // `proxyProvidedCapability`, the gateway-host fallback for raw_exec
+    // instances, etc.). On macOS docker driver mode the actual published
+    // host can be e.g. 10.188.0.21 via `host_network = "external"`, never
+    // loopback — so silently picking 127.0.0.1 leaves the panel fetching
+    // a host nothing is listening on.
+    const safe = safePort(port);
+    const fromSs = () => {
+        const hosts = [];
+        try {
+            const out = execFileSync("ss", ["-tlnH", "sport", "=", ":" + safe], {
+                encoding: "utf-8",
+                timeout: 3000,
+                stdio: ["pipe", "pipe", "pipe"],
+            });
+            for (const line of out.split("\n")) {
+                let match = line.match(/\s([\d.]+):(\d+)\s/);
+                if (!match)
+                    match = line.match(/\s\[([0-9a-fA-F:]+)\]:(\d+)\s/);
+                if (match && match[2] === String(port))
+                    hosts.push(match[1]);
+            }
+        }
+        catch { /* ss not available or no match */ }
+        return hosts;
+    };
+    const fromLsof = () => {
+        const hosts = [];
+        try {
+            // `-FnP` keeps numeric output (no name resolution, no /etc/services).
+            // Lines beginning with `n` carry the bind address: e.g. `n10.188.0.21:8080`,
+            // `n127.0.0.1:8080`, `n[::1]:8080`, or `n*:8080` for wildcard binds.
+            const out = execFileSync("lsof", ["-nP", "-iTCP:" + safe, "-sTCP:LISTEN", "-FnP"], {
+                encoding: "utf-8",
+                timeout: 3000,
+                stdio: ["pipe", "pipe", "pipe"],
+            });
+            for (const line of out.split("\n")) {
+                if (!line.startsWith("n"))
+                    continue;
+                const body = line.slice(1);
+                // IPv6 form: [::1]:8080 → strip brackets
+                const v6 = body.match(/^\[([0-9a-fA-F:]+)\]:(\d+)$/);
+                if (v6 && v6[2] === String(port)) {
+                    hosts.push(v6[1]);
+                    continue;
+                }
+                const idx = body.lastIndexOf(":");
+                if (idx <= 0)
+                    continue;
+                const addr = body.slice(0, idx);
+                const portPart = body.slice(idx + 1);
+                if (portPart === String(port))
+                    hosts.push(addr === "*" ? "0.0.0.0" : addr);
+            }
+        }
+        catch { /* lsof unavailable or no match */ }
+        return hosts;
+    };
+    const detected = process.platform === "linux"
+        ? [...fromSs(), ...fromLsof()]
+        : [...fromLsof(), ...fromSs()];
+    const unique = [...new Set(detected)];
+    if (unique.length === 0)
+        return "127.0.0.1";
+    return unique[0] === "0.0.0.0" ? "127.0.0.1" : unique[0];
+}
+function getExclusiveLoopbackListenerForPort(port) {
+    const safe = safePort(port);
+    const hosts = new Set();
+    try {
+        const out = execFileSync("lsof", ["-nP", "-iTCP:" + safe, "-sTCP:LISTEN", "-FnP"], {
+            encoding: "utf-8",
+            timeout: 3000,
+            stdio: ["pipe", "pipe", "pipe"],
+        });
+        for (const line of out.split("\n")) {
+            if (!line.startsWith("n"))
+                continue;
+            const body = line.slice(1);
+            if (body === `127.0.0.1:${safe}`) {
+                hosts.add("127.0.0.1");
+                continue;
+            }
+            if (body === `[::1]:${safe}`) {
+                hosts.add("::1");
+                continue;
+            }
+            if (!body.endsWith(`:${safe}`))
+                continue;
+            const addr = body.startsWith("[")
+                ? body.slice(1, body.lastIndexOf("]"))
+                : body.slice(0, body.lastIndexOf(":"));
+            hosts.add(addr === "*" ? "0.0.0.0" : addr);
+        }
+    }
+    catch { /* lsof unavailable or no match */ }
+    try {
+        const out = execFileSync("ss", ["-tlnH", "sport", "=", ":" + safe], {
+            encoding: "utf-8",
+            timeout: 3000,
+            stdio: ["pipe", "pipe", "pipe"],
+        });
+        for (const line of out.split("\n")) {
+            const ipv4 = line.match(/\s([\d.]+):(\d+)\s/);
+            if (ipv4 && ipv4[2] === String(safe))
+                hosts.add(ipv4[1]);
+            const ipv6 = line.match(/\s\[([0-9a-fA-F:]+)\]:(\d+)\s/);
+            if (ipv6 && ipv6[2] === String(safe))
+                hosts.add(ipv6[1]);
+        }
+    }
+    catch { /* ss unavailable or no match */ }
+    if (hosts.size === 0)
+        return null;
+    let hasIpv4Loopback = false;
+    let hasIpv6Loopback = false;
+    for (const host of hosts) {
+        if (host === "127.0.0.1") {
+            hasIpv4Loopback = true;
+            continue;
+        }
+        if (host === "::1") {
+            hasIpv6Loopback = true;
+            continue;
+        }
+        if (host === "0.0.0.0" || host === "::")
+            return null;
+        return null;
+    }
+    if (hasIpv4Loopback)
+        return "127.0.0.1";
+    if (hasIpv6Loopback)
+        return "::1";
+    return null;
+}
+export function getPrimaryIpv4Address() {
+    try {
+        for (const list of Object.values(networkInterfaces())) {
+            for (const iface of list ?? []) {
+                if (!iface.internal && iface.family === "IPv4")
+                    return iface.address;
+            }
+        }
+    }
+    catch { /* fall through */ }
+    return "127.0.0.1";
+}
+export function getAdvertisedHostForPort(port) {
+    const host = getListeningHostForPort(port);
+    if (host && host !== "127.0.0.1" && host !== "0.0.0.0" && host !== "::1" && host !== "::") {
+        return host;
+    }
+    return getPrimaryIpv4Address();
+}
+export function getConnectHostForPort(port) {
+    const host = getListeningHostForPort(port);
+    if (!host || host === "0.0.0.0" || host === "::")
+        return "127.0.0.1";
+    return host;
+}
+export async function getPrimaryHostForInstance(instanceId) {
+    const cached = _gwHostCache.get(instanceId);
+    if (cached && Date.now() - cached.ts < GW_HOST_CACHE_TTL)
+        return cached.host;
+    const port = getPrimaryHostPort(instanceId);
+    let result = "127.0.0.1";
+    try {
+        const { getNomadDriver } = await import("../../config.js");
+        if (getNomadDriver() === "docker") {
+            const { getNomadAddr, getNomadToken } = await import("../../config.js");
+            // Dispatch job-id construction through the integration so every runtime
+            // owns its own Nomad job namespace (<kind>-<id>, bare app id, etc.).
+            // Falls back to a generic `jishushell-` prefix only when the integration
+            // lookup fails — that branch should never fire for a registered
+            // agent type.
+            const meta = getInstance(instanceId);
+            let prefix = "jishushell-";
+            try {
+                const a = getRuntimeIntegrationEntry(meta)?.integration;
+                if (a && typeof a.nomadJobPrefix === "string" && a.nomadJobPrefix.length) {
+                    prefix = a.nomadJobPrefix;
+                }
+            }
+            catch (error) {
+                if (isExecutionOwnerRequiredError(error))
+                    throw error;
+                /* use fallback prefix for non-identity integration failures */
+            }
+            // Avoid double-prefix when the instance ID already carries the
+            // integration prefix. Without this guard we'd double-prefix the id,
+            // get 0 allocs, and fall back
+            // to the 127.0.0.1 default — which silently breaks the gateway
+            // proxy on docker driver where the real HostIP differs.
+            const jid = instanceId.startsWith(prefix) ? instanceId : `${prefix}${instanceId}`;
+            const headers = { "Content-Type": "application/json" };
+            const token = getNomadToken();
+            if (token)
+                headers["X-Nomad-Token"] = token;
+            const resp = await fetch(`${getNomadAddr()}/v1/job/${encodeURIComponent(jid)}/allocations`, {
+                headers,
+                signal: AbortSignal.timeout(5000),
+            });
+            if (resp.ok) {
+                const allocs = await resp.json();
+                const alloc = allocs.find((a) => a.ClientStatus === "running")
+                    ?? allocs.find((a) => a.ClientStatus === "pending");
+                if (alloc) {
+                    const detail = await fetch(`${getNomadAddr()}/v1/allocation/${encodeURIComponent(alloc.ID)}`, { headers, signal: AbortSignal.timeout(5000) });
+                    if (detail.ok) {
+                        const d = await detail.json();
+                        // Preferred source: AllocatedResources.Shared.Ports (bridge mode).
+                        const sharedPorts = d?.AllocatedResources?.Shared?.Ports ?? [];
+                        const gwPort = sharedPorts.find((p) => p.Label === "gateway");
+                        if (gwPort?.HostIP && gwPort.HostIP !== "0.0.0.0") {
+                            result = gwPort.HostIP;
+                        }
+                        else {
+                            // Host mode / task-level reservation: address lives under
+                            // AllocatedResources.Tasks.<task>.Networks[*].IP. On Nomad
+                            // 1.6.5 with `network_interface = "lo"`, the IP is whichever
+                            // address the OS enumerates first — which can be IPv6 `::1`
+                            // on systems where lo has both `127.0.0.1/8` and `::1/128`
+                            // (the default on most modern Linux distros). Reading it from
+                            // here is the authoritative source and matches what nomad
+                            // configures the docker-proxy bind to use.
+                            //
+                            // Scan every task instead of indexing a hardcoded "gateway"
+                            // task — integrations are free to name the task whatever they
+                            // like, we only require the reserved port carry the
+                            // framework-level `gateway` label.
+                            const tasksMap = d?.AllocatedResources?.Tasks ?? {};
+                            for (const taskName of Object.keys(tasksMap)) {
+                                const taskNets = tasksMap[taskName]?.Networks ?? [];
+                                const net = taskNets.find((n) => {
+                                    const rps = n?.ReservedPorts ?? [];
+                                    return rps.some((p) => p.Label === "gateway");
+                                });
+                                if (net?.IP && net.IP !== "0.0.0.0") {
+                                    result = net.IP;
+                                    break;
+                                }
+                            }
+                        }
+                    }
+                }
+            }
+            // If Nomad API resolved a non-default host, cache and return it
+            if (result !== "127.0.0.1") {
+                const localLoopbackHost = getExclusiveLoopbackListenerForPort(port);
+                if (localLoopbackHost) {
+                    result = localLoopbackHost;
+                }
+                _gwHostCache.set(instanceId, { host: result, ts: Date.now() });
+                return result;
+            }
+            // Otherwise fall through to ss-based detection
+        }
+    }
+    catch { /* fall through */ }
+    result = getListeningHostForPort(port);
+    _gwHostCache.set(instanceId, { host: result, ts: Date.now() });
+    return result;
+}
+const _appPortHostCache = new Map();
+const APP_PORT_HOST_CACHE_TTL = 30000;
+/**
+ * Resolve the host IP for a specific port belonging to an app's Nomad job.
+ *
+ * On macOS with Colima + docker driver the container port is bound *inside*
+ * the VM, not on the host.  `ss` (or `netstat`) run on the macOS host see
+ * nothing on that port, so `getListeningHostForPort` returns 127.0.0.1 and
+ * the core proxy gets a 502.
+ *
+ * This function mirrors the logic of `getPrimaryHostForInstance` but matches by port
+ * *value* rather than by the "gateway" label, making it suitable for
+ * arbitrary capability ports exposed by app tasks.
+ */
+export async function getHostForAppPort(instanceId, port) {
+    const cacheKey = `${instanceId}:${port}`;
+    const cached = _appPortHostCache.get(cacheKey);
+    if (cached && Date.now() - cached.ts < APP_PORT_HOST_CACHE_TTL)
+        return cached.host;
+    let result = "127.0.0.1";
+    try {
+        const { getNomadDriver, getNomadAddr, getNomadToken } = await import("../../config.js");
+        if (getNomadDriver() === "docker") {
+            const headers = { "Content-Type": "application/json" };
+            const token = getNomadToken();
+            if (token)
+                headers["X-Nomad-Token"] = token;
+            const resp = await fetch(`${getNomadAddr()}/v1/job/${encodeURIComponent(instanceId)}/allocations`, { headers, signal: AbortSignal.timeout(5000) });
+            if (resp.ok) {
+                const allocs = await resp.json();
+                const alloc = allocs.find((a) => a.ClientStatus === "running")
+                    ?? allocs.find((a) => a.ClientStatus === "pending");
+                if (alloc) {
+                    const detail = await fetch(`${getNomadAddr()}/v1/allocation/${encodeURIComponent(alloc.ID)}`, { headers, signal: AbortSignal.timeout(5000) });
+                    if (detail.ok) {
+                        const d = await detail.json();
+                        // Bridge / host-network mode: ports listed under Shared.Ports
+                        const sharedPorts = d?.AllocatedResources?.Shared?.Ports ?? [];
+                        const matched = sharedPorts.find((p) => p.Value === port || p.To === port);
+                        if (matched?.HostIP && matched.HostIP !== "0.0.0.0") {
+                            result = matched.HostIP;
+                        }
+                    }
+                }
+            }
+        }
+    }
+    catch { /* fall through to ss-based detection */ }
+    if (result === "127.0.0.1") {
+        result = getListeningHostForPort(port);
+    }
+    _appPortHostCache.set(cacheKey, { host: result, ts: Date.now() });
+    return result;
+}
+/**
+ * Wrap an IPv6 literal in brackets for safe URL host-component / Host-header
+ * use. Bare names ("gateway.local") and IPv4 ("127.0.0.1") contain no colon
+ * and pass through unchanged; anything with a colon is an IPv6 literal and
+ * MUST be bracketed before being concatenated with a port, otherwise
+ * `http://::1:18095/` is unparseable.
+ */
+export function urlHost(host) {
+    return host.includes(":") ? `[${host}]` : host;
+}
+export function findInstancesSharingIntegrationHome(instanceId) {
+    const meta = getInstance(instanceId);
+    try {
+        const entry = getRuntimeIntegrationEntry(meta);
+        if (!entry)
+            return [];
+        const a = entry.integration;
+        return typeof a.findInstancesSharingHome === "function"
+            ? a.findInstancesSharingHome(instanceId)
+            : [];
+    }
+    catch (error) {
+        if (isExecutionOwnerRequiredError(error))
+            throw error;
+        return [];
+    }
+}
+/**
+ * Re-pick the primary host port for an existing instance and rewrite only the
+ * persisted host-side mapping in `runtime.ports[].hostPort`.
+ *
+ * Used when {@link isPortInUse} reports that the previously-assigned
+ * `hostPort` has been taken by something else between create-time and
+ * start-time (e.g. an unrelated service that grabbed the port at boot, or a
+ * Docker race on the next allocation). The Nomad job spec is rebuilt from
+ * instance metadata on every submit, so updating `instance.json` here is
+ * sufficient — no other files need patching, and the in-container process
+ * listener keeps the same `containerPort`.
+ *
+ * Lifecycle: this is the canonical Step 2 reserve / commit / release flow:
+ *   - `allocateHostPort(...)` reserves a candidate hostPort.
+ *   - On successful durable persist (`safeWriteJson` of `instance.json`),
+ *     `alloc.commit()` retires the reservation; durable ownership has taken
+ *     over via `runtime.ports[].hostPort`.
+ *   - On any thrown failure, `alloc.release()` frees the slot so concurrent
+ *     / retried reallocations can reuse the port.
+ *
+ * Domain note: this function intentionally only rewrites `hostPort`.
+ * Integration-specific `reallocateRuntimePort` implementations and the
+ * generic AppSpec fallback must both preserve the workload's
+ * `containerPort`.
+ *
+ * Scope note: this is a primary-port helper for single-gateway integration
+ * runtimes and legacy compatibility paths. Generic multi-port AppSpec
+ * preflight must not use it as a full conflict check; it should iterate every
+ * external `runtime.ports[]` entry and call `reallocateRuntimeHostPort(...)`
+ * for the specific conflicting task/port.
+ */
+export async function reallocatePrimaryHostPort(instanceId) {
+    const meta = getInstance(instanceId);
+    if (!meta)
+        throw new Error(`Cannot reallocate port for unknown instance '${instanceId}'`);
+    const entry = getRuntimeIntegrationEntry(meta);
+    const fromPort = requireCanonicalPrimaryHostPort(instanceId, meta.runtime);
+    const alloc = await allocateHostPort(instanceId, entry?.integration.preferredHostPort ?? fromPort, fromPort);
+    let committed = false;
+    try {
+        const runtime = (meta.runtime ?? {});
+        // Delegate kind-specific rewrites to integrations when present. Generic
+        // AppSpec instances rewrite only the first externally visible
+        // `runtime.ports[].hostPort`; never rewrite containerPort.
+        if (typeof entry?.integration.reallocateRuntimePort === "function") {
+            entry.integration.reallocateRuntimePort(runtime, alloc.port);
+        }
+        else if (Array.isArray(runtime.ports) && runtime.ports.length > 0) {
+            let rewritten = false;
+            runtime.ports = runtime.ports.map((port, index) => {
+                if (!rewritten && ((port?.visibility ?? "external") !== "internal" || index === 0)) {
+                    rewritten = true;
+                    return { ...port, hostPort: alloc.port };
+                }
+                return port;
+            });
+        }
+        else {
+            throw new CanonicalRuntimePortRequiredError(instanceId);
+        }
+        updateInstanceMeta(instanceId, { runtime });
+        // `instance.json` now durably owns the new hostPort; flip the
+        // reservation from `reserve` to `commit` BEFORE follow-up I/O so any
+        // later failure does not leak the reservation slot.
+        alloc.commit();
+        committed = true;
+        console.log(`[instance] ${instanceId}: primary port reallocated ${fromPort} -> ${alloc.port}`);
+        return { from: fromPort, to: alloc.port, skipped: alloc.skipped };
+    }
+    catch (error) {
+        if (!committed)
+            alloc.release();
+        throw error;
+    }
+}
+export async function reallocateRuntimeHostPort(instanceId, portRef) {
+    const meta = getInstance(instanceId);
+    if (!meta)
+        throw new Error(`Cannot reallocate port for unknown instance '${instanceId}'`);
+    const runtime = structuredClone((meta.runtime ?? {}));
+    const ports = Array.isArray(runtime.ports) ? runtime.ports : [];
+    const index = ports.findIndex((port) => port?.name === portRef.name
+        && (portRef.taskName == null
+            || port?.taskName === portRef.taskName));
+    if (index < 0) {
+        throw new CanonicalRuntimePortRequiredError(instanceId);
+    }
+    const fromPort = ports[index]?.hostPort;
+    if (!Number.isInteger(fromPort) || fromPort <= 0) {
+        throw new CanonicalRuntimePortRequiredError(instanceId);
+    }
+    const alloc = await allocateHostPort(instanceId, fromPort + 1, fromPort);
+    let committed = false;
+    try {
+        runtime.ports = ports.map((port, portIndex) => portIndex === index ? { ...port, hostPort: alloc.port } : port);
+        updateInstanceMeta(instanceId, { runtime });
+        alloc.commit();
+        committed = true;
+        console.log(`[instance] ${instanceId}: runtime port ${portRef.taskName ? `${portRef.taskName}/` : ""}${portRef.name} ` +
+            `reallocated ${fromPort} -> ${alloc.port}`);
+        return { from: fromPort, to: alloc.port, skipped: alloc.skipped };
+    }
+    catch (error) {
+        if (!committed)
+            alloc.release();
+        throw error;
+    }
+}
+export function findInstancesSharingPrimaryHostPort(instanceId) {
+    const targetPort = getPrimaryHostPort(instanceId);
+    return listInstances()
+        .filter((inst) => inst.id !== instanceId)
+        .filter((inst) => extractPrimaryHostPort(inst.runtime) === targetPort)
+        .map((inst) => inst.id);
+}
+export function getRuntimeEnv(instanceId) {
+    const runtime = getInstanceRuntime(instanceId);
+    const env = {};
+    for (const envFile of getRuntimeEnvFiles(instanceId)) {
+        Object.assign(env, parseEnvFile(envFile));
+    }
+    for (const [key, value] of Object.entries(runtime.env || {})) {
+        if (value != null)
+            env[key] = String(value);
+    }
+    return env;
+}
+// Re-export instanceDir for the Nomad driver under its getInstanceDir alias.
+export { instanceDir as getInstanceDir };
+// Integration config-path resolvers are owned by their integration modules.
+//# sourceMappingURL=manager.js.map