@polycode-projects/the-mechanical-code-talker 0.2.0 → 0.4.0

package/src/server.mjs

@@ -48,6 +48,7 @@ import {
   renderClassHistory,
 } from "./codegraph.mjs";
 import { ask } from "./ask.mjs";
+import { createGraphService } from "./providers/graph-service.mjs";
 
 const SNIPPET_MAX_LINES = 200;
 
@@ -66,7 +67,7 @@ export const TOOLS = [
       type: "object",
       required: ["symbol"],
       properties: {
-        symbol: { type: "string", description: "Module path (django/utils/text.py) or a sibling function/class name in it (lower)." },
+        symbol: { type: "string", description: "Module path (e.g. path/to/module) or a sibling function/class name defined in it." },
         depth: { type: "string", enum: ["min", "auto", "full"], default: "auto", description: "auto (sized to the task) | min (leanest) | full (every section)." },
       },
     },
@@ -78,7 +79,7 @@ export const TOOLS = [
       type: "object",
       required: ["symbol"],
       properties: {
-        symbol: { type: "string", description: "function/class name (slugify, Truncator), Class.method, or fn:<path>#name." },
+        symbol: { type: "string", description: "function/class name, Class.method, or fn:<path>#name." },
       },
     },
   },
@@ -110,12 +111,17 @@ async function loadGraph(config, source) {
   return graph;
 }
 
