@mindrian_os/install 1.13.0-beta.11

package/lib/core/migrations/phase-109-nodes-provenance.cjs

@@ -0,0 +1,339 @@
+'use strict';
+/**
+ * Phase 109 nodes-table provenance migration.
+ *
+ * Implements PROVENANCE.md (Plan 108-02) 6 plus 3 fields contract.
+ * Implements TRUTH-STATES.md (Plan 108-03) status_aliases backfill.
+ * Idempotent via identity.key = 'phase_109_migration_v1' sentinel row.
+ *
+ * BEGIN/COMMIT/ROLLBACK transaction wrapper per Phase 87-06 invariant
+ * (node:sqlite has no transaction(fn) higher-order helper).
+ *
+ * Canon Part 8 invariants:
+ *   - Writes only to room.db.
+ *   - Zero Brain queries.
+ *   - Zero remote egress.
+ *   - Sentinel row identity.phase_109_migration_v1 is local-only.
+ *
+ * Migration shape:
+ *   Step 1. ALTER TABLE nodes ADD COLUMN x9 (each duplicate-resilient).
+ *   Step 1. Backfill from properties JSON via json_extract.
+ *   Step 1. status_aliases assumptions backfill to graph nodes.
+ *   Step 1. state_alias_migration memory_event log per migrated row.
+ *   Step 2. Re-create-table-with-NOT-NULL plus CHECK constraints
+ *           (canonical SQLite 12-step recipe) plus 6 new indices.
+ *   Insert sentinel row.
+ *
+ * Exports:
+ *   runMigration(db) -> { applied, sentinelInserted, backfilledAssumptions }
+ *   SENTINEL_KEY (string)
+ */
+
+const SENTINEL_KEY = 'phase_109_migration_v1';
+
+// New columns added to the legacy 3-column nodes table.
+// Order matters: the re-create-table SELECT in tightenSchema relies on this list
+// matching the destination schema column order.
+const NEW_COLUMNS = [
+  // [colName, ALTER TABLE clause]
+  ['source_path', 'TEXT'],
+  ['created_by', 'TEXT'],
+  ['confidence', 'REAL'],
+  ['review_status', "TEXT DEFAULT 'proposed'"],
+  ['created_at', 'INTEGER'],
+  ['last_seen_at', 'INTEGER'],
+  ['source_section', 'TEXT'],
+  ['confirmed_by', 'TEXT'],
+  ['confirmed_at', 'INTEGER'],
+];
+
+// ----- Helpers -----
+
+function tableExists(db, name) {
+  const row = db.prepare(
+    "SELECT name FROM sqlite_master WHERE type='table' AND name=?"
+  ).get(name);
+  return Boolean(row);
+}
+
+function identityHasUpdatedAt(db) {
+  // Existing identity tables (Phase 84-02 memory-ops.cjs:24-29) have 3 columns
+  // including updated_at TEXT NOT NULL. The Phase 108 PROVENANCE.md contract
+  // assumed 2 columns. Detect at runtime so the sentinel insert builds the
+  // correct INSERT statement.
+  const cols = db.prepare("PRAGMA table_info(identity)").all().map((c) => c.name);
+  return cols.includes('updated_at');
+}
+
+function sentinelPresent(db) {
+  if (!tableExists(db, 'identity')) return false;
+  try {
+    const row = db.prepare('SELECT value FROM identity WHERE key = ?').get(SENTINEL_KEY);
+    return Boolean(row && row.value);
+  } catch (_) {
+    return false;
+  }
+}
+
+function ensureIdentityTable(db) {
+  // Create identity table compatible with both the 3-column memory-ops shape
+  // (Phase 84-02) and the 2-column PROVENANCE.md spec. We default to the
+  // 3-column shape because that is what real rooms ship with; openRoomDb
+  // composition runs initMemorySchema before this migration so the table
+  // already exists in the canonical 3-column form by the time runMigration
+  // is invoked from production. The CREATE IF NOT EXISTS only fires for
+  // hermetic test fixtures that build identity manually.
+  db.exec(
+    "CREATE TABLE IF NOT EXISTS identity (" +
+    "key TEXT PRIMARY KEY, " +
+    "value TEXT NOT NULL, " +
+    "updated_at TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP" +
+    ")"
+  );
+}
+
+function addColumnsIdempotent(db) {
+  // PRAGMA table_info gives us existing column names; skip ALTER for any
+  // already present (safe against partial migrations or parallel races).
+  const existing = new Set(db.prepare('PRAGMA table_info(nodes)').all().map((c) => c.name));
+  for (const [col, clause] of NEW_COLUMNS) {
+    if (existing.has(col)) continue;
+    try {
+      db.exec('ALTER TABLE nodes ADD COLUMN ' + col + ' ' + clause);
+    } catch (err) {
+      // Treat duplicate-column as no-op (parallel migration may have raced).
+      if (!/duplicate column name/i.test(err.message)) throw err;
+    }
+  }
+}
+
+function backfillFromProperties(db) {
+  // source_path: prefer properties.source_path, then properties.source_artifact,
+  // then id for Artifact / Section nodes.
+  db.exec(
+    "UPDATE nodes SET source_path = json_extract(properties, '$.source_path') " +
+    "WHERE source_path IS NULL " +
+    "AND json_extract(properties, '$.source_path') IS NOT NULL"
+  );
+  db.exec(
+    "UPDATE nodes SET source_path = json_extract(properties, '$.source_artifact') " +
+    "WHERE source_path IS NULL " +
+    "AND json_extract(properties, '$.source_artifact') IS NOT NULL"
+  );
+  db.exec(
+    "UPDATE nodes SET source_path = id " +
+    "WHERE source_path IS NULL AND type IN ('Artifact', 'Section')"
+  );
+  // Last-resort source_path fallback so the NOT NULL Step 2 constraint is
+  // satisfiable for every legacy row. PROVENANCE.md L125 mandates "sensible
+  // defaults" when JSON fields are missing; we synthesize a path-like handle
+  // from the node id so provenance is at minimum self-referential.
+  db.exec(
+    "UPDATE nodes SET source_path = 'unknown:' || id WHERE source_path IS NULL"
+  );
+
+  // created_at: epoch ms from properties.created (ISO string) or fall back to now.
+  db.exec(
+    "UPDATE nodes SET created_at = CAST(strftime('%s', json_extract(properties, '$.created')) AS INTEGER) * 1000 " +
+    "WHERE created_at IS NULL AND json_extract(properties, '$.created') IS NOT NULL"
+  );
+  db.exec(
+    "UPDATE nodes SET created_at = CAST(strftime('%s', 'now') AS INTEGER) * 1000 WHERE created_at IS NULL"
+  );
+
+  // last_seen_at: same as created_at on first migration (drives stale-marker job later).
+  db.exec('UPDATE nodes SET last_seen_at = created_at WHERE last_seen_at IS NULL');
+
+  // confidence: string enum to REAL; preserve existing REAL / INTEGER values.
+  db.exec(
+    "UPDATE nodes SET confidence = CASE " +
+    "WHEN typeof(json_extract(properties, '$.confidence')) = 'real' THEN json_extract(properties, '$.confidence') " +
+    "WHEN typeof(json_extract(properties, '$.confidence')) = 'integer' THEN json_extract(properties, '$.confidence') " +
+    "WHEN json_extract(properties, '$.confidence') = 'high' THEN 0.8 " +
+    "WHEN json_extract(properties, '$.confidence') = 'medium' THEN 0.5 " +
+    "WHEN json_extract(properties, '$.confidence') = 'low' THEN 0.3 " +
+    "ELSE NULL END " +
+    "WHERE confidence IS NULL"
+  );
+
+  // created_by + review_status defaults for legacy rows.
+  db.exec("UPDATE nodes SET created_by = 'system' WHERE created_by IS NULL");
+  db.exec("UPDATE nodes SET review_status = 'proposed' WHERE review_status IS NULL");
+
+  // source_section from properties.section.
+  db.exec(
+    "UPDATE nodes SET source_section = json_extract(properties, '$.section') " +
+    "WHERE source_section IS NULL AND json_extract(properties, '$.section') IS NOT NULL"
+  );
+
+  // source_section fallback: section nodes use their own id.
+  db.exec(
+    "UPDATE nodes SET source_section = id " +
+    "WHERE source_section IS NULL AND type = 'section'"
+  );
+}
+
+function backfillAssumptionsAsGraphNodes(db) {
+  if (!tableExists(db, 'assumptions')) return 0;
+
+  // Promote each assumptions row to a graph node via status_aliases mapping.
+  // assumptions.id is INTEGER per memory-ops.cjs:65 so we cast to TEXT for the
+  // node id construction. INSERT OR IGNORE makes the operation idempotent if
+  // the migration is re-run somehow (defense in depth on top of sentinel).
+  const insertNodes = db.prepare(
+    "INSERT OR IGNORE INTO nodes " +
+    "(id, type, properties, source_path, created_by, confidence, " +
+    " review_status, created_at, last_seen_at, source_section) " +
+    "SELECT " +
+    "  'assumption:' || CAST(a.id AS TEXT), " +
+    "  'assumption', " +
+    "  json_object(" +
+    "    'claim', a.claim, " +
+    "    'evidence_for', a.evidence_for, " +
+    "    'evidence_against', a.evidence_against, " +
+    "    'legacy_validity', a.validity" +
+    "  ), " +
+    "  COALESCE(a.section, 'unknown'), " +
+    "  'system', " +
+    "  NULL, " +
+    "  CASE a.validity " +
+    "    WHEN 'untested' THEN 'proposed' " +
+    "    WHEN 'supported' THEN 'validated' " +
+    "    WHEN 'contradicted' THEN 'invalidated' " +
+    "    WHEN 'stale' THEN 'stale' " +
+    "  END, " +
+    "  CAST(strftime('%s', a.created_at) AS INTEGER) * 1000, " +
+    "  CAST(strftime('%s', COALESCE(a.last_tested, a.created_at)) AS INTEGER) * 1000, " +
+    "  a.section " +
+    "FROM assumptions a"
+  );
+  insertNodes.run();
+
+  // Log one state_alias_migration memory_event per assumption row.
+  // Phase 108 TRUTH-STATES.md L68 mandates one event per migrated row.
+  const nowMs = Date.now();
+  const insertEvents = db.prepare(
+    "INSERT OR IGNORE INTO nodes " +
+    "(id, type, properties, source_path, created_by, confidence, " +
+    " review_status, created_at, last_seen_at) " +
+    "SELECT " +
+    "  'memory_event:state_alias_migration:' || CAST(a.id AS TEXT), " +
+    "  'memory_event', " +
+    "  json_object(" +
+    "    'event_type', 'state_alias_migration', " +
+    "    'target_node_id', 'assumption:' || CAST(a.id AS TEXT), " +
+    "    'from_validity', a.validity, " +
+    "    'to_review_status', CASE a.validity " +
+    "      WHEN 'untested' THEN 'proposed' " +
+    "      WHEN 'supported' THEN 'validated' " +
+    "      WHEN 'contradicted' THEN 'invalidated' " +
+    "      WHEN 'stale' THEN 'stale' " +
+    "    END" +
+    "  ), " +
+    "  'phase-109-migration', " +
+    "  'system', " +
+    "  NULL, " +
+    "  'confirmed', " +
+    "  ?, ? " +
+    "FROM assumptions a"
+  );
+  insertEvents.run(nowMs, nowMs);
+
+  return db.prepare("SELECT COUNT(*) AS n FROM assumptions").get().n;
+}
+
+function tightenSchemaWithCheckConstraints(db) {
+  // Step 2: re-create-table-with-NOT-NULL plus CHECK constraints.
+  // Canonical SQLite 12-step recipe (foreign_keys disabled for the duration;
+  // operation runs inside the caller's BEGIN/COMMIT transaction).
+  //
+  // Note: foreign_keys PRAGMA cannot be changed inside a transaction, so we
+  // do not flip it here; the BEGIN/COMMIT wrapper guarantees atomicity, and
+  // FK behavior is unchanged because the only FK targeting nodes is from edges
+  // which we do not drop.
+  db.exec(
+    "CREATE TABLE nodes_new (" +
+    "  id TEXT PRIMARY KEY, " +
+    "  type TEXT NOT NULL, " +
+    "  properties TEXT DEFAULT '{}', " +
+    "  source_path TEXT NOT NULL, " +
+    "  created_by TEXT NOT NULL CHECK(created_by IN ('user','larry','import','brain','system')), " +
+    "  confidence REAL, " +
+    "  review_status TEXT NOT NULL DEFAULT 'proposed' " +
+    "    CHECK(review_status IN ('proposed','confirmed','rejected','stale','superseded','needs_evidence','validated','invalidated')), " +
+    "  created_at INTEGER NOT NULL, " +
+    "  last_seen_at INTEGER NOT NULL, " +
+    "  source_section TEXT, " +
+    "  confirmed_by TEXT, " +
+    "  confirmed_at INTEGER" +
+    ")"
+  );
+
+  db.exec(
+    "INSERT INTO nodes_new " +
+    "SELECT id, type, properties, source_path, created_by, confidence, " +
+    "       review_status, created_at, last_seen_at, source_section, " +
+    "       confirmed_by, confirmed_at " +
+    "FROM nodes"
+  );
+  db.exec('DROP TABLE nodes');
+  db.exec('ALTER TABLE nodes_new RENAME TO nodes');
+
+  // Recreate the existing index plus the 6 new ones (mandatory + recommended
+  // per PROVENANCE.md L97-104).
+  db.exec('CREATE INDEX IF NOT EXISTS idx_nodes_type ON nodes(type)');
+  db.exec('CREATE INDEX IF NOT EXISTS idx_nodes_review_status ON nodes(review_status)');
+  db.exec('CREATE INDEX IF NOT EXISTS idx_nodes_source_path ON nodes(source_path)');
+  db.exec('CREATE INDEX IF NOT EXISTS idx_nodes_created_by ON nodes(created_by)');
+  db.exec('CREATE INDEX IF NOT EXISTS idx_nodes_created_at ON nodes(created_at)');
+  db.exec('CREATE INDEX IF NOT EXISTS idx_nodes_last_seen_at ON nodes(last_seen_at)');
+  db.exec(
+    'CREATE INDEX IF NOT EXISTS idx_nodes_confirmed_by ON nodes(confirmed_by) ' +
+    'WHERE confirmed_by IS NOT NULL'
+  );
+}
+
+function insertSentinel(db) {
+  const now = new Date().toISOString();
+  if (identityHasUpdatedAt(db)) {
+    db.prepare(
+      "INSERT OR REPLACE INTO identity (key, value, updated_at) VALUES (?, ?, ?)"
+    ).run(SENTINEL_KEY, now, now);
+  } else {
+    // Fallback for the 2-column PROVENANCE.md spec (legacy / hypothetical).
+    db.prepare(
+      "INSERT OR REPLACE INTO identity (key, value) VALUES (?, ?)"
+    ).run(SENTINEL_KEY, now);
+  }
+}
+
+// ----- Public API -----
+
+/**
+ * Run the Phase 109 nodes-provenance migration. Idempotent.
+ *
+ * @param {import('node:sqlite').DatabaseSync} db
+ * @returns {{applied: boolean, sentinelInserted: boolean, backfilledAssumptions: number}}
+ */
+function runMigration(db) {
+  ensureIdentityTable(db);
+  if (sentinelPresent(db)) {
+    return { applied: false, sentinelInserted: false, backfilledAssumptions: 0 };
+  }
+  let backfilledAssumptions = 0;
+  db.exec('BEGIN');
+  try {
+    addColumnsIdempotent(db);
+    backfillFromProperties(db);
+    backfilledAssumptions = backfillAssumptionsAsGraphNodes(db);
+    tightenSchemaWithCheckConstraints(db);
+    insertSentinel(db);
+    db.exec('COMMIT');
+  } catch (err) {
+    try { db.exec('ROLLBACK'); } catch (_rbErr) { /* ignore */ }
+    throw err;
+  }
+  return { applied: true, sentinelInserted: true, backfilledAssumptions };
+}
+
+module.exports = { runMigration, SENTINEL_KEY };

