ruvnet-brain 4.0.1 → 4.0.2

package/plugin/scripts/ground-ruvnet.sh

@@ -121,7 +121,7 @@ check_memory_db() {
 for _db in .swarm/agentdb-memory.db .swarm/memory.db .claude/memory.db; do
   check_memory_db "$_db" && break
 done
-if [ "$MEM_STATE" = "off" ]; then
+if [ "$MEM_STATE" != "on" ]; then
   _common_git=$(git rev-parse --path-format=absolute --git-common-dir 2>/dev/null)
   case "$_common_git" in
     */.git)
@@ -136,6 +136,15 @@ if [ "$MEM_STATE" = "off" ]; then
       ;;
   esac
 fi
+if [ "$MEM_STATE" != "on" ] && [ -n "${HOME:-}" ] && [ "$PWD" != "$HOME" ]; then
+  for _db in \
+    "$HOME/.swarm/agentdb-memory.db" \
+    "$HOME/.swarm/memory.db" \
+    "$HOME/.claude/memory.db"
+  do
+    check_memory_db "$_db" && break
+  done
+fi
 unset _db
 unset _common_git _primary_root
 # RUNNING version (this session's loaded plugin) vs STAGED version (marketplace copy on disk).
@@ -162,11 +171,10 @@ if [ "$RUFLO_STATE" = "yes" ] && [ "$MEM_STATE" = "off" ]; then
 This project runs the Ruflo stack but AgentDB persistent project memory is NOT set up (.swarm/memory.db does not exist) — decisions made here are being lost between sessions. rUv's default is memory ON. If you have not already offered this session, offer ONCE, plainly and warmly: "One thing I noticed: this project doesn't have persistent memory turned on — AgentDB would let me carry decisions and context across sessions instead of starting cold each time. Want me to turn it on and wire it up?" On a yes, set it up with the ruflo tools you have (a first memory_store write creates the store) and confirm with the real file path. If they decline, respect it for the rest of the session — the status line keeps them informed without nagging.
 EOF
 fi
-if [ "$RUFLO_STATE" = "yes" ] && [ "$MEM_IDLE" = "1" ]; then
-  cat <<'EOF'
-AgentDB memory exists here but has NOT been written in over 90 minutes. If meaningful decisions HAVE happened this session, the memory hooks may be miswired — do what Ruv would: probe it. Quietly store a session checkpoint via the ruflo memory tools, then verify .swarm/memory.db's mtime actually changed. If the write fails or the file doesn't move, tell the user plainly: "your project memory isn't capturing this session — the hooks look miswired; want me to fix them?" If this session genuinely hasn't produced decisions yet, stay silent — idle is normal at a session's start.
-EOF
-fi
+# A stale mtime is not a user-facing event. SessionEnd/PreCompact own capture;
+# their persistence receipt must fail closed at the write boundary. Emitting a
+# UserPromptSubmit instruction here interrupted unrelated work and still could
+# not prove that the store command wrote the canonical database.
 
 # ── Self-learning flywheel (ruflo ≥3.24, ADR-176) — OFFER it, never switch it on for them ────────
 # Opt-in is a single env var; `harnessLoopOptedIn()` in @claude-flow/cli reads process.env directly,
@@ -375,6 +383,7 @@ This task touches the RuvNet / rUv stack. Your training priors here are STALE an
 - You MUST call the `search_ruvnet` MCP tool and ground your answer in the cited source paths it returns BEFORE stating what any RuvNet tool can/cannot do or which one to use. Asserting a RuvNet capability from memory, without a cited source path, is an error — do not do it.
 - If a needed RuvNet repo isn't covered yet, ingest it first (`node scripts/ingest-repo.mjs --name <repo>`) rather than guessing.
 - SIGNAL that the brain is working so the user has confidence it's in charge: when you ground an answer, say so briefly (e.g. "Grounding in rUv's source…" → cite the path). Silent grounding leaves the user unsure it's even on.
