@yugabytedb/meko-mcp 2.1.0 → 2.3.0

package/lib/migrate/adapters/opencode.mjs

@@ -0,0 +1,148 @@
+import { execFileSync, spawnSync } from "node:child_process";
+import path from "node:path";
+import { agentIdForOpenCode } from "../id.mjs";
+import { normalizeOpenCodeSession } from "../opencode-normalizer.mjs";
+function defaultRunExport(sessionId, opts = {}) {
+  const runner = opts.runExport ?? defaultRunExportCommand;
+  return runner(sessionId, opts);
+}
+function defaultRunExportCommand(sessionId, opts = {}) {
+  const bin = opts.opencodeBin ?? probeOpenCode()?.path ?? "opencode";
+  const result = spawnSync(bin, ["export", sessionId], {
+    encoding: "utf8",
+    maxBuffer: 64 * 1024 * 1024,
+    timeout: 10_000,
+  });
+  if (result.error) throw result.error;
+  if (result.status !== 0) {
+    throw new Error(
+      `opencode export ${sessionId} failed (${result.status}): ${(result.stderr || "").trim()}`,
+    );
+  }
+  return parseJsonStdout(result.stdout);
+}
+function defaultRunList(opts = {}) {
+  const runner = opts.runList ?? defaultRunListCommand;
+  return runner(opts);
+}
+function defaultRunListCommand(opts = {}) {
+  // OpenCode 1.18.x exposes roots only here; child sessions are not
+  // enumerable through the supported CLI.
+  const bin = opts.opencodeBin ?? probeOpenCode()?.path ?? "opencode";
+  const result = spawnSync(bin, ["session", "list", "--format", "json"], {
+    encoding: "utf8",
+    maxBuffer: 16 * 1024 * 1024,
+    timeout: 10_000,
+  });
+  if (result.error) throw result.error;
+  if (result.status !== 0) {
+    throw new Error(
+      `opencode session list failed (${result.status}): ${(result.stderr || "").trim()}`,
+    );
+  }
+  return parseJsonStdout(result.stdout);
+}
+function parseJsonStdout(stdout) {
+  const trimmed = String(stdout || "").trim();
+  if (!trimmed) return [];
+  try {
+    return JSON.parse(trimmed);
+  } catch (err) {
+    throw new Error(`invalid OpenCode JSON output: ${err.message}`);
+  }
+}
+export function probeOpenCode(opts = {}) {
+  const probe = opts.probe ?? opts.probeOpenCode ?? defaultProbeOpenCode;
+  return probe();
+}
+export function isSupportedOpenCodeVersion(version) {
+  const match = String(version || "").match(/(\d+)\.(\d+)\.(\d+)/);
+  return Boolean(match && Number(match[1]) === 1 && Number(match[2]) === 18);
+}
+function defaultProbeOpenCode() {
+  try {
+    const which = process.platform === "win32" ? "where" : "which";
+    const pathResult = execFileSync(which, ["opencode"], { encoding: "utf8", timeout: 10_000 }).trim().split(/\r?\n/)[0];
+    const version = execFileSync(pathResult, ["--version"], { encoding: "utf8", timeout: 10_000 }).trim();
+    return { found: true, path: pathResult, version };
+  } catch {
+    return { found: false, path: "", version: "" };
+  }
+}
+function sessionScopeMatches(sessionDir, opts) {
+  if (opts.scope !== "project") return true;
+  return path.resolve(sessionDir) === path.resolve(opts.projectCwd || process.cwd());
+}
+function firstString(...values) {
+  for (const value of values) {
+    if (typeof value === "string" && value.trim()) return value.trim();
+  }
+  return "";
+}
+export async function listSessions(opts = {}) {
+  const installation = probeOpenCode(opts);
+  if (!installation?.found) return [];
+  if (!isSupportedOpenCodeVersion(installation.version)) {
+    return [];
+  }
+  const listed = await Promise.resolve(defaultRunList(opts));
+  const rows = Array.isArray(listed) ? listed : (listed?.sessions || listed?.data);
+  if (!Array.isArray(rows)) {
+    throw new Error("invalid OpenCode session list shape: expected an array");
+  }
+  const out = [];
+  for (const row of rows) {
+    if (!row || typeof row !== "object") continue;
+    const sessionId = firstString(row.id, row.sessionID, row.sessionId);
+    if (!sessionId) continue;
+    const cwd = firstString(row.directory, row.cwd, row.projectPath);
+    if (!cwd || !sessionScopeMatches(cwd, opts)) continue;
+    const mtimeMs = timestampMs(row.updated, row.updatedAt, row.time?.updated);
+    out.push({
+      sessionUuid: sessionId,
+      path: sessionId,
+      cwd,
+      agentId: agentIdForOpenCode(cwd, { historical: true }),
+      mtimeMs,
+      likelyInProgress: mtimeMs > Date.now() - 60_000,
+      parentSessionId: firstString(row.parentID, row.parentId) || null,
+    });
+  }
+  return out;
+}
+function timestampMs(...values) {
+  for (const value of values) {
+    if (typeof value === "number" && Number.isFinite(value)) return value;
+    if (typeof value === "string" && value.trim()) {
+      const parsed = Date.parse(value);
+      if (Number.isFinite(parsed)) return parsed;
+    }
+  }
+  return 0;
+}
+export async function parseSession(ref, opts = {}) {
+  let exportShape = ref.exportData;
+  if (!exportShape) {
+    exportShape = await Promise.resolve(defaultRunExport(ref.sessionUuid || ref.path, opts));
+  }
+  const normalized = normalizeOpenCodeSession(exportShape, {
+    terminalError: Boolean(ref.terminalError),
+    interrupted: Boolean(ref.interrupted),
+  });
+  return {
+    sessionUuid: normalized.sessionId,
+    firstUserText: normalized.firstUserText,
+    startedAt: normalized.startedAt,
+    exchanges: normalized.exchanges.map((ex) => ({
+      user_uuid: ex.userId,
+      input: ex.input,
+      output: ex.output,
+      reasoning: "",
+      timestamp: ex.timestamp,
+      interrupted: ex.interrupted,
+    })),
+    partial: Boolean(normalized.partial),
+    parentSessionId: normalized.parentSessionId,
+    cwd: normalized.cwd,
+  };
+}

