@fastagent-sh/fastagent 0.17.1 → 0.18.0

package/dist/engines/pi/models.js

@@ -4,11 +4,14 @@
  * it into the harness alongside the selected `model`; the two must come from the same collection so
  * the model's provider auth is in scope.
  */
+import { join } from "node:path";
 import { defaultProviderAuthContext } from "@earendil-works/pi-ai";
 import { builtinModels } from "@earendil-works/pi-ai/providers/all";
 import { ModelRuntime } from "@earendil-works/pi-coding-agent";
 import { fastagentCredentialStore } from "./auth.js";
+import { providerOf } from "./config.js";
 import { interactiveLoginKind } from "./login.js";
+import { AGENT_MODELS_FILE, resolveStateRoot } from "../../paths.js";
 /**
  * A `Models` with every built-in pi provider, wired to fastagent's auth: stored credentials from the
  * {@link CreatePiModelsOptions.authPath} file (via {@link fastagentCredentialStore}; the global
@@ -28,18 +31,62 @@ export function createPiModels(options = {}) {
 /**
  * The `ModelRuntime`-shaped sibling of {@link createPiModels} — the SAME hub semantics (built-in
  * providers + fastagent's credential store at `authPath`) in the type pi's session services require
- * (`createAgentSessionServices({ modelRuntime })`). Builtins only (`modelsPath: null` — pi's
- * machine-global models.json is definition-foreign) and no availability network, so the model
- * surface equals serving's. No `providers` option: `ModelRuntime` registers providers by config
- * record, not `Provider` instance — accepting the option and dropping it would be a silent no-op;
- * add the mapping when a consumer actually needs it.
+ * (`createAgentSessionServices({ modelRuntime })`). Built-ins PLUS the agent's own
+ * {@link AGENT_MODELS_FILE} when `agentDir` is given (a dir-less caller gets built-ins only), and no
+ * availability network, so the model surface equals serving's.
+ *
+ * `ModelRuntime` also takes `Provider` INSTANCES via `registerNativeProvider` (pi 0.83); the
+ * declarative file is what this rung wires because it is data that travels with the definition.
  */
