@automagik/omni 2.260504.2 → 2.260505.2

package/dist/commands/doctor.d.ts

@@ -61,6 +61,14 @@ export interface DoctorOptions {
     fix?: boolean;
     json?: boolean;
     verbose?: boolean;
+    /**
+     * Force read-only mode. When true, any `fix: true` is suppressed and
+     * `runDoctor` only collects the check report. Used by `omni update`'s
+     * post-update maintenance hook (`runPostUpdateMaintenance`) so the
+     * probe stays read-only — `omni doctor --fix` remains the explicit
+     * operator action for repair.
+     */
+    dryRun?: boolean;
 }
 /**
  * Narrow shape of a pm2 process entry from `pm2 jlist`. We only care about

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/commands/update.d.ts

@@ -22,6 +22,8 @@
  */
 import { Command } from 'commander';
 import { type Config } from '../config.js';
+import { type ParallelInstallReport } from '../update-diagnostics.js';
+import { type DoctorReport, runDoctor } from './doctor.js';
 export type UpdateChannel = 'latest' | 'next';
 /**
  * Resolve the npm dist-tag to install. Priority:
@@ -44,11 +46,26 @@ export interface HealthBody {
  * trigger a spurious mismatch.
  */
 export declare function normalizeVersion(version: string): string;
+/**
+ * Reasons the verify step can be skipped without a server probe. Aligned
+ * byte-for-byte with the genie-side `VerifyResult.skipped.reason` shape so
+ * cross-CLI diagnostics tooling can read either repo's output uniformly
+ * (see `.genie/wishes/update-unify-stages/SHARED-DESIGN.md`).
+ *
+ * - `no-restart`: operator passed `--no-restart`, so no service was touched.
+ * - `no-verify-flag`: operator passed `--no-verify`, restart ran but probe was suppressed.
+ * - `no-running-services`: no tracked PM2 services were online before the install.
+ */
+export type VerifySkipReason = 'no-restart' | 'no-verify-flag' | 'no-running-services';
 /**
  * Result of the pure 3-step update verification. Exported so tests can
  * exercise the logic without mocking pm2 / fetch / process.exit.
+ *
+ * Public-shape parity with the genie wish — each variant's keys match
+ * `automagik-dev/genie` exactly so a shared diagnostics consumer can decode
+ * either CLI's output without per-repo branching.
  */
