// `runtime diagnose` (CV22.DS7.TS3 plateau 3b). Port of the drift-diagnosis // half of `src/memory/cli/runtime.py`. // // Diagnose is the read-only "what is wrong with this install?" pass: filesystem // posture, recent front-door errors, FTS index health, and everything the // status readers already found, flattened into ordered findings. It must never // repair, migrate, or write -- a diagnosis that changes the thing it is // diagnosing reports a state it created. // // ONE RECORDED DIVERGENCE (D3), the same class the Navigator settled for the // manifest notes in plateau 3a: `fts_corrupt` embeds the DRIVER's error text, // and the two drivers describe the same corruption differently -- // // Python: database disk image is malformed // Node: fts5: corruption found reading blob 10 from table "memories_fts" // // -- because they link different SQLite builds. Mirror's own words around it // are byte-identical, and the golden pins those and records both tails. TS is // not normalized to Python's string: the message is driver-dependent rather // than a fixed mapping, so translating it would invent an answer, and Node's // is the more actionable of the two. // // NOT ported: a live model catalog call. `probeModelPins` runs against the DS5 // replay substrate or reports inconclusive, exactly as the oracle reports // inconclusive without a key; the live fetch belongs to DS8. import { accessSync, constants, existsSync, readdirSync, readFileSync, statSync } from "node:fs"; import { basename, dirname, join, posix, win32 } from "node:path"; import { openDatabaseReadOnly } from "#db/database.ts"; import { type ExtensionPluginReport, extensionPluginDirectory, extensionPluginRoot, readExtensionPlugin, } from "#extensions/extensionPlugin.ts"; import { identityKeyBreaksGrammar, SLUG_KEYED_LAYERS } from "#identity/identityKey.ts"; import { hasOpenRouterKey, keyFileInstruction, REASONING_EFFORTS, resolveExtractionReasoning, } from "#providers/config.ts"; import { pyRepr, sortByCodePoint } from "#util/pythonText.ts"; import { configFilePath } from "./config.ts"; import { extensionPluginStates } from "./extensionPluginWiring.ts"; import type { GitWorktreeEntry } from "./git.ts"; import { agyPluginCopyState, codexPluginCacheState, grokPluginCopyState, installedPluginVersion, pluginLinkState, } from "./pluginWiring.ts"; import type { RuntimeStatusReport } from "./status.ts"; import { agyPluginInstallCommand, CODEX_PLUGIN_ADD_COMMAND, grokPluginReinstallCommand, } from "./wiring.ts"; export interface DriftFinding { code: string; severity: string; subject: string; detail: string; recommendation: string; repair_route: string; } /** * CV9.E2.S6 — the homes root (`~/.mirror-minds`) holds user-home directories * and nothing else. A known runtime directory sitting directly in the root is * a legacy artifact of the pre-containment resolution rule. */ const ROOT_RUNTIME_DIR_NAMES = new Set(["backups"]); const FRONT_DOOR_WINDOW_MS = 24 * 60 * 60 * 1000; const FRONT_DOOR_TAIL_LINES = 1000; const FTS_PROBE_TERM = "mirror_fts_integrity_probe"; /** Port of `_git_dirty_finding`. */ export function gitDirtyFinding(entry: GitWorktreeEntry): DriftFinding { const isSessionHtml = entry.path.startsWith("pi-session-") && entry.path.endsWith(".html"); let recommendation: string; let repairRoute: string; if (entry.status === "??" && isSessionHtml) { recommendation = "archive or ignore generated session HTML before update planning"; repairRoute = "manual review"; } else if (entry.status === "??") { recommendation = "review untracked file before update planning"; repairRoute = "manual review"; } else { recommendation = "commit, stash, or discard intentional work before update planning"; repairRoute = "commit or manual review"; } return { code: "git_dirty", severity: "attention", subject: "repository", detail: `${entry.status} ${entry.path}`, recommendation, repair_route: repairRoute, }; } /** * Port of `scan_homes_root_state`: files and known runtime directories sitting * directly in the homes root. User homes and hidden entries (`.DS_Store`) are * not offenders. */ export function scanHomesRootState(homesRoot: string): string[] { let names: string[]; try { names = sortByCodePoint(readdirSync(homesRoot)); } catch { return []; } const offenders: string[] = []; for (const name of names) { if (name.startsWith(".")) continue; const full = join(homesRoot, name); let isFile: boolean; try { isFile = statSync(full).isFile(); } catch { continue; } if (isFile || ROOT_RUNTIME_DIR_NAMES.has(name)) offenders.push(full); } return offenders; } /** Port of `root_state_findings`. */ export function rootStateFindings(homesRoot: string): DriftFinding[] { return scanHomesRootState(homesRoot).map((path) => ({ code: "legacy_root_runtime_state", severity: "attention", subject: `homes root ${homesRoot}`, detail: path, recommendation: "relocate into the owning mirror home " + "(see REFERENCE.md — Relocating legacy root runtime state)", repair_route: "manual relocation", })); } /** * Port of `_loose_permission_findings`. The mirror home holds a person's * identity, memories, and conversations; the expected posture is owner-only. * Creation points enforce it -- this only reports drift on installs that * predate the rule. POSIX only, as in the oracle: Windows ACLs are out of scope. * * Since CV22.DS10.US3 (D3) the user's config file is a target too: it is where * `OPENROUTER_API_KEY` lives. `init` creates it 0600; a hand-made one may not be. */ export function loosePermissionFindings( report: RuntimeStatusReport, configFile: string | null = configFilePath(), ): DriftFinding[] { if (process.platform === "win32") return []; const targets: [string, string][] = []; if (report.mirror_home !== null && report.mirror_home_error === null) { targets.push(["mirror home", report.mirror_home]); } if (report.db_path !== null && report.db_exists) targets.push(["database", report.db_path]); if (configFile !== null && existsSync(configFile)) targets.push(["config file", configFile]); const findings: DriftFinding[] = []; for (const [area, path] of targets) { let stats: ReturnType; try { stats = statSync(path); } catch { continue; } const mode = stats.mode & 0o777; if ((mode & 0o077) === 0) continue; const wanted = stats.isDirectory() ? "700" : "600"; findings.push({ code: "loose_permissions", severity: "attention", subject: area, detail: `${path} is group/other-accessible (mode ${mode.toString(8)})`, recommendation: "mirror data should be owner-only; restrict directories to 700 and files to 600", repair_route: `chmod ${wanted} ${path}`, }); } return findings; } /** * Python `datetime.fromisoformat(value.replace("Z", "+00:00"))`, narrowed to * what the front door actually writes (`Date.toISOString()`). * * Returns null for anything unparseable AND for a timestamp with no offset. * The oracle parses a naive timestamp successfully and then raises TypeError * comparing it to an aware cutoff -- an uncaught crash in a read-only * diagnostic. Unreachable with the current writer, which always emits `Z`, so * this is not a behavioral divergence on any log the front door produces; it * is a crash not worth porting. Captured for Debt Review. */ function parseLogTimestamp(value: string): number | null { if (!/(?:Z|[+-]\d{2}:\d{2})$/.test(value)) return null; const parsed = Date.parse(value); return Number.isNaN(parsed) ? null : parsed; } /** * Port of `_front_door_error_findings` (CR026). The front door appends * redacted, metadata-only lines; a non-green summary when ERROR lines appear * in the last 24h keeps backup, guard, and routing failures from being * invisible. */ export function frontDoorErrorFindings( report: RuntimeStatusReport, now: Date = new Date(), ): DriftFinding[] { if (report.db_path === null) return []; const logPath = join(dirname(report.db_path), "front-door.log"); if (!existsSync(logPath)) return []; const cutoff = now.getTime() - FRONT_DOOR_WINDOW_MS; let lines: string[]; try { // `errors="replace"` in the oracle; Node's utf8 decode substitutes U+FFFD // for the same malformed bytes, so a corrupt line is skipped, not fatal. lines = readFileSync(logPath, "utf8").split("\n"); } catch { return []; } // Python's `splitlines()` drops a trailing empty segment; `split` does not. if (lines.at(-1) === "") lines.pop(); let recentErrors = 0; for (const line of lines.slice(-FRONT_DOOR_TAIL_LINES)) { const parts = line.split("\t"); if (parts.length < 2 || parts[1] !== "ERROR") continue; const stamp = parseLogTimestamp(parts[0] as string); if (stamp === null) continue; if (stamp >= cutoff) recentErrors += 1; } if (recentErrors === 0) return []; return [ { code: "front_door_errors", severity: "attention", subject: "front door", detail: `${recentErrors} front-door error(s) in the last 24h (${logPath})`, recommendation: "inspect the front-door log; rule out routing, schema-guard, and backup failures", repair_route: "review front-door.log", }, ]; } /** * CR104: one finding per journey slug or persona id outside the grammar * (`#identity/identityKey.ts`). A new key cannot break it any more, so each one * found here predates the rule. It keeps working, and nothing rewrites it: renaming * a key that other tables copy is not a repair to make silently. What quoting * cannot cover is named instead. Mirror quotes the key in every command it prints, * but an agent may put it into a command of its own. * * The key is printed escaped, so a newline or a terminal escape in it cannot forge * the report. A database that cannot be read, or has no identity table, reports * nothing; other findings say why it cannot be read. */ export function identityKeyFindings( report: Pick, ): DriftFinding[] { if (report.db_path === null || !report.db_exists) return []; const layers = SLUG_KEYED_LAYERS.map(() => "?").join(", "); let rows: { layer: string; key: string }[]; try { const db = openDatabaseReadOnly(report.db_path); try { rows = db .prepare(`SELECT layer, key FROM identity WHERE layer IN (${layers}) ORDER BY layer, key`) .all(...SLUG_KEYED_LAYERS) .map((row) => ({ layer: String(row.layer), key: String(row.key) })); } finally { db.close(); } } catch { return []; } return rows .filter((row) => identityKeyBreaksGrammar(row.layer, row.key)) .map((row) => ({ code: "identity_key_outside_grammar", severity: "attention", subject: row.layer, detail: pyRepr(row.key), recommendation: "an agent may put this key into a shell command unquoted; recreate it under a " + "kebab-case key (lowercase letters, digits, and single hyphens)", repair_route: "manual review", })); } /** * Port of `_fts_consistency_findings` (CR021). `memories_fts` is an * external-content FTS5 index kept in sync by triggers, so a row-count * comparison cannot detect desync -- the count always mirrors the content * table. A corrupt index, however, raises on any MATCH, which makes a probe * query a genuine read-only detector. The authoritative FTS5 * `integrity-check` needs a writable handle and lives in the write path. * * See D3 in the module header for the driver-text divergence this carries. */ export function ftsConsistencyFindings(report: RuntimeStatusReport): DriftFinding[] { if (report.db_path === null || !report.db_exists) return []; let db: ReturnType; try { db = openDatabaseReadOnly(report.db_path); } catch { return []; } try { const tables = db.prepare("SELECT name FROM sqlite_master WHERE type = 'table'").all() as { name: string; }[]; if (!tables.some((row) => row.name === "memories_fts")) return []; db.prepare("SELECT rowid FROM memories_fts WHERE memories_fts MATCH ? LIMIT 1").get( FTS_PROBE_TERM, ); } catch (error) { const detail = error instanceof Error ? error.message : String(error); return [ { code: "fts_corrupt", severity: "attention", subject: "memories_fts", detail: `FTS query failed (${detail}); the index may be corrupt or desynced`, recommendation: "rebuild the FTS index: INSERT INTO memories_fts(memories_fts) VALUES('rebuild')", repair_route: "rebuild memories_fts", }, ]; } finally { db.close(); } return []; } /** A deferred close tail waits for a session start; after this long, nobody started one. */ const DEFERRED_CLOSE_TAIL_STALE_MS = 24 * 60 * 60 * 1000; /** * CV21.DS4.TS2: a runtime that bounds its SessionEnd hook (Codex, Grok) closes * without the LLM tail and flags the conversation for the next session start to * finish. A user whose last session was on such a runtime, and who starts no * session for a day, has memories and titles waiting and nothing saying so: * this is the one place that says so. Younger flags are the normal state * between two sessions, not a finding. */ export function deferredCloseTailFindings( report: Pick, now: Date = new Date(), ): DriftFinding[] { if (report.db_path === null || !report.db_exists) return []; let row: { n: number; oldest: string } | null; try { const db = openDatabaseReadOnly(report.db_path); try { const found = db .prepare( `SELECT COUNT(*) AS n, MIN(ended_at) AS oldest FROM conversations WHERE ended_at IS NOT NULL AND json_extract(metadata, '$.close_tail_pending') IS 1`, ) .get(); row = found && Number(found.n) > 0 ? { n: Number(found.n), oldest: String(found.oldest) } : null; } finally { db.close(); } } catch { return []; } if (row === null) return []; const oldest = Date.parse(row.oldest); if (Number.isNaN(oldest) || now.getTime() - oldest < DEFERRED_CLOSE_TAIL_STALE_MS) return []; return [ { code: "deferred_close_tails_waiting", severity: "attention", subject: "conversations", detail: `${row.n} conversation(s) closed by a runtime that defers the close tail are waiting ` + `for a session start to finish it; the oldest ended ${row.oldest}`, recommendation: "start a session on any runtime: its maintenance extracts and finalizes them, " + "five per start", repair_route: "session start", }, ]; } export interface DiagnoseOptions { /** Injected only so the 24h boundary is testable; production passes none. */ now?: Date; /** The user's config file; `null` skips it. Tests pin it so a developer's own file never enters a golden. */ configFile?: string | null; } /** * Port of `diagnose_runtime`. Finding ORDER is part of the rendered output, so * the sequence below mirrors the oracle statement for statement. */ export function diagnoseRuntime( report: RuntimeStatusReport, worktreeEntries: readonly GitWorktreeEntry[] = [], options: DiagnoseOptions = {}, ): DriftFinding[] { const findings: DriftFinding[] = []; findings.push(...loosePermissionFindings(report, options.configFile)); findings.push(...frontDoorErrorFindings(report, options.now)); findings.push(...ftsConsistencyFindings(report)); findings.push(...identityKeyFindings(report)); findings.push(...deferredCloseTailFindings(report, options.now)); if (report.mirror_home_error) { findings.push({ code: "mirror_home_missing", severity: "blocker", subject: "mirror home", detail: report.mirror_home_error, recommendation: "configure MIRROR_HOME or MIRROR_USER before update planning", repair_route: "configuration", }); } if (report.db_exists === false) { findings.push({ code: "database_missing", severity: "blocker", subject: "database", detail: report.db_path ?? "unknown", recommendation: "restore or initialize the memory database before update planning", repair_route: "restore or initialize", }); } findings.push(...worktreeEntries.map(gitDirtyFinding)); for (const migrationId of report.core_migrations.missing) { findings.push({ code: "core_migration_pending", severity: "blocker", subject: "database _migrations", detail: migrationId, recommendation: "run pending core migrations only after backup", repair_route: "backup then migrate", }); } for (const migrationId of report.core_migrations.unknown) { findings.push({ code: "core_migration_unknown", severity: "attention", subject: "database _migrations", detail: migrationId, recommendation: "classify as legacy core row, extension-owned row, or experimental drift", repair_route: "manual review", }); } if (report.core_migrations.note) { findings.push({ code: "core_migration_unreadable", severity: "blocker", subject: "database _migrations", detail: report.core_migrations.note, recommendation: "restore readable migration tracking before update planning", repair_route: "database repair", }); } for (const extension of report.extension_health) { // Only the missing-field shape is a blocker in the oracle: the other // manifest failures are reported by `status` but do not gate an update. if (extension.note?.includes("missing required field")) { findings.push({ code: "extension_manifest_invalid", severity: "blocker", subject: `extension/${extension.extension_id}`, detail: extension.note, recommendation: "repair or reinstall the extension manifest before update planning", repair_route: "extension repair", }); } for (const filename of extension.pending_migrations) { findings.push({ code: "extension_migration_pending", severity: "blocker", subject: `extension/${extension.extension_id}`, detail: filename, recommendation: "run pending extension migrations only after backup", repair_route: "backup then extension migrate", }); } for (const filename of extension.drifted_migrations) { findings.push({ code: "extension_migration_checksum_drift", severity: "blocker", subject: `extension/${extension.extension_id}`, detail: filename, recommendation: "restore the original migration file or create a new migration", repair_route: "extension repair", }); } for (const filename of extension.unknown_migrations) { findings.push({ code: "extension_migration_unknown", severity: "attention", subject: `extension/${extension.extension_id}`, detail: filename, recommendation: "compare installed extension with canonical source and classify history", repair_route: "manual review or reinstall", }); } } return findings; } /** * The plugin wiring findings (CV21.DS4.TS6; the debt US1 carried; Grok in * CV21.DS10.US1; agy in CV21.DS11.TS4). Codex, agy, and Grok copy the plugin, * so an npm update leaves the copy behind; Claude Code links it in place, so * its failure mode is a dangling link, and Grok's rules link fails the same * way. Grok adds one * failure of its own: a respelt install path keys a SECOND copy, and Grok * loads one of the two without saying which. Absence is not drift: no * cache, no registry, and no link fire nothing, so an unwired machine stays * green. * * The defaulting happens HERE, from the env the caller hands in — CODEX_HOME * else ~/.codex, GROK_HOME else ~/.grok, ~/.claude, and ~/.gemini — never * inside the readers, so every reader test is hermetic on a maintainer's * machine with real wiring (CR123/128/137/142). */ export function pluginWiringFindings( installRoot: string | null, env: NodeJS.ProcessEnv, ): DriftFinding[] { const findings: DriftFinding[] = []; const home = env.HOME?.trim() || null; const codexHome = env.CODEX_HOME?.trim() || (home ? join(home, ".codex") : null); const installedVersion = installRoot ? installedPluginVersion(installRoot) : null; if (codexHome && installedVersion) { const cache = codexPluginCacheState(codexHome, installedVersion); if (cache.state === "behind") { findings.push({ code: "codex_plugin_cache_behind", severity: "warning", subject: cache.cachePath, detail: `cached ${cache.newestCached} < installed ${installedVersion}; Codex runs the copy it cached at install`, recommendation: `run \`${CODEX_PLUGIN_ADD_COMMAND}\` to bring the cached plugin level (Codex has no plugin-update verb; re-adding refreshes the cache)`, repair_route: CODEX_PLUGIN_ADD_COMMAND, }); } } // agy stages a copy under ~/.gemini/config/plugins/mirror-mind/ (agy 1.4.7, // DS11.TS4's route), read the way the extensions plugin's copy is read: the // `.gemini` home from HOME, with no Mirror variable to override it. const geminiHome = home ? join(home, ".gemini") : null; if (geminiHome && installedVersion && installRoot) { const copy = agyPluginCopyState(geminiHome, installedVersion, "mirror-mind"); if (copy.state === "behind") { const install = agyPluginInstallCommand(installRoot); findings.push({ code: "agy_plugin_copy_behind", severity: "warning", subject: copy.copyPath, detail: `copied ${copy.copiedVersion} < installed ${installedVersion}; agy runs the copy it staged at install`, recommendation: `run \`${install}\` to bring the copy level (an update leaves agy's copy as it was, and installing again replaces it)`, repair_route: install, }); } } if (home) { const link = pluginLinkState(join(home, ".claude", "skills", "mirror-mind")); if (link.state === "dangling") { findings.push({ code: "claude_plugin_link_dangling", severity: "warning", subject: link.linkPath, detail: `the link points at ${link.target ?? "an unreadable target"}, which cannot be read`, recommendation: 'relink it — `rm ~/.claude/skills/mirror-mind && ln -s "/plugins/mirror-mind" ~/.claude/skills/mirror-mind` — or remove it if Claude Code is no longer wired', repair_route: "relink or remove", }); } } const grokHome = env.GROK_HOME?.trim() || (home ? join(home, ".grok") : null); if (grokHome && installedVersion && installRoot) { const copy = grokPluginCopyState(grokHome, installedVersion); const reinstall = grokPluginReinstallCommand(installRoot); if (copy.copies.length > 1) { findings.push({ code: "grok_plugin_copies_duplicated", severity: "warning", subject: copy.registryPath, detail: `${copy.copies.length} copies of the plugin are installed (${copy.copies.map((c) => `${c.key} at ${c.version}`).join(", ")}); Grok loads one of them and does not say which`, recommendation: `run \`grok plugin uninstall mirror-mind --confirm\` until \`grok plugin list\` shows none, then \`${reinstall}\` (a plugin installed from a differently spelt path is a second copy, not an update)`, repair_route: reinstall, }); } if (copy.state === "behind") { findings.push({ code: "grok_plugin_copy_behind", severity: "warning", subject: copy.copies.length === 1 ? (copy.copies[0]?.path ?? copy.registryPath) : copy.registryPath, detail: `copied ${copy.newestCopied} < installed ${installedVersion}; Grok runs the copy it made at install`, recommendation: `run \`${reinstall}\` to bring the copy level (\`grok plugin update\` leaves a local-path copy as it is, and an install over the same path is refused)`, repair_route: reinstall, }); } } if (grokHome) { const rules = pluginLinkState(join(grokHome, "rules", "mirror-mind.md")); if (rules.state === "dangling") { findings.push({ code: "grok_rules_link_dangling", severity: "warning", subject: rules.linkPath, detail: `the link points at ${rules.target ?? "an unreadable target"}, which cannot be read; Grok loads no Operating Instructions and says nothing`, recommendation: 'relink it — `ln -s "/AGENTS.md" ~/.grok/rules/mirror-mind.md` — or remove it if Grok Build is no longer wired', repair_route: "relink or remove", }); } } return findings; } /** The catalog read `probeModelPins` needs. DS5 replay only until DS8. */ export interface ModelCatalogProvider { listAvailableModels(): Promise>; } /** A DS5-substrate replay catalog: the fixture IS the answer. */ export class ReplayModelCatalogProvider implements ModelCatalogProvider { private readonly models: Set; constructor(models: Iterable) { this.models = new Set(models); } async listAvailableModels(): Promise> { return this.models; } } /** * Port of `probe_model_pins`. OpenRouter's `/models` lists completion models * only, so the extraction pin is catalog-verifiable while the embedding pin is * not -- checking the embedding pin against this catalog would be a false * positive, and an embedding failure surfaces through degraded search instead. * * Any inability to read the catalog is INCONCLUSIVE and yields no findings, so * diagnose stays green offline and only a confirmed-missing pin warns. With no * provider this is always the case: TS3 has no live catalog client, matching * the oracle's behavior without a key (DS8 adds the live fetch). */ export async function probeModelPins( provider: ModelCatalogProvider | null, extractionModel: string, ): Promise { if (provider === null) return []; let available: Set; try { available = await provider.listAvailableModels(); } catch { return []; } if (available.has(extractionModel)) return []; return [ { code: "model_pin_unresolved", severity: "attention", subject: "model pin", detail: `${extractionModel} is not available on OpenRouter`, recommendation: "set MEMORY_EXTRACTION_MODEL to a current model id (see https://openrouter.ai/models)", repair_route: "repoint model pin", }, ]; } /** Port of `render_runtime_diagnosis`. */ export function renderRuntimeDiagnosis(findings: readonly DriftFinding[]): string { const lines: string[] = ["Mirror runtime drift diagnosis", ""]; if (findings.length === 0) { lines.push("Findings: 0", "", "Status: ready"); return `${lines.join("\n")}\n`; } lines.push(`Findings: ${findings.length} attention needed`); for (const finding of findings) { lines.push(""); lines.push(`[${finding.severity}] ${finding.code}: ${finding.detail}`); lines.push(`Subject: ${finding.subject}`); lines.push(`Recommendation: ${finding.recommendation}`); lines.push(`Repair route: ${finding.repair_route}`); } lines.push("", "Status: attention needed"); return `${lines.join("\n")}\n`; } // --- CV22.DS10.TS5: the transition's own leftovers ------------------------- /** * The variables that used to send a route to Python, deleted by CV22.DS10.TS5 * (D3): the twenty-one family revert gates, the MCP launcher's engine switch * (plateau 1), and DS5's replay opt-in, inert since DS8.US3. * * NAMED, not matched by prefix. The first version of this check reported every * non-`_REPLAY` `MIRROR_TS_*` variable, which told users to delete two that * still do something -- `MIRROR_TS_MCP_GUARDS` (the MCP wallet guards) and * `MIRROR_TS_CONSULT_CONTEXT` (consult's context input). A prefix is a claim * about names nobody has written yet (inventory F8). */ export const RETIRED_REVERT_GATES: readonly string[] = [ "MIRROR_TS_BACKUP", "MIRROR_TS_BUILD", "MIRROR_TS_CONSULT", "MIRROR_TS_CONVERSATION_APPEND", "MIRROR_TS_CONVERSATION_LLM_TAIL", "MIRROR_TS_CONVERSATION_LOGGER", "MIRROR_TS_CONVERSATIONS_LIFECYCLE", "MIRROR_TS_CULTIVATION", "MIRROR_TS_DESCRIPTOR", "MIRROR_TS_EXPLORE", "MIRROR_TS_EXTENSIONS", "MIRROR_TS_EXTERNAL_ROUTES", "MIRROR_TS_IDENTITY_EDIT", "MIRROR_TS_JOURNAL", "MIRROR_TS_MCP", "MIRROR_TS_MIRROR_QUERY", "MIRROR_TS_REPAIR_ENCODING", "MIRROR_TS_RUNTIME_READS", "MIRROR_TS_RUNTIME_UPDATE", "MIRROR_TS_SEARCH", "MIRROR_TS_SOUL", "MIRROR_TS_WEEK", "MIRROR_TS_WELCOME", ]; /** * A retired gate still set in the environment. * * A value left in someone's `.env` changes nothing -- which is the right * behavior and an invisible one, so diagnose says it out loud rather than * letting a user believe a revert is armed. */ export function staleRevertGateFindings(env: NodeJS.ProcessEnv): DriftFinding[] { const stale = RETIRED_REVERT_GATES.filter((name) => (env[name] ?? "") !== ""); if (stale.length === 0) return []; return [ { code: "stale_revert_gate", severity: "info", subject: stale.join(", "), detail: "set, but inert since CV22.DS10.TS5: the Python engine these gates reverted to no longer exists", recommendation: "remove from .env and the environment; routing ignores them", repair_route: "edit .env", }, ]; } /** * No OpenRouter key (CR187), read by the predicate every refusal uses, so * diagnose and the refusals cannot disagree about what "configured" means. * Presence only: the value is never read into a finding. Attention, not a * blocker -- a keyless install still runs and updates; it just remembers * nothing new and answers no `consult`. The recommendation names the file the * key goes in, and says to make it owner-only when it does not exist yet. */ export function openRouterKeyFindings(env: NodeJS.ProcessEnv, home?: string): DriftFinding[] { if (hasOpenRouterKey(env)) return []; return [ { code: "openrouter_key_missing", severity: "attention", subject: "OPENROUTER_API_KEY", detail: "not set, so embeddings, memory extraction, and consult are off", recommendation: `add ${keyFileInstruction(env, home)}`, repair_route: "configuration", }, ]; } /** * A `MEMORY_EXTRACTION_REASONING` that is not a reasoning effort (CV9.DS9.TS1). * * The transport reads it as unset rather than fail the call -- a failed call is * an extraction attempt, and three quarantine a conversation for good (CR178) -- * so the setting is silently not in force: the calls send the model's own default * effort (CV9.DS9.US3), or no reasoning field for a model without one. Diagnose * says which, with the values that would be in force. */ export function extractionReasoningFindings(env: NodeJS.ProcessEnv): DriftFinding[] { const { model, effort, invalid } = resolveExtractionReasoning({ env }); if (invalid === null) return []; const sent = effort === null ? "no reasoning setting" : `${model}'s own default, ${effort}`; return [ { code: "extraction_reasoning_invalid", severity: "attention", subject: "MEMORY_EXTRACTION_REASONING", detail: `"${invalid}" is not a reasoning effort, so extraction calls send ${sent}`, recommendation: `set it to ${formatEffortList()}, or unset it, where it is set: ` + "the environment, the clone's .env, or ~/.config/mirror/env", repair_route: "edit the setting", }, ]; } function formatEffortList(): string { return `${REASONING_EFFORTS.slice(0, -1).join(", ")}, or ${REASONING_EFFORTS.at(-1)}`; } /** * Where a hook wrapper looks for Node after `MIRROR_NODE` and `PATH`, in order. * The generated wrappers carry the same list (`for candidate in ...`), and * `hooks.test.ts` fails if the two differ: they had, by `/usr/bin/node`, which * diagnose counted and no wrapper searched (TS5 handoff review, finding N1). */ export const HOOK_NODE_CANDIDATES: readonly string[] = [ "$HOME/.nvm/current/bin/node", "/opt/homebrew/bin/node", "/usr/local/bin/node", ]; /** * An executable that is not a directory: what every reader of `MIRROR_NODE` * accepts (CR192), and what `hookNodeFindings` is handed to probe with. * `X_OK` alone passes a directory, and on Windows it is only an existence * check, so the directory is ruled out first. */ export function isExecutableFile(path: string): boolean { try { if (statSync(path).isDirectory()) return false; accessSync(path, constants.X_OK); return true; } catch { return false; } } /** How far back `hookFailureFindings` looks. Longer than the front door's day, * because a hook failure is the kind a user notices weeks later. */ const HOOK_FAILURE_WINDOW_MS = 7 * 24 * 60 * 60 * 1000; /** * Hook failures recorded in `/hooks.log` in the last 7 days. * * `hookNodeFindings` can only ask from diagnose's own environment. The hooks * write this file from theirs -- a Node that is missing or cannot run them, * a front-door call that failed -- so it is the evidence of what a runtime * actually met. The finding counts and names the latest hook; the reasons * stay in the file, because a diagnosis gets pasted into issues. */ export function hookFailureFindings( report: RuntimeStatusReport, now: Date = new Date(), ): DriftFinding[] { if (report.db_path === null) return []; const logPath = join(dirname(report.db_path), "hooks.log"); if (!existsSync(logPath)) return []; let lines: string[]; try { lines = readFileSync(logPath, "utf8").split("\n"); } catch { return []; } const cutoff = now.getTime() - HOOK_FAILURE_WINDOW_MS; let count = 0; let latest: { stamp: string; hook: string } | null = null; for (const line of lines) { const match = /^(\S+) ([^\s:]+:[^\s:]+): /.exec(line); if (!match) continue; const [, stamp = "", hook = ""] = match; const time = parseLogTimestamp(stamp); if (time === null || time < cutoff) continue; count += 1; latest = { stamp, hook }; } if (latest === null) return []; return [ { code: "hook_failures_recorded", severity: "warning", subject: "hooks", detail: `${count} hook failure(s) in the last 7 days, latest ${latest.stamp}, ${latest.hook} (${logPath})`, recommendation: "read the log: a missing or too-old Node, or a failing front-door call, each has its own line", repair_route: "review hooks.log", }, ]; } /** * Can a hook find Node? * * The failure this exists for: `/usr/bin/python3` is on every macOS, so the * Python hooks always found their interpreter and could end in `|| true` * safely. `node` usually lives under nvm or Homebrew and is NOT on the PATH a * GUI-launched runtime inherits. A hook that cannot resolve it skips silently, * and the user meets it weeks later as "Mirror stopped remembering". * * The wrappers write to `/hooks.log` when this happens. This * finding is the other half: a place to ASK, before anything is lost. * * It asks from the CALLER's environment, which is a terminal's, not a GUI * runtime's -- so it can say Node is missing, never that a hook found it. * `hookFailureFindings` reads the evidence hooks write from their own context. */ export function hookNodeFindings( env: NodeJS.ProcessEnv, isExecutable: (path: string) => boolean, platform: NodeJS.Platform = process.platform, ): DriftFinding[] { // The platform's PATH separator and its executable name: `;` and `node.exe` // on Windows, where splitting on `:` cut `C:\Program Files\nodejs` into `C` // and a path and the finding fired on every install that had Node (PR #49). // `platform` is a parameter so the test runs both branches on every host: // CI's Windows job runs two files and this one is not among them. const paths = platform === "win32" ? win32 : posix; // MIRROR_NODE counts only as every hook reads it: an absolute path to an // executable file (CR192). A relative one would resolve against this // terminal's cwd, and no hook would use it. const explicit = env.MIRROR_NODE ?? ""; if (explicit && paths.isAbsolute(explicit) && isExecutable(explicit)) return []; const candidates = HOOK_NODE_CANDIDATES.map((candidate) => candidate.replace("$HOME", env.HOME ?? ""), ); const name = platform === "win32" ? "node.exe" : "node"; const onPath = (env.PATH ?? "") .split(paths.delimiter) .filter(Boolean) .some((entry) => isExecutable(paths.join(entry, name))); if (onPath || candidates.some((candidate) => isExecutable(candidate))) return []; return [ { code: "hook_node_unresolvable", severity: "warning", subject: "node", detail: "not found on PATH or in the usual install locations; runtime hooks will skip and log to hooks.log", recommendation: "set MIRROR_NODE to the node binary, or install node where the runtime can see it", repair_route: "export MIRROR_NODE=/path/to/node", }, ]; } /** * The extensions plugin findings (CV21.DS5.US2): the same reading the `extensions` * verbs print, as drift. A home with no plugin, a runtime not wired, and a runtime * off the PATH are silence; a dangling link, a stale copy (any version other than * the home's), and two Grok copies are warnings, each naming its repair. */ export function extensionPluginFindings( mirrorHome: string | null, env: NodeJS.ProcessEnv, isExecutable: (path: string) => boolean, ): DriftFinding[] { if (mirrorHome === null) return []; const previous = readExtensionPlugin(mirrorHome); if (previous === null) return []; const name = `mirror-ext-${basename(mirrorHome)}`; const skills = Object.keys(previous.files).filter((path) => path.endsWith("/SKILL.md")).length; const plugin: ExtensionPluginReport = { name, directory: extensionPluginDirectory(mirrorHome), marketplaceRoot: extensionPluginRoot(mirrorHome), version: `0.1.${previous.generation}`, skills, changed: false, notCarried: [], }; const findings: DriftFinding[] = []; for (const state of extensionPluginStates(plugin, env, isExecutable)) { if (state.state === "wired" || state.state === "not_wired") continue; const code = state.state === "dangling" ? "ext_plugin_claude_link_dangling" : state.state === "duplicated" ? "ext_plugin_grok_copies_duplicated" : state.runtime === "codex" ? "ext_plugin_codex_cache_stale" : state.runtime === "antigravity" ? "ext_plugin_agy_copy_stale" : "ext_plugin_grok_copy_stale"; const repair = state.steps.join("; then "); findings.push({ code, severity: "warning", subject: state.subject, detail: state.state === "stale" ? `${state.detail}, the home generates ${plugin.version}; ${state.title} runs the copy it made at install` : state.detail, recommendation: `run \`${repair}\` to bring ${state.title}'s copy of ${plugin.name} level`, repair_route: repair, }); } return findings; }