@timqi/pier 0.1.4 → 0.1.5

package/README.md

@@ -2,7 +2,7 @@
 
 A self-hosted workspace for coding agents. Pier puts a web workbench and your
 IM channels in front of [Pi](https://github.com/earendil-works/pi) sessions:
-talk to the same agent from a browser, Slack, Telegram or Lark, steer a running
+talk to the same agent from a browser, Slack or Lark, steer a running
 turn, schedule tasks, watch every session, and publish a static page when
 something is worth showing.
 
@@ -62,9 +62,9 @@ Console → Settings:
   `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: the bundled extensions
-  (`web`: `web_search` on Anthropic or OpenAI, `web_fetch` on Anthropic; a
-  copy of yours registering the same tool makes Pier's stand down) and the
+  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
   [ubix](https://github.com/timqi/ubix) block), installed into
   `~/.pier/tools/bin`, first on every session's PATH beside the `pier` shim

package/dist/agent/events.js

@@ -200,9 +200,14 @@ export function toSessionEvents(e) {
                 return [];
             // Carried twice: on turn-end because it is how the turn ended (what a
             // task run settles on), and as the error event every chat surface reports.
+            // `toolUse` without a tool call is a provider protocol violation (the
+            // block was billed but never delivered); Pi ends the run on it, so it
+            // reaches the conversation as the failure it is, not as an empty turn.
             const failure = final?.stopReason === "error"
                 ? final.errorMessage || "unknown agent error"
-                : undefined;
+                : final?.stopReason === "toolUse" && !hasToolCalls(final)
+                    ? "the provider stopped on tool_use but sent no tool call"
+                    : undefined;
             const out = [
                 { type: "turn-end", text: hasToolCalls(final) ? "" : textOf(final?.content), ...(failure ? { error: failure } : {}) },
             ];
@@ -228,8 +233,12 @@ export function toSessionEvents(e) {
             // On the message, not its text: an attachment with no caption is still a turn.
             const out = [{ type: "turn-start" }];
             const text = textOf(m.content);
-            if (text)
-                out.push(origin ? { type: "system-input", text, origin } : { type: "user-message", text });
+            if (text) {
+                out.push(origin
+                    // `at` is what `turnMetaAt` will read back as this turn's start.
+                    ? { type: "system-input", text, origin, at: m.timestamp }
+                    : { type: "user-message", text });
+            }
             return out;
         }
         case "message_update": {

package/dist/agent/listing.js

@@ -15,6 +15,13 @@ const log = logger("agent");
 const AUDIT_SAMPLE = 5;
 const titleOf = (name, first) => name || first || undefined;
 const str = (v) => (typeof v === "string" ? v : undefined);
+/** The budget is the words, not the header: a 34-character Lark id would spend
+ *  it all and leave a clip that no longer parses back as a header. */
+function clipTitle(whole, clean) {
+    const body = clean(whole);
+    const header = whole.slice(0, whole.length - body.length);
+    return header + body.slice(0, SESSION_TITLE_MAX);
+}
 /** A reply that calls a tool is a step, not a reply (events.ts), and steps are
  *  not indexed. `clean` takes off the speaker header (core/identity.ts), which
  *  as text would make "operator" hit every session. */
@@ -67,7 +74,7 @@ function fold(acc, line, clean) {
         // through core/identity.ts.
         if (acc.first || said.role !== "user")
             return acc;
-        return { ...acc, first: textOf(message?.content).trim().slice(0, SESSION_TITLE_MAX) };
+        return { ...acc, first: clipTitle(textOf(message?.content).trim(), clean) };
     }
     return acc;
 }
@@ -201,7 +208,8 @@ export class IndexedListing {
             const want = info && {
                 cwd: info.cwd,
                 created: info.created.getTime(),
-                title: info.name ?? info.firstMessage?.slice(0, SESSION_TITLE_MAX),
+                title: info.name ??
+                    (info.firstMessage ? clipTitle(info.firstMessage.trim(), this.clean) : undefined),
             };
             if (want && want.cwd === seen.cwd && want.created === seen.created &&
                 want.title === seen.title)

package/dist/agent/packages.js

@@ -6,10 +6,8 @@ import { existsSync, promises as fs } from "node:fs";
 import { basename, dirname, join, relative, resolve } from "node:path";
 import { DefaultPackageManager, SettingsManager, } from "@earendil-works/pi-coding-agent";
 import { PackageError, } from "../core/types.js";
-import { BUNDLED } from "../extensions/index.js";
 import { logger } from "../log.js";
 import { defaultAgentDir } from "./config.js";
-import { shadowedBuiltin } from "./pi.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;
@@ -152,12 +150,8 @@ export class PiPackageStore {
     }
     async #fillPier(pkg) {
         pkg.version = this.pier.version;
-        const { extensions: on, skillsOff: off } = this.pier.settings.get();
-        // Off is off: a stand-down recorded while it was on is not this switch's state.
-        pkg.resources = BUNDLED.map(({ name }) => ({
-            kind: "extension", name, path: `<inline:${name}>`, enabled: on.includes(name),
-            state: on.includes(name) ? shadowedBuiltin(name) : null,
-        }));
+        const { skillsOff: off } = this.pier.settings.get();
+        pkg.resources = [];
         for (const dir of this.skillDirs) {
             for (const entry of (await fs.readdir(dir, { withFileTypes: true })).filter((e) => e.isDirectory())) {
                 const path = join(dir, entry.name, "SKILL.md");
@@ -265,11 +259,7 @@ export class PiPackageStore {
         if (resource.locked)
             throw new PackageError("refused", `${resource.name} is ${resource.state} — its switch is under Tools`);
         if (pkg.kind === "pier") {
-            const { extensions, skillsOff } = this.pier.settings.get();
-            if (kind === "skill")
-                this.pier.settings.setSkillsOff(withName(skillsOff, resource.name, !enabled));
-            else
-                this.pier.settings.setExtensions(withName(extensions, resource.name, enabled));
+            this.pier.settings.setSkillsOff(withName(this.pier.settings.get().skillsOff, resource.name, !enabled));
         }
         else {
             const key = kind === "extension" ? "extensions" : "skills";

package/dist/agent/pi.js

@@ -1,10 +1,9 @@
-// The only file outside src/extensions allowed to import @earendil-works/pi-*.
+// One of the two files (with packages.ts) allowed to import @earendil-works/pi-*.
 // Implements the AgentFactory/AgentSession seam from src/core/types.ts on the
 // 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, ModelRuntime, SessionManager, } from "@earendil-works/pi-coding-agent";
-import { inlineExtensions } from "../extensions/index.js";
+import { createAgentSession, CredentialSynchronizationError, DefaultResourceLoader, ModelRegistry, ModelRuntime, SessionManager, } from "@earendil-works/pi-coding-agent";
 import { SESSION_TITLE_MAX } from "../core/types.js";
 import { logger } from "../log.js";
 import { textOf, toChatTurns, toSessionEvents, turnMetaAt, } from "./events.js";
@@ -64,7 +63,7 @@ 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 leading `[name time]` or `[name<id> time]` on the user's message is a speaker header, not content.";
 /** 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>`;
@@ -112,34 +111,6 @@ const bashTimeoutDefault = (pi) => {
         }
     });
 };
