@yugabytedb/meko-mcp 1.1.0 → 1.2.0

package/assets/skills/meko-mcp-tools-desktop/references/tools-troubleshooting.md

@@ -0,0 +1,155 @@
+# Troubleshooting — Error Recovery and Retry Strategies
+
+These patterns are extracted from real agent sessions. Follow them to avoid wasting tool calls and context window on repeated failures.
+
+## General rules
+
+1. **Never retry the identical failed call more than once.** If it fails twice with the same error, it's not transient — diagnose the cause.
+2. **Distinguish transient vs persistent failures.** "Connection already closed" is transient (retry once). "Permission denied" is persistent (stop, don't retry).
+3. **Don't guess parameters sequentially.** If a tool fails with one parameter format, don't try 4 variations. Check this skill's docs for the correct format first.
+4. **Use your session's `agent_id` consistently.** For Claude Desktop the default is `claude_desktop`; for cross-project common facts use `meko_agent`. Other clients use `<client>:<repo-basename>` (e.g. `claude_code:meko-mcp-server`). Use `agent_id="meko_agent"` deliberately on `memory_search`/`memory_get_all` only when you want the common bucket — empty string also resolves to `meko_agent`, not a cross-agent fan-out. Don't switch between forms mid-session.
+
+---
+
+## Connection errors: "connection already closed"
+
+**Affects:** Memory tools (`memory_add`, `memory_search`, `memory_get_all`) most frequently. DB tools less often.
+
+**Why it happens:** The Python memory subsystem uses a connection cache that doesn't recover from dropped connections (unlike the Go API server which has retry logic with 5 retries and 3-second delays).
+
+**What to do:**
+
+1. Retry the same call **once**.
+2. If it fails again, the memory subsystem is unhealthy for this session — stop trying memory calls and tell the user. Do not waste tokens re-sending the same payload.
+3. Direct-SQL fallback **does not apply** on cloud Free Tier (`db_run_read_only_query` returns `{"error": "not_available", "detail": "Free Tier: DB Tools access is not enabled. coming soon."}`). On self-hosted / paid deployments where DB tools are available, inspect memory rows via the multi-tenant schema — tables are namespaced by datapack, not by agent_id. The old `{agent_id}_mem0_collection` per-agent-table layout is gone.
+
+**Anti-pattern from real sessions:** Agent called `memory_add` with 500+ tokens of text, got "connection already closed", retried the identical call 3 more times (each 500+ tokens). Wasted ~2000 tokens on guaranteed failures.
+
+---
+
+## RAG pipeline stuck at INIT
+
+**Affects:** `knowledgebase_trigger_index_creation` — the build triggers but never completes.
+
+**Symptoms:**
+- `knowledgebase_check_index_status` returns empty `pipeline_details` and `pipeline_stats`
+- Documents remain at `INIT` status indefinitely
+- Work queue tasks are `IN_PROGRESS` with `lease_expires_at` in the past
+
+**Diagnosis:** Query the work queue directly:
+```
+db_run_read_only_query(scope="read",
+    query="SELECT task_type, status, lease_expires_at FROM dist_rag.work_queue WHERE index_name = 'your_index' ORDER BY created_at DESC LIMIT 10")
+```
+
+Look for tasks stuck `IN_PROGRESS` with expired leases — these indicate crashed or hung workers.
+
+**What to do:**
+
+1. Poll status **at most 3 times** with 1-2 minute intervals
+2. If no progress after 3 checks, **stop polling** — the pipeline is stuck
+3. There is **no way to reset or retry stuck tasks via MCP tools**
+4. Creating a new index with a different name (e.g., `_v2`) is a workaround, but if the workers themselves are down, this will also get stuck
+5. Recommend the user check worker logs or restart the pipeline service
+
+**Anti-pattern from real sessions:** Agent created indexes `v1`, `v2`, `v3` — all stuck with the same symptoms. Even making the S3 bucket public didn't help. The issue was worker infrastructure, not permissions.
+
+---
+
+## db_run_write_query guardrail error
+
+**Error:** `'dict' object has no attribute 'guardrail_config'`
+
+**Affects:** `db_run_write_query` in some deployments.
+
+**What to do:**
+
+1. Try the call once. If it fails with this specific error, write operations are unavailable in this deployment.
+2. For reads, always use `db_run_read_only_query` (never `db_run_write_query` for SELECT).
+3. Report the issue — it's a server-side bug, not a parameter problem.
+
+---
+
+## knowledgebase_add_source_to_index failure
+
+**Error shape:** `{"error": "not_available", "detail": "Vector index creation is not available on the free tier."}`
+
+You're on cloud Free Tier; the ingestion tools are gated off. There is no retry that will succeed. Point the user at the Meko UI's **Add Knowledge** file-upload flow (Datapack → Actions → Add Knowledge) instead.
+
+**Error shape:** `{"error": "index_not_found", "detail": "No vector index found with name '...'"}`
+
+The `index_name` doesn't exist in this datapack's `dist_rag.vector_indexes` table. Either you're targeting the wrong datapack (check `datapack_id`), or the index hasn't been created yet — call `knowledgebase_trigger_index_creation` first.
+
+**Error shape:** tool returns `"build_triggered"` but `knowledgebase_check_index_status` shows documents stuck at `INIT` for >5 minutes.
+
+Most common cause on self-hosted deployments: the worker can't reach the S3 bucket. `S3BucketCrawler()` uses boto3's default credential chain — check `AWS_ACCESS_KEY_ID` / `AWS_SECRET_ACCESS_KEY` / IAM role / `~/.aws/credentials` on the worker host, not on the MCP server. Second cause: the URI isn't `s3://`-prefixed (`aws_source_processor.py` rejects other schemes with `ValueError("Invalid source URI")` async).
+
+**Historical note:** the old `r_index_name` vs `r_index_id` parameter-mismatch bug is fixed on main — the MCP tool now resolves `index_name → index_id` internally via a `SELECT id FROM dist_rag.vector_indexes WHERE index_name = %s` step. Older docs referencing this bug are stale.
+
+---
+
+## Scope parameter errors
+
+**Error:** `Insufficient scope: 'all'. This tool requires 'read' or higher.`
+
+The only valid scope values are: `"read"`, `"write"`, `"admin"`.
+
+- Use `"read"` for all read operations (default choice)
+- Use `"write"` for inserts, updates, creates, memory writes
+- Use `"admin"` only for destructive deletes
+
+**Never use:** `"all"`, `"readwrite"`, `"rw"`, or any other value.
+
+---
+
+## agent_id errors
+
+On the Cloud multi-tenant schema, `agent_id` is a TEXT column value — not a PostgreSQL identifier — so arbitrary strings are accepted.
+
+`agent_id` is **not a constant**. Cloud Meko supports multiple agents on one datapack, and the Cloud UI renders every `agent_id` as a badge on each row regardless of value. The canonical shape for new writes is `<client>:<repo-basename>` for coding agents (e.g. `claude_code:meko-mcp-server`), a bare client name for non-coding clients like Claude Desktop (`claude_desktop`), or `meko_agent` for the cross-project common bucket — see `tools-agent-id-conventions.md`.
+
+### "My writes are landing in `meko_agent` instead of my agent's bucket"
+
+If you call `memory_add` with empty / None / whitespace `agent_id`, the server does NOT reject the write. It silently resolves the value to `meko_agent` (the cross-project common bucket) and the row lands there. The Cloud UI then shows a `meko_agent` badge instead of your client's badge.
+
+Fix: always pass a concrete non-empty `agent_id`. For Claude Desktop use `agent_id="claude_desktop"`; for hook-driven clients (Claude Code, Cursor) fetch the value the SessionStart hook injected into `additionalContext` and pass it verbatim. Use `agent_id="meko_agent"` only when you genuinely want a fact in the cross-project pool (user identity, global preferences).
+
+### "My reads return fewer results than I expected"
+
+`memory_search` and `memory_get_all` filter strictly on your passed `agent_id`. A memory written by `claude-code:<slug-A>` is invisible to a search with `agent_id="cursor:<slug-B>"`. If you need a broader view, call repeatedly across the agent_ids you want to cover, or point the user at the UI's Memory Summary page (which shows every row regardless of agent_id).
+
+### "I'm seeing rows tagged with legacy agent_id values"
+
+Pre-existing data may be tagged `"agent"`, `"claude_code"`, `"cursor:<slug>"`, or similar ad-hoc values. All remain readable. New writes should follow the canonical `<client>:<project-slug>` form; don't try to retag old rows.
+
+---
+
+## Permission denied on data tables
+
+**Error:** `permission denied for table customer_complaints`
+
+**Why:** The MCP database user may not have read access to all tables, particularly data tables created by the provisioning system within a datapack.
+
+**What to do:**
+
+1. This is a server-side configuration issue — not fixable via MCP tools.
+2. Don't retry. Don't try different query formulations.
+3. Use `db_summarize_database` to see which tables you CAN access.
+4. Report the permission gap to the Meko admin.
+
+---
+
+## Safe-to-retry vs not
+
+| Tool | Safe to retry? | Why |
+|------|---------------|-----|
+| All `read` scope tools | Yes | Reads are idempotent |
+| `memory_add` | Yes (once) | Mem0 has dedup logic |
+| `memory_update` | Yes (once) | Overwrites same ID |
+| `memory_delete_by_id` | Yes | Deleting already-deleted is a no-op |
+| `db_run_write_query` (INSERT) | **No** | May double-insert rows |
+| `db_run_write_query` (CREATE TABLE) | **No** | "Table already exists" error |
+| `knowledgebase_trigger_index_creation` | **No** | Creates duplicate indexes |
+| `conversation_create` | **No** | Creates duplicate conversations |
+| `conversation_add_message` with `seed` | Yes | Seed-based dedup prevents duplicates |
+| `conversation_add_message` without `seed` | **No** | Creates duplicate messages |

package/bin/create-meko-setup.mjs

@@ -25,7 +25,7 @@ const options = {
   scope:              { type: 'string',  default: 'user' },
   name:               { type: 'string',  default: 'meko' },
   client:             { type: 'string',  default: 'claude-code' },
-  'cursor-hook-mode': { type: 'string',  default: 'hybrid' },
+  'cursor-hook-mode': { type: 'string',  default: 'native' },
   'skip-skills':      { type: 'boolean', default: false },
   'skip-validation':  { type: 'boolean', default: false },
   'no-canary':        { type: 'boolean', default: false },
@@ -109,7 +109,7 @@ Options:
                         codex always installs at user scope (no project-level
                         config); --scope=project degrades with a warning.
   --name <name>         MCP server name in config (default: meko)
-  --cursor-hook-mode    Cursor hook mode: native, claude-compat, hybrid (default: hybrid)
+  --cursor-hook-mode    Cursor hook mode: native or claude-compat (default: native)
   --skip-skills         Skip plugin and skills installation
   --skip-validation     Skip post-install validation
   --no-canary           Skip the canary datapack_list call. The
@@ -218,7 +218,7 @@ function detectInstalledClients() {
 }
 
 function isValidCursorHookMode(mode) {
-  return ['native', 'claude-compat', 'hybrid'].includes(mode);
+  return ['native', 'claude-compat'].includes(mode);
 }
 
 /**
@@ -391,7 +391,7 @@ async function main() {
     process.exit(0);
   }
   if (!isValidCursorHookMode(flags['cursor-hook-mode'])) {
-    error(`Unknown --cursor-hook-mode "${flags['cursor-hook-mode']}". Valid values: native, claude-compat, hybrid.`);
+    error(`Unknown --cursor-hook-mode "${flags['cursor-hook-mode']}". Valid values: native, claude-compat.`);
     process.exit(1);
   }
 

package/lib/clients/claude-desktop.mjs

@@ -9,8 +9,8 @@ import {
   removeKeys,
 } from "../config.mjs";
 import {
+  getAssetRoot,
   getInstallerVersion,
-  getRepoRoot,
   markerIsStale,
   readInstallerMarker,
   run,
@@ -39,13 +39,16 @@ import {
  * mcp-remote) with no space around the colon after the header name —
  * some clients mis-parse space-containing `--header` args.
  *
- * installSkills() runs skills/scripts/package-desktop-skill.sh to build the
- * .skill bundle and prints import instructions. Desktop has no programmatic
- * skill install API — the user drags the .skill into the app.
+ * installSkills() runs scripts/package-desktop-skill.sh under the resolved
+ * asset root to build the .skill bundle and prints import instructions.
+ * Desktop has no programmatic skill install API — the user drags the .skill
+ * into the app. The asset root is `installer/assets/` for packaged installs
+ * (npx) and `<repo>/skills/` for source checkouts; both layouts share the
+ * same shape so the script can be invoked the same way.
  */
 export function createClaudeDesktopAdapter(options = {}) {
   const configPathResolver = options.getConfigPath ?? getClaudeDesktopConfigPath;
-  const repoRootResolver = options.getRepoRoot ?? getRepoRoot;
+  const assetRootResolver = options.getAssetRoot ?? getAssetRoot;
   const packageRunner = options.runPackageScript ?? defaultRunPackageScript;
   const npxProber = options.probeNpx ?? defaultProbeNpx;
 
@@ -126,9 +129,9 @@ export function createClaudeDesktopAdapter(options = {}) {
       }
     },
     installSkills({ dryRun, log }) {
-      const repoRoot = repoRootResolver();
-      const script = join(repoRoot, "skills", "scripts", "package-desktop-skill.sh");
-      const output = join(repoRoot, "skills", "meko-mcp-tools-desktop.skill");
+      const assetRoot = assetRootResolver();
+      const script = join(assetRoot, "scripts", "package-desktop-skill.sh");
+      const output = join(assetRoot, "meko-mcp-tools-desktop.skill");
       // The .skill output is a ZIP file, so we can't drop a marker inside it.
       // Stamp the marker in the parent dir instead — it signals which
       // installer version produced the bundle sitting alongside it, so a

package/lib/clients/codex.mjs

@@ -11,12 +11,14 @@
 import { execSync } from "node:child_process";
 import {
   appendFileSync,
+  chmodSync,
   copyFileSync,
   existsSync,
   lstatSync,
   mkdirSync,
   readFileSync,
   readlinkSync,
+  rmSync,
   writeFileSync,
 } from "node:fs";
 import { homedir } from "node:os";
@@ -26,13 +28,19 @@ import { askYesNo } from "../prompt.mjs";
 import {
   getCodexAgentsMdPath,
   getCodexConfigPath,
+  getCodexHooksPath,
+  getCodexMekoEnvFilePath,
   getCodexSkillsRoot,
+  readJsonFile,
+  writeJsonFile,
 } from "../config.mjs";
 import {
   getInstallerVersion,
+  isDanglingSymlink,
   markerIsStale,
   readInstallerMarker,
   removePath,
+  resolveHooksRoot,
   resolveSkillSource,
   shellQuote,
   symlinkOrCopy,
@@ -54,12 +62,24 @@ const RC_FENCE_START = "# >>> meko mcp >>>";
 const RC_FENCE_END = "# <<< meko mcp <<<";
 
 const SKILLS = [{ name: "meko-mcp-tools" }];
+// Codex hook timeouts are in SECONDS (Duration::from_secs in
+// codex-rs/hooks/src/engine/command_runner.rs), not milliseconds like Claude
+// Code / Cursor. Default is 600s if omitted; we cap SessionStart/SessionEnd
+// at 15s/30s to match the Claude Code values logically.
+const MEKO_HOOKS = [
+  { event: "SessionStart", script: "session-start.sh", timeout: 15 },
+  { event: "PreCompact", script: "pre-compact.sh" },
+  { event: "SessionEnd", script: "session-end.sh", timeout: 30 },
+];
+const MEKO_HOOK_SCRIPTS = MEKO_HOOKS.map((hook) => hook.script);
 
 /**
  * @param {{
  *   getConfigPath?: () => string,
  *   getAgentsMdPath?: () => string,
+ *   getHooksPath?: () => string,
  *   getSkillsRoot?: () => string,
+ *   resolveHooksRoot?: () => string,
  *   runCommand?: (cmd: string) => string,
  *   probeCodex?: () => {found: boolean, version: string, path: string},
  *   probeCodexApp?: () => {found: boolean, path: string, platform: string, version: string} | null,
@@ -71,6 +91,10 @@ const SKILLS = [{ name: "meko-mcp-tools" }];
 export function createCodexAdapter(options = {}) {
   const resolveConfigPath = options.getConfigPath ?? getCodexConfigPath;
   const resolveAgentsMdPath = options.getAgentsMdPath ?? getCodexAgentsMdPath;
+  const resolveHooksPath = options.getHooksPath ?? getCodexHooksPath;
+  const resolveMekoEnvFilePath =
+    options.getMekoEnvFilePath ?? getCodexMekoEnvFilePath;
+  const resolveHooksRootPath = options.resolveHooksRoot ?? resolveHooksRoot;
   const resolveSkillsRoot = options.getSkillsRoot ?? getCodexSkillsRoot;
   const runCommand = options.runCommand ?? defaultRunCommand;
   const probeCodex = options.probeCodex ?? defaultProbeCodex;
@@ -256,6 +280,12 @@ export function createCodexAdapter(options = {}) {
               log,
             });
           }
+        } else if (hasApp && platform === "darwin") {
+          setLaunchctlMekoApiKey({
+            apiKey,
+            runCommand,
+            log,
+          });
         }
       }
 
@@ -268,10 +298,29 @@ export function createCodexAdapter(options = {}) {
       if (yes) return true;
       return promptUser(`${name} MCP is already configured. Overwrite?`, false);
     },
-    setHookEnvironment({ log, dryRun }) {
-      if (!dryRun) {
+    setHookEnvironment({ url, apiKey, log, dryRun, verbose }) {
+      const hooksPath = resolveHooksPath();
+      const hooksRoot = resolveHooksRootPath();
+      const envFilePath = resolveMekoEnvFilePath();
+      if (dryRun) {
+        log?.dim?.(`  Would write env file at ${envFilePath} (mode 0600)`);
+        log?.dim?.(`  Would configure Codex hooks at ${hooksPath}`);
+        if (apiKey) {
+          log?.dim?.(
+            `  MEKO_API_KEY will be stored in ${envFilePath} (mode 0600); hook commands source it (no API key in process args).`,
+          );
+        }
+        return;
+      }
+
+      writeCodexMekoEnvFile(envFilePath, { url, apiKey });
+      const changed = upsertCodexMekoHooks(hooksPath, hooksRoot, { envFilePath });
+      if (verbose || changed) {
+        log?.dim?.(`  Updated Codex hooks at ${hooksPath}`);
+      }
+      if (apiKey) {
         log?.dim?.(
-          "  Codex does not expose user-installable session hooks; auto-capture is unavailable.",
+          `  MEKO_API_KEY stored in ${envFilePath} (mode 0600). Hook commands source the file at run time, so the key never appears in process arguments.`,
         );
       }
     },
@@ -314,6 +363,15 @@ export function createCodexAdapter(options = {}) {
           } else {
             continue;
           }
+        } else if (isDanglingSymlink(destination)) {
+          // Stale symlink left behind by an earlier install whose target
+          // (e.g. a deleted worktree) no longer exists. existsSync is false
+          // for these, so the branch above misses them. Clear it so the
+          // fresh-install path below can replace it cleanly.
+          log.dim?.(
+            `  Replacing dangling symlink at ${destination} (target missing).`,
+          );
+          removePath(destination);
         }
 
         const strategy = symlinkOrCopy(source, destination);
@@ -373,6 +431,25 @@ export function createCodexAdapter(options = {}) {
         });
       }
 
+      try {
+        const hooksPath = resolveHooksPath();
+        const envFilePath = resolveMekoEnvFilePath();
+        const changed = removeCodexMekoHooks(hooksPath, { envFilePath });
+        if (changed) {
+          results.push({
+            key: "hooks",
+            ok: true,
+            message: "Codex Meko hooks cleaned up.",
+          });
+        }
+      } catch (err) {
+        results.push({
+          key: "hooks",
+          ok: false,
+          message: `Could not clean Codex hooks: ${err.message}`,
+        });
+      }
+
       try {
         const agentsMdPath = resolveAgentsMdPath();
         const raw = safeReadFile(agentsMdPath);
@@ -434,6 +511,149 @@ export function createCodexAdapter(options = {}) {
   };
 }
 
+// Codex's hooks.json schema only deserializes `hooks` and `state` — sibling
+// keys like `env` are silently dropped, and `HookHandlerConfig::Command` has
+// no per-command `env` field. The runner spawns each command via
+// `$SHELL -lc <command>` with the parent env inherited.
+//
+// We sidestep that by writing a 0600 env file (default ~/.codex/meko-env.sh)
+// that the hook command sources before invoking the script:
+//   `. /path/to/meko-env.sh && bash /path/to/hook.sh`
+// The API key never appears in process arguments, so a `ps -ef` from another
+// user (or a logging shim) can't lift it from the command line. Same trust
+// boundary as `git credential-store`.
+function upsertCodexMekoHooks(hooksPath, hooksRoot, { envFilePath } = {}) {
+  const cfg = readJsonFile(hooksPath);
+  const before = JSON.stringify(cfg);
+  if (!cfg.hooks || typeof cfg.hooks !== "object") {
+    cfg.hooks = {};
+  }
+
+  pruneCodexMekoHooksObject(cfg.hooks);
+  for (const hook of MEKO_HOOKS) {
+    const entry = {
+      type: "command",
+      command: buildCodexHookCommand(join(hooksRoot, hook.script), { envFilePath }),
+    };
+    if (hook.timeout) entry.timeout = hook.timeout;
+    upsertCodexHookEntry(cfg.hooks, hook.event, entry);
+  }
+
+  const after = JSON.stringify(cfg);
+  if (after !== before) {
+    writeJsonFile(hooksPath, cfg);
+    return true;
+  }
+  return false;
+}
+
+function buildCodexHookCommand(scriptPath, { envFilePath } = {}) {
+  const parts = [];
+  if (envFilePath) parts.push(`. ${shellQuote(envFilePath)}`);
+  parts.push(`bash ${shellQuote(scriptPath)}`);
+  return parts.join(" && ");
+}
+
+/**
+ * Write the Meko env file the Codex hooks source. Mode 0600 (user
+ * read/write only) so the API key isn't readable by other users.
+ * Idempotent: re-running with the same values is a no-op write that
+ * still asserts the mode.
+ */
+function writeCodexMekoEnvFile(path, { url, apiKey }) {
+  mkdirSync(dirname(path), { recursive: true });
+  const lines = [
+    "# Auto-generated by @yugabytedb/meko-mcp installer.",
+    "# Sourced by Codex hooks (see ~/.codex/hooks.json) before each hook runs.",
+    "# Mode 0600 — do not commit, do not share, do not relax permissions.",
+    `export MEKO_MCP_URL=${shellQuote(url || "")}`,
+    `export MEKO_API_KEY=${shellQuote(apiKey || "")}`,
+    "",
+  ];
+  writeFileSync(path, lines.join("\n"), { encoding: "utf8", mode: 0o600 });
+  // writeFileSync's `mode` only applies on initial create; re-assert
+  // explicitly so a permission relaxation between installs is corrected.
+  chmodSync(path, 0o600);
+}
+
+function removeCodexMekoHooks(hooksPath, { envFilePath } = {}) {
+  const cfg = readJsonFile(hooksPath);
+  let changed = false;
+  if (cfg.hooks && typeof cfg.hooks === "object") {
+    const before = JSON.stringify(cfg);
+    pruneCodexMekoHooksObject(cfg.hooks);
+    if (Object.keys(cfg.hooks).length === 0) {
+      delete cfg.hooks;
+    }
+    // Older installs (PR 127 first cut) wrote a top-level cfg.env block that
+    // Codex silently ignored. Strip it during uninstall so we don't leave a
+    // misleading env hanging around in user configs.
+    if (cfg.env && typeof cfg.env === "object") {
+      delete cfg.env.MEKO_MCP_URL;
+      delete cfg.env.MEKO_API_KEY;
+      if (Object.keys(cfg.env).length === 0) {
+        delete cfg.env;
+      }
+    }
+    if (JSON.stringify(cfg) !== before) {
+      writeJsonFile(hooksPath, cfg);
+      changed = true;
+    }
+  }
+
+  // Remove the meko-env.sh file too — leaving a 0600 file with credentials
+  // around after uninstall is a security gap.
+  if (envFilePath) {
+    try {
+      rmSync(envFilePath, { force: true });
+    } catch {
+      // best-effort
+    }
+  }
+  return changed;
+}
+
+function upsertCodexHookEntry(hooksObj, event, entry) {
+  if (!Array.isArray(hooksObj[event])) hooksObj[event] = [];
+  let group = hooksObj[event].find((item) => Array.isArray(item?.hooks));
+  if (!group) {
+    group = { hooks: [] };
+    hooksObj[event].push(group);
+  }
+  const exists = group.hooks.some((hook) => hook.command === entry.command);
+  if (!exists) group.hooks.push(entry);
+}
+
+function pruneCodexMekoHooksObject(hooksObj) {
+  for (const event of Object.keys(hooksObj)) {
+    const groups = hooksObj[event];
+    if (!Array.isArray(groups)) continue;
+    hooksObj[event] = groups
+      .map((group) => {
+        if (!Array.isArray(group?.hooks)) return group;
+        return {
+          ...group,
+          hooks: group.hooks.filter((hook) => !isMekoHookCommand(hook?.command)),
+        };
+      })
+      .filter((group) => !Array.isArray(group?.hooks) || group.hooks.length > 0);
+    if (hooksObj[event].length === 0) {
+      delete hooksObj[event];
+    }
+  }
+}
+
+function isMekoHookCommand(command) {
+  if (typeof command !== "string") return false;
+  return MEKO_HOOK_SCRIPTS.some((script) => {
+    const escaped = script.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    const pattern = new RegExp(
+      String.raw`(^|[/\\])hooks-handlers[/\\]${escaped}(?=$|['"\s])`,
+    );
+    return pattern.test(command);
+  });
+}
+
 // ---------------------------------------------------------------------------
 // Probes (default impls; tests inject stubs)
 // ---------------------------------------------------------------------------
@@ -915,12 +1135,24 @@ export async function maybeOfferLaunchctlSetenv({
     false,
   );
   if (!accept) return { set: false };
+  return setLaunchctlMekoApiKey({ apiKey, runCommand, log });
+}
+
+/**
+ * Run `launchctl setenv MEKO_API_KEY <key>` so the macOS Codex.app launched
+ * from Finder/Dock can authenticate during the current login session.
+ *
+ * The key is passed to launchctl but never logged.
+ *
+ * @returns {{set: boolean}}
+ */
+export function setLaunchctlMekoApiKey({ apiKey, runCommand, log }) {
   try {
     runCommand(`launchctl setenv MEKO_API_KEY ${shellQuote(apiKey)}`);
     log?.dim?.("  Set MEKO_API_KEY via launchctl (current login session).");
     return { set: true };
   } catch (err) {
-    log?.warn?.(`  launchctl setenv failed: ${err.message}`);
+    log?.warn?.("  launchctl setenv failed; run it manually if Codex.app needs cloud auth.");
     return { set: false };
   }
 }

package/lib/clients/common.mjs

@@ -5,6 +5,7 @@ import {
   symlinkSync,
   cpSync,
   lstatSync,
+  statSync,
   unlinkSync,
   rmSync,
   readFileSync,
@@ -108,14 +109,94 @@ export function shellQuote(value) {
   return `'${String(value).replace(/'/g, `'\\''`)}'`;
 }
 
+// statSync error codes that mean a symlink is broken — its target cannot be
+// resolved to a real inode. We deliberately do NOT include EACCES / EPERM:
+// those mean "target may exist but I can't see it", and silently removing
+// someone else's link based on a permission failure is unsafe.
+const BROKEN_SYMLINK_STAT_CODES = new Set([
+  "ENOENT", // target does not exist (the textbook "dangling symlink")
+  "ENOTDIR", // a non-directory component appears mid-path (e.g. link -> file/child)
+  "ELOOP", // too many redirections (cyclic symlinks)
+]);
+
+/**
+ * True when `targetPath` is a symlink whose target cannot be resolved. A
+ * regular file/dir or a working symlink returns false; a missing path also
+ * returns false. See `BROKEN_SYMLINK_STAT_CODES` for which resolution
+ * failures count.
+ *
+ * Why this matters: `existsSync` returns false for a broken symlink, so a
+ * naive `if (existsSync(dest)) {...}` branch falls through and tries to write
+ * over the symlink. On macOS, `cpSync` then aborts the entire process via an
+ * uncaught libc++ `filesystem_error` ("Operation not supported" inside
+ * `std::filesystem::equivalent`) whenever one operand is a broken symlink —
+ * not just the ENOENT case but also ENOTDIR (`link -> file/child`) and ELOOP.
+ * Detecting any of these lets callers either treat the path as an existing
+ * entry or clear it before writing.
+ *
+ * @param {string} targetPath
+ * @returns {boolean}
+ */
+export function isDanglingSymlink(targetPath) {
+  let stat;
+  try {
+    stat = lstatSync(targetPath);
+  } catch {
+    return false;
+  }
+  if (!stat.isSymbolicLink()) return false;
+  try {
+    statSync(targetPath);
+    return false;
+  } catch (err) {
+    return BROKEN_SYMLINK_STAT_CODES.has(err.code);
+  }
+}
+
+/**
+ * Unlink that tolerates the narrow race window where another process
+ * already removed `targetPath` between our check and our write (ENOENT)
+ * but propagates every other failure (EACCES, EPERM, EBUSY, etc.) as a
+ * normal JS error.
+ *
+ * Why not `removePath`: that helper swallows ALL errors, which is fine
+ * for cleanup paths but dangerous in front of `cpSync`. If unlink truly
+ * fails (e.g. read-only parent dir), the broken symlink is still on
+ * disk; cpSync would then dive into the macOS libc++ `filesystem_error`
+ * abort path described in `isDanglingSymlink`. Surfacing the unlink
+ * error here lets the surrounding installer surface a clean error
+ * instead of aborting the process.
+ *
+ * @param {string} targetPath
+ */
+function unlinkAllowingMissing(targetPath) {
+  try {
+    unlinkSync(targetPath);
+  } catch (err) {
+    if (err && err.code === "ENOENT") return;
+    throw err;
+  }
+}
+
 /**
  * Create symlink when possible; fallback to copy.
+ *
+ * Pre-clears a broken symlink at `destination` so the copy fallback path
+ * doesn't crash. See `isDanglingSymlink` above for the macOS libc++ trap.
+ * Uses `unlinkAllowingMissing` rather than `removePath` so an unlink
+ * failure (e.g. read-only parent dir) surfaces as a normal JS error
+ * instead of silently leaving the broken link in place — otherwise
+ * `cpSync` below would still abort the process.
+ *
  * @param {string} source
  * @param {string} destination
  * @returns {"symlink"|"copy"}
  */
 export function symlinkOrCopy(source, destination) {
   mkdirSync(dirname(destination), { recursive: true });
+  if (isDanglingSymlink(destination)) {
+    unlinkAllowingMissing(destination);
+  }
   try {
     symlinkSync(source, destination, "junction");
     return "symlink";