cli-relay 1.0.0

package/src/adapters/codex.mjs

@@ -0,0 +1,58 @@
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { ENV_BASE } from '../core/adapter-env.mjs';
+
+function findRolloutFile(threadId) {
+  const root = join(homedir(), '.codex', 'sessions');
+  if (!existsSync(root)) return null;
+  try {
+    const entries = readdirSync(root, { recursive: true });
+    const match = entries.find((entry) =>
+      typeof entry === 'string' && entry.includes(threadId) && entry.endsWith('.jsonl'));
+    return match ? join(root, match) : null;
+  } catch {
+    return null;
+  }
+}
+
+export default {
+  name: 'codex',
+  order: 10,
+  binaryCandidates: ['codex'],
+  fresh: (prompt) => [
+    'codex', 'exec', '--skip-git-repo-check', '--sandbox', 'workspace-write',
+    '-m', 'gpt-5.6-sol', '--json', prompt,
+  ],
+  // `codex exec resume` has no --sandbox flag. This is the only confirmed non-interactive
+  // path that restores the write access granted to the fresh invocation.
+  resume: (id, prompt) => [
+    'codex', 'exec', 'resume', id, '--dangerously-bypass-approvals-and-sandbox', '--json', prompt,
+  ],
+  env: ENV_BASE,
+  parse(stdout) {
+    let id = null;
+    let answer = null;
+    for (const line of stdout.split('\n')) {
+      if (!line.trim()) continue;
+      let event;
+      try { event = JSON.parse(line); } catch { continue; }
+      if (event.type === 'thread.started' && event.thread_id) id = event.thread_id;
+      if (event.type === 'item.completed' &&
+          event.item?.type === 'agent_message' && event.item.text) {
+        answer = event.item.text;
+      }
+    }
+    return { id, answer };
+  },
+  checkCompaction(id) {
+    if (!id) return false;
+    const file = findRolloutFile(id);
+    if (!file) return false;
+    try {
+      return readFileSync(file, 'utf8').includes('"context_compacted"');
+    } catch {
+      return false;
+    }
+  },
+};

package/src/adapters/command-code.mjs

@@ -0,0 +1,18 @@
+import { ENV_BASE } from '../core/adapter-env.mjs';
+import { parseJsonResult } from '../core/parse-json-result.mjs';
+
+export default {
+  name: 'command-code',
+  order: 40,
+  binaryCandidates: ['command-code'],
+  fresh: (prompt) => [
+    'command-code', '-p', prompt, '-m', 'zai-org/glm-5.2', '--output-format', 'json',
+    '--trust', '--no-auto-update',
+  ],
+  // Resume remains deliberately unsupported because the seed turn can disappear silently.
+  resume: null,
+  env: ENV_BASE,
+  parse: (stdout) => parseJsonResult(stdout, { id: 'sessionId', answer: 'finalText' }),
+  checkCompaction: (_id, stdout) =>
+    stdout.includes('"compaction_start"') || stdout.includes('"compaction_done"'),
+};

package/src/commands/doctor.mjs

@@ -0,0 +1,59 @@
+import { spawn } from 'node:child_process';
+
+export function realWhichCheck(binary) {
+  return new Promise((resolve) => {
+    const command = process.platform === 'win32' ? 'where' : 'which';
+    const child = spawn(command, [binary], { stdio: 'ignore' });
+    child.on('error', () => resolve(false));
+    child.on('exit', (code) => resolve(code === 0));
+  });
+}
+
+export async function resolveBinaryName(candidates, isAvailable = realWhichCheck) {
+  for (const candidate of candidates) {
+    if (await isAvailable(candidate)) return candidate;
+  }
+  return null;
+}
+
+function binaryCandidates(adapter) {
+  if (adapter.binaryCandidates) return adapter.binaryCandidates;
+  const generated = adapter.fresh('');
+  return generated.length > 0 ? [generated[0]] : [];
+}
+
+export async function cmdDoctor(adapters, isAvailable = realWhichCheck) {
+  const checks = Object.values(adapters).map((adapter) => ({
+    adapter,
+    candidates: binaryCandidates(adapter),
+    attempted: [],
+  }));
+  const results = await Promise.allSettled(checks.map(async (check) => {
+    const resolved = await resolveBinaryName(check.candidates, async (candidate) => {
+      check.attempted.push(candidate);
+      return isAvailable(candidate);
+    });
+    return resolved;
+  }));
+
+  for (let index = 0; index < results.length; index += 1) {
+    const result = results[index];
+    const check = checks[index];
+    const tried = check.attempted.join(', ') || 'none';
+    if (result.status === 'rejected') {
+      console.log(
+        `${check.adapter.name}: unavailable (check failed; tried: ${tried}; ` +
+        `reason: ${result.reason?.message ?? String(result.reason)})`,
+      );
+      continue;
+    }
+    const resolved = result.value;
+    if (resolved) {
+      console.log(
+        `${check.adapter.name}: available (found; tried: ${tried}; resolved: ${resolved})`,
+      );
+    } else {
+      console.log(`${check.adapter.name}: unavailable (not found; tried: ${tried})`);
+    }
+  }
+}

