@mutmutco/cli 2.25.1 → 2.27.0

package/dist/main.cjs

@@ -4235,6 +4235,7 @@ function parseHookInput(stdin) {
 }
 
 // src/saga-health.ts
+var MEMORY_STALE_DAYS = 14;
 function buildHealth(i) {
   const problems = [];
   if (!i.sagaApiUrl) problems.push("Hub API URL not configured");
@@ -4245,6 +4246,10 @@ function buildHealth(i) {
   }
   if (i.reachable && i.authorized === false) problems.push("saga backend rejected authenticated state access");
   if (!i.key.sessionId || i.key.sessionId === "-") problems.push("unsafe session id");
+  const warnings = [];
+  if (i.memoryAgeDays !== void 0 && i.memoryAgeDays > MEMORY_STALE_DAYS) {
+    warnings.push(`PROJECT MEMORY is ${Math.round(i.memoryAgeDays)}d stale \u2014 the saga-keeper may have stalled`);
+  }
   const safeToWrite = problems.length === 0;
   return {
     ok: safeToWrite,
@@ -4258,14 +4263,19 @@ function buildHealth(i) {
     pendingNotes: i.pendingNotes ?? 0,
     key: i.key,
     source: i.source,
-    problems
+    problems,
+    warnings,
+    memoryAgeDays: i.memoryAgeDays
   };
 }
 function healthBanner(report) {
-  if (report.ok) return null;
-  const summary = report.problems.slice(0, 2).join("; ") || "unknown saga health gap";
-  const suffix = report.problems.length > 2 ? ` (+${report.problems.length - 2} more)` : "";
-  return `saga health: CHECK - ${summary}${suffix}`;
+  if (report.problems.length) {
+    const summary = report.problems.slice(0, 2).join("; ") || "unknown saga health gap";
+    const suffix = report.problems.length > 2 ? ` (+${report.problems.length - 2} more)` : "";
+    return `saga health: CHECK - ${summary}${suffix}`;
+  }
+  if (report.warnings.length) return `saga health: NOTE - ${report.warnings.join("; ")}`;
+  return null;
 }
 function resumeCue() {
   return '> STATUS/RESUME CUE \u2014 For any status, resume, or "where do I stand" report: read THIS saga HEAD first (`mmi-cli saga show`), then reconcile its NEXT / LAST 5 / DECISIONS against the live board + git/gh before reporting. Do not rebuild the picture from board/issues/memory while skipping the HEAD. PRECEDENCE: the HEAD is prior-session belief and MAY BE SUPERSEDED \u2014 the current live user/master instruction WINS over any conflicting HEAD anchor, NEXT, or checklist; follow the live instruction and treat the stale HEAD item as superseded.';
@@ -4384,6 +4394,19 @@ async function probeSagaAccess(url, key) {
     return false;
   }
 }
+async function fetchMemoryAge(url, project2) {
+  try {
+    const qs = new URLSearchParams({ project: project2 }).toString();
+    const res = await fetch(`${url}/saga/memory-age?${qs}`, { headers: await hubHeaders(), signal: AbortSignal.timeout(8e3) });
+    if (!res.ok) return void 0;
+    const body = await res.json();
+    if (!body.updatedAt) return void 0;
+    const ms = Date.now() - Date.parse(body.updatedAt);
+    return Number.isFinite(ms) && ms >= 0 ? ms / 864e5 : void 0;
+  } catch {
+    return void 0;
+  }
+}
 async function runSagaHealth(o, io = consoleIo) {
   const cfg = await loadConfig();
   const session = resolveSessionId();
@@ -4394,6 +4417,7 @@ async function runSagaHealth(o, io = consoleIo) {
     cfg.sagaApiUrl ? probeBackend(cfg.sagaApiUrl) : Promise.resolve({ reachable: false })
   ]);
   const authorized = cfg.sagaApiUrl && liveness.reachable ? await probeSagaAccess(cfg.sagaApiUrl, key) : void 0;
+  const memoryAgeDays = cfg.sagaApiUrl && liveness.reachable ? await fetchMemoryAge(cfg.sagaApiUrl, key.project) : void 0;
   const report = buildHealth({
     key,
     source,
@@ -4403,7 +4427,8 @@ async function runSagaHealth(o, io = consoleIo) {
     livenessMessage: liveness.message,
     authorized,
     sagaApiUrl: cfg.sagaApiUrl,
-    pendingNotes: readPending().length
+    pendingNotes: readPending().length,
+    memoryAgeDays
   });
   if (o.json) return io.log(JSON.stringify(report));
   if (o.banner) {
@@ -4414,6 +4439,7 @@ async function runSagaHealth(o, io = consoleIo) {
   if (o.quiet) return;
   io.log(`saga health: ${report.ok ? "OK" : "NOT OK"}`);
   if (report.problems.length) io.log(report.problems.map((p) => ` - ${p}`).join("\n"));
+  if (report.warnings.length) io.log(report.warnings.map((w) => ` - ${w}`).join("\n"));
   if (report.pendingNotes > 0) io.log(` - ${report.pendingNotes} note(s) queued locally \u2014 \`mmi-cli saga flush\` to roll forward`);
 }
 function registerSagaCommands(program3) {
@@ -10587,6 +10613,32 @@ async function planPush(deps, slug, opts = {}) {
   deps.log(`queued ${slug} for background push \u2014 expected, not a failure (\`mmi-cli northstar status\` to check; \`mmi-cli northstar sync\` or --wait for durable confirmation)`);
   return true;
 }
+function buildPutBody(project2, slug, content, opts = {}) {
+  const body = { project: project2, slug, content };
+  const frontmatterMeta = extractPlanMeta(content);
+  if (Object.keys(frontmatterMeta).length) body.meta = frontmatterMeta;
+  if (opts.force) body.force = true;
+  else if (opts.baseEtag) body.baseEtag = opts.baseEtag;
+  return body;
+}
+async function reconcilePushConflict(deps, project2, slug, content, baseHash) {
+  const qs = new URLSearchParams({ project: project2, slug }).toString();
+  const pull = await deps.fetch(`${deps.apiUrl}/plan/get?${qs}`, { method: "GET", headers: await deps.headers(), signal: AbortSignal.timeout(TIMEOUT_MS) }).catch(() => null);
+  const doc = pull?.ok ? await pull.json() : null;
+  if (!doc) return null;
+  const remote = normalizeEol(doc.content ?? "");
+  if (remote === content) return { etag: doc.etag };
+  if (baseHash && hashContent(remote) === baseHash) {
+    const res = await deps.fetch(`${deps.apiUrl}/plan/put`, {
+      method: "POST",
+      headers: await deps.headers({ "content-type": "application/json" }),
+      body: JSON.stringify(buildPutBody(project2, slug, content, { baseEtag: doc.etag })),
+      signal: AbortSignal.timeout(TIMEOUT_MS)
+    }).catch(() => null);
+    if (res?.ok) return await res.json();
+  }
+  return null;
+}
 async function planPushNow(deps, slug, opts = {}) {
   const raw = deps.readLocal(slug);
   if (raw == null) {
@@ -10597,25 +10649,21 @@ async function planPushNow(deps, slug, opts = {}) {
   const project2 = opts.project ?? await deps.project();
   const meta = parseMeta(deps.readMetaRaw());
   const entry = meta[metaKey(project2, slug)];
-  const body = { project: project2, slug, content };
-  const frontmatterMeta = extractPlanMeta(content);
-  if (Object.keys(frontmatterMeta).length) body.meta = frontmatterMeta;
-  if (opts.force) body.force = true;
-  else if (entry?.etag) body.baseEtag = entry.etag;
   const res = await deps.fetch(`${deps.apiUrl}/plan/put`, {
     method: "POST",
     headers: await deps.headers({ "content-type": "application/json" }),
-    body: JSON.stringify(body),
+    body: JSON.stringify(buildPutBody(project2, slug, content, { force: opts.force, baseEtag: entry?.etag })),
     signal: AbortSignal.timeout(TIMEOUT_MS)
   });
-  if (res.ok) {
-    const out = await res.json();
-    meta[metaKey(project2, slug)] = { etag: out.etag, hash: hashContent(content), syncedAt: deps.now() };
-    deps.writeMetaRaw(serializeMeta(meta));
-    dropQueued(deps, project2, slug);
-    deps.log(`pushed ${slug}`);
-    return true;
-  } else if (res.status === 409) {
+  if (res.ok || res.status === 409) {
+    const adopted = res.ok ? await res.json() : await reconcilePushConflict(deps, project2, slug, content, entry?.hash);
+    if (adopted) {
+      meta[metaKey(project2, slug)] = { etag: adopted.etag, hash: hashContent(content), syncedAt: deps.now() };
+      deps.writeMetaRaw(serializeMeta(meta));
+      dropQueued(deps, project2, slug);
+      deps.log(`pushed ${slug}`);
+      return true;
+    }
     deps.err(staleHint(slug));
     return false;
   } else {
@@ -10766,11 +10814,7 @@ async function planSync(deps, opts = {}) {
     const content = normalizeEol(raw);
     const meta = parseMeta(deps.readMetaRaw());
     const metaEntry = meta[metaKey(entry.project, entry.slug)];
-    const body = { project: entry.project, slug: entry.slug, content };
-    const frontmatterMeta = extractPlanMeta(content);
-    if (Object.keys(frontmatterMeta).length) body.meta = frontmatterMeta;
-    if (entry.force) body.force = true;
-    else if (metaEntry?.etag) body.baseEtag = metaEntry.etag;
+    const body = buildPutBody(entry.project, entry.slug, content, { force: entry.force, baseEtag: metaEntry?.etag });
     let res;
     try {
       res = await deps.fetch(`${deps.apiUrl}/plan/put`, {
@@ -10789,12 +10833,11 @@ async function planSync(deps, opts = {}) {
       deps.writeMetaRaw(serializeMeta(meta));
       if (!opts.quiet) deps.log(`pushed ${entry.slug}`);
     } else if (res.status === 409) {
-      const qs = new URLSearchParams({ project: entry.project, slug: entry.slug }).toString();
-      const pull = await deps.fetch(`${deps.apiUrl}/plan/get?${qs}`, { method: "GET", headers: await deps.headers(), signal: AbortSignal.timeout(TIMEOUT_MS) }).catch(() => null);
-      const doc = pull?.ok ? await pull.json() : null;
-      if (doc && normalizeEol(doc.content ?? "") === content) {
-        meta[metaKey(entry.project, entry.slug)] = { etag: doc.etag, hash: hashContent(content), syncedAt: deps.now() };
+      const adopted = await reconcilePushConflict(deps, entry.project, entry.slug, content, metaEntry?.hash);
+      if (adopted) {
+        meta[metaKey(entry.project, entry.slug)] = { etag: adopted.etag, hash: hashContent(content), syncedAt: deps.now() };
         deps.writeMetaRaw(serializeMeta(meta));
+        if (!opts.quiet) deps.log(`pushed ${entry.slug}`);
       } else {
         kept.push({ ...entry, attempts: entry.attempts + 1, conflict: staleHint(entry.slug) });
       }
@@ -10822,6 +10865,38 @@ async function planStatus(deps) {
   deps.log(idx ? `plan index: ${idx.plans.length} plans, fetched ${idx.fetchedAt}` : "plan index: cold (first read will fetch)");
   if (queue.some((e) => e.conflict || e.deadLettered)) process.exitCode = 1;
 }
+async function planReconcile(deps) {
+  const meta = parseMeta(deps.readMetaRaw());
+  let refreshed = 0;
+  let diverged = 0;
+  let unreachable = 0;
+  for (const [key, entry] of Object.entries(meta)) {
+    const i = key.indexOf("/");
+    if (i < 0) continue;
+    const project2 = key.slice(0, i);
+    const slug = key.slice(i + 1);
+    const qs = new URLSearchParams({ project: project2, slug }).toString();
+    const res = await deps.fetch(`${deps.apiUrl}/plan/get?${qs}`, { method: "GET", headers: await deps.headers(), signal: AbortSignal.timeout(TIMEOUT_MS) }).catch(() => null);
+    if (!res || !res.ok) {
+      unreachable++;
+      continue;
+    }
+    const doc = await res.json();
+    const remote = normalizeEol(doc.content ?? "");
+    if (!entry.hash || hashContent(remote) !== entry.hash) {
+      diverged++;
+      continue;
+    }
+    if (doc.etag && doc.etag !== entry.etag) {
+      meta[key] = { ...entry, etag: doc.etag, syncedAt: deps.now() };
+      refreshed++;
+    }
+  }
+  if (refreshed) deps.writeMetaRaw(serializeMeta(meta));
+  deps.log(
+    `reconcile: ${refreshed} etag(s) refreshed` + (diverged ? `, ${diverged} diverged (pull or push them)` : "") + (unreachable ? `, ${unreachable} unreachable` : "")
+  );
+}
 async function planGraduate(deps, slug, opts = {}) {
   if (!opts.orgVisible) {
     deps.err("refusing to mark an org-visible graduation without --org-visible");
@@ -11913,6 +11988,7 @@ function registerNorthStarCommands(cmd) {
   }));
   cmd.command("sync").description("drain queued background pushes and refresh the local plan index").option("--quiet", "silent (background worker)").action((o) => withPlan(o.quiet ?? false, (d) => planSync(d, o)));
   cmd.command("status").description("show pending/conflicted background pushes and the plan-cache age").action(() => withPlan(false, (d) => planStatus(d)));
+  cmd.command("reconcile").description("refresh stale local etags from the server without --force (recovers from an object-store re-stamp)").action(() => withPlan(false, (d) => planReconcile(d)));
   cmd.command("open <slug>").description("pull if needed, then open plans/<slug>.md in $EDITOR").option("--project <name>", "override the project key").action(
     (slug, o) => withPlan(false, async (d) => {
       const ok = await planPull(d, slug, { project: o.project });

package/dist/saga.cjs

@@ -3565,6 +3565,7 @@ async function runHeadEngine(prompt, timeoutMs = HEAD_ENGINE_TIMEOUT_MS) {
 }
 
 // src/saga-health.ts
+var MEMORY_STALE_DAYS = 14;
 function buildHealth(i) {
   const problems = [];
   if (!i.sagaApiUrl) problems.push("Hub API URL not configured");
@@ -3575,6 +3576,10 @@ function buildHealth(i) {
   }
   if (i.reachable && i.authorized === false) problems.push("saga backend rejected authenticated state access");
   if (!i.key.sessionId || i.key.sessionId === "-") problems.push("unsafe session id");
+  const warnings = [];
+  if (i.memoryAgeDays !== void 0 && i.memoryAgeDays > MEMORY_STALE_DAYS) {
+    warnings.push(`PROJECT MEMORY is ${Math.round(i.memoryAgeDays)}d stale \u2014 the saga-keeper may have stalled`);
+  }
   const safeToWrite = problems.length === 0;
   return {
     ok: safeToWrite,
@@ -3588,14 +3593,19 @@ function buildHealth(i) {
     pendingNotes: i.pendingNotes ?? 0,
     key: i.key,
     source: i.source,
-    problems
+    problems,
+    warnings,
+    memoryAgeDays: i.memoryAgeDays
   };
 }
 function healthBanner(report) {
-  if (report.ok) return null;
-  const summary = report.problems.slice(0, 2).join("; ") || "unknown saga health gap";
-  const suffix = report.problems.length > 2 ? ` (+${report.problems.length - 2} more)` : "";
-  return `saga health: CHECK - ${summary}${suffix}`;
+  if (report.problems.length) {
+    const summary = report.problems.slice(0, 2).join("; ") || "unknown saga health gap";
+    const suffix = report.problems.length > 2 ? ` (+${report.problems.length - 2} more)` : "";
+    return `saga health: CHECK - ${summary}${suffix}`;
+  }
+  if (report.warnings.length) return `saga health: NOTE - ${report.warnings.join("; ")}`;
+  return null;
 }
 function resumeCue() {
   return '> STATUS/RESUME CUE \u2014 For any status, resume, or "where do I stand" report: read THIS saga HEAD first (`mmi-cli saga show`), then reconcile its NEXT / LAST 5 / DECISIONS against the live board + git/gh before reporting. Do not rebuild the picture from board/issues/memory while skipping the HEAD. PRECEDENCE: the HEAD is prior-session belief and MAY BE SUPERSEDED \u2014 the current live user/master instruction WINS over any conflicting HEAD anchor, NEXT, or checklist; follow the live instruction and treat the stale HEAD item as superseded.';
@@ -4205,6 +4215,19 @@ async function probeSagaAccess(url, key) {
     return false;
   }
 }
+async function fetchMemoryAge(url, project) {
+  try {
+    const qs = new URLSearchParams({ project }).toString();
+    const res = await fetch(`${url}/saga/memory-age?${qs}`, { headers: await hubHeaders(), signal: AbortSignal.timeout(8e3) });
+    if (!res.ok) return void 0;
+    const body = await res.json();
+    if (!body.updatedAt) return void 0;
+    const ms = Date.now() - Date.parse(body.updatedAt);
+    return Number.isFinite(ms) && ms >= 0 ? ms / 864e5 : void 0;
+  } catch {
+    return void 0;
+  }
+}
 async function runSagaHealth(o, io = consoleIo) {
   const cfg = await loadConfig();
   const session = resolveSessionId();
@@ -4215,6 +4238,7 @@ async function runSagaHealth(o, io = consoleIo) {
     cfg.sagaApiUrl ? probeBackend(cfg.sagaApiUrl) : Promise.resolve({ reachable: false })
   ]);
   const authorized = cfg.sagaApiUrl && liveness.reachable ? await probeSagaAccess(cfg.sagaApiUrl, key) : void 0;
+  const memoryAgeDays = cfg.sagaApiUrl && liveness.reachable ? await fetchMemoryAge(cfg.sagaApiUrl, key.project) : void 0;
   const report = buildHealth({
     key,
     source,
@@ -4224,7 +4248,8 @@ async function runSagaHealth(o, io = consoleIo) {
     livenessMessage: liveness.message,
     authorized,
     sagaApiUrl: cfg.sagaApiUrl,
-    pendingNotes: readPending().length
+    pendingNotes: readPending().length,
+    memoryAgeDays
   });
   if (o.json) return io.log(JSON.stringify(report));
   if (o.banner) {
@@ -4235,6 +4260,7 @@ async function runSagaHealth(o, io = consoleIo) {
   if (o.quiet) return;
   io.log(`saga health: ${report.ok ? "OK" : "NOT OK"}`);
   if (report.problems.length) io.log(report.problems.map((p) => ` - ${p}`).join("\n"));
+  if (report.warnings.length) io.log(report.warnings.map((w) => ` - ${w}`).join("\n"));
   if (report.pendingNotes > 0) io.log(` - ${report.pendingNotes} note(s) queued locally \u2014 \`mmi-cli saga flush\` to roll forward`);
 }
 function registerSagaCommands(program2) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mutmutco/cli",
-  "version": "2.25.1",
+  "version": "2.27.0",
   "description": "MMI Future CLI — delivers the org rules (whole-file), plus saga and KB access. The cross-IDE engine the plugin's SessionStart hook drives.",
   "type": "module",
   "license": "UNLICENSED",