@cosmonapse/sdk 0.1.2 → 0.1.4

package/dist/index.js

@@ -55,7 +55,13 @@ var SignalType = {
   IMPRINT: "IMPRINT",
   IMPRINTED: "IMPRINTED",
   // Discovery [C]
-  DISCOVER: "DISCOVER"
+  DISCOVER: "DISCOVER",
+  // Workflow control [C]  -  cooperative cancellation of a whole trace.
+  // STOP is broadcast on the trace; every Dendrite filters by trace_id,
+  // cancels its in-flight work + engram I/O, optionally rolls back Engram
+  // writes via the saga journal, then acks with STOPPED.
+  STOP: "STOP",
+  STOPPED: "STOPPED"
 };
 var AXON_TYPES = /* @__PURE__ */ new Set([
   SignalType.AGENT_OUTPUT,
@@ -92,7 +98,11 @@ var SYNAPSE_TYPES = /* @__PURE__ */ new Set([
   SignalType.RECALL,
   SignalType.RECALLED,
   SignalType.IMPRINT,
-  SignalType.IMPRINTED
+  SignalType.IMPRINTED,
+  // Workflow control - STOP is orchestrator-gated (see Dendrite role gate);
+  // STOPPED is the per-Dendrite ack.
+  SignalType.STOP,
+  SignalType.STOPPED
 ]);
 function normalizeDirected(d) {
   if (d === null || d === void 0) return null;
@@ -125,6 +135,12 @@ function createSignal(input) {
   return signal;
 }
 function validateSignal(signal) {
+  const major = signal.v.split(".", 1)[0];
+  if (major !== "1") {
+    throw new Error(
+      `unsupported protocol version '${signal.v}': this SDK speaks major version 1 (accepts '1' or '1.x')`
+    );
+  }
   if (!signal.id.startsWith("evt_")) {
     throw new Error(`Signal id must start with 'evt_', got: ${signal.id}`);
   }
@@ -162,6 +178,7 @@ function taskSignal(args) {
   const payload = { input: args.input };
   if (args.contextRef) payload["context_ref"] = args.contextRef;
   if (args.capabilities) payload["capabilities"] = args.capabilities;
+  if (args.finalize) payload["finalize"] = true;
   return createSignal({
     type: SignalType.TASK,
     trace_id: args.traceId ?? newTraceId(),
@@ -258,9 +275,10 @@ function errorSignal(args) {
 }
 function registerSignal(args) {
   const caps = args.capabilities ?? args.directed?.capabilities ?? [];
-  const payload = { capabilities: caps };
+  const role = args.role ?? (args.engram ? "engram" : "neuron");
+  const payload = { role, capabilities: caps };
   if (args.version) payload["version"] = args.version;
-  if (args.engram) payload["engram"] = true;
+  if (args.engram || role === "engram") payload["engram"] = true;
   return createSignal({
     type: SignalType.REGISTER,
     trace_id: newTraceId(),
@@ -325,6 +343,32 @@ function bidSignal(args) {
     meta: args.meta ?? {}
   });
 }
+function taskAwardedSignal(args) {
+  const payload = { input: args.input };
+  if (args.winningBid !== void 0) payload["winning_bid"] = args.winningBid;
+  if (args.contextRef !== void 0) payload["context_ref"] = args.contextRef;
+  if (args.finalize) payload["finalize"] = true;
+  return createSignal({
+    type: SignalType.TASK_AWARDED,
+    trace_id: args.traceId,
+    parent_id: args.parentId,
+    directed: args.directed ?? null,
+    payload,
+    meta: args.meta ?? {}
+  });
+}
+function taskDeclinedSignal(args) {
+  const payload = {};
+  if (args.reason !== void 0) payload["reason"] = args.reason;
+  return createSignal({
+    type: SignalType.TASK_DECLINED,
+    trace_id: args.traceId,
+    parent_id: args.parentId,
+    directed: args.directed ?? null,
+    payload,
+    meta: args.meta ?? {}
+  });
+}
 function critiqueSignal(args) {
   return createSignal({
     type: SignalType.CRITIQUE,
@@ -520,6 +564,237 @@ function imprintedSignal(args) {
     meta: args.meta ?? {}
   });
 }
+function stopSignal(args) {
+  const payload = { rollback: Boolean(args.rollback) };
+  if (args.reason !== void 0) payload["reason"] = args.reason;
+  return createSignal({
+    type: SignalType.STOP,
+    trace_id: args.traceId,
+    parent_id: args.parentId ?? null,
+    directed: args.directed ?? null,
+    payload,
+    meta: args.meta ?? {}
+  });
+}
+function stoppedSignal(args) {
+  const payload = {
+    rolled_back: Boolean(args.rolledBack),
+    cancelled: args.cancelled ?? 0,
+    compensated: args.compensated ?? 0
+  };
+  if (args.node !== void 0) payload["node"] = args.node;
+  return createSignal({
+    type: SignalType.STOPPED,
+    trace_id: args.traceId,
+    parent_id: args.parentId ?? null,
+    directed: args.directed ?? null,
+    payload,
+    meta: args.meta ?? {}
+  });
+}
+
+// src/pathway.ts
+var TERMINAL_TYPES = /* @__PURE__ */ new Set([
+  SignalType.FINAL,
+  SignalType.ERROR
+]);
+var WAIT_TYPES = /* @__PURE__ */ new Set([
+  SignalType.AGENT_OUTPUT,
+  SignalType.CLARIFICATION,
+  SignalType.PERMISSION,
+  SignalType.ERROR,
+  SignalType.FINAL
+]);
+var SCOPE_TERMINAL_TYPES = /* @__PURE__ */ new Set([
+  SignalType.FINAL,
+  SignalType.ERROR,
+  SignalType.CLARIFICATION,
+  SignalType.PERMISSION
+]);
+var PATHWAY_TYPES = new Set(
+  Object.values(SignalType).filter(
+    (t) => t !== SignalType.TASK && t !== SignalType.REGISTER && t !== SignalType.DEREGISTER && t !== SignalType.HEARTBEAT && t !== SignalType.DISCOVER
+  )
+);
+var PathwayClosedError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "PathwayClosedError";
+  }
+};
+var Pathway = class {
+  traceId;
+  parentId;
+  role;
+  scope;
+  scopeFilter;
+  onCloseHook;
+  handlers = /* @__PURE__ */ new Map();
+  waiters = [];
+  buffered = [];
+  closed_ = false;
+  // Async iteration: a pull queue of pending `next()` resolvers and a push
+  // queue of undelivered values. `null` is the close sentinel.
+  iterPush = [];
+  iterPull = [];
+  constructor(opts) {
+    const scope = opts.scope ?? "all";
+    if (scope !== "all" && scope !== "terminal") {
+      throw new Error(`scope must be 'all' or 'terminal', got '${scope}'`);
+    }
+    this.traceId = opts.traceId;
+    this.parentId = opts.parentId ?? null;
+    this.role = opts.role ?? "originator";
+    this.scope = scope;
+    this.scopeFilter = scope === "terminal" ? SCOPE_TERMINAL_TYPES : null;
+    this.onCloseHook = opts.onClose;
+  }
+  get closed() {
+    return this.closed_;
+  }
+  // -- consumer shape #1: wait ---------------------------------------
+  /** Resolve on the next AGENT_OUTPUT, CLARIFICATION, PERMISSION, ERROR or
+   *  FINAL. Rejects with PathwayClosedError if the Pathway closes first, and
+   *  with a TimeoutError-named Error if `timeoutMs` elapses. */
+  async wait(timeoutMs) {
+    return this.waitForTypes(WAIT_TYPES, timeoutMs);
+  }
+  /** Resolve on the next Signal of the given type. */
+  async waitFor(type, timeoutMs) {
+    return this.waitForTypes(/* @__PURE__ */ new Set([type]), timeoutMs);
+  }
+  async waitForTypes(types, timeoutMs) {
+    for (let i = 0; i < this.buffered.length; i++) {
+      const sig = this.buffered[i];
+      if (types.has(sig.type)) {
+        this.buffered.splice(i, 1);
+        return sig;
+      }
+    }
+    if (this.closed_) {
+      throw new PathwayClosedError(`Pathway for trace '${this.traceId}' is closed`);
+    }
+    return new Promise((resolve, reject) => {
+      const waiter = { types, resolve, reject, settled: false };
+      let timer = null;
+      const settle = (fn) => (a) => {
+        if (waiter.settled) return;
+        waiter.settled = true;
+        if (timer !== null) clearTimeout(timer);
+        this.waiters = this.waiters.filter((w) => w !== waiter);
+        fn(a);
+      };
+      waiter.resolve = settle(resolve);
+      waiter.reject = settle(reject);
+      if (timeoutMs !== void 0) {
+        timer = setTimeout(() => {
+          const err = new Error(
+            `Pathway.wait timed out after ${timeoutMs}ms on trace '${this.traceId}'`
+          );
+          err.name = "TimeoutError";
+          waiter.reject(err);
+        }, timeoutMs);
+      }
+      this.waiters.push(waiter);
+    });
+  }
+  // -- consumer shape #2: callbacks ----------------------------------
+  /** Register a callback fired for each Signal of the given type. */
+  on(type, fn) {
+    const list = this.handlers.get(type) ?? [];
+    list.push(fn);
+    this.handlers.set(type, list);
+    return fn;
+  }
+  // -- consumer shape #3: async iteration ----------------------------
+  [Symbol.asyncIterator]() {
+    return {
+      next: () => {
+        if (this.iterPush.length > 0) {
+          const v = this.iterPush.shift();
+          return Promise.resolve(
+            v === null ? { value: void 0, done: true } : { value: v, done: false }
+          );
+        }
+        if (this.closed_) {
+          return Promise.resolve({ value: void 0, done: true });
+        }
+        return new Promise((resolve) => this.iterPull.push(resolve));
+      }
+    };
+  }
+  iterEmit(v) {
+    const pull = this.iterPull.shift();
+    if (pull) {
+      pull(v === null ? { value: void 0, done: true } : { value: v, done: false });
+    } else {
+      this.iterPush.push(v);
+    }
+  }
+  // -- lifecycle ------------------------------------------------------
+  /** Close the Pathway. Idempotent. Pending waits reject with
+   *  PathwayClosedError; iteration completes; the onClose hook fires once. */
+  async close() {
+    if (this.closed_) return;
+    this.closed_ = true;
+    for (const w of [...this.waiters]) {
+      w.reject(
+        new PathwayClosedError(
+          `Pathway for trace '${this.traceId}' closed before a matching Signal arrived`
+        )
+      );
+    }
+    this.waiters = [];
+    this.iterEmit(null);
+    if (this.onCloseHook) {
+      try {
+        await this.onCloseHook(this);
+      } catch {
+      }
+    }
+  }
+  /** `await using pathway = ...` support. */
+  async [Symbol.asyncDispose]() {
+    await this.close();
+  }
+  // -- internal: signal delivery (called by the owning Dendrite) ------
+  /** @internal */
+  async _deliver(signal) {
+    if (this.closed_) return;
+    if (this.scopeFilter !== null && !this.scopeFilter.has(signal.type)) {
+      await this.fireHandlers(signal);
+      if (TERMINAL_TYPES.has(signal.type)) await this.close();
+      return;
+    }
+    let consumed = false;
+    for (const w of [...this.waiters]) {
+      if (w.types.has(signal.type)) {
+        w.resolve(signal);
+        consumed = true;
+      }
+    }
+    if (!consumed) this.buffered.push(signal);
+    await this.fireHandlers(signal);
+    this.iterEmit(signal);
+    if (TERMINAL_TYPES.has(signal.type)) await this.close();
+  }
+  async fireHandlers(signal) {
+    for (const h of this.handlers.get(signal.type) ?? []) {
+      try {
+        await h(signal);
+      } catch {
+      }
+    }
+  }
+};
+
+// src/retry.ts
+function defaultRetryOn(outcome) {
+  if (outcome instanceof PathwayClosedError) return true;
+  if (outcome instanceof Error) return outcome.name === "TimeoutError";
+  const sig = outcome;
+  return sig.type === SignalType.ERROR && Boolean(sig.payload?.["recoverable"]);
+}
 
 // src/synapse.ts
 var MemorySubscription = class {
@@ -1796,6 +2071,16 @@ var LifecycleHooks = class {
   }
 };
 
+// src/trace-context.ts
+import { AsyncLocalStorage } from "async_hooks";
+var storage = new AsyncLocalStorage();
+function ambientTrace() {
+  return storage.getStore() ?? null;
+}
+function runWithTraceContext(traceId, parentId, fn) {
+  return storage.run([traceId, parentId], fn);
+}
+
 // src/neuron.ts
 function clarify(question, context) {
   return context === void 0 ? { __clarification__: true, question } : { __clarification__: true, question, context };
@@ -1827,122 +2112,492 @@ function isErrorOutput(output) {
   return typeof output === "object" && output !== null && output["__error__"] === true;
 }
 
-// src/neuron-mcp.ts
-var standardMcpServers = {
-  filesystem: {
-    command: "npx",
-    args: ["-y", "@modelcontextprotocol/server-filesystem"],
-    note: "Append one or more allowed directories, e.g. args=['/data']."
-  },
-  memory: {
-    command: "npx",
-    args: ["-y", "@modelcontextprotocol/server-memory"],
-    note: "Knowledge-graph memory store."
-  },
-  everything: {
-    command: "npx",
-    args: ["-y", "@modelcontextprotocol/server-everything"],
-    note: "Reference server exercising every MCP feature; handy for tests."
-  },
-  sequentialthinking: {
-    command: "npx",
-    args: ["-y", "@modelcontextprotocol/server-sequential-thinking"],
-    note: "Structured step-by-step reasoning tool."
-  },
-  fetch: {
-    command: "uvx",
-    args: ["mcp-server-fetch"],
-    note: "Fetch a URL and return its content as markdown/text."
-  },
-  git: {
-    command: "uvx",
-    args: ["mcp-server-git"],
-    note: "Read/inspect a git repo. Append --repository <path>."
-  },
-  time: {
-    command: "uvx",
-    args: ["mcp-server-time"],
-    note: "Current time and timezone conversions."
-  }
-};
-var CONTROL_KEYS = /* @__PURE__ */ new Set(["tool", "arguments", "args", "__list_tools__"]);
-function resolveLaunch(opts) {
-  const extra = opts.args ?? [];
-  if (opts.server != null) {
-    const preset = standardMcpServers[opts.server];
-    if (!preset) {
-      const available = Object.keys(standardMcpServers).sort().join(", ");
+// src/engram.ts
+var EngramBinding = class {
+  name;
+  directedId;
+  directedType;
+  defaultDeadlineMs;
+  defaultRecallMode;
+  constructor(init) {
+    this.name = init.name;
+    this.directedId = init.directedId ?? null;
+    this.directedType = init.directedType ?? null;
+    this.defaultDeadlineMs = init.defaultDeadlineMs ?? null;
+    this.defaultRecallMode = init.defaultRecallMode ?? "first";
+    if (!this.directedId && !this.directedType) {
       throw new Error(
-        `Unknown MCP server preset '${opts.server}'. Available: ${available}. (Or pass command/args to wrap any other stdio MCP server.)`
+        `EngramBinding '${this.name}' requires directedId (engram_id) or directedType (engram_kind), or both`
       );
     }
-    return { command: opts.command ?? preset.command, args: [...preset.args, ...extra] };
   }
-  if (opts.command == null) {
-    throw new Error("mcpNeuron(...) needs either `command` (+optional `args`) or a `server` preset name.");
+  /** Build the `Directed` addressing this Engram. */
+  toDirected() {
+    return { id: this.directedId, type: this.directedType, capabilities: [] };
   }
-  return { command: opts.command, args: extra };
-}
-function mcpNeuron(opts) {
-  const { command, args } = resolveLaunch(opts);
-  let client = null;
-  let connecting = null;
-  async function ensure() {
-    if (client) return client;
-    if (connecting) return connecting;
-    connecting = (async () => {
-      const clientSpec = "@modelcontextprotocol/sdk/client/index.js";
-      const stdioSpec = "@modelcontextprotocol/sdk/client/stdio.js";
-      const clientMod = await import(clientSpec);
-      const stdioMod = await import(stdioSpec);
-      const Client = clientMod.Client;
-      const StdioClientTransport = stdioMod.StdioClientTransport;
-      const transport = new StdioClientTransport({
-        command,
-        args,
-        ...opts.env ? { env: opts.env } : {},
-        ...opts.cwd ? { cwd: opts.cwd } : {}
-      });
-      const c = new Client(
-        { name: opts.clientName ?? "cosmonapse", version: opts.clientVersion ?? "0.2.0" },
-        { capabilities: {} }
-      );
-      await c.connect(transport);
-      client = c;
-      return c;
-    })();
-    return connecting;
+};
+var EngramError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = new.target.name;
   }
-  const fn = (async (input, _context) => {
-    const c = await ensure();
-    const inp = input ?? {};
-    if (inp.__list_tools__) {
-      const res2 = await c.listTools();
-      return {
-        tools: (res2.tools ?? []).map((t) => ({
-          name: t.name,
-          description: t.description ?? null,
-          input_schema: t.inputSchema ?? null
-        }))
-      };
+};
+var EngramTimeout = class extends EngramError {
+};
+var EngramCancelled = class extends EngramError {
+};
+var EngramNotBound = class extends EngramError {
+};
+var EngramOverloaded = class extends EngramError {
+};
+var Engram = class {
+  version = null;
+  // ----------------------------------------------------------------------
+  // Saga / compensating-log rollback
+  // ----------------------------------------------------------------------
+  // A backend opts in by calling `sagaRecord` from inside `imprint` with the
+  // inverse op needed to undo the write it is about to apply. `compensate`
+  // then replays those inverses in reverse (LIFO) through the public
+  // `imprint` path with no traceId/imprintId (so they neither re-journal nor
+  // consume idempotency keys). Every inverse is itself a valid
+  // add/upsert/delete, so this is fully backend-agnostic.
+  sagaJournal = /* @__PURE__ */ new Map();
+  sagaRecord(traceId, op, entry, mergeKey) {
+    if (!traceId) return;
+    let j = this.sagaJournal.get(traceId);
+    if (!j) {
+      j = [];
+      this.sagaJournal.set(traceId, j);
     }
-    let tool = inp.tool ?? opts.tool;
-    let toolArgs = inp.arguments ?? inp.args;
-    if (toolArgs == null) {
-      toolArgs = {};
-      for (const [k, v] of Object.entries(inp)) {
-        if (!CONTROL_KEYS.has(k)) toolArgs[k] = v;
+    j.push({ op, entry, mergeKey });
+  }
+  /** Reverse every journaled write for `traceId` (LIFO) and discard the
+   * journal. Returns the number of inverse ops applied. Best-effort. Only
+   * Engram state is reversed - external side effects are out of scope. */
+  async compensate(traceId) {
+    const inverses = this.sagaJournal.get(traceId);
+    if (!inverses) return 0;
+    this.sagaJournal.delete(traceId);
+    let applied = 0;
+    for (let i = inverses.length - 1; i >= 0; i--) {
+      const inv = inverses[i];
+      try {
+        const opts = inv.mergeKey !== void 0 ? { mergeKey: inv.mergeKey } : {};
+        await this.imprint(inv.op, inv.entry, opts);
+        applied++;
+      } catch {
       }
     }
-    if (!tool) {
-      const res2 = await c.listTools();
-      const names = (res2.tools ?? []).map((t) => t.name);
-      if (names.length === 1) {
-        tool = names[0];
-      } else {
-        throw new Error(
-          `MCP Neuron could not determine which tool to call. Pass tool=... (server exposes: ${JSON.stringify(names)}).`
-        );
+    return applied;
+  }
+  /** Discard the trace's saga journal without reversing anything. Called at
+   * the workflow commit point (FINAL/ERROR on the trace). */
+  async commit(traceId) {
+    this.sagaJournal.delete(traceId);
+  }
+  /** Return false if this Engram cannot satisfy the query. Default: serve all. */
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  async canServe(_query) {
+    return true;
+  }
+};
+function receipt(engramId, op, fields = {}) {
+  const error = fields.error ?? null;
+  return {
+    engramId,
+    op,
+    id: fields.id ?? null,
+    version: fields.version ?? null,
+    tookMs: fields.tookMs ?? null,
+    error,
+    ok: error === null
+  };
+}
+function entryToDict(e) {
+  const out = {
+    id: e.id,
+    content: e.content,
+    tags: [...e.tags],
+    version: e.version,
+    created_at: e.createdAt,
+    updated_at: e.updatedAt
+  };
+  if (e.mergeKey !== null) out["merge_key"] = e.mergeKey;
+  if (Object.keys(e.extra).length > 0) out["meta"] = { ...e.extra };
+  return out;
+}
+function asStringArray(v) {
+  return Array.isArray(v) ? v.filter((x) => typeof x === "string") : [];
+}
+function asObject(v) {
+  return v !== null && typeof v === "object" && !Array.isArray(v) ? v : {};
+}
+var InMemoryEngram = class extends Engram {
+  engramId;
+  engramKind;
+  capabilities;
+  entries = /* @__PURE__ */ new Map();
+  byMergeKey = /* @__PURE__ */ new Map();
+  imprintSeen = /* @__PURE__ */ new Map();
+  constructor(init = {}) {
+    super();
+    this.engramId = init.engramId ?? "engram-memory";
+    this.engramKind = init.engramKind ?? "keyvalue";
+    this.capabilities = init.capabilities ?? ["substring", "tags", "merge_key"];
+    this.version = init.version ?? "0.0.1";
+  }
+  async connect() {
+    return;
+  }
+  async close() {
+    this.entries.clear();
+    this.byMergeKey.clear();
+    this.imprintSeen.clear();
+  }
+  async recall(query, opts = {}) {
+    const q = query ?? {};
+    const text = typeof q["text"] === "string" ? q["text"].toLowerCase() : "";
+    const tagQ = typeof q["tag"] === "string" ? q["tag"] : null;
+    const mergeKey = typeof q["merge_key"] === "string" ? q["merge_key"] : null;
+    const topK = typeof q["top_k"] === "number" ? q["top_k"] : 50;
+    const filters = opts.filters ?? {};
+    const requireTags = asStringArray(filters["tags"]);
+    const since = typeof filters["since"] === "string" ? Date.parse(filters["since"]) : NaN;
+    const until = typeof filters["until"] === "string" ? Date.parse(filters["until"]) : NaN;
+    let candidates;
+    if (mergeKey !== null) {
+      const ids = this.byMergeKey.get(mergeKey) ?? [];
+      candidates = ids.map((i) => this.entries.get(i)).filter((e) => e !== void 0);
+    } else {
+      candidates = [...this.entries.values()];
+    }
+    const hits = [];
+    for (const ent of candidates) {
+      if (requireTags.length > 0 && !requireTags.every((t) => ent.tags.includes(t))) continue;
+      const updated = Date.parse(ent.updatedAt);
+      if (!Number.isNaN(since) && updated < since) continue;
+      if (!Number.isNaN(until) && updated > until) continue;
+      if (tagQ !== null && !ent.tags.includes(tagQ)) continue;
+      let score = 1;
+      if (text) {
+        const hay = String(ent.content).toLowerCase();
+        if (!hay.includes(text)) continue;
+        score = Math.min(1, text.length / Math.max(1, hay.length));
+      }
+      if (opts.minConfidence !== void 0 && score < opts.minConfidence) continue;
+      hits.push({ id: ent.id, entry: entryToDict(ent), score });
+    }
+    hits.sort((a, b) => b.score - a.score);
+    return hits.slice(0, topK);
+  }
+  async imprint(op, entry, opts = {}) {
+    const t0 = Date.now();
+    const mergeKey = opts.mergeKey ?? null;
+    const traceId = opts.traceId;
+    const tookMs = () => Date.now() - t0;
+    if (opts.imprintId !== void 0) {
+      const seen = this.imprintSeen.get(opts.imprintId);
+      if (seen !== void 0) {
+        const existing = this.entries.get(seen);
+        return receipt(this.engramId, op, {
+          id: seen,
+          version: existing ? existing.version : null,
+          tookMs: tookMs()
+        });
+      }
+    }
+    let resultingId = null;
+    let version = null;
+    if (op === "add") {
+      const ent = this.makeEntry(entry, mergeKey);
+      if (this.entries.has(ent.id)) {
+        return receipt(this.engramId, op, { error: `entry id '${ent.id}' already exists`, tookMs: tookMs() });
+      }
+      this.store(ent);
+      resultingId = ent.id;
+      version = ent.version;
+      this.sagaRecord(traceId, "delete", { id: ent.id });
+    } else if (op === "append") {
+      let ent = this.makeEntry(entry, mergeKey);
+      while (this.entries.has(ent.id)) {
+        ent = this.makeEntry({ ...entry, id: newEngramId() }, mergeKey);
+      }
+      this.store(ent);
+      resultingId = ent.id;
+      version = ent.version;
+      this.sagaRecord(traceId, "delete", { id: ent.id });
+    } else if (op === "upsert") {
+      const existingIds = this.byMergeKey.get(mergeKey ?? "") ?? [];
+      const targetId = existingIds[existingIds.length - 1];
+      const old = targetId !== void 0 ? this.entries.get(targetId) : void 0;
+      if (old !== void 0) {
+        this.sagaRecord(
+          traceId,
+          "upsert",
+          { id: old.id, content: structuredClone(old.content), tags: [...old.tags], meta: structuredClone(old.extra) },
+          old.mergeKey ?? void 0
+        );
+        const next = this.makeEntry({ ...entry, id: old.id }, mergeKey);
+        next.createdAt = old.createdAt;
+        next.version = old.version + 1;
+        this.store(next, true);
+        resultingId = next.id;
+        version = next.version;
+      } else {
+        const ent = this.makeEntry(entry, mergeKey);
+        this.store(ent);
+        resultingId = ent.id;
+        version = ent.version;
+        this.sagaRecord(traceId, "delete", { id: ent.id });
+      }
+    } else if (op === "merge") {
+      const existingIds = this.byMergeKey.get(mergeKey ?? "") ?? [];
+      const targetId = existingIds[existingIds.length - 1];
+      const old = targetId !== void 0 ? this.entries.get(targetId) : void 0;
+      if (old === void 0) {
+        return receipt(this.engramId, op, { error: `no entry for merge_key='${mergeKey}'`, tookMs: tookMs() });
+      }
+      this.sagaRecord(
+        traceId,
+        "upsert",
+        { id: old.id, content: structuredClone(old.content), tags: [...old.tags], meta: structuredClone(old.extra) },
+        old.mergeKey ?? void 0
+      );
+      const now = (/* @__PURE__ */ new Date()).toISOString();
+      const next = {
+        id: old.id,
+        content: deepMerge(old.content, entry["content"]),
+        tags: [.../* @__PURE__ */ new Set([...old.tags, ...asStringArray(entry["tags"])])],
+        mergeKey: old.mergeKey,
+        version: old.version + 1,
+        createdAt: old.createdAt,
+        updatedAt: now,
+        extra: asObject(deepMerge(old.extra, entry["meta"]))
+      };
+      this.store(next, true);
+      resultingId = next.id;
+      version = next.version;
+    } else if (op === "delete") {
+      let targetId = null;
+      const entId = entry["id"];
+      if (typeof entId === "string") {
+        targetId = entId;
+      } else if (mergeKey !== null) {
+        const ids = this.byMergeKey.get(mergeKey) ?? [];
+        targetId = ids[ids.length - 1] ?? null;
+      }
+      if (targetId === null || !this.entries.has(targetId)) {
+        return receipt(this.engramId, op, { tookMs: tookMs() });
+      }
+      const old = this.entries.get(targetId);
+      this.sagaRecord(
+        traceId,
+        "add",
+        { id: old.id, content: structuredClone(old.content), tags: [...old.tags], meta: structuredClone(old.extra) },
+        old.mergeKey ?? void 0
+      );
+      this.evict(targetId);
+      resultingId = targetId;
+      version = null;
+    } else {
+      return receipt(this.engramId, op, { error: `unknown op '${op}'`, tookMs: tookMs() });
+    }
+    if (opts.imprintId !== void 0 && resultingId !== null) {
+      this.imprintSeen.set(opts.imprintId, resultingId);
+    }
+    return receipt(this.engramId, op, { id: resultingId, version, tookMs: tookMs() });
+  }
+  /** Test/debug helper - NOT part of the Engram contract. */
+  snapshot() {
+    return [...this.entries.values()].map(entryToDict);
+  }
+  makeEntry(entry, mergeKey) {
+    const id = typeof entry["id"] === "string" ? entry["id"] : newEngramId();
+    const now = (/* @__PURE__ */ new Date()).toISOString();
+    return {
+      id,
+      content: entry["content"],
+      tags: asStringArray(entry["tags"]),
+      mergeKey,
+      version: 1,
+      createdAt: now,
+      updatedAt: now,
+      extra: asObject(entry["meta"])
+    };
+  }
+  store(ent, replace = false) {
+    if (replace) {
+      const old = this.entries.get(ent.id);
+      if (old !== void 0 && old.mergeKey) {
+        const bucket = this.byMergeKey.get(old.mergeKey);
+        if (bucket) {
+          const idx = bucket.indexOf(ent.id);
+          if (idx >= 0) bucket.splice(idx, 1);
+          if (bucket.length === 0) this.byMergeKey.delete(old.mergeKey);
+        }
+      }
+    }
+    this.entries.set(ent.id, ent);
+    if (ent.mergeKey) {
+      const bucket = this.byMergeKey.get(ent.mergeKey);
+      if (bucket) bucket.push(ent.id);
+      else this.byMergeKey.set(ent.mergeKey, [ent.id]);
+    }
+  }
+  evict(entryId) {
+    const ent = this.entries.get(entryId);
+    this.entries.delete(entryId);
+    if (ent === void 0) return;
+    if (ent.mergeKey) {
+      const bucket = this.byMergeKey.get(ent.mergeKey);
+      if (bucket) {
+        const idx = bucket.indexOf(entryId);
+        if (idx >= 0) bucket.splice(idx, 1);
+        if (bucket.length === 0) this.byMergeKey.delete(ent.mergeKey);
+      }
+    }
+  }
+};
+function deepMerge(base, incoming) {
+  if (incoming === void 0 || incoming === null) return base;
+  const bothObjects = base !== null && typeof base === "object" && !Array.isArray(base) && typeof incoming === "object" && !Array.isArray(incoming);
+  if (bothObjects) {
+    const out = { ...base };
+    for (const [k, v] of Object.entries(incoming)) {
+      out[k] = k in out ? deepMerge(out[k], v) : v;
+    }
+    return out;
+  }
+  if (Array.isArray(base) && Array.isArray(incoming)) {
+    const seen = /* @__PURE__ */ new Set();
+    const out = [];
+    for (const item of [...base, ...incoming]) {
+      const key = JSON.stringify(item);
+      if (seen.has(key)) continue;
+      seen.add(key);
+      out.push(item);
+    }
+    return out;
+  }
+  return incoming;
+}
+
+// src/neuron-mcp.ts
+var standardMcpServers = {
+  filesystem: {
+    command: "npx",
+    args: ["-y", "@modelcontextprotocol/server-filesystem"],
+    note: "Append one or more allowed directories, e.g. args=['/data']."
+  },
+  memory: {
+    command: "npx",
+    args: ["-y", "@modelcontextprotocol/server-memory"],
+    note: "Knowledge-graph memory store."
+  },
+  everything: {
+    command: "npx",
+    args: ["-y", "@modelcontextprotocol/server-everything"],
+    note: "Reference server exercising every MCP feature; handy for tests."
+  },
+  sequentialthinking: {
+    command: "npx",
+    args: ["-y", "@modelcontextprotocol/server-sequential-thinking"],
+    note: "Structured step-by-step reasoning tool."
+  },
+  fetch: {
+    command: "uvx",
+    args: ["mcp-server-fetch"],
+    note: "Fetch a URL and return its content as markdown/text."
+  },
+  git: {
+    command: "uvx",
+    args: ["mcp-server-git"],
+    note: "Read/inspect a git repo. Append --repository <path>."
+  },
+  time: {
+    command: "uvx",
+    args: ["mcp-server-time"],
+    note: "Current time and timezone conversions."
+  }
+};
+var CONTROL_KEYS = /* @__PURE__ */ new Set(["tool", "arguments", "args", "__list_tools__"]);
+function resolveLaunch(opts) {
+  const extra = opts.args ?? [];
+  if (opts.server != null) {
+    const preset = standardMcpServers[opts.server];
+    if (!preset) {
+      const available = Object.keys(standardMcpServers).sort().join(", ");
+      throw new Error(
+        `Unknown MCP server preset '${opts.server}'. Available: ${available}. (Or pass command/args to wrap any other stdio MCP server.)`
+      );
+    }
+    return { command: opts.command ?? preset.command, args: [...preset.args, ...extra] };
+  }
+  if (opts.command == null) {
+    throw new Error("mcpNeuron(...) needs either `command` (+optional `args`) or a `server` preset name.");
+  }
+  return { command: opts.command, args: extra };
+}
+function mcpNeuron(opts) {
+  const { command, args } = resolveLaunch(opts);
+  let client = null;
+  let connecting = null;
+  async function ensure() {
+    if (client) return client;
+    if (connecting) return connecting;
+    connecting = (async () => {
+      const clientSpec = "@modelcontextprotocol/sdk/client/index.js";
+      const stdioSpec = "@modelcontextprotocol/sdk/client/stdio.js";
+      const clientMod = await import(clientSpec);
+      const stdioMod = await import(stdioSpec);
+      const Client = clientMod.Client;
+      const StdioClientTransport = stdioMod.StdioClientTransport;
+      const transport = new StdioClientTransport({
+        command,
+        args,
+        ...opts.env ? { env: opts.env } : {},
+        ...opts.cwd ? { cwd: opts.cwd } : {}
+      });
+      const c = new Client(
+        { name: opts.clientName ?? "cosmonapse", version: opts.clientVersion ?? "0.2.0" },
+        { capabilities: {} }
+      );
+      await c.connect(transport);
+      client = c;
+      return c;
+    })();
+    return connecting;
+  }
+  const fn = (async (input, _context) => {
+    const c = await ensure();
+    const inp = input ?? {};
+    if (inp.__list_tools__) {
+      const res2 = await c.listTools();
+      return {
+        tools: (res2.tools ?? []).map((t) => ({
+          name: t.name,
+          description: t.description ?? null,
+          input_schema: t.inputSchema ?? null
+        }))
+      };
+    }
+    let tool = inp.tool ?? opts.tool;
+    let toolArgs = inp.arguments ?? inp.args;
+    if (toolArgs == null) {
+      toolArgs = {};
+      for (const [k, v] of Object.entries(inp)) {
+        if (!CONTROL_KEYS.has(k)) toolArgs[k] = v;
+      }
+    }
+    if (!tool) {
+      const res2 = await c.listTools();
+      const names = (res2.tools ?? []).map((t) => t.name);
+      if (names.length === 1) {
+        tool = names[0];
+      } else {
+        throw new Error(
+          `MCP Neuron could not determine which tool to call. Pass tool=... (server exposes: ${JSON.stringify(names)}).`
+        );
       }
     }
     const res = await c.callTool({ name: tool, arguments: toolArgs });
@@ -1979,8 +2634,46 @@ function readMessages(input) {
   const m = input["messages"];
   return Array.isArray(m) ? m : null;
 }
+function followupPrompt(input) {
+  const c = input["clarification"];
+  if (c !== null && typeof c === "object" && !Array.isArray(c)) {
+    const cd = c;
+    const lines = ["You previously asked a clarifying question while working on a task."];
+    if (cd["question"] !== void 0 && cd["question"] !== null) {
+      lines.push(`Your question: ${String(cd["question"])}`);
+    }
+    if ("answer" in cd) lines.push(`The answer: ${JSON.stringify(cd["answer"])}`);
+    const extra = Object.fromEntries(
+      Object.entries(cd).filter(([k]) => k !== "question" && k !== "answer")
+    );
+    if (Object.keys(extra).length) lines.push(`Additional context: ${JSON.stringify(extra)}`);
+    lines.push("Continue the original task using this answer.");
+    return lines.join("\n");
+  }
+  const p = input["permission"];
+  if (p !== null && typeof p === "object" && !Array.isArray(p)) {
+    const pd = p;
+    const granted = Boolean(pd["granted"]);
+    const lines = ["You previously requested permission while working on a task."];
+    if (pd["action"] !== void 0 && pd["action"] !== null) {
+      lines.push(`Requested action: ${String(pd["action"])}`);
+    }
+    lines.push(`The decision: ${granted ? "GRANTED" : "DENIED"}.`);
+    if (pd["reason"] !== void 0 && pd["reason"] !== null) {
+      lines.push(`Reason: ${String(pd["reason"])}`);
+    }
+    if (pd["ttl_ms"] !== void 0 && pd["ttl_ms"] !== null) {
+      lines.push(`The grant is valid for ${String(pd["ttl_ms"])} ms.`);
+    }
+    lines.push(
+      granted ? "Proceed with the action and continue the original task." : "Do not perform the action. Continue the task another way, or explain why you cannot."
+    );
+    return lines.join("\n");
+  }
+  return null;
+}
 function requireInput(input, provider) {
-  const prompt = readPrompt(input);
+  const prompt = readPrompt(input) ?? followupPrompt(input);
   const messages = readMessages(input);
   if (!prompt && !messages) {
     throw new Error(
@@ -2191,9 +2884,11 @@ var Axon = class _Axon {
   neuronId;
   capabilities;
   version;
+  neuronKind;
   fn;
   contextFetcher;
   outputParser;
+  engramBindings = /* @__PURE__ */ new Map();
   dendrite = null;
   /**
    * Decorator-registered recognisers, one bucket per capability (the asking
@@ -2202,48 +2897,139 @@ var Axon = class _Axon {
    * output by {@link applyRecognisers}.
    */
   recognisers = { error: [], clarification: [], permission: [], output: [] };
+  /** Pre-task hooks (beforeTask): transform/validate/reject the TASK input
+   *  before the Neuron runs. */
+  beforeTaskHooks = [];
   /** @internal  -  lifecycle hooks, driven by the hosting Dendrite. */
   hooks = new LifecycleHooks(this);
   constructor(opts) {
     this.neuronId = opts.neuronId;
     this.capabilities = opts.capabilities ?? [];
     this.version = opts.version;
+    this.neuronKind = opts.neuronKind ?? "neuron";
     this.fn = opts.neuronFn;
     this.contextFetcher = opts.contextFetcher ?? noopContextFetcher;
     this.outputParser = opts.outputParser;
+    for (const b of opts.engrams ?? []) {
+      if (this.engramBindings.has(b.name)) {
+        throw new Error(`Axon '${opts.neuronId}': duplicate EngramBinding name '${b.name}'`);
+      }
+      this.engramBindings.set(b.name, b);
+    }
+  }
+  /** Declared Engram bindings, keyed by name. */
+  get engrams() {
+    return new Map(this.engramBindings);
+  }
+  resolveBinding(name) {
+    const binding = this.engramBindings.get(name);
+    if (!binding) {
+      throw new EngramNotBound(
+        `Axon '${this.neuronId}': no Engram binding named '${name}'; available: ${[...this.engramBindings.keys()].sort().join(", ")}`
+      );
+    }
+    return binding;
+  }
+  /** Build the per-task helpers object handed to the Neuron as its third
+   *  argument. Helpers throw EngramNotBound for undeclared names and
+   *  require a hosting Dendrite (the only thing the Axon pulls from it). */
+  buildHelpers(traceId, parentId) {
+    const requireClient = () => {
+      if (this.dendrite === null) {
+        throw new Error(
+          `Axon '${this.neuronId}': not attached to a Dendrite; engram helpers require a hosting Dendrite`
+        );
+      }
+      return this.dendrite.engramClient;
+    };
+    return {
+      recall: async (name, args) => {
+        const binding = this.resolveBinding(name);
+        return requireClient().recall({
+          binding,
+          query: args.query,
+          traceId,
+          parentId,
+          ...args.filters !== void 0 ? { filters: args.filters } : {},
+          ...args.contextRef !== void 0 ? { contextRef: args.contextRef } : {},
+          ...args.deadlineMs !== void 0 ? { deadlineMs: args.deadlineMs } : {},
+          ...args.recallMode !== void 0 ? { recallMode: args.recallMode } : {},
+          ...args.minConfidence !== void 0 ? { minConfidence: args.minConfidence } : {},
+          ...args.meta !== void 0 ? { meta: args.meta } : {}
+        });
+      },
+      imprint: async (name, args) => {
+        const binding = this.resolveBinding(name);
+        return requireClient().imprint({
+          binding,
+          op: args.op,
+          entry: args.entry,
+          traceId,
+          parentId,
+          ...args.mergeKey !== void 0 ? { mergeKey: args.mergeKey } : {},
+          ...args.awaitAck !== void 0 ? { awaitAck: args.awaitAck } : {},
+          ...args.deadlineMs !== void 0 ? { deadlineMs: args.deadlineMs } : {},
+          ...args.meta !== void 0 ? { meta: args.meta } : {}
+        });
+      }
+    };
   }
   // -- source-paired factories --------------------------------------
   // Build an Axon already paired with one of the `neuron(source, ...)`
   // providers AND wired with the matching recogniser. No new class: the
   // result is a plain Axon.
+  /** Resolve the teach-intents decision and return (possibly augmented) source opts. */
+  static applyTeachIntents(source, opts, extra) {
+    const recognize = extra.recognize ?? true;
+    const teach = extra.teachIntents ?? (recognize && SYSTEM_CAPABLE_SOURCES.has(source.toLowerCase()));
+    if (!teach) return opts;
+    if (!SYSTEM_CAPABLE_SOURCES.has(source.toLowerCase())) {
+      throw new Error(
+        `teachIntents: true is not supported for source '${source}': its Neuron wrapper accepts no system option. Embed the convention in the prompt yourself (COSMO_INTENT_SYSTEM_PROMPT).`
+      );
+    }
+    const existing = opts?.system;
+    return {
+      ...opts ?? {},
+      system: existing ? `${existing}
+
+${COSMO_INTENT_SYSTEM_PROMPT}` : COSMO_INTENT_SYSTEM_PROMPT
+    };
+  }
   static build(neuronId, neuronFn, source, extra) {
     const recognize = extra.recognize ?? true;
     const o = { neuronId, neuronFn };
     if (extra.capabilities) o.capabilities = extra.capabilities;
     if (extra.version !== void 0) o.version = extra.version;
+    if (extra.neuronKind !== void 0) o.neuronKind = extra.neuronKind;
     if (extra.contextFetcher) o.contextFetcher = extra.contextFetcher;
     if (recognize) o.outputParser = source === "mcp" ? parseMcpIntents : parseLlmIntents;
     return new _Axon(o);
   }
   /** Axon paired with any registered Neuron source + its recogniser. */
   static fromSource(source, neuronId, opts, extra = {}) {
-    return _Axon.build(neuronId, neuron(source, opts), source, extra);
+    const o = _Axon.applyTeachIntents(source, opts, extra);
+    return _Axon.build(neuronId, neuron(source, o), source, extra);
   }
   /** Axon paired with the OpenAI Chat Completions API. */
   static openai(neuronId, opts, extra = {}) {
-    return _Axon.build(neuronId, neuron("openai", opts), "openai", extra);
+    const o = _Axon.applyTeachIntents("openai", opts, extra);
+    return _Axon.build(neuronId, neuron("openai", o), "openai", extra);
   }
   /** Axon paired with the Anthropic Messages API. */
   static anthropic(neuronId, opts, extra = {}) {
-    return _Axon.build(neuronId, neuron("anthropic", opts), "anthropic", extra);
+    const o = _Axon.applyTeachIntents("anthropic", opts, extra);
+    return _Axon.build(neuronId, neuron("anthropic", o), "anthropic", extra);
   }
   /** Axon paired with a local Ollama daemon. */
   static ollama(neuronId, opts, extra = {}) {
-    return _Axon.build(neuronId, neuron("ollama", opts), "ollama", extra);
+    const o = _Axon.applyTeachIntents("ollama", opts, extra);
+    return _Axon.build(neuronId, neuron("ollama", o), "ollama", extra);
   }
   /** Axon paired with a HuggingFace TGI / OpenAI-compatible endpoint. */
   static huggingface(neuronId, opts, extra = {}) {
-    return _Axon.build(neuronId, neuron("huggingface", opts), "huggingface", extra);
+    const o = _Axon.applyTeachIntents("huggingface", opts, extra);
+    return _Axon.build(neuronId, neuron("huggingface", o), "huggingface", extra);
   }
   /** Axon paired with a stdio MCP server. */
   static mcp(neuronId, opts, extra = {}) {
@@ -2255,6 +3041,26 @@ var Axon = class _Axon {
   // Signals). Return the intent's fields to match, or null/undefined to fall
   // through. Sync or async; multiple per capability tried in order. These run
   // after `outputParser` and before the literal `__marker__` checks.
+  /**
+   * Register a pre-task hook over the TASK's `input`. Runs before the Neuron.
+   * Sync or async; multiple hooks run in registration order, each receiving
+   * the previous one's result. Return a (new) object to replace the input,
+   * return null/undefined to pass through unchanged, or throw to reject the
+   * TASK (surfaces as an ERROR Signal, code NEURON_EXCEPTION). The natural
+   * place for input normalisation or per-Axon policy checks.
+   */
+  beforeTask(fn) {
+    this.beforeTaskHooks.push(fn);
+    return fn;
+  }
+  async applyBeforeTask(input) {
+    let current = input;
+    for (const fn of this.beforeTaskHooks) {
+      const r = await fn(current);
+      if (r !== null && r !== void 0) current = r;
+    }
+    return current;
+  }
   /** Detector returning the AGENT_OUTPUT payload, or null to wrap verbatim. */
   detectsOutput(fn) {
     this.recognisers.output.push(fn);
@@ -2325,8 +3131,21 @@ var Axon = class _Axon {
   [DETACH]() {
     this.dendrite = null;
   }
-  /** Run the Neuron and return AGENT_OUTPUT / CLARIFICATION / ERROR. */
+  /** Run the Neuron and return AGENT_OUTPUT / CLARIFICATION / ERROR.
+   *
+   * Binds the TASK's (traceId, parentId=task.id) as the ambient trace
+   * context for the whole handling pass  -  neuronFn, detectors, and hooks
+   * included  -  so engram calls made without explicit trace plumbing (e.g.
+   * `dendrite.imprint` from a `detectsOutput` hook) are attributed to this
+   * task's trace. */
   async handleTask(task) {
+    return runWithTraceContext(
+      task.trace_id,
+      task.id,
+      () => this.handleTaskInner(task)
+    );
+  }
+  async handleTaskInner(task) {
     const traceId = task.trace_id;
     const parentId = task.id;
     const input = task.payload["input"] ?? {};
@@ -2341,7 +3160,9 @@ var Axon = class _Axon {
     }
     let rawOutput;
     try {
-      rawOutput = await this.fn(input, context);
+      const effectiveInput = this.beforeTaskHooks.length ? await this.applyBeforeTask(input) : input;
+      const helpers = this.engramBindings.size ? this.buildHelpers(traceId, parentId) : void 0;
+      rawOutput = await this.fn(effectiveInput, context, helpers);
       if (this.outputParser) rawOutput = this.outputParser(rawOutput);
       rawOutput = await this.applyRecognisers(rawOutput);
     } catch (err) {
@@ -2388,6 +3209,16 @@ var Axon = class _Axon {
     return agentOutputSignal({ traceId, parentId, directed: { id: this.neuronId }, output });
   }
 };
+var COSMO_INTENT_SYSTEM_PROMPT = 'You can control the surrounding agent protocol by replying with a single JSON object carrying a "cosmo" key (either as your whole reply or inside a ```json fenced block):\n{"cosmo": "clarification", "question": "<what you need to know>"} - ask the orchestrator a question when the task is ambiguous.\n{"cosmo": "permission", "action": "<action>", "scope": {...}, "reason": "<why>"} - request approval before a sensitive action.\n{"cosmo": "error", "code": "<CODE>", "message": "<details>"} - report a structured failure.\n{"cosmo": "output", "output": {...}} - return a structured result.\nFor a normal answer, just reply with plain text - do not wrap ordinary answers in a cosmo object.';
+var SYSTEM_CAPABLE_SOURCES = /* @__PURE__ */ new Set([
+  "ollama",
+  "openai",
+  "anthropic",
+  "groq",
+  "openrouter",
+  "together",
+  "mistral"
+]);
 var INTENT_KEY = "cosmo";
 var FENCED_JSON = /```(?:json)?\s*(\{[\s\S]*?\})\s*```/g;
 function extractCosmoIntent(text) {
@@ -2460,15 +3291,241 @@ function parseMcpIntents(raw) {
     const msg = r["response"] ?? r["content"] ?? "MCP tool returned is_error";
     return { __error__: true, code: "MCP_TOOL_ERROR", message: String(msg) };
   }
-  const text = r["response"];
-  if (typeof text === "string") {
-    const intent = extractCosmoIntent(text);
-    if (intent) {
-      const marker = intentToMarker(intent);
-      if (marker) return marker;
-    }
+  const text = r["response"];
+  if (typeof text === "string") {
+    const intent = extractCosmoIntent(text);
+    if (intent) {
+      const marker = intentToMarker(intent);
+      if (marker) return marker;
+    }
+  }
+  return raw;
+}
+
+// src/engram-client.ts
+function deferred() {
+  let resolve;
+  let reject;
+  const promise = new Promise((res, rej) => {
+    resolve = res;
+    reject = rej;
+  });
+  return { promise, resolve, reject };
+}
+var EngramClient = class {
+  constructor(publisher) {
+    this.publisher = publisher;
+  }
+  publisher;
+  pendingRecalls = /* @__PURE__ */ new Map();
+  pendingImprints = /* @__PURE__ */ new Map();
+  byTrace = /* @__PURE__ */ new Map();
+  async recall(args) {
+    let engramId = args.engramId;
+    let engramKind = args.engramKind;
+    let deadlineMs = args.deadlineMs;
+    let recallMode = args.recallMode;
+    if (args.binding) {
+      engramId = engramId ?? args.binding.directedId ?? void 0;
+      engramKind = engramKind ?? args.binding.directedType ?? void 0;
+      if (deadlineMs === void 0) deadlineMs = args.binding.defaultDeadlineMs ?? void 0;
+      if (recallMode === void 0) recallMode = args.binding.defaultRecallMode;
+    }
+    const mode = recallMode ?? "first";
+    const sig = recallSignal({
+      traceId: args.traceId,
+      parentId: args.parentId,
+      directed: directedTo(engramId ?? null, { type: engramKind ?? null }),
+      query: args.query,
+      ...args.filters !== void 0 ? { filters: args.filters } : {},
+      ...args.contextRef !== void 0 ? { contextRef: args.contextRef } : {},
+      ...deadlineMs !== void 0 ? { deadlineMs } : {},
+      ...args.minConfidence !== void 0 ? { minConfidence: args.minConfidence } : {},
+      recallMode: mode,
+      ...args.meta !== void 0 ? { meta: args.meta } : {}
+    });
+    const d = deferred();
+    const pending = { deferred: d, mode, timer: null, done: false, hitsSoFar: [], engrams: [] };
+    this.pendingRecalls.set(sig.id, pending);
+    this.track(args.traceId, sig.id);
+    if (deadlineMs !== void 0 && deadlineMs > 0) {
+      pending.timer = setTimeout(() => this.onRecallDeadline(sig.id), deadlineMs);
+    }
+    try {
+      await this.publisher.publish(sig);
+    } catch (err) {
+      this.cleanupRecall(args.traceId, sig.id);
+      throw err;
+    }
+    try {
+      return await d.promise;
+    } finally {
+      this.cleanupRecall(args.traceId, sig.id);
+    }
+  }
+  async imprint(args) {
+    let engramId = args.engramId;
+    let engramKind = args.engramKind;
+    if (args.binding) {
+      engramId = engramId ?? args.binding.directedId ?? void 0;
+      engramKind = engramKind ?? args.binding.directedType ?? void 0;
+    }
+    const sig = imprintSignal({
+      traceId: args.traceId,
+      parentId: args.parentId,
+      directed: directedTo(engramId ?? null, { type: engramKind ?? null }),
+      op: args.op,
+      entry: args.entry,
+      ...args.mergeKey !== void 0 ? { mergeKey: args.mergeKey } : {},
+      ...args.meta !== void 0 ? { meta: args.meta } : {}
+    });
+    if (!args.awaitAck) {
+      await this.publisher.publish(sig);
+      return null;
+    }
+    const d = deferred();
+    const pending = { deferred: d, timer: null, done: false };
+    this.pendingImprints.set(sig.id, pending);
+    this.track(args.traceId, sig.id);
+    if (args.deadlineMs !== void 0 && args.deadlineMs > 0) {
+      pending.timer = setTimeout(() => this.onImprintDeadline(sig.id), args.deadlineMs);
+    }
+    try {
+      await this.publisher.publish(sig);
+    } catch (err) {
+      this.cleanupImprint(args.traceId, sig.id);
+      throw err;
+    }
+    try {
+      return await d.promise;
+    } finally {
+      this.cleanupImprint(args.traceId, sig.id);
+    }
+  }
+  /** Match RECALLED / IMPRINTED by parent_id and resolve pendings. */
+  deliver(sig) {
+    const pid = sig.parent_id;
+    if (pid === null) return;
+    if (sig.type === SignalType.RECALLED) {
+      const pending = this.pendingRecalls.get(pid);
+      if (pending === void 0) return;
+      const hits = hitsFromPayload(sig.payload["hits"]);
+      const engramId = typeof sig.payload["engram_id"] === "string" ? sig.payload["engram_id"] : "";
+      const tookMs = typeof sig.payload["took_ms"] === "number" ? sig.payload["took_ms"] : null;
+      const truncated = sig.payload["truncated"] === true;
+      if (pending.mode === "first") {
+        if (!pending.done) {
+          pending.done = true;
+          pending.deferred.resolve({
+            hits,
+            engramIds: engramId ? [engramId] : [],
+            truncated,
+            tookMs
+          });
+        }
+      } else {
+        pending.hitsSoFar.push(...hits);
+        if (engramId) pending.engrams.push(engramId);
+      }
+    } else if (sig.type === SignalType.IMPRINTED) {
+      const pending = this.pendingImprints.get(pid);
+      if (pending === void 0 || pending.done) return;
+      pending.done = true;
+      pending.deferred.resolve({
+        engramId: typeof sig.payload["engram_id"] === "string" ? sig.payload["engram_id"] : "",
+        op: typeof sig.payload["op"] === "string" ? sig.payload["op"] : "",
+        id: typeof sig.payload["id"] === "string" ? sig.payload["id"] : null,
+        version: typeof sig.payload["version"] === "number" ? sig.payload["version"] : null,
+        tookMs: typeof sig.payload["took_ms"] === "number" ? sig.payload["took_ms"] : null,
+        error: typeof sig.payload["error"] === "string" ? sig.payload["error"] : null,
+        ok: !(typeof sig.payload["error"] === "string")
+      });
+    }
+  }
+  /** Cancel every in-flight recall/imprint on a trace (FINAL/ERROR or shutdown). */
+  cancelTrace(traceId) {
+    const ids = this.byTrace.get(traceId);
+    this.byTrace.delete(traceId);
+    if (ids === void 0) return;
+    for (const id of ids) {
+      const pr = this.pendingRecalls.get(id);
+      if (pr !== void 0 && !pr.done) {
+        pr.done = true;
+        if (pr.timer !== null) clearTimeout(pr.timer);
+        pr.deferred.reject(new EngramCancelled(`trace ${traceId} terminated while recall ${id} in flight`));
+        this.pendingRecalls.delete(id);
+      }
+      const pi = this.pendingImprints.get(id);
+      if (pi !== void 0 && !pi.done) {
+        pi.done = true;
+        if (pi.timer !== null) clearTimeout(pi.timer);
+        pi.deferred.reject(new EngramCancelled(`trace ${traceId} terminated while imprint ${id} in flight`));
+        this.pendingImprints.delete(id);
+      }
+    }
+  }
+  cancelAll() {
+    for (const traceId of [...this.byTrace.keys()]) this.cancelTrace(traceId);
+  }
+  onRecallDeadline(id) {
+    const pending = this.pendingRecalls.get(id);
+    if (pending === void 0 || pending.done) return;
+    pending.done = true;
+    if (pending.mode === "first") {
+      pending.deferred.reject(new EngramTimeout(`RECALL ${id} elapsed deadline without any responder`));
+    } else {
+      pending.deferred.resolve({
+        hits: [...pending.hitsSoFar].sort((a, b) => b.score - a.score),
+        engramIds: [...pending.engrams],
+        truncated: false,
+        tookMs: null
+      });
+    }
+  }
+  onImprintDeadline(id) {
+    const pending = this.pendingImprints.get(id);
+    if (pending === void 0 || pending.done) return;
+    pending.done = true;
+    pending.deferred.reject(new EngramTimeout(`IMPRINT ${id} elapsed deadline without IMPRINTED`));
+  }
+  track(traceId, id) {
+    const bucket = this.byTrace.get(traceId);
+    if (bucket) bucket.add(id);
+    else this.byTrace.set(traceId, /* @__PURE__ */ new Set([id]));
+  }
+  cleanupRecall(traceId, id) {
+    const p = this.pendingRecalls.get(id);
+    if (p?.timer != null) clearTimeout(p.timer);
+    this.pendingRecalls.delete(id);
+    this.discardTrace(traceId, id);
+  }
+  cleanupImprint(traceId, id) {
+    const p = this.pendingImprints.get(id);
+    if (p?.timer != null) clearTimeout(p.timer);
+    this.pendingImprints.delete(id);
+    this.discardTrace(traceId, id);
+  }
+  discardTrace(traceId, id) {
+    const bucket = this.byTrace.get(traceId);
+    if (bucket === void 0) return;
+    bucket.delete(id);
+    if (bucket.size === 0) this.byTrace.delete(traceId);
   }
-  return raw;
+};
+function hitsFromPayload(raw) {
+  if (!Array.isArray(raw)) return [];
+  const out = [];
+  for (const h of raw) {
+    if (h === null || typeof h !== "object") continue;
+    const obj = h;
+    const entryVal = obj["entry"];
+    out.push({
+      id: typeof obj["id"] === "string" ? obj["id"] : "",
+      entry: entryVal !== null && typeof entryVal === "object" && !Array.isArray(entryVal) ? entryVal : { value: entryVal },
+      score: typeof obj["score"] === "number" ? obj["score"] : 1
+    });
+  }
+  return out;
 }
 
 // src/dendrite.ts
@@ -2479,33 +3536,72 @@ var DendriteProtocolError = class extends Error {
     this.name = "DendriteProtocolError";
   }
 };
-var Dendrite = class {
+var Dendrite = class _Dendrite {
   synapse;
   registryStore;
   namespace;
   dendriteId;
+  role;
   heartbeatMs;
   reregisterOnHeartbeat;
+  autoBid;
+  staleAfterMs;
   _axons = /* @__PURE__ */ new Map();
   handlers = /* @__PURE__ */ new Map();
   taskSub = null;
+  routedTaskSub = null;
   inboundSubs = /* @__PURE__ */ new Map();
-  // Self-scheduling setTimeout handle (not setInterval  -  see startHeartbeatLoop).
+  inflightSubs = /* @__PURE__ */ new Map();
+  pendingSubs = /* @__PURE__ */ new Set();
+  /** Recently seen CLARIFICATION_ANSWER / PERMISSION_DECISION signals keyed
+   *  by parent_id, so {@link awaitDecision} can serve an answer that arrived
+   *  before it was called (an in-process synapse can deliver the whole
+   *  request->answer chain within the original publish). Bounded FIFO. */
+  recentDecisions = /* @__PURE__ */ new Map();
+  /** Hosted Engrams keyed by engramId, plus a kind index so RECALL/IMPRINT
+   *  addressed by engramKind reach every matching host. */
+  _engrams = /* @__PURE__ */ new Map();
+  // In-flight neuron work keyed by trace_id so a STOP can abandon exactly
+  // one workflow. JS can't force-kill a running async body, so abort means
+  // 'stop awaiting + suppress the reply'; the neuron should also check the
+  // AbortSignal cooperatively where it can.
+  traceAborts = /* @__PURE__ */ new Map();
+  engramKindIndex = /* @__PURE__ */ new Map();
+  /** Engrams learned from peer REGISTER signals (possibly out-of-process). */
+  _engramRegistrations = /* @__PURE__ */ new Map();
+  engramRegKindIndex = /* @__PURE__ */ new Map();
+  /** Caller-side correlation table for RECALL/IMPRINT awaiting
+   *  RECALLED/IMPRINTED. The Dendrite owns the subscriptions and feeds it. */
+  engramClient = new EngramClient(this);
   heartbeatTimer = null;
-  // Set true by stop() so an in-flight tick won't re-arm the loop.
   heartbeatStopped = true;
   running = false;
+  /** Open Pathways keyed by trace_id (dispatch / observePathway). */
+  pathways = /* @__PURE__ */ new Map();
+  /** Per-operation Pathways keyed by the issuing request's id (matched
+   *  against inbound parent_id)  -  the generic request/reply primitive
+   *  behind awaitDecision (and a future EngramClient wiring). */
+  opPathways = /* @__PURE__ */ new Map();
   /** @internal  -  lifecycle hooks for this Dendrite. */
   hooks = new LifecycleHooks(this);
   constructor(opts) {
     if (!opts.synapse) throw new TypeError("Dendrite requires a synapse");
+    const role = opts.role ?? "orchestrator";
+    if (role !== "orchestrator" && role !== "worker") {
+      throw new Error(`role must be 'orchestrator' or 'worker', got '${role}'`);
+    }
     this.synapse = opts.synapse;
     this.registryStore = opts.registryStore ?? null;
     this.namespace = opts.namespace ?? "default";
     this.dendriteId = opts.dendriteId ?? "dendrite";
     this.heartbeatMs = opts.heartbeatMs ?? 3e4;
     this.reregisterOnHeartbeat = opts.reregisterOnHeartbeat ?? true;
-    for (const t of AXON_TYPES) this.handlers.set(t, []);
+    this.role = role;
+    this.autoBid = opts.autoBid ?? true;
+    this.staleAfterMs = opts.staleAfterMs ?? (this.heartbeatMs > 0 ? this.heartbeatMs * 3 : 0);
+    for (const t of Object.values(SignalType)) {
+      this.handlers.set(t, []);
+    }
   }
   // -- properties ----------------------------------------------------
   get axons() {
@@ -2514,70 +3610,393 @@ var Dendrite = class {
   axon(neuronId) {
     return this._axons.get(neuronId);
   }
+  /** Aggregate of every attached Axon's capabilities, deduplicated + sorted. */
+  get capabilities() {
+    const caps = /* @__PURE__ */ new Set();
+    for (const ax of this._axons.values()) for (const c of ax.capabilities) caps.add(c);
+    return [...caps].sort();
+  }
+  /** Canonical queue-group name for this Dendrite's aggregate caps, or null
+   *  when no Axons are attached. Identical Dendrites share a group. */
+  capQueueGroup() {
+    const caps = this.capabilities;
+    return caps.length ? `caps:${caps.join(",")}` : null;
+  }
+  requireOrchestrator(op) {
+    if (this.role !== "orchestrator") {
+      throw new DendriteProtocolError(
+        `Dendrite role='${this.role}' cannot perform '${op}': only role='orchestrator' Dendrites may dispatch TASK signals. Workers host Axons and emit replies / cognition signals freely.`
+      );
+    }
+  }
   // -- attachment ----------------------------------------------------
+  /**
+   * Attach an Axon to a *stopped* Dendrite. Throws if the Dendrite is
+   * running  -  a running Dendrite needs the async activation path
+   * (subscriptions, queue-group refresh, REGISTER): use
+   * `await dendrite.addAxon(axon)` instead, which works in both states.
+   */
   attachAxon(axon) {
+    if (this.running) {
+      throw new Error(
+        "attachAxon on a running Dendrite would never receive TASKs (no subscription / REGISTER is set up after start). Use `await dendrite.addAxon(axon)` instead."
+      );
+    }
+    this.attachAxonRecord(axon);
+  }
+  attachAxonRecord(axon) {
     if (this._axons.has(axon.neuronId)) {
       throw new Error(`Dendrite already has an Axon for neuronId='${axon.neuronId}'`);
     }
     this._axons.set(axon.neuronId, axon);
     axon[ATTACH](this);
   }
+  /**
+   * Attach an Axon; if the Dendrite is running, activate it live: ensure the
+   * addressed + routed TASK subscriptions exist (re-keying the routed queue
+   * group for the new aggregate cap profile), subscribe TASK_AWARDED /
+   * DISCOVER (and TASK_OFFER when autoBid), mirror to the registry store,
+   * emit REGISTER, and fire the Axon's onConnect hooks.
+   */
+  async addAxon(axon) {
+    this.attachAxonRecord(axon);
+    if (!this.running) return;
+    if (this.taskSub === null) {
+      this.taskSub = await this.synapse.subscribe(
+        this.subject(SignalType.TASK),
+        (s) => this.onTask(s)
+      );
+    }
+    await this.refreshRoutedSub();
+    await this.ensureInboundSub(SignalType.TASK_AWARDED);
+    await this.ensureInboundSub(SignalType.DISCOVER);
+    if (this.autoBid) await this.ensureInboundSub(SignalType.TASK_OFFER);
+    await this.mirrorToStore(axon, "registered");
+    await this.emitRegister(axon);
+    await axon.hooks._fireConnect();
+    axon.hooks._launchSchedule();
+  }
+  /** Detach an Axon. If running: deregister, tear down its hooks, and re-key
+   *  (or drop) the TASK subscriptions for the changed cap profile. */
+  async detachAxon(neuronId, opts = {}) {
+    const axon = this._axons.get(neuronId);
+    if (!axon) {
+      throw new Error(`Dendrite has no Axon for neuronId='${neuronId}'`);
+    }
+    if (this.running) {
+      axon.hooks._stopHooks();
+      if (this.registryStore !== null) {
+        try {
+          await this.registryStore.markDeregistered(neuronId);
+        } catch {
+        }
+      }
+      await this.emitDeregister(axon, opts.reason);
+    }
+    this._axons.delete(neuronId);
+    axon[DETACH]();
+    if (this.running && this._axons.size === 0) {
+      if (this.taskSub !== null) {
+        try {
+          await this.taskSub.unsubscribe();
+        } catch {
+        }
+        this.taskSub = null;
+      }
+      if (this.routedTaskSub !== null) {
+        try {
+          await this.routedTaskSub.unsubscribe();
+        } catch {
+        }
+        this.routedTaskSub = null;
+      }
+    } else if (this.running) {
+      await this.refreshRoutedSub();
+    }
+  }
+  /**
+   * Mount an Engram on this Dendrite. After attachment (and start), the
+   * Dendrite subscribes to RECALL/IMPRINT, routes Signals addressed to
+   * `engram.engramId` or matching `engram.engramKind` to the instance, and
+   * announces it on the Synapse with an engram REGISTER. The Engram still
+   * owns its backend lifecycle: `connect()` on start(), `close()` on stop().
+   * When the Dendrite is already running, the backend is connected and the
+   * subscriptions/REGISTER are established immediately.
+   */
+  async attachEngram(engram) {
+    if (this._engrams.has(engram.engramId)) {
+      throw new Error(`Dendrite already hosts an Engram with engramId='${engram.engramId}'`);
+    }
+    this._engrams.set(engram.engramId, engram);
+    const bucket = this.engramKindIndex.get(engram.engramKind) ?? [];
+    bucket.push(engram.engramId);
+    this.engramKindIndex.set(engram.engramKind, bucket);
+    if (this.running) {
+      await engram.connect();
+      await this.ensureInboundSub(SignalType.RECALL);
+      await this.ensureInboundSub(SignalType.IMPRINT);
+      await this.ensureInboundSub(SignalType.REGISTER);
+      await this.emitEngramRegister(engram);
+    }
+  }
+  /** Remove a hosted Engram. Closes its backend if the Dendrite is running. */
+  async detachEngram(engramId) {
+    const engram = this._engrams.get(engramId);
+    if (!engram) {
+      throw new Error(`Dendrite has no Engram with engramId='${engramId}'`);
+    }
+    if (this.running) {
+      try {
+        await engram.close();
+      } catch {
+      }
+    }
+    const bucket = this.engramKindIndex.get(engram.engramKind) ?? [];
+    const kept = bucket.filter((id) => id !== engramId);
+    if (kept.length) this.engramKindIndex.set(engram.engramKind, kept);
+    else this.engramKindIndex.delete(engram.engramKind);
+    this._engrams.delete(engramId);
+  }
+  get engrams() {
+    return new Map(this._engrams);
+  }
+  /** Engrams learned via REGISTER, keyed by directed.id (or directed.type
+   *  when no id), including in-process ones. */
+  get engramRegistrations() {
+    return new Map(this._engramRegistrations);
+  }
+  /** True when an Engram with this id/kind is reachable  -  hosted
+   *  in-process or learned from a peer's REGISTER. */
+  isEngramKnown(opts) {
+    if (opts.engramId) {
+      if (this._engrams.has(opts.engramId) || this._engramRegistrations.has(opts.engramId)) {
+        return true;
+      }
+    }
+    if (opts.engramKind) {
+      if (this.engramKindIndex.has(opts.engramKind) || this.engramRegKindIndex.has(opts.engramKind)) {
+        return true;
+      }
+    }
+    return false;
+  }
+  /** (Re)subscribe the capability-routed TASK subscription so its queue
+   *  group matches the *current* aggregate cap profile. */
+  async refreshRoutedSub() {
+    const qgroup = this.capQueueGroup();
+    if (this.routedTaskSub !== null) {
+      try {
+        await this.routedTaskSub.unsubscribe();
+      } catch {
+      }
+      this.routedTaskSub = null;
+    }
+    if (qgroup !== null) {
+      this.routedTaskSub = await this.synapse.subscribe(
+        this.routedSubject(),
+        (s) => this.onTask(s),
+        { queueGroup: qgroup }
+      );
+    }
+  }
   // -- inbound handler registration ----------------------------------
-  on(type, fn) {
-    const list = this.handlers.get(type);
-    if (!list) {
-      throw new DendriteProtocolError(`Cannot handle non-Axon type '${type}'`);
+  wrapWithFilter(fn, filter) {
+    if (!filter || filter.neuron === void 0 && filter.capability === void 0 && filter.traceId === void 0) {
+      return fn;
     }
-    list.push(fn);
+    return async (sig) => {
+      const sigNeuron = sig.directed?.id ?? null;
+      if (filter.neuron !== void 0 && sigNeuron !== filter.neuron) return;
+      if (filter.traceId !== void 0 && sig.trace_id !== filter.traceId) return;
+      if (filter.capability !== void 0) {
+        if (!await this.neuronHasCapability(sigNeuron, filter.capability)) return;
+      }
+      await fn(sig);
+    };
+  }
+  async neuronHasCapability(neuronId, capability) {
+    if (!neuronId) return false;
+    const axon = this._axons.get(neuronId);
+    if (axon) return axon.capabilities.includes(capability);
+    if (this.registryStore !== null) {
+      try {
+        const recs = await this.registryStore.list({ includeDeregistered: true });
+        const rec = recs.find((r) => r.neuron_id === neuronId);
+        return rec ? rec.capabilities.includes(capability) : false;
+      } catch {
+        return false;
+      }
+    }
+    return false;
+  }
+  on(type, fn, filter) {
+    const list = this.handlers.get(type);
+    list.push(this.wrapWithFilter(fn, filter));
     if (this.running && !this.inboundSubs.has(type)) {
-      void this.ensureInboundSub(type);
+      const p = this.ensureInboundSub(type).finally(() => this.pendingSubs.delete(p));
+      this.pendingSubs.add(p);
+      p.catch(() => {
+      });
     }
     return fn;
   }
-  onAgentOutput(fn) {
-    return this.on(SignalType.AGENT_OUTPUT, fn);
+  /**
+   * Generic handler registration for *any* SignalType  -  the escape hatch
+   * behind every named `on*` helper. New protocol types are observable the
+   * day they exist. Supports the same filters as the named helpers.
+   */
+  onSignal(type, fn, filter) {
+    return this.on(type, fn, filter);
+  }
+  /** Await until inbound subscriptions exist for `types`  -  removes the
+   *  late-registration race deterministically. Idempotent. */
+  async ensureSubscribed(...types) {
+    for (const t of types) await this.ensureInboundSub(t);
+  }
+  // -- lifecycle / reply handlers --
+  onAgentOutput(fn, filter) {
+    return this.on(SignalType.AGENT_OUTPUT, fn, filter);
   }
-  onClarification(fn) {
-    return this.on(SignalType.CLARIFICATION, fn);
+  onClarification(fn, filter) {
+    return this.on(SignalType.CLARIFICATION, fn, filter);
   }
   /**
    * Register a handler fired on inbound PERMISSION requests - the *answering*
-   * side. A central Cortex or a peer Dendrite evaluates the request (often
-   * consulting an Engram of standing grants, keyed per-neuron) and replies via
-   * {@link respondToPermission} (re-dispatch a TASK with the verdict) or
-   * {@link grantPermission} / {@link denyPermission} (emit a discrete
-   * PERMISSION_DECISION). It may also imprint the decision into an Engram so
-   * future recalls hit.
+   * side. Reply via {@link respondToPermission} (re-dispatch a TASK with the
+   * verdict) or {@link grantPermission} / {@link denyPermission} (emit a
+   * discrete PERMISSION_DECISION).
    */
-  onPermission(fn) {
-    return this.on(SignalType.PERMISSION, fn);
+  onPermission(fn, filter) {
+    return this.on(SignalType.PERMISSION, fn, filter);
   }
-  onErrorSignal(fn) {
-    return this.on(SignalType.ERROR, fn);
+  onErrorSignal(fn, filter) {
+    return this.on(SignalType.ERROR, fn, filter);
   }
-  onRegister(fn) {
-    return this.on(SignalType.REGISTER, fn);
+  /** Register a handler fired on FINAL  -  workflow conclusion. */
+  onFinal(fn, filter) {
+    return this.on(SignalType.FINAL, fn, filter);
   }
-  onDeregister(fn) {
-    return this.on(SignalType.DEREGISTER, fn);
-  }
-  onHeartbeat(fn) {
-    return this.on(SignalType.HEARTBEAT, fn);
+  /** Observe inbound TASKs (audit/logging). Observation only  -  Axon routing
+   *  happens on its own subscription and is unaffected. */
+  onTaskSignal(fn, filter) {
+    return this.on(SignalType.TASK, fn, filter);
+  }
+  onRegister(fn, filter) {
+    return this.on(SignalType.REGISTER, fn, filter);
+  }
+  onDeregister(fn, filter) {
+    return this.on(SignalType.DEREGISTER, fn, filter);
+  }
+  onHeartbeat(fn, filter) {
+    return this.on(SignalType.HEARTBEAT, fn, filter);
+  }
+  onDiscover(fn, filter) {
+    return this.on(SignalType.DISCOVER, fn, filter);
+  }
+  // -- cognition handlers --
+  onPlan(fn, filter) {
+    return this.on(SignalType.PLAN, fn, filter);
+  }
+  onThoughtDelta(fn, filter) {
+    return this.on(SignalType.THOUGHT_DELTA, fn, filter);
+  }
+  onToolCall(fn, filter) {
+    return this.on(SignalType.TOOL_CALL, fn, filter);
+  }
+  onToolResult(fn, filter) {
+    return this.on(SignalType.TOOL_RESULT, fn, filter);
+  }
+  onMemoryAppend(fn, filter) {
+    return this.on(SignalType.MEMORY_APPEND, fn, filter);
+  }
+  onCritique(fn, filter) {
+    return this.on(SignalType.CRITIQUE, fn, filter);
+  }
+  onEscalation(fn, filter) {
+    return this.on(SignalType.ESCALATION, fn, filter);
+  }
+  onConsensus(fn, filter) {
+    return this.on(SignalType.CONSENSUS, fn, filter);
+  }
+  onContextSync(fn, filter) {
+    return this.on(SignalType.CONTEXT_SYNC, fn, filter);
+  }
+  // -- routing / market handlers --
+  /** Workers use this to evaluate offers and call {@link bid} to compete.
+   *  Registering it suppresses the default auto-bidder entirely. */
+  onTaskOffer(fn, filter) {
+    return this.on(SignalType.TASK_OFFER, fn, filter);
+  }
+  /** Observe BIDs (market observability). dispatchOffer collects its own. */
+  onBid(fn, filter) {
+    return this.on(SignalType.BID, fn, filter);
+  }
+  /** Observe TASK_AWARDED. The hosting Dendrite's award-to-TASK synthesis is
+   *  unaffected by handlers here. */
+  onTaskAwarded(fn, filter) {
+    return this.on(SignalType.TASK_AWARDED, fn, filter);
+  }
+  /** e.g. release a reservation made while bidding. */
+  onTaskDeclined(fn, filter) {
+    return this.on(SignalType.TASK_DECLINED, fn, filter);
+  }
+  // -- discrete answer-path consumers --
+  /** Fired on CLARIFICATION_ANSWER  -  correlate by `sig.parent_id === the
+   *  CLARIFICATION's id`, or use {@link awaitDecision}. */
+  onClarificationAnswer(fn, filter) {
+    return this.on(SignalType.CLARIFICATION_ANSWER, fn, filter);
+  }
+  /** Fired on PERMISSION_DECISION  -  correlate by parent_id, or use
+   *  {@link awaitDecision}. */
+  onPermissionDecision(fn, filter) {
+    return this.on(SignalType.PERMISSION_DECISION, fn, filter);
+  }
+  // -- memory-traffic observers --
+  onRecalled(fn, filter) {
+    return this.on(SignalType.RECALLED, fn, filter);
+  }
+  onImprinted(fn, filter) {
+    return this.on(SignalType.IMPRINTED, fn, filter);
+  }
+  onRecallSignal(fn, filter) {
+    return this.on(SignalType.RECALL, fn, filter);
+  }
+  onImprintSignal(fn, filter) {
+    return this.on(SignalType.IMPRINT, fn, filter);
+  }
+  // -- trace-scoped helper --
+  static TRACE_DEFAULT_TYPES = [
+    SignalType.AGENT_OUTPUT,
+    SignalType.FINAL,
+    SignalType.ERROR,
+    SignalType.PLAN,
+    SignalType.THOUGHT_DELTA,
+    SignalType.TOOL_CALL,
+    SignalType.TOOL_RESULT,
+    SignalType.MEMORY_APPEND,
+    SignalType.CRITIQUE,
+    SignalType.ESCALATION,
+    SignalType.CONSENSUS,
+    SignalType.CONTEXT_SYNC,
+    SignalType.CLARIFICATION
+  ];
+  /** Register one handler for multiple types narrowed to a single workflow. */
+  onTrace(traceId, fn, types) {
+    for (const t of types ?? _Dendrite.TRACE_DEFAULT_TYPES) {
+      this.on(t, fn, { traceId });
+    }
+    return fn;
   }
   // -- lifecycle hooks ----------------------------------------------
-  /** Register a fire-once handler called after start() completes. */
   onConnect(fn) {
     return this.hooks.onConnect(fn);
   }
-  /** Register a handler called whenever this Dendrite's state refreshes. */
   onRefresh(fn) {
     return this.hooks.onRefresh(fn);
   }
-  /** Register a periodic handler that runs every `everyMs` until stop(). */
   onSchedule(everyMs, fn) {
     return this.hooks.onSchedule(everyMs, fn);
   }
-  /** Manually fire a refresh event (reason defaults to "manual"). */
   async refresh(opts = {}) {
     await this.hooks.refresh(opts);
   }
@@ -2590,11 +4009,44 @@ var Dendrite = class {
         this.subject(SignalType.TASK),
         (s) => this.onTask(s)
       );
+      const qgroup = this.capQueueGroup();
+      if (qgroup !== null) {
+        this.routedTaskSub = await this.synapse.subscribe(
+          this.routedSubject(),
+          (s) => this.onTask(s),
+          { queueGroup: qgroup }
+        );
+      }
+      await this.ensureInboundSub(SignalType.TASK_AWARDED);
+      await this.ensureInboundSub(SignalType.DISCOVER);
+      await this.ensureInboundSub(SignalType.STOP);
+      if (this.autoBid) await this.ensureInboundSub(SignalType.TASK_OFFER);
       for (const axon of this._axons.values()) {
         await this.mirrorToStore(axon, "registered");
         await this.emitRegister(axon);
       }
     }
+    if (this._engrams.size > 0) {
+      for (const engram of this._engrams.values()) {
+        try {
+          await engram.connect();
+        } catch {
+        }
+      }
+      await this.ensureInboundSub(SignalType.RECALL);
+      await this.ensureInboundSub(SignalType.IMPRINT);
+      await this.ensureInboundSub(SignalType.FINAL);
+      await this.ensureInboundSub(SignalType.ERROR);
+      await this.ensureInboundSub(SignalType.REGISTER);
+      for (const engram of this._engrams.values()) {
+        try {
+          await this.emitEngramRegister(engram);
+        } catch {
+        }
+      }
+    }
+    await this.ensureInboundSub(SignalType.RECALLED);
+    await this.ensureInboundSub(SignalType.IMPRINTED);
     for (const [type, hs] of this.handlers) {
       if (hs.length) await this.ensureInboundSub(type);
     }
@@ -2603,6 +4055,7 @@ var Dendrite = class {
         await this.ensureInboundSub(t);
       }
     }
+    await this.ensureInboundSub(SignalType.STOP);
     this.running = true;
     if (this._axons.size > 0 && this.heartbeatMs > 0) {
       this.startHeartbeatLoop();
@@ -2614,17 +4067,6 @@ var Dendrite = class {
       axon.hooks._launchSchedule();
     }
   }
-  /**
-   * Heartbeat as a self-scheduling async loop rather than `setInterval`.
-   *
-   * Why not setInterval: it fires on a fixed wall-clock cadence regardless of
-   * whether the previous tick finished, so under load ticks overlap and the
-   * effective interval drifts; and because the callback is sync, any rejection
-   * from the async work inside is an unhandled rejection that setInterval
-   * silently drops. Here each tick is fully awaited, its errors are caught, and
-   * only then is the next tick scheduled  -  matching the Python SDK's
-   * asyncio.Task semantics (structured error handling + clean cancellation).
-   */
   startHeartbeatLoop() {
     this.heartbeatStopped = false;
     const schedule = () => {
@@ -2644,8 +4086,29 @@ var Dendrite = class {
     schedule();
   }
   async stop(reason) {
+    for (const pw of [...this.pathways.values()]) {
+      try {
+        await pw.close();
+      } catch {
+      }
+    }
+    this.pathways.clear();
+    for (const pw of [...this.opPathways.values()]) {
+      try {
+        await pw.close();
+      } catch {
+      }
+    }
+    this.opPathways.clear();
+    this.engramClient.cancelAll();
     if (!this.running) return;
     this.running = false;
+    for (const engram of this._engrams.values()) {
+      try {
+        await engram.close();
+      } catch {
+      }
+    }
     this.hooks._stopHooks();
     for (const axon of this._axons.values()) axon.hooks._stopHooks();
     this.heartbeatStopped = true;
@@ -2657,6 +4120,10 @@ var Dendrite = class {
       await this.taskSub.unsubscribe();
       this.taskSub = null;
     }
+    if (this.routedTaskSub !== null) {
+      await this.routedTaskSub.unsubscribe();
+      this.routedTaskSub = null;
+    }
     for (const sub of this.inboundSubs.values()) {
       try {
         await sub.unsubscribe();
@@ -2674,20 +4141,6 @@ var Dendrite = class {
       await this.emitDeregister(axon, reason);
     }
   }
-  /**
-   * Explicit-resource-management hook so a Dendrite can be used with
-   * `await using`  -  the TS equivalent of Python's `async with dendrite:`.
-   *
-   * ```ts
-   * await using dendrite = new Dendrite({ synapse });
-   * dendrite.attachAxon(axon);
-   * await dendrite.start();
-   * // ... stop() runs automatically when this scope exits, even on throw.
-   * ```
-   *
-   * Idempotent: stop() is a no-op if the Dendrite was never started or already
-   * stopped. As with stop(), the caller still owns the Synapse/registry store.
-   */
   async [Symbol.asyncDispose]() {
     await this.stop();
   }
@@ -2702,29 +4155,390 @@ var Dendrite = class {
   }
   /** All known records, optionally filtered (live records only by default). */
   async registrySnapshot(opts = {}) {
-    return this.requireStore().list(opts);
+    const { maxAgeMs, ...listOpts } = opts;
+    const records = await this.requireStore().list(listOpts);
+    return maxAgeMs !== void 0 ? _Dendrite.filterFresh(records, maxAgeMs) : records;
   }
-  /** Live (non-deregistered) records, optionally filtered by capability. */
+  /** Live (non-deregistered) records, optionally filtered by capability.
+   *  `maxAgeMs` additionally drops records whose last heartbeat is older  -
+   *  a read-side freshness guard when the background sweep can't be relied on. */
   async findNeurons(opts = {}) {
-    return this.requireStore().list({
+    const records = await this.requireStore().list({
       ...opts.capability !== void 0 ? { capability: opts.capability } : {},
       includeDeregistered: false
     });
+    return opts.maxAgeMs !== void 0 ? _Dendrite.filterFresh(records, opts.maxAgeMs) : records;
+  }
+  static filterFresh(records, maxAgeMs) {
+    const now = Date.now();
+    return records.filter((r) => {
+      const seen = r.last_heartbeat ?? r.registered_at;
+      if (!seen) return false;
+      return now - Date.parse(seen) <= maxAgeMs;
+    });
   }
   // -- outbound primitives ------------------------------------------
+  /**
+   * Emit a TASK. Addressed (`neuron`) or capability-routed (`capabilities`)
+   *  -  at least one must be set. `finalize: true` tags the TASK so the
+   * handling worker Dendrite promotes a successful AGENT_OUTPUT to FINAL
+   * (terminal-handler finalize  -  see {@link dispatch}). Only
+   * orchestrator-role Dendrites may dispatch.
+   */
   async dispatchTask(args) {
+    this.requireOrchestrator("dispatchTask");
+    if (!args.neuron && !args.capabilities?.length) {
+      throw new Error(
+        "dispatchTask requires either neuron (addressed) or capabilities (capability-routed)"
+      );
+    }
     const sig = taskSignal({
-      directed: { id: args.neuron },
       input: args.input,
+      ...args.neuron ? { directed: { id: args.neuron } } : {},
       ...args.traceId !== void 0 ? { traceId: args.traceId } : {},
       ...args.parentId !== void 0 ? { parentId: args.parentId } : {},
       ...args.contextRef !== void 0 ? { contextRef: args.contextRef } : {},
       ...args.capabilities !== void 0 ? { capabilities: args.capabilities } : {},
+      ...args.finalize !== void 0 ? { finalize: args.finalize } : {},
+      ...args.meta !== void 0 ? { meta: args.meta } : {}
+    });
+    await this.publishTask(sig);
+    return sig;
+  }
+  /** Publish a TASK to the right subject for its routing mode. Addressed ->
+   *  broadcast subject; capability-routed -> queue-grouped routed subject. */
+  async publishTask(sig) {
+    const subject = sig.directed?.id ? this.subject(SignalType.TASK) : sig.payload["capabilities"]?.length ? this.routedSubject() : this.subject(SignalType.TASK);
+    await this.synapse.publish(subject, sig);
+  }
+  // -- Pathway-based dispatch ----------------------------------------
+  /**
+   * Dispatch a TASK and return a {@link Pathway} scoped to its trace  -
+   * await it, attach callbacks, or iterate:
+   *
+   * ```ts
+   * // 1) sequential / request-reply
+   * const pw = await orch.dispatch({ neuron: "summarize", input });
+   * const out = await pw.wait();
+   *
+   * // 2) reactive
+   * pw.on(SignalType.PLAN, (sig) => { ... });
+   *
+   * // 3) streaming
+   * for await (const sig of pw) { ... }
+   * ```
+   *
+   * `capabilities` instead of `neuron` gives event-driven dispatch. Delivery
+   * is exactly-once within a queue group (identical cap profiles) but
+   * **at-least-once across heterogeneous groups**  -  use
+   * {@link dispatchOffer} when overlapping profiles need an atomic claim.
+   *
+   * `scope: "terminal"` filters delivery to FINAL / ERROR / CLARIFICATION /
+   * PERMISSION. `finalize` (default: true exactly when scope is "terminal")
+   * tags the TASK for terminal-handler finalize: the worker Dendrite promotes
+   * a successful AGENT_OUTPUT by also emitting FINAL  -  a default Axon never
+   * emits FINAL itself, so a terminal-scoped Pathway would otherwise never
+   * resolve against stock workers.
+   */
+  async dispatch(args) {
+    this.requireOrchestrator("dispatch");
+    if (!args.neuron && !args.capabilities?.length) {
+      throw new Error(
+        "dispatch requires either neuron (addressed) or capabilities (capability-routed)"
+      );
+    }
+    const scope = args.scope ?? "all";
+    const finalize = args.finalize ?? scope === "terminal";
+    const tid = args.traceId ?? newTraceId();
+    await this.ensurePathwaySubs();
+    const pathway = new Pathway({
+      traceId: tid,
+      role: "originator",
+      scope,
+      onClose: (pw) => {
+        this.pathways.delete(pw.traceId);
+      }
+    });
+    this.pathways.set(tid, pathway);
+    const sig = taskSignal({
+      input: args.input,
+      traceId: tid,
+      ...args.neuron ? { directed: { id: args.neuron } } : {},
+      ...args.parentId !== void 0 ? { parentId: args.parentId } : {},
+      ...args.contextRef !== void 0 ? { contextRef: args.contextRef } : {},
+      ...args.capabilities !== void 0 ? { capabilities: args.capabilities } : {},
+      finalize,
+      ...args.meta !== void 0 ? { meta: args.meta } : {}
+    });
+    try {
+      await this.publishTask(sig);
+    } catch (err) {
+      this.pathways.delete(tid);
+      await pathway.close();
+      throw err;
+    }
+    return pathway;
+  }
+  /** Sync-shape sugar: dispatch, await the first matching Signal, close the
+   *  Pathway, return the Signal. Use `scope: "terminal"` to wait only for
+   *  FINAL / ERROR / CLARIFICATION / PERMISSION. */
+  async dispatchAndWait(args) {
+    const { timeoutMs, retry, ...rest } = args;
+    if (retry) {
+      return this.runWithRetry({ ...rest, retry, ...timeoutMs !== void 0 ? { timeoutMs } : {} });
+    }
+    const pathway = await this.dispatch(rest);
+    try {
+      return await pathway.wait(timeoutMs ?? 3e4);
+    } finally {
+      await pathway.close();
+    }
+  }
+  /** Async-shape sugar: dispatch, return the live Pathway immediately. The
+   *  caller attaches `pw.on(...)` callbacks or iterates. */
+  async dispatchAndSubscribe(args) {
+    return this.dispatch(args);
+  }
+  /** Open a Pathway in *observer* role for a trace another peer started. */
+  async observePathway(traceId) {
+    if (this.pathways.has(traceId)) {
+      throw new Error(`Dendrite already has a Pathway open for trace '${traceId}'`);
+    }
+    await this.ensurePathwaySubs();
+    const pathway = new Pathway({
+      traceId,
+      role: "observer",
+      onClose: (pw) => {
+        this.pathways.delete(pw.traceId);
+      }
+    });
+    this.pathways.set(traceId, pathway);
+    return pathway;
+  }
+  async ensurePathwaySubs() {
+    for (const t of PATHWAY_TYPES) await this.ensureInboundSub(t);
+  }
+  // -- per-operation (request/reply) Pathways -------------------------
+  openOpPathway(opId, traceId) {
+    const pathway = new Pathway({
+      traceId,
+      parentId: opId,
+      role: "originator",
+      onClose: (pw) => {
+        if (pw.parentId !== null) this.opPathways.delete(pw.parentId);
+      }
+    });
+    this.opPathways.set(opId, pathway);
+    return pathway;
+  }
+  async cancelOpPathways(traceId) {
+    for (const pw of [...this.opPathways.values()].filter((p) => p.traceId === traceId)) {
+      try {
+        await pw.close();
+      } catch {
+      }
+    }
+  }
+  /**
+   * Await the discrete answer to a CLARIFICATION or PERMISSION request.
+   *
+   * Opens a per-operation Pathway keyed on `request.id` and resolves on the
+   * first CLARIFICATION_ANSWER / PERMISSION_DECISION whose parent_id matches.
+   * The awaitable counterpart to {@link onClarificationAnswer} /
+   * {@link onPermissionDecision}.
+   */
+  async awaitDecision(request, opts = {}) {
+    let expected;
+    if (request.type === SignalType.CLARIFICATION) {
+      expected = SignalType.CLARIFICATION_ANSWER;
+    } else if (request.type === SignalType.PERMISSION) {
+      expected = SignalType.PERMISSION_DECISION;
+    } else {
+      throw new DendriteProtocolError(
+        `awaitDecision expects a CLARIFICATION or PERMISSION signal, got '${request.type}'`
+      );
+    }
+    await this.ensureInboundSub(expected);
+    const cached = this.recentDecisions.get(request.id);
+    if (cached && cached.type === expected) {
+      this.recentDecisions.delete(request.id);
+      return cached;
+    }
+    const pathway = this.openOpPathway(request.id, request.trace_id);
+    try {
+      return await pathway.waitFor(expected, opts.timeoutMs ?? 3e4);
+    } finally {
+      await pathway.close();
+    }
+  }
+  // -- competitive bidding: TASK_OFFER / BID / TASK_AWARDED ------------
+  /**
+   * Broadcast a TASK_OFFER, collect BIDs for `deadlineMs`, award the winner
+   * per `select` ("first_bid" | "lowest_cost" | "highest_confidence"), and
+   * return a Pathway scoped to the resulting workflow. Losers get
+   * TASK_DECLINED. Throws a TimeoutError-named Error when no BID arrives.
+   * `finalize` follows the same rule as {@link dispatch}.
+   */
+  async dispatchOffer(args) {
+    this.requireOrchestrator("dispatchOffer");
+    const select = args.select ?? "first_bid";
+    if (!["first_bid", "lowest_cost", "highest_confidence"].includes(select)) {
+      throw new Error(
+        `select must be 'first_bid' / 'lowest_cost' / 'highest_confidence', got '${select}'`
+      );
+    }
+    const deadlineMs = args.deadlineMs ?? 250;
+    const scope = args.scope ?? "all";
+    const finalize = args.finalize ?? scope === "terminal";
+    const tid = args.traceId ?? newTraceId();
+    await this.ensurePathwaySubs();
+    await this.ensureInboundSub(SignalType.BID);
+    const pathway = new Pathway({
+      traceId: tid,
+      role: "originator",
+      scope,
+      onClose: (pw) => {
+        this.pathways.delete(pw.traceId);
+      }
+    });
+    this.pathways.set(tid, pathway);
+    const offer = taskOfferSignal({
+      traceId: tid,
+      input: args.input,
+      deadlineMs,
+      ...args.parentId !== void 0 ? { parentId: args.parentId } : {},
+      ...args.capabilities !== void 0 ? { capabilities: args.capabilities } : {},
+      ...args.meta !== void 0 ? { meta: args.meta } : {}
+    });
+    const bids = [];
+    let firstBid = null;
+    const firstBidArrived = new Promise((resolve) => {
+      firstBid = resolve;
+    });
+    pathway.on(SignalType.BID, (sig) => {
+      bids.push(sig);
+      if (select === "first_bid") firstBid?.(sig);
+    });
+    try {
+      await this.emit(offer);
+    } catch (err) {
+      this.pathways.delete(tid);
+      await pathway.close();
+      throw err;
+    }
+    const sleep = (ms) => new Promise((r) => setTimeout(() => r(null), ms));
+    if (select === "first_bid") {
+      const winnerOrNull = await Promise.race([firstBidArrived, sleep(deadlineMs)]);
+      if (winnerOrNull === null && bids.length === 0) {
+        await pathway.close();
+        const err = new Error(`dispatchOffer: no BID arrived within ${deadlineMs}ms`);
+        err.name = "TimeoutError";
+        throw err;
+      }
+    } else {
+      await sleep(deadlineMs);
+      if (bids.length === 0) {
+        await pathway.close();
+        const err = new Error(`dispatchOffer: no BID arrived within ${deadlineMs}ms`);
+        err.name = "TimeoutError";
+        throw err;
+      }
+    }
+    let winner;
+    if (select === "first_bid") {
+      winner = bids[0];
+    } else if (select === "lowest_cost") {
+      winner = bids.reduce(
+        (a, b) => (b.payload["cost"] ?? Infinity) < (a.payload["cost"] ?? Infinity) ? b : a
+      );
+    } else {
+      winner = bids.reduce(
+        (a, b) => (b.payload["confidence"] ?? -Infinity) > (a.payload["confidence"] ?? -Infinity) ? b : a
+      );
+    }
+    for (const b of bids) {
+      if (b.id === winner.id) continue;
+      const bNeuron = b.directed?.id ?? null;
+      try {
+        await this.emit(
+          taskDeclinedSignal({
+            traceId: tid,
+            parentId: b.id,
+            reason: "not selected",
+            ...bNeuron ? { directed: { id: bNeuron } } : {}
+          })
+        );
+      } catch {
+      }
+    }
+    const winnerNeuron = winner.directed?.id ?? null;
+    const winningBid = {};
+    for (const k of ["cost", "eta_ms", "confidence"]) {
+      if (k in winner.payload) winningBid[k] = winner.payload[k];
+    }
+    const awarded = taskAwardedSignal({
+      traceId: tid,
+      parentId: winner.id,
+      input: args.input,
+      winningBid,
+      finalize,
+      ...winnerNeuron ? { directed: { id: winnerNeuron } } : {},
+      ...args.contextRef !== void 0 ? { contextRef: args.contextRef } : {}
+    });
+    try {
+      await this.emit(awarded);
+    } catch (err) {
+      await pathway.close();
+      throw err;
+    }
+    return pathway;
+  }
+  /**
+   * Emit a BID in response to a TASK_OFFER, on behalf of the local Axon named
+   * by `neuron`. Bypasses the role guard  -  a worker bidding announces
+   * capability, not orchestration.
+   */
+  async bid(offer, args) {
+    if (offer.type !== SignalType.TASK_OFFER) {
+      throw new DendriteProtocolError(
+        `bid() expects a TASK_OFFER signal, got '${offer.type}'`
+      );
+    }
+    const sig = bidSignal({
+      traceId: offer.trace_id,
+      parentId: offer.id,
+      directed: { id: args.neuron },
+      cost: args.cost,
+      ...args.etaMs !== void 0 ? { etaMs: args.etaMs } : {},
+      ...args.confidence !== void 0 ? { confidence: args.confidence } : {},
       ...args.meta !== void 0 ? { meta: args.meta } : {}
     });
-    await this.emit(sig);
+    await this.publish(sig);
     return sig;
   }
+  /** Default bidder: first hosted Axon whose caps cover the offer answers
+   *  (cost 0, confidence 1). No-op when nothing matches. */
+  async maybeAutoBid(offer) {
+    const requested = new Set(
+      offer.payload["capabilities"] ?? []
+    );
+    for (const axon of this._axons.values()) {
+      if (requested.size && ![...requested].every((c) => axon.capabilities.includes(c))) {
+        continue;
+      }
+      try {
+        await this.bid(offer, {
+          neuron: axon.neuronId,
+          cost: 0,
+          confidence: 1,
+          meta: { auto_bid: true }
+        });
+      } catch {
+      }
+      return;
+    }
+  }
+  // -- reply / cognition emit helpers ---------------------------------
   async emitFinal(args) {
     const sig = finalSignal({
       traceId: args.traceId,
@@ -2749,16 +4563,187 @@ var Dendrite = class {
     await this.emit(sig);
     return sig;
   }
-  /** Emit a synapse-side Signal. Refuses Axon-owned types. */
+  async emitPlan(args) {
+    const sig = planSignal({
+      traceId: args.traceId,
+      parentId: args.parentId,
+      steps: args.steps,
+      directed: { id: args.neuron ?? this.dendriteId },
+      ...args.rationale !== void 0 ? { rationale: args.rationale } : {},
+      ...args.meta !== void 0 ? { meta: args.meta } : {}
+    });
+    await this.emit(sig);
+    return sig;
+  }
+  async emitThoughtDelta(args) {
+    const sig = thoughtDeltaSignal({
+      traceId: args.traceId,
+      parentId: args.parentId,
+      delta: args.delta,
+      directed: { id: args.neuron ?? this.dendriteId },
+      ...args.seq !== void 0 ? { seq: args.seq } : {},
+      ...args.meta !== void 0 ? { meta: args.meta } : {}
+    });
+    await this.emit(sig);
+    return sig;
+  }
+  async emitToolCall(args) {
+    const sig = toolCallSignal({
+      traceId: args.traceId,
+      parentId: args.parentId,
+      tool: args.tool,
+      args: args.args_,
+      directed: { id: args.neuron ?? this.dendriteId },
+      ...args.callId !== void 0 ? { callId: args.callId } : {},
+      ...args.meta !== void 0 ? { meta: args.meta } : {}
+    });
+    await this.emit(sig);
+    return sig;
+  }
+  async emitToolResult(args) {
+    const sig = toolResultSignal({
+      traceId: args.traceId,
+      parentId: args.parentId,
+      tool: args.tool,
+      directed: { id: args.neuron ?? this.dendriteId },
+      ...args.result !== void 0 ? { result: args.result } : {},
+      ...args.error !== void 0 ? { error: args.error } : {},
+      ...args.callId !== void 0 ? { callId: args.callId } : {},
+      ...args.meta !== void 0 ? { meta: args.meta } : {}
+    });
+    await this.emit(sig);
+    return sig;
+  }
+  async emitMemoryAppend(args) {
+    const sig = memoryAppendSignal({
+      traceId: args.traceId,
+      parentId: args.parentId,
+      key: args.key,
+      value: args.value,
+      directed: { id: args.neuron ?? this.dendriteId },
+      ...args.meta !== void 0 ? { meta: args.meta } : {}
+    });
+    await this.emit(sig);
+    return sig;
+  }
+  async emitCritique(args) {
+    const sig = critiqueSignal({
+      traceId: args.traceId,
+      parentId: args.parentId,
+      targetEventId: args.targetEventId,
+      issues: args.issues,
+      verdict: args.verdict,
+      directed: { id: args.neuron ?? this.dendriteId },
+      ...args.meta !== void 0 ? { meta: args.meta } : {}
+    });
+    await this.emit(sig);
+    return sig;
+  }
+  async emitEscalation(args) {
+    const sig = escalationSignal({
+      traceId: args.traceId,
+      parentId: args.parentId,
+      reason: args.reason,
+      directed: { id: args.neuron ?? this.dendriteId },
+      ...args.target !== void 0 ? { target: args.target } : {},
+      ...args.context !== void 0 ? { context: args.context } : {},
+      ...args.meta !== void 0 ? { meta: args.meta } : {}
+    });
+    await this.emit(sig);
+    return sig;
+  }
+  async emitConsensus(args) {
+    const sig = consensusSignal({
+      traceId: args.traceId,
+      parentId: args.parentId,
+      members: args.members,
+      verdict: args.verdict,
+      directed: { id: args.neuron ?? this.dendriteId },
+      ...args.votes !== void 0 ? { votes: args.votes } : {},
+      ...args.meta !== void 0 ? { meta: args.meta } : {}
+    });
+    await this.emit(sig);
+    return sig;
+  }
+  async emitContextSync(args) {
+    const sig = contextSyncSignal({
+      traceId: args.traceId,
+      parentId: args.parentId,
+      snapshot: args.snapshot,
+      directed: { id: args.neuron ?? this.dendriteId },
+      ...args.version !== void 0 ? { version: args.version } : {},
+      ...args.meta !== void 0 ? { meta: args.meta } : {}
+    });
+    await this.emit(sig);
+    return sig;
+  }
+  // -- close-the-loop helpers ------------------------------------------
+  /**
+   * Reply to a CLARIFICATION by re-dispatching a TASK with the answer. The
+   * new TASK is addressed by default to the asking Neuron, with parentId =
+   * the clarification's id and the original traceId carried over. Input
+   * shape: `{ clarification: { question, answer, ...extra } }`.
+   */
+  async respondToClarification(request, opts) {
+    if (request.type !== SignalType.CLARIFICATION) {
+      throw new DendriteProtocolError(
+        `respondToClarification expects a CLARIFICATION signal, got '${request.type}'`
+      );
+    }
+    const target = opts.neuron ?? request.directed?.id ?? null;
+    if (!target) {
+      throw new DendriteProtocolError(
+        "respondToClarification: signal has no neuron and no neuron override - nowhere to dispatch the follow-up TASK"
+      );
+    }
+    const clarification = {
+      question: request.payload["question"] ?? null,
+      answer: opts.answer
+    };
+    if (opts.extra !== void 0) Object.assign(clarification, opts.extra);
+    return this.dispatchTask({
+      neuron: target,
+      input: { clarification },
+      traceId: request.trace_id,
+      parentId: request.id,
+      ...opts.meta !== void 0 ? { meta: opts.meta } : {}
+    });
+  }
+  /**
+   * Reply to an ESCALATION by dispatching a TASK to the escalation target
+   * (default: `payload.target`). Default input:
+   * `{ escalation: { reason, context, from } }`.
+   */
+  async respondToEscalation(request, opts = {}) {
+    if (request.type !== SignalType.ESCALATION) {
+      throw new DendriteProtocolError(
+        `respondToEscalation expects an ESCALATION signal, got '${request.type}'`
+      );
+    }
+    const target = opts.neuron ?? request.payload["target"] ?? null;
+    if (!target) {
+      throw new DendriteProtocolError(
+        "respondToEscalation: signal has no payload.target and no neuron override - nowhere to dispatch the follow-up TASK"
+      );
+    }
+    const input = opts.input ?? {
+      escalation: {
+        reason: request.payload["reason"] ?? null,
+        context: request.payload["context"] ?? null,
+        from: request.directed?.id ?? null
+      }
+    };
+    return this.dispatchTask({
+      neuron: target,
+      input,
+      traceId: request.trace_id,
+      parentId: request.id,
+      ...opts.meta !== void 0 ? { meta: opts.meta } : {}
+    });
+  }
   /**
    * Reply to a PERMISSION by re-dispatching a TASK carrying the verdict.
-   *
-   * The "send it back to the axon" path: the follow-up TASK is addressed by
-   * default to the Neuron that asked (`signal.neuron`), with `parentId` = the
-   * PERMISSION's id and the original `traceId` carried over, so the Neuron
-   * resumes on the same thread and can imprint the decision into an Engram (or
-   * recall it next time). New TASK input: `{ permission: { action, granted,
-   * reason?, ttlMs?, ...extra } }`.
+   * Input shape: `{ permission: { action, granted, reason?, ttl_ms?, ...extra } }`.
    */
   async respondToPermission(request, opts) {
     if (request.type !== SignalType.PERMISSION) {
@@ -2788,14 +4773,7 @@ var Dendrite = class {
     });
   }
   // -- cognition decision signals (discrete, decentralised option) -----
-  // Thin, stateless emit helpers for the new response signal types - no
-  // correlation client. Use these when you want the decision to travel as a
-  // discrete PERMISSION_DECISION / CLARIFICATION_ANSWER signal (e.g. for a
-  // peer/observer to imprint into an Engram) rather than as a re-dispatched
-  // TASK. Published via `publish` so any Dendrite - including a peer - can
-  // answer; correlation, if needed, is the developer's choice.
-  /** Approve a PERMISSION request. `ttlMs` optionally advertises how long the
-   * grant is valid so the requester can cache it (e.g. in an Engram). */
+  /** Approve a PERMISSION request. */
   async grantPermission(request, opts = {}) {
     return this.decidePermission(request, true, opts);
   }
@@ -2809,707 +4787,755 @@ var Dendrite = class {
         `grant/denyPermission expects a PERMISSION signal, got '${request.type}'`
       );
     }
-    const sig = permissionDecisionSignal({
-      traceId: request.trace_id,
-      parentId: request.id,
-      granted,
-      directed: { id: this.dendriteId },
-      ...opts.reason !== void 0 ? { reason: opts.reason } : {},
-      ...opts.ttlMs !== void 0 ? { ttlMs: opts.ttlMs } : {},
-      ...opts.meta !== void 0 ? { meta: opts.meta } : {}
-    });
-    await this.publish(sig);
-    return sig;
-  }
-  /** Answer a *blocking* CLARIFICATION (the Neuron called ask(...) and is
-   * awaiting). Distinct from the legacy return-marker flow. */
-  async answerClarification(request, answer, opts = {}) {
-    if (request.type !== SignalType.CLARIFICATION) {
-      throw new DendriteProtocolError(
-        `answerClarification expects a CLARIFICATION signal, got '${request.type}'`
-      );
-    }
-    const sig = clarificationAnswerSignal({
-      traceId: request.trace_id,
-      parentId: request.id,
-      answer,
-      directed: { id: this.dendriteId },
-      ...opts.meta !== void 0 ? { meta: opts.meta } : {}
-    });
-    await this.publish(sig);
-    return sig;
-  }
-  async emit(signal) {
-    if (!SYNAPSE_TYPES.has(signal.type)) {
-      throw new DendriteProtocolError(
-        `Dendrite refuses to emit '${signal.type}': only synapse-side types may be emitted this way. '${signal.type}' is an Axon-owned type.`
-      );
-    }
-    await this.publish(signal);
-  }
-  async publish(signal) {
-    await this.synapse.publish(this.subject(signal.type), signal);
-  }
-  async subscribe(type, handler, opts) {
-    return this.synapse.subscribe(this.subject(type), handler, opts);
-  }
-  // -- internal ------------------------------------------------------
-  subject(type) {
-    return `cosmonapse.${this.namespace}.${type}`;
-  }
-  async ensureInboundSub(type) {
-    if (this.inboundSubs.has(type)) return;
-    const sub = await this.subscribe(type, (s) => this.dispatchInbound(s));
-    this.inboundSubs.set(type, sub);
-  }
-  async onTask(task) {
-    const target = task.directed?.id ?? null;
-    if (!target) return;
-    const axon = this._axons.get(target);
-    if (!axon) return;
-    let reply2;
-    try {
-      reply2 = await axon.handleTask(task);
-    } catch (err) {
-      reply2 = errorSignal({
-        traceId: task.trace_id,
-        parentId: task.id,
-        directed: { id: target },
-        code: "AXON_EXCEPTION",
-        message: err instanceof Error ? err.message : String(err),
-        recoverable: false
-      });
-    }
-    await this.publish(reply2);
-  }
-  async emitRegister(axon) {
-    await this.publish(
-      registerSignal({
-        directed: { id: axon.neuronId, capabilities: [...axon.capabilities] },
-        capabilities: axon.capabilities,
-        ...axon.version !== void 0 ? { version: axon.version } : {}
-      })
-    );
-  }
-  async emitDeregister(axon, reason) {
-    await this.publish(
-      deregisterSignal({
-        directed: { id: axon.neuronId },
-        ...reason !== void 0 ? { reason } : {}
-      })
-    );
-  }
-  async heartbeatTick() {
-    if (!this.running) return;
-    const now = (/* @__PURE__ */ new Date()).toISOString();
-    for (const axon of this._axons.values()) {
-      try {
-        if (this.reregisterOnHeartbeat) await this.emitRegister(axon);
-        await this.synapse.publish(
-          this.subject(SignalType.HEARTBEAT),
-          heartbeatSignal({ directed: { id: axon.neuronId } })
-        );
-      } catch {
-      }
-      if (this.registryStore !== null) {
-        try {
-          await this.registryStore.touchHeartbeat(axon.neuronId, now);
-        } catch {
-        }
-      }
-      await this.hooks._fireRefresh({ reason: "heartbeat", neuronId: axon.neuronId, extra: {} });
-      await axon.hooks._fireRefresh({ reason: "heartbeat", neuronId: axon.neuronId, extra: {} });
-    }
-  }
-  async mirrorToStore(axon, status) {
-    if (this.registryStore === null) return;
-    try {
-      await this.registryStore.upsert(
-        neuronRecord({
-          neuron_id: axon.neuronId,
-          capabilities: [...axon.capabilities],
-          version: axon.version ?? null,
-          status,
-          last_heartbeat: (/* @__PURE__ */ new Date()).toISOString()
-        })
-      );
-    } catch {
-    }
-  }
-  async dispatchInbound(signal) {
-    if (!AXON_TYPES.has(signal.type)) return;
-    if (this.registryStore !== null) {
-      try {
-        await this.updateRegistry(signal);
-      } catch {
-      }
-    }
-    const handlers = this.handlers.get(signal.type) ?? [];
-    if (!handlers.length) return;
-    await Promise.allSettled(handlers.map((h) => h(signal)));
-  }
-  async updateRegistry(signal) {
-    if (this.registryStore === null) return;
-    if (signal.payload["engram"]) return;
-    const neuronId = signal.directed?.id ?? null;
-    if (!neuronId) return;
-    let reason = null;
-    if (signal.type === SignalType.REGISTER) {
-      await this.registryStore.upsert(
-        neuronRecord({
-          neuron_id: neuronId,
-          capabilities: signal.payload["capabilities"] ?? [],
-          version: signal.payload["version"] ?? null,
-          status: "registered",
-          last_heartbeat: signal.ts
-        })
-      );
-      reason = "register";
-    } else if (signal.type === SignalType.DEREGISTER) {
-      await this.registryStore.markDeregistered(neuronId);
-      reason = "deregister";
-    } else if (signal.type === SignalType.HEARTBEAT) {
-      const status = signal.payload["status"];
-      if (status) await this.registryStore.touchHeartbeat(neuronId, signal.ts, status);
-      else await this.registryStore.touchHeartbeat(neuronId, signal.ts);
-      reason = "heartbeat";
-    }
-    if (reason !== null) {
-      await this.hooks._fireRefresh({ reason, neuronId, extra: {} });
-    }
+    const sig = permissionDecisionSignal({
+      traceId: request.trace_id,
+      parentId: request.id,
+      granted,
+      directed: { id: this.dendriteId },
+      ...opts.reason !== void 0 ? { reason: opts.reason } : {},
+      ...opts.ttlMs !== void 0 ? { ttlMs: opts.ttlMs } : {},
+      ...opts.meta !== void 0 ? { meta: opts.meta } : {}
+    });
+    await this.publish(sig);
+    return sig;
   }
-};
-var Cortex = Dendrite;
-
-// src/engram.ts
-var EngramBinding = class {
-  name;
-  directedId;
-  directedType;
-  defaultDeadlineMs;
-  defaultRecallMode;
-  constructor(init) {
-    this.name = init.name;
-    this.directedId = init.directedId ?? null;
-    this.directedType = init.directedType ?? null;
-    this.defaultDeadlineMs = init.defaultDeadlineMs ?? null;
-    this.defaultRecallMode = init.defaultRecallMode ?? "first";
-    if (!this.directedId && !this.directedType) {
-      throw new Error(
-        `EngramBinding '${this.name}' requires directedId (engram_id) or directedType (engram_kind), or both`
+  /** Answer a CLARIFICATION with a discrete CLARIFICATION_ANSWER signal
+   *  (parent_id = the request's id). Consumers pick it up via
+   *  {@link onClarificationAnswer} or {@link awaitDecision}. Distinct from
+   *  {@link respondToClarification}, which re-dispatches a TASK. */
+  async answerClarification(request, answer, opts = {}) {
+    if (request.type !== SignalType.CLARIFICATION) {
+      throw new DendriteProtocolError(
+        `answerClarification expects a CLARIFICATION signal, got '${request.type}'`
       );
     }
+    const sig = clarificationAnswerSignal({
+      traceId: request.trace_id,
+      parentId: request.id,
+      answer,
+      directed: { id: this.dendriteId },
+      ...opts.meta !== void 0 ? { meta: opts.meta } : {}
+    });
+    await this.publish(sig);
+    return sig;
   }
-  /** Build the `Directed` addressing this Engram. */
-  toDirected() {
-    return { id: this.directedId, type: this.directedType, capabilities: [] };
-  }
-};
-var EngramError = class extends Error {
-  constructor(message) {
-    super(message);
-    this.name = new.target.name;
+  /** Emit a synapse-side Signal. Refuses Axon-owned types; TASK initiation
+   *  additionally requires orchestrator role. */
+  async emit(signal) {
+    if (signal.type === SignalType.TASK) {
+      this.requireOrchestrator(`emit(${signal.type})`);
+    }
+    if (!SYNAPSE_TYPES.has(signal.type)) {
+      throw new DendriteProtocolError(
+        `Dendrite refuses to emit '${signal.type}': only synapse-side types may be emitted this way. '${signal.type}' is an Axon-owned type.`
+      );
+    }
+    await this.publish(signal);
   }
-};
-var EngramTimeout = class extends EngramError {
-};
-var EngramCancelled = class extends EngramError {
-};
-var EngramNotBound = class extends EngramError {
-};
-var EngramOverloaded = class extends EngramError {
-};
-var Engram = class {
-  version = null;
-  /** Return false if this Engram cannot satisfy the query. Default: serve all. */
-  // eslint-disable-next-line @typescript-eslint/no-unused-vars
-  async canServe(_query) {
-    return true;
+  async publish(signal) {
+    await this.synapse.publish(this.subject(signal.type), signal);
   }
-};
-function receipt(engramId, op, fields = {}) {
-  const error = fields.error ?? null;
-  return {
-    engramId,
-    op,
-    id: fields.id ?? null,
-    version: fields.version ?? null,
-    tookMs: fields.tookMs ?? null,
-    error,
-    ok: error === null
-  };
-}
-function entryToDict(e) {
-  const out = {
-    id: e.id,
-    content: e.content,
-    tags: [...e.tags],
-    version: e.version,
-    created_at: e.createdAt,
-    updated_at: e.updatedAt
-  };
-  if (e.mergeKey !== null) out["merge_key"] = e.mergeKey;
-  if (Object.keys(e.extra).length > 0) out["meta"] = { ...e.extra };
-  return out;
-}
-function asStringArray(v) {
-  return Array.isArray(v) ? v.filter((x) => typeof x === "string") : [];
-}
-function asObject(v) {
-  return v !== null && typeof v === "object" && !Array.isArray(v) ? v : {};
-}
-var InMemoryEngram = class extends Engram {
-  engramId;
-  engramKind;
-  capabilities;
-  entries = /* @__PURE__ */ new Map();
-  byMergeKey = /* @__PURE__ */ new Map();
-  imprintSeen = /* @__PURE__ */ new Map();
-  constructor(init = {}) {
-    super();
-    this.engramId = init.engramId ?? "engram-memory";
-    this.engramKind = init.engramKind ?? "keyvalue";
-    this.capabilities = init.capabilities ?? ["substring", "tags", "merge_key"];
-    this.version = init.version ?? "0.0.1";
+  async subscribe(type, handler, opts) {
+    return this.synapse.subscribe(this.subject(type), handler, opts);
   }
-  async connect() {
-    return;
+  // -- internal ------------------------------------------------------
+  subject(type) {
+    return `cosmonapse.${this.namespace}.${type}`;
   }
-  async close() {
-    this.entries.clear();
-    this.byMergeKey.clear();
-    this.imprintSeen.clear();
+  /** Subject for capability-routed TASKs (queue-grouped consumers). */
+  routedSubject() {
+    return `cosmonapse.${this.namespace}.${SignalType.TASK}.routed`;
+  }
+  ensureInboundSub(type) {
+    if (this.inboundSubs.has(type)) return Promise.resolve();
+    let p = this.inflightSubs.get(type);
+    if (!p) {
+      p = (async () => {
+        const sub = await this.subscribe(type, (s) => this.dispatchInbound(s));
+        this.inboundSubs.set(type, sub);
+      })().finally(() => this.inflightSubs.delete(type));
+      this.inflightSubs.set(type, p);
+    }
+    return p;
   }
-  async recall(query, opts = {}) {
-    const q = query ?? {};
-    const text = typeof q["text"] === "string" ? q["text"].toLowerCase() : "";
-    const tagQ = typeof q["tag"] === "string" ? q["tag"] : null;
-    const mergeKey = typeof q["merge_key"] === "string" ? q["merge_key"] : null;
-    const topK = typeof q["top_k"] === "number" ? q["top_k"] : 50;
-    const filters = opts.filters ?? {};
-    const requireTags = asStringArray(filters["tags"]);
-    const since = typeof filters["since"] === "string" ? Date.parse(filters["since"]) : NaN;
-    const until = typeof filters["until"] === "string" ? Date.parse(filters["until"]) : NaN;
-    let candidates;
-    if (mergeKey !== null) {
-      const ids = this.byMergeKey.get(mergeKey) ?? [];
-      candidates = ids.map((i) => this.entries.get(i)).filter((e) => e !== void 0);
+  /**
+   * Route an inbound TASK to a local Axon. Addressed: by neuron_id (drop if
+   * not hosted here). Capability-routed: first local Axon whose caps superset
+   * the request. After publishing the reply, apply terminal-handler finalize:
+   * a TASK tagged `payload.finalize` promotes a successful AGENT_OUTPUT by
+   * also emitting FINAL (parented to the AGENT_OUTPUT, attributed to the
+   * producing Neuron). Only AGENT_OUTPUT is promoted  -  CLARIFICATION /
+   * PERMISSION pause the workflow and ERROR is already terminal.
+   */
+  async onTask(task) {
+    let target = task.directed?.id ?? null;
+    let axon;
+    if (target) {
+      axon = this._axons.get(target);
+      if (!axon) return;
     } else {
-      candidates = [...this.entries.values()];
+      const requested = task.payload["capabilities"] ?? [];
+      if (!requested.length) return;
+      for (const candidate of this._axons.values()) {
+        if (requested.every((c) => candidate.capabilities.includes(c))) {
+          axon = candidate;
+          break;
+        }
+      }
+      if (!axon) return;
+      target = axon.neuronId;
     }
-    const hits = [];
-    for (const ent of candidates) {
-      if (requireTags.length > 0 && !requireTags.every((t) => ent.tags.includes(t))) continue;
-      const updated = Date.parse(ent.updatedAt);
-      if (!Number.isNaN(since) && updated < since) continue;
-      if (!Number.isNaN(until) && updated > until) continue;
-      if (tagQ !== null && !ent.tags.includes(tagQ)) continue;
-      let score = 1;
-      if (text) {
-        const hay = String(ent.content).toLowerCase();
-        if (!hay.includes(text)) continue;
-        score = Math.min(1, text.length / Math.max(1, hay.length));
+    const ac = new AbortController();
+    this.registerTraceAbort(task.trace_id, ac);
+    let reply2;
+    try {
+      reply2 = await this.raceAbort(axon.handleTask(task), ac.signal);
+    } catch (err) {
+      reply2 = errorSignal({
+        traceId: task.trace_id,
+        parentId: task.id,
+        directed: { id: target },
+        code: "AXON_EXCEPTION",
+        message: err instanceof Error ? err.message : String(err),
+        recoverable: false
+      });
+    } finally {
+      this.unregisterTraceAbort(task.trace_id, ac);
+    }
+    if (reply2 === null) {
+      return;
+    }
+    await this.publish(reply2);
+    if (reply2.type === SignalType.AGENT_OUTPUT && task.payload["finalize"]) {
+      try {
+        await this.publish(
+          finalSignal({
+            traceId: reply2.trace_id,
+            parentId: reply2.id,
+            directed: { id: target },
+            result: reply2.payload["output"] ?? {}
+          })
+        );
+      } catch {
       }
-      if (opts.minConfidence !== void 0 && score < opts.minConfidence) continue;
-      hits.push({ id: ent.id, entry: entryToDict(ent), score });
     }
-    hits.sort((a, b) => b.score - a.score);
-    return hits.slice(0, topK);
   }
-  async imprint(op, entry, opts = {}) {
-    const t0 = Date.now();
-    const mergeKey = opts.mergeKey ?? null;
-    const tookMs = () => Date.now() - t0;
-    if (opts.imprintId !== void 0) {
-      const seen = this.imprintSeen.get(opts.imprintId);
-      if (seen !== void 0) {
-        const existing = this.entries.get(seen);
-        return receipt(this.engramId, op, {
-          id: seen,
-          version: existing ? existing.version : null,
-          tookMs: tookMs()
-        });
-      }
+  // -- workflow control: STOP / STOPPED -------------------------------
+  registerTraceAbort(traceId, ac) {
+    let set = this.traceAborts.get(traceId);
+    if (!set) {
+      set = /* @__PURE__ */ new Set();
+      this.traceAborts.set(traceId, set);
     }
-    let resultingId = null;
-    let version = null;
-    if (op === "add") {
-      const ent = this.makeEntry(entry, mergeKey);
-      if (this.entries.has(ent.id)) {
-        return receipt(this.engramId, op, { error: `entry id '${ent.id}' already exists`, tookMs: tookMs() });
-      }
-      this.store(ent);
-      resultingId = ent.id;
-      version = ent.version;
-    } else if (op === "append") {
-      let ent = this.makeEntry(entry, mergeKey);
-      while (this.entries.has(ent.id)) {
-        ent = this.makeEntry({ ...entry, id: newEngramId() }, mergeKey);
-      }
-      this.store(ent);
-      resultingId = ent.id;
-      version = ent.version;
-    } else if (op === "upsert") {
-      const existingIds = this.byMergeKey.get(mergeKey ?? "") ?? [];
-      const targetId = existingIds[existingIds.length - 1];
-      const old = targetId !== void 0 ? this.entries.get(targetId) : void 0;
-      if (old !== void 0) {
-        const next = this.makeEntry({ ...entry, id: old.id }, mergeKey);
-        next.createdAt = old.createdAt;
-        next.version = old.version + 1;
-        this.store(next, true);
-        resultingId = next.id;
-        version = next.version;
-      } else {
-        const ent = this.makeEntry(entry, mergeKey);
-        this.store(ent);
-        resultingId = ent.id;
-        version = ent.version;
-      }
-    } else if (op === "merge") {
-      const existingIds = this.byMergeKey.get(mergeKey ?? "") ?? [];
-      const targetId = existingIds[existingIds.length - 1];
-      const old = targetId !== void 0 ? this.entries.get(targetId) : void 0;
-      if (old === void 0) {
-        return receipt(this.engramId, op, { error: `no entry for merge_key='${mergeKey}'`, tookMs: tookMs() });
+    set.add(ac);
+  }
+  unregisterTraceAbort(traceId, ac) {
+    const set = this.traceAborts.get(traceId);
+    if (set) {
+      set.delete(ac);
+      if (set.size === 0) this.traceAborts.delete(traceId);
+    }
+  }
+  /** Resolve to the promise's value, or to null if the signal aborts first. */
+  raceAbort(p, signal) {
+    if (signal.aborted) return Promise.resolve(null);
+    return new Promise((resolve, reject) => {
+      const onAbort = () => resolve(null);
+      signal.addEventListener("abort", onAbort, { once: true });
+      p.then(
+        (v) => {
+          signal.removeEventListener("abort", onAbort);
+          resolve(v);
+        },
+        (e) => {
+          signal.removeEventListener("abort", onAbort);
+          reject(e);
+        }
+      );
+    });
+  }
+  async onStop(signal) {
+    const traceId = signal.trace_id;
+    if (!traceId) return;
+    const rollback = Boolean(signal.payload["rollback"]);
+    let cancelled = 0;
+    let compensated = 0;
+    let didWork = false;
+    const acs = this.traceAborts.get(traceId);
+    if (acs) {
+      for (const ac of acs) {
+        if (!ac.signal.aborted) {
+          ac.abort();
+          cancelled++;
+        }
       }
-      const now = (/* @__PURE__ */ new Date()).toISOString();
-      const next = {
-        id: old.id,
-        content: deepMerge(old.content, entry["content"]),
-        tags: [.../* @__PURE__ */ new Set([...old.tags, ...asStringArray(entry["tags"])])],
-        mergeKey: old.mergeKey,
-        version: old.version + 1,
-        createdAt: old.createdAt,
-        updatedAt: now,
-        extra: asObject(deepMerge(old.extra, entry["meta"]))
-      };
-      this.store(next, true);
-      resultingId = next.id;
-      version = next.version;
-    } else if (op === "delete") {
-      let targetId = null;
-      const entId = entry["id"];
-      if (typeof entId === "string") {
-        targetId = entId;
-      } else if (mergeKey !== null) {
-        const ids = this.byMergeKey.get(mergeKey) ?? [];
-        targetId = ids[ids.length - 1] ?? null;
+      this.traceAborts.delete(traceId);
+      didWork = true;
+    }
+    try {
+      await this.cancelOpPathways(traceId);
+      this.engramClient.cancelTrace(traceId);
+    } catch {
+    }
+    for (const engram of this._engrams.values()) {
+      try {
+        if (rollback) {
+          const n = await engram.compensate(traceId);
+          if (n > 0) {
+            compensated += n;
+            didWork = true;
+          }
+        } else {
+          await engram.commit(traceId);
+        }
+      } catch {
       }
-      if (targetId === null || !this.entries.has(targetId)) {
-        return receipt(this.engramId, op, { tookMs: tookMs() });
+    }
+    const pw = this.pathways.get(traceId);
+    if (pw && !pw.closed) {
+      didWork = true;
+      try {
+        await pw.close();
+      } catch {
       }
-      this.evict(targetId);
-      resultingId = targetId;
-      version = null;
-    } else {
-      return receipt(this.engramId, op, { error: `unknown op '${op}'`, tookMs: tookMs() });
     }
-    if (opts.imprintId !== void 0 && resultingId !== null) {
-      this.imprintSeen.set(opts.imprintId, resultingId);
+    if (didWork) {
+      try {
+        await this.publish(
+          stoppedSignal({
+            traceId,
+            parentId: signal.id,
+            node: this.namespace,
+            rolledBack: rollback,
+            cancelled,
+            compensated
+          })
+        );
+      } catch {
+      }
     }
-    return receipt(this.engramId, op, { id: resultingId, version, tookMs: tookMs() });
   }
-  /** Test/debug helper - NOT part of the Engram contract. */
-  snapshot() {
-    return [...this.entries.values()].map(entryToDict);
+  /** Broadcast a STOP for `traceId` (orchestrator-gated). Best-effort and
+   *  idempotent. */
+  async emitStop(args) {
+    this.requireOrchestrator("emitStop");
+    await this.ensureInboundSub(SignalType.STOP);
+    const sig = stopSignal({
+      traceId: args.traceId,
+      ...args.rollback !== void 0 ? { rollback: args.rollback } : {},
+      ...args.reason !== void 0 ? { reason: args.reason } : {}
+    });
+    await this.publish(sig);
+    return sig;
   }
-  makeEntry(entry, mergeKey) {
-    const id = typeof entry["id"] === "string" ? entry["id"] : newEngramId();
-    const now = (/* @__PURE__ */ new Date()).toISOString();
-    return {
-      id,
-      content: entry["content"],
-      tags: asStringArray(entry["tags"]),
-      mergeKey,
-      version: 1,
-      createdAt: now,
-      updatedAt: now,
-      extra: asObject(entry["meta"])
+  /** Stop a whole workflow. With `collectAcks` returns the STOPPED acks seen
+   *  within `timeoutMs` (best effort). */
+  async stopTrace(traceId, opts = {}) {
+    if (!opts.collectAcks) {
+      await this.emitStop({
+        traceId,
+        ...opts.rollback !== void 0 ? { rollback: opts.rollback } : {},
+        ...opts.reason !== void 0 ? { reason: opts.reason } : {}
+      });
+      return [];
+    }
+    const acks = [];
+    const collect = async (sig) => {
+      if (sig.trace_id === traceId) acks.push(sig);
     };
+    const list = this.handlers.get(SignalType.STOPPED) ?? [];
+    list.push(collect);
+    this.handlers.set(SignalType.STOPPED, list);
+    await this.ensureInboundSub(SignalType.STOPPED);
+    try {
+      await this.emitStop({
+        traceId,
+        ...opts.rollback !== void 0 ? { rollback: opts.rollback } : {},
+        ...opts.reason !== void 0 ? { reason: opts.reason } : {}
+      });
+      await new Promise((r) => setTimeout(r, opts.timeoutMs ?? 1e3));
+    } finally {
+      const idx = (this.handlers.get(SignalType.STOPPED) ?? []).indexOf(collect);
+      if (idx >= 0) (this.handlers.get(SignalType.STOPPED) ?? []).splice(idx, 1);
+    }
+    return acks;
   }
-  store(ent, replace = false) {
-    if (replace) {
-      const old = this.entries.get(ent.id);
-      if (old !== void 0 && old.mergeKey) {
-        const bucket = this.byMergeKey.get(old.mergeKey);
-        if (bucket) {
-          const idx = bucket.indexOf(ent.id);
-          if (idx >= 0) bucket.splice(idx, 1);
-          if (bucket.length === 0) this.byMergeKey.delete(old.mergeKey);
+  // -- retry ----------------------------------------------------------
+  async safeStop(traceId, retry) {
+    try {
+      await this.emitStop({
+        traceId,
+        rollback: Boolean(retry.rollbackOnRetry),
+        reason: retry.reason ?? "retry"
+      });
+    } catch {
+    }
+  }
+  /** Dispatch and wait, retrying per `retry` until a non-retryable outcome or
+   *  attempts are exhausted. Returns the resolved Signal; re-throws the last
+   *  error when every attempt failed with an exception. */
+  async runWithRetry(args) {
+    const { retry, timeoutMs, traceId: callerTrace, ...rest } = args;
+    const maxAttempts = retry.maxAttempts ?? 3;
+    const retryOn = retry.retryOn ?? defaultRetryOn;
+    const newTrace = retry.newTrace ?? true;
+    const perTimeout = retry.timeoutMs ?? timeoutMs ?? 3e4;
+    let outcome = null;
+    for (let attempt = 0; attempt < maxAttempts; attempt++) {
+      const tid = callerTrace && !newTrace ? callerTrace : newTraceId();
+      const meta = { ...rest.meta ?? {}, attempt };
+      try {
+        const pathway = await this.dispatch({ ...rest, traceId: tid, meta });
+        try {
+          outcome = await pathway.wait(perTimeout);
+        } finally {
+          await pathway.close();
         }
+      } catch (err) {
+        outcome = err instanceof Error ? err : new Error(String(err));
       }
+      if (!retryOn(outcome)) {
+        if (outcome instanceof Error) throw outcome;
+        return outcome;
+      }
+      if (newTrace) await this.safeStop(tid, retry);
+      if (attempt + 1 >= maxAttempts) {
+        if (outcome instanceof Error) throw outcome;
+        return outcome;
+      }
+      if (retry.onRetry) {
+        try {
+          retry.onRetry(attempt, outcome);
+        } catch {
+        }
+      }
+      const delay = retry.backoffMs ? retry.backoffMs(attempt) : 0;
+      if (delay > 0) await new Promise((r) => setTimeout(r, delay));
     }
-    this.entries.set(ent.id, ent);
-    if (ent.mergeKey) {
-      const bucket = this.byMergeKey.get(ent.mergeKey);
-      if (bucket) bucket.push(ent.id);
-      else this.byMergeKey.set(ent.mergeKey, [ent.id]);
-    }
+    throw new Error("runWithRetry: exhausted attempts unexpectedly");
   }
-  evict(entryId) {
-    const ent = this.entries.get(entryId);
-    this.entries.delete(entryId);
-    if (ent === void 0) return;
-    if (ent.mergeKey) {
-      const bucket = this.byMergeKey.get(ent.mergeKey);
-      if (bucket) {
-        const idx = bucket.indexOf(entryId);
-        if (idx >= 0) bucket.splice(idx, 1);
-        if (bucket.length === 0) this.byMergeKey.delete(ent.mergeKey);
+  async emitRegister(axon) {
+    await this.publish(
+      registerSignal({
+        directed: {
+          id: axon.neuronId,
+          type: axon.neuronKind ?? "neuron",
+          capabilities: [...axon.capabilities]
+        },
+        capabilities: axon.capabilities,
+        role: "neuron",
+        ...axon.version !== void 0 ? { version: axon.version } : {}
+      })
+    );
+  }
+  async emitDeregister(axon, reason) {
+    await this.publish(
+      deregisterSignal({
+        directed: { id: axon.neuronId },
+        ...reason !== void 0 ? { reason } : {}
+      })
+    );
+  }
+  async heartbeatTick() {
+    if (!this.running) return;
+    const now = (/* @__PURE__ */ new Date()).toISOString();
+    for (const axon of this._axons.values()) {
+      try {
+        if (this.reregisterOnHeartbeat) await this.emitRegister(axon);
+        await this.synapse.publish(
+          this.subject(SignalType.HEARTBEAT),
+          heartbeatSignal({ directed: { id: axon.neuronId } })
+        );
+      } catch {
+      }
+      if (this.registryStore !== null) {
+        try {
+          await this.registryStore.touchHeartbeat(axon.neuronId, now);
+        } catch {
+        }
       }
+      await this.hooks._fireRefresh({ reason: "heartbeat", neuronId: axon.neuronId, extra: {} });
+      await axon.hooks._fireRefresh({ reason: "heartbeat", neuronId: axon.neuronId, extra: {} });
     }
-  }
-};
-function deepMerge(base, incoming) {
-  if (incoming === void 0 || incoming === null) return base;
-  const bothObjects = base !== null && typeof base === "object" && !Array.isArray(base) && typeof incoming === "object" && !Array.isArray(incoming);
-  if (bothObjects) {
-    const out = { ...base };
-    for (const [k, v] of Object.entries(incoming)) {
-      out[k] = k in out ? deepMerge(out[k], v) : v;
+    if (this.registryStore !== null && this.staleAfterMs > 0) {
+      try {
+        await this.sweepStaleNeurons(Date.now());
+      } catch {
+      }
     }
-    return out;
   }
-  if (Array.isArray(base) && Array.isArray(incoming)) {
-    const seen = /* @__PURE__ */ new Set();
-    const out = [];
-    for (const item of [...base, ...incoming]) {
-      const key = JSON.stringify(item);
-      if (seen.has(key)) continue;
-      seen.add(key);
-      out.push(item);
+  /** Mark Neurons deregistered when their last heartbeat is older than
+   *  `staleAfterMs`. Own hosted Axons were touched immediately before the
+   *  sweep, so they never qualify. */
+  async sweepStaleNeurons(nowMs) {
+    const store = this.registryStore;
+    if (store === null) return;
+    const records = await store.list({ includeDeregistered: false });
+    for (const rec of records) {
+      const seen = rec.last_heartbeat ?? rec.registered_at;
+      if (!seen) continue;
+      if (nowMs - Date.parse(seen) > this.staleAfterMs) {
+        try {
+          await store.markDeregistered(rec.neuron_id);
+          await this.hooks._fireRefresh({
+            reason: "stale",
+            neuronId: rec.neuron_id,
+            extra: {}
+          });
+        } catch {
+        }
+      }
     }
-    return out;
-  }
-  return incoming;
-}
-
-// src/engram-client.ts
-function deferred() {
-  let resolve;
-  let reject;
-  const promise = new Promise((res, rej) => {
-    resolve = res;
-    reject = rej;
-  });
-  return { promise, resolve, reject };
-}
-var EngramClient = class {
-  constructor(publisher) {
-    this.publisher = publisher;
   }
-  publisher;
-  pendingRecalls = /* @__PURE__ */ new Map();
-  pendingImprints = /* @__PURE__ */ new Map();
-  byTrace = /* @__PURE__ */ new Map();
-  async recall(args) {
-    let engramId = args.engramId;
-    let engramKind = args.engramKind;
-    let deadlineMs = args.deadlineMs;
-    let recallMode = args.recallMode;
-    if (args.binding) {
-      engramId = engramId ?? args.binding.directedId ?? void 0;
-      engramKind = engramKind ?? args.binding.directedType ?? void 0;
-      if (deadlineMs === void 0) deadlineMs = args.binding.defaultDeadlineMs ?? void 0;
-      if (recallMode === void 0) recallMode = args.binding.defaultRecallMode;
+  async mirrorToStore(axon, status) {
+    if (this.registryStore === null) return;
+    try {
+      await this.registryStore.upsert(
+        neuronRecord({
+          neuron_id: axon.neuronId,
+          capabilities: [...axon.capabilities],
+          version: axon.version ?? null,
+          status,
+          last_heartbeat: (/* @__PURE__ */ new Date()).toISOString()
+        })
+      );
+    } catch {
     }
-    const mode = recallMode ?? "first";
-    const sig = recallSignal({
-      traceId: args.traceId,
-      parentId: args.parentId,
-      directed: directedTo(engramId ?? null, { type: engramKind ?? null }),
-      query: args.query,
-      ...args.filters !== void 0 ? { filters: args.filters } : {},
-      ...args.contextRef !== void 0 ? { contextRef: args.contextRef } : {},
-      ...deadlineMs !== void 0 ? { deadlineMs } : {},
-      ...args.minConfidence !== void 0 ? { minConfidence: args.minConfidence } : {},
-      recallMode: mode,
-      ...args.meta !== void 0 ? { meta: args.meta } : {}
-    });
-    const d = deferred();
-    const pending = { deferred: d, mode, timer: null, done: false, hitsSoFar: [], engrams: [] };
-    this.pendingRecalls.set(sig.id, pending);
-    this.track(args.traceId, sig.id);
-    if (deadlineMs !== void 0 && deadlineMs > 0) {
-      pending.timer = setTimeout(() => this.onRecallDeadline(sig.id), deadlineMs);
+  }
+  /** Respond to a DISCOVER by re-emitting REGISTER for matching Axons. */
+  async respondToDiscover(signal) {
+    if (this._axons.size === 0) return;
+    const target = signal.payload["neuron"];
+    const capsFilter = signal.payload["capabilities"];
+    for (const axon of this._axons.values()) {
+      if (target && axon.neuronId !== target) continue;
+      if (capsFilter?.length && !capsFilter.every((c) => axon.capabilities.includes(c))) {
+        continue;
+      }
+      try {
+        await this.emitRegister(axon);
+      } catch {
+      }
     }
-    try {
-      await this.publisher.publish(sig);
-    } catch (err) {
-      this.cleanupRecall(args.traceId, sig.id);
-      throw err;
+  }
+  async dispatchInbound(signal) {
+    if (signal.type === SignalType.DISCOVER) {
+      const hs = this.handlers.get(SignalType.DISCOVER) ?? [];
+      if (hs.length) await Promise.allSettled(hs.map((h) => h(signal)));
+      else await this.respondToDiscover(signal);
+      return;
     }
-    try {
-      return await d.promise;
-    } finally {
-      this.cleanupRecall(args.traceId, sig.id);
+    if (signal.type === SignalType.RECALL) {
+      await this.onRecall(signal);
+      const hs = this.handlers.get(SignalType.RECALL) ?? [];
+      if (hs.length) await Promise.allSettled(hs.map((h) => h(signal)));
+      return;
     }
-  }
-  async imprint(args) {
-    let engramId = args.engramId;
-    let engramKind = args.engramKind;
-    if (args.binding) {
-      engramId = engramId ?? args.binding.directedId ?? void 0;
-      engramKind = engramKind ?? args.binding.directedType ?? void 0;
+    if (signal.type === SignalType.IMPRINT) {
+      await this.onImprint(signal);
+      const hs = this.handlers.get(SignalType.IMPRINT) ?? [];
+      if (hs.length) await Promise.allSettled(hs.map((h) => h(signal)));
+      return;
     }
-    const sig = imprintSignal({
-      traceId: args.traceId,
-      parentId: args.parentId,
-      directed: directedTo(engramId ?? null, { type: engramKind ?? null }),
-      op: args.op,
-      entry: args.entry,
-      ...args.mergeKey !== void 0 ? { mergeKey: args.mergeKey } : {},
-      ...args.meta !== void 0 ? { meta: args.meta } : {}
-    });
-    if (!args.awaitAck) {
-      await this.publisher.publish(sig);
-      return null;
+    if (signal.type === SignalType.STOP) {
+      if (signal.trace_id) {
+        const pw = this.pathways.get(signal.trace_id);
+        if (pw) {
+          try {
+            await pw._deliver(signal);
+          } catch {
+          }
+        }
+      }
+      await this.onStop(signal);
+      const hs = this.handlers.get(SignalType.STOP) ?? [];
+      if (hs.length) await Promise.allSettled(hs.map((h) => h(signal)));
+      return;
     }
-    const d = deferred();
-    const pending = { deferred: d, timer: null, done: false };
-    this.pendingImprints.set(sig.id, pending);
-    this.track(args.traceId, sig.id);
-    if (args.deadlineMs !== void 0 && args.deadlineMs > 0) {
-      pending.timer = setTimeout(() => this.onImprintDeadline(sig.id), args.deadlineMs);
+    if (signal.type === SignalType.RECALLED || signal.type === SignalType.IMPRINTED) {
+      this.engramClient.deliver(signal);
     }
-    try {
-      await this.publisher.publish(sig);
-    } catch (err) {
-      this.cleanupImprint(args.traceId, sig.id);
-      throw err;
+    if (signal.type === SignalType.REGISTER && this.isEngramRegister(signal)) {
+      this.recordEngramRegistration(signal);
+      return;
     }
-    try {
-      return await d.promise;
-    } finally {
-      this.cleanupImprint(args.traceId, sig.id);
+    if (signal.parent_id) {
+      const opPw = this.opPathways.get(signal.parent_id);
+      if (opPw) {
+        try {
+          await opPw._deliver(signal);
+        } catch {
+        }
+      }
     }
-  }
-  /** Match RECALLED / IMPRINTED by parent_id and resolve pendings. */
-  deliver(sig) {
-    const pid = sig.parent_id;
-    if (pid === null) return;
-    if (sig.type === SignalType.RECALLED) {
-      const pending = this.pendingRecalls.get(pid);
-      if (pending === void 0) return;
-      const hits = hitsFromPayload(sig.payload["hits"]);
-      const engramId = typeof sig.payload["engram_id"] === "string" ? sig.payload["engram_id"] : "";
-      const tookMs = typeof sig.payload["took_ms"] === "number" ? sig.payload["took_ms"] : null;
-      const truncated = sig.payload["truncated"] === true;
-      if (pending.mode === "first") {
-        if (!pending.done) {
-          pending.done = true;
-          pending.deferred.resolve({
-            hits,
-            engramIds: engramId ? [engramId] : [],
-            truncated,
-            tookMs
-          });
+    if ((signal.type === SignalType.CLARIFICATION_ANSWER || signal.type === SignalType.PERMISSION_DECISION) && signal.parent_id) {
+      this.recentDecisions.set(signal.parent_id, signal);
+      while (this.recentDecisions.size > 256) {
+        const oldest = this.recentDecisions.keys().next().value;
+        this.recentDecisions.delete(oldest);
+      }
+    }
+    if ((signal.type === SignalType.FINAL || signal.type === SignalType.ERROR) && signal.trace_id) {
+      await this.cancelOpPathways(signal.trace_id);
+      this.engramClient.cancelTrace(signal.trace_id);
+      for (const engram of this._engrams.values()) {
+        try {
+          await engram.commit(signal.trace_id);
+        } catch {
         }
-      } else {
-        pending.hitsSoFar.push(...hits);
-        if (engramId) pending.engrams.push(engramId);
       }
-    } else if (sig.type === SignalType.IMPRINTED) {
-      const pending = this.pendingImprints.get(pid);
-      if (pending === void 0 || pending.done) return;
-      pending.done = true;
-      pending.deferred.resolve({
-        engramId: typeof sig.payload["engram_id"] === "string" ? sig.payload["engram_id"] : "",
-        op: typeof sig.payload["op"] === "string" ? sig.payload["op"] : "",
-        id: typeof sig.payload["id"] === "string" ? sig.payload["id"] : null,
-        version: typeof sig.payload["version"] === "number" ? sig.payload["version"] : null,
-        tookMs: typeof sig.payload["took_ms"] === "number" ? sig.payload["took_ms"] : null,
-        error: typeof sig.payload["error"] === "string" ? sig.payload["error"] : null,
-        ok: !(typeof sig.payload["error"] === "string")
-      });
+      this.traceAborts.delete(signal.trace_id);
+    }
+    if (signal.type === SignalType.TASK_AWARDED) {
+      const target = signal.directed?.id ?? null;
+      if (target && this._axons.has(target)) {
+        const synthetic = taskSignal({
+          traceId: signal.trace_id,
+          parentId: signal.id,
+          directed: { id: target },
+          input: signal.payload["input"] ?? {},
+          finalize: Boolean(signal.payload["finalize"]),
+          ...signal.payload["context_ref"] !== void 0 ? { contextRef: signal.payload["context_ref"] } : {},
+          meta: signal.meta
+        });
+        await this.onTask(synthetic);
+      }
+    }
+    if (signal.trace_id && PATHWAY_TYPES.has(signal.type)) {
+      const pathway = this.pathways.get(signal.trace_id);
+      if (pathway) {
+        try {
+          await pathway._deliver(signal);
+        } catch {
+        }
+      }
+    }
+    if (AXON_TYPES.has(signal.type) && this.registryStore !== null) {
+      try {
+        await this.updateRegistry(signal);
+      } catch {
+      }
+    }
+    if (signal.type === SignalType.TASK_OFFER && this.autoBid && this._axons.size > 0 && (this.handlers.get(SignalType.TASK_OFFER) ?? []).length === 0) {
+      await this.maybeAutoBid(signal);
+    }
+    const handlers = this.handlers.get(signal.type) ?? [];
+    if (handlers.length) await Promise.allSettled(handlers.map((h) => h(signal)));
+  }
+  // -- Engram: hosted-side handlers -----------------------------------
+  /** Pick the hosted Engrams that should respond to a RECALL/IMPRINT.
+   *  directed.id (engramId) wins over directed.type (engramKind). */
+  resolveEngramTargets(signal) {
+    const eid = signal.directed?.id ?? null;
+    if (eid) {
+      const ent = this._engrams.get(eid);
+      return ent ? [ent] : [];
+    }
+    const ekind = signal.directed?.type ?? null;
+    if (ekind) {
+      return (this.engramKindIndex.get(ekind) ?? []).map((id) => this._engrams.get(id)).filter((e) => e !== void 0);
+    }
+    return [];
+  }
+  async onRecall(signal) {
+    const targets = this.resolveEngramTargets(signal);
+    if (!targets.length) return;
+    const query = signal.payload["query"] ?? {};
+    const filters = signal.payload["filters"];
+    const contextRef = signal.payload["context_ref"];
+    const deadlineMs = signal.payload["deadline_ms"];
+    const minConfidence = signal.payload["min_confidence"];
+    for (const engram of targets) {
+      let hits;
+      try {
+        if (!await engram.canServe(query)) continue;
+        hits = await engram.recall(query, {
+          ...filters !== void 0 ? { filters } : {},
+          ...contextRef !== void 0 ? { contextRef } : {},
+          ...deadlineMs !== void 0 ? { deadlineMs } : {},
+          ...minConfidence !== void 0 ? { minConfidence } : {}
+        });
+      } catch {
+        continue;
+      }
+      try {
+        await this.publish(
+          recalledSignal({
+            traceId: signal.trace_id,
+            parentId: signal.id,
+            engramId: engram.engramId,
+            hits: hits.map((h) => ({ id: h.id, entry: h.entry, score: h.score })),
+            // Attribute the reply to the Engram that answered, not the host
+            // Dendrite, so observers classify it by the Engram's REGISTER.
+            directed: { id: engram.engramId, type: engram.engramKind }
+          })
+        );
+      } catch {
+      }
     }
   }
-  /** Cancel every in-flight recall/imprint on a trace (FINAL/ERROR or shutdown). */
-  cancelTrace(traceId) {
-    const ids = this.byTrace.get(traceId);
-    this.byTrace.delete(traceId);
-    if (ids === void 0) return;
-    for (const id of ids) {
-      const pr = this.pendingRecalls.get(id);
-      if (pr !== void 0 && !pr.done) {
-        pr.done = true;
-        if (pr.timer !== null) clearTimeout(pr.timer);
-        pr.deferred.reject(new EngramCancelled(`trace ${traceId} terminated while recall ${id} in flight`));
-        this.pendingRecalls.delete(id);
+  async onImprint(signal) {
+    const targets = this.resolveEngramTargets(signal);
+    if (!targets.length) return;
+    const op = signal.payload["op"] ?? "add";
+    const entry = signal.payload["entry"] ?? {};
+    const mergeKey = signal.payload["merge_key"];
+    for (const engram of targets) {
+      let reply2;
+      try {
+        const receipt2 = await engram.imprint(op, entry, {
+          imprintId: signal.id,
+          traceId: signal.trace_id,
+          ...mergeKey !== void 0 ? { mergeKey } : {}
+        });
+        reply2 = imprintedSignal({
+          traceId: signal.trace_id,
+          parentId: signal.id,
+          engramId: receipt2.engramId || engram.engramId,
+          op: receipt2.op,
+          ...receipt2.id !== null ? { id: receipt2.id } : {},
+          ...receipt2.version !== null ? { version: receipt2.version } : {},
+          ...receipt2.tookMs !== null ? { tookMs: receipt2.tookMs } : {},
+          ...receipt2.error !== null ? { error: receipt2.error } : {},
+          directed: { id: engram.engramId, type: engram.engramKind }
+        });
+      } catch (err) {
+        reply2 = imprintedSignal({
+          traceId: signal.trace_id,
+          parentId: signal.id,
+          engramId: engram.engramId,
+          op,
+          error: `engram_exception: ${err instanceof Error ? err.message : String(err)}`,
+          directed: { id: engram.engramId, type: engram.engramKind }
+        });
       }
-      const pi = this.pendingImprints.get(id);
-      if (pi !== void 0 && !pi.done) {
-        pi.done = true;
-        if (pi.timer !== null) clearTimeout(pi.timer);
-        pi.deferred.reject(new EngramCancelled(`trace ${traceId} terminated while imprint ${id} in flight`));
-        this.pendingImprints.delete(id);
+      try {
+        await this.publish(reply2);
+      } catch {
       }
     }
   }
-  cancelAll() {
-    for (const traceId of [...this.byTrace.keys()]) this.cancelTrace(traceId);
+  // -- Engram: registration (announce + learn) -------------------------
+  async emitEngramRegister(engram) {
+    await this.publish(
+      registerSignal({
+        directed: {
+          id: engram.engramId,
+          type: engram.engramKind,
+          capabilities: [...engram.capabilities]
+        },
+        capabilities: engram.capabilities,
+        role: "engram",
+        ...engram.version !== null ? { version: engram.version } : {}
+      })
+    );
   }
-  onRecallDeadline(id) {
-    const pending = this.pendingRecalls.get(id);
-    if (pending === void 0 || pending.done) return;
-    pending.done = true;
-    if (pending.mode === "first") {
-      pending.deferred.reject(new EngramTimeout(`RECALL ${id} elapsed deadline without any responder`));
-    } else {
-      pending.deferred.resolve({
-        hits: [...pending.hitsSoFar].sort((a, b) => b.score - a.score),
-        engramIds: [...pending.engrams],
-        truncated: false,
-        tookMs: null
-      });
+  isEngramRegister(signal) {
+    if (signal.payload["role"] === "engram" || signal.payload["engram"]) return true;
+    const dtype = signal.directed?.type ?? null;
+    if (dtype && (this.engramKindIndex.has(dtype) || this.engramRegKindIndex.has(dtype))) {
+      return true;
+    }
+    return false;
+  }
+  recordEngramRegistration(signal) {
+    const d = signal.directed;
+    if (!d || !d.id && !d.type) return;
+    let caps = [...d.capabilities];
+    if (!caps.length) {
+      caps = [...signal.payload["capabilities"] ?? []];
+    }
+    const key = d.id ?? d.type;
+    this._engramRegistrations.set(key, { id: d.id, type: d.type, capabilities: caps });
+    if (d.type) {
+      const bucket = this.engramRegKindIndex.get(d.type) ?? /* @__PURE__ */ new Set();
+      bucket.add(key);
+      this.engramRegKindIndex.set(d.type, bucket);
     }
   }
-  onImprintDeadline(id) {
-    const pending = this.pendingImprints.get(id);
-    if (pending === void 0 || pending.done) return;
-    pending.done = true;
-    pending.deferred.reject(new EngramTimeout(`IMPRINT ${id} elapsed deadline without IMPRINTED`));
-  }
-  track(traceId, id) {
-    const bucket = this.byTrace.get(traceId);
-    if (bucket) bucket.add(id);
-    else this.byTrace.set(traceId, /* @__PURE__ */ new Set([id]));
+  // -- Engram: caller-side helpers -------------------------------------
+  /** Resolve (traceId, parentId) for a caller-side engram op: explicit ids
+   *  win, then the ambient task context (bound by Axon.handleTask), then a
+   *  freshly minted trace (the pre-task-hydration shape). */
+  static resolveTrace(traceId, parentId) {
+    let tid = traceId;
+    let pid = parentId;
+    if (tid === void 0) {
+      const amb = ambientTrace();
+      if (amb !== null) {
+        tid = amb[0];
+        if (pid === void 0) pid = amb[1];
+      }
+    }
+    return [tid ?? newTraceId(), pid ?? newEventId()];
   }
-  cleanupRecall(traceId, id) {
-    const p = this.pendingRecalls.get(id);
-    if (p?.timer != null) clearTimeout(p.timer);
-    this.pendingRecalls.delete(id);
-    this.discardTrace(traceId, id);
+  /** Emit RECALL and await RECALLED. Trace attribution: explicit ids win,
+   *  then the ambient task context, then a fresh trace. */
+  async recall(args) {
+    const [tid, pid] = _Dendrite.resolveTrace(args.traceId, args.parentId);
+    return this.engramClient.recall({
+      query: args.query,
+      traceId: tid,
+      parentId: pid,
+      ...args.engramId !== void 0 ? { engramId: args.engramId } : {},
+      ...args.engramKind !== void 0 ? { engramKind: args.engramKind } : {},
+      ...args.filters !== void 0 ? { filters: args.filters } : {},
+      ...args.contextRef !== void 0 ? { contextRef: args.contextRef } : {},
+      ...args.deadlineMs !== void 0 ? { deadlineMs: args.deadlineMs } : {},
+      ...args.recallMode !== void 0 ? { recallMode: args.recallMode } : {},
+      ...args.minConfidence !== void 0 ? { minConfidence: args.minConfidence } : {},
+      ...args.meta !== void 0 ? { meta: args.meta } : {}
+    });
   }
-  cleanupImprint(traceId, id) {
-    const p = this.pendingImprints.get(id);
-    if (p?.timer != null) clearTimeout(p.timer);
-    this.pendingImprints.delete(id);
-    this.discardTrace(traceId, id);
+  /** Emit IMPRINT. Resolves null unless `awaitAck: true`. Trace attribution
+   *  as {@link recall}. */
+  async imprint(args) {
+    const [tid, pid] = _Dendrite.resolveTrace(args.traceId, args.parentId);
+    return this.engramClient.imprint({
+      op: args.op,
+      entry: args.entry,
+      traceId: tid,
+      parentId: pid,
+      ...args.engramId !== void 0 ? { engramId: args.engramId } : {},
+      ...args.engramKind !== void 0 ? { engramKind: args.engramKind } : {},
+      ...args.mergeKey !== void 0 ? { mergeKey: args.mergeKey } : {},
+      ...args.awaitAck !== void 0 ? { awaitAck: args.awaitAck } : {},
+      ...args.deadlineMs !== void 0 ? { deadlineMs: args.deadlineMs } : {},
+      ...args.meta !== void 0 ? { meta: args.meta } : {}
+    });
   }
-  discardTrace(traceId, id) {
-    const bucket = this.byTrace.get(traceId);
-    if (bucket === void 0) return;
-    bucket.delete(id);
-    if (bucket.size === 0) this.byTrace.delete(traceId);
+  async updateRegistry(signal) {
+    if (this.registryStore === null) return;
+    if (signal.payload["role"] === "engram" || signal.payload["engram"]) return;
+    const neuronId = signal.directed?.id ?? null;
+    if (!neuronId) return;
+    let reason = null;
+    if (signal.type === SignalType.REGISTER) {
+      await this.registryStore.upsert(
+        neuronRecord({
+          neuron_id: neuronId,
+          capabilities: signal.payload["capabilities"] ?? [],
+          version: signal.payload["version"] ?? null,
+          status: "registered",
+          last_heartbeat: signal.ts
+        })
+      );
+      reason = "register";
+    } else if (signal.type === SignalType.DEREGISTER) {
+      await this.registryStore.markDeregistered(neuronId);
+      reason = "deregister";
+    } else if (signal.type === SignalType.HEARTBEAT) {
+      const status = signal.payload["status"];
+      if (status) await this.registryStore.touchHeartbeat(neuronId, signal.ts, status);
+      else await this.registryStore.touchHeartbeat(neuronId, signal.ts);
+      reason = "heartbeat";
+    }
+    if (reason !== null) {
+      await this.hooks._fireRefresh({ reason, neuronId, extra: {} });
+    }
   }
 };
-function hitsFromPayload(raw) {
-  if (!Array.isArray(raw)) return [];
-  const out = [];
-  for (const h of raw) {
-    if (h === null || typeof h !== "object") continue;
-    const obj = h;
-    const entryVal = obj["entry"];
-    out.push({
-      id: typeof obj["id"] === "string" ? obj["id"] : "",
-      entry: entryVal !== null && typeof entryVal === "object" && !Array.isArray(entryVal) ? entryVal : { value: entryVal },
-      score: typeof obj["score"] === "number" ? obj["score"] : 1
-    });
-  }
-  return out;
-}
+var Cortex = Dendrite;
 
 // src/engram-sqlite.ts
 var SCHEMA3 = `
@@ -4047,10 +6073,11 @@ var PostgresEngram = class extends Engram {
 };
 
 // src/index.ts
-var VERSION = true ? "0.1.2" : "0.0.0-dev";
+var VERSION = true ? "0.1.4" : "0.0.0-dev";
 export {
   AXON_TYPES,
   Axon,
+  COSMO_INTENT_SYSTEM_PROMPT,
   Cortex,
   DendriteProtocolError as CortexProtocolError,
   Dendrite,
@@ -4071,14 +6098,19 @@ export {
   MemoryRegistryStore,
   MemorySynapse,
   NatsSynapse,
+  PATHWAY_TYPES,
+  Pathway,
+  PathwayClosedError,
   PostgresEngram,
   PostgresRegistryStore,
   SYNAPSE_TYPES,
   SignalType,
   SqliteEngram,
   SqliteRegistryStore,
+  TERMINAL_TYPES,
   VERSION,
   agentOutputSignal,
+  ambientTrace,
   anthropicNeuron,
   bidSignal,
   clarificationAnswerSignal,
@@ -4091,6 +6123,7 @@ export {
   critiqueSignal,
   decode,
   deepMerge,
+  defaultRetryOn,
   deregisterSignal,
   directedTo,
   discoverSignal,
@@ -4099,6 +6132,7 @@ export {
   errorSignal,
   escalationSignal,
   finalSignal,
+  followupPrompt,
   heartbeatSignal,
   huggingFaceNeuron,
   imprintSignal,
@@ -4126,8 +6160,13 @@ export {
   recalledSignal,
   registerSignal,
   reply,
+  runWithTraceContext,
   standardMcpServers,
+  stopSignal,
+  stoppedSignal,
   synapseFromUrl,
+  taskAwardedSignal,
+  taskDeclinedSignal,
   taskOfferSignal,
   taskSignal,
   thoughtDeltaSignal,