@timqi/pier 0.1.0 → 0.1.2

package/dist/agent/pi.js

@@ -5,26 +5,16 @@ import { realpathSync } from "node:fs";
 import { basename, dirname, join } from "node:path";
 import { createAgentSession, CredentialSynchronizationError, DefaultResourceLoader, defineTool, ModelRuntime, SessionManager, } from "@earendil-works/pi-coding-agent";
 import { inlineExtensions } from "../extensions/index.js";
-import { SESSION_TITLE_MAX } from "../limits.js";
+import { SESSION_TITLE_MAX } from "../core/types.js";
 import { logger } from "../log.js";
 import { textOf, toChatTurns, toSessionEvents, turnMetaAt, } from "./events.js";
 import { defaultAgentDir, PiConfigStore } from "./config.js";
 import { IndexedListing } from "./listing.js";
 import { curateModels, pinFirst } from "./models.js";
 const log = logger("agent");
-/** A directory is what a session is compared by — the rail groups on it, the
- *  New-session menu drops a `<repo>.<branch>` worktree when the repository
- *  itself is in the list — so two names for one directory are two projects. A
- *  session opened under `/home/qiqi` (a symlink to `/essd/qiqi`) never matched
- *  the worktrees recorded under the real path, and every branch checkout was
- *  offered as a project of its own. Resolved once per distinct path: a symlink
- *  that moves under a running instance is not a case we have.
- *
- *  A directory that is gone — a worktree merged and removed — is still a
- *  session's cwd, and its spelling still decides whether the rail reads it as a
- *  branch of its repository. So the deepest ancestor that does resolve carries
- *  the rest of the path, and only a cwd with no resolvable ancestor at all is
- *  reported as recorded. */
+/** Sessions are grouped by directory, so two names for one directory (a
+ *  symlinked home) are two projects. A directory that is gone is still a cwd:
+ *  the deepest resolvable ancestor carries the rest of the path. */
 const realPaths = new Map();
 function realPath(cwd) {
     const known = realPaths.get(cwd);
@@ -50,9 +40,6 @@ function realPath(cwd) {
     realPaths.set(cwd, real);
     return real;
 }
-/** A listed record as the seam reports it. The one mapping, because `list` and
- *  `find` answer with the same shape and drifting would mean two answers about
- *  one session. */
 const summaryOf = (s) => ({
     id: s.id,
     cwd: realPath(s.cwd),
@@ -60,49 +47,36 @@ const summaryOf = (s) => ({
     modified: s.modified,
     ...(s.title ? { title: s.title } : {}),
 });
-/** Pi's bash tool has no default timeout, so a hung command holds the turn
- * until someone aborts it — nobody is watching in a scheduled task. Kept below
- * the default task-run timeout so a stuck command comes back as
- * a tool error the agent can retry with an explicit longer timeout, instead of
- * killing the whole run. */
+/** Pi's bash tool has no default timeout, and nobody is watching a scheduled
+ *  task. Below the default task-run timeout, so a stuck command comes back as a
+ *  tool error instead of killing the run. */
 const BASH_DEFAULT_TIMEOUT_SECONDS = 600;
-/** How long a session listing stays usable: long enough that one workspace
- *  event, which several surfaces answer at once, scans disk once; short enough
- *  that a title no invalidation covers is never stale on screen. */
+/** Long enough that one workspace event, answered by several surfaces, scans
+ *  disk once; short enough that a title no invalidation covers is never stale. */
 const LIST_TTL_MS = 3_000;
-/** A probe nobody is watching is a hung page: the Console waits on this. */
 const PROVIDER_CHECK_TIMEOUT_MS = 20_000;
-/** An ordinary budget, not a token: a 1-token cap is a request no real turn
- *  ever makes, and answers about it are answers about a different request. */
+/** An ordinary budget: a 1-token cap is a request no real turn ever makes. */
 const PROVIDER_CHECK_MAX_TOKENS = 8192;
-/** Neither half of a probe is worth more than a screen. */
 const clip = (text) => text.length > 4000 ? `${text.slice(0, 4000)}\n[… ${text.length - 4000} more characters]` : text;
-/** Naming a session: one bare request on the operator's title model, after the
- *  first exchange. Each half of the exchange is cut to a few hundred
- *  characters — a title is about the subject, and the subject is in the
- *  opening lines — and the answer is a line, so the cap is a line's worth. */
+/** The subject of an exchange is in its opening lines; the answer is one line. */
 const TITLE_INPUT_CHARS = 600;
 const TITLE_MAX_TOKENS = 40;
 const TITLE_TIMEOUT_MS = 20_000;
 const TITLE_PROMPT = "Name this conversation for a session list. Reply with the title only: at most 12 Chinese characters " +
     "or 6 English words, in the language the user wrote in, no quotes, no trailing period. " +
     "A leading `[name<id> time]` on the user's message is a speaker header, not content.";
-/** A subject, not the request: the model is asked to title the exchange, and
- *  the two halves are labelled so a reply that quotes an instruction back is
- *  not mistaken for one. */
+/** The halves are labelled so a reply quoting an instruction back is not
+ *  mistaken for one. */
 const titleRequest = (first, reply) => `${TITLE_PROMPT}\n\n<user>\n${first.slice(0, TITLE_INPUT_CHARS)}\n</user>\n\n<assistant>\n${reply.slice(0, TITLE_INPUT_CHARS)}\n</assistant>`;
-/** The text of a bare completion, or the refusal it was: a provider can
- *  decline as a message rather than a throw, and only the stop reason tells
- *  that from an answer. */
+/** A provider can decline as a message rather than a throw; only the stop
+ *  reason tells that from an answer. */
 function textOfAnswer(answer) {
     if (answer.stopReason === "error" || answer.stopReason === "aborted") {
         throw new Error(answer.errorMessage ?? `the provider stopped: ${answer.stopReason}`);
     }
     return textOf(answer.content).trim();
 }
-/** What a model hands back as a title, made into one: the first line, quotes
- *  off, capped where every other title is capped. Empty is a failure, not a
- *  cleared name — the caller reports it. */
+/** Empty is a failure, not a cleared name — the caller reports it. */
 export function titleFromAnswer(text) {
     const line = text.trim().split("\n")[0]?.trim() ?? "";
     return line.replace(/^["'“‘「]+|["'”’」.。]+$/g, "").trim().slice(0, SESSION_TITLE_MAX);
@@ -130,8 +104,7 @@ These rules govern conversational replies. A human reads them on a phone-sized s
 - Destructive or irreversible actions on things you didn't create — deleting user files, force push, migrations, deploys, service restarts: ask first; unattended, don't do them and report what you would have done.
 - Say plainly when something failed, was skipped, or is unverified. Never claim a test passed without running it.`;
 export const pierSystemPrompt = (userPrompt) => userPrompt ? `${PIER_SYSTEM_PROMPT}\n\n${userPrompt}` : PIER_SYSTEM_PROMPT;
-/** Patching the call is cheaper than replacing the tool: the built-in keeps its
- * shell settings, and the agent spends no tokens deciding a timeout. */
+/** Patching the call keeps the built-in's shell settings. */
 const bashTimeoutDefault = (pi) => {
     pi.on("tool_call", (event) => {
         if (event.toolName === "bash" && event.input.timeout === undefined) {
@@ -139,12 +112,8 @@ const bashTimeoutDefault = (pi) => {
         }
     });
 };
-/**
- * A bundled extension stands down when a copy on disk already registers one of
- * its tools. Pi loads both and reports the clash as a diagnostic nobody reads,
- * leaving two tools of the same name and no way to tell which one answered;
- * the copy the user put there wins, and the journal says so (§5b).
- */
+/** Pi loads a bundled extension and its on-disk twin both, leaving two tools
+ *  of one name; the copy the user put there wins, and the journal says so (§5). */
 export const standDownShadowed = (base) => {
     const inline = (ext) => ext.path.startsWith("<inline:");
     const onDisk = new Set(base.extensions.filter((ext) => !inline(ext)).flatMap((ext) => [...ext.tools.keys()]));
@@ -161,11 +130,8 @@ export const standDownShadowed = (base) => {
         }),
     };
 };
-/**
- * A bundled skill stands down with the tool it documents. A skill's
- * description is resident in every prompt, so one pointing at a tool this
- * session was not given is both a cost and a route the agent cannot take.
- */
+/** A skill's description is resident in every prompt; one pointing at a tool
+ *  this session was not given is a route the agent cannot take. */
 export const standDownUndocumented = (tools, skills) => {
     const gone = new Set(tools.filter((tool) => tool.skill && !(tool.available?.() ?? true)).map((tool) => tool.skill));
     if (!gone.size)
@@ -179,17 +145,12 @@ export class PiSession {
     retention;
     suggestTitle;
     constructor(pi, 
-    /** Operator pins, read per call — the menu can change while we run. */
+    /** Read per call — the menu can change while we run. */
     pinned = () => [], 
-    /** "What I just wrote is not in your listing yet." The factory retains a
-     *  scan for a few seconds, which is exactly the window a rename lands in:
-     *  every surface would re-read the old title and keep it until some
-     *  unrelated event moved the list again. Same drop `create` does — a
-     *  callback only because the session is what knows it happened. */
+    /** Drops the factory's retained listing: a rename lands in exactly the
+     *  window it covers, and every surface would keep the old title. */
     wrote = () => { }, retention = { value: "long" }, 
-    /** The operator's title model asked to name a first exchange, or nothing
-     *  when auto-titling is off. Read per turn: switching it on names the next
-     *  session that finishes a first turn, without a restart. */
+    /** Read per turn: switching auto-titling on takes effect without a restart. */
     suggestTitle = () => undefined) {
         this.pi = pi;
         this.pinned = pinned;
@@ -197,11 +158,8 @@ export class PiSession {
         this.retention = retention;
         this.suggestTitle = suggestTitle;
     }
-    /** Pi's dispose unhooks the one listener that persists and emits, so a turn
-     *  started after it runs for real — model call, tools and all — and lands
-     *  nowhere: no transcript entry, no event, and a promise that resolves as if
-     *  it worked. Refusing is what turns that silence into the failure it is;
-     *  callers already report or retry a rejection (§5b). */
+    /** A turn started after Pi's dispose runs for real and lands nowhere — no
+     *  transcript, no event, a promise that resolves. Refusing makes it a failure (§5). */
     disposed = false;
     live() {
         if (this.disposed)
@@ -227,7 +185,6 @@ export class PiSession {
     async setModel(ref) {
         const m = this.pi.modelRuntime.getModel(ref.provider, ref.id);
         if (!m) {
-            // Lazy discovery: the failure itself documents what is selectable.
             const available = (await this.availableModels())
                 .slice(0, 8).map((entry) => `${entry.provider}/${entry.id}`).join(", ");
             throw new Error(`unknown model: ${ref.provider}/${ref.id}; available: ${available}`);
@@ -237,8 +194,7 @@ export class PiSession {
     async availableModels() {
         const available = await this.pi.modelRuntime.getAvailable();
         const curated = pinFirst(curateModels(available.map((m) => ({ provider: m.provider, id: m.id, reasoning: m.reasoning }))), this.pinned());
-        // The session's active model must stay selectable even when curation
-        // (or an older catalog) would hide it.
+        // The active model must stay selectable even when curation would hide it.
         const current = this.model;
         if (current && !curated.some((m) => m.provider === current.provider && m.id === current.id)) {
             curated.unshift(current);
@@ -261,22 +217,20 @@ export class PiSession {
         };
     }
     /** A system input handed to a streaming session goes into Pi's *agent*
-     *  queue, and the arrays above are the *session's* — they only ever hold
-     *  text a `prompt`/`steer`/`followUp` call queued. So a task message sitting
-     *  in front of a running turn is in neither the queue nor the transcript,
-     *  and this list is the only thing that says it exists. */
+     *  queue, which `pendingQueue` cannot see; this list is the only thing that
+     *  says it exists. */
     queuedInputs = [];
     async pendingSystemInputs() {
-        // Pi drains its follow-up queue before the turn ends, so an idle session
-        // has nothing in flight. Anything still listed was aborted or cleared, and
-        // calling that queued would leave its sender waiting on it forever (§5b).
+        // Pi drains its queue before the turn ends; anything still listed on an
+        // idle session was aborted, and calling it queued would leave its sender
+        // waiting forever (§5).
         if (!this.pi.isStreaming)
             this.queuedInputs.length = 0;
         return [...this.queuedInputs];
     }
     async clearQueue() {
-        // Not among the texts returned — a system input is nobody's draft — but
-        // dropped all the same, so its sender stops being told it is on its way.
+        // Not returned (a system input is nobody's draft), but dropped, so its
+        // sender stops being told it is on its way.
         this.queuedInputs.length = 0;
         return this.pi.clearQueue();
     }
@@ -286,8 +240,8 @@ export class PiSession {
     }
     async rewindToUserTurn(index) {
         const total = (await this.history()).filter((t) => t.role === "user").length;
-        // Anchor at the tail: branch entries keep compacted-away history that
-        // history() no longer shows, so only end-relative indices line up.
+        // Branch entries keep compacted-away history that history() no longer
+        // shows, so only end-relative indices line up.
         const back = total - index;
         const users = this.pi.sessionManager
             .getBranch()
@@ -295,27 +249,20 @@ export class PiSession {
         const target = back >= 1 ? users[users.length - back] : undefined;
         if (!target)
             throw new Error(`no user turn at index ${index}`);
-        // navigateTree on a user message moves the leaf to its parent — the old
-        // branch stays in the file but leaves the context.
+        // The old branch stays in the file but leaves the context.
         const { cancelled } = await this.pi.navigateTree(target.id);
         if (cancelled)
             throw new Error("rewind cancelled");
     }
-    /** The compaction running right now, or null. Pi keeps no lock of its own —
-     *  a second `compact()` aborts the first's turn and summarizes a transcript
-     *  that is being replaced under it — and two POSTs a millisecond apart both
-     *  pass the route's idle check, so the gate has to be here. */
+    /** Pi keeps no lock of its own: a second `compact()` summarizes a transcript
+     *  being replaced under it, and two POSTs a millisecond apart both pass the
+     *  route's idle check. */
     compacting = null;
-    /** Pi's own compaction, minus its `CompactionResult`: the numbers reach
-     *  surfaces as the `context-compacted` event the seam already emits for the
-     *  automatic one, so a caller has nothing to do with them. Refused while one
-     *  is running, rather than run twice over one context. */
     async compact() {
         this.live();
         if (this.compacting)
             throw new Error(`session ${this.pi.sessionId} is already compacting`);
-        // Started and recorded in the same tick, with no await between: that is
-        // what makes the check above a gate and not a hint.
+        // Recorded in the same tick, no await between: that is what makes the check a gate.
         const running = this.pi.compact().then(() => undefined);
         this.compacting = running;
         try {
@@ -325,48 +272,30 @@ export class PiSession {
             this.compacting = null;
         }
     }
-    /** One `session_info` entry, which Pi's own reader takes the latest of — so
-     *  a rename is an append like everything else in a transcript, and nothing
-     *  has to be rewritten. Never refused for being busy: a name has nothing to
-     *  do with the turn running.
-     *
-     *  Returns nothing, because the transcript is the answer: what the session is
-     *  called after this — the name, or the title a cleared one falls back to —
-     *  is what the next listing reads off the file, and deriving it here as well
-     *  was a second copy of a rule agent/listing.ts already owns.
-     *
-     *  TODO: renaming a cold session costs a whole resume, because the route
-     *  reaches it through `ensure` and this method needs a live Pi session to
-     *  append through. The work is one line in a file. Revisit when Pi offers a
-     *  lightweight append to a session it has not loaded. */
+    /** An append: Pi's reader takes the latest `session_info`. Never refused for
+     *  being busy. TODO: renaming a cold session costs a whole resume for one
+     *  appended line; revisit when Pi offers a lightweight append. */
     async rename(name) {
         this.live();
         this.pi.sessionManager.appendSessionInfo(name);
         this.wrote();
     }
-    /** Compaction replaces the context a turn would run against, so a dispatch
-     *  that lands mid-compaction waits for the summary instead of starting a turn
-     *  over it — the follow-up promise ("delivered when idle") without Pi's
-     *  follow-up queue, which is only drained by the *next* turn: a message
-     *  parked there while nothing is running would sit unsent, and Pi's own
-     *  `prompt()` guard would have thrown the user's message away (§5b). */
+    /** A dispatch landing mid-compaction waits for the summary instead of
+     *  starting a turn over it. Not Pi's follow-up queue: that is drained only by
+     *  the *next* turn, so a message parked there while idle would sit unsent. */
     async whenCompacted() {
         while (this.compacting)
             await this.compacting.catch(() => undefined);
     }
-    // Async, so a refusal is a rejected promise: the seam promises callers they
-    // may only `.catch()` (core/types.ts), and dispatch does exactly that.
+    // Async, so a refusal is a rejected promise the seam lets callers `.catch()`.
     async prompt(text) {
         this.live();
         await this.whenCompacted();
-        // Re-checked: the wait above is long enough for a dispose to land.
+        // The wait above is long enough for a dispose to land.
         this.live();
-        // A turn may have started since the caller read the state this prompt was
-        // decided against — two messages arriving together, or several released at
-        // once by the wait above. Bare, Pi throws that back as "already
-        // processing" and the message is gone (§5b); queued, it is the same
-        // "delivered when idle" the core's own policy picks for an auto message
-        // that lands mid-turn (core/queue.ts).
+        // A turn may have started since the caller read the state. Bare, Pi throws
+        // "already processing" and the message is gone (§5); queued, it is the
+        // same "delivered when idle" core/queue.ts picks for a mid-turn message.
         return this.pi.prompt(text, { streamingBehavior: "followUp" });
     }
     async steer(text) {
@@ -379,13 +308,10 @@ export class PiSession {
     }
     async systemInput(text, origin, mode) {
         this.live();
-        // Same gate as prompt(): an idle session takes a system input as a turn
-        // whatever the mode says, so a callback landing mid-compaction would race
-        // the summary too.
+        // Same gate as prompt(): an idle session takes a system input as a turn.
         await this.whenCompacted();
         this.live();
-        // Read here, not before the wait, and whatever the mode says: a turn is
-        // running, so the call below queues this input rather than starting one.
+        // Read after the wait: a running turn means the call below queues.
         const queued = this.pi.isStreaming;
         if (queued)
             this.queuedInputs.push(origin);
@@ -393,8 +319,7 @@ export class PiSession {
             return await this.pi.sendCustomMessage({ customType: "pier.system-input", content: text, display: true, details: origin }, { triggerTurn: true, deliverAs: mode === "prompt" ? undefined : mode });
         }
         catch (error) {
-            // Refused: nothing is in flight, and the caller is about to retry. The
-            // turn may have ended while we waited, so the entry may be gone already.
+            // Refused: nothing is in flight. The entry may be gone already.
             const at = this.queuedInputs.indexOf(origin);
             if (at >= 0)
                 this.queuedInputs.splice(at, 1);
@@ -411,9 +336,7 @@ export class PiSession {
             if (piEvent.type === "agent_end")
                 retryPending = piEvent.willRetry === true;
             if (piEvent.type === "agent_settled" && retryPending) {
-                // Aborting Pi during retry backoff produces no final agent_end, so the
-                // turn has to be ended here. The idle is not: `agent_settled` carries
-                // it through the table below like any other settle.
+                // Aborting Pi during retry backoff produces no final agent_end.
                 retryPending = false;
                 fn({ type: "turn-end", text: "", meta: this.lastTurnMeta() });
             }
@@ -424,23 +347,16 @@ export class PiSession {
             }
         });
     }
-    /** Whether naming has been decided for this session — done, started, or
-     *  never: a session that already has a name (a task's, a rename during the
-     *  turn) or more than one exchange behind it keeps what it has. Several
-     *  subscribers see every turn-end; this is what makes the request one. */
+    /** Several subscribers see every turn-end; this is what makes the request one. */
     titleDecided = false;
-    /** Name the session after its first exchange, on the operator's title model.
-     *  Off by default (settings.titleModel), in which case the title stays the
-     *  first prompt that agent/listing.ts derives. The result is a rename like
-     *  any other — an append the next listing reads — announced as `renamed` so
-     *  every surface re-lists; a failure is announced too, because a title that
-     *  silently stayed the prompt looks like the setting did nothing (§5b). */
+    /** A failure is announced too: a title that silently stayed the prompt looks
+     *  like the setting did nothing (§5). */
     autoTitle(reply, fn) {
         if (this.titleDecided)
             return;
         const suggest = this.suggestTitle();
         if (!suggest)
-            return; // off — not decided: switched on later, the next turn still counts
+            return; // off is not decided: switched on later, the next turn still counts
         this.titleDecided = true;
         if (this.pi.sessionManager.getSessionName())
             return;
@@ -449,7 +365,7 @@ export class PiSession {
         if (!first.trim())
             return;
         void suggest(first, reply).then((title) => {
-            // Named while we waited — by a person, whose word beats the model's.
+            // Named while we waited, by a person: their word beats the model's.
             if (this.disposed || this.pi.sessionManager.getSessionName())
                 return;
             this.pi.sessionManager.appendSessionInfo(title);
@@ -460,7 +376,6 @@ export class PiSession {
             fn({ type: "error", message: `session title: ${err instanceof Error ? err.message : String(err)} — the first message stays the title` });
         });
     }
-    /** Meta of the just-finished turn; live path, so "now" is the completion. */
     lastTurnMeta() {
         const messages = this.pi.messages;
         for (let i = messages.length - 1; i >= 0; i--) {
@@ -485,31 +400,16 @@ export class PiAgentFactory {
     titleModel;
     listings;
     constructor(extraTools = [], 
-    /** Appended as a virtual context file, so Pi's own prompt stays intact.
-     * Read per session, not captured once: it carries settings a user can
-     * change while the process runs, and the next session must say the new
-     * ones. */
+    /** Getters are read per session open, so a Console change reaches the next
+     *  session without a restart. Appended as a context file so the user's own
+     *  instructions still win. */
     instructions = () => "", 
-    /** Skills documenting Pier's own tools: loaded per session, never installed
-     * into the user's global or project skill directories. */
+    /** Loaded per session, never installed into the user's skill directories. */
     skillPaths = [], 
-    /** Provider credentials from pier.db instead of <agentDir>/auth.json.
-     * Optional only for bare test factories; main.ts always passes one, and
-     * every runtime built here reads and writes through it — an OAuth refresh
-     * persists to the database, never to a plaintext file. */
-    credentials, providerConfig = new PiConfigStore(), 
-    /** Operator-pinned models (Console → Settings → Models), surfaced first in
-     * every picker. A getter for the same reason `instructions` is one. */
-    pinned = () => [], 
-    /** Which bundled extensions the Console has switched on. A getter for the
-     * same reason again: the toggle takes effect on the next session open. */
-    enabledExtensions = () => [], 
-    /** The model that names a session after its first exchange (Console →
-     * Settings → Models); unset means the first prompt stays the title. A
-     * getter, read per turn end. */
-    titleModel = () => undefined, 
-    /** What exists on disk. Injected so a test can hand this factory a listing
-     * instead of a session directory and a database. */
+    /** Optional only for bare test factories; an OAuth refresh persists here,
+     *  never to a plaintext auth.json. */
+    credentials, providerConfig = new PiConfigStore(), pinned = () => [], enabledExtensions = () => [], titleModel = () => undefined, 
+    /** Injected so a test needs no session directory or database. */
     listings = new IndexedListing()) {
         this.extraTools = extraTools;
         this.instructions = instructions;
@@ -521,22 +421,16 @@ export class PiAgentFactory {
         this.titleModel = titleModel;
         this.listings = listings;
     }
-    /** One runtime for the whole process; catalogs are global, not per session. */
+    /** Catalogs are global, not per session. */
     catalog;
-    /** Where each listed session lives. A scan still stats every session file on
-     *  disk, which `resume` would pay on every cold open — web selection, an IM
-     *  message, a task run. The sidebar's own listing keeps this warm; a miss
-     *  still lists. */
+    /** A scan stats every session file, which `resume` would otherwise pay on
+     *  every cold open. */
     located = new Map();
-    /** That same scan, retained for LIST_TTL_MS instead of paid once per asking
-     *  surface — one workspace event has three (sidebar, Activity, task lookups).
-     *  Dropped on create; ids appear for reasons this factory never sees, so
-     *  a miss that decides something re-lists rather than trusts it (`resume`). */
+    /** Retained for LIST_TTL_MS; one workspace event has three asking surfaces. */
     listing;
     refreshQueue = Promise.resolve();
     builtinProviderIds;
-    /** Structural fit: CredentialStore mirrors pi-ai's interface of the same
-     * name, so the SDK accepts it without this file exporting any SDK type. */
+    /** CredentialStore mirrors pi-ai's interface structurally, so no SDK type is exported. */
     createRuntime() {
         return ModelRuntime.create(this.credentials ? { credentials: this.credentials } : {});
     }
@@ -568,8 +462,8 @@ export class PiAgentFactory {
             this.builtinIds(),
             this.providerConfig.providerStructures(),
         ]);
-        // Refresh after queued config writes settle, so runtime and structure never
-        // combine an older catalog with a newer models.json snapshot.
+        // After queued config writes settle, so runtime and structure never
+        // combine an older catalog with a newer models.json.
         const runtime = await this.refreshedRuntime();
         const stored = new Map((await runtime.listCredentials()).map((c) => [c.providerId, c.type]));
         return runtime.getProviders().map((provider) => {
@@ -601,17 +495,9 @@ export class PiAgentFactory {
             };
         });
     }
-    /**
-     * One real request on the model the operator named. `configured` only ever
-     * meant "a credential is stored", and a wrong base URL, a revoked key, a
-     * gateway rewriting the request and a model this endpoint has never heard of
-     * all look identical until a turn fails hours later.
-     *
-     * The request goes out through a fetch of our own for one reason: what a
-     * provider (or a proxy in front of it) was actually sent, and what it
-     * actually said, is the answer here — a summary of either would be Pier's
-     * word for someone else's.
-     */
+    /** A fetch of our own records what the provider (or a proxy in front of it)
+     *  was actually sent and actually said; a summary would be Pier's word for
+     *  someone else's. */
     async check(providerId, modelId) {
         const started = Date.now();
         const signal = AbortSignal.timeout(PROVIDER_CHECK_TIMEOUT_MS);
@@ -620,7 +506,7 @@ export class PiAgentFactory {
         const recorded = async (input, init) => {
             request = typeof init?.body === "string" ? init.body : "";
             const response = await globalThis.fetch(input, init);
-            // Cloned, not consumed: the SDK still needs to read the real stream.
+            // Cloned: the SDK still needs the real stream.
             body = response.clone().text().then(clip, () => "");
             return response;
         };
@@ -638,7 +524,6 @@ export class PiAgentFactory {
                 throw new Error(`unknown model: ${providerId}/${modelId}`);
             const answer = await runtime.completeSimple(model, { messages: [{ role: "user", content: "hi", timestamp: Date.now() }] }, { maxTokens: PROVIDER_CHECK_MAX_TOKENS, signal, fetch: recorded });
             const text = textOfAnswer(answer);
-            // An empty answer is still an answer; say which kind of nothing it was.
             return answered(clip(text) || `(no text; stop reason: ${answer.stopReason})`, true);
         }
         catch (err) {
@@ -650,17 +535,13 @@ export class PiAgentFactory {
                 : raw || error, false);
         }
     }
-    /** One bare completion — no session, no tools, no history — on the title
-     *  model. Rejects on anything but a usable line: the session reports it. */
     async suggestTitle(model, first, reply) {
         const runtime = await this.refreshedRuntime();
         const resolved = runtime.getModel(model.provider, model.id);
         if (!resolved)
             throw new Error(`title model ${model.provider}/${model.id} is not in the catalog`);
-        // The least reasoning the model does, said explicitly: unset means the
-        // provider's default, which on a reasoning model is not "none" (gpt-5:
-        // medium) and spends the whole output cap thinking about a title. Anthropic
-        // is the exception — its default is thinking off, and any level turns it on.
+        // Unset means the provider's default, which on gpt-5 is medium and spends
+        // the whole output cap thinking. Anthropic's default is off, and any level turns it on.
         const reasoning = resolved.reasoning && resolved.api !== "anthropic-messages" ? "minimal" : undefined;
         const answer = await runtime.completeSimple(resolved, { messages: [{ role: "user", content: titleRequest(first, reply), timestamp: Date.now() }] }, { maxTokens: TITLE_MAX_TOKENS, reasoning, signal: AbortSignal.timeout(TITLE_TIMEOUT_MS) });
         const title = titleFromAnswer(textOfAnswer(answer));
@@ -723,17 +604,11 @@ export class PiAgentFactory {
     async logout(providerId) {
         await (await this.authRuntime()).logout(providerId, { signal: AbortSignal.timeout(15_000) });
     }
-    /**
-     * Pi discovers AGENTS.md itself; we append one more, in memory, telling the
-     * agent what the surface it is talking to can render. Layered as a context
-     * file (not a systemPromptOverride) so the user's own instructions still win.
-     */
     async resourceLoader(cwd) {
         const loader = new DefaultResourceLoader({
             cwd,
-            agentDir: defaultAgentDir(), // same discovery Pi would have done itself
-            // SYSTEM.md remains user-owned: append it after Pier's replacement for
-            // Pi's generic default, preserving the user's later instruction layer.
+            agentDir: defaultAgentDir(),
+            // The user's SYSTEM.md is appended after Pier's baseline, so it still wins.
             systemPromptOverride: pierSystemPrompt,
             additionalSkillPaths: this.skillPaths,
             skillsOverride: (base) => ({
@@ -762,11 +637,8 @@ export class PiAgentFactory {
     }
     async openSnapshot(cwd, sessionManager, opts) {
         let live;
-        // Asked per open, not captured at wiring: a tool whose channel is not
-        // configured yet would otherwise cost context on every turn of every
-        // session and be able to answer nothing.
+        // Per open: an unconfigured tool would cost context on every turn and answer nothing.
         const active = this.extraTools.filter((tool) => tool.available?.() ?? true);
-        // Generic translation only — tool contracts are data owned by their feature.
         const customTools = active.map((tool) => defineTool({
             name: tool.name,
             label: tool.label,
@@ -780,8 +652,7 @@ export class PiAgentFactory {
                         content: [
                             {
                                 type: "text",
-                                // Compact, not indented: pretty-printing a nested result
-                                // costs ~20% more tokens and buys the model nothing.
+                                // Pretty-printing costs ~20% more tokens and buys the model nothing.
                                 text: JSON.stringify(await tool.execute(params, caller, signal)),
                             },
                         ],
@@ -789,25 +660,20 @@ export class PiAgentFactory {
                     };
                 }
                 catch (err) {
-                    // Pi turns this into tool-result text the model reads, which is the
-                    // right recovery and the wrong record: rethrown, but logged first.
+                    // Pi turns this into tool-result text: the right recovery, the wrong record.
                     log.warn(`tool ${tool.name} failed for ${caller}`, err);
                     throw err;
                 }
             },
         }));
-        // Locked Secrets is a refusal with a reason, here — not "provider is not
-        // configured" three calls later, and never a fall back to auth.json. Before
-        // appendSessionInfo, so the refused open writes nothing to disk.
+        // A locked store is a refusal with a reason here, not "provider not
+        // configured" later. Before appendSessionInfo, so nothing is written.
         this.credentials?.assertUnlocked();
         if (opts.name)
             sessionManager.appendSessionInfo(opts.name);
-        // This runtime serves exactly this one session, so shadowing its
-        // streamSimple is the per-session seam for the Anthropic cache TTL:
-        // interactive sessions keep "long" (1h — turns arrive minutes apart),
-        // tasks downgrade to "short" (5m) via setCacheRetention. The default sits
-        // before the spread so an explicit per-request value still wins —
-        // compaction passes cacheRetention: "none" and must keep it.
+        // This runtime serves one session, so shadowing streamSimple is the
+        // per-session seam for the cache TTL. Default before the spread: compaction
+        // passes cacheRetention: "none" and must keep it.
         const runtime = await this.createRuntime();
         const retention = { value: "long" };
         const stream = runtime.streamSimple.bind(runtime);
@@ -820,12 +686,9 @@ export class PiAgentFactory {
             resourceLoader: await this.resourceLoader(cwd),
         });
         live = created.session;
-        // Pi's queue defaults to handing over one follow-up per turn boundary, so N
-        // queued messages cost N model turns and anything behind them waits them
-        // out — 11 progress reports drained over 2.5 minutes and put a guidance
-        // message 11 minutes late (2026-09-07). The agent's own setter only flips
-        // the in-memory queue; `session.setFollowUpMode` would persist it to Pi's
-        // settings.json on every open and make it global forever.
+        // Pi defaults to one follow-up per turn boundary, so N queued messages cost
+        // N turns. The agent's setter flips only the in-memory queue;
+        // `session.setFollowUpMode` would persist it to Pi's settings.json.
         live.agent.followUpMode = "all";
         const session = new PiSession(live, this.pinned, () => {
             this.listing = undefined;
@@ -842,8 +705,7 @@ export class PiAgentFactory {
     }
     async create(opts) {
         this.listing = undefined;
-        // Resolved before Pi records it, so the transcript, the session directory
-        // and every later listing all name the directory the same way.
+        // Resolved before Pi records it, so every later listing names it the same way.
         const cwd = realPath(opts.cwd);
         return this.open(cwd, SessionManager.create(cwd), { ...opts, cwd });
     }
@@ -854,8 +716,6 @@ export class PiAgentFactory {
                 return await this.open(known.cwd, SessionManager.open(known.path));
             }
             catch (err) {
-                // The file moved or went away under us: the cache was the only thing
-                // that claimed otherwise, so drop it and take the slow, true path.
                 log.warn(`cached path for session ${sessionId} did not open; re-listing`, err);
                 this.located.delete(sessionId);
             }
@@ -865,14 +725,9 @@ export class PiAgentFactory {
             throw new Error(`unknown session: ${sessionId}`);
         return this.open(info.cwd || process.cwd(), SessionManager.open(info.path));
     }
-    /** The listed record for one id, and the one place "no such session" is
-     *  decided. A retained listing is not evidence that a session is gone: it may
-     *  have been written since — by another Pier, or by the first turn of a
-     *  session this factory opened. The miss is what earns a fresh scan, because
-     *  callers read it as permission to start a replacement session
-     *  (channels/conversations.ts), which costs a conversation its history, or as
-     *  a session that no longer exists (tasks/, web/server.ts). `reused` is how we
-     *  know a scan is owed: same entry back, same disk state. */
+    /** The one place "no such session" is decided. A retained listing is not
+     *  evidence a session is gone, and callers read a miss as permission to start
+     *  a replacement, so a miss earns a fresh scan. */
     async locate(sessionId) {
         const find = (infos) => infos.find((s) => s.id === sessionId);
         const reused = this.listing;
@@ -883,11 +738,9 @@ export class PiAgentFactory {
         const info = await this.locate(sessionId);
         return info ? summaryOf(info) : undefined;
     }
-    /** Once per process, after the first listing: agent/listing.ts reads Pi's
-     *  transcripts with a parser of its own, and only a comparison notices when
-     *  that format moves under it. */
+    /** agent/listing.ts parses Pi's transcripts itself; only a comparison
+     *  notices when that format moves under it. */
     audited = false;
-    /** Every listing goes through here, so it also refreshes `located`. */
     listed(force = false) {
         const now = Date.now();
         if (!force && this.listing && now - this.listing.at < LIST_TTL_MS)
@@ -913,9 +766,7 @@ export class PiAgentFactory {
     async list() {
         return (await this.listed()).map(summaryOf);
     }
-    /** After a listing, so a transcript that grew since the last one is indexed
-     *  before it is asked about; the listing owns the index. One that cannot
-     *  search — a test's — has nothing to say. */
+    /** After a listing, so a transcript that grew is indexed before it is asked about. */
     async search(query) {
         await this.listed();
         return this.listings.search?.(query) ?? [];