@lh8ppl/claude-memory-kit 0.3.5 → 0.4.0

package/src/kiro-permissions.mjs

@@ -0,0 +1,175 @@
+// kiro-permissions.mjs — write Kiro IDE 1.0's authoritative trust store so the
+// kit's surfaces run prompt-free (Task 50.N.5 / D-203h/D-203i).
+//
+// On Kiro IDE 1.0, the LIVE trust is `~/.kiro/workspace-roots/<hash>/
+// permissions.yaml` (capability/match/effect), NOT `.vscode/settings.json` — Kiro
+// auto-MIGRATES the latter into the former at first open (D-203i: proven by the
+// `.trust-migration.json` sibling + MCP running prompt-free with no `.vscode`
+// trustedMcpTools). There is NO `.vscode` setting for SKILL trust, so the only
+// reliable pre-trust for the memory-write skill-load prompt is to write
+// permissions.yaml directly.
+//
+// <hash> = sha256( projectRoot, normalized: forward-slash + no-trailing-slash +
+// lowercase ).hexdigest().slice(0,16) — VERIFIED on a real install (D-203h:
+// c:/temp/kiro-ide-gate → a7ffdb64ec4c31c8).
+//
+// Format (ground-truth, read from a real grant — D-203h):
+//   rules:
+//     - { capability: shell, match: [cmd.exe /c cmk hook *, ...], effect: allow }
+//     - { capability: mcp,   match: [claude-memory-kit/mk_remember, ...], effect: allow }
+//     - { capability: skill, match: [memory-write, memory-search], effect: allow }
+//
+// Public surface:
+//   kiroWorkspaceHash(projectRoot) → string (the 16-hex workspace key)
+//   installKiroPermissions({ projectRoot, env? }) → { action, changed, path }
+//   uninstallKiroPermissions({ projectRoot, env? }) → { action, changed }
+//
+// Managed-merge: we own ONLY the rules whose capability+match are ours (matched
+// by the kit's known tokens); a user's own rules are byte-preserved on install +
+// uninstall (the over-mutation discipline).
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join, dirname, resolve } from 'node:path';
+import { createHash } from 'node:crypto';
+import yaml from 'js-yaml';
+
+import { MCP_AUTO_APPROVE } from './kiro-constants.mjs';
+
+// The kit's MCP tools, namespaced as Kiro's permissions.yaml lists them
+// (server/tool). MCP_AUTO_APPROVE is the shared source of the 11 tool names
+// (also used for the IDE's mcp.json autoApprove), so the two never drift.
+const MCP_MATCH = MCP_AUTO_APPROVE.map((t) => `claude-memory-kit/${t}`);
+const SHELL_MATCH = Object.freeze(['cmd.exe /c cmk hook *', 'cmd.exe /c cmk-guard-memory*']);
+const SKILL_MATCH = Object.freeze(['memory-write', 'memory-search']);
+
+// The kit's owned MATCH ENTRIES, per capability+effect. Ownership is PER-ENTRY
+// (not per-rule): Kiro stores ONE rule per (capability, effect) with a combined
+// `match` array, so a user can co-locate their own match in the SAME rule as ours.
+// We add/remove only OUR entries and never drop a co-located user entry (the
+// over-mutation discipline — mirrors kiro-trusted-commands.mjs's per-entry filter,
+// skill-review B1).
+const OUR_MATCHES = Object.freeze({
+  shell: SHELL_MATCH,
+  mcp: MCP_MATCH,
+  skill: SKILL_MATCH,
+});
+function isOurMatch(capability, entry) {
+  const owned = OUR_MATCHES[capability];
+  return Array.isArray(owned) && owned.includes(entry);
+}
+
+// Merge our match entries into an existing rules array, PER-ENTRY + PER-(capability,
+// effect:allow) rule. Preserves the user's rules + their co-located match entries;
+// adds only the missing OUR entries; keeps rule order stable (in-place, no float).
+function withOurRules(existing) {
+  // clone so we never mutate the parsed input
+  const rules = existing.map((r) => ({ ...r, match: Array.isArray(r.match) ? [...r.match] : r.match }));
+  for (const [capability, owned] of Object.entries(OUR_MATCHES)) {
+    // find the existing allow-rule for this capability (Kiro's convention: one per cap)
+    let rule = rules.find((r) => r && r.capability === capability && r.effect === 'allow' && Array.isArray(r.match));
+    if (!rule) {
+      rule = { capability, match: [], effect: 'allow' };
+      rules.push(rule);
+    }
+    for (const m of owned) if (!rule.match.includes(m)) rule.match.push(m);
+  }
+  return rules;
+}
+
+// Remove our match entries PER-ENTRY; drop a rule only if its match becomes empty
+// AND it was an allow-rule for a capability we own (never delete a user's rule).
+function withoutOurRules(existing) {
+  const out = [];
+  let changed = false;
+  for (const r of existing) {
+    if (!r || r.capability == null || r.effect !== 'allow' || !Array.isArray(r.match) || !OUR_MATCHES[r.capability]) {
+      out.push(r); // not a rule we touch
+      continue;
+    }
+    const kept = r.match.filter((m) => !isOurMatch(r.capability, m));
+    if (kept.length !== r.match.length) changed = true;
+    if (kept.length > 0) out.push({ ...r, match: kept }); // user entries survive
+    // else: the rule was ours-only → drop it
+  }
+  return { rules: out, changed };
+}
+
+/**
+ * Kiro IDE 1.0's workspace-roots hash for a project path.
+ * sha256(forward-slash + no-trailing-slash + lowercase).slice(0,16). (D-203h)
+ */
+export function kiroWorkspaceHash(projectRoot) {
+  // resolve() a RELATIVE input to absolute (defense — Kiro keys on the absolute
+  // workspace root; a relative path would hash to a dir Kiro never reads, review
+  // M1). An ALREADY-absolute path (drive-letter `C:\…` or POSIX `/…`) is passed
+  // through verbatim — so a Windows path stays correct even when this runs on a
+  // POSIX CI (resolve() there would wrongly prepend cwd to `c:/…`). NOTE: only
+  // ordinary drive-letter paths are ground-truth-verified (D-203h); UNC/extended-
+  // length are untested.
+  const p = String(projectRoot);
+  const isAbsolute = /^[a-zA-Z]:[\\/]/.test(p) || /^[\\/]/.test(p);
+  const abs = isAbsolute ? p : resolve(p);
+  const norm = abs.replace(/\\/g, '/').replace(/\/+$/, '').toLowerCase();
+  return createHash('sha256').update(norm).digest('hex').slice(0, 16);
+}
+
+function permissionsPath(projectRoot, env) {
+  const home = env.USERPROFILE || env.HOME || homedir();
+  return join(home, '.kiro', 'workspace-roots', kiroWorkspaceHash(projectRoot), 'permissions.yaml');
+}
+
+// Parse an existing permissions.yaml → its rules array. A missing file → []. A
+// MALFORMED file → { malformed: true } so the caller REFUSES to overwrite it
+// (mirrors kiro-trusted-commands' don't-clobber-a-corrupt-file posture, review
+// M3 — this writes to the user's HOME; never destroy content we couldn't parse).
+function readRules(path) {
+  if (!existsSync(path)) return { rules: [], existed: false };
+  let parsed;
+  try {
+    parsed = yaml.load(readFileSync(path, 'utf8'));
+  } catch {
+    return { rules: [], existed: true, malformed: true };
+  }
+  // a parse that yields a non-object (e.g. a stray scalar) is also unsafe to clobber.
+  if (parsed != null && typeof parsed !== 'object') return { rules: [], existed: true, malformed: true };
+  const rules = parsed && Array.isArray(parsed.rules) ? parsed.rules : [];
+  return { rules, existed: true };
+}
+
+function serialize(rules) {
+  // js-yaml dump; flow-style for the compact match arrays Kiro uses is optional —
+  // block style is equally valid YAML and is what Kiro itself wrote.
+  return yaml.dump({ rules }, { lineWidth: -1, noRefs: true });
+}
+
+export function installKiroPermissions({ projectRoot, env = process.env } = {}) {
+  if (!projectRoot) throw new Error('installKiroPermissions: projectRoot is required');
+  const path = permissionsPath(projectRoot, env);
+  const { rules: existing, malformed } = readRules(path);
+  if (malformed) return { action: 'skipped', changed: false, path, reason: 'malformed-permissions-yaml' };
+  const merged = withOurRules(existing); // per-entry merge — preserves order + user entries
+  const serialized = serialize(merged);
+
+  const prior = existsSync(path) ? readFileSync(path, 'utf8') : null;
+  let changed = false;
+  if (prior !== serialized) {
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, serialized, 'utf8');
+    changed = true;
+  }
+  return { action: 'installed', changed, path };
+}
+
+export function uninstallKiroPermissions({ projectRoot, env = process.env } = {}) {
+  if (!projectRoot) throw new Error('uninstallKiroPermissions: projectRoot is required');
+  const path = permissionsPath(projectRoot, env);
+  if (!existsSync(path)) return { action: 'uninstalled', changed: false };
+  const { rules: existing } = readRules(path);
+  const { rules: kept, changed: removed } = withoutOurRules(existing); // per-entry removal
+  if (!removed) return { action: 'uninstalled', changed: false }; // none of ours present
+  // preserve the user's rules + co-located entries; write back without ours (never
+  // delete the file — it may hold the user's own + Kiro's migration data).
+  writeFileSync(path, serialize(kept), 'utf8');
+  return { action: 'uninstalled', changed: true };
+}

