talon-agent 1.12.0 → 1.34.0

package/src/core/prompt/templates.ts

@@ -0,0 +1,124 @@
+/**
+ * Package-owned prompt templates — loader + Liquid renderer.
+ *
+ * Talon's prompt text lives in two places with different ownership:
+ *
+ *   - **User-editable prompts** (`identity.md`, `base.md`/`custom.md`,
+ *     frontend files like `telegram.md`) are seeded once into
+ *     `~/.talon/prompts/` and read from there — user edits win, and
+ *     package updates deliberately never overwrite them. These are
+ *     rendered with plain `{{name}}` string replacement by their
+ *     consumers (heartbeat/dream), NOT through Liquid — a user file
+ *     must never be able to break prompt assembly with a syntax error.
+ *
+ *   - **System templates** (`prompts/system/*.md` — delivery
+ *     contracts, capability docs, section wrappers) are read straight
+ *     from the PACKAGE directory and are NOT seeded. They describe
+ *     runtime behaviour that is versioned with the code (tool names,
+ *     flow enforcement, trigger limits); a stale seeded copy would
+ *     silently document a contract the code no longer implements.
+ *
+ * System templates are [Liquid](https://liquidjs.com) — `{{name}}`
+ * output (missing → empty string, matching the legacy renderer),
+ * `{% if %}`/`{% else %}` conditionals, and `{% render 'partial' %}`
+ * includes resolved against `prompts/system/`. Liquid was chosen over
+ * a homegrown DSL so prompt text can be composed (sections,
+ * conditionals, partials) inside fewer files instead of one file per
+ * fragment — and over JS-in-template engines because templates stay
+ * pure prose: no code execution.
+ *
+ * Templates are parsed once per process and cached; rendering with
+ * vars is pure in-memory work.
+ */
+
+import type { FS } from "liquidjs";
+import { Liquid, type Template } from "liquidjs";
+import { promptAssetExists, readPromptAsset } from "#prompt-assets";
+
+// ── Renderer ────────────────────────────────────────────────────────────────
+
+export type TemplateVars = Record<string, string | undefined>;
+
+/**
+ * Map a Liquid lookup (a bare partial name or `<name>.md`) to its rel path
+ * under the package `prompts/system/` directory. System templates live
+ * flat there and are referenced by bare name in `{% render %}`.
+ */
+const systemRel = (file: string): string => {
+  const base = file.split(/[\\/]/).pop() ?? file;
+  return `system/${base.endsWith(".md") ? base : `${base}.md`}`;
+};
+
+/**
+ * A Liquid filesystem backed by the `#prompt-assets` seam instead of the
+ * real disk, so `{% render 'partial' %}` includes resolve identically
+ * under tsx (reads `prompts/system/*.md` from disk) and a
+ * `bun build --compile` binary (reads the same files embedded in the
+ * binary). System templates are flat, so resolution is by basename.
+ */
+const liquidFs: FS = {
+  sep: "/",
+  dirname: () => ".",
+  resolve: (_dir, file, ext) => (file.endsWith(ext) ? file : `${file}${ext}`),
+  existsSync: (file) => promptAssetExists(systemRel(file)),
+  readFileSync: (file) => readPromptAsset(systemRel(file)),
+  exists: (file) => Promise.resolve(promptAssetExists(systemRel(file))),
+  readFile: (file) => Promise.resolve(readPromptAsset(systemRel(file))),
+  contains: () => Promise.resolve(true),
+  containsSync: () => true,
+};
+
+/**
+ * One engine instance per process. The custom `fs` lets templates compose
+ * via `{% render 'partial-name' %}` against `prompts/system/`. Variables
+ * stay lenient (unknown → empty string) — a template must degrade to
+ * readable prose when an optional var (e.g. a frontend without
+ * reactions) is absent.
+ */
+const liquid = new Liquid({
+  fs: liquidFs,
+  extname: ".md",
+  // JS truthiness, not Shopify's: `""` and `0` are falsy. The legacy
+  // renderer treated empty-string vars as "absent", and callers rely
+  // on it (`truncated: truncated ? "yes" : undefined`-style flags).
+  jsTruthy: true,
+});
+
+/**
+ * Render a raw Liquid template string with `vars`. For one-off
+ * strings (tests, dynamic snippets); file templates should go through
+ * `loadSystemTemplate`, which caches the parse.
+ */
+export function renderTemplate(template: string, vars: TemplateVars): string {
+  return liquid.parseAndRenderSync(template, vars);
+}
+
+// ── Loader ──────────────────────────────────────────────────────────────────
+
+const parseCache = new Map<string, Template[]>();
+
+/**
+ * Load a system template by name (e.g. `"contract-tool-only"`) and
+ * render it with `vars`. Throws if the file is missing — system
+ * templates ship with the package, so absence is a packaging bug, not
+ * a user-configuration state.
+ */
+export function loadSystemTemplate(
+  name: string,
+  vars: TemplateVars = {},
+): string {
+  const file = `${name}.md`;
+  let parsed = parseCache.get(file);
+  if (parsed === undefined) {
+    // The filepath argument anchors relative {% render %} resolution
+    // (resolved against the prompt-asset seam, not the disk).
+    parsed = liquid.parse(readPromptAsset(`system/${file}`).trim(), file);
+    parseCache.set(file, parsed);
+  }
+  return liquid.renderSync(parsed, vars) as string;
+}
+
+/** Test seam: drop the parse cache (e.g. after writing fixture templates). */
+export function clearTemplateCache(): void {
+  parseCache.clear();
+}

