@timqi/pier 0.1.14 → 0.2.0

package/dist/agent/roles.js

@@ -0,0 +1,103 @@
+// The role contracts Pier injects from code, never written to disk
+// (docs/design/10-continuous-session.md): the dispatcher's, for the main
+// session of the continuous conversation, the feature lead's, and the chat
+// surface's, which every session gets.
+export const DISPATCHER = `# You are the main session of Pier's continuous conversation
+
+The user talks to Pier as one conversation; you are its current session, in the home directory, which holds memory only. You answer, remember and dispatch. You never edit code or files outside this directory yourself.
+
+## Dispatch
+- Real work is a child run: \`pier task run --prompt … --cwd <dir> --model hardest|balanced|cheap [--timeout <s>]\` (skills/pier-tasks). The model is a tier the operator pinned: \`hardest\` for a lead, design, architecture; \`balanced\` for coding a feature or a fix, integration; \`cheap\` for research, summaries, lookups, transcripts, bulk mechanical edits. A tier follows the change's difficulty, not the task's kind: a review takes the builder's tier, \`hardest\` only when the diff touches a seam (core/channels/tasks \`types.ts\`, \`db.ts\` migrations, auth/vault/secrets) or the builder's result reports a risk or an unverified part; a model the user names overrides both. Thinking follows the pin: pass \`--thinking\` only to override it; never \`--model ?\` per message. One \`wt\` worktree per feature: \`wt switch -c <branch> --no-cd -y --format json\` in the repo, its \`.path\` as \`--cwd\`.
+- A small, clear task is a worker: one run, one worktree. Larger work is a lead: \`pier task run --role lead --prompt … --cwd <its worktree> --model hardest --thinking high\`; it builds with its own workers and reports milestones, one callback per wave, never one per worker. Only a product or architecture design the user finalizes adds \`--design\`, which tags it design: the user designs with the lead in its own session, and you are not in that path. Any other lead — a build, a plan it builds itself, a review — has no \`--design\` and is tagged build.
+- Before the first tool call on a message, decide: answer from what is in context, or dispatch. One command may answer; a second command means a worker.
+- Every new run carries \`--name "<a few words>"\` that hit its intent — the session's title in the user's language, no role word (the web status panel tags a lead design or build itself).
+- Only the user finalizes a design: the lead asks them, and its milestone \`Design final: <path>\` means they confirmed. That milestone, or the user telling you to build a design, starts the build in a NEW lead, never the design lead continued: \`pier task run --role lead --thinking medium --cwd <the lead's worktree> --model hardest --name "…" --prompt "Build per <path>: …"\` — no \`--design\`, the lead's model, never a new pick. Never start a build on a design the user has not confirmed.
+- A follow-up on a feature continues its child — \`--run <id>\`, or \`--session <id>\` once idle — never a new one. Pass the user's words verbatim, your additions after them; never re-summarize.
+- Say in your reply what you dispatched, then end your turn: callbacks are the only delivery. A callback's text is on the surface the user reads: the reply says what it means and what is next, never repeats it.
+- \`pier task runs\` lists the runs this conversation launched (in flight, and finished in the last 24h) — for orientation, never for waiting.
+
+## Memory
+- \`MEMORY.md\`: durable facts, decisions, the project index (repo → path, worktree convention). \`memory/YYYY-MM-DD.md\`: daily notes, local date.
+- MEMORY.md is re-read in full at every session open: a list of facts, one line each. Rationale, narrative and working notes go in the daily note. Never record what this contract, AGENTS.md or a skill already says.
+- Edit MEMORY.md in place: a decision that supersedes another replaces it, no history kept.
+- A callback is the ledger's and the transcript's record already: it writes no note. A note records a decision, or a fact the ledger does not hold. Repo knowledge belongs in that repo's own AGENTS.md, written by a child.
+- Recall is files plus transcripts: \`rg\` over \`memory/\` and the Pi session directory.
+- A new session of this conversation opens with a seed: MEMORY.md, the open items, the run ledger, today's and yesterday's notes, and the previous session's last exchanges.
+
+## Open items
+- The list of what this conversation is solving is yours, written inside your reply and stripped from what the user sees: \`<open>problem — stage (run <id>)</open>\` adds or replaces the item with that problem, \`<done>problem</done>\` removes it. The problem is the user's words, the same every time (it is the key); the stage is where it stands (\`worker running\`, \`merged, restart pending\`, \`waiting on you: 60K or 80K?\`); one \`(run <id>)\` per run behind it, or none.
+- An open item is work in flight or waiting on the user's decision now; backlog and ideas go in MEMORY.md, never here.
+- Write one on dispatch, and on every callback and decision that moves a stage; \`<done>\` when the run finishes and nothing awaits the user, the daily note holding what was decided.
+- The user sees the list with \`/status\`; a stale stage there is fixed with another marker.`;
+export const LEAD = `# You are a feature lead
+
+You own one feature, in this worktree. The design doc you keep here is the state: anything not in it is lost when your session ends.
+
+## Design
+- Only when your run is a design discussion the user finalizes; any other lead goes straight to §Build.
+- Work the design out with the user, who talks to you directly in this session. Write it to a doc in this worktree and keep it current.
+- Only the user declares it final. When you think it is ready, ask whether to finalize, offering it as a next-step button (\`[Finalize design]\`); the question never carries the \`Design final:\` line.
+- Once the user confirms, end your reply with \`Design final: <absolute path of the doc>\` and stop: a new lead builds it, launched by your supervisor from that line or when the user says to build. Do not start building here.
+
+## Build
+- Started to build per a doc: read it first; it is the whole state. Started on a task with no doc: plan it in one here and build it; a plan that needs the user's OK is a question in your reply, never a \`Design final:\`.
+- Decompose it into worker runs: \`pier task run --name "<a few words>" --prompt … --cwd <worker worktree>\`, one \`wt\` worktree each (\`wt switch -c <branch> --no-cd -y --format json\` in the repo). The prompt is the worker's whole handoff; a worker never delegates.
+- Workers run on \`--model balanced\` for code, \`--model cheap\` for research and mechanical work.
+- Never launch another lead (\`--role lead\` is refused).
+- Each worker's result comes back to you: review it and integrate its branch here. While other results are still owed you, your replies reach only this session; your reply to the last one is the milestone your supervisor reads — what is done, what is next, any decision you need.
+- The build is yours to declare done, never the user's to confirm: a reply that leaves nothing owed you, workers or none, is that milestone.
+- \`pier task runs\` lists the runs you launched, for orientation, never for waiting.`;
+/** The surface contract handed to every agent Pier launches (main.ts); the
+ *  syntax it tells the agent to emit is parsed back by core/reply.ts. */
+const REPLY_SURFACE_PROMPT = `## Pier chat surface
+
+Your replies render in a chat UI (web and IM). Three optional markdown
+conventions:
+
+- **Next-step buttons** — a last line of \`---\`, then up to 5 \`[label]\` tokens
+  separated by \`|\`: \`---\` / \`[Run it] | [Show the diff]\`. A click sends that
+  label as the user's next message. Only for short, obvious next moves, never
+  for anything destructive.
+- **Attachments** — link a file you produced by absolute \`file://\` URL:
+  \`[report.md](file:///abs/path/report.md)\`. Images render as thumbnails,
+  other files as a download card, wherever on disk you wrote it. The same
+  convention runs inbound: a user message ending in \`[name](file:///…)\`
+  lines is carrying files the sender attached, already saved to disk — read
+  one only when it matters to the task; every read puts its content in your
+  context for good.
+- **Staying silent** — \`<silent>why</silent>\` is stripped, and if nothing else
+  remains no message is sent. In a group chat you are handed every message,
+  including humans talking to each other: stay silent rather than acknowledge
+  what was not addressed to you.
+
+A message may start with \`[name<id> time place]\` — the sender and the chat,
+added by Pier, not typed by them. It appears only on a change — new speaker, a
+~10-minute gap, a new day — so the last one still applies; a gap alone shows as
+time only, like \`[14:23]\`. Use that \`id\` to mention someone; never ask for
+their own. \`place\` is \`<platform>:<conversation>\` (Slack:
+\`slack:<channel>/<thread_ts>\`), said once per session: the channel and thread a
+script takes. Where no tool of yours takes that platform's ids, the header
+carries neither and reads \`[name time platform]\`. A last \`lang=zh\` (or
+\`en\`, \`ja\`, …) means the sender switched to that language: reply in it
+until another one appears, whatever language the context around it is in.
+`;
+/** Deployment facts an agent cannot discover: a guessed path is wrong wherever
+ *  `PIER_HOME` moved and fails as "nothing is configured"; GPT models carry
+ *  `apply_patch` from post-training and go hunting for it in the shell. */
+export function surfacePrompt(instance) {
+    const reach = instance.publicUrl
+        ? `Address: ${instance.publicUrl} — a board's link is that plus ` +
+            "`/boards/<slug>/`, or `/p/<slug>-<token>/` once published, where `token` " +
+            "is the random field the manifest carries beside `public`."
+        : "No public address is configured (the user sets one in Console → Settings), " +
+            "so give paths and never guess a host.";
+    return `${REPLY_SURFACE_PROMPT}
+## This Pier instance
+
+Boards: \`${instance.boardsDir}/<slug>/\` — this path, not \`~/.pier\`. ${reach}
+
+Editing: files change through the \`edit\` tool (exact text replacement) or
+\`write\`. There is no \`apply_patch\` here — not as a tool, not as a command —
+so do not call one or go looking for one in the shell.
+`;
+}

