@mneme-ai/core 2.21.6 → 2.21.7

package/dist/upgrade_visibility/exit_log.js

@@ -0,0 +1,128 @@
+/**
+ * v2.21.7 — UPGRADE VISIBILITY · EXIT LOG.
+ *
+ * HMAC-chained log of every upgrade attempt + its exit code. Closes
+ * the "silent upgrade fail" concern from the v2.21.6 AI-agent audit:
+ *
+ *   "exit-4294963214 = mneme upgrade ตัวเองพังเงียบๆ แล้ว pulse ก็ยังบอกว่า
+ *    auto-upgrade is one tool call away."
+ *
+ *   - Append-only log at `.mneme/upgrade/log.jsonl`.
+ *   - Every entry: ts + version-before/after + npm exit code + reason +
+ *     prev sig (chain-linked, tamper-evident).
+ *   - `verifyChain()` audits integrity.
+ *   - `lastFailure()` surfaces the most recent non-zero exit so the
+ *     pulse can mention "previous upgrade attempt failed (exit X)" —
+ *     no more silent fails.
+ */
+import { existsSync, readFileSync, appendFileSync, mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { createHmac, randomBytes } from "node:crypto";
+const DIR = ".mneme/upgrade";
+const LOG = "log.jsonl";
+const KEY = "upgrade.key";
+function dir(repoRoot) {
+    const d = join(repoRoot, DIR);
+    if (!existsSync(d))
+        mkdirSync(d, { recursive: true });
+    return d;
+}
+function key(repoRoot) {
+    const p = join(dir(repoRoot), KEY);
+    if (existsSync(p))
+        return readFileSync(p, "utf8").trim();
+    const k = randomBytes(32).toString("base64url");
+    writeFileSync(p, k, "utf8");
+    return k;
+}
+function sign(payload, k) {
+    return createHmac("sha256", k).update(payload).digest("base64url").slice(0, 22);
+}
+function logPath(repoRoot) { return join(dir(repoRoot), LOG); }
+export function recordUpgrade(repoRoot, opts) {
+    const k = key(repoRoot);
+    const ts = new Date().toISOString();
+    const id = "up_" + randomBytes(4).toString("hex");
+    const existing = listUpgrades(repoRoot);
+    const prev = existing.length > 0 ? existing[existing.length - 1].sig : "genesis";
+    const canonical = `${ts}|${opts.versionBefore}|${opts.versionAfter ?? ""}|${opts.exitCode}|${opts.reason}|${prev}`;
+    const sig = sign(canonical, k);
+    const entry = {
+        v: 1, id, ts,
+        versionBefore: opts.versionBefore,
+        versionAfter: opts.versionAfter,
+        exitCode: opts.exitCode,
+        reason: opts.reason,
+        prev, sig,
+        ...(opts.command ? { command: opts.command } : {}),
+        ...(opts.stderrTail ? { stderrTail: opts.stderrTail } : {}),
+    };
+    appendFileSync(logPath(repoRoot), JSON.stringify(entry) + "\n", "utf8");
+    return entry;
+}
+export function listUpgrades(repoRoot) {
+    const p = logPath(repoRoot);
+    if (!existsSync(p))
+        return [];
+    try {
+        return readFileSync(p, "utf8").trim().split("\n").map((l) => { try {
+            return JSON.parse(l);
+        }
+        catch {
+            return null;
+        } }).filter((r) => !!r);
+    }
+    catch {
+        return [];
+    }
+}
+export function lastFailure(repoRoot) {
+    const all = listUpgrades(repoRoot);
+    for (let i = all.length - 1; i >= 0; i--) {
+        if (all[i].exitCode !== 0)
+            return all[i];
+    }
+    return null;
+}
+export function lastSuccess(repoRoot) {
+    const all = listUpgrades(repoRoot);
+    for (let i = all.length - 1; i >= 0; i--) {
+        if (all[i].exitCode === 0)
+            return all[i];
+    }
+    return null;
+}
+export function verifyChain(repoRoot) {
+    const all = listUpgrades(repoRoot);
+    if (all.length === 0)
+        return { ok: true };
+    const k = key(repoRoot);
+    let lastSig = "genesis";
+    for (let i = 0; i < all.length; i++) {
+        const e = all[i];
+        if (e.prev !== lastSig)
+            return { ok: false, brokenAt: i, reason: `entry ${i} prev=${e.prev.slice(0, 8)} expected ${lastSig.slice(0, 8)}` };
+        const canonical = `${e.ts}|${e.versionBefore}|${e.versionAfter ?? ""}|${e.exitCode}|${e.reason}|${e.prev}`;
+        if (sign(canonical, k) !== e.sig)
+            return { ok: false, brokenAt: i, reason: `entry ${i} signature mismatch` };
+        lastSig = e.sig;
+    }
+    return { ok: true };
+}
+export function formatUpgradeLog(entries) {
+    if (entries.length === 0)
+        return "📜 UPGRADE LOG — empty";
+    const lines = [`📜 UPGRADE LOG — ${entries.length} entries`, ""];
+    for (const e of entries.slice(-20)) {
+        const badge = e.exitCode === 0 ? "✓" : "✗";
+        lines.push(`  ${badge} ${e.ts}  v${e.versionBefore} → ${e.versionAfter ?? "(failed)"}  exit=${e.exitCode}  ${e.reason}`);
+        if (e.stderrTail && e.exitCode !== 0) {
+            const tail = e.stderrTail.split("\n").slice(-2).join(" / ").slice(0, 200);
+            lines.push(`     stderr: ${tail}`);
+        }
+    }
+    if (entries.length > 20)
+        lines.push(`  (showing last 20 of ${entries.length})`);
+    return lines.join("\n");
+}
+//# sourceMappingURL=exit_log.js.map

package/dist/upgrade_visibility/exit_log.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"exit_log.js","sourceRoot":"","sources":["../../src/upgrade_visibility/exit_log.ts"],"names":[],"mappings":"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"}