package/src/kiro-skills.mjs

@@ -0,0 +1,96 @@
+// kiro-skills.mjs — install the kit's memory skills into Kiro (Task 50.I, skills leg).
+//
+// Kiro's skill surface is Claude-Code-style <name>/SKILL.md with YAML frontmatter
+// (verified from real installs: .kiro/skills/<name>/SKILL.md project-tier,
+// ~/.kiro/skills/<name>/SKILL.md user-tier). The kit already ships memory-search
+// + memory-write as SKILL.md under template/.claude/skills/ — they port directly.
+// The only transform: drop the Claude-Code-specific frontmatter keys Kiro doesn't
+// honor (`context`, `allowed-tools`) while keeping `name` + `description` + the
+// instruction body. The cmk MCP tools the skills reference are wired by the MCP
+// leg, so the skill body works unchanged.
+//
+// Public surface:
+//   installKiroSkills({ projectRoot, templateDir? }) → { action, changed, skills }
+//   uninstallKiroSkills({ projectRoot }) → { action, changed, skills }
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync, rmSync } from 'node:fs';
+import { join } from 'node:path';
+import { resolveTemplateDir } from './install.mjs';
+
+// The kit skills that map to Kiro. (memory-search + memory-write — the two the
+// kit scaffolds for Claude Code.)
+const KIT_SKILLS = ['memory-search', 'memory-write'];
+
+// Frontmatter keys Kiro does NOT use — dropped on translation. Everything else
+// in the frontmatter (name, description) + the whole body is preserved.
+const DROP_KEYS = new Set(['context', 'allowed-tools']);
+
+export function installKiroSkills({ projectRoot, templateDir } = {}) {
+  if (!projectRoot) throw new Error('installKiroSkills: projectRoot is required');
+  const tpl = templateDir || resolveTemplateDir();
+  const skillsRoot = join(projectRoot, '.kiro', 'skills');
+
+  let changed = false;
+  const installed = [];
+  for (const name of KIT_SKILLS) {
+    const src = join(tpl, '.claude', 'skills', name, 'SKILL.md');
+    if (!existsSync(src)) continue; // skill not in this template — skip, don't fail
+    const translated = translateFrontmatter(readFileSync(src, 'utf8'));
+    const destDir = join(skillsRoot, name);
+    const dest = join(destDir, 'SKILL.md');
+
+    const existing = existsSync(dest) ? readFileSync(dest, 'utf8') : null;
+    if (existing !== translated) {
+      mkdirSync(destDir, { recursive: true });
+      writeFileSync(dest, translated, 'utf8');
+      changed = true;
+    }
+    installed.push(name);
+  }
+  return { action: 'installed', changed, skills: installed };
+}
+
+export function uninstallKiroSkills({ projectRoot } = {}) {
+  if (!projectRoot) throw new Error('uninstallKiroSkills: projectRoot is required');
+  const skillsRoot = join(projectRoot, '.kiro', 'skills');
+  let changed = false;
+  const removed = [];
+  for (const name of KIT_SKILLS) {
+    const dir = join(skillsRoot, name);
+    if (existsSync(dir)) {
+      rmSync(dir, { recursive: true, force: true });
+      changed = true;
+      removed.push(name);
+    }
+  }
+  return { action: 'uninstalled', changed, skills: removed };
+}
+
+// ── internal ─────────────────────────────────────────────────────────────────
+
+// Drop the Claude-Code-only frontmatter keys, keep the rest of the frontmatter +
+// the entire body. Operates on the leading `---` … `---` block only; the body is
+// byte-preserved. Multi-line values (e.g. a wrapped description) are kept whole —
+// a dropped key's continuation lines (indented) are dropped with it.
+function translateFrontmatter(content) {
+  const m = content.match(/^---\n([\s\S]*?)\n---\n([\s\S]*)$/);
+  if (!m) return content; // no frontmatter — pass through unchanged
+  const [, fm, body] = m;
+
+  const lines = fm.split('\n');
+  const kept = [];
+  let dropping = false;
+  for (const line of lines) {
+    const keyMatch = line.match(/^([A-Za-z0-9_-]+):/);
+    if (keyMatch) {
+      // a new top-level key — decide whether to drop it (+ its continuation)
+      dropping = DROP_KEYS.has(keyMatch[1]);
+      if (!dropping) kept.push(line);
+    } else if (!dropping) {
+      // continuation line of a kept key (indented / blank) — preserve
+      kept.push(line);
+    }
+    // else: continuation of a dropped key — skip
+  }
+  return `---\n${kept.join('\n')}\n---\n${body}`;
+}