package/dist/agent/types.js

@@ -0,0 +1,78 @@
+// The Pi-config seams the Console asks agent/ for, declared by the side that
+// answers them. Imports no SDK and no node:* — web/ui bundles it type-only —
+// so any area may import it; keep it implementable over RPC.
+/** The global files the configuration document carries (`web/config-sync.ts`):
+ *  the three whole, settings.json only its two defaults. */
+export const SNAPSHOT_FILES = ["SYSTEM.md", "AGENTS.md", "models.json", "settings.json"];
+export class PackageError extends Error {
+    reason;
+    constructor(reason, message) {
+        super(message);
+        this.reason = reason;
+    }
+}
+// Wire-protocol names, not SDK types — but they are pi-ai's spellings, and a
+// non-Pi backend is bound to them by this seam.
+const PROVIDER_APIS = [
+    "openai-completions",
+    "openai-responses",
+    "anthropic-messages",
+    "google-generative-ai",
+];
+export const isProviderApi = (value) => typeof value === "string" && PROVIDER_APIS.includes(value);
+/** How far a model's reasoning goes. Every reasoning model offers up to
+ *  "high"; the two levels above it exist only for a model whose catalog entry
+ *  says so, which is the one thing a Console-defined model could not say. */
+export const MODEL_EFFORTS = ["high", "xhigh", "max"];
+/** The rules of the ProviderSetup seam, in one place: agent/ enforces them on
+ *  write and web/ pre-checks them at its HTTP boundary. Throws the message the
+ *  surface shows. */
+export function validateProviderSetup(input) {
+    if (input.id.length > 100 || !/^[a-z0-9][a-z0-9._-]*$/.test(input.id)) {
+        throw new Error("invalid provider id");
+    }
+    if (input.endpoint) {
+        if (input.endpoint.length > 2048 || input.endpoint !== input.endpoint.trim()) {
+            throw new Error("invalid endpoint");
+        }
+        validateEndpoint(input.endpoint);
+    }
+    if (input.kind === "builtin")
+        return;
+    if (!input.endpoint)
+        throw new Error("custom provider endpoint required");
+    if (input.name && (input.name.length > 200 || input.name !== input.name.trim())) {
+        throw new Error("invalid provider name");
+    }
+    if (!isProviderApi(input.api))
+        throw new Error("unsupported provider API");
+    if (!input.models.length || input.models.length > 100)
+        throw new Error("1-100 models required");
+    const ids = input.models.map((model) => model.id);
+    if (ids.some((id) => !id || id.length > 200 || id !== id.trim()) || new Set(ids).size !== ids.length) {
+        throw new Error("model ids must be non-empty, trimmed and unique");
+    }
+    // An effort ceiling on a model that does not reason would be written into
+    // the catalog and never offered — a setting that lies about itself.
+    if (input.models.some((model) => model.effort !== undefined && !model.reasoning)) {
+        throw new Error("effort requires reasoning");
+    }
+    if (input.models.some((model) => model.effort !== undefined && !MODEL_EFFORTS.includes(model.effort))) {
+        throw new Error("unsupported model effort");
+    }
+}
+export function validateEndpoint(endpoint) {
+    let url;
+    try {
+        url = new URL(endpoint);
+    }
+    catch {
+        throw new Error("endpoint must be an http(s) URL");
+    }
+    if (url.protocol !== "http:" && url.protocol !== "https:") {
+        throw new Error("endpoint must be an http(s) URL");
+    }
+    if (url.username || url.password || url.search || url.hash) {
+        throw new Error("endpoint must not contain credentials, query or fragment");
+    }
+}

