@lifeaitools/clauth 2.1.1 → 2.10.1

package/cli/services/git-exec.test.js

@@ -0,0 +1,41 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { execFileSync } from "node:child_process";
+
+import { runGit, runGitRaw } from "./git-exec.js";
+
+function withRepo(fn) {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), "clauth-git-exec-test-"));
+  execFileSync("git", ["init", "-q"], { cwd: dir });
+  execFileSync("git", ["config", "user.email", "t@t.com"], { cwd: dir });
+  execFileSync("git", ["config", "user.name", "t"], { cwd: dir });
+  execFileSync("git", ["commit", "-q", "--allow-empty", "-m", "first"], { cwd: dir });
+  try { return fn(dir); } finally { fs.rmSync(dir, { recursive: true, force: true }); }
+}
+
+test("runGit returns trimmed stdout on success", () =>
+  withRepo((dir) => {
+    const branch = runGit(dir, ["rev-parse", "--abbrev-ref", "HEAD"]);
+    assert.equal(typeof branch, "string");
+    assert.ok(branch.length > 0, "must resolve to a real branch name, not an empty string");
+    assert.equal(branch, branch.trim(), "must be trimmed — no trailing newline from git's own stdout");
+  }));
+
+test("runGit throws with git's stderr on a non-zero exit", () =>
+  withRepo((dir) => {
+    assert.throws(() => runGit(dir, ["rev-parse", "--verify", "refs/heads/does-not-exist"]), /failed/);
+  }));
+
+test("runGitRaw returns a Buffer, not a string", () =>
+  withRepo((dir) => {
+    const out = runGitRaw(dir, ["rev-parse", "HEAD"]);
+    assert.ok(Buffer.isBuffer(out));
+  }));
+
+test("runGitRaw throws on a non-zero exit, same as runGit", () =>
+  withRepo((dir) => {
+    assert.throws(() => runGitRaw(dir, ["rev-parse", "--verify", "refs/heads/does-not-exist"]), /failed/);
+  }));

package/cli/services/git-import-guard.js

@@ -0,0 +1,28 @@
+// cli/services/git-import-guard.js
+// Path-safety guards for fs_import_git_files: normalize a repo-relative path
+// (reject traversal/absolute), and check it against the allowed-prefix
+// allowlist. Split out of fs-mount.js for SRP — this is a path-validation
+// concern, not a filesystem-mount concern.
+
+import path from "node:path";
+
+export const FS_GIT_IMPORT_ALLOWED_PREFIXES = [
+  "docs/",
+  ".rdc/plans/",
+  ".rdc/guides/",
+  ".claude/context/",
+  ".claude/rules/",
+  ".rdc/relay/from-claude-ai/",
+];
+
+export function normalizeRepoPath(p) {
+  if (!p || typeof p !== "string") return null;
+  const normalized = p.replace(/\\/g, "/").replace(/^\/+/, "");
+  const parts = normalized.split("/").filter(Boolean);
+  if (parts.length === 0 || parts.includes("..") || path.isAbsolute(p)) return null;
+  return parts.join("/");
+}
+
+export function isAllowedGitImportPath(p, allowedPrefixes = FS_GIT_IMPORT_ALLOWED_PREFIXES) {
+  return allowedPrefixes.some((prefix) => p === prefix.replace(/\/$/, "") || p.startsWith(prefix));
+}

package/cli/services/git-import-guard.test.js

@@ -0,0 +1,18 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+
+import { normalizeRepoPath, isAllowedGitImportPath, FS_GIT_IMPORT_ALLOWED_PREFIXES } from "./git-import-guard.js";
+
+test("normalizeRepoPath rejects absolute paths and path traversal", () => {
+  assert.equal(normalizeRepoPath("docs/README.md"), "docs/README.md");
+  assert.equal(normalizeRepoPath("../outside.txt"), null);
+  assert.equal(normalizeRepoPath("C:/Dev/regen-root/x"), null, "an absolute path must be rejected, not silently accepted");
+  assert.equal(normalizeRepoPath(""), null);
+});
+
+test("isAllowedGitImportPath only allows the declared prefix set by default", () => {
+  assert.equal(isAllowedGitImportPath("docs/README.md"), true);
+  assert.equal(isAllowedGitImportPath(".rdc/plans/foo.md"), true);
+  assert.equal(isAllowedGitImportPath("apps/lifeai/secret.env"), false);
+  assert.ok(FS_GIT_IMPORT_ALLOWED_PREFIXES.includes("docs/"));
+});