package/src/commands/list.mjs

@@ -0,0 +1,52 @@
+import { MAP_PATH } from '../config.mjs';
+import { loadMap } from '../core/map-store.mjs';
+
+function truncId(id, max = 24) {
+  if (id == null) return '-';
+  const value = String(id);
+  return value.length > max ? `${value.slice(0, max - 1)}…` : value;
+}
+
+export function cmdList() {
+  const map = loadMap();
+  const names = Object.keys(map.sessions);
+  if (names.length === 0) {
+    console.log(`no threads recorded in ${MAP_PATH}`);
+    return;
+  }
+  const columns = [
+    'thread', 'backend', 'confirmed', 'native_session_id', 'status', 'turns', 'created_iso',
+    'last_run_iso', 'last_exit_code', 'resume_fails', 'compacted', 'pins',
+  ];
+  const rows = names.sort().map((name) => {
+    const session = map.sessions[name];
+    return {
+      thread: name,
+      backend: session.backend ?? '?',
+      confirmed: session.confirmed ? 'yes' : 'no',
+      native_session_id: truncId(session.native_session_id),
+      status: session.status ?? '-',
+      turns: session.turn_count ?? '-',
+      created_iso: session.created_iso ?? '-',
+      last_run_iso: session.last_run_iso ?? 'never',
+      last_exit_code: session.last_exit_code ?? '-',
+      resume_fails: session.consecutive_resume_failures ?? 0,
+      compacted: session.compaction_detected === true
+        ? 'YES'
+        : session.compaction_detected === false ? 'no' : '-',
+      pins: session.pinned_facts?.length ?? 0,
+    };
+  });
+  const widths = Object.fromEntries(
+    columns.map((column) => [
+      column,
+      Math.max(column.length, ...rows.map((row) => String(row[column]).length)),
+    ]),
+  );
+  const formatRow = (values) => columns
+    .map((column) => String(values[column]).padEnd(widths[column]))
+    .join('  ');
+  console.log(formatRow(Object.fromEntries(columns.map((column) => [column, column]))));
+  console.log(columns.map((column) => '-'.repeat(widths[column])).join('  '));
+  for (const row of rows) console.log(formatRow(row));
+}

package/src/commands/pin.mjs

@@ -0,0 +1,37 @@
+import { MAP_PATH, PIN_WARNING_THRESHOLD } from '../config.mjs';
+import { withLock } from '../core/lock.mjs';
+import { loadMap, saveMap } from '../core/map-store.mjs';
+import { validatePinText } from '../core/pins.mjs';
+import { withThreadSuggestions } from '../core/thread-lookup.mjs';
+
+export async function cmdPin(thread, factText) {
+  const invalid = validatePinText(factText);
+  if (!thread || invalid) {
+    console.error(`usage: cli-relay pin <thread> "<fact>"${invalid ? ` — ${invalid}` : ''}`);
+    process.exit(2);
+  }
+  await withLock(() => {
+    const map = loadMap();
+    const session = map.sessions[thread];
+    if (!session) {
+      throw new Error(withThreadSuggestions(
+        `no such thread "${thread}" in ${MAP_PATH} — run fresh first, then pin`,
+        map.sessions,
+        thread,
+      ));
+    }
+    session.pinned_facts = session.pinned_facts ?? [];
+    session.pinned_facts.push({ text: factText, pinned_at: new Date().toISOString() });
+    if (session.pinned_facts.length >= PIN_WARNING_THRESHOLD) {
+      console.error(
+        `warning: thread "${thread}" now has ${session.pinned_facts.length} pinned facts ` +
+        `(advisory threshold ${PIN_WARNING_THRESHOLD}) — a long, growing pin list defeats ` +
+        `its own purpose; consider consolidating into fewer, more curated facts instead of ` +
+        `appending indefinitely.`,
+      );
+    }
+    map.sessions[thread] = session;
+    saveMap(map);
+    console.log(`pinned to "${thread}" (${session.pinned_facts.length} total): ${factText}`);
+  });
+}