package/src/core/prompt/workspace-listing.ts

@@ -0,0 +1,91 @@
+/**
+ * Workspace file listing for the system prompt's dynamic tail.
+ *
+ * Renders a compact tree of `~/.talon/workspace/` so the model knows
+ * what artifacts exist. Volatile by nature (file sizes change as logs
+ * grow), so it always belongs to the DYNAMIC prompt part — never the
+ * cacheable static prefix.
+ *
+ * Any directory with more than `COLLAPSE_THRESHOLD` rendered entries
+ * collapses to a single `name/ (N files)` summary line, so per-file
+ * sizes inside such a directory are never needed. The tree is built
+ * lazily: `statSync` is deferred to render time and only ever called
+ * for files that actually appear in the output. The eager
+ * implementation stat'd every file during the walk — on a workspace
+ * with tens of thousands of files (logs, build artifacts, media) that
+ * meant one blocking syscall per file on every session start, just to
+ * print a handful of summary lines.
+ */
+
+import { readdirSync, statSync } from "node:fs";
+import { resolve } from "node:path";
+
+const COLLAPSE_THRESHOLD = 8;
+
+// A node contributes `count` rendered lines to its parent (used to
+// decide the collapse) and renders those lines lazily via `render()`.
+type Node = { count: number; render: () => string[] };
+
+function buildNode(dir: string, prefix: string): Node {
+  const children: Node[] = [];
+  try {
+    for (const e of readdirSync(dir, { withFileTypes: true })) {
+      if (
+        e.name.startsWith(".") ||
+        e.name === "node_modules" ||
+        e.name === "talon.log"
+      )
+        continue;
+      const full = resolve(dir, e.name);
+      if (e.isDirectory()) {
+        const sub = buildNode(full, `${prefix}${e.name}/`);
+        if (sub.count === 0) continue; // empty dir → omitted
+        if (sub.count <= COLLAPSE_THRESHOLD) {
+          children.push(sub); // expand inline
+        } else {
+          // Collapse to one summary line — never render (or stat) the
+          // files inside.
+          const line = `${prefix}${e.name}/ (${sub.count} files)`;
+          children.push({ count: 1, render: () => [line] });
+        }
+      } else {
+        children.push({
+          count: 1,
+          render: () => {
+            let sz = 0;
+            try {
+              sz = statSync(full).size;
+            } catch {
+              /* file vanished between readdir and stat — show 0B */
+            }
+            return [
+              `${prefix}${e.name} (${sz < 1024 ? sz + "B" : (sz / 1024).toFixed(0) + "KB"})`,
+            ];
+          },
+        });
+      }
+    }
+  } catch {
+    /* unreadable dir → treat as empty */
+  }
+  const count = children.reduce((n, c) => n + c.count, 0);
+  return { count, render: () => children.flatMap((c) => c.render()) };
+}
+
+/**
+ * Render the `## Current Workspace Contents` section, or an empty
+ * string when the workspace is missing or empty.
+ */
+export function renderWorkspaceListing(workspaceDir: string): string {
+  try {
+    const files = buildNode(workspaceDir, "").render();
+    if (files.length === 0) return "";
+    return (
+      "## Current Workspace Contents\n\n" +
+      files.map((f) => `  ${f}`).join("\n")
+    );
+  } catch {
+    /* no workspace yet */
+    return "";
+  }
+}

