@bendyline/gezel-inference 1.0.5 → 1.0.7

package/dist/providers/native/device-capacity-ledger.js

@@ -2,6 +2,7 @@ import { chmod, mkdir } from 'node:fs/promises';
 import { createRequire } from 'node:module';
 import { join } from 'node:path';
 import { CapacityDeniedError } from './capacity-broker.js';
+import { readProcessIdentities } from './process-identity.js';
 // Keep the newer builtin behind a runtime require. The current tsup/esbuild
 // target rewrites a static `node:sqlite` import to the nonexistent npm package
 // `sqlite`, making the daemon bundle fail before it can write runtime state.
@@ -38,9 +39,26 @@ export class DeviceCapacityLedger {
             await chmod(path, 0o600);
             db.exec('PRAGMA busy_timeout = 1000');
             db.exec('CREATE TABLE IF NOT EXISTS claims (id TEXT PRIMARY KEY, claim TEXT NOT NULL)');
+            const snapshot = db
+                .prepare('SELECT claim FROM claims')
+                .all()
+                .map((row) => JSON.parse(String(row.claim)));
+            const pids = snapshot.flatMap((claim) => [
+                claim.ownerPid,
+                ...(claim.childPid === undefined ? [] : [claim.childPid]),
+            ]);
+            if (command.action === 'acquire')
+                pids.push(command.ownerPid);
+            if (command.action === 'bind')
+                pids.push(command.childPid);
+            // OS probes may spawn a helper. Never hold SQLite's writer lock while awaiting one.
+            const probe = this.options.identities ?? (this.options.alive ? undefined : readProcessIdentities);
+            const identities = command.action !== 'release' && probe
+                ? await probe(pids).catch(() => new Map())
+                : new Map();
             db.exec('BEGIN IMMEDIATE');
             try {
-                const result = this.transact(db, command, sample);
+                const result = this.transact(db, command, sample, identities, new Map(snapshot.map((claim) => [claim.id, JSON.stringify(claim)])));
                 db.exec('COMMIT');
                 return result;
             }
@@ -53,17 +71,27 @@ export class DeviceCapacityLedger {
             db.close();
         }
     }