-export type UpdateVerifyResult = {
+export type VerifyResult = {
     kind: 'ok';
     cliVersion: string;
     serverVersion: string;
@@ -61,22 +78,155 @@ export type UpdateVerifyResult = {
     serverVersion: string | null;
 } | {
     kind: 'auth-invalid';
+} | {
+    kind: 'skipped';
+    reason: VerifySkipReason;
 };
 /**
- * Pure decision function for update verification. Given the raw inputs
- * (health body + key-valid flag + CLI version + port), return a tagged
- * union describing the outcome. The caller decides how to render and
- * whether to exit non-zero.
+ * @deprecated Use {@link VerifyResult}. Retained for backward compatibility
+ * with any external consumer that imported the original name.
+ */
+export type UpdateVerifyResult = VerifyResult;
+/**
+ * Args accepted by {@link decideVerify}. Either `skipReason` is set (the
+ * verify step short-circuits to `{ kind: 'skipped' }`) or all of `latest` /
+ * `apiPort` / `healthBody` / `keyValid` are provided for the full decision.
  */
-export declare function decideUpdateVerify(args: {
+export type DecideVerifyArgs = {
     latest: string;
     apiPort: number;
     healthBody: HealthBody | null;
     keyValid: boolean;
-}): UpdateVerifyResult;
+    skipReason?: undefined;
+} | {
+    skipReason: VerifySkipReason;
+};
+/**
+ * Pure decision function for update verification. Given the raw inputs
+ * (health body + key-valid flag + CLI version + port), return a tagged
+ * union describing the outcome. The caller decides how to render and
+ * whether to exit non-zero.
+ *
+ * When `skipReason` is provided, the function short-circuits to
+ * `{ kind: 'skipped', reason }` without inspecting the other fields. This
+ * is the path used by `--no-restart`, `--no-verify`, and the
+ * no-running-services case.
+ */
+export declare function decideVerify(args: DecideVerifyArgs): VerifyResult;
+/**
+ * @deprecated Use {@link decideVerify}. Pointer-equal alias retained for
+ * backward compatibility with any external consumer that imported the
+ * original name.
+ */
+export declare const decideUpdateVerify: typeof decideVerify;
 /** Error message strings — exported for tests and documentation. */
 export declare function updateErrorVersionMismatch(cli: string, server: string | null): string;
 export declare const UPDATE_ERROR_AUTH_INVALID = "Auth key invalid after restart. Run: omni doctor --fix";
+/**
+ * Detect a parallel npm-global install of `@automagik/omni`. Omni doesn't
+ * support npm-global server (we install via `bun add -g`), but a parallel
+ * install hides stale binaries on PATH and confuses `which omni`. When
+ * detected, the operator gets a one-line warning naming the offending path
+ * with the recommended remediation: `npm uninstall -g @automagik/omni`.
+ *
+ * Pure-ish: probes `npm root -g`, then checks if `<root>/@automagik/omni`
+ * exists. Never throws — when `npm` is absent the probe simply reports
+ * `skipped: 'npm-not-on-path'` and the warning never fires.
+ *
+ * Exported for tests so we can exercise both paths without spawning npm.
+ */
+export declare function detectParallelNpmGlobalInstall(deps?: {
+    npmRoot?: () => string | null;
+    exists?: (p: string) => boolean;
+}): ParallelInstallReport;
+/**
+ * Reasons the post-update maintenance hook can be skipped.
+ *
+ * - `cli-flag`:      operator passed `--skip-maintenance`.
+ * - `env`:           `OMNI_UPDATE_SKIP_MAINTENANCE` was set in the environment.
+ * - `verify-failed`: upstream `decideVerify` outcome was not `ok`, so probing
+ *                    further is pointless (the operator already has a
+ *                    `Run: omni doctor` pointer from the verify step).
+ */
+export type MaintenanceSkipReason = 'cli-flag' | 'env' | 'verify-failed';
+/**
+ * Outcome of a single post-update maintenance run. Public-shape parity with
+ * the genie wish — the same field names land in diagnostics so a shared
+ * consumer can read either CLI's output uniformly.
+ *
+ * - `completed`: `runDoctor` returned a report (regardless of WARN/FAIL counts).
+ * - `failed`:    `runDoctor` threw; the call was non-blocking, exit code stays 0.
+ * - `skipped`:   maintenance was opted out (flag/env) or upstream verify wasn't OK.
+ */
+export type MaintenanceOutcome = 'completed' | 'failed' | 'skipped';
+/**
+ * Captured shape of the post-update maintenance hook. Always populated, even
+ * when skipped — diagnostics (Group 4) consumes the same struct on every
+ * code path so the JSON file shape is invariant.
+ */
+export interface MaintenanceReport {
+    outcome: MaintenanceOutcome;
+    /** Wall time spent inside `runDoctor` (or 0 when skipped). */
+    durationMs: number;
+    /** Present only when `outcome === 'completed'`. */
+    doctorReport?: DoctorReport;
+    /** Present only when `outcome === 'skipped'`. */
+    skipReason?: MaintenanceSkipReason;
+    /** Present only when `outcome === 'failed'` — the thrown error message. */
+    error?: string;
+}
+/** Env-var name that opts out of the post-update maintenance hook. */
+export declare const OMNI_UPDATE_SKIP_MAINTENANCE_ENV = "OMNI_UPDATE_SKIP_MAINTENANCE";
+/**
+ * Resolve the effective skip reason for the post-update maintenance hook.
+ * Returns `null` when maintenance should run. Pure — exported for tests so
+ * we can exercise the precedence logic without spinning up `runDoctor`.
+ *
+ * Precedence (first match wins):
+ *   1. `verify-failed` — upstream verify wasn't `ok`; nothing to probe.
+ *   2. `cli-flag`      — operator passed `--skip-maintenance`.
+ *   3. `env`           — `OMNI_UPDATE_SKIP_MAINTENANCE` is set to a truthy value.
+ *
+ * The truthy check for the env var matches the same loose semantics as
+ * `--yes`/CI flags elsewhere: any non-empty value other than `0`/`false`
+ * counts as opt-out.
+ */
+export declare function resolveMaintenanceSkipReason(args: {
+    verifyOk: boolean;
+    skipMaintenance: boolean | undefined;
+    env: Record<string, string | undefined>;
+}): MaintenanceSkipReason | null;
+/**
+ * Format the one-line summary printed after a completed maintenance run.
+ * Pure — exported so tests can lock the exact shape and so diagnostics
+ * (Group 4) can reuse it without re-deriving the format.
+ *
+ * Shape: `Maintenance: <ok> ok, <warn> warn, <fail> fail`.
+ */
+export declare function formatMaintenanceSummary(report: DoctorReport): string;
+/**
+ * Run the post-update maintenance hook — a read-only `omni doctor` sweep
+ * that captures a `DoctorReport` for diagnostics.
+ *
+ * The call is non-blocking by contract: any thrown error is captured into
+ * the returned `MaintenanceReport` (`outcome: 'failed'`) and the caller
+ * proceeds with exit code 0. This matches the shared exit-code contract
+ * (see `SHARED-DESIGN.md` §4.5: "Maintenance failed (non-blocking) → 0,
+ * with banner warning").
+ *
+ * `runDoctor({ json: true, dryRun: true })` is the canonical call shape:
+ * `dryRun: true` defeats any accidental `fix: true` injection so the probe
+ * never mutates pm2 / config / DB state. `omni doctor --fix` remains the
+ * explicit operator action for repair (decision #4).
+ *
+ * `runDoctorImpl` is injected for tests so we can stub the doctor surface
+ * without monkey-patching the module — module-level mocks leak across
+ * test files in bun and would pollute `doctor.test.ts`.
+ */
+export declare function runPostUpdateMaintenance(args: {
+    skipReason: MaintenanceSkipReason | null;
+    runDoctorImpl?: typeof runDoctor;
+}): Promise<MaintenanceReport>;
 /**
  * Halt updates that would cross the phase-2 default-flip cutoff on hosts
  * still running legacy embedded pgserve without the canonical binary
@@ -90,5 +240,10 @@ export declare function checkCanonicalPgservePreflight(args: {
     useCanonicalPgserve: boolean | undefined;
     pgserveOnPath: boolean;
 }): string | null;
+/**
+ * Parse the `--skip-cleanup=name1,name2` value into a Set. Empty / undefined
+ * yields an empty set. Whitespace and empty entries are tolerated.
+ */
+export declare function parseSkipCleanupList(value: string | undefined): Set<string>;
 export declare function createUpdateCommand(): Command;
 //# sourceMappingURL=update.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"update.d.ts","sourceRoot":"","sources":["../../src/commands/update.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAKH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEpC,OAAO,EAAE,KAAK,MAAM,EAA4C,MAAM,cAAc,CAAC;AA8BrF,MAAM,MAAM,aAAa,GAAG,QAAQ,GAAG,MAAM,CAAC;AAE9C;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE;IAAE,IAAI,CAAC,EAAE,OAAO,CAAC;IAAC,MAAM,CAAC,EAAE,OAAO,CAAA;CAAE,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,aAAa,CAQ5G;AAiID,4DAA4D;AAC5D,MAAM,WAAW,UAAU;IACzB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAExD;AAED;;;GAGG;AACH,MAAM,MAAM,kBAAkB,GAC1B;IAAE,IAAI,EAAE,IAAI,CAAC;IAAC,UAAU,EAAE,MAAM,CAAC;IAAC,aAAa,EAAE,MAAM,CAAA;CAAE,GACzD;IAAE,IAAI,EAAE,oBAAoB,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GAC/C;IAAE,IAAI,EAAE,kBAAkB,CAAC;IAAC,UAAU,EAAE,MAAM,CAAC;IAAC,aAAa,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,GAC9E;IAAE,IAAI,EAAE,cAAc,CAAA;CAAE,CAAC;AAE7B;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE;IACvC,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,UAAU,GAAG,IAAI,CAAC;IAC9B,QAAQ,EAAE,OAAO,CAAC;CACnB,GAAG,kBAAkB,CAarB;AAED,oEAAoE;AACpE,wBAAgB,0BAA0B,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,CAErF;AAED,eAAO,MAAM,yBAAyB,2DAA2D,CAAC;AA+MlG;;;;;;GAMG;AACH,wBAAgB,8BAA8B,CAAC,IAAI,EAAE;IACnD,cAAc,EAAE,MAAM,CAAC;IACvB,aAAa,EAAE,MAAM,CAAC;IACtB,mBAAmB,EAAE,OAAO,GAAG,SAAS,CAAC;IACzC,aAAa,EAAE,OAAO,CAAC;CACxB,GAAG,MAAM,GAAG,IAAI,CAkChB;AAuFD,wBAAgB,mBAAmB,IAAI,OAAO,CAoD7C"}
+{"version":3,"file":"update.d.ts","sourceRoot":"","sources":["../../src/commands/update.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -78229,7 +78229,7 @@ var require_path = __commonJS((exports) => {
   function isAbsolute(path) {
     return path.charAt(0) === "/";
   }
-  function join16(...args) {
+  function join18(...args) {
     return normalizePath(args.join("/"));
   }
   function dirname6(path) {
@@ -78254,7 +78254,7 @@ var require_path = __commonJS((exports) => {
   exports.basename = basename6;
   exports.dirname = dirname6;
   exports.isAbsolute = isAbsolute;
-  exports.join = join16;
+  exports.join = join18;
   exports.normalizePath = normalizePath;
   exports.relative = relative;
   exports.resolve = resolve4;
@@ -100994,12 +100994,12 @@ var require_instrumentation9 = __commonJS((exports) => {
         pendingMetrics.forEach((m2) => m2());
         return result;
       }).catch((reason) => {
-        let errorMessage;
+        let errorMessage2;
         let errorType = semantic_conventions_1.ERROR_TYPE_VALUE_OTHER;
         if (typeof reason === "string" || reason === undefined) {
-          errorMessage = reason;
+          errorMessage2 = reason;
         } else if (typeof reason === "object" && Object.prototype.hasOwnProperty.call(reason, "message")) {
-          errorMessage = reason.message;
+          errorMessage2 = reason.message;
           errorType = reason.constructor.name;
         }
         pendingMetrics.forEach((m2) => m2(errorType));
@@ -101007,7 +101007,7 @@ var require_instrumentation9 = __commonJS((exports) => {
           span.setAttribute(semantic_conventions_1.ATTR_ERROR_TYPE, errorType);
           span.setStatus({
             code: api_1.SpanStatusCode.ERROR,
-            message: errorMessage
+            message: errorMessage2
           });
         });
         throw reason;
@@ -114211,7 +114211,7 @@ import { fileURLToPath } from "url";
 // package.json
 var package_default = {
   name: "@automagik/omni",
-  version: "2.260504.2",
+  version: "2.260505.2",
   description: "LLM-optimized CLI for Omni",
   type: "module",
   bin: {
@@ -119684,7 +119684,7 @@ async function runDoctor(options, depsOverride) {
   const deps = depsOverride ?? productionDeps();
   let checks = await runAllChecks(deps);
   const fixesApplied = [];
-  if (options.fix) {
+  if (options.fix && options.dryRun !== true) {
     const phase1 = await runPhase1MigrationFix(deps, checks, fixesApplied);
     checks = phase1.checks;
     await runPhase2Fixes(deps, checks, phase1.canonicalFailed, fixesApplied);
@@ -125829,10 +125829,11 @@ function createTurnsCommand() {
 }
 
 // src/commands/update.ts
+import { existsSync as existsSync17 } from "fs";
+import { join as join16 } from "path";
 import { createInterface as createInterface3 } from "readline";
 init_source();
 init_config();
-init_output();
 
 // src/sidecar-cleanup.ts
 var SIDECAR_BASENAME = "nats-reply-sidecar.mjs";
@@ -126009,8 +126010,185 @@ function formatCleanupSummary(result) {
   return lines.join(`
 `);
 }
-function cleanupSucceeded(result) {
-  return result.pm2Failed.length === 0 && result.rawFailed.length === 0;
+
+// src/legacy-cleanup.ts
+function createNatsReplySidecarArtifact() {
+  let lastResult = null;
+  return {
+    name: "nats-reply-sidecar",
+    async detect() {
+      return true;
+    },
+    async cleanup() {
+      const result = await cleanupSidecars();
+      lastResult = result;
+      const removed = [];
+      const warnings = [];
+      for (const m2 of result.pm2Stopped) {
+        removed.push(`pm2:${m2.name.length > 0 ? m2.name : `pm_id=${m2.pmId}`}`);
+      }
+      for (const m2 of result.rawKilled) {
+        removed.push(`pid:${m2.pid}`);
+      }
+      for (const m2 of result.pm2Failed) {
+        warnings.push(`pm2-failed:${m2.name.length > 0 ? m2.name : `pm_id=${m2.pmId}`}`);
+      }
+      for (const m2 of result.rawFailed) {
+        warnings.push(`raw-failed:pid=${m2.pid}`);
+      }
+      return { removed, warnings };
+    },
+    summary() {
+      return lastResult === null ? "" : formatCleanupSummary(lastResult);
+    }
+  };
+}
+var REGISTRY = [createNatsReplySidecarArtifact()];
+function errorMessage(error2) {
+  return error2 instanceof Error ? error2.message : String(error2);
+}
+function erroredOutcome(name, phase, error2) {
+  const message2 = errorMessage(error2);
+  return {
+    name,
+    state: "errored",
+    removed: [],
+    warnings: [`${phase}-threw:${message2}`],
+    summary: "",
+    error: message2
+  };
+}
+async function runArtifact(artifact) {
+  let detected;
+  try {
+    detected = await artifact.detect();
+  } catch (error2) {
+    return erroredOutcome(artifact.name, "detect", error2);
+  }
+  if (!detected) {
+    return {
+      name: artifact.name,
+      state: "not-detected",
+      removed: [],
+      warnings: [],
+      summary: ""
+    };
+  }
+  try {
+    const { removed, warnings } = await artifact.cleanup();
+    return {
+      name: artifact.name,
+      state: "ran",
+      removed,
+      warnings,
+      summary: artifact.summary()
+    };
+  } catch (error2) {
+    return erroredOutcome(artifact.name, "cleanup", error2);
+  }
+}
+async function cleanupLegacyArtifacts(skipList) {
+  const outcomes = [];
+  const skipped = [];
+  for (const artifact of REGISTRY) {
+    if (skipList.has(artifact.name)) {
+      skipped.push(artifact.name);
+      outcomes.push({
+        name: artifact.name,
+        state: "skipped",
+        removed: [],
+        warnings: [],
+        summary: ""
+      });
+      continue;
+    }
+    outcomes.push(await runArtifact(artifact));
+  }
+  const succeeded = outcomes.every((o2) => o2.state !== "errored" && (o2.state !== "ran" || o2.warnings.length === 0));
+  return { outcomes, succeeded, skipped };
+}
+
+// src/commands/update.ts
+init_output();
+
+// src/update-diagnostics.ts
+import { existsSync as existsSync16, mkdirSync as mkdirSync10, readFileSync as readFileSync11, writeFileSync as writeFileSync9 } from "fs";
+import { homedir as homedir11 } from "os";
+import { join as join15 } from "path";
+var UPDATE_DIAGNOSTICS_SCHEMA_VERSION = 1;
+function createDiagnostics(args) {
+  const startedAt = new Date().toISOString();
+  return {
+    schemaVersion: UPDATE_DIAGNOSTICS_SCHEMA_VERSION,
+    startedAt,
+    finishedAt: startedAt,
+    cli: { runningVersion: args.runningVersion, channel: args.channel },
+    registry: { latestVersion: null },
+    preflight: { ran: false, blocked: false },
+    install: { attempted: false, succeeded: null, targetVersion: null },
+    restart: { attempted: false, succeeded: null, services: [] },
+    verify: null,
+    cleanups: null,
+    maintenance: null,
+    parallelNpmGlobal: null,
+    recentLogSignals: [],
+    exitCode: 0
+  };
+}
+function getDiagnosticsDir() {
+  const base = process.env.OMNI_CONFIG_DIR ?? join15(homedir11(), ".omni");
+  return join15(base, "logs");
+}
+function getDiagnosticsPath(startedAt) {
+  const safe = startedAt.replace(/:/g, "-");
+  return join15(getDiagnosticsDir(), `update-diagnostics-${safe}.json`);
+}
+function tailFileLines(path, maxLines) {
+  if (!existsSync16(path))
+    return [];
+  try {
+    const raw2 = readFileSync11(path, "utf8");
+    const lines = raw2.split(/\r?\n/);
+    if (lines.length > 0 && lines[lines.length - 1] === "")
+      lines.pop();
+    return lines.slice(-maxLines);
+  } catch {
+    return [];
+  }
+}
+function collectRecentLogSignals(maxLinesPerStream = 30, logPathsFor = getPm2LogPaths) {
+  const signals2 = [];
+  for (const name of Object.values(PM2_PROCESSES)) {
+    const { out, error: error2 } = logPathsFor(name);
+    const outLines = tailFileLines(out, maxLinesPerStream);
+    if (outLines.length > 0) {
+      signals2.push({ source: name, stream: "out", lines: outLines });
+    }
+    const errLines = tailFileLines(error2, maxLinesPerStream);
+    if (errLines.length > 0) {
+      signals2.push({ source: name, stream: "error", lines: errLines });
+    }
+  }
+  return signals2;
+}
+function writeDiagnostics(state, exitCode) {
+  state.exitCode = exitCode;
+  state.finishedAt = new Date().toISOString();
+  if (state.recentLogSignals.length === 0) {
+    state.recentLogSignals = collectRecentLogSignals();
+  }
+  const dir = getDiagnosticsDir();
+  const path = getDiagnosticsPath(state.startedAt);
+  try {
+    if (!existsSync16(dir)) {
+      mkdirSync10(dir, { recursive: true, mode: 448 });
+    }
+    writeFileSync9(path, `${JSON.stringify(state, null, 2)}
+`, { mode: 384 });
+    return path;
+  } catch {
+    return null;
+  }
 }
 
 // src/commands/update.ts
@@ -126111,7 +126289,10 @@ async function restartPm2Services(processNames) {
 function normalizeVersion(version2) {
   return version2.split("+")[0] ?? version2;
 }
-function decideUpdateVerify(args) {
+function decideVerify(args) {
+  if (args.skipReason !== undefined) {
+    return { kind: "skipped", reason: args.skipReason };
+  }
   const cliVersion = normalizeVersion(args.latest);
   if (args.healthBody === null) {
     return { kind: "health-unreachable", apiPort: args.apiPort };
@@ -126166,52 +126347,158 @@ function printVerifyBanner(latest) {
   console.log(`${source_default.green("\u2713")} Server: v${latest} (healthy)`);
   console.log(`${source_default.green("\u2713")} Auth:   key valid`);
 }
-async function runSidecarCleanup() {
-  const cleanupSpinner = ora("Checking for legacy nats-reply-sidecar processes...").start();
-  const result = await cleanupSidecars();
+function printVerifySkippedBanner(latest) {
+  console.log(`${source_default.green("\u2713")} CLI:    v${latest}`);
+  console.log(`${source_default.yellow("-")} Server: v${latest} (skipped)`);
+  console.log(`${source_default.yellow("-")} Auth:   skipped`);
+}
+function detectParallelNpmGlobalInstall(deps) {
+  const npmRootFn = deps?.npmRoot ?? defaultNpmRoot;
+  const existsFn = deps?.exists ?? existsSync17;
+  let root;
+  try {
+    root = npmRootFn();
+  } catch {
+    return { detected: false, skipped: "npm-root-failed" };
+  }
+  if (root === null || root.length === 0) {
+    return { detected: false, skipped: "npm-not-on-path" };
+  }
+  const candidate = join16(root, "@automagik", "omni");
+  if (existsFn(candidate)) {
+    return { detected: true, path: candidate };
+  }
+  return { detected: false };
+}
+function defaultNpmRoot() {
+  try {
+    const result = Bun.spawnSync({
+      cmd: ["npm", "root", "-g"],
+      stdout: "pipe",
+      stderr: "pipe",
+      timeout: 5000
+    });
+    if (result.exitCode !== 0)
+      return null;
+    const text3 = new TextDecoder().decode(result.stdout).trim();
+    return text3.length > 0 ? text3 : null;
+  } catch {
+    return null;
+  }
+}
+async function runLegacyCleanup(skipList) {
+  const cleanupSpinner = ora("Checking for legacy artifacts to clean up...").start();
+  const report = await cleanupLegacyArtifacts(skipList);
   cleanupSpinner.stop();
-  const summary = formatCleanupSummary(result);
-  if (summary.length > 0) {
-    console.log(summary);
+  for (const outcome of report.outcomes) {
+    if (outcome.state === "ran" && outcome.summary.length > 0) {
+      console.log(outcome.summary);
+    }
   }
-  return result;
+  return report;
 }
-async function restartServicesAndVerify(servicesToRestart, latest, options3) {
+var OMNI_UPDATE_SKIP_MAINTENANCE_ENV = "OMNI_UPDATE_SKIP_MAINTENANCE";
+function resolveMaintenanceSkipReason(args) {
+  if (!args.verifyOk)
+    return "verify-failed";
+  if (args.skipMaintenance === true)
+    return "cli-flag";
+  const raw2 = args.env[OMNI_UPDATE_SKIP_MAINTENANCE_ENV];
+  if (raw2 !== undefined && raw2 !== "" && raw2 !== "0" && raw2.toLowerCase() !== "false") {
+    return "env";
+  }
+  return null;
+}
+function formatMaintenanceSummary(report) {
+  const { ok: ok2, warn: warn2, fail } = report.summary;
+  return `Maintenance: ${ok2} ok, ${warn2} warn, ${fail} fail`;
+}
+async function runPostUpdateMaintenance(args) {
+  if (args.skipReason !== null) {
+    return { outcome: "skipped", durationMs: 0, skipReason: args.skipReason };
+  }
+  const impl = args.runDoctorImpl ?? runDoctor;
+  const startedAt = Date.now();
+  try {
+    const doctorReport = await impl({ json: true, dryRun: true });
+    return {
+      outcome: "completed",
+      durationMs: Date.now() - startedAt,
+      doctorReport
+    };
+  } catch (err2) {
+    return {
+      outcome: "failed",
+      durationMs: Date.now() - startedAt,
+      error: err2 instanceof Error ? err2.message : String(err2)
+    };
+  }
+}
+async function restartServicesAndVerify(servicesToRestart, latest, options3, diagnostics, finalize) {
   const apiPort = loadServerConfig().port;
+  diagnostics.restart.attempted = true;
+  diagnostics.restart.services = [...servicesToRestart];
   const restartSpinner = ora("Restarting services...").start();
   const restartSucceeded = await restartPm2Services(servicesToRestart);
   restartSpinner.stop();
+  diagnostics.restart.succeeded = restartSucceeded;
   if (!restartSucceeded) {
     warn(`omni CLI updated to v${latest}, but one or more service restarts failed. Run \`omni status\`.`);
-    process.exit(1);
-  }
-  let sidecarCleanupResult = null;
-  if (options3.sidecarCleanup) {
-    sidecarCleanupResult = await runSidecarCleanup();
+    finalize(1);
+  }
+  let cleanupReport = null;
+  if (options3.legacyCleanup) {
+    cleanupReport = await runLegacyCleanup(options3.skipList);
+    diagnostics.cleanups = cleanupReport;
+  }
+  if (options3.skipVerify) {
+    const result2 = decideVerify({ skipReason: "no-verify-flag" });
+    diagnostics.verify = result2;
+    printVerifySkippedBanner(latest);
+    if (cleanupReport !== null && !cleanupReport.succeeded) {
+      warn("One or more legacy artifacts could not be cleaned up automatically. " + "See messages above and docs/migration/nats-genie-sidecar-decommission.md.");
+    }
+    const maintenance = await runPostUpdateMaintenance({ skipReason: "verify-failed" });
+    diagnostics.maintenance = maintenance;
+    return;
   }
   const verifySpinner = ora("Verifying server version...").start();
   const healthBody = await fetchHealthBody(apiPort, UPDATE_HEALTH_TIMEOUT_MS);
   verifySpinner.stop();
   const keyValid = healthBody !== null ? await validateStoredKey(apiPort) : false;
-  const result = decideUpdateVerify({ latest, apiPort, healthBody, keyValid });
+  const result = decideVerify({ latest, apiPort, healthBody, keyValid });
+  diagnostics.verify = result;
   switch (result.kind) {
-    case "ok":
+    case "ok": {
       printVerifyBanner(result.cliVersion);
-      if (sidecarCleanupResult !== null && !cleanupSucceeded(sidecarCleanupResult)) {
-        warn("One or more legacy nats-reply-sidecar processes could not be stopped automatically. " + "See messages above and docs/migration/nats-genie-sidecar-decommission.md.");
+      if (cleanupReport !== null && !cleanupReport.succeeded) {
+        warn("One or more legacy artifacts could not be cleaned up automatically. " + "See messages above and docs/migration/nats-genie-sidecar-decommission.md.");
+      }
+      const skipReason = resolveMaintenanceSkipReason({
+        verifyOk: true,
+        skipMaintenance: options3.skipMaintenance,
+        env: process.env
+      });
+      const maintenance = await runPostUpdateMaintenance({ skipReason });
+      diagnostics.maintenance = maintenance;
+      if (maintenance.outcome === "completed" && maintenance.doctorReport) {
+        info(formatMaintenanceSummary(maintenance.doctorReport));
+      } else if (maintenance.outcome === "failed") {
+        warn(`Maintenance: skipped (runDoctor failed: ${maintenance.error ?? "unknown error"})`);
       }
       return;
+    }
     case "health-unreachable":
       warn(`omni CLI updated to v${latest}, but health check failed on port ${result.apiPort}. Run \`omni status\`.`);
-      process.exit(1);
+      finalize(1);
       break;
     case "version-mismatch":
       console.error(`${source_default.red("\u2717")} ${updateErrorVersionMismatch(result.cliVersion, result.serverVersion)}`);
-      process.exit(1);
+      finalize(1);
       break;
     case "auth-invalid":
       console.error(`${source_default.red("\u2717")} ${UPDATE_ERROR_AUTH_INVALID}`);
-      process.exit(1);
+      finalize(1);
       break;
   }
 }
@@ -126288,20 +126575,35 @@ async function runUpdate(options3) {
   if (options3.next || options3.stable) {
     persistChannel(channel2);
   }
+  const currentClean = VERSION.split("+")[0];
+  const diagnostics = createDiagnostics({ runningVersion: currentClean, channel: channel2 });
+  const finalize = (exitCode) => {
+    const path = writeDiagnostics(diagnostics, exitCode);
+    if (path !== null && process.env.OMNI_UPDATE_DIAGNOSTICS_VERBOSE === "1") {
+      info(`Diagnostics written: ${path}`);
+    }
+    process.exit(exitCode);
+  };
+  const parallelInstall = detectParallelNpmGlobalInstall();
+  diagnostics.parallelNpmGlobal = parallelInstall;
+  if (parallelInstall.detected && parallelInstall.path) {
+    warn(`Parallel npm-global install of ${PACKAGE_NAME} detected at ${parallelInstall.path}. This may shadow the bun-installed binary on PATH. Recommended: npm uninstall -g ${PACKAGE_NAME}`);
+  }
   info(`Channel: ${channel2}${channel2 === "next" ? " (dev builds)" : " (stable)"}`);
   const versionSpinner = ora(`Checking ${channel2} version of ${PACKAGE_NAME}...`).start();
   const latest = await fetchLatestVersion(channel2);
   versionSpinner.stop();
+  diagnostics.registry.latestVersion = latest;
   if (latest === null) {
     warn("Could not reach npm registry. Check your network connection and try again.");
-    process.exit(1);
+    return finalize(1);
   }
-  const currentClean = VERSION.split("+")[0];
   if (currentClean === latest) {
     success(`Already up to date (v${latest}, channel: ${channel2})`);
-    process.exit(0);
+    return finalize(0);
   }
   if (!options3.skipCanonicalPreflight) {
+    diagnostics.preflight.ran = true;
     const serverConfig = loadServerConfig();
     const preflightError = checkCanonicalPgservePreflight({
       currentVersion: currentClean,
@@ -126310,8 +126612,11 @@ async function runUpdate(options3) {
       pgserveOnPath: isPgserveOnPath()
     });
     if (preflightError !== null) {
+      diagnostics.preflight.blocked = true;
+      diagnostics.preflight.reason = preflightError.split(`
+`)[0];
       warn(preflightError);
-      process.exit(1);
+      return finalize(1);
     }
   }
   info(`Update available: v${currentClean} \u2192 v${latest} (${channel2})`);
@@ -126319,27 +126624,47 @@ async function runUpdate(options3) {
     const confirmed = await promptConfirm(`Update from v${currentClean} to v${latest}? [Y/n] `);
     if (!confirmed) {
       info("Update cancelled.");
-      process.exit(0);
+      return finalize(0);
     }
   }
   const servicesToRestart = options3.restart !== false ? getRunningPm2Services() : [];
   const installSpinner = ora(`Updating ${PACKAGE_NAME}@${channel2}...`).start();
+  diagnostics.install.attempted = true;
+  diagnostics.install.targetVersion = latest;
   const installed = await installLatest(channel2);
   installSpinner.stop();
+  diagnostics.install.succeeded = installed;
   if (!installed) {
     warn(`Installation failed. Your current version (v${currentClean}) is still intact.`);
-    process.exit(1);
+    return finalize(1);
+  }
+  const sidecarCleanupExplicit = options3.sidecarCleanup === false;
+  if (sidecarCleanupExplicit) {
+    info("--no-sidecar-cleanup (deprecated alias for --no-legacy-cleanup)");
   }
+  const legacyCleanupEnabled = options3.legacyCleanup !== false && options3.sidecarCleanup !== false;
+  const skipList = parseSkipCleanupList(options3.skipCleanup);
   if (servicesToRestart.length > 0) {
     await restartServicesAndVerify(servicesToRestart, latest, {
-      sidecarCleanup: options3.sidecarCleanup !== false
-    });
-    return;
-  }
+      legacyCleanup: legacyCleanupEnabled,
+      skipList,
+      skipMaintenance: options3.skipMaintenance === true,
+      skipVerify: options3.verify === false
+    }, diagnostics, finalize);
+    return finalize(0);
+  }
+  diagnostics.verify = decideVerify({ skipReason: "no-restart" });
   success(`omni updated to v${latest}`);
+  return finalize(0);
+}
+function parseSkipCleanupList(value) {
+  if (!value)
+    return new Set;
+  const names = value.split(",").map((s2) => s2.trim()).filter((s2) => s2.length > 0);
+  return new Set(names);
 }
 function createUpdateCommand() {
-  return new Command("update").description(`Update ${PACKAGE_NAME} to the latest version (restart only services already running)`).option("-y, --yes", "Skip confirmation prompts (non-interactive)").option("--no-restart", "Update CLI only; skip service restarts and verification").option("--no-sidecar-cleanup", "Skip the legacy nats-reply-sidecar.mjs cleanup step").option("--next", "Switch to dev builds (npm @next tag) and persist as default").option("--stable", "Switch to stable releases (npm @latest tag) and persist as default").option("--skip-canonical-preflight", "Bypass the canonical-pgserve phase-2 pre-flight (NOT recommended; for operators who pre-installed pgserve via a path the auto-detector misses)").addHelpText("after", `
+  return new Command("update").description(`Update ${PACKAGE_NAME} to the latest version (restart only services already running)`).option("-y, --yes", "Skip confirmation prompts (non-interactive)").option("--no-restart", "Update CLI only; skip service restarts and verification").option("--no-verify", "Restart services but skip the post-restart probe (use when a release ships a broken /api/v2/health and operators need to roll forward)").option("--no-legacy-cleanup", "Skip every registered legacy-artifact cleanup (e.g. nats-reply-sidecar)").option("--no-sidecar-cleanup", "Deprecated alias for --no-legacy-cleanup").option("--skip-cleanup <names>", 'Comma-separated list of legacy-cleanup registry entries to skip (e.g. "nats-reply-sidecar")').option("--next", "Switch to dev builds (npm @next tag) and persist as default").option("--stable", "Switch to stable releases (npm @latest tag) and persist as default").option("--skip-canonical-preflight", "Bypass the canonical-pgserve phase-2 pre-flight (NOT recommended; for operators who pre-installed pgserve via a path the auto-detector misses)").option("--skip-maintenance", `Skip the post-update maintenance hook (read-only \`omni doctor\` sweep). Also honored via the ${OMNI_UPDATE_SKIP_MAINTENANCE_ENV} env var.`).addHelpText("after", `
 Channels:
   - stable (default) \u2014 tracks the npm @latest tag, bumped from main branch releases.
   - next (dev builds) \u2014 tracks the npm @next tag, bumped on every CI-green dev merge.
@@ -126365,14 +126690,38 @@ Behavior:
       "Server version mismatch: cli=v<X> server=v<Y>. Run: omni doctor"
   - On auth failure, exits non-zero with:
       "Auth key invalid after restart. Run: omni doctor --fix"
-  - After a successful restart, scans for any legacy nats-reply-sidecar.mjs
-    process (PM2-managed or raw) and stops it. The sidecar was an external
-    workaround for bugs that were fixed in #362; leaving it running causes
-    every agent reply to be delivered twice. Skippable with
-    --no-sidecar-cleanup. Manual runbook:
+  - After a successful restart, runs every registered legacy-artifact cleanup.
+    The day-one entry is nats-reply-sidecar: it scans for any legacy
+    nats-reply-sidecar.mjs process (PM2-managed or raw) and stops it. The
+    sidecar was an external workaround for bugs that were fixed in #362;
+    leaving it running causes every agent reply to be delivered twice.
+    Skip every cleanup with --no-legacy-cleanup, or skip a single registry
+    entry with --skip-cleanup=<name1,name2>. The deprecated alias
+    --no-sidecar-cleanup still works and behaves identically. Manual runbook:
       docs/migration/nats-genie-sidecar-decommission.md
   - Use --no-restart to skip restart + verification entirely. --no-restart
-    also skips sidecar cleanup; manage the sidecar manually.
+    also skips legacy-artifact cleanup; manage those services manually.
+  - Use --no-verify to restart services but skip the post-restart probe.
+    The banner shows the new CLI version on both lines but tags Server /
+    Auth as "(skipped)"; maintenance is auto-skipped because verify never
+    confirmed health.
+  - Detects parallel npm-global installs of ${PACKAGE_NAME} (omni installs
+    via bun-global; an npm-global install hides stale binaries on PATH and
+    confuses 'which omni'). When found, prints a one-line warning naming
+    the offending path; recommended remediation: npm uninstall -g ${PACKAGE_NAME}.
+  - Every invocation writes a diagnostics record to
+    ~/.omni/logs/update-diagnostics-<iso>.json (schemaVersion: 1). Captures
+    install attempt, registry probe, restart outcome, verify result, cleanup
+    registry result, maintenance hook, and a tail of pm2 log signals. Set
+    OMNI_UPDATE_DIAGNOSTICS_VERBOSE=1 to print the path on completion. A
+    failed write never changes the update exit code.
+  - On a successful restart + verify, runs a post-update maintenance hook:
+    a read-only \`omni doctor\` sweep that prints a one-line summary
+    ("Maintenance: <ok> ok, <warn> warn, <fail> fail"). The probe never
+    mutates pm2 / config / DB state (\`omni doctor --fix\` remains the
+    explicit operator action for repair). A failing maintenance call is
+    non-fatal \u2014 exit code stays 0 with a banner warning. Skip with
+    --skip-maintenance or ${OMNI_UPDATE_SKIP_MAINTENANCE_ENV}=1.
   - Verify runtime health after update with: omni status
 `).action(runUpdate);
 }
@@ -126484,9 +126833,9 @@ function createVoiceCommand() {
     const startTime = Date.now();
     let saveDir = "";
     if (opts.save) {
-      const { mkdirSync: mkdirSync10 } = await import("fs");
+      const { mkdirSync: mkdirSync11 } = await import("fs");
       saveDir = opts.save;
-      mkdirSync10(saveDir, { recursive: true });
+      mkdirSync11(saveDir, { recursive: true });
       info(`Saving audio to: ${saveDir}`);
     }
     ws.onopen = () => {
@@ -126710,17 +127059,17 @@ init_config();
 init_output();
 
 // src/manifest-pin.ts
-import { existsSync as existsSync16, readFileSync as readFileSync11, renameSync as renameSync3, writeFileSync as writeFileSync9 } from "fs";
-import { homedir as homedir11 } from "os";
-import { join as join15 } from "path";
+import { existsSync as existsSync18, readFileSync as readFileSync12, renameSync as renameSync3, writeFileSync as writeFileSync10 } from "fs";
+import { homedir as homedir12 } from "os";
+import { join as join17 } from "path";
 var PACKAGE_NAME2 = "@automagik/omni";
-var BUN_GLOBAL_MANIFEST = join15(homedir11(), ".bun", "install", "global", "package.json");
+var BUN_GLOBAL_MANIFEST = join17(homedir12(), ".bun", "install", "global", "package.json");
 function pinManifestEntry(manifestPath, exactVersion) {
-  if (!existsSync16(manifestPath))
+  if (!existsSync18(manifestPath))
     return false;
   let manifest;
   try {
-    manifest = JSON.parse(readFileSync11(manifestPath, "utf-8"));
+    manifest = JSON.parse(readFileSync12(manifestPath, "utf-8"));
   } catch {
     return false;
   }
@@ -126746,7 +127095,7 @@ function pinManifestEntry(manifestPath, exactVersion) {
     return false;
   const tmp = `${manifestPath}.tmp.${process.pid}`;
   try {
-    writeFileSync9(tmp, `${JSON.stringify(manifest, null, 2)}
+    writeFileSync10(tmp, `${JSON.stringify(manifest, null, 2)}
 `, { mode: 420 });
     renameSync3(tmp, manifestPath);
   } catch {

package/dist/legacy-cleanup.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Legacy artifact cleanup registry.
+ *
+ * Generalizes the bespoke `cleanupSidecars()` step in `omni update` into a
+ * registry of `LegacyArtifact` entries so future deprecation cleanups (e.g.
+ * obsolete WhatsApp baileys session formats, dead pm2 process names, stale
+ * config files) drop in without code changes to the update orchestration.
+ *
+ * The day-one entry is `nats-reply-sidecar`, which wraps the existing
+ * `cleanupSidecars()` / `cleanupSucceeded()` / `formatCleanupSummary()`
+ * helpers in `sidecar-cleanup.ts`. Operator-facing output is byte-identical
+ * to the pre-registry behavior — the registry only changes the dispatch.
+ *
+ * Public shape mirrors the genie wish (independent code, identical signature
+ * per SHARED-DESIGN.md decision #3).
+ */
+/**
+ * One legacy artifact eligible for cleanup. Implementations are stateful:
+ * `cleanup()` may stash the raw result so `summary()` can render it.
+ */
+export interface LegacyArtifact {
+    readonly name: string;
+    /**
+     * Best-effort fast probe — return true if cleanup() should be run. Returning
+     * false is reserved for hard short-circuits (e.g. the artifact's namespace
+     * doesn't exist on this OS). If detection itself is cheap relative to
+     * cleanup, implementations may simply return true and let the empty-case
+     * path in cleanup() produce an empty summary.
+     */
+    detect(): Promise<boolean>;
+    /**
+     * Run the cleanup. Returns the user-visible artifacts (`removed`) and any
+     * non-fatal problems (`warnings`). Implementations should never throw —
+     * the registry treats a thrown error as "warning, succeeded=false".
+     */
+    cleanup(): Promise<{
+        removed: string[];
+        warnings: string[];
+    }>;
+    /**
+     * Human-readable multi-line summary of the most recent cleanup() call.
+     * Empty string when nothing happened (so the caller can suppress the block).
+     */
+    summary(): string;
+}
+/**
+ * Per-artifact outcome captured in the report.
+ */
+export interface ArtifactOutcome {
+    readonly name: string;
+    readonly state: 'ran' | 'skipped' | 'not-detected' | 'errored';
+    readonly removed: string[];
+    readonly warnings: string[];
+    readonly summary: string;
+    readonly error?: string;
+}
+/**
+ * Aggregate cleanup outcome across the registry. Consumed by diagnostics
+ * (Group 4) and by the update banner ("warn loudly when a cleanup partially
+ * failed").
+ */
+export interface CleanupReport {
+    readonly outcomes: ArtifactOutcome[];
+    /** True iff every ran artifact reported zero warnings AND nothing errored. */
+    readonly succeeded: boolean;
+    /** Names that were skipped via `skipList`. */
+    readonly skipped: string[];
+}
+/**
+ * The live registry. Order matters — artifacts run sequentially so an earlier
+ * cleanup's side effects are visible to a later one (e.g. stopping a process
+ * before deleting its config file).
+ *
+ * To add a new artifact:
+ *   1. Implement `LegacyArtifact` (idempotent, never-throws).
+ *   2. Append a factory call below.
+ *   3. Add a unit test that runs the registry round-trip.
+ *   4. Document the deprecation in `docs/migration/`.
+ */
+export declare const REGISTRY: LegacyArtifact[];
+export declare function cleanupLegacyArtifacts(skipList: Set<string>): Promise<CleanupReport>;
+//# sourceMappingURL=legacy-cleanup.d.ts.map

package/dist/legacy-cleanup.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"legacy-cleanup.d.ts","sourceRoot":"","sources":["../src/legacy-cleanup.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAQH;;;GAGG;AACH,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB;;;;;;OAMG;IACH,MAAM,IAAI,OAAO,CAAC,OAAO,CAAC,CAAC;IAC3B;;;;OAIG;IACH,OAAO,IAAI,OAAO,CAAC;QAAE,OAAO,EAAE,MAAM,EAAE,CAAC;QAAC,QAAQ,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC,CAAC;IAC9D;;;OAGG;IACH,OAAO,IAAI,MAAM,CAAC;CACnB;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,KAAK,GAAG,SAAS,GAAG,cAAc,GAAG,SAAS,CAAC;IAC/D,QAAQ,CAAC,OAAO,EAAE,MAAM,EAAE,CAAC;IAC3B,QAAQ,CAAC,QAAQ,EAAE,MAAM,EAAE,CAAC;IAC5B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AAED;;;;GAIG;AACH,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,QAAQ,EAAE,eAAe,EAAE,CAAC;IACrC,8EAA8E;IAC9E,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,8CAA8C;IAC9C,QAAQ,CAAC,OAAO,EAAE,MAAM,EAAE,CAAC;CAC5B;AA+CD;;;;;;;;;;GAUG;AACH,eAAO,MAAM,QAAQ,EAAE,cAAc,EAAuC,CAAC;AA2D7E,wBAAsB,sBAAsB,CAAC,QAAQ,EAAE,GAAG,CAAC,MAAM,CAAC,GAAG,OAAO,CAAC,aAAa,CAAC,CAuB1F"}

package/dist/server/index.js

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

package/dist/update-diagnostics.d.ts

@@ -0,0 +1,136 @@
+/**
+ * Update diagnostics capture.
+ *
+ * Every `omni update` invocation writes a structured JSON report to
+ * `~/.omni/logs/update-diagnostics-<iso>.json` capturing the install attempt,
+ * registry probe, restart, verify outcome, cleanup registry result,
+ * maintenance hook, and a tail of recent pm2 log signals. The file is the
+ * canonical post-mortem artifact: operators paste it into bug reports; the
+ * shape mirrors the genie wish (independent code, parity per
+ * `SHARED-DESIGN.md` decision #3) so a shared diagnostics consumer can read
+ * either CLI's output uniformly. omni starts at `schemaVersion: 1` (decision
+ * #4 in the wish: per-repo schema versions are intentionally asymmetric).
+ *
+ * The writer is best-effort: any failure (no perms, disk full, etc.) is
+ * swallowed so update never exits non-zero because diagnostics couldn't be
+ * persisted.
+ */
+import type { MaintenanceReport, UpdateChannel, VerifyResult } from './commands/update.js';
+import type { CleanupReport } from './legacy-cleanup.js';
+/** Stable schema version for omni-side update diagnostics. */
+export declare const UPDATE_DIAGNOSTICS_SCHEMA_VERSION: 1;
+/** Captured tail of one pm2 log file (best-effort). */
+export interface LogSignal {
+    /** Tracked pm2 process name (e.g. `omni-v2-api`). */
+    source: string;
+    /** Which file (`out` or `error`). */
+    stream: 'out' | 'error';
+    /** Up to N most recent lines, oldest first. Empty when the file does not exist. */
+    lines: string[];
+}
+/**
+ * Outcome of the parallel npm-global install probe (Group 5a). Omni doesn't
+ * support npm-global server, but a parallel install hides stale binaries on
+ * PATH and confuses `which omni`. Captured here so a future bug report
+ * includes the smoking-gun path.
+ */
+export interface ParallelInstallReport {
+    detected: boolean;
+    /** Filesystem path to the parallel install (when detected). */
+    path?: string;
+    /** Reason detection couldn't run, e.g. `npm` not on PATH. */
+    skipped?: string;
+}
+/** Top-level diagnostics record. */
+export interface UpdateDiagnostics {
+    readonly schemaVersion: typeof UPDATE_DIAGNOSTICS_SCHEMA_VERSION;
+    /** ISO-8601 timestamp the run started at (filename derives from this). */
+    startedAt: string;
+    /** ISO-8601 timestamp diagnostics was finalized (= just before write). */
+    finishedAt: string;
+    cli: {
+        /** CLI version executing this update (the previous one — install hasn't restarted us). */
+        runningVersion: string;
+        channel: UpdateChannel;
+    };
+    registry: {
+        latestVersion: string | null;
+    };
+    preflight: {
+        /** Did the canonical-pgserve phase-2 check run? False when `--skip-canonical-preflight`. */
+        ran: boolean;
+        /** Did the check return a blocking error? When true, the run aborted. */
+        blocked: boolean;
+        /** First line of the rendered error message, when blocked. */
+        reason?: string;
+    };
+    install: {
+        attempted: boolean;
+        succeeded: boolean | null;
+        targetVersion: string | null;
+    };
+    restart: {
+        attempted: boolean;
+        succeeded: boolean | null;
+        services: string[];
+    };
+    verify: VerifyResult | null;
+    cleanups: CleanupReport | null;
+    maintenance: MaintenanceReport | null;
+    parallelNpmGlobal: ParallelInstallReport | null;
+    recentLogSignals: LogSignal[];
+    /** Final exit code — populated by the writer; useful for bug-report triage. */
+    exitCode: number;
+}
+/**
+ * Build a fresh diagnostics state with the invariant fields populated.
+ * Mutated in-place by `runUpdate` as it advances through the pipeline.
+ */
+export declare function createDiagnostics(args: {
+    runningVersion: string;
+    channel: UpdateChannel;
+}): UpdateDiagnostics;
+/** Get the directory diagnostics are written to. Honors `OMNI_CONFIG_DIR`. */
+export declare function getDiagnosticsDir(): string;
+/**
+ * Compute the canonical filename for a diagnostics record. The ISO timestamp
+ * is sanitized to be filename-safe (`:` → `-`).
+ */
+export declare function getDiagnosticsPath(startedAt: string): string;
+/**
+ * Read the last `maxLines` lines of a UTF-8 text file. Best-effort: returns
+ * an empty array on any error (missing file, perms, decoding issue).
+ *
+ * Implementation notes:
+ *   - We slurp the whole file (pm2 log files are small in steady state and
+ *     log-rotated by pm2-logrotate; reading the whole thing is simpler than
+ *     a reverse-byte tail and avoids edge cases on multi-byte UTF-8).
+ *   - Trailing empty line from a trailing newline is dropped.
+ */
+export declare function tailFileLines(path: string, maxLines: number): string[];
+/**
+ * Collect the most recent log lines from each tracked pm2 process. Skips
+ * processes whose log files don't exist (i.e. that have never run on this
+ * host). Limited to `maxLinesPerStream` per file to keep diagnostics small.
+ *
+ * `logPathsFor` is injectable so tests can point at a tmp dir without
+ * touching the developer's real `~/.omni/logs` (pm2 log paths don't honor
+ * `OMNI_CONFIG_DIR` and we'd rather not change that surface here).
+ *
+ * This is best-effort and called from the diagnostics writer; never throws.
+ */
+export declare function collectRecentLogSignals(maxLinesPerStream?: number, logPathsFor?: (name: string) => {
+    out: string;
+    error: string;
+}): LogSignal[];
+/**
+ * Persist the diagnostics record to `~/.omni/logs/update-diagnostics-*.json`.
+ * Returns the path that was written (or null on failure). Never throws —
+ * diagnostics is observability, not load-bearing for the update outcome.
+ *
+ * The exit code is captured into `state.exitCode` and the timestamp into
+ * `state.finishedAt` before serialization so the JSON file is a complete
+ * snapshot at write time.
+ */
+export declare function writeDiagnostics(state: UpdateDiagnostics, exitCode: number): string | null;
+//# sourceMappingURL=update-diagnostics.d.ts.map

package/dist/update-diagnostics.d.ts.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@automagik/omni",
-  "version": "2.260504.2",
+  "version": "2.260505.2",
   "description": "LLM-optimized CLI for Omni",
   "type": "module",
   "bin": {
@@ -51,15 +51,15 @@
     "qrcode-terminal": "^0.12.0"
   },
   "devDependencies": {
-    "@omni/api": "2.260504.1",
-    "@omni/channel-discord": "2.260504.1",
-    "@omni/channel-gupshup": "2.260504.1",
-    "@omni/channel-sdk": "2.260504.1",
-    "@omni/channel-slack": "2.260504.1",
-    "@omni/channel-telegram": "2.260504.1",
-    "@omni/channel-whatsapp": "2.260504.1",
-    "@omni/core": "2.260504.1",
-    "@omni/sdk": "2.260504.1",
+    "@omni/api": "2.260505.1",
+    "@omni/channel-discord": "2.260505.1",
+    "@omni/channel-gupshup": "2.260505.1",
+    "@omni/channel-sdk": "2.260505.1",
+    "@omni/channel-slack": "2.260505.1",
+    "@omni/channel-telegram": "2.260505.1",
+    "@omni/channel-whatsapp": "2.260505.1",
+    "@omni/core": "2.260505.1",
+    "@omni/sdk": "2.260505.1",
     "@types/node": "^22.10.3",
     "@types/qrcode-terminal": "^0.12.2",
     "typescript": "^5.7.3"