@remnic/core 9.3.688 → 9.3.690

package/src/maintenance/namespace-maintenance-fanout.ts

@@ -0,0 +1,318 @@
+/**
+ * Namespace maintenance fanout coordinator (issue #1500).
+ *
+ * Builds on the namespace-aware maintenance planner (#1499 / #1517) to fan out
+ * the REMAINING background maintenance jobs — dreams, pattern reinforcement,
+ * governance/lifecycle, contradiction scans, semantic/causal consolidation,
+ * graph decay, fact archival, tier migration — across all maintained
+ * namespaces.
+ *
+ * The planner (`namespace-planner.ts`) already handles namespace discovery
+ * (configured + catalog), per-kind gating, cycle budgeting, per-job+namespace
+ * locking, status recording, and catalog maintenance timestamps. QMD
+ * maintenance was wired through it in #1517. This module standardizes the
+ * per-job adapter pattern so every other maintenance job can be fanned out
+ * with one call, and aggregates per-namespace health for doctor/dashboard.
+ *
+ * Design contract (issue #1500 compatibility requirements):
+ * - Existing direct `runJob({ namespace })` calls continue to work unchanged.
+ * - Namespaces disabled: fanout is a no-op (the planner returns only the
+ *   default namespace; jobs run exactly as before).
+ * - `maintenanceNamespaceFanoutEnabled: false`: fanout is a no-op.
+ * - A failure in one namespace must not abort other namespaces (the planner
+ *   already isolates per-namespace failures).
+ * - Per-namespace locks prevent duplicate concurrent runs (planner-provided).
+ */
+
+import type { NamespaceCatalog } from "../namespaces/catalog.js";
+import type { PluginConfig } from "../types.js";
+import {
+  planNamespaceMaintenance,
+  readNamespaceMaintenanceLastRanStatuses,
+  readNamespaceMaintenanceStatuses,
+  runNamespaceMaintenancePlan,
+  type NamespaceMaintenanceCandidate,
+  type NamespaceMaintenanceRunStatus,
+  type NamespaceMaintenanceSummary,
+} from "./namespace-planner.js";
+
+/**
+ * Standard maintenance job names fanned out across namespaces.
+ *
+ * These strings are used as the `jobName` key in:
+ * - per-namespace status files (`state/namespace-maintenance-status/<job>/...`)
+ * - catalog `lastMaintenanceAt[jobName]` timestamps
+ * - per-job+namespace lock files (`state/maintenance-locks/<job>/...`)
+ *
+ * Keeping them centralized ensures the doctor, CLI, and dashboard all report
+ * against the same keys.
+ */
+export const NAMESPACE_MAINTENANCE_JOBS = [
+  "qmd",
+  "pattern-reinforcement",
+  "contradiction-scan",
+  "semantic-consolidation",
+  "governance",
+  "lifecycle",
+  "graph-decay",
+  "fact-archival",
+  "tier-migration",
+] as const;
+
+export type NamespaceMaintenanceStandardJob =
+  (typeof NAMESPACE_MAINTENANCE_JOBS)[number];
+
+/**
+ * Context passed to a fanout job runner. The runner receives the per-namespace
+ * candidate (namespace name, kind, storage dir) and a storage resolver that
+ * the orchestrator wires to `storageRouter.storageFor(namespace)`.
+ *
+ * The storage resolver is intentionally typed as `unknown` here so this module
+ * does not depend on the `StorageManager` class — the orchestrator provides the
+ * typed resolver. This keeps the fanout module free of orchestrator/storage
+ * imports and unit-testable with a stub.
+ */
+export interface NamespaceMaintenanceFanoutRunnerContext {
+  config: PluginConfig;
+  candidate: NamespaceMaintenanceCandidate;
+  resolveStorage: (namespace: string) => Promise<unknown>;
+}
+
+/**
+ * Result returned by a fanout job runner. `itemCount` is optional and
+ * domain-specific (e.g. memories scanned, edges decayed, embeddings updated).
+ *
+ * `skipped`/`skipReason`: when a runner performs no work for a namespace
+ * (e.g. the job's own cadence gate throttled it), set `skipped: true`. The
+ * planner records the namespace as `state: "skipped"` and does NOT touch
+ * the catalog's `lastMaintenanceAt`, so a throttled namespace is not
+ * falsely reported as maintained.
+ */
+export interface NamespaceMaintenanceFanoutRunnerResult {
+  itemCount?: number;
+  skipped?: boolean;
+  skipReason?: string;
+}
+
+export type NamespaceMaintenanceFanoutRunner = (
+  ctx: NamespaceMaintenanceFanoutRunnerContext,
+) => Promise<NamespaceMaintenanceFanoutRunnerResult | undefined>;
+
+export interface RunNamespaceMaintenanceFanoutOptions {
+  config: PluginConfig;
+  catalog?: NamespaceCatalog;
+  jobName: string;
+  runner: NamespaceMaintenanceFanoutRunner;
+  resolveStorage: (namespace: string) => Promise<unknown>;
+  /**
+   * When `false`, skip fanout entirely and return a zero-summary without
+   * touching the planner or locks. This lets callers gate fanout on
+   * per-job config (e.g. `semanticConsolidationEnabled`) without repeating
+   * the namespace-discovery logic.
+   */
+  enabled?: boolean;
+}
+
+/**
+ * Fan out a single maintenance job across all maintained namespaces.
+ *
+ * This is the primary entry point for wiring a maintenance job through the
+ * namespace-aware planner. It:
+ * 1. Plans which namespaces should be maintained (configured + catalog,
+ *    budgeted, kind-gated).
+ * 2. Runs the job per-namespace through `runNamespaceMaintenancePlan`, which
+ *    acquires per-job+namespace locks, records status files, and touches the
+ *    catalog's `lastMaintenanceAt`.
+ *
+ * When namespaces are disabled or fanout is off, the planner returns only the
+ * default namespace, so the job runs exactly once against default storage —
+ * preserving single-user behavior.
+ */
+export async function runNamespaceMaintenanceFanout(
+  options: RunNamespaceMaintenanceFanoutOptions,
+): Promise<NamespaceMaintenanceSummary> {
+  if (options.enabled === false) {
+    return {
+      jobName: options.jobName,
+      generatedAt: new Date().toISOString(),
+      ran: 0,
+      skipped: 0,
+      failed: 0,
+      statuses: [],
+    };
+  }
+
+  const plan = await planNamespaceMaintenance(options.config, {
+    jobName: options.jobName,
+    catalog: options.catalog,
+  });
+
+  return runNamespaceMaintenancePlan(
+    options.config,
+    plan,
+    async (candidate) => {
+      return options.runner({
+        config: options.config,
+        candidate,
+        resolveStorage: options.resolveStorage,
+      });
+    },
+    options.catalog,
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Health summary for doctor / dashboard / CLI
+// ---------------------------------------------------------------------------
+
+export interface NamespaceMaintenanceJobHealth {
+  jobName: string;
+  ran: number;
+  skipped: number;
+  failed: number;
+  lastRunAt: string | null;
+  namespaces: NamespaceMaintenanceRunStatus[];
+}
+
+export interface NamespaceMaintenanceHealthSummary {
+  generatedAt: string;
+  fanoutEnabled: boolean;
+  namespacesEnabled: boolean;
+  maxNamespacesPerCycle: number;
+  jobs: NamespaceMaintenanceJobHealth[];
+  totalRan: number;
+  totalSkipped: number;
+  totalFailed: number;
+}
+
+/**
+ * Read all per-namespace maintenance status files and aggregate them into a
+ * health summary suitable for `remnic doctor` and the admin dashboard.
+ *
+ * This is a pure read operation — it never runs maintenance or acquires locks.
+ */
+export async function summarizeNamespaceMaintenanceHealth(
+  config: PluginConfig,
+): Promise<NamespaceMaintenanceHealthSummary> {
+  const generatedAt = new Date().toISOString();
+  const statuses = await readNamespaceMaintenanceStatuses(config);
+  // Merge last-successful-run records so lastRunAt reflects the most recent
+  // successful maintenance, not just the latest (possibly skipped/failed)
+  // outcome. The latest status file is overwritten on every run; without
+  // this merge a namespace that ran then got budget-skipped shows ran=0 /
+  // lastRunAt=null (review #1622: preserve last successful run).
+  const lastRanStatuses = await readNamespaceMaintenanceLastRanStatuses(config);
+  const lastRanByJobNs = new Map<string, NamespaceMaintenanceRunStatus>();
+  for (const lr of lastRanStatuses) {
+    lastRanByJobNs.set(`${lr.jobName}\u0000${lr.namespace}`, lr);
+  }
+
+  const byJob = new Map<string, NamespaceMaintenanceRunStatus[]>();
+  for (const status of statuses) {
+    const bucket = byJob.get(status.jobName);
+    if (bucket) {
+      bucket.push(status);
+    } else {
+      byJob.set(status.jobName, [status]);
+    }
+  }
+
+  const knownJobs = new Set<string>(NAMESPACE_MAINTENANCE_JOBS);
+  // Include any job names seen in status files that are not in the standard
+  // set (e.g. custom jobs registered by the orchestrator) so the doctor does
+  // not silently hide them.
+  for (const jobName of byJob.keys()) {
+    knownJobs.add(jobName);
+  }
+
+  const jobs: NamespaceMaintenanceJobHealth[] = [];
+  let totalRan = 0;
+  let totalSkipped = 0;
+  let totalFailed = 0;
+
+  for (const jobName of [...knownJobs].sort()) {
+    const jobStatuses = byJob.get(jobName) ?? [];
+    const ran = jobStatuses.filter((s) => s.state === "ran").length;
+    const skipped = jobStatuses.filter((s) => s.state === "skipped").length;
+    const failed = jobStatuses.filter((s) => s.state === "failed").length;
+    // Consider BOTH the latest outcome and the last successful run so a
+    // namespace that ran then was later skipped still reports lastRunAt.
+    const candidates: string[] = [];
+    for (const st of jobStatuses) {
+      if (typeof st.completedAt === "string") candidates.push(st.completedAt);
+      const lr = lastRanByJobNs.get(`${jobName}\u0000${st.namespace}`);
+      if (lr && typeof lr.completedAt === "string") candidates.push(lr.completedAt);
+    }
+    const lastRunAt = candidates.sort().at(-1) ?? null;
+
+    totalRan += ran;
+    totalSkipped += skipped;
+    totalFailed += failed;
+
+    jobs.push({
+      jobName,
+      ran,
+      skipped,
+      failed,
+      lastRunAt,
+      namespaces: jobStatuses,
+    });
+  }
+
+  return {
+    generatedAt,
+    fanoutEnabled: config.maintenanceNamespaceFanoutEnabled !== false,
+    namespacesEnabled: config.namespacesEnabled,
+    maxNamespacesPerCycle: config.maintenanceMaxNamespacesPerCycle,
+    jobs,
+    totalRan,
+    totalSkipped,
+    totalFailed,
+  };
+}
+
+/**
+ * Format the health summary as human-readable text for the CLI.
+ */
+export function formatNamespaceMaintenanceHealthText(
+  summary: NamespaceMaintenanceHealthSummary,
+): string {
+  const lines: string[] = [
+    "=== Namespace Maintenance ===",
+    "",
+    `  fanout:        ${summary.fanoutEnabled ? "enabled" : "disabled"}`,
+    `  namespaces:    ${summary.namespacesEnabled ? "enabled" : "disabled"}`,
+    `  max/cycle:     ${summary.maxNamespacesPerCycle}`,
+    `  total ran:     ${summary.totalRan}`,
+    `  total skipped: ${summary.totalSkipped}`,
+    `  total failed:  ${summary.totalFailed}`,
+    "",
+  ];
+
+  if (summary.totalRan === 0 && summary.totalSkipped === 0 && summary.totalFailed === 0) {
+    lines.push("  (no maintenance status recorded yet)");
+    return lines.join("\n");
+  }
+
+  lines.push("  Per-job breakdown:");
+  for (const job of summary.jobs) {
+    const parts = [
+      `ran=${job.ran}`,
+      `skipped=${job.skipped}`,
+      `failed=${job.failed}`,
+    ];
+    if (job.lastRunAt) {
+      parts.push(`last=${job.lastRunAt}`);
+    }
+    lines.push(`    ${job.jobName}: ${parts.join(", ")}`);
+    // Surface failed namespaces with their reason/error so operators know
+    // WHAT to fix without rerunning with --json (review #1622).
+    const failedNs = job.namespaces.filter((n) => n.state === "failed");
+    for (const ns of failedNs) {
+      const detail = ns.error ? `: ${ns.error}` : "";
+      lines.push(`      ! ${ns.namespace} failed (reason=${ns.reason ?? "unknown"})${detail}`);
+    }
+  }
+
+  return lines.join("\n");
+}

package/src/maintenance/namespace-planner.ts

@@ -213,7 +213,14 @@ export async function planNamespaceMaintenance(
   options: NamespaceMaintenancePlannerOptions
 ): Promise<NamespaceMaintenancePlan> {
   const generatedAt = (options.now ?? new Date()).toISOString();
-  const configured = configuredNamespaces(config);
+  // When namespaces are disabled, storageFor() collapses every namespace name
+  // to config.memoryDir. Seeding all configured namespaces (default + shared +
+  // policies) would make a mutating maintenance job process the SAME corpus
+  // once per configured name. The #1500 contract is "namespaces disabled:
+  // maintain the current default storage only," so collapse to the default.
+  const configured = config.namespacesEnabled
+    ? configuredNamespaces(config)
+    : [config.defaultNamespace.trim()].filter(Boolean);
   const byNamespace = new Map<string, NamespaceMaintenanceCandidate>();
   const skipped: NamespaceMaintenanceSkippedNamespace[] = [];
 
@@ -640,10 +647,44 @@ export async function readNamespaceMaintenanceStatuses(config: PluginConfig): Pr
   });
 }
 