package/dist/upgrade_visibility/index.d.ts

@@ -0,0 +1,45 @@
+/**
+ * v2.21.7 — UPGRADE VISIBILITY.
+ *
+ * Closes the two deferred concerns from the v2.21.6 AI-agent audit:
+ *
+ *   5. "Silent upgrade fail (exit 4294963214) swallowed."
+ *       → exit_log.ts: HMAC-chained record of every attempt + exit
+ *         code; `lastFailure()` surfaces the most recent non-zero
+ *         exit. No more silent fails.
+ *
+ *   6. "Auto-upgrade race during user's npm install."
+ *       → npm_detector.ts + mutex.ts: ancestor-chain detection blocks
+ *         self-upgrade when an `npm install` is alive in the parent
+ *         tree; file-lock mutex prevents two Mneme processes from
+ *         running `npm install` at the same time.
+ *
+ * Composes:
+ *
+ *     const safety = isUpgradeSafeRightNow();
+ *     if (!safety.safe) return recordUpgrade(repoRoot, {
+ *       versionBefore: cur, versionAfter: null, exitCode: -1,
+ *       reason: `aborted: ${safety.reason}`,
+ *     });
+ *     const lock = acquireLock(repoRoot, { reason: "auto-upgrade" });
+ *     if (!lock.ok) return recordUpgrade(repoRoot, {...exitCode: -2, reason: lock.reason!});
+ *     // ... run `npm install -g mneme-ai` ...
+ *     recordUpgrade(repoRoot, { versionBefore, versionAfter, exitCode, ... });
+ *     releaseLock(repoRoot);
+ */
+export { acquireLock, releaseLock, readLock, isLocked, formatLock, type LockState, type AcquireResult, type AcquireOptions, } from "./mutex.js";
+export { recordUpgrade, listUpgrades, lastFailure, lastSuccess, verifyChain, formatUpgradeLog, type UpgradeEntry, type RecordUpgradeOptions, } from "./exit_log.js";
+export { isInsideNpmInstall, isUpgradeSafeRightNow, formatDetection, type DetectionResult, } from "./npm_detector.js";
+import { lastFailure, lastSuccess } from "./exit_log.js";
+/** One-shot doctor: is it safe to attempt an upgrade right now? Pure
+ *  read-only — never mutates state. */
+export interface UpgradeDoctorReport {
+    ready: boolean;
+    reasons: string[];
+    recentFailure: ReturnType<typeof lastFailure>;
+    recentSuccess: ReturnType<typeof lastSuccess>;
+    attempts: number;
+}
+export declare function upgradeDoctor(repoRoot: string): UpgradeDoctorReport;
+export declare function formatDoctor(r: UpgradeDoctorReport): string;
+//# sourceMappingURL=index.d.ts.map