package/src/commands/pins.mjs

@@ -0,0 +1,27 @@
+import { MAP_PATH } from '../config.mjs';
+import { loadMap } from '../core/map-store.mjs';
+import { withThreadSuggestions } from '../core/thread-lookup.mjs';
+
+export function cmdPins(thread) {
+  if (!thread) {
+    console.error('usage: cli-relay pins <thread>');
+    process.exit(2);
+  }
+  const map = loadMap();
+  const session = map.sessions[thread];
+  if (!session) {
+    throw new Error(withThreadSuggestions(
+      `no such thread "${thread}" in ${MAP_PATH}`,
+      map.sessions,
+      thread,
+    ));
+  }
+  const pins = session.pinned_facts ?? [];
+  if (pins.length === 0) {
+    console.log(`no pinned facts for "${thread}"`);
+    return;
+  }
+  pins.forEach((pin, index) => {
+    console.log(`${index + 1}. ${pin.text} (pinned ${pin.pinned_at})`);
+  });
+}

package/src/commands/reset.mjs

@@ -0,0 +1,36 @@
+import { MAP_PATH } from '../config.mjs';
+import { withLock } from '../core/lock.mjs';
+import { loadMap, saveMap } from '../core/map-store.mjs';
+import { withThreadSuggestions } from '../core/thread-lookup.mjs';
+
+export async function cmdReset(thread) {
+  if (!thread) {
+    console.error('usage: cli-relay reset <thread>');
+    process.exit(2);
+  }
+  await withLock(() => {
+    const map = loadMap();
+    const session = map.sessions[thread];
+    if (!session) {
+      throw new Error(withThreadSuggestions(
+        `no such thread "${thread}" in ${MAP_PATH} — nothing to reset`,
+        map.sessions,
+        thread,
+      ));
+    }
+    if (session.pinned_facts?.length) {
+      console.error(
+        `warning: thread "${thread}" has ${session.pinned_facts.length} pinned fact(s) that ` +
+        `will be destroyed by reset — unlike a fresh restart, reset does not carry them ` +
+        `forward. Run "cli-relay pins ${thread}" first if they're worth keeping.`,
+      );
+    }
+    delete map.sessions[thread];
+    saveMap(map);
+    const { pinned_facts: pinnedFacts, ...redacted } = session;
+    console.log(
+      `removed thread "${thread}": ${JSON.stringify(redacted)}` +
+      (pinnedFacts?.length ? ` (+ ${pinnedFacts.length} pinned fact(s), not shown)` : ''),
+    );
+  });
+}

package/src/commands/unpin.mjs

@@ -0,0 +1,32 @@
+import { MAP_PATH } from '../config.mjs';
+import { withLock } from '../core/lock.mjs';
+import { loadMap, saveMap } from '../core/map-store.mjs';
+import { withThreadSuggestions } from '../core/thread-lookup.mjs';
+
+export async function cmdUnpin(thread, indexText) {
+  const index = Number(indexText);
+  if (!thread || !Number.isInteger(index) || index < 1) {
+    console.error('usage: cli-relay unpin <thread> <index>  (1-based — see "cli-relay pins <thread>")');
+    process.exit(2);
+  }
+  await withLock(() => {
+    const map = loadMap();
+    const session = map.sessions[thread];
+    if (!session) {
+      throw new Error(withThreadSuggestions(
+        `no such thread "${thread}" in ${MAP_PATH}`,
+        map.sessions,
+        thread,
+      ));
+    }
+    const pins = session.pinned_facts ?? [];
+    if (index > pins.length) {
+      throw new Error(`thread "${thread}" has only ${pins.length} pinned fact(s) — no #${index}`);
+    }
+    const [removed] = pins.splice(index - 1, 1);
+    session.pinned_facts = pins;
+    map.sessions[thread] = session;
+    saveMap(map);
+    console.log(`unpinned #${index} from "${thread}": ${removed.text}`);
+  });
+}

package/src/config.mjs