package/dist/boards/boards.js

@@ -1,5 +1,5 @@
-// Boards: static pages an agent writes, derived by scanning $PIER_HOME/boards,
-// never registered (docs/design/05-boards.md). Only <board>/site is reachable
+// Boards: static pages an agent writes under $PIER_HOME/boards, never
+// registered (docs/design/05-boards.md). Only <board>/site is reachable
 // over HTTP, so a public board leaks nothing about how it was made. Bytes are
 // served on two password-free prefixes, `/p/*` (published) and `/b/*` (a
 // signed prefix the boundary mints), stylesheet included, and run sandboxed.
@@ -10,7 +10,7 @@ import { logger } from "../log.js";
 import { pierPath } from "../paths.js";
 export const defaultBoardsDir = () => pierPath("boards");
 /** Deleted boards keep their bytes under `<slug>.deleted-<ts>`, which this
- *  pattern excludes from every scan — one rename is the whole delete path. */
+ *  pattern refuses on every route — one rename is the whole delete path. */
 const SLUG = /^[a-z0-9][a-z0-9-]{0,63}$/;
 /** Without the 32 bits after the slug, `/p/` could be walked with a dictionary.
  *  Minted the first time a manifest is seen public, by whichever path did it. */
@@ -55,14 +55,27 @@ let viewKey = randomBytes(32);
 export const rotateBoardViews = () => {
     viewKey = randomBytes(32);
 };
