@staix/agent-hub 0.14.0 → 0.16.0

package/src/hub/token-window.ts

@@ -0,0 +1,46 @@
+/**
+ * A rolling window of counted tokens, by the time each was used (not the time it was read), so a row read late still ages out
+ * on schedule. The hub's own count against a ceiling a person configured, never the provider's quota (#285).
+ */
+export class TokenWindow {
+  private rows: { at: number; n: number }[] = [];
+  constructor(private readonly spanMs: number) {}
+
+  add(at: number, n: number): void {
+    if (!Number.isFinite(at) || !Number.isSafeInteger(n) || n <= 0) return;
+    // The common case is a row at or after the newest one: no search. An older row (a late read) is placed by a scan from the end, which stops at once for a near-current one.
+    let index = this.rows.length;
+    while (index > 0 && this.rows[index - 1]!.at > at) index--;
+    if (index === this.rows.length) this.rows.push({ at, n }); else this.rows.splice(index, 0, { at, n });
+  }
+
+  /**
+   * Rebuild from a history in one pass, for a start-up replay of a long event log: rows already out of the window at `now` are skipped before
+   * anything is inserted, so the cost follows the window and not the log. `add`-ing every historical row instead keeps the expired ones until a read prunes them.
+   */
+  seed(rows: Iterable<{ at: number; n: number }>, now: number): void {
+    const live: { at: number; n: number }[] = [];
+    for (const row of rows) if (Number.isFinite(row.at) && Number.isSafeInteger(row.n) && row.n > 0 && now - row.at <= this.spanMs) live.push({ at: row.at, n: row.n });
+    live.sort((a, b) => a.at - b.at);
+    this.rows = this.rows.length ? [...this.rows, ...live].sort((a, b) => a.at - b.at) : live;
+  }
+
+  private prune(now: number): void {
+    let drop = 0;
+    while (drop < this.rows.length && now - this.rows[drop]!.at > this.spanMs) drop++;
+    if (drop) this.rows.splice(0, drop);
+  }
+
+  sum(now: number): number {
+    this.prune(now);
+    return this.rows.reduce((total, row) => total + row.n, 0);
+  }
+
+  /** When the oldest counted token was used: the window frees its first share at this time plus its span. */
+  oldest(now: number): number | undefined {
+    this.prune(now);
+    return this.rows[0]?.at;
+  }
+
+  reset(): void { this.rows = []; }
+}

package/src/hub/usage-rollup.ts

