@fastagent-sh/fastagent 0.19.0 → 0.20.0

package/dist/engines/pi/session-inheritance.d.ts

@@ -1,4 +1,4 @@
-import { SessionManager } from "@earendil-works/pi-coding-agent";
+import type { SessionManager } from "@earendil-works/pi-coding-agent";
 /** What a Caller names when a new session should start from an existing one. */
 export interface SessionInheritance {
     /** The session to inherit from. Missing or unreadable → start empty, with a warn: context is not
@@ -19,26 +19,12 @@ export declare function inheritanceCut(parent: SessionManager, branchHints?: str
  * Copy the parent's path up to `at` into `child`, entry by entry — what a backend with no FILE to
  * fork has to do instead. Kinds pi models as facts about an entry rather than positions (labels,
  * the session name) are not copied: they describe the parent's record, not the thread's history.
- */
-export declare function copyBranchInto(parent: SessionManager, child: SessionManager, at: string): void;
-/**
- * Fork `parent` into a record named `id`, up to the branch point the hints locate, in `stagingDir`.
- *
- * Two pi calls rather than one, because neither alone does it: `createBranchedSession` copies
- * exactly the path to an entry but names the result with a generated id, and `forkFrom` takes an id
- * but copies everything. The intermediate is deleted; it exists for one call.
  *
- * STAGED, not published: the caller finishes the record (crash reconciliation) and moves it into
- * place. Publishing here and finishing after would leave a half-prepared record under the id on any
- * later failure — and the fallback path would then create a SECOND record with the same id, making
- * which one a lookup finds a matter of directory order.
- *
- * Returns undefined when inheritance cannot be honored — the caller starts the session empty.
+ * The COPY only. Bounding what the child's model sees is {@link markInheritanceWindow}, which only
+ * {@link copyBranchForInheritance} applies: a lifecycle fork that marked a window would hide the
+ * exact entries its user forked to keep.
  */
-export declare function forkForInheritance(options: {
-    parent: SessionManager;
-    id: string;
-    cwd: string;
-    stagingDir: string;
-    branchHints?: string[];
-}): SessionManager | undefined;
+export declare function copyBranchInto(parent: SessionManager, child: SessionManager, at: string): void;
+/** {@link copyBranchInto} plus the inheritance window — what a new THREAD gets and a fork does not.
+ *  Both backends call THIS one, so neither can drift on where a child's context begins. */
+export declare function copyBranchForInheritance(parent: SessionManager, child: SessionManager, at: string): void;

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

@@ -1,22 +1,5 @@
-/**
- * Where a NEW thread starts from, when it names a parent — participant-model.md §5's rule ("a thread
- * starts from what the room knew"), on pi's `SessionManager`.
- *
- * Shape: copy the parent's ACTIVE PATH up to the branch point (everything — text, images, tool
- * results — because they are entries, not prompt text), then bound what the MODEL sees with one
- * mechanical compaction mark (a plain string; zero model calls). Disk keeps the full copy — storage
- * and context are different budgets — and pi honors the mark exactly as it honors a real compaction.
- *
- * Read ONLY on the create path. An existing session ignores it entirely, which is what makes
- * inheritance one-time by construction: no marker to persist, no decision to retry per turn; the
- * session existing IS the record that the decision was taken.
- *
- * Every failure lands on "start empty + warn": a thread must not lose its first turn to an
- * inheritance edge.
- */
-import { unlinkSync } from "node:fs";
-import { SessionManager } from "@earendil-works/pi-coding-agent";
 import { log } from "../../log.js";
+import { isPlaneMarker } from "./session-markers.js";
 /** Inheritance window: at most this many exchanges of the parent reach the child's model context. */
 const INHERIT_MAX_EXCHANGES = 50;
 /** …and at most roughly this many tokens (~1/4 of a 200K context: generous, not everything). Both
@@ -37,8 +20,7 @@ function isUserMessage(entry) {
 }
 /** Rough token estimate for windowing — text at chars/4, images flat. Precision is not the point:
  *  the window is a budget, and being 20% off moves a boundary by an exchange, not correctness. */
-function estimateMessageTokens(message) {
-    const content = message.content;
+function estimateContentTokens(content) {
     if (typeof content === "string")
         return Math.ceil(content.length / 4);
     if (!Array.isArray(content))
@@ -54,17 +36,40 @@ function estimateMessageTokens(message) {
     }
     return tokens;
 }
+/** Both entry kinds pi projects into model context from a copied path: a `custom_message` is an
+ *  extension's injection INTO the conversation, so it charges the budget like any message. */
 function estimateEntryTokens(entry) {
-    return entry.type === "message" && entry.message ? estimateMessageTokens(entry.message) : 0;
+    if (entry.type === "message")
+        return estimateContentTokens(entry.message?.content);
+    if (entry.type === "custom_message")
+        return estimateContentTokens(entry.content);
+    return 0;
 }
-/** A compaction entry's summary and retained tail DO reach the model — they are the floor under
- *  every window that starts above the compaction, so the budget must count them. */
-function estimateCompactionTokens(entry) {
-    if (entry?.type !== "compaction")
+/** A compaction entry's summary AND its retained tail — the entries from `firstKeptEntryId` up to
+ *  the compaction — DO reach the model. They are the floor under every window that starts above the
+ *  compaction, so the budget must count them; the tail is read off the path, since pi-coding-agent's
+ *  SessionManager stores it as a POINTER and not as messages on the entry (0.84: `appendCompaction`
+ *  writes `firstKeptEntryId`, and both of AgentSession's compaction paths go through it).
+ *
+ *  pi-agent-core's harness writes the newer self-contained form instead — `retainedTail` on the entry,
+ *  no pointer. If pi-coding-agent adopts it the pointer stops resolving, and this function prices the
+ *  tail at zero while {@link copyBranchInto} drops it. Adopting it the way pi-agent-core did, by
+ *  REPLACING the pointer, fails to typecheck at `Entry.firstKeptEntryId` rather than running quietly;
+ *  a `retainedTail` added BESIDE the pointer would not, and is the case to watch on the next bump.
+ *  Either way this is the place to change — not a reason to read both shapes today. */
+function estimateCompactionTokens(path, compactionIdx) {
+    const compaction = path[compactionIdx];
+    if (compaction?.type !== "compaction")
         return 0;
-    let tokens = Math.ceil((entry.summary ?? "").length / 4);
-    for (const message of entry.retainedTail ?? [])
-        tokens += estimateMessageTokens(message);
+    let tokens = Math.ceil((compaction.summary ?? "").length / 4);
+    const firstKept = path.findIndex((entry) => entry.id === compaction.firstKeptEntryId);
+    if (firstKept < 0)
+        return tokens; // an unresolvable pointer keeps nothing — pi's own reading
+    for (let i = firstKept; i < compactionIdx; i++) {
+        const entry = path[i];
+        if (entry)
+            tokens += estimateEntryTokens(entry);
+    }
     return tokens;
 }
 /**
@@ -116,7 +121,7 @@ function markInheritanceWindow(child) {
     const scanned = path.slice(scanFrom);
     // The compaction's own summary + retained tail reach the model regardless of where the window
     // lands, so they charge the budget as a base cost — not estimating them would over-admit.
-    const baseTokens = estimateCompactionTokens(path[scanFrom - 1]);
+    const baseTokens = estimateCompactionTokens(path, scanFrom - 1);
     const starts = [];
     scanned.forEach((entry, i) => {
         if (isUserMessage(entry))
@@ -169,74 +174,88 @@ export function inheritanceCut(parent, branchHints) {
  * Copy the parent's path up to `at` into `child`, entry by entry — what a backend with no FILE to
  * fork has to do instead. Kinds pi models as facts about an entry rather than positions (labels,
  * the session name) are not copied: they describe the parent's record, not the thread's history.
+ *
+ * The COPY only. Bounding what the child's model sees is {@link markInheritanceWindow}, which only
+ * {@link copyBranchForInheritance} applies: a lifecycle fork that marked a window would hide the
+ * exact entries its user forked to keep.
  */
 export function copyBranchInto(parent, child, at) {
+    /** Parent entry id → the child's id for that entry: the copy mints its own, and a compaction
+     *  points BACK into the path it was appended to. */
+    const copied = new Map();
+    /** Ids of entries this copy did NOT append. A compaction's `firstKeptEntryId` routinely names one:
+     *  pi walks the cut point backwards onto the metadata entries adjacent to it, which carry no
+     *  context. They resolve to the next entry that survived — the retained tail starts there — so a
+     *  dropped anchor moves the boundary by an invisible entry instead of erasing the whole tail. */
+    let unanchored = [];
+    const record = (parentId, childId) => {
+        for (const id of unanchored)
+            copied.set(id, childId);
+        unanchored = [];
+        copied.set(parentId, childId);
+    };
     for (const raw of parent.getBranch(at)) {
         const entry = raw;
+        let childId;
         switch (entry.type) {
             case "message":
-                if (entry.message)
-                    child.appendMessage(entry.message);
+                if (entry.message) {
+                    childId = child.appendMessage(entry.message);
+                }
+                break;
+            case "custom_message":
+                // Model-visible history, unlike the `custom` entries below it: an extension injected it INTO
+                // the conversation, and the assistant messages answering it are being copied.
+                childId = child.appendCustomMessageEntry(entry.customType ?? "", entry.content, entry.display ?? false, entry.details);
                 break;
             case "compaction":
-                child.appendCompaction(entry.summary ?? "", child.getLeafId() ?? "", entry.tokensBefore ?? 0, entry.details);
+                // `firstKeptEntryId` is where the RETAINED TAIL starts — the entries pi did not summarize,
+                // which still reach the model. Translated through the copy rather than pinned to the child's
+                // leaf: pinning kept exactly ONE entry, and when that entry was a toolResult (a compaction
+                // lands wherever the turn ended) the child's first request opened with a tool result whose
+                // call had been summarized away, which every provider rejects. An id the copy never saw
+                // keeps nothing, which is what pi itself does with a pointer it cannot resolve.
+                childId = child.appendCompaction(entry.summary ?? "", copied.get(entry.firstKeptEntryId ?? "") ?? "", entry.tokensBefore ?? 0, entry.details);
                 break;
             case "model_change":
                 if (entry.provider && entry.modelId)
-                    child.appendModelChange(entry.provider, entry.modelId);
+                    childId = child.appendModelChange(entry.provider, entry.modelId);
                 break;
             case "thinking_level_change":
                 if (entry.thinkingLevel)
-                    child.appendThinkingLevelChange(entry.thinkingLevel);
+                    childId = child.appendThinkingLevelChange(entry.thinkingLevel);
                 break;
             case "custom":
-                if (entry.customType)
-                    child.appendCustomEntry(entry.customType, entry.data);
+                // The plane's markers describe the parent's RECORD, not the thread's history: a copied
+                // provenance would make a fork of a fork claim its grandparent's branch point (the
+                // idempotency check reads that value), and a copied leaf anchor would pin the child's head
+                // to a position its own history never chose. Every other custom entry is history and travels
+                // — the engine's tool-activation delta above all, since the copied assistant messages call
+                // the tools it records.
+                if (entry.customType && !isPlaneMarker(entry)) {
+                    childId = child.appendCustomEntry(entry.customType, entry.data);
+                }
                 break;
             default:
                 break; // label / session_info / branch_summary: the parent's facts, not the thread's history
         }
+        if (childId === undefined)
+            unanchored.push(entry.id);
+        else
+            record(entry.id, childId);
     }
+}
+/** {@link copyBranchInto} plus the inheritance window — what a new THREAD gets and a fork does not.
+ *  Both backends call THIS one, so neither can drift on where a child's context begins. */
+export function copyBranchForInheritance(parent, child, at) {
+    copyBranchInto(parent, child, at);
     markInheritanceWindow(child);
 }
-/**
- * Fork `parent` into a record named `id`, up to the branch point the hints locate, in `stagingDir`.
- *
- * Two pi calls rather than one, because neither alone does it: `createBranchedSession` copies
- * exactly the path to an entry but names the result with a generated id, and `forkFrom` takes an id
- * but copies everything. The intermediate is deleted; it exists for one call.
- *
- * STAGED, not published: the caller finishes the record (crash reconciliation) and moves it into
- * place. Publishing here and finishing after would leave a half-prepared record under the id on any
- * later failure — and the fallback path would then create a SECOND record with the same id, making
- * which one a lookup finds a matter of directory order.
- *
- * Returns undefined when inheritance cannot be honored — the caller starts the session empty.
+/*
+ * There is deliberately NO file-level fork here. pi can copy a path into a new file
+ * (`createBranchedSession` + `forkFrom`), but that pair writes the intermediate only when the copied
+ * path contains an ASSISTANT message — so forking at a user entry hands `forkFrom` a path that does
+ * not exist, and the failure reads as retryable for a condition no retry can change. Copying entries
+ * is what a backend with no file to fork has to do anyway, so both share these functions and one
+ * semantics; a fork is not hot enough to buy a second path back.
  */
-export function forkForInheritance(options) {
-    const { parent, id, cwd, stagingDir: dir } = options;
-    const cut = inheritanceCut(parent, options.branchHints);
-    if (!cut)
-        return undefined;
-    let branched;
-    try {
-        branched = parent.createBranchedSession(cut.at);
-        if (!branched)
-            return undefined; // a non-persisting parent has no file to fork from
-        const child = SessionManager.forkFrom(branched, cwd, dir, { id });
-        markInheritanceWindow(child);
-        return child;
-    }
-    finally {
-        if (branched) {
-            try {
-                unlinkSync(branched);
-            }
-            catch (error) {
-                // The intermediate is inert (it is never listed as this store's record), so a failed
-                // cleanup costs a stray file, not correctness — but silence would hide a full disk.
-                log.warn(`[fastagent] could not remove the intermediate fork ${branched}: ${String(error)}`);
-            }
-        }
-    }
-}

package/dist/engines/pi/session-markers.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Which journal entries are POSITIONS and which are the control plane's own bookkeeping.
+ *
+ * pi's journal has one shape for everything, so the plane writes what it needs to remember into the
+ * same log the conversation lives in: what fork a record is, and the anchor that makes a leaf move
+ * survive a reopen. Both the record store and the history copier have to agree on which is which —
+ * one publishes and navigates, the other copies — and a disagreement is invisible until a fork comes
+ * back missing something. Hence one module, imported by both, depending on neither.
+ */
+import type { SessionManager } from "@earendil-works/pi-coding-agent";
+/** What pins a leaf move to disk. pi's `branch()` writes nothing — the leaf is runtime state, and
+ *  `open()` puts it back on the file's last entry — so a move that no other write follows is
+ *  forgotten. Carries no data: its PARENT is the position, which is the whole point of appending it. */
+export declare const LEAF_ANCHOR = "fastagent.leaf";
+/**
+ * The CONTROL PLANE's bookkeeping — not a place in a conversation, so never published, never
+ * navigable, and never copied by a fork: these describe THIS record, not the history it holds.
+ *
+ * An EXACT list, not a `fastagent` prefix. The prefix was tried and was wrong for one entry, at a
+ * cost worth remembering: `fastagent:tool-activation` is written by the ENGINE and is thread history
+ * (which deferred tools this conversation discovered), so matching it here dropped it from every
+ * fork and every inherited thread — while the assistant messages that call those tools came along.
+ * A new marker joins this list deliberately, which is the point of it being a list.
+ */
+export declare function isPlaneMarker(entry: {
+    type?: string;
+    customType?: string;
+}): boolean;
+/** Every position a client may move the branch head to, and everything `entries()` publishes — ONE
+ *  predicate, so "anything published is navigable" holds by construction. `label` is metadata ABOUT
+ *  an entry rather than a place; {@link isPlaneMarker} is ours rather than the conversation's. */
+export declare function isNavigable(entry: {
+    type?: string;
+    customType?: string;
+}): boolean;
+/**
+ * The head a client SEES: the last publishable entry on the active path.
+ *
+ * Not pi's leaf, which may be a marker — a solo leaf move anchors itself with one — so reporting
+ * pi's answer would hand back an id the client did not ask for and cannot find in `entries()`.
+ */
+export declare function publishedLeaf(record: SessionManager): string | undefined;
+/** Stamp a fresh fork with where it came from. */
+export declare function stampProvenance(record: SessionManager, provenance: string): void;
+/** What fork this record IS, or undefined for a record that was not forked. The LAST stamp wins — a
+ *  fork of a fork carries its own — and the whole journal is read rather than the active path, so a
+ *  later leaf move cannot make a fork stop being one. */
+export declare function forkProvenance(record: SessionManager): string | undefined;

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

@@ -0,0 +1,59 @@
+/** "This record is a fork of X at Y." Its own entry rather than pi's header `parentSession`, which
+ *  pi fills from its own fork path and names a FILE, not the branch point idempotency needs. */
+const FORK_PROVENANCE = "fastagent.fork";
+/** What pins a leaf move to disk. pi's `branch()` writes nothing — the leaf is runtime state, and
+ *  `open()` puts it back on the file's last entry — so a move that no other write follows is
+ *  forgotten. Carries no data: its PARENT is the position, which is the whole point of appending it. */
+export const LEAF_ANCHOR = "fastagent.leaf";
+/**
+ * The CONTROL PLANE's bookkeeping — not a place in a conversation, so never published, never
+ * navigable, and never copied by a fork: these describe THIS record, not the history it holds.
+ *
+ * An EXACT list, not a `fastagent` prefix. The prefix was tried and was wrong for one entry, at a
+ * cost worth remembering: `fastagent:tool-activation` is written by the ENGINE and is thread history
+ * (which deferred tools this conversation discovered), so matching it here dropped it from every
+ * fork and every inherited thread — while the assistant messages that call those tools came along.
+ * A new marker joins this list deliberately, which is the point of it being a list.
+ */
+export function isPlaneMarker(entry) {
+    return entry.type === "custom" && (entry.customType === FORK_PROVENANCE || entry.customType === LEAF_ANCHOR);
+}
+/** Every position a client may move the branch head to, and everything `entries()` publishes — ONE
+ *  predicate, so "anything published is navigable" holds by construction. `label` is metadata ABOUT
+ *  an entry rather than a place; {@link isPlaneMarker} is ours rather than the conversation's. */
+export function isNavigable(entry) {
+    return entry.type !== "label" && !isPlaneMarker(entry);
+}
+/**
+ * The head a client SEES: the last publishable entry on the active path.
+ *
+ * Not pi's leaf, which may be a marker — a solo leaf move anchors itself with one — so reporting
+ * pi's answer would hand back an id the client did not ask for and cannot find in `entries()`.
+ */
+export function publishedLeaf(record) {
+    const path = record.getBranch();
+    for (let i = path.length - 1; i >= 0; i--) {
+        const entry = path[i];
+        if (entry && isNavigable(entry))
+            return entry.id;
+    }
+    return undefined;
+}
+/** Stamp a fresh fork with where it came from. */
+export function stampProvenance(record, provenance) {
+    record.appendCustomEntry(FORK_PROVENANCE, { provenance });
+}
+/** What fork this record IS, or undefined for a record that was not forked. The LAST stamp wins — a
+ *  fork of a fork carries its own — and the whole journal is read rather than the active path, so a
+ *  later leaf move cannot make a fork stop being one. */
+export function forkProvenance(record) {
+    let found;
+    for (const raw of record.getEntries()) {
+        if (raw.type !== "custom" || raw.customType !== FORK_PROVENANCE)
+            continue;
+        const value = raw.data?.provenance;
+        if (typeof value === "string")
+            found = value;
+    }
+    return found;
+}

package/dist/engines/pi/session-settings.d.ts

@@ -1,7 +1,7 @@
 /**
  * What a session is SET TO, and what it may be set to. Model and thinking level are ONE setting —
  * which levels exist is a property of the model — so they resolve together, here, and `state()`, the
- * `set_thinking` gate and the per-invoke binding all read this rather than deriving their own.
+ * `update({ thinkingLevel })` gate and the per-invoke binding all read this rather than deriving their own.
  *
  * Read-only by design. The durable record may hold a level the current model cannot do; that record
  * is the user's PREFERENCE, so resolving per read restores it when the session returns to a capable
@@ -33,7 +33,7 @@ export interface SessionSettings {
     model: AnyModel;
     /** Already clamped to what {@link model} supports. */
     thinkingLevel: ThinkingLevel;
-    /** What `set_thinking` accepts for this session. */
+    /** What `update({ thinkingLevel })` accepts for this session. */
     availableThinkingLevels: string[];
     /** Recorded but not honored — only the execution path reports it (as a warn). */
     dropped?: {
@@ -52,7 +52,7 @@ export declare function resolveSessionSettings(entries: OverrideEntryLike[], mod
 }): SessionSettings;
 /**
  * The entries on the session's ACTIVE path, root→leaf — what every last-wins settings read walks.
- * `getBranch()` is exactly that walk: the journal can hold abandoned branches after a `navigate`,
+ * `getBranch()` is exactly that walk: the journal can hold abandoned branches after a leaf move,
  * and reading it flat would run the session on a setting it moved away from.
  *
  * A chain that is not intact THROWS. `getBranch()` stops where a parent is missing and answers the
@@ -60,4 +60,4 @@ export declare function resolveSessionSettings(entries: OverrideEntryLike[], mod
  * turn silently on assembly defaults. The caller decides what to do with the fault (state() reports
  * the settings as absent, dispatch answers with a code); what it must not do is guess.
  */
-export declare function activePath(record: SessionManager): OverrideEntryLike[];
+export declare function activePath(record: SessionManager, from?: string): OverrideEntryLike[];

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

@@ -1,7 +1,8 @@
 import { clampThinkingLevel, getSupportedThinkingLevels } from "@earendil-works/pi-ai";
 /** Which strings are levels at all — the vocabulary. What a MODEL supports is
  *  `getSupportedThinkingLevels`. The `satisfies` anchor keeps this exhaustive against pi's union: a
- *  level pi adds becomes a type error here rather than a value `set_thinking` silently rejects. */
+ *  level pi adds becomes a type error here rather than a value `update({ thinkingLevel })` silently
+ *  rejects. */
 const ALL_THINKING_LEVELS = {
     off: true,
     minimal: true,
@@ -73,7 +74,7 @@ export function resolveSessionSettings(entries, models, defaults) {
 }
 /**
  * The entries on the session's ACTIVE path, root→leaf — what every last-wins settings read walks.
- * `getBranch()` is exactly that walk: the journal can hold abandoned branches after a `navigate`,
+ * `getBranch()` is exactly that walk: the journal can hold abandoned branches after a leaf move,
  * and reading it flat would run the session on a setting it moved away from.
  *
  * A chain that is not intact THROWS. `getBranch()` stops where a parent is missing and answers the
@@ -81,8 +82,10 @@ export function resolveSessionSettings(entries, models, defaults) {
  * turn silently on assembly defaults. The caller decides what to do with the fault (state() reports
  * the settings as absent, dispatch answers with a code); what it must not do is guess.
  */
-export function activePath(record) {
-    const path = record.getBranch();
+export function activePath(record, from) {
+    // `from` asks a different question: the path a leaf move is ABOUT to make active, which a caller
+    // validating a patch needs before the move exists. Absent, it is the session's current path.
+    const path = record.getBranch(from);
     const root = path[0];
     if (root?.parentId != null) {
         throw new Error(`session entry "${root.parentId}" is missing from the journal (parent of "${root.id}")`);

package/dist/engines/pi/session-store.d.ts

@@ -1,13 +1,75 @@
 import { SessionManager } from "@earendil-works/pi-coding-agent";
+import type { SessionSummary, SessionUpdateField } from "../../session.ts";
+import { type OverrideEntryLike } from "./session-settings.ts";
 import { type SessionInheritance } from "./session-inheritance.ts";
-/** What the AgentSession L0 needs from a session backend: open-or-create by opaque id, plus the one
- *  creation option — where a NEW session starts from (session-inheritance.ts). */
+/**
+ * The session RECORDS, as operations rather than as pi handles.
+ *
+ * The distinction is the point. `openOrCreate`/`openIfExists` hand out a live `SessionManager` for
+ * the two things that genuinely need one — driving a turn, and reading a session's contents — and
+ * everything else is a whole-record operation implemented HERE. That line was drawn after the
+ * lifecycle work: when the control plane wrote properties by calling pi's append methods itself, it
+ * had to know pi's rules to do it (every append advances the single leaf pointer, so order decides
+ * where a fork's head lands; `appendSessionInfo` rewrites the name it is given; a record buffers in
+ * memory until its first assistant message). Every caller learning those separately is how the same
+ * fact ended up half-known in two modules — so they are known once, here.
+ */
 export interface PiSessionRecordStore {
     openOrCreate(sessionId: string, inherit?: SessionInheritance): Promise<SessionManager>;
     /** OPEN-EXISTING sibling: an unknown session answers undefined, never creates one — sessions are
-     *  the data plane's monopoly. This is what the control plane reads and writes boundary records
-     *  through, so a mutation on an unknown id is rejected rather than minted into a ghost record. */
+     *  the data plane's monopoly. The READ path (state/entries) and the turn binding use this; the
+     *  write path does not, because a caller holding a handle is a caller learning pi's rules. */
     openIfExists(sessionId: string): Promise<SessionManager | undefined>;
+    /**
+     * Write session properties, in the order pi's leaf pointer requires, and report what LANDED.
+     *
+     * Each property is its own journal entry — pi has no "append these together" — so a failure
+     * partway is a real state, and this answers it rather than pretending a rollback happened. The
+     * caller supplies an already-VALIDATED patch (a model resolved to provider+id, a level this model
+     * accepts): what belongs here is how a record is written, not what a value means.
+     *
+     * `undefined` = no such record (it vanished between the caller's check and this call).
+     */
+    applyProperties(sessionId: string, writes: PropertyWrites): Promise<AppliedProperties | undefined>;
+    /** Every record this store holds, in CALLER ids. Rejects when the store cannot be enumerated —
+     *  `[]` means "no sessions", so it must not double as "could not look". Answers the CONTRACT's row
+     *  type: the hub forwards it, and a second identical shape here would only be a thing to keep in
+     *  sync. */
+    list(): Promise<SessionSummary[]>;
+    /** Copy `from`'s history up to entry `at` into a new record named `into`, stamped with `provenance`
+     *  so a repeat of the SAME fork can be recognised as one ({@link forkProvenance}) instead of
+     *  becoming a second record or an overwrite. Throws on any failure: a half-copied fork is never
+     *  left in place, and the caller turns the throw into a coded result. */
+    fork(from: string, at: string, into: string, provenance: string): Promise<void>;
+    /** Destroy a record. `false` = there was none (the caller answers `no_such_session`). */
+    delete(sessionId: string): Promise<boolean>;
+}
+/** A validated property patch, in the shape a RECORD takes it: the model already resolved to the
+ *  provider + id pi's append wants, so this layer never asks what a model spec means. */
+export interface PropertyWrites {
+    name?: string;
+    model?: {
+        provider: string;
+        id: string;
+    };
+    thinkingLevel?: string;
+    leafEntryId?: string;
+}
+/** What a property write actually did, and what the record holds after it. */
+interface AppliedProperties {
+    /** In write order. A field asked for but absent here did not land. */
+    landed: SessionUpdateField[];
+    /** Why the rest stopped, if anything did. The caller turns this into a coded result; the record
+     *  already reflects `landed`. */
+    failure?: unknown;
+    /** The record AFTER the writes — what the caller reports, rather than echoing the request. pi
+     *  rewrites a name (newlines collapse, ends trim), so the request is not what was stored. */
+    name?: string;
+    leafEntryId?: string;
+    /** The active path after the writes, for a caller that resolves settings against a model registry
+     *  this layer has no business knowing. Absent when the chain cannot be walked — the caller decides
+     *  what an unreadable chain means (design §7); it is never silently a short path. */
+    path?: OverrideEntryLike[];
 }
 /**
  * A Caller's session id, as a name pi will accept.
@@ -32,24 +94,31 @@ export interface PiSessionRecordStore {
  * tell which room a file belongs to.
  */
 export declare function piSessionId(sessionId: string): string;
+/**
+ * {@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 declare function callerSessionId(recordId: string): string | undefined;
 /**
  * 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.
+ * 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}).
  *
  * 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.
  *
- * 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.
+ * A PRE-EXISTING record is continued in place: 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. Nothing on disk
+ * is rewritten.
  *
  * 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
@@ -68,3 +137,4 @@ export declare function piSessionRecordStore(options: {
 export declare function piInMemorySessionRecordStore(options?: {
     cwd?: string;
 }): PiSessionRecordStore;
+export {};