@@ -0,0 +1,84 @@
+import { existsSync, mkdirSync, readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+const home = homedir();
+
+export const STATE_DIR = join(home, '.cli-relay');
+export const CONFIG_PATH = join(STATE_DIR, 'config.json');
+export const MAP_VERSION = 1;
+
+export const DEFAULTS = Object.freeze({
+  MAP_PATH: join(STATE_DIR, 'sessions.json'),
+  USER_ADAPTERS_DIR: join(STATE_DIR, 'adapters'),
+  SPAWN_TIMEOUT_MS: 20 * 60_000,
+  SPAWN_KILL_GRACE_MS: 3_000,
+  LOCK_TIMEOUT_MS: 10_000,
+  LOCK_RETRY_MS: 100,
+  LOCK_STALE_GRACE_MS: 60_000,
+  RESUME_FAILURE_THRESHOLD: 3,
+  RESUME_WARNING_THRESHOLD: 10,
+  PIN_WARNING_THRESHOLD: 8,
+  MAX_PIN_LENGTH: 500,
+});
+
+mkdirSync(STATE_DIR, { recursive: true, mode: 0o700 });
+
+function camelCase(name) {
+  return name.toLowerCase().replace(/_([a-z])/g, (_, letter) => letter.toUpperCase());
+}
+
+function configuredValue(raw, name) {
+  return raw[name] ?? raw[camelCase(name)] ?? DEFAULTS[name];
+}
+
+function expandHome(value) {
+  if (value === '~') return home;
+  if (value.startsWith('~/')) return join(home, value.slice(2));
+  return value;
+}
+
+function loadConfig() {
+  if (!existsSync(CONFIG_PATH)) return { ...DEFAULTS };
+  const raw = JSON.parse(readFileSync(CONFIG_PATH, 'utf8'));
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
+    throw new Error(`${CONFIG_PATH} must contain a JSON object`);
+  }
+
+  const merged = Object.fromEntries(
+    Object.keys(DEFAULTS).map((name) => [name, configuredValue(raw, name)]),
+  );
+  for (const name of ['MAP_PATH', 'USER_ADAPTERS_DIR']) {
+    if (typeof merged[name] !== 'string' || !merged[name]) {
+      throw new Error(`${CONFIG_PATH}: ${name} must be a non-empty string`);
+    }
+    merged[name] = expandHome(merged[name]);
+  }
+  for (const name of Object.keys(DEFAULTS).filter((key) => typeof DEFAULTS[key] === 'number')) {
+    if (!Number.isFinite(merged[name]) || merged[name] < 0) {
+      throw new Error(`${CONFIG_PATH}: ${name} must be a non-negative number`);
+    }
+  }
+  return merged;
+}
+
+export const CONFIG = Object.freeze(loadConfig());
+
+export const {
+  MAP_PATH,
+  USER_ADAPTERS_DIR,
+  SPAWN_TIMEOUT_MS,
+  SPAWN_KILL_GRACE_MS,
+  LOCK_TIMEOUT_MS,
+  LOCK_RETRY_MS,
+  LOCK_STALE_GRACE_MS,
+  RESUME_FAILURE_THRESHOLD,
+  RESUME_WARNING_THRESHOLD,
+  PIN_WARNING_THRESHOLD,
+  MAX_PIN_LENGTH,
+} = CONFIG;
+
+// These must follow the configured base values. They are intentionally not independently
+// configurable, so a map or timeout override cannot leave its related safety value behind.
+export const LOCK_PATH = `${MAP_PATH}.lock`;
+export const LOCK_STALE_MS = SPAWN_TIMEOUT_MS + LOCK_STALE_GRACE_MS;

package/src/core/adapter-env.mjs

@@ -0,0 +1,3 @@
+// Native authentication lives in each CLI's own store. These variables preserve binary
+// resolution, config-home discovery, git-over-SSH, and normal terminal locale behavior.
+export const ENV_BASE = Object.freeze(['PATH', 'HOME', 'SSH_AUTH_SOCK', 'LANG', 'TERM']);

package/src/core/env.mjs

@@ -0,0 +1,7 @@
+export function scrubEnv(allowlist) {
+  const env = {};
+  for (const name of allowlist) {
+    if (process.env[name] !== undefined) env[name] = process.env[name];
+  }
+  return env;
+}

package/src/core/errors.mjs

@@ -0,0 +1,8 @@
+export class RelayError extends Error {
+  constructor(code, message, options = {}) {
+    super(message, options.cause === undefined ? undefined : { cause: options.cause });
+    this.name = 'RelayError';
+    this.code = code;
+    this.exitCode = options.exitCode ?? 1;
+  }
+}

package/src/core/lock.mjs