-    transact(db, command, sample) {
+    transact(db, command, sample, identities, observedClaims) {
         const alive = this.options.alive ?? processAlive;
+        const sameProcess = (pid, identity) => {
+            if (!alive(pid))
+                return false;
+            const current = identities.get(pid);
+            return identity === undefined || current === undefined || current === identity;
+        };
         const rows = db.prepare('SELECT claim FROM claims ORDER BY rowid').all();
         const claims = rows.map((row) => JSON.parse(String(row.claim)));
         const remove = db.prepare('DELETE FROM claims WHERE id = ?');
         const save = db.prepare('UPDATE claims SET claim = ? WHERE id = ?');
         const live = claims.filter((claim) => {
+            // Another coordinator can acquire/rebind while the OS probe is in flight.
+            // Its newer claim must not be compared with our earlier process snapshot.
+            if (observedClaims.get(claim.id) !== JSON.stringify(claim))
+                return true;
             // An unbound grant with a dead owner could have spawned just before the
             // owner died. Keep it conservatively; never guess that its bytes are free.
-            const stale = (claim.childPid !== undefined && !alive(claim.childPid)) ||
-                (!alive(claim.ownerPid) && claim.phase === 'waiting');
+            const stale = (claim.childPid !== undefined && !sameProcess(claim.childPid, claim.childIdentity)) ||
+                (!sameProcess(claim.ownerPid, claim.ownerIdentity) && claim.phase === 'waiting');
             if (stale)
                 remove.run(claim.id);
             return !stale;
@@ -80,6 +108,7 @@ export class DeviceCapacityLedger {
             own = {
                 id: command.id,
                 ownerPid: command.ownerPid,
+                ownerIdentity: identities.get(command.ownerPid),
                 label: command.label,
                 bytes: command.bytes,
                 gpuBytes: command.gpuBytes,
@@ -95,8 +124,10 @@ export class DeviceCapacityLedger {
             return { state: 'released', releaseRequested: false };
         if (command.action === 'acquire' && command.priority === 'interactive')
             own.priority = 'interactive';
-        if (command.action === 'bind' && own.phase !== 'waiting')
+        if (command.action === 'bind' && own.phase !== 'waiting') {
             own.childPid = command.childPid;
+            own.childIdentity = identities.get(command.childPid);
+        }
         if (command.action === 'ready' && own.phase === 'loading')
             own.phase = 'ready';
         const active = live.filter((c) => c.phase !== 'waiting');

package/dist/providers/native/device-capacity.js

@@ -1,11 +1,12 @@
 import { randomUUID } from 'node:crypto';
 import { readdir, stat } from 'node:fs/promises';
-import { homedir, totalmem } from 'node:os';
+import { homedir } from 'node:os';
 import { join } from 'node:path';
 import { DS4_FULL_RESIDENCY_HEADROOM_BYTES, GEZEL_VERSION, NativeCapacityCommandSchema, NativeCapacityReplySchema, awakeNow, createLogger, isUnstampedDevBuild, } from '@bendyline/gezel';
 import { readSystemServiceRuntime, systemServiceHome } from '@bendyline/gezel-client/node';
 import { ConfigStore } from '../../fs/config-store.js';
 import { createPinnedFetch } from '../../remotes/pinned-fetch.js';
+import { totalMemoryBytes } from '../../system/host-memory.js';
 import { CapacityDeniedError, availableSystemRamBytes, liveRamOsReserveBytes, } from './capacity-broker.js';
 import { DeviceCapacityLedger } from './device-capacity-ledger.js';
 import { measuredCapacityBudget } from './measured-budget.js';
@@ -156,7 +157,7 @@ export function staticCapacityCeilings(budget, ramBytes, configuredBytes, platfo
 }
 export async function sampleDeviceCapacity(home) {
     const budget = await measuredCapacityBudget();
-    const ram = totalmem();
+    const ram = totalMemoryBytes();
     const config = home ? await new ConfigStore(home).readConfig() : {};
     const ceilings = staticCapacityCeilings(budget, ram, configuredEngineMemoryBytes(config));
     // The ledger's RAM ceiling and the OS's currently reclaimable RAM answer
@@ -213,7 +214,7 @@ async function capacityExecutor(home) {
                 // broker that is merely unreachable is an outage, never permission to
                 // double-book the machine — so claim the authority before rethrowing.
                 observedMachineAuthorities.add(machineHome);
-                throw error;
+                throw new Error(`Local models can't start: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
             }
             const skew = assessBrokerVersionSkew(identity.gezelVersion);
             if (skew)

package/dist/providers/native/local-engine-runtime.js

@@ -609,10 +609,10 @@ export class LocalEngineRuntime {
                                 residentCtxTokens: ds4Block?.residentCtxTokens,
                             });
                             if (line) {
-                                const { totalmem } = await import('node:os');
+                                const { totalMemoryBytes } = await import('../../system/host-memory.js');
                                 bytes = ds4ProjectedResidentBytes(line, resolveDs4LaunchCtx({
                                     configured: config.modelContextOverrides?.[`ds4:${modelId}`] ?? config.ds4NumCtx,
-                                    ramTieredCtx: totalmem() / 1024 ** 3 >= 192 ? 262_144 : 131_072,
+                                    ramTieredCtx: totalMemoryBytes() / 1024 ** 3 >= 192 ? 262_144 : 131_072,
                                     catalogMaxCtx: ds4Block?.maxLaunchCtx,
                                     minViableContextTokens: minViableLocalContextTokens(),
                                 }));
@@ -1046,8 +1046,8 @@ export class LocalEngineRuntime {
             if (!installed && !hasExplicitSource && !(opts.allowUninstalled && ds4Source)) {
                 throw new ModelNotInstalledError(name, modelId);
             }
-            const { totalmem } = await import('node:os');
-            const ramTieredCtx = totalmem() / 1024 ** 3 >= 192 ? 262_144 : 131_072;
+            const { totalMemoryBytes } = await import('../../system/host-memory.js');
+            const ramTieredCtx = totalMemoryBytes() / 1024 ** 3 >= 192 ? 262_144 : 131_072;
             const ds4Override = config.modelContextOverrides?.[`ds4:${modelId}`];
             const ds4Floor = ds4Override !== undefined ? Math.min(contextFloor, ds4Override) : contextFloor;
             const effective = resolveDs4LaunchCtx({

package/dist/providers/native/process-identity.d.ts

@@ -0,0 +1,2 @@
+/** Birth stamps survive coordinator restarts and distinguish a reused PID. */
+export declare function readProcessIdentities(pids: readonly number[]): Promise<ReadonlyMap<number, string>>;

package/dist/providers/native/process-identity.js

@@ -0,0 +1,70 @@
+import { execFile } from 'node:child_process';
+import { readFile } from 'node:fs/promises';
+import { promisify } from 'node:util';
+const exec = promisify(execFile);
+/**
+ * One PID the probe refuses blanks every row in its batch: macOS ps prints
+ * "process id too large" past XNU's PID_MAX, and Get-Process -Id binds Int32.
+ * A PID past the limit cannot be live, so it is left out like an absent one.
+ */
+const PROBE_PID_LIMIT = {
+    darwin: 99_999,
+    win32: 2_147_483_647,
+};
+/** Birth stamps survive coordinator restarts and distinguish a reused PID. */
+export async function readProcessIdentities(pids) {
+    const limit = PROBE_PID_LIMIT[process.platform] ?? Number.MAX_SAFE_INTEGER;
+    const ids = [...new Set(pids)].filter((pid) => Number.isSafeInteger(pid) && pid > 0 && pid <= limit);
+    const identities = new Map();
+    if (!ids.length)
+        return identities;
+    try {
+        if (process.platform === 'linux') {
+            const boot = (await readFile('/proc/sys/kernel/random/boot_id', 'utf8')).trim();
+            await Promise.all(ids.map(async (pid) => {
+                const value = await readFile(`/proc/${pid}/stat`, 'utf8').catch(() => null);
+                if (!value)
+                    return;
+                // comm may contain spaces and parentheses; fields after its final ')' start at field 3.
+                const start = value
+                    .slice(value.lastIndexOf(')') + 2)
+                    .trim()
+                    .split(/\s+/)[19];
+                if (start && /^\d+$/.test(start))
+                    identities.set(pid, `${boot}:${start}`);
+            }));
+        }
+        else {
+            const windows = process.platform === 'win32';
+            const { stdout } = await exec(windows ? 'powershell.exe' : 'ps', windows
+                ? [
+                    '-NoProfile',
+                    '-NonInteractive',
+                    '-Command',
+                    `Get-Process -Id ${ids.join(',')} -ErrorAction SilentlyContinue | ForEach-Object { try { [string]$_.Id + ":" + $_.StartTime.ToUniversalTime().Ticks.ToString() } catch {} }`,
+                ]
+                : ['-p', ids.join(','), '-o', 'pid=', '-o', 'lstart='], {
+                windowsHide: true,
+                timeout: 3000,
+                maxBuffer: 256 * 1024,
+                env: { ...process.env, TZ: 'UTC', LC_ALL: 'C', LANG: 'C' },
+            }).catch((error) => {
+                // ps (and Windows process lookup) may return live rows alongside a missing PID error.
+                if (typeof error.stdout === 'string')
+                    return { stdout: error.stdout };
+                throw error;
+            });
+            for (const line of stdout.split(/\r?\n/)) {
+                const match = windows
+                    ? /^\s*(\d+):(\d+)\s*$/.exec(line)
+                    : /^\s*(\d+)\s+(.+?)\s*$/.exec(line);
+                if (match && ids.includes(Number(match[1])))
+                    identities.set(Number(match[1]), match[2]);
+            }
+        }
+    }
+    catch {
+        // Access denied or an unavailable OS probe is unknown, never proof of death.
+    }
+    return identities;
+}

package/dist/relevance/relevance-core.js

@@ -3,6 +3,7 @@ import { createReadStream } from 'node:fs';
 import { join } from 'node:path';
 import { createLogger } from '@bendyline/gezel';
 import { transformersGraphOptions } from '@bendyline/gezel-knowledge';
+import { disableOnnxRuntimeTelemetry } from '@bendyline/gezel/native';
 import { PipelineLoadError } from '../memory/embed-core.js';
 /**
  * Cross-encoder inference: load a pinned relevance model from its local
@@ -19,6 +20,7 @@ const BATCH = 8;
 const MAX_LOADED = 2;
 const loaded = new Map();
 async function importTransformers() {
+    disableOnnxRuntimeTelemetry();
     return (await import('@huggingface/transformers'));
 }
 export async function loadRelevanceModel(model, transformers) {

package/dist/relevance/relevance-model.js

@@ -1,5 +1,6 @@
 import { Worker } from 'node:worker_threads';
 import { createLogger } from '@bendyline/gezel';
+import { disableOnnxRuntimeTelemetry } from '@bendyline/gezel/native';
 import { retireModelWorker } from '../utils/retire-model-worker.js';
 import { findServiceWorkerEntry } from '../utils/service-worker-entry.js';
 import { disposeRelevanceModels, loadRelevanceModel, scoreRelevancePairs, } from './relevance-core.js';
@@ -185,6 +186,7 @@ class RelevanceModelHost {
             return null;
         }
         try {
+            disableOnnxRuntimeTelemetry();
             const worker = new Worker(entry);
             worker.on('message', (reply) => {
                 const pending = this.pending.get(reply.id);

package/dist/relevance/settings.js

@@ -1,5 +1,5 @@
-import { availableParallelism } from 'node:os';
 import { KNOWLEDGE_FILTER_MIN_RELEVANCE, } from '@bendyline/gezel';
+import { availableCpuCount } from '../system/host-memory.js';
 import { relevanceModelDir } from './install.js';
 import { DEFAULT_RELEVANCE_MODEL_ID, findRelevanceModel } from './registry.js';
 const DEFAULT_BUDGETS = {
@@ -76,6 +76,6 @@ export function toResolvedModel(home, spec) {
         maxTokens: spec.maxTokens,
         queryMaxTokens: spec.queryMaxTokens,
         scoreActivation: spec.scoreActivation,
-        intraOpNumThreads: Math.max(1, Math.min(4, Math.floor(availableParallelism() / 2))),
+        intraOpNumThreads: Math.max(1, Math.min(4, Math.floor(availableCpuCount() / 2))),
     };
 }

package/dist/runtime-lock.d.ts

@@ -6,24 +6,62 @@
 export declare class SingleInstanceError extends Error {
     readonly holderPid: number;
     readonly lockPath: string;
-    constructor(holderPid: number, lockPath: string);
+    readonly holderHost?: string | undefined;
+    constructor(holderPid: number, lockPath: string, holderHost?: string | undefined);
 }
 export interface RuntimeLock {
     release(): Promise<void>;
 }
+/**
+ * Who holds a lock. A pid alone identifies a process only inside one pid
+ * namespace on one boot: two containers sharing a volume each see the
+ * other's pid as dead (or as an unrelated process), which let a one-shot
+ * `docker run … gezel do` reclaim a serving container's live lock. The
+ * namespace, boot and host fields say when a pid check is meaningful; a
+ * holder outside our namespace is judged by the lock file's heartbeat.
+ */
+export interface LockIdentity {
+    pid: number;
+    hostname?: string;
+    bootId?: string;
+    pidNs?: string;
+    /** Process start time in clock ticks since boot (`/proc/<pid>/stat` field 22). */
+    startTicks?: string;
+    /** Random per-process id; tells our own heartbeat whether the lock is still ours. */
+    instance?: string;
+}
+export declare function procStartTicks(pid: number | 'self'): string | undefined;
+export declare function currentLockIdentity(): LockIdentity;
+export declare function parseLockFile(text: string): LockIdentity | null;
+/**
+ * Whether a pid check against `holder` means anything here. Any field the
+ * holder recorded must match ours; a legacy pid-only record is assumed to be
+ * in our namespace, which is how it was judged before.
+ */
+export declare function sharesPidNamespace(holder: LockIdentity, me: LockIdentity): boolean;
 /**
  * Acquire an exclusive single-instance lock for a gezel home so two daemons
  * can't share one `~/.gezel/` and race its on-disk state (config, sessions,
  * tasks, runtime files). Atomic `O_CREAT|O_EXCL` create of
- * `<runtimeDir>/lock` holding the owner pid; a stale lock (dead holder) is
+ * `<runtimeDir>/lock` holding the owner's identity; a stale lock is
  * reclaimed. Throws {@link SingleInstanceError} when a live daemon holds it.
  *
- * The returned `release()` removes the lock — call it on graceful shutdown.
- * A hard crash leaves a stale lock that the next start reclaims via the
- * pid-liveness check.
+ * While held, the lock file's mtime is touched every few seconds: that
+ * heartbeat is how a daemon in another container (another pid namespace)
+ * is told apart from a dead one.
+ *
+ * The returned `release()` stops the heartbeat and removes the lock — call
+ * it on graceful shutdown. A hard crash leaves a stale lock the next start
+ * reclaims.
  */
 export declare function acquireSingleInstanceLock(opts: {
     runtimeDir: string;
     lockPath: string;
     isAlive?: (pid: number) => boolean;
+    identity?: LockIdentity;
+    startTicksOf?: (pid: number) => string | undefined;
+    now?: () => number;
+    sleep?: (ms: number) => Promise<void>;
+    heartbeatIntervalMs?: number;
+    staleAfterMs?: number;
 }): Promise<RuntimeLock>;

package/dist/runtime-lock.js

@@ -1,4 +1,6 @@
-import { mkdir, open, readFile, rm } from 'node:fs/promises';
+import { readFileSync, readlinkSync } from 'node:fs';
+import { mkdir, open, readFile, rm, stat, utimes } from 'node:fs/promises';
+import { hostname as osHostname } from 'node:os';
 /**
  * Thrown when a gezel home already has a live daemon. The CLI's `gezel
  * start` / the supervisor surface this as an actionable message rather
@@ -7,15 +9,21 @@ import { mkdir, open, readFile, rm } from 'node:fs/promises';
 export class SingleInstanceError extends Error {
     holderPid;
     lockPath;
-    constructor(holderPid, lockPath) {
-        super(holderPid > 0
-            ? `Another gezel daemon is already running for this home (pid ${holderPid}). Stop it first with \`gezel stop\`, or use a different GEZEL_HOME.`
-            : `Could not acquire the single-instance lock at ${lockPath}.`);
+    holderHost;
+    constructor(holderPid, lockPath, holderHost) {
+        super(holderHost !== undefined
+            ? `Another Gezel daemon (host "${holderHost}", pid ${holderPid}) is using this home. If it runs in a container, run commands inside that container with \`docker exec <container> gezel …\` instead of starting a second container on the same volume.`
+            : holderPid > 0
+                ? `Another gezel daemon is already running for this home (pid ${holderPid}). Stop it first with \`gezel stop\`, or use a different GEZEL_HOME.`
+                : `Could not acquire the single-instance lock at ${lockPath}.`);
         this.holderPid = holderPid;
         this.lockPath = lockPath;
+        this.holderHost = holderHost;
         this.name = 'SingleInstanceError';
     }
 }
+const HEARTBEAT_INTERVAL_MS = 10_000;
+const STALE_AFTER_MS = 40_000;
 function defaultIsAlive(pid) {
     try {
         process.kill(pid, 0);
@@ -27,55 +35,177 @@ function defaultIsAlive(pid) {
         return err.code === 'EPERM';
     }
 }
-async function readHolderPid(lockPath) {
+function readTrimmed(path) {
     try {
-        const pid = Number.parseInt((await readFile(lockPath, 'utf8')).trim(), 10);
-        return Number.isFinite(pid) ? pid : null;
+        return readFileSync(path, 'utf8').trim() || undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+export function procStartTicks(pid) {
+    if (process.platform !== 'linux')
+        return undefined;
+    const stat = readTrimmed(`/proc/${pid}/stat`);
+    if (!stat)
+        return undefined;
+    // comm (field 2) may contain spaces and parentheses; fields resume after
+    // the last ')'. starttime is field 22 overall, the 20th after comm.
+    const rest = stat.slice(stat.lastIndexOf(')') + 2).split(' ');
+    return rest[19];
+}
+export function currentLockIdentity() {
+    const linux = process.platform === 'linux';
+    let pidNs;
+    if (linux) {
+        try {
+            pidNs = readlinkSync('/proc/self/ns/pid');
+        }
+        catch {
+            pidNs = undefined;
+        }
+    }
+    return {
+        pid: process.pid,
+        hostname: osHostname(),
+        bootId: linux ? readTrimmed('/proc/sys/kernel/random/boot_id') : undefined,
+        pidNs,
+        startTicks: procStartTicks('self'),
+        instance: `${process.pid}-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 10)}`,
+    };
+}
+/**
+ * The pid stays on the first line so a daemon from before the identity
+ * record (which parses the leading integer) still reads it as held instead
+ * of stale.
+ */
+function serializeIdentity(identity) {
+    return `${identity.pid}\n${JSON.stringify({ v: 1, ...identity })}\n`;
+}
+export function parseLockFile(text) {
+    const [first, second] = text.split('\n');
+    const pid = Number.parseInt((first ?? '').trim(), 10);
+    if (!Number.isFinite(pid))
+        return null;
+    if (!second?.trim())
+        return { pid };
+    try {
+        const record = JSON.parse(second);
+        const text = (value) => (typeof value === 'string' && value ? value : undefined);
+        return {
+            pid,
+            hostname: text(record.hostname),
+            bootId: text(record.bootId),
+            pidNs: text(record.pidNs),
+            startTicks: text(record.startTicks),
+            instance: text(record.instance),
+        };
+    }
+    catch {
+        return { pid };
+    }
+}
+async function readHolder(lockPath) {
+    try {
+        return parseLockFile(await readFile(lockPath, 'utf8'));
     }
     catch {
         return null;
     }
 }
+/**
+ * Whether a pid check against `holder` means anything here. Any field the
+ * holder recorded must match ours; a legacy pid-only record is assumed to be
+ * in our namespace, which is how it was judged before.
+ */
+export function sharesPidNamespace(holder, me) {
+    const same = (a, b) => !a || !b || a === b;
+    return (same(holder.hostname, me.hostname) &&
+        same(holder.bootId, me.bootId) &&
+        same(holder.pidNs, me.pidNs));
+}
+async function lockMtimeMs(lockPath) {
+    try {
+        return (await stat(lockPath)).mtimeMs;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * A holder outside our pid namespace is alive while its heartbeat moves.
+ * A fresh-looking mtime may be a holder that died moments ago (a killed
+ * container restarting onto its own volume), so wait until the heartbeat
+ * either advances (alive) or ages past the stale bound (dead).
+ */
+async function foreignHolderIsAlive(lockPath, opts) {
+    const first = await lockMtimeMs(lockPath);
+    if (first === null)
+        return false;
+    for (;;) {
+        if (opts.now() - first > opts.staleAfterMs)
+            return false;
+        await opts.sleep(1_000);
+        const current = await lockMtimeMs(lockPath);
+        if (current === null)
+            return false;
+        if (current !== first)
+            return true;
+    }
+}
 /**
  * Acquire an exclusive single-instance lock for a gezel home so two daemons
  * can't share one `~/.gezel/` and race its on-disk state (config, sessions,
  * tasks, runtime files). Atomic `O_CREAT|O_EXCL` create of
- * `<runtimeDir>/lock` holding the owner pid; a stale lock (dead holder) is
+ * `<runtimeDir>/lock` holding the owner's identity; a stale lock is
  * reclaimed. Throws {@link SingleInstanceError} when a live daemon holds it.
  *
- * The returned `release()` removes the lock — call it on graceful shutdown.
- * A hard crash leaves a stale lock that the next start reclaims via the
- * pid-liveness check.
+ * While held, the lock file's mtime is touched every few seconds: that
+ * heartbeat is how a daemon in another container (another pid namespace)
+ * is told apart from a dead one.
+ *
+ * The returned `release()` stops the heartbeat and removes the lock — call
+ * it on graceful shutdown. A hard crash leaves a stale lock the next start
+ * reclaims.
  */
 export async function acquireSingleInstanceLock(opts) {
     const isAlive = opts.isAlive ?? defaultIsAlive;
+    const me = opts.identity ?? currentLockIdentity();
+    const startTicksOf = opts.startTicksOf ?? procStartTicks;
+    const now = opts.now ?? Date.now;
+    const sleep = opts.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+    const staleAfterMs = opts.staleAfterMs ?? STALE_AFTER_MS;
     await mkdir(opts.runtimeDir, { recursive: true });
     for (let attempt = 0; attempt < 3; attempt++) {
         try {
             const handle = await open(opts.lockPath, 'wx'); // fails with EEXIST if present
             try {
-                await handle.writeFile(`${process.pid}\n`);
+                await handle.writeFile(serializeIdentity(me));
             }
             finally {
                 await handle.close();
             }
-            return {
-                async release() {
-                    // Only remove the lock if it's still ours — defends against a
-                    // narrow race where another process reclaimed our stale lock.
-                    const holder = await readHolderPid(opts.lockPath);
-                    if (holder === null || holder === process.pid) {
-                        await rm(opts.lockPath, { force: true }).catch(() => { });
-                    }
-                },
-            };
+            return holdLock(opts.lockPath, me, opts.heartbeatIntervalMs ?? HEARTBEAT_INTERVAL_MS);
         }
         catch (err) {
             if (err.code !== 'EEXIST')
                 throw err;
-            const holder = await readHolderPid(opts.lockPath);
-            if (holder !== null && holder !== process.pid && isAlive(holder)) {
-                throw new SingleInstanceError(holder, opts.lockPath);
+            const holder = await readHolder(opts.lockPath);
+            if (holder) {
+                if (!sharesPidNamespace(holder, me)) {
+                    if (await foreignHolderIsAlive(opts.lockPath, { now, sleep, staleAfterMs })) {
+                        throw new SingleInstanceError(holder.pid, opts.lockPath, holder.hostname ?? 'unknown');
+                    }
+                }
+                else if (holder.pid !== me.pid && isAlive(holder.pid)) {
+                    // A recorded start time that no longer matches means the pid was
+                    // reused by an unrelated process after the holder died.
+                    const reused = holder.startTicks !== undefined &&
+                        startTicksOf(holder.pid) !== undefined &&
+                        startTicksOf(holder.pid) !== holder.startTicks;
+                    if (!reused)
+                        throw new SingleInstanceError(holder.pid, opts.lockPath);
+                }
             }
             // Stale (dead holder / our own pid / unreadable) — reclaim and retry.
             await rm(opts.lockPath, { force: true }).catch(() => { });
@@ -83,3 +213,36 @@ export async function acquireSingleInstanceLock(opts) {
     }
     throw new SingleInstanceError(-1, opts.lockPath);
 }
+function holdLock(lockPath, me, intervalMs) {
+    const isOurs = (holder) => holder === null ||
+        (me.instance !== undefined && holder.instance !== undefined
+            ? holder.instance === me.instance
+            : holder.pid === me.pid);
+    let timer = setInterval(() => {
+        void (async () => {
+            const holder = await readHolder(lockPath);
+            if (holder === null || !isOurs(holder)) {
+                // Someone else owns the file now; touching it would keep their lock
+                // looking alive on our behalf.
+                clearInterval(timer);
+                timer = undefined;
+                return;
+            }
+            const at = new Date();
+            await utimes(lockPath, at, at).catch(() => { });
+        })();
+    }, intervalMs);
+    timer.unref?.();
+    return {
+        async release() {
+            if (timer)
+                clearInterval(timer);
+            timer = undefined;
+            // Only remove the lock if it's still ours — defends against a
+            // narrow race where another process reclaimed our stale lock.
+            if (isOurs(await readHolder(lockPath))) {
+                await rm(lockPath, { force: true }).catch(() => { });
+            }
+        },
+    };
+}

package/dist/system/host-memory.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Memory and CPU as this process may actually use them. `os.totalmem()` and
+ * `os.availableParallelism()` describe the host; inside a container started
+ * with `--memory 8g --cpus 4` on a 64 GB, 16-core machine they still say 64
+ * and 16, so a model sized from them gets the container killed by its own
+ * cgroup. Every sizing decision reads these instead.
+ */
+export interface HostLimitsProbe {
+    totalmem: () => number;
+    freemem: () => number;
+    constrainedMemory: () => number | undefined;
+    availableMemory: () => number | undefined;
+    availableParallelism: () => number;
+    /** Every logical CPU the host has, whatever this process may use. */
+    hostCpuCount: () => number;
+    readFile: (path: string) => string | undefined;
+}
+/**
+ * The cgroup memory limit when it is below the host's RAM, else null.
+ * Node reads cgroup v1 and v2; "no limit" comes back as 0 or as a value at
+ * or above physical RAM, depending on the libuv release.
+ */
+export declare function containerMemoryLimitBytes(probe?: HostLimitsProbe): number | null;
+/** RAM this process may use: host RAM, or the container's limit when lower. */
+export declare function totalMemoryBytes(probe?: HostLimitsProbe): number;
+/** Free RAM, never more than the container's limit leaves. */
+export declare function freeMemoryBytes(probe?: HostLimitsProbe): number;
+/**
+ * Caps a host-wide free-memory reading (`MemAvailable`, `vm_stat`) to what
+ * the container still has. Unchanged outside a container.
+ */
+export declare function capToContainer(hostFreeBytes: number, probe?: HostLimitsProbe): number;
+/**
+ * CPUs this process may keep busy: the scheduler's CPU set, further capped
+ * by a cgroup v2 `cpu.max` quota (or v1 `cfs_quota_us`) rounded up.
+ */
+export declare function availableCpuCount(probe?: HostLimitsProbe): number;
+export declare function cgroupCpuQuota(probe?: HostLimitsProbe): number | null;
+/**
+ * The CPUs a container (a `--cpus` quota or a `--cpuset-cpus` set) leaves this
+ * process when that is fewer than the host has, else null. Engines that size
+ * their own thread pool from the host's cores, as llama.cpp does, oversubscribe
+ * such a limit badly: 32 threads under a 4-CPU quota spend most of each period
+ * throttled. Measured in a 4-CPU container: a 0.8B model decoded at 3.7 t/s.
+ */
+export declare function containerCpuLimit(probe?: HostLimitsProbe): number | null;