package/dist/upgrade_visibility/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/upgrade_visibility/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,OAAO,EACL,WAAW,EAAE,WAAW,EAAE,QAAQ,EAAE,QAAQ,EAAE,UAAU,EACxD,KAAK,SAAS,EAAE,KAAK,aAAa,EAAE,KAAK,cAAc,GACxD,MAAM,YAAY,CAAC;AAEpB,OAAO,EACL,aAAa,EAAE,YAAY,EAAE,WAAW,EAAE,WAAW,EAAE,WAAW,EAAE,gBAAgB,EACpF,KAAK,YAAY,EAAE,KAAK,oBAAoB,GAC7C,MAAM,eAAe,CAAC;AAEvB,OAAO,EACL,kBAAkB,EAAE,qBAAqB,EAAE,eAAe,EAC1D,KAAK,eAAe,GACrB,MAAM,mBAAmB,CAAC;AAI3B,OAAO,EAAE,WAAW,EAAE,WAAW,EAAgB,MAAM,eAAe,CAAC;AAEvE;uCACuC;AACvC,MAAM,WAAW,mBAAmB;IAClC,KAAK,EAAE,OAAO,CAAC;IACf,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,aAAa,EAAE,UAAU,CAAC,OAAO,WAAW,CAAC,CAAC;IAC9C,aAAa,EAAE,UAAU,CAAC,OAAO,WAAW,CAAC,CAAC;IAC9C,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,wBAAgB,aAAa,CAAC,QAAQ,EAAE,MAAM,GAAG,mBAAmB,CAiBnE;AAED,wBAAgB,YAAY,CAAC,CAAC,EAAE,mBAAmB,GAAG,MAAM,CAsB3D"}

package/dist/upgrade_visibility/index.js

@@ -0,0 +1,83 @@
+/**
+ * v2.21.7 — UPGRADE VISIBILITY.
+ *
+ * Closes the two deferred concerns from the v2.21.6 AI-agent audit:
+ *
+ *   5. "Silent upgrade fail (exit 4294963214) swallowed."
+ *       → exit_log.ts: HMAC-chained record of every attempt + exit
+ *         code; `lastFailure()` surfaces the most recent non-zero
+ *         exit. No more silent fails.
+ *
+ *   6. "Auto-upgrade race during user's npm install."
+ *       → npm_detector.ts + mutex.ts: ancestor-chain detection blocks
+ *         self-upgrade when an `npm install` is alive in the parent
+ *         tree; file-lock mutex prevents two Mneme processes from
+ *         running `npm install` at the same time.
+ *
+ * Composes:
+ *
+ *     const safety = isUpgradeSafeRightNow();
+ *     if (!safety.safe) return recordUpgrade(repoRoot, {
+ *       versionBefore: cur, versionAfter: null, exitCode: -1,
+ *       reason: `aborted: ${safety.reason}`,
+ *     });
+ *     const lock = acquireLock(repoRoot, { reason: "auto-upgrade" });
+ *     if (!lock.ok) return recordUpgrade(repoRoot, {...exitCode: -2, reason: lock.reason!});
+ *     // ... run `npm install -g mneme-ai` ...
+ *     recordUpgrade(repoRoot, { versionBefore, versionAfter, exitCode, ... });
+ *     releaseLock(repoRoot);
+ */
+export { acquireLock, releaseLock, readLock, isLocked, formatLock, } from "./mutex.js";
+export { recordUpgrade, listUpgrades, lastFailure, lastSuccess, verifyChain, formatUpgradeLog, } from "./exit_log.js";
+export { isInsideNpmInstall, isUpgradeSafeRightNow, formatDetection, } from "./npm_detector.js";
+import { isUpgradeSafeRightNow } from "./npm_detector.js";
+import { isLocked, readLock } from "./mutex.js";
+import { lastFailure, lastSuccess, listUpgrades } from "./exit_log.js";
+export function upgradeDoctor(repoRoot) {
+    const reasons = [];
+    let ready = true;
+    const safety = isUpgradeSafeRightNow();
+    if (!safety.safe) {
+        ready = false;
+        reasons.push(safety.reason);
+    }
+    if (isLocked(repoRoot)) {
+        ready = false;
+        const lk = readLock(repoRoot);
+        reasons.push(`upgrade lock active: pid=${lk?.pid} reason="${lk?.reason}"`);
+    }
+    return {
+        ready,
+        reasons,
+        recentFailure: lastFailure(repoRoot),
+        recentSuccess: lastSuccess(repoRoot),
+        attempts: listUpgrades(repoRoot).length,
+    };
+}
+export function formatDoctor(r) {
+    const lines = [];
+    lines.push(`🩺 UPGRADE DOCTOR — ${r.ready ? "✓ ready" : "✗ blocked"}`);
+    lines.push("");
+    if (r.reasons.length > 0) {
+        lines.push("  Blockers:");
+        for (const reason of r.reasons)
+            lines.push(`    - ${reason}`);
+        lines.push("");
+    }
+    lines.push(`  Attempts logged:  ${r.attempts}`);
+    if (r.recentFailure) {
+        lines.push(`  Last failure:     ${r.recentFailure.ts}  exit=${r.recentFailure.exitCode}`);
+        lines.push(`                    reason: ${r.recentFailure.reason}`);
+    }
+    else {
+        lines.push("  Last failure:     (none recorded)");
+    }
+    if (r.recentSuccess) {
+        lines.push(`  Last success:     ${r.recentSuccess.ts}  v${r.recentSuccess.versionBefore} → v${r.recentSuccess.versionAfter}`);
+    }
+    else {
+        lines.push("  Last success:     (none recorded)");
+    }
+    return lines.join("\n");
+}
+//# sourceMappingURL=index.js.map

package/dist/upgrade_visibility/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/upgrade_visibility/index.ts"],"names":[],"mappings":"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"}

package/dist/upgrade_visibility/mutex.d.ts

@@ -0,0 +1,44 @@
+/**
+ * v2.21.7 — UPGRADE VISIBILITY · MUTEX.
+ *
+ * File-lock-based mutex that prevents two Mneme operations from
+ * running `npm install` concurrently. Closes the race condition
+ * surfaced in the v2.21.6 AI-agent audit:
+ *
+ *   "auto-upgrade triggers in parallel with the user's npm install
+ *    on session start; npm install fails because the daemon holds
+ *    DLL handles."
+ *
+ *   - Lock file at `.mneme/upgrade/upgrade.lock` (per-repo).
+ *   - Lock contains owner PID + ts + reason; stale-lock detection
+ *     when owner PID is no longer alive (process check) OR lock is
+ *     older than maxAgeMs (default 10 min — generous for slow CI).
+ *   - acquire() returns ok/false; never blocks.
+ */
+export interface LockState {
+    pid: number;
+    ts: string;
+    reason: string;
+    /** Optional: hostname for cross-machine awareness. */
+    host?: string;
+}
+export interface AcquireResult {
+    ok: boolean;
+    /** When ok=false, the existing lock that blocks acquisition. */
+    heldBy?: LockState;
+    reason?: string;
+}
+export interface AcquireOptions {
+    reason: string;
+    /** Stale-lock threshold; default 10 minutes. */
+    maxAgeMs?: number;
+}
+export declare function acquireLock(repoRoot: string, opts: AcquireOptions): AcquireResult;
+export declare function releaseLock(repoRoot: string): {
+    ok: boolean;
+    reason?: string;
+};
+export declare function readLock(repoRoot: string): LockState | null;
+export declare function isLocked(repoRoot: string, maxAgeMs?: number): boolean;
+export declare function formatLock(state: LockState | null): string;
+//# sourceMappingURL=mutex.d.ts.map

package/dist/upgrade_visibility/mutex.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mutex.d.ts","sourceRoot":"","sources":["../../src/upgrade_visibility/mutex.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AASH,MAAM,WAAW,SAAS;IACxB,GAAG,EAAE,MAAM,CAAC;IACZ,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,MAAM,CAAC;IACf,sDAAsD;IACtD,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAqBD,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAE,OAAO,CAAC;IACZ,gEAAgE;IAChE,MAAM,CAAC,EAAE,SAAS,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,MAAM,CAAC;IACf,gDAAgD;IAChD,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,wBAAgB,WAAW,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,cAAc,GAAG,aAAa,CAuBjF;AAED,wBAAgB,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG;IAAE,EAAE,EAAE,OAAO,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,CAa9E;AAED,wBAAgB,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,CAI3D;AAED,wBAAgB,QAAQ,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,SAAqB,GAAG,OAAO,CAMjF;AAED,wBAAgB,UAAU,CAAC,KAAK,EAAE,SAAS,GAAG,IAAI,GAAG,MAAM,CAG1D"}

package/dist/upgrade_visibility/mutex.js

@@ -0,0 +1,114 @@
+/**
+ * v2.21.7 — UPGRADE VISIBILITY · MUTEX.
+ *
+ * File-lock-based mutex that prevents two Mneme operations from
+ * running `npm install` concurrently. Closes the race condition
+ * surfaced in the v2.21.6 AI-agent audit:
+ *
+ *   "auto-upgrade triggers in parallel with the user's npm install
+ *    on session start; npm install fails because the daemon holds
+ *    DLL handles."
+ *
+ *   - Lock file at `.mneme/upgrade/upgrade.lock` (per-repo).
+ *   - Lock contains owner PID + ts + reason; stale-lock detection
+ *     when owner PID is no longer alive (process check) OR lock is
+ *     older than maxAgeMs (default 10 min — generous for slow CI).
+ *   - acquire() returns ok/false; never blocks.
+ */
+import { existsSync, readFileSync, writeFileSync, unlinkSync, mkdirSync } from "node:fs";
+import { join } from "node:path";
+const DIR = ".mneme/upgrade";
+const LOCK = "upgrade.lock";
+const DEFAULT_MAX_AGE_MS = 10 * 60 * 1000;
+function dir(repoRoot) {
+    const d = join(repoRoot, DIR);
+    if (!existsSync(d))
+        mkdirSync(d, { recursive: true });
+    return d;
+}
+function lockPath(repoRoot) { return join(dir(repoRoot), LOCK); }
+function pidAlive(pid) {
+    if (pid <= 0)
+        return false;
+    try {
+        // signal 0 = liveness probe; throws on dead process.
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export function acquireLock(repoRoot, opts) {
+    const p = lockPath(repoRoot);
+    if (existsSync(p)) {
+        let existing = null;
+        try {
+            existing = JSON.parse(readFileSync(p, "utf8"));
+        }
+        catch { /* corrupt */ }
+        if (existing) {
+            const alive = pidAlive(existing.pid);
+            const age = Date.now() - Date.parse(existing.ts);
+            const stale = !alive || age > (opts.maxAgeMs ?? DEFAULT_MAX_AGE_MS);
+            if (!stale) {
+                return { ok: false, heldBy: existing, reason: `lock held by pid=${existing.pid} since ${existing.ts}: ${existing.reason}` };
+            }
+            // stale → take it
+        }
+    }
+    const state = {
+        pid: process.pid,
+        ts: new Date().toISOString(),
+        reason: opts.reason,
+        host: (() => { try {
+            return require("node:os").hostname();
+        }
+        catch {
+            return undefined;
+        } })(),
+    };
+    writeFileSync(p, JSON.stringify(state, null, 2), "utf8");
+    return { ok: true };
+}
+export function releaseLock(repoRoot) {
+    const p = lockPath(repoRoot);
+    if (!existsSync(p))
+        return { ok: true };
+    try {
+        const cur = JSON.parse(readFileSync(p, "utf8"));
+        if (cur.pid !== process.pid) {
+            return { ok: false, reason: `cannot release lock held by another pid=${cur.pid}` };
+        }
+        unlinkSync(p);
+        return { ok: true };
+    }
+    catch (e) {
+        return { ok: false, reason: `failed to release: ${e.message}` };
+    }
+}
+export function readLock(repoRoot) {
+    const p = lockPath(repoRoot);
+    if (!existsSync(p))
+        return null;
+    try {
+        return JSON.parse(readFileSync(p, "utf8"));
+    }
+    catch {
+        return null;
+    }
+}
+export function isLocked(repoRoot, maxAgeMs = DEFAULT_MAX_AGE_MS) {
+    const cur = readLock(repoRoot);
+    if (!cur)
+        return false;
+    const alive = pidAlive(cur.pid);
+    const age = Date.now() - Date.parse(cur.ts);
+    return alive && age <= maxAgeMs;
+}
+export function formatLock(state) {
+    if (!state)
+        return "✓ no upgrade in progress";
+    return `🔒 upgrade in progress\n  pid:    ${state.pid}\n  host:   ${state.host ?? "(unknown)"}\n  since:  ${state.ts}\n  reason: ${state.reason}`;
+}
+//# sourceMappingURL=mutex.js.map

package/dist/upgrade_visibility/mutex.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mutex.js","sourceRoot":"","sources":["../../src/upgrade_visibility/mutex.ts"],"names":[],"mappings":"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"}

package/dist/upgrade_visibility/npm_detector.d.ts

@@ -0,0 +1,40 @@
+/**
+ * v2.21.7 — UPGRADE VISIBILITY · NPM INSTALL DETECTOR.
+ *
+ * Detects whether the current process tree is inside / parented by a
+ * live `npm install` (or similar package-manager) operation. Used as
+ * a SAFETY GATE before auto-upgrade fires — closes the race condition
+ * the v2.21.6 AI-agent audit flagged:
+ *
+ *   "Pulse hook trigger upgrade ขนานกับที่ผมรัน npm install"
+ *
+ * The detection is heuristic + platform-aware:
+ *
+ *   - Windows: check parent process via `wmic` / `tasklist` lookup
+ *     for npm.exe / yarn.exe / pnpm.exe in the ancestor chain.
+ *   - POSIX:   walk `/proc/<ppid>/comm` upward looking for the same.
+ *
+ * On EITHER platform, if detection cannot complete (e.g. wmic
+ * missing), we fail OPEN — caller should treat unknown as "do not
+ * auto-upgrade right now". Better to skip a self-upgrade than to
+ * collide with the user's package install.
+ */
+export interface DetectionResult {
+    /** True iff we believe an `npm install` is active in the ancestor chain. */
+    detected: boolean;
+    /** The detected command name, when available. */
+    evidence?: string;
+    /** When detection couldn't be performed, this surfaces the reason. */
+    unknownReason?: string;
+}
+/** Whether an npm-like operation owns the ancestor chain.  Caller
+ *  should treat any positive result as "do NOT auto-upgrade". */
+export declare function isInsideNpmInstall(): DetectionResult;
+/** Safety predicate used by callers that want to gate an auto-upgrade.
+ *  Pass a hint string for the log. */
+export declare function isUpgradeSafeRightNow(): {
+    safe: boolean;
+    reason: string;
+};
+export declare function formatDetection(r: DetectionResult): string;
+//# sourceMappingURL=npm_detector.d.ts.map

package/dist/upgrade_visibility/npm_detector.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"npm_detector.d.ts","sourceRoot":"","sources":["../../src/upgrade_visibility/npm_detector.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAIH,MAAM,WAAW,eAAe;IAC9B,4EAA4E;IAC5E,QAAQ,EAAE,OAAO,CAAC;IAClB,iDAAiD;IACjD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,sEAAsE;IACtE,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AA6DD;iEACiE;AACjE,wBAAgB,kBAAkB,IAAI,eAAe,CAGpD;AAED;sCACsC;AACtC,wBAAgB,qBAAqB,IAAI;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CASzE;AAED,wBAAgB,eAAe,CAAC,CAAC,EAAE,eAAe,GAAG,MAAM,CAI1D"}

package/dist/upgrade_visibility/npm_detector.js

@@ -0,0 +1,118 @@
+/**
+ * v2.21.7 — UPGRADE VISIBILITY · NPM INSTALL DETECTOR.
+ *
+ * Detects whether the current process tree is inside / parented by a
+ * live `npm install` (or similar package-manager) operation. Used as
+ * a SAFETY GATE before auto-upgrade fires — closes the race condition
+ * the v2.21.6 AI-agent audit flagged:
+ *
+ *   "Pulse hook trigger upgrade ขนานกับที่ผมรัน npm install"
+ *
+ * The detection is heuristic + platform-aware:
+ *
+ *   - Windows: check parent process via `wmic` / `tasklist` lookup
+ *     for npm.exe / yarn.exe / pnpm.exe in the ancestor chain.
+ *   - POSIX:   walk `/proc/<ppid>/comm` upward looking for the same.
+ *
+ * On EITHER platform, if detection cannot complete (e.g. wmic
+ * missing), we fail OPEN — caller should treat unknown as "do not
+ * auto-upgrade right now". Better to skip a self-upgrade than to
+ * collide with the user's package install.
+ */
+import { execSync } from "node:child_process";
+const NPM_LIKE = new Set(["npm", "npm-cli.js", "yarn", "pnpm", "bun", "npx"]);
+function detectWindows() {
+    // wmic is being deprecated on newer Win11 builds; fall back to PowerShell Get-CimInstance.
+    // Both ways: walk parent chain up to 8 levels looking for an npm-like command.
+    try {
+        const out = execSync('wmic process get ProcessId,ParentProcessId,Name /FORMAT:CSV', { encoding: "utf8", timeout: 3000 }).toString();
+        const rows = out.split(/\r?\n/).slice(1)
+            .map((l) => l.split(",").map((s) => s.trim()))
+            .filter((r) => r.length >= 4);
+        const byPid = new Map();
+        for (const r of rows) {
+            const [, name, ppid, pid] = r;
+            const pidN = parseInt(pid, 10);
+            const ppidN = parseInt(ppid, 10);
+            if (!Number.isFinite(pidN))
+                continue;
+            byPid.set(pidN, { name: (name ?? "").toLowerCase(), ppid: ppidN });
+        }
+        let cur = process.ppid;
+        for (let i = 0; i < 8 && byPid.has(cur); i++) {
+            const node = byPid.get(cur);
+            const stem = node.name.replace(/\.exe$/i, "");
+            if (NPM_LIKE.has(stem))
+                return { detected: true, evidence: node.name };
+            cur = node.ppid;
+        }
+        return { detected: false };
+    }
+    catch (e) {
+        return { detected: false, unknownReason: `wmic probe failed: ${e.message.slice(0, 80)}` };
+    }
+}
+function detectPosix() {
+    try {
+        let cur = process.ppid;
+        for (let i = 0; i < 8 && cur > 0; i++) {
+            const commPath = `/proc/${cur}/comm`;
+            let comm;
+            try {
+                comm = require("node:fs").readFileSync(commPath, "utf8").trim();
+            }
+            catch {
+                return { detected: false };
+            }
+            const stem = comm.toLowerCase();
+            if (NPM_LIKE.has(stem))
+                return { detected: true, evidence: comm };
+            const statPath = `/proc/${cur}/stat`;
+            let parent;
+            try {
+                const stat = require("node:fs").readFileSync(statPath, "utf8");
+                // /proc/PID/stat format: pid (comm) state ppid ...
+                // comm can contain spaces; split from the LAST ')' to be safe.
+                const after = stat.slice(stat.lastIndexOf(")") + 1).trim().split(/\s+/);
+                parent = parseInt(after[1], 10);
+            }
+            catch {
+                return { detected: false };
+            }
+            if (!Number.isFinite(parent) || parent <= 1)
+                break;
+            cur = parent;
+        }
+        return { detected: false };
+    }
+    catch (e) {
+        return { detected: false, unknownReason: `proc probe failed: ${e.message.slice(0, 80)}` };
+    }
+}
+/** Whether an npm-like operation owns the ancestor chain.  Caller
+ *  should treat any positive result as "do NOT auto-upgrade". */
+export function isInsideNpmInstall() {
+    if (process.platform === "win32")
+        return detectWindows();
+    return detectPosix();
+}
+/** Safety predicate used by callers that want to gate an auto-upgrade.
+ *  Pass a hint string for the log. */
+export function isUpgradeSafeRightNow() {
+    const r = isInsideNpmInstall();
+    if (r.detected) {
+        return { safe: false, reason: `package manager active in ancestor chain (${r.evidence}); skipping to avoid race` };
+    }
+    if (r.unknownReason) {
+        return { safe: false, reason: `cannot verify package-manager state; skipping out of caution (${r.unknownReason})` };
+    }
+    return { safe: true, reason: "no package manager detected in ancestor chain" };
+}
+export function formatDetection(r) {
+    if (r.detected)
+        return `⚠ npm-like process detected in ancestor chain: ${r.evidence}`;
+    if (r.unknownReason)
+        return `· detection inconclusive: ${r.unknownReason}`;
+    return "✓ no package manager active in ancestor chain";
+}
+//# sourceMappingURL=npm_detector.js.map

package/dist/upgrade_visibility/npm_detector.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"npm_detector.js","sourceRoot":"","sources":["../../src/upgrade_visibility/npm_detector.ts"],"names":[],"mappings":"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"}

package/dist/upgrade_visibility/upgrade_visibility.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=upgrade_visibility.test.d.ts.map

package/dist/upgrade_visibility/upgrade_visibility.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"upgrade_visibility.test.d.ts","sourceRoot":"","sources":["../../src/upgrade_visibility/upgrade_visibility.test.ts"],"names":[],"mappings":""}