-export function createPiModelRuntime(options = {}) {
-    return ModelRuntime.create({
+export async function createPiModelRuntime(options = {}) {
+    const { agentDir } = options;
+    const runtime = await ModelRuntime.create({
         credentials: fastagentCredentialStore(options.authPath, { warn: options.warn }),
-        modelsPath: null,
+        modelsPath: agentDir ? join(agentDir, AGENT_MODELS_FILE) : null,
+        // MUST be set whenever modelsPath is: pi defaults this to `<dirname(modelsPath)>/models-store.json`,
+        // which would write a generated cache INTO the author's agent dir — and `deploy` bakes the whole
+        // tree, so it would travel into the image as stale state. Machinery belongs under the state root.
+        ...(agentDir
+            ? { modelsStorePath: join(options.stateRoot ?? resolveStateRoot(agentDir), "models-store.json") }
+            : {}),
         allowModelNetwork: false,
     });
+    // A malformed models.json does NOT throw upstream — `create` resolves with the built-ins and parks the
+    // reason in getError(). Left unread, a typo'd endpoint would silently degrade to "provider not in
+    // registry" at model-resolution time, i.e. the silent fallback this codebase forbids. The upstream
+    // message already names both the reason and the file, so it is surfaced verbatim.
+    const error = runtime.getError();
+    if (error)
+        throw new Error(error);
+    for (const provider of options.providers ?? [])
+        runtime.registerNativeProvider(provider);
+    return runtime;
+}
+/**
+ * How a model's credential will REACH a deployed agent — the question `deploy` asks, which
+ * {@link probeAuthSource} cannot answer: it flattens every models.json endpoint to the display label
+ * "configured API key", so a self-hosted endpoint looks credential-less to the deploy gate even when
+ * its key is sitting in an env var.
+ *
+ * - `envVar`: an environment variable backs it, BY NAME — the shape `deploy` already understands, so
+ *   the value carries as a host secret with no extra declaration from the author.
+ * - `inDefinition`: the definition itself carries it (a literal `apiKey`, or a `!command` run on the
+ *   host). Nothing for `deploy` to carry — and nothing to gate on either, which is the point: the
+ *   `fastagent login` remedy is meaningless for a provider login cannot serve.
+ *
+ * Neither set = a stored credential or nothing at all; the existing auth.json / gate paths decide.
+ */
+export function modelCredentialCarry(runtime, spec) {
+    const status = runtime.getProviderAuthStatus(providerOf(spec));
+    if (!status.configured)
+        return { inDefinition: false };
+    // An env-var name is only useful downstream if it IS one: `"${A}_${B}"` interpolation resolves from
+    // the environment but has no single name to carry, so it falls through to the definition-carried
+    // branch, where the author's `deploy.secrets` is the mechanism.
+    if (status.source === "environment" && status.label && /^[A-Z][A-Z0-9_]*$/.test(status.label)) {
+        return { envVar: status.label, inDefinition: false };
+    }
+    return { inDefinition: status.source !== "stored" };
 }
 /**
  * Probe every provider's auth once (auth is provider-scoped, so any of its models works as the probe)

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

@@ -100,12 +100,14 @@ sessionManager) {
         // on the session in createRuntime — pi's session starts all-active), and the activation bridge
         // above rides the same turn context, so the SAME search_tools works against pi's AgentSession
         // instead of fastagent's harness.
-        const { config, modelSpec, agentDir, authPath, tools, deferredToolNames, toolCollisions, toolFailures } = await resolveAgentAssembly(cwd, options);
+        const { config, modelSpec, agentDir, authPath, stateRoot, tools, deferredToolNames, toolCollisions, toolFailures } = await resolveAgentAssembly(cwd, options);
         reportToolCollisions(toolCollisions);
         reportModuleLoadFailures(toolFailures);
         // ONE hub owns model resolution AND per-request auth — the ModelRuntime-shaped sibling of
         // serving's createPiModels; see models.ts.
-        const modelRuntime = await createPiModelRuntime({ authPath });
+        // agentDir carries the agent's own models.json (custom endpoints); stateRoot keeps pi's generated
+        // catalog cache out of the definition dir. See createPiModelRuntime.
+        const modelRuntime = await createPiModelRuntime({ authPath, agentDir, stateRoot });
         // MIGRATION HINT (deliberate breaking change): chat historically used pi's own `~/.pi` auth;
         // it now reads the agent's credential file like every other command. Probe the RESOLVED
         // model's provider through the normal resolution path (stored credential OR env var — an

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

@@ -1,7 +1,8 @@
 import type { ThinkingLevel } from "@earendil-works/pi-agent-core";
 import type { Models } from "@earendil-works/pi-ai";
 import { type AgentCommand, type SessionControl, type SessionEvent } from "../../session.ts";
-import type { Lease, SessionObserver } from "./invoke.ts";
+import type { SessionObserver } from "./invoke.ts";
+import type { Lease } from "./turn-kit.ts";
 import { type AnyModel, type PiHarnessFactory } from "./harness.ts";
 import { type PiSessionReader } from "./sessions.ts";
 /** Ceiling for one subscriber's unconsumed backlog. A consumer this far behind (a stalled remote

package/dist/engines/pi/sessions.d.ts

@@ -1,7 +1,21 @@
 import type { Session, SessionTreeEntry } from "@earendil-works/pi-agent-core";
+/**
+ * Where a NEW session starts from, when it names a parent (participant-model.md §5: "a thread starts
+ * from what the room knew"). 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.
+ */
+export interface SessionInheritance {
+    /** The session to fork from. Missing or unreadable → the new session starts empty, with a warn —
+     *  context is not the ask, and losing it must not cost the turn. */
+    parentSession: string;
+    /** Opaque markers that MAY locate the branch point on the parent's active path (searched in
+     *  message content, first hit wins, most recent occurrence). No match → the parent's present. */
+    branchHints?: string[];
+}
 /** What fastagent needs from a session backend: open-or-create by opaque id. */
 export interface PiSessionStore {
-    openOrCreate(sessionId: string): Promise<Session>;
+    openOrCreate(sessionId: string, inherit?: SessionInheritance): Promise<Session>;
 }
 /**
  * OPEN-EXISTING sibling of {@link PiSessionStore} (session-control.ts): an unknown session answers
@@ -41,4 +55,6 @@ export declare function inMemorySessionStore(): PiSessionStore & PiSessionReader
 export declare function jsonlSessionStore(options: {
     dir: string;
     cwd?: string;
+    /** Inheritance guard override (tests): parent journals above this are not forked. Default 32 MiB. */
+    forkMaxBytes?: number;
 }): PiSessionStore & PiSessionReader;

package/dist/engines/pi/sessions.js

@@ -1,14 +1,17 @@
 /**
  * Session persistence — the K-axis port and its first two backends.
  *
- * PiSessionStore is the consumer-owned port: open-or-create by opaque session id, nothing more.
- * pi's full SessionRepo surface (list/open/create/delete/fork) stays behind the adapters. The `Pi`
- * prefix is honest — `openOrCreate` returns pi's `Session`, so this is pi-coupled, not a neutral
+ * PiSessionStore is the consumer-owned port: open-or-create by opaque session id, plus one creation
+ * option — inheritance. pi's full SessionRepo surface (list/open/create/delete) stays behind the
+ * adapters; `fork` is surfaced only through {@link SessionInheritance}, never raw. The `Pi` prefix
+ * is honest — `openOrCreate` returns pi's `Session`, so this is pi-coupled, not a neutral
  * persistence contract.
  *
  * Continuity = same backing store + same session id: in-memory continuity dies with the instance;
  * jsonl survives process restarts (disk is the truth).
  */
+import { mkdir, rename, stat } from "node:fs/promises";
+import { basename, dirname, join, resolve } from "node:path";
 import { InMemorySessionRepo } from "@earendil-works/pi-agent-core";
 import { JsonlSessionRepo, NodeExecutionEnv } from "@earendil-works/pi-agent-core/node";
 import { log } from "../../log.js";
@@ -131,14 +134,227 @@ export async function activePathEntries(session) {
     }
     return path.reverse(); // walked leaf→root; every consumer reads it root→leaf
 }