package/src/kiro-transcript.mjs

@@ -0,0 +1,366 @@
+// kiro-transcript.mjs — the Kiro session-transcript adapter (Task 50.H).
+//
+// Resolves the D-180 "highest unverified risk": Kiro stores transcripts
+// differently from Claude Code, and the kit's capture path hardcoded the
+// Claude-Code touchpoints (~/.claude/projects/<slug>/<session>.jsonl, JSONL).
+// Verified on a REAL Kiro install (D-180): Kiro is a VS Code fork; per-session
+// JSON lives at
+//   %APPDATA%/Kiro/User/globalStorage/kiro.kiroagent/workspace-sessions/
+//     <base64url(workspacePath)>/<sessionId>.json
+// with a `history[]` of { message: { role, content: [{type:'text', text}] } }
+// plus a sibling `sessions.json` index.
+//
+// This module is the per-agent transcript adapter the cross-agent seam needs:
+// it turns Kiro's session JSON into the {role, text} turns the kit's capture
+// path consumes, and resolves the workspace→dir key. Pure + defensive — a
+// malformed/partial session returns [] rather than throwing (a capture hook
+// must never crash the agent).
+//
+// Public surface:
+//   parseKiroSessionHistory(jsonText) → [{role, text}]   (ordered turns, IDE schema)
+//   parseKiroCliSession(jsonText) → {assistantText}       (kiro-cli schema, D-199)
+//   readKiroCliTurn({projectRoot, env}) → {userText, assistantText}  (~/.kiro/sessions/cli)
+//   workspaceKeyForPath(workspacePath) → string          (the base64url dir key)
+//   parseKiroIdeV1Messages(jsonlText) → {userText, assistantText}  (IDE 1.0 messages.jsonl)
+//   readKiroIdeV1Turn({projectRoot, env}) → {userText, assistantText}  (~/.kiro/sessions/<hash>/sess_*)
+//   readKiroTurn({projectRoot, env}) → {userText, assistantText}  (IDE-0.x → CLI → IDE-1.0)
+
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+/**
+ * Parse a Kiro session JSON into ordered {role, text} turns.
+ * @param {string} jsonText raw contents of a <sessionId>.json file
+ * @returns {{role:string, text:string}[]}
+ */
+export function parseKiroSessionHistory(jsonText) {
+  let session;
+  try {
+    session = JSON.parse(jsonText);
+  } catch {
+    return [];
+  }
+  if (!session || !Array.isArray(session.history)) return [];
+
+  const turns = [];
+  for (const item of session.history) {
+    const msg = item && item.message;
+    if (!msg || typeof msg.role !== 'string') continue;
+    const text = extractText(msg.content);
+    if (text !== '') turns.push({ role: msg.role, text });
+  }
+  return turns;
+}
+
+/**
+ * Parse a kiro-cli session JSON into the latest assistant turn text.
+ *
+ * The kiro-CLI session schema is DIFFERENT from the IDE's (D-199 gate finding —
+ * primary-source verified on a real `~/.kiro/sessions/cli/<uuid>.json`): there is
+ * NO `history[]`. Instead the per-turn assistant text lives at
+ *   session_state.conversation_metadata.user_turn_metadatas[].result.Ok.content[].data
+ * (each content part is `{ kind, data }`, `kind === 'text'`). The user's prompt
+ * text is NOT stored verbatim (only `user_prompt_length`), so the CLI path yields
+ * the ASSISTANT text only — which is all captureTurn's extractTurnText needs.
+ *
+ * @param {string} jsonText raw contents of a kiro-cli <uuid>.json file
+ * @returns {{assistantText:string}}
+ */
+export function parseKiroCliSession(jsonText) {
+  let session;
+  try {
+    session = JSON.parse(jsonText);
+  } catch {
+    return { assistantText: '' };
+  }
+  const turns = session?.session_state?.conversation_metadata?.user_turn_metadatas;
+  if (!Array.isArray(turns) || turns.length === 0) return { assistantText: '' };
+
+  // the LAST turn is the most recent; read its assistant text from result.Ok.content[].
+  const last = turns[turns.length - 1];
+  const content = last?.result?.Ok?.content;
+  if (!Array.isArray(content)) return { assistantText: '' };
+  const assistantText = content
+    .filter((part) => part && part.kind === 'text' && typeof part.data === 'string')
+    .map((part) => part.data)
+    .join('\n');
+  return { assistantText };
+}
+
+/**
+ * Read the latest assistant turn from a kiro-CLI session for a project. The CLI
+ * stores sessions at ~/.kiro/sessions/cli/<uuid>.json, each carrying its own
+ * `cwd` + `updated_at`; we pick the most-recent file whose `cwd` matches the
+ * project root. Pure + defensive (a capture hook must never crash the session).
+ * @param {{projectRoot:string, env?:object}} args
+ * @returns {{userText:string, assistantText:string}}
+ */
+export function readKiroCliTurn({ projectRoot, env = process.env } = {}) {
+  const empty = { userText: '', assistantText: '' };
+  try {
+    if (!projectRoot) return empty;
+    const home = env.USERPROFILE || env.HOME || homedir();
+    const cliDir = join(home, '.kiro', 'sessions', 'cli');
+    if (!existsSync(cliDir)) return empty;
+
+    // Compare cwd by NORMALIZED separators + case, NOT path.resolve(): both
+    // projectRoot and json.cwd are already absolute, same-machine, same-form
+    // paths (the hook's cwd and the session's recorded cwd). resolve() would
+    // re-root a value against the current cwd if it ever looked relative — a real
+    // hazard. ASSUMPTION: both sides are absolute drive-letter or matching-form
+    // paths; an extended-length (\\?\) or `~` form on one side only won't match
+    // (a missed match → empty capture, never a crash). Full-string equality, not
+    // a prefix test — so `C:\Temp\proj` and `C:\Temp\proj-2` correctly differ.
+    const norm = (p) => p.replace(/[\\/]+/g, '/').replace(/\/+$/, '').toLowerCase();
+    const want = norm(projectRoot);
+    const files = readdirSync(cliDir).filter((f) => f.endsWith('.json'));
+    let best = null;
+    let bestStamp = null; // [epochMs, filename] for a deterministic tie-break
+    for (const f of files) {
+      let json;
+      try {
+        json = JSON.parse(readFileSync(join(cliDir, f), 'utf8'));
+      } catch {
+        continue;
+      }
+      if (!json?.cwd || norm(json.cwd) !== want) continue;
+      // Parse updated_at to epoch ms for a numeric compare — robust to ISO
+      // precision/offset drift (a future kiro-cli format change won't silently
+      // mis-order). Unparseable → 0, so the filename tie-break still orders it.
+      const epoch = Date.parse(json.updated_at) || 0;
+      const stamp = [epoch, f];
+      if (bestStamp === null || stamp[0] > bestStamp[0] || (stamp[0] === bestStamp[0] && stamp[1] > bestStamp[1])) {
+        bestStamp = stamp;
+        best = json;
+      }
+    }
+    if (!best) return empty;
+    const { assistantText } = parseKiroCliSession(JSON.stringify(best));
+    return { userText: '', assistantText };
+  } catch {
+    return empty;
+  }
+}
+
+/**
+ * Parse a Kiro IDE 1.0 messages.jsonl (D-203g) into the latest user + assistant
+ * text. IDE 1.0 moved session storage to ~/.kiro/sessions/<hash>/sess_<uuid>/ —
+ * a JSON-Lines `messages.jsonl`: one `{id, timestamp, payload:{type, content}}` per
+ * line; `payload.type ∈ {user, assistant, tool_call, tool_result, turn_start/end,
+ * ContextualHookInvoked, …}`; `payload.content` is the message text (string) for
+ * user/assistant. We take the LAST user + LAST assistant content. Primary-source
+ * verified on a real IDE-1.0 session.
+ * @param {string} jsonlText raw contents of a messages.jsonl
+ * @returns {{userText:string, assistantText:string}}
+ */
+export function parseKiroIdeV1Messages(jsonlText) {
+  const empty = { userText: '', assistantText: '' };
+  if (typeof jsonlText !== 'string') return empty;
+  let userText = '';
+  let assistantText = '';
+  for (const line of jsonlText.split('\n')) {
+    if (line.trim() === '') continue;
+    let msg;
+    try {
+      msg = JSON.parse(line);
+    } catch {
+      continue; // a malformed line never crashes the whole read
+    }
+    const type = msg?.payload?.type;
+    if (type !== 'user' && type !== 'assistant') continue;
+    const text = ideV1ContentText(msg?.payload?.content);
+    if (text === '') continue;
+    if (type === 'user') userText = text; // keep the LAST one
+    else assistantText = text;
+  }
+  return { userText, assistantText };
+}
+
+// IDE 1.0 payload.content is a STRING for plain messages (verified on a real
+// session), but a multi-part message (with images/documents) MAY serialize it as
+// an array of typed parts like IDE-0.x — so handle BOTH (review I1): a string is
+// returned as-is; an array joins the `text`-typed parts (the `{type:'text', text}`
+// shape, like extractText). Anything else → '' (drop, never crash). Defensive so a
+// multi-part assistant reply isn't silently dropped → capture-nothing recurrence.
+function ideV1ContentText(content) {
+  if (typeof content === 'string') return content;
+  if (Array.isArray(content)) {
+    return content
+      .filter((part) => part && part.type === 'text' && typeof part.text === 'string')
+      .map((part) => part.text)
+      .join('\n');
+  }
+  return '';
+}
+
+/**
+ * Read the latest turn from a Kiro IDE 1.0 session (D-203g). Scans
+ * ~/.kiro/sessions/<workspace-hash>/sess_<uuid>/, matching session.json's
+ * `workspacePaths` to projectRoot (no hash-reversing), picking the most-recently-
+ * modified messages.jsonl. Pure + defensive (a capture hook must never crash).
+ * @param {{projectRoot:string, env?:object}} args
+ * @returns {{userText:string, assistantText:string}}
+ */
+export function readKiroIdeV1Turn({ projectRoot, env = process.env } = {}) {
+  const empty = { userText: '', assistantText: '' };
+  try {
+    if (!projectRoot) return empty;
+    const home = env.USERPROFILE || env.HOME || homedir();
+    const sessionsRoot = join(home, '.kiro', 'sessions');
+    if (!existsSync(sessionsRoot)) return empty;
+
+    const norm = (p) => p.replace(/[\\/]+/g, '/').replace(/\/+$/, '').toLowerCase();
+    const want = norm(projectRoot);
+
+    // walk <hash>/sess_*/ dirs; match by session.json.workspacePaths; pick latest
+    // messages.jsonl by mtime, tie-broken by path (review M1 — mirror the CLI/0.x
+    // readers' deterministic [stamp, path] tie-break so an equal mtime isn't
+    // decided by readdir order).
+    let best = null; // [mtimeMs, messagesPath]
+    for (const hash of readdirSync(sessionsRoot)) {
+      const hashDir = join(sessionsRoot, hash);
+      let sessDirs;
+      try {
+        sessDirs = readdirSync(hashDir).filter((d) => d.startsWith('sess_'));
+      } catch {
+        // a non-directory entry at sessions/ root → readdirSync throws ENOTDIR;
+        // skip it. (The `cli/` sibling IS a dir but has no sess_* children, so it
+        // falls out of the filter below — both cases are handled, never crash.)
+        continue;
+      }
+      for (const sd of sessDirs) {
+        const dir = join(hashDir, sd);
+        const metaPath = join(dir, 'session.json');
+        const msgPath = join(dir, 'messages.jsonl');
+        if (!existsSync(metaPath) || !existsSync(msgPath)) continue;
+        let meta;
+        try {
+          meta = JSON.parse(readFileSync(metaPath, 'utf8'));
+        } catch {
+          continue;
+        }
+        const paths = Array.isArray(meta?.workspacePaths) ? meta.workspacePaths : [];
+        if (!paths.some((p) => typeof p === 'string' && norm(p) === want)) continue;
+        let mtimeMs = 0;
+        try {
+          mtimeMs = statSync(msgPath).mtimeMs;
+        } catch {
+          /* keep 0 */
+        }
+        if (
+          best === null ||
+          mtimeMs > best[0] ||
+          (mtimeMs === best[0] && msgPath > best[1]) // deterministic tie-break (M1)
+        ) {
+          best = [mtimeMs, msgPath];
+        }
+      }
+    }
+    if (!best) return empty;
+    return parseKiroIdeV1Messages(readFileSync(best[1], 'utf8'));
+  } catch {
+    return empty;
+  }
+}
+
+// Join the text of all text-type content parts; ignore tool/other blocks.
+// Kiro's content is always an array of typed parts (verified on a real install);
+// a non-array is treated as "no text" rather than guessed at.
+function extractText(content) {
+  if (!Array.isArray(content)) return '';
+  return content
+    .filter((part) => part && part.type === 'text' && typeof part.text === 'string')
+    .map((part) => part.text)
+    .join('\n');
+}
+
+/**
+ * Encode a workspace path to Kiro's workspace-sessions directory key.
+ * EXACT scheme verified on a real install: standard base64, then +→-, /→_, and
+ * the `=` padding → `_` (NOT stripped — Kiro keeps the padding as underscores).
+ * @param {string} workspacePath e.g. 'c:\\Projects\\demo'
+ * @returns {string}
+ */
+export function workspaceKeyForPath(workspacePath) {
+  return Buffer.from(workspacePath, 'utf8')
+    .toString('base64')
+    .replace(/\+/g, '-')
+    .replace(/\//g, '_')
+    .replace(/=/g, '_');
+}
+
+/**
+ * Read the latest user+assistant turn from Kiro's transcript for a project.
+ *
+ * Composes the verified pieces (probe P-CJYGTQYR + D-180):
+ *   - the globalStorage dir is given to the hook via env CONTINUE_GLOBAL_DIR
+ *     (= …/Kiro/User/globalStorage/kiro.kiroagent), so we don't guess the path;
+ *   - the per-project dir is workspace-sessions/<base64url(projectRoot)>;
+ *   - the most-recent <sessionId>.json (by dateCreated, else mtime) is the live
+ *     session; its history[] is parsed to the latest user + assistant text.
+ *
+ * Pure + defensive: any missing dir / absent env / parse error returns empty
+ * strings, never throws (a capture hook must never crash the Kiro session).
+ *
+ * @param {{projectRoot:string, env?:object}} args
+ * @returns {{userText:string, assistantText:string}}
+ */
+// The non-(IDE-0.x) fallback chain: kiro-CLI (~/.kiro/sessions/cli, D-199) → IDE
+// 1.0 (~/.kiro/sessions/<hash>/sess_*/messages.jsonl, D-203g). Tried when the
+// legacy IDE-0.x globalStorage path yields nothing. Returns the first non-empty.
+function readKiroFallbackTurn({ projectRoot, env }) {
+  const cli = readKiroCliTurn({ projectRoot, env });
+  if (cli.assistantText || cli.userText) return cli;
+  return readKiroIdeV1Turn({ projectRoot, env });
+}
+
+export function readKiroTurn({ projectRoot, env = process.env } = {}) {
+  const empty = { userText: '', assistantText: '' };
+  try {
+    const globalDir = env.CONTINUE_GLOBAL_DIR;
+    // No IDE-0.x globalStorage (the CLI/IDE-1.0 don't set CONTINUE_GLOBAL_DIR) →
+    // the fallback chain (kiro-CLI then IDE-1.0). The legacy IDE-0.x path stays
+    // PRIMARY when its env+dir are present, so an 0.x user is unaffected.
+    if (!globalDir || !projectRoot) return readKiroFallbackTurn({ projectRoot, env });
+    const wsDir = join(globalDir, 'workspace-sessions', workspaceKeyForPath(projectRoot));
+    if (!existsSync(wsDir)) return readKiroFallbackTurn({ projectRoot, env });
+
+    // pick the most-recent session file (by dateCreated in the JSON, else mtime).
+    const files = readdirSync(wsDir).filter((f) => f.endsWith('.json') && f !== 'sessions.json');
+    if (files.length === 0) return readKiroFallbackTurn({ projectRoot, env });
+
+    // Sort files for a DETERMINISTIC pick (review M2): primary by dateCreated
+    // (desc), secondary by filename (desc) so an equal-stamp tie isn't decided by
+    // readdir order. The first after sort is the most-recent session.
+    let best = null;
+    let bestKey = null; // [stamp, filename]
+    for (const f of files) {
+      let json;
+      try {
+        json = JSON.parse(readFileSync(join(wsDir, f), 'utf8'));
+      } catch {
+        continue;
+      }
+      const key = [Number(json.dateCreated) || 0, f];
+      if (bestKey === null || key[0] > bestKey[0] || (key[0] === bestKey[0] && key[1] > bestKey[1])) {
+        bestKey = key;
+        best = json;
+      }
+    }
+    if (!best || !Array.isArray(best.history)) return readKiroFallbackTurn({ projectRoot, env });
+
+    const turns = parseKiroSessionHistory(JSON.stringify(best));
+    const lastUser = [...turns].reverse().find((t) => t.role === 'user');
+    const lastAssistant = [...turns].reverse().find((t) => t.role === 'assistant');
+    // IDE-0.x session present but no text → fall through (a mixed install where the
+    // same project was used from another surface).
+    if (!lastAssistant?.text && !lastUser?.text) return readKiroFallbackTurn({ projectRoot, env });
+    return {
+      userText: lastUser?.text || '',
+      assistantText: lastAssistant?.text || '',
+    };
+  } catch {
+    return empty;
+  }
+}