package/lib/migrate/claude-parser.mjs

@@ -5,8 +5,12 @@
  *   - no CLI / side effects; only exports
  *   - streaming via readline so sessions larger than available RAM
  *     don't need to be loaded whole
- *   - filters isSidechain / isMeta / attachment-type entries up front
- *     (the hook-side version doesn't need to because it runs live)
+ *   - filters isSidechain / attachment-type entries up front, and drops
+ *     `isMeta` entries other than skill context and subagent hand-backs
+ *   - folds skill bodies, task notifications and subagent hand-backs into
+ *     the turn they belong to, with the same rules as capture.js
+ *     (MEKO-710). The whole session is parsed at once, so there is no parse
+ *     window; a session still being written holds its trailing turn.
  *
  * Kept deliberately independent of `skills/hooks-handlers/lib/capture.js`:
  * installer packages ship without that sibling directory, and mixing
@@ -15,6 +19,7 @@
  */
 
 import fs from "node:fs";
+import path from "node:path";
 import readline from "node:readline";
 
 export const MAX_THINKING_LEN = Number(process.env.MEKO_MAX_THINKING_LEN ?? 2000);
@@ -24,6 +29,8 @@ export const MAX_TOOL_RESULT_LEN = Number(process.env.MEKO_MAX_TOOL_RESULT_LEN ?
 const SKIP_INPUT_PATTERN =
   /^<(system-reminder|command-|local-command|available-deferred)/;
 
+const SKILL_BODY_PATTERN = /^Base directory for this skill: *(\S+)/;
+
 export function truncate(str, max) {
   if (!str || str.length <= max) return str;
   return str.slice(0, max) + "... [truncated]";
@@ -104,6 +111,84 @@ export function extractToolResultContent(msg) {
   return "TOOL RESULT:\n" + parts.join("\n---\n");
 }
 
+/**
+ * Render a Claude Code skill or prompt command entry as the command the user
+ * typed (`/commit fix typo`). Only the `<command-message>`-led shape loads a
+ * skill; built-in commands lead with `<command-name>` and return "".
+ * Mirrors skillCommandInput in capture.js.
+ */
+export function skillCommandInput(text) {
+  if (typeof text !== "string" || !/^<command-message>/.test(text)) return "";
+  const name = /<command-name>([\s\S]*?)<\/command-name>/.exec(text);
+  if (!name) return "";
+  const args = /<command-args>([\s\S]*?)<\/command-args>/.exec(text);
+  return [name[1].trim(), args ? args[1].trim() : ""].filter(Boolean).join(" ");
+}
+
+/** Is this a background-task or subagent notification? Mirrors capture.js. */
+export function isTaskNotification(obj) {
+  if (obj?.type !== "user" || isToolResultMessage(obj)) return false;
+  if (obj.origin && obj.origin.kind === "task-notification") return true;
+  return /^\s*<task-notification>/.test(extractText(obj.message?.content));
+}
+
+/**
+ * Is this a subagent's hand-back report? Claude Code writes it as an
+ * `isMeta` entry tagged `origin: { kind: "peer", handback: true }`. Other
+ * peer messages are requests from another session. Mirrors capture.js.
+ */
+export function isSubagentHandback(obj) {
+  if (obj?.type !== "user" || isToolResultMessage(obj)) return false;
+  return obj.origin?.kind === "peer" && obj.origin.handback === true;
+}
+
+function handbackInput(obj) {
+  const name = obj.origin?.name || obj.origin?.from || "";
+  return name ? `Agent message: ${name}` : "Agent message";
+}
+
+/**
+ * Is this an `isMeta` entry Claude Code injected while loading a skill? The
+ * model-invoked shape carries `sourceToolUseID`; a typed `/skill` body starts
+ * with "Base directory for this skill:". Mirrors capture.js.
+ */
+export function isSkillContext(obj) {
+  if (obj?.type !== "user" || obj.isMeta !== true) return false;
+  if (isToolResultMessage(obj)) return false;
+  if (obj.sourceToolUseID) return true;
+  return SKILL_BODY_PATTERN.test(extractText(obj.message?.content));
+}
+
+function taskNotificationInput(text) {
+  const summary = /<summary>([\s\S]*?)<\/summary>/.exec(text || "");
+  return `Task notification: ${summary ? summary[1].trim() : "background task update"}`;
+}
+
+function skillContextInput(text) {
+  const dir = SKILL_BODY_PATTERN.exec(text || "");
+  const name = dir ? path.basename(dir[1].replace(/\/+$/, "")) : "";
+  return name ? `Skill loaded: ${name}` : "Skill context loaded";
+}
+
+/**
+ * The rendered input for a turn. A typed skill command that got its body is
+ * unwrapped to `/name args`; a turn opened by injected context gets a one-line
+ * summary so that context is never sent as user input.
+ */
+function turnInput(turn) {
+  const text = extractText(turn.userMsg.message?.content);
+  if (isTaskNotification(turn.userMsg)) return taskNotificationInput(text);
+  if (isSubagentHandback(turn.userMsg)) return handbackInput(turn.userMsg);
+  if (isSkillContext(turn.userMsg)) return skillContextInput(text);
+  return turn.injectedEntries.some((e) => e.isMeta === true && !isSubagentHandback(e))
+    ? skillCommandInput(text) || text
+    : text;
+}
+
+function isCapturableInput(input) {
+  return !!input && !SKIP_INPUT_PATTERN.test(input);
+}
+
 /**
  * Should this JSON entry be dropped before we start pairing turns?
  * Mirrors the plan: skip sidechains, meta turns, and the non-message types.
@@ -177,6 +262,10 @@ export async function parseSessionStream(sessionPath) {
   // Turn-assembly state.
   const exchanges = [];
   let current = null;
+  // The last entry kept for turn assembly, and whether consecutive injected
+  // isMeta entries are still arriving after a skill command or Skill call.
+  let prev = null;
+  let insideInjectedRun = false;
 
   for await (const raw of rl) {
     const line = raw.trim();
@@ -191,28 +280,63 @@ export async function parseSessionStream(sessionPath) {
     if (!cwd && typeof obj.cwd === "string") cwd = obj.cwd;
     if (!gitBranch && typeof obj.gitBranch === "string") gitBranch = obj.gitBranch;
     if (!startedAt && typeof obj.timestamp === "string") startedAt = obj.timestamp;
-    if (!firstUserText && obj.type === "user" && !isSkippable(obj) && !isToolResultMessage(obj)) {
+    if (!firstUserText && obj.type === "user" && !isSkippable(obj) && !isToolResultMessage(obj) && !isTaskNotification(obj)) {
       const txt = extractText(obj.message?.content);
       if (txt && !SKIP_INPUT_PATTERN.test(txt)) firstUserText = txt.slice(0, 240);
     }
 
-    if (isSkippable(obj)) continue;
+    // Skill context and hand-backs are isMeta but belong to their turn, so
+    // test them before isSkippable drops every other isMeta entry. A
+    // hand-back is never skill context, even if it carries sourceToolUseID.
+    const handback = isSubagentHandback(obj) && obj.isSidechain !== true;
+    const skillContext =
+      !handback && isSkillContext(obj) && obj.isSidechain !== true;
+    if (!skillContext && !handback && isSkippable(obj)) continue;
+
+    const isUserText = obj.type === "user" && !isToolResultMessage(obj);
+    let foldIntoCurrent = false;
+    if (isUserText && current) {
+      if (skillContext) {
+        const prevIsSkillCommand =
+          prev?.type === "user" &&
+          skillCommandInput(extractText(prev.message?.content)) !== "";
+        foldIntoCurrent =
+          !!obj.sourceToolUseID || insideInjectedRun || prevIsSkillCommand;
+      } else if (isTaskNotification(obj) || handback) {
+        // Folding into a turn that is never captured (a `/compact` or
+        // `<local-command-…>` turn) would drop the reply with it.
+        foldIntoCurrent = isCapturableInput(turnInput(current));
+      }
+    }
+    insideInjectedRun = skillContext && (!!obj.sourceToolUseID || foldIntoCurrent);
 
-    if (obj.type === "user" && !isToolResultMessage(obj)) {
+    if (isUserText && !foldIntoCurrent) {
       if (current) {
         const built = buildExchange(current);
         if (built) exchanges.push(built);
       }
-      current = { userMsg: obj, assistantEntries: [], toolResultEntries: [] };
+      current = {
+        userMsg: obj,
+        assistantEntries: [],
+        toolResultEntries: [],
+        injectedEntries: [],
+      };
     } else if (current) {
       if (obj.type === "assistant") {
         current.assistantEntries.push(obj);
       } else if (obj.type === "user" && isToolResultMessage(obj)) {
         current.toolResultEntries.push(obj);
+      } else if (isUserText) {
+        current.injectedEntries.push(obj);
       }
     }
+    prev = obj;
   }
-  if (current) {
+  // A session still being written can get more entries for its trailing
+  // turn, such as a task notification and its reply. Hold that turn, like
+  // the Codex adapter does: if it were sent now, resume would skip it on the
+  // next run and the new entries would never be migrated.
+  if (current && !partial) {
     const built = buildExchange(current);
     if (built) exchanges.push(built);
   }
@@ -236,8 +360,8 @@ function baseName(p) {
 }
 
 function buildExchange(ex) {
-  const input = extractText(ex.userMsg.message?.content);
-  if (!input || SKIP_INPUT_PATTERN.test(input)) return null;
+  const input = turnInput(ex);
+  if (!isCapturableInput(input)) return null;
   if (ex.assistantEntries.length === 0) return null;
 
   const outputParts = [];
@@ -257,9 +381,29 @@ function buildExchange(ex) {
     const trText = extractToolResultContent(tr);
     if (trText) reasoningParts.push(trText);
   }
+  const anchoredOnInjection =
+    isTaskNotification(ex.userMsg) || isSubagentHandback(ex.userMsg) || isSkillContext(ex.userMsg);
+  const injected = anchoredOnInjection
+    ? [ex.userMsg, ...ex.injectedEntries]
+    : ex.injectedEntries;
+  for (const inj of injected) {
+    const text = extractText(inj.message?.content);
+    if (text) {
+      const label = isTaskNotification(inj)
+        ? "TASK NOTIFICATION:\n"
+        : isSubagentHandback(inj)
+          ? "AGENT MESSAGE:\n"
+          : "INJECTED CONTEXT:\n";
+      reasoningParts.push(label + truncate(text, MAX_TOOL_RESULT_LEN));
+    }
+  }
 
   return {
     user_uuid: ex.userMsg.uuid || "unknown",
+    // Uuids of the injected entries folded into this turn. Older migrator
+    // versions sent a task notification as its own exchange, so a resume
+    // cursor saved by them can name one of these.
+    folded_uuids: ex.injectedEntries.map((e) => e.uuid).filter(Boolean),
     input,
     output: outputParts.join("\n\n"),
     reasoning: reasoningParts.join("\n---\n"),

package/lib/migrate/id.mjs

@@ -3,6 +3,8 @@
  */
 
 import { createHash } from "node:crypto";
+import fs from "node:fs";
+import os from "node:os";
 import path from "node:path";
 
 /**
@@ -44,7 +46,7 @@ export const COMMON_BUCKET_AGENT_ID = "meko_agent";
 
 const AGENT_ID_MAX_LEN = 64;
 const KNOWN_LOOSE_CLIENTS = new Set(["claude-desktop", "claude_desktop"]);
-const KNOWN_CODING_CLIENTS = new Set(["claude_code", "cursor"]);
+const KNOWN_CODING_CLIENTS = new Set(["claude_code", "cursor", "codex", "kiro", "opencode"]);
 
 /**
  * Sanitize a project segment: lowercase, collapse non-`[a-z0-9-]` to `-`,
@@ -61,21 +63,125 @@ function sanitizeProjectSegment(segment) {
   return collapsed.slice(0, AGENT_ID_MAX_LEN);
 }
 
+/**
+ * The user's home directory, read fresh so tests (and shells that re-point
+ * `$HOME`) see the current value rather than a module-load snapshot.
+ *
+ * @returns {string|null}
+ */
+function homeBoundary() {
+  const fromEnv = (process.env.HOME || "").trim();
+  if (fromEnv) return path.resolve(fromEnv);
+  try {
+    const h = os.homedir();
+    return h ? path.resolve(h) : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Walk parents of `cwd` looking for a `.git` entry (directory for a normal
+ * checkout, file for a submodule or linked worktree). Returns the absolute
+ * repo-root path, or `null` if none is found.
+ *
+ * The walk stops at `$HOME`: a directory under home that is not itself in a
+ * repo must NOT inherit home's repo-ness. Users who keep dotfiles under git
+ * would otherwise see every scratch directory collapse into
+ * `claude_code:<username>` — the same cross-project merge MEKO-590 exists to
+ * prevent, one level up. `$HOME` itself is still a valid repo root, so a
+ * session run directly in a git-tracked home resolves normally.
+ *
+ * Sync + best-effort: any I/O error at a level just skips that level. The
+ * caller treats `null` as "outside a repo" and falls back to the bare client
+ * name, per the MEKO-590 contract.
+ *
+ * @param {string} [cwd]
+ * @returns {string|null}
+ */
+export function resolveRepoRoot(cwd) {
+  if (!cwd || typeof cwd !== "string") return null;
+  let dir;
+  try {
+    dir = path.resolve(cwd);
+  } catch {
+    return null;
+  }
+  const start = dir;
+  const home = homeBoundary();
+  let prev = null;
+  while (dir && dir !== prev) {
+    // A directory below a git-tracked home must not inherit home's `.git`.
+    if (home && dir === home && dir !== start) return null;
+    try {
+      fs.statSync(path.join(dir, ".git"));
+      return dir;
+    } catch {
+      // no .git here; keep walking
+    }
+    // Check home itself for `.git`, then stop. This lets a git-tracked home
+    // resolve as a repo root without allowing a non-git home to inherit a
+    // `.git` from /Users, /home, or /.
+    if (home && dir === home) return null;
+    prev = dir;
+    dir = path.dirname(dir);
+  }
+  return null;
+}
+
+/**
+ * Repo root for a cwd that is HISTORICAL rather than live — a path recorded
+ * in an old transcript, or reverse-derived from a `~/.claude/projects/<slug>`
+ * directory name. Such a path may no longer exist (repo deleted, moved, or
+ * renamed) while its transcripts survive, so a filesystem walk is not a
+ * usable oracle.
+ *
+ * Walks first, so a repo still on disk gets the correct root. When the walk
+ * finds nothing, treats the recorded path's own basename as the project
+ * segment instead of reporting "outside a repo". That keeps each historical
+ * project in its own bucket: collapsing them all into a bare `claude_code`
+ * would re-create, inside the migrator, exactly the cross-repo merge
+ * MEKO-590 fixes in the hook.
+ *
+ * @param {string} [cwd]
+ * @returns {string|null}
+ */
+export function repoRootForHistoricalCwd(cwd) {
+  if (!cwd || typeof cwd !== "string") return null;
+  const live = resolveRepoRoot(cwd);
+  if (live) return live;
+  try {
+    return path.resolve(cwd);
+  } catch {
+    return null;
+  }
+}
+
 /**
  * Derive an `agent_id` for a Meko write.
  *
- * Contract:
+ * Contract (MEKO-590):
  *   - `envOverride` (typically `MEKO_AGENT_ID`) wins if non-empty.
  *   - Loose clients (Claude Desktop) → bare `claude_desktop`; no schema.
- *   - Coding clients (Claude Code, Cursor) → `<client>:<repo-basename>`.
- *     Outside a repo (basename is empty/`.`/`/`) → bare client name to
- *     keep coding-agent traffic out of the common bucket.
+ *   - Coding clients (Claude Code, Cursor, Codex, Kiro, OpenCode) →
+ *     `<client>:<repo-basename>`, resolved by walking parents of `cwd`
+ *     for a `.git` entry. The basename is lowercased and non-`[a-z0-9-]`
+ *     runs collapse to `-`. Outside a repo (no `.git` in any ancestor,
+ *     or basename sanitizes to empty) → bare client name, so sibling
+ *     directories named `docs` / `webapp` / `src` across unrelated repos
+ *     cannot silently collapse into one agent_id.
  *   - Anything else → `meko_agent` (the common cross-project bucket).
  *
+ * The `repoRoot` opt lets callers bypass the filesystem walk when they
+ * already know the repo root (or, for Cursor's flat project-name model,
+ * want to treat a supplied name as the basename directly). Passing
+ * `repoRoot: null` explicitly is an assertion of "outside a repo".
+ *
  * @param {object} opts
- * @param {string} [opts.client]       e.g. "claude_code", "cursor", "claude-desktop"
+ * @param {string} [opts.client]       e.g. "claude_code", "cursor", "codex", "kiro", "claude-desktop"
  * @param {string} [opts.cwd]          Absolute working directory, for coding clients
  * @param {string} [opts.envOverride]  Raw value of `MEKO_AGENT_ID`, if set
+ * @param {string|null} [opts.repoRoot] Pre-resolved repo root; bypasses the FS walk when set
  * @returns {string}
  */
 export function deriveAgentId(opts = {}) {
@@ -86,13 +192,45 @@ export function deriveAgentId(opts = {}) {
   if (KNOWN_LOOSE_CLIENTS.has(client)) return "claude_desktop";
   if (!KNOWN_CODING_CLIENTS.has(client)) return COMMON_BUCKET_AGENT_ID;
 
-  const rawBase = opts.cwd ? path.basename(opts.cwd) : "";
-  if (!rawBase || rawBase === "." || rawBase === "/") return client;
-  const project = sanitizeProjectSegment(rawBase);
+  const repoRoot = Object.prototype.hasOwnProperty.call(opts, "repoRoot")
+    ? opts.repoRoot
+    : resolveRepoRoot(opts.cwd);
+  if (!repoRoot) return client;
+  const project = sanitizeProjectSegment(path.basename(repoRoot));
   if (!project) return client;
   return `${client}:${project}`;
 }
 
+/**
+ * Derive the coding-agent id used before MEKO-590: from the cwd's leaf
+ * basename without a repo-root walk. Persisted migrator state and datapack
+ * pin filenames may still use this value, so callers use it as a compatibility
+ * alias while new sessions use `deriveAgentId`.
+ *
+ * @param {object} opts
+ * @param {string} [opts.client]
+ * @param {string} [opts.cwd]
+ * @param {string} [opts.envOverride]
+ * @returns {string}
+ */
+export function deriveLegacyAgentId(opts = {}) {
+  const override = (opts.envOverride ?? "").trim();
+  if (override) return override;
+
+  const client = (opts.client ?? "").trim();
+  if (KNOWN_LOOSE_CLIENTS.has(client)) return "claude_desktop";
+  if (!KNOWN_CODING_CLIENTS.has(client)) return COMMON_BUCKET_AGENT_ID;
+
+  let rawBase = "";
+  try {
+    rawBase = opts.cwd ? path.basename(opts.cwd) : "";
+  } catch {
+    return client;
+  }
+  const project = sanitizeProjectSegment(rawBase);
+  return project ? `${client}:${project}` : client;
+}
+
 /**
  * Back-compat alias. New code should call `deriveAgentId(...)`.
  */
@@ -101,14 +239,23 @@ export const AGENT_ID = COMMON_BUCKET_AGENT_ID;
 /**
  * @param {string} [cwd] Absolute project cwd. Required for project-scope
  *   writes; omit for user-scope writes (returns the common bucket).
+ *
+ * Pass `{ historical: true }` when `cwd` came from a recorded transcript or
+ * a reverse-slugged project directory rather than the live process. The repo
+ * root is then resolved via `repoRootForHistoricalCwd`, which falls back to
+ * the recorded basename when the path no longer exists on disk, so projects
+ * whose repos were deleted or moved keep distinct buckets.
+ * @param {object} [opts]
+ * @param {boolean} [opts.historical] Treat `cwd` as a recorded path.
  * @returns {string}
  */
-export function agentIdForClaude(cwd) {
+export function agentIdForClaude(cwd, opts = {}) {
   if (!cwd) return COMMON_BUCKET_AGENT_ID;
   return deriveAgentId({
     client: "claude_code",
     cwd,
     envOverride: process.env.MEKO_AGENT_ID,
+    ...(opts.historical ? { repoRoot: repoRootForHistoricalCwd(cwd) } : {}),
   });
 }
 
@@ -122,14 +269,74 @@ export const CLAUDE_CODE_USER_AGENT_ID = COMMON_BUCKET_AGENT_ID;
 /**
  * @param {string} [cwd] Absolute project cwd (or basename — Cursor's projects
  *   live under a flat `~/.cursor/projects/<name>/`). Omit for user-scope.
+ *
+ * Cursor's persisted transcripts store a flat project name rather than a
+ * full absolute cwd, so we treat the supplied value as the repo basename
+ * directly (via `repoRoot`) instead of walking the filesystem for a `.git`
+ * that isn't there.
+ *
  * @returns {string}
  */
 export function agentIdForCursor(cwd) {
   if (!cwd) return COMMON_BUCKET_AGENT_ID;
   return deriveAgentId({
     client: "cursor",
+    repoRoot: cwd,
+    envOverride: process.env.MEKO_AGENT_ID,
+  });
+}
+
+/**
+ * @param {string} [cwd] Absolute project cwd of the Codex session (from the
+ *   rollout's `session_meta.payload.cwd`). Omit for user-scope writes
+ *   (returns the common bucket).
+ *
+ * Pass `{ historical: true }` when `cwd` came from a recorded transcript or
+ * a reverse-slugged project directory rather than the live process. The repo
+ * root is then resolved via `repoRootForHistoricalCwd`, which falls back to
+ * the recorded basename when the path no longer exists on disk, so projects
+ * whose repos were deleted or moved keep distinct buckets.
+ * @param {object} [opts]
+ * @param {boolean} [opts.historical] Treat `cwd` as a recorded path.
+ * @returns {string}
+ */
+export function agentIdForCodex(cwd, opts = {}) {
+  if (!cwd) return COMMON_BUCKET_AGENT_ID;
+  return deriveAgentId({
+    client: "codex",
+    cwd,
+    envOverride: process.env.MEKO_AGENT_ID,
+    ...(opts.historical ? { repoRoot: repoRootForHistoricalCwd(cwd) } : {}),
+  });
+}
+
+/**
+ * Derive the project-scoped owner used by Kiro hook capture.
+ *
+ * Pass `{ historical: true }` when `cwd` came from a recorded transcript or
+ * a reverse-slugged project directory rather than the live process. The repo
+ * root is then resolved via `repoRootForHistoricalCwd`, which falls back to
+ * the recorded basename when the path no longer exists on disk, so projects
+ * whose repos were deleted or moved keep distinct buckets.
+ */
+export function agentIdForKiro(cwd, opts = {}) {
+  if (!cwd) return COMMON_BUCKET_AGENT_ID;
+  return deriveAgentId({
+    client: "kiro",
+    cwd,
+    envOverride: process.env.MEKO_AGENT_ID,
+    ...(opts.historical ? { repoRoot: repoRootForHistoricalCwd(cwd) } : {}),
+  });
+}
+
+/** Derive the project-scoped owner used by OpenCode capture and migration. */
+export function agentIdForOpenCode(cwd, opts = {}) {
+  if (!cwd) return COMMON_BUCKET_AGENT_ID;
+  return deriveAgentId({
+    client: "opencode",
     cwd,
     envOverride: process.env.MEKO_AGENT_ID,
+    ...(opts.historical ? { repoRoot: repoRootForHistoricalCwd(cwd) } : {}),
   });
 }