@fastagent-sh/fastagent 0.19.0 → 0.21.0

package/dist/engines/pi/session-store.js

@@ -1,16 +1,14 @@
 /**
  * Session persistence for the `AgentSession` L0 — open-or-create a durable record by the Caller's
  * opaque session id, on pi-coding-agent's `SessionManager` (the v3 jsonl every pi surface reads).
- *
- * Records written before this store existed (by the pi-agent-core `Session` the serving path used
- * to run on) are the same v3 jsonl and are continued in place — see `legacySessionId`. That is a
- * READ path for existing conversations, not a second engine.
  */
-import { existsSync, mkdirSync, renameSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, readdirSync, renameSync, rmSync, writeFileSync } from "node:fs";
 import { basename, dirname, join, resolve } from "node:path";
 import { SessionManager } from "@earendil-works/pi-coding-agent";
 import { log } from "../../log.js";
-import { copyBranchInto, forkForInheritance, inheritanceCut } from "./session-inheritance.js";
+import { LEAF_ANCHOR, publishedLeaf, stampProvenance } from "./session-markers.js";
+import { activePath } from "./session-settings.js";
+import { copyBranchForInheritance, copyBranchInto, inheritanceCut, } from "./session-inheritance.js";
 /**
  * A Caller's session id, as a name pi will accept.
  *
@@ -25,10 +23,10 @@ import { copyBranchInto, forkForInheritance, inheritanceCut } from "./session-in
  * produce one output. `_` escapes itself for the same reason. A trailing `.` or `-` is legal
  * mid-name but not at the end, so it escapes too.
  *
- * Injective within this encoding — which is only sufficient because new records live in their own
- * directory. The older spelling draws names from the same character set (it stored a room literally
- * called `s42` as `s42`, which is also this encoding of `42`), so one directory would make some
- * names ambiguous no matter how either side spells them.
+ * Injective within this encoding — which is only sufficient because this store's records live in
+ * their own directory. A name this store did not write draws from the same character set and can
+ * still decode: a file called `s42` is also this encoding of `42`, so one directory would make some
+ * names ambiguous no matter how this side spells them.
  *
  * Readability is deliberate: `-1001234567890` becomes `s-1001234567890`, so an operator can still
  * tell which room a file belongs to.
@@ -43,33 +41,55 @@ export function piSessionId(sessionId) {
     const body = sessionId.replace(/[^A-Za-z0-9.-]/g, hex).replace(/[.-]$/, hex);
     return `s${body}`;
 }
+/**
+ * {@link piSessionId} backwards — what `list()` needs, because a session id belongs to the CALLER and
+ * a record name is storage detail. The encoding is self-describing (fixed widths, `_` escapes
+ * itself), so this is a decode rather than a guess; a name this store did not write (no `s` head, a
+ * truncated escape) answers undefined and is left out of the listing rather than reported under a
+ * name nobody can dial.
+ */
+export function callerSessionId(recordId) {
+    if (!recordId.startsWith("s"))
+        return undefined;
+    let out = "";
+    for (let i = 1; i < recordId.length; i++) {
+        const c = recordId[i];
+        if (c !== "_") {
+            out += c;
+            continue;
+        }
+        const wide = recordId[i + 1] === "u";
+        const start = i + (wide ? 2 : 1);
+        const width = wide ? 4 : 2;
+        const hex = recordId.slice(start, start + width);
+        if (hex.length !== width || !/^[0-9A-F]+$/.test(hex))
+            return undefined;
+        out += String.fromCharCode(Number.parseInt(hex, 16));
+        i = start + width - 1;
+    }
+    return out;
+}
 /**
  * Disk-backed store under `dir`: restart the process, conversations continue.
  *
- * Lookup is a directory scan (`SessionManager.list`) because pi names files `<timestamp>_<id>.jsonl`
- * and the timestamp is not ours to predict — the same trade sessions.ts makes today.
- *
- * A record written before this store existed keeps ITS id (the older path spelled them differently),
- * so the scan accepts either: a conversation that predates this store is continued rather than
- * silently restarted as an empty one. Nothing is rewritten on disk.
- *
- * NEW records live in a subdirectory of their own, because the two engines cannot share a namespace:
- * both spell ids into `[A-Za-z0-9._-]`, so neither can claim a prefix the other cannot produce, and
- * a directory holding both would have names that belong to two conversations at once — in whichever
- * direction it is read. Separate directories make each side's own injectivity sufficient.
+ * Lookup is a directory scan of THIS store's own directory, reading ids out of the filenames pi
+ * writes (`<timestamp>_<id>.jsonl`) — not `SessionManager.list`, which filters by the cwd recorded in
+ * each header and would make a renamed agent directory look like an empty store (see
+ * {@link recordFiles}).
  *
- * A PRE-EXISTING record is still continued in place: it is looked up by the older spelling, which is
- * injective on its own terms, and appended to where it lies. Both spellings are the same v3 jsonl,
- * so a conversation started before this store keeps going rather than restarting empty.
+ * Records live in a subdirectory of their own, because a name this store did not write can still
+ * decode to a Caller id: a file called `s42` beside them is also this encoding of `42`, so a shared
+ * directory would answer `42` with a record it does not own. Only this directory is scanned, which
+ * makes this encoding's own injectivity sufficient — a record written before this store existed
+ * lies outside it and is never read.
  *
  * SCOPE OF "open-or-create": idempotent against a store that is serialized per session, which is what
  * the serving path provides — the single-writer lease is taken before any store call, so no two
  * turns of one conversation reach this at once. What it does NOT do is arbitrate a FIRST open racing
  * across processes: two instances that scan before either writes will both create, and the
- * conversation forks into two records. sessions.ts states the same boundary for the same reason
- * ("the serving path serializes it with the single-writer lease before reaching any store"), and a
- * horizontally-scaled deployment that wants more owes a lease that spans its instances — an
- * in-process one cannot arbitrate between them, and a file lock here would only look like it could.
+ * conversation forks into two records. A horizontally-scaled deployment that wants more owes a lease
+ * that spans its instances — an in-process one cannot arbitrate between them, and a file lock here
+ * would only look like it could.
  */
 export function piSessionRecordStore(options) {
     const cwd = options.cwd ?? process.cwd();
@@ -80,74 +100,359 @@ export function piSessionRecordStore(options) {
     /** Where a forked record is finished before it becomes discoverable. A SUBDIRECTORY of the store,
      *  so `list()` (one level, `*.jsonl`) never sees a record that is still being prepared. */
     const staging = join(own, ".staging");
+    /** An empty record under `id`, ON DISK (see {@link materialize}) and not yet discoverable. Copying
+     *  into it appends immediately, so a crash leaves a partial record in staging rather than a
+     *  complete-looking one under the id. */
+    const stage = (id) => {
+        mkdirSync(staging, { recursive: true });
+        return materialize(SessionManager.create(cwd, staging, { id }), staging);
+    };
+    /** Fill a staged record and move it in — or leave nothing behind. The partial file is deleted on
+     *  the way out and the failure is rethrown untouched: `fork` turns it into a coded result and
+     *  inheritance falls back to an empty session, but neither can see `.staging`, which would
+     *  otherwise accumulate a file per failed attempt (ENOSPC being the realistic repeat offender) in
+     *  a directory nothing ever reads. */
+    const fillStaged = (id, fill) => {
+        const staged = stage(id);
+        // WHERE the record is, so cleanup deletes the file that exists rather than the path it used to
+        // have: after the rename, removing the staging path succeeds against nothing while the record it
+        // was supposed to undo sits in the store.
+        let published;
+        try {
+            fill(staged);
+            // Publishing is a mkdir + rename, and both can fail (EACCES, a store root on another
+            // filesystem) — a finished record stranded in staging is the same accumulation as a partial
+            // one. NOT covered by a test: the tests reach a fill failure by making a copy throw, and there
+            // is no equivalent injection point for rename without mocking node:fs for the whole file.
+            published = publishStaged(staged);
+            return SessionManager.open(published, own);
+        }
+        catch (error) {
+            rmSync(published ?? staged.getSessionFile() ?? "", { force: true });
+            throw error;
+        }
+    };
+    /** Move a finished record into the store: one same-filesystem rename, so a reader sees the whole
+     *  thing or nothing at all. Answers WHERE it landed — the caller opens it, and can undo it. */
+    const publishStaged = (staged) => {
+        const file = staged.getSessionFile();
+        if (!file)
+            throw new Error(`staged record ${staged.getSessionId()} has no file to publish`);
+        mkdirSync(own, { recursive: true });
+        const target = join(own, basename(file));
+        renameSync(file, target);
+        return target;
+    };
     /** Fork the named parent into `id`, or answer undefined so the caller starts empty. Every failure
      *  is a warn: a thread must not lose its first turn to an inheritance edge. */
-    const inheritInto = async (id, inherit) => {
-        const parentId = piSessionId(inherit.parentSession);
-        const found = (await SessionManager.list(cwd, own)).find((r) => r.id === parentId) ??
-            (await SessionManager.list(cwd, root)).find((r) => r.id === legacySessionId(inherit.parentSession));
+    const inheritInto = async (sessionId, inherit) => {
+        const found = locate(inherit.parentSession);
         if (!found) {
-            log.warn(`[fastagent] session "${id}" names parent "${inherit.parentSession}", which has no record — starting empty`);
+            log.warn(`[fastagent] session "${sessionId}" names parent "${inherit.parentSession}", which has no record — starting empty`);
             return undefined;
         }
         try {
-            const parentDir = found.id === parentId ? own : root;
-            mkdirSync(staging, { recursive: true });
-            const staged = forkForInheritance({
-                // A parent that crashed mid tool-execution would otherwise pass its dangling tool_use down
-                // to the child, whose very first request the provider then rejects.
-                parent: reconcileInterruptedToolCalls(SessionManager.open(found.path, parentDir)),
-                id,
-                cwd,
-                stagingDir: staging,
-                branchHints: inherit.branchHints,
-            });
-            if (!staged)
+            // A parent that crashed mid tool-execution would otherwise pass its dangling tool_use down
+            // to the child, whose very first request the provider then rejects.
+            const parent = reconcileInterruptedToolCalls(SessionManager.open(found.path, found.dir));
+            const cut = inheritanceCut(parent, inherit.branchHints);
+            if (!cut)
                 return undefined;
-            // Publish only once the record is complete: same-filesystem rename, so a reader sees the whole
-            // thing or nothing at all.
-            const stagedFile = staged.getSessionFile();
-            if (!stagedFile)
-                return staged; // non-persisting backend: nothing to publish
-            const target = join(own, basename(stagedFile));
-            renameSync(stagedFile, target);
-            return SessionManager.open(target, own);
+            return fillStaged(piSessionId(sessionId), (staged) => copyBranchForInheritance(parent, staged, cut.at));
         }
         catch (error) {
             // Unattributed on purpose: this spans reading the parent AND writing the child.
-            log.warn(`[fastagent] could not inherit from "${inherit.parentSession}" into "${id}" (${String(error)}) — starting empty`);
+            log.warn(`[fastagent] could not inherit from "${inherit.parentSession}" into "${sessionId}" (${String(error)}) — starting empty`);
             return undefined;
         }
     };
+    /** The unreadable records the last listing reported, so a polled endpoint states the condition
+     *  once rather than once a second. */
+    let lastUnreadable = "";
+    /** WHERE a session's record is — the one lookup every caller shares, so a fix to it (this store's
+     *  own directory rather than pi's cwd-filtered listing) cannot reach three of the four. */
+    const locate = (sessionId) => {
+        const mine = recordFiles(own).find((f) => f.id === piSessionId(sessionId));
+        return mine ? { path: mine.path, dir: own } : undefined;
+    };
+    /** Open an existing record, or undefined. A closure rather than a method call, so `fork` cannot be
+     *  broken by a caller that spreads this object into another one. */
+    const openExisting = async (sessionId) => {
+        const found = locate(sessionId);
+        return found ? SessionManager.open(found.path, found.dir) : undefined;
+    };
     return {
         async openOrCreate(sessionId, inherit) {
-            const id = piSessionId(sessionId);
-            const mine = (await SessionManager.list(cwd, own)).find((r) => r.id === id);
-            if (mine)
-                return reconcileInterruptedToolCalls(SessionManager.open(mine.path, own));
-            const legacy = (await SessionManager.list(cwd, root)).find((r) => r.id === legacySessionId(sessionId));
-            if (legacy)
-                return reconcileInterruptedToolCalls(SessionManager.open(legacy.path, root));
+            const found = locate(sessionId);
+            if (found)
+                return reconcileInterruptedToolCalls(SessionManager.open(found.path, found.dir));
             mkdirSync(own, { recursive: true });
             // Inheritance is a CREATE-path decision: an existing session above ignores it entirely, which
             // is what makes it one-time by construction.
             if (inherit) {
-                const inherited = await inheritInto(id, inherit);
+                const inherited = await inheritInto(sessionId, inherit);
                 if (inherited)
                     return inherited;
             }
-            return publish(SessionManager.create(cwd, own, { id }), own);
+            // The CALLER's id in every message above; pi's spelling only where pi names the file.
+            return materialize(SessionManager.create(cwd, own, { id: piSessionId(sessionId) }), own);
         },
-        async openIfExists(sessionId) {
-            const id = piSessionId(sessionId);
-            const mine = (await SessionManager.list(cwd, own)).find((r) => r.id === id);
-            if (mine)
-                return SessionManager.open(mine.path, own);
-            const legacy = (await SessionManager.list(cwd, root)).find((r) => r.id === legacySessionId(sessionId));
-            return legacy ? SessionManager.open(legacy.path, root) : undefined;
+        openIfExists: openExisting,
+        applyProperties: (sessionId, writes) => applyProperties(() => openExisting(sessionId), writes),
+        async list() {
+            const files = recordFiles(own);
+            const rows = [];
+            const unreadable = [];
+            for (const file of files) {
+                // A name this store did not write cannot be decoded back to a Caller id, and a row nobody
+                // can dial is worse than a row that is missing.
+                const session = callerSessionId(file.id);
+                if (!session)
+                    continue;
+                try {
+                    rows.push(summarize(session, SessionManager.open(file.path, own)));
+                }
+                catch (error) {
+                    // ONE unreadable record must not take the listing down — the other conversations are fine,
+                    // and a GUI that shows nothing is worse than one missing a row. But it must not vanish
+                    // silently either: that is the same conflation `sessions_unavailable` prevents one level
+                    // up, just per record. Named, with its reason, every time it is polled: a record that
+                    // cannot be read is a condition someone has to act on.
+                    unreadable.push(`${basename(file.path)} (${String(error)})`);
+                }
+                // A TURN for everything else. Reading a record is synchronous (pi parses the whole file and
+                // builds its index), and this endpoint is POLLED — so without a yield the process stops for
+                // the length of the whole listing, once a second, while SSE heartbeats and in-flight turns
+                // wait. pi's own listing streamed and interleaved; this reads faster and must not take that
+                // away.
+                await new Promise((resolve) => setImmediate(resolve));
+            }
+            // NEWEST ACTIVITY first. The filenames sort by CREATION, so an old conversation that just
+            // received a message would otherwise sit below a newer idle one — the wrong answer for the
+            // column a conversation list is read by.
+            rows.sort((a, b) => b.updatedAt - a.updatedAt);
+            // Said when the SET changes, not on every poll: this endpoint is polled once a second or so,
+            // and an unreadable record stays unreadable until someone acts on it.
+            const reported = unreadable.join("; ");
+            if (reported !== lastUnreadable) {
+                lastUnreadable = reported;
+                if (unreadable.length > 0) {
+                    log.warn(`[fastagent] ${unreadable.length} of ${files.length} session records in ${own} could not be read and are missing from this listing: ${reported}`);
+                }
+            }
+            return rows;
+        },
+        async fork(from, at, into, provenance) {
+            const parent = await openExisting(from);
+            if (!parent)
+                throw new Error(`session "${from}" has no record`);
+            // The port promises a NEW record, so the guarantee belongs here rather than in the one caller
+            // that happens to check: two records under one id makes which one a lookup finds a matter of
+            // directory order.
+            if (await openExisting(into))
+                throw new Error(`session "${into}" already exists`);
+            fillStaged(piSessionId(into), (staged) => {
+                // METADATA FIRST, history last. pi has one leaf pointer and every append advances it, so
+                // whatever is written last becomes the fork's `leafEntryId` — and a client opening a fresh
+                // fork would find its head on an empty `custom` record instead of on the exchange it forked
+                // at. The name and the provenance describe the record; the history is what the session IS.
+                const name = parent.getSessionName();
+                // The name travels: a fork of "Deploy notes" that lists as untitled is a row a user cannot
+                // place. A client that wants "(copy)" calls `update({ name })`.
+                if (name)
+                    staged.appendSessionInfo(name);
+                stampProvenance(staged, provenance);
+                // NOT reconciled: the repair appends at the parent's LEAF, which a copy stopping at `at` can
+                // never reach — it would only write to the record being copied FROM. The child is reconciled
+                // on its own first open, like every other record.
+                copyBranchInto(parent, staged, at);
+            });
+        },
+        async delete(sessionId) {
+            const found = locate(sessionId);
+            if (!found)
+                return false;
+            // A record that cannot be deleted must not report success — the caller turns the throw into a
+            // coded failure, and the session is still there for the next attempt.
+            rmSync(found.path);
+            return true;
         },
     };
 }
+/**
+ * The property write, for both backends: the ONE place that knows how pi records a property.
+ *
+ * ORDER IS THE POINT. pi has a single leaf pointer and every append advances it, so the leaf ends up
+ * wherever the last write landed — which is why the move goes FIRST (the properties below it must
+ * hang off the branch the caller asked for, not the one it left) and why a fork writes its metadata
+ * before its history (session-store's `fork`). The handle is opened HERE, inside the caller's lease:
+ * one taken earlier could be a snapshot of a run that finished in the window, and appending to it
+ * would hang the property off a stale leaf.
+ */
+async function applyProperties(open, writes) {
+    const record = await open();
+    if (!record)
+        return undefined;
+    const landed = [];
+    let moved = false;
+    let failure;
+    try {
+        if (writes.leafEntryId !== undefined) {
+            // A move to where the head ALREADY is asks for nothing: a client retry, or a UI firing on
+            // every selection, must not grow the session. Compared against the PUBLISHED head, because
+            // pi's leaf may be the anchor a previous move left there.
+            if (publishedLeaf(record) !== writes.leafEntryId) {
+                record.branch(writes.leafEntryId);
+                moved = true;
+            }
+            landed.push("leafEntryId");
+        }
+        if (writes.model) {
+            record.appendModelChange(writes.model.provider, writes.model.id);
+            landed.push("model");
+        }
+        if (writes.thinkingLevel !== undefined) {
+            record.appendThinkingLevelChange(writes.thinkingLevel);
+            landed.push("thinkingLevel");
+        }
+        if (writes.name !== undefined) {
+            record.appendSessionInfo(writes.name);
+            landed.push("name");
+        }
+    }
+    catch (error) {
+        // Held, not rethrown: what already landed still has to be reported, and the report is the only
+        // way a caller learns the record moved.
+        failure = error;
+    }
+    // THE ANCHOR, outside the try so a failed property write cannot skip it — that is precisely the
+    // case reporting a MOVE as landed. pi's `branch()` writes nothing (the leaf is runtime state, and
+    // `open()` puts it back on the file's last entry), so a move nothing followed is forgotten the
+    // moment anything reopens the record. Appending anything pins it; this appends only when nothing
+    // else in the patch already did.
+    if (moved && record.getLeafId() === writes.leafEntryId) {
+        try {
+            record.appendCustomEntry(LEAF_ANCHOR, {});
+        }
+        catch (error) {
+            // The move is runtime-only and will not survive the next open, so it did NOT land: saying it
+            // did is the one thing a partial report cannot afford. A first failure keeps its place — it is
+            // what stopped the patch — and this one is reported when nothing else went wrong.
+            landed.splice(landed.indexOf("leafEntryId"), 1);
+            failure ??= error;
+        }
+    }
+    // READ BACK, never echo: pi rewrites a name (newlines collapse, ends trim), and the settings a
+    // path resolves to can change under a moved leaf. The caller reports THIS, so `state()` and
+    // `list()` cannot disagree with what it said.
+    const name = record.getSessionName();
+    // The PUBLISHED head, not pi's: the anchor above is ours, and a client must be told the position
+    // it asked for — the one it can find in `entries()`.
+    const leafEntryId = publishedLeaf(record);
+    let path;
+    try {
+        path = activePath(record);
+    }
+    catch (error) {
+        // An unreadable chain is the caller's decision (design §7), not a silent short path. The writes
+        // are already durable either way.
+        log.warn(`[fastagent] session ${record.getSessionId()}: written, active path unreadable: ${String(error)}`);
+    }
+    return {
+        landed,
+        ...(failure !== undefined ? { failure } : {}),
+        ...(name ? { name } : {}),
+        ...(leafEntryId ? { leafEntryId } : {}),
+        ...(path ? { path } : {}),
+    };
+}
+/**
+ * The record files in a directory, newest first — pi names them `<ISO timestamp>_<id>.jsonl`, so the
+ * name sorts by time and carries the id without opening anything.
+ *
+ * OUR readdir, not pi's `SessionManager.list`, and the difference is the reason this exists: that one
+ * filters by the cwd recorded in each header — right for a TUI showing "this project's sessions",
+ * wrong for a repository, where renaming the agent directory made every conversation vanish from the
+ * listing AND from lookup, so the next turn started an empty session on top of the old one. It also
+ * swallows per-file faults, which a listing needs to see.
+ *
+ * ENOENT is the one condition that is not a fault: a store nobody has written to holds no records.
+ * Anything else — an unreadable ancestor, a file where the directory should be — travels with its
+ * code, because "this deployment has no conversations" is not an answer for a store we cannot read.
+ */
+function recordFiles(dir) {
+    let names;
+    try {
+        names = readdirSync(dir);
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            throw error;
+        return [];
+    }
+    // UNORDERED. Lookup does not care, and `list()` sorts its rows by activity — a filename order kept
+    // here would be one nobody consumes and the next reader has to prove is unused.
+    return names
+        .filter((name) => name.endsWith(RECORD_SUFFIX))
+        .flatMap((name) => {
+        // The FIRST underscore: the timestamp holds none, and an encoded id may hold several
+        // (`piSessionId` escapes with `_`).
+        const cut = name.indexOf("_");
+        return cut < 0 ? [] : [{ path: join(dir, name), id: name.slice(cut + 1, -RECORD_SUFFIX.length) }];
+    });
+}
+/** One record as a conversation-list row. Read out of the record itself rather than from pi's
+ *  listing, which is not asked for one — so the fields mean exactly what they say: no sentinel
+ *  standing in for "no first message", and `updatedAt` floored at the record's own creation (a
+ *  fork's entries carry the SOURCE's timestamps, so a branch made today would otherwise sort into
+ *  whenever the original was written — the one column a conversation list orders by). */
+function summarize(session, record) {
+    const entries = record.getEntries();
+    const createdAt = Date.parse(record.getHeader()?.timestamp ?? "") || 0;
+    // `|| 0` on both: an unparseable timestamp is NaN, and NaN in `updatedAt` serializes to `null` —
+    // which the contract types as a number and a client sorts by.
+    const lastAt = Date.parse(entries.at(-1)?.timestamp ?? "") || 0;
+    const messages = entries.filter((e) => e.type === "message");
+    const name = record.getSessionName();
+    const preview = firstUserText(messages);
+    return {
+        session,
+        ...(name ? { name } : {}),
+        createdAt,
+        updatedAt: Math.max(lastAt, createdAt),
+        messageCount: messages.length,
+        ...(preview ? { preview } : {}),
+    };
+}
+/** The first user message with text in it, truncated by CODE POINT (a cut through a surrogate pair
+ *  would put a lone half in the row, which renders as U+FFFD). A session opened with a caption-less
+ *  photo has none, and answers undefined — a row without a preview, not a row claiming one. */
+function firstUserText(messages) {
+    for (const entry of messages) {
+        const message = entry.message;
+        if (message?.role !== "user")
+            continue;
+        const content = message.content;
+        const text = typeof content === "string"
+            ? content
+            : Array.isArray(content)
+                ? content
+                    .filter((block) => block.type === "text")
+                    .map((block) => block.text ?? "")
+                    .join(" ")
+                : "";
+        // Cut to UTF-16 units FIRST: a pasted megabyte would otherwise become a million-element array
+        // on the way to keeping 200 of them. Two units per code point is the ceiling, so this cannot
+        // take fewer characters than the slice below wants.
+        if (text.trim())
+            return [...text.slice(0, PREVIEW_CHARS * 2)].slice(0, PREVIEW_CHARS).join("");
+    }
+    return undefined;
+}
+/** What pi names a record file. */
+const RECORD_SUFFIX = ".jsonl";
+/** How much of the first message a list row carries. A row, not a transcript. */
+const PREVIEW_CHARS = 200;
 /**
  * Crash-safety reconciliation, run on every OPEN of an existing record.
  *
@@ -226,7 +531,7 @@ function reconcileInterruptedToolCalls(record) {
     }
     return record;
 }
-/** Where this engine's own records live, under the sessions directory both engines are pointed at. */
+/** Where the records live, under the sessions directory the store is pointed at. */
 const OWN_RECORDS_DIR = "agent-session";
 /**
  * Make a NEW record exist on disk before anyone can act on it.
@@ -243,7 +548,7 @@ const OWN_RECORDS_DIR = "agent-session";
  * Writing pi's OWN header (`getHeader()`, not a hand-built literal) and reopening puts the manager
  * on its normal "file exists" path, where every append lands immediately.
  */
-function publish(session, dir) {
+function materialize(session, dir) {
     const file = session.getSessionFile();
     if (!file || existsSync(file))
         return session; // in-memory, or already on disk
@@ -283,7 +588,7 @@ export function piInMemorySessionRecordStore(options = {}) {
                     const staged = fresh();
                     const cut = inheritanceCut(reconcileInterruptedToolCalls(parent), inherit.branchHints);
                     if (cut)
-                        copyBranchInto(parent, staged, cut.at);
+                        copyBranchForInheritance(parent, staged, cut.at);
                     created = staged;
                 }
                 catch (error) {
@@ -300,14 +605,40 @@ export function piInMemorySessionRecordStore(options = {}) {
         async openIfExists(sessionId) {
             return live.get(sessionId);
         },
+        applyProperties: (sessionId, writes) => applyProperties(async () => live.get(sessionId), writes),
+        async list() {
+            // The SAME row builder the disk store uses, ordered the same way: a backend difference here is
+            // one an embedder discovers as a missing field (this one had no `preview` for exactly that
+            // reason). Nothing to read from disk, so nothing can be unreadable.
+            return [...live].map(([session, record]) => summarize(session, record)).sort((a, b) => b.updatedAt - a.updatedAt);
+        },
+        async fork(from, at, into, provenance) {
+            const parent = live.get(from);
+            if (!parent)
+                throw new Error(`session "${from}" has no record`);
+            // The port's promise, not the caller's: registering over a live session would replace its
+            // history outright.
+            if (live.has(into))
+                throw new Error(`session "${into}" already exists`);
+            // Entry-by-entry, like the in-memory inheritance path: there is no file to fork. Registered
+            // only once complete, so a failure leaves no half-copied session behind. NO inheritance
+            // window: this is the same user keeping their own history, not a new thread bounded from a
+            // parent's.
+            const staged = SessionManager.inMemory(cwd, { id: piSessionId(into) });
+            // METADATA FIRST, history last — the same order the disk store writes in, and for the same
+            // reason: pi has one leaf pointer, so whatever is appended last is where a client opening this
+            // fork finds its head. That should be the exchange it was forked at, not a metadata record.
+            // The name travels so a fork of "Deploy notes" is not an untitled row a user cannot place; a
+            // client that wants "(copy)" calls `update({ name })`.
+            const name = parent.getSessionName();
+            if (name)
+                staged.appendSessionInfo(name);
+            stampProvenance(staged, provenance);
+            copyBranchInto(parent, staged, at);
+            live.set(into, staged);
+        },
+        async delete(sessionId) {
+            return live.delete(sessionId);
+        },
     };
 }
-/** The spelling used before this store existed — read-only, so older records still resolve. */
-function legacySessionId(sessionId) {
-    return sessionId.replace(/[^A-Za-z0-9._-]/g, (c) => {
-        const code = c.charCodeAt(0);
-        return code < 0x100
-            ? `%${code.toString(16).toUpperCase().padStart(2, "0")}`
-            : `%u${code.toString(16).toUpperCase().padStart(4, "0")}`;
-    });
-}

package/dist/engines/pi/tool-context.d.ts

@@ -4,8 +4,7 @@
  * closures. Deploy-time ambients a tool closes over at build time do NOT belong here.
  */
 import { AsyncLocalStorage } from "node:async_hooks";
-import type { SessionEntry as PiSessionEntry } from "@earendil-works/pi-coding-agent";
-import type { AgentSession } from "@earendil-works/pi-coding-agent";
+import type { SessionEntry as PiSessionEntry, AgentSession } from "@earendil-works/pi-coding-agent";
 /** FastAgent's read-only port over the current conversation manager. Serving and chat adapt their
  * different concrete session implementations to this one tool-runtime contract. */
 export interface ReadonlySessionManager {
@@ -42,21 +41,35 @@ export interface ToolActivation {
         description: string;
     }>;
     /** ADDITIVE activation. Unknown names are filtered out before reaching pi (whose `setActiveTools`
-     *  THROWS on them); resolves the names actually newly activated (already-active names don't repeat). */
-    activate(names: string[]): Promise<string[]>;
+     *  THROWS on them); answers the names actually newly activated (already-active names don't repeat).
+     *
+     *  SYNCHRONOUS, and that is the contract, not an implementation detail: read-modify-write against
+     *  pi's active set cannot be interleaved as long as no caller can await inside it. An async
+     *  signature would need a lock to say the same thing, and the lock is what a previous version had
+     *  — one rebuilt per tool call, so the parallel batch it existed for never met on it. If pi's
+     *  setters ever become async, this signature is where that breaks, loudly. */
+    activate(names: string[]): string[];
 }
+/**
+ * The activation bridge over a live pi session — the ONE implementation, for both consumers.
+ *
+ * Serving (`agent-session-factory.ts`) and chat (`session-builder.ts`) had a copy each, identical
+ * but for the persistence line; the neighbouring `definitionResourceLoaderOptions` exists because
+ * that exact duplication drifted once before. The difference is a PARAMETER now: `onActivated` is
+ * what a served session uses to record the delta that carries the discovery into its next turn,
+ * and chat has nowhere to put one (pi's SessionContext has no active-tool set).
+ *
+ * Bind it to the SESSION, never to a tool call: the next call has to see what this one activated.
+ */
+export declare function sessionToolActivation(session: AgentSession, onActivated?: (added: string[]) => void): ToolActivation;
 export interface TurnContext {
     /** Working directory for this execution. Falls back to process.cwd() only for an unbound direct call. */
     cwd?: string;
     /** Current conversation manager. Absent outside a FastAgent-managed agent turn. */
     sessionManager?: ReadonlySessionManager;
-    /** Tool activation for the current turn. Two producers, one consumer surface: invoke.ts bridges the
-     *  served session; chat.ts bridges the resident one (chat emulates deferral — same loader, same
-     *  semantics). Absent only outside any turn (a bare `fastagent tool` run). */
+    /** Tool activation for the current turn. Two producers, one consumer surface: agent-session-factory.ts
+     *  bridges the served session; session-builder.ts bridges the resident one (chat emulates deferral —
+     *  same loader, same semantics). Absent only outside any turn (a bare `fastagent tool` run). */
     tools?: ToolActivation;
 }
 export declare const turnContext: AsyncLocalStorage<TurnContext>;
-/** The additive-activation contract, in ONE place for both bridges (the served session,
- *  chat.ts over pi's AgentSession): dedupe → keep registered names only (pi's setters THROW on
- *  unknown) → exclude already-active → the names to actually add (empty = nothing to set). */
-export declare function additiveActivation(registered: string[], current: string[], names: string[]): string[];