-/** What the last session open stood down, by bundled extension name: the
- *  registry (agent/packages.ts) shows it as the row's state. Known only at
- *  open, so a built-in no session has loaded since reads nothing. */
-const shadowed = new Map();
-export const shadowedBuiltin = (name) => shadowed.get(name) ?? null;
-/** 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 Map(base.extensions.filter((ext) => !inline(ext)).flatMap((ext) => [...ext.tools.keys()].map((tool) => [tool, ext.path])));
-    return {
-        ...base,
-        extensions: base.extensions.filter((ext) => {
-            if (!inline(ext))
-                return true;
-            const name = ext.path.slice("<inline:".length, -1);
-            const clash = [...ext.tools.keys()].filter((tool) => onDisk.has(tool));
-            if (!clash.length) {
-                shadowed.delete(name);
-                return true;
-            }
-            const from = onDisk.get(clash[0]);
-            shadowed.set(name, `stood down — ${clash.join(", ")} from ${from}`);
-            log.info(`bundled ${ext.path} stood down — ${clash.join(", ")} already loaded from ${from}`);
-            return false;
-        }),
-    };
-};
 export class PiSession {
     pi;
     pinned;
@@ -410,8 +381,8 @@ export class PiAgentFactory {
     /** Optional only for bare test factories; an OAuth refresh persists here,
      *  never to a plaintext auth.json. */
     credentials, providerConfig = new PiConfigStore(), pinned = () => [], 