@@ -101,7 +101,8 @@ export class UsageRollup {
    * Fold the next slice of the log. Whole lines only: a trailing partial line (a crash, or a write in flight) waits for the next pass.
    * A log that is shorter than the stored offset was replaced or reset, so the roll-up starts over from byte 0.
    */
-  poll(): { bytes: number; done: boolean } {
+  poll(maxMs = 20): { bytes: number; done: boolean } {
+    const deadline = performance.now() + Math.max(0, Math.min(20, maxMs));
     if (this.closed) return { bytes: 0, done: true };
     if (!existsSync(this.eventsFile)) return { bytes: 0, done: true };
     const fd = openSync(this.eventsFile, "r");
@@ -127,18 +128,27 @@ export class UsageRollup {
         want = Math.min(size - offset, want * 2);
       }
       if (end < 0) return { bytes: 0, done: true };                    // the last line is still being written: it waits for the next pass
-      const text = buffer.subarray(0, end + 1).toString("utf8");
+      let consumed = 0;
       // The offset was read before the slice was; another roll-up on this hub.db (a restart that overlaps the old process) may have folded the same
       // bytes since. The transaction takes the write lock first and checks the stored offset again: a pass whose start is stale is abandoned whole,
       // so a byte range is folded exactly once however many writers there are (found by a forced interleave: the counts doubled).
       const applied = this.db.transaction(() => {
         if (this.state().offset !== offset) return false;
-        for (const line of text.split("\n")) this.fold(line);
-        this.db.query("UPDATE rollup_state SET byte_offset = ? WHERE id = 1").run(offset + end + 1);
+        // Commit only complete processed records with their offset. Yield between records;
+        // ponytail: one whole record and the existing corrupt-line skip are indivisible;
+        // a streaming parser would be needed to preempt within either operation.
+        for (let start = 0; start <= end;) {
+          const newline = buffer.indexOf(0x0a, start);
+          if (newline < 0 || newline > end) break;
+          this.fold(buffer.subarray(start, newline).toString("utf8"));
+          consumed = newline + 1; start = consumed;
+          if (performance.now() >= deadline) break;
+        }
+        this.db.query("UPDATE rollup_state SET byte_offset = ? WHERE id = 1").run(offset + consumed);
         return true;
       }).immediate();
       if (!applied) return { bytes: 0, done: false };                   // stale: the next pass starts from the stored offset
-      return { bytes: end + 1, done: offset + end + 1 >= size };
+      return { bytes: consumed, done: offset + consumed >= size };
     } finally { closeSync(fd); }
   }
 
@@ -160,7 +170,7 @@ export class UsageRollup {
    */
   catchUp(maxMs?: number): boolean {
     const until = maxMs === undefined ? Infinity : Date.now() + maxMs;
-    for (let i = 0; i < 100_000; i++) { if (this.poll().done) return true; if (Date.now() >= until) return false; }
+    for (let i = 0; i < 100_000; i++) { if (this.poll(Math.min(20, until - Date.now())).done) return true; if (Date.now() >= until) return false; }
     return true;
   }
 

package/src/hub/window-kind.ts

@@ -0,0 +1,13 @@
+/** What a number is (#285 AC6): the provider's own ratio, tokens the hub counted against a ceiling a person set, or a value a person fed. */
+export type WindowKind = "native" | "count" | "manual";
+export interface KindedWindow { id: string; source?: string; kind?: WindowKind }
+/**
+ * The one place a window is classified. A reader that names its kind wins; an untagged window is the hub count when it is the `tokens` window,
+ * a person's when its source is `ahub budget set`, and the provider's otherwise.
+ */
+export function windowKind(w: KindedWindow): WindowKind {
+  if (w.kind) return w.kind;
+  if (w.id === "tokens") return "count";
+  if (w.source === "ahub budget set") return "manual";
+  return "native";
+}

package/src/hub/workflow.ts

@@ -46,4 +46,20 @@ export function criteriaView(config: SdlcConfig, task: Task, isPrivate: (t: Task
   for (const criterion of checklist.criteria) if (criterion.required && criterion.result !== "verified") blockers.push(`criterion ${criterion.id}: ${criterion.result}`);
   return { id: checklist.id, ready: blockers.length === 0, blockers, criteria: checklist.criteria.map(c => ({ ...c, refs: [...c.refs] })), ...("tasks" in checklist && (checklist as LegacyPhaseReceipt).tasks.length ? { note: "stored checklist task list ignored: task import was retired (#481)" } : {}) };
 }
+/**
+ * #507b: which of a task's recorded acceptance criteria (the #481 S8 checklist, the only criteria model) a reviewer's unmet items name.
+ * An item names a criterion when it STARTS with that criterion's id, exactly (case and all), followed by the end of the item or a delimiter:
+ * `AC3: the overwrite case has no test`, or just `AC3`. An id the checklist does not hold is plain text, never a criterion, and an id in the
+ * middle of a sentence is not a claim. Pure: items in, ids out (in the order first named, each once).
+ */
+export function unmetCriteriaIds(items: readonly string[], checklist: Pick<CriteriaReceipt, "criteria"> | undefined): string[] {
+  if (!checklist) return [];
+  const known = new Set(checklist.criteria.map(c => c.id));
+  const named: string[] = [];
+  for (const item of items) {
+    const id = /^\s*([A-Za-z][A-Za-z0-9-]{0,47})(?=$|[\s:.,;)\]])/.exec(item)?.[1];
+    if (id !== undefined && known.has(id) && !named.includes(id)) named.push(id);
+  }
+  return named;
+}
 export function workflowHash(value: unknown): string { return createHash("sha256").update(JSON.stringify(value)).digest("hex"); }

package/src/local/tools.ts

@@ -29,7 +29,7 @@ export interface ToolContext {
   /** Turn cancellation signal, including the execution-budget wall cap. */
   signal?: AbortSignal;
   /** Only true permits an effect; expiry and abort remain distinct from a person's denial. */
-  permit: (title: string, tool?: string, signal?: AbortSignal, canonicalTarget?: string, observe?: ApprovalObserver, originalPath?: string) => Promise<ToolApproval>;
+  permit: (title: string, tool?: string, signal?: AbortSignal, canonicalTarget?: string, observe?: ApprovalObserver, originalPath?: string, input?: unknown) => Promise<ToolApproval>;
   /** Trusted process status, independent of what its stdout says. */
   onProcessExit?: (code: number | null) => void;
   /** Publish a message to other peers mid-turn. Returns a one-line receipt. */
@@ -147,7 +147,7 @@ export async function runTool(name: string, rawArgs: string, ctx: ToolContext):
         let file = guardPath(ctx, String(a.path), "write");
         const approvedTarget = file;
         const content = String(a.content ?? "");
-        const refused = approvalError(await ctx.permit(`write ${a.path} (${content.length} chars):\n${preview(content)}`, "write", ctx.signal, file, undefined, String(a.path)), "error: the user did not approve this write");
+        const refused = approvalError(await ctx.permit(`write ${a.path} (${content.length} chars):\n${preview(content)}`, "write", ctx.signal, file, undefined, String(a.path), a), "error: the user did not approve this write");
         if (refused) return refused;
         if (ctx.signal?.aborted) return "error: turn cancelled before write";
         file = guardPath(ctx, String(a.path), "write");
@@ -162,7 +162,7 @@ export async function runTool(name: string, rawArgs: string, ctx: ToolContext):
         let text = readFileSync(file, "utf8");
         let count = text.split(String(a.old)).length - 1;
         if (!a.old || count !== 1) return `error: \`old\` must match exactly once, it matched ${count} times`;
-        const refused = approvalError(await ctx.permit(`edit ${a.path}:\n- ${preview(String(a.old), 600)}\n+ ${preview(String(a.new ?? ""), 600)}`, "edit", ctx.signal, file, undefined, String(a.path)), "error: the user did not approve this edit");
+        const refused = approvalError(await ctx.permit(`edit ${a.path}:\n- ${preview(String(a.old), 600)}\n+ ${preview(String(a.new ?? ""), 600)}`, "edit", ctx.signal, file, undefined, String(a.path), a), "error: the user did not approve this edit");
         if (refused) return refused;
         if (ctx.signal?.aborted) return "error: turn cancelled before edit";
         // Approval can outlive another peer's edit or a path change. Apply only the approved fragment to current bytes.
@@ -179,7 +179,7 @@ export async function runTool(name: string, rawArgs: string, ctx: ToolContext):
         if (!command.trim()) return "error: empty command";
         // The approver sees the whole command, not a prefix: what is hidden cannot be approved.
         if (command.length > 4000) return "error: command longer than 4000 characters; put it in a script file with write, then run that";
-        const refused = approvalError(await ctx.permit(`bash: ${command}`, "bash", ctx.signal), "error: the user did not approve this command");
+        const refused = approvalError(await ctx.permit(`bash: ${command}`, "bash", ctx.signal, undefined, undefined, undefined, a), "error: the user did not approve this command");
         if (refused) return refused;
         const res = await sandboxedExec(["/bin/bash", "-c", command], { cwd: ctx.cwd, profile: ctx.sandboxProfile, readOnlyData: !!ctx.readOnly?.length, timeoutMs: (Number(a.timeout_s) || 120) * 1000, ...(ctx.sandboxEnv ? { env: ctx.sandboxEnv } : {}), ...(ctx.signal ? { signal: ctx.signal } : {}) });
         try { ctx.onProcessExit?.(res.code); } catch { /* optional status observer never changes a tool result */ }
@@ -192,7 +192,7 @@ export async function runTool(name: string, rawArgs: string, ctx: ToolContext):
         const problem = gitArgsProblem(args, ctx.deny);
         if (problem) return `error: git ${sub}: ${problem}`;
         if (GIT_WRITE.has(sub)) {
-          const refused = approvalError(await ctx.permit(`git ${args.join(" ")}`, "git", ctx.signal), "error: the user did not approve this git command");
+          const refused = approvalError(await ctx.permit(`git ${args.join(" ")}`, "git", ctx.signal, undefined, undefined, undefined, a), "error: the user did not approve this git command");
           if (refused) return refused;
         }
         // Sandboxed like bash: flags such as --output or an editor cannot write outside the project or reach the network.

package/src/memory/brief.ts

@@ -2,17 +2,17 @@ import type { PeerId } from "../hub/envelope.ts";
 import type { MemoryClient } from "./client.ts";
 
 export interface BriefItem {
-  id: number;
+  id: number | string;
   time: string;
   type: string;
   title: string;
 }
 
-/** Rows of claude-mem's index tables: `| #65499 | 12:30 PM | ◆ | Title | ~372 |`. A row that does not match is skipped, never an error. */
+/** Amem entry tables (plus legacy numeric fixture compatibility): `| #65499 | 12:30 PM | ◆ | Title | ~372 |`. A row that does not match is skipped, never an error. */
 export function parseRows(markdown: string | undefined): BriefItem[] {
   const out: BriefItem[] = [];
-  for (const m of (markdown ?? "").matchAll(/^\|\s*#(\d+)\s*\|\s*([^|]*?)\s*\|\s*([^|]*?)\s*\|\s*(.*?)\s*\|/gm)) {
-    out.push({ id: Number(m[1]), time: m[2]!, type: m[3]!, title: m[4]!.replace(/\s*<-\s*\*\*ANCHOR\*\*/, "") });
+  for (const m of (markdown ?? "").matchAll(/^\|\s*#(mem:[a-f0-9]{32}|\d+)\s*\|\s*([^|]*?)\s*\|\s*([^|]*?)\s*\|\s*(.*?)\s*\|/gm)) {
+    out.push({ id: m[1]!.startsWith("mem:") ? m[1]! : Number(m[1]), time: m[2]!, type: m[3]!, title: m[4]!.replace(/\s*<-\s*\*\*ANCHOR\*\*/, "") });
   }
   return out;
 }
@@ -28,14 +28,14 @@ export async function related(client: MemoryClient, project: string, query: stri
 }
 
 /** A native memory line for a brief (#258): `mem:<id8> <kind> <tier>: <title or text>`, fails first. */
-export interface NativeItem { id: string; line: string; kind?: string; about?: readonly string[] }
-export type NativeBrief = (task: BriefTask) => NativeItem[];
+export interface NativeItem { id: string; line: string; kind?: string; about?: readonly string[]; tier?: string; peer?: string; machine?: string; at?: string }
+export type NativeBrief = (task: BriefTask) => NativeItem[] | Promise<NativeItem[]>;
 export interface BriefTask { id?: number; created?: number; title: string; refs: { paths?: string[] }; plan?: { paths?: string[]; symbols?: string[] } }
 
 /**
  * Task briefs: what memory already knows about a piece of work, handed over with it. The hub's own store first (#258:
  * entries one or two hops from the task's paths, symbols, issue and task, a linked fail first, superseded entries
- * dropped), then claude-mem: index first (search), then the neighbourhood of the top hit (timeline); details stay in
+ * dropped), then amem: index first (search), then the neighbourhood of the top hit (timeline); details stay in
  * the store for the receiver to fetch by id. `brief_items` caps both together. A peer is never shown the same entry
  * twice in one hub run, except a directly matching plan fail that must accompany a new task.
  */
@@ -53,25 +53,35 @@ export class Briefs {
   ) {}
 
   async forTask(peer: PeerId, task: BriefTask, priority: readonly NativeItem[] = []): Promise<string | undefined> {
+    // A brief snapshots its configured cap once, before either optional source is selected.
     const maximum = typeof this.maxItems === "function" ? this.maxItems() : this.maxItems;
     const seen = this.seen.get(peer) ?? new Set<string>();
     this.seen.set(peer, seen);
+    let native: NativeItem[] = [];
+    try { native = await (this.native?.(task) ?? []); } catch { /* fail-open: the store and derived code context are optional */ }
     const own: NativeItem[] = [];
     // A plan fail is task-specific guidance even when a previous task already carried it.
+    const priorityIds = new Set(priority.map(item => item.id));
     for (const item of priority) if (own.length < maximum && !own.some(existing => existing.id === item.id)) own.push(item);
-    try { for (const item of this.native?.(task) ?? []) if (!seen.has(item.id) && !own.some(existing => existing.id === item.id) && own.length < maximum) own.push(item); } catch { /* fail-open: the store is optional */ }
+    // Native order is host-supplied (linked fails, then nearer/newer); preserve it for synchronous callers too.
+    try { for (const item of native) if (!seen.has(item.id) && !own.some(existing => existing.id === item.id) && own.length < maximum) own.push(item); } catch { /* optional native iteration stays fail-open */ }
     const found = this.client && own.length < maximum ? await related(this.client, this.project, [task.title, ...(task.refs.paths ?? [])].join(" ")) : [];
+    // Another brief for this peer may finish while either optional source is awaited.
+    const currentOwn = own.filter(item => priorityIds.has(item.id) || !seen.has(item.id)).slice(0, maximum);
+    own.splice(0, own.length, ...currentOwn);
     const items: BriefItem[] = [];
     for (const item of found) {
-      if (seen.has(`#${item.id}`)) continue;
+      if (own.length + items.length >= maximum) break;
+      if (seen.has(`#${item.id}`) || seen.has(String(item.id)) || own.some(v => v.id === item.id)) continue;
       items.push(item);
       if (own.length + items.length === maximum) break;
     }
-    if (!own.length && !items.length) return undefined;
+    const notice = this.client?.readNotice();
+    if (!own.length && !items.length && !notice) return undefined;
     for (const item of own) seen.add(item.id);
     for (const item of items) seen.add(`#${item.id}`);
     if (task.id !== undefined) try { this.observe?.(peer, task.id, { native: own.length, fails: own.filter((i) => i.kind === "fail").length, claudeMem: items.length }); } catch { /* telemetry never fails a brief */ }
-    const header = own.length ? "Memory brief (hub memory first, fails first: ahub memory show <mem id>; claude-mem by #id):" : "Memory brief (claude-mem; fetch details by id if you need them):";
-    return [header, ...(this.displayNative?.(own) ?? own.map((i) => i.line)), ...items.map((i) => `#${i.id} ${i.time} ${i.type} ${i.title}`)].join("\n");
+    const header = own.length ? "Memory brief (hub memory first, fails first: ahub memory show <mem id>; amem by mem:id):" : "Memory brief (amem curated notes; fetch details by mem:id):";
+    return [header, ...(notice ? [notice] : []), ...(this.displayNative?.(own) ?? own.map((i) => i.line)), ...items.map((i) => `${i.id.toString().startsWith("mem:") ? i.id : `#${i.id}`} ${i.time} ${i.type} ${i.title}`)].join("\n");
   }
 }

package/src/memory/capture.ts

@@ -1,23 +1,10 @@
+import { isAbsolute, relative, resolve, sep } from "node:path";
 import { defaultCapturePeer } from "../adapters/definitions/native-identity-defaults.ts";
 import { BOUNDED_TASK_TOOLS } from "../hub/hub-tools.ts";
 import { MEMORY_READ_TOOLS } from "../hub/read-tools.ts";
-import { readFileSync } from "node:fs";
-import { homedir } from "node:os";
-import { join } from "node:path";
 import { isDenied } from "../local/deny.ts";
 import type { MemoryClient } from "./client.ts";
 
-const OUTPUT_CAP = 4000;
-
-/** claude-mem's own skip list, so the hub captures what the native hooks would. */
-export function skipTools(settingsPath = join(homedir(), ".claude-mem", "settings.json")): string[] {
-  try {
-    return String(JSON.parse(readFileSync(settingsPath, "utf8")).CLAUDE_MEM_SKIP_TOOLS ?? "").split(",").map((s) => s.trim()).filter(Boolean);
-  } catch {
-    return [];
-  }
-}
-
 export interface CaptureOptions {
   project: string;
   cwd: string;
@@ -27,12 +14,11 @@ export interface CaptureOptions {
   deny?: string[];
 }
 
-/**
- * The hub acting as claude-mem's hook client for the local worker (payload shapes read from the 13.25.1 hook code).
- * Fire-and-forget on top of the fail-open client: a down worker costs one log line per call and never a turn.
- */
+/** Deterministic local capture. No observer/model runs; private-turn gating stays in the host. */
 export class Capture {
   private sessionId = "";
+  private readonly toolTimes = new Map<string, string>();
+  private sequence = 0;
   private readonly platformSource: string;
   private readonly agentId: string;
 
@@ -46,41 +32,41 @@ export class Capture {
 
   init(sessionId: string, prompt: string): void {
     this.sessionId = sessionId;
-    void this.client.request("POST", "/api/sessions/init", { contentSessionId: sessionId, project: this.opts.project, prompt, platformSource: this.platformSource });
+    this.toolTimes.clear();
+    this.sequence = 0;
+    void this.client.appendCapture({ project: this.opts.project, cwd: this.opts.cwd, at: new Date().toISOString(), sessionId, agent: this.agentId, event: "SessionStart", excerpt: prompt, platformSource: this.platformSource });
   }
 
-  observe(call: { tool: string; args: string; output: string; id: string; paths: string[] }): void {
+  observe(call: { tool: string; args: string; output: string; id: string; paths: string[]; sourceId?: string }): void {
     if (!this.sessionId || ((MEMORY_READ_TOOLS.has(call.tool.replace(/^mcp__[^ ]+__/, "")) || BOUNDED_TASK_TOOLS.has(call.tool.replace(/^mcp__[^ ]+__/, ""))) || call.tool.replace(/^mcp__[^ ]+__/, "") === "hub_memory_correct") || this.opts.skip?.includes(call.tool)) return;
     // Anything that names a denylisted path is kept out of memory entirely, input and output alike.
-    if (call.paths.some((p) => p.split(/\s+/).some((word) => isDenied(word, this.opts.deny)))) return;
-    void this.client.request("POST", "/api/sessions/observations", {
-      contentSessionId: this.sessionId,
-      platformSource: this.platformSource,
-      tool_name: call.tool,
-      tool_input: call.args,
-      tool_response: call.output.slice(0, OUTPUT_CAP),
-      cwd: this.opts.cwd,
-      agentId: this.agentId,
-      agentType: "local-worker",
-      tool_use_id: call.id,
-    });
+    if (call.paths.some((p) => isDenied(p, this.opts.deny) || p.split(/\s+/).some((word) => isDenied(word, this.opts.deny)))) return;
+    // ponytail: legacy callers without a host sourceId dedupe native ids within a summary interval; all live LocalPeer calls supply invocation identity. Require that port for other hosts.
+    const sourceId = call.sourceId ?? `${this.sequence}:${call.id}`;
+    let at = this.toolTimes.get(sourceId);
+    if (!at) {
+      at = new Date().toISOString(); this.toolTimes.set(sourceId, at);
+      // ponytail: duplicate-call timestamps retain the newest 1024 source ids; upgrade to a host-supplied source-event timestamp.
+      if (this.toolTimes.size > 1024) this.toolTimes.delete(this.toolTimes.keys().next().value!);
+    }
+    // Commands/argv are policy inputs, never path metadata. Persist only in-project file-tool paths.
+    const paths = ["read", "write", "edit"].includes(call.tool) ? call.paths.flatMap(p => {
+      const name = relative(resolve(this.opts.cwd), resolve(this.opts.cwd, p));
+      return !name || isAbsolute(name) || name.split(sep).includes("..") ? [] : [name.split(sep).join("/")];
+    }) : [];
+    void this.client.appendCapture({ project: this.opts.project, cwd: this.opts.cwd, at, sessionId: this.sessionId, agent: this.agentId, event: "PostToolUse", tool: call.tool, paths, excerpt: `${call.args}\n${call.output}`, input: call.args, output: call.output, toolUseId: call.id, sourceId, platformSource: this.platformSource });
   }
 
   summarize(lastAssistantMessage: string): void {
     if (!this.sessionId) return;
-    // No agentId here: the worker answers a summarize that carries one with {status: "skipped", reason: "subagent_context"} (verified live).
-    void this.client.request("POST", "/api/sessions/summarize", {
-      contentSessionId: this.sessionId,
-      last_assistant_message: lastAssistantMessage,
-      platformSource: this.platformSource,
-    });
+    void this.client.appendCapture({ project: this.opts.project, cwd: this.opts.cwd, at: new Date().toISOString(), sessionId: this.sessionId, toolUseId: `summary:${++this.sequence}`, agent: this.agentId, event: "Stop", excerpt: lastAssistantMessage, platformSource: this.platformSource });
   }
 
-  /** Awaited by the caller: the hub process exits right after stop(), and an unawaited request would die with it. Bounded by the client timeout. */
+  /** Awaited by the caller: the hub process exits right after stop(), and an unawaited request would die with it. The synchronous published store operation has completed before this promise settles. */
   async end(): Promise<void> {
     if (!this.sessionId) return;
     const contentSessionId = this.sessionId;
     this.sessionId = "";
-    await this.client.request("POST", "/api/sessions/session-end", { contentSessionId, platformSource: this.platformSource, reason: "hub stop", cwd: this.opts.cwd });
+    await this.client.appendCapture({ project: this.opts.project, cwd: this.opts.cwd, at: new Date().toISOString(), sessionId: contentSessionId, agent: this.agentId, event: "SessionEnd", excerpt: "hub stop", platformSource: this.platformSource });
   }
 }

package/src/memory/client.ts

@@ -1,79 +1,151 @@
-import { readFileSync } from "node:fs";
-import { homedir } from "node:os";
-import { join } from "node:path";
+import packageJson from "../../package.json";
+import { createHash } from "node:crypto";
+import { CaptureStore, SearchIndex, looksSecret, memoryBase, readCaptureConfig, type CaptureOptions as StoreCaptureOptions, type MemoryStore, type CandidateStore, type View } from "@staix/agent-mem";
 
-const DEFAULT_PORT = 37701;
+export interface CaptureEvent {
+  project: string; at?: string; agent: string; event: string; tool?: string; paths?: string[]; status?: string; excerpt: string;
+  cwd?: string; sourceId?: string; sessionId?: string; toolUseId?: string; input?: string; output?: string; platformSource?: string;
+}
+export interface MemoryClientOptions {
+  project: string;
+  store?: MemoryStore;
+  candidates?: CandidateStore;
+  check(): void;
+  /** The host screens complete rows before selection or rendering. */
+  screen(rows: View[]): View[];
+  publicText(text: string): boolean;
+  capture?: () => Omit<StoreCaptureOptions, "project">;
+  log?: (line: string) => void;
+}
+const safeCell = (text: string) => text.replace(/[|\r\n]/g, " ");
+const table = (rows: View[]) => "| ID | Time | T | Title |\n|---|---|---|---|\n" + rows.map(v => `| #mem:${v.id} | ${v.at} | ${v.kind} | ${safeCell(v.title || v.text)} |`).join("\n");
 
-/** claude-mem worker URL: `memory.worker_url` override, else the port in ~/.claude-mem/settings.json. */
-export function workerUrl(settingsPath = join(homedir(), ".claude-mem", "settings.json")): string {
-  let port = DEFAULT_PORT;
-  try {
-    port = Number(JSON.parse(readFileSync(settingsPath, "utf8")).CLAUDE_MEM_WORKER_PORT) || DEFAULT_PORT;
-  } catch {
-    // no settings file: default port
-  }
-  return `http://127.0.0.1:${port}`;
+/** Policy sees literal field strings as well as JSON, before display/storage escaping can hide a private value. */
+function policyText(value: unknown): string {
+  const raw: string[] = [];
+  const encoded = JSON.stringify(value, (key: string, item: unknown) => {
+    if (key && item !== undefined) raw.push(key);
+    if (typeof item === "number" && !Number.isFinite(item)) throw new Error("invalid memory scalar");
+    if (item === null || ["string", "number", "boolean"].includes(typeof item)) {
+      const text = String(item); raw.push(text); if (key) raw.push(`${key}: ${text}`);
+    }
+    return item;
+  });
+  return `${encoded ?? ""}\n${raw.join("\n")}`;
+}
+/** Only authoritative tool JSON is decoded, once; arbitrary embedded encodings are not interpreted. */
+function toolJson(text: string | undefined): unknown {
+  if (text === undefined) return undefined;
+  try { return JSON.parse(text) as unknown; } catch { return undefined; }
 }
 
-/**
- * Client for the claude-mem worker HTTP API. The API is internal and unversioned, so every call is
- * fail-open: a down or changed worker yields `undefined`, never an exception, and never blocks a turn.
- * Typed endpoint wrappers are added by the milestone that first needs them.
- */
+/** In-process amem host. No worker URL, HTTP, model, timer or resident helper. Errors are neutral and fail open. */
 export class MemoryClient {
-  constructor(
-    readonly url = workerUrl(),
-    private readonly timeoutMs = 2000,
-    private readonly log: (line: string) => void = () => {},
-  ) {}
-
-  async request<T = unknown>(method: "GET" | "POST", path: string, body?: unknown): Promise<T | undefined> {
-    return this.call(method, path, body, (res) => res.json() as Promise<T>);
+  private captureStore?: CaptureStore;
+  private captureKey?: string;
+  private closed = false;
+  private viewStatus = { truncated: false, scanned: 0, limit: 4096 };
+  constructor(private readonly options?: MemoryClientOptions) {}
+  readStatus(): { truncated: boolean; scanned: number; limit: number } { return { ...this.viewStatus }; }
+  readNotice(): string | undefined { return this.viewStatus.truncated ? `memory view truncated: newest ${this.viewStatus.limit} project candidates considered` : undefined; }
+  private releaseCapture(): void {
+    const store = this.captureStore; this.captureStore = undefined; this.captureKey = undefined;
+    try { store?.close(); } catch { /* fail-open teardown */ }
   }
-
-  /** Recent-context block (text/plain markdown). `chain`: project names, the primary one last. No `platformSource` = all platforms. */
-  contextInject(chain: string[], platformSource?: string): Promise<string | undefined> {
-    const query = `projects=${encodeURIComponent(chain.join(","))}${platformSource ? `&platformSource=${encodeURIComponent(platformSource)}` : ""}`;
-    return this.call("GET", `/api/context/inject?${query}`, undefined, (res) => res.text());
+  close(): void { this.closed = true; this.releaseCapture(); }
+  private run<T>(work: (o: MemoryClientOptions) => T): T | undefined {
+    try { if (!this.options || this.closed) return undefined; this.options.check(); return work(this.options); }
+    catch { this.releaseCapture(); this.options?.log?.("amem operation unavailable"); return undefined; }
   }
-
-  /** Index search. The worker answers in MCP shape, `{content: [{type: "text", text: <markdown table>}]}`; this returns the text. */
-  async search(query: string, project: string, limit = 10): Promise<string | undefined> {
-    const q = `query=${encodeURIComponent(query)}&project=${encodeURIComponent(project)}&limit=${limit}`;
-    return mcpText(await this.request("GET", `/api/search?${q}`));
+  private rows(o: MemoryClientOptions): View[] {
+    const store = o.store;
+    this.viewStatus = { truncated: false, scanned: 0, limit: 4096 };
+    if (!store) return [];
+    const rows: View[] = [];
+    let after: { position: number; id: string } | undefined;
+    // ponytail: at most 4096 exact-project candidate bodies, in published keyset pages. The core still folds relation metadata; upgrade to core tier/scope pages and incremental metadata snapshots.
+    for (let page = 0; page < 16; page++) {
+      const result = store.readPage({ project: o.project, limit: 256, ...(after ? { after } : {}) });
+      this.viewStatus.scanned += result.rows.length;
+      if (result.rows.length) rows.push(...o.screen(result.rows.filter(v => !looksSecret(`${v.title ?? ""}\n${v.text}`) && !v.title?.startsWith("ahub ask (model answer)"))));
+      if (!result.next) return rows;
+      after = result.next;
+    }
+    this.viewStatus.truncated = !!store.readPage({ project: o.project, limit: 1, ...(after ? { after } : {}) }).next;
+    return rows;
   }
-
-  async timeline(anchor: number, project: string, before = 3, after = 3): Promise<string | undefined> {
-    return mcpText(await this.request("GET", `/api/timeline?anchor=${anchor}&project=${encodeURIComponent(project)}&depth_before=${before}&depth_after=${after}`));
+  async contextInject(_chain: string[], _platformSource?: string): Promise<string | undefined> {
+    return this.run(o => {
+      const rows = this.rows(o).filter(v => v.tier === "short").slice(0, 30);
+      const notice = this.readNotice();
+      return rows.length || notice ? `# [amem] recent curated context\n\n### Curated short-term notes\n${[...(notice ? [notice] : []), ...rows.map(v => `mem:${v.id} ${v.kind}: ${safeCell(v.title || v.text)}`)].join("\n")}` : undefined;
+    });
   }
-
-  /** An explicit shared note. `metadata` carries who said it and about which task. */
-  save(note: { text: string; title?: string; project: string; metadata: Record<string, unknown> }): Promise<unknown> {
-    return this.request("POST", "/api/memory/save", note);
+  async search(query: string, _project: string, limit = 10): Promise<string | undefined> {
+    return this.run(o => {
+      if (!o.publicText(query)) return undefined;
+      const rows = this.rows(o), cap = Math.min(30, Math.max(0, limit));
+      const index = new SearchIndex(":memory:");
+      try {
+        const notice = this.readNotice();
+        const coverage = notice ? `${notice}\n` : "";
+        if (!index.available) {
+          const terms = query.toLowerCase().split(/\s+/).filter(Boolean);
+          return coverage + "Search engine: substring\n" + table(rows.filter(v => terms.every(term => `${v.title ?? ""} ${v.text} ${v.about.join(" ")}`.toLowerCase().includes(term))).slice(0, cap));
+        }
+        index.resync(() => rows.map(v => ({ id: v.id, at: v.at, project: o.project, tier: v.tier, scope: v.scope, body: `${v.title ?? ""}\n${v.text}\n${v.about.join(" ")}` })));
+        const byId = new Map(rows.map(v => [v.id, v]));
+        return coverage + table(index.query(query, cap, o.project).flatMap(hit => { const v = byId.get(hit.ref); return v ? [v] : []; }));
+      } finally { index.close(); }
+    });
   }
-
-  private async call<T>(method: "GET" | "POST", path: string, body: unknown, read: (res: Response) => Promise<T>): Promise<T | undefined> {
-    try {
-      const res = await fetch(`${this.url}${path}`, {
-        method,
-        signal: AbortSignal.timeout(this.timeoutMs),
-        ...(body === undefined ? {} : { headers: { "content-type": "application/json" }, body: JSON.stringify(body) }),
-      });
-      if (!res.ok) throw new Error(`HTTP ${res.status}`);
-      return await read(res);
-    } catch (e) {
-      this.log(`memory ${method} ${path} dropped: ${(e as Error).message}`);
-      return undefined;
-    }
+  async timeline(anchor: number | string, _project: string, before = 3, after = 3): Promise<string | undefined> {
+    return this.run(o => {
+      const rows = this.rows(o), at = rows.findIndex(v => `mem:${v.id}` === anchor);
+      return at < 0 ? this.readNotice() : `${this.readNotice() ? this.readNotice() + "\n" : ""}` + table(rows.slice(Math.max(0, at - Math.min(10, before)), at + Math.min(10, after) + 1));
+    });
+  }
+  /** Auxiliary model/checkpoint writes are candidates, never curated evidence. Tasks' native note remains authoritative. */
+  async save(note: { text: string; title?: string; project: string; metadata: Record<string, unknown> }): Promise<unknown> {
+    return this.run(o => {
+      if (!o.candidates) return undefined;
+      const complete = policyText({ ...note, project: o.project });
+      if (!o.publicText(complete) || looksSecret(complete)) return undefined;
+      o.check();
+      const text = `Submitted metadata: ${JSON.stringify(note.metadata)}\n\n${note.text}`;
+      if (!o.publicText(text) || looksSecret(text)) return undefined;
+      const noteKind = ["decision", "finding", "contract", "fail"].includes(String(note.metadata.kind)) ? note.metadata.kind as "decision" | "finding" | "contract" | "fail" : "finding";
+      const id = o.candidates.put({ kind: "memory", project: o.project, text, noteKind, ...(note.title ? { title: note.title } : {}) }, "public");
+      return { status: "candidate", id: `candidate:${id}` };
+    });
+  }
+  async appendCapture(event: CaptureEvent): Promise<unknown> {
+    return this.run(o => {
+      // Inspect persisted/user data, not host locators such as cwd (the parent of every private path).
+      const data = { project: o.project, agent: event.agent, event: event.event, tool: event.tool, paths: event.paths,
+        status: event.status, excerpt: event.excerpt, input: event.input, output: event.output };
+      const complete = policyText([data, toolJson(event.input), toolJson(event.output)]);
+      if (!o.capture || !o.publicText(complete) || looksSecret(complete)) return undefined;
+      o.check();
+      const options = o.capture();
+      const config = this.captureStore ? readCaptureConfig(this.captureStore.dir, options.memoryDir ?? memoryBase(options.home)) : undefined;
+      const key = JSON.stringify([o.project, options.home, options.memoryDir, options.capMb ?? config?.capMb, options.retentionDays ?? config?.retentionDays]);
+      if (this.captureKey !== key) {
+        this.releaseCapture();
+        this.captureStore = new CaptureStore({ ...options, project: o.project, screen: text => looksSecret(text) || !o.publicText(text) });
+        const limits = this.captureStore.stats();
+        this.captureKey = JSON.stringify([o.project, options.home, options.memoryDir, limits.capMb, limits.retentionDays]);
+      }
+      const store = this.captureStore!;
+      {
+        const at = event.at ?? new Date().toISOString();
+        const receipt = createHash("sha256").update(JSON.stringify([o.project,event.sessionId,event.sourceId,event.toolUseId,event.event,at])).digest("hex");
+        o.check();
+        return store.append({ project: o.project, at, agent: event.agent, event: event.event, ...(event.tool ? { tool: event.tool } : {}), paths: event.paths ?? [], ...(event.status ? { status: event.status } : {}), excerpt: event.excerpt }, { receipt });
+      }
+    });
   }
-
   async health(): Promise<{ ok: boolean; version?: string }> {
-    const h = await this.request<{ status?: string; version?: string }>("GET", "/api/health");
-    return h?.status === "ok" ? { ok: true, ...(h.version ? { version: h.version } : {}) } : { ok: false };
+    return this.run(() => ({ ok: true, version: packageJson.dependencies["@staix/agent-mem"] })) ?? { ok: false };
   }
 }
-
-function mcpText(res: unknown): string | undefined {
-  const content = (res as { content?: { type: string; text?: string }[] } | undefined)?.content;
-  return content?.find((c) => c.type === "text")?.text;
-}