@timqi/pier 0.1.14 → 0.2.0

package/README.md

@@ -9,9 +9,9 @@ something is worth showing.
 One instance, one account, your own machine. The agent runs shell commands in
 directories you name — meant for a machine you own, not a shared host.
 
-**Status: pre-release.** The version is `0.0.x`; the database schema is
-versioned from `0.0.1` on. Read `docs/deploy.md` before putting it anywhere
-reachable.
+**Status: pre-release.** Releases may still change behaviour and the
+database schema between versions; schema upgrades are one-way. Read
+`docs/deploy.md` before putting it anywhere reachable.
 
 ## Requirements
 
@@ -30,15 +30,35 @@ pier serve
 
 It listens on `127.0.0.1:3141` (`PORT`, `HOST`) and keeps everything under
 `~/.pier` (`PIER_HOME`): one SQLite database, the boards it serves, the
-`master.key` that seals stored credentials, and the Pi runtime with its
-session transcripts (`~/.pier/pi`, unless `PI_CODING_AGENT_DIR` says
-otherwise).
+`master.key` that seals stored credentials, the conversation's memory
+(`~/.pier/home`), and the Pi runtime with its session transcripts
+(`~/.pier/pi`, unless `PI_CODING_AGENT_DIR` says otherwise).
 
 **The first start generates a password and prints it once.** Lost it?
 `sqlite3 ~/.pier/db/pier.db 'DELETE FROM auth'` and restart. Open
-`http://localhost:3141`, sign in; **Console → Settings** configures Models,
-Agent, Channels, Vault, the public URL, password and master key; **New session**
-picks the directory the agent's shell runs in.
+`http://localhost:3141`, sign in; **Console → Settings** has Models, Agent,
+Channels, Vault, Tasks, Boards, Instance (public URL, accent, notifications,
+reload) and Security (master key, password, passkeys, signed-in devices).
+
+## How the conversation works
+
+The web chat is one conversation, Pier. Its current session answers,
+remembers and dispatches; it runs in `~/.pier/home`, which holds
+memory only: `MEMORY.md` (one-line facts) and daily notes in
+`memory/YYYY-MM-DD.md`.
+
+- Real work is delegated with `pier task run`: a worker for a small task, a
+  lead for a feature, which designs with you or builds with its own workers.
+  Each is its own session; its result comes back to Pier as a callback.
+- After an idle hour, or past 60K tokens, the next message starts a fresh
+  session, seeded with the memory, the open items, recent runs and the last
+  exchanges. The old transcripts stay readable.
+- `/status` lists what is open, `/new` starts a fresh session now, `/stop` stops
+  the reply in progress, `/skills` lists the skills. `%` works in place of
+  `/` (`%status`), because Slack's client eats an unregistered `/`.
+- One IM DM, on Lark or Slack, can be the conversation: Console → Settings →
+  Channels, the DM's row, "This DM is the conversation". Pier then
+  answers there, from the phone; other chats keep one session per thread.
 
 ## Configure Pi
 
@@ -58,14 +78,15 @@ Console → Settings:
 - **Models** — endpoints, API-key/OAuth login, pinned models. Credentials are
   sealed in Pier's SQLite database, never written back to `models.json`.
   **Test** sends one real request and shows the body as sent and the reply.