package/lib/core/migrations/phase-109-session-focus.cjs

@@ -0,0 +1,99 @@
+'use strict';
+// Phase 109 session_focus table migration. Idempotent via identity sentinel.
+// Runs AFTER Plan 109-01 nodes-provenance migration (FK target schema must exist).
+//
+// Parallel-worktree note (Phase 109-02 isolated execution):
+// This migration is authored to run primarily against the post-109-01 nodes
+// schema (12 columns including source_path / created_by / confidence /
+// review_status / created_at / last_seen_at). When 109-01 has not yet run in
+// the same worktree, ensureProvenanceColumns() defensively backfills the
+// missing nodes columns via additive ALTER TABLE so the FK target accepts
+// our test fixtures (which insert with all 9 provenance fields). The 109-01
+// canonical migration will re-add the same columns idempotently when it
+// later runs in the merged trunk; ALTER TABLE ADD COLUMN IF NOT EXISTS
+// semantics (we wrap each in try/catch since SQLite < 3.35 lacks IF NOT
+// EXISTS on ADD COLUMN) keep the operation safe in either order.
+
+const SENTINEL_KEY = 'phase_109_session_focus_v1';
+
+function sentinelPresent(db) {
+  try {
+    const row = db.prepare('SELECT value FROM identity WHERE key = ?').get(SENTINEL_KEY);
+    return Boolean(row && row.value);
+  } catch (_) {
+    return false;
+  }
+}
+
+function ensureIdentityTable(db) {
+  // identity table is canonically created by memory-ops.cjs initMemorySchema
+  // with shape (key TEXT PK, value TEXT NOT NULL, updated_at TEXT NOT NULL).
+  // We re-issue CREATE TABLE IF NOT EXISTS as a safety net for callers that
+  // skip initMemorySchema; the IF NOT EXISTS clause makes this a no-op when
+  // memory-ops already created the table.
+  db.exec(
+    "CREATE TABLE IF NOT EXISTS identity (" +
+    "key TEXT PRIMARY KEY, " +
+    "value TEXT NOT NULL, " +
+    "updated_at TEXT NOT NULL" +
+    ")"
+  );
+}
+
+// Defensive backfill of 109-01 provenance columns when running in a parallel
+// worktree where 109-01 has not yet executed. Each ADD COLUMN is wrapped in a
+// try/catch so re-runs (when 109-01 has already added the column) are no-ops.
+// This is additive ONLY; it never alters existing column types or drops data.
+function ensureProvenanceColumns(db) {
+  const additions = [
+    "ALTER TABLE nodes ADD COLUMN source_path TEXT",
+    "ALTER TABLE nodes ADD COLUMN created_by TEXT",
+    "ALTER TABLE nodes ADD COLUMN confidence REAL",
+    "ALTER TABLE nodes ADD COLUMN review_status TEXT",
+    "ALTER TABLE nodes ADD COLUMN created_at INTEGER",
+    "ALTER TABLE nodes ADD COLUMN last_seen_at INTEGER",
+    "ALTER TABLE nodes ADD COLUMN source_section TEXT",
+  ];
+  for (const sql of additions) {
+    try {
+      db.exec(sql);
+    } catch (_e) {
+      // Column already exists or table missing; either is acceptable here.
+      // The migration cannot proceed if nodes table is absent; that error
+      // surfaces below at session_focus FK creation time.
+    }
+  }
+}
+
+function runMigration(db) {
+  ensureIdentityTable(db);
+  if (sentinelPresent(db)) {
+    return { applied: false };
+  }
+  // Defensive backfill BEFORE creating session_focus, so the FK target column
+  // set is present whether or not 109-01 has run in this worktree.
+  ensureProvenanceColumns(db);
+  db.exec('BEGIN');
+  try {
+    db.exec(
+      "CREATE TABLE IF NOT EXISTS session_focus ( " +
+      "session_id    TEXT PRIMARY KEY, " +
+      "focus_node_id TEXT NOT NULL, " +
+      "focus_type    TEXT NOT NULL, " +
+      "set_at        INTEGER NOT NULL, " +
+      "set_by        TEXT NOT NULL CHECK(set_by IN ('user','larry','auto-from-jtbd','auto-from-operator','auto-from-state')), " +
+      "FOREIGN KEY (focus_node_id) REFERENCES nodes(id) " +
+      ")"
+    );
+    db.exec("CREATE INDEX IF NOT EXISTS idx_session_focus_set_at ON session_focus(set_at DESC)");
+    const nowIso = new Date().toISOString();
+    db.prepare("INSERT OR REPLACE INTO identity (key, value, updated_at) VALUES (?, ?, ?)").run(SENTINEL_KEY, nowIso, nowIso);
+    db.exec('COMMIT');
+  } catch (err) {
+    db.exec('ROLLBACK');
+    throw err;
+  }
+  return { applied: true };
+}
+
+module.exports = { runMigration, SENTINEL_KEY };

