@timqi/pier 0.1.14 → 0.3.0

package/dist/channels/runtime.js

@@ -1,13 +1,19 @@
 // Channel lifecycle: which adapters are running; one call for the Console to
 // apply a config change.
+import { splitReply } from "../core/reply.js";
+import { Refused } from "../core/router.js";
 import { logger } from "../log.js";
 import { LarkChannel } from "./lark.js";
 import { SlackChannel } from "./slack.js";
+import { chatOf } from "./types.js";
 const ADAPTERS = [
     { platform: "slack", build: (deps) => new SlackChannel(deps) },
     // Lark's "token" is the App ID and "appToken" the App Secret.
     { platform: "lark", build: (deps) => new LarkChannel(deps) },
 ];
+const rootLine = (lead, state) => state === "waiting" ? `▷ ${lead.name} · design — waiting for you`
+    : state === "final" ? `✓ ${lead.name} · design final`
+        : `⚠ ${lead.name} · design — ${lead.text}`;
 // The injected sink is for warnings; "slack started" is not one.
 const log = logger("channels");
 // The parameter below shadows `log` inside its own default expression.
@@ -15,19 +21,19 @@ const warn = (m) => log.warn(m);
 export class ChannelRuntime {
     store;
     router;
+    chain;
     control;
-    handoff;
+    conversations;
     log;
-    live = new Map();
+    running = new Map();
     reloading = Promise.resolve();
     stopped = false;
-    constructor(store, router, control, 
-    /** The pull half only; the push half needs this runtime, so main.ts closes the loop. */
-    handoff, log = warn) {
+    constructor(store, router, chain, control, conversations, log = warn) {
         this.store = store;
         this.router = router;
+        this.chain = chain;
         this.control = control;
-        this.handoff = handoff;
+        this.conversations = conversations;
         this.log = log;
     }
     /** Serialized: two concurrent Console saves would race into duplicate live
@@ -48,9 +54,10 @@ export class ChannelRuntime {
     }
     async restart(adapter) {
         const { platform, build } = adapter;
-        const existing = this.live.get(platform);
+        const existing = this.running.get(platform);
         if (existing) {
-            this.live.delete(platform);
+            this.running.delete(platform);
+            this.router.unregisterChannel(platform);
             // Never fatal: the config still has to be applied.
             await existing.stop().catch((err) => this.log(`${platform} did not stop cleanly: ${String(err)}`));
         }
@@ -66,10 +73,12 @@ export class ChannelRuntime {
             store: this.store,
             log: (m) => this.log(`${platform}: ${m}`),
             control: this.control,
-            handoff: this.handoff,
         });
         try {
             await channel.start((msg) => {
+                // A thread of the home chat bound to a child (§Child threads) is that session's.
+                if (this.control.isHome(msg.key) && !this.control.knows(msg.key))
+                    return this.toHead(channel, msg);
                 void this.router.dispatch(msg).catch((err) => this.log(`dispatch failed: ${String(err)}`));
             });
         }
@@ -77,38 +86,83 @@ export class ChannelRuntime {
             this.log(`${platform} failed to start: ${String(err)}`);
             return;
         }
+        // Running before registered: the router asks main.ts's chatKeyOf, which asks `live`.
+        this.running.set(platform, channel);
         this.router.registerChannel(channel);
-        this.live.set(platform, channel);
         log.info(`${platform} started`);
     }
+    /** The home chat's every message, threaded or not, is the head's under the
+     *  chat's key. A refusal is the chat's to see (§5): the adapter only logs. */
+    toHead(channel, msg) {
+        const conversationId = chatOf(msg.key.conversationId);
+        this.chain.send(msg, { channelId: msg.key.channelId, conversationId }).catch((err) => {
+            this.log(`the conversation did not take a message: ${String(err)}`);
+            if (err instanceof Refused)
+                return;
+            const text = err instanceof Error ? err.message : String(err);
+            void channel.notify(conversationId, { text, origin: { kind: "error" } })
+                .catch((e) => this.log(`could not report it to ${channel.id}: ${String(e)}`));
+        });
+    }
+    live(platform) {
+        return this.running.has(platform);
+    }
+    /** A design lead waiting on the user gets a thread in the home DM bound to
+     *  its session (docs/design/11 §Child threads); its later states edit the
+     *  root. No home, its adapter down, or the session already in a chat: nothing
+     *  — the web's needs-you carries it. Every failure is a note in the chat. */
+    async designLead(lead, state) {
+        const home = this.store.home();
+        const channel = home && this.running.get(home.platform);
+        if (!home || !channel)
+            return;
+        const note = { text: rootLine(lead, state), origin: lead.origin };
+        const bound = this.conversations.keyOf(lead.sessionId);
+        if (state === "waiting") {
+            if (bound)
+                return;
+            let thread;
+            try {
+                thread = await channel.openThread(home.chatId, note);
+                // The row first: `ensure` resolves the thread through it, as any thread's message would.
+                this.conversations.set({ channelId: home.platform, conversationId: thread }, lead.sessionId);
+                await this.router.ensure({ channelId: home.platform, conversationId: thread });
+                await channel.send(thread, splitReply(lead.text));
+            }
+            catch (err) {
+                // A root already posted is the thread's failure to report; none, the main flow's.
+                await this.report(channel, thread ?? home.chatId, `"${lead.name}" waits for you on the web; ${thread ? "its turn did not reach this thread" : "its thread could not be opened"}: ${String(err)}`);
+            }
+            return;
+        }
+        // Only a thread of the home chat has a root of ours to edit.
+        if (!bound || bound.channelId !== home.platform || chatOf(bound.conversationId) !== home.chatId)
+            return;
+        await channel.editRoot(bound.conversationId, note).catch((err) => this.report(channel, bound.conversationId, `the thread's root could not be updated to "${note.text}": ${String(err)}`));
+    }
+    async report(channel, conversationId, text) {
+        this.log(text);
+        await channel.notify(conversationId, { text, origin: { kind: "error" } })
+            .catch((e) => this.log(`could not report it to ${channel.id}: ${String(e)}`));
+    }
     /** For restart-note delivery (src/drain.ts), which has no session to report
      *  through; false means the platform is not running. */
     async notify(platform, conversationId, text) {
-        const channel = this.live.get(platform);
+        const channel = this.running.get(platform);
         if (!channel)
             return false;
         await channel.notify(conversationId, { text, origin: { kind: "error" } });
         return true;
     }
-    running() {
-        return [...this.live.keys()];
-    }
-    /** Throws by name when the platform is not running: the caller's answer is
-     *  "enable it in Settings", not a silent no-op. */
-    async openThread(platform, chatId, note) {
-        const channel = this.live.get(platform);
-        if (!channel)
-            throw new Error(`${platform} is not running`);
-        return channel.openThread(chatId, note);
-    }
     async stop() {
-        // An in-flight restart could otherwise register an adapter after `live`
+        // An in-flight restart could otherwise register an adapter after `running`
         // was cleared — running, unstoppable.
         this.stopped = true;
         await this.reloading.catch(() => { });
-        for (const channel of this.live.values()) {
+        for (const channel of this.running.values()) {
+            this.router.unregisterChannel(channel.id);
             await channel.stop().catch((err) => this.log(`${channel.id} did not stop cleanly: ${String(err)}`));
         }
-        this.live.clear();
+        this.running.clear();
     }
 }

package/dist/channels/slack-outbound.js

@@ -1,7 +1,8 @@
-// How a turn becomes messages in a Slack thread: which renderer, how to chunk
-// against its limit, and what an empty turn still has to say.
-import { formatTurnMeta, isSilentReply, originLabel, quietLabel } from "../core/reply.js";
+// How a turn becomes messages in a Slack thread, or the home DM's main flow:
+// which renderer, how to chunk against its limit, 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 { isBlockRejection } from "./slack-api.js";
 import { actions, chunk, context, escapeMrkdwn, markdown, MARKDOWN_MAX, MRKDWN_MAX, sections, toMrkdwn, } from "./slack-render.js";
 const footerText = (meta) => escapeMrkdwn(formatTurnMeta(meta));
@@ -14,6 +15,7 @@ export class SlackOutbound {
         this.api = api;
         this.log = log;
     }
+    /** No `threadTs` is the home DM's main flow (slack.ts target). */
     async reply(channel, threadTs, reply) {
         // A local file link is dead in Slack: the bytes are uploaded instead.
         const { text: spoken, paths } = splitAttachments(reply.text);
@@ -43,22 +45,18 @@ export class SlackOutbound {
     /** No footer: the turn this input triggers has not ended. Answers with the
      *  `ts` of the last message posted, where the caller puts the 👀. */
     async note(channel, threadTs, note) {
-        const body = note.text.split("\n").map((line) => `> ${line}`).join("\n");
         let ts;
-        for (const part of chunk(`_${originLabel(note.origin)}_\n${body}`, this.budget())) {
+        for (const part of chunk(noteBody(note, "_"), this.budget())) {
             ts = await this.post(channel, threadTs, part, []);
         }
         return ts;
     }
-    /** The one root Pier posts (no `thread_ts`): the thread a web session is
-     *  continued in has no user message to hang from. Answers the root's `ts`. */
-    async open(channel, note) {
-        const link = note.url || "_(no public URL set — Settings → Instance)_";
-        const sent = await this.api.postMessage({
-            channel,
-            text: `Continued from web: *${escapeMrkdwn(note.title)}*\n${link}\n_Reply in this thread to continue._`,
-        });
-        return sent.ts;
+    /** A note's root rewritten in place (a child thread's state); one message,
+     *  so the body is cut to the smaller budget rather than split. */
+    async edit(channel, ts, note) {
+        const body = chunk(noteBody(note, "_"), MRKDWN_MAX)[0] ?? "";
+        const blocks = this.markdownBlocks ? [markdown(body)] : sections(toMrkdwn(body));
+        await this.api.updateMessage({ channel, ts, text: body, blocks });
     }
     budget() {
         return this.markdownBlocks ? MARKDOWN_MAX : MRKDWN_MAX;

package/dist/channels/slack-panel.js

@@ -18,7 +18,7 @@ const row = (buttons, value) => ({
     type: "actions",
     elements: buttons.map((b) => button(b, value)),
 });
-const fresh = (channel, ts, draft) => ({ chatId: channel, ts, draft, dirs: [], sessions: [] });
+const fresh = (channel, ts, draft) => ({ chatId: channel, ts, draft, dirs: [] });
 export class SlackPanel extends ChatPanel {
     deps;
     fence = ["`", "`"];

package/dist/channels/slack-render.js

@@ -97,7 +97,7 @@ export const context = (text) => ({
 // --- next-step buttons -------------------------------------------------------
 /** `action_id` carries an index: the label is read back off the message Slack
  *  echoes with the click, so a button survives a reload. */
-export const OFFER_PREFIX = "sg:";
+const OFFER_PREFIX = "sg:";
 /** Slack refuses a button label over BUTTON_MAX: every button, the panel's too. */
 export const truncate = (label) => cut(label, BUTTON_MAX);
 /** Slack wraps buttons on its own, so there is no row packing to budget. */

package/dist/channels/slack-thread.js

@@ -39,3 +39,68 @@ export async function readThread(directory, client, channel, threadTs, limit) {
         messages: transcript(window, names, { ts: true, ids: true, thread: true }),
     };
 }
+/** A token budget, not a Slack limit: past this the agent gets the
+ *  coordinates and decides for itself. */
+const INLINE_REPLY_MAX = 30;
+/** The eager thread read is not gated: a human handing the agent a message
+ *  is the same act as an upload. */
+export async function sharedBlock(directory, api, log, share) {
+    const source = share.original_message;
+    const ts = share.ts ?? source?.ts;
+    const threadTs = share.thread_ts ?? source?.thread_ts ?? ts;
+    const replies = share.reply_count ?? source?.reply_count;
+    // A share of a reply is one message; only a parent has a thread.
+    const parent = share.channel_id && ts && threadTs === ts && replies
+        ? { channel: share.channel_id, ts, replies }
+        : null;
+    // `name<id>` is the sender prefix's grammar (core/identity.ts).
+    const author = share.author_id
+        ? `${await directory.user(api, share.author_id)}<${share.author_id}>`
+        : share.author_name || share.author_subname;
+    const where = share.channel_name
+        ? `#${share.channel_name}${share.channel_id ? `<${share.channel_id}>` : ""}`
+        : share.channel_id;
+    const head = [
+        "shared message",
+        author && `from ${author}`,
+        where && `in ${where}`,
+        ts && `at ${ts}`,
+    ].filter(Boolean).join(" ");
+    // `fallback` is Slack's plain-text rendering when a share's `text` is
+    // empty (a file-only forward, or a body that is all blocks); "" is normal.
+    const body = (share.text || share.fallback || source?.text || "").trim();
+    const thread = parent && parent.replies <= INLINE_REPLY_MAX
+        ? await sharedThread(directory, api, log, parent.channel, parent.ts, parent.replies)
+        : { transcript: false, lines: [] };
+    // The coordinates in `pier slack`'s own words (skills/pier-slack).
+    const hint = parent && !thread.transcript
+        ? `[thread: ${parent.replies} replies — channel ${parent.channel}, thread_ts ${parent.ts}]`
+        : "";
+    // The transcript opens with the shared message itself.
+    return [`[${head}]`, thread.transcript ? "" : body, ...thread.lines, hint]
+        .filter(Boolean).join("\n");
+}
+/** A read that fails or comes back cut says so in the prompt (§5). */
+export async function sharedThread(directory, api, log, channel, ts, replies) {
+    try {
+        // One over the budget, so an undercounting reply_count still reports as cut.
+        const read = await readThread(directory, api, channel, ts, INLINE_REPLY_MAX + 2);
+        if (!read.messages.length)
+            return { transcript: false, lines: [] };
+        return {
+            transcript: true,
+            lines: [
+                `[thread: ${replies} replies, oldest first — ${read.format}]`,
+                ...read.messages,
+                ...(read.truncated ? [`[thread partly read: cut at ${read.count} lines]`] : []),
+            ],
+        };
+    }
+    catch (err) {
+        log(`shared thread ${channel}/${ts} not read: ${String(err)}`);
+        return {
+            transcript: false,
+            lines: [`[thread not read: ${err instanceof Error ? err.message : String(err)}]`],
+        };
+    }
+}

package/dist/channels/slack.js

@@ -1,11 +1,14 @@
 // Slack adapter: normalize inbound Socket Mode envelopes, render outbound turns.
-// Pier never posts into a channel's main flow: a conversation is
-// `<channel>/<threadTs>` and the thread is the session. Slack-specific: the
-// client intercepts unregistered slash commands, so `stop` and `settings` are
-// bare words; reactions are short names (`reactions.add` rejects 👀 with
+// Pier never posts into a channel's main flow but the home DM's
+// (docs/design/11-im-conversation.md), which is one conversation keyed `<channel>`:
+// any other is `<channel>/<threadTs>` and the thread is the session. Slack-specific: the
+// client intercepts unregistered slash commands, so `%stop` is the spelling
+// that arrives; reactions are short names (`reactions.add` rejects 👀 with
 // `invalid_name`); unacked envelopes are redelivered, so `event_id` is deduplicated.
+import { isChatCommand } from "../core/types.js";
 import { saveInboundAll } from "../core/inbox.js";
 import { MAX_INBOUND_BYTES } from "../core/inbound-file.js";
+import { skillsText } from "../core/chain.js";
 import { awaitsTurn } from "../core/reply.js";
 import { bindHint, bindResult, picked, STALE_OPTION, STOPPED } from "./lines.js";
 import { logger } from "../log.js";
@@ -18,7 +21,7 @@ import { SlackDirectory } from "./slack-directory.js";
 import { SlackApi, } from "./slack-api.js";
 import { SlackOutbound } from "./slack-outbound.js";
 import { SlackPanel } from "./slack-panel.js";
-import { readThread } from "./slack-thread.js";
+import { sharedBlock } from "./slack-thread.js";
 import { context, escapeMrkdwn, offeredLabel } from "./slack-render.js";
 const WORKING = "eyes";
 // The envelope is already acked, so this bounds concurrency (sockets,
@@ -30,12 +33,9 @@ const DRAIN_TIMEOUT_MS = 5000;
 /** Only has to cover a redelivery that crossed our immediate ack. */
 const DEDUP_TTL_MS = 5 * 60_000;
 const DEDUP_MAX = 2000;
-/** Bare words with exact arity, since there is no leading `/` to key on: "stop
- *  the deploy and tell me why" is a sentence for the agent, not an abort. */
-const BARE_COMMANDS = new Map([["stop", 0], ["settings", 0], ["bind", 1]]);
 /** The only definition of the conversation id format; control.ts decodes with it. */
 const conversationId = (channel, threadTs) => `${channel}/${threadTs}`;
-export const parseConversation = (id) => {
+const parseConversation = (id) => {
     const at = id.indexOf("/");
     return at < 0
         ? { channel: id, threadTs: "" }
@@ -51,21 +51,6 @@ const READABLE_SUBTYPES = new Set(["file_share", "thread_broadcast", "message_sh
  *  sender did not choose to forward; a real share carries both flags. */
 const sharesOf = (event) => (event.attachments ?? []).filter((a) => a.is_share === true || (event.subtype === "message_share" && !a.is_msg_unfurl));
 const sharedFiles = (share) => share.files ?? share.original_message?.files ?? [];
-/** A token budget, not a Slack limit: past this the agent gets the
- *  coordinates and decides for itself. */
-const INLINE_REPLY_MAX = 30;
-/** `/stop` is accepted for muscle memory; a bare `stop` is what actually arrives. */
-function slackCommand(text) {
-    const slash = parseCommand(text);
-    if (slash)
-        return { name: slash.name, args: slash.args };
-    const words = text.trim().split(/\s+/).filter(Boolean);
-    const name = words[0]?.toLowerCase() ?? "";
-    const arity = BARE_COMMANDS.get(name);
-    if (arity === undefined || words.length - 1 !== arity)
-        return undefined;
-    return { name, args: words.slice(1).join(" ") };
-}
 export class SlackChannel {
     deps;
     id = "slack";
@@ -103,13 +88,8 @@ export class SlackChannel {
                 ? this.api.addReaction(channel, ts, emoji)
                 : this.api.removeReaction(channel, ts, WORKING),
         }, deps.receipts ?? new ReceiptLedger("slack"), this.log, WORKING, RECEIPT_STALE_MS, (conversationId) => deps.control?.working({ channelId: this.id, conversationId }) ?? false);
-        if (deps.control && deps.handoff) {
-            this.panel = new SlackPanel({
-                api: this.api,
-                control: deps.control,
-                handoff: deps.handoff,
-                log: this.log,
-            });
+        if (deps.control) {
+            this.panel = new SlackPanel({ api: this.api, control: deps.control, log: this.log });
         }
     }
     async start(onMessage) {
@@ -203,13 +183,16 @@ export class SlackChannel {
             this.deps.store.discoverChat("slack", { id: channel, name, kind });
         }
         const text = this.stripMention(raw);
-        const command = slackCommand(text);
+        const command = parseCommand(text);
         const threadTs = threadOf(event);
-        const here = { channelId: this.id, conversationId: conversationId(channel, threadTs) };
+        // The home DM is the head's, in a thread or not, under one key — except a
+        // child's thread (docs/design/11 §Child threads), which is that session's.
+        const home = this.isHead(channel, event.thread_ts);
+        const here = { channelId: this.id, conversationId: home ? channel : conversationId(channel, threadTs) };
         const bindRequest = command?.name === "bind" && isDm;
         const admitted = this.gate.admit("message", channel, {
             isDm,
-            addressed: this.addressed(raw, event, here),
+            addressed: this.addressed(raw, event, here, home),
             userId: event.user,
             bindRequest,
         });
@@ -220,23 +203,30 @@ export class SlackChannel {
         }
         if (bindRequest)
             return this.bind(channel, event.user, threadTs, command?.args ?? "");
-        if (command?.name === "stop")
+        // The head has no panel and takes `/stop` and `/skills` as chat commands (core/chain.ts).
+        if (!home && command?.name === "stop")
             return this.abortTurn(here, channel, threadTs);
+        if (!home && command?.name === "skills")
+            return this.listSkills(here);
+        if (!text && !files.length && !shares.length)
+            return this.log(`empty message in ${here.conversationId}, dropped`);
         // Downloading only past the gate: an unauthorized sender must not make the
         // bot pull bytes on their behalf.
         const markers = await this.saveAttachments(files);
-        const shared = await Promise.all(shares.map((share) => this.sharedBlock(share)));
-        // A bare `@bot` and `settings` are the same request; `s <text>` drafts a
-        // session, so only where this message would start one: a thread root. The
-        // held question carries its markers, so Start sends what the user sent.
+        const shared = await Promise.all(shares.map((share) => sharedBlock(this.directory, this.api, this.log, share)));
+        // `/s <text>` drafts a session, so only where this message would start one:
+        // a thread root. The held question carries its markers, so Start sends what the user sent.
         const question = threadTs === ts ? settingsDraft(text) : undefined;
-        if (this.panel && (question || command?.name === "settings" || (!text && !files.length && !shares.length))) {
+        if (this.panel && !home && (question || command?.name === "settings")) {
             return this.panel.open(here, channel, threadTs, question && [question, ...shared, ...markers].join("\n"));
         }
         // Resolved before the mark: any await between mark() and dispatch is a
         // window in which a previous turn can settle and take this receipt with it.
         const sender = { id: event.user, name: await this.directory.user(this.api, event.user) };
-        this.receipts.mark(here.conversationId, channel, ts);
+        // The head answers a chat command with a note, not a turn: nothing would take a 👀 off it.
+        const answered = home && command && !command.args && isChatCommand(command.name);
+        if (!answered)
+            this.receipts.mark(here.conversationId, channel, ts);
         // Steer: a follow-up is the wrong default when the human is watching a 👀.
         onMessage({
             key: here,
@@ -267,10 +257,13 @@ export class SlackChannel {
             this.log("incomplete block_actions payload, dropped");
             return;
         }
-        const threadTs = message.thread_ts ?? message.ts;
+        // Any click in the home DM is the head's, echoed where the button was,
+        // unless a child's thread; anywhere else a top-level message roots a thread.
+        const home = this.isHead(channel, message.thread_ts);
+        const threadTs = home ? message.thread_ts : message.thread_ts ?? message.ts;
         const key = {
             channelId: this.id,
-            conversationId: conversationId(channel, threadTs),
+            conversationId: home ? channel : conversationId(channel, message.thread_ts ?? message.ts),
         };
         const admitted = this.gate.admit("action", channel, {
             isDm: (await this.directory.channel(this.api, channel)).kind === "dm",
@@ -281,7 +274,8 @@ export class SlackChannel {
             return;
         // Start's question: the card is the message the click was on, so it carries the 👀.
         const run = (text) => this.deliver(key, channel, message.ts, user, text, onMessage);
-        if (await this.panel?.onAction(interaction, key, actionId, run))
+        // The head has no panel: a card left in the DM before it became the home is stale.
+        if (!home && (await this.panel?.onAction(interaction, key, actionId, run)))
             return;
         const text = offeredLabel(message.blocks, actionId);
         if (text === undefined) {
@@ -324,6 +318,11 @@ export class SlackChannel {
         await this.deps.control?.abort(key);
         await this.api.postMessage({ channel, thread_ts: threadTs, text: STOPPED });
     }
+    /** The head's `/skills` is MainChain's; a thread has no chain, so it is answered here. */
+    async listSkills(key) {
+        const text = skillsText((await this.deps.control?.skills(key)) ?? []);
+        await this.notify(key.conversationId, { text, origin: { kind: "chat-command", command: "skills" } });
+    }
     // --- bind ------------------------------------------------------------------
     /** Channels stay silent, but a DM that swallows every message looks broken
      *  rather than locked. */
@@ -333,7 +332,7 @@ export class SlackChannel {
         await this.api.postMessage({
             channel,
             thread_ts: threadTs,
-            text: bindHint("`bind <code>`"),
+            text: bindHint("`%bind <code>`"),
         }).catch((err) => this.log(`bind hint failed: ${String(err)}`));
     }
     async bind(channel, userId, threadTs, code) {
@@ -347,11 +346,26 @@ export class SlackChannel {
     }
     // --- addressing ------------------------------------------------------------
     /** Mentioned, or continuing a thread Pier already owns — durable, so it
-     *  holds after a restart. */
-    addressed(raw, event, key) {
+     *  holds after a restart. The home key has no row to know. */
+    addressed(raw, event, key, home) {
         if (this.me && raw.includes(`<@${this.me}>`))
             return true;
-        return !!event.thread_ts && !!this.deps.control?.knows(key);
+        return !home && !!event.thread_ts && !!this.deps.control?.knows(key);
+    }
+    isHome(channel) {
+        return this.deps.control?.isHome({ channelId: this.id, conversationId: channel }) ?? false;
+    }
+    /** The head's: the home DM, outside any thread a session of its own is bound to. */
+    isHead(channel, threadTs) {
+        return this.isHome(channel) &&
+            !(threadTs && this.deps.control?.knows({ channelId: this.id, conversationId: conversationId(channel, threadTs) }));
+    }
+    /** A thread, or the home DM's main flow (no `threadTs`); undefined for any other channel's. */
+    target(conversation) {
+        const { channel, threadTs } = parseConversation(conversation);
+        if (threadTs)
+            return { channel, threadTs };
+        return this.isHome(channel) ? { channel } : undefined;
     }
     /** Slack does not strip the mention for us. */
     stripMention(text) {
@@ -367,68 +381,6 @@ export class SlackChannel {
         }
         return name ?? channel;
     }
-    /** The eager thread read is not gated: a human handing the agent a message
-     *  is the same act as an upload. */
-    async sharedBlock(share) {
-        const source = share.original_message;
-        const ts = share.ts ?? source?.ts;
-        const threadTs = share.thread_ts ?? source?.thread_ts ?? ts;
-        const replies = share.reply_count ?? source?.reply_count;
-        // A share of a reply is one message; only a parent has a thread.
-        const parent = share.channel_id && ts && threadTs === ts && replies
-            ? { channel: share.channel_id, ts, replies }
-            : null;
-        // `name<id>` is the sender prefix's grammar (core/identity.ts).
-        const author = share.author_id
-            ? `${await this.directory.user(this.api, share.author_id)}<${share.author_id}>`
-            : share.author_name || share.author_subname;
-        const where = share.channel_name
-            ? `#${share.channel_name}${share.channel_id ? `<${share.channel_id}>` : ""}`
-            : share.channel_id;
-        const head = [
-            "shared message",
-            author && `from ${author}`,
-            where && `in ${where}`,
-            ts && `at ${ts}`,
-        ].filter(Boolean).join(" ");
-        // `fallback` is Slack's plain-text rendering when a share's `text` is
-        // empty (a file-only forward, or a body that is all blocks); "" is normal.
-        const body = (share.text || share.fallback || source?.text || "").trim();
-        const thread = parent && parent.replies <= INLINE_REPLY_MAX
-            ? await this.sharedThread(parent.channel, parent.ts, parent.replies)
-            : { transcript: false, lines: [] };
-        // The coordinates in `pier slack`'s own words (skills/pier-slack).
-        const hint = parent && !thread.transcript
-            ? `[thread: ${parent.replies} replies — channel ${parent.channel}, thread_ts ${parent.ts}]`
-            : "";
-        // The transcript opens with the shared message itself.
-        return [`[${head}]`, thread.transcript ? "" : body, ...thread.lines, hint]
-            .filter(Boolean).join("\n");
-    }
-    /** A read that fails or comes back cut says so in the prompt (§5). */
-    async sharedThread(channel, ts, replies) {
-        try {
-            // One over the budget, so an undercounting reply_count still reports as cut.
-            const read = await readThread(this.directory, this.api, channel, ts, INLINE_REPLY_MAX + 2);
-            if (!read.messages.length)
-                return { transcript: false, lines: [] };
-            return {
-                transcript: true,
-                lines: [
-                    `[thread: ${replies} replies, oldest first — ${read.format}]`,
-                    ...read.messages,
-                    ...(read.truncated ? [`[thread partly read: cut at ${read.count} lines]`] : []),
-                ],
-            };
-        }
-        catch (err) {
-            this.log(`shared thread ${channel}/${ts} not read: ${String(err)}`);
-            return {
-                transcript: false,
-                lines: [`[thread not read: ${err instanceof Error ? err.message : String(err)}]`],
-            };
-        }
-    }
     saveAttachments(files) {
         return saveInboundAll(this.id, files.map((file) => ({
             label: file.name ?? "attachment",
@@ -441,32 +393,41 @@ export class SlackChannel {
     }
     // --- outbound --------------------------------------------------------------
     async send(conversation, reply) {
-        const { channel, threadTs } = parseConversation(conversation);
-        // No thread is a foreign id; posting it would put a turn in the channel's
-        // main flow. Refused loudly, receipts still cleared.
-        if (!threadTs) {
+        const to = this.target(conversation);
+        // No thread outside the home DM is a foreign id; posting it would put a
+        // turn in the channel's main flow. Refused loudly, receipts still cleared.
+        if (!to) {
             this.log(`refusing to answer ${conversation}: no thread in the conversation id`);
             await this.receipts.settle(conversation);
             return;
         }
         // The turn ended either way; a 👀 left up by a failed send looks like work.
-        await this.receipts.settleAfter(conversation, () => this.out.reply(channel, threadTs, reply), reply.meta);
-    }
-    /** A web session's thread: the root is the one message Pier posts into a
-     *  channel's main flow (channels/handoff.ts). */
-    async openThread(chatId, note) {
-        return conversationId(chatId, await this.out.open(chatId, note));
+        await this.receipts.settleAfter(conversation, () => this.out.reply(to.channel, to.threadTs, reply), reply.meta);
     }
     /** The 👀 goes on the note itself: the turn it triggers has no message of
      *  the user's to carry them. */
     async notify(conversation, note) {
-        const { channel, threadTs } = parseConversation(conversation);
-        if (!threadTs) {
+        const to = this.target(conversation);
+        if (!to) {
             this.log(`refusing to post a system note to ${conversation}: no thread in the conversation id`);
             return;
         }
-        const ts = await this.out.note(channel, threadTs, note);
+        const ts = await this.out.note(to.channel, to.threadTs, note);
         if (ts && awaitsTurn(note.origin))
-            this.receipts.mark(conversation, channel, ts, note.at);
+            this.receipts.mark(conversation, to.channel, ts, note.at);
+    }
+    async openThread(channel, note) {
+        if (!this.isHome(channel))
+            throw new Error(`refusing to open a thread in ${channel}: not the home DM`);
+        const ts = await this.out.note(channel, undefined, note);
+        if (!ts)
+            throw new Error(`Slack returned no ts for the root in ${channel}`);
+        return conversationId(channel, ts);
+    }
+    async editRoot(conversation, note) {
+        const { channel, threadTs } = parseConversation(conversation);
+        if (!threadTs)
+            throw new Error(`refusing to edit ${conversation}: no thread in the conversation id`);
+        await this.out.edit(channel, threadTs, note);
     }
 }