total-recall-brain 3.40.7 → 3.41.0

package/src/core/plugin-state.mjs

@@ -2,23 +2,64 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import matter from './frontmatter.mjs';
-import { globalPluginsDir, vaultForPluginsDir } from './plugin-loader.mjs';
+import { globalPluginsDir, projectPluginsDir, vaultForPluginsDir } from './plugin-loader.mjs';
 
-export function pluginActivation(plugin) {
+/**
+ * Enablement has two layers. The plugin's own brain holds the shared setting —
+ * the global brain, since a shared plugin lives in one folder per machine. A
+ * repository adds its own `plugin_record` in its project brain whose
+ * `runtime_enabled` overrides that setting for that repository alone. With no
+ * override the shared setting applies; an override carrying only a
+ * `runtime_disabled: false` tombstone means "follow the shared setting" and
+ * keeps no second copy of the plugin on disk.
+ */
+export function projectActivationOverride(id, projectRoot) {
+  const pluginsDir = projectPluginsDir(projectRoot);
+  const file = path.join(vaultForPluginsDir(pluginsDir), 'system', 'plugins', `${id}.md`);
+  return { pluginsDir, file, record: readActivationRecord(file, id) };
+}
+
+export function pluginActivation(plugin, { projectRoot } = {}) {
   const pluginsDir = plugin.scope === 'scaffold' ? globalPluginsDir() : plugin.pluginsDir;
   if (!/^[a-z][a-z0-9-]{1,63}$/.test(plugin.id)) throw new Error('Invalid plugin identity');
   const file = pluginsDir ? path.join(vaultForPluginsDir(pluginsDir), 'system', 'plugins', `${plugin.id}.md`) : null;
   const record = readActivationRecord(file, plugin.id);
-  const enabled = plugin.valid === true && record?.runtime_enabled !== false;
+  // Only a plugin owned by the shared (global) folder has an override to read:
+  // a project's own copy already is that repository's setting.
+  const override = plugin.scope === 'global' && projectRoot ? projectActivationOverride(plugin.id, projectRoot).record : null;
+  const applied = override?.runtime_enabled;
+  const source = typeof applied === 'boolean' ? 'project' : 'shared';
+  const shared = record?.runtime_enabled !== false;
+  const enabled = plugin.valid === true && (typeof applied === 'boolean' ? applied : shared);
   const runtime = plugin.manifest?.runtime || {};
   return {
-    state: enabled ? 'active' : 'inactive', enabled,
-    hasRuntime: Boolean(plugin.manifest?.tasks?.length || Object.keys(runtime).length),
+    state: enabled ? 'active' : 'inactive', enabled, source,
+    overridden: source === 'project' && applied !== shared,
     evidence: 'Host activation policy, not external process or provider health',
+    hasRuntime: Boolean(plugin.manifest?.tasks?.length || Object.keys(runtime).length),
     externalRuntime: Boolean(runtime.jobs?.length || runtime.daemons?.length || runtime.startup?.length),
   };
 }
 
+/**
+ * Whether execution is permitted. `pluginActivation` reports a plugin's policy
+ * state, which includes whether the plugin is valid at all; a caller that
+ * already holds a usable plugin object asks this instead, because the only thing
+ * that switches execution off is an explicit negative — the shared setting or
+ * the repository's own override.
+ */
+export function pluginExecutionEnabled(plugin, { projectRoot } = {}) {
+  if (!plugin) return false;
+  const pluginsDir = plugin.scope === 'scaffold' ? globalPluginsDir() : plugin.pluginsDir;
+  if (!pluginsDir) return true;
+  if (!/^[a-z][a-z0-9-]{1,63}$/.test(plugin.id)) throw new Error('Invalid plugin identity');
+  const file = path.join(vaultForPluginsDir(pluginsDir), 'system', 'plugins', `${plugin.id}.md`);
+  const record = readActivationRecord(file, plugin.id);
+  const override = plugin.scope === 'global' && projectRoot ? projectActivationOverride(plugin.id, projectRoot).record : null;
+  const applied = override?.runtime_enabled;
+  return typeof applied === 'boolean' ? applied : record?.runtime_enabled !== false;
+}
+
 /** Pure bootstrap read, avoiding configuration/kernel cycles; malformed existing policy fails closed. */
 export function readActivationRecord(file, id) {
   if (!file) return null;

package/src/core/plugin-store.mjs

@@ -31,7 +31,7 @@ import {
 } from './plugin-bundle.mjs';
 import { writeVfsDocument, patchVfsDocument, deleteVfsDocument, appendVfsEvent } from './ssss-operation-service.mjs';
 import { findVfsDocumentByPath } from './vfs-documents.mjs';
-import { readActivationRecord } from './plugin-state.mjs';
+import { readActivationRecord, projectActivationOverride } from './plugin-state.mjs';
 
 const execFileAsync = promisify(execFile);
 const ID_PATTERN = /^[a-z][a-z0-9-]{1,63}$/;
@@ -62,6 +62,18 @@ export function readPluginRecord(plugin) {
   return record;
 }
 
+/**
+ * A repository's own enablement for a shared plugin, read from its project
+ * brain. This is an overlay, never an install: it is absent for a repository
+ * that has never switched the plugin either way.
+ */
+export function readProjectActivationRecord(id, projectRoot) {
+  if (!projectRoot) return null;
+  const { file } = projectActivationOverride(id, projectRoot);
+  if (!readActivationRecord(file, id)) return null;
+  return findVfsDocumentByPath(recordPath(id), vaultForPluginsDir(projectPluginsDir(projectRoot)));
+}
+
 export async function emit(vaultRoot, id, kind, payload) {
   await appendVfsEvent(
     `plugins/${id}/${kind}-${Date.now()}-${crypto.randomBytes(3).toString('hex')}`,
@@ -164,6 +176,65 @@ export async function patchPluginRecord(plugin, patches) {
   });
 }
 
+/**
+ * Write one repository's enablement for a shared plugin as a `plugin_record`
+ * overlay in that repository's brain. Passing `null` clears the repository's own
+ * setting so it follows the shared one again. The overlay never installs the
+ * plugin: a repository without it uses the shared folder's copy.
+ */
+export async function patchProjectActivationRecord(id, projectRoot, runtimeEnabled, { manifest = null } = {}) {
+  if (!ID_PATTERN.test(id)) throw new Error('Invalid plugin identity');
+  const pluginsDir = projectPluginsDir(projectRoot);
+  const vaultRoot = vaultForPluginsDir(pluginsDir);
+  const now = new Date().toISOString();
+  // Clear: the overlay is rewritten without `runtime_enabled`, which is what
+  // "follow the shared setting" means. A patch cannot remove a key, so this
+  // replaces the document rather than merging into it.
+  if (runtimeEnabled === null) {
+    const existing = readProjectActivationRecord(id, projectRoot);
+    if (!existing) return null;
+    const { runtime_enabled: _dropped, ...frontmatter } = { ...(existing.frontmatter || {}) };
+    await writeVfsDocument(recordPath(id), {
+      ...frontmatter,
+      type: 'plugin_record',
+      runtime_disabled: false,
+      timestamp: now
+    }, existing.body ?? buildPluginDocumentBody(manifest || {}, id), {
+      actorRole: 'system',
+      intent: `Clear repository activation override for plugin ${id}`,
+      vaultRoot
+    });
+    return readProjectActivationRecord(id, projectRoot);
+  }
+  if (typeof runtimeEnabled !== 'boolean') throw new Error('Plugin activation requires a boolean or null');
+  const previous = readProjectActivationRecord(id, projectRoot);
+  if (previous) {
+    return patchVfsDocument(recordPath(id), { runtime_enabled: runtimeEnabled, timestamp: now }, {
+      actorRole: 'system',
+      intent: `Set repository activation for plugin ${id}`,
+      vaultRoot
+    });
+  }
+  const m = manifest || {};
+  const frontmatter = {
+    type: 'plugin_record',
+    title: m.name || id,
+    description: `Repository activation for shared plugin ${id}.`,
+    timestamp: now,
+    plugin_id: id,
+    category: 'plugins',
+    tags: ['plugin', 'activation-override'],
+    runtime_enabled: runtimeEnabled,
+    source: { kind: 'shared', ref: globalPluginsDir() }
+  };
+  await writeVfsDocument(recordPath(id), frontmatter, buildPluginDocumentBody(m, id), {
+    actorRole: 'system',
+    intent: `Record repository activation for plugin ${id}`,
+    vaultRoot
+  });
+  return frontmatter;
+}
+
 /** Facts about one installed plugin, merged with its record. */
 export function describePlugin(plugin) {
   const record = readPluginRecord(plugin);
@@ -394,9 +465,12 @@ export async function installPlugin(source, options = {}) {
     sourceRecord = { kind: 'bundled', ref: manifest.id };
   } else if (isGitSource(source)) {
     const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'tr-plugin-'));
+    let commit;
     try {
       try {
         await execFileAsync('git', ['clone', '--depth', '1', '--', source, tmp], { timeout: 120_000 });
+        // The installed commit is what automatic updates compare against the remote head.
+        commit = (await execFileAsync('git', ['-C', tmp, 'rev-parse', 'HEAD'], { timeout: 30_000 })).stdout.trim();
       } catch (err) {
         throw new Error(`Failed to clone ${source}: ${(err.stderr || err.message || '').toString().trim()}`);
       }
@@ -406,7 +480,7 @@ export async function installPlugin(source, options = {}) {
     } finally {
       fs.rmSync(tmp, { recursive: true, force: true });
     }
-    sourceRecord = { kind: 'git', ref: source };
+    sourceRecord = { kind: 'git', ref: source, commit };
   } else {
     const abs = path.isAbsolute(source) ? source : path.resolve(projectRoot, source);
     if (!fs.existsSync(abs)) {
@@ -450,7 +524,8 @@ export async function installPlugin(source, options = {}) {
     throw new Error(`Plugin files were written but its record could not be: ${err.message}`);
   }
 
-  const compilation = await recompileAfterPluginMutation(projectRoot, isGlobal);
+  // A batch of installs (automatic updates) compiles once after the batch instead.
+  const compilation = options.recompile === false ? { skipped: true } : await recompileAfterPluginMutation(projectRoot, isGlobal);
   return {
     plugin: { id: manifest.id, name: manifest.name, version: manifest.version, dir: dest, scope },
     source: sourceRecord,

package/src/core/plugin-tasks.mjs

@@ -14,6 +14,7 @@
  */
 import { discoverPlugins } from './plugin-loader.mjs';
 import { readPluginRecord, patchPluginRecord, ensurePluginRecord } from './plugin-store.mjs';
+import { pluginExecutionEnabled } from './plugin-state.mjs';
 import { runPluginCommand } from './plugin-runner.mjs';
 import { appendVfsEvent } from './ssss-operation-service.mjs';
 import { vaultForPluginsDir } from './plugin-loader.mjs';
@@ -75,7 +76,8 @@ export async function runDuePluginTasks(options = {}) {
 
     let record = readPluginRecord(plugin);
     if (!record) record = await ensurePluginRecord(plugin);
-    if (record?.runtime_enabled === false) continue;
+    // Scheduled work follows the repository's own setting for a shared plugin.
+    if (!pluginExecutionEnabled(plugin, { projectRoot })) continue;
     const runs = { ...(record?.task_runs || {}) };
     let changed = false;
 

package/src/core/plugin-updates.mjs

@@ -0,0 +1,117 @@
+/** Automatic maintenance keeps every installed plugin current with the source it was installed from. */
+import fs from 'node:fs';
+import path from 'node:path';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { discoverPlugins, listBundledPlugins } from './plugin-loader.mjs';
+import { describePlugin } from './plugin-store.mjs';
+import { hashPluginDir } from './plugin-bundle.mjs';
+import { DEFAULT_PLUGIN_IDS } from './default-plugins.mjs';
+
+const execFileAsync = promisify(execFile);
+
+/** The commit a git source's default branch points at now. */
+export async function remoteGitHead(ref) {
+  const { stdout } = await execFileAsync('git', ['ls-remote', '--', ref, 'HEAD'], { timeout: 30_000 });
+  const commit = stdout.split(/\s/)[0];
+  if (!/^[0-9a-f]{40}$/.test(commit)) throw new Error(`No HEAD commit advertised by ${ref}`);
+  return commit;
+}
+
+async function peerSha({ id, ref }) {
+  const { listPeerPlugins } = await import('./plugin-peers.mjs');
+  const host = ref.slice('peer:'.length, ref.lastIndexOf('/'));
+  const { peers } = await listPeerPlugins();
+  const peer = peers.find(p => p.hostname === host || p.ip === host);
+  if (!peer) throw new Error(`Mesh peer '${host}' is not reachable`);
+  const offered = (peer.plugins || []).find(p => p.id === id);
+  if (!offered?.sha256) throw new Error(`Mesh peer '${host}' no longer shares '${id}'`);
+  return offered.sha256;
+}
+
+/**
+ * Decide whether one installed plugin is behind its source.
+ * Returns { status, install? } where install is the source to reinstall from.
+ */
+export async function checkPlugin(plugin, { gitHead = remoteGitHead, peerHash = peerSha, bundled = listBundledPlugins } = {}) {
+  const { id, source } = plugin;
+  // The filesystem decides, not the record: a linked plugin is its owner's
+  // checkout (often recorded long ago as a copy) and is as current as that checkout.
+  if (plugin.linked || source?.kind === 'link') return { status: 'linked', ref: source?.ref || plugin.dir };
+  // Default plugins are refreshed in every brain by ensureRequiredPlugins with the package.
+  if (DEFAULT_PLUGIN_IDS.includes(id)) return { status: 'package' };
+  // A copy that records itself (or nothing) as its source has no upstream to follow.
+  if (!source?.ref || (source.kind === 'local' && path.resolve(source.ref) === path.resolve(plugin.dir))) {
+    return { status: 'unmanaged', error: 'No install source recorded; reinstall it from its git repository or a mesh peer with --replace to keep it updated' };
+  }
+  switch (source.kind) {
+    case 'public':
+      // A public share link pins one content hash by design.
+      return { status: 'pinned', ref: source.ref };
+    case 'bundled': {
+      const shipped = bundled().find(p => p.id === id);
+      if (!shipped) return { status: 'failed', error: `Bundled plugin '${id}' is no longer shipped in this package` };
+      return hashPluginDir(shipped.dir).sha256 === plugin.installed_sha256 ? { status: 'current' } : { status: 'behind', install: id };
+    }
+    case 'git': {
+      const head = await gitHead(source.ref);
+      return head === source.commit ? { status: 'current', commit: head } : { status: 'behind', install: source.ref, from: source.commit || null, to: head };
+    }
+    case 'peer': {
+      const sha = await peerHash({ id, ref: source.ref });
+      return sha === plugin.installed_sha256 ? { status: 'current' } : { status: 'behind', install: source.ref, from: plugin.installed_sha256, to: sha };
+    }
+    case 'local': {
+      if (!source.ref || !fs.existsSync(source.ref)) {
+        return { status: 'failed', error: `Installed from a directory that no longer exists (${source.ref}); reinstall it from its git repository or a mesh peer with --replace` };
+      }
+      return hashPluginDir(source.ref).sha256 === plugin.installed_sha256 ? { status: 'current' } : { status: 'behind', install: source.ref };
+    }
+    default:
+      return { status: 'failed', error: `Plugin '${id}' has no recorded install source` };
+  }
+}
+
+/**
+ * Check every installed plugin under the given roots and reinstall the ones that
+ * are behind. Surfaces are compiled once by the caller, not once per plugin.
+ */
+export async function updateInstalledPlugins({ roots = [process.cwd()], dryRun = false, check = checkPlugin, install, discover = discoverPlugins, describe = describePlugin } = {}) {
+  if (!install) ({ installPlugin: install } = await import('./plugin-distribution.mjs'));
+  const seen = new Set();
+  const results = [];
+  for (const root of roots) {
+    let plugins;
+    try { plugins = discover(root); }
+    catch (error) { results.push({ root, status: 'failed', error: error.message }); continue; }
+    for (const found of plugins) {
+      if (found.scope === 'scaffold' || !found.dir || seen.has(found.dir)) continue;
+      seen.add(found.dir);
+      const row = { id: found.id, scope: found.scope, dir: found.dir };
+      results.push(row);
+      try {
+        const plugin = describe(found);
+        row.version = plugin.version;
+        row.source = plugin.source?.kind || null;
+        const verdict = await check(plugin);
+        Object.assign(row, verdict);
+        delete row.install;
+        if (verdict.status !== 'behind' || dryRun) continue;
+        const result = await install(verdict.install, { projectRoot: root, global: found.scope === 'global', replace: true, recompile: false });
+        row.status = 'updated';
+        row.previous_version = plugin.version;
+        row.version = result.plugin.version;
+        row.previous_directory = result.previousDirectory;
+      } catch (error) {
+        row.status = 'failed';
+        row.error = error.message;
+      }
+    }
+  }
+  return {
+    updated: results.filter(row => row.status === 'updated').length,
+    failed: results.filter(row => row.status === 'failed').length,
+    unmanaged: results.filter(row => row.status === 'unmanaged').length,
+    results
+  };
+}

package/src/core/plugin-vendor.mjs

@@ -12,7 +12,7 @@ import os from 'node:os';
 import path from 'node:path';
 import { execFile } from 'node:child_process';
 import { promisify } from 'node:util';
-import { listPluginFiles, hashPluginDir } from './plugin-bundle.mjs';
+import { pluginBundleFiles, hashPluginDir } from './plugin-bundle.mjs';
 import { listBundledPlugins } from './plugin-loader.mjs';
 import { isGitSource } from './plugin-store.mjs';
 
@@ -190,15 +190,21 @@ export async function vendorPlugin(source, dest, options = {}) {
       throw new Error(`Brick '${manifest.id}' is already in this project.`);
     }
 
-    const files = listPluginFiles(srcDir);
-    const sha256 = hashPluginDir(srcDir).sha256;
+    // A plugin that declares a capability is vendored as a brick: capability
+    // code only, no UI and no host manifest. Anything else is copied whole.
+    const audience = manifest.capability ? 'brick' : 'host';
+    const files = pluginBundleFiles(srcDir, { audience });
     fs.mkdirSync(target, { recursive: true });
     for (const f of files) {
       const out = path.join(target, f.path);
       fs.mkdirSync(path.dirname(out), { recursive: true });
-      fs.copyFileSync(f.abs, out);
+      if (f.data) fs.writeFileSync(out, f.data);
+      else fs.copyFileSync(f.abs, out);
       fs.chmodSync(out, f.mode);
     }
+    // The recorded hash describes the vendored files, so drift detection stays
+    // correct when a brick is a reduced copy of its source plugin.
+    const sha256 = hashPluginDir(target).sha256;
     const vendoredAt = new Date().toISOString();
     const provenance = {
       vendored_from: manifest.id,

package/src/core/project-brain.mjs

@@ -9,7 +9,6 @@
  *     memory-derived/
  *     sessions/
  *     scheduler/queue/
- *     openwiki/
  *     skills-registry/
  *     config/brain.json
  *   <repo>/.agent/skills/<user-skills>/  ← sibling agent skills
@@ -46,16 +45,16 @@ function ensureDir(dir) {
   return false;
 }
 
-function copyDirMerge(src, dest) {
+function copyDirMerge(src, dest, { skip = new Set() } = {}) {
   if (!fs.existsSync(src)) return 0;
   let n = 0;
   ensureDir(dest);
   for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
-    if (entry.name === '.git' || entry.name === 'node_modules') continue;
+    if (entry.name === '.git' || entry.name === 'node_modules' || skip.has(entry.name)) continue;
     const from = path.join(src, entry.name);
     const to = path.join(dest, entry.name);
     if (entry.isDirectory()) {
-      n += copyDirMerge(from, to);
+      n += copyDirMerge(from, to, { skip });
     } else if (!fs.existsSync(to)) {
       fs.copyFileSync(from, to);
       n++;
@@ -64,45 +63,22 @@ function copyDirMerge(src, dest) {
   return n;
 }
 
-/**
- * Seed openwiki pages (templates if packaged).
- */
-export function ensureOpenWiki(brainDir) {
-  const wikiDir = path.join(brainDir, 'openwiki');
-  const created = ensureDir(wikiDir);
-  const templateRoot = path.join(ROOT, 'templates', 'openwiki');
-  let files = 0;
-  if (fs.existsSync(templateRoot)) {
-    files = copyDirMerge(templateRoot, wikiDir);
-  } else {
-    const pages = {
-      'README.md': `# OpenWiki\n\nProject knowledge docs for this Total Recall brain.\n`,
-      'memory.md': `# Memory\n\nUse \`npx total-recall remember\` / \`recall\` with --project.\n`,
-      'skills.md': `# Skills\n\nUser skills: \`.agent/skills/<name>/SKILL.md\`.\n`,
-      'ide.md': `# IDE\n\n\`npx total-recall connect <ide>\`\n`,
-      'secrets.md': `# Secrets\n\nNever put secrets in openwiki or vault markdown.\n`,
-    };
-    for (const [name, body] of Object.entries(pages)) {
-      const dest = path.join(wikiDir, name);
-      if (!fs.existsSync(dest)) {
-        fs.writeFileSync(dest, body);
-        files++;
-      }
-    }
-  }
-  return { wikiDir, created, files_added: files };
-}
-
 /**
  * Ensure core total-recall skill package files exist (SKILL.md minimum).
+ *
+ * The required plugins live in one shared folder per machine. `sharedBrainDir`
+ * names the global brain that owns them; without it the ambient global brain is
+ * used, which is what an interactive CLI run means.
  */
-export function ensureCoreSkillPackage(brainDir) {
-  ensureRequiredPlugins(brainDir);
+export function ensureCoreSkillPackage(brainDir, { sharedBrainDir } = {}) {
+  ensureRequiredPlugins(brainDir, sharedBrainDir ? { sharedBrainDir } : {});
   const skillMd = path.join(brainDir, 'SKILL.md');
   if (fs.existsSync(skillMd)) return { seeded: false };
   const scaffold = path.join(ROOT, 'scaffold', '.agent', 'skills', 'total-recall');
   if (fs.existsSync(scaffold)) {
-    copyDirMerge(scaffold, brainDir);
+    // `plugins/` is deliberately skipped: the defaults live in one shared folder
+    // per machine, and copying them here is what put a copy in every repository.
+    copyDirMerge(scaffold, brainDir, { skip: new Set(['plugins']) });
     return { seeded: true, from: 'scaffold' };
   }
   // Scaffold directory missing — warn and fall back to a minimal SKILL.md
@@ -111,7 +87,7 @@ export function ensureCoreSkillPackage(brainDir) {
     skillMd,
     `---
 name: total-recall
-description: "Use this skill to operate Total Recall — portable memory, instructions, openwiki, skill deploy, and secrets."
+description: "Use this skill to operate Total Recall — portable memory, instructions and plugin discovery."
 ---
 
 # Total Recall — Project Brain
@@ -169,8 +145,7 @@ export function ensureFullProjectBrain(repoRoot, opts = {}) {
     if (ensureDir(d)) dirsCreated++;
   }
 
-  const core = ensureCoreSkillPackage(brainDir);
-  const wiki = ensureOpenWiki(brainDir);
+  const core = ensureCoreSkillPackage(brainDir, { sharedBrainDir: opts.globalBrainDir });
   const identity = writeBrainIdentity(brainDir, { name, tags });
 
   // Empty skills registry if missing
@@ -207,7 +182,6 @@ export function ensureFullProjectBrain(repoRoot, opts = {}) {
     skillsDir,
     full_brain: true,
     identity,
-    openwiki: wiki,
     core,
     dirs_created: dirsCreated,
     created_top: created,
@@ -258,7 +232,6 @@ export function inspectProjectBrain(repoRoot) {
     brainDir: fs.existsSync(brainDir),
     skillMd: fs.existsSync(path.join(brainDir, 'SKILL.md')),
     memoryVault: fs.existsSync(path.join(brainDir, 'memory-vault')),
-    openwiki: fs.existsSync(path.join(brainDir, 'openwiki')),
     sessions: fs.existsSync(path.join(brainDir, 'sessions')),
     scheduler: fs.existsSync(path.join(brainDir, 'scheduler')),
     skillsRegistry: fs.existsSync(path.join(brainDir, 'skills-registry')),

package/src/core/project-id.mjs

@@ -37,7 +37,10 @@ export function readProjectId(brainDir) {
  */
 export function ensureProjectId(brainDir) {
   const file = brainJsonPath(brainDir);
-  const cfg = readJson(file, {});
+  let cfg;
+  try { cfg = JSON.parse(fs.readFileSync(file, 'utf8')); }
+  catch (err) { if (err.code === 'ENOENT') cfg = {}; else throw new Error('Existing project identity is unreadable or malformed'); }
+  if (!cfg || typeof cfg !== 'object' || Array.isArray(cfg)) throw new Error('Existing project identity must be an object');
   if (cfg.project_id) return { project_id: cfg.project_id, created: false };
   cfg.project_id = randomUUID();
   writeJsonAtomic(file, cfg);