@mrciphersmith/keryx 0.2.140 → 0.2.143

package/README.md

@@ -248,6 +248,16 @@ What is in it today:
   session that keeps its ancestry, without editing a transcript by hand.
   `/status` is the session inspector (identity, context window and limits when
   the provider reported them); `/session-info` and `/info` are not aliases.
+- **Plans that survive the turn.** For multi-step work, the agent can keep a
+  structured execution plan in the session. The TUI shows pending, active,
+  completed, blocked, and skipped steps in the sidebar, and restored sessions
+  continue from the same plan instead of rebuilding it from transcript text.
+- **Theme-aware rich transcripts.** Assistant prose, headings, emphasis,
+  inline code, fenced code, diffs, and GFM pipe tables use semantic colors
+  derived from the selected `/theme`. Use a language fence such as
+  ```` ```typescript ```` for syntax color, ```` ```diff ```` for addition and
+  deletion rows, or ```` ```text ````/```` ```txt ```` when content must remain
+  literal, including terminal output and ASCII diagrams.
 - **Responsive busy-turn UX.** A running main turn can be interrupted with
   `/interrupt`; additional prompts are queued and answered as read-only side workers
   (`side-1`) in the TUI so the shell stays usable under long-running turns.

package/dist/cli.js

@@ -23987,7 +23987,7 @@ async function openSlateAtomic(dir, mintAttemptId, build) {
     if (existing !== undefined) {
       await archiveIfExistsLocked(dir, mintAttemptId());
     }
-    const next = build();
+    const next = build(existing);
     await writeFileAtomic(slatePath(dir), `${JSON.stringify(next, null, 2)}
 `);
     await rm7(path93.join(dir, "terminal-state.json"), { force: true });
@@ -24089,6 +24089,123 @@ var init_slate = __esm(() => {
   ];
 });
 
+// src/session/execution-plan.ts
+function clonePlan(plan) {
+  return { revision: plan.revision, items: plan.items.map((item) => ({ ...item })) };
+}
+function validateItems(items) {
+  const ids = new Set;
+  let active = 0;
+  return items.map((item) => {
+    const id = item.id.trim();
+    const title = item.title.trim();
+    if (id.length === 0)
+      throw new ExecutionPlanValidationError("item id must be non-empty");
+    if (ids.has(id))
+      throw new ExecutionPlanValidationError(`duplicate item id: ${id}`);
+    ids.add(id);
+    if (title.length === 0)
+      throw new ExecutionPlanValidationError(`item ${id} has an empty title`);
+    if (!EXECUTION_PLAN_STATUSES.includes(item.status)) {
+      throw new ExecutionPlanValidationError(`item ${id} has unknown status ${JSON.stringify(item.status)}`);
+    }
+    if (item.status === "in_progress" && ++active > 1) {
+      throw new ExecutionPlanValidationError("at most one item may be in_progress");
+    }
+    return { id, title, status: item.status };
+  });
+}
+function notify(dir, plan) {
+  for (const listener of listeners) {
+    try {
+      listener(dir, clonePlan(plan));
+    } catch {}
+  }
+}
+function subscribeExecutionPlans(listener) {
+  listeners.add(listener);
+  return () => listeners.delete(listener);
+}
+async function getExecutionPlan(dir) {
+  const plan = (await readSlate(dir))?.executionPlan;
+  return plan === undefined ? undefined : clonePlan(plan);
+}
+async function setExecutionPlan(dir, input) {
+  const items = validateItems(input.items);
+  let result;
+  await writeSlate(dir, (prev) => {
+    if (prev === undefined)
+      throw new ExecutionPlanValidationError("no open Slate");
+    const actual = prev.executionPlan?.revision ?? 0;
+    if (input.expectedRevision !== actual)
+      throw new ExecutionPlanConflictError(input.expectedRevision, actual);
+    result = { revision: actual + 1, items };
+    return { ...prev, executionPlan: result };
+  });
+  const plan = clonePlan(result);
+  notify(dir, plan);
+  return plan;
+}
+async function updateExecutionPlan(dir, input) {
+  let result;
+  await writeSlate(dir, (prev) => {
+    if (prev === undefined)
+      throw new ExecutionPlanValidationError("no open Slate");
+    const current = prev.executionPlan;
+    const actual = current?.revision ?? 0;
+    if (input.expectedRevision !== actual)
+      throw new ExecutionPlanConflictError(input.expectedRevision, actual);
+    if (current === undefined)
+      throw new ExecutionPlanValidationError("no execution plan exists");
+    if (!EXECUTION_PLAN_STATUSES.includes(input.status)) {
+      throw new ExecutionPlanValidationError(`unknown status ${JSON.stringify(input.status)}`);
+    }
+    if (!current.items.some((item) => item.id === input.itemId)) {
+      throw new ExecutionPlanValidationError(`unknown item id: ${input.itemId}`);
+    }
+    const items = validateItems(current.items.map((item) => item.id === input.itemId ? { ...item, status: input.status } : item));
+    result = { revision: actual + 1, items };
+    return { ...prev, executionPlan: result };
+  });
+  const plan = clonePlan(result);
+  notify(dir, plan);
+  return plan;
+}
+function hasActionableExecutionPlanItems(plan) {
+  return plan?.items.some((item) => item.status === "pending" || item.status === "in_progress") ?? false;
+}
+function renderExecutionPlanSnapshot(plan, maxItems = 7) {
+  if (plan === undefined || plan.items.length === 0)
+    return;
+  const rows = plan.items.slice(0, Math.max(0, maxItems)).map((item) => {
+    const title = item.title.length > 120 ? `${item.title.slice(0, 119)}\u2026` : item.title;
+    return `- ${item.id} [${item.status}]: ${title}`;
+  });
+  if (plan.items.length > rows.length)
+    rows.push(`- \u2026 ${plan.items.length - rows.length} more item(s)`);
+  return `Current execution plan (revision ${plan.revision}):
+${rows.join(`
+`)}`;
+}
+var EXECUTION_PLAN_STATUSES, listeners, ExecutionPlanConflictError, ExecutionPlanValidationError;
+var init_execution_plan = __esm(() => {
+  init_slate();
+  EXECUTION_PLAN_STATUSES = ["pending", "in_progress", "completed", "blocked", "skipped"];
+  listeners = new Set;
+  ExecutionPlanConflictError = class ExecutionPlanConflictError extends Error {
+    constructor(expected, actual) {
+      super(`execution plan revision conflict: expected ${expected}, current ${actual}`);
+      this.name = "ExecutionPlanConflictError";
+    }
+  };
+  ExecutionPlanValidationError = class ExecutionPlanValidationError extends Error {
+    constructor(message) {
+      super(`invalid execution plan: ${message}`);
+      this.name = "ExecutionPlanValidationError";
+    }
+  };
+});
+
 // src/flow/store.ts
 import { createHash as createHash16 } from "crypto";
 import { appendFile as appendFile3, mkdir as mkdir32, readFile as readFile49, readdir as readdir12 } from "fs/promises";