+// ── Inheritance: fork-on-first-open ───────────────────────────────────────────────────────
+//
+// The mechanism behind participant-model.md §5's rule, engine-side and channel-neutral: a channel
+// only names WHERE a place branched from (scope.parentSession) and possibly at WHICH message
+// (branchHints); how much is inherited and where the boundaries sit is decided here.
+//
+// Shape: fork the parent's ACTIVE PATH up to the branch point (everything — text, images, tool
+// results — because they are session 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 (the fork is inspectable; the mark governs the window),
+// and pi's context assembly honors the mark the same as a real compaction.
+/** 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
+ *  limits govern how far the window EXTENDS into older history — the newest exchange is a FLOOR,
+ *  kept whole even when it alone exceeds the budget: the mark's boundary is entry-granular, and an
+ *  inheritance that drops the exchange the thread branched off would be no inheritance at all. */
+const INHERIT_MAX_TOKENS = 50_000;
+/** Branch hints are IDS, not payloads: each one costs a scan over the parent's serialized path, and
+ *  the wire accepts arbitrary arrays — so the engine caps them where the cost lives. */
+const MAX_BRANCH_HINTS = 16;
+const MAX_BRANCH_HINT_CHARS = 128;
+/** A vision image is priced FLAT — what a provider bills for a resized image, roughly — because its
+ *  base64 length (~1M chars for a photo) measures storage, not context: pricing it by chars would
+ *  let one photo evict the whole text window. */
+const INHERIT_IMAGE_TOKENS = 1_600;
+/** The fork reads the whole parent journal into memory; beyond this it is skipped (empty session +
+ *  warn) rather than stalling the thread's first turn. */
+const FORK_MAX_BYTES = 32 * 1024 * 1024;
+function isUserMessage(entry) {
+    return entry?.type === "message" && entry.message.role === "user";
+}
+/** 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) {
+    // AgentMessage is a role-keyed union and not every member carries `content` — read it loosely.
+    const content = message.content;
+    if (typeof content === "string")
+        return Math.ceil(content.length / 4);
+    if (!Array.isArray(content))
+        return 0;
+    let tokens = 0;
+    // Blocks are role-dependent unions; the estimate only needs `type`/`text`, so read them loosely.
+    for (const block of content) {
+        if (block.type === "image")
+            tokens += INHERIT_IMAGE_TOKENS;
+        else if (typeof block.text === "string")
+            tokens += Math.ceil(block.text.length / 4);
+        else
+            tokens += Math.ceil(JSON.stringify(block).length / 4);
+    }
+    return tokens;
+}
+function estimateEntryTokens(entry) {
+    if (entry.type !== "message")
+        return 0;
+    return estimateMessageTokens(entry.message);
+}
+/** 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")
+        return 0;
+    let tokens = Math.ceil(entry.summary.length / 4);
+    for (const message of entry.retainedTail ?? [])
+        tokens += estimateMessageTokens(message);
+    return tokens;
+}
+/**
+ * Find the fork target on the parent's active path: the LAST message whose content carries a hint
+ * (the most recent turn that talked about that message), extended forward to the end of its exchange
+ * — forking mid-exchange would inherit a question without its answer. Hints are tried in caller
+ * order; the first that matches anywhere wins. No match → undefined (the caller forks the present).
+ */
+function locateBranchPoint(path, hints) {
+    const usable = hints
+        .filter((hint) => hint.length > 0 && hint.length <= MAX_BRANCH_HINT_CHARS)
+        .slice(0, MAX_BRANCH_HINTS);
+    if (usable.length < hints.length) {
+        log.warn(`[fastagent] ignored ${hints.length - usable.length} branch hint(s) (over ${MAX_BRANCH_HINTS} hints or ${MAX_BRANCH_HINT_CHARS} chars each) — hints are message ids, not payloads`);
+    }
+    if (usable.length === 0)
+        return undefined;
+    // Serialize each message ONCE — the scan is hints × entries, and stringify must not sit in the
+    // inner loop. The whole message, not just content: shape-agnostic, and a hint is a platform id —
+    // a false positive would need the id to appear outside content, which is where ids live anyway.
+    const serialized = path.map((entry) => (entry.type === "message" ? JSON.stringify(entry.message) : ""));
+    for (const hint of usable) {
+        for (let i = path.length - 1; i >= 0; i--) {
+            if (!serialized[i]?.includes(hint))
+                continue;
+            let j = i + 1;
+            while (j < path.length && !isUserMessage(path[j]))
+                j++;
+            return path[j - 1]?.id;
+        }
+    }
+    return undefined;
+}
+/**
+ * Bound what the child's MODEL CONTEXT starts with: keep the newest exchange unconditionally, extend
+ * older while both window limits hold, and mark the boundary with a mechanical compaction entry.
+ * Entries above the parent's own last compaction are already outside model context and need no mark;
+ * a child whose visible history fits the window gets no mark at all.
+ */
+async function markInheritanceWindow(child) {
+    const path = await activePathEntries(child);
+    let scanFrom = 0;
+    for (let i = path.length - 1; i >= 0; i--) {
+        if (path[i]?.type === "compaction") {
+            scanFrom = i + 1;
+            break;
+        }
+    }
+    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 starts = [];
+    scanned.forEach((entry, i) => {
+        if (isUserMessage(entry))
+            starts.push(i);
+    });
+    if (starts.length <= 1)
+        return; // zero or one visible exchange — nothing to cut
+    const suffixTokens = new Array(scanned.length + 1).fill(0);
+    for (let i = scanned.length - 1; i >= 0; i--) {
+        const entry = scanned[i];
+        suffixTokens[i] = (suffixTokens[i + 1] ?? 0) + (entry ? estimateEntryTokens(entry) : 0);
+    }
+    let chosen = starts.length - 1;
+    for (let k = starts.length - 2; k >= 0; k--) {
+        const exchanges = starts.length - k;
+        const startIdx = starts[k];
+        if (startIdx === undefined)
+            break;
+        if (exchanges > INHERIT_MAX_EXCHANGES || baseTokens + (suffixTokens[startIdx] ?? 0) > INHERIT_MAX_TOKENS)
+            break;
+        chosen = k;
+    }
+    if (chosen === 0)
+        return; // the whole visible history fits the window
+    const boundaryIdx = starts[chosen];
+    if (boundaryIdx === undefined)
+        return;
+    const boundary = scanned[boundaryIdx];
+    if (boundary === undefined)
+        return;
+    await child.appendCompaction(`Inherited from the parent conversation; ${chosen} earlier exchange(s) are not shown.`, boundary.id, (suffixTokens[0] ?? 0) - (suffixTokens[boundaryIdx] ?? 0));
+}
+/**
+ * The create-with-parent path (the open path never reaches here) — SEMANTICS only: where to branch
+ * and what the newborn is born with. Writing and publishing it is
+ * {@link SessionBackend.createAtomically}'s contract.
+ *
+ * Every failure lands on "start empty + warn": a thread must not lose its first turn to an
+ * inheritance edge.
+ */
+async function createInheriting(backend, id, inherit, parentId, maxBytes) {
+    const startEmpty = () => backend.createAtomically(id, undefined, async () => { });
+    const parentMeta = await backend.find(parentId);
+    if (!parentMeta) {
+        log.warn(`[fastagent] session "${id}" names parent "${parentId}", which does not exist — starting empty`);
+        return startEmpty();
+    }
+    if (backend.bytes) {
+        const bytes = await backend.bytes(parentMeta).catch(() => 0);
+        if (bytes > maxBytes) {
+            log.warn(`[fastagent] parent session "${parentId}" is ${bytes} bytes (limit ${maxBytes}) — starting empty rather than stalling the first turn`);
+            return startEmpty();
+        }
+    }
+    try {
+        const parent = await backend.open(parentMeta);
+        const path = await activePathEntries(parent);
+        const leaf = path[path.length - 1];
+        if (leaf !== undefined) {
+            const hints = inherit.branchHints ?? [];
+            const at = locateBranchPoint(path, hints);
+            if (at === undefined && hints.length > 0) {
+                log.warn(`[fastagent] no branch hint matched in parent "${parentId}" — inheriting from its present instead of the branch point`);
+            }
+            // The one repair that must run before the child is visible: a mid-turn parent forks with a
+            // dangling tool call at its leaf, which would hand the provider an invalid transcript.
+            return await backend.createAtomically(id, { meta: parentMeta, atEntryId: at ?? leaf.id }, async (draft) => {
+                await reconcileInterruptedToolCalls(draft);
+                await markInheritanceWindow(draft);
+            });
+        }
+    }
+    catch (error) {
+        // Unattributed on purpose: this spans reading the parent AND writing the child, so the fault may
+        // belong to either — a torn parent journal, or a store that cannot publish.
+        log.warn(`[fastagent] could not inherit from "${parentId}" into "${id}" (${String(error)}) — starting empty`);
+    }
+    return startEmpty();
+}
 /** In-process store (pi InMemorySessionRepo). Continuity lives and dies with the instance. */
 export function inMemorySessionStore() {
     const repo = new InMemorySessionRepo();
+    const backend = {
+        find: async (id) => (await repo.list()).find((m) => m.id === id),
+        open: (m) => repo.open(m),
+        // No draft realm needed: nothing partial outlives the process, and `fill` still runs before the
+        // session reaches any caller.
+        createAtomically: async (id, from, fill) => {
+            const draft = from
+                ? await repo.fork(from.meta, { id, entryId: from.atEntryId, position: "at" })
+                : await repo.create({ id });
+            await fill(draft);
+            return draft;
+        },
+    };
     return {
-        async openOrCreate(sessionId) {
+        async openOrCreate(sessionId, inherit) {
             const existing = (await repo.list()).find((m) => m.id === sessionId);
-            if (!existing)
+            if (!existing) {
+                if (inherit)
+                    return createInheriting(backend, sessionId, inherit, inherit.parentSession, FORK_MAX_BYTES);
                 return repo.create({ id: sessionId });
+            }
             const session = await repo.open(existing);
             await reconcileInterruptedToolCalls(session);
             return session;
@@ -155,16 +371,63 @@ export function inMemorySessionStore() {
  */
 export function jsonlSessionStore(options) {
     const cwd = options.cwd ?? process.cwd();
-    const repo = new JsonlSessionRepo({ fs: new NodeExecutionEnv({ cwd }), sessionsRoot: options.dir });
+    const forkMaxBytes = options.forkMaxBytes ?? FORK_MAX_BYTES;
+    // Resolve ONCE, by pi's rule (`NodeExecutionEnv.absolutePath` is `resolve(cwd, path)`): the direct
+    // fs calls below resolve against process.cwd() instead, and a relative `dir` would straddle both.
+    const root = resolve(cwd, options.dir);
+    const repo = new JsonlSessionRepo({ fs: new NodeExecutionEnv({ cwd }), sessionsRoot: root });
+    // Where {@link SessionBackend.createAtomically} stages: a sibling root INSIDE the store root but
+    // OUTSIDE every lookup — `list({ cwd })` scans only `<root>/<encodedCwd>`, and a cwd-less `list()`
+    // scans `<root>/*/​*.jsonl`, one level, which `.drafts/<encodedCwd>/*.jsonl` sits below.
+    //
+    // A crash, or a handled failure once the draft file exists (a throw from `fill`, or from the
+    // rename), leaves it behind. Drafts are never resumed, so staleness cannot poison anything — but
+    // nothing unlinks them either.
+    const draftRepo = new JsonlSessionRepo({
+        fs: new NodeExecutionEnv({ cwd }),
+        sessionsRoot: join(root, ".drafts"),
+    });
+    const backend = {
+        find: async (id) => (await repo.list({ cwd })).find((m) => m.id === id),
+        open: (m) => repo.open(m),
+        createAtomically: async (id, from, fill) => {
+            // `fork` opens the source by its metadata's absolute path, so the draft repo reads the real
+            // repo's parent file directly while writing into its own root.
+            const draft = from
+                ? await draftRepo.fork(from.meta, { cwd, id, entryId: from.atEntryId, position: "at" })
+                : await draftRepo.create({ id, cwd });
+            await fill(draft);
+            // The interface erases the metadata generic; a jsonl draft's metadata always carries `path`.
+            const draftPath = (await draft.getMetadata()).path;
+            // `<root>/.drafts/<encodedCwd>/<file>` → `<root>/<encodedCwd>/<file>`: the draft's own
+            // parent directory NAME is pi's cwd encoding, already computed — read it back rather than
+            // re-deriving it, and rather than borrowing the parent session's path (a parentless draft has
+            // none). Same filesystem, so the rename is atomic; the real directory may not exist yet when
+            // this store has never created a session for this cwd.
+            const target = join(root, basename(dirname(draftPath)), basename(draftPath));
+            await mkdir(dirname(target), { recursive: true });
+            await rename(draftPath, target);
+            const published = (await repo.list({ cwd })).find((m) => m.path === target);
+            if (!published)
+                throw new Error(`published session vanished: ${target}`);
+            return repo.open(published);
+        },
+        bytes: async (m) => (await stat(m.path)).size,
+    };
     return {
-        async openOrCreate(sessionId) {
+        async openOrCreate(sessionId, inherit) {
             // Caller-provided ids land in jsonl FILENAMES — encode anything unsafe before it reaches disk.
             const id = encodeSessionId(sessionId);
             // Scope the lookup to this store's cwd: two stores sharing a sessionsRoot must not open each
             // other's sessions (pi groups sessions by project dir).
             const existing = (await repo.list({ cwd })).find((m) => m.id === id);
-            if (!existing)
+            if (!existing) {
+                if (inherit)
+                    return createInheriting(backend, id, inherit, encodeSessionId(inherit.parentSession), forkMaxBytes);
+                // Straight into the store, unstaged: an empty session is complete the moment its file
+                // exists, so there is no half for a reader to catch.
                 return repo.create({ id, cwd });
+            }
             const session = await repo.open(existing);
             await reconcileInterruptedToolCalls(session);
             return session;
@@ -176,7 +439,26 @@ export function jsonlSessionStore(options) {
         },
     };
 }
-/** Injective filename-safe encoding: [A-Za-z0-9._-] verbatim, the rest %-escaped. */
+/**
+ * Filename-safe encoding, INJECTIVE: `[A-Za-z0-9._-]` verbatim, everything else `%XX` (one byte) or
+ * `%uXXXX` (above it). Two different ids must never encode alike: the encoded id is what
+ * `openOrCreate` matches on, so a collision is two conversations resolving to ONE session, and —
+ * since `parentSession` comes through the same encoder — one inheriting from the wrong room. Not the
+ * same thing as a filename clash: a file is `<timestamp>_<id>.jsonl`, and identity is the `id` its
+ * metadata carries, not the name on disk.
+ *
+ * Injectivity is what the previous form lacked: it padded to a MINIMUM of two hex digits, so an
+ * escape run could be re-split — `"\u0100"` and `"\u0010" + "0"` both produced `"%100"`. Every
+ * escape now has a self-describing width, so no two inputs can produce one output. ASCII ids — every
+ * id the built-in channels mint — encode exactly as before, so existing session FILES keep their
+ * names; only non-ASCII ids (a custom `route()` could mint one) change, and those are the ones that
+ * were unsafe anyway.
+ */
 function encodeSessionId(id) {
-    return id.replace(/[^A-Za-z0-9._-]/g, (c) => `%${c.charCodeAt(0).toString(16).toUpperCase().padStart(2, "0")}`);
+    return id.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/turn-kit.d.ts

@@ -0,0 +1,56 @@
+/**
+ * The turn mechanism's pi-CLASS-neutral half, shared by every pi L0. Not "engine-neutral" in this
+ * repo's sense — that term is reserved for code with no engine import at all (src/agent.ts), and
+ * everything here speaks pi's message and image types. What it is neutral about is which pi class
+ * runs the turn.
+ *
+ *   Lease       — single-writer concurrency floor (injectable port + in-process default)
+ *   Terminals   — a settled pi message or a thrown error → the SPEC terminal, `retryable` included
+ *   EventQueue  — push→pull plumbing for engines that emit events beside their result
+ *   Prompt prep — SPEC images → pi's ImageContent
+ *
+ * What is NOT neutral — the harness's event vocabulary and its observation plane — stays in
+ * invoke.ts, and the AgentSession's in invoke-session.ts.
+ */
+import type { AssistantMessage, ImageContent } from "@earendil-works/pi-ai";
+import { type AgentEvent, type Prompt } from "../../agent.ts";
+export type Release = () => void;
+export interface Lease {
+    /** Try to acquire exclusive write access for the session (fail-fast). Returns null if held. */
+    tryAcquire(session: string): Release | null;
+}
+export declare function inProcessLease(): Lease;
+/** Classify `retryable`: structured status/code first, message prose only as the last-resort ceiling. */
+export declare function classifyRetryable(details: string, signal: {
+    status?: number;
+    code?: unknown;
+}): boolean;
+/**
+ * Terminal mapping, decided by the resolved message's stopReason: pi's prompt() resolves a message
+ * with stopReason "error"/"aborted" rather than throwing, so relying on catch alone would miss this
+ * entire failure class (violating SPEC MUST 1).
+ */
+export declare function toTerminal(message: AssistantMessage): AgentEvent;
+export declare function errorToTerminal(error: unknown): Extract<AgentEvent, {
+    type: "failed";
+}>;
+/**
+ * Map prompt images to pi ImageContent, resizing each to model-friendly dimensions/size with pi's
+ * Photon resizer (reused from pi-coding-agent, lazy-imported so the common no-image headless path never
+ * loads the TUI module graph). A null resize (unresizable / Photon unavailable) keeps the original
+ * bytes — the provider then applies its own limit.
+ */
+export declare function toPiPromptOptions(prompt: Prompt): Promise<{
+    images?: ImageContent[];
+} | undefined>;
+export declare class EventQueue<T> {
+    private buffer;
+    private wake?;
+    push(item: T): void;
+    /**
+     * Yield pushed events in order until `done` settles AND the buffer is drained. The terminal is
+     * produced separately (toTerminal); rejections of `done` are swallowed here (the caller awaits
+     * `run` itself) to avoid unhandled rejections.
+     */
+    drainUntil(done: Promise<unknown>): AsyncGenerator<T>;
+}