+- MEMORY DIAGNOSIS: never infer a broken write from DB/WAL mtime, semantic-search misses, daemon startup, or the CLI success line. Prove it against ONE canonical absolute path: unique-key `ruflo memory store --path <project>/.swarm/memory.db` → exact-key `ruflo memory retrieve --path ...` → exact SQL row. Only then call it miswired.
 EOF
 fi
 
@@ -398,6 +407,7 @@ This is a build / change request — run THE PLAYBOOK (the standing build playbo
 - Read the actual files in THEIR repo this touches — what pattern do they already use? what would duplicate?
 - Call `search_ruvnet` for what the feature technically DOES — never trust memory about what the corpus has.
 - Check project memory (ruflo memory search / AgentDB) for prior decisions on this area.
+- If memory looks broken, use the exact-path store → exact-key retrieve → exact SQL proof; never diagnose from semantic search, mtime, daemon startup, or a success message.
 ⛔ NO SILENT SUBSTITUTION: use the real RuvNet tool, or say out loud that you're hand-rolling and why.
 Senior partner: one plan, momentum, end with real work.
 EOF

package/plugin/scripts/hook-shim.mjs

@@ -75,13 +75,13 @@ catch (e) { BRAIN_OFF = !(e && (e.code === 'ENOENT' || e.code === 'ENOTDIR')); }
 //               stops a subagent fan-out inheriting an expensive model; design-wall stops an
 //               ungraded surface shipping; protect-state guards the user's own consent record.
 //               None becomes acceptable because retrieval is off.
-//   'partial' — the hook splits INTERNALLY. session-start still runs the auto-updater heartbeat, the
+//   'partial' — the hook splits INTERNALLY. session-start-core still runs the auto-updater heartbeat, the
 //               GONG health alarm and the SLA banner (an off machine must still receive fixes,
 //               otherwise the fix for an off-state bug can never arrive) while suppressing every
 //               advertising byte. The snapshot is forwarded as RUVNET_BRAIN_OFF so the body reads
 //               ONE resolved answer instead of racing the filesystem again mid-run.
 const TABLE = {
-  'session-start':    { file: 'session-start.sh',    interpreter: 'bash', mode: 'advisory', offBehavior: 'partial' },
+  'session-start':    { file: 'session-start-core.mjs', interpreter: 'node', mode: 'advisory', offBehavior: 'partial' },
   'ground-ruvnet':    { file: 'ground-ruvnet.sh',    interpreter: 'bash', mode: 'advisory', offBehavior: 'silence' },
   'hijack-ruvnet':    { file: 'hijack-ruvnet.sh',    interpreter: 'bash', mode: 'advisory', offBehavior: 'silence' },
   'route-dispatch':   { file: 'route-dispatch.sh',   interpreter: 'bash', mode: 'blocking', offBehavior: 'run' },
@@ -102,7 +102,7 @@ const TABLE = {
   // SEPARATE process, SEPARATE cadence) resolves later via `gh run list`. offBehavior 'silence' per
   // the ADR's explicit instruction: this plane observes and advises, it never guards money or
   // honesty on its own — the git-push debt it opens is only ever SURFACED (never gated) by
-  // session-start.sh, and that surfacing already lives under session-start's own 'partial' contract.
+  // session-start-core.mjs, and that surfacing already lives under SessionStart's 'partial' contract.
   'signal-watch':     { file: 'signal-watch.mjs',    interpreter: 'node', mode: 'advisory', offBehavior: 'silence' },
   'routing-outcome':  { file: 'routing-outcome-capture.mjs', interpreter: 'node', mode: 'advisory', offBehavior: 'run' },
   // The unprompted-speech chokepoint (ADR-040 / DDD-0004). ONE runtime is the sole writer of
@@ -247,10 +247,10 @@ function runHook(file) {
   // The unprompted-speech chokepoint uses this to receive the CC event name:
   // `hook-shim.mjs unprompted-speech UserPromptSubmit` → `unprompted-runtime.mjs UserPromptSubmit`.
   const extraArgs = process.argv.slice(3);
-  // Forward the ONE resolved OFF snapshot to a 'partial' body (ADR-054 §4). The body could stat the
-  // sentinel itself — and session-start.sh still does, because it is also invoked directly, outside
-  // this shim, by tests and by a bare install. Passing it means the two readings cannot disagree
-  // within a single invocation if the user flips the switch while the hook is mid-run.
+  // Forward the ONE resolved OFF snapshot to a 'partial' body (ADR-054 §4). The native SessionStart
+  // core also reads the sentinel because the POSIX compatibility launcher and bare installs invoke
+  // it outside this shim. Passing the snapshot means the two readings cannot disagree within one
+  // invocation if the user flips the switch while the hook is mid-run.
   const env = (BRAIN_OFF && entry.offBehavior === 'partial')
     ? { ...process.env, RUVNET_BRAIN_OFF: '1' }
     : process.env;

package/plugin/scripts/learn-capture.sh

@@ -9,6 +9,21 @@
 
 set -uo pipefail
 
+# One policy source for both capture and flush. `off` means zero bytes written. `project` keeps the
+# trajectory queue under this project's .swarm directory; `user` preserves the cross-project learner
+# introduced by ADR-0017. Tests and managed hosts may pass an already-resolved snapshot in
+# RUVNET_LEARNING_SCOPE so the two halves cannot disagree during one hook invocation.
+HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" 2>/dev/null && pwd)"
+SCOPE="${RUVNET_LEARNING_SCOPE:-}"
+if [ -z "$SCOPE" ] && [ -f "$HERE/runtime-preferences.mjs" ] && command -v node >/dev/null 2>&1; then
+  SCOPE=$(node "$HERE/runtime-preferences.mjs" --learning-scope 2>/dev/null) || SCOPE=""
+fi
+case "$SCOPE" in
+  off) exit 0 ;;
+  user|project) ;;
+  *) SCOPE="project" ;;
+esac
+
 # BOUNDED READ. An unqualified `read` waits forever on a stdin that is opened and never closed, and
 # an unbounded accumulator turns a large payload into an unbounded regex scan. Claude Code always
 # writes the payload and closes, so neither costs a normal turn — which is exactly why a hook that
@@ -104,7 +119,11 @@ re_s='"session_id"[[:space:]]*:[[:space:]]*"([^"\]*)"'
 # keeping `.` would let a crafted id survive as `..`-shaped debris in a filename for no benefit.
 SID="${SID//[^A-Za-z0-9_-]/}"           # a filename COMPONENT, never a path
 [ -n "$SID" ] || SID="default"
-DIR="$HOME/.cache/ruvnet-brain/learn"
+if [ "$SCOPE" = "user" ]; then
+  DIR="$HOME/.cache/ruvnet-brain/learn"
+else
+  DIR="$PWD/.swarm/ruvnet-brain-learn"
+fi
 # Owner-only (0700 dir / 0600 file). This queue was 0644 inside a 0755 dir: on macOS every local
 # account is normally in `staff`, so any other user on a shared or corporate machine could read it.
 ( umask 077 && mkdir -p "$DIR" ) 2>/dev/null || exit 0
@@ -147,8 +166,8 @@ if [ "$LINES" -ge "$HEARTBEAT_EVERY" ]; then
   LAST=$(cat "$STAMP" 2>/dev/null || echo 0)
   if [ $((NOW - LAST)) -ge 60 ]; then
     echo "$NOW" > "$STAMP" 2>/dev/null || true
-    FLUSH="${CLAUDE_PLUGIN_ROOT:-$HOME/.claude/plugins/marketplaces/ruvnet-brain/plugin}/scripts/learn-flush.mjs"
-    [ -f "$FLUSH" ] && (nohup node "$FLUSH" >/dev/null 2>&1 &) || true
+    FLUSH="$HERE/learn-flush.mjs"
+    [ -f "$FLUSH" ] && (RUVNET_LEARNING_SCOPE="$SCOPE" nohup node "$FLUSH" >/dev/null 2>&1 &) || true
   fi
 fi
 exit 0

package/plugin/scripts/learn-flush.mjs

@@ -13,8 +13,15 @@ import os from 'node:os';
 import path from 'node:path';
 import { execFileSync } from 'node:child_process';
 import { readStdinBounded } from './hook-input.mjs';
+import { loadRuntimePreferences } from './runtime-preferences.mjs';
 
 const HOME = os.homedir();
+const PROJECT = process.env.RUVNET_BRAIN_PROJECT_DIR || process.cwd();
+const configuredScope = process.env.RUVNET_LEARNING_SCOPE
+  || loadRuntimePreferences({ cwd: PROJECT }).values.learningScope;
+const LEARNING_SCOPE = ['off', 'project', 'user'].includes(configuredScope)
+  ? configuredScope : 'project';
+if (LEARNING_SCOPE === 'off') process.exit(0);
 
 // THE SESSION ID COMES OFF THE PAYLOAD, exactly as it does in learn-capture.sh (fixed 2026-07-27).
 //
@@ -37,8 +44,12 @@ async function payloadSessionId() {
 }
 // A filename COMPONENT, never a path — the payload is untrusted input.
 const SID = ((await payloadSessionId()) || process.env.CLAUDE_SESSION_ID || '').replace(/[^A-Za-z0-9_-]/g, '') || 'default';
-const QUEUE = process.env.LEARN_QUEUE || path.join(HOME, '.cache/ruvnet-brain/learn', `session-${SID}.jsonl`);
+const QUEUE_ROOT = LEARNING_SCOPE === 'user'
+  ? path.join(HOME, '.cache', 'ruvnet-brain', 'learn')
+  : path.join(PROJECT, '.swarm', 'ruvnet-brain-learn');
+const QUEUE = process.env.LEARN_QUEUE || path.join(QUEUE_ROOT, `session-${SID}.jsonl`);
 const RUFLO = path.join(HOME, '.npm-global/bin/ruflo');
+const RUFLO_ENV = { ...process.env, RUFLO_DAEMON_AUTOSTART: '0' };
 const MAX_ACTIONS = 8; // bound the work so SessionEnd stays fast
 
 // THE DEADLINE. SessionEnd's registered timeout is 30s (plugin/hooks/hooks.json) and this hook fires
@@ -100,8 +111,14 @@ for (let i = 0; i < actions.length; i++) {
     ? ['hooks', 'post-command', '-c', s.action, '-s', 'true']
     : ['hooks', 'post-edit', '-f', s.action, '-s', 'true', '-o', 'session edit'];
   try {
-    // cwd: HOME → writes the GLOBAL per-user learner (cross-project), not a project-local one.
-    execFileSync(RUFLO, args, { cwd: HOME, stdio: 'ignore', timeout: Math.min(6000, remaining) });
+    // One command, two real Ruflo scopes: project cwd keeps patterns local; HOME retains the
+    // cross-project SONA learner for users who explicitly chose `user`.
+    execFileSync(RUFLO, args, {
+      cwd: LEARNING_SCOPE === 'user' ? HOME : PROJECT,
+      env: RUFLO_ENV,
+      stdio: 'ignore',
+      timeout: Math.min(6000, remaining),
+    });
     fed++;
   } catch { /* best-effort — one slow/failed record must not stall session end */ }
 }
@@ -129,7 +146,7 @@ if (fed > 0 || allDistinct.length === 0) {
   console.log(`learn-flush: 0/${actions.length} fed (ruflo hooks failing?) — queue KEPT for retry next session-end`);
 }
 if (process.argv.includes('--sync')) {
-  console.log(`learn-flush: fed ${fed}/${actions.length} distinct actions to the global learner`
+  console.log(`learn-flush: fed ${fed}/${actions.length} distinct actions to the ${LEARNING_SCOPE} learner`
     // Say the deadline out loud when it fires. A budget that silently truncates reads as "that was
     // all there was", which is the same lie as the count cap that preceded it.
     + (stoppedAt < actions.length ? `; STOPPED at ${stoppedAt}/${actions.length} on the ${DEADLINE_MS}ms deadline` : '')

package/plugin/scripts/runtime-preferences.mjs

@@ -0,0 +1,269 @@
+#!/usr/bin/env node
+// runtime-preferences.mjs — one policy boundary for every live Brain control.
+//
+// The console records intent. Runtime code asks this module what is allowed. Keeping that read in
+// one place prevents routing, QE, learning, and first-open initialization from each inventing a
+// subtly different default. Secrets are deliberately separate: ordinary settings and their backup
+// journal must never contain an API key.
+
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+
+const DEFAULT_HOME = os.homedir();
+const PROJECT_FILE = '.swarm/ruvnet-brain-settings.json';
+const PROJECT_KEYS = Object.freeze([
+  'routing',
+  'qeFleet',
+  'learningScope',
+  'autoApply',
+  'advocacy',
+  'provider',
+]);
+
+const readJSON = (file) => {
+  try {
+    const value = JSON.parse(fs.readFileSync(file, 'utf8'));
+    return value && typeof value === 'object' && !Array.isArray(value) ? value : null;
+  } catch {
+    return null;
+  }
+};
+
+export function preferencePaths({ env = process.env, cwd = process.cwd() } = {}) {
+  const home = env.HOME || DEFAULT_HOME;
+  return {
+    config: env.RUVNET_BRAIN_CONFIG_FILE
+      || path.join(home, '.claude', 'ruvnet-brain', 'config.json'),
+    settings: env.RUVNET_SETTINGS_FILE
+      || path.join(home, '.config', 'ruvnet-brain', 'settings.json'),
+    secrets: env.RUVNET_BRAIN_SECRETS_FILE
+      || path.join(home, '.config', 'ruvnet-brain', 'secrets.enc.json'),
+    project: env.RUVNET_BRAIN_PROJECT_SETTINGS_FILE
+      || path.join(cwd, PROJECT_FILE),
+    ageIdentity: env.SOPS_AGE_KEY_FILE
+      || path.join(home, '.config', 'sops', 'age', 'keys.txt'),
+  };
+}
+
+function validConfig(raw = {}) {
+  return {
+    provider: ['auto', 'anthropic', 'openai', 'codex', 'google', 'xai'].includes(raw.provider)
+      ? raw.provider : null,
+    routing: raw.routing === 'auto' || raw.routing === 'off' ? raw.routing : null,
+    qeFleet: typeof raw.qeFleet === 'boolean' ? raw.qeFleet : null,
+    nightly: typeof raw.nightly === 'boolean' ? raw.nightly : null,
+  };
+}
+
+function validSettings(raw = {}) {
+  const source = raw.settings && typeof raw.settings === 'object' ? raw.settings : raw;
+  return {
+    learningScope: ['off', 'project', 'user'].includes(source.learningScope)
+      ? source.learningScope : 'project',
+    autoApply: source.autoApply === true,
+    newProjectDefaults: source.newProjectDefaults === true,
+    advocacy: Number.isInteger(source.advocacy) && source.advocacy >= 1 && source.advocacy <= 5
+      ? source.advocacy : 3,
+  };
+}
+
+function validProject(raw = {}) {
+  const out = {};
+  if (raw.routing === 'auto' || raw.routing === 'off') out.routing = raw.routing;
+  if (typeof raw.qeFleet === 'boolean') out.qeFleet = raw.qeFleet;
+  if (['off', 'project', 'user'].includes(raw.learningScope)) out.learningScope = raw.learningScope;
+  if (typeof raw.autoApply === 'boolean') out.autoApply = raw.autoApply;
+  if (Number.isInteger(raw.advocacy) && raw.advocacy >= 1 && raw.advocacy <= 5) out.advocacy = raw.advocacy;
+  if (['auto', 'anthropic', 'openai', 'codex', 'google', 'xai'].includes(raw.provider)) out.provider = raw.provider;
+  return out;
+}
+
+export function loadRuntimePreferences(options = {}) {
+  const paths = preferencePaths(options);
+  const config = validConfig(readJSON(paths.config) || {});
+  const settings = validSettings(readJSON(paths.settings) || {});
+  const projectRaw = readJSON(paths.project);
+  const project = projectRaw ? validProject(projectRaw.values || projectRaw) : {};
+  return {
+    values: { ...config, ...settings, ...project },
+    chosen: {
+      routing: config.routing !== null || Object.hasOwn(project, 'routing'),
+      qeFleet: config.qeFleet !== null || Object.hasOwn(project, 'qeFleet'),
+      nightly: config.nightly !== null,
+    },
+    paths,
+    projectInherited: !!projectRaw,
+  };
+}
+
+function commandExists(command, env) {
+  const probe = spawnSync(command, ['--version'], {
+    env,
+    encoding: 'utf8',
+    shell: false,
+    timeout: 3000,
+  });
+  return !probe.error && probe.status === 0;
+}
+
+function decryptSecrets(paths, env) {
+  if (!fs.existsSync(paths.secrets) || !commandExists('sops', env)) return {};
+  const run = spawnSync('sops', ['decrypt', '--input-type', 'json', '--output-type', 'json', paths.secrets], {
+    env,
+    encoding: 'utf8',
+    shell: false,
+    timeout: 10_000,
+  });
+  if (run.status !== 0) return {};
+  return readJSONString(run.stdout);
+}
+
+function readJSONString(text) {
+  try {
+    const value = JSON.parse(text);
+    return value && typeof value === 'object' && !Array.isArray(value) ? value : {};
+  } catch {
+    return {};
+  }
+}
+
+export function openRouterCredentialStatus(options = {}) {
+  const env = options.env || process.env;
+  if (typeof env.OPENROUTER_API_KEY === 'string' && env.OPENROUTER_API_KEY.trim()) {
+    return { configured: true, source: 'environment', legacyPlaintext: false };
+  }
+  const paths = preferencePaths(options);
+  const encrypted = decryptSecrets(paths, env);
+  if (typeof encrypted.OPENROUTER_API_KEY === 'string' && encrypted.OPENROUTER_API_KEY.trim()) {
+    return { configured: true, source: 'sops-age', legacyPlaintext: false };
+  }
+  const legacy = readJSON(paths.config);
+  return {
+    configured: typeof legacy?.openrouterKey === 'string' && legacy.openrouterKey.trim().length > 8,
+    source: legacy?.openrouterKey ? 'legacy-plaintext' : null,
+    legacyPlaintext: !!legacy?.openrouterKey,
+  };
+}
+
+export function runtimeChildEnv(options = {}) {
+  const env = { ...(options.env || process.env) };
+  if (typeof env.OPENROUTER_API_KEY === 'string' && env.OPENROUTER_API_KEY.trim()) return env;
+  const paths = preferencePaths({ ...options, env });
+  const encrypted = decryptSecrets(paths, env);
+  if (typeof encrypted.OPENROUTER_API_KEY === 'string' && encrypted.OPENROUTER_API_KEY.trim()) {
+    env.OPENROUTER_API_KEY = encrypted.OPENROUTER_API_KEY.trim();
+    return env;
+  }
+  // Read-only migration compatibility. The legacy value is consumed but never copied into a new
+  // file or returned to the caller; the console marks it for migration.
+  const legacy = readJSON(paths.config);
+  if (typeof legacy?.openrouterKey === 'string' && legacy.openrouterKey.trim()) {
+    env.OPENROUTER_API_KEY = legacy.openrouterKey.trim();
+  }
+  return env;
+}
+
+function ageRecipient(identityFile, env) {
+  if (!fs.existsSync(identityFile) || !commandExists('age-keygen', env)) return null;
+  const run = spawnSync('age-keygen', ['-y', identityFile], {
+    env,
+    encoding: 'utf8',
+    shell: false,
+    timeout: 5000,
+  });
+  return run.status === 0 ? run.stdout.trim() : null;
+}
+
+export function saveOpenRouterCredential(secret, options = {}) {
+  if (typeof secret !== 'string' || secret.trim().length < 9) {
+    return { ok: false, log: 'OpenRouter key was not saved — enter a complete key.' };
+  }
+  const env = options.env || process.env;
+  const paths = preferencePaths({ ...options, env });
+  if (!commandExists('sops', env) || !commandExists('age-keygen', env)) {
+    return { ok: false, log: 'OpenRouter key was not saved — SOPS and age are required for encrypted storage. OPENROUTER_API_KEY in your environment remains supported.' };
+  }
+  const recipient = ageRecipient(paths.ageIdentity, env);
+  if (!recipient) {
+    return { ok: false, log: 'OpenRouter key was not saved — no SOPS age identity is configured. Set SOPS_AGE_KEY_FILE or use OPENROUTER_API_KEY.' };
+  }
+  const input = JSON.stringify({ OPENROUTER_API_KEY: secret.trim() });
+  const run = spawnSync('sops', [
+    'encrypt',
+    '--input-type', 'json',
+    '--output-type', 'json',
+    '--age', recipient,
+    '/dev/stdin',
+  ], {
+    env,
+    input,
+    encoding: 'utf8',
+    shell: false,
+    timeout: 10_000,
+  });
+  if (run.status !== 0 || !run.stdout.trim()) {
+    return { ok: false, log: 'OpenRouter key was not saved — SOPS encryption failed. The plaintext was not written to disk.' };
+  }
+  try {
+    fs.mkdirSync(path.dirname(paths.secrets), { recursive: true, mode: 0o700 });
+    let backup = null;
+    if (fs.existsSync(paths.secrets)) {
+      backup = `${paths.secrets}.bak-${new Date().toISOString().replace(/[:.]/g, '-')}`;
+      fs.copyFileSync(paths.secrets, backup, fs.constants.COPYFILE_EXCL);
+      fs.chmodSync(backup, 0o600);
+    }
+    const tmp = `${paths.secrets}.tmp-${process.pid}-${Date.now()}`;
+    fs.writeFileSync(tmp, run.stdout, { flag: 'wx', mode: 0o600 });
+    fs.renameSync(tmp, paths.secrets);
+    fs.chmodSync(paths.secrets, 0o600);
+    return {
+      ok: true,
+      log: 'OpenRouter key saved with SOPS+age encryption.',
+      path: paths.secrets,
+      backup,
+      existed: backup !== null,
+    };
+  } catch {
+    return { ok: false, log: 'OpenRouter key was encrypted but could not be saved. No plaintext file was created.' };
+  }
+}
+
+export function seedProjectDefaults(options = {}) {
+  const state = loadRuntimePreferences(options);
+  if (!state.values.newProjectDefaults) return { ok: true, action: 'disabled', path: state.paths.project };
+  const cwd = options.cwd || process.cwd();
+  const looksLikeProject = ['.git', 'package.json', 'Cargo.toml', 'pyproject.toml', 'go.mod']
+    .some((name) => fs.existsSync(path.join(cwd, name)));
+  if (!looksLikeProject && options.env?.RUVNET_ALLOW_NONPROJECT_DEFAULTS !== '1') {
+    return { ok: true, action: 'not-a-project', path: state.paths.project };
+  }
+  if (fs.existsSync(state.paths.project)) return { ok: true, action: 'already-initialized', path: state.paths.project };
+  const values = {};
+  for (const key of PROJECT_KEYS) {
+    const value = state.values[key];
+    if (value !== null && value !== undefined) values[key] = value;
+  }
+  const payload = {
+    version: 1,
+    inheritedAt: new Date().toISOString(),
+    source: 'user-defaults',
+    values,
+  };
+  try {
+    fs.mkdirSync(path.dirname(state.paths.project), { recursive: true, mode: 0o700 });
+    fs.writeFileSync(state.paths.project, `${JSON.stringify(payload, null, 2)}\n`, { flag: 'wx', mode: 0o600 });
+    return { ok: true, action: 'created', path: state.paths.project, values };
+  } catch (error) {
+    if (error?.code === 'EEXIST') return { ok: true, action: 'already-initialized', path: state.paths.project };
+    return { ok: false, action: 'failed', path: state.paths.project, error: error?.message || String(error) };
+  }
+}
+
+if (process.argv.includes('--learning-scope')) {
+  process.stdout.write(`${loadRuntimePreferences().values.learningScope}\n`);
+} else if (process.argv.includes('--seed-project')) {
+  const result = seedProjectDefaults();
+  if (!result.ok) process.exitCode = 1;
+}