-const sign = (slug, expires) => createHmac("sha256", viewKey).update(`${slug}\0${String(expires)}`).digest("base64url").slice(0, 22);
+const sign = (board, expires, key = viewKey) => createHmac("sha256", key).update(`${board}\0${String(expires)}`).digest("base64url").slice(0, 22);
 /** `<expiry in base36>-<signature>`: its own path segment, so the first hyphen
  *  is the cut and a hyphenated slug stays unambiguous. */
-const mintView = (slug) => {
+const mintView = (board, key) => {
     const expires = Date.now() + VIEW_TTL_MS;
-    return `${expires.toString(36)}-${sign(slug, expires)}`;
+    return `${expires.toString(36)}-${sign(board, expires, key)}`;
 };
-function validView(slug, view) {
+/** What a prefix is signed for: the slug and its directory, because a delete
+ *  renames the board away and frees the slug, and a prefix must not open the
+ *  successor. Null when there is no such directory. */
+async function boardOf(dir, slug) {
+    try {
+        return `${slug}\0${String((await stat(join(dir, slug))).ino)}`;
+    }
+    catch (err) {
+        if (err.code !== "ENOENT")
+            logger("boards").warn(`cannot stat board ${slug}`, err);
+        return null;
+    }
+}
+function validView(board, view) {
     const cut = view.indexOf("-");
     if (cut < 1)
         return false;
@@ -74,9 +87,9 @@ function validView(slug, view) {
         return false;
     if (expires <= Date.now())
         return false;
-    return sameToken(sign(slug, expires), view.slice(cut + 1));
+    return sameToken(sign(board, expires), view.slice(cut + 1));
 }
-/** Malformed boards are reported once, not on every scan. */
+/** Malformed boards are reported once, not on every request. */
 const warned = new Set();
 /** The one place a slug becomes a path, so it is validated here (`../../etc`,
  *  NUL). Extra keys survive a write. The one write-back is minting a token for
@@ -104,7 +117,6 @@ async function readManifest(dir, slug) {
         ...m,
         title: typeof m.title === "string" && m.title ? m.title : slug,
         description: typeof m.description === "string" ? m.description : "",
-        sessions: Array.isArray(m.sessions) ? m.sessions.filter((s) => typeof s === "string") : [],
         public: m.public === true,
         token: typeof m.token === "string" && TOKEN.test(m.token) ? m.token : "",
     };
@@ -130,7 +142,7 @@ async function updatedAt(dir, slug) {
         (await stat(join(dir, slug)).catch(() => null));
     return (info?.mtime ?? new Date()).toISOString();
 }
-export async function listBoards(dir) {
+async function listBoards(dir) {
     let entries;
     try {
         entries = (await readdir(dir, { withFileTypes: true }))
@@ -143,17 +155,14 @@ export async function listBoards(dir) {
             logger("boards").warn(`cannot scan ${dir}`, err);
         return [];
     }
-    // One board's manifest says nothing about the next one's, so the scan waits
-    // once for all of them rather than once per board.
     const boards = await Promise.all(entries.map(async (slug) => {
         const manifest = await readManifest(dir, slug);
         if (!manifest)
             return null;
-        const { title, description, sessions, public: isPublic, token } = manifest;
-        return { slug, title, description, sessions, public: isPublic, token, updatedAt: await updatedAt(dir, slug) };
+        const { title, description, public: isPublic, token } = manifest;
+        return { slug, title, description, public: isPublic, token, updatedAt: await updatedAt(dir, slug) };
     }));
-    // Freshest first: the board someone just wrote is the one they came to see.
-    // Slug breaks ties so equal mtimes still list in a stable order.
+    // Freshest first; slug breaks ties so equal mtimes still list in a stable order.
     return boards
         .filter((board) => board !== null)
         .sort((a, b) => b.updatedAt.localeCompare(a.updatedAt) || a.slug.localeCompare(b.slug));
@@ -231,8 +240,7 @@ async function serveFile(c, dir, slug, rest) {
 }
 export function registerBoardRoutes(app, dir = defaultBoardsDir()) {
     app.get("/api/boards", async (c) => c.json(await listBoards(dir)));
-    // Publishing is the one decision a human owns; every other field belongs to
-    // the agent that wrote the board.
+    // Publishing is the one manifest field a human owns; the rest is the agent's.
     app.patch("/api/boards/:slug", async (c) => {
         const slug = c.req.param("slug");
         const body = (await c.req.json().catch(() => null));
@@ -242,21 +250,19 @@ export function registerBoardRoutes(app, dir = defaultBoardsDir()) {
         if (!manifest)
             return c.json({ error: "no such board" }, 404);
         manifest.public = body.public;
-        // Publishing an unpublished board is the case readManifest cannot mint for:
-        // it read the manifest while it was still private.
+        // readManifest mints only for a manifest it read as public.
         if (manifest.public && !manifest.token)
             manifest.token = mintToken();
         await writeManifest(dir, slug, manifest);
         return c.json({ public: manifest.public, token: manifest.token });
     });
+    // A rename, so the undo is on disk; signed prefixes are bound to the
+    // directory's inode (boardOf), so none opens a successor on the same slug.
     app.delete("/api/boards/:slug", async (c) => {
         const slug = c.req.param("slug");
         if (!(await readManifest(dir, slug)))
             return c.json({ error: "no such board" }, 404);
         await rename(join(dir, slug), join(dir, `${slug}.deleted-${Date.now()}`));
-        // A capability names a slug, and a slug can be taken again: the prefixes
-        // handed out for the board that just died must not open its successor.
-        rotateBoardViews();
         return c.json({ deleted: slug });
     });
     // Declared before the wildcards below: `_assets` is not a slug.
@@ -285,10 +291,12 @@ export function registerBoardRoutes(app, dir = defaultBoardsDir()) {
     // needs no cookie and can be sandboxed into an opaque origin.
     const mint = async (c) => {
         const slug = c.req.param("slug") ?? "";
-        // Signed before the read: a sign-out landing during it would otherwise
-        // hand this request a capability made with the key that replaced the
-        // revoked one.
-        const view = SLUG.test(slug) ? mintView(slug) : "";
+        // The key as this request found it: a sign-out landing during the reads
+        // would otherwise hand it a capability made with the key that replaced
+        // the revoked one.
+        const key = viewKey;
+        const board = SLUG.test(slug) ? await boardOf(dir, slug) : null;
+        const view = board ? mintView(board, key) : "";
         // A board that is gone says so here, rather than after a redirect.
         if (!view || !(await readManifest(dir, slug)))
             return c.notFound();
@@ -304,10 +312,12 @@ export function registerBoardRoutes(app, dir = defaultBoardsDir()) {
         const rest = c.req.path.slice(`/b/${slug}/${view}/`.length);
         if (!SLUG.test(slug))
             return c.notFound();
-        // Expired, forged, or signed with a key that has since rotated: send it
-        // back through the boundary, which re-mints for a live session in one hop
-        // and asks a stranger for the password. Existence stays unsaid either way.
-        if (!validView(slug, view)) {
+        // Expired, forged, signed with a key that has since rotated, or for a
+        // board since renamed away: send it back through the boundary, which
+        // re-mints for a live session in one hop and asks a stranger for the
+        // password. Existence stays unsaid either way.
+        const board = await boardOf(dir, slug);
+        if (!board || !validView(board, view)) {
             return c.redirect(`/boards/${slug}/${rest}${new URL(c.req.url).search}`);
         }
         if (!(await readManifest(dir, slug)))

package/dist/channels/chains.js

@@ -48,10 +48,6 @@ export class Chains {
         else
             this.held -= 1;
     }
-    /** The backpressure primitive. */
-    oldest() {
-        return Promise.race(this.active.values()).catch(() => { });
-    }
     /** Two adapters handling one message would prompt twice; a hung handler
      *  holding up the Console's save is worse than either, hence the bound. */
     async drain(timeoutMs) {

package/dist/channels/commands.js

@@ -1,19 +1,14 @@
 // Slash commands in IM text, parsed once for every platform: clients add
-// whitespace and capitalise.
-/** The configure-first trigger, one spelling on both platforms: `s <text>`
- *  (Lark also `/s <text>`), the text being the panel's pending question. A bare
- *  `s` carries no question and is prose. */
+// whitespace and capitalise. `%` is `/` too: Slack's client eats an unregistered `/`.
+/** The configure-first trigger: `/s <text>` or `%s <text>`, the text being the
+ *  panel's pending question. `/s` alone carries no question and is prose. */
 export function settingsDraft(text) {
-    return /^\/?s[ \t]+(\S[\s\S]*)$/i.exec(text.trim())?.[1];
+    return /^[/%]s[ \t]+(\S[\s\S]*)$/i.exec(text.trim())?.[1];
 }
 export function parseCommand(text) {
     const trimmed = text.trim();
-    if (!trimmed.startsWith("/"))
-        return null;
     // Args verbatim: a path or a sentence must keep its own spacing.
-    const match = /^\/(\S+)[ \t]*([\s\S]*)$/.exec(trimmed);
-    const name = match?.[1] ?? "";
-    if (!name)
-        return null; // a bare "/" is not a command
-    return { name: name.toLowerCase(), args: match?.[2] ?? "" };
+    const match = /^[/%](\S+)[ \t]*([\s\S]*)$/.exec(trimmed);
+    // A bare "/" or "%" is not a command.
+    return match?.[1] ? { name: match[1].toLowerCase(), args: match[2] ?? "" } : null;
 }

package/dist/channels/config.js

@@ -1,7 +1,7 @@
 // Channel config persistence and the permission gate every adapter shares: one
 // JSON document per platform, so a surface configuring one reads and writes one row.
 import { randomInt } from "node:crypto";
-import { defaultChannelConfig, } from "./types.js";
+import { defaultChannelConfig, PLATFORMS, } from "./types.js";
 const BIND_CODE_TTL_MS = 10 * 60_000;
 /** Six symbols out of 36 is 2 billion, but a caller who may retry forever only
  *  needs the TTL; five wrong tries void the code instead. */
@@ -72,6 +72,32 @@ export class ChannelStore {
     chat(platform, chatId) {
         return this.get(platform).chats.find((c) => c.id === chatId);
     }
+    /** One home instance-wide: setting it clears every other row on both
+     *  platforms. Refuses a chat that is unknown or not a DM; `null` leaves no home anywhere. */
+    setHome(platform, chatId) {
+        if (chatId !== null && this.cached(platform).chats.find((c) => c.id === chatId)?.kind !== "dm") {
+            throw new Error(`${platform}:${chatId} is not a known DM`);
+        }
+        for (const p of PLATFORMS) {
+            const config = this.get(p);
+            for (const chat of config.chats) {
+                if (p === platform && chat.id === chatId)
+                    chat.home = true;
+                else
+                    delete chat.home;
+            }
+            this.save(p, config);
+        }
+    }
+    // On the per-message path: no clone.
+    home() {
+        for (const platform of PLATFORMS) {
+            const chat = this.cached(platform).chats.find((c) => c.home);
+            if (chat)
+                return { platform, chatId: chat.id };
+        }
+        return undefined;
+    }
     /** No platform reliably lists every chat a bot is in, so discovery is passive
      *  and happens on every message: the unchanged case must cost no clone. A new
      *  chat copies the platform defaults and owns them from then on. */

package/dist/channels/control.js

@@ -50,7 +50,7 @@ export function createControl({ router, factory, conversations, store, modelMenu
                 model: session.model,
                 thinking: session.thinkingLevel,
                 tokens: usage?.tokens ?? null,
-                contextWindow: usage?.contextWindow ?? null,
+                compactAt: usage?.compactAt ?? null,
             };
         },
         pins: modelMenu,
@@ -89,21 +89,10 @@ export function createControl({ router, factory, conversations, store, modelMenu
             const seen = new Set([...(own ? [own] : []), ...projectCwds(await factory.list())]);
             return [...seen].slice(0, limit);
         },
-        async recent(key, exchanges) {
-            const session = await live(key);
-            if (!session)
-                return [];
-            const pairs = [];
-            for (const turn of await session.history()) {
-                const last = pairs.at(-1);
-                if (turn.role === "user")
-                    pairs.push({ user: turn.text });
-                // The first reply after a user turn; later assistant turns of the same
-                // exchange are continuations of the same answer.
-                else if (turn.role === "assistant" && last && last.assistant === undefined)
-                    last.assistant = turn.text;
-            }
-            return pairs.slice(-exchanges);
+        isHome(key) {
+            const home = store.home();
+            return home?.platform === key.channelId && home.chatId === chatOf(key.conversationId);
         },
+        skills: async (key) => (await live(key))?.skills() ?? [],
     };
 }

package/dist/channels/conversations.js

@@ -47,11 +47,6 @@ export class ConversationStore {
     `).get(sessionId);
         return row && { channelId: row.channel_id, conversationId: row.conversation_id };
     }
-    /** Every session some IM conversation answers for, in one query. */
-    boundSessions() {
-        const rows = this.db.prepare(`SELECT session_id FROM conversations`).all();
-        return new Set(rows.map((r) => r.session_id));
-    }
     /** Every thread of one chat: a chat that is gone would otherwise keep its
      *  sessions bound to a conversation nothing can reach. */
     forgetChat(channelId, chatId) {

package/dist/channels/lark-api.js

@@ -100,29 +100,30 @@ export class LarkApi {
         });
     }
     // --- messages ------------------------------------------------------------------
-    async replyCard(messageId, card) {
-        const res = await this.client.im.v1.message.reply({
-            path: { message_id: messageId },
-            data: {
-                msg_type: "interactive",
-                content: JSON.stringify(card),
-                // Lark's equivalent of posting to a thread_ts.
-                reply_in_thread: true,
-            },
-        });
-        return { messageId: ok("message.reply", res).data?.message_id ?? "" };
+    replyCard(messageId, card) {
+        return this.post({ root: messageId }, "interactive", card);
     }
-    async createCard(chatId, card) {
-        const res = await this.client.im.v1.message.create({
-            params: { receive_id_type: "chat_id" },
-            data: { receive_id: chatId, msg_type: "interactive", content: JSON.stringify(card) },
-        });
-        return { messageId: ok("message.create", res).data?.message_id ?? "" };
+    sendCard(chatId, card) {
+        return this.post({ chatId }, "interactive", card);
+    }
+    async post(to, type, content) {
+        const data = { msg_type: type, content: JSON.stringify(content) };
+        const res = "root" in to
+            // `reply_in_thread` is Lark's equivalent of posting to a thread_ts.
+            ? ok("message.reply", await this.client.im.v1.message.reply({
+                path: { message_id: to.root },
+                data: { ...data, reply_in_thread: true },
+            }))
+            : ok("message.create", await this.client.im.v1.message.create({
+                params: { receive_id_type: "chat_id" },
+                data: { ...data, receive_id: to.chatId },
+            }));
+        return { messageId: res.data?.message_id ?? "" };
     }
     /** Images take the image endpoint so they render inline; `stream` is Lark's
      *  "type unknown". The SDK unwraps an upload response to its `data`, so a
      *  failure arrives as a missing key, not a code. */
-    async uploadFile(rootId, file) {
+    async uploadFile(to, file) {
         const bytes = Buffer.from(file.bytes);
         let content;
         if (file.image) {
@@ -141,14 +142,7 @@ export class LarkApi {
                 throw new Error(`lark file.create: no file_key for ${file.name}`);
             content = { file_key: res.file_key };
         }
-        ok("message.reply", await this.client.im.v1.message.reply({
-            path: { message_id: rootId },
-            data: {
-                msg_type: file.image ? "image" : "file",
-                content: JSON.stringify(content),
-                reply_in_thread: true,
-            },
-        }));
+        await this.post(to, file.image ? "image" : "file", content);
     }
     async patchCard(messageId, card) {
         ok("message.patch", await this.client.im.v1.message.patch({

package/dist/channels/lark-outbound.js

@@ -1,7 +1,9 @@
-// How a turn becomes cards in a Lark thread: one card per chunk, footer and
-// buttons on the last, and what an empty turn still has to say.
-import { formatTurnMeta, isSilentReply, originLabel, quietLabel } from "../core/reply.js";
+// How a turn becomes cards in a Lark thread, or the home chat's main flow: one
+// card per chunk, footer and buttons on the last, and what an empty turn still
+// has to say.
+import { formatTurnMeta, isSilentReply, quietLabel } from "../core/reply.js";
 import { sendAttachments, splitAttachments } from "./attach.js";
+import { noteBody } from "./lines.js";
 import { button, buttonRow, card, chunk, footer, LARK_MAX, markdown, OFFER_PREFIX, withFooter, withoutButtons, } from "./lark-render.js";
 const SENT_CACHE = 200;
 export class LarkOutbound {
@@ -18,7 +20,7 @@ export class LarkOutbound {
     /** An empty turn still posts its footer and says which kind of nothing (§5).
      *  The footer folds into the last chunk's element (a second element renders
      *  a blank gap); only a bodiless turn gets the standalone one. */
-    async reply(root, reply) {
+    async reply(to, reply) {
         // A local file link is dead in Lark: the bytes are uploaded instead.
         const { text: spoken, paths } = splitAttachments(reply.text);
         const text = spoken.trim();
@@ -27,6 +29,8 @@ export class LarkOutbound {
         const note = [quiet, meta].filter(Boolean).join(" · ");
         if (!(text || reply.suggestions.length || note || paths.length))
             return;
+        // An empty root is a main-flow button, which only the home chat has (lark.ts onAction).
+        const root = "root" in to ? to.root : "";
         const row = reply.suggestions.length
             ? buttonRow(reply.suggestions.map((label, index) => button(label, { key: `${OFFER_PREFIX}${index}`, root, label })))
             : undefined;
@@ -42,32 +46,16 @@ export class LarkOutbound {
                 elements.push(row);
             if (!elements.length)
                 continue;
-            const { messageId } = await this.api.replyCard(root, card(elements));
+            const { messageId } = await this.post(to, card(elements));
             if (last && row && messageId)
                 this.remember(messageId, card(elements));
         }
-        const lost = await sendAttachments(paths, (file) => this.api.uploadFile(root, file), this.log);
+        const lost = await sendAttachments(paths, (file) => this.api.uploadFile(to, file), this.log);
         if (lost)
-            await this.api.replyCard(root, card([markdown(lost)]));
+            await this.post(to, card([markdown(lost)]));
     }
-    /** The root, then one card inside its topic: on the phone a topic has its
-     *  own composer only once it has a reply. Answers the root's id. The handoff
-     *  writes no row when this throws, so a root left behind would invite a reply
-     *  into a thread nobody answers: it is taken back down. */
-    async open(chatId, note) {
-        const link = note.url ? `[Open on the web](${note.url})` : "(no public URL set — Settings → Instance)";
-        const { messageId: root } = await this.api.createCard(chatId, card([
-            markdown(`**Continued from web: ${note.title}**\n${link}\nReply in this thread to continue.`),
-        ]));
-        try {
-            await this.api.replyCard(root, card([markdown("Reply here to continue.")]));
-        }
-        catch (err) {
-            await this.api.deleteMessage(root)
-                .catch((e) => this.log(`orphan handoff root ${root} not deleted: ${String(e)}`));
-            throw err;
-        }
-        return root;
+    post(to, sent) {
+        return "root" in to ? this.api.replyCard(to.root, sent) : this.api.sendCard(to.chatId, sent);
     }
     /** Best-effort: a card sent before a restart keeps its row, logged. */
     async retire(messageId) {
@@ -91,11 +79,10 @@ export class LarkOutbound {
     }
     /** No footer: the turn this input triggers has not ended. Answers with the
      *  id of the last card posted, where the caller puts the 👀. */
-    async note(root, note) {
-        const body = note.text.split("\n").map((line) => `> ${line}`).join("\n");
+    async note(to, note) {
         let messageId;
-        for (const part of chunk(`*${originLabel(note.origin)}*\n${body}`, LARK_MAX)) {
-            messageId = (await this.api.replyCard(root, card([markdown(part)]))).messageId;
+        for (const part of chunk(noteBody(note, "*"), LARK_MAX)) {
+            messageId = (await this.post(to, card([markdown(part)]))).messageId;
         }
         return messageId;
     }

package/dist/channels/lark-panel.js

@@ -7,7 +7,7 @@ import { ChatPanel, CWD_DRAFT_TAIL, CWD_PLACEHOLDER, holdQuestion, PANEL_PREFIX,
 /** A form-submit button name: `cwdgo:<thread root>`. */
 export const CWD_SUBMIT_PREFIX = "cwdgo:";
 const CWD_FIELD = "cwd";
-const fresh = (root, messageId, draft) => ({ root, messageId, draft, dirs: [], sessions: [] });
+const fresh = (root, messageId, draft) => ({ root, messageId, draft, dirs: [] });
 export class LarkPanel extends ChatPanel {
     deps;
     fence = ["`", "`"];