package/src/core/scripting/lua-runner.ts

@@ -0,0 +1,210 @@
+/**
+ * Lua trigger runner — executes a trigger script inside a WASM-sandboxed
+ * Lua 5.4 VM (wasmoon), speaking the same stdout protocol bash/python/node
+ * triggers use (see core/background/triggers.ts).
+ *
+ * Why a separate process at all: the trigger supervisor's whole contract
+ * (kill/respawn, SIGTERM grace, log streaming, TALON_FIRE line scanning)
+ * is built around child processes. Lua therefore runs as `talon _lua-run
+ * <script>` — the same self-reinvocation shape MCP supervision uses
+ * (util/mcp-launcher.ts) — so it works identically for tsx source runs,
+ * npm installs, and bun-compiled binaries with no source tree on disk.
+ *
+ * Sandbox (verified empirically, not aspirational):
+ *   - wasmoon is Lua 5.4 compiled to WASM under emscripten. The VM's
+ *     filesystem is MEMFS: `io.open("/etc/hostname")` returns nil, and
+ *     `os.getenv` sees only emscripten's stub environment — the host
+ *     process env is invisible. No sockets, no subprocesses.
+ *   - The full Lua stdlib (string/table/math/os.time/os.clock/io) works
+ *     INSIDE the VM; io/os just can't reach the host.
+ *   - The only host surface is the injected `talon` API below.
+ *
+ * Host API (global `talon` table):
+ *   talon.fire(text)  — emit `TALON_FIRE: <text>` on stdout (newlines in
+ *                       text collapsed to spaces); fires a mid-run wake-up.
+ *   talon.log(text)   — stderr line; lands in the trigger run-log as
+ *                       `[stderr] …`.
+ *   talon.sleep(ms)   — synchronous-looking sleep. Implemented as a JS
+ *                       promise the Lua thread suspends on via wasmoon's
+ *                       `:await()` (the engine yields the coroutine and
+ *                       resumes it when the promise settles).
+ *
+ * Fire-protocol forgery guard: ALL VM-visible stdout — print(), io.write,
+ * io.output():write, anything emscripten emits — funnels through
+ * console.log (emscripten's `out` channel). We patch BOTH console.log and
+ * process.stdout.write for the run: under node, console.log delegates to
+ * the stream's write method, but under bun (compiled binaries) console.log
+ * is native and bypasses it entirely — patching only the stream was
+ * verified to let a forged print() through in the compiled binary.
+ * Everything is line-buffered: any script-originated line starting with
+ * `TALON_FIRE:` is escaped with one leading space, which defeats the
+ * supervisor's startsWith() check while keeping the text readable in the
+ * run-log. Only talon.fire writes through the saved raw stream method, and
+ * it terminates any pending partial script line first so a trailing
+ * io.write fragment can't glue onto (and break) the protocol line. This is
+ * an anti-accident/anti-confusion guard at the stdout choke points —
+ * the host sandbox above is what provides actual isolation.
+ *
+ * Known stdio quirk (verified): `io.write("text")` WITHOUT a trailing
+ * newline sits in emscripten's internal TTY buffer and is never flushed —
+ * not at chunk end, not at engine close — so it's silently lost, exactly
+ * like unflushed C stdio. Scripts should end stdout writes with "\n"
+ * (print() always does).
+ *
+ * Exit codes: 0 — script completed; 1 — Lua error (message + traceback on
+ * stderr); 2 — usage error (no script path / unreadable file).
+ */
+
+import { readFileSync } from "node:fs";
+import { basename } from "node:path";
+
+/** Hidden CLI subcommand that turns a Talon process into the Lua runner.
+ *  Dispatched by src/index.ts and src/cli.ts before the app graph loads. */
+export const LUA_RUN_SUBCOMMAND = "_lua-run";
+
+/** Must match FIRE_PREFIX in core/background/triggers.ts. */
+const FIRE_PREFIX = "TALON_FIRE:";
+
+/**
+ * Run a Lua script file to completion inside a fresh wasmoon engine.
+ * Throws on Lua errors (message shaped `<file>:<line>: <msg>` plus
+ * traceback). Restores process.stdout.write before returning.
+ */
+export async function runLuaScript(scriptPath: string): Promise<void> {
+  const source = readFileSync(scriptPath, "utf-8");
+
+  const originalWrite = process.stdout.write;
+  const originalConsoleLog = console.log;
+  const rawWrite = originalWrite.bind(process.stdout);
+
+  // ── Line-buffered, fire-escaping stdout for everything the VM emits ──
+  let pending = "";
+  const emitLine = (line: string): void => {
+    rawWrite(line.startsWith(FIRE_PREFIX) ? ` ${line}\n` : `${line}\n`);
+  };
+  const scriptWrite = (text: string): void => {
+    pending += text;
+    let nl: number;
+    while ((nl = pending.indexOf("\n")) !== -1) {
+      emitLine(pending.slice(0, nl));
+      pending = pending.slice(nl + 1);
+    }
+  };
+  const flushPending = (): void => {
+    if (pending.length === 0) return;
+    emitLine(pending);
+    pending = "";
+  };
+
+  // Both patches MUST be installed before wasmoon is imported: its
+  // emscripten glue captures `console.log.bind(console)` at module-eval
+  // time. Under node the binding still routes through the stream's write
+  // method at call time, but under bun (compiled binaries) console.log is
+  // native and a pre-patch binding writes straight to fd 1 — verified to
+  // let a forged print() through when the patch came after the import.
+  process.stdout.write = ((
+    chunk: string | Uint8Array,
+    encodingOrCb?: BufferEncoding | ((err?: Error | null) => void),
+    cb?: (err?: Error | null) => void,
+  ): boolean => {
+    scriptWrite(
+      typeof chunk === "string" ? chunk : Buffer.from(chunk).toString("utf-8"),
+    );
+    const callback = typeof encodingOrCb === "function" ? encodingOrCb : cb;
+    callback?.();
+    return true;
+  }) as typeof process.stdout.write;
+
+  // Emscripten calls console.log with a single already-formatted string
+  // per line; joining covers stray multi-arg calls.
+  console.log = (...args: unknown[]): void => {
+    scriptWrite(`${args.map(String).join(" ")}\n`);
+  };
+
+  let lua: import("wasmoon").LuaEngine | undefined;
+  try {
+    // Lazy import: entrypoints and triggers.ts import this module just for
+    // LUA_RUN_SUBCOMMAND — they must not pay for the embedded WASM bundle.
+    const { LuaFactory } = await import("wasmoon");
+    const factory = new LuaFactory();
+    lua = await factory.createEngine();
+
+    // ── Host API ──
+    lua.global.set("__talon_fire", (text: unknown) => {
+      flushPending();
+      const single = String(text)
+        .replace(/[\r\n]+/g, " ")
+        .trim();
+      rawWrite(`${FIRE_PREFIX} ${single}\n`);
+    });
+    lua.global.set("__talon_log", (text: unknown) => {
+      process.stderr.write(`${String(text)}\n`);
+    });
+    lua.global.set("__talon_sleep", (ms: unknown) => {
+      const delay = Math.max(0, Number(ms) || 0);
+      return new Promise<void>((resolve) => setTimeout(resolve, delay));
+    });
+
+    // The sleep wrapper hides the promise plumbing: scripts just call
+    // talon.sleep(ms) and the Lua thread suspends until it resolves.
+    await lua.doString(`
+      talon = {
+        fire = function(text) __talon_fire(tostring(text)) end,
+        log = function(text) __talon_log(tostring(text)) end,
+        sleep = function(ms) __talon_sleep(ms):await() end,
+      }
+    `);
+
+    // Mount under the script's basename so Lua errors read
+    // `<name>.lua:<line>: <msg>` instead of `[string "…"]`.
+    const mounted = `/${basename(scriptPath)}`;
+    await factory.mountFile(mounted, source);
+    await lua.doFile(mounted);
+  } finally {
+    // Close the engine BEFORE restoring the patches: if any
+    // wasmoon/emscripten teardown ever flushes buffered VM stdout, it must
+    // still hit the sanitizer. (Empirically nothing flushes today — see
+    // header — but the safe order costs nothing.)
+    lua?.global.close();
+    console.log = originalConsoleLog;
+    process.stdout.write = originalWrite;
+    flushPending();
+  }
+}
+
+/**
+ * `_lua-run` entry: run argv[0] as a Lua script and exit with the
+ * protocol's exit code. Never resolves — mirrors runSupervisor() so
+ * entrypoints can `await` it and nothing after the dispatch ever runs.
+ */
+export async function runLuaMain(argvTail: string[]): Promise<never> {
+  const scriptPath = argvTail[0];
+  if (!scriptPath) {
+    process.stderr.write("lua-runner: missing script path\n");
+    process.exit(2);
+  }
+
+  let code = 0;
+  try {
+    await runLuaScript(scriptPath);
+  } catch (err) {
+    process.stderr.write(
+      `${err instanceof Error ? err.message : String(err)}\n`,
+    );
+    code = 1;
+  }
+
+  // Don't process.exit() straight away: stdout/stderr to a pipe flush
+  // asynchronously and an immediate exit can drop the tail of the output
+  // (including the final TALON_FIRE line). exitCode is the fallback if a
+  // stream never runs its callback.
+  process.exitCode = code;
+  let remaining = 2;
+  const done = (): void => {
+    remaining -= 1;
+    if (remaining === 0) process.exit(code);
+  };
+  process.stdout.write("", done);
+  process.stderr.write("", done);
+  return new Promise<never>(() => {});
+}