@@ -0,0 +1,123 @@
+import {
+  mkdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync,
+} from 'node:fs';
+import { join } from 'node:path';
+import {
+  LOCK_PATH, LOCK_RETRY_MS, LOCK_STALE_MS, LOCK_TIMEOUT_MS,
+} from '../config.mjs';
+
+const LOCK_HOLDER_FILE = 'holder.json';
+
+function isPidAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function readHolderRaw() {
+  try {
+    return readFileSync(join(LOCK_PATH, LOCK_HOLDER_FILE), 'utf8');
+  } catch {
+    return null; // missing or unreadable — a real signal in its own right, not an error
+  }
+}
+
+// Reclaiming a dead lock by inspecting it and then unconditionally `rmSync`-ing the path is
+// a TOCTOU race: two waiters can both judge the SAME dead instance eligible, and whichever
+// runs second deletes whatever is CURRENTLY at that path — which may by then be a brand-new,
+// legitimate holder the first reclaimer already created, letting both waiters into fn() at
+// once (found in review, twice — first via holder.json timing, then via this exact
+// path-based-delete gap). `renameSync` is atomic at the OS level, so at most one caller's
+// rename of a given source path can ever succeed; the loser gets ENOENT and safely backs
+// off having touched nothing. But atomicity alone isn't enough either: the thing a winner
+// captures might no longer be the dead instance it originally inspected (a legitimate new
+// holder could have appeared in the gap between that inspection and this call) — so after
+// winning the rename, re-check the captured content against what was judged dead before
+// destroying anything. A mismatch means we accidentally captured a live replacement; put it
+// back for its rightful owner instead.
+// Returns true only if this call actually took an action (rename succeeded, whether the
+// outcome was destroying a confirmed-dead instance or restoring a live replacement it
+// accidentally captured). False means nothing changed — the caller must fall through to
+// the normal deadline/retry wait rather than looping without pause, which would otherwise
+// spin at full CPU on a persistent rename failure (e.g. a permissions problem) instead of
+// respecting LOCK_TIMEOUT_MS.
+function reclaim(expectedHolderRaw) {
+  const claim = `${LOCK_PATH}.reclaim.${process.pid}.${Date.now()}`;
+  try {
+    renameSync(LOCK_PATH, claim);
+  } catch {
+    return false; // lost the race to someone else, or a real error (e.g. permissions) — either way, did nothing
+  }
+  let capturedHolderRaw;
+  try {
+    capturedHolderRaw = readFileSync(join(claim, LOCK_HOLDER_FILE), 'utf8');
+  } catch {
+    capturedHolderRaw = null;
+  }
+  if (capturedHolderRaw === expectedHolderRaw) {
+    rmSync(claim, { recursive: true, force: true });
+  } else {
+    // Not the same instance we judged dead — a legitimate holder slipped in during our
+    // check. Restore it. If even that races (LOCK_PATH got recreated in the meantime by
+    // yet another party), there is nowhere safe to put it back; drop it rather than loop
+    // forever — this compounds three independent low-probability races at once.
+    try {
+      renameSync(claim, LOCK_PATH);
+    } catch {
+      rmSync(claim, { recursive: true, force: true });
+    }
+  }
+  return true;
+}
+
+export async function withLock(fn) {
+  const deadline = Date.now() + LOCK_TIMEOUT_MS;
+  for (;;) {
+    try {
+      mkdirSync(LOCK_PATH);
+      writeFileSync(
+        join(LOCK_PATH, LOCK_HOLDER_FILE),
+        JSON.stringify({ pid: process.pid, ts: Date.now() }),
+      );
+      break;
+    } catch (error) {
+      if (error.code !== 'EEXIST') throw error;
+      const holderRaw = readHolderRaw();
+      let eligible = false;
+      if (holderRaw !== null) {
+        try {
+          const holder = JSON.parse(holderRaw);
+          eligible = Date.now() - holder.ts > LOCK_STALE_MS || !isPidAlive(holder.pid);
+        } catch {
+          eligible = true; // holder.json exists but isn't valid JSON — not a state any live holder writes
+        }
+      } else {
+        // Missing holder.json while the lock dir exists: either mid-write (a real holder's
+        // mkdir+writeFileSync are back-to-back synchronous, resolving in microseconds) or
+        // the holder died in that exact window and never will. Use the lock directory's own
+        // mtime — an objective fact any process can check on the same physical directory —
+        // rather than this waiter's own elapsed wait time, which can't tell "the original
+        // holder died" apart from "a brand-new holder's mkdir just landed."
+        try {
+          eligible = Date.now() - statSync(LOCK_PATH).mtimeMs > LOCK_TIMEOUT_MS;
+        } catch {
+          eligible = false; // the directory itself vanished already — nothing here to reclaim
+        }
+      }
+      if (eligible && reclaim(holderRaw)) continue;
+      if (Date.now() > deadline) {
+        throw new Error(`another cli-relay invocation holds the lock (${LOCK_PATH}) — not waiting forever`);
+      }
+      await new Promise((resolve) => setTimeout(resolve, LOCK_RETRY_MS));
+    }
+  }
+
+  try {
+    return await fn();
+  } finally {
+    try { rmSync(LOCK_PATH, { recursive: true, force: true }); } catch {}
+  }
+}

