@triflux/core 10.0.0-alpha.1 → 10.0.0

package/hud/renderers.mjs

@@ -16,14 +16,15 @@ import {
   TEAM_STATE_PATH, SV_ACCUMULATOR_PATH, LEGACY_SV_ACCUMULATOR,
 } from "./constants.mjs";
 import {
-  readJson, readJsonMigrate, stripAnsi, padAnsiRight, fitText,
+  readJson, readJsonMigrate, stripAnsi, padAnsiRight, fitText, truncateAnsi,
   clampPercent, formatPercentCell, formatPlaceholderPercentCell,
   formatTimeCell, formatTimeCellDH,
   formatResetRemaining, formatResetRemainingDayHour,
-  getContextPercent, formatTokenCount, formatSvPct, formatSavings,
+  formatTokenCount, formatSvPct, formatSavings,
 } from "./utils.mjs";
-import { tierBar, tierDimBar } from "./terminal.mjs";
+import { tierBar, tierDimBar, getTerminalColumns } from "./terminal.mjs";
 import { deriveGeminiLimits } from "./providers/gemini.mjs";
+import { buildContextUsageView } from "./context-monitor.mjs";
 
 // ============================================================================
 // 최근 벤치마크 diff 파일 읽기
@@ -125,27 +126,39 @@ export function getTeamRow(currentTier) {
 // 행 정렬 렌더링
 // ============================================================================
 export function renderAlignedRows(rows) {
+  const cols = getTerminalColumns() || 120;
   const rightRows = rows.filter((row) => stripAnsi(String(row.right || "")).trim().length > 0);
   const rawLeftWidth = rightRows.reduce((max, row) => Math.max(max, stripAnsi(row.left).length), 0);
   return rows.map((row) => {
     const prefix = padAnsiRight(row.prefix, PROVIDER_PREFIX_WIDTH);
     const hasRight = stripAnsi(String(row.right || "")).trim().length > 0;
     if (!hasRight) {
-      return `${prefix} ${row.left}`;
+      return truncateAnsi(`${prefix} ${row.left}`, cols);
     }
     // 자기 left 대비 패딩 상한: 최대 2칸까지만 패딩 (과도한 공백 방지)
     const ownLen = stripAnsi(row.left).length;
     const effectiveWidth = Math.min(rawLeftWidth, ownLen + 2);
     const left = padAnsiRight(row.left, effectiveWidth);
-    return `${prefix} ${left} ${dim("|")} ${row.right}`;
+    // 우선순위 기반 truncate: right 먼저 축소, 그래도 넘치면 left 축소
+    // prefix(PROVIDER_PREFIX_WIDTH) + " "(1) + left(effectiveWidth) + " | "(3) + right
+    const fixedWidth = PROVIDER_PREFIX_WIDTH + 1 + effectiveWidth + 3;
+    const availableForRight = cols - fixedWidth;
+    if (availableForRight <= 0) {
+      return truncateAnsi(`${prefix} ${left}`, cols);
+    }
+    const rightVisible = stripAnsi(row.right).length;
+    const right = rightVisible <= availableForRight
+      ? row.right
+      : truncateAnsi(row.right, availableForRight);
+    return `${prefix} ${left} ${dim("|")} ${right}`;
   });
 }
 
 // ============================================================================
 // micro tier: 모든 프로바이더를 1줄로 압축
 // ============================================================================
-export function getMicroLine(stdin, claudeUsage, codexBuckets, geminiSession, geminiBucket, combinedSvPct) {
-  const ctx = getContextPercent(stdin);
+export function getMicroLine(contextView, claudeUsage, codexBuckets, geminiSession, geminiBucket, combinedSvPct) {
+  const ctxView = contextView || buildContextUsageView({}, null);
 
   // Claude 5h/1w
   const cF = claudeUsage?.fiveHourPercent != null ? clampPercent(claudeUsage.fiveHourPercent) : null;
@@ -180,18 +193,20 @@ export function getMicroLine(stdin, claudeUsage, codexBuckets, geminiSession, ge
   // sv
   const sv = formatSvPct(combinedSvPct || 0).trim();
 
-  return `${bold(claudeOrange("c"))}${dim(":")}${cVal} ` +
+  const cols = getTerminalColumns() || 120;
+  const line = `${bold(claudeOrange("c"))}${dim(":")}${cVal} ` +
     `${bold(codexWhite("x"))}${dim(":")}${xVal} ` +
     `${bold(geminiBlue("g"))}${dim(":")}${gVal} ` +
     `${dim("sv:")}${sv} ` +
-    `${dim("ctx:")}${colorByPercent(ctx, `${ctx}%`)}`;
+    `${dim("CTX:")}${colorByPercent(ctxView.percent, ctxView.display)}`;
+  return truncateAnsi(line, cols);
 }
 
 // ============================================================================
 // Claude 행 렌더러
 // ============================================================================
-export function getClaudeRows(currentTier, stdin, claudeUsage, combinedSvPct) {
-  const contextPercent = getContextPercent(stdin);
+export function getClaudeRows(currentTier, contextView, claudeUsage, combinedSvPct) {
+  const ctxView = contextView || buildContextUsageView({}, null);
   const prefix = `${bold(claudeOrange("c"))}:`;
 
   // 절약 퍼센트
@@ -226,18 +241,21 @@ export function getClaudeRows(currentTier, stdin, claudeUsage, combinedSvPct) {
 
   if (currentTier === "minimal") {
     const quotaSection = `${dim("5h:")}${fStr} ${dim("1w:")}${wStr}`;
-    return [{ prefix, left: quotaSection, right: "" }];
+    const right = `${dim("CTX:")}${colorByPercent(ctxView.percent, ctxView.display)}`;
+    return [{ prefix, left: quotaSection, right }];
   }
 
   if (currentTier === "compact") {
     const quotaSection = `${dim("5h:")}${fStr} ${dim(fTime)} ${dim("1w:")}${wStr} ${dim(wTime)}`;
-    const contextSection = `${svSuffix} ${dim("|")} ${dim("ctx:")}${colorByPercent(contextPercent, `${contextPercent}%`)}`;
+    const warning = ctxView.warningTag ? ` ${dim("|")} ${yellow(ctxView.warningTag)}` : "";
+    const contextSection = `${svSuffix} ${dim("|")} ${dim("CTX:")}${colorByPercent(ctxView.percent, ctxView.display)}${warning}`;
     return [{ prefix, left: quotaSection, right: contextSection }];
   }
 
   // full tier (>= 120 cols)
   const quotaSection = `${dim("5h:")}${fBar}${fStr} ${dim(fTime)} ${dim("1w:")}${wBar}${wStr} ${dim(wTime)}`;
-  const contextSection = `${svSuffix} ${dim("|")} ${dim("ctx:")}${colorByPercent(contextPercent, `${contextPercent}%`)}`;
+  const warning = ctxView.warningTag ? ` ${dim("|")} ${yellow(ctxView.warningTag)}` : "";
+  const contextSection = `${svSuffix} ${dim("|")} ${dim("CTX:")}${colorByPercent(ctxView.percent, ctxView.display)}${warning}`;
   return [{ prefix, left: quotaSection, right: contextSection }];
 }
 

package/hud/utils.mjs

@@ -82,6 +82,32 @@ export function fitText(text, width) {
   return `${t.slice(0, width - 1)}…`;
 }
 
+/**
+ * ANSI 이스케이프 시퀀스를 보존하면서 visible width 기준으로 truncate.
+ * maxWidth 초과 시 잘라내고 RESET(\x1b[0m)을 추가한다.
+ */
+export function truncateAnsi(text, maxWidth) {
+  if (maxWidth <= 0) return "";
+  const str = String(text);
+  let visible = 0;
+  let i = 0;
+  while (i < str.length) {
+    if (str.charCodeAt(i) === 0x1b && str[i + 1] === "[") {
+      const mIdx = str.indexOf("m", i + 2);
+      if (mIdx !== -1) {
+        i = mIdx + 1;
+        continue;
+      }
+    }
+    visible++;
+    if (visible > maxWidth) {
+      return str.slice(0, i) + "\x1b[0m";
+    }
+    i++;
+  }
+  return str;
+}
+
 export function makeHash(text) {
   return createHash("sha256").update(String(text || ""), "utf8").digest("hex").slice(0, 16);
 }

package/package.json

@@ -1,12 +1,13 @@
 {
   "name": "@triflux/core",
-  "version": "10.0.0-alpha.1",
+  "version": "10.0.0",
   "description": "triflux core — CLI routing, pipeline, adapters. Zero native dependencies.",
   "type": "module",
   "main": "hub/index.mjs",
   "exports": {
     ".": "./hub/index.mjs",
-    "./hub/*": "./hub/*"
+    "./hub/*": "./hub/*",
+    "./scripts/*": "./scripts/*"
   },
   "engines": { "node": ">=18.0.0" },
   "dependencies": {

package/scripts/lib/claudemd-scanner.mjs

@@ -0,0 +1,218 @@
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+export const TFX_START = "<!-- TFX:START -->";
+export const TFX_END = "<!-- TFX:END -->";
+export const OMC_END = "<!-- OMC:END -->";
+const TFX_VERSION_RE = /<!-- TFX:VERSION:([\d.]+) -->/u;
+
+const LEGACY_PATTERNS = [
+  /<user_cli_routing>/u,
+  /Codex Pro 무료 기간/u,
+  /codex exec --dangerously-bypass.*skip-git-repo-check/u,
+  /OMC 에이전트 → CLI 매핑/u,
+  /Spark 가드레일/u,
+];
+
+const DEFAULT_TFX_TEMPLATE = [
+  "### triflux CLI routing (managed)",
+  "- 이 블록은 triflux setup에서 자동으로 관리됩니다.",
+  "- 직접 수정이 필요하면 블록 바깥에 사용자 섹션을 추가하세요.",
+].join("\n");
+
+const SCRIPT_DIR = dirname(fileURLToPath(import.meta.url));
+const DEFAULT_TEMPLATE_PATH = join(SCRIPT_DIR, "..", "templates", "claudemd-tfx-section.md");
+
+function resolveVersion(version) {
+  if (version) return version;
+  try {
+    const pkgPath = join(SCRIPT_DIR, "..", "..", "package.json");
+    const pkg = JSON.parse(readFileSync(pkgPath, "utf8"));
+    return pkg.version || "0.0.0";
+  } catch {
+    return "0.0.0";
+  }
+}
+
+function resolveTemplate(template, templatePath = DEFAULT_TEMPLATE_PATH) {
+  if (typeof template === "string" && template.trim()) {
+    return template.trim();
+  }
+  if (existsSync(templatePath)) {
+    const raw = readFileSync(templatePath, "utf8").trim();
+    if (raw) return raw;
+  }
+  return DEFAULT_TFX_TEMPLATE;
+}
+
+function findManagedSection(rawText) {
+  const raw = String(rawText || "");
+  const startIdx = raw.indexOf(TFX_START);
+  const endMarkerIdx = raw.indexOf(TFX_END);
+  if (startIdx === -1 || endMarkerIdx === -1 || endMarkerIdx <= startIdx) {
+    return {
+      found: false,
+      content: null,
+      version: null,
+      startIdx: -1,
+      endIdx: -1,
+    };
+  }
+
+  const endIdx = endMarkerIdx + TFX_END.length;
+  const content = raw.slice(startIdx, endIdx);
+  const versionMatch = content.match(TFX_VERSION_RE);
+
+  return {
+    found: true,
+    content,
+    version: versionMatch ? versionMatch[1] : null,
+    startIdx,
+    endIdx,
+  };
+}
+
+function detectLegacyRange(rawText) {
+  const raw = String(rawText || "");
+  const matches = LEGACY_PATTERNS.some((pattern) => pattern.test(raw));
+  if (!matches) {
+    return { found: false, startIdx: -1, endIdx: -1 };
+  }
+
+  const startTag = raw.indexOf("<user_cli_routing>");
+  const endTag = raw.indexOf("</user_cli_routing>");
+  if (startTag === -1 || endTag === -1 || endTag <= startTag) {
+    return { found: true, startIdx: -1, endIdx: -1 };
+  }
+
+  let removeStart = startTag;
+  const userOverridesComment = "<!-- USER OVERRIDES";
+  const commentIdx = raw.lastIndexOf(userOverridesComment, startTag);
+  if (commentIdx !== -1 && startTag - commentIdx < 200) {
+    removeStart = commentIdx;
+  }
+
+  return {
+    found: true,
+    startIdx: removeStart,
+    endIdx: endTag + "</user_cli_routing>".length,
+  };
+}
+
+function normalizeSpacing(text) {
+  return String(text || "").replace(/\n{3,}/gu, "\n\n");
+}
+
+export function findAllClaudeMdPaths(options = {}) {
+  const cwd = options.cwd ? resolve(options.cwd) : process.cwd();
+  const homeDir = options.homeDir ? resolve(options.homeDir) : homedir();
+  const includeGlobal = options.includeGlobal !== false;
+  const includeProject = options.includeProject !== false;
+
+  const candidates = [];
+  if (includeGlobal) candidates.push(join(homeDir, ".claude", "CLAUDE.md"));
+  if (includeProject) candidates.push(join(cwd, "CLAUDE.md"));
+
+  const seen = new Set();
+  const paths = [];
+  for (const candidate of candidates) {
+    const normalized = resolve(candidate);
+    if (seen.has(normalized)) continue;
+    seen.add(normalized);
+    if (existsSync(normalized)) {
+      paths.push(normalized);
+    }
+  }
+  return paths;
+}
+
+export function writeSection(filePath, options = {}) {
+  const absolutePath = resolve(filePath);
+  const version = resolveVersion(options.version);
+  const template = resolveTemplate(options.template, options.templatePath);
+  const block = [
+    TFX_START,
+    `<!-- TFX:VERSION:${version} -->`,
+    template,
+    TFX_END,
+  ].join("\n");
+
+  if (!existsSync(absolutePath)) {
+    writeFileSync(absolutePath, `${block}\n`, "utf8");
+    return { action: "created", version, path: absolutePath };
+  }
+
+  const raw = readFileSync(absolutePath, "utf8");
+  const existing = findManagedSection(raw);
+
+  if (existing.found) {
+    const nextContent = `${raw.slice(0, existing.startIdx)}${block}${raw.slice(existing.endIdx)}`;
+    writeFileSync(absolutePath, nextContent, "utf8");
+    return {
+      action: "updated",
+      oldVersion: existing.version,
+      version,
+      path: absolutePath,
+    };
+  }
+
+  const omcEndIdx = raw.indexOf(OMC_END);
+  if (omcEndIdx !== -1) {
+    const insertAt = omcEndIdx + OMC_END.length;
+    const before = raw.slice(0, insertAt);
+    const after = raw.slice(insertAt);
+    const nextContent = `${before}\n${block}${after}`;
+    writeFileSync(absolutePath, nextContent, "utf8");
+    return { action: "inserted_after_omc", version, path: absolutePath };
+  }
+
+  const separator = raw.endsWith("\n") ? "" : "\n";
+  writeFileSync(absolutePath, `${raw}${separator}${block}\n`, "utf8");
+  return { action: "appended", version, path: absolutePath };
+}
+
+export function migrateClaudeMd(filePath, options = {}) {
+  const absolutePath = resolve(filePath);
+  if (!existsSync(absolutePath)) {
+    return { action: "no_file", removed: [], path: absolutePath };
+  }
+
+  const raw = readFileSync(absolutePath, "utf8");
+  const existing = findManagedSection(raw);
+  const legacy = detectLegacyRange(raw);
+
+  if (existing.found && !legacy.found) {
+    return {
+      action: "already_managed",
+      removed: [],
+      version: existing.version,
+      path: absolutePath,
+    };
+  }
+
+  const removed = [];
+  let nextContent = raw;
+
+  if (legacy.found && legacy.startIdx !== -1 && legacy.endIdx !== -1) {
+    nextContent = `${nextContent.slice(0, legacy.startIdx)}${nextContent.slice(legacy.endIdx)}`;
+    removed.push("<user_cli_routing> block");
+  }
+
+  const existingAfterLegacy = findManagedSection(nextContent);
+  if (existingAfterLegacy.found) {
+    nextContent = `${nextContent.slice(0, existingAfterLegacy.startIdx)}${nextContent.slice(existingAfterLegacy.endIdx)}`;
+    removed.push("old TFX block");
+  }
+
+  writeFileSync(absolutePath, normalizeSpacing(nextContent), "utf8");
+  const writeResult = writeSection(absolutePath, options);
+
+  return {
+    action: "migrated",
+    removed,
+    version: writeResult.version,
+    path: absolutePath,
+  };
+}

package/scripts/lib/handoff.mjs

@@ -0,0 +1,171 @@
+import { execSync } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import { basename, resolve } from "node:path";
+import { findAllClaudeMdPaths } from "./claudemd-scanner.mjs";
+
+function runCommand(command, cwd, executor = execSync) {
+  try {
+    const output = executor(command, {
+      cwd,
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"],
+      windowsHide: true,
+    });
+    return String(output || "").trimEnd();
+  } catch {
+    return "";
+  }
+}
+
+function parseStatusLines(statusText) {
+  const lines = String(statusText || "").split(/\r?\n/u).filter(Boolean);
+  const changedFiles = [];
+  const status = [];
+
+  for (const line of lines) {
+    const normalized = line.trimEnd();
+    if (!normalized) continue;
+
+    const rawStatus = normalized.slice(0, 2).trim() || "??";
+    const rawPath = normalized.slice(3).trim();
+    const filePath = rawPath.includes(" -> ") ? rawPath.split(" -> ").at(-1)?.trim() : rawPath;
+    if (!filePath) continue;
+
+    changedFiles.push(filePath);
+    status.push({ path: filePath, status: rawStatus });
+  }
+
+  return {
+    changedFiles: Array.from(new Set(changedFiles)),
+    status,
+  };
+}
+
+function normalizeDecisionLine(line) {
+  return String(line || "")
+    .trim()
+    .replace(/^[-*]\s+/u, "")
+    .trim();
+}
+
+function parseDecisionFile(decisionFile) {
+  if (!decisionFile) return [];
+  const absolute = resolve(decisionFile);
+  if (!existsSync(absolute)) return [];
+
+  const raw = readFileSync(absolute, "utf8");
+  return raw
+    .split(/\r?\n/u)
+    .map(normalizeDecisionLine)
+    .filter((line) => line.length > 0);
+}
+
+function normalizeDecisions(decisions, decisionFile) {
+  const merged = [
+    ...(Array.isArray(decisions) ? decisions : []),
+    ...parseDecisionFile(decisionFile),
+  ]
+    .map(normalizeDecisionLine)
+    .filter(Boolean);
+
+  return Array.from(new Set(merged));
+}
+
+function formatAheadBehind(value) {
+  if (!value) return null;
+  const [behindRaw, aheadRaw] = value.split(/\s+/u);
+  const behind = Number.parseInt(behindRaw, 10);
+  const ahead = Number.parseInt(aheadRaw, 10);
+  if (!Number.isFinite(behind) || !Number.isFinite(ahead)) return null;
+  return { ahead, behind };
+}
+
+export function collectHandoffContext(options = {}) {
+  const cwd = resolve(options.cwd || process.cwd());
+  const executor = typeof options.commandRunner === "function" ? options.commandRunner : execSync;
+  const target = options.target === "local" ? "local" : "remote";
+  const decisions = normalizeDecisions(options.decisions, options.decisionFile);
+  const generatedAt = options.generatedAt || new Date().toISOString();
+  const claudeMdPaths = Array.isArray(options.claudeMdPaths)
+    ? options.claudeMdPaths
+    : findAllClaudeMdPaths({
+      cwd,
+      homeDir: options.homeDir,
+    });
+
+  const gitRoot = runCommand("git rev-parse --show-toplevel", cwd, executor);
+  const branch = runCommand("git rev-parse --abbrev-ref HEAD", cwd, executor) || null;
+  const shortStatus = runCommand("git status --short", cwd, executor);
+  const diffStat = runCommand("git diff --stat --no-color", cwd, executor);
+  const upstreamRaw = runCommand("git rev-list --left-right --count @{upstream}...HEAD", cwd, executor);
+  const parsedStatus = parseStatusLines(shortStatus);
+
+  return {
+    generatedAt,
+    target,
+    cwd,
+    gitRoot: gitRoot || null,
+    repository: gitRoot ? basename(gitRoot) : basename(cwd),
+    branch,
+    upstream: formatAheadBehind(upstreamRaw),
+    changedFiles: parsedStatus.changedFiles,
+    fileStatus: parsedStatus.status,
+    diffStat,
+    decisions,
+    claudeMdPaths,
+  };
+}
+
+export function buildHandoffPrompt(context) {
+  const safeContext = context || collectHandoffContext();
+  const branch = safeContext.branch || "unknown";
+  const upstream = safeContext.upstream
+    ? `ahead ${safeContext.upstream.ahead}, behind ${safeContext.upstream.behind}`
+    : "unknown";
+  const changedFiles = safeContext.changedFiles.length > 0
+    ? safeContext.changedFiles.map((file) => `- ${file}`).join("\n")
+    : "- 변경 파일 없음";
+  const decisions = safeContext.decisions.length > 0
+    ? safeContext.decisions.map((decision) => `- ${decision}`).join("\n")
+    : "- 명시된 결정사항 없음";
+  const claudeMdList = Array.isArray(safeContext.claudeMdPaths) && safeContext.claudeMdPaths.length > 0
+    ? safeContext.claudeMdPaths.map((path) => `- ${path}`).join("\n")
+    : "- 자동 탐지된 CLAUDE.md 없음";
+  const diffStat = safeContext.diffStat || "(diff stat 없음)";
+
+  return [
+    "## TFX Remote Handoff",
+    `- generated_at: ${safeContext.generatedAt}`,
+    `- target: ${safeContext.target}`,
+    `- repository: ${safeContext.repository}`,
+    `- branch: ${branch} (${upstream})`,
+    `- cwd: ${safeContext.cwd}`,
+    "",
+    "### 변경 파일",
+    changedFiles,
+    "",
+    "### 변경 요약 (git diff --stat)",
+    "```",
+    diffStat,
+    "```",
+    "",
+    "### 결정사항",
+    decisions,
+    "",
+    "### CLAUDE.md 참조",
+    claudeMdList,
+    "",
+    "### 다음 세션 지시",
+    "- 위 변경사항을 먼저 검토하고 누락된 테스트를 확인하세요.",
+    "- 필요 시 CLAUDE.md 지침을 재확인한 뒤 작업을 이어가세요.",
+    "- 작업 완료 후 변경 파일과 검증 결과를 요약하세요.",
+  ].join("\n");
+}
+
+export function serializeHandoff(options = {}) {
+  const context = collectHandoffContext(options);
+  return {
+    ...context,
+    prompt: buildHandoffPrompt(context),
+  };
+}

package/scripts/lib/mcp-guard-engine.mjs

@@ -543,6 +543,18 @@ export function loadRegistry() {
   };
 }
 
+export function loadRegistryOrDefault() {
+  const state = inspectRegistry();
+  if (!state.exists) return cloneDefaultRegistry();
+  if (!state.valid) return cloneDefaultRegistry();
+  return {
+    ...state.registry,
+    defaults: { ...(state.registry?.defaults || {}) },
+    servers: { ...(state.registry?.servers || {}) },
+    policies: { ...(state.registry?.policies || {}) },
+  };
+}
+
 export function saveRegistry(registry) {
   const errors = validateRegistry(registry);
   if (errors.length > 0) {
@@ -552,7 +564,7 @@ export function saveRegistry(registry) {
   return registry;
 }
 
-export function listManagedConfigTargets(registry = loadRegistry()) {
+export function listManagedConfigTargets(registry = loadRegistryOrDefault()) {
   return (registry?.policies?.watched_paths || []).map((watchedPath) => {
     const filePath = resolveFilePath(watchedPath);
     return {
@@ -565,18 +577,18 @@ export function listManagedConfigTargets(registry = loadRegistry()) {
   });
 }
 
-export function listPrimaryConfigTargets(registry = loadRegistry()) {
+export function listPrimaryConfigTargets(registry = loadRegistryOrDefault()) {
   return listManagedConfigTargets(registry).filter((target) => isPrimaryConfigTarget(target.filePath));
 }
 
-export function scanManagedConfigs(registry = loadRegistry()) {
+export function scanManagedConfigs(registry = loadRegistryOrDefault()) {
   return listManagedConfigTargets(registry).map((target) => ({
     ...target,
     ...scanConfig(target.filePath),
   }));
 }
 
-export function inspectRegistryStatus(registry = loadRegistry()) {
+export function inspectRegistryStatus(registry = loadRegistryOrDefault()) {
   const configs = scanManagedConfigs(registry);
   const primaryTargets = new Set(listPrimaryConfigTargets(registry).map((target) => normalizeForMatch(target.filePath)));
   const rows = [];
@@ -710,7 +722,7 @@ export function remediate(filePath, stdioServers, policy = {}) {
   let replacement = null;
 
   if (action === "replace-with-hub") {
-    const registry = loadRegistry();
+    const registry = loadRegistryOrDefault();
     const [hubServerName, hubServerConfig] = getHubServerEntry(registry);
     const desired = buildDesiredServerRecord(hubServerName, hubServerConfig, resolvedPath);
     replacement = { name: desired.name, ...desired.config };
@@ -823,6 +835,8 @@ export function removeRegistryServer(name) {
   const trimmedName = String(name || "").trim();
   if (!trimmedName) throw new Error("server name is required");
 
+  const state = inspectRegistry();
+  if (!state.exists || !state.valid) return null;
   const registry = loadRegistry();
   const existing = registry.servers[trimmedName] || null;
   if (existing) {
@@ -881,7 +895,7 @@ export function removeServerFromTargets(name, options = {}) {
 }
 
 export function syncRegistryTargets(options = {}) {
-  const registry = options.registry || loadRegistry();
+  const registry = options.registry || loadRegistryOrDefault();
   const actions = [];
 
   for (const target of listManagedConfigTargets(registry)) {