package/lib/core/model-profiles.cjs

@@ -0,0 +1,246 @@
+/**
+ * MindrianOS Plugin - Model Profiles & Routing
+ * Maps agents to model aliases across profile tiers, venture stages, and cascade steps.
+ * Pure Node.js built-ins only. No npm dependencies.
+ */
+
+'use strict';
+
+const path = require('path');
+const os = require('os');
+const { safeReadFile } = require('./index.cjs');
+const { getState } = require('./state-ops.cjs');
+
+/**
+ * MODEL_PROFILES: 8 agents x 3 profile tiers (quality/balanced/budget).
+ * Each value is a model alias (opus, sonnet, haiku).
+ */
+const MODEL_PROFILES = {
+  'larry-extended':      { quality: 'opus',   balanced: 'opus',   budget: 'sonnet' },
+  'framework-runner':    { quality: 'opus',   balanced: 'opus',   budget: 'sonnet' },
+  'grading':             { quality: 'opus',   balanced: 'opus',   budget: 'sonnet' },
+  'investor':            { quality: 'opus',   balanced: 'sonnet', budget: 'sonnet' },
+  'brain-query':         { quality: 'opus',   balanced: 'sonnet', budget: 'haiku'  },
+  'research':            { quality: 'opus',   balanced: 'sonnet', budget: 'haiku'  },
+  'opportunity-scanner': { quality: 'sonnet', balanced: 'sonnet', budget: 'haiku'  },
+  'persona-analyst':     { quality: 'sonnet', balanced: 'sonnet', budget: 'haiku'  },
+};
+
+/** Valid profile tier names */
+const VALID_PROFILES = ['quality', 'balanced', 'budget'];
+
+/**
+ * STAGE_HINTS: Venture-stage adaptive model hints.
+ * null means "skip" - agent should not run at this stage.
+ */
+const STAGE_HINTS = {
+  'Pre-Opportunity': { 'framework-runner': 'sonnet', 'research': 'haiku',  'grading': null,     'investor': null     },
+  'Discovery':       { 'framework-runner': 'opus',   'research': 'sonnet', 'grading': 'sonnet', 'investor': null     },
+  'Validation':      { 'framework-runner': 'opus',   'research': 'sonnet', 'grading': 'opus',   'investor': 'sonnet' },
+  'Design':          { 'framework-runner': 'opus',   'research': 'sonnet', 'grading': 'opus',   'investor': 'sonnet' },
+  'Investment':      { 'framework-runner': 'opus',   'research': 'opus',   'grading': 'opus',   'investor': 'opus'   },
+};
+
+/** Valid venture stage names */
+const VALID_STAGES = ['Pre-Opportunity', 'Discovery', 'Validation', 'Design', 'Investment'];
+
+/**
+ * CASCADE_MODELS: Model assignments for cascade pipeline steps.
+ * null means the step uses no LLM (pure computation).
+ */
+const CASCADE_MODELS = {
+  'classify':           'haiku',
+  'detect-edges':       'sonnet',
+  'proactive-analysis': 'sonnet',
+  'hsi-to-graph':       'haiku',
+  'compute-state':      null,
+};
+
+/**
+ * Load room config from .config.json with graceful defaults.
+ * Tries room-level first, then global ~/.mindrian/defaults.json.
+ * @param {string} roomDir - Path to room directory
+ * @returns {{ model_profile: string, model_overrides: Object }}
+ */
+function loadRoomConfig(roomDir) {
+  const defaults = { model_profile: 'quality', model_overrides: {} };
+
+  // Try room-level config
+  const roomConfigPath = path.join(roomDir, '.config.json');
+  const roomRaw = safeReadFile(roomConfigPath);
+  if (roomRaw) {
+    try {
+      const parsed = JSON.parse(roomRaw);
+      return { ...defaults, ...parsed };
+    } catch (_) {
+      // Fall through on parse error
+    }
+  }
+
+  // Try global config
+  const globalConfigPath = path.join(os.homedir(), '.mindrian', 'defaults.json');
+  const globalRaw = safeReadFile(globalConfigPath);
+  if (globalRaw) {
+    try {
+      const parsed = JSON.parse(globalRaw);
+      return { ...defaults, ...parsed };
+    } catch (_) {
+      // Fall through on parse error
+    }
+  }
+
+  return defaults;
+}
+
+/**
+ * Parse venture stage from room STATE.md.
+ * @param {string} roomDir - Path to room directory
+ * @returns {string|null} Valid stage name or null
+ */
+function parseVentureStage(roomDir) {
+  const stateContent = getState(roomDir);
+  if (!stateContent) return null;
+
+  const match = stateContent.match(/(?:Venture\s+)?Stage:\s*(.+)/i);
+  if (!match) return null;
+
+  const rawStage = match[1].trim();
+  const found = VALID_STAGES.find(s => s.toLowerCase() === rawStage.toLowerCase());
+  return found || null;
+}
+
+/**
+ * Resolve model alias for a given agent in a room context.
+ * 5-step cascade: override > stage-hint > inherit > profile > default.
+ * @param {string} roomDir - Path to room directory
+ * @param {string} agentType - Agent key from MODEL_PROFILES
+ * @returns {string} Model alias or 'skip'
+ */
+function resolveModel(roomDir, agentType) {
+  const config = loadRoomConfig(roomDir);
+
+  // Step 1: Per-agent override
+  if (config.model_overrides && config.model_overrides[agentType]) {
+    return config.model_overrides[agentType];
+  }
+
+  // Step 2: Venture-stage hint
+  const stage = parseVentureStage(roomDir);
+  if (stage && STAGE_HINTS[stage]) {
+    const hint = STAGE_HINTS[stage][agentType];
+    if (hint === null) return 'skip';
+    if (typeof hint === 'string') return hint;
+    // Agent not in stage hints - fall through
+  }
+
+  // Step 3: Inherit profile
+  if (config.model_profile === 'inherit') {
+    return 'inherit';
+  }
+
+  // Step 4: Profile lookup
+  const profile = config.model_profile || 'quality';
+  if (MODEL_PROFILES[agentType] && MODEL_PROFILES[agentType][profile]) {
+    return MODEL_PROFILES[agentType][profile];
+  }
+
+  // Step 5: Default
+  return 'sonnet';
+}
+
+/**
+ * Resolve model for a cascade pipeline step.
+ * @param {string} step - Cascade step key
+ * @returns {string|null} Model alias, null, or 'sonnet' fallback
+ */
+function resolveCascadeModel(step) {
+  if (step in CASCADE_MODELS) {
+    return CASCADE_MODELS[step];
+  }
+  return 'sonnet';
+}
+
+/**
+ * Format a human-readable table of current model resolution for a room.
+ * @param {string} roomDir - Path to room directory
+ * @returns {string} Formatted table string
+ */
+function formatProfileTable(roomDir) {
+  const config = loadRoomConfig(roomDir);
+  const stage = parseVentureStage(roomDir);
+  const profile = config.model_profile || 'quality';
+
+  let lines = [];
+  lines.push(`Profile: ${profile}` + (stage ? `  |  Stage: ${stage}` : ''));
+  lines.push('');
+
+  // Agent table header
+  const agentWidth = 22;
+  const modelWidth = 10;
+  const sourceWidth = 20;
+  const sep = '-'.repeat(agentWidth + 2) + '+' + '-'.repeat(modelWidth + 2) + '+' + '-'.repeat(sourceWidth + 2);
+  lines.push(' ' + 'Agent'.padEnd(agentWidth) + ' | ' + 'Model'.padEnd(modelWidth) + ' | ' + 'Source'.padEnd(sourceWidth));
+  lines.push(sep);
+
+  for (const agent of Object.keys(MODEL_PROFILES)) {
+    const resolved = resolveModel(roomDir, agent);
+    let source = '(default)';
+
+    if (config.model_overrides && config.model_overrides[agent]) {
+      source = '(override)';
+    } else if (stage && STAGE_HINTS[stage] && agent in STAGE_HINTS[stage]) {
+      source = `(stage: ${stage})`;
+    } else if (profile === 'inherit') {
+      source = '(inherit)';
+    } else if (MODEL_PROFILES[agent] && MODEL_PROFILES[agent][profile]) {
+      source = '(profile)';
+    }
+
+    lines.push(' ' + agent.padEnd(agentWidth) + ' | ' + String(resolved).padEnd(modelWidth) + ' | ' + source);
+  }
+
+  // Cascade section
+  lines.push('');
+  lines.push('Cascade Steps:');
+  lines.push(sep);
+
+  for (const [step, model] of Object.entries(CASCADE_MODELS)) {
+    const display = model === null ? 'none' : model;
+    lines.push(' ' + step.padEnd(agentWidth) + ' | ' + display.padEnd(modelWidth) + ' | (cascade)');
+  }
+
+  return lines.join('\n');
+}
+
+// CLI interface
+if (require.main === module) {
+  const args = process.argv.slice(2);
+  const subcmd = args[0];
+
+  if (subcmd === 'resolve' && args.length >= 3) {
+    const result = resolveModel(args[1], args[2]);
+    process.stdout.write(result + '\n');
+  } else if (subcmd === 'cascade' && args.length >= 2) {
+    const result = resolveCascadeModel(args[1]);
+    process.stdout.write((result === null ? 'null' : result) + '\n');
+  } else if (subcmd === 'table' && args.length >= 2) {
+    process.stdout.write(formatProfileTable(args[1]) + '\n');
+  } else if (subcmd === 'profile' && args.length >= 2) {
+    process.stdout.write(JSON.stringify(loadRoomConfig(args[1]), null, 2) + '\n');
+  } else {
+    process.stderr.write('Usage: node model-profiles.cjs <resolve|cascade|table|profile> [args...]\n');
+    process.exit(1);
+  }
+}
+
+module.exports = {
+  MODEL_PROFILES,
+  VALID_PROFILES,
+  STAGE_HINTS,
+  CASCADE_MODELS,
+  loadRoomConfig,
+  parseVentureStage,
+  resolveModel,
+  resolveCascadeModel,
+  formatProfileTable,
+};