package/src/core/map-store.mjs

@@ -0,0 +1,20 @@
+import { existsSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { MAP_PATH, MAP_VERSION } from '../config.mjs';
+
+export function loadMap() {
+  if (!existsSync(MAP_PATH)) return { version: MAP_VERSION, sessions: {} };
+  const map = JSON.parse(readFileSync(MAP_PATH, 'utf8'));
+  if (map.version !== MAP_VERSION) {
+    throw new Error(
+      `${MAP_PATH} version ${map.version} unsupported (router wants ${MAP_VERSION}) — ` +
+      'no migration, fix by hand or delete',
+    );
+  }
+  return map;
+}
+
+export function saveMap(map) {
+  const tmp = `${MAP_PATH}.${process.pid}.tmp`;
+  writeFileSync(tmp, `${JSON.stringify(map, null, 2)}\n`, { mode: 0o600 });
+  renameSync(tmp, MAP_PATH);
+}

package/src/core/parse-json-result.mjs

@@ -0,0 +1,24 @@
+export function parseJsonResult(stdout, fields) {
+  const hasFields = (value) => value && typeof value === 'object' &&
+    (fields.id in value || fields.answer in value);
+
+  const trimmed = stdout.trim();
+  try {
+    const value = JSON.parse(trimmed);
+    if (hasFields(value)) {
+      return { id: value[fields.id] ?? null, answer: value[fields.answer] ?? null };
+    }
+  } catch {
+    // Not one JSON object. Fall through to the NDJSON scan.
+  }
+
+  const lines = trimmed.split('\n');
+  for (let index = lines.length - 1; index >= 0; index -= 1) {
+    let value;
+    try { value = JSON.parse(lines[index]); } catch { continue; }
+    if (hasFields(value)) {
+      return { id: value[fields.id] ?? null, answer: value[fields.answer] ?? null };
+    }
+  }
+  return { id: null, answer: null };
+}

package/src/core/pins.mjs

@@ -0,0 +1,24 @@
+import { MAX_PIN_LENGTH } from '../config.mjs';
+
+export function validatePinText(factText) {
+  if (!factText || !factText.trim()) return 'fact text must not be empty or whitespace-only';
+  if (factText.includes('\n')) {
+    return 'fact text must be a single line — multiline facts risk breaking the pinned-block delimiter';
+  }
+  if (factText.length > MAX_PIN_LENGTH) {
+    return `fact text is ${factText.length} chars, over the ${MAX_PIN_LENGTH}-char limit — ` +
+      'keep pins short and curated, not a transcript';
+  }
+  return null;
+}
+
+export function buildPinnedBlock(pins) {
+  if (!pins || pins.length === 0) return '';
+  const lines = pins.map((pin, index) => `${index + 1}. ${pin.text} (pinned ${pin.pinned_at})`);
+  return (
+    `[PINNED FACTS for this thread — externally verified, override anything else in this ` +
+    `conversation's history including your own summarized memory of earlier turns. Treat any ` +
+    `contradiction between these and your own recollection as your recollection being wrong.]\n` +
+    `${lines.join('\n')}\n[END PINNED FACTS]\n\n`
+  );
+}

package/src/core/thread-lookup.mjs

@@ -0,0 +1,12 @@
+export function withThreadSuggestions(message, sessions, thread) {
+  if (!thread) return message;
+  const needle = thread.toLocaleLowerCase();
+  const matches = Object.keys(sessions)
+    .filter((name) => {
+      const candidate = name.toLocaleLowerCase();
+      return candidate.includes(needle) || needle.includes(candidate);
+    })
+    .sort()
+    .slice(0, 3);
+  return matches.length === 0 ? message : `${message} — did you mean: ${matches.join(', ')}?`;
+}