package/src/core/scripts/runner.ts

@@ -0,0 +1,125 @@
+/**
+ * Script runner — run-to-completion execution of saved scripts.
+ *
+ * Unlike triggers (supervised long-running watchers with a fire
+ * protocol), a script invocation is a plain subprocess: spawn the
+ * interpreter on the script with the caller's args, capture output,
+ * enforce a timeout, return the result to the calling turn. Local
+ * execution — no model involvement, no token cost.
+ *
+ * Security posture matches triggers and the agent's Bash tool: the
+ * bot account (its OS user, its workspace) is the boundary, not the
+ * script contents.
+ */
+
+import { spawn } from "node:child_process";
+import { dirs } from "../../util/paths.js";
+import { log } from "../../util/log.js";
+import { commandForLanguage } from "../background/triggers/index.js";
+import type { Script } from "../../storage/script-store.js";
+
+export const DEFAULT_SCRIPT_TIMEOUT_SECONDS = 60;
+export const MAX_SCRIPT_TIMEOUT_SECONDS = 300;
+
+/** Cap on captured stdout/stderr — keeps tool results context-friendly. */
+const OUTPUT_CAP_CHARS = 16_000;
+
+export type ScriptRunResult = {
+  exitCode: number | null;
+  stdout: string;
+  stderr: string;
+  timedOut: boolean;
+  durationMs: number;
+};
+
+export function validateScriptTimeout(seconds: number): string | null {
+  if (!Number.isFinite(seconds) || seconds <= 0)
+    return "Timeout must be a positive number";
+  if (seconds > MAX_SCRIPT_TIMEOUT_SECONDS)
+    return `Timeout exceeds max (${MAX_SCRIPT_TIMEOUT_SECONDS}s)`;
+  return null;
+}
+
+/**
+ * Run a script to completion. Resolves (never rejects) with the
+ * captured result; spawn failures surface as `exitCode: null` with
+ * the error message in stderr.
+ */
+export function runScript(
+  script: Script,
+  args: readonly string[] = [],
+  timeoutSeconds = DEFAULT_SCRIPT_TIMEOUT_SECONDS,
+): Promise<ScriptRunResult> {
+  const command = commandForLanguage(script.language);
+  if (!command) {
+    return Promise.resolve({
+      exitCode: null,
+      stdout: "",
+      stderr: `No ${script.language} interpreter available on this host`,
+      timedOut: false,
+      durationMs: 0,
+    });
+  }
+
+  const t0 = Date.now();
+  return new Promise((resolvePromise) => {
+    let stdout = "";
+    let stderr = "";
+    let timedOut = false;
+    let settled = false;
+
+    const child = spawn(
+      command.cmd,
+      [...command.args, script.scriptPath, ...args],
+      {
+        cwd: dirs.workspace,
+        env: process.env,
+        stdio: ["ignore", "pipe", "pipe"],
+        windowsHide: true,
+      },
+    );
+
+    const timer = setTimeout(() => {
+      timedOut = true;
+      child.kill("SIGTERM");
+      // SIGKILL backstop for scripts that trap/ignore SIGTERM.
+      setTimeout(() => child.kill("SIGKILL"), 5_000).unref();
+      // Settle without waiting for 'close': a grandchild that
+      // inherited the stdio pipes (e.g. bash spawning `sleep`) keeps
+      // them open after the direct child dies, so 'close' may never
+      // fire. Whatever output was captured by now is the result.
+      setTimeout(() => settle(null), 1_500).unref();
+    }, timeoutSeconds * 1000);
+    timer.unref();
+
+    child.stdout.on("data", (chunk: Buffer) => {
+      if (stdout.length < OUTPUT_CAP_CHARS) stdout += chunk.toString("utf-8");
+    });
+    child.stderr.on("data", (chunk: Buffer) => {
+      if (stderr.length < OUTPUT_CAP_CHARS) stderr += chunk.toString("utf-8");
+    });
+
+    const settle = (exitCode: number | null, spawnError?: string) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      const durationMs = Date.now() - t0;
+      log(
+        "scripts",
+        `ran "${script.name}" (exit=${exitCode ?? "n/a"}${timedOut ? ", TIMED OUT" : ""}, ${durationMs}ms)`,
+      );
+      resolvePromise({
+        exitCode,
+        stdout: stdout.slice(0, OUTPUT_CAP_CHARS),
+        stderr: spawnError
+          ? `${spawnError}\n${stderr}`.slice(0, OUTPUT_CAP_CHARS)
+          : stderr.slice(0, OUTPUT_CAP_CHARS),
+        timedOut,
+        durationMs,
+      });
+    };
+
+    child.on("error", (err) => settle(null, err.message));
+    child.on("close", (code) => settle(code));
+  });
+}

