qualia-framework 6.2.9 → 6.2.10

package/bin/contract-runner.js

@@ -0,0 +1,219 @@
+#!/usr/bin/env node
+// Execute Qualia phase contract checks and write evidence.
+// No shell interpolation: command checks run through spawnSync(argv).
+
+const fs = require("fs");
+const path = require("path");
+const { spawnSync } = require("child_process");
+const pc = require("./plan-contract.js");
+
+function parseArgs(argv) {
+  const args = { _: [] };
+  for (let i = 2; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--json") args.json = true;
+    else if (a === "--no-write") args.no_write = true;
+    else if (a === "--cwd") args.cwd = argv[++i];
+    else if (a.startsWith("--cwd=")) args.cwd = a.slice("--cwd=".length);
+    else args._.push(a);
+  }
+  return args;
+}
+
+function usage() {
+  console.error([
+    "Usage:",
+    "  contract-runner.js <contract.json> [--cwd DIR] [--json] [--no-write]",
+    "",
+    "Runs file-exists, grep-match, command-exit, and behavioral evidence checks.",
+  ].join("\n"));
+}
+
+function rel(root, p) {
+  return path.resolve(root, p);
+}
+
+function checkFileExists(root, check) {
+  const file = rel(root, check.path);
+  if (!fs.existsSync(file)) return { ok: false, detail: `missing file: ${check.path}` };
+  if (check.must_contain != null) {
+    const content = fs.readFileSync(file, "utf8");
+    if (!content.includes(check.must_contain)) {
+      return { ok: false, detail: `file does not contain required text: ${check.path}` };
+    }
+  }
+  return { ok: true };
+}
+
+function checkGrepMatch(root, check) {
+  const file = rel(root, check.path);
+  if (!fs.existsSync(file)) return { ok: false, detail: `missing file: ${check.path}` };
+  const content = fs.readFileSync(file, "utf8");
+  const re = new RegExp(check.pattern);
+  const present = re.test(content);
+  if (check.expect === "present" && !present) return { ok: false, detail: `pattern absent: ${check.pattern}` };
+  if (check.expect === "absent" && present) return { ok: false, detail: `pattern present: ${check.pattern}` };
+  return { ok: true };
+}
+
+function checkCommandExit(root, check) {
+  const started = Date.now();
+  const r = spawnSync(check.command, check.args || [], {
+    cwd: root,
+    encoding: "utf8",
+    timeout: check.timeout_ms || 30_000,
+    stdio: ["ignore", "pipe", "pipe"],
+    shell: false,
+  });
+  const status = typeof r.status === "number" ? r.status : 1;
+  if (status !== check.expected_exit) {
+    return {
+      ok: false,
+      detail: `exit ${status}, expected ${check.expected_exit}`,
+      duration_ms: Date.now() - started,
+      stdout: (r.stdout || "").slice(-1000),
+      stderr: (r.stderr || r.error?.message || "").slice(-1000),
+    };
+  }
+  if (check.expect_stdout_match != null) {
+    const re = new RegExp(check.expect_stdout_match);
+    if (!re.test(r.stdout || "")) {
+      return {
+        ok: false,
+        detail: `stdout did not match: ${check.expect_stdout_match}`,
+        duration_ms: Date.now() - started,
+        stdout: (r.stdout || "").slice(-1000),
+        stderr: (r.stderr || "").slice(-1000),
+      };
+    }
+  }
+  return {
+    ok: true,
+    duration_ms: Date.now() - started,
+    stdout: (r.stdout || "").slice(-1000),
+    stderr: (r.stderr || "").slice(-1000),
+  };
+}
+
+function checkBehavioral(root, check) {
+  for (const ev of check.evidence_required || []) {
+    const file = rel(root, ev.path);
+    if (!fs.existsSync(file)) {
+      return { ok: false, detail: `missing evidence file: ${ev.path}` };
+    }
+    if (ev.matcher != null) {
+      const content = fs.readFileSync(file, "utf8");
+      const re = new RegExp(ev.matcher);
+      if (!re.test(content)) {
+        return { ok: false, detail: `evidence matcher failed for ${ev.path}: ${ev.matcher}` };
+      }
+    }
+  }
+  return { ok: true };
+}
+
+function runCheck(root, check) {
+  try {
+    if (check.type === "file-exists") return checkFileExists(root, check);
+    if (check.type === "grep-match") return checkGrepMatch(root, check);
+    if (check.type === "command-exit") return checkCommandExit(root, check);
+    if (check.type === "behavioral") return checkBehavioral(root, check);
+    return { ok: false, detail: `unknown check type: ${check.type}` };
+  } catch (e) {
+    return { ok: false, detail: e.message };
+  }
+}
+
+function writeEvidence(root, contract, result) {
+  const dir = path.join(root, ".planning", "evidence");
+  fs.mkdirSync(dir, { recursive: true });
+  const phase = Number(contract.phase || 0) || "unknown";
+  const file = path.join(dir, `phase-${phase}-contract-run.json`);
+  fs.writeFileSync(file, JSON.stringify(result, null, 2) + "\n");
+  return path.relative(root, file);
+}
+
+function runContract(contract, opts = {}) {
+  const root = path.resolve(opts.cwd || process.cwd());
+  const errors = pc.validate(contract);
+  if (errors.length > 0) {
+    return {
+      ok: false,
+      error: "CONTRACT_INVALID",
+      errors,
+      checked: 0,
+      failed: errors.length,
+      results: [],
+    };
+  }
+
+  const results = [];
+  for (const task of contract.tasks || []) {
+    for (let i = 0; i < (task.verification || []).length; i++) {
+      const check = task.verification[i];
+      const r = runCheck(root, check);
+      results.push({
+        task_id: task.id,
+        task_title: task.title,
+        index: i,
+        type: check.type,
+        ok: !!r.ok,
+        detail: r.detail || "",
+        duration_ms: r.duration_ms,
+        stdout: r.stdout,
+        stderr: r.stderr,
+      });
+    }
+  }
+  const failed = results.filter((r) => !r.ok).length;
+  const payload = {
+    ok: failed === 0,
+    phase: contract.phase,
+    goal: contract.goal,
+    checked: results.length,
+    failed,
+    generated_at: new Date().toISOString(),
+    results,
+  };
+  if (!opts.no_write) payload.evidence_file = writeEvidence(root, contract, payload);
+  return payload;
+}
+
+function main(argv) {
+  const args = parseArgs(argv);
+  const contractPath = args._[0];
+  if (!contractPath || contractPath === "--help" || contractPath === "-h") {
+    usage();
+    return 2;
+  }
+  const loaded = pc.readContractFile(contractPath);
+  if (!loaded.ok) {
+    const payload = { ok: false, ...loaded, path: contractPath };
+    if (args.json) console.log(JSON.stringify(payload, null, 2));
+    else console.error(`${payload.error}: ${payload.message}`);
+    return 2;
+  }
+  const result = runContract(loaded.contract, {
+    cwd: args.cwd,
+    no_write: args.no_write,
+  });
+  if (args.json) {
+    console.log(JSON.stringify(result, null, 2));
+  } else if (result.ok) {
+    console.log(`PASS phase ${result.phase}: ${result.checked} check(s)`);
+    if (result.evidence_file) console.log(`Evidence: ${result.evidence_file}`);
+  } else {
+    console.error(`FAIL phase ${result.phase || "?"}: ${result.failed} of ${result.checked || result.failed} check(s) failed`);
+    for (const r of result.results || []) {
+      if (!r.ok) console.error(`- ${r.task_id} ${r.type}: ${r.detail}`);
+    }
+    if (result.error) for (const e of result.errors || []) console.error(`- ${e}`);
+  }
+  return result.ok ? 0 : 1;
+}
+
+module.exports = { runContract, runCheck };
+
+if (require.main === module) {
+  process.exit(main(process.argv));
+}

