@staix/agent-mem 0.9.1 → 0.11.0

package/src/memory/project-import.ts

@@ -15,7 +15,7 @@ const NOTE_KEYS = new Set(["schema", "id", "at", "machine", "op", "project", "sc
 const OPERATIONS_WARNING = "Supersede, demote, settle and forget operations are not exported; re-import restores authored note rows only.";
 
 type ImportedNote = { id: string; at: string; machine: string; note: NoteInput };
-type Provenance = { source: Record<string, number>; peer: Record<string, number>; scope: Record<string, number> };
+type Provenance = { source: Record<string, number>; peer: Record<string, number>; scope: Record<string, number>; machine: Record<string, number> };
 export interface ProjectImportResult {
   applied: boolean;
   project: string;
@@ -46,13 +46,18 @@ function increment(counts: Map<string, number>, value: string | undefined): void
 }
 
 function provenance(notes: Iterable<ImportedNote>): Provenance {
-  const source = new Map<string, number>(), peer = new Map<string, number>(), scope = new Map<string, number>();
-  for (const { note } of notes) {
+  const source = new Map<string, number>(), peer = new Map<string, number>(), scope = new Map<string, number>(), machine = new Map<string, number>();
+  for (const { note, machine: origin } of notes) {
     increment(source, note.source);
     increment(peer, note.peer);
     increment(scope, note.scope);
+    increment(machine, origin);
   }
-  return { source: Object.fromEntries(source), peer: Object.fromEntries(peer), scope: Object.fromEntries(scope) };
+  return { source: Object.fromEntries(source), peer: Object.fromEntries(peer), scope: Object.fromEntries(scope), machine: Object.fromEntries(machine) };
+}
+
+function relationTargets(imported: ImportedNote): string[] {
+  return [imported.note.supersedes, imported.note.promotedFrom].filter((target): target is string => typeof target === "string");
 }
 
 function unchangedAfterNormalization(note: NoteInput): boolean {
@@ -71,10 +76,10 @@ export async function importProject(store: MemoryStore, opts: {
   const fd = openSync(opts.from, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
   const stream = createReadStream(opts.from, { fd, encoding: "utf8" });
   const result: ProjectImportResult = { applied: opts.confirm === true, project: opts.project, read: 0, added: 0, wouldAdd: 0,
-    skipped: { invalid: 0, policy: 0, other: 0 }, provenance: { source: {}, peer: {}, scope: {} }, warnings: [OPERATIONS_WARNING] };
+    skipped: { invalid: 0, policy: 0, other: 0 }, provenance: { source: {}, peer: {}, scope: {}, machine: {} }, warnings: [OPERATIONS_WARNING] };
   let header = false, bytes = 0;
   let aliases: string[] = [];
-  const pending = new Map<string, ImportedNote>(), accepted: ImportedNote[] = [];
+  const pending = new Map<string, ImportedNote>(), accepted = new Map<string, ImportedNote>();
   try {
     const stat = fstatSync(fd);
     if (!stat.isFile() || stat.size > PROJECT_IMPORT_MAX_BYTES) throw new Error("project import needs a regular JSONL file of at most 64 MiB");
@@ -121,22 +126,34 @@ export async function importProject(store: MemoryStore, opts: {
     if (!header) throw new Error("project import has no header");
 
     for (const imported of pending.values()) {
-      if (["supersedes", "promotedFrom"].some(field => {
-        const target = imported.note[field as "supersedes" | "promotedFrom"] as string | null | undefined;
-        return target !== undefined && target !== null && !pending.has(target);
-      })) {
+      if (relationTargets(imported).some(target => !pending.has(target))) {
         result.skipped.invalid++;
         continue;
       }
       const screened = stripPrivateDeep(imported.note);
       if (looksSecret(JSON.stringify(screened)) || !await opts.policy(screened)) { result.skipped.policy++; continue; }
-      accepted.push(imported);
+      accepted.set(imported.id, imported);
+    }
+    // A policy-refused target cannot authorize its dependents. Propagate removals before any append,
+    // regardless of file order, in linear time even when a long relation chain is refused.
+    const dependents = new Map<string, string[]>(), refused: string[] = [];
+    for (const imported of accepted.values()) for (const target of relationTargets(imported)) {
+      const rows = dependents.get(target) ?? [];
+      rows.push(imported.id); dependents.set(target, rows);
+      if (!accepted.has(target)) refused.push(imported.id);
+    }
+    for (let at = 0; at < refused.length; at++) {
+      const id = refused[at]!;
+      if (!accepted.delete(id)) continue;
+      result.skipped.invalid++;
+      for (const dependent of dependents.get(id) ?? []) refused.push(dependent);
     }
-    result.provenance = provenance(accepted);
+    result.provenance = provenance(accepted.values());
     const existing = new Set(store.portableNotes(opts.project).map(note => note.id));
-    result.wouldAdd = accepted.filter(note => !existing.has(note.id)).length;
+    result.wouldAdd = [...accepted.keys()].filter(id => !existing.has(id)).length;
     if (opts.confirm === true) {
-      for (const imported of accepted) {
+      store.assertImportable([...accepted.values()].map(imported => imported.note));
+      for (const imported of accepted.values()) {
         const written = store.importNote(imported.note, imported.at, { machine: imported.machine, expectedId: imported.id });
         if (written.added) result.added++;
       }

package/src/memory/search-fts.ts

@@ -1,3 +1,4 @@
+import { rankedScoreSql, rankedScoreSqlDetails, type ScoreFactors } from "./search-score.ts";
 import { Database } from "bun:sqlite";
 import { chmodSync, existsSync } from "node:fs";
 import { join } from "node:path";
@@ -187,6 +188,67 @@ export class SearchIndex {
   close(): void { this.db?.close(); }
 }
 
+const SCREENED_SCORE = rankedScoreSql(), SCREENED_SUBSTRING_SCORE = rankedScoreSql("-1.0");
+
+/** Screened query-local corpus in SQLite-owned TEMP storage, removed even when the process exits. */
+export class ScreenedSearchIndex<T> {
+  readonly available = fts5Available();
+  private readonly db: Database;
+  private closed = false;
+
+  constructor() {
+    let db: Database | undefined;
+    try {
+      db = new Database(":memory:");
+      // SQLite owns the anonymous TEMP files; no named plaintext cache survives a killed MCP child.
+      if ((db.query("SELECT sqlite_compileoption_used('TEMP_STORE=3') AS memoryOnly").get() as { memoryOnly: number }).memoryOnly) throw Error("disk-backed search unavailable");
+      db.run("PRAGMA temp_store = FILE");
+      db.run(this.available
+        ? "CREATE VIRTUAL TABLE temp.docs USING fts5(body, ref UNINDEXED, tier UNINDEXED, at UNINDEXED, payload UNINDEXED, expires UNINDEXED)"
+        : "CREATE TEMP TABLE docs (body TEXT, ref TEXT, tier TEXT, at TEXT, payload TEXT, expires REAL)");
+      db.run("PRAGMA temp.cache_size = -2048");
+      // A platform spill minimum can exceed cache_size (macOS: 20,000 pages).
+      // Spill at the cache target so dirty TEMP pages cannot accumulate behind that minimum.
+      db.run("PRAGMA temp.cache_spill = 1");
+      this.db = db;
+    } catch (error) { db?.close(); throw error; }
+  }
+
+  append(rows: readonly { body: string; ref: string; tier: string; at: string; value: T; expiresAt?: string | null }[]): void {
+    const insert = this.db.query("INSERT INTO docs (body, ref, tier, at, payload, expires) VALUES (?, ?, ?, ?, ?, ?)");
+    this.db.transaction(() => {
+      for (const row of rows) {
+        const deadline = row.expiresAt == null ? null : Date.parse(row.expiresAt);
+        // Invalid deadlines fail closed; this sentinel predates every representable Date.
+        insert.run(row.body, row.ref, row.tier, row.at, JSON.stringify(row.value), deadline !== null && !Number.isFinite(deadline) ? Number.MIN_SAFE_INTEGER : deadline);
+      }
+    })();
+  }
+
+  best(query: string, limit: number, now: number, useFts = this.available, explain = false): { value: T; score: number; scoreDetails?: ScoreFactors }[] {
+    if (useFts && !ftsTerms(query)) return [];
+    const score = useFts ? SCREENED_SCORE : SCREENED_SUBSTRING_SCORE;
+    const instant = new Date(now).toISOString();
+    const where = "WHERE (expires IS NULL OR expires > ?)" + (useFts ? " AND docs MATCH ?" : "");
+    const factors = explain ? rankedScoreSqlDetails(useFts ? "bm25(docs)" : "-1.0", useFts) : undefined;
+    const columns = factors ? `, ${factors.rawBm25Rank} AS rawBm25Rank, ${factors.tierFactor} AS tierFactor, ${factors.recencyFactor} AS recencyFactor` : "";
+    const statement = this.db.query(`SELECT payload, ${score} AS score${columns} FROM docs ${where} ORDER BY score DESC, ref LIMIT ?`);
+    const rows = (explain ? statement.all(instant, instant, now, ...(useFts ? [ftsTerms(query)] : []), limit)
+      : statement.all(instant, now, ...(useFts ? [ftsTerms(query)] : []), limit)) as { payload: string; score: number; rawBm25Rank?: number | null; tierFactor?: number | null; recencyFactor?: number | null }[];
+    return rows.map(row => {
+      const hit: { value: T; score: number; scoreDetails?: ScoreFactors } = { value: JSON.parse(row.payload) as T, score: row.score };
+      if (explain) hit.scoreDetails = { rawBm25Rank: row.rawBm25Rank ?? null, tierFactor: row.tierFactor ?? null, recencyFactor: row.recencyFactor ?? null, finalScore: row.score, matchMode: useFts ? "fts5" : "substring" };
+      return hit;
+    });
+  }
+
+  close(): void {
+    if (this.closed) return;
+    this.closed = true;
+    this.db.close();
+  }
+}
+
 interface RawCaptureRow { id: number; at: string; project: string; agent: string; event: string; tool: string | null; paths: string; status: string | null; excerpt: string }
 
 /**
@@ -222,20 +284,23 @@ export interface ReadWindow {
   anchor?: string;
   prefix?: string;
   id?: string;
+  /** Exhaustive screened scans need stable identity order, not a chronological relevance window. */
+  order?: "id";
   after?: { position: number; id: string };
 }
 export interface ReadRef { id: string; at: string; position: number }
 /** Fixed column names supplied by the three derived stores; all caller values remain SQL parameters. */
-export function readWindowSql(window: ReadWindow, id: "id" | "ref") {
+export function readWindowSql(window: ReadWindow, id: "id" | "ref", identity: "text" | "integer" = "text") {
   if (!Number.isSafeInteger(window.limit) || window.limit < 1 || window.limit > 256) throw new Error("invalid read page limit");
   const bind: (string | number)[] = [];
-  const position = window.anchor ? (bind.push(window.anchor), "abs(julianday(at) - julianday(?))") : "-julianday(at)";
+  const position = window.order === "id" ? (identity === "integer" ? id : "0") : window.anchor ? (bind.push(window.anchor), "abs(julianday(at) - julianday(?))") : "-julianday(at)";
   const columns = `CAST(${id} AS TEXT) AS candidate_id, at, ${position} AS candidate_position`;
   const where = ["project IN (SELECT value FROM json_each(?))"]; bind.push(JSON.stringify(window.projects ?? [window.project]));
   if (window.since) { where.push("julianday(at) >= julianday(?)"); bind.push(window.since); }
   if (window.id !== undefined) { where.push(`${id} = ?`); bind.push(window.id); }
   if (window.prefix !== undefined) { where.push(`substr(${id}, 1, length(?)) = ?`); bind.push(window.prefix, window.prefix); }
-  if (window.after) {
+  if (window.after && window.order === "id") { where.push(`${id} > ?`); bind.push(window.after.id); }
+  else if (window.after) {
     where.push("(candidate_position > ? OR (candidate_position = ? AND candidate_id > ?))");
     bind.push(window.after.position, window.after.position, window.after.id);
   }

package/src/memory/search-score.ts

@@ -0,0 +1,66 @@
+/** One fixed score recipe for numeric library ranking and native screened SQL. */
+export interface ScoreFactors {
+  rawBm25Rank: number | null;
+  tierFactor: number | null;
+  recencyFactor: number | null;
+  finalScore: number | null;
+  matchMode: "fts5" | "substring";
+}
+export interface SearchScoreDetails extends ScoreFactors { source: "curated" | "capture" | "repo" }
+
+type ScoreExpr = { op: "rank" | "tier" | "age" } | { op: "constant"; value: number }
+  | { op: "negative" | "reciprocal"; value: ScoreExpr }
+  | { op: "add" | "multiply" | "max"; left: ScoreExpr; right: ScoreExpr };
+const MONTH_DAYS = 30;
+const TIER_WEIGHTS: Readonly<Record<string, number>> = { long: 1, capture: 0.5 };
+const DEFAULT_TIER_WEIGHT = 0.9;
+const TIER_FACTOR: ScoreExpr = { op: "tier" };
+const DENOMINATOR: ScoreExpr = { op: "add", left: { op: "constant", value: 1 }, right: { op: "max", left: { op: "constant", value: 0 }, right: { op: "age" } } };
+const RECENCY_FACTOR: ScoreExpr = { op: "reciprocal", value: DENOMINATOR };
+const SCORE: ScoreExpr = { op: "multiply", left: { op: "multiply", left: { op: "negative", value: { op: "rank" } }, right: TIER_FACTOR }, right: RECENCY_FACTOR };
+// ponytail: this represents only the fixed rank/tier/age recipe, not arbitrary expressions;
+// extend its operations with numeric/SQL parity tests when the ranking contract changes.
+function numeric(expr: ScoreExpr, rank: number, tier: string, at: string, now: number): number {
+  switch (expr.op) {
+    case "rank": return rank;
+    case "tier": return Object.hasOwn(TIER_WEIGHTS, tier) ? TIER_WEIGHTS[tier]! : DEFAULT_TIER_WEIGHT;
+    case "age": return (now - Date.parse(at)) / (MONTH_DAYS * 24 * 3600_000);
+    case "constant": return expr.value;
+    case "negative": return -numeric(expr.value, rank, tier, at, now);
+    case "reciprocal": return 1 / numeric(expr.value, rank, tier, at, now);
+    case "add": return numeric(expr.left, rank, tier, at, now) + numeric(expr.right, rank, tier, at, now);
+    case "multiply": return numeric(expr.left, rank, tier, at, now) * numeric(expr.right, rank, tier, at, now);
+    case "max": return Math.max(numeric(expr.left, rank, tier, at, now), numeric(expr.right, rank, tier, at, now));
+  }
+}
+const real = (value: number): string => Number.isInteger(value) ? `${value}.0` : String(value);
+function sql(expr: ScoreExpr, rank: string): string {
+  const get = (part: ScoreExpr): string => sql(part, rank);
+  switch (expr.op) {
+    case "rank": return rank;
+    case "tier": return `CASE tier ${Object.entries(TIER_WEIGHTS).map(([name, value]) => `WHEN '${name}' THEN ${real(value)}`).join(" ")} ELSE ${real(DEFAULT_TIER_WEIGHT)} END`;
+    case "age": return `((julianday(?) - julianday(at)) / ${real(MONTH_DAYS)})`;
+    case "constant": return real(expr.value);
+    case "negative": return `(-(${get(expr.value)}))`;
+    case "reciprocal": return `(1.0 / ${get(expr.value)})`;
+    case "add": return `(${get(expr.left)} + ${get(expr.right)})`;
+    // Preserve the existing SQL quotient's floating-point order; numeric ranking
+    // retains its original reciprocal product. Both interpret the same recipe.
+    case "multiply": return expr.right.op === "reciprocal" ? `(${get(expr.left)} / ${get(expr.right.value)})` : `(${get(expr.left)} * ${get(expr.right)})`;
+    case "max": return `max(${get(expr.left)}, ${get(expr.right)})`;
+  }
+}
+export function rankedScore(rank: number, tier: string, at: string, now: number): number {
+  return numeric(SCORE, rank, tier, at, now);
+}
+/** SQL uses fixed internal identifiers and bound clock values, never interpolated row/query input. */
+export function rankedScoreSql(rank = "bm25(docs)"): string { return sql(SCORE, rank); }
+export function rankedScoreSqlDetails(rank = "bm25(docs)", useFts = true): { rawBm25Rank: string; tierFactor: string; recencyFactor: string } {
+  return { rawBm25Rank: useFts ? rank : "NULL", tierFactor: sql(TIER_FACTOR, rank), recencyFactor: sql(RECENCY_FACTOR, rank) };
+}
+export function rankedScoreDetails(source: SearchScoreDetails["source"], rank: number, tier: string, at: string, now: number, finalScore: number): SearchScoreDetails {
+  return { source, rawBm25Rank: rank, tierFactor: numeric(TIER_FACTOR, rank, tier, at, now), recencyFactor: numeric(RECENCY_FACTOR, rank, tier, at, now), finalScore, matchMode: "fts5" };
+}
+export function unrankedScoreDetails(source: SearchScoreDetails["source"], finalScore: number | null): SearchScoreDetails {
+  return { source, rawBm25Rank: null, tierFactor: null, recencyFactor: null, finalScore, matchMode: "substring" };
+}

package/src/memory/store.ts

@@ -10,6 +10,8 @@ import { memoryHome } from "./home.ts";
 import { machineId, type Machine } from "./machine.ts";
 import { assertProjectActive } from "./lifecycle.ts";
 export { machineId, type Machine } from "./machine.ts";
+import { rankedScore, rankedScoreDetails, unrankedScoreDetails, type SearchScoreDetails } from "./search-score.ts";
+export type { SearchScoreDetails } from "./search-score.ts";
 import { readWindowSql, readRef, type ReadWindow, type ReadRef, SearchIndex, captureSearch } from "./search-fts.ts";
 import { assertCuratedShardPaths, ensureShardDescriptor, readShardDescriptor, readShardedSelection, aliasedKeys, resolveAlias, resolveShardProfile, shardDir, shardKeyHash, shardMachineDir, userShardDir } from "./shard.ts";
 import { readCaptureConfig, type CaptureRow } from "./capture.ts";
@@ -168,10 +170,12 @@ export interface Filter { project?: string; tier?: Tier; kind?: Kind; peer?: str
 /** #13 search: `Filter` plus the capture-tier switch (on by default; capture is recall, never curated evidence). */
 export interface SearchFilter extends Filter {
   includeCapture?: boolean;
+  /** Attach score factors only when explicitly requested. */
+  explain?: boolean;
   /** A host that writes capture with a `retentionDays` override passes the same value here; files decide otherwise. */
   captureRetentionDays?: number;
 }
-export interface SearchHit { source: "curated" | "capture"; score: number; view?: View; capture?: CaptureRow }
+export interface SearchHit { source: "curated" | "capture"; score: number; scoreDetails?: SearchScoreDetails; view?: View; capture?: CaptureRow }
 export interface SearchResult { engine: "fts5" | "substring"; hits: SearchHit[] }
 export interface Graph { nodes: { id: Node; type: string; label: string; kind?: string; tier?: Tier }[]; edges: { from: Node; to: Node; rel: string }[] }
 
@@ -490,18 +494,30 @@ export class MemoryStore {
   // `ownClock`: a note asked for short-term on purpose expires on its own clock, open task or not, and is never promoted.
   note(n: NoteInput, ownClock = false): string { return this.append(n.tier === "short" && !n.expires && (ownClock || !n.task || this.settled(n.task)) ? { ...n, expires: this.until() } : n, n.tier === "short"); }
 
-  /**
-   * An entry from another store with its own time (`ahub memory import claude-mem`): the same source row always gives
-   * the same id, so a second import writes nothing. Returns the id and whether it was new.
-   */
-  importNote(n: NoteInput, at: string, identity: { machine?: string; expectedId?: string } = {}): { id: string; added: boolean } {
+  /** The already-opened owner of an imported row, shared by preflight and append. */
+  private importOwner(n: NoteInput): MemoryStore {
     if (this.bootstrapOnly) throw new Error("migration bootstrap cannot import memory");
-    if (this.userOverlay && n.scope === "shared") return this.userOverlay.importNote(n, at, identity);
+    if (this.userOverlay && n.scope === "shared") return this.userOverlay.importOwner(n);
     if (this.profile.sharded && !this.profile.shardUser && n.scope === "project" && n.project !== this.profile.shardKey) {
       const owner = this.aliasStores.find(store => store.profile.shardKey === n.project);
-      if (owner) return owner.importNote(n, at, identity);
+      if (owner) return owner.importOwner(n);
     }
     if (this.profile.sharded && (this.profile.shardUser ? n.scope !== "shared" : n.scope !== "project" || n.project !== this.profile.shardKey)) throw new Error("entry does not belong to this curated shard");
+    return this;
+  }
+
+  /** Check every import route before a multi-row caller appends; never creates a missing alias shard. */
+  assertImportable(notes: Iterable<NoteInput>): void {
+    for (const note of notes) this.importOwner(note);
+  }
+
+  /**
+   * An entry from another store with its own time (`ahub memory import claude-mem`): the same source row always gives
+   * the same id, so a second import writes nothing. Returns the id and whether it was new.
+   */
+  importNote(n: NoteInput, at: string, identity: { machine?: string; expectedId?: string } = {}): { id: string; added: boolean } {
+    const owner = this.importOwner(n);
+    if (owner !== this) return owner.importNote(n, at, identity);
     assertSharedV1Op(n.op);
     // A fixed machine: the same observation imported on two machines is one entry once they sync. A project import preserves the exported identity instead.
     const body = { schema: MEMORY_SCHEMA, at, machine: identity.machine ?? "claude-mem", ...n, text: stripPrivateSpans(n.text).slice(0, MAX_TEXT), ...(n.title ? { title: stripPrivateSpans(n.title).slice(0, MAX_TITLE) } : {}) } as Omit<Entry, "id">;
@@ -1057,12 +1073,15 @@ export class MemoryStore {
    */
   search(q: string, f: SearchFilter = {}): SearchResult {
     const limit = f.limit ?? 200;
-    if (!this.searchIndex.available) return { engine: "substring", hits: this.list({ ...f, q }).map((view) => ({ source: "curated" as const, score: 0, view })) };
+    if (!this.searchIndex.available) return { engine: "substring", hits: this.list({ ...f, q }).map(view => {
+      const hit: SearchHit = { source: "curated", score: 0, view };
+      if (f.explain) hit.scoreDetails = unrankedScoreDetails("curated", hit.score);
+      return hit;
+    }) };
     const visible = new Map(this.live(f).filter((v) => (!f.project || this.inScope(v.project, f.project) || v.scope === "shared")
       && (!f.since || Date.parse(v.at) >= Date.parse(f.since)) && (f.includeSuperseded || !v.supersededBy)).map((v) => [v.id, v]));
     for (const store of this.readStores()) store.syncSearchIndex();
     const now = this.now();
-    const recency = (at: string): number => 1 / (1 + Math.max(0, now - Date.parse(at)) / (30 * 24 * 3600_000));
     const hits: SearchHit[] = [];
     // The project filter runs inside the FTS query (its rows plus shared ones), so a busy sibling project can never
     // starve this project's LIMIT.
@@ -1082,7 +1101,9 @@ export class MemoryStore {
           if (!view || seen.has(hit.ref)) continue;
           seen.add(hit.ref);
           found++;
-          hits.push({ source: "curated", score: -hit.rank * (view.tier === "long" ? 1 : 0.9) * recency(hit.at), view });
+          const selected: SearchHit = { source: "curated", score: rankedScore(hit.rank, view.tier, hit.at, now), view };
+          if (f.explain) selected.scoreDetails = rankedScoreDetails("curated", hit.rank, view.tier, hit.at, now, selected.score);
+          hits.push(selected);
         }
         if (ranked.length < page) break;
       }
@@ -1097,12 +1118,18 @@ export class MemoryStore {
       const retained = Number.isFinite(cutoff.getTime()) ? cutoff.toISOString() : undefined;
       const since = f.since && Number.isFinite(Date.parse(f.since)) ? new Date(Date.parse(f.since)).toISOString() : undefined;
       for (const { row, rank } of captureSearch(shard, q, Math.max(limit * 4, 32), since && (!retained || since > retained) ? since : retained)) {
-        hits.push({ source: "capture", score: -rank * 0.5 * recency(row.at), capture: row });
+        const selected: SearchHit = { source: "capture", score: rankedScore(rank, "capture", row.at, now), capture: row };
+        if (f.explain) selected.scoreDetails = rankedScoreDetails("capture", rank, "capture", row.at, now, selected.score);
+        hits.push(selected);
       }
     }
     // Where FTS misses entirely (a stopword-only query, a tokenization edge), the substring filter is the safety net.
     if (!hits.length && q.trim()) {
-      for (const view of this.list({ ...f, q })) hits.push({ source: "curated", score: 0, view });
+      for (const view of this.list({ ...f, q })) {
+        const hit: SearchHit = { source: "curated", score: 0, view };
+        if (f.explain) hit.scoreDetails = unrankedScoreDetails("curated", hit.score);
+        hits.push(hit);
+      }
     }
     const ref = (h: SearchHit): string => h.view?.id ?? String(h.capture?.id ?? 0).padStart(12, "0");
     hits.sort((a, b) => b.score - a.score || ref(a).localeCompare(ref(b)));

package/src/session-brief-worker.ts

@@ -50,7 +50,11 @@ if (import.meta.main) {
     if (!(HOOK_EVENTS as readonly string[]).includes(event)) stop();
     const expectedScope = hookCaptureScope(options.cwd, options.base!);
     let project: string;
-    try { project = resolveAlias(options.base!, await resolveHookProjectAsync({ cwd: options.cwd, base: options.base!, scope: expectedScope, timeRemaining: remaining, maintainCache: event !== "SessionStart" }, nativeUsage)); }
+    // Overlap the shared resolver's existing origin/metadata reads on a cold cache;
+    // serial native launches can exhaust every hook before any binding or replay is published.
+    // ponytail: cold identity must still fit one hook deadline. Revalidated durable
+    // identity progress is the upgrade if slower native reads keep exhausting that slice.
+    try { project = resolveAlias(options.base!, await resolveHookProjectAsync({ cwd: options.cwd, base: options.base!, scope: expectedScope, timeRemaining: remaining, maintainCache: event !== "SessionStart", prefetch: true }, nativeUsage)); }
     catch {
       if (expectedScope !== undefined) quarantineHookScope({ cwd: options.cwd, base: options.base!, scope: expectedScope });
       project = stop();

package/src/setup-agy.ts

@@ -0,0 +1,9 @@
+import type { ConfigImage } from "./setup-owned.ts";
+import { createJsonMcpCodec } from "./setup-json.ts";
+
+// ponytail: Antigravity setup supports strict JSON only. JSONC needs a comment-aware
+// lexical view and trailing-comma ownership before byte-preserving edits can support it.
+const codec = createJsonMcpCodec({ canonicalKey: "mcpServers", label: "Antigravity strict JSON" });
+export function readAgyMcp(image: ConfigImage): unknown { return codec.read(image); }
+export function putAgyMcp(image: ConfigImage, value: unknown): ConfigImage { return codec.put(image, value); }
+export function restoreAgyMcp(before: ConfigImage, after: ConfigImage, current: ConfigImage): ConfigImage { return codec.restore(before, after, current); }

package/src/setup-jcode.ts

@@ -0,0 +1,7 @@
+import type { ConfigImage } from "./setup-owned.ts";
+import { createJsonMcpCodec } from "./setup-json.ts";
+
+const codec = createJsonMcpCodec({ canonicalKey: "servers", aliases: ["mcpServers"], label: "Jcode" });
+export function readJcodeMcp(image: ConfigImage): unknown { return codec.read(image); }
+export function putJcodeMcp(image: ConfigImage, value: unknown): ConfigImage { return codec.put(image, value); }
+export function restoreJcodeMcp(before: ConfigImage, after: ConfigImage, current: ConfigImage): ConfigImage { return codec.restore(before, after, current); }

package/src/setup-json.ts

@@ -0,0 +1,151 @@
+import { isDeepStrictEqual } from "node:util";
+import type { ConfigImage } from "./setup-owned.ts";
+import { SETUP_CONFIG_BYTES } from "./setup-toml.ts";
+
+interface Member { key: string; keyStart: number; keyEnd: number; valueStart: number; valueEnd: number; comma?: number }
+interface ObjectSpan { close: number; members: Member[] }
+interface Document { text: string; root: ObjectSpan; container?: Member; servers?: ObjectSpan; owned?: Member }
+interface Edit { start: number; end: number; text: string }
+const decode = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true });
+const same = (a: ConfigImage, b: ConfigImage) => a.bytes === b.bytes && a.mode === b.mode;
+export interface JsonMcpCodecOptions { canonicalKey: string; aliases?: readonly string[]; label: string }
+
+/** Strict JSON only. Shared lexical edits never re-render unrelated configuration data. */
+export function createJsonMcpCodec(options: JsonMcpCodecOptions) {
+  const { canonicalKey, label } = options, keys = new Set([canonicalKey, ...(options.aliases ?? [])]);
+  const fail = (): never => { throw Error(`setup ${label} MCP configuration unavailable or ambiguous; no configuration changed`); };
+  const whitespace = (text: string, start: number) => { let at = start; while (at < text.length && /[ \t\r\n]/.test(text[at]!)) at++; return at; };
+  function stringEnd(text: string, start: number): number {
+    let at = start + 1;
+    while (at < text.length) { if (text[at] === "\\") at += 2; else if (text[at++] === '"') return at; }
+    return fail();
+  }
+  /** JSON.parse validates syntax first; this scanner retains only lexical edit boundaries. */
+  function valueEnd(text: string, start: number): number {
+    if (text[start] === '"') return stringEnd(text, start);
+    if (text[start] === "{" || text[start] === "[") {
+      let depth = 0, at = start;
+      while (at < text.length) {
+        const char = text[at]!;
+        if (char === '"') { at = stringEnd(text, at); continue; }
+        if (char === "{" || char === "[") depth++;
+        else if ((char === "}" || char === "]") && --depth === 0) return at + 1;
+        at++;
+      }
+      return fail();
+    }
+    let at = start; while (at < text.length && !/[ \t\r\n,}\]]/.test(text[at]!)) at++; return at;
+  }
+  function objectSpan(text: string, start: number): ObjectSpan {
+    if (text[start] !== "{") return fail();
+    const members: Member[] = []; let at = whitespace(text, start + 1);
+    while (text[at] !== "}") {
+      const keyStart = at, keyEnd = stringEnd(text, at), key: unknown = JSON.parse(text.slice(keyStart, keyEnd));
+      if (typeof key !== "string") return fail();
+      const valueStart = whitespace(text, whitespace(text, keyEnd) + 1), end = valueEnd(text, valueStart), next = whitespace(text, end);
+      const comma = text[next] === "," ? next : undefined;
+      members.push({ key, keyStart, keyEnd, valueStart, valueEnd: end, ...(comma === undefined ? {} : { comma }) });
+      at = comma === undefined ? next : whitespace(text, comma + 1);
+    }
+    return { close: at, members };
+  }
+  /** Only the owned value requires recursive key uniqueness; unrelated JSON stays opaque. */
+  function uniqueOwnedKeys(text: string, member: Member): void {
+    const objects: (Set<string> | null)[] = [];
+    let at = member.valueStart;
+    while (at < member.valueEnd) {
+      const char = text[at]!;
+      if (char === '"') {
+        const end = stringEnd(text, at), current = objects.at(-1);
+        if (text[whitespace(text, end)] === ":" && current) {
+          const key = JSON.parse(text.slice(at, end)) as string;
+          if (current.has(key)) return fail();
+          current.add(key);
+        }
+        at = end;
+      } else {
+        if (char === "{") objects.push(new Set());
+        else if (char === "[") objects.push(null);
+        else if (char === "}" || char === "]") objects.pop();
+        at++;
+      }
+    }
+  }
+  function document(image: ConfigImage): Document {
+    let text = "{}";
+    if (image.bytes !== null) {
+      if (image.bytes.length > Math.ceil(SETUP_CONFIG_BYTES / 3) * 4) return fail();
+      const bytes = Buffer.from(image.bytes, "base64");
+      if (bytes.toString("base64") !== image.bytes || bytes.length > SETUP_CONFIG_BYTES) return fail();
+      try { text = decode.decode(bytes); } catch { return fail(); }
+    }
+    let value: unknown; try { value = JSON.parse(text); } catch { return fail(); }
+    if (!value || typeof value !== "object" || Array.isArray(value)) return fail();
+    const root = objectSpan(text, whitespace(text, 0));
+    const containers = root.members.filter(member => keys.has(member.key));
+    if (containers.length > 1) return fail();
+    const container = containers[0]; if (!container) return { text, root };
+    const servers = objectSpan(text, container.valueStart), owned = servers.members.filter(member => member.key === "amem");
+    if (owned.length > 1) return fail();
+    if (owned[0]) uniqueOwnedKeys(text, owned[0]);
+    return { text, root, container, servers, ...(owned[0] ? { owned: owned[0] } : {}) };
+  }
+  const entry = (doc: Document): unknown => doc.owned ? JSON.parse(doc.text.slice(doc.owned.valueStart, doc.owned.valueEnd)) : undefined;
+  function readMcp(image: ConfigImage): unknown { return entry(document(image)); }
+
+  function insert(object: ObjectSpan, text: string): Edit {
+    const last = object.members.at(-1);
+    const at = last?.valueEnd ?? object.close;
+    return { start: at, end: at, text: `${last ? "," : ""}${text}` };
+  }
+  function remove(object: ObjectSpan, member: Member): Edit {
+    if (member.comma !== undefined) return { start: member.keyStart, end: member.comma + 1, text: "" };
+    const previous = object.members[object.members.indexOf(member) - 1];
+    return { start: previous?.comma ?? member.keyStart, end: member.valueEnd, text: "" };
+  }
+  function publish(image: ConfigImage, doc: Document, edits: Edit[]): ConfigImage {
+    let text = doc.text;
+    for (const edit of edits.sort((a, b) => b.start - a.start)) text = text.slice(0, edit.start) + edit.text + text.slice(edit.end);
+    if (text === doc.text) return image;
+    if (Buffer.byteLength(text) > SETUP_CONFIG_BYTES) return fail();
+    const result = { bytes: Buffer.from(text).toString("base64"), mode: image.mode };
+    document(result); return result;
+  }
+  function put(image: ConfigImage, value: unknown, options: { key?: string; keepEmpty?: boolean; rawValue?: string; emptyContainer?: string } = {}): ConfigImage {
+    const doc = document(image), edits: Edit[] = [], key = options.key ?? canonicalKey;
+    if (!doc.container) {
+      if (value === undefined && !options.keepEmpty) return image;
+      const body = value === undefined ? options.emptyContainer ?? "{}" : `{"amem":${options.rawValue ?? JSON.stringify(value)}}`;
+      edits.push(insert(doc.root, `${JSON.stringify(key)}:${body}`));
+    } else if (value === undefined && !options.keepEmpty && doc.servers!.members.every(member => member.key === "amem")) {
+      edits.push(remove(doc.root, doc.container));
+    } else {
+      if (doc.container.key !== key) edits.push({ start: doc.container.keyStart, end: doc.container.keyEnd, text: JSON.stringify(key) });
+      if (value === undefined && doc.owned) edits.push(remove(doc.servers!, doc.owned));
+      else if (value !== undefined && !isDeepStrictEqual(entry(doc), value)) {
+        const rendered = options.rawValue ?? JSON.stringify(value); if (rendered === undefined) return fail();
+        edits.push(doc.owned ? { start: doc.owned.valueStart, end: doc.owned.valueEnd, text: rendered } : insert(doc.servers!, `"amem":${rendered}`));
+      }
+    }
+    return publish(image, doc, edits);
+  }
+  /** Canonicalize only the owned container key; all unrelated bytes remain untouched. */
+  function putMcp(image: ConfigImage, value: unknown): ConfigImage { return put(image, value); }
+
+  /** Restore the owned entry (and our alias rename), preserving unrelated lexical edits. */
+  function restoreMcp(before: ConfigImage, after: ConfigImage, current: ConfigImage): ConfigImage {
+    const original = document(before), installed = document(after), live = document(current);
+    if (same(current, after)) return before;
+    if (same(current, before)) return current;
+    const previous = entry(original), expected = entry(installed), present = entry(live);
+    const previousRestored = isDeepStrictEqual(present, previous);
+    const pendingLayout = !!original.container && !!installed.container && original.container.key !== installed.container.key && live.container?.key === installed.container.key;
+    if (previousRestored && !pendingLayout) return current;
+    if (!previousRestored && !isDeepStrictEqual(present, expected)) throw Error(`setup-owned ${label} MCP entry changed; refusing to overwrite it`);
+    const restored = put(current, previous, { key: original.container?.key ?? canonicalKey, keepEmpty: !!original.container && !original.servers!.members.length,
+      ...(original.owned ? { rawValue: original.text.slice(original.owned.valueStart, original.owned.valueEnd) } : {}),
+      ...(original.container && !original.servers!.members.length ? { emptyContainer: original.text.slice(original.container.valueStart, original.container.valueEnd) } : {}) });
+    return before.bytes === null && !document(restored).root.members.length ? { bytes: null, mode: current.mode } : restored;
+  }
+  return { read: readMcp, put: putMcp, restore: restoreMcp };
+}