package/src/core/soul/README.md

@@ -0,0 +1,110 @@
+# Soul Kernel
+
+Talon's compiled identity. Not a markdown prompt, not a JSON blob — a
+**content-addressed Merkle DAG** of typed identity nodes, learned **mechanically**
+from behavioral telemetry and projected into the system prompt by **selection**.
+
+> The model is the brain. Talon is the body. The Soul is the persistent identity
+> artifact that tells the brain how to be Talon.
+
+## The thesis: the model never writes its own soul
+
+There are two jobs — _being the self_ (the reasoning model reads the soul and
+acts) and _writing the self_ (turning experience into identity). If the reasoning
+model does the second, it can rationalize, flatter itself, and confabulate a
+coherent self-story that isn't true. So **writing the self is strictly
+model-free**: continuous, deterministic, evidence-grounded. The reasoning model is
+a _reader_ of the soul, never its author. That is the safety property, not just a
+cost saving.
+
+The only neural component anywhere is an optional **local embedder** (for
+clustering/dedup/contradiction-distance) — a frozen fixed function, not an agent.
+Everything else is counters, exponential decay, dot products, and selection.
+
+## The substrate
+
+A node's identity is the sha-256 of its canonical content. The single most
+important decision is the split between:
+
+- **Content** (hashed, immutable) — a node's semantic identity: kind + verbatim
+  payload + referenced child hashes. A change of content is a new node.
+- **State** (mutable, keyed by hash) — salience, evidence weight, activation
+  counts. Churns every tick; lives _outside_ the Merkle structure.
+
+So reinforcing a value a thousand times never churns a single content hash.
+Versioning, provenance, dedup, and partial recompilation fall out structurally;
+learning and decay live in the state layer.
+
+## The five structures
+
+| Structure | Node kind       | What it is                                                                                  |
+| --------- | --------------- | ------------------------------------------------------------------------------------------- |
+| Spine     | `spine`         | append-only causal narrative — _why_ Talon became Talon                                     |
+| Lattice   | `value` + edges | values as evidence clusters; tension/affinity edges self-organize via Hebbian co-activation |
+| Reflexes  | `reflex`        | `trigger → guard → action` rules the harness _enforces_                                     |
+| Holograph | `lens`          | identity refracted per interlocutor (selection + reweighting)                               |
+| Critic    | (classifiers)   | frozen feature-based gates over failure modes                                               |
+
+The atoms under all of it are `evidence` nodes — verbatim ground truth. The kernel
+never paraphrases; it only ever quotes.
+
+## The model-free pipeline
+
+```
+telemetry ──▶ signals ──▶ compiler ──▶ DAG (+ salience/Hebbian) ──▶ projector ──▶ runtime.md
+  (harness)   (structured)  (arithmetic)   (content + state)        (selection)   (injected)
+```
+
+- **Signals** (`signals.ts`) — structured harness events (reaction, engagement,
+  correction, reflex-fire). Interpretation already happened; no transcript reading.
+- **Compiler** (`compiler.ts`) — routes each signal to pure update rules. Outcome
+  signals reinforce/penalize the values that were live in that turn's projection
+  and Hebbian-coactivate them; corrections store verbatim evidence + a Spine event.
+- **Salience** (`salience.ts`) — lazy exponential decay, reinforcement, Hebbian
+  edges, predictive-coding delta rule. The whole "learning" is here, all arithmetic.
+- **Projector** (`projector.ts`) — selects verbatim evidence, salience-ordered
+  under a token budget. Reflexes are never budgeted away. The soul cannot
+  hallucinate itself.
+- **Critic** (`critic.ts`) — frozen classifiers for wall-of-text, sycophancy,
+  emoji-overload.
+- **Kernel** (`kernel.ts`) — orchestrator: genesis → ingest → commit → project,
+  with a git-like commit chain and JSON persistence.
+
+## File map
+
+```
+types.ts       node payloads, edges, activation state, commits, config
+hash.ts        canonical serialization + content addressing + Merkle root
+dag.ts         the DAG store: integrity, dirty propagation, snapshot/restore
+salience.ts    decay / reinforce / coactivate / prediction-error  (the math)
+reflex.ts      predicate registry + enforcer + the three seed reflexes
+signals.ts     structured telemetry types + emoji→valence
+compiler.ts    signal → arithmetic update routing  (writing the self)
+projector.ts   DAG → runtime surface by selection  (reading the self)
+critic.ts      frozen failure-mode classifiers
+kernel.ts      orchestrator: lifecycle, commits, persistence
+index.ts       public surface
+```
+
+## Status
+
+Implemented and tested (150+ tests, model-free end to end):
+
+- **Substrate** — content-addressed Merkle DAG, dirty-tracking, commits, persistence.
+- **Learning** — salience decay/reinforce, Hebbian edges, predictive-coding updates.
+- **Emergence** — value clustering (`crystallize`), self-reorganizing `consolidate`
+  ("dream") with adaptive thresholds + state migration, reflection into `theme`s.
+- **Embedding** — our own `TalonEmbedder` (model-free) behind a pluggable seam.
+- **Adaptation** — learned valence (meaning from outcomes), FSRS/DSR forgetting,
+  ADWIN drift → Spine epochs, emergent failure modes.
+- **Recall** — Generative-Agents context retrieval, PageRank centrality, modern
+  Hopfield associative recall, VSA/HDC compositional episodic memory.
+- **Refraction** — relational holograph lens compilation.
+- **Surfaces** — projector (selection), delta stream, mechanical Critic.
+- **Governance** — protected-node approval queue; runtime gate (off by default).
+
+See `RESEARCH.md` for the literature behind each mechanism.
+
+Remaining: **harness wiring** — telemetry taps (reactions/engagement/corrections →
+signals), prompt injection of the projected surface, and live reflex enforcement.
+This touches the live Talon runtime and is gated behind `TALON_SOUL_ENABLED`.