package/bin/host-adapters.js

@@ -0,0 +1,66 @@
+#!/usr/bin/env node
+// Host adapter rendering for installed Qualia text surfaces.
+
+const path = require("path");
+const os = require("os");
+
+const HOSTS = {
+  claude: {
+    name: "Claude Code",
+    home: path.join(os.homedir(), ".claude"),
+  },
+  codex: {
+    name: "OpenAI Codex",
+    home: path.join(os.homedir(), ".codex"),
+  },
+};
+
+function adapter(name) {
+  const host = HOSTS[name];
+  if (!host) throw new Error(`Unknown Qualia host adapter: ${name}`);
+  const home = host.home;
+  return {
+    ...host,
+    tokens: {
+      QUALIA_HOME: home,
+      QUALIA_BIN: `${home}/bin`,
+      QUALIA_AGENTS: `${home}/agents`,
+      QUALIA_SKILLS: `${home}/skills`,
+      QUALIA_RULES: `${home}/rules`,
+      QUALIA_TEMPLATES: `${home}/qualia-templates`,
+      QUALIA_KNOWLEDGE: `${home}/knowledge`,
+      QUALIA_REFERENCES: `${home}/qualia-references`,
+      QUALIA_DESIGN: `${home}/qualia-design`,
+    },
+  };
+}
+
+function renderText(content, hostName) {
+  const host = adapter(hostName);
+  let out = String(content);
+  for (const [token, value] of Object.entries(host.tokens)) {
+    out = out.replaceAll(`\${${token}}`, value);
+  }
+
+  // Backward-compatible rendering while source files migrate from hardcoded
+  // Claude paths to explicit ${QUALIA_*} tokens.
+  out = out
+    .replaceAll("~/.claude/", `${host.home}/`)
+    .replaceAll("$HOME/.claude/", `${host.home}/`)
+    .replaceAll("${HOME}/.claude/", `${host.home}/`)
+    .replaceAll("@~/.claude/", `@${host.home}/`)
+    .replaceAll(".claude/", `${path.basename(host.home)}/`);
+
+  if (hostName === "codex") {
+    out = out
+      .replaceAll("Claude Code", "Codex")
+      .replaceAll("Claude's", "Codex's");
+  }
+  return out;
+}
+
+module.exports = {
+  HOSTS,
+  adapter,
+  renderText,
+};