-    /** The built-in `pier` package's switches: bundled extensions on, Pier's own skills off. */
-    pier = () => ({ extensions: [], skillsOff: [] }), titleModel = () => undefined, 
+    /** 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()) {
         this.instructions = instructions;
@@ -606,8 +577,14 @@ export class PiAgentFactory {
     async logout(providerId) {
         await (await this.authRuntime()).logout(providerId, { signal: AbortSignal.timeout(15_000) });
     }
+    /** Pi's registry over the shared runtime, so an OAuth refresh lands in the
+     *  credential store like every other request's. */
+    async webContext(active) {
+        const modelRegistry = new ModelRegistry(await this.refreshedRuntime());
+        return { modelRegistry, model: active && modelRegistry.find(active.provider, active.id) };
+    }
     async resourceLoader(cwd) {
-        const { extensions, skillsOff } = this.pier();
+        const { skillsOff } = this.pier();
         const loader = new DefaultResourceLoader({
             cwd,
             agentDir: defaultAgentDir(),
@@ -620,11 +597,7 @@ export class PiAgentFactory {
                 ...base,
                 skills: base.skills.filter((skill) => !skillsOff.includes(skill.name) || !this.skillPaths.some((dir) => skill.filePath.startsWith(dir + sep))),
             }),
-            extensionFactories: [
-                { name: "pier-bash-timeout", factory: bashTimeoutDefault, hidden: true },
-                ...inlineExtensions(extensions),
-            ],
-            extensionsOverride: standDownShadowed,
+            extensionFactories: [{ name: "pier-bash-timeout", factory: bashTimeoutDefault, hidden: true }],
             agentsFilesOverride: (current) => {
                 const content = this.instructions();
                 return {

package/dist/channels/attach.js

@@ -5,8 +5,8 @@
 import { readFile, stat } from "node:fs/promises";
 import { basename, extname } from "node:path";
 import { lostMarker, replaceOutsideCode } from "../core/inbound-file.js";
-/** Telegram refuses a photo past 10 MB, the smallest of the three; one cap so
- *  a turn does not land on one chat and not another. */
+/** Lark refuses an image past 10 MB, the smaller of the two; one cap so a
+ *  turn does not land on one chat and not another. */
 export const MAX_ATTACH_BYTES = 10 * 1024 * 1024;
 const MAX_ATTACHMENTS = 5;
 /** svg excluded deliberately: it is markup, and renders as a file. */

package/dist/channels/commands.js

@@ -1,17 +1,19 @@
-// Slash commands in IM text, parsed once for every platform: Telegram appends
-// `@botname` when several bots share a group, clients add whitespace, users capitalise.
+// 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. */
+export function settingsDraft(text) {
+    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 = "", target] = (match?.[1] ?? "").split("@");
+    const name = match?.[1] ?? "";
     if (!name)
         return null; // a bare "/" is not a command
-    return {
-        name: name.toLowerCase(),
-        args: match?.[2] ?? "",
-        ...(target ? { target } : {}),
-    };
+    return { name: name.toLowerCase(), args: match?.[2] ?? "" };
 }

package/dist/channels/config.js

@@ -9,9 +9,8 @@ const BIND_CODE_TRIES = 5;
 const BIND_CODE_ALPHABET = "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ";
 /** Where each platform's credentials live in the vault — fixed names, so a
  *  skill and the Console agree without a setting. Migration 24 spells the same
- *  table in SQL. Telegram authenticates with one token. */
+ *  table in SQL. */
 const CREDENTIAL_NAMES = {
-    telegram: { token: "TELEGRAM_TOKEN" },
     slack: { token: "SLACK_TOKEN", appToken: "SLACK_APP_TOKEN" },
     lark: { token: "LARK_APP_ID", appToken: "LARK_APP_SECRET" },
 };
@@ -69,9 +68,9 @@ export class ChannelStore {
     chat(platform, chatId) {
         return this.get(platform).chats.find((c) => c.id === chatId);
     }
-    /** Telegram has no "list my chats" API, 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. */
+    /** 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. */
     discoverChat(platform, chat) {
         const cached = this.cached(platform).chats.find((c) => c.id === chat.id);
         if (cached && cached.name === chat.name && cached.kind === chat.kind)
@@ -102,7 +101,6 @@ export class ChannelStore {
             enabled: true,
             requireMention: config.requireMention,
             requireBind: config.requireBind,
-            topicMode: config.topicMode,
             cwd: config.cwd,
             model: config.model,
             thinking: config.thinking,

package/dist/channels/control.js

@@ -1,8 +1,11 @@
 // What an adapter may do to a session beyond handing it a prompt. Not part of
 // the `Channel` seam: the channel layer owns the router and hands adapters this
 // narrow interface instead. Thin wrappers over core; no policy.
+import { projectCwds } from "../core/identity.js";
 import { chatOf, isChannelPlatform } from "./types.js";
-export function createControl({ router, factory, conversations, store }) {
+export const NO_SESSION = "No session in this thread yet — start one first (Start in the panel).";
+export const HAS_SESSION = "This thread already has a session — send your question as a message.";
+export function createControl({ router, factory, conversations, store, modelMenu }) {
     const launchFor = (key) => {
         if (!isChannelPlatform(key.channelId))
             return {};
@@ -13,44 +16,87 @@ export function createControl({ router, factory, conversations, store }) {
             thinking: policy.thinking ?? undefined,
         };
     };
+    /** The thread's session, resumed if evicted; undefined when the thread has
+     *  none. Never creates: a look at the panel must not open a session. */
+    const live = async (key) => {
+        if (!conversations.get(key))
+            return undefined;
+        return router.sessionOf(key) ?? router.ensure(key);
+    };
     return {
         launchFor,
         knows: (key) => conversations.get(key) !== undefined,
         abort: (key) => router.abortConversation(key),
+        working: (key) => router.sessionOf(key)?.state === "streaming",
         async status(key) {
-            const session = router.sessionOf(key);
+            const session = await live(key);
             if (!session)
                 return null;
             const summary = await factory.find(session.id);
             const usage = session.contextUsage;
             return {
                 sessionId: session.id,
-                cwd: summary?.cwd ?? "",
+                // Not on disk until its first reply; the launch record knows where it is.
+                cwd: summary?.cwd ?? conversations.launchOf(key)?.cwd ?? "",
                 state: session.state,
+                empty: (await session.history()).length === 0,
                 model: session.model,
                 thinking: session.thinkingLevel,
-                thinkingLevels: session.availableThinkingLevels(),
                 tokens: usage?.tokens ?? null,
                 contextWindow: usage?.contextWindow ?? null,
             };
         },
-        models: () => factory.availableModels(),
+        pins: modelMenu,
         async setModel(key, model) {
-            await router.sessionOf(key)?.setModel(model);
+            const session = await live(key);
+            if (!session)
+                throw new Error(NO_SESSION);
+            await session.setModel(model);
+            conversations.amendLaunch(key, { model });
         },
         async setThinking(key, level) {
-            router.sessionOf(key)?.setThinkingLevel(level);
+            const session = await live(key);
+            if (!session)
+                throw new Error(NO_SESSION);
+            session.setThinkingLevel(level);
+            conversations.amendLaunch(key, { thinking: level });
         },
-        async newSession(key, cwd) {
-            const launch = launchFor(key);
-            const session = await factory.create({
-                ...launch,
-                cwd: cwd || launch.cwd || process.cwd(),
-            });
+        async newSession(key, over = {}) {
+            const defaults = launchFor(key);
+            const launch = { ...defaults, ...over, cwd: over.cwd || defaults.cwd || process.cwd() };
+            const session = await factory.create(launch);
+            // A message already inside the router's resolve can write the row while Pi
+            // was opening: the first row wins, and the session nobody routes to goes.
+            if (conversations.get(key)) {
+                await session.dispose();
+                throw new Error(HAS_SESSION);
+            }
             // Persist before attaching: a crash between must not leave an unrecorded session.
-            conversations.set(key, session.id);
+            conversations.set(key, session.id, launch);
             router.attach(key, session);
             return session.id;
         },
+        async recentDirs(key, limit = 6) {
+            const own = launchFor(key).cwd;
+            // The web's rule (worktrees folded into their project); task runs' directories count too.
+            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);
+        },
     };
 }

package/dist/channels/conversations.js

@@ -13,21 +13,44 @@ export class ConversationStore {
     `).get(key.channelId, key.conversationId);
         return row?.session_id;
     }
-    set(key, sessionId) {
+    /** `launch`: what the session was created with, for a re-create when Pi has
+     *  no transcript (a session never prompted was never written); omitted for
+     *  one launched from the chat defaults, which a re-create reads again. */
+    set(key, sessionId, launch) {
         this.db.prepare(`
-      INSERT INTO conversations(channel_id, conversation_id, session_id, updated_at)
-      VALUES (?, ?, ?, ?)
+      INSERT INTO conversations(channel_id, conversation_id, session_id, updated_at, launch)
+      VALUES (?, ?, ?, ?, ?)
       ON CONFLICT(channel_id, conversation_id) DO UPDATE SET
-        session_id = excluded.session_id, updated_at = excluded.updated_at
-    `).run(key.channelId, key.conversationId, sessionId, Date.now());
+        session_id = excluded.session_id, updated_at = excluded.updated_at, launch = excluded.launch
+    `).run(key.channelId, key.conversationId, sessionId, Date.now(), launch ? JSON.stringify(launch) : null);
+    }
+    launchOf(key) {
+        const row = this.db.prepare(`
+      SELECT launch FROM conversations WHERE channel_id = ? AND conversation_id = ?
+    `).get(key.channelId, key.conversationId);
+        return row?.launch ? JSON.parse(row.launch) : undefined;
+    }
+    /** No record: nothing to amend. */
+    amendLaunch(key, patch) {
+        const launch = this.launchOf(key);
+        if (!launch)
+            return;
+        this.db.prepare(`
+      UPDATE conversations SET launch = ? WHERE channel_id = ? AND conversation_id = ?
+    `).run(JSON.stringify({ ...launch, ...patch }), key.channelId, key.conversationId);
     }
     /** Durable, unlike the router's answer, which is gone once an idle session
      *  is evicted. No row: nobody's conversation. */
-    channelOf(sessionId) {
+    keyOf(sessionId) {
         const row = this.db.prepare(`
-      SELECT channel_id FROM conversations WHERE session_id = ? LIMIT 1
+      SELECT channel_id, conversation_id FROM conversations WHERE session_id = ? LIMIT 1
     `).get(sessionId);
-        return row?.channel_id;
+        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));
     }
     forget(key) {
         this.db.prepare(`
@@ -35,24 +58,48 @@ export class ConversationStore {
     `).run(key.channelId, key.conversationId);
     }
 }
+/** The backend's "no such session" (`agent/pi.ts`), also read in `web/server.ts`. */
+const UNKNOWN_SESSION = "unknown session";
+/** A note reaches the chat through `channels.notify`, which does not cut for
+ *  itself the way `Router.report` does. */
+const ERROR_CHARS = 200;
 /** The IM half of the router's session factory, wired in main.ts so neither
  *  core nor an adapter learns where the mapping lives. */
-export function resolveConversation(store, factory, launchFor, onStale) {
+export function resolveConversation(store, factory, launchFor, 
+/** The thread is told, not only the log: its next answer comes from a
+ *  session that remembers nothing. */
+onStale) {
     return async (key) => {
         const known = store.get(key);
+        let stale;
+        let recorded;
         if (known) {
             try {
                 return await factory.resume(known);
             }
             catch (err) {
                 // Never persisted, or deleted: re-route rather than fail every message.
-                onStale?.(`${key.channelId}:${key.conversationId} lost session ${known}: ${String(err)}`);
+                // main.ts notifies the chat directly, so the cause is cut here.
+                stale = String(err).slice(0, ERROR_CHARS);
+                recorded = store.launchOf(key);
                 store.forget(key);
             }
         }
-        const launch = launchFor(key);
-        const session = await factory.create({ ...launch, cwd: launch.cwd ?? process.cwd() });
-        store.set(key, session.id);
+        const defaults = launchFor(key);
+        const launch = recorded ?? { ...defaults, cwd: defaults.cwd ?? process.cwd() };
+        const session = await factory.create(launch);
+        store.set(key, session.id, recorded);
+        if (stale) {
+            const was = known.slice(0, 8);
+            const now = session.id.slice(0, 8);
+            // Pi writes nothing before the first reply, so a recorded session the
+            // backend never knew lost no message: that is not data loss to report.
+            onStale?.(key, recorded && stale.includes(UNKNOWN_SESSION)
+                ? `Session ${was} had no messages yet — continuing as ${now}.`
+                : recorded
+                    ? `Session ${was} is gone from disk (${stale}); re-created as ${now} with its own settings in ${launch.cwd}.`
+                    : `Session ${was} is gone from disk (${stale}); this thread continues in a new session with the chat defaults in ${launch.cwd}.`);
+        }
         return session;
     };
 }

package/dist/channels/handoff.js

@@ -0,0 +1,90 @@
+// Web ↔ IM handoff: the only code that binds an existing session to a thread it
+// did not create — pushed from the web (a new thread, the only root message
+// Pier ever posts; post before row, since a row for a thread that does not
+// exist is worse than a message with no row) or pulled from a thread's panel.
+import { sessionLabel } from "../core/identity.js";
+import { chatOf, isChannelPlatform, } from "./types.js";
+export class HandoffError extends Error {
+    status;
+    constructor(status, message) {
+        super(message);
+        this.status = status;
+    }
+}
+const platformName = (platform) => platform[0].toUpperCase() + platform.slice(1);
+export function createHandoff(deps) {
+    const { store, runtime, conversations, factory, router, hub, publicUrl, log } = deps;
+    /** Where a session already answers, for the refusal: the chat's name, else its id. */
+    const nameOf = (key) => {
+        const chatId = chatOf(key.conversationId);
+        return (isChannelPlatform(key.channelId) && store.chat(key.channelId, chatId)?.name) || chatId;
+    };
+    /** The guards both directions share: on disk, and nobody's yet. */
+    const claimable = async (sessionId) => {
+        const summary = await factory.find(sessionId);
+        if (!summary) {
+            throw new HandoffError(404, `Session ${sessionId.slice(0, 8)} has no transcript yet — send it one message first.`);
+        }
+        const bound = conversations.keyOf(sessionId);
+        if (bound)
+            throw new HandoffError(409, `Already answers in ${bound.channelId} · ${nameOf(bound)}.`);
+        return summary;
+    };
+    /** The one binding. Loaded on the web right now: the next turn answers in
+     *  the thread without waiting for the thread to speak. Not loaded: the row
+     *  is enough. */
+    const bind = (key, sessionId) => {
+        conversations.set(key, sessionId);
+        const live = router.sessionOf({ channelId: "web", conversationId: sessionId });
+        if (live)
+            router.attach(key, live);
+        hub.emitWorkspace({ type: "sessions-changed" });
+        log(`session ${sessionId} continued in ${key.channelId}:${key.conversationId}`);
+    };
+    return {
+        targets: () => runtime.running().flatMap((platform) => store.get(platform).chats
+            .filter((chat) => chat.enabled)
+            .map((chat) => ({ platform, chatId: chat.id, name: chat.name, kind: chat.kind }))),
+        async continueIn({ sessionId, platform, chatId }) {
+            if (!runtime.running().includes(platform)) {
+                throw new HandoffError(409, `${platformName(platform)} is not running — enable it in Settings → Channels.`);
+            }
+            const chat = store.chat(platform, chatId);
+            if (!chat?.enabled)
+                throw new HandoffError(chat ? 409 : 404, "That chat is not enabled for the bot.");
+            const summary = await claimable(sessionId);
+            const base = publicUrl();
+            const note = {
+                title: sessionLabel(summary),
+                url: base ? `${base}/#/session/${encodeURIComponent(sessionId)}` : "",
+            };
+            let conversationId;
+            try {
+                conversationId = await runtime.openThread(platform, chatId, note);
+            }
+            catch (err) {
+                throw new HandoffError(502, String(err));
+            }
+            bind({ channelId: platform, conversationId }, sessionId);
+            return { conversationId };
+        },
+        async unbound(limit) {
+            const bound = conversations.boundSessions();
+            const owned = deps.taskSessions();
+            const ranks = deps.workingSet();
+            const rank = (id) => ranks.get(id)?.rank ?? Infinity;
+            return (await factory.list())
+                .filter((s) => !bound.has(s.id) && !owned.has(s.id))
+                .sort((a, b) => rank(a.id) - rank(b.id) || b.createdAt - a.createdAt)
+                .slice(0, limit);
+        },
+        async continueHere(key, sessionId) {
+            // The panel hides the button once a row exists, but a stale panel or a
+            // message that raced the tap must not orphan the thread's session.
+            if (conversations.get(key))
+                throw new HandoffError(409, "This thread already has a session.");
+            await claimable(sessionId);
+            bind(key, sessionId);
+        },
+    };
+}

package/dist/channels/lark-api.js

@@ -112,6 +112,13 @@ export class LarkApi {
         });
         return { messageId: ok("message.reply", res).data?.message_id ?? "" };
     }
+    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 ?? "" };
+    }
     /** 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. */

package/dist/channels/lark-outbound.js

@@ -50,6 +50,25 @@ export class LarkOutbound {
         if (lost)
             await this.api.replyCard(root, 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;
+    }
     /** Best-effort: a card sent before a restart keeps its row, logged. */
     async retire(messageId) {
         const known = this.sent.get(messageId);