@mindrian_os/install 1.13.0-beta.14 → 1.13.0-beta.16

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "mos",
   "description": "MindrianOS -- Your AI innovation co-founder. Larry thinks with you through PWS methodology, builds your Data Room as you explore, and chains frameworks intelligently. Install and go.",
-  "version": "1.13.0-beta.14",
+  "version": "1.13.0-beta.16",
   "author": {
     "name": "Jonathan Sagir",
     "url": "https://mindrian.ai"

package/CHANGELOG.md

@@ -1,3 +1,8 @@
+## [1.13.0-beta.16] - 2026-05-14
+
+### Added
+- 
+
 ## [1.13.0-beta.14] - 2026-05-14
 
 ### Added

package/lib/core/cache-prune.cjs

@@ -31,10 +31,33 @@
  *
  * If installed_plugins.json is unreadable (ENOENT, parse error, or no
  * mos@mindrian-marketplace entry), the function returns
- *   { kept: [], removed: [], skipped: true, reason: '...' }
+ *   { kept: [], removed: [], removedBackups: [], skipped: true, reason: '...' }
  * with NO mutation. Never guesses; never deletes anything in the absence
  * of an authoritative active-version answer.
  *
+ * Phase 126 Plan-06 extension -- STALE BACKUP DIR PRUNING.
+ * In addition to the marketplace-cache version dirs, this function ALSO
+ * prunes Phase 95.2's atomic-swap backup directories at
+ *   ~/.claude/plugins/mindrian-os.stale-<tag>-<timestamp>/
+ * that are older than MOS_CACHE_PRUNE_AGE_DAYS (default 30 days).
+ *
+ * Background: Phase 95.2 wraps `claude plugin update` in an atomic-swap
+ * recovery flow. Each recovery leaves a backup of the prior install at
+ * the sibling path above. By Phase 95.2 contract, backups are retained
+ * "indefinitely" (after 24h the user can delete manually). Long-running
+ * tester installs (Lawrence, Gary, etc) never see manual cleanup, so
+ * backups accumulate. 30 days is the next operational threshold beyond
+ * the 24h user-driven cleanup window.
+ *
+ * Pattern match is LITERAL prefix `mindrian-os.stale-` (regex
+ * /^mindrian-os\.stale-/). Does NOT match `mindrian-os/` (the live
+ * install) or unrelated siblings -- the period after `mindrian-os` is
+ * what gates the match.
+ *
+ * Window override: set process.env.MOS_CACHE_PRUNE_AGE_DAYS to any
+ * positive integer. Invalid values (non-numeric, negative) fall back
+ * to the 30-day default. v2 may move this to .mos/config.json.
+ *
  * Signature:
  *   pruneMarketplaceCache({
  *     home = os.homedir(),
@@ -42,14 +65,22 @@
  *     retainCount = 2,
  *     dryRun = false,
  *   } = {}) => {
- *     kept: string[],     // version basenames kept on disk (incl. active)
- *     removed: string[],  // version basenames removed (or would be, in dryRun)
- *     skipped: boolean,   // true if we declined to act (see `reason`)
- *     reason: string|null // human-readable explanation, or null on success
+ *     kept: string[],            // version basenames kept on disk (incl. active)
+ *     removed: string[],         // version basenames removed (or would be, in dryRun)
+ *     removedBackups: string[],  // absolute paths of stale backup dirs removed (Phase 126)
+ *     skipped: boolean,          // true if we declined the marketplace-cache prune
+ *     reason: string|null,       // human-readable explanation, or null on success
+ *     ageDays: number,           // the active stale-backup age window in days (Phase 126)
  *   }
  *
+ * Backward compat: the original Phase 123 consumer at scripts/doctor.cjs
+ * line ~2100 reads r.removed.length + r.kept only; both unchanged here.
+ * `removedBackups` and `ageDays` are ADDITIVE fields.
+ *
  * Canon Part 8 sanity check (cp.6): the forbidden-network-token grep
- * exits 1 (no match) on this source file. Test cp.6 enforces it.
+ * exits 1 (no match) on this source file. Test cp.6 enforces it. The
+ * Phase 126 extension reads only local fs (stat + readdir + rmSync on
+ * scratch / on-disk backup dirs); zero network surface.
  */
 
 const fs = require('node:fs');
@@ -137,10 +168,20 @@ function pruneMarketplaceCache(opts) {
   const retainCount = (typeof o.retainCount === 'number' && o.retainCount >= 0) ? o.retainCount : 2;
   const dryRun = !!o.dryRun;
 
+  // Phase 126 Plan-06: stale-backup age window. Read once at the top so the
+  // returned `ageDays` field reflects the value that gated the prune.
+  // Env override is integer-only; invalid values fall back to the default.
+  const ageDaysRaw = process.env.MOS_CACHE_PRUNE_AGE_DAYS;
+  const ageDays = (typeof ageDaysRaw === 'string' && /^\d+$/.test(ageDaysRaw))
+    ? parseInt(ageDaysRaw, 10)
+    : 30;
+
   // Step 1: read active version. Skip entirely if unavailable -- never guess.
+  // (When skipped, we also decline the Phase-126 stale-backup pass, mirroring
+  // "no mutation in the absence of authoritative state".)
   const active = readActiveVersion(home);
   if (active.skipped) {
-    return { kept: [], removed: [], skipped: true, reason: active.reason };
+    return { kept: [], removed: [], removedBackups: [], skipped: true, reason: active.reason, ageDays };
   }
   const activeVersion = active.activeVersion;
 
@@ -149,7 +190,9 @@ function pruneMarketplaceCache(opts) {
   if (names.length === 0) {
     // No cache dir to prune. The active version is still "kept" conceptually
     // (it lives in the cache when it exists; absent cache = nothing to do).
-    return { kept: [activeVersion], removed: [], skipped: false, reason: 'no cache dir to prune' };
+    // Phase 126: still run the stale-backup pass below (returns at end).
+    const removedBackups = pruneStaleBackups(home, ageDays, dryRun);
+    return { kept: [activeVersion], removed: [], removedBackups, skipped: false, reason: 'no cache dir to prune', ageDays };
   }
 
   // Step 3: build the keep-set.
@@ -191,18 +234,81 @@ function pruneMarketplaceCache(opts) {
     }
   }
 
+  // Phase 126 Plan-06: stale-backup pass. ADDITIVE to the cache prune above;
+  // walks PLUGIN_HOME (sibling of cache/) for mindrian-os.stale-* dirs older
+  // than `ageDays`. Failures are swallowed per-entry (best-effort, mirrors the
+  // existing per-version rmSync error path).
+  const removedBackups = pruneStaleBackups(home, ageDays, dryRun);
+
   return {
     kept: Array.from(keep),
     removed,
+    removedBackups,
     skipped: false,
     reason: null,
+    ageDays,
   };
 }
 
+// ---------------------------------------------------------------------------
+// Phase 126 Plan-06 helper -- prune stale backup directories.
+//
+// Walks <home>/.claude/plugins/ for entries whose basename matches the
+// LITERAL prefix /^mindrian-os\.stale-/ (the period after `mindrian-os`
+// is what gates the match -- does NOT match `mindrian-os/` live install
+// or unrelated siblings such as `mindrian-marketplace/`).
+//
+// Returns an array of absolute paths that were removed (or that would
+// have been removed in dryRun mode). On error (unreadable dir, stat
+// failure, rm failure), the entry is silently skipped -- best-effort
+// semantics mirror the in-loop pattern of the cache-version prune above.
+// ---------------------------------------------------------------------------
+function pruneStaleBackups(home, ageDays, dryRun) {
+  const removedBackups = [];
+  const pluginsDir = path.join(home, '.claude', 'plugins');
+  const cutoffMs = Date.now() - (ageDays * 86400000);
+
+  let entries = [];
+  try {
+    entries = fs.readdirSync(pluginsDir, { withFileTypes: true });
+  } catch (_) {
+    // pluginsDir absent: nothing to prune. Return empty list.
+    return removedBackups;
+  }
+
+  for (const e of entries) {
+    if (!e.isDirectory()) continue;
+    if (!/^mindrian-os\.stale-/.test(e.name)) continue;
+    const fullPath = path.join(pluginsDir, e.name);
+    let mtimeMs;
+    try {
+      mtimeMs = fs.statSync(fullPath).mtimeMs;
+    } catch (_) {
+      continue; // stat failure: leave for inspection
+    }
+    if (mtimeMs >= cutoffMs) continue; // recent enough; retain
+
+    if (dryRun) {
+      removedBackups.push(fullPath);
+      continue;
+    }
+    try {
+      fs.rmSync(fullPath, { recursive: true, force: true });
+      removedBackups.push(fullPath);
+    } catch (_) {
+      // Best-effort: a failed removal does not abort the whole prune.
+      // (Mirrors the existing pattern in the cache-version prune above.)
+    }
+  }
+
+  return removedBackups;
+}
+
 module.exports = {
   pruneMarketplaceCache,
   // Internal helpers exposed for testability + future reuse.
   readActiveVersion,
   listCacheVersions,
   sortByMtimeDesc,
+  pruneStaleBackups,
 };

package/lib/core/install-state.cjs

@@ -0,0 +1,242 @@
+'use strict';
+
+/*
+ * lib/core/install-state.cjs -- install-state.json read / write / migrate
+ * module.
+ *
+ * Extracts the inline session-start read+write+derive logic into a focused
+ * single-purpose module; adds the v1 -> v2 schema migration with additive-only
+ * semantics + future-version detection + atomic-write crash safety.
+ *
+ * Phase 126 Plan 07. Canon Part 6 (dog-fooding: schema evolution surfaces only
+ * via shipped harness -- v1 was shipped in v1.13.0-beta.13). Canon Part 7
+ * (reuse: extracts inline session-start write into a module; does NOT
+ * re-architect the write path).
+ *
+ * The wire shape evolves through a single integer sentinel (`schema_version`).
+ * Per CONTEXT.md D3 (LOCKED): integer not semver string (simpler comparison
+ * for additive-only migrations). Per Open Question 5 settlement: `===` integer
+ * equality is the comparison.
+ *
+ * The v1 -> v2 additive-only mapping (CONTEXT.md D3 + Plan 07 must_haves):
+ *
+ *   v1 file (Phase 123, NO schema_version):
+ *     {
+ *       active_root, active_version, topology, installed_at,
+ *       snapshot, surfaces?, resolved_at?, ...
+ *     }
+ *
+ *   v2 file (Phase 126):
+ *     v1-fields-preserved-byte-identical +
+ *     {
+ *       schema_version: 2,
+ *       topology_class: derived from topology (see deriveTopologyClass below),
+ *       last_acceptance_run: null,                  // Plan 03 + Plan 05 fill this
+ *       renderer_contract_version: 'unknown'        // Plan 01 sets this
+ *     }
+ *
+ * Future-version detection: schema_version > 2 -> warn on stderr + DEFER to
+ * /mos:doctor --fix. Do NOT downgrade. Do NOT touch the file. Return a typed
+ * sentinel so callers can decide.
+ *
+ * Atomic write: write to `<path>.tmp`, fsync, rename. A crash between write
+ * and rename leaves the original file untouched. The MOS_TEST_FORCE_FAIL=rename
+ * env-var hook mirrors scripts/doctor.cjs lines ~304-307 -- it injects a throw
+ * at the rename moment so the crash-recovery contract is testable.
+ *
+ * Canon Part 8: this module reads + writes LOCAL files only ($HOME/.mindrian/).
+ * Zero network calls. Zero Brain queries. Zero side-channel to remote services.
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const SCHEMA_VERSION = 2;
+const STATE_FILE_PATH_REL = path.join('.mindrian', 'install-state.json');
+
+function statePath(home) {
+  return path.join(home, STATE_FILE_PATH_REL);
+}
+
+/**
+ * readInstallState({ home }) -> object | null
+ *
+ * Returns the parsed JSON object, or null when the file is absent OR
+ * unparseable. Never throws -- the goal is a robust read for downstream
+ * consumers (doctor, session-start, the migrator itself). A corrupt file is
+ * surfaced as null so the caller can decide whether to derive-from-scratch
+ * (session-start's existing behavior) or surface a finding (doctor class I).
+ */
+function readInstallState(opts) {
+  const home = (opts && opts.home) || '';
+  if (!home) return null;
+  const p = statePath(home);
+  if (!fs.existsSync(p)) return null;
+  try {
+    return JSON.parse(fs.readFileSync(p, 'utf8'));
+  } catch (_) {
+    // Corrupt file -> null (mirrors doctor.cjs's class-I "absent" finding).
+    return null;
+  }
+}
+
+/**
+ * writeInstallState({ home, state }) -> void
+ *
+ * Atomic write: $HOME/.mindrian/install-state.json.tmp -> fsync -> rename.
+ *
+ * The MOS_TEST_FORCE_FAIL=rename env injection mirrors the doctor.cjs
+ * pattern -- if set, throws AFTER the .tmp write but BEFORE the rename so
+ * tests can verify the original file is left untouched.
+ *
+ * Test-only side note: when MOS_TEST_FORCE_FAIL=rename, the .tmp file is left
+ * on disk; the rename never happens; the original target is untouched. A
+ * subsequent successful call will overwrite the .tmp via openSync('w') so
+ * stale .tmp files are not a long-term hazard.
+ */
+function writeInstallState(opts) {
+  const home = opts.home;
+  const state = opts.state;
+  const p = statePath(home);
+  const tmp = p + '.tmp';
+  // Ensure parent dir exists. Idempotent.
+  fs.mkdirSync(path.dirname(p), { recursive: true });
+  // Atomic write: write to tmp, fsync (best-effort), rename.
+  const fd = fs.openSync(tmp, 'w');
+  try {
+    fs.writeSync(fd, JSON.stringify(state, null, 2) + '\n');
+    try { fs.fsyncSync(fd); } catch (_) { /* fsync best-effort -- some FS lack support */ }
+  } finally {
+    fs.closeSync(fd);
+  }
+  // Test injection point (mirrors scripts/doctor.cjs MOS_TEST_FORCE_FAIL).
+  // Throw AFTER the .tmp write so the original target is byte-identical.
+  if (process.env.MOS_TEST_FORCE_FAIL === 'rename') {
+    throw new Error('MOS_TEST_FORCE_FAIL=rename injection (test-only)');
+  }
+  fs.renameSync(tmp, p);
+}
+
+/**
+ * deriveTopologyClass(topology) -> 'healthy' | 'missing' | 'drifted'
+ *
+ * Canonical 4-state taxonomy from CONTEXT.md D3 + Plan 03 needs.
+ *
+ * Mapping (see PLAN.md Task 2 behavior block):
+ *   marketplace-cache -> healthy   (Claude Code's standard install path)
+ *   direct            -> healthy   (npx round-trip install -- @mindrian_os/install)
+ *   dev-clone         -> healthy   (developer machine -- a clone with a remote)
+ *   not-found         -> missing   (resolver returned null root)
+ *   legacy            -> drifted   (the legacy hand-clone path -- pre-Phase 123)
+ *   <unknown>         -> drifted   (conservative default for any new topology
+ *                                   introduced after this module's release)
+ */
+function deriveTopologyClass(topology) {
+  switch (topology) {
+    case 'marketplace-cache': return 'healthy';
+    case 'direct':            return 'healthy';
+    case 'dev-clone':         return 'healthy';
+    case 'not-found':         return 'missing';
+    case 'legacy':            return 'drifted';
+    default:                  return 'drifted';
+  }
+}
+
+/**
+ * migrateIfNeeded({ home }) -> {
+ *   migrated: boolean,
+ *   // present in v1 -> v2 path:
+ *   fromVersion?: 1, toVersion?: 2,
+ *   // present in v2 path:
+ *   currentVersion?: 2,
+ *   // present in future-version path:
+ *   futureVersion?: true, currentVersion?: number, advice?: string,
+ *   // present in no-file path:
+ *   fileAbsent?: true,
+ * }
+ *
+ * Behavior matrix:
+ *
+ *   File absent
+ *     -> { migrated:false, fileAbsent:true }
+ *     -> Do NOT create the file (creation is session-start's job).
+ *
+ *   File present + no schema_version (or schema_version absent/null)
+ *     -> Treat as v1. Run additive migration. Write back. Return
+ *        { migrated:true, fromVersion:1, toVersion:2 }.
+ *
+ *   File present + schema_version === 2
+ *     -> No-op. Return { migrated:false, currentVersion:2 }.
+ *
+ *   File present + schema_version > 2 (a future-version file)
+ *     -> Emit stderr warn. Do NOT touch the file. Return
+ *        { migrated:false, futureVersion:true, currentVersion:<n>,
+ *          advice:'run /mos:doctor --fix' }.
+ *
+ *   File present + schema_version < 2 (unexpected lower-than-v1, e.g. 0)
+ *     -> Treat as v1 (coerce). Same outcome as the v1 path.
+ *
+ *   File present + corrupt JSON
+ *     -> readInstallState returned null -> indistinguishable from absent at
+ *        this layer -> { migrated:false, fileAbsent:true }. doctor class I
+ *        is the surface that catches corrupt-but-present and offers --fix.
+ */
+function migrateIfNeeded(opts) {
+  const home = opts.home;
+  const state = readInstallState({ home });
+  if (!state) return { migrated: false, fileAbsent: true };
+
+  const sv = state.schema_version;
+  if (typeof sv === 'undefined' || sv === null) {
+    // v1 (or unmarked) -> v2 additive migration.
+    return _runV1ToV2({ home, state });
+  }
+  if (sv === SCHEMA_VERSION) {
+    return { migrated: false, currentVersion: SCHEMA_VERSION };
+  }
+  if (typeof sv === 'number' && sv > SCHEMA_VERSION) {
+    // Future-version: warn + defer. Do NOT downgrade. Do NOT touch the file.
+    process.stderr.write(
+      '[install-state] schema_version ' + sv + ' is newer than the plugin understands (' +
+      SCHEMA_VERSION + '). Skipping migration; run /mos:doctor --fix.\n'
+    );
+    return {
+      migrated: false,
+      futureVersion: true,
+      currentVersion: sv,
+      advice: 'run /mos:doctor --fix',
+    };
+  }
+  // Unexpected lower-than-v1 (e.g. schema_version: 0 or a non-number) -- coerce
+  // to v1 and run the additive migration. This is a safety net; not expected
+  // to fire in practice.
+  return _runV1ToV2({ home, state });
+}
+
+// Internal: perform the v1 -> v2 additive migration + write.
+function _runV1ToV2(opts) {
+  const home = opts.home;
+  const state = opts.state;
+  // Object.assign preserves v1 fields byte-identically; new fields are
+  // appended last (since v2's schema_version is the sentinel, the order
+  // could be reshuffled but additive-on-top is the simplest invariant).
+  const v2 = Object.assign({}, state, {
+    schema_version: SCHEMA_VERSION,
+    topology_class: deriveTopologyClass(state.topology),
+    last_acceptance_run: null,
+    renderer_contract_version: 'unknown',
+  });
+  writeInstallState({ home, state: v2 });
+  return { migrated: true, fromVersion: 1, toVersion: SCHEMA_VERSION };
+}
+
+module.exports = {
+  SCHEMA_VERSION,
+  readInstallState,
+  writeInstallState,
+  migrateIfNeeded,
+  deriveTopologyClass,
+  // Test-only helpers (intentionally exported with leading underscore so
+  // consumers do not depend on them and grep can spot test surface usage).
+  _statePath: statePath,
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mindrian_os/install",
-  "version": "1.13.0-beta.14",
+  "version": "1.13.0-beta.16",
   "description": "Install MindrianOS into Claude Code with one command -- `npx @mindrian_os/install`. Ships the MindrianOS plugin (Larry + PWS methodology + Data Room) plus a setup/diagnostics CLI (install/doctor/update).",
   "scripts": {
     "mcp": "node bin/mindrian-mcp-server.cjs",