package/bin/install.js

@@ -4,6 +4,8 @@ const { createInterface } = require("readline");
 const path = require("path");
 const fs = require("fs");
 const ui = require("./qualia-ui.js");
+const { RUNTIME_BIN_SCRIPTS, binFiles } = require("./runtime-manifest.js");
+const { renderText } = require("./host-adapters.js");
 
 // ─── Colors (kept for legacy log lines; new sections route through qualia-ui) ─
 const TEAL = "\x1b[38;2;0;206;209m";
@@ -24,6 +26,24 @@ const TARGET_CLAUDE_ONLY = "1";
 const TARGET_CODEX_ONLY = "2";
 const TARGET_BOTH = "3";
 
+const CODEX_STATUS_LINE = [
+  "model-with-reasoning",
+  "task-progress",
+  "current-dir",
+  "git-branch",
+  "context-used",
+  "five-hour-limit",
+  "weekly-limit",
+];
+
+const CODEX_STATUS_LINE_BLOCK = [
+  "# Added by qualia-framework — Codex native bottom status line.",
+  "[tui]",
+  `status_line = ${JSON.stringify(CODEX_STATUS_LINE)}`,
+  "status_line_use_colors = true",
+  "",
+].join("\n");
+
 // Total install timer — set in main(), read by the final summary card.
 const installStart = Date.now();
 
@@ -125,14 +145,8 @@ function copyTree(src, dest) {
   }
 }
 
-function codexText(content) {
-  return String(content)
-    .replaceAll("~/.claude/", "~/.codex/")
-    .replaceAll("$HOME/.claude/", "$HOME/.codex/")
-    .replaceAll("${HOME}/.claude/", "${HOME}/.codex/")
-    .replaceAll("@~/.claude/", "@~/.codex/")
-    .replaceAll(".claude/", ".codex/");
-}
+const claudeText = (content) => renderText(content, "claude");
+const codexText = (content) => renderText(content, "codex");
 
 function copyTextTransform(src, dest, transform) {
   const destDir = path.dirname(dest);
@@ -156,6 +170,45 @@ function copyTreeTransform(src, dest, transform) {
   }
 }
 