+/**
+ * Read the last SUCCESSFUL run status per job+namespace (the
+ * `<namespace>.last-ran.json` files written only when state === "ran").
+ *
+ * The latest status file (`<namespace>.json`) is overwritten on every run,
+ * so after a successful run followed by a skip (budget/lock/cadence) the
+ * latest file shows "skipped" and the prior success is invisible. Merging
+ * these last-ran records into the health summary lets `lastRunAt` and run
+ * history reflect the most recent successful maintenance (review #1622).
+ */
+export async function readNamespaceMaintenanceLastRanStatuses(
+  config: PluginConfig,
+): Promise<NamespaceMaintenanceRunStatus[]> {
+  return (await readLastRanStatusFiles(config)).sort((a, b) => {
+    const byJob = a.jobName.localeCompare(b.jobName);
+    if (byJob !== 0) return byJob;
+    return a.namespace.localeCompare(b.namespace);
+  });
+}
+
+export type NamespaceMaintenancePlanRunnerResult = {
+  itemCount?: number;
+  /**
+   * When `true`, the runner performed NO work for this namespace (e.g. the
+   * job's own cadence gate throttled it). The planner records the namespace
+   * as `state: "skipped"` with the given reason and does NOT touch the
+   * catalog's `lastMaintenanceAt`, so a throttled namespace is not falsely
+   * reported as maintained. Without this signal a runner that resolves
+   * without throwing is always recorded as `state: "ran"`.
+   */
+  skipped?: boolean;
+  skipReason?: string;
+} | undefined;
+
 export async function runNamespaceMaintenancePlan(
   config: PluginConfig,
   plan: NamespaceMaintenancePlan,
-  runner: (candidate: NamespaceMaintenanceCandidate) => Promise<{ itemCount?: number } | undefined>,
+  runner: (candidate: NamespaceMaintenanceCandidate) => Promise<NamespaceMaintenancePlanRunnerResult>,
   catalog?: NamespaceCatalog
 ): Promise<NamespaceMaintenanceSummary> {
   const statuses: NamespaceMaintenanceRunStatus[] = [];
@@ -683,20 +724,37 @@ export async function runNamespaceMaintenancePlan(
     try {
       const result = await withNamespaceMaintenanceLockHeartbeat(config, lock, () => runner(candidate));
       const completedAt = new Date().toISOString();
-      const status: NamespaceMaintenanceRunStatus = {
-        namespace: candidate.namespace,
-        jobName: plan.jobName,
-        state: "ran",
-        startedAt,
-        completedAt,
-        itemCount: result?.itemCount,
-      };
-      statuses.push(status);
-      await recordNamespaceMaintenanceStatusSafely(config, status);
-      try {
-        await catalog?.markMaintenance(candidate.namespace, plan.jobName, new Date(completedAt));
-      } catch {
-        // Catalog maintenance touches are best-effort status metadata.
+      if (result?.skipped) {
+        // The runner performed no work (e.g. the job's own cadence gate
+        // throttled this namespace). Record skipped WITHOUT touching the
+        // catalog's lastMaintenanceAt so a throttled namespace is not
+        // falsely reported as maintained.
+        const status: NamespaceMaintenanceRunStatus = {
+          namespace: candidate.namespace,
+          jobName: plan.jobName,
+          state: "skipped",
+          reason: (result.skipReason ?? "throttled") as NamespaceMaintenanceSkipReason,
+          startedAt,
+          completedAt,
+        };
+        statuses.push(status);
+        await recordNamespaceMaintenanceStatusSafely(config, status);
+      } else {
+        const status: NamespaceMaintenanceRunStatus = {
+          namespace: candidate.namespace,
+          jobName: plan.jobName,
+          state: "ran",
+          startedAt,
+          completedAt,
+          itemCount: result?.itemCount,
+        };
+        statuses.push(status);
+        await recordNamespaceMaintenanceStatusSafely(config, status);
+        try {
+          await catalog?.markMaintenance(candidate.namespace, plan.jobName, new Date(completedAt));
+        } catch {
+          // Catalog maintenance touches are best-effort status metadata.
+        }
       }
     } catch (error) {
       const completedAt = new Date().toISOString();

package/src/operator-toolkit.ts

@@ -12,6 +12,7 @@ import {
 } from "./native-knowledge.js";
 import { StorageManager } from "./storage.js";
 import { listNamespaces } from "./namespaces/migrate.js";
+import { summarizeNamespaceMaintenanceHealth } from "./maintenance/namespace-maintenance-fanout.js";
 import {
   createEvalBaselineSnapshot,
   getEvalHarnessStatus,
@@ -1301,6 +1302,30 @@ export async function runOperatorDoctor(options: OperatorDoctorOptions): Promise
   // state and is never an error.
   checks.push(await summarizeObservationThroughput(config.memoryDir));
 
+  // Namespace maintenance fanout status (issue #1500).
+  // Reports per-job+namespace maintenance outcomes (ran/skipped/failed) so
+  // operators can verify that dynamic project/team namespaces are being
+  // maintained. Informational: never errors on its own — a namespace that has
+  // never been maintained is the expected cold-install state.
+  const namespaceMaintenanceHealth = await summarizeNamespaceMaintenanceHealth(config);
+  checks.push({
+    key: "namespace_maintenance",
+    status: namespaceMaintenanceHealth.totalFailed > 0 ? "warn" : "ok",
+    summary:
+      namespaceMaintenanceHealth.totalRan === 0 && namespaceMaintenanceHealth.totalFailed === 0
+        ? "No namespace maintenance recorded yet (expected for a fresh install)."
+        : `${namespaceMaintenanceHealth.totalRan} namespace maintenance run(s)` +
+          (namespaceMaintenanceHealth.totalFailed > 0
+            ? `, ${namespaceMaintenanceHealth.totalFailed} failure(s) across ${namespaceMaintenanceHealth.jobs.filter((j) => j.failed > 0).length} job(s)`
+            : "") +
+          ".",
+    remediation:
+      namespaceMaintenanceHealth.totalFailed > 0
+        ? "Run `remnic namespaces maintenance` for per-namespace details."
+        : undefined,
+    details: namespaceMaintenanceHealth,
+  });
+
   const summary = checks.reduce(
     (acc, check) => {
       acc[check.status] += 1;

package/src/orchestrator.ts

@@ -318,7 +318,14 @@ import {
   runNamespaceMaintenanceBatchPlan,
   type NamespaceMaintenancePlan,
   type NamespaceMaintenanceSkipReason,
+  type NamespaceMaintenanceSummary,
 } from "./maintenance/namespace-planner.js";
+import {
+  runNamespaceMaintenanceFanout,
+  summarizeNamespaceMaintenanceHealth,
+  type NamespaceMaintenanceFanoutRunnerContext,
+  type NamespaceMaintenanceHealthSummary,
+} from "./maintenance/namespace-maintenance-fanout.js";
 import {
   namespaceIdentityFromToken,
   namespaceIdentityToken,
@@ -2483,6 +2490,42 @@ export class Orchestrator {
     return plan.namespaces.map((candidate) => candidate.namespace);
   }
 
+  /**
+   * Fan out a maintenance job across all maintained namespaces (issue #1500).
+   *
+   * Delegates to the namespace-maintenance-fanout coordinator, which plans
+   * namespace discovery (configured + catalog), applies the cycle budget,
+   * acquires per-job+namespace locks, records status files, and touches the
+   * catalog's `lastMaintenanceAt`. The runner receives a per-namespace
+   * candidate and a storage resolver wired to `this.getStorage(namespace)`.
+   *
+   * When namespaces are disabled the planner returns only the default
+   * namespace, so the job runs exactly once — preserving single-user behavior.
+   */
+  async runNamespaceMaintenanceFanoutForJob(
+    jobName: string,
+    runner: (ctx: NamespaceMaintenanceFanoutRunnerContext) => Promise<{ itemCount?: number } | undefined>,
+    options: { enabled?: boolean } = {},
+  ): Promise<NamespaceMaintenanceSummary> {
+    return runNamespaceMaintenanceFanout({
+      config: this.config,
+      catalog: this.namespaceCatalog,
+      jobName,
+      runner,
+      resolveStorage: (namespace) => this.getStorage(namespace),
+      enabled: options.enabled,
+    });
+  }
+
+  /**
+   * Read-only namespace maintenance health summary for doctor / dashboard /
+   * CLI (issue #1500). Aggregates all per-namespace maintenance status files
+   * into one report without running any maintenance.
+   */
+  async readNamespaceMaintenanceHealth(): Promise<NamespaceMaintenanceHealthSummary> {
+    return summarizeNamespaceMaintenanceHealth(this.config);
+  }
+
   private buildConfiguredQmdSearchOptions(
     queryText: string,
   ): SearchQueryOptions | undefined {
@@ -3998,6 +4041,107 @@ export class Orchestrator {
     return { ran: true, result, namespace: cadenceKey };
   }
 
+  /**
+   * Fan out pattern reinforcement across all maintained namespaces (issue #1500).
+   * Delegates per-namespace execution to {@link runPatternReinforcement} while
+   * the planner handles discovery, budgeting, locking, and status recording.
+   * When namespaces are disabled, runs once against default storage.
+   */
+  async runPatternReinforcementFanout(options: {
+    force?: boolean;
+  } = {}): Promise<NamespaceMaintenanceSummary> {
+    return this.runNamespaceMaintenanceFanoutForJob(
+      "pattern-reinforcement",
+      async (ctx) => {
+        const result = await this.runPatternReinforcement({
+          namespace: ctx.candidate.namespace,
+          force: options.force,
+        });
+        // runPatternReinforcement has its own per-namespace cadence gate
+        // (lastPatternReinforcementAtByNs). When it throttles (ran:false),
+        // signal skip so the planner records state:"skipped" and does NOT
+        // touch lastMaintenanceAt — otherwise a throttled namespace would
+        // look maintained while pattern reinforcement never ran (#1500
+        // review: cadence-skip accuracy).
+        if (!result.ran) {
+          return {
+            skipped: true,
+            skipReason: result.skippedReason ?? "throttled",
+          };
+        }
+        return result.result
+          ? { itemCount: result.result.clustersFound }
+          : { itemCount: 0 };
+      },
+      { enabled: this.config.patternReinforcementEnabled },
+    );
+  }
+
+  /**
+   * Fan out lifecycle/governance policy across all maintained namespaces
+   * (issue #1500). Each namespace gets its own lifecycle pass against its
+   * namespace-scoped storage. When namespaces are disabled, runs once against
+   * default storage.
+   */
+  async runLifecyclePolicyFanout(): Promise<NamespaceMaintenanceSummary> {
+    return this.runNamespaceMaintenanceFanoutForJob(
+      "lifecycle",
+      async (ctx) => {
+        const storage = await this.getStorage(ctx.candidate.namespace);
+        const corpus = await storage.readAllMemories();
+        const assessed = await this.runLifecyclePolicyPass(corpus, storage);
+        return { itemCount: assessed };
+      },
+      { enabled: this.config.lifecyclePolicyEnabled },
+    );
+  }
+
+  /**
+   * Fan out semantic consolidation across all maintained namespaces (issue #1500).
+   * Each namespace gets its own consolidation pass against its namespace-scoped
+   * storage. When namespaces are disabled, runs once against default storage.
+   */
+  async runSemanticConsolidationFanout(options: {
+    dryRun?: boolean;
+  } = {}): Promise<NamespaceMaintenanceSummary> {
+    return this.runNamespaceMaintenanceFanoutForJob(
+      "semantic-consolidation",
+      async (ctx) => {
+        const storage = await this.getStorage(ctx.candidate.namespace);
+        const result = await this.runSemanticConsolidation({
+          dryRun: options.dryRun,
+          thresholdOverride: undefined,
+          force: true,
+          storage,
+        });
+        return { itemCount: result.clustersFound };
+      },
+      { enabled: this.config.semanticConsolidationEnabled },
+    );
+  }
+
+  /**
+   * Fan out deep-sleep governance across all maintained namespaces (issue #1500).
+   * Each namespace gets its own governance scan against its namespace-scoped
+   * storage. When namespaces are disabled, runs once against default storage.
+   */
+  async runDeepSleepGovernanceFanout(options: {
+    dryRun?: boolean;
+  } = {}): Promise<NamespaceMaintenanceSummary> {
+    return this.runNamespaceMaintenanceFanoutForJob(
+      "governance",
+      async (ctx) => {
+        const storage = await this.getStorage(ctx.candidate.namespace);
+        const result = await this.runDeepSleepGovernanceNow({
+          dryRun: options.dryRun,
+          storage,
+        });
+        return { itemCount: result.scannedMemories };
+      },
+      { enabled: this.config.dreamsPhases.deepSleep.enabled },
+    );
+  }
+
   private async autoRegisterGraphEdgeDecayCron(): Promise<void> {
     const home = resolveHomeDir();
     const jobsPath = path.join(home, ".openclaw", "cron", "jobs.json");