-- **Agent** — edits `SYSTEM.md`, `AGENTS.md`, `settings.json` and the
-  `models.json` structure, globally or per project scope (with that project's
-  `.pi/skills` and `.pi/extensions` listed). Changes apply when a session next
-  opens; saving recycles idle sessions; **Settings → Instance → Reload** does
-  the same for files changed elsewhere. Also here: Pier's own skills
-  (`pier web search|fetch` reaches the web through the provider's hosted
-  tools — Anthropic or OpenAI, no key of your own) and the
-  managed CLI tools (`rtk`, `rg`, `fd`, `wt`, `jq`, or your own as a
+- **Agent** — edits `SYSTEM.md`, `AGENTS.md` and the `models.json`
+  structure, globally or per project scope (with that project's
+  `.pi/skills` and `.pi/extensions` listed); `settings.json` is Pier's and
+  shown read-only. Changes apply when a session next opens; saving recycles
+  idle sessions; **Settings → Instance → Reload** does the same for files
+  changed elsewhere. Also here: packages (Pi's registry, **Add package**),
+  Pier's own skills as the built-in `pier` package (`pier web search|fetch`
+  reaches the web through the provider's hosted tools — Anthropic or OpenAI,
+  no key of your own), **Browse files**, and the managed CLI tools (`rtk`, `rg`, `fd`, `wt`, `jq`, or your own as a
   [ubix](https://github.com/timqi/ubix) block), installed into
   `~/.pier/tools/bin`, first on every session's PATH beside the `pier` shim
   Pier writes there at start.
@@ -79,7 +100,7 @@ store and renamed `auth.json.imported`; literal keys in `models.json` likewise
 (`models.json.imported`). The editor rejects plaintext keys or header values.
 Pi's provider environment variables are inherited from the Pier process; a
 systemd service does not inherit your shell, so put non-secret settings in a
-unit override and API keys in the Providers UI.
+unit override and API keys in Settings → Models.
 
 ## Run it as a service
 
@@ -118,8 +139,9 @@ npm test          # vitest
 
 ## Releases
 
-Pier asks `registry.npmjs.org` at boot and every 30 minutes; the footer version
-becomes `v0.0.1 → 0.0.2` when a release is out and opens a panel: source link,
+Pier asks `registry.npmjs.org` at boot and every 30 minutes; the version in
+the Settings header turns into a badge when a release is out (`Pier <version>
+is out`) and opens a panel: source link,
 **Update now**, **Update automatically** (idle instance only). Both drain first
 and hand the install to the updater unit; off systemd the panel says `pier
 update`. The updater writes `~/.pier/db/backups/pier.db.release-<version>.bak`
@@ -128,10 +150,10 @@ update`. The updater writes `~/.pier/db/backups/pier.db.release-<version>.bak`
 
 `main` is the only development line. `just release [patch|minor|major]` checks,
 tags and pushes; the tag builds and publishes to npm and a GitHub Release. The
-footer version is `package.json`'s.
+version shown is `package.json`'s.
 
 ## License
 
 [AGPL-3.0-only](LICENSE). Run it, change it, deploy it. If you offer a modified
 Pier to other people over a network, they are entitled to your source — the
-version in the footer links to this repository for exactly that reason.
+version in the Settings header links to this repository for exactly that reason.

package/dist/agent/config.js

@@ -4,7 +4,8 @@
 import { randomUUID } from "node:crypto";
 import { promises as fs } from "node:fs";
 import { join } from "node:path";
-import { isProviderApi, isThinkingLevel, validateEndpoint, validateProviderSetup } from "../core/types.js";
+import { isThinkingLevel } from "../core/types.js";
+import { isProviderApi, SNAPSHOT_FILES, validateEndpoint, validateProviderSetup } from "./types.js";
 import { pierPath } from "../paths.js";
 import { mergeSnapshotProviders, normalizeAgentSnapshot, snapshotProviders } from "./config-sync.js";
 const GLOBAL_FILES = ["SYSTEM.md", "AGENTS.md", "settings.json", "models.json"];
@@ -13,7 +14,6 @@ const PROJECT_FILES = ["AGENTS.md"];
 // go through writeDefaults, and are the only fields a snapshot carries. The
 // Console shows the file and never edits it; the rest of it is machine-local.
 const READONLY_FILES = ["settings.json"];
-const SNAPSHOT_FILES = ["SYSTEM.md", "AGENTS.md", "models.json", "settings.json"];
 /** What a first boot writes (docs/deploy.md says why each key): the list the
  *  Console installs into, Pi's attribution headers off — a server is not a
  *  person to survey — and a retry budget of minutes, because an unattended

package/dist/agent/events.js

@@ -1,7 +1,7 @@
 // Pure Pi-event → SessionEventPayload translation. Structurally typed: no Pi
 // imports, so it is unit-testable without Pi and Pi types never leak past the
 // seam. The golden table in events.test.ts is the mapping's spec.
-import { isThinkingLevel, MAX_STEP_OUTPUT } from "../core/types.js";
+import { isChatCommand, isThinkingLevel, MAX_STEP_OUTPUT } from "../core/types.js";
 /** An assistant message that calls a tool is work in progress, not a reply. */
 export const hasToolCalls = (message) => Array.isArray(message?.content) && message.content.some((part) => part.type === "toolCall");
 export function textOf(content) {
@@ -20,14 +20,36 @@ function systemOrigin(message) {
     const value = message.details;
     if (!value || typeof value !== "object")
         return null;
-    const { source: raw, ...origin } = value;
+    const { source: raw, cwd, ...origin } = value;
+    if (origin.kind === "session-seed") {
+        const { reason, previousSessionId } = origin;
+        return (reason === "first" || reason === "idle" || reason === "lost" || reason === "full" || reason === "new") &&
+            (previousSessionId === null || typeof previousSessionId === "string")
+            ? { kind: "session-seed", reason, previousSessionId }
+            : null;
+    }
+    if (origin.kind === "chat-command") {
+        const { command, sessions } = origin;
+        if (!isChatCommand(command))
+            return null;
+        // A malformed map costs the card its links, not the card.
+        const links = sessions && typeof sessions === "object" && !Array.isArray(sessions) && Object.values(sessions).every((v) => typeof v === "string")
+            ? { sessions: sessions }
+            : {};
+        return { kind: "chat-command", command, ...links };
+    }
     if (typeof origin.taskId !== "string" ||
         typeof origin.runId !== "string" ||
         (origin.sourceSessionId !== null && typeof origin.sourceSessionId !== "string"))
         return null;
     // A half-valid `source` drawn by the card is an `undefined` in a chip.
     const source = inputSource(raw);
-    const shape = { ...origin, ...(source ? { source } : {}) };
+    // A callback's, and relative paths resolve against it, so only an absolute one is kept.
+    const shape = {
+        ...origin,
+        ...(source ? { source } : {}),
+        ...(origin.kind === "task-callback" && typeof cwd === "string" && cwd.startsWith("/") ? { cwd } : {}),
+    };
     if (origin.kind === "task-delegation" || origin.kind === "task-callback") {
         return shape;
     }
@@ -168,6 +190,13 @@ export function toChatTurns(messages) {
             }
         }
         const text = textOf(m.content);
+        // Only the attempt that ended the turn: one Pi retried past is no failure.
+        if (m.role === "assistant" && m.stopReason === "error" && messages[i + 1]?.role !== "assistant") {
+            flush("assistant", hasTools ? "" : text, turnMetaAt(messages, i), undefined, m.timestamp);
+            turns[turns.length - 1].error = m.errorMessage || "unknown agent error";
+            candidate = undefined;
+            continue;
+        }
         // Tool-bearing messages are intermediate work, even when they include text.
         if (!text || hasTools)
             continue;

package/dist/agent/packages.js

@@ -5,17 +5,16 @@
 import { existsSync, promises as fs } from "node:fs";
 import { basename, dirname, join, relative, resolve } from "node:path";
 import { DefaultPackageManager, loadSkills, SettingsManager, } from "@earendil-works/pi-coding-agent";
-import { PackageError, } from "../core/types.js";
+import { PackageError, } from "./types.js";
 import { logger } from "../log.js";
 import { defaultAgentDir } from "./config.js";
 const log = logger("packages");
 /** Set by how long a released fix may sit unnoticed, like update.ts. */
 const CHECK_EVERY_MS = 24 * 60 * 60_000;
 const KINDS = { extensions: "extension", skills: "skill" };
-/** Written by `rtk init -g --agent pi` (the rtk block's `post_install` hook): a `local` file whose
- *  switch is the rtk tool's, so a settings.json pattern would fight the tool. */
+/** Written by `rtk init -g --agent pi` (the rtk block's `post_install` hook): the rtk tool's, so it
+ *  is left out of `local` — the Console switches it as that tool, and a settings.json pattern would fight it. */
 const RTK_FILE = join("extensions", "rtk.ts");
-const RTK_STATE = "installed by the rtk tool";
 export const kindOf = (source) => source.startsWith("npm:") ? "npm" : /^(git:|(https?|ssh|git):\/\/)/.test(source) ? "git" : "path";
 /** A trailing `@ref` on an npm or git source; the leading `@` of a scope is not one. */
 export const pinnedRef = (source) => {
@@ -120,13 +119,12 @@ export class PiPackageStore {
         row("local", "local", "global", this.agentDir);
         for (const key of Object.keys(KINDS)) {
             for (const r of resolved[key]) {
+                if (r.path === rtkPath)
+                    continue;
                 const own = r.metadata.origin === "top-level";
                 const scope = r.metadata.scope === "project" ? "project" : "global";
-                const resource = resourceRow(KINDS[key], r);
-                if (r.path === rtkPath)
-                    Object.assign(resource, { state: RTK_STATE, locked: true });
                 row(own ? "local" : r.metadata.source, own ? "local" : kindOf(r.metadata.source), scope, r.metadata.baseDir ?? null)
-                    .resources.push(resource);
+                    .resources.push(resourceRow(KINDS[key], r));
             }
         }
         // Configured but unresolved (not installed, or empty): still a row.
@@ -277,8 +275,6 @@ export class PiPackageStore {
     async setEnabled(change) {
         const { source, kind, path, enabled, cwd } = change;
         const { pkg, resource } = await this.#find(change);
-        if (resource.locked)
-            throw new PackageError("refused", `${resource.name} is ${resource.state} — its switch is under Tools`);
         if (pkg.kind === "pier") {
             this.pier.settings.setSkillsOff(withName(this.pier.settings.get().skillsOff, resource.name, !enabled));
         }

package/dist/agent/pi.js

@@ -3,9 +3,11 @@
 // Pi SDK. No Pi type may appear in an exported signature.
 import { realpathSync } from "node:fs";
 import { basename, dirname, join, sep } from "node:path";
-import { createAgentSession, CredentialSynchronizationError, DefaultResourceLoader, ModelRegistry, ModelRuntime, SessionManager, } from "@earendil-works/pi-coding-agent";
+import { createAgentSession, CredentialSynchronizationError, DefaultResourceLoader, ModelRegistry, ModelRuntime, SessionManager, sessionEntryToContextMessages, } from "@earendil-works/pi-coding-agent";
 import { SESSION_TITLE_MAX } from "../core/types.js";
 import { logger } from "../log.js";
+import { pierPath } from "../paths.js";
+import { DISPATCHER, LEAD } from "./roles.js";
 import { textOf, toChatTurns, toSessionEvents, turnMetaAt, } from "./events.js";
 import { defaultAgentDir, PiConfigStore } from "./config.js";
 import { IndexedListing } from "./listing.js";
@@ -99,7 +101,7 @@ These rules govern conversational replies. A human reads them on a phone-sized s
 - Before touching files: list and search first. Never guess a path or a line number.
 - Read before you edit. Match the surrounding code's style, naming, and comment density.
 - Do exactly what was asked. No unrequested refactors, no extra files, no README updates.
-- Each bash call is a fresh shell in the working directory; chain what must share state.
+- Each bash call is a fresh shell in the working directory; chain what must share state. Don't prefix commands with \`cd\` to that same directory — use relative paths; \`cd\` only to go elsewhere.
 - 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;
@@ -111,25 +113,37 @@ const bashTimeoutDefault = (pi) => {
         }
     });
 };
+/** The transcript's current branch in order, compacted entries included. */
+const branchMessages = (sessionManager) => sessionManager.getBranch().flatMap((entry) => sessionEntryToContextMessages(entry));
+/** Where a session compacts — a main session
+ *  and a session a run launched from a session made (a lead or a worker, which
+ *  never rotate); above 200K input, 1M-context models price higher. */
+const MAIN_COMPACTION_CAP = 100_000;
+const CHILD_COMPACTION_CAP = 150_000;
 export class PiSession {
     pi;
     pinned;
     wrote;
     retention;
     suggestTitle;
+    cap;
     constructor(pi, 
     /** Read per call — the menu can change while we run. */
     pinned = () => [], 
-    /** Drops the factory's retained listing: a rename lands in exactly the
-     *  window it covers, and every surface would keep the old title. */
+    /** Drops the factory's retained listing: a title lands in exactly the
+     *  window it covers, and every surface would keep the old one. */
     wrote = () => { }, retention = { value: "long" }, 
     /** Read per turn: switching auto-titling on takes effect without a restart. */
-    suggestTitle = () => undefined) {
+    suggestTitle = () => undefined, 
+    /** Auto-compaction triggers once the context passes this many tokens. */
+    cap) {
         this.pi = pi;
         this.pinned = pinned;
         this.wrote = wrote;
         this.retention = retention;
         this.suggestTitle = suggestTitle;
+        this.cap = cap;
+        this.applyCap();
     }
     /** 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). */
@@ -153,7 +167,7 @@ export class PiSession {
     }
     get contextUsage() {
         const u = this.pi.getContextUsage();
-        return u ? { tokens: u.tokens, contextWindow: u.contextWindow } : undefined;
+        return u ? { tokens: u.tokens, contextWindow: u.contextWindow, compactAt: u.contextWindow - this.reserve(u.contextWindow) } : undefined;
     }
     async setModel(ref) {
         const m = this.pi.modelRuntime.getModel(ref.provider, ref.id);
@@ -163,6 +177,8 @@ export class PiSession {
             throw new Error(`unknown model: ${ref.provider}/${ref.id}; available: ${available}`);
         }
         await this.pi.setModel(m);
+        // The reserve is per context window, so a cap outlives a model switch only if recomputed.
+        this.applyCap();
     }
     async availableModels() {
         const available = await this.pi.modelRuntime.getAvailable();
@@ -183,6 +199,27 @@ export class PiSession {
     setCacheRetention(retention) {
         this.retention.value = retention;
     }
+    instanceReserve;
+    /** Pi compacts past `contextWindow − reserveTokens`; this session's settings
+     *  manager is its own, so the override reaches no other session. Never later
+     *  than the instance's own reserve. */
+    applyCap() {
+        const window = this.pi.model?.contextWindow;
+        if (this.cap === undefined || !window)
+            return;
+        this.pi.settingsManager.applyOverrides({ compaction: { reserveTokens: this.reserve(window) } });
+    }
+    /** The instance's reserve is read once under a cap, before the first override replaces it. */
+    reserve(window) {
+        const settings = this.pi.settingsManager;
+        if (this.cap === undefined)
+            return settings.getCompactionSettings().reserveTokens;
+        this.instanceReserve ??= settings.getCompactionSettings().reserveTokens;
+        return Math.max(window - this.cap, this.instanceReserve);
+    }
+    skills() {
+        return this.pi.resourceLoader.getSkills().skills.map(({ name, description }) => ({ name, description }));
+    }
     async pendingQueue() {
         return {
             steering: [...this.pi.getSteeringMessages()],
@@ -209,12 +246,11 @@ export class PiSession {
     }
     async history() {
         this.live();
-        return toChatTurns(this.pi.messages);
+        return toChatTurns(branchMessages(this.pi.sessionManager));
     }
     async rewindToUserTurn(index) {
         const total = (await this.history()).filter((t) => t.role === "user").length;
-        // Branch entries keep compacted-away history that history() no longer
-        // shows, so only end-relative indices line up.
+        // End-relative: a user entry toChatTurns would not count cannot shift the target.
         const back = total - index;
         const users = this.pi.sessionManager
             .getBranch()
@@ -227,49 +263,41 @@ export class PiSession {
         if (cancelled)
             throw new Error("rewind cancelled");
     }
-    /** 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;
-    async compact() {
-        this.live();
-        if (this.compacting)
-            throw new Error(`session ${this.pi.sessionId} is already compacting`);
-        // 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 {
-            await running;
-        }
-        finally {
-            this.compacting = null;
-        }
-    }
-    /** 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();
-    }
-    /** 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 lets callers `.catch()`.
     async prompt(text) {
-        this.live();
-        await this.whenCompacted();
-        // The wait above is long enough for a dispose to land.
         this.live();
         // 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" });
+        let refused = false;
+        try {
+            await this.pi.prompt(text, { streamingBehavior: "followUp", preflightResult: (ok) => { refused = !ok; } });
+        }
+        catch (error) {
+            if (refused)
+                this.recordRefusal(text, error);
+            throw error;
+        }
+    }
+    /** Pi refuses before writing anything (no model, no key), so without this the
+     *  message and its reason would exist only as a live event (§5). Recorded the
+     *  way a provider failure is — an errored reply the model's context drops. */
+    recordRefusal(text, error) {
+        const now = Date.now();
+        const manager = this.pi.sessionManager;
+        manager.appendMessage({ role: "user", content: [{ type: "text", text }], timestamp: now });
+        manager.appendMessage({
+            role: "assistant",
+            content: [],
+            api: this.pi.model?.api ?? "",
+            provider: this.pi.model?.provider ?? "",
+            model: this.pi.model?.id ?? "",
+            usage: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, totalTokens: 0, cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 } },
+            stopReason: "error",
+            errorMessage: error instanceof Error ? error.message : String(error),
+            timestamp: now,
+        });
+        this.pi.agent.state.messages = manager.buildSessionProjection().messages;
     }
     async steer(text) {
         this.live();
@@ -281,15 +309,13 @@ export class PiSession {
     }
     async systemInput(text, origin, mode) {
         this.live();
-        // Same gate as prompt(): an idle session takes a system input as a turn.
-        await this.whenCompacted();
-        this.live();
-        // Read after the wait: a running turn means the call below queues.
-        const queued = this.pi.isStreaming;
+        // A running turn means the call below queues.
+        const queued = this.pi.isStreaming && mode !== "append";
         if (queued)
             this.queuedInputs.push(origin);
         try {
-            return await this.pi.sendCustomMessage({ customType: "pier.system-input", content: text, display: true, details: origin }, { triggerTurn: true, deliverAs: mode === "prompt" ? undefined : mode });
+            // Without a turn Pi appends it now, or after a running turn's tool results.
+            return await this.pi.sendCustomMessage({ customType: "pier.system-input", content: text, display: true, details: origin }, { triggerTurn: mode !== "append", deliverAs: mode === "prompt" || mode === "append" ? undefined : mode });
         }
         catch (error) {
             // Refused: nothing is in flight. The entry may be gone already.
@@ -338,8 +364,7 @@ export class PiSession {
         if (!first.trim())
             return;
         void suggest(first, reply).then((title) => {
-            // Named while we waited, by a person: their word beats the model's.
-            if (this.disposed || this.pi.sessionManager.getSessionName())
+            if (this.disposed)
                 return;
             this.pi.sessionManager.appendSessionInfo(title);
             this.wrote();
@@ -371,6 +396,7 @@ export class PiAgentFactory {
     pier;
     titleModel;
     listings;
+    roleOf;
     constructor(
     /** 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
@@ -384,7 +410,9 @@ export class PiAgentFactory {
     /** The built-in `pier` package's one switch list: Pier's own skills switched off. */
     pier = () => ({ skillsOff: [] }), titleModel = () => undefined, 
     /** Injected so a test needs no session directory or database. */
-    listings = new IndexedListing()) {
+    listings = new IndexedListing(), 
+    /** A reopened session's role, which only its runs record (tasks/). */
+    roleOf = () => undefined) {
         this.instructions = instructions;
         this.skillPaths = skillPaths;
         this.credentials = credentials;
@@ -393,6 +421,7 @@ export class PiAgentFactory {
         this.pier = pier;
         this.titleModel = titleModel;
         this.listings = listings;
+        this.roleOf = roleOf;
     }
     /** Catalogs are global, not per session. */
     catalog;
@@ -583,8 +612,9 @@ export class PiAgentFactory {
         const modelRegistry = new ModelRegistry(await this.refreshedRuntime());
         return { modelRegistry, model: active && modelRegistry.find(active.provider, active.id) };
     }
-    async resourceLoader(cwd) {
-        const { skillsOff } = this.pier();
+    async resourceLoader(cwd, role, dispatcher) {
+        // A worker never delegates (tasks/operations.ts refuses it), so it is not taught how.
+        const skillsOff = role === "worker" ? [...this.pier().skillsOff, "pier-tasks"] : this.pier().skillsOff;
         const loader = new DefaultResourceLoader({
             cwd,
             agentDir: defaultAgentDir(),
@@ -601,19 +631,27 @@ export class PiAgentFactory {
             agentsFilesOverride: (current) => {
                 const content = this.instructions();
                 return {
-                    agentsFiles: content
-                        ? [...current.agentsFiles, { path: "<pier>/AGENTS.md", content }]
-                        : current.agentsFiles,
+                    agentsFiles: [
+                        ...current.agentsFiles,
+                        ...(content ? [{ path: "<pier>/AGENTS.md", content }] : []),
+                        ...(dispatcher ? [{ path: "<pier>/dispatcher.md", content: DISPATCHER }] : []),
+                        ...(role === "lead" ? [{ path: "<pier>/lead.md", content: LEAD }] : []),
+                    ],
                 };
             },
         });
         await loader.reload();
         return loader;
     }
-    open(cwd, sessionManager, opts = { cwd }) {
-        return this.providerConfig.withWrite(() => this.openSnapshot(cwd, sessionManager, opts));
+    open(sessionManager, opts) {
+        return this.providerConfig.withWrite(() => this.openSnapshot(sessionManager, opts));
     }
-    async openSnapshot(cwd, sessionManager, opts) {
+    async openSnapshot(sessionManager, opts) {
+        const { cwd, role } = opts;
+        // The home is where the continuous conversation's sessions run: only they
+        // dispatch, and they compact at main's cap.
+        const main = realPath(cwd) === realPath(pierPath("home"));
+        const cap = main ? MAIN_COMPACTION_CAP : role ? CHILD_COMPACTION_CAP : undefined;
         // A locked store is a refusal with a reason here, not "provider not
         // configured" later. Before appendSessionInfo, so nothing is written.
         await this.credentials?.assertUnlocked();
@@ -630,7 +668,7 @@ export class PiAgentFactory {
             cwd,
             sessionManager,
             modelRuntime: runtime,
-            resourceLoader: await this.resourceLoader(cwd),
+            resourceLoader: await this.resourceLoader(cwd, role, main),
         });
         const live = created.session;
         // Pi defaults to one follow-up per turn boundary, so N queued messages cost
@@ -642,7 +680,7 @@ export class PiAgentFactory {
         }, retention, () => {
             const model = this.titleModel();
             return model && ((first, reply) => this.suggestTitle(model, first, reply));
-        });
+        }, cap);
         if (opts.model)
             await session.setModel(opts.model);
         if (opts.thinking)
@@ -654,13 +692,14 @@ export class PiAgentFactory {
         this.listing = undefined;
         // 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 });
+        return this.open(SessionManager.create(cwd), { ...opts, cwd });
     }
     async resume(sessionId) {
+        const role = this.roleOf(sessionId);
         const known = this.located.get(sessionId);
         if (known) {
             try {
-                return await this.open(known.cwd, SessionManager.open(known.path));
+                return await this.open(SessionManager.open(known.path), { cwd: known.cwd, role });
             }
             catch (err) {
                 log.warn(`cached path for session ${sessionId} did not open; re-listing`, err);
@@ -670,7 +709,7 @@ export class PiAgentFactory {
         const info = await this.locate(sessionId);
         if (!info)
             throw new Error(`unknown session: ${sessionId}`);
-        return this.open(info.cwd || process.cwd(), SessionManager.open(info.path));
+        return this.open(SessionManager.open(info.path), { cwd: info.cwd || process.cwd(), role });
     }
     /** 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
@@ -681,6 +720,10 @@ export class PiAgentFactory {
         return find(await this.listed()) ??
             (reused && this.listing === reused ? find(await this.listed(true)) : undefined);
     }
+    async readHistory(sessionId) {
+        const info = await this.locate(sessionId);
+        return info && toChatTurns(branchMessages(SessionManager.open(info.path)));
+    }
     async find(sessionId) {
         const info = await this.locate(sessionId);
         return info ? summaryOf(info) : undefined;