sizmo 0.4.1 → 0.5.0

package/commands/snapshot.mjs

@@ -2,8 +2,11 @@
 // Trust-fix #1: LOC from ctx.cfg.loc (no baked default).
 // Trust-fix #2: leads() and revenue() paginate to completion.
 // Trust-fix #3: revenue tracks per-currency (never cross-sums).
+// v0.5.0: calendar list from CRM model; location currency from model.
+// v0.6.0 (C2): modelMeta emitted in JSON envelope; TTY staleness note.
 import { paginate } from '../lib/paginate.mjs';
 import { mapLimit } from '../lib/pool.mjs';
+import { ENTITY_SPECS } from '../lib/model.mjs';
 
 export const meta = {
   name: 'snapshot',
@@ -31,6 +34,35 @@ export async function collect(args, ctx) {
     return Number.isFinite(t) && t >= START && t <= NOW;
   };
 
+  // Location currency from CRM model (fallback PHP if model missing/blocked)
+  let locationCurrency = 'PHP';
+  let _snapshotModelLoaded = null;
+  let modelMeta = null;
+  if (ctx.ensureModel) {
+    try {
+      _snapshotModelLoaded = await ctx.ensureModel();
+      const locCur = _snapshotModelLoaded?.entities?.location?.item?.business?.currency
+        || _snapshotModelLoaded?.entities?.location?.item?.currency;
+      if (locCur) locationCurrency = locCur.toUpperCase();
+    } catch { /* use default */ }
+  } else if (ctx.cfg.currency) {
+    locationCurrency = ctx.cfg.currency;
+  }
+  // Build modelMeta for the JSON envelope (C2)
+  if (_snapshotModelLoaded) {
+    const specMap = Object.fromEntries(ENTITY_SPECS.map(s => [s.name, s]));
+    // Check calendars staleness (the main model-sourced entity in snapshot)
+    const calEnt = _snapshotModelLoaded.entities?.calendars;
+    const calSpec = specMap.calendars;
+    const calStale = calEnt && calSpec ? (NOW - (calEnt.fetchedAt ?? 0)) > calSpec.ttlMs : false;
+    modelMeta = {
+      syncedAt: _snapshotModelLoaded.syncedAt,
+      ageMs: NOW - _snapshotModelLoaded.syncedAt,
+      stale: calStale,
+      offline: !!(_snapshotModelLoaded.offline),
+    };
+  }
+
   // ── LEADS: paginate contacts newest→older, stop past window ──
   async function leads() {
     let count = 0, pages = 0, oldest = null;
@@ -78,12 +110,27 @@ export async function collect(args, ctx) {
   // Full fix = date-window splitting; tracked as follow-up. Cheap mitigation: warn + degrade.
   const EVENTS_CAP = 100;
   async function bookings() {
-    const cr = await ctx.http.get('/calendars/', { query: { locationId: LOC }, version: '2021-04-15' });
-    if (!cr.ok) return [
-      metric('Bookings', null, { blocked: true, blocker: `calendars list HTTP ${cr.code}` }),
-      metric('Show rate', null, { blocked: true, blocker: 'no calendars' }),
-    ];
-    const cals = cr.j.calendars || [];
+    // Get calendar list from the CRM model if available; fall back to live fetch.
+    // Use _snapshotModelLoaded already loaded above — no second ensureModel call.
+    let cals = null;
+    if (_snapshotModelLoaded?.entities?.calendars && !_snapshotModelLoaded.entities.calendars.blocked && !_snapshotModelLoaded.entities.calendars.networkError) {
+      cals = _snapshotModelLoaded.entities.calendars.items ?? [];
+    } else if (!_snapshotModelLoaded && ctx.ensureModel) {
+      try {
+        const model = await ctx.ensureModel();
+        if (model?.entities?.calendars && !model.entities.calendars.blocked && !model.entities.calendars.networkError) {
+          cals = model.entities.calendars.items ?? [];
+        }
+      } catch { /* fall through to live fetch */ }
+    }
+    if (cals === null) {
+      const cr = await ctx.http.get('/calendars/', { query: { locationId: LOC }, version: '2021-04-15' });
+      if (!cr.ok) return [
+        metric('Bookings', null, { blocked: true, blocker: `calendars list HTTP ${cr.code}` }),
+        metric('Show rate', null, { blocked: true, blocker: 'no calendars' }),
+      ];
+      cals = cr.j.calendars || [];
+    }
     let booked = 0, showed = 0, noshow = 0, calsHit = 0, skippedCalendars = 0;
     // Parallel fan-out, capped at 5 concurrent (GHL rate-limit-safe: 100 req/10s; 5 concurrent is well under).
     // ONLY the independent per-calendar fetches are parallelized — pagination pages stay sequential.
@@ -152,7 +199,7 @@ export async function collect(args, ctx) {
       const when = t.createdAt || t.created_at || t.dateAdded;
       const ok = (t.status || t.paymentStatus || '').toLowerCase();
       if (inWindow(when) && (ok === 'succeeded' || ok === 'success' || ok === 'paid' || ok === 'completed' || ok === 'captured')) {
-        const cur = (t.currency || 'PHP').toUpperCase();
+        const cur = (t.currency || locationCurrency).toUpperCase();
         byCur[cur] = byCur[cur] || { sum: 0, n: 0 };
         byCur[cur].sum += Number(t.amount) || 0;
         byCur[cur].n++;
@@ -163,7 +210,7 @@ export async function collect(args, ctx) {
     // If only one currency, match original format; multi-currency → list all
     const entries = Object.entries(byCur);
     if (entries.length === 0)
-      return metric('Collected', money(0, 'PHP'), { note: `0 payment(s) · ${totalScanned} txns scanned` });
+      return metric('Collected', money(0, locationCurrency), { note: `0 payment(s) · ${totalScanned} txns scanned` });
     if (entries.length === 1) {
       const [cur, { sum, n }] = entries[0];
       return metric('Collected', money(sum, cur), { note: `${n} payment(s) · ${totalScanned} txns scanned` });
@@ -195,7 +242,7 @@ export async function collect(args, ctx) {
       sum += Number(o.monetaryValue || o.monetary_value || 0) || 0;
       n++;
     }
-    return metric('Pipeline value', money(sum), { note: `${n} open deal(s)` });
+    return metric('Pipeline value', money(sum, locationCurrency), { note: `${n} open deal(s)` });
   }
 
   // ── REPLY RATE ──
@@ -223,6 +270,7 @@ export async function collect(args, ctx) {
     location: LOC,
     window: { days: DAYS, startISO, endISO: new Date(NOW).toISOString() },
     metrics: rows,
+    ...(modelMeta ? { modelMeta } : {}),
   };
 }
 
@@ -239,6 +287,16 @@ export async function run(args, ctx) {
     const line = (l, v) => '│ ' + l.padEnd(16) + ' ' + String(v).padEnd(W - 20) + '│';
     ctx.out.line('┌' + '─'.repeat(W - 2) + '┐');
     ctx.out.line(line('SNAPSHOT', winLabel.slice(0, W - 20)));
+    // C2: model staleness note
+    if (data.modelMeta) {
+      const mm = data.modelMeta;
+      if (mm.offline) {
+        ctx.out.line(line('· model', 'OFFLINE — calendar list from cache'));
+      } else if (mm.stale) {
+        const ageD = Math.round(mm.ageMs / 86400000);
+        ctx.out.line(line('· model', `${ageD}d old — run sizmo sync`));
+      }
+    }
     ctx.out.line('├' + '─'.repeat(W - 2) + '┤');
     for (const m of data.metrics) {
       if (m.blocked) {

package/commands/sync.mjs

@@ -0,0 +1,84 @@
+// commands/sync.mjs — force-refresh the local CRM model.
+// Fetches all 6 structure entities (or a subset) and stores the blob.
+// READ-ONLY. Only writes to the local model file; never writes to GoHighLevel.
+import { syncModel, ENTITY_SPECS, DEFAULT_MODEL_DIR } from '../lib/model.mjs';
+
+export const meta = {
+  name: 'sync',
+  summary: 'Refresh the local CRM model (pipelines, calendars, tags, fields, users, location)',
+  flags: [],
+  readOnly: true,
+};
+
+export async function run(args, ctx) {
+  const dir = ctx._modelDir ?? DEFAULT_MODEL_DIR;
+  const loc = ctx.cfg.loc;
+  const now = typeof ctx.now === 'function' ? ctx.now : () => ctx.now;
+
+  // Optional: sync only one entity — `sizmo sync tags`
+  const entityArg = args._?.[0];
+  const validNames = ENTITY_SPECS.map(s => s.name);
+  // Also accept 'fields' as alias for 'customFields'
+  const alias = { fields: 'customFields' };
+  const resolvedArg = entityArg ? (alias[entityArg] ?? entityArg) : null;
+  const only = resolvedArg ? [resolvedArg] : null;
+
+  if (resolvedArg && !validNames.includes(resolvedArg)) {
+    ctx.out.warn(`unknown entity "${entityArg}" — valid: ${validNames.join(', ')}`);
+    return 1;
+  }
+
+  let model;
+  try {
+    model = await syncModel({ http: ctx.http, loc, dir, now, only });
+  } catch (e) {
+    if (e.offline) {
+      ctx.out.warn("⚠ OFFLINE — can't reach GoHighLevel — check your connection; run `sizmo sync` when online");
+      return 1;
+    }
+    // Write failure (disk full, permissions, etc.)
+    ctx.out.warn(`sync failed — model not written: ${e.message}`);
+    return 1;
+  }
+
+  // Count results
+  let synced = 0, blocked = 0, networkErrors = 0;
+  for (const [, ent] of Object.entries(model.entities)) {
+    if (ent.networkError) networkErrors++;
+    else if (ent.blocked) blocked++;
+    else synced++;
+  }
+
+  ctx.out.data({ synced, blocked, networkErrors: networkErrors || undefined, offline: model.offline || undefined,
+    locationId: loc, syncedAt: model.syncedAt, entities: Object.fromEntries(
+    Object.entries(model.entities).map(([name, ent]) => [
+      name,
+      ent.networkError
+        ? { networkError: true, error: ent.error }
+        : ent.blocked
+          ? { blocked: true, scope: ent.scope }
+          : { fetchedAt: ent.fetchedAt, count: ent.items ? ent.items.length : (ent.item ? 1 : 0) },
+    ])
+  )});
+
+  ctx.out.card(() => {
+    const blockedNote = blocked > 0 ? ` (${blocked} scope-blocked)` : '';
+    const netNote = networkErrors > 0 ? ` (${networkErrors} network-error — check connection)` : '';
+    ctx.out.line(`synced ${synced} of ${synced + blocked + networkErrors} entities${blockedNote}${netNote} · loc ${loc}`);
+    for (const [name, ent] of Object.entries(model.entities)) {
+      if (ent.networkError) {
+        ctx.out.line(`  ⚠ ${name.padEnd(14)} couldn't reach GHL`);
+      } else if (ent.blocked) {
+        ctx.out.line(`  ✖ ${name.padEnd(14)} needs ${ent.scope}`);
+      } else {
+        const count = ent.items ? ent.items.length : (ent.item ? 1 : 0);
+        ctx.out.line(`  ✔ ${name.padEnd(14)} ${count} item(s)`);
+      }
+    }
+    if (model.offline) {
+      ctx.out.line('  ⚠ some entities could not be reached — model may be partially stale');
+    }
+  });
+
+  return 0;
+}

package/docs/how-to/crm-model.md

@@ -0,0 +1,105 @@
+# CRM model — how it works
+
+`sizmo` keeps a local copy of your CRM's structure — pipelines + stages, calendars, tags, custom fields, users, and location info. Recipes read from this cache instead of re-fetching on every run.
+
+## What is cached
+
+| Entity | Endpoint | TTL | Key fields |
+|--------|----------|-----|-----------|
+| pipelines + stages | `GET /opportunities/pipelines` | 24h | pipeline `{id,name}`, stages `[{id,name,position}]` |
+| calendars | `GET /calendars/` | 24h | `{id,name,calendarType,isActive}` |
+| tags | `GET /locations/{loc}/tags` | 12h | `{id,name}` |
+| customFields | `GET /locations/{loc}/customFields` | 12h | `{id,name,fieldKey,dataType}` |
+| users | `GET /users/` | 24h | `{id,firstName,lastName,email}` |
+| location | `GET /locations/{loc}` | 24h | `{name,timezone,currency,country}` |
+
+Stored at `~/.config/sizmo/model/<locationId>.json`. Written atomically (temp + rename), permissions 0600.
+
+## First run
+
+The model is synced automatically the first time a command needs it. Nothing to do.
+
+## Keeping the model fresh
+
+Run `sizmo sync` after:
+- Adding or renaming a pipeline stage
+- Adding or removing a calendar
+- Adding custom fields or tags
+- Onboarding a new user
+
+```sh
+sizmo sync              # full refresh (6 single-page calls, rate-safe)
+sizmo sync tags         # refresh one entity
+sizmo sync customFields
+```
+
+Valid entity names: `pipelines`, `calendars`, `tags`, `customFields` (or `fields`), `users`, `location`.
+
+## Querying the model
+
+```sh
+sizmo crm                   # overview: count + age per entity
+sizmo crm pipelines         # list pipelines + stages
+sizmo crm calendars         # list calendars
+sizmo crm tags              # list tags (first 20)
+sizmo crm tags --all        # list all tags
+sizmo crm fields            # list custom fields
+sizmo crm users             # list users
+sizmo crm location          # timezone / currency / country
+
+# Machine output:
+sizmo crm pipelines --json  # includes _meta with source/syncedAt/ageMs/stale
+```
+
+## Honest staleness
+
+Every model read shows the age of the data. Stale means the entity has passed its TTL (24h or 12h).
+
+- Fresh (under TTL): no special marker
+- Stale (past TTL): `⚠ STALE — run sizmo sync` banner; served anyway
+- Blocked (scope missing): `✖ needs <scope>`; other entities still served
+
+The CLI **never** auto-syncs mid-recipe when stale — it serves the cache and warns. This avoids surprise network calls and rate-limit hits. Use `sizmo sync` to force a refresh.
+
+The `--json` output includes `_meta` so agents can branch without parsing prose:
+
+```json
+{
+  "_meta": {
+    "source": "cache",
+    "syncedAt": 1718000000000,
+    "ageMs": 3600000,
+    "stale": false,
+    "offline": false
+  }
+}
+```
+
+## Name resolution
+
+Recipes use names (not IDs) in output when the model is available. If an ID is not found in the model (renamed stage, deleted calendar), the output shows:
+
+```
+<unknown:<id> — run sizmo sync>
+```
+
+This is the resolver's miss path. It never fabricates a name. Run `sizmo sync` to refresh the model after structural changes.
+
+## Partial sync (missing scopes)
+
+A 401 or 403 on one entity marks it blocked and stores what succeeded. `sizmo crm` shows blocked entities with `✖ needs <scope>`. Other entities are unaffected.
+
+Required scopes for a full sync:
+
+```
+opportunities.readonly
+calendars.readonly
+locations/tags.readonly
+locations/customFields.readonly
+users.readonly
+locations.readonly
+```
+
+## Schema versioning
+
+The model blob has a `schemaVersion` field. A format change bumps this version and invalidates the cached file (treated as missing, triggering a re-sync on next use).

package/lib/context.mjs

@@ -3,6 +3,8 @@ import { makeHttp } from './http.mjs';
 import { makeOut } from './output.mjs';
 import { makeCache } from './cache.mjs';
 import { GhlError, EXIT } from './errors.mjs';
+import { loadModel, syncModel, DEFAULT_MODEL_DIR } from './model.mjs';
+import { makeResolver } from './resolver.mjs';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
 import { env as processEnv } from 'node:process';
@@ -29,5 +31,38 @@ export function buildCtx({ creds, globals, now = Date.now(), httpFactory = makeH
       return r;
     },
   };
-  return { http, cfg: creds, out, now };
+
+  // CRM model — lazy, loaded once per ctx. Auto-syncs if missing.
+  // Recipes read ctx.model (the raw blob) and ctx.resolve (the resolver).
+  // We expose a lazy getter so commands that don't need the model pay nothing.
+  let _model = undefined; // undefined = not yet loaded; null = load attempted, none found + sync ran
+  let _resolver = undefined;
+
+  async function ensureModel() {
+    if (_model !== undefined) return _model;
+    _model = loadModel(creds.loc, DEFAULT_MODEL_DIR);
+    if (!_model) {
+      // Auto-sync on first use (model missing)
+      try {
+        _model = await syncModel({ http: rawHttp, loc: creds.loc, now: () => now });
+      } catch {
+        _model = null;
+      }
+    }
+    _resolver = makeResolver(_model, { now: () => now });
+    return _model;
+  }
+
+  return {
+    http,
+    cfg: creds,
+    out,
+    now,
+    // Expose model access for recipes
+    get model() { return _model; },
+    // ensureModel() → async lazy-loads + returns model
+    ensureModel,
+    // resolve(kind, id) → sync resolver call (after ensureModel was awaited)
+    get resolve() { return _resolver; },
+  };
 }

package/lib/model.mjs

@@ -0,0 +1,213 @@
+// lib/model.mjs — per-profile CRM structure store + sync.
+// Caches 6 slow-changing GHL entities (pipelines, calendars, tags, customFields, users, location)
+// in a single JSON blob per location at ~/.config/sizmo/model/<loc>.json.
+// Atomic write (temp+rename, same-dir to avoid EXDEV), 0600, per-entity age tracked, partial-sync-safe.
+// READ-ONLY. No writes to GoHighLevel.
+import { mkdirSync, writeFileSync, readFileSync, renameSync, unlinkSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { env as processEnv } from 'node:process';
+import { mapLimit } from './pool.mjs';
+
+const XDG = processEnv.XDG_CONFIG_HOME || join(homedir(), '.config');
+export const DEFAULT_MODEL_DIR = join(XDG, 'sizmo', 'model');
+export const SCHEMA_VERSION = 1;
+
+// TTLs: pipelines/calendars/users/location 24h; tags/customFields 12h
+const H24 = 24 * 60 * 60 * 1000;
+const H12 = 12 * 60 * 60 * 1000;
+
+// Entity specs — each describes how to fetch + parse one CRM entity.
+// buildPath(loc) → the API path segment; version → GHL API Version header;
+// scope → human-readable scope name for blocked messages;
+// ttlMs → staleness threshold; extract(json) → items[] or item{}.
+export const ENTITY_SPECS = [
+  {
+    name: 'pipelines',
+    buildPath: (loc) => `/opportunities/pipelines?locationId=${loc}`,
+    version: '2021-07-28',
+    scope: 'opportunities.readonly',
+    ttlMs: H24,
+    extract: (j) => ({ items: j?.pipelines ?? [] }),
+  },
+  {
+    name: 'calendars',
+    buildPath: (loc) => `/calendars/?locationId=${loc}`,
+    version: '2021-04-15',
+    scope: 'calendars.readonly',
+    ttlMs: H24,
+    extract: (j) => ({ items: j?.calendars ?? [] }),
+  },
+  {
+    name: 'tags',
+    buildPath: (loc) => `/locations/${loc}/tags`,
+    version: '2021-07-28',
+    scope: 'locations/tags.readonly',
+    ttlMs: H12,
+    extract: (j) => ({ items: j?.tags ?? [] }),
+  },
+  {
+    name: 'customFields',
+    buildPath: (loc) => `/locations/${loc}/customFields?model=all`,
+    version: '2021-07-28',
+    scope: 'locations/customFields.readonly',
+    ttlMs: H12,
+    extract: (j) => ({ items: j?.customFields ?? [] }),
+  },
+  {
+    name: 'users',
+    buildPath: (loc) => `/users/?locationId=${loc}`,
+    version: '2021-07-28',
+    scope: 'users.readonly',
+    ttlMs: H24,
+    extract: (j) => ({ items: j?.users ?? [] }),
+  },
+  {
+    name: 'location',
+    buildPath: (loc) => `/locations/${loc}`,
+    version: '2021-07-28',
+    scope: 'locations.readonly',
+    ttlMs: H24,
+    extract: (j) => ({ item: j?.location ?? {} }),
+  },
+];
+
+/**
+ * syncModel — fetch (up to) 6 entities and write the blob atomically.
+ * @param {object} opts
+ * @param {object} opts.http        ctx.http (get returns {code,ok,j})
+ * @param {string} opts.loc         locationId
+ * @param {string} [opts.dir]       override default model dir (for tests)
+ * @param {Function} [opts.now]     injectable clock () => ms
+ * @param {string[]} [opts.only]    subset of entity names (partial sync; for `sync <entity>`)
+ * @returns {object} the written model blob, with an `offline` boolean property:
+ *   true  = at least one entity hit a network/transport error (couldn't reach GHL at all).
+ *   false = all entities either succeeded or were blocked by an HTTP 401/403 scope error.
+ * @throws {Error} if the model is missing AND all fetches hit network errors (cold+offline).
+ *   Caller must show a real error — do NOT display a fresh-looking empty model in this case.
+ */
+export async function syncModel({ http, loc, dir = DEFAULT_MODEL_DIR, now = Date.now, only = null } = {}) {
+  const specs = only ? ENTITY_SPECS.filter(s => only.includes(s.name)) : ENTITY_SPECS;
+  const syncedAt = now();
+
+  // Start from any existing model (keep entities not in this sync run)
+  const base = loadModel(loc, dir) || {};
+  const hadExistingModel = !!(base.entities && Object.keys(base.entities).length > 0);
+  const entities = base.entities ? { ...base.entities } : {};
+
+  let networkErrorCount = 0;
+
+  await mapLimit(specs, 5, async (spec) => {
+    const path = spec.buildPath(loc);
+    let r;
+    try {
+      r = await http.get(path, spec.version !== '2021-07-28' ? { version: spec.version } : undefined);
+    } catch (e) {
+      // Transport/network failure — couldn't reach GHL at all. Distinct from auth errors.
+      networkErrorCount++;
+      entities[spec.name] = { networkError: true, error: e?.message ?? 'network error', fetchedAt: now() };
+      return;
+    }
+    // http.get returned code:0 signals a network-level failure (no response from server)
+    if (r.code === 0) {
+      networkErrorCount++;
+      entities[spec.name] = { networkError: true, error: r.message ?? 'no response', fetchedAt: now() };
+      return;
+    }
+    if (r.code === 401 || r.code === 403) {
+      // Scope/auth blocked — this is NOT a network error. Clearly distinguished.
+      entities[spec.name] = { blocked: true, scope: spec.scope, fetchedAt: now() };
+      return;
+    }
+    if (!r.ok) {
+      // Other HTTP errors (5xx, 404, etc.) — mark blocked with code, NOT networkError.
+      entities[spec.name] = { blocked: true, scope: spec.scope, httpCode: r.code, fetchedAt: now() };
+      return;
+    }
+    const extracted = spec.extract(r.j);
+    entities[spec.name] = { fetchedAt: now(), ...extracted };
+  });
+
+  const offline = networkErrorCount > 0;
+
+  // Cold + offline: no existing model AND all/some fetches hit network errors.
+  // Do NOT write a fresh-looking empty blob. Throw so the caller shows a real error.
+  if (!hadExistingModel && offline) {
+    const err = new Error(
+      "can't reach GoHighLevel — check your connection; run `sizmo sync` when online"
+    );
+    err.offline = true;
+    err.networkErrorCount = networkErrorCount;
+    throw err;
+  }
+
+  const model = {
+    schemaVersion: SCHEMA_VERSION,
+    locationId: loc,
+    syncedAt,
+    entities,
+    offline,
+  };
+
+  writeModelAtomic(loc, model, dir);
+  return model;
+}
+
+/**
+ * loadModel — read the blob for a location. Returns null if missing, corrupt,
+ * or schemaVersion mismatch (caller must re-sync).
+ */
+export function loadModel(loc, dir = DEFAULT_MODEL_DIR) {
+  const path = join(dir, `${loc}.json`);
+  try {
+    const raw = readFileSync(path, 'utf8');
+    const parsed = JSON.parse(raw);
+    if (!parsed || parsed.schemaVersion !== SCHEMA_VERSION) return null;
+    return parsed;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * isStale — true if the entity's fetchedAt is older than ttlMs relative to now.
+ * @param {object} entity  model.entities[name]
+ * @param {number} nowMs   current time in ms
+ * @param {number} ttlMs   TTL for this entity type
+ */
+export function isStale(entity, nowMs, ttlMs) {
+  if (!entity || entity.blocked || entity.networkError || typeof entity.fetchedAt !== 'number') return true;
+  return (nowMs - entity.fetchedAt) > ttlMs;
+}
+
+/**
+ * ageMs — ms since this entity was last fetched.
+ */
+export function ageMs(entity, nowMs) {
+  if (!entity || typeof entity.fetchedAt !== 'number') return null;
+  return nowMs - entity.fetchedAt;
+}
+
+// ── internal ──────────────────────────────────────────────────────────────────
+
+/**
+ * writeModelAtomic — write model to disk with a same-directory temp+rename pattern.
+ * Same-dir temp avoids EXDEV (cross-filesystem rename failure) that occurs when tmpdir()
+ * is on a different mount than the model dir. Throws on any write failure so callers can
+ * surface the error (M1 + M2 fix).
+ */
+function writeModelAtomic(loc, model, dir) {
+  mkdirSync(dir, { recursive: true, mode: 0o700 });
+  const dest = join(dir, `${loc}.json`);
+  // Same directory as dest — no cross-FS EXDEV risk.
+  const tmp = join(dir, `.${loc}.json.tmp.${process.pid}`);
+  try {
+    writeFileSync(tmp, JSON.stringify(model, null, 2), { mode: 0o600 });
+    renameSync(tmp, dest);
+  } catch (e) {
+    // Clean up orphaned temp file on failure; ignore cleanup error.
+    try { unlinkSync(tmp); } catch { /* ignore */ }
+    // Re-throw so the caller (sync command) can surface "sync failed — nothing written".
+    throw e;
+  }
+}

package/lib/registry.mjs

@@ -1,4 +1,4 @@
-// lib/registry.mjs — name → lazy loader. All 10 commands run in-process (v0.3 importable-core).
+// lib/registry.mjs — name → lazy loader. All 12 commands run in-process (v0.5 importable-core).
 export const registry = {
   snapshot: () => import('../commands/snapshot.mjs'),
   triage: () => import('../commands/triage.mjs'),
@@ -10,4 +10,6 @@ export const registry = {
   'booked-not-paid': () => import('../commands/booked-not-paid.mjs'),
   brief: () => import('../commands/brief.mjs'),
   focus: () => import('../commands/focus.mjs'),
+  crm: () => import('../commands/crm.mjs'),
+  sync: () => import('../commands/sync.mjs'),
 };