@@ -28849,7 +28966,12 @@ async function openSlate(opts) {
     cwd: opts.cwd,
     ...opts.runtime !== undefined ? { runtime: opts.runtime } : {}
   });
-  return openSlateAtomic(opts.dir, opts.mintAttemptId, () => ({ anchors, course: {}, seeds: [] }));
+  return openSlateAtomic(opts.dir, opts.mintAttemptId, (existing) => ({
+    anchors,
+    course: {},
+    seeds: [],
+    ...existing?.executionPlan === undefined ? {} : { executionPlan: existing.executionPlan }
+  }));
 }
 async function closeSlate(dir, mintAttemptId) {
   await archiveSlate(dir, mintAttemptId());
@@ -28891,7 +29013,12 @@ async function ensureSlateOpened(ref, mintAttemptId, runtime) {
   if (isSlateSessionDetached(ref)) {
     return;
   }
-  await openSlateAtomic(ref.dir, mintAttemptId, () => ({ anchors, course: {}, seeds: [] }));
+  await openSlateAtomic(ref.dir, mintAttemptId, (existing) => ({
+    anchors,
+    course: {},
+    seeds: [],
+    ...existing?.executionPlan === undefined ? {} : { executionPlan: existing.executionPlan }
+  }));
   ref.opened = true;
 }
 async function closeSlateSession(ref, mintAttemptId) {
@@ -29360,7 +29487,7 @@ function buildAgentSystemInstruction(orient, ctx = {}) {
 ` + locateRule + "- read_file returns a bounded window starting at `start_line` (default 1). A large file " + "is read by paging: its truncation notice names the start_line to continue from, and a " + `line number from ${hasGraph ? "search_code or graph_symbol" : "search_code"} can be read directly \u2014 do not re-read the ` + `same head hoping for more.
 ` + "- Prefer ONE correct shell_exec over many exploratory tool calls when the user asks " + `to run a known keryx workflow.
 ` + "- Tool-call budget: shell_exec, file-mutating shell, workspace_create/workspace_propose, and spawn_subagent " + "all share ONE small per-turn pool (distinct non-read actions), separate from the much larger read-tool pool. " + (hasGraph ? "search_code/graph_*/memory_search/read_wiki/wiki_*/test_related/health_status/flow_status/repomap/read_file/" : "search_code/read_file/") + "list_dir do NOT touch it. Conserve the small pool: batch multiple shell steps into ONE call with `&&` instead " + "of issuing them one at a time, get a command's arguments right the first time instead of trying variants, and " + "for any check covered by a read tool above, use that tool instead of shelling out to the equivalent `keryx \u2026` " + `CLI command.
-` + "- This session has its own Slate (working-set scratch, not project knowledge): " + "**slate_read** shows the Course (if a Flow is bound) and Seeds recorded so far \u2014 nothing " + "here is auto-injected, so call it if you want to see it. **slate_write_seed** with " + "`{ text, kind? }` records a draft hypothesis/decision/follow-up worth a later human " + "review. WRITE A SEED when you: found a root cause or a bug worth remembering; changed or " + "added code (summarize WHAT changed and WHY); took a design/architecture decision; " + "identified a risk; or discovered a constraint/lesson. Use the `kind` that fits: " + "`decision` (a choice made), `wiki-update` (something a wiki page should say), " + "`memory-entry` (a lesson/constraint), `follow-up` (a TODO for a later session), " + "`risk`, or `contract-change`. Keep each Seed to 2-3 sentences, concrete and specific. " + "Do NOT write Seeds for routine progress notes, one-shot operational requests (e.g. " + '"run git pull", "count files"), or trivia \u2014 those need no workspace and no proposal. ' + "Seeds are the ONLY input wrap-up proposes from: a session whose Slate has zero Seeds " + `produces zero proposals. A Seed is never accepted knowledge by itself.
+` + "- For multi-step work, use **plan_set** to publish a structured plan, **plan_update** after each real status " + "change, and **plan_get** before resolving a revision conflict. Keep stable item ids, at most one " + "`in_progress` item, and do not mark work complete before verification. These tools update session metadata " + "only; `/plan` remains the operator's separate read-only permission mode.\n" + "- This session has its own Slate (working-set scratch, not project knowledge): " + "**slate_read** shows the Course (if a Flow is bound) and Seeds recorded so far \u2014 nothing " + "here is auto-injected, so call it if you want to see it. **slate_write_seed** with " + "`{ text, kind? }` records a draft hypothesis/decision/follow-up worth a later human " + "review. WRITE A SEED when you: found a root cause or a bug worth remembering; changed or " + "added code (summarize WHAT changed and WHY); took a design/architecture decision; " + "identified a risk; or discovered a constraint/lesson. Use the `kind` that fits: " + "`decision` (a choice made), `wiki-update` (something a wiki page should say), " + "`memory-entry` (a lesson/constraint), `follow-up` (a TODO for a later session), " + "`risk`, or `contract-change`. Keep each Seed to 2-3 sentences, concrete and specific. " + "Do NOT write Seeds for routine progress notes, one-shot operational requests (e.g. " + '"run git pull", "count files"), or trivia \u2014 those need no workspace and no proposal. ' + "Seeds are the ONLY input wrap-up proposes from: a session whose Slate has zero Seeds " + `produces zero proposals. A Seed is never accepted knowledge by itself.
 ` + "- Shared Agent Context (SAC) workspaces hold accepted, evidence-backed project context " + "beyond this codebase. **workspace_list** with `{ includeArchived? }` shows every workspace " + "visible to you \u2014 call it first when the user references a shared team workspace or accepted " + "project context, or before creating a new workspace, to judge whether an existing one " + "already fits the current topic. **workspace_show** with `{ workspaceId }` shows one " + "workspace's manifest. **workspace_overview** with `{ workspaceId }`, then **workspace_read** " + "with `{ workspaceId, itemId }` for one specific item, reads its accepted Facts/Work/Know-how. " + "**workspace_create** with `{ title, component? }` creates a new workspace AND binds it to " + "this session's slate (wrap-up then proposes into it) \u2014 only when workspace_list found no " + "fitting one and the session has real, durable results worth persisting; a workspace is " + "meant to persist across sessions, so prefer an existing one over creating another for the " + "same topic, and do NOT create one for one-shot operational requests. **workspace_propose** with " + "`{ workspaceId, kind, sessionId?, note? }` (sessionId defaults to this session) proposes a decision/wiki-update/memory-entry/" + "follow-up/contract-change/risk from this session for later human review \u2014 it never accepts " + "anything by itself; accepting always requires a human running `keryx workspace review` at a " + `real terminal, never this tool.
 ` + "- When you need a decision, interview step, or clarification: use **ask_user** with " + "2\u20136 options `{ id, label, description, recommended? }` (mark one recommended). " + `Do not dump long prose questions without options.
 ` + "- For a focused independent subtask (investigate X, review Y, research Z): use " + "**spawn_subagent** with `{ task, mode?: 'read_only'|'general', label? }`. " + "Default mode is read_only (no shell). Prefer spawn for work that can finish " + `without your intermediate turns; do not spawn for trivial one-line answers.
@@ -29657,6 +29784,7 @@ async function runAgentTurnCore(io, deps, history, userLine, options = {}) {
     return "stop";
   };
   let toollessReprompts = 0;
+  let planFollowThroughUsed = false;
   let lastToollessText;
   for (;; ) {
     if (roundState.round >= roundState.maxRounds) {
@@ -29666,7 +29794,20 @@ async function runAgentTurnCore(io, deps, history, userLine, options = {}) {
       return { finishReason: "budget" };
     }
     roundState.round += 1;
-    const preRequestEstimate = estimateRequestTokens(history, deps.systemInstruction, toolDefs);
+    let currentPlan;
+    if (options.slateSession?.opened === true) {
+      try {
+        currentPlan = await getExecutionPlan(options.slateSession.dir);
+      } catch (cause) {
+        io.onSystem?.(`execution plan read failed (ignored): ${cause instanceof Error ? cause.message : String(cause)}
+`);
+      }
+    }
+    const planSnapshot = renderExecutionPlanSnapshot(currentPlan);
+    const roundSystemInstruction = planSnapshot === undefined ? deps.systemInstruction : `${deps.systemInstruction}
+
+${planSnapshot}`;
+    const preRequestEstimate = estimateRequestTokens(history, roundSystemInstruction, toolDefs);
     if (needsCompaction(preRequestEstimate, deps.contextWindow)) {
       const compacted = compactMessages(history, { keepLastUserTurns: 3 });
       if (!compacted.noop) {
@@ -29681,7 +29822,7 @@ async function runAgentTurnCore(io, deps, history, userLine, options = {}) {
     const baseRequest = {
       providerId: deps.providerId,
       modelId: deps.modelId,
-      systemInstruction: deps.systemInstruction,
+      systemInstruction: roundSystemInstruction,
       messages: [...history],
       tools: toolDefs,
       budget: { maxOutputTokens, runReservation: maxOutputTokens },
@@ -29911,6 +30052,32 @@ async function runAgentTurnCore(io, deps, history, userLine, options = {}) {
         }
         continue;
       }
+      if (!planFollowThroughUsed && hasActionableExecutionPlanItems(currentPlan)) {
+        planFollowThroughUsed = true;
+        history.push({
+          role: "user",
+          content: "[system] The current execution plan still has actionable items remaining. Continue the work now. " + "Do not give another final reply until the plan is complete or genuinely blocked.",
+          provenance: "project",
+          ts: now()
+        });
+        io.onHistoryChange?.("tool");
+        continue;
+      }
+      if (planFollowThroughUsed && hasActionableExecutionPlanItems(currentPlan)) {
+        const actionable = currentPlan?.items.filter((item) => item.status === "pending" || item.status === "in_progress") ?? [];
+        const shown = actionable.slice(0, 7).map((item) => {
+          const title = item.title.length > 120 ? `${item.title.slice(0, 119)}\u2026` : item.title;
+          return `- ${item.id} [${item.status}]: ${title}`;
+        });
+        if (actionable.length > shown.length) {
+          shown.push(`- \u2026 ${actionable.length - shown.length} more actionable item(s)`);
+        }
+        system(`
+[plan] Actionable items remain after the single follow-through:
+${shown.join(`
+`)}
+`);
+      }
       return {};
     }
     if (isAborted()) {
@@ -30481,6 +30648,7 @@ var init_agent = __esm(() => {
   init_peer_notification();
   init_scheduler();
   init_slate();
+  init_execution_plan();
   init_slate_course();
   init_machine_wrap_up();
   init_slate_lifecycle();
@@ -44782,7 +44950,7 @@ import { stdout } from "process";
 // src/lib/md-blocks.ts
 var FENCE_LINE = /^[ \t]{0,3}(```|~~~)(.*)\r?$/;
 var HUNK_HEADER = /^@@ -\d+(?:,\d+)? \+\d+(?:,\d+)? @@/;
-var MARKDOWN_LANGS = new Set(["md", "markdown", "prompt", "txt", "text"]);
+var MARKDOWN_LANGS = new Set(["md", "markdown", "prompt"]);
 var DIFF_LANGS = new Set(["diff", "patch"]);
 function stripTrailingCr(line) {
   return line.endsWith("\r") ? line.slice(0, -1) : line;
@@ -44791,6 +44959,101 @@ function splitLines(text) {
   return text.split(`
 `).map(stripTrailingCr);
 }
+function markdownTableCells(line) {
+  const source = line.trim();
+  if (!source.includes("|")) {
+    return;
+  }
+  const cells = [];
+  let cell = "";
+  let inCode = false;
+  for (let index = 0;index < source.length; index += 1) {
+    const char = source[index] ?? "";
+    if (char === "\\" && source[index + 1] === "|") {
+      cell += "|";
+      index += 1;
+      continue;
+    }
+    if (char === "`") {
+      inCode = !inCode;
+      cell += char;
+      continue;
+    }
+    if (char === "|" && !inCode) {
+      cells.push(cell.trim());
+      cell = "";
+      continue;
+    }
+    cell += char;
+  }
+  cells.push(cell.trim());
+  if (source.startsWith("|")) {
+    cells.shift();
+  }
+  if (source.endsWith("|")) {
+    cells.pop();
+  }
+  return cells.length >= 2 ? cells : undefined;
+}
+function tableAlignments(line, columns) {
+  const cells = markdownTableCells(line);
+  if (cells === undefined || cells.length !== columns) {
+    return;
+  }
+  const alignments = [];
+  for (const cell of cells) {
+    const marker = cell.trim();
+    if (!/^:?-{3,}:?$/.test(marker)) {
+      return;
+    }
+    alignments.push(marker.startsWith(":") && marker.endsWith(":") ? "center" : marker.endsWith(":") ? "right" : "left");
+  }
+  return alignments;
+}
+function parseMarkdownTables(text) {
+  if (text.length === 0) {
+    return [];
+  }
+  const lines = splitLines(text);
+  const parts = [];
+  let proseStart = 0;
+  const flushProse = (end) => {
+    if (end <= proseStart) {
+      return;
+    }
+    const prose = lines.slice(proseStart, end).join(`
+`);
+    if (prose.length > 0) {
+      parts.push({ kind: "prose", text: prose });
+    }
+  };
+  for (let index = 0;index + 1 < lines.length; index += 1) {
+    const headers = markdownTableCells(lines[index] ?? "");
+    if (headers === undefined) {
+      continue;
+    }
+    const alignments = tableAlignments(lines[index + 1] ?? "", headers.length);
+    if (alignments === undefined) {
+      continue;
+    }
+    flushProse(index);
+    const rows = [];
+    let cursor = index + 2;
+    while (cursor < lines.length) {
+      const row = markdownTableCells(lines[cursor] ?? "");
+      if (row === undefined || row.length !== headers.length) {
+        break;
+      }
+      rows.push(row);
+      cursor += 1;
+    }
+    parts.push({ kind: "table", table: { headers, alignments, rows } });
+    proseStart = cursor;
+    index = cursor - 1;
+  }
+  flushProse(lines.length);
+  return parts.length > 0 ? parts : [{ kind: "prose", text }];
+}
 function fenceInfo(line) {
   const match = FENCE_LINE.exec(line);
   if (match === null) {
@@ -51141,7 +51404,7 @@ import path47 from "path";
 // package.json
 var package_default = {
   name: "@mrciphersmith/keryx",
-  version: "0.2.140",
+  version: "0.2.143",
   description: "Version-controlled project context for AI coding agents: code graph, architecture wiki, project memory, relevant tests, quality signals, and task flows.",
   private: false,
   publishConfig: {
@@ -86842,6 +87105,107 @@ shell_exec: no output for ${info.idleTimeoutMs}ms, so the command was killed (ra
   };
 }
 
+// src/harness/tool/builtin/execution-plan-tool.ts
+init_execution_plan();
+var statusSchema = { type: "string", enum: [...EXECUTION_PLAN_STATUSES] };
+function noSession(name) {
+  return { output: `${name}: no active session in this run`, isError: true };
+}
+function failed(name, cause) {
+  return { output: `${name} failed: ${cause instanceof Error ? cause.message : String(cause)}`, isError: true };
+}
+function executionPlanTools(getSessionDir) {
+  const get = {
+    definition: {
+      name: "plan_get",
+      description: "Read the current structured execution plan. Input: {}.",
+      inputSchema: { type: "object", properties: {}, additionalProperties: false },
+      risk: "read"
+    },
+    invoke: async () => {
+      const dir = getSessionDir();
+      if (dir === undefined)
+        return noSession("plan_get");
+      try {
+        return { output: JSON.stringify(await getExecutionPlan(dir) ?? null, null, 2), isError: false };
+      } catch (cause) {
+        return failed("plan_get", cause);
+      }
+    }
+  };
+  const set = {
+    definition: {
+      name: "plan_set",
+      description: "Replace the structured execution plan using optimistic revision control.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          expectedRevision: { type: "integer", minimum: 0 },
+          items: {
+            type: "array",
+            items: {
+              type: "object",
+              properties: { id: { type: "string", minLength: 1 }, title: { type: "string", minLength: 1 }, status: statusSchema },
+              required: ["id", "title", "status"],
+              additionalProperties: false
+            }
+          }
+        },
+        required: ["expectedRevision", "items"],
+        additionalProperties: false
+      },
+      risk: "read"
+    },
+    invoke: async (input) => {
+      const dir = getSessionDir();
+      if (dir === undefined)
+        return noSession("plan_set");
+      try {
+        const plan = await setExecutionPlan(dir, {
+          expectedRevision: input.expectedRevision,
+          items: input.items
+        });
+        return { output: JSON.stringify(plan, null, 2), isError: false };
+      } catch (cause) {
+        return failed("plan_set", cause);
+      }
+    }
+  };
+  const update = {
+    definition: {
+      name: "plan_update",
+      description: "Update one execution-plan item's status using optimistic revision control.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          expectedRevision: { type: "integer", minimum: 0 },
+          itemId: { type: "string", minLength: 1 },
+          status: statusSchema
+        },
+        required: ["expectedRevision", "itemId", "status"],
+        additionalProperties: false
+      },
+      risk: "read"
+    },
+    invoke: async (input) => {
+      const dir = getSessionDir();
+      if (dir === undefined)
+        return noSession("plan_update");
+      try {
+        const plan = await updateExecutionPlan(dir, {
+          expectedRevision: input.expectedRevision,
+          itemId: input.itemId,
+          status: input.status
+        });
+        return { output: JSON.stringify(plan, null, 2), isError: false };
+      } catch (cause) {
+        return failed("plan_update", cause);
+      }
+    }
+  };
+  return [set, update, get];
+}
+
 // src/harness/tool/builtin/slate-tool.ts
 init_slate();
 init_slate_course();
@@ -87760,6 +88124,7 @@ function buildInteractiveAgentTools(input) {
     createAskUserTool(invokeAskUserHost),
     slateReadTool(input.cwd, getSessionDir),
     slateWriteSeedTool(getSessionDir, idSeq, clock),
+    ...executionPlanTools(getSessionDir),
     ...input.bus?.client() === undefined ? [] : buildBusTools(input.bus.client),
     ...input.mcp === undefined ? [] : createMcpInteractiveTools({
       catalog: input.mcp.catalog,
@@ -91315,6 +91680,64 @@ class LiveMarkdownBlock {
 init_config_dir();
 import { existsSync as existsSync33 } from "fs";
 import path192 from "path";
+function hexChannels(hex) {
+  return [1, 3, 5].map((offset) => Number.parseInt(hex.slice(offset, offset + 2), 16));
+}
+function mixHex(base, accent, accentWeight) {
+  const a = hexChannels(base);
+  const b = hexChannels(accent);
+  const channel = (index) => Math.round((a[index] ?? 0) * (1 - accentWeight) + (b[index] ?? 0) * accentWeight).toString(16).padStart(2, "0");
+  return `#${channel(0)}${channel(1)}${channel(2)}`;
+}
+function relativeLuminance(hex) {
+  const linear = hexChannels(hex).map((channel) => {
+    const value = channel / 255;
+    return value <= 0.04045 ? value / 12.92 : ((value + 0.055) / 1.055) ** 2.4;
+  });
+  return 0.2126 * (linear[0] ?? 0) + 0.7152 * (linear[1] ?? 0) + 0.0722 * (linear[2] ?? 0);
+}
+function contrastRatio(a, b) {
+  const [light, dark] = [relativeLuminance(a), relativeLuminance(b)].sort((x, y) => y - x);
+  return ((light ?? 0) + 0.05) / ((dark ?? 0) + 0.05);
+}
+function transcriptAccent(theme, accent) {
+  for (let weight = 0.5;weight >= 0; weight -= 0.05) {
+    const candidate = mixHex(theme.text, accent, weight);
+    if (contrastRatio(candidate, theme.bg) >= 3 && contrastRatio(candidate, theme.panel) >= 3) {
+      return candidate;
+    }
+  }
+  return theme.text;
+}
+function deriveTranscriptPalette(theme) {
+  const heading = transcriptAccent(theme, theme.assistant);
+  const muted = transcriptAccent(theme, theme.muted);
+  const positive = transcriptAccent(theme, theme.ok);
+  const negative = transcriptAccent(theme, theme.error);
+  const focus = transcriptAccent(theme, theme.focus);
+  return {
+    prose: theme.text,
+    heading,
+    emphasis: theme.text,
+    inlineCode: focus,
+    inlineCodeBackground: theme.highlight,
+    blockMeta: theme.muted,
+    tableHeader: heading,
+    tableBorder: theme.border,
+    codePlain: theme.text,
+    codeComment: muted,
+    codeString: positive,
+    codeNumber: focus,
+    codeKeyword: heading,
+    diffContext: theme.text,
+    diffMeta: muted,
+    diffHunk: heading,
+    diffAdd: positive,
+    diffDelete: negative,
+    diffAddBackground: mixHex(theme.panel, theme.ok, 0.12),
+    diffDeleteBackground: mixHex(theme.panel, theme.error, 0.12)
+  };
+}
 var THEME_NAMES = [
   "groknight",
   "tokyonight",
@@ -91528,7 +91951,7 @@ var THEMES = {
 };
 var kind = DEFAULT_THEME_ID;
 var resolved = THEMES.groknight;
-var listeners = new Set;
+var listeners2 = new Set;
 function parseThemeId(raw) {
   const key = raw.trim().toLowerCase();
   if (key === "auto" || key === "system") {
@@ -91568,15 +91991,15 @@ function themeLabel(id) {
 function applyThemeId(id, mode = null) {
   kind = id;
   resolved = resolveTheme(id, mode);
-  for (const listener of listeners) {
+  for (const listener of listeners2) {
     listener(resolved, kind);
   }
   return resolved;
 }
 function onThemeChange(listener) {
-  listeners.add(listener);
+  listeners2.add(listener);
   return () => {
-    listeners.delete(listener);
+    listeners2.delete(listener);
   };
 }
 function tuiConfigPath(dir) {
@@ -92305,11 +92728,15 @@ function clipBody(text, maxLines = MAX_BODY_LINES) {
   return [...lines.slice(0, maxLines), `\u2026 (${hidden} more line${hidden === 1 ? "" : "s"} not shown)`].join(`
 `);
 }
-function markdownToChunks(otui, md) {
+function themedChunk(otui, text, fg, bg) {
+  const foreground = otui.fg(fg)(text);
+  return bg === undefined ? foreground : otui.bg(bg)(foreground);
+}
+function markdownToChunks(otui, md, palette = deriveTranscriptPalette(getTheme())) {
   const out = [];
   const plain = (s) => {
     if (s.length > 0) {
-      out.push(...otui.stringToStyledText(s).chunks);
+      out.push(themedChunk(otui, s, palette.prose));
     }
   };
   const inline = (text) => {
@@ -92319,9 +92746,9 @@ function markdownToChunks(otui, md) {
     while ((m = re.exec(text)) !== null) {
       plain(text.slice(last, m.index));
       if (m[1] !== undefined) {
-        out.push(otui.dim(m[1].slice(1, -1)));
+        out.push(themedChunk(otui, m[1].slice(1, -1), palette.inlineCode, palette.inlineCodeBackground));
       } else if (m[2] !== undefined) {
-        out.push(otui.bold(m[2].slice(2, -2)));
+        out.push(otui.bold(themedChunk(otui, m[2].slice(2, -2), palette.emphasis)));
       }
       last = m.index + m[0].length;
     }
@@ -92340,12 +92767,12 @@ function markdownToChunks(otui, md) {
 `);
     }
     if (inCode) {
-      out.push(otui.dim(line));
+      out.push(themedChunk(otui, line, palette.codePlain));
       continue;
     }
     const heading = /^#{1,6}\s+(.*)$/.exec(line);
     if (heading !== null) {
-      out.push(otui.cyan(otui.bold(heading[1] ?? "")));
+      out.push(otui.bold(themedChunk(otui, heading[1] ?? "", palette.heading)));
       continue;
     }
     const bullet = /^(\s*)[-*]\s+(.*)$/.exec(line);
@@ -92358,109 +92785,150 @@ function markdownToChunks(otui, md) {
   }
   return out;
 }
-function diffChunks(otui, text) {
+function diffChunks(otui, text, palette = deriveTranscriptPalette(getTheme())) {
   const out = [];
   const lines = splitLines(text);
   for (const [index, line] of lines.entries()) {
     if (index > 0) {
-      out.push(...otui.stringToStyledText(`
-`).chunks);
+      out.push(themedChunk(otui, `
+`, palette.diffContext));
     }
     switch (classifyDiffLine(line)) {
       case "add":
-        out.push(otui.green(line));
+        out.push(themedChunk(otui, line, palette.diffAdd, palette.diffAddBackground));
         break;
       case "del":
-        out.push(otui.red(line));
+        out.push(themedChunk(otui, line, palette.diffDelete, palette.diffDeleteBackground));
         break;
       case "hunk":
-        out.push(otui.cyan(line));
+        out.push(themedChunk(otui, line, palette.diffHunk));
         break;
       case "meta":
-        out.push(otui.dim(line));
+        out.push(themedChunk(otui, line, palette.diffMeta));
         break;
       default:
-        out.push(...otui.stringToStyledText(line).chunks);
+        out.push(themedChunk(otui, line, palette.diffContext));
     }
   }
   return out;
 }
-function flatDimChunks(otui, text) {
+function flatDimChunks(otui, text, palette = deriveTranscriptPalette(getTheme())) {
   const out = [];
   for (const [index, line] of splitLines(text).entries()) {
     if (index > 0) {
-      out.push(...otui.stringToStyledText(`
-`).chunks);
+      out.push(otui.dim(themedChunk(otui, `
+`, palette.blockMeta)));
     }
-    out.push(otui.dim(line));
+    out.push(otui.dim(themedChunk(otui, line, palette.blockMeta)));
   }
   return out;
 }
-function codeChunks(otui, text, lang) {
+function codeChunks(otui, text, lang, palette) {
   const out = [];
   for (const [index, line] of splitLines(text).entries()) {
     if (index > 0) {
-      out.push(...otui.stringToStyledText(`
-`).chunks);
+      out.push(themedChunk(otui, `
+`, palette.codePlain));
     }
     for (const token of tokenizeCodeLine(line, lang)) {
       switch (token.kind) {
         case "comment":
-          out.push(otui.dim(token.text));
+          out.push(themedChunk(otui, token.text, palette.codeComment));
           break;
         case "string":
-          out.push(otui.green(token.text));
+          out.push(themedChunk(otui, token.text, palette.codeString));
           break;
         case "number":
-          out.push(otui.yellow(token.text));
+          out.push(themedChunk(otui, token.text, palette.codeNumber));
           break;
         case "keyword":
-          out.push(otui.cyan(token.text));
+          out.push(themedChunk(otui, token.text, palette.codeKeyword));
           break;
         default:
-          out.push(...otui.stringToStyledText(token.text).chunks);
+          out.push(themedChunk(otui, token.text, palette.codePlain));
       }
     }
   }
   return out;
 }
-function payloadChunks(otui, text, lang = "") {
+function payloadChunks(otui, text, lang = "", palette = deriveTranscriptPalette(getTheme())) {
   const kind = payloadKind(lang, lineCountOf(text));
   if (kind === "diff" || looksLikeUnifiedDiff(text)) {
-    return diffChunks(otui, text);
+    return diffChunks(otui, text, palette);
   }
   if (kind === "markdown" || lang.length === 0) {
-    return markdownToChunks(otui, text);
+    return markdownToChunks(otui, text, palette);
   }
-  return codeChunks(otui, text, lang);
+  return codeChunks(otui, text, lang, palette);
 }
 function createSegmentView(otui, renderer, parent, segment) {
   viewSeq += 1;
   const id = `seg${viewSeq}`;
   if (segment.kind === "text") {
-    const text = new otui.TextRenderable(renderer, {
-      id,
-      content: new otui.StyledText(markdownToChunks(otui, segment.text))
-    });
-    parent.add(text);
+    let mounted = [];
+    const paint = (source) => {
+      for (const child of mounted) {
+        try {
+          parent.remove(child);
+          child.destroyRecursively();
+        } catch {}
+      }
+      mounted = [];
+      const palette = deriveTranscriptPalette(getTheme());
+      for (const [index, part] of parseMarkdownTables(source).entries()) {
+        if (part.kind === "prose") {
+          const text = new otui.TextRenderable(renderer, {
+            id: `${id}-prose-${index}`,
+            content: new otui.StyledText(markdownToChunks(otui, part.text, palette))
+          });
+          parent.add(text);
+          mounted.push(text);
+          continue;
+        }
+        const header = part.table.headers.map((cell) => [otui.bold(themedChunk(otui, cell, palette.tableHeader))]);
+        const rows = part.table.rows.map((row) => row.map((cell) => markdownToChunks(otui, cell, palette)));
+        const table = new otui.TextTableRenderable(renderer, {
+          id: `${id}-table-${index}`,
+          content: [header, ...rows],
+          width: "100%",
+          wrapMode: "word",
+          columnWidthMode: "full",
+          columnFitter: "balanced",
+          cellPaddingX: 1,
+          cellPaddingY: 0,
+          showBorders: true,
+          outerBorder: true,
+          borderStyle: "rounded",
+          borderColor: palette.tableBorder,
+          fg: palette.prose,
+          backgroundColor: getTheme().panel
+        });
+        parent.add(table);
+        mounted.push(table);
+      }
+    };
+    paint(segment.text);
     return {
       kind: "text",
       update: (next) => {
         if (next.kind === "text") {
-          text.content = new otui.StyledText(markdownToChunks(otui, next.text));
+          paint(next.text);
         }
       },
       destroy: () => {
-        try {
-          parent.remove(text);
-          text.destroyRecursively();
-        } catch {}
+        for (const child of mounted) {
+          try {
+            parent.remove(child);
+            child.destroyRecursively();
+          } catch {}
+        }
+        mounted = [];
       }
     };
   }
   const tag = (lang, body) => {
     const n = lineCountOf(body);
-    return `${lang.length > 0 ? lang : "text"} \xB7 ${n} ${n === 1 ? "line" : "lines"} \xB7 y copy`;
+    return `${lang.length > 0 ? lang : "text"} \xB7 ${n} ${n === 1 ? "line" : "lines"} \xB7 ctrl+o then y copy`;
   };
   const frameWidth = (lang, body) => Math.max(hugWidth(body, FRAME_CHROME), hugWidth(tag(lang, body), FRAME_CHROME));
   const frame = new otui.BoxRenderable(renderer, {
@@ -92471,12 +92939,15 @@ function createSegmentView(otui, renderer, parent, segment) {
     borderStyle: "rounded",
     border: true,
     borderColor: frameColor(),
+    backgroundColor: getTheme().panel,
     paddingLeft: 1,
     paddingRight: 1
   });
   const header = new otui.TextRenderable(renderer, {
     id: `${id}-tag`,
-    content: otui.t`${otui.dim(tag(segment.lang, segment.body))}`
+    content: new otui.StyledText([
+      themedChunk(otui, tag(segment.lang, segment.body), deriveTranscriptPalette(getTheme()).blockMeta)
+    ])
   });
   const body = new otui.TextRenderable(renderer, {
     id: `${id}-body`,
@@ -92491,7 +92962,9 @@ function createSegmentView(otui, renderer, parent, segment) {
       if (next.kind !== "code") {
         return;
       }
-      header.content = otui.t`${otui.dim(tag(next.lang, next.body))}`;
+      header.content = new otui.StyledText([
+        themedChunk(otui, tag(next.lang, next.body), deriveTranscriptPalette(getTheme()).blockMeta)
+      ]);
       body.content = new otui.StyledText(payloadChunks(otui, next.body, next.lang));
       frame.maxWidth = frameWidth(next.lang, next.body);
     },
@@ -95107,12 +95580,50 @@ function themeColorRemap(from, to) {
       remap.set(oldColor, newColor);
     }
   }
+  const fromTranscript = deriveTranscriptPalette(from);
+  const toTranscript = deriveTranscriptPalette(to);
+  for (const slot of Object.keys(fromTranscript)) {
+    const oldColor = fromTranscript[slot];
+    const newColor = toTranscript[slot];
+    if (oldColor !== newColor) {
+      remap.set(oldColor, newColor);
+    }
+  }
   return remap;
 }
-function recolorThemeTree(node, remap) {
+function recolorContent(value, remap, color) {
+  if (Array.isArray(value)) {
+    let changed = false;
+    for (const item of value) {
+      changed = recolorContent(item, remap, color) || changed;
+    }
+    return changed;
+  }
+  if (value === null || typeof value !== "object") {
+    return false;
+  }
+  const target = value;
+  let changed = false;
+  if (typeof target.text === "string") {
+    for (const prop of ["fg", "bg"]) {
+      const hex = themeColorToHex(target[prop]);
+      const next = hex === undefined ? undefined : remap.get(hex);
+      if (next !== undefined) {
+        target[prop] = color(next);
+        changed = true;
+      }
+    }
+  }
+  if (target.chunks !== undefined) {
+    changed = recolorContent(target.chunks, remap, color) || changed;
+  }
+  return changed;
+}
+function recolorThemeTree(node, fromTheme, toTheme, color = (hex) => hex) {
   if (node === null || node === undefined) {
     return;
   }
+  const remap = themeColorRemap(fromTheme, toTheme);
   const target = node;
   for (const prop of ["borderColor", "backgroundColor", "fg"]) {
     const hex = themeColorToHex(target[prop]);
@@ -95123,9 +95634,13 @@ function recolorThemeTree(node, remap) {
       }
     }
   }
+  const content = target.content;
+  if (content !== undefined && recolorContent(content, remap, color)) {
+    target.content = content;
+  }
   if (typeof target.getChildren === "function") {
     for (const child of target.getChildren()) {
-      recolorThemeTree(child, remap);
+      recolorThemeTree(child, fromTheme, toTheme, color);
     }
   }
 }
@@ -95745,7 +96260,6 @@ async function createShellChrome(otui, renderer, opts) {
     }
   });
   const applyTheme = (theme = getTheme()) => {
-    const remap = themeColorRemap(appliedTheme, theme);
     try {
       r.setBackgroundColor(theme.bg);
     } catch {}
@@ -95770,14 +96284,15 @@ async function createShellChrome(otui, renderer, opts) {
     menu.selectedTextColor = theme.focus;
     menu.descriptionColor = theme.muted;
     menu.selectedDescriptionColor = theme.muted;
-    recolorThemeTree(transcript, remap);
-    recolorThemeTree(dock, remap);
-    recolorThemeTree(queueDock, remap);
-    recolorThemeTree(sidebarTop, remap);
-    recolorThemeTree(menu, remap);
-    recolorThemeTree(composer, remap);
-    recolorThemeTree(header, remap);
-    recolorThemeTree(footer, remap);
+    const chunkColor = (hex) => otui.RGBA.fromHex(hex);
+    recolorThemeTree(transcript, appliedTheme, theme, chunkColor);
+    recolorThemeTree(dock, appliedTheme, theme, chunkColor);
+    recolorThemeTree(queueDock, appliedTheme, theme, chunkColor);
+    recolorThemeTree(sidebarTop, appliedTheme, theme, chunkColor);
+    recolorThemeTree(menu, appliedTheme, theme, chunkColor);
+    recolorThemeTree(composer, appliedTheme, theme, chunkColor);
+    recolorThemeTree(header, appliedTheme, theme, chunkColor);
+    recolorThemeTree(footer, appliedTheme, theme, chunkColor);
     appliedTheme = theme;
   };
   const unsubTheme = onThemeChange((theme) => applyTheme(theme));
@@ -102363,6 +102878,96 @@ function paintBackgroundJobSidebar(otui, renderer, parent, entries, options) {
   }
 }
 
+// src/tui/execution-plan-panel.ts
+init_execution_plan();
+var GLYPHS = {
+  completed: "\u2713",
+  in_progress: "\u25B6",
+  pending: "\u25CB",
+  blocked: "!",
+  skipped: "\u2212"
+};
+function truncate7(text, width) {
+  if (width <= 0)
+    return "";
+  if (displayWidth(text) <= width)
+    return text;
+  if (width === 1)
+    return "\u2026";
+  let prefix = "";
+  for (const character of text) {
+    if (displayWidth(prefix + character) > width - 1)
+      break;
+    prefix += character;
+  }
+  return `${prefix}\u2026`;
+}
+function projectExecutionPlanPanel(plan, options) {
+  if (plan === undefined || plan.items.length === 0) {
+    return { visible: false, rows: [], revision: undefined };
+  }
+  const size = Math.max(1, Math.min(options.maxRows ?? 7, 7, plan.items.length));
+  const active = Math.max(0, plan.items.findIndex((item) => item.status === "in_progress"));
+  const start = Math.max(0, Math.min(active - Math.floor(size / 2), plan.items.length - size));
+  const rows = plan.items.slice(start, start + size).map((item) => {
+    const glyph = GLYPHS[item.status];
+    return { id: item.id, status: item.status, glyph, text: truncate7(`${glyph} ${item.title}`, options.width) };
+  });
+  return { visible: true, rows, revision: plan.revision };
+}
+function mountExecutionPlanPanel(otui, renderer, parent, options) {
+  const box = parent;
+  let paintedDir;
+  let paintedRevision;
+  let refreshGeneration = 0;
+  let disposed = false;
+  const paint = (plan, dir) => {
+    const projected = projectExecutionPlanPanel(plan, {
+      width: options.width,
+      ...options.maxRows === undefined ? {} : { maxRows: options.maxRows }
+    });
+    if (paintedDir === dir && paintedRevision === projected.revision)
+      return;
+    paintedDir = dir;
+    paintedRevision = projected.revision;
+    if (box.getChildren !== undefined && box.remove !== undefined) {
+      for (const child of [...box.getChildren()])
+        box.remove(child);
+    }
+    const Ctor = otui.TextRenderable;
+    if (!projected.visible || box.add === undefined || Ctor === undefined)
+      return;
+    box.add(new Ctor(renderer, { id: "sb-plan-h", content: "Plan", marginTop: 1 }));
+    for (const row of projected.rows)
+      box.add(new Ctor(renderer, { id: `sb-plan-${row.id}`, content: row.text }));
+  };
+  const refresh = async () => {
+    const dir = options.getSessionDir();
+    const generation = ++refreshGeneration;
+    const plan = dir === undefined ? undefined : await getExecutionPlan(dir).catch(() => {
+      return;
+    });
+    if (disposed || generation !== refreshGeneration || dir !== options.getSessionDir())
+      return;
+    paint(plan, dir);
+  };
+  const unsubscribe = subscribeExecutionPlans((dir, plan) => {
+    if (dir === options.getSessionDir()) {
+      refreshGeneration += 1;
+      paint(plan, dir);
+    }
+  });
+  refresh();
+  return {
+    refresh,
+    dispose: () => {
+      disposed = true;
+      refreshGeneration += 1;
+      unsubscribe();
+    }
+  };
+}
+
 // src/tui/bus-command.ts
 var SEND_USAGE = "usage: /bus send @<name> <text>  (or /bus @<name> <text>)";
 var ASK_USAGE = "usage: /bus ask @<name> <text>";
@@ -104346,6 +104951,7 @@ async function launchTuiAgentShell(opts) {
   let mountedChrome;
   let liveDeps;
   let liveJobs;
+  let disposeExecutionPlanPanel;
   let detachExternal;
   let liveBus;
   let destroyed = false;
@@ -104368,6 +104974,7 @@ async function launchTuiAgentShell(opts) {
   try {
     const r = renderer = await createShellRenderer(otui, {
       onDestroy: () => {
+        disposeExecutionPlanPanel?.();
         destroyed = true;
         foregroundOperation.cancel("renderer destroyed");
         foregroundOperation.dispose();
@@ -104407,6 +105014,7 @@ async function launchTuiAgentShell(opts) {
     saveShellConfig(sel.baseUrl === undefined ? { provider: sel.provider, model: sel.model } : { provider: sel.provider, model: sel.model, baseUrl: sel.baseUrl });
     let currentSel = sel;
     const suggestionGate = new NextStepSuggestionGate;
+    let slateSession;
     const liveSlateSession = () => whilePersisting(slateSession, () => sessionLease.canPersist());
     let deps = await opts.makeAgentDeps(sel, liveSlateSession, busClientRef);
     liveDeps = deps;
@@ -104550,6 +105158,18 @@ async function launchTuiAgentShell(opts) {
       marginTop: 1
     });
     sidebar.add(sbSubagents);
+    const sbPlan = new otui.BoxRenderable(r, {
+      id: "sb-plan",
+      flexDirection: "column",
+      flexShrink: 0
+    });
+    sidebar.add(sbPlan);
+    const executionPlanPanel = mountExecutionPlanPanel(otui, r, sbPlan, {
+      getSessionDir: () => liveSlateSession()?.dir,
+      width: SIDEBAR_TEXT_WIDTH,
+      maxRows: 7
+    });
+    disposeExecutionPlanPanel = executionPlanPanel.dispose;
     const sbJobs = new otui.BoxRenderable(r, {
       id: "sb-jobs",
       flexDirection: "column",
@@ -105134,9 +105754,9 @@ async function launchTuiAgentShell(opts) {
     let archive = [];
     let nextArchiveIndex = 0;
     let sessionPersistTimer;
-    let slateSession;
     const bindSlateToLiveSession = () => {
       slateSession = freshSlateSessionRef(liveSession.dir, sessionCwd);
+      executionPlanPanel.refresh();
     };
     const onContextCompaction = (r) => {
       if (!sessionLease.canPersist()) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mrciphersmith/keryx",
-  "version": "0.2.140",
+  "version": "0.2.143",
   "description": "Version-controlled project context for AI coding agents: code graph, architecture wiki, project memory, relevant tests, quality signals, and task flows.",
   "private": false,
   "publishConfig": {