+function ensureCodexStatusLineConfig(existing) {
+  const statusLine = `status_line = ${JSON.stringify(CODEX_STATUS_LINE)}`;
+  const colors = "status_line_use_colors = true";
+  if (!existing || !existing.trim()) {
+    return [
+      "# Created by qualia-framework install.",
+      "# User settings can be added normally; Qualia runtime lives in AGENTS.md, hooks.json, agents/, and bin/.",
+      "",
+      "[features]",
+      "hooks = true",
+      "plugin_hooks = true",
+      "",
+      "# Codex's native status line is rendered at the bottom of the TUI.",
+      "# It supports a fixed list of built-in segment names. Custom command-backed",
+      "# status lines are not supported in Codex 0.133, so Qualia phase/project",
+      "# context is rendered by the SessionStart banner while the native bottom",
+      "# line keeps model, task, directory, git, context, and limit state visible.",
+      CODEX_STATUS_LINE_BLOCK,
+    ].join("\n");
+  }
+
+  let next = existing;
+  if (!/^\[tui\]\s*$/m.test(next)) {
+    return `${next.replace(/\s*$/, "\n\n")}${CODEX_STATUS_LINE_BLOCK}`;
+  }
+
+  const tuiMatch = next.match(/^\[tui\]\s*$(?:\n(?!\[)[^\n]*)*/m);
+  if (!tuiMatch) return `${next.replace(/\s*$/, "\n\n")}${CODEX_STATUS_LINE_BLOCK}`;
+
+  let tuiBlock = tuiMatch[0];
+  if (!/^\s*status_line\s*=/m.test(tuiBlock)) {
+    tuiBlock = tuiBlock.replace(/^\[tui\]\s*$/m, `[tui]\n${statusLine}`);
+  }
+  if (!/^\s*status_line_use_colors\s*=/m.test(tuiBlock)) {
+    tuiBlock = `${tuiBlock.replace(/\s*$/, "")}\n${colors}`;
+  }
+  return `${next.slice(0, tuiMatch.index)}${tuiBlock}${next.slice(tuiMatch.index + tuiMatch[0].length)}`;
+}
+
 function backupIfDifferent(dest, nextContent, label) {
   if (!fs.existsSync(dest)) return false;
   try {
@@ -207,9 +260,7 @@ function parseAgentMarkdown(content) {
 
 function renderCodexAgentToml(markdown, filenameFallback) {
   const parsed = parseAgentMarkdown(markdown);
-  const body = parsed.body
-    .replaceAll("~/.claude/", "~/.codex/")
-    .replaceAll("@~/.claude/", "@~/.codex/");
+  const body = codexText(parsed.body);
   const name = (parsed.name || filenameFallback || "").replace(/^qualia-/, "");
   const description = parsed.description || "Qualia Framework specialist agent.";
   return [
@@ -507,14 +558,15 @@ async function main() {
   for (const name of claudePruned) ok(`pruned deprecated: ${name}`);
   for (const skill of skills) {
     try {
-      copy(
+      copyTextTransform(
         path.join(skillsDir, skill, "SKILL.md"),
-        path.join(CLAUDE_DIR, "skills", skill, "SKILL.md")
+        path.join(CLAUDE_DIR, "skills", skill, "SKILL.md"),
+        claudeText
       );
       // Copy REFERENCE.md if the skill has one (progressive-disclosure pattern)
       const refSrc = path.join(skillsDir, skill, "REFERENCE.md");
       if (fs.existsSync(refSrc)) {
-        copy(refSrc, path.join(CLAUDE_DIR, "skills", skill, "REFERENCE.md"));
+        copyTextTransform(refSrc, path.join(CLAUDE_DIR, "skills", skill, "REFERENCE.md"), claudeText);
       }
       // v5.1: Copy scripts/ subfolder if present (e.g. qualia-polish ships
       // playwright-capture.mjs, loop.mjs, score.mjs that the --loop mode
@@ -537,7 +589,7 @@ async function main() {
   const agentsDir = path.join(FRAMEWORK_DIR, "agents");
   for (const file of fs.readdirSync(agentsDir)) {
     try {
-      copy(path.join(agentsDir, file), path.join(CLAUDE_DIR, "agents", file));
+      copyTextTransform(path.join(agentsDir, file), path.join(CLAUDE_DIR, "agents", file), claudeText);
       ok(file);
     } catch (e) {
       warn(`${file} — ${e.message}`);
@@ -549,7 +601,7 @@ async function main() {
   const rulesDir = path.join(FRAMEWORK_DIR, "rules");
   for (const file of fs.readdirSync(rulesDir)) {
     try {
-      copy(path.join(rulesDir, file), path.join(CLAUDE_DIR, "rules", file));
+      copyTextTransform(path.join(rulesDir, file), path.join(CLAUDE_DIR, "rules", file), claudeText);
       ok(file);
     } catch (e) {
       warn(`${file} — ${e.message}`);
@@ -590,7 +642,7 @@ async function main() {
   if (fs.existsSync(designDir)) {
     for (const file of fs.readdirSync(designDir)) {
       try {
-        copy(path.join(designDir, file), path.join(designDest, file));
+        copyTextTransform(path.join(designDir, file), path.join(designDest, file), claudeText);
         ok(file);
       } catch (e) {
         warn(`${file} — ${e.message}`);
@@ -651,10 +703,10 @@ async function main() {
     const destPath = path.join(tmplDest, entry.name);
     try {
       if (entry.isDirectory()) {
-        copyTree(srcPath, destPath);
+        copyTreeTransform(srcPath, destPath, claudeText);
         ok(`${entry.name}/ (directory)`);
       } else {
-        copy(srcPath, destPath);
+        copyTextTransform(srcPath, destPath, claudeText);
         ok(entry.name);
       }
     } catch (e) {
@@ -685,7 +737,7 @@ async function main() {
         if (fs.existsSync(dest)) {
           log(`${DIM}${file} (kept — user has customized)${RESET}`);
         } else {
-          copy(src, dest);
+          copyTextTransform(src, dest, claudeText);
           ok(`${file} (initialized)`);
         }
       } catch (e) {
@@ -702,7 +754,7 @@ async function main() {
     if (!fs.existsSync(refDest)) fs.mkdirSync(refDest, { recursive: true });
     for (const file of fs.readdirSync(refDir)) {
       try {
-        copy(path.join(refDir, file), path.join(refDest, file));
+        copyTextTransform(path.join(refDir, file), path.join(refDest, file), claudeText);
         ok(file);
       } catch (e) {
         warn(`${file} — ${e.message}`);
@@ -741,7 +793,7 @@ async function main() {
         try { fs.copyFileSync(claudeDest, bak); ok(`Backed up existing CLAUDE.md → ${path.basename(bak)}`); } catch {}
       }
     }
-    fs.writeFileSync(claudeDest, claudeMd, "utf8");
+    fs.writeFileSync(claudeDest, claudeText(claudeMd), "utf8");
     ok(`Configured as ${member.role}`);
   } catch (e) {
     warn(`CLAUDE.md — ${e.message}`);
@@ -752,84 +804,23 @@ async function main() {
   try {
     const binDest = path.join(CLAUDE_DIR, "bin");
     if (!fs.existsSync(binDest)) fs.mkdirSync(binDest, { recursive: true });
-    copy(
-      path.join(FRAMEWORK_DIR, "bin", "state.js"),
-      path.join(binDest, "state.js")
-    );
-    ok("state.js (state machine)");
-    copy(
-      path.join(FRAMEWORK_DIR, "bin", "qualia-ui.js"),
-      path.join(binDest, "qualia-ui.js")
-    );
-    fs.chmodSync(path.join(binDest, "qualia-ui.js"), 0o755);
-    ok("qualia-ui.js (cosmetics library)");
-    copy(
-      path.join(FRAMEWORK_DIR, "bin", "statusline.js"),
-      path.join(binDest, "statusline.js")
-    );
-    ok("statusline.js (status bar renderer)");
-    copy(
-      path.join(FRAMEWORK_DIR, "bin", "knowledge.js"),
-      path.join(binDest, "knowledge.js")
-    );
-    fs.chmodSync(path.join(binDest, "knowledge.js"), 0o755);
-    ok("knowledge.js (memory-layer loader)");
-    copy(
-      path.join(FRAMEWORK_DIR, "bin", "knowledge-flush.js"),
-      path.join(binDest, "knowledge-flush.js")
-    );
-    fs.chmodSync(path.join(binDest, "knowledge-flush.js"), 0o755);
-    ok("knowledge-flush.js (cron-runnable flush)");
-    copy(
-      path.join(FRAMEWORK_DIR, "bin", "plan-contract.js"),
-      path.join(binDest, "plan-contract.js")
-    );
-    ok("plan-contract.js (plan JSON validator)");
-    copy(
-      path.join(FRAMEWORK_DIR, "bin", "agent-runs.js"),
-      path.join(binDest, "agent-runs.js")
-    );
-    ok("agent-runs.js (agent telemetry writer)");
-    copy(
-      path.join(FRAMEWORK_DIR, "bin", "slop-detect.mjs"),
-      path.join(binDest, "slop-detect.mjs")
-    );
-    fs.chmodSync(path.join(binDest, "slop-detect.mjs"), 0o755);
-    ok("slop-detect.mjs (anti-pattern scanner — runs pre-commit on frontend builds)");
-    copy(
-      path.join(FRAMEWORK_DIR, "bin", "erp-retry.js"),
-      path.join(binDest, "erp-retry.js")
-    );
-    fs.chmodSync(path.join(binDest, "erp-retry.js"), 0o755);
-    ok("erp-retry.js (ERP report retry queue — drained by session-start hook and erp-flush CLI)");
-    copy(
-      path.join(FRAMEWORK_DIR, "bin", "report-payload.js"),
-      path.join(binDest, "report-payload.js")
-    );
-    fs.chmodSync(path.join(binDest, "report-payload.js"), 0o755);
-    ok("report-payload.js (Framework -> ERP report payload builder)");
-    copy(
-      path.join(FRAMEWORK_DIR, "bin", "project-snapshot.js"),
-      path.join(binDest, "project-snapshot.js")
-    );
-    fs.chmodSync(path.join(binDest, "project-snapshot.js"), 0o755);
-    ok("project-snapshot.js (ERP/admin project progress snapshot)");
-    copy(
-      path.join(FRAMEWORK_DIR, "bin", "codex-goal.js"),
-      path.join(binDest, "codex-goal.js")
-    );
-    fs.chmodSync(path.join(binDest, "codex-goal.js"), 0o755);
-    ok("codex-goal.js (Codex /goal objective + token-budget suggester)");
+    for (const script of RUNTIME_BIN_SCRIPTS) {
+      const out = path.join(binDest, script.file);
+      copy(path.join(FRAMEWORK_DIR, "bin", script.file), out);
+      try { fs.chmodSync(out, 0o755); } catch {}
+      ok(script.label);
+    }
   } catch (e) {
     warn(`scripts — ${e.message}`);
   }
 
   // ─── Guide ─────────────────────────────────────────────
   try {
-    copy(
-      path.join(FRAMEWORK_DIR, "guide.md"),
-      path.join(CLAUDE_DIR, "qualia-guide.md")
-    );
+      copyTextTransform(
+        path.join(FRAMEWORK_DIR, "guide.md"),
+        path.join(CLAUDE_DIR, "qualia-guide.md"),
+        claudeText
+      );
     ok("guide.md");
   } catch (e) {
     warn(`guide.md — ${e.message}`);
@@ -1048,6 +1039,7 @@ Client-specific preferences, design choices, and requirements. Loaded by \`/qual
     excludeDefault: true,
     tips: [
       "⬢ Lost? Type /qualia for the next step",
+      "⬢ Broken behavior? Use /qualia-fix for root cause, patch, verify",
       "⬢ Single feature? Use /qualia-feature, it auto-scopes",
       "⬢ End of day? /qualia-report submits your shift before clock-out",
       "⬢ Context isolation: every task gets a fresh AI brain",
@@ -1264,6 +1256,7 @@ function printSummary({ member, target, claudeInstalled }) {
   }
   console.log("");
   console.log(`  ${DIM}New project?${RESET}    ${TEAL}/qualia-new${RESET}`);
+  console.log(`  ${DIM}Broken thing?${RESET}  ${TEAL}/qualia-fix${RESET}`);
   console.log(`  ${DIM}Single feature?${RESET} ${TEAL}/qualia-feature${RESET}`);
   console.log(`  ${DIM}End of day?${RESET}     ${TEAL}/qualia-report${RESET} ${DIM}(shift submission)${RESET}`);
   console.log(`  ${DIM}Stuck?${RESET}          ${TEAL}/qualia${RESET}`);
@@ -1341,53 +1334,20 @@ async function installCodex(member, target) {
   }
 
   // Codex treats config.toml as optional, but doctor reports a warning when it
-  // is absent. Create a minimal, parseable file on fresh Codex-only homes and
-  // leave existing user config untouched.
+  // is absent. Keep user settings intact while guaranteeing the native bottom
+  // status line is present.
   try {
     const configToml = path.join(CODEX_DIR, "config.toml");
+    const existing = fs.existsSync(configToml) ? fs.readFileSync(configToml, "utf8") : "";
+    const next = ensureCodexStatusLineConfig(existing);
     if (!fs.existsSync(configToml)) {
-      atomicWrite(configToml, [
-        "# Created by qualia-framework install.",
-        "# User settings can be added normally; Qualia runtime lives in AGENTS.md, hooks.json, agents/, and bin/.",
-        "",
-        "[features]",
-        "hooks = true",
-        "plugin_hooks = true",
-        "",
-        "# Codex's built-in status line is rendered at the bottom of the TUI.",
-        "# It takes an ARRAY of pre-defined segment names; Codex does NOT support",
-        "# custom-command status lines (unlike Claude's settings.json statusLine),",
-        "# so the Qualia phase/state info is rendered via the SessionStart banner",
-        "# at the top of the session instead. The segment list below mirrors the",
-        "# Codex default rich layout.",
-        "[tui]",
-        'status_line = ["model-with-reasoning", "task-progress", "current-dir", "git-branch", "context-used", "five-hour-limit", "weekly-limit"]',
-        "status_line_use_colors = true",
-        "",
-      ].join("\n"));
+      atomicWrite(configToml, next);
       ok("config.toml (minimal Codex config)");
+    } else if (next !== existing) {
+      atomicWrite(configToml, next);
+      ok("config.toml (Codex bottom status line)");
     } else {
-      // Existing user config — append [tui] block only if absent. Leaves
-      // every other user setting untouched.
-      try {
-        const existing = fs.readFileSync(configToml, "utf8");
-        if (!/^\[tui\]/m.test(existing) && !/^status_line\s*=/m.test(existing)) {
-          const append = [
-            "",
-            "# Added by qualia-framework — Codex bottom status line.",
-            "[tui]",
-            'status_line = ["model-with-reasoning", "task-progress", "current-dir", "git-branch", "context-used", "five-hour-limit", "weekly-limit"]',
-            "status_line_use_colors = true",
-            "",
-          ].join("\n");
-          fs.appendFileSync(configToml, append);
-          ok("config.toml (appended [tui] status line block)");
-        } else {
-          log(`${DIM}config.toml (kept — user has customized)${RESET}`);
-        }
-      } catch {
-        log(`${DIM}config.toml (kept — user has customized)${RESET}`);
-      }
+      log(`${DIM}config.toml (kept — Codex status line already wired)${RESET}`);
     }
   } catch (e) {
     warn(`Codex config.toml — ${e.message}`);
@@ -1436,20 +1396,7 @@ async function installCodex(member, target) {
   try {
     const binDest = path.join(CODEX_DIR, "bin");
     if (!fs.existsSync(binDest)) fs.mkdirSync(binDest, { recursive: true });
-    const scripts = [
-      "state.js",
-      "qualia-ui.js",
-      "statusline.js",
-      "knowledge.js",
-      "knowledge-flush.js",
-      "plan-contract.js",
-      "agent-runs.js",
-      "slop-detect.mjs",
-      "erp-retry.js",
-      "report-payload.js",
-      "project-snapshot.js",
-      "codex-goal.js",
-    ];
+    const scripts = binFiles();
     for (const script of scripts) {
       const src = path.join(FRAMEWORK_DIR, "bin", script);
       const out = path.join(binDest, script);
@@ -1487,9 +1434,9 @@ async function installCodex(member, target) {
     const rulesDest = path.join(CODEX_DIR, "rules");
     if (!fs.existsSync(rulesDest)) fs.mkdirSync(rulesDest, { recursive: true });
     for (const file of fs.readdirSync(rulesDir)) {
-      copy(path.join(rulesDir, file), path.join(rulesDest, file));
+      copyTextTransform(path.join(rulesDir, file), path.join(rulesDest, file), codexText);
     }
-    copyTree(path.join(FRAMEWORK_DIR, "qualia-design"), path.join(CODEX_DIR, "qualia-design"));
+    copyTreeTransform(path.join(FRAMEWORK_DIR, "qualia-design"), path.join(CODEX_DIR, "qualia-design"), codexText);
     ok("rules/ + qualia-design/");
   } catch (e) {
     warn(`Codex rules/design — ${e.message}`);