-function resolveOrThrow(graph, symbol, what) {
-  const { match, candidates } = resolveSymbol(graph, symbol);
+// Resolution + the miss→ToolError bridge, threaded through the typed service
+// object (createGraphService). The service is the named seam; tmct's own
+// presentation (render*) reads its raw graph (svc.graph) and formats. A clean
+// miss on the interface becomes the instructive ToolError the CLI/chat expect —
+// message-only, never a stack, no fabricated entity names (generic placeholder).
+function resolveOrThrow(svc, symbol, what) {
+  const { match, candidates } = resolveSymbol(svc.graph, symbol);
   if (!match) {
     throw new ToolError(
       `no entity matching ${what} "${symbol}" in the code-map graph. ` +
-        "Try a repo-relative path (e.g. django/utils/text.py), a basename, or tmct_search for a fuzzy lookup.",
+        "Try a repo-relative path (e.g. path/to/module), a basename, or tmct_search for a fuzzy lookup.",
     );
   }
   return { match, candidates };
@@ -146,7 +152,8 @@ export async function buildContextBundle(args, { config, source = defaultSource,
   // by the tmct-max arm to test whether more injection re-bloats.
   const max = Boolean(args?.max);
   const graph = await loadGraph(config, source);
-  const { match } = resolveOrThrow(graph, symbol, "symbol");
+  const svc = createGraphService(graph);
+  const { match } = resolveOrThrow(svc, symbol, "symbol");
   const plan = contextPlan(graph, match);
   // #6/B1/B6: pick the section mask by depth — min forces TINY, full/max forces everything, auto
   // runs the size classifier (lean TINY default + one-tier top-up when the edit needs it).
@@ -256,29 +263,48 @@ export async function buildContextBundle(args, { config, source = defaultSource,
   return { text: out.join("\n"), tier, topup };
 }
 
+// The full set of tool names dispatchTool serves (hot catalog + cold tools). Used
+// to reject an unknown tool before any graph load.
+const DISPATCH_TOOLS = new Set([
+  "tmct_context", "tmct_context_more", "tmct_describe", "tmct_snippet", "tmct_signature",
+  "tmct_impact", "tmct_search", "tmct_members", "tmct_subclasses", "tmct_architecture",
+  "tmct_exports", "tmct_untested", "tmct_ask", "tmct_tests_for", "tmct_history",
+  "tmct_callers", "tmct_callees", "tmct_cochanges", "tmct_calls",
+  "tmct_file_history", "tmct_method_history", "tmct_class_history",
+]);
+
 export async function dispatchTool(name, args, { config, source = defaultSource } = {}) {
+  // tmct_context builds (and loads) its own edit bundle — return early so we don't
+  // double-load the graph for it.
   if (name === "tmct_context") {
     return (await buildContextBundle(args, { config, source })).text;
   }
+  // Reject an unknown tool BEFORE touching the graph — preserves the original
+  // ordering (an unknown name never triggers a load).
+  if (!DISPATCH_TOOLS.has(name)) throw new ToolError(`unknown tool: ${name}`);
+  // Every other tool reads graph truth: load once and build the typed service
+  // object (the Repository Interface). dispatchTool is the presentation adapter —
+  // it delegates resolution + the miss/error contract to the service and formats
+  // the result with tmct's own render* layer (which reads svc.graph). This is the
+  // switch's operations extracted into a named, typed seam without changing bytes.
+  const graph = await loadGraph(config, source);
+  const svc = createGraphService(graph);
   if (name === "tmct_context_more") {
     const symbol = String(args?.symbol || "").trim();
     if (!symbol) throw new ToolError("symbol is required");
-    const graph = await loadGraph(config, source);
-    const { match } = resolveOrThrow(graph, symbol, "symbol");
+    const { match } = resolveOrThrow(svc, symbol, "symbol");
     return renderContextMore(contextPlan(graph, match));
   }
   if (name === "tmct_describe") {
     const symbol = String(args?.symbol || "").trim();
     if (!symbol) throw new ToolError("symbol is required");
-    const graph = await loadGraph(config, source);
-    const { match, candidates } = resolveOrThrow(graph, symbol, "symbol");
+    const { match, candidates } = resolveOrThrow(svc, symbol, "symbol");
     return renderDescribe(graph, match, { candidates });
   }
   if (name === "tmct_snippet") {
     const symbol = String(args?.symbol || "").trim();
     if (!symbol) throw new ToolError("symbol is required");
-    const graph = await loadGraph(config, source);
-    const { match, candidates } = resolveOrThrow(graph, symbol, "symbol");
+    const { match, candidates } = resolveOrThrow(svc, symbol, "symbol");
     const site = siteOf(match);
     if (!site) {
       throw new ToolError(
@@ -308,22 +334,19 @@ export async function dispatchTool(name, args, { config, source = defaultSource
   if (name === "tmct_signature") {
     const symbol = String(args?.symbol || "").trim();
     if (!symbol) throw new ToolError("symbol is required");
-    const graph = await loadGraph(config, source);
-    const { match } = resolveOrThrow(graph, symbol, "symbol");
+    const { match } = resolveOrThrow(svc, symbol, "symbol");
     return renderSignature(graph, match);
   }
   if (name === "tmct_impact") {
     const module = String(args?.module || "").trim();
     if (!module) throw new ToolError("module is required");
-    const graph = await loadGraph(config, source);
-    const { match } = resolveOrThrow(graph, module, "module");
+    const { match } = resolveOrThrow(svc, module, "module");
     return renderImpact(graph, match);
   }
   if (name === "tmct_search") {
     const query = String(args?.query || "").trim();
     const kind = String(args?.kind || "").trim();
     if (!query && !kind) throw new ToolError("query is required");
-    const graph = await loadGraph(config, source);
     return renderSearch(graph, query, {
       kind,
       decorator: String(args?.decorator || "").trim(),
@@ -333,36 +356,30 @@ export async function dispatchTool(name, args, { config, source = defaultSource
   if (name === "tmct_members") {
     const symbol = String(args?.class || "").trim();
     if (!symbol) throw new ToolError("class is required");
-    const graph = await loadGraph(config, source);
-    const { match } = resolveOrThrow(graph, symbol, "class");
+    const { match } = resolveOrThrow(svc, symbol, "class");
     return renderMembers(graph, match);
   }
   if (name === "tmct_subclasses") {
     const symbol = String(args?.class || "").trim();
     if (!symbol) throw new ToolError("class is required");
-    const graph = await loadGraph(config, source);
-    const { match } = resolveOrThrow(graph, symbol, "class");
+    const { match } = resolveOrThrow(svc, symbol, "class");
     return renderSubclasses(graph, match);
   }
   if (name === "tmct_architecture") {
-    const graph = await loadGraph(config, source);
     return renderArchitecture(graph, { pkg: String(args?.package || "").trim() });
   }
   if (name === "tmct_exports") {
     const module = String(args?.module || "").trim();
     if (!module) throw new ToolError("module is required");
-    const graph = await loadGraph(config, source);
-    const { match } = resolveOrThrow(graph, module, "module");
+    const { match } = resolveOrThrow(svc, module, "module");
     return renderExports(graph, match);
   }
   if (name === "tmct_untested") {
-    const graph = await loadGraph(config, source);
     return renderUntested(graph);
   }
   if (name === "tmct_ask") {
     const query = String(args?.query || "").trim();
     if (!query) throw new ToolError("query is required");
-    const graph = await loadGraph(config, source);
     const { content, tmct_ask } = ask(graph, query);
     // Every dispatchTool caller (the chat surface, the CLI fallback) expects a plain string —
     // append the structured envelope as a delimited, machine-parseable block rather than
@@ -376,8 +393,7 @@ export async function dispatchTool(name, args, { config, source = defaultSource
   ) {
     const symbol = String(args?.symbol || "").trim();
     if (!symbol) throw new ToolError("symbol is required");
-    const graph = await loadGraph(config, source);
-    const { match } = resolveOrThrow(graph, symbol, "symbol");
+    const { match } = resolveOrThrow(svc, symbol, "symbol");
     if (name === "tmct_tests_for") return renderTestsFor(graph, match);
     if (name === "tmct_history") return renderHistory(graph, match);
     if (name === "tmct_callers") return renderCallers(graph, match);

package/src/sessions.mjs

@@ -4,7 +4,7 @@
 //   .tmct/session-<uuidv7>.log            — the human-readable transcript (chat.mjs)
 //   .tmct/sessions/session-<uuidv7>.jsonl — the STRUCTURED sidecar this module owns:
 //     {"type":"session", id, started, repo, tmctVersion}        (header line)
-//     {"type":"turn", ts, query, resolvedIds, answeredIds, miss}  (one per turn, flushed)
+//     {"type":"turn", ts, query, via, resolvedIds, answeredIds, miss}  (one per turn, flushed)
 //     {"type":"end", ts}                                          (clean close marker)
 //
 // From the sidecar the session enters the typed graph twice:
@@ -24,7 +24,8 @@
 // rather than re-deriving them from source.
 
 import { mkdir, readFile, readdir, rename, writeFile } from "node:fs/promises";
-import { dirname, join } from "node:path";
+import { basename, dirname, join } from "node:path";
+import { appendUtterances, CREATED_AT_PROP } from "./memory/core.mjs";
 
 export const SESSIONS_DIR_REL = join(".tmct", "sessions");
 
@@ -72,6 +73,10 @@ export function upsertSession(entities, record) {
   entities.individuals ||= [];
   entities.objectProperties ||= [];
 
+  // capture the prior copy's createdAt BEFORE we drop it — first-write-wins so
+  // mgx:createdAt records when the session was FIRST seen, not last re-appended.
+  const priorSession = entities.individuals.find((i) => i?.id === sid);
+  const priorCreatedAt = priorSession?.attributes?.find((a) => a?.prop === CREATED_AT_PROP)?.value || "";
   // replace any prior copy of this session (read-time appends run once per turn)
   entities.individuals = entities.individuals.filter((i) => i?.id !== sid);
   let group = entities.objectProperties.find((g) => g?.prop === ASKS_ABOUT_PROP);
@@ -110,6 +115,8 @@ export function upsertSession(entities, record) {
     id: sid, label, class: SESSION_CLASS,
     derived_from: [], mentions: [],
     attributes: [
+      // referenced via the imported constant (single-sourced from memory/core.mjs)
+      { prop: CREATED_AT_PROP, key: "createdAt", value: priorCreatedAt || started || new Date().toISOString() },
       { prop: "mgx:sessionStarted", key: "started", value: started },
       { prop: "mgx:sessionEnded", key: "ended", value: ended },
       { prop: "mgx:sessionTurns", key: "turns", value: String(turns.length) },
@@ -144,8 +151,13 @@ export function upsertSession(entities, record) {
  *  may have replaced it mid-session), upsert, write back atomically. A MISSING
  *  artifact is the empty-graph bootstrap: seed a minimal valid payload so the
  *  conversation itself becomes the first graph write. Still throws on an invalid
- *  (unparseable) artifact — the caller treats the append as best-effort. */
-export async function appendSessionToGraph(graphFile, record) {
+ *  (unparseable) artifact — the caller treats the append as best-effort.
+ *
+ *  Signature stays backward-compatible: chat.mjs passes (graphFile, record)
+ *  exactly as before. The optional third param only tunes the MEMORY side-write
+ *  (below): `repoDir` overrides the derived repo root, `memory: false` disables
+ *  the side-write entirely. */
+export async function appendSessionToGraph(graphFile, record, { memory = true, repoDir = null } = {}) {
   let text = null;
   try {
     text = await readFile(graphFile, "utf8");
@@ -161,9 +173,83 @@ export async function appendSessionToGraph(graphFile, record) {
   }
   const res = upsertSession(entities, record);
   await atomicWriteJson(graphFile, entities);
+  // ALSO record the turn(s) into tmct's OWN memory graph (.tmct/memory/ — item 9),
+  // and fold the transcript into the text-block corpus once the session has ended.
+  // Best-effort by design: memory must never degrade the graph append that already
+  // succeeded, so every failure here is swallowed (mirrors chat.mjs's own stance).
+  if (memory) {
+    try { await recordSessionMemory(graphFile, record, repoDir); } catch { /* best-effort */ }
+  }
   return res;
 }
 
+/** Derive the repo root the memory store lives under from the graph artifact's
+ *  location: the default layout is <repo>/.tmct/graph.json. A custom
+ *  TMCT_GRAPH_FILE outside a .tmct dir has no discoverable repo (and no session
+ *  transcript/sidecar layout to read), so the memory side-write is skipped —
+ *  memory writes go ONLY under a real .tmct/, never beside arbitrary files. */
+function repoDirFromGraphFile(graphFile) {
+  const tmctDir = dirname(graphFile);
+  return basename(tmctDir) === ".tmct" ? dirname(tmctDir) : null;
+}
+
+/** The memory side-write for one session append (item 9's chat wiring, placed
+ *  HERE so chat.mjs needs no change — it already calls appendSessionToGraph
+ *  every turn). Each recorded turn becomes an a-visitor-said Utterance; the
+ *  response prose is recovered from the human transcript (the only artifact
+ *  that carries answer TEXT — the sidecar records ids) and recorded alongside
+ *  as a tmct Utterance replying to it. Deterministic utterance ids make the
+ *  per-turn replay idempotent. Once the sidecar carries its end marker (chat
+ *  writes it before the final graph upsert), the session is folded into the
+ *  text-block corpus (memory/fold.mjs). */
+async function recordSessionMemory(graphFile, record, repoDirOverride = null) {
+  const repoDir = repoDirOverride ?? repoDirFromGraphFile(graphFile);
+  if (!repoDir || !record?.id) return;
+
+  let answers = new Map();
+  try {
+    answers = parseSessionLog(await readFile(join(repoDir, ".tmct", `session-${record.id}.log`), "utf8"));
+  } catch { /* no transcript (direct API callers) — record the requests alone */ }
+
+  const utterances = [];
+  for (const t of record.turns || []) {
+    const query = String(t?.query || "");
+    const ts = String(t?.ts || "");
+    if (!query || !ts) continue;
+    // the structured parse the turn produced — stored on the visitor utterance
+    const parsed = {};
+    if (t.resolvedIds?.length) parsed.resolvedIds = t.resolvedIds;
+    if (t.answeredIds?.length) parsed.answeredIds = t.answeredIds;
+    if (t.command) parsed.command = t.command;
+    if (t.miss) parsed.miss = true;
+    if (t.via) parsed.via = t.via; // answer provenance (W1) — carried into memory
+    utterances.push({
+      role: "visitor", text: query, ts, sessionId: record.id, sessionStarted: record.started || "",
+      ...(Object.keys(parsed).length ? { parsed } : {}),
+    });
+    const answer = answers.get(turnKey(ts, query));
+    if (answer) {
+      utterances.push({
+        role: "tmct", text: answer, ts, sessionId: record.id,
+        replyTo: `utt:${record.id}#${ts}#visitor`,
+      });
+    }
+  }
+  await appendUtterances(repoDir, utterances);
+
+  // Session over? The sidecar's end marker is authoritative (chat.mjs writes it
+  // before the final upsert). Fold THIS session's transcript into the corpus.
+  let ended = false;
+  try {
+    const sidecar = await readFile(join(repoDir, SESSIONS_DIR_REL, `session-${record.id}.jsonl`), "utf8");
+    ended = Boolean(parseSessionJsonl(sidecar)?.ended);
+  } catch { /* no sidecar — nothing to fold from */ }
+  if (ended) {
+    const { foldSessionLogs } = await import("./memory/fold.mjs"); // lazy: fold imports this module
+    await foldSessionLogs(repoDir, { sessionId: record.id });
+  }
+}
+
 /** Parse one sidecar .jsonl into a session record (null if no valid header).
  *  Torn/partial trailing lines (a killed session) are skipped, not fatal. */
 export function parseSessionJsonl(text) {
@@ -181,6 +267,14 @@ export function parseSessionJsonl(text) {
       turns.push({
         ts: String(rec.ts || ""), query: String(rec.query || ""),
         resolvedIds: arr(rec.resolvedIds), answeredIds: arr(rec.answeredIds), miss: !!rec.miss,
+        // preserved for the memory fold (memory/fold.mjs): slash-command turns and
+        // conversational filler are recorded but never folded into the corpus.
+        ...(rec.command ? { command: String(rec.command) } : {}),
+        ...(rec.conversational ? { conversational: true } : {}),
+        // answer provenance (W1): composed|template|count|command|conversational|
+        // assert|recall|fact|corpus — carried through so the memory side-write and
+        // any re-fold keep the banding signal the Phase-5 bench reads.
+        ...(rec.via ? { via: String(rec.via) } : {}),
       });
     } else if (rec?.type === "end") ended = String(rec.ts || "") || ended;
   }
@@ -188,6 +282,45 @@ export function parseSessionJsonl(text) {
   return { id: String(header.id), started: String(header.started || ""), ended, turns };
 }
 
+// A transcript turn opens with an ISO-8601 ms timestamp line followed by the
+// echoed "> <query>" line (chat.mjs's logLines shape).
+const LOG_TS_RE = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/;
+
+/** Key a transcript answer by its turn: ts + query (ts alone can collide when
+ *  two instant turns land in the same millisecond). */
+export const turnKey = (ts, query) => `${ts}${query}`;
+
+/**
+ * Parse a human-readable session transcript (.tmct/session-<id>.log) into a
+ * Map of turnKey(ts, query) → answer text. The transcript is the ONLY session
+ * artifact that carries the answer PROSE (the structured sidecar records ids,
+ * not text), so the memory write-path recovers response text from here.
+ * Tolerant by design: a block is `ts` line + "> query" line + answer lines
+ * until the next block; header/footer and torn tails just don't match.
+ */
+export function parseSessionLog(text) {
+  const lines = String(text ?? "").split("\n");
+  const answers = new Map();
+  let open = null; // { ts, query, answerLines }
+  const close = () => {
+    if (!open) return;
+    while (open.answerLines.length && !open.answerLines.at(-1).trim()) open.answerLines.pop();
+    answers.set(turnKey(open.ts, open.query), open.answerLines.join("\n"));
+    open = null;
+  };
+  for (let i = 0; i < lines.length; i += 1) {
+    if (LOG_TS_RE.test(lines[i]) && lines[i + 1]?.startsWith("> ")) {
+      close();
+      open = { ts: lines[i], query: lines[i + 1].slice(2), answerLines: [] };
+      i += 1;
+    } else if (open) {
+      open.answerLines.push(lines[i]);
+    }
+  }
+  close();
+  return answers;
+}
+
 /** All recorded sessions under <rootDir>/.tmct/sessions/*.jsonl, oldest first
  *  (uuidv7 filenames sort chronologically). Best-effort: no dir → []. */
 export async function readSessionRecords(rootDir) {

package/src/source.mjs

@@ -2,16 +2,39 @@
 // layer. The tool layer takes this as an injectable dependency (so tests can
 // stub it); in production it reads the JSON artifact the deterministic indexer
 // wrote to config.graphFile. No network, no model calls.
+//
+// This module is the PROVIDER SEAM (ROADMAP item 14, docs/adapter-contract.md):
+// any graph producer can feed tmct either by writing the entities-payload JSON
+// where config.graphFile points, or by registering a custom loader with
+// registerProvider() — no indexer is ever imported here. tmct only READS
+// through this seam; its own writes go to .tmct/memory/ (src/memory/), never
+// back into a provider's artifact.
 
 import { readFile } from "node:fs/promises";
 import { ToolError } from "./config.mjs";
 
 let cache = null; // { file, payload } — one artifact per process; cheap re-reads.
+let provider = null; // registered custom loader (config) => entities payload | Promise
 
 export function clearCache() {
   cache = null;
 }
 
+/** Register a custom graph provider: an async (or sync) `(config) => payload`
+ *  returning the entities-payload shape documented in docs/adapter-contract.md.
+ *  Pass `null` to restore the default file loader. Returns the PREVIOUS
+ *  provider (so a caller can wrap or restore it). The read cache is cleared
+ *  either way — a provider swap must never serve the old source's payload. */
+export function registerProvider(fn) {
+  if (fn != null && typeof fn !== "function") {
+    throw new TypeError("registerProvider expects a function (config) => entities payload, or null");
+  }
+  const prev = provider;
+  provider = fn ?? null;
+  cache = null;
+  return prev;
+}
+
 /** The empty-graph bootstrap payload: what a repo with no artifact "contains".
  *  Shaped exactly like a buildEntities payload so parseEntities and the session
  *  upsert treat it as a normal (just empty) graph. `bootstrap: true` marks it. */
@@ -27,12 +50,28 @@ export function emptyEntities() {
   };
 }
 
-/** Read + parse the local graph artifact. Cached per file for the process.
- *  A MISSING artifact (ENOENT) is not an error: the chat surface starts from an
- *  empty graph and the first session fold-in creates the file — so we return the
- *  bootstrap payload (uncached, so the freshly written file is picked up next
- *  fetch). Every other failure still throws a clean ToolError. */
+/** Fetch the entities payload through the provider seam. With a registered
+ *  provider, its result is returned as-is (uncached — a live provider owns its
+ *  own caching/refresh policy); a non-object result is a clean ToolError.
+ *  Default: read + parse the local graph artifact, cached per file for the
+ *  process. A MISSING artifact (ENOENT) is not an error: the chat surface
+ *  starts from an empty graph and the first session fold-in creates the file —
+ *  so we return the bootstrap payload (uncached, so the freshly written file is
+ *  picked up next fetch). Every other failure still throws a clean ToolError. */
 export async function fetchEntities(config) {
+  if (provider) {
+    let payload;
+    try {
+      payload = await provider(config);
+    } catch (e) {
+      if (e instanceof ToolError) throw e;
+      throw new ToolError(`graph provider failed (${e?.message || e})`);
+    }
+    if (!payload || typeof payload !== "object") {
+      throw new ToolError("graph provider returned no entities payload");
+    }
+    return payload;
+  }
   if (cache && cache.file === config.graphFile) return cache.payload;
   let text;
   try {

package/src/toml-config.mjs

@@ -87,6 +87,20 @@ export async function normalizeConfig(raw, { configDir } = {}) {
     cfg.outRoot = resolve(dir, String(src.out_root));
   }
 
+  // `tmct init` onboarding keys (ROADMAP Phase 8). Sparse like the rest: only a
+  // key actually present appears, so "unset" stays distinguishable from "set to
+  // the default". `graph_file` is resolved against configDir to match outRoot.
+  if (src.graph_file !== undefined) {
+    cfg.graphFile = resolve(dir, String(src.graph_file));
+  }
+  const corpus = src.corpus || {};
+  if (corpus.tier !== undefined) cfg.corpus = { tier: corpus.tier };
+  const seed = src.seed || {};
+  const seedCfg = {};
+  if (seed.enabled !== undefined) seedCfg.enabled = seed.enabled;
+  if (seed.limit !== undefined) seedCfg.limit = seed.limit;
+  if (Object.keys(seedCfg).length) cfg.seed = seedCfg;
+
   const idx = src.index || {};
   const index = {};
   if (idx.languages !== undefined) index.languages = idx.languages;

package/src/tui/app.mjs

@@ -0,0 +1,173 @@
+// tui/app.mjs — the Ink full-screen chat shell (the default on a TTY).
+//
+// The claude-code feel: an alternate-screen, full-height layout with a scrolling
+// transcript pane (each visitor line echoed under the prompt it was typed at,
+// the answer below it), a bottom input line carrying the live `tmct> ` /
+// `tmct(label)> ` focus prompt, and a thin status bar (repo · module count ·
+// session id · an honest "no graph — starting empty" when bootstrapping).
+//
+// EVERY turn goes through the SAME createSession sink (src/chat.mjs) the plain
+// readline shell uses — the transcript log, structured sidecar, per-turn graph
+// upsert and memory side-write are byte-identical to `--plain`; only the
+// screen drawing differs. Slash-commands work unchanged (they're session.turn's
+// job); `/exit` and a conversational "bye" end the session; Ctrl+C exits
+// cleanly through the same close() (Ink's exitOnCtrlC → waitUntilExit → close).
+//
+// Library decision (ROADMAP Phase 1 shell work): Ink 7 + React 19 — plain Node
+// ESM, no JSX/build step (React.createElement throughout). OpenTUI was ruled
+// out for now: @opentui/core depends on Bun FFI (bun-ffi-structs / a native Zig
+// renderer), so it doesn't run under plain Node; revisit when it does.
+//
+// The view-model is PURE and exported (statusText, appendTurn, transcriptLines,
+// wrapLines) so node:test exercises it without a terminal; the component tree
+// is thin glue over it.
+
+import React, { useEffect, useState } from "react";
+import { render, Box, Text, useApp, useInput, useStdout } from "ink";
+import { createSession } from "../chat.mjs";
+
+const h = React.createElement;
+
+/** The thin status-bar text: repo · module count · session id (short, like the
+ *  Session graph label) — plus the honest bootstrap note when the graph is empty. */
+export function statusText({ repo, moduleCount, sessionId, empty }) {
+  const parts = [String(repo), `${moduleCount} module(s)`, `session ${String(sessionId).slice(0, 8)}`];
+  if (empty) parts.push("no graph — starting empty");
+  return parts.join(" · ");
+}
+
+/** Append one completed turn to the transcript model (pure — returns a new array).
+ *  `prompt` is the prompt the question was typed at (so a focus label is preserved
+ *  in the echo, exactly like a scrolled readline session reads). */
+export function appendTurn(items, { prompt, query, answer }) {
+  return [...items, { kind: "q", prompt: String(prompt), text: String(query) }, { kind: "a", text: String(answer) }];
+}
+
+/** Flatten the transcript model to display lines: the echoed `tmct> question`
+ *  line, the answer's own lines, and a blank separator after each turn —
+ *  mirroring the transcript log's visual rhythm. */
+export function transcriptLines(items) {
+  const lines = [];
+  for (const item of items) {
+    if (item.kind === "q") lines.push(`${item.prompt}${item.text}`);
+    else { lines.push(...String(item.text).split("\n")); lines.push(""); }
+  }
+  return lines;
+}
+
+/** Hard-wrap display lines at `width` columns so the pane's line budget is honest
+ *  (Ink would soft-wrap and overflow the fixed-height layout otherwise). */
+export function wrapLines(lines, width) {
+  const w = Math.max(1, Number(width) || 80);
+  const out = [];
+  for (const line of lines) {
+    let s = String(line);
+    if (s.length <= w) { out.push(s); continue; }
+    while (s.length > w) { out.push(s.slice(0, w)); s = s.slice(w); }
+    out.push(s);
+  }
+  return out;
+}
+
+/** Terminal size, live across resizes (falls back to 80×24 off-TTY). */
+function useTerminalSize() {
+  const { stdout } = useStdout();
+  const size = () => ({ columns: stdout?.columns || 80, rows: stdout?.rows || 24 });
+  const [dim, setDim] = useState(size);
+  useEffect(() => {
+    if (!stdout) return undefined;
+    const onResize = () => setDim(size());
+    stdout.on("resize", onResize);
+    return () => stdout.off("resize", onResize);
+  }, [stdout]);
+  return dim;
+}
+
+/** The Ink app over one createSession sink. Owns only VIEW state — the session
+ *  (focus, files, records) lives in the sink, exactly as in the readline shell. */
+export function App({ session }) {
+  const { exit } = useApp();
+  const { columns, rows } = useTerminalSize();
+  const [items, setItems] = useState([]);
+  const [input, setInput] = useState("");
+  const [prompt, setPrompt] = useState(session.promptFor());
+  const [busy, setBusy] = useState(false);
+
+  const submit = async (line) => {
+    if (line === "/exit") { exit(); return; }
+    setBusy(true);
+    const echoedAt = prompt; // the prompt the question was typed at, kept in the echo
+    try {
+      const { answer, end, prompt: nextPrompt } = await session.turn(line);
+      setItems((prev) => appendTurn(prev, { prompt: echoedAt, query: line, answer }));
+      setPrompt(nextPrompt);
+      if (end) { exit(); return; } // a conversational "bye" — same clean end as /exit
+    } finally {
+      setBusy(false);
+    }
+  };
+
+  const trySubmit = (raw) => {
+    if (busy) return; // one turn at a time — the engine is deterministic and fast
+    const line = String(raw).trim();
+    setInput("");
+    if (line) void submit(line);
+  };
+
+  useInput((ch, key) => {
+    if (key.return) { trySubmit(input); return; }
+    if (key.backspace || key.delete) { setInput((s) => s.slice(0, -1)); return; }
+    if (key.ctrl && ch === "u") { setInput(""); return; }
+    if (key.ctrl || key.meta || key.escape || key.tab || key.upArrow || key.downArrow || key.leftArrow || key.rightArrow) return;
+    if (!ch) return;
+    // A PASTED chunk arrives as one multi-char event; a newline inside it means
+    // "submit this line" (one line per turn — the readline shell's per-line read).
+    const nl = ch.search(/[\r\n]/);
+    if (nl === -1) { setInput((s) => s + ch); return; }
+    trySubmit(input + ch.slice(0, nl));
+  });
+
+  // The pane's line budget: full height minus the input line and the status bar.
+  const paneRows = Math.max(1, rows - 2);
+  const banner = { kind: "a", text: session.bannerLines.join("\n") }; // one block, one separator
+  const allLines = wrapLines(transcriptLines([banner, ...items]), columns);
+  const visible = allLines.slice(-paneRows);
+
+  return h(Box, { flexDirection: "column", height: rows, width: columns },
+    h(Box, { flexDirection: "column", height: paneRows, overflow: "hidden" },
+      ...visible.map((line, i) =>
+        h(Text, { key: `l${i}`, wrap: "truncate-end" }, line === "" ? " " : line)),
+    ),
+    h(Box, { height: 1 },
+      h(Text, { wrap: "truncate-end" },
+        h(Text, { bold: true }, prompt),
+        input,
+        busy ? h(Text, { dimColor: true }, "…") : h(Text, { inverse: true }, " "),
+      ),
+    ),
+    h(Box, { height: 1 },
+      h(Text, { dimColor: true, wrap: "truncate-end" },
+        statusText(session), " · /help commands · /exit leaves"),
+    ),
+  );
+}
+
+/** Run the full-screen TUI over a fresh session sink: alternate screen in, Ink
+ *  render, wait for exit (Ctrl+C / /exit / bye), alternate screen out, then the
+ *  SAME session close the readline shell performs (end lines, final upsert —
+ *  which also triggers the memory fold — stream flush). Returns
+ *  { logFile, sidecarFile, turns } exactly like runChat. */
+export async function runTui({ repoPath, stdout = process.stdout, stdin = process.stdin, ...sessionOpts } = {}) {
+  const session = await createSession({ repoPath, ...sessionOpts });
+  stdout.write("\x1b[?1049h\x1b[H"); // alternate screen buffer + home — a clean full-screen canvas
+  const app = render(h(App, { session }), { stdout, stdin, exitOnCtrlC: true });
+  try {
+    await app.waitUntilExit();
+  } finally {
+    app.unmount();
+    stdout.write("\x1b[?1049l"); // restore the primary screen (shell scrollback intact)
+    await session.close();
+    stdout.write(`session ended — log ${session.logFile}\n`);
+  }
+  return { logFile: session.logFile, sidecarFile: session.sidecarFile, turns: session.turns };
+}