package/cli/services/service-status.js

@@ -0,0 +1,191 @@
+// cli/services/service-status.js
+// Cached vault service-status lookup + text/address search over it.
+// Shared by both the HTTP routes (/status, /search, /knowledge) and the MCP
+// tools (clauth_status, clauth_search, clauth_knowledge) in serve.js — one
+// module, one cache, one reason to change.
+
+import { deriveToken } from "../fingerprint.js";
+import * as api from "../api.js";
+export const ENV_MAP = {
+  "github":           "GITHUB_TOKEN",
+  "supabase-anon":    "NEXT_PUBLIC_SUPABASE_ANON_KEY",
+  "supabase-service": "SUPABASE_SERVICE_ROLE_KEY",
+  "supabase-db":      "SUPABASE_DB_URL",
+  "vercel":           "VERCEL_TOKEN",
+  "anthropic":        "ANTHROPIC_API_KEY",
+  "cloudflare":       "CLOUDFLARE_API_TOKEN",
+  "r2":               "R2_ACCESS_KEY_ID",
+  "r2-bucket":        "R2_BUCKET_NAME",
+  "neo4j":            "NEO4J_URI",
+  "rocketreach":      "ROCKETREACH_API_KEY",
+  "npm":              "NPM_TOKEN",
+  "namecheap":        "NAMECHEAP_API_KEY",
+  "gmail":            "GMAIL_CREDENTIALS",
+};
+
+const ADDRESS_KEY_TYPES = new Set(["connstring", "fileserver", "oauth"]);
+const ADDRESS_FIELDS = new Set(["url", "uri", "host", "hostname", "server", "address", "base_url", "endpoint", "path", "root"]);
+const SERVICE_STATUS_CACHE_TTL_MS = 30_000;
+const serviceStatusCache = new Map();
+
+function serviceStatusCacheKey(machineHash, project) {
+  return `${machineHash || "unknown"}::${project || ""}`;
+}
+
+function cloneJson(value) {
+  return JSON.parse(JSON.stringify(value));
+}
+
+export function invalidateServiceStatusCache(machineHash) {
+  const prefix = `${machineHash || "unknown"}::`;
+  for (const key of serviceStatusCache.keys()) {
+    if (key.startsWith(prefix)) serviceStatusCache.delete(key);
+  }
+}
+
+export function sanitizeServiceMetadata(service) {
+  return {
+    name: service.name,
+    label: service.label || null,
+    key_type: service.key_type || null,
+    enabled: !!service.enabled,
+    has_key: !!(service.has_key ?? service.vault_key),
+    last_retrieved: service.last_retrieved || null,
+    last_rotated: service.last_rotated || null,
+    created_at: service.created_at || null,
+    project: service.project || null,
+    description: service.description || null,
+  };
+}
+
+export async function getCachedServiceStatus({ password, machineHash, token, timestamp, project, whitelist, force = false }) {
+  if (!password) return { error: "Vault is locked" };
+  const key = serviceStatusCacheKey(machineHash, project);
+  const now = Date.now();
+  let cached = serviceStatusCache.get(key);
+
+  if (!force && cached && now - cached.at < SERVICE_STATUS_CACHE_TTL_MS) {
+    const payload = cloneJson(cached.payload);
+    if (whitelist) payload.services = (payload.services || []).filter(s => whitelist.includes(String(s.name || "").toLowerCase()));
+    payload.cached = true;
+    payload.cache_ttl_ms = SERVICE_STATUS_CACHE_TTL_MS;
+    return payload;
+  }
+
+  const auth = token && timestamp ? { token, timestamp } : deriveToken(password, machineHash);
+  const result = await api.status(password, machineHash, auth.token, auth.timestamp, project);
+  if (result.error) return result;
+
+  const payload = {
+    ...result,
+    services: result.services || [],
+  };
+  serviceStatusCache.set(key, { at: now, payload: cloneJson(payload) });
+
+  const output = cloneJson(payload);
+  if (whitelist) output.services = (output.services || []).filter(s => whitelist.includes(String(s.name || "").toLowerCase()));
+  output.cached = false;
+  output.cache_ttl_ms = SERVICE_STATUS_CACHE_TTL_MS;
+  return output;
+}
+
+function normalizeSearchText(value) {
+  return String(value || "").toLowerCase();
+}
+
+function redactUrlish(value) {
+  const text = String(value || "").trim();
+  if (!text) return "";
+  try {
+    const url = new URL(text);
+    if (url.username) url.username = "***";
+    if (url.password) url.password = "***";
+    return url.toString();
+  } catch {
+    return text.replace(/:\/\/([^:@/\s]+):([^@/\s]+)@/g, "://***:***@");
+  }
+}
+
+function collectAddressHints(value, keyType) {
+  if (!ADDRESS_KEY_TYPES.has(String(keyType || "").toLowerCase())) return [];
+  const hints = new Set();
+
+  function add(candidate) {
+    if (candidate === undefined || candidate === null) return;
+    const text = redactUrlish(candidate);
+    if (text) hints.add(text);
+  }
+
+  function walk(node, fieldName = "") {
+    if (node === undefined || node === null) return;
+    if (typeof node === "string") {
+      if (fieldName && ADDRESS_FIELDS.has(fieldName.toLowerCase())) add(node);
+      if (/^[a-z][a-z0-9+.-]*:\/\//i.test(node) || /^[A-Za-z]:[\\/]/.test(node) || node.startsWith("\\\\")) add(node);
+      return;
+    }
+    if (Array.isArray(node)) {
+      for (const item of node) walk(item, fieldName);
+      return;
+    }
+    if (typeof node === "object") {
+      for (const [key, child] of Object.entries(node)) walk(child, key);
+    }
+  }
+
+  try {
+    walk(JSON.parse(value));
+  } catch {
+    walk(value);
+  }
+
+  return [...hints];
+}
+
+export async function searchServices({ password, machineHash, token, timestamp, query, project, includeAddresses = false, whitelist, forceStatusRefresh = false }) {
+  const q = normalizeSearchText(query);
+  if (!q) return { error: "query is required" };
+
+  const result = await getCachedServiceStatus({ password, machineHash, token, timestamp, project, whitelist, force: forceStatusRefresh });
+  if (result.error) return { error: result.error };
+
+  let services = result.services || [];
+
+  const matches = [];
+  for (const s of services) {
+    const fields = {
+      name: s.name,
+      label: s.label,
+      project: s.project,
+      type: s.key_type,
+      description: s.description
+    };
+    const matched = Object.entries(fields)
+      .filter(([, value]) => normalizeSearchText(value).includes(q))
+      .map(([field]) => field);
+
+    let addressHints = [];
+    if (includeAddresses && ADDRESS_KEY_TYPES.has(String(s.key_type || "").toLowerCase()) && (s.has_key || s.vault_key)) {
+      const secret = await api.retrieve(password, machineHash, token, timestamp, s.name);
+      if (!secret.error) {
+        addressHints = collectAddressHints(secret.value, s.key_type);
+        if (addressHints.some(h => normalizeSearchText(h).includes(q))) matched.push("address");
+      }
+    }
+
+    if (matched.length) {
+      matches.push({
+        name: s.name,
+        label: s.label || null,
+        project: s.project || null,
+        key_type: s.key_type,
+        enabled: !!s.enabled,
+        has_key: !!(s.has_key || s.vault_key),
+        description: s.description || null,
+        matched: [...new Set(matched)],
+        address_hints: addressHints
+      });
+    }
+  }
+
+  return { query, count: matches.length, matches };
+}

package/cli/services/service-status.test.js

@@ -0,0 +1,39 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+
+import {
+  ENV_MAP,
+  invalidateServiceStatusCache,
+  sanitizeServiceMetadata,
+  getCachedServiceStatus,
+  searchServices,
+} from "./service-status.js";
+
+test("sanitizeServiceMetadata strips a service down to safe display fields", () => {
+  const out = sanitizeServiceMetadata({
+    name: "github", label: "GitHub", key_type: "token", enabled: true,
+    vault_key: "some-internal-key-name", last_retrieved: "2026-01-01T00:00:00Z",
+  });
+  assert.equal(out.name, "github");
+  assert.equal(out.has_key, true, "has_key must derive from vault_key when has_key itself is absent");
+  assert.equal(out.vault_key, undefined, "the raw vault key name must never appear in sanitized metadata");
+});
+
+test("getCachedServiceStatus refuses without a password rather than hitting the vault", async () => {
+  const result = await getCachedServiceStatus({ password: null, machineHash: "h" });
+  assert.equal(result.error, "Vault is locked");
+});
+
+test("invalidateServiceStatusCache is a safe no-op with no cache entries yet", () => {
+  assert.doesNotThrow(() => invalidateServiceStatusCache("some-machine-hash"));
+});
+
+test("searchServices requires a non-empty query", async () => {
+  const result = await searchServices({ password: "pw", machineHash: "h", query: "" });
+  assert.equal(result.error, "query is required");
+});
+
+test("ENV_MAP names the expected env var for well-known services", () => {
+  assert.equal(ENV_MAP.github, "GITHUB_TOKEN");
+  assert.equal(ENV_MAP.anthropic, "ANTHROPIC_API_KEY");
+});

package/cli/services/terminal-dispatch.js

@@ -0,0 +1,135 @@
+// cli/services/terminal-dispatch.js
+// Sends a message into a terminal session (warm-pool dispatch or cold spawn
+// fallback) and reads back the response. Split out of terminal-sessions.js --
+// the SOLID scorer flagged that file's original shape as mixing this
+// message-dispatch concern with shared-registry state, session lifecycle, and
+// Windows-window control.
+
+import { spawn as spawnProc } from "node:child_process";
+import { getAgentPool } from "./agent-pool-instance.js";
+import { findClaudeBinary, CHITCHAT_FALLBACK_CWD } from "./claude-binary.js";
+import { terminalSessions } from "./terminal-registry.js";
+
+export function sendTerminalMessage(session_id, message) {
+  const session = terminalSessions.get(session_id);
+  if (!session) return { error: 'not_found', message: `Session ${session_id} not found` };
+  if (session.status === 'stopped') return { error: 'stopped', message: 'Session is stopped' };
+  if (session.status === 'busy') return { error: 'session_busy', message: 'Session is busy — try again shortly' };
+
+  const nextTurn = (session.turn || 0) + 1;
+  session.lastResponse = undefined;
+  session.lastResponseAt = null;
+  session.pendingTurn = nextTurn;
+
+  // ── Warm-pool path: dispatch to the pinned worker (maintains its own context) ──
+  if (session.warmWorker && !session.warmWorker.isDead()) {
+    session.status = 'busy';
+    const pool = getAgentPool();
+    pool.dispatchToSession(session_id, { prompt: message })
+      .then((result) => {
+        if (!terminalSessions.has(session_id)) return;
+        const s = terminalSessions.get(session_id);
+        const response = result.ok
+          ? (result.package || '').trim() || '(no output)'
+          : `(warm dispatch error: ${result.error || 'unknown'})`;
+        // Still update rolling context for terminal_recv compatibility
+        const turn = `\n\nUser: ${message}\nAssistant: ${response}`;
+        const combined = s.context + turn;
+        s.context = combined.length > 8000 ? combined.slice(combined.length - 8000) : combined;
+        s.lastResponse = response;
+        s.lastResponseAt = new Date().toISOString();
+        s.turn = s.pendingTurn || ((s.turn || 0) + 1);
+        s.pendingTurn = null;
+        s.status = 'ready';
+        s.activeProc = null;
+        console.log(`[terminal] session ${session_id} turn=${s.turn} complete (warm) ok=${result.ok}`);
+
+        // If the warm worker died during dispatch, clear it so next turn falls back to cold
+        if (!result.ok && result.error === 'pinned_worker_died') {
+          s.warmWorker = null;
+          console.log(`[terminal] session ${session_id} warm worker died, next turn will use cold path`);
+        }
+      })
+      .catch((err) => {
+        if (!terminalSessions.has(session_id)) return;
+        const s = terminalSessions.get(session_id);
+        s.lastResponse = `(warm dispatch failed: ${err.message})`;
+        s.lastResponseAt = new Date().toISOString();
+        s.turn = s.pendingTurn || ((s.turn || 0) + 1);
+        s.pendingTurn = null;
+        s.status = 'ready';
+        s.activeProc = null;
+        s.warmWorker = null; // fall back to cold on next turn
+        console.log(`[terminal] session ${session_id} warm dispatch threw, falling back to cold: ${err.message}`);
+      });
+    return { queued: true, session_id, warm: true, turn: nextTurn };
+  }
+
+  // ── Cold-spawn fallback: original path ──
+  const binary = findClaudeBinary();
+  if (!binary) return { error: 'binary_not_found', message: 'claude CLI not found in PATH or AppData/npm' };
+
+  session.status = 'busy';
+  const isCmdShim = process.platform === "win32" && /\.cmd$/i.test(binary);
+  const command = isCmdShim ? "cmd" : binary;
+  const args = isCmdShim
+    ? ["/d", "/s", "/c", `"${binary}"`, "-p", message, "--system-prompt", session.context, "--setting-sources", "user", "--dangerously-skip-permissions"]
+    : ["-p", message, "--system-prompt", session.context, "--setting-sources", "user", "--dangerously-skip-permissions"];
+  const proc = spawnProc(command, args, {
+    cwd: session.cwd || CHITCHAT_FALLBACK_CWD,
+    env: process.env,
+    stdio: ['ignore', 'pipe', 'pipe'],
+    shell: false,
+    windowsHide: true,
+  });
+  session.activeProc = proc;
+
+  let stdout = '';
+  let stderr = '';
+  proc.stdout.on('data', d => { stdout += d; });
+  proc.stderr.on('data', d => { stderr += d; });
+  proc.on('close', (code) => {
+    if (terminalSessions.has(session_id)) {
+      const s = terminalSessions.get(session_id);
+      const response = stdout.trim() || stderr.trim() || '(no output)';
+      // Append turn to rolling context (cap at ~8000 chars to avoid overflow)
+      const turn = `\n\nUser: ${message}\nAssistant: ${response}`;
+      const combined = s.context + turn;
+      s.context = combined.length > 8000 ? combined.slice(combined.length - 8000) : combined;
+      s.lastResponse = response;
+      s.lastResponseAt = new Date().toISOString();
+      s.turn = s.pendingTurn || ((s.turn || 0) + 1);
+      s.pendingTurn = null;
+      s.status = 'ready';
+      s.activeProc = null;
+      console.log(`[terminal] session ${session_id} turn=${s.turn} complete code=${code}`);
+    }
+  });
+
+  return { queued: true, session_id, warm: false, turn: nextTurn };
+}
+
+export function recvTerminalResponse(session_id, timeout_ms = 30000) {
+  const session = terminalSessions.get(session_id);
+  if (!session) return { error: 'not_found', message: `Session ${session_id} not found` };
+
+  // If already ready with a response, return it immediately
+  if (session.status === 'ready' && session.lastResponse !== undefined) {
+    return {
+      session_id,
+      status: 'ready',
+      turn: session.turn || 0,
+      response: session.lastResponse,
+      responded_at: session.lastResponseAt,
+    };
+  }
+
+  // Session is still busy — caller should poll again
+  return {
+    session_id,
+    status: session.status,
+    turn: session.turn || 0,
+    response: null,
+    message: session.status === 'busy' ? 'Still processing — poll again in a few seconds' : 'No response yet',
+  };
+}

package/cli/services/terminal-dispatch.test.js

@@ -0,0 +1,9 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+
+import { recvTerminalResponse } from "./terminal-dispatch.js";
+
+test("recvTerminalResponse reports not_found for an unknown session", () => {
+  const result = recvTerminalResponse("does-not-exist");
+  assert.equal(result.error, "not_found");
+});

package/cli/services/terminal-registry.js

@@ -0,0 +1,39 @@
+// cli/services/terminal-registry.js
+// The single shared in-memory registry every session kind (plain terminal,
+// chitchat, codevelop) is stored in, plus the small stateless helpers that
+// don't belong to any one session kind. Split out of terminal-sessions.js --
+// the SOLID scorer flagged that file's original shape (72.1 total) as mixing
+// this shared-state concern with dispatch logic and Windows-window control.
+//
+// mcpHttpBaseUrl is exported as a live "let" binding + a setter: createServer()
+// sets it once the real listening port is known; ES modules do not allow an
+// IMPORTING module to reassign an imported binding directly, so the setter is
+// how serve.js updates it without a circular re-export.
+
+import crypto from "node:crypto";
+import path from "node:path";
+import os from "node:os";
+import fs from "node:fs";
+
+export const terminalSessions = new Map(); // session_id → SessionState
+export let mcpHttpBaseUrl = "http://127.0.0.1:52437";
+export function setMcpHttpBaseUrl(url) { mcpHttpBaseUrl = url; }
+
+// ── Channel webhook event queue ───────────────────────────────────────────────
+export const channelEvents = [];   // { id, event, resource, status, url, repository, created_at }
+export const MAX_CHANNEL_EVENTS = 100;
+
+export function generateSessionId() {
+  return crypto.randomUUID();
+}
+
+export function defaultTerminalCwd() {
+  const dir = process.env.CLAUTH_TERMINAL_CWD || path.join(os.tmpdir(), "clauth-terminal");
+  try {
+    fs.mkdirSync(dir, { recursive: true });
+  } catch {
+    // If the neutral directory cannot be created, fall back to the user's home.
+    return os.homedir();
+  }
+  return dir;
+}

package/cli/services/terminal-registry.test.js

@@ -0,0 +1,31 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+
+import {
+  mcpHttpBaseUrl,
+  setMcpHttpBaseUrl,
+  channelEvents,
+  MAX_CHANNEL_EVENTS,
+  generateSessionId,
+} from "./terminal-registry.js";
+
+test("generateSessionId returns distinct UUIDs", () => {
+  const a = generateSessionId();
+  const b = generateSessionId();
+  assert.notEqual(a, b);
+  assert.match(a, /^[0-9a-f-]{36}$/);
+});
+
+test("setMcpHttpBaseUrl updates the live exported binding", () => {
+  const before = mcpHttpBaseUrl;
+  setMcpHttpBaseUrl("http://127.0.0.1:9999");
+  // Re-import isn't needed -- `mcpHttpBaseUrl` is a live ES module binding,
+  // so reading the SAME imported name again reflects the setter's update.
+  assert.equal(mcpHttpBaseUrl, "http://127.0.0.1:9999");
+  setMcpHttpBaseUrl(before); // restore, since this is shared module state
+});
+
+test("channelEvents starts as an array and MAX_CHANNEL_EVENTS caps it at a sane size", () => {
+  assert.ok(Array.isArray(channelEvents));
+  assert.equal(MAX_CHANNEL_EVENTS, 100);
+});

package/cli/services/terminal-sessions.js

@@ -0,0 +1,100 @@
+// cli/services/terminal-sessions.js
+// Named persistent Claude terminal session lifecycle (start/list/stop).
+// Message dispatch moved to terminal-dispatch.js, Windows-window control
+// moved to terminal-window.js, and the shared registry (terminalSessions Map,
+// mcpHttpBaseUrl, channelEvents, generateSessionId, defaultTerminalCwd) moved
+// to terminal-registry.js after the SOLID scorer flagged this file's original
+// single-file shape (72.1 total) as mixing all four concerns.
+//
+// Sixth slice of the authorized serve.js module split.
+
+import { getAgentPool } from "./agent-pool-instance.js";
+import { findClaudeBinary } from "./claude-binary.js";
+import { terminalSessions, generateSessionId, defaultTerminalCwd } from "./terminal-registry.js";
+
+// ── Terminal session manager ─────────────────────────────────────
+// Rolling-context approach: each session stores a context string.
+// /terminal/send spawns a fresh claude -p with [context + message],
+// captures stdout, stores result back in session context.
+
+export function startTerminalSession(name, knowledge_tier, context_md, cwd, use_warm = false) {
+  const binary = findClaudeBinary();
+  if (!binary) {
+    return { error: 'binary_not_found', message: 'claude CLI not found in PATH or AppData/npm' };
+  }
+  const session_id = generateSessionId();
+  const preamble = context_md
+    ? `${context_md}\n\n---\n`
+    : '';
+  const initialContext = `${preamble}Session: ${name}, Tier: ${knowledge_tier}\nConversation transcript follows. Respond only to the final User message.`;
+  const session = {
+    session_id,
+    name,
+    knowledge_tier,
+    status: 'ready',
+    started_at: new Date().toISOString(),
+    context: initialContext,
+    activeProc: null,
+    warmWorker: null,
+    use_warm,
+    cwd: cwd || defaultTerminalCwd(),
+  };
+
+  // Try to acquire a warm worker only when explicitly requested. The warm pool
+  // is optimized for call_agent one-shots; a terminal session needs reliable
+  // repeated turns more than experimental low-latency pinning.
+  if (use_warm) {
+    try {
+      const pool = getAgentPool();
+      if (pool) {
+        const worker = pool.acquireForSession(session_id);
+        if (worker) {
+          session.warmWorker = worker;
+          console.log(`[terminal] session ${session_id} acquired warm worker`);
+        }
+      }
+    } catch (e) {
+      console.log(`[terminal] session ${session_id} warm pool unavailable, will use cold path: ${e.message}`);
+    }
+  }
+
+  terminalSessions.set(session_id, session);
+  console.log(`[terminal] started session ${session_id} name=${name} cwd=${session.cwd} warm=${!!session.warmWorker}`);
+  return { session_id, status: 'ready', warm: !!session.warmWorker };
+}
+
+export function listTerminalSessions() {
+  const sessions = [];
+  for (const [, s] of terminalSessions) {
+    sessions.push({
+      session_id: s.session_id,
+      name: s.name,
+      status: s.status,
+      knowledge_tier: s.knowledge_tier,
+      started_at: s.started_at,
+    });
+  }
+  return sessions;
+}
+
+export function stopTerminalSession(session_id) {
+  const session = terminalSessions.get(session_id);
+  if (!session) return { error: 'not_found', message: `Session ${session_id} not found` };
+  if (session.activeProc) {
+    try { session.activeProc.kill(); } catch {}
+  }
+  // Release the warm worker back to the pool
+  if (session.warmWorker) {
+    try {
+      const pool = getAgentPool();
+      pool.releaseSession(session_id);
+      console.log(`[terminal] session ${session_id} released warm worker`);
+    } catch (e) {
+      console.log(`[terminal] session ${session_id} warm worker release failed: ${e.message}`);
+    }
+    session.warmWorker = null;
+  }
+  terminalSessions.delete(session_id);
+  console.log(`[terminal] stopped session ${session_id}`);
+  return { stopped: true, session_id };
+}

package/cli/services/terminal-sessions.test.js

@@ -0,0 +1,26 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+
+import { terminalSessions } from "./terminal-registry.js";
+import { listTerminalSessions, stopTerminalSession } from "./terminal-sessions.js";
+
+test("listTerminalSessions reflects the shared terminalSessions Map directly", () => {
+  terminalSessions.clear();
+  terminalSessions.set("t1", { session_id: "t1", name: "test", status: "ready", knowledge_tier: "db_only", started_at: "2026-01-01T00:00:00Z" });
+  const list = listTerminalSessions();
+  assert.equal(list.length, 1);
+  assert.equal(list[0].session_id, "t1");
+  terminalSessions.clear();
+});
+
+test("stopTerminalSession reports not_found for an unknown session, without throwing", () => {
+  const result = stopTerminalSession("does-not-exist");
+  assert.equal(result.error, "not_found");
+});
+
+test("stopTerminalSession removes a real (non-process-backed) session from the shared Map", () => {
+  terminalSessions.set("t2", { session_id: "t2", name: "test", status: "ready", activeProc: null, warmWorker: null });
+  const result = stopTerminalSession("t2");
+  assert.equal(result.stopped, true);
+  assert.equal(terminalSessions.has("t2"), false);
+});