@automagik/omni 2.260508.1 → 2.260508.3

package/dist/commands/doctor.d.ts

@@ -15,8 +15,9 @@
  *   5. orphaned-data-dirs      — `.pgserve-data/` directories under cwd
  *   6. version-match           — CLI version vs. /api/v2/health `version` field
  *   7. pm2-status              — omni-api and omni-nats both `online` in pm2
- *   8. pm2-max-restarts        — omni-api has bounded restarts (not 0 or >= 1000)
+ *   8. pm2-max-restarts        — omni-api + omni-nats have bounded restarts
  *   9. pm2-logrotate-installed — pm2-logrotate module configured correctly
+ *  10. port-canonical-owner    — canonical ports owned by pm2-managed PIDs
  *
  * Each check returns OK / WARN / FAIL with a one-line detail. `--fix`
  * attempts repair for checks with a known repair path. The fix flow
@@ -35,6 +36,12 @@
  *                              so the hardened `--max-restarts` flag takes effect.
  *   - pm2-logrotate-installed: Re-run `pm2 install pm2-logrotate` + the four
  *                              `pm2 set pm2-logrotate:*` commands.
+ *   - port-canonical-owner:    SIGTERM (then SIGKILL) the non-pm2 squatter
+ *                              holding 4222 / api port, then `pm2 restart`
+ *                              the managed entry. Refuses to act when the
+ *                              squatter PID matches another pm2-managed entry.
+ *   - pm2-status:              Reconcile port ownership (above) then `pm2
+ *                              restart` any non-online managed process.
  */
 import { Command } from 'commander';
 import { type Config, type ServerConfig } from '../config.js';
@@ -42,7 +49,7 @@ import { type EmbeddedDumpResult } from '../lib/canonical-pgserve.js';
 /** Severity levels reported by each check. */
 export type CheckLevel = 'OK' | 'WARN' | 'FAIL';
 /** Identifier used in tests and --json output. */
-export type CheckId = 'pm2-env-drift' | 'cli-key-valid' | 'pgserve-reachable' | 'omni-db-exists' | 'orphaned-data-dirs' | 'version-match' | 'pm2-status' | 'pm2-max-restarts' | 'pm2-logrotate-installed' | 'cli-signing-key-for-locked-instances' | 'pgserve-canonical';
+export type CheckId = 'pm2-env-drift' | 'cli-key-valid' | 'pgserve-reachable' | 'omni-db-exists' | 'orphaned-data-dirs' | 'version-match' | 'pm2-status' | 'pm2-max-restarts' | 'pm2-logrotate-installed' | 'cli-signing-key-for-locked-instances' | 'pgserve-canonical' | 'port-canonical-owner';
 export interface CheckResult {
     id: CheckId;
     level: CheckLevel;
@@ -77,6 +84,8 @@ export interface DoctorOptions {
 interface Pm2Entry {
     name?: string;
     pm_id?: number;
+    /** Top-level OS PID of the spawned child. Used by port-canonical-owner. */
+    pid?: number;
     pm2_env?: {
         status?: string;
         env?: Record<string, string | undefined>;
@@ -174,6 +183,20 @@ export interface DoctorDeps {
      * to ~/.omni/config.json.
      */
     saveServerConfig: (partial: Partial<ServerConfig>) => void;
+    /**
+     * Resolve the OS PID currently bound to a TCP port (LISTEN). Returns
+     * null when nothing is listening, when the lookup fails, or when the
+     * platform tool (`ss`) is unavailable. Used by the port-canonical-owner
+     * check + fixer to detect non-pm2 squatters on canonical ports.
+     */
+    findPortOwner: (port: number) => Promise<number | null>;
+    /**
+     * Send a signal to a PID. Returns true when the signal was delivered,
+     * false on EPERM/ESRCH/etc. We never throw — callers treat falsy as
+     * "could not signal, fall through to next strategy". Tests stub this
+     * so they don't actually kill anything.
+     */
+    processKill: (pid: number, signal: 'SIGTERM' | 'SIGKILL') => boolean;
 }
 /**
  * Run all checks and optionally apply fixes. Returns a structured

package/dist/commands/doctor.d.ts.map

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

package/dist/index.js

@@ -123990,7 +123990,7 @@ import { fileURLToPath } from "url";
 // package.json
 var package_default = {
   name: "@automagik/omni",
-  version: "2.260508.1",
+  version: "2.260508.3",
   description: "LLM-optimized CLI for Omni",
   type: "module",
   bin: {
@@ -129027,7 +129027,31 @@ function productionDeps() {
     dumpEmbeddedDb,
     restoreSnapshotToCanonical,
     getCanonicalPgserveDataDir,
-    saveServerConfig
+    saveServerConfig,
+    findPortOwner: async (port) => {
+      try {
+        const proc = Bun.spawn(["ss", "-tlnpH", `sport = :${port}`], {
+          stdout: "pipe",
+          stderr: "ignore"
+        });
+        const stdout = await new Response(proc.stdout).text();
+        const exitCode = await proc.exited;
+        if (exitCode !== 0)
+          return null;
+        const match = stdout.match(/pid=(\d+)/);
+        return match ? Number.parseInt(match[1], 10) : null;
+      } catch {
+        return null;
+      }
+    },
+    processKill: (pid, signal) => {
+      try {
+        process.kill(pid, signal);
+        return true;
+      } catch {
+        return false;
+      }
+    }
   };
 }
 function scanForOrphans(dir, acc, depth, maxDepth = 4) {
@@ -129162,36 +129186,41 @@ async function checkPm2MaxRestarts(deps) {
   if (!processes) {
     return { id: "pm2-max-restarts", level: "WARN", detail: "pm2 not reachable" };
   }
-  const apiEntry = processes.find((p) => p.name === PM2_PROCESSES.api);
-  if (!apiEntry) {
-    return { id: "pm2-max-restarts", level: "WARN", detail: `${PM2_PROCESSES.api} not found in pm2` };
-  }
-  const maxRestarts = apiEntry.pm2_env?.max_restarts;
-  if (typeof maxRestarts !== "number") {
-    return {
-      id: "pm2-max-restarts",
-      level: "FAIL",
-      detail: `${PM2_PROCESSES.api} has no max_restarts set \u2014 crash loops are unbounded`
-    };
-  }
-  if (maxRestarts === 0 || maxRestarts >= 1000) {
-    return {
-      id: "pm2-max-restarts",
-      level: "FAIL",
-      detail: `${PM2_PROCESSES.api} max_restarts=${maxRestarts} \u2014 crash loops are effectively unbounded`
-    };
+  const issues = [];
+  let hasFail = false;
+  const targets = [PM2_PROCESSES.api, PM2_PROCESSES.nats];
+  for (const name of targets) {
+    const entry = processes.find((p) => p.name === name);
+    if (!entry) {
+      issues.push(`${name} not found in pm2`);
+      continue;
+    }
+    const v = entry.pm2_env?.max_restarts;
+    if (typeof v !== "number") {
+      hasFail = true;
+      issues.push(`${name} has no max_restarts set \u2014 crash loops are unbounded`);
+      continue;
+    }
+    if (v === 0 || v >= 1000) {
+      hasFail = true;
+      issues.push(`${name} max_restarts=${v} \u2014 crash loops are effectively unbounded`);
+      continue;
+    }
+    if (!(v >= 5 && v <= 50)) {
+      issues.push(`${name} max_restarts=${v} \u2014 expected 5..50`);
+    }
   }
-  if (maxRestarts >= 5 && maxRestarts <= 50) {
+  if (issues.length === 0) {
     return {
       id: "pm2-max-restarts",
       level: "OK",
-      detail: `${PM2_PROCESSES.api} max_restarts=${maxRestarts}`
+      detail: `${PM2_PROCESSES.api} and ${PM2_PROCESSES.nats} max_restarts in hardened range`
     };
   }
   return {
     id: "pm2-max-restarts",
-    level: "WARN",
-    detail: `${PM2_PROCESSES.api} max_restarts=${maxRestarts} \u2014 expected 5..50`
+    level: hasFail ? "FAIL" : "WARN",
+    detail: issues.join("; ")
   };
 }
 async function checkPm2LogrotateInstalled(deps) {
@@ -129226,6 +129255,48 @@ async function checkPm2LogrotateInstalled(deps) {
     detail: "pm2-logrotate installed with expected settings"
   };
 }
+function canonicalPortTargets(serverConfig) {
+  return [
+    { name: PM2_PROCESSES.api, port: serverConfig.port },
+    { name: PM2_PROCESSES.nats, port: 4222 }
+  ];
+}
+async function checkPortCanonicalOwner(deps) {
+  const processes = await deps.getPm2Processes();
+  if (!processes) {
+    return { id: "port-canonical-owner", level: "WARN", detail: "pm2 not reachable" };
+  }
+  const { serverConfig } = deps.loadState();
+  const targets = canonicalPortTargets(serverConfig);
+  const issues = [];
+  for (const { name, port } of targets) {
+    const pm2Entry = processes.find((p) => p.name === name);
+    const pm2Pid = pm2Entry?.pid;
+    const ownerPid = await deps.findPortOwner(port);
+    if (ownerPid === null) {
+      continue;
+    }
+    if (typeof pm2Pid !== "number" || pm2Pid <= 0) {
+      issues.push(`${name}:${port} owned by pid=${ownerPid} but pm2 has no PID for ${name}`);
+      continue;
+    }
+    if (ownerPid !== pm2Pid) {
+      issues.push(`${name}:${port} owned by non-pm2 pid=${ownerPid} (pm2 child pid=${pm2Pid})`);
+    }
+  }
+  if (issues.length === 0) {
+    return {
+      id: "port-canonical-owner",
+      level: "OK",
+      detail: "all canonical ports owned by pm2-managed processes"
+    };
+  }
+  return {
+    id: "port-canonical-owner",
+    level: "FAIL",
+    detail: issues.join("; ")
+  };
+}
 async function fixPm2EnvDrift(deps) {
   const { serverConfig, cliConfig } = deps.loadState();
   const env2 = buildRuntimeEnv(serverConfig, cliConfig);
@@ -129335,6 +129406,83 @@ async function fixPgserveCanonical(deps) {
   const dataNote = dumpResult.status === "dumped" && restoreOutcome.status === "restored" ? `restored ${dumpResult.snapshotPath} into ${canonicalDir} (omni-api \u2192 ${url})` : dumpResult.status === "no-embedded-data" ? `no embedded data to migrate; canonical started empty at ${canonicalDir} (omni-api \u2192 ${url})` : `embedded data dir invalid; canonical started empty at ${canonicalDir} (omni-api \u2192 ${url})`;
   return `migrated to canonical pgserve@^2.1.0; ${dataNote}`;
 }
+async function waitForPortRelease(deps, pid, port) {
+  for (let i = 0;i < 10; i++) {
+    await deps.sleepMs(500);
+    const stillOwner = await deps.findPortOwner(port);
+    if (stillOwner !== pid)
+      return true;
+  }
+  return false;
+}
+async function reclaimPortFromSquatter(deps, target, pm2Pid, managedPids) {
+  const { name, port } = target;
+  const ownerPid = await deps.findPortOwner(port);
+  if (ownerPid === null)
+    return null;
+  if (typeof pm2Pid === "number" && ownerPid === pm2Pid)
+    return null;
+  if (managedPids.has(ownerPid)) {
+    return `SKIPPED ${name}:${port} squatter pid=${ownerPid} is itself pm2-managed`;
+  }
+  if (!deps.processKill(ownerPid, "SIGTERM")) {
+    return `FAILED ${name}:${port} could not signal pid=${ownerPid} (EPERM/ESRCH)`;
+  }
+  const released = await waitForPortRelease(deps, ownerPid, port);
+  if (!released) {
+    deps.processKill(ownerPid, "SIGKILL");
+    await deps.sleepMs(500);
+  }
+  const code = await deps.runPm2(["restart", name]);
+  if (code !== 0) {
+    return `FAILED ${name}:${port} pm2 restart exited ${code} after killing pid=${ownerPid}`;
+  }
+  return `reclaimed ${name}:${port} from non-pm2 pid=${ownerPid}`;
+}
+async function fixPortCanonicalOwner(deps) {
+  const processes = await deps.getPm2Processes();
+  if (!processes) {
+    throw new Error("pm2 not reachable \u2014 cannot reconcile port ownership");
+  }
+  const { serverConfig } = deps.loadState();
+  const targets = canonicalPortTargets(serverConfig);
+  const managedPids = new Set(processes.map((p) => p.pid).filter((p) => typeof p === "number" && p > 0));
+  const repairs = [];
+  for (const target of targets) {
+    const pm2Entry = processes.find((p) => p.name === target.name);
+    const outcome = await reclaimPortFromSquatter(deps, target, pm2Entry?.pid, managedPids);
+    if (outcome !== null)
+      repairs.push(outcome);
+  }
+  if (repairs.length === 0)
+    return "no port-ownership conflicts to reconcile";
+  return repairs.join("; ");
+}
+async function restartNonOnlineProcesses(deps) {
+  const processes = await deps.getPm2Processes();
+  if (!processes)
+    return [];
+  const restarted = [];
+  for (const name of [PM2_PROCESSES.api, PM2_PROCESSES.nats]) {
+    const entry = processes.find((p) => p.name === name);
+    if (entry?.pm2_env?.status !== "online") {
+      const code = await deps.runPm2(["restart", name]);
+      if (code === 0)
+        restarted.push(name);
+    }
+  }
+  return restarted;
+}
+async function fixPm2Status(deps) {
+  const portRepairs = await fixPortCanonicalOwner(deps);
+  const restarted = await restartNonOnlineProcesses(deps);
+  const parts = [];
+  if (portRepairs !== "no port-ownership conflicts to reconcile")
+    parts.push(portRepairs);
+  if (restarted.length > 0)
+    parts.push(`restarted ${restarted.join(", ")}`);
+  return parts.length > 0 ? parts.join("; ") : "no pm2 status remediation needed";
+}
 function fixOrphanedDataDirs(deps) {
   const found = deps.findOrphanedDataDirs();
   if (found.length === 0) {
@@ -129400,7 +129548,8 @@ async function runAllChecks(deps) {
     await checkPm2MaxRestarts(deps),
     await checkPm2LogrotateInstalled(deps),
     await checkSigningKeyForLockedInstances(deps),
-    checkPgserveCanonical(deps)
+    checkPgserveCanonical(deps),
+    await checkPortCanonicalOwner(deps)
   ];
 }
 async function applyFix(deps, check) {
@@ -129417,6 +129566,10 @@ async function applyFix(deps, check) {
       return await fixPm2LogrotateInstalled(deps);
     if (check.id === "pgserve-canonical")
       return await fixPgserveCanonical(deps);
+    if (check.id === "port-canonical-owner")
+      return await fixPortCanonicalOwner(deps);
+    if (check.id === "pm2-status")
+      return await fixPm2Status(deps);
     return null;
   } catch (err) {
     const msg = err instanceof Error ? err.message : String(err);
@@ -129508,9 +129661,10 @@ Checks:
   orphaned-data-dirs       .pgserve-data directories outside ~/.omni
   version-match            CLI version vs. /api/v2/health version field
   pm2-status               omni-api and omni-nats both online in pm2
-  pm2-max-restarts         omni-api max_restarts is in the hardened range
+  pm2-max-restarts         omni-api + omni-nats max_restarts in hardened range
   pm2-logrotate-installed  pm2-logrotate module installed with expected settings
   pgserve-canonical        using canonical pgserve@^2.1.0 (shared backbone) vs. embedded
+  port-canonical-owner     canonical ports (NATS, API) owned by pm2-managed PIDs
 
 Safety:
   --fix NEVER touches ~/.omni/data/pgserve \u2014 it only operates on the pm2

package/dist/server/index.js

@@ -230060,7 +230060,7 @@ var init_sentry_scrub = __esm(() => {
 var require_package8 = __commonJS((exports, module) => {
   module.exports = {
     name: "@omni/api",
-    version: "2.260508.1",
+    version: "2.260508.3",
     type: "module",
     exports: {
       ".": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@automagik/omni",
-  "version": "2.260508.1",
+  "version": "2.260508.3",
   "description": "LLM-optimized CLI for